部署项目

这份指南假设你的 Compose 项目已经能在本地构建，并且已有有效的 tarsail.yml。

如果还没有准备项目，请先阅读快速上手。

1. 确认本地 Compose 输出

在项目根目录运行 Compose config：

docker compose -p my-app -f compose.yaml config

如果配置了 compose.env_file.source，用同一个文件测试：

docker compose -p my-app --env-file .deploy/prod.env -f compose.yaml config

检查：

• 每个服务都有 image 值；
• 必要环境变量已存在；
• bind mount 路径从远端目标路径看是合理的；
• 对外端口符合预期访问方式。

2. 运行 doctor

使用默认 SSH 配置：

tarsail doctor

指定配置文件：

tarsail --config tarsail.production.yml doctor

指定私钥：

tarsail --identity-file ~/.ssh/my-app-deploy-key doctor

使用密码认证：

tarsail --ask-password doctor

doctor 检查本地和远端部署条件。它不会创建发布包，也不会启动应用。

3. 使用密钥部署

tarsail --identity-file ~/.ssh/my-app-deploy-key deploy

--ssh-key 是 --identity-file 的别名：

tarsail --ssh-key ~/.ssh/my-app-deploy-key deploy

常规部署建议使用密钥认证。它更容易自动化，也通常更稳定。

4. 使用密码部署

tarsail --ask-password deploy

Tarsail 会提示一次：

SSH password for [email protected]:

密码只保存在当前命令进程内存中，用于本次运行中的 SSH 命令和文件上传。Tarsail 不会把它写入磁盘。

密码模式要求主机密钥已经存在于本机 known_hosts。如果这是新主机，请先用系统 SSH 客户端连接一次：

ssh [email protected]

确认主机密钥后再接受，然后重新运行 Tarsail。

5. deploy 做了什么

部署命令会输出八个主要步骤：

1/8 Checking local environment
2/8 Checking remote server
3/8 Building images
4/8 Creating bundle
5/8 Uploading bundle
6/8 Loading images
7/8 Starting Compose app
8/8 Reading status

关键行为：

• 本地 Compose build 在打包前运行；
• 配置的环境文件和密钥文件上传到 shared/；
• 发布包上传到 incoming/；
• 发布包解压到新的 release 目录；
• 远端用 docker load 加载镜像；
• Compose 启动前 current 指向新发布；
• Compose 会收到 current/.tarsail.env 和配置的 shared 环境文件。

6. 验证远端状态

使用 Tarsail：

tarsail status
tarsail logs --tail 100
tarsail logs --tail 100 web

或直接在服务器检查：

ssh [email protected]
cd /opt/my-app
docker compose -p my-app --env-file current/.tarsail.env --env-file shared/.env -f current/compose.yaml ps

如果没有配置 compose.env_file，省略 --env-file shared/.env。

7. 一行部署示例

默认配置和 SSH 密钥：

tarsail --identity-file ~/.ssh/my-app-deploy-key deploy

生产配置和 SSH 密钥：

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

生产配置和密码：

tarsail --config tarsail.production.yml --ask-password deploy

Windows PowerShell 使用二进制变量：

& $TARSAIL --config .\tarsail.production.yml --ask-password deploy

8. 如果激活后部署失败

如果 current 已更新但 Compose 启动失败，Tarsail 会报告：

Deployment failed after activation.
Run "tarsail rollback" to restore the previous release.

运行：

tarsail rollback

然后查看日志和状态：

tarsail logs --tail 300
tarsail status

9. 部署检查清单

生产部署前确认：

• 目标 host 和 path 正确；
• Compose 文件是预期的生产文件；
• compose.env_file.source 指向被忽略的本地文件；
• 真实密钥没有提交；
• 远端 Docker 和 Compose 已安装；
• 必要公网端口已在 OS 防火墙和云服务商规则中放行；
• 使用域名时 DNS 指向预期服务器；
• 数据库迁移行为已理解；
• 回滚限制可以接受。