From 280edce231ee1c3eacb9f703116c22e59c0db382 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 30 Jun 2026 18:23:24 +0000 Subject: [PATCH] docs(sub2api): document PK01 host-docker trace gap --- .agents/skills/unidesk-sub2api/references/operations.md | 2 ++ .agents/skills/unidesk-sub2api/references/validation.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.agents/skills/unidesk-sub2api/references/operations.md b/.agents/skills/unidesk-sub2api/references/operations.md index fa9bd4db..89103a43 100644 --- a/.agents/skills/unidesk-sub2api/references/operations.md +++ b/.agents/skills/unidesk-sub2api/references/operations.md @@ -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` 为准。 diff --git a/.agents/skills/unidesk-sub2api/references/validation.md b/.agents/skills/unidesk-sub2api/references/validation.md index 0efe2f2a..8e1d876c 100644 --- a/.agents/skills/unidesk-sub2api/references/validation.md +++ b/.agents/skills/unidesk-sub2api/references/validation.md @@ -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 --request-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 --request-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。