快速上手

这份指南展示如何从一个已有 Docker Compose 项目开始，完成一次 Tarsail 部署。

学习和公开文档中请使用占位值。不要把真实服务器地址、私有域名、凭据或生产 .env 内容提交到公开仓库。

要求

本机：

Docker；
Docker Compose v2；
使用密钥认证时需要 ssh 和 scp；
已全局安装 Tarsail。

远端服务器：

Linux；
SSH 访问；
Docker；
Docker Compose v2；
有权限执行 Docker 命令；
一个可写的项目路径，例如 /opt/my-app。

1. 安装 Tarsail

Windows、macOS 或 Linux 上的 PowerShell：

irm https://tarsail.plystra.com/install.ps1 | iex

Linux 或 macOS 上的 POSIX shell：

curl -fsSL https://tarsail.plystra.com/install.sh | sh

验证：

tarsail version

自定义安装目录和指定 release ID 安装见安装和升级。

2. 准备 Compose 镜像标签

每个服务都必须有显式 image:。

3. 初始化配置

在 Compose 项目根目录执行：

tarsail init

它会创建 tarsail.yml。

编辑配置：

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

4. 按需添加环境文件

如果远端 Compose 应用需要运行时变量，把真实文件放在版本控制之外，例如：

.deploy/prod.env

示例内容：

APP_ENV=production
APP_BASE_URL=https://app.example.com
DATABASE_URL=postgres://user:[email protected]:5432/app
SESSION_SECRET=replace-with-a-long-random-value

在 tarsail.yml 中配置：

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

Tarsail 会在 deploy 时把这个文件上传到 <target.path>/shared/.env，然后传给远端 Docker Compose。

5. 检查部署条件

使用默认 SSH 身份：

tarsail doctor

使用指定密钥：

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

使用密码认证：

tarsail --ask-password doctor

密码模式会请求一次远端用户的 SSH 密码，并在当前 Tarsail 命令里复用它执行远端命令和上传文件。

6. 部署

密钥认证：

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

密码认证：

tarsail --ask-password deploy

Tarsail 会输出每个主要步骤，最后显示远端 Compose 状态。

7. 查看部署状态

tarsail status
tarsail logs
tarsail logs web

跟随日志：

tarsail logs -f web

限制日志行数：

tarsail logs --tail 100 web

8. 需要时回滚

tarsail rollback

回滚会重新激活上一个发布的 Compose 文件和已打包镜像。

回滚不会恢复数据库、Docker volumes、bind mount 数据或外部服务。

9. 清理旧发布

tarsail prune

非交互：

tarsail prune --yes

deploy.keep_releases 控制清理时保留多少个发布。

完整最小示例

compose.yaml:

services:
  web:
    build: .
    image: my-app-web:${TARSAIL_RELEASE_ID:-local}
    environment:
      APP_ENV: ${APP_ENV:-production}
      APP_ADDR: ${APP_ADDR:-0.0.0.0:8080}
      SESSION_SECRET: ${SESSION_SECRET}
    ports:
      - "80:8080"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "-", "http://127.0.0.1:8080/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3

tarsail.yml:

project: my-app

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

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

deploy:
  keep_releases: 5

部署：

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