故障排查

Tarsail 会尽量用明确的区域标签失败，例如 [config:target]、[remote:ssh] 或 [compose:image]。

用标签定位失败层：配置、本地 Docker、SSH、远端 Docker、文件传输、镜像加载或 Compose 启动。

找不到配置文件

现象：

[config:load] Config file not found: tarsail.yml

修复：

tarsail init

或传入目标文件：

tarsail --config tarsail.production.yml doctor

未知或不支持的配置 key

现象：

[config:parse] Unknown top-level config key

或：

[config:scope] Unsupported Phase 0 config section: targets

修复：只使用 Phase 0 支持的顶层 key：

project
target
compose
deploy
files
secrets

Tarsail 会拒绝尚未实现行为的未来配置段。

Compose 服务没有 image tag

现象：

[compose:image] Service "web" has a build section but no explicit image tag.

修复：

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

然后重新运行：

tarsail doctor

找不到 Docker 命令

现象：

[local:docker] Docker command not found.

修复：

• 安装 Docker Engine 或 Docker Desktop；
• 确认 docker 在 PATH 中；
• 安装后重启终端。

验证：

docker ps
docker compose version

Docker daemon 不可访问

现象：

Docker daemon reachable: FAIL

修复：

• 启动 Docker Desktop 或 Docker Engine；
• 确认当前用户可以访问 Docker；
• Linux 上确认 group 或 sudo 策略；
• Windows 上确认 Docker Desktop 使用预期 backend。

验证：

docker ps

SSH 连接失败

现象：

[remote:ssh] Remote command failed

先直接检查 SSH：

ssh [email protected]

如果使用密钥：

ssh -i ~/.ssh/my-app-deploy-key [email protected]

然后运行：

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

常见原因：

• target.host 错误；
• target.user 错误；
• target.port 错误；
• 服务器防火墙阻止 SSH；
• 云服务商安全组阻止 SSH；
• 私钥路径错误；
• 密码登录被禁用；
• 主机密钥未受信任。

密码模式提示 known_hosts 无法加载

现象：

[remote:ssh] Could not load SSH known_hosts file

修复：

ssh [email protected]

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

tarsail --ask-password doctor

密码认证失败

现象：

Password authentication failed

检查：

• 密码是否正确；
• 服务器是否允许密码认证；
• 配置用户是否允许登录；
• 服务器是否因限速或安全策略关闭密码会话。

如果密码登录被禁用，请使用 SSH 密钥。

目标路径被拒绝

现象：

[config:target] target.path is too broad

修复：

target:
  path: /opt/my-app

不要使用 /opt、/var、/home、/root 或 /tmp 这类过宽路径。

目标路径不可写

现象：

target path writable: FAIL

在服务器修复：

sudo mkdir -p /opt/my-app
sudo chown deploy:deploy /opt/my-app

然后：

tarsail doctor

如果用 root 部署，确认路径没有被权限或只读文件系统阻止。

缺少 shared 环境文件

现象：

shared files available: FAIL

如果省略了 compose.env_file.source，Tarsail 会要求远端文件已存在：

compose:
  env_file:
    target: shared/.env

在服务器创建它，或添加本地 source：

compose:
  env_file:
    source: .deploy/prod.env
    target: shared/.env

密钥 source 不存在

现象：

[config:secrets] secrets[0].source is not available

修复：

• 创建本地文件；
• 修正路径；
• 路径相对于配置文件；
• 使用正斜杠。

示例：

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

本地缺少镜像

现象：

[docker:image] Image is not available locally

Tarsail 在 Compose 中发现了镜像，但构建后本地仍找不到它。

修复：

docker compose -p my-app --env-file .deploy/prod.env -f compose.yaml build
docker image ls
tarsail deploy

没有 build: 的镜像需要提前拉取：

docker pull nginx:1.27-alpine

远端 Docker 不可用

现象：

Docker available: FAIL

在服务器检查：

docker ps
docker compose version

修复：

• 安装 Docker；
• 安装 Docker Compose v2；
• 启动 Docker daemon；
• 如合适，把 deploy 用户加入 Docker group；
• 修改 group 后重新连接。

Compose 已启动但公网访问失败

如果 tarsail deploy 成功且容器在运行，剩余问题可能在 Tarsail 外部。

在服务器检查：

cd /opt/my-app
docker compose -p my-app --env-file current/.tarsail.env --env-file shared/.env -f current/compose.yaml ps
curl -v http://127.0.0.1:8080/healthz
ss -ltnp

从本机检查：

curl -v http://example.com/healthz

常见原因：

• Compose 发布端口错误；
• 应用在容器内监听 127.0.0.1 而不是 0.0.0.0；
• OS 防火墙阻止端口；
• 云服务商安全组阻止端口；
• DNS 指向了其他 IP；
• 反向代理配置期望 HTTPS 或不同 host；
• 端口已被其他服务占用。

端口已被占用

Compose 错误示例：

bind: address already in use

在服务器检查：

ss -ltnp | grep ':80'

选择一种修复方式：

• 停止冲突服务；
• 修改 Compose 发布端口；
• 通过已有反向代理转发；
• 如果是旧 Compose 形态遗留容器，移除 orphan containers。

激活后部署失败

现象：

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

运行：

tarsail rollback
tarsail logs --tail 300

必要时手动检查失败发布：

ssh [email protected]
cd /opt/my-app
ls -la releases
cat current/manifest.json

记住，回滚不会撤销数据库迁移或 Docker volume 变更。