feat: add ops center and node onboarding flow

2026-04-18 23:52:51 +08:00
parent 246838ae4c
commit b9c29481b5
142 changed files with 89727 additions and 186 deletions
--- a/docs/26_domainCheck_发布前运行验证与交付模板.md
+++ b/docs/26_domainCheck_发布前运行验证与交付模板.md
@@ -0,0 +1,635 @@
+# 26 domainCheck 发布前运行验证与交付模板
+
+## 一、这份模板怎么用
+
+这份文档不是设计说明，而是正式发布前最后一轮执行模板。
+
+适用场景：
+
+- 海外单脑控制面已经搭好
+- 大陆节点已经接入或正在收口
+- 代码已经更新到待发布版本
+- 现在要做最后一轮运行验证、证据留存、交付确认
+
+这份模板分成 3 段：
+
+1. 发布前运行验证
+2. 上线证据导出
+3. 最终交付结论模板
+
+---
+
+## 二、发布前运行验证
+
+### 1. 先跑统一收口摘要
+
+```bash
+cd /www/wwwroot/getDomain
+bash domain-api/deploy/multi-region/drive_ops_center.sh go-live-check http://127.0.0.1:8100 http://127.0.0.1:8100 summary
+```
+
+记录结果：
+
+- `go_live_status`
+- `publish_status`
+- `blocking_reasons`
+- `warnings`
+- `next_step_action_code`
+- `operator_title`
+- `launchpad_recommended_target_node_code`
+- `launchpad_recommended_recovery_label`
+- `launchpad_recommended_recovery_summary`
+- `launchpad_onboarding_bootstrap_pending_nodes`
+- `launchpad_onboarding_acceptance_ready_nodes`
+
+通过标准：
+
+- `go_live_status != blocked`
+- `publish_status != blocked`
+
+### 1.5 先看环境差异是否已收口
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh env-audit
+bash domain-api/deploy/multi-region/drive_ops_center.sh runtime-refresh-recover
+bash domain-api/deploy/multi-region/drive_ops_center.sh go-live-recover
+```
+
+重点只看：
+
+- `status`
+- `headline`
+- `python.pytest_installed / fastapi_installed / uvicorn_installed`
+- `python.runtimes`
+- `services`
+- `runtime.preflight_ok`
+- `runtime.readiness_status`
+- `runtime.route_surface_complete`
+- `missing_items`
+- `tooling_items`
+
+通过标准建议：
+
+- `status != blocked`
+- `runtime.preflight_ok=true`
+- `route_surface_complete=true`
+- 如果 `missing_items` 里仍有关键基础项，先补环境，再继续业务复核
+- 如果只有 `tooling_items`，可以继续上线复核，但建议后补本机工具链
+- 如果 `runtime.runtime_may_need_restart=true`
+  - 不要直接继续接管或发布链
+  - 先按 `runtime-refresh-recover` 给出的固定顺序完成 API 重启与复检
+- 如果你希望把这一轮“重启 + 总检 + 默认下一步 + 上线摘要”压成一次复核
+  - 直接执行 `go-live-recover`
+
+### 1.6 先看托管节点接入面是否清楚
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh nodes http://127.0.0.1:8100
+```
+
+重点只看：
+
+- `summary.agent_ready`
+- `summary.ssh_ready`
+- `summary.remote_access_ready`
+- `summary.remote_access_state_counts`
+- 每台节点的 `agent_state`
+- 每台节点的 `remote_access_state`
+- 每台节点的 `ssh_access_label`
+- 每台节点的 `ssh_entry`
+
+通过标准建议：
+
+- 如果某台节点还是 `agent_pending`
+  - 先确认是否已经保存 SSH 入口
+- 如果节点尚未保存 SSH 入口，但你已经决定由海外控制面统一接管
+  - 先补录：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh node-bind-ssh http://127.0.0.1:8100 mainland-worker-01 121.204.244.248 root 22
+```
+
+- 补录后立即复查：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh nodes http://127.0.0.1:8100
+bash domain-api/deploy/multi-region/drive_ops_center.sh node-handover http://127.0.0.1:8100 mainland-worker-01
+```
+
+- 如果已经 `agent_ready`
+  - 说明该节点已进入标准远端执行器接管面
+- 如果还不是 `agent_ready`，但 `ssh_ready` 已经成立
+  - 说明至少已经具备海外主控经 SSH 进入节点完成 bootstrap / 验收的前置条件
+
+### 2. 再看总检详情
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh stack-diagnosis
+```
+
+记录结果：
+
+- `stack_status`
+- `issues`
+- `next_step`
+- `quick_commands`
+
+通过标准：
+
+- `stack_status != blocked`
+- `issues` 里没有未处理的关键阻断项
+
+### 3. 再看驾驶主线
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh driver-feed
+bash domain-api/deploy/multi-region/drive_ops_center.sh codex-brief
+```
+
+记录结果：
+
+- `top_recommendation`
+- `automation_coverage`
+- `recommended_behavior`
+- `focus`
+- `summary.launchpad_recommended_target_node_code`
+- `summary.launchpad_recommended_recovery_label`
+- `summary.launchpad_onboarding_bootstrap_pending_nodes`
+- `summary.launchpad_onboarding_acceptance_ready_nodes`
+
+通过标准：
+
+- `automation_coverage.launch_status != blocked`
+- 默认下一步已经明确
+- 如果 `summary.launchpad_recommended_target_node_code` 非空
+  - 值班同事应能直接知道当前卡在哪台节点
+  - 不需要再回 launchpad 明细手工翻 gap rows
+
+### 4. 若涉及发布，再看 Release Hub
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh release-launchpad
+```
+
+记录结果：
+
+- `launchpad_status`
+- `recommended_action_code`
+- `default_rollout_gate_status`
+- `recommended_target_node_code`
+- `recommended_recovery_label`
+- `recommended_recovery_summary`
+- `onboarding_bootstrap_pending_nodes`
+- `onboarding_acceptance_ready_nodes`
+
+通过标准：
+
+- `launchpad_status != blocked`
+- `default_rollout_gate_status != blocked`
+
+特殊判读：
+
+- 如果 `recommended_action_code=api-restart`
+  - 不要误判成“节点没接好”
+  - 这更像是运行中的控制面 API 还没刷新到当前仓库的最新运维能力
+  - 应先执行：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh runtime-refresh-recover
+```
+
+  - 然后重新跑：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh stack-diagnosis
+bash domain-api/deploy/multi-region/drive_ops_center.sh release-launchpad
+```
+
+补充说明：
+
+- 从 `latest_release.json` 直接创建 Release，或执行“基于最新包的一键智能 Rollout”之前
+- 现在不仅要求 `smoke_test_ok=true`
+- 还要求当前 `final_release_report.json` 与最新包完全匹配，且 `final_release_ok=true`
+- 如果页面按钮被禁用，或 API 返回“最新发布包尚未完成最终签收”
+  - 优先检查 `final_release_report_stale_reason`
+  - 再检查 `final_release_gate_decision / final_release_gate_blocked_reasons`
+
+### 5. 若涉及节点接管，补跑节点验收
+
+如果这次发布包含：
+
+- 新增大陆节点
+- 重新接管旧节点
+- 切换到 Node Agent 主接管模式
+
+则不能只看总检摘要，还要对目标节点逐台完成验收。
+
+先看验收计划：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh node-acceptance-plan http://127.0.0.1:8100 mainland-worker-01
+```
+
+确认无误后执行：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh node-acceptance-run http://127.0.0.1:8100 mainland-worker-01 cli/acceptance
+```
+
+记录结果：
+
+- `node_code`
+- `status`
+- `checks`
+- `blocking_issues`
+- `warnings`
+- `recommended_next_step`
+
+通过标准：
+
+- `status != blocked`
+- 没有未处理的 `blocking_issues`
+- 目标节点已经不再停留在“bootstrap pending / acceptance pending”
+
+### 6. 若涉及远端执行，补跑日志回传验证
+
+如果当前版本准备进入：
+
+- 多机值班
+- 海外单脑统一接管
+- 远端动作回执与现场日志复核
+
+则需要确认日志回传链已经可用，而不是只看节点在线。
+
+先检查：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh log-sync-check
+```
+
+如果存在缺口，再执行恢复：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh log-sync-recover http://127.0.0.1:8100 key confirm cli/log-sync
+```
+
+必要时抓一份节点现场日志：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh scene-node-log http://127.0.0.1:8100 mainland-worker-01 120 full
+```
+
+记录结果：
+
+- `log_sync_enabled`
+- `line_count`
+- `source_nodes`
+- `missing_nodes`
+- `scene_log.status`
+
+通过标准：
+
+- 关键节点已出现在 `source_nodes`
+- `missing_nodes` 不包含当前发布主车道节点
+- 如需人工复核现场，`scene-node-log` 能取到有效日志
+
+### 7. 若涉及 Node Agent 交付，补看队列健康
+
+如果这轮发布已经进入“控制面发动作、节点拉任务、节点回执结果”的模式，就必须确认 delivery queue 没有假健康。
+
+先看队列摘要：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh queue-status http://127.0.0.1:8100 mainland-worker-01
+```
+
+如果怀疑有堆积或死信，再看明细：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh queue-records http://127.0.0.1:8100 mainland-worker-01 dead_letter
+```
+
+如需重放：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh queue-replay http://127.0.0.1:8100 mainland-worker-01 20 cli/queue-replay
+```
+
+记录结果：
+
+- `delivery_queue.summary`
+- `dead_letter`
+- `retrying`
+- `pending`
+- `replayed_count`
+
+通过标准：
+
+- `dead_letter=0`
+- 没有持续增长的 `retrying`
+- 队列不处于异常堆积状态
+
+注意：
+
+- `dead_letter > 0` 时，不应宣称“可正式发布”
+- 这种情况至少按 `publish_status = blocked` 处理
+
+### 8. 最后跑一次 doctor 结论
+
+前面的检查是分面复核，最后还要再收成一句话，让交班、值班、Codex 驾驶员看到同一结论。
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh doctor-decision
+```
+
+记录结果：
+
+- `status`
+- `decision`
+- `recommended_commands`
+- `recommended_reading_order`
+- `launchpad_alignment`
+
+通过标准：
+
+- `status != blocked`
+- `decision` 与前面的 `go-live-check / stack-diagnosis / release-launchpad` 不冲突
+- `recommended_commands` 已经指向明确的下一跳，而不是泛化排查
+
+### 9. 若希望直接生成“可否签字上线”的最终摘要
+
+如果你不想手工再拼：
+
+- bundle review
+- doctor 结论
+- 发布门禁
+
+可以直接执行：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh go-live-signoff
+```
+
+如果已经有现成证据包，也可以直接基于 manifest 输出：
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh go-live-signoff /path/to/go-live-bundle
+```
+
+这一步现在不是“另一套单独判断”，而是固定复用：
+
+- `go-live-review`
+- `doctor-decision`
+- `go-live-summary / 发布门禁 / launchpad 摘要`
+
+也就是说，页面首屏、CLI 和海外 Codex 看到的最终签收结论，已经开始共享同一份签字口径。
+
+重点只看：
+
+- `signoff_status`
+- `headline`
+- `release_gate`
+- `blocked_reasons`
+- `attention_reasons`
+- `decision`
+- `recommended_commands`
+
+通过标准：
+
+- `signoff_status=ready`
+  - 可进入最终人工签字或正式发布
+- `signoff_status=attention`
+  - 说明现场已经接近完成，但仍应先清 attention 项
+- `signoff_status=blocked`
+  - 本轮不应宣称收口完成
+
+---
+
+## 三、上线证据导出
+
+### 1. 导出 bundle
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh go-live-export
+```
+
+这会生成一整包上线前证据。
+
+建议至少保留：
+
+- `00_env_audit.txt`
+- `01_go_live_check_summary.txt`
+- `02_go_live_summary.json`
+- `03_stack_diagnosis.json`
+- `04_driver_feed.json`
+- `05_codex_brief.json`
+- `06_release_launchpad.json`
+- `manifest.json`
+
+如果当前轮次涉及节点接管，建议额外保留：
+
+- `agent_gap_export.json`
+- `node_bootstrap_plan.txt`
+- `node_acceptance_plan.json`
+
+如果当前轮次涉及远端执行与日志回传，建议额外保留：
+
+- `scene_log_*.txt`
+- `doctor_decision.json`
+
+### 2. 直接复核 bundle
+
+```bash
+bash domain-api/deploy/multi-region/drive_ops_center.sh go-live-review
+```
+
+如果你已经切到 Ops Center 页面，也可以直接看：
+
+- 首屏 `总检决策`
+- `总检主决策详情`
+- API `GET /api/v1/ops/doctor-decision`
+- 首屏 `交付证据`
+- `交付证据详情`
+- API `GET /api/v1/ops/go-live-bundle`
+- 首屏 `正式复核`
+- `正式复核详情`
+- API `GET /api/v1/ops/go-live-review`
+
+记录结果：
+
+- `status`
+- `headline`
+- `critical_failures`
+- `noncritical_failures`
+- `launchpad_alignment.consistent`
+- `env_audit.status`
+- `env_audit.missing_items`
+- `recommended_next_steps`
+
+通过标准建议：
+
+- `status=ready`
+  - 可进入最终人工确认或正式发布
+- `status=attention`
+  - 核心报告已齐，但仍需复核补充失败项或环境缺口
+  - 也包括 `go_live_summary / stack_diagnosis / driver_feed / codex_brief` 的 launchpad 摘要出现不一致
+- `status=blocked`
+  - 关键报告缺失，或环境审计已经判定阻断，不应直接宣称收口完成
+
+如果 `env_audit.missing_items` 里出现：
+
+- `missing_env:/etc/default/domaincheck-node-agent`
+
+则这次 bundle review 已经不是泛泛地提示“环境缺口”，而是明确指向 Node Agent 接管还未收口。此时按下面顺序推进：
+
+1. `agent-gap-export`
+2. `node-bootstrap-plan`
+3. 如果 summary 已提示 `runtime_may_need_restart=true`
+4. 完成恢复后重新导出 bundle，再做一次 `go-live-review`
+
+### 3. 生成最终交付包
+
+运行验证、bundle 复核都通过后，再生成最终交付包。
+
+如果当前机器已经具备 smoke 运行条件，直接执行：
+
+```bash
+bash ./prepare_final_release.sh
+```
+
+如果当前机器只适合先做离线打包，可先跳过 smoke：
+
+```bash
+DOMAINCHECK_SKIP_SMOKE_TEST=1 bash ./package_domain_release.sh
+bash ./verify_domain_release.sh
+```
+
+后续再回到具备运行条件的机器上执行：
+
+```bash
+bash ./prepare_final_release.sh
+```
+
+最后统一查看最新交付结果：
+
+```bash
+bash ./show_latest_release.sh
+```
+
+重点只看：
+
+- `latest_release.package_name`
+- `latest_release.archive_path`
+- `latest_release.sha256`
+- `latest_release.smoke_test_ok`
+- `final_release_ok`
+- `final_release_report`
+- `final_release_report_ok`
+- `final_release_report_matches_latest`
+- `final_release_report_stale_reason`
+- `final_release_gate_decision`
+- `final_release_gate_blocked_reasons`
+- `final_release_gate_verify_ok`
+- `final_release_gate_smoke_test_ok`
+
+通过标准：
+
+- `verify_domain_release.sh` 返回 `ok=true`
+- `latest_release.smoke_test_ok=true`
+- `final_release_ok=true`
+- `final_release_report_matches_latest=true`
+- `final_release_gate_decision=ready`
+- `final_release_gate_verify_ok=true`
+- `final_release_gate_smoke_test_ok=true`
+- `final_release_report` 已指向最新一轮生成的正式报告
+4. 先执行 `runtime-refresh-recover`
+5. 再重新导出 bootstrap plan
+
+---
+
+## 四、最终交付结论模板
+
+下面这段可以直接作为正式发布前的交付结论模板使用。
+
+### 模板正文
+
+```text
+本轮发布前运行验证已完成。
+
+一、统一收口结论
+- go_live_status: <填写>
+- publish_status: <填写>
+- stack_status: <填写>
+- automation_coverage.launch_status: <填写>
+- launchpad_status: <填写>
+
+二、默认下一步
+- next_step_action_code: <填写>
+- operator_title: <填写>
+- launchpad_recommended_target_node_code: <填写>
+- launchpad_recommended_recovery_label: <填写>
+
+三、上线证据包
+- bundle 路径: <填写>
+- manifest 复核状态: <填写 ready/attention/blocked>
+- go-live-review.headline: <填写>
+- manifest.review_status_hint: <填写>
+- critical_failures: <填写>
+- noncritical_failures: <填写>
+- manifest.launchpad_recommended_target_node_code: <填写>
+- manifest.launchpad_recommended_recovery_label: <填写>
+- manifest.launchpad_onboarding_bootstrap_pending_nodes: <填写>
+- manifest.launchpad_onboarding_acceptance_ready_nodes: <填写>
+- manifest.launchpad_alignment.consistent: <填写 true/false>
+
+四、结论
+- <填写：可进入正式发布 / 仍需继续收口 / 暂不可发布>
+```
+
+### 模板补充说明
+
+填写“可进入正式发布”前，建议再做一次人工交叉确认：
+
+- 发布门禁是否为 `ready` 或至少非 `blocked`
+- 当前主车道是否已经明确
+- 是否还存在 `dead_letter`
+- 是否还有节点停留在 `bootstrap pending / acceptance pending`
+- 是否已经保留可复盘的证据包与 manifest
+
+---
+
+## 五、交付给值班同事时最少要带什么
+
+最少带下面 4 样：
+
+1. `go-live-check` 摘要
+2. `stack-diagnosis` 结果
+3. `driver-feed / codex-brief` 结果
+4. `go-live-export` 生成的 `manifest.json`
+
+如果值班同事需要直接接手节点问题，再多带 3 样：
+
+1. `node-acceptance-run` 最近结果
+2. `log-sync-check` 最近结果
+3. `queue-status` 或 `queue-records dead_letter` 最近结果
+
+这样交班的人不需要重新从零拼现场。
+
+---
+
+## 六、真正的收工标准
+
+如果要算“这次版本已经可以收工”，建议至少同时满足：
+
+- 前端构建成功
+- 海外单脑驾驶舱首屏状态正常
+- `go-live-review.status != blocked`
+- 发布门禁不为 `blocked`
+- Node Agent 目标节点已完成接管验收
+- 远端日志回传链可用或已确认本轮不依赖
+- delivery queue 不存在未处理 `dead_letter`
+- 当前默认下一步已经不是“继续补基础设施”，而是进入正式发布 / 观察 / 验收车道
+
+到这一步，才适合说：
+
+> 当前项目已经进入可上线、可交付、可持续运维状态。