可重复代际升级验收

证明固定构件可全新部署、安全重跑并恢复，而非只证明构建或健康检查成功。适用于 Vn→Vnext、蓝绿或主机替换；不绑定云平台、业务域名、数据库或 CD 产品。默认完成阶段 0–7 并提交待切换报告。

发布分类与新目标边界

先按UI/API/DB 发布分类判断是否需要代际替换。纯 UI、兼容 API 小修复以及独立非业务/非账单监控服务的原地发布，不因引用本技能被扩展为全量重建。

数据库版本、SQL schema 版本和升级数据迁移，以及 Vault Raft/其他持久卷工作负载的版本或状态转换，必须在新集群和独立存储验证；数据库使用空目标库，不将同集群另建库、复用旧 PVC 或修改旧有状态 HelmRelease 版本称为新集群升级。保留源 schema、数据及原写入方，源只读迁移连接不改变源业务写入权。独立监控例外仅限分类表中明确的范围。

参数契约

云平台/基础设施类型、目标环境、源/目标代际、执行入口、配置执行器、固定声明和部署控制器均为输入，不以某个云、代际或工具链作为隐式默认：

upgrade:
  provider: <选定云平台或基础设施类型>
  environment: <目标环境>
  source_generation: <当前已验收代际>
  target_generation: <待验收代际>
execution:
  mode: <manual或pipeline>
  entrypoint: <人工连接入口或流水线入口及固定版本>
  configuration_executor: <既有配置执行器及固定版本>
  desired_state_ref: <固定声明仓库commit或不可变tag>
  deployment_controller: <既有部署控制器及固定版本>
acceptance:
  stages: "0-7"
  cutover: manual_confirmation

将输入归一化为同一份已核实的环境、inventory 和构件清单，再交给执行 owner。必填输入缺失或相互矛盾时不启动相应变更；不静默选择生产平台、源或目标。不适用的配置执行器/控制器明确说明替代执行路径及证据，不引入工具来填字段。

manual 可映射 SSH → Playbook → 固定 GitOps → Doco-CD，pipeline 可映射已审查的流水线 → 固定执行器 → 固定声明 → 部署控制器。两种模式共享阶段、数据保护和证据门禁，不能因选择流水线而获得额外权限。

输入与执行归属

• 核实环境、provider、source_generation、target_generation、已验收源、目标 inventory、公共/版本域名、构件和观察预算。不要推定目标代际名称意味着已部署或源代际已验收。
• 阅读实际仓库 AGENTS.md，保护工作区修改、业务库、演练库和既有证据；不默认清库重来。以固定 commit 构建/执行工具，不从混有无关改动的工作区发布。
• GitOps 是执行前的目标声明；控制面负责选择、授权和证据放行；IaC 负责资源/DNS/权威 inventory；Playbooks 等配置执行器负责主机、部署、证书、迁移和恢复；应用迁移工具拥有业务合并语义。遵循现有 owner，不新增平行执行路径。
• 手动 Selfhost 可采用 SSH → Playbook → 固定 GitOps → Doco-CD：SSH 仅连接经核实目标，Playbook 消费固定声明，CD 收敛服务。其他已授权执行器可替换；不因本技能触发 CI 部署或新增网关。
• 修复进入所属配置源并重跑对应路径；主机热修和本地文档不构成可重复交付。PR、合并、发布、部署、切换分别以任务授权为准。

阶段 0–7：候选验收

阶段 0 及数据操作前读取运维验收与回归清单，使用其中的恢复、冲突及回归证据契约。无需重复载入无关技能。

运行和证据约束

• 候选阶段源继续服务；不修改、不重启或冻结源，不更改公共 DNS/流量。对源的迁移连接只读并不代表源业务已只读。源持续写入时不声称目标已零延迟追平。
• 目标允许受控迁移和隔离测试写入；生产消费者、真实扣退款、通知及外部副作用不得随测试开启。生产配置就绪与 Sandbox 功能验证分别记录。
• 每个 case 为 PASS/FAIL/BLOCKED/NOT_RUN；不适用项须有理由和依据。必测项缺测试条件即阻断，不用静态配置、行数相同、跳过证书验证或 readyz 代替业务验收。
• 证据绑定 run_id、固定候选和实际运行版本，包含命令/脚本版本、目标、时间、退出码、脱敏结果、恢复和指纹记录及关联问题。密钥运行时读取，不记录值或敏感身份。
• 修复生成新候选，重跑受影响阶段及依赖项；部署/恢复共享配置变化需重验全新部署、幂等和恢复。旧版本回执不能直接放行新版本。
• 观察预算基于业务/采集/调度周期和任务约定，记录起止和样本；时间或条件不足明确标未完成。

