配置

Tarsail 默认读取 tarsail.yml。

使用其他配置文件：

tarsail --config tarsail.production.yml deploy

配置文件位置定义项目根目录。配置中的相对路径都从配置文件所在目录解析。

完整示例

project: my-app

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

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

deploy:
  keep_releases: 5

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

secrets:
  - source: .deploy/htpasswd
    target: shared/auth/htpasswd
    mode: 600

支持的顶层配置段

配置段	必填	用途
`project`	是	用于发布包名称、Compose project name 和元数据的项目名。
`target`	是	远端 Linux 服务器和目标路径。
`compose`	是	Compose 文件和可选环境文件。
`deploy`	否	发布保留设置。
`files`	否	复制进发布包的非密钥发布文件。
`secrets`	否	上传到远端 `shared/` 的密钥文件。

未知顶层 key 会被拒绝。

Phase 0 也会拒绝保留给未来的配置段，例如 targets、registry、registries、kubernetes、swarm、ci、plugins、nginx、caddy、tls、backups 和 notifications。

`project`

必填字符串。

project: my-app

允许：

小写字母；
数字；
连字符；
下划线；
长度 1 到 64。

模式：

^[a-z0-9_-]{1,64}$

Tarsail 使用该值作为：

本地 Docker Compose project name；
远端 Docker Compose project name；
发布包文件名；
manifest 元数据。

`target`

必填对象。

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

`target.name`

必填字符串。

允许：

小写字母；
数字；
连字符；
下划线；
长度 1 到 64。

Phase 0 只支持一个 target，但保留名称可以让配置文件更清楚。

`target.host`

必填字符串。

允许字符：

字母；
数字；
点；
连字符。

使用主机名或 IPv4 地址：

host: example.com

host: 192.0.2.10

`target.user`

必填字符串。

SSH 用户名。

允许模式：

^[A-Za-z_][A-Za-z0-9_-]{0,63}$

示例：

user: deploy
user: root

条件允许时，建议使用专门的 deploy 用户。

`target.port`

可选整数。

默认：

port: 22

允许范围：1 到 65535。

`target.path`

必填远端绝对路径。

示例：

path: /opt/my-app

路径必须：

是绝对路径；
已清理；
不包含 ..；
使用简单路径字符；
不能是 /；
不能是过宽系统目录。

会被拒绝的过宽路径：

/opt
/var
/usr
/home
/etc
/root
/tmp

请使用项目专属子路径。

`compose`

必填对象。

compose:
  file: compose.yaml

`compose.file`

必填字符串。

相对于配置根目录的 Docker Compose 文件路径。

规则：

必须是相对路径；
必须使用正斜杠；
不能包含 ..；
不能包含空格或 shell 元字符；
必须指向已有文件。

示例：

compose:
  file: compose.yaml

compose:
  file: deploy/compose.production.yaml

`compose.env_file`

可选对象。

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

该文件会通过 --env-file 传给远端 Docker Compose。

字段：

字段	必填	默认值	说明
`source`	否	无	部署前上传的本地文件。
`target`	否	`shared/.env`	Tarsail 目标路径下的远端路径。
`mode`	否	`600`	上传后设置的文件权限。

如果省略 source，Tarsail 会要求服务器上已经存在 target。

target 必须在 shared/ 下。

`deploy`

可选对象。

deploy:
  keep_releases: 3

`deploy.keep_releases`

可选整数。

默认：

keep_releases: 3

允许范围：1 到 20。

该值用于 tarsail prune。deploy 不会自动 prune。

`files`

可选数组。

files:
  - source: deploy/nginx
    target: files/nginx
  - source: public/maintenance.html
    target: files/maintenance.html

files 用于非密钥发布文件。它们会进入发布包，并随发布回滚。

字段：

字段	必填	说明
`source`	是	相对于配置根目录的本地文件或目录。
`target`	是	`files/` 下的发布包目标路径。

规则：

source 必须存在；
source 必须是相对路径；
source 必须使用正斜杠；
source 不能包含 ..；
符号链接 source 会被拒绝；
目录中不能包含符号链接；
target 必须在 files/ 下；
target 不能使用 manifest.json、compose.yaml 或 images 等保留名。

`secrets`

可选数组。

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

secrets 用于复制到远端 shared/ 目录的显式文件。

字段：

字段	必填	默认值	说明
`source`	是	无	相对于配置根目录的本地文件。
`target`	是	无	`shared/` 下的远端路径。
`mode`	否	`600`	上传后设置的文件权限。

规则：

source 必须存在；
source 必须是相对路径；
target 必须在 shared/ 下；
mode 必须是 600 或 0644 这类八进制权限。

密钥不会进入发布包。

路径规则

配置路径一律使用正斜杠，即使在 Windows 上：

compose:
  file: deploy/compose.production.yaml

不要使用反斜杠：

compose:
  file: deploy\compose.production.yaml

Tarsail 会拒绝不安全路径组件和托管目标路径中的常见 shell 元字符。

Tarsail 提供的环境变量

运行 deploy 时，Tarsail 会设置：

TARSAIL_RELEASE_ID=<release-id>

它会传给本地 Compose 命令用于构建和配置发现，也会写入 current/.tarsail.env 供远端 Compose 使用。

在镜像标签里使用：

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

:-local fallback 可以让普通本地 Compose 命令继续可用。