📚 课程目录第4章保存点机制详解

4. 保存点机制详解

在 Flink 的容错体系中，Checkpoint 解决的是“作业运行期间自动恢复”的问题，而 Savepoint 解决的是“作业生命周期内可控地停机、升级、迁移与回滚”的问题。很多初学者会把两者混为一谈，认为只要开了 Checkpoint 就等于拥有了升级能力，结果在真正做版本迭代时才发现状态无法对齐、算子无法匹配。本节围绕 Savepoint 的原理、与 Checkpoint 的本质区别、触发与恢复流程、状态映射规则以及实战操作展开。

一、核心原理：Savepoint 是什么

Savepoint 是 Flink 对作业状态做的一次全局、一致、可持久化的快照，它由用户显式触发，写入外部存储（如 HDFS、S3、OBS），并带有一份描述“状态属于哪个算子、哪个状态、如何映射”的元数据。与 Checkpoint 由 JobManager 周期性调度不同，Savepoint 的触发权在用户手里，因此它天然适合做发布、扩缩容、集群迁移等运维动作。

Savepoint 的目录结构通常包含两部分：

状态数据文件：各算子实际的状态内容，按算子 UID 分目录存放。
元数据文件（_metadata）：记录算子 UID、状态名称、状态类型、并行度、序列化信息以及状态到算子的映射关系。

正因为元数据中保存了算子 UID 与状态名称，Flink 才能在恢复时把旧状态“对号入座”地分配给新作业的算子。这也是 Savepoint 能跨版本、跨并行度恢复的关键。

Savepoint 的可恢复性依赖两个稳定标识：算子 UID（uid）与状态名称。只要这两者在升级前后保持一致，状态就能被正确映射；一旦改变，就可能出现状态丢失或恢复失败。

二、Savepoint 与 Checkpoint 的区别

理解两者差异，是正确使用它们的前提。下表从触发方式、存储、生命周期、用途等维度进行对比：

对比维度	Checkpoint	Savepoint
触发方式	JobManager 周期性自动触发	用户通过命令或 API 显式触发
主要用途	故障自动恢复	停机升级、迁移、扩缩容、回滚
生命周期	作业停止后通常被清理	长期保留，由用户手动删除
状态格式	可使用增量、RocksDB 原生格式	默认全量、格式更稳定、可移植
并行度调整	一般不支持随意变更	支持修改并行度后恢复
性能开销	频繁触发，追求轻量	触发较少，允许更大开销

一句话总结：Checkpoint 面向“自动容错”，Savepoint 面向“人工运维”。生产环境通常两者都开，Checkpoint 保证运行稳定，Savepoint 保证升级可控。

三、触发与恢复流程

Savepoint 的触发流程可以概括为：客户端向 JobManager 发起请求，JobManager 向所有 Source 注入屏障，各算子完成本地状态快照并上传到外部存储，最后 JobManager 汇总元数据并返回存储路径。恢复时则反向进行：读取元数据，按算子 UID 匹配状态，重新分配并加载。

# 触发 Savepoint（停止作业并保存）
flink stop \
  --savepointPath hdfs:///flink/savepoints \
  -yid application_1234567890_0001

# 仅触发 Savepoint，不停止作业
flink savepoint \
  -yid application_1234567890_0001 \
  hdfs:///flink/savepoints

# 从 Savepoint 恢复
flink run \
  -s hdfs:///flink/savepoints/savepoint-xxxxxx \
  -c com.example.UpgradeJob \
  app.jar

恢复时若修改了并行度，Flink 会依据状态类型自动做重分区：KeyedState 按 key group 重新分配，OperatorState 按并行度做均匀拆分或合并。这也是 Savepoint 支持扩缩容的底层原因。

四、状态映射规则与实战场景

状态映射的核心是“按 UID 找算子，按名称找状态”。假设原作业中有一个算子未显式设置 UID，Flink 会根据算子结构自动生成一个哈希 UID，一旦代码结构变化，这个哈希就会改变，导致恢复失败。因此生产代码中必须为每个有状态算子显式指定 UID。

DataStream<Event> stream = env
    .addSource(new KafkaSource())
    .uid("kafka-source")
    .keyBy(Event::getUserId)
    .process(new DedupProcessFunction())
    .uid("dedup-process")
    .uid("sink");

常见误区：升级时新增或删除算子、调整算子顺序、修改 UID，都会破坏状态映射。若必须调整拓扑，应使用 --allowNonRestoredState 显式允许丢弃无法映射的状态，但要确认丢弃的状态确实不再需要。

典型实战场景是“双十一前扩容”：原作业并行度为 4，大促前通过 Savepoint 停机，将并行度调整为 16 后恢复，KeyedState 自动按 key group 重新分布，业务无数据丢失。另一个场景是“逻辑修复上线”：修复去重逻辑后，从 Savepoint 恢复，历史状态继续生效，避免重复计算。

五、误区复盘与操作建议

在实际项目中，Savepoint 相关故障大多集中在以下几类：

未设置 UID：代码重构后自动生成的 UID 变化，恢复时报“无法映射状态”。
状态名称变更：修改了 StateDescriptor 的名称，导致旧状态被丢弃。
误用 Checkpoint 做升级：Checkpoint 生命周期短、格式不稳定，不适合跨版本恢复。
忽略状态大小：Savepoint 是全量快照，状态过大时触发耗时长，需评估存储与超时。

建议在 CI/CD 流程中固化 Savepoint 操作：发布前先触发 Savepoint 并记录路径，发布后从该路径恢复；同时为所有有状态算子显式声明 UID，并在代码评审中检查 UID 是否被意外修改。

掌握 Savepoint 的关键，不在于记住命令，而在于理解“UID + 状态名称”这套映射契约。只要契约稳定，作业就能在版本迭代、并行度调整、集群迁移中平滑过渡；一旦契约被破坏，再完善的容错配置也无法挽回状态。把 Savepoint 当作发布流程中的一等公民，才是 Flink 在线升级真正落地的标志。