概览

Tarsail 是面向 Docker Compose 项目的发布打包器和 SSH 部署工具。

它适合个人维护者和小团队：应用已经能用 Docker Compose 运行，但目标服务器访问 Docker Hub、GHCR、Quay 或私有镜像仓库不稳定、很慢、被限制，或者你不希望部署过程依赖实时拉取镜像。

问题

常规 Docker Compose 部署通常默认目标服务器可以拉取所有镜像：

docker compose pull
docker compose up -d

以下情况会让这个默认假设失效：

服务器的出站网络受限；
镜像仓库访问很慢或不稳定；
小项目不值得维护私有镜像仓库；
部署需要在外部仓库不可用时仍然可重复；
构建机器能访问依赖，但服务器不能。

Tarsail 改变部署路径。它让本机完成重网络依赖的工作，然后把一个可携带的发布包传到服务器。

部署模型

Tarsail 的 Phase 0 部署模型刻意保持很小：

本地项目
  compose.yaml
  Dockerfile
  .deploy/prod.env

本地 Docker daemon
  构建镜像
  保存镜像为 tar 文件

Tarsail 发布包
  manifest.json
  compose.yaml
  images/*.tar
  files/*

SSH 目标服务器
  /opt/my-app/
    current -> releases/<release-id>
    releases/
    incoming/
    shared/

运行 deploy 时，Tarsail 会：

读取 tarsail.yml；
验证本机 Docker 和 Docker Compose；
验证 Compose 文件里的镜像标签是显式的；
检查 SSH、远端目标路径、Docker 和 Docker Compose；
把配置的环境文件和密钥文件上传到 shared/；
在本机构建 Compose 镜像；
把本地镜像保存成镜像 tar 文件；
创建 .tarsail.tar.gz 发布包；
把发布包上传并解压到服务器；
在服务器上用 docker load 加载镜像；
将 current 指向新发布；
执行 docker compose up -d；
输出远端 Compose 状态。

发布目录结构

Tarsail 在服务器上管理一个项目专属目录：

/opt/my-app/
  current -> releases/20260622-101530-a1b2
  incoming/
    my-app-20260622-101530-a1b2.tarsail.tar.gz
  releases/
    20260622-101530-a1b2/
      manifest.json
      compose.yaml
      .tarsail.env
      shared -> ../../shared
      images/
        web.tar
        worker.tar
      files/
        nginx/
          default.conf
  shared/
    .env
    secrets/
      app.key

releases/ 保存属于某次发布的文件和镜像。shared/ 保存跨发布稳定存在的运行时文件，例如环境文件和上传的密钥文件。

运行时 Compose 命令

在服务器上，Tarsail 从目标路径执行 Compose，并指向当前激活的发布：

docker compose -p my-app \
  --env-file current/.tarsail.env \
  --env-file shared/.env \
  -f current/compose.yaml \
  up -d

自动生成的 current/.tarsail.env 包含 TARSAIL_RELEASE_ID。你可以在镜像标签里使用它：

services:
  web:
    build: .
    image: my-app-web:${TARSAIL_RELEASE_ID:-local}

各类文件应该放在哪里

位置	用途	回滚行为
`compose.yaml`	当前发布的 Compose 定义	会回滚
`images/*.tar`	`docker image save` 生成的镜像文件	会回滚
`files/`	`files:` 复制的非密钥发布文件	会回滚
`shared/`	环境文件和密钥文件	不会回滚
Docker volumes	应用运行数据	不会回滚
外部数据库	发布包外部的数据	不会回滚

适合使用 Tarsail 的场景

Tarsail 适合这些条件：

应用已经能用 Docker Compose 运行；
部署到一台 Linux 服务器；
服务器可通过 SSH 访问；
本机 Docker 可以构建或拉取镜像；
远端服务器已安装 Docker 和 Docker Compose v2；
远端访问镜像仓库不稳定，或你不希望依赖远端拉取；
你希望有可读的发布目录和简单回滚路径。

不适合使用 Tarsail 的场景

如果你需要以下能力，Tarsail 不是合适工具：

Kubernetes 或 Docker Swarm 编排；
一次部署到多台服务器；
自动 TLS 证书申请；
自动数据库备份或恢复；
容器监控；
镜像仓库管理；
蓝绿或金丝雀发布；
Web 控制台；
完整密钥生命周期管理。

这些需求本身可能合理，但不属于 Phase 0。

成熟度

当前成熟度：Public Alpha。

维护状态：Active。

Phase 0 保持保守。支持形态越窄，行为越容易解释：

一个配置文件；
一个 Compose 文件；
一台目标服务器；
一个当前激活发布；
显式文件传输；
显式环境和密钥处理。