核心概念

Tarsail 很小，但有几个概念在正式使用前必须理解。

项目

Tarsail 项目是包含以下内容的本地目录：

tarsail.yml；
compose.file 指向的 Docker Compose 文件；
Compose 构建使用的 Dockerfile 和源代码；
files 引用的可选发布文件；
compose.env_file 和 secrets 引用的可选本地环境和密钥文件。

配置文件所在位置定义项目根目录。tarsail.yml 里的相对路径都从该目录解析。

目标服务器

目标服务器在 target 下配置。

Phase 0 每个配置文件只支持一个目标：

target:
  name: prod
  host: example.com
  user: deploy
  port: 22
  path: /opt/my-app

目标路径必须是项目专属路径。Tarsail 会拒绝 /、/opt、/var、/home、/root、/tmp、/etc、/usr 这类过宽路径。

发布 ID

每次部署都会创建一个发布 ID，例如：

20260622-101530-a1b2

发布 ID 用于：

发布包文件名；
发布目录；
manifest.json；
自动生成的 .tarsail.env；
Compose 使用 ${TARSAIL_RELEASE_ID:-local} 时的镜像标签。

发布包

发布包是在本机创建的 gzip 压缩 tar 归档。

它包含：

manifest.json
compose.yaml
images/
  web.tar
  worker.tar
files/
  ...

它不包含：

SSH 私钥；
SSH 密码；
配置的 compose.env_file 内容；
配置的 secrets 内容；
Docker volumes；
数据库 dump；
未显式配置的项目文件。

Manifest

manifest.json 记录发布元数据：

{
  "schema_version": 1,
  "project": "my-app",
  "release_id": "20260622-101530-a1b2",
  "created_at": "2026-06-22T10:15:30Z",
  "created_by": "tarsail",
  "compose_file": "compose.yaml",
  "images": [
    {
      "service": "web",
      "image": "my-app-web:20260622-101530-a1b2",
      "file": "images/web.tar"
    }
  ]
}

Tarsail 使用 manifest 做发布列表和验证。

托管文件

托管文件是通过 files 复制进发布包的非密钥文件或目录：

files:
  - source: deploy/nginx
    target: files/nginx

适合放在托管文件里的内容：

Nginx 配置模板；
静态构建产物；
可以安全提交的本地配置；
Compose 服务使用的脚本。

托管文件会跟随发布一起回滚。

不要把密钥放进 files。

Shared 文件

shared/ 是远端目标路径下的持久目录。

适合放在这里：

.env 文件；
你自己管理的 TLS 证书；
htpasswd 文件；
应用密钥；
其他显式配置的密钥文件。

运行 tarsail rollback 时，shared 文件不会回滚。

Compose 环境文件

compose.env_file 是会传给 Docker Compose 的特殊密钥文件：

compose:
  file: compose.yaml
  env_file:
    source: .deploy/prod.env
    target: shared/.env
    mode: 600

如果设置了 source，Tarsail 会在 deploy 时上传它。

如果省略 source，Tarsail 会要求服务器上已经存在目标文件：

compose:
  file: compose.yaml
  env_file:
    target: shared/.env

这适用于密钥由其他流程预先下发的环境。

密钥文件

secrets 会把显式配置的文件上传到 shared/：

secrets:
  - source: .deploy/app.key
    target: shared/secrets/app.key
    mode: 600

Tarsail 只复制文件并设置权限。它不会加密、生成、轮换、验证、备份或审计密钥值。

激活

发布包上传并解压后，Tarsail 会更新远端 current 符号链接来激活发布：

current -> releases/20260622-101530-a1b2

然后它针对 current/compose.yaml 执行 Compose。

如果 Compose 启动在激活后失败，Tarsail 会报告失败并提示运行 tarsail rollback。

回滚边界

回滚影响：

current；
当前激活的 compose.yaml；
已打包镜像；
发布内的托管文件。

回滚不影响：

数据库；
Docker named volumes；
发布目录外的 bind-mounted 目录；
shared/ 文件；
外部服务；
网络服务商状态；
DNS 或证书。