diff --git a/.agents/skills/unidesk-sub2api/references/operations.md b/.agents/skills/unidesk-sub2api/references/operations.md index d1286bca..161316c8 100644 --- a/.agents/skills/unidesk-sub2api/references/operations.md +++ b/.agents/skills/unidesk-sub2api/references/operations.md @@ -96,6 +96,12 @@ proxy secret/config 文件只允许放在受控 Secret/state 路径,输出只 5. 提交并推送 YAML source truth 后,执行 `sub2api image-prepull --target --confirm`,按返回 job 或 `--wait` 输出确认 YAML 声明的镜像已存在于目标 runtime。 6. 镜像准备好后执行 `sub2api apply --target --confirm`,按返回的 `job status` 命令轮询完成。 7. 执行 `sub2api status --target `,确认运行镜像等于 YAML 声明;滚动过程中短暂 `0/1` 先等待并复查,不要立即改账号池、Caddy 或 Secret。 -8. 执行 `sub2api validate --target `、目标 public `/health` 和最小 public `/v1/responses` smoke;若需要确认未影响其它公开入口,再跑对应 target 的 `validate`。 +8. 执行 `sub2api validate --target ` 和目标 public `/health`;若需要确认未影响其它公开入口,再跑对应 target 的 `validate`。 +9. 镜像升级禁止配置对齐: + - 不得执行 `codex-pool plan`、`codex-pool sync` 或 `codex-pool validate`; + - 不得对齐账号、group、统一 key、capacity、load factor、WebSocket、临时不可调度规则、代理绑定或手工账号。 +10. 镜像升级的真实模型请求证据: + - 只能复用升级前已经存在的消费配置执行无写入 smoke; + - 不得为完成 smoke 创建、恢复、同步或覆盖任何配置。 不要把镜像版本写进脚本常量、JSON 或 manifest 模板。 diff --git a/.agents/skills/unidesk-sub2api/references/validation.md b/.agents/skills/unidesk-sub2api/references/validation.md index 8e1d876c..8b2d630a 100644 --- a/.agents/skills/unidesk-sub2api/references/validation.md +++ b/.agents/skills/unidesk-sub2api/references/validation.md @@ -2,11 +2,31 @@ 部署 closeout 至少包含: +- 镜像升级验收: + - 只验证镜像、容器健康、依赖连通性和公开入口健康; + - 不执行 `codex-pool plan`、`codex-pool sync` 或 `codex-pool validate`; + - 保持账号池和手工配置原样,防止升级覆盖手动配置。 +- 镜像升级的真实模型请求证据: + - 只复用既有消费配置做无写入 smoke; + - 缺少既有消费配置时记录为未执行; + - 不得通过恢复 key、同步账号或对齐 group 补齐验收条件。 + - `sub2api status`:Deployment/StatefulSet/Service/Secret/NetworkPolicy 可见,运行镜像与 YAML 一致,`NetworkPolicy/allow-all` 符合 `podSelector: {}`、Ingress/Egress 全放行。 - `sub2api validate`:app、PostgreSQL、Redis、service proxy、`NetworkPolicy/allow-all` 和临时跨 Pod PostgreSQL/Redis 连通性检查通过。 -- `codex-pool validate`:统一 key 的 `GET /v1/models` 成功,并用 `localCodex.responsesSmokeModel` 跑一次小的 `POST /v1/responses` smoke;owner balance / owner concurrency 已满足 YAML 最小值,capacity、WebSocket v2、Sub2API 内置 temporary-unschedulable 开关/规则和 sentinel runtime 状态与 YAML 对齐;`validation.gatewayResponsesRecent` 汇总最近 6 小时普通 `/responses` 和 `/v1/responses` 的 failover、forward failure、最终 4xx/5xx、慢 final error 与 `context canceled` 证据,`validation.gatewayCompactRecent` 单独汇总 `/responses/compact` 证据。若当前 Responses smoke `ok=true` 但 recent 字段 `degraded=true`,先区分是历史窗口残留还是新的 request id 正在失败;长期判定见 `docs/reference/platform-infra.md`。 +- 账号池验收: + - 仅在用户明确要求账号池运维或配置对齐时执行 `codex-pool validate`; + - 统一 key 的 `GET /v1/models` 必须成功; + - 使用 `localCodex.responsesSmokeModel` 跑一次小的 `POST /v1/responses` smoke; + - owner balance、owner concurrency、capacity、WebSocket v2、临时不可调度规则和 sentinel runtime 必须与 YAML 对齐; + - `validation.gatewayResponsesRecent` 汇总最近 6 小时普通 `/responses` 和 `/v1/responses` 的错误证据; + - `validation.gatewayCompactRecent` 单独汇总 `/responses/compact` 证据; + - 当前 Responses smoke 成功但 recent 字段 degraded 时,先区分历史窗口残留和新的 request id 失败; + - 长期判定见 `docs/reference/platform-infra.md`。 - 若 `publicExposure.enabled=true`,确认 YAML 声明的 public path 可用。FRP target 检查 FRP path;PK01 local target 检查 PK01 Caddy managed block 和 loopback upstream。未带 key 的 public `/v1/models` 401 只能证明网关可达,不能证明账号池可调度。 -- 多 target 同时启用 public exposure 时,必须分别验证每个 target 的 root、`/health`、未带 key `/v1/models` 401,以及各自 `codex-pool validate --target `;一个域名可用不能替代另一个域名的验收。 +- 多 target 公开入口验收: + - 分别验证每个 target 的 root、`/health` 和未带 key `/v1/models` 401; + - 只有用户明确要求账号池运维或配置对齐时,才执行各自的 `codex-pool validate --target `; + - 一个域名可用不能替代另一个域名的验收。 - 若目标声明了 `egressProxy.enabled=true`,确认 proxy Deployment/Service ready,Sub2API 和 sentinel env 与 YAML 对齐,并通过 YAML 声明的 health URL 完成代理出站探针。 如果要证明真实模型请求可用,使用最小 `/v1/responses` 或等价 Codex smoke。不要把 group-level `/v1/models` 成功解释成每个上游 account 都健康。