Menu
准备基础架构生产上线。当准备升级分布式系统、存储引擎或网络组件时使用。当需要上线前检查清单、滚动升级与灰度计划、数据迁移与一致性校验，或需要回滚与降级预案时使用。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
指导稳定的 RPC、存储协议和接口设计。在设计节点间 RPC、存储协议语义、模块边界或任何公共接口时使用。在定义 gRPC service、对象存储或文件系统语义、节点间的类型契约，或确立组件边界时使用。
自动化 CI/CD 流水线设置。在设置或修改构建和部署流水线时使用。当需要自动化质量门禁、在 CI 中配置测试运行器，或建立部署策略时使用。当需要处理 CI 上不稳定（flaky）的测试时使用。
进行多维度代码审查。在合并任何变更之前使用。在审查由你自己、另一个智能体或人类编写的代码时使用。当需要在代码进入主分支之前评估其跨多个维度的质量时使用。当需要评估变更的正确性、可读性、架构与性能，或审查 PR/diff 时使用。
为清晰性而简化代码。在重构代码以提高可读性而不改变行为时使用。当代码可以正常工作但比应有的更难阅读、维护或扩展时使用。在审查已积累不必要复杂性的代码时使用。当组件过度设计、过于炫技而难以维护时使用。当需要清理越来越难读懂的代码时使用。
验证系统的一致性与持久性承诺。在设计或修改复制协议、写路径、崩溃恢复逻辑时使用。当需要证明已确认的写入不丢失、副本间不发散、崩溃后能恢复到一致状态，或评审 fsync/校验和/事务语义时使用。
优化智能体上下文设置。在开始新会话、智能体输出质量下降、在不同任务之间切换，或需要为项目配置规则文件和上下文时使用。
| name | shipping-and-launch |
| description | 准备基础架构生产上线。当准备升级分布式系统、存储引擎或网络组件时使用。当需要上线前检查清单、滚动升级与灰度计划、数据迁移与一致性校验，或需要回滚与降级预案时使用。 |
充满信心地上线。目标不仅仅是把新版本部署上去——而是可靠地部署：协议与磁盘格式兼容性已验证，监控到位，回滚计划就绪，并清楚地理解成功是什么样子。每次上线都应该是可逆的、可观察的和增量的。对分布式系统而言，"可逆"意味着你必须假设新旧版本会长时间混跑，并且回滚时旧版本必须能读懂新版本写下的数据。
在功能开关后面发布高风险行为，将二进制部署与行为启用解耦。对基础架构而言，开关通常控制：新格式写入、新代码路径、双写比对：
// 格式版本开关：默认仍以旧格式写入
if cfg.EnableNewRecordFormat {
// 新路径：写 v2 格式记录
return writeRecordV2(buf, record)
}
// 默认：现有行为，v1 格式，旧版本可读
return writeRecordV1(buf, record)
功能开关生命周期：
1. 部署 开关关闭 → 新二进制在运行，行为与旧版本一致
2. 启用 在测试集群 → 用生产流量的回放/影子流量验证
3. 灰度启用 → 单节点 → 单机架 → 单集群 → 全量
4. 每个阶段监控 → 观察错误率、延迟、副本滞后、校验和不匹配数
5. 清理 → 全量稳定后移除开关和旧代码路径
规则：
1. 在测试/预发集群验证
└── 用生产数据副本或回放流量跑完整测试套件
└── 注入故障演练：升级中杀节点、断网、塞满磁盘
2. 单节点升级（canary）
└── 升级集群中一个非关键节点
└── 验证：正常加入集群、副本同步追平、读写正常
└── 至少 24 小时观察窗口
3. 单机架升级
└── 升级一个故障域内的所有节点
└── 验证：机架级故障域隔离仍有效，副本分布不越界
└── 监控副本滞后、重建速率、IO 错误
4. 单集群升级
└── 升级一个完整集群（跨机架滚动进行）
└── 每一步等待副本追平和健康检查通过
└── 24-48 小时监控窗口
5. 全量推广（剩余集群按批次）
└── 每批之间留出观察窗口
└── 任何时候能停止推广并回滚已升级节点
6. 启用新行为（如格式开关）
└── 仅在所有节点升级完成且不再计划回滚之后
└── 按"单节点 → 单机架 → 单集群 → 全量"重新灰度
1. 新节点上线为空节点，先不承接流量
2. 开启重均衡，限速到不影响业务 P99（如限制搬迁带宽 ≤ 磁盘能力的 20%）
3. 监控：搬迁速率、源/目标节点 IO 延迟、副本可用性、业务延迟
4. 触发任一红线立即暂停重均衡（pause），而不是等它自己跑完
5. 搬迁完成后做副本一致性校验，再开放新节点承接全量流量
使用这些阈值来决定在每个阶段是推进、暂停还是回滚：
| 指标 | 推进（绿色） | 暂停并调查（黄色） | 回滚/停止（红色） |
|---|---|---|---|
| RPC 错误率 | 在基准的 10% 以内 | 高于基准 10-100% | > 基准 2 倍 |
| P99 延迟 | 在基准的 20% 以内 | 高于基准 20-50% | > 高于基准 50% |
| 副本滞后（replication lag） | 追平且稳定 | 持续增长但可恢复 | 持续增长且预计写满磁盘 |
| 校验和/一致性不匹配 | 0 | 个别且可归因于已知问题 | 批量出现或无法归因 |
| 磁盘水位 | <70% | 70-85% | >85% 或单盘写满 |
| 节点宕机/重启 | 无异常 | 单点偶发重启 | 同一版本节点批量崩溃 |
在以下情况下立即停止推进并回滚：
服务指标：
├── RPC 错误率（总计和按方法）
├── 响应时间（p50、p99、p999）
├── 请求量和吞吐
├── 慢请求/超时计数
└── 队列深度（写队列、复制队列、compaction 队列）
分布式系统指标：
├── 副本滞后与同步状态（replication lag、under-replicated 数量）
├── Leader/选举稳定性（选举频率、lease 续约失败）
├── 一致性指标（校验和不匹配数、对账差异）
├── 重均衡/搬迁速率与剩余量
└── 成员变更事件（节点上下线、扩缩容）
主机与存储指标：
├── 磁盘容量水位、inode、IO 延迟与 util
├── 慢盘/坏盘检测（IO error、retry 计数）
├── CPU、内存、页缓存命中
├── 网络吞吐、重传、分区检测
└── 文件描述符、连接数
// 关键路径错误必须带上下文上报，且分级：
// 数据面错误（影响正确性）立即告警，性能面退化按阈值告警
if err != nil {
metrics.IncWriteErrors(cfg.ClusterID, cfg.NodeID)
logger.Error("write failed",
"cluster", cfg.ClusterID,
"node", cfg.NodeID,
"partition", partitionID,
"error", err,
"checksum_mismatch", isChecksumErr(err),
)
if isChecksumErr(err) {
// 数据正确性问题：立即告警，不聚合不降级
alerting.PageOncall("checksum mismatch", partitionID)
}
}
告警分级原则：
在升级每个阶段后的第一个小时内：
1. 检查节点健康状态与集群成员关系正常
2. 检查错误监控仪表盘（无新错误类型）
3. 检查延迟与副本滞后仪表盘（无回归）
4. 抽查读写路径：写入 → 读取 → 校验和比对
5. 验证日志在流动且可读
6. 确认回滚机制有效（本阶段至少演练一次单节点回退）
每次变更都需要在发生之前有一个回滚计划。基础架构的回滚有一个 Web 发布没有的核心约束：回滚后的旧二进制必须能读懂升级期间写入的数据。
## [变更/升级]的回滚计划
### 触发条件
- 校验和不匹配批量出现
- 副本滞后持续增长超过 [X] 分钟
- P99 延迟 > [X]ms
- 节点批量崩溃且共同点是新版本
### 数据兼容性确认（回滚前置条件）
- 升级期间是否写入了新格式数据？[是/否]
- 若否：可直接回退二进制
- 若是：旧版本是否能读？[能 → 回退 / 不能 → 禁止回退，走修复向前 roll-forward]
- 格式开关是否已开启？[已开启 → 先关闭开关，确认全部恢复旧格式写入，再评估回退]
### 回滚步骤
1. 停止推进：暂停滚动升级/重均衡（pause，不是继续）
2. 按逆序回退节点：逐台回退，每台验证重新加入集群且副本追平
3. 验证：健康检查、读写抽查、校验和比对
4. 沟通：通知团队和依赖方
### 降级预案（回滚不可行时）
- 关闭新功能开关，退回旧行为
- 读路径降级：从副本/备集群读
- 写路径降级：限流、排队或切到备用写入路径
- 数据修复：从备份/快照恢复受影响分区
### 回滚时间
- 停止推进/暂停重均衡：< 1 分钟
- 关闭功能开关：< 5 分钟
- 单节点回退二进制：< 15 分钟
- 从快照恢复单分区：< [X] 小时（实测，非估计）
references/definition-of-done.mdreferences/performance-checklist.mdreferences/observability-checklist.md| 合理化借口 | 现实 |
|---|---|
| "测试集群升级没问题，生产也一样" | 生产有不同的数据量、数据倾斜和故障模式。测试集群不会替你发现混跑窗口里的兼容性问题。 |
| "滚动升级不需要等副本追平，直接下一台" | 不等追平就是在叠加故障域。连续升级两台副本未同步的节点，等于自己制造数据丢失。 |
| "新版本会写新格式，但我们应该不用回滚" | "应该不用"不是回滚计划。一旦需要回滚而旧版本读不了新数据，你就被困在新版本上了。 |
| "重均衡全速跑，跑完就完事了" | 不限速的搬迁会打爆磁盘 IO 和网络，把正常的延迟尖刺变成线上事故。限速是默认项，不是可选项。 |
| "删数据前不用再确认，脚本是对的" | 不可逆操作没有"脚本是对的"这回事。dry-run、审批、快照，一个都不能少。 |
| "磁盘还有 20%，够用" | 重建一个故障节点需要整个节点容量的冗余空间。水位线要按故障场景算，不是按当前用量算。 |
| "回滚就是承认失败" | 回滚是负责任的工程。带着校验和不匹配硬扛才是失败。 |
上线之前：
上线之后（每个灰度阶段）：