feat: 加速 Sub2API 版本发布流程

2026-07-15 19:15:11 +02:00
parent e9360bd589
commit b6fb219579
10 changed files with 513 additions and 12 deletions
@@ -19,6 +19,7 @@ UniDesk 通过 `platform-infra sub2api` 运维 YAML 选中的 Sub2API target；
 bun scripts/cli.ts platform-infra sub2api report
 bun scripts/cli.ts platform-infra sub2api status --target PK01
 bun scripts/cli.ts platform-infra sub2api validate --target PK01
+bun scripts/cli.ts platform-infra sub2api rollout --target PK01 --dry-run
 bun scripts/cli.ts platform-infra sub2api ops diagnosis --target PK01
 bun scripts/cli.ts platform-infra sub2api ops channels --target PK01 --window 7d
 bun scripts/cli.ts platform-infra sub2api plan --target PK01
@@ -1,5 +1,14 @@
 # UniDesk Sub2API

+## 目录
+
+- [先看报表](#先看报表)
+- [先读边界](#先读边界)
+- [部署与状态](#部署与状态)
+- [PK01 host-Docker target](#pk01-host-docker-target)
+- [D601 Egress Proxy](#d601-egress-proxy)
+- [镜像升级](#镜像升级)
+
 UniDesk 通过 `platform-infra sub2api` 运维 YAML 选中的 Sub2API target。当前 active target 以 `config/platform-infra/sub2api.yaml` 为准；PK01 可作为 host-Docker active target 并通过 PK01 Caddy 本地反代提供 `api.pikapython.com`，D518/D601 等 k3s target 仍可按 YAML 声明为 external-active 或 retired，G14 由同一 YAML/CLI 控制为 standby predeploy。日常操作统一使用 UniDesk CLI，不直接写 Kubernetes 资源或手工调用 Sub2API 管理 API。

 **固定入口**: `cd /root/unidesk && bun scripts/cli.ts platform-infra sub2api ...`
@@ -41,6 +50,9 @@ bun scripts/cli.ts platform-infra sub2api plan
 bun scripts/cli.ts platform-infra sub2api plan --target G14
 bun scripts/cli.ts platform-infra sub2api image-prepull --target PK01
 bun scripts/cli.ts platform-infra sub2api image-prepull --target PK01 --confirm
+bun scripts/cli.ts platform-infra sub2api rollout --target PK01 --dry-run
+bun scripts/cli.ts platform-infra sub2api rollout --target PK01 --confirm
+bun scripts/cli.ts platform-infra sub2api smoke --target PK01
 bun scripts/cli.ts platform-infra sub2api apply --dry-run
 bun scripts/cli.ts platform-infra sub2api apply --target G14 --dry-run
 bun scripts/cli.ts platform-infra sub2api apply --confirm
@@ -69,7 +81,13 @@ PK01 没有 k3s control plane。`codex-pool sync --target PK01 --confirm` 和 `c

 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。

-正式镜像升级前必须用 `platform-infra sub2api image-prepull --target <id> --confirm` 预拉 YAML 声明的 Sub2API runtime images；不带 `--confirm` 只做 inspect/dry-run。`--confirm` 默认返回 async job，显式 `--wait` 才同步等待。不得用临时 `trans <node> docker pull ...` 作为长期入口。
+- 正式镜像升级优先使用 `platform-infra sub2api rollout`：
+  - 同一入口组合镜像 presence、plan、apply dry-run、预拉、apply、status、validate 和既有消费配置 smoke；
+  - `--confirm` 默认返回 async job，显式 `--wait` 只用于 job 内部或同步调试；
+  - 镜像预拉长连接预算读取 `defaults.rollout.imagePrepullTimeoutSeconds`；
+  - 禁止依赖默认 60 秒 SSH 上限反复续拉。
+- `image-prepull` 只作为单阶段诊断入口，不作为标准升级主路径。
+- 禁止用临时 `trans <node> docker pull ...` 作为长期入口。

 ## D601 Egress Proxy

@@ -89,19 +107,43 @@ proxy secret/config 文件只允许放在受控 Secret/state 路径，输出只

 ## 镜像升级

-1. 先定位目标 target 的 `id`、`publicBaseUrl` 和当前 `image` block。`config/platform-infra/sub2api.yaml` 同时有全局默认镜像和多个 target-scoped 镜像；只升级单个 target 时必须用 `id: <target>` 附近的上下文 patch，不能按第一个 `tag:` 命中。
-2. 只修改目标 target 的 `image.repository`、`image.tag` 或 `pullPolicy`；不要顺手改全局默认、PK01 host-Docker target、standby target 或其它共用 `api2.pikapython.com` 历史 target。
-3. 提交前用 `git diff -- config/platform-infra/sub2api.yaml` 和 `rg -n "id: <target>|tag: <version>|publicBaseUrl"` 确认只有目标 target 变化，且要保护的公开入口没有被误改。
-4. 执行 `sub2api plan --target <target>` 和 `sub2api apply --target <target> --dry-run`，确认策略检查通过。
-5. 提交并推送 YAML source truth 后，执行 `sub2api image-prepull --target <target> --confirm`，按返回 job 或 `--wait` 输出确认 YAML 声明的镜像已存在于目标 runtime。
-6. 镜像准备好后执行 `sub2api apply --target <target> --confirm`，按返回的 `job status` 命令轮询完成。
-7. 执行 `sub2api status --target <target>`，确认运行镜像等于 YAML 声明；滚动过程中短暂 `0/1` 先等待并复查，不要立即改账号池、Caddy 或 Secret。
-8. 执行 `sub2api validate --target <target>` 和目标 public `/health`；若需要确认未影响其它公开入口，再跑对应 target 的 `validate`。
-9. 镜像升级禁止配置对齐：
+- 目标 patch：
+  - 只修改目标 target 的 `image.repository`、`image.tag` 或 `pullPolicy`；
+  - 使用 target 附近的上下文 patch；
+  - 不按第一个 `tag:` 命中，不改全局默认或其他 target。
+- 发布 dry-run：
+  - 只调用一次 `sub2api rollout --target <target> --dry-run`；
+  - 默认摘要同时披露当前镜像、目标镜像、presence、plan 和 apply dry-run；
+  - 摘要完整时不再分别调用 `status`、`plan`、`image-prepull` 和 `apply --dry-run`。
+- PR 身份：
+  - 提交并推送 YAML source truth，创建 draft PR；
+  - 创建后立即回读准确 PR；
+  - 核对 PR number、head branch 和 head SHA 与当前分支完全一致；
+  - 禁止通过“最新 PR”、列表顺序或相邻编号推断操作对象。
+- 发布确认：
+  - 只调用一次 `sub2api rollout --target <target> --confirm`；
+  - 按返回的唯一 `job status` 命令观察终态；
+  - job 内顺序完成预拉和 apply，并行完成 status、validate 与既有消费配置 smoke；
+  - 不在外部重复逐阶段轮询。
+- 报告与合并：
+  - 把 job 终态和分阶段耗时写入同一 PR 的 MDTODO 报告；
+  - 推送后将准确 PR 标记 ready，再通过 guarded merge 合入；
+  - 运行面成功但 PR 身份或 source truth 不一致时，先恢复准确分支，不重复 rollout。
+- 精确下钻：
+  - 只有 rollout 终态缺少某项证据时，才使用输出给出的下钻命令；
+  - 不固定重复执行 status、validate、public health 或 smoke。
+- 镜像升级禁止配置对齐：
   - 不得执行 `codex-pool plan`、`codex-pool sync` 或 `codex-pool validate`；
   - 不得对齐账号、group、统一 key、capacity、load factor、WebSocket、临时不可调度规则、代理绑定或手工账号。
-10. 镜像升级的真实模型请求证据：
+- 镜像升级的真实模型请求证据：
   - 只能复用升级前已经存在的消费配置执行无写入 smoke；
+   - `rollout` 自动复用匹配目标 public URL 的 `~/.codex/config.toml` 和 `auth.json`；
+   - 配置缺失或目标不匹配时只报告 skipped；
   - 不得为完成 smoke 创建、恢复、同步或覆盖任何配置。

+- 正常热缓存升级的操作目标是 5 分钟内完成：
+  - `rollout` 输出 `prepull`、`apply`、`verify` 和 `total` 分阶段耗时；
+  - 超时先按失败 stage 下钻；
+  - 不回退到旧的十余条手工串联流程。
+
 不要把镜像版本写进脚本常量、JSON 或 manifest 模板。