docs(sub2api): document PK01 host-docker trace gap

2026-06-30 18:23:24 +00:00
parent b88e6e54e4
commit 280edce231
2 changed files with 3 additions and 1 deletions
@@ -65,6 +65,8 @@ bun scripts/cli.ts platform-infra sub2api validate --target PK01

 PK01 没有 k3s control plane。当前 `codex-pool sync`、`codex-pool validate`、`sentinel-report` 和 `trace` 的部分实现仍依赖 k8s/kubectl 远端脚本；在 PK01 host-Docker target 上看到 `kubectl` 缺失时，应归类为 CLI host-Docker adapter 缺口，不要误判为 Sub2API app、Caddy、上游或账号池故障。正式修复应补 host-Docker 版 codex-pool sync/validate/report/trace；临时排障只能做只读 admin API、DB join 表和最小公网 `/v1/responses` smoke，并且不得打印 admin password、API key 或账号凭据。

+PK01 host-Docker apply 仍必须由 `platform-infra sub2api apply --target PK01 --confirm` 受控执行。若 dry-run 或 apply 输出显示 `docker compose is absent; apply will use raw docker run fallback`，这表示 CLI 选择了 host-Docker fallback，不是裸手工 Docker 操作；只要 YAML image、env、ports、Caddy managed block 和 `status/validate` 最终对齐，可作为受控滚动升级证据。不要改用手工 `docker run`、手工 compose 文件或直接编辑 PK01 Caddyfile。
+
 ## D601 Egress Proxy

 D601 的目标级 `egressProxy` 完全由 `config/platform-infra/sub2api.yaml` 控制。当前成熟形态是 master Docker `shadowsocks-rust` 作为加密出站源，D601 k3s 内 `sing-box` 暴露 HTTP/mixed ClusterIP proxy 给 Sub2API 和按 YAML 启用的 sentinel 使用。不要把 endpoint、端口、密码、健康探针或镜像 tag 写进 skill；只以 YAML 和 `config/platform-infra/sub2api-master-egress-proxy.compose.yaml` 为准。
@@ -11,4 +11,4 @@

 如果要证明真实模型请求可用，使用最小 `/v1/responses` 或等价 Codex smoke。不要把 group-level `/v1/models` 成功解释成每个上游 account 都健康。

-公网 `/v1/responses` smoke 应尽量复用 `codex-pool validate` 的非流式请求形态：带统一 key、`stream:false`、`store:false`、小 `max_output_tokens`、短输入、`X-Request-ID` 和 `OpenAI-Client-Request-ID`，并用同一 request id 跑 `codex-pool trace --target <id> --request-id <id>` 取证。不要用没有超时的临时脚本或省略 request id 的公网 POST 作为最终证据；`/v1/models` 200 只能证明 key 和模型列表入口可用，不能替代 Responses smoke。
+公网 `/v1/responses` smoke 应尽量复用 `codex-pool validate` 的非流式请求形态：带统一 key、`stream:false`、`store:false`、小 `max_output_tokens`、短输入、`X-Request-ID` 和 `OpenAI-Client-Request-ID`，并用同一 request id 跑 `codex-pool trace --target <id> --request-id <id>` 取证。PK01 host-Docker target 当前可能因 trace adapter 依赖 `kubectl` 而无法追踪；这时把 trace 失败记录为工具缺口，验收以 `status --target PK01`、`validate --target PK01`、public `/health`、public `/v1/models` 200 和 public `/v1/responses` 200 为准。不要用没有超时的临时脚本或省略 request id 的公网 POST 作为最终证据；`/v1/models` 200 只能证明 key 和模型列表入口可用，不能替代 Responses smoke。