迁移案例模板
要点
- 迁移案例记录系统迁移的策略、风险控制、回滚方案
- 重点是迁移策略——怎么平滑过渡、怎么控制风险、怎么回滚
- 迁移通常有兼容性要求——新老系统并行运行
- 写清楚数据迁移、流量切换、回滚步骤
1. 适用场景
迁移案例用于记录系统从一个状态迁移到另一个状态的过程。
典型场景：
- 数据库迁移（MySQL → PostgreSQL）
- 框架升级（React 16 → React 18）
- 服务迁移（自建 → 云服务）
- 协议迁移（HTTP → gRPC）
- 存储迁移（本地存储 → 对象存储）
2. 模板结构
# [迁移标题]
## 背景
什么系统、从什么迁移到什么、为什么要迁移。
## 约束
- 不能停机（或停机时间 < 30 分钟）
- 数据不能丢失
- 上下游系统不配合改造
- 时间窗口：2 周
## 迁移策略
### 策略选择
选择了「双写 + 逐步切流」策略，而不是「一次性切换」策略。
理由：
- 一次性切换风险太大，回滚困难
- 双写可以验证数据一致性
- 逐步切流可以控制风险
### 迁移步骤
#### 阶段 1：双写（第 1-3 天）
- 新系统上线，同时写入新老系统
- 读取还是从老系统
- 验证数据一致性
#### 阶段 2：灰度切流（第 4-7 天）
- 10% 流量切换到新系统（读取）
- 观察指标，确认无异常
- 逐步扩大到 50%、100%
#### 阶段 3：下线老系统（第 8-14 天）
- 停止双写，只写新系统
- 观察 1 周，确认稳定
- 下线老系统
## 风险控制
### 数据一致性
- 双写期间，对比新老系统的数据
- 发现不一致时，以老系统为准
- 数据修复脚本准备好
### 回滚方案
每个阶段都可以回滚：
- 阶段 1 回滚：停止双写，只写老系统
- 阶段 2 回滚：流量切回老系统
- 阶段 3 回滚：重新开启双写，从阶段 1 开始
### 监控告警
- 新系统的错误率 > 1% 告警
- 新系统的延迟 > 老系统 2 倍告警
- 数据不一致告警
## 结果
迁移耗时 2 周，按计划完成：
- 第 1-3 天：双写，发现 3 处数据不一致，修复
- 第 4-7 天：灰度切流，无异常
- 第 8-14 天：下线老系统，稳定运行
迁移后：
- 查询性能提升 50%
- 运维成本降低 30%
## 复盘
- 双写策略是正确的，发现了数据一致性问题
- 灰度切流的比例可以更激进（10% → 30% → 100%）
- 回滚方案没有用到，但准备是必要的
- 后续行动：把迁移流程文档化，供其他团队参考3. 写作要点
迁移策略是核心
不要直接写「迁移完成了」。要写：
- 选择了什么策略（一次性 vs 逐步 vs 双写）
- 为什么选这个策略（风险、时间、兼容性）
- 迁移分几个阶段，每个阶段做什么
回滚方案必须写
迁移最大的风险是失败后回不来。每个阶段都要有回滚方案：
- 怎么回滚
- 回滚的成本（数据、时间）
- 回滚的触发条件
数据迁移要详细
如果涉及数据迁移，要写清楚：
- 数据怎么迁移（全量 vs 增量）
- 数据一致性怎么验证
- 发现不一致怎么处理
流量切换要灰度
不要一次性切换所有流量。灰度切流：
- 先切 1% → 10% → 50% → 100%
- 每个阶段观察指标
- 发现异常立即回滚
4. 常见误区
只写结果，不写策略
「迁移成功」不是案例。要写：选择了什么策略、为什么、分几个阶段、怎么控制风险。
没有回滚方案
迁移不写回滚方案是赌博。每个阶段都要有回滚方案，即使没用上。
忽略数据一致性
数据迁移不验证一致性，等于埋雷。要写清楚：怎么验证、发现不一致怎么处理。
总结
迁移案例的核心是迁移策略和风险控制。写清楚策略选择（双写 vs 一次性）、分阶段执行、回滚方案、数据一致性验证。灰度切流，每个阶段观察指标。