## 运行面排障

- `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 路径后重跑，并以最终结构化结果作为证据。
