# 排障

## 先看受控状态

```bash
bun scripts/cli.ts platform-infra nginx plan --target PK01
bun scripts/cli.ts platform-infra nginx status --target PK01
```

只在受控输出不足时使用 `trans PK01` 做有界只读诊断。
诊断不能替代最后一次正式 `status`。

## Compose 不可用

- 症状：`docker compose` 不存在或插件 metadata 无效。
- 先直接运行 YAML 固定的 Compose 二进制 `version`，再检查 `docker info` 插件警告。
- Master 的发行版插件可能依赖较新的 GLIBC，不能直接复制到 Ubuntu 20.04 的 PK01。
- 使用 owning YAML 固定的官方静态二进制及 SHA-256，不在 PK01 现场下载漂移版本。

## 制品传输超时

- 症状：`trans upload` 大文件长期无进度，或单次 SSH 到 60 秒后退出 `124`。
- 正常路径应为本机临时 HTTP 源、PK01 远端 job 和短轮询。
- 不要把大镜像改回 base64 分块上传，也不要用长 SSH 等待下载、Docker load 和验证。
- apply 结束后检查 `/tmp/unidesk-nginx-artifacts` 不存在，临时 HTTP 端口已释放。

## Logger API 拒绝

- `401` 表示没有 `X-API-Key`，属于正常鉴权结果。
- `403` 表示 key 不匹配。
- 只核对 Secret sourceRef、key 名、presence 和 fingerprint。
- 禁止读取远端环境文件并打印明文，也禁止把 key 放进 job 命令参数。

## 业务端口无响应

- 先看 YAML routes 是否仍指向已撤除的测试端口。
- 验收成功后删除两个测试后端是设计要求，不代表 Nginx 容器异常。
- 部署真实应用时只修改 YAML routes，不改镜像源码。
- 多端口问题按每个 `listenPort` 独立核对上游，不推断所有端口共享同一组后端。

## 测试后端残留

- 正式 status 的 `activeTestBackends` 必须为 `0`。
- 检查两个 unit、Python 脚本和 enable symlink 是否仍存在。
- 若 apply 失败在验证阶段，优先修复 CLI 的退出清理路径，再重跑受控 apply。
- 不把临时后端长期保留为运行依赖。