修复、发布与重新验收闭环

升级或迁移发现问题时，保留失败候选及证据，按以下闭环推进，不能以文档更新、主机热修或 PR 通过代替运行关闭：

记录故障和复现证据
→ 在所属仓库修复，新增或修正真实回归 case
→ 提交 PR，通过必需检查和审查
→ 按任务授权合并 main，核实远端合并 commit
→ 从该 main commit 创建新的唯一不可变 tag，验证构件及来源
→ 更新消费者的固定声明，经其审查流程形成新的声明 commit
→ 重新部署候选，重跑受影响阶段及后续依赖验收
→ 依据运行证据关闭问题；未通过则进入下一轮

• 版本命名采用所属仓库批准的规则，不移动、覆盖、删除或复用旧 tag；失败重试分配新版本。生产资格仍受原有环境/ref 门禁约束，不把 main 直接当作生产部署 ref。
• 多仓修复分别走所属 PR，并按 producer → 已验证构件 → consumer 固定声明顺序推进。未改仓库可保留已验证的不可变版本，重新绑定本轮完整构件矩阵，不强制无意义重建。
• 每轮记录 attempt_id、上一失败轮次、问题、修复 PR、main 合并 SHA、新 tag/digest、声明 commit 和 case 回执。构件或参数变化需明确证据失效范围；新候选不能继承已失效结论。
• 若共享部署/恢复配置、schema/迁移或跨服务契约改变，重新执行其影响的全新部署、数据保护、恢复、回归和幂等验证；新候选重新完成相关稳定观察。
• 合并、tag 发布和目标部署依据任务已有授权执行，无需重复索取已给出的授权；本技能不自行授予这些权限。未授权/门禁阻断时记录精确边界，继续独立工作。修复循环不包含公共流量或写入权的自动切换。

切换及下一代

数据库身份与正式运行配置

• 区分审计读取、迁移执行、业务运行三类身份。本项目的 readonly_release 仅用于快照/备份读取、迁移源读取及审核，不是业务 DB 用户；不得接入 Accounts/Billing，也不得为修复业务写入而给它 DML、DDL、角色成员或绕过行级权限。迁移目标写入由单独的受控执行身份完成。
• 业务角色按实际 SQL 授予必要的表读写、序列使用及 schema 使用权限；不以超级用户、对象所有权、建库/建角色或清表权限修复普通业务写入。现有 RLS 契约须单独核实，不能用扩大权限掩盖策略错误。
• 候选只读或仅写会话的角色是隔离测试配置，不能直接作为正式运行配置。本项目 generation_auth 仅写会话、generation_app 只读时，登录成功不证明注册、账单或流量入账可用。
• Playbook 显式区分候选与正式运行模式；准备好正式配置后，在已授权切换中核实旧写入隔离、事务排空及目标备份，再提升目标业务角色和切换应用连接。共同核对声明、环境文件、进程实际连接身份、数据库有效权限、事务只读设置、后台写入及入口方法规则。暂停/恢复容器本身不完成角色提升。
• 角色提升不轮换认证凭据、不修改业务数据、不改变审计身份；重跑必须幂等。已提升目标不得被候选/恢复默认配置静默改回只读。若正式运行所需 SMTP、OAuth/Webhook 或支付配置仍是候选占位值，按实际功能标阻断，不以补授权宣称全部修复。
• 候选阶段用隔离身份和事务回滚验证业务写入、拒绝越权及恢复后的权限；单写入者交接后验证真实注册/会话和流量落库。业务写入成功及审计身份写入被拒绝都要有运行回执。

阶段 7 给出具体计划：隔离全部源写入者 → 排空事务 → 最终追齐及校验 → 捕获一致性/身份基线 → 确认源持续禁写 → 移交目标写入权与流量 → 切换后真实业务验收。

切换只在任务已有明确授权或人类审阅具体计划后确认时执行；默认停在 0–7。DNS 缓存或已有连接不能保证单写入者，所有 API、后台任务、Webhook、消费者及直连脚本都须纳入。无法隔离旧写入则停止。

目标接受新写入后，旧代际已经落后；不以仅切回 DNS 自动恢复旧库写入，不执行破坏性数据库降级。切换后观察及业务验收完成才将目标登记为下一轮来源。完整回退和遗漏数据修复见运维参考。