verifying-production-changes

验证生产环境中的变更

已合并不代表已部署，已部署也不代表已验证。

以部署为门槛

编写一条命令，打印生产请求实际使用的提交 SHA，而不是版本字符串；从服务暴露的信息中获取（状态端点、构建信息路由、引导清单）。如果平台直接报告实例修订版本，优先使用这种方式，并说明这一点。然后，在服务仓库的克隆中运行：

scripts/deploy-gate.sh --target <merged-sha> --baseline <prior-prod-sha> -- <command>

如果实例数量较多，请提高 --samples 或 --clean-polls 的值；也可以根据平台的发布节奏设置 --interval 和 --max-polls。脚本头部说明了门槛规则。

• 退出码 0： 逐字写下最后一行：“在 N 个采样请求中未观察到过时实例”。

• 退出码 1，rollout-in-progress： 报告发布仍在进行中，并说明已上线和未上线的数量，不要将其报告为失败。not-deployed： 报告没有任何采样请求运行此变更。

• 退出码 2、3 或 5： 修正命令调用、SHA 或采样命令，然后重新运行。

• 退出码 4： 基线已包含目标变更，因此请询问此次部署前生产环境运行的是哪个修订版本。

• 关于生产环境运行内容的所有断言都必须以采样结果为限：绝不要说“已完全部署”或“生产环境已不再运行旧 SHA”。

• 如果脚本无法运行，请阅读其头部，并根据现有采样结果应用其中的规则。

• 即使所有采样结果都指向目标版本，也仍要写下上述句子；祖先关系检查尚未完成时也一样。

验证变更后的数据

适用于一次性迁移、回填或清理。验证过程必须只读：绝不要以写入模式重新运行任务，也不要修复数据。报告差异。

• 使用报告模式日志。 写入完成后，只有该日志中的逐行预期值可作为变更前数据的记录。
• 检查两类数据： 应当变更的行，以及不应变更的行。只有未变更的数据类别能发现任务是否触及了过多数据。沿各个变化维度对每类数据进行采样，包含报告中被特殊处理的行（部分处理、跳过、冲突），并使用只读查询对比预测值与实际值。
• 检查一个全量不变量： 任务旨在清除的数据现在应为空。该计数涵盖采样遗漏的所有行。
• 将报告中的汇总数与变更后的计数进行核对。
• 明确列出证据： 报告与实际数据一致且不变量为空，是有力证据，但并非逐行的变更前记录。没有逐行记录，就没有被删除行原始内容的独立记录。请说明你掌握了哪些证据。

部署顺序

• 一个部署必须先于另一个部署时，这种约束通常是不对称的。
• 在 PR 正文中说明哪种顺序安全、另一种顺序会导致什么问题，以及损害是否会自行修复。
• 根据两端的代码验证这一点：例如，客户端即使“能容忍任意顺序”，在某种顺序下仍可能丢失信号，因为上游存在无条件过滤器，而下游只有条件重标记。
• 如果一次性任务删除了旧版渲染器仍会读取的行，则必须等两个部署都完成后再执行，而且不会自行修复；请在记录顺序的地方说明这一点，因为没有任何机制会强制执行这一顺序。