命令

Tarsail 命令形态：

tarsail [全局参数] <命令> [命令参数]

全局参数

参数	值	说明
--config	path	Tarsail 配置文件路径。默认：tarsail.yml。
--identity-file	path	用于远端访问的 SSH 私钥文件。
--ssh-key	path	--identity-file 的别名。
--ask-password	boolean	运行时请求一次远端用户的 SSH 密码。
--verbose	boolean	在可用位置显示更详细的命令输出。
--yes	boolean	对支持确认的问题自动回答 yes。
-v, --version	boolean	显示 Tarsail 版本并退出。

--identity-file 和 --ask-password 不能同时使用。

--identity-file 支持 ~/ 展开，并会解析成绝对路径后使用。

init

创建最小配置文件。

tarsail init

指定路径：

tarsail --config tarsail.production.yml init

init 不会覆盖已有配置文件。

它按以下顺序检测 Compose 文件：

1. compose.yaml
2. compose.yml
3. docker-compose.yaml
4. docker-compose.yml

如果都不存在，它会写入 compose.yaml。

生成配置：

project: my-app

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

compose:
  file: compose.yaml

deploy:
  keep_releases: 3

doctor

检查本地和远端部署条件。

tarsail doctor

常见用法：

tarsail --config tarsail.production.yml doctor
tarsail --identity-file ~/.ssh/my-app-deploy-key doctor
tarsail --ask-password doctor

本地检查：

• 配置可加载；
• Compose 文件存在；
• Docker 命令可用；
• Docker Compose 可用；
• Docker daemon 可访问；
• Compose 镜像可发现。

远端检查：

• SSH 可连接；
• 目标路径可写；
• 必要 shared 文件存在；
• Docker 可用；
• Docker Compose 可用。

doctor 在检查路径可写性时可能会创建基础远端目录：

releases/
incoming/
shared/

deploy

构建、打包、上传、加载、激活并启动应用。

tarsail deploy

常见用法：

tarsail --identity-file ~/.ssh/my-app-deploy-key deploy
tarsail --ask-password deploy
tarsail --config tarsail.production.yml --ask-password deploy

步骤：

1. 检查本地环境；
2. 检查远端服务器；
3. 上传配置的环境文件和密钥文件；
4. 构建镜像；
5. 创建发布包；
6. 上传发布包；
7. 加载镜像；
8. 启动 Compose 应用；
9. 读取状态。

生成的发布 ID 会作为 TARSAIL_RELEASE_ID 提供给本地和远端 Compose。

status

显示当前激活发布的远端 Docker Compose 状态。

tarsail status

等价远端操作：

cd <target.path>
docker compose -p <project> --env-file current/.tarsail.env --env-file shared/.env -f current/compose.yaml ps

只有配置了 compose.env_file 时才会加入 shared 环境文件。

logs

显示远端 Compose 日志。

tarsail logs

查看某个服务：

tarsail logs web

参数：

参数	值	说明
--tail	number	显示日志行数。默认：200。范围：1 到 10000。
-f	boolean	持续跟随日志。

示例：

tarsail logs --tail 100
tarsail logs --tail 500 web
tarsail logs -f web

服务名校验允许字母、数字、点、下划线和连字符。

rollback

重新激活上一个发布。

tarsail rollback

回滚会：

• 从 current 符号链接读取当前发布；
• 根据发布元数据选择上一个有效发布；
• 从该发布加载镜像；
• 更新 current；
• 执行 Compose；
• 输出状态。

回滚不会恢复数据存储、Docker volumes、shared/ 文件或外部服务。

prune

删除旧的非当前发布目录。

tarsail prune

跳过确认：

tarsail prune --yes

或：

tarsail --yes prune

保留数量来自：

deploy:
  keep_releases: 3

keep_releases 允许范围是 1 到 20。

version

显示已安装的 Tarsail 版本。

tarsail version

Release 二进制文件使用日期加 hash 的版本字符串，例如 20260622-194500-a1b2c3d4e5f6。

等价写法：

tarsail -v
tarsail --version

如果二进制文件由 GitHub Release workflow 构建，verbose 版本输出会包含 commit 和构建时间：

tarsail --verbose version

help

显示命令用法：

tarsail help
tarsail --help
tarsail -h