From 8f54b591d7efab4feacfe9cbcdf3ca94b445976f Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 1 Jul 2026 14:53:24 +0000 Subject: [PATCH] docs: record sub2api account sync closeout pitfalls --- .agents/skills/unidesk-sub2api/references/manual-accounts.md | 2 ++ .agents/skills/unidesk-sub2api/references/sentinel.md | 2 +- .agents/skills/unidesk-sub2api/references/upstreams.md | 4 ++-- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.agents/skills/unidesk-sub2api/references/manual-accounts.md b/.agents/skills/unidesk-sub2api/references/manual-accounts.md index 4c65a3e6..24f4330a 100644 --- a/.agents/skills/unidesk-sub2api/references/manual-accounts.md +++ b/.agents/skills/unidesk-sub2api/references/manual-accounts.md @@ -15,3 +15,5 @@ bun scripts/cli.ts platform-infra sub2api codex-pool validate --target D601 ``` `sync` 输出应显示 `manualAccounts.ok=true`、`proxySync.ok=true`、`groupSync.ok=true`，且该账号的 proxy/group `bindingAligned=true`。`sentinel-probe --account --confirm` 对受保护手动账号必须继续拒绝，通常返回 `account-protected-manual`；不要为了测试而把该账号移入 `profiles.entries` 或取消保护。需要证明 WebUI 同款账号测试恢复时，用 Sub2API admin account test 原入口测最小 `hi` 和默认/受支持模型，并只记录 account id、proxy id、event types、HTTP status 和短 output preview，不记录 OAuth token 或 Secret 明文。若指定模型返回 “model is not supported when using Codex with a ChatGPT account” 一类能力错误，先归因到模型能力/映射，而不是 proxy。 + +如果 `manualAccounts.protected` 中声明的账号在当前 Sub2API 运行面已经不存在，`codex-pool sync --confirm` / `validate` 会把 `manualAccounts.ok=false`、`proxySync.action=account-missing` 或 `groupSync.action=account-missing` 作为整体失败项。这是手动账号漂移，不是 YAML-managed pool 账号创建失败；不要自动创建、删除、接管或从 YAML 移除该手动账号。先确认账号所有权：需要继续保护时由人工在 Sub2API UI 恢复同名账号，再跑 sync 对齐 proxy/group；确认退役时再按明确决策修改 `manualAccounts.protected`。对同一次新增的 YAML-managed 上游，可用该账号自己的 `sentinel-probe --account --confirm`、`sentinel-report` 和 `trace` 作为窄验收证据，并把手动账号漂移单独登记。 diff --git a/.agents/skills/unidesk-sub2api/references/sentinel.md b/.agents/skills/unidesk-sub2api/references/sentinel.md index 817426ec..cb0838d2 100644 --- a/.agents/skills/unidesk-sub2api/references/sentinel.md +++ b/.agents/skills/unidesk-sub2api/references/sentinel.md @@ -11,7 +11,7 @@ 对已支持的 k3s target，`sync --confirm` 会登录 Sub2API admin、创建/更新 group、创建/更新 YAML 中的 `unidesk-codex-*` accounts、创建/复用统一 API key Secret，并部署/更新哨兵资源；它不把既有 managed account 直接恢复为 `schedulable=true`。恢复只由哨兵在读取 Sub2API runtime `schedulable=false` 后触发 recovery probe，并在 marker 命中时执行。`sync` 默认不删除 YAML 中缺席的 managed account。只有明确退役上游时才使用 `sync --confirm --prune-removed` 删除缺席且 `extra.unidesk_managed=true` 的 `unidesk-codex-*` account。对 `manualAccounts.protected`，`sync` 只执行 YAML 显式允许的窄同步；当前允许项是从目标 `egressProxy` 创建/更新 Sub2API internal proxy 记录并绑定 `proxy_id`，以及把受保护手动账号加入当前 `pool.groupName`。它仍不接管该账号凭据、status、schedulable、priority/capacity/loadFactor 或哨兵状态。PK01 host-Docker target 在 codex-pool adapter 补齐前不具备这条完整 sync 路径。 -`sentinel-image status|build` 管理哨兵 Python 运行环境镜像。镜像由 YAML 的 `sentinel.image` 基础镜像和 `sentinel.sdk.openaiPythonVersion` 派生，发布到目标 runtime 的本地 registry；`build --confirm` 会先检查 registry tag，存在则快速复用，不存在才在目标 host 构建并 push。CronJob 启动时只校验 SDK 版本，不在运行时 `pip install`。目标是否启用哨兵以 `config/platform-infra/sub2api.yaml` 的 `sentinel.enabledOnTargets` 为准；未启用的 target 在 `sync`/`validate` 中应显示 `skipped-target-disabled`，不得要求镜像构建、CronJob、Secret 或 state ConfigMap 存在。 +`sentinel-image status|build` 管理哨兵 Python 运行环境镜像。镜像由 YAML 的 `sentinel.image` 基础镜像和 `sentinel.sdk.openaiPythonVersion` 派生，发布到目标 runtime 的本地 registry；`build --confirm` 会先检查 registry tag，存在则快速复用，不存在才在目标 host 构建并 push。CronJob 启动脚本会通过导出的 `OPENAI_PYTHON_VERSION` 校验 SDK 版本；当当前 target 使用基础 Python 镜像作为 runtime image 时，容器启动会按 YAML pin 执行一次 `pip install openai==$OPENAI_PYTHON_VERSION`，日志可能主要是依赖下载，完成后再运行 `/opt/sentinel/sentinel.py`。目标是否启用哨兵以 `config/platform-infra/sub2api.yaml` 的 `sentinel.enabledOnTargets` 为准；未启用的 target 在 `sync`/`validate` 中应显示 `skipped-target-disabled`，不得要求镜像构建、CronJob、Secret 或 state ConfigMap 存在。 `sync --confirm` 同时会按 YAML 渲染账号级哨兵资源，并在 monitor 开启时先确保可复用哨兵镜像存在。当前目标是 `sentinel.monitor.enabled=true` + `sentinel.actions.enabled=true` 的 marker-only 自动冻结/恢复；不要手工 patch CronJob、Secret 或 Sub2API account。若 YAML 新增账号或修改 profile/base URL/API key fingerprint/upstream User-Agent/Responses WebSocket mode，sync 会从变更前 runtime state 写入 pending probe 记录并立即安排 sentinel probe，但不会把既有账号直接恢复为可调度；只有 sentinel 读取到 Sub2API runtime `schedulable=false` 后执行 recovery probe，且 marker 命中，才恢复 `schedulable=true`。sentinel 冻结/恢复只改 `schedulable=false|true`，不得顺手调用 Sub2API `recover-state` 清除请求路径临时不可调度或其他 runtime backoff。无关账号的既有成功/失败退避不能被重置。若 YAML 下调失败冻结最大窗口，sync 会把仍 active 的旧冻结状态迁移到当前最大窗口内并立即安排 recovery probe，但不会直接解冻。若怀疑某个账号被误判，先用 `codex-pool sentinel-probe --account --confirm` 立即触发该账号测量；该命令从现有 CronJob 模板派生一次性 Job，复用同一份 Secret、ConfigMap、OpenAI SDK probe、token/cost 账本和冻结/恢复状态机。 diff --git a/.agents/skills/unidesk-sub2api/references/upstreams.md b/.agents/skills/unidesk-sub2api/references/upstreams.md index 73797f26..90d74feb 100644 --- a/.agents/skills/unidesk-sub2api/references/upstreams.md +++ b/.agents/skills/unidesk-sub2api/references/upstreams.md @@ -1,12 +1,12 @@ ## 添加上游 -1. 在 master `~/.codex/` 准备带后缀的上游 profile 文件，例如 `config.toml.` 和 `auth.json.`；禁止覆盖默认 `config.toml` / `auth.json`。 +1. 在 master `~/.codex/` 准备带后缀的上游 profile 文件，例如 `config.toml.` 和 `auth.json.`；禁止覆盖默认 `config.toml` / `auth.json`。`codex-pool configure-local` 只重写默认消费端，不用于新增上游 profile。 2. 在 `config/platform-infra/sub2api-codex-pool.yaml` 添加 `profiles.entries` 项，指定 `profile`、`accountName`、`configFile`、`authFile`。 3. 如需要，给该项加 `priority`、`capacity`、`loadFactor`、`trustUpstream`、`sentinelProtect`、`openaiResponsesWebSocketsV2Mode` 或 `upstreamUserAgent`；capacity/loadFactor/信任退避/保护阈值的具体数值只写在 YAML。只有显式恢复 Sub2API 内置临时不可调度时才添加 per-account `tempUnschedulable`。 4. 如果新增账号会提高声明 capacity 总和，默认让省略的 `pool.minOwnerConcurrency` 继续按 capacity 总和自动解析；只有 YAML 已经显式写了该 override 时，才同步提高到不低于总 capacity，或删除 override 回到自动解析。 5. 跑 `codex-pool plan`，确认 profile 可读、`base_url` 和 API key 来源有效，且 stdout 未泄露完整 key。 6. 跑 `codex-pool sync --confirm`。 -7. 跑 `codex-pool validate`。 +7. 跑 `codex-pool validate`。如果整体 validate 只被既有 `manualAccounts.protected` 缺失或未对齐卡成 false，不能把它归因到新上游；对新增 YAML-managed account 用 `sentinel-probe --account --confirm` 和 `sentinel-report` 做窄验证，同时把手动账号漂移单独登记处理。 普通新增上游是 YAML 操作，不走 CI/CD，不改代码。只有需要渲染或校验上游 Sub2API 已经存在的可复用能力时才修改 `scripts/src/platform-infra-sub2api-codex.ts`；Sub2API 本身不支持的能力不在 UniDesk 侧魔改实现。