pikasTech-unidesk/.agents/skills/unidesk-sub2api/references/troubleshooting-runtime.md

运行面排障

• api.pikapython.com 返回 502/503 时，先按 YAML 判定 target 和 failure layer。PK01 host-Docker target 先跑 sub2api status --target PK01 和 sub2api validate --target PK01，再分别检查 PK01 Caddy managed block、loopback app health、Docker container health、admin account availability 和最小 public /v1/responses smoke。k3s/FRP target 先跑对应 sub2api status --target <id> 和 validate --target <id>；若 sub2api、sub2api-frpc、sub2api-redis 或 sub2api-egress-proxy 出现 0/1，或 validate 显示 no endpoints available for service "sub2api" / app Pod 已终止，先用 bun scripts/cli.ts platform-infra sub2api apply --target <id> --confirm 重新收敛 YAML 资源，按返回的 job status 轮询，再跑 status、validate 和可用的 Codex-pool 验证。不要先改账号池、哨兵状态、Secret 或 Caddy。
• 镜像升级或 apply --confirm 后，k3s target 可能短暂显示 sub2api 0/1 而 egress/frpc/redis 已 ready。先等待一轮并重跑 status --target <id>；若 status --full 显示目标 Pod Running/Ready、runtime image 等于 YAML、init containers Completed，则按滚动中间态处理并继续 validate。只有持续不 ready、事件显示拉取/启动失败、或 service proxy health 失败时，才进入运行面排障。
• 快速恢复完成后，用分层证据 closeout：目标 public /health 应返回 200；最小公网 /v1/responses marker 应使用统一 key 或明确用户 key 返回 200；只输出 HTTP status、模型数量、marker、account id/group id 和 key fingerprint，不打印 key。不要为了公网验证运行 configure-local --confirm，它会重写本机 ~/.codex；本机默认 auth.json key 返回 401 只能说明本机配置和公网统一 key 不一致，不能当作服务不可用证据。
• Sub2API 卡在 wait-postgres / wait-redis 或服务内大量 context deadline exceeded：先跑 sub2api status 看 networkPolicy.ok，再跑 sub2api validate 看 postgresCrossPodPgIsReady / redisCrossPodPing；缺失或异常时用 sub2api apply --confirm 恢复受控 NetworkPolicy/allow-all，不要保留手工 iptables bypass 作为长期修复。
• codex-pool sync --confirm 或 codex-pool validate 超时：先区分 CLI 传输超时和 Sub2API 运行失败。受控 CLI 应返回远端作业进度和 stdout/stderr tail；如果只是低层 trans 60s 超时，不能据此判定 Sub2API failover 不工作。改用或修复 CLI 的远端 job/poll 路径后重跑，并以最终结构化结果作为证据。