pikasTech-unidesk/.agents/skills/unidesk-nginx/references/troubleshooting.md

排障

先看受控状态

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。
• 不把临时后端长期保留为运行依赖。