Flink 应用升级与版本迁移Savepoint、状态兼容、跨版本恢复一次讲透

一、为什么 Flink 升级比普通服务更难？

很多后端服务升级时，常见流程是：

• 停服务
• 发新包
• 重启
• 完成

但 Flink 不一样。

因为 Flink 跑的不是一次性任务，而是 持续运行的流式应用。它在运行过程中会不断累积状态，比如：

• 去重状态
• 窗口聚合状态
• Join 缓存
• Keyed State
• 定时器
• RocksDB 中持久化的状态
• 算子内部维护的中间结果

所以 Flink 升级的真正难点不在于"换代码"，而在于：

新程序能不能接住旧程序留下来的状态。

如果接不住，就会出现：

• 作业启动失败
• 状态丢失
• 结果计算错误
• 重复消费
• 重复写出

这就是为什么 Flink 升级绝不是"换个版本"这么简单，而是一场真正的 状态迁移工程。

二、Savepoint 到底是什么？

一句话解释：

Savepoint 是 Flink 在某一时刻对作业状态做的一次一致性快照。

你可以把它理解成 Flink 作业的"状态存档点"。

它的核心作用不是单纯备份，而是为了支持：

• 作业升级
• 作业迁移
• 集群切换
• 问题回滚
• 版本升级恢复

1. 只做 Savepoint，作业继续运行

./bin/flink savepoint <jobID> [pathToSavepoint]

这个命令会触发一次 savepoint，但不会停止当前作业。

适合场景：

• 周期性保留可恢复点
• 预留回滚基线
• 为后续升级做准备

如果要用 detached 模式，可以加上 -detached。

2. Savepoint 完成后直接停止作业

./bin/flink cancel -s [pathToSavepoint] <jobID>

或者新版流程里常用：

bin/flink stop [--savepointPath :savepointPath] :jobId

这类方式更适合生产升级，因为它能保证：

• 作业停止前完成 savepoint
• 停止后不会再产生新的外部写入
• 降低恢复后重复输出的风险

3. 从 Savepoint 恢复新作业

./bin/flink run -d -s [pathToSavepoint] ~/application.jar

这就意味着：

• 你可以换新代码
• 也可以换新集群
• 但状态从旧作业的 savepoint 中恢复
• 逻辑从旧状态继续往后跑

这正是 Flink 实现平滑升级的核心能力。

三、Savepoint 能恢复状态，但不能回滚外部写入

这是很多人在生产环境中最容易忽视的问题。

Flink 的 Savepoint 可以恢复的是：

• 内部算子状态
• 处理进度
• checkpoint/savepoint 时刻的一致性状态

但它做不到的是：

撤销已经写到外部系统的数据。

举个例子。

你的作业把结果写到：

• Kafka
• MySQL
• Elasticsearch
• HBase
• Redis
• ClickHouse

如果你执行的是"只打 savepoint，不停作业"，那么 savepoint 完成后，旧作业还会继续写数据。之后你又从这个 savepoint 启动新作业，就可能导致：

• 一部分数据再次处理
• 一部分结果再次写出
• 下游看到重复数据

什么时候风险较小？

如果你的 Sink 是幂等写入，比如：

• 带主键的 Upsert
• 覆盖写
• 相同 key 覆盖更新

重复写可能还可以接受。

什么时候风险很大？

如果你的 Sink 是追加型写入，比如：

• Kafka append
• 日志型写入
• 纯追加型明细表

那恢复后重复输出就很危险。

所以生产上更推荐：

stop with savepoint，而不是 savepoint 后继续运行。

四、Flink API 兼容性规则详解

Flink 的 Java API 对外会用稳定性注解来标识兼容级别：

• Public
• PublicEvolving
• Experimental

如果一个 API 没有这些注解，那么一般就意味着：

它属于内部 API，不承诺兼容性。

这类 API 不建议在生产里深度依赖。

1. 什么叫源码兼容和二进制兼容？

源码兼容

老代码拿到新版本里，重新编译还能通过。

二进制兼容

老代码已经编译好了，不重新编译，直接放到新版本环境里还能运行。

这两个概念非常重要。

2. Public API 的兼容性

如果你的代码使用的是 Public API：

• Patch 版本升级：通常源码兼容、二进制兼容
• Minor 版本升级：通常源码兼容，但不保证二进制兼容
• Major 版本升级：源码兼容和二进制兼容都不保证

举个例子：

你在 Flink 1.15.2 上写的代码，如果升级到 1.15.3，大概率不需要重新编译就能跑；但如果升级到 1.16.0，则通常需要重新编译；如果升级到 2.x，则可能还要改代码。

3. PublicEvolving API 的兼容性

PublicEvolving 的风险会大很多：

• Patch 版本通常还好
• Minor 版本可能既不保证源码兼容，也不保证二进制兼容

也就是说，这类 API 虽然开放给用户使用，但本身还在快速演进中。

4. Experimental API 的兼容性

这个名字已经很直白了。

Experimental API 可以尝试，但不适合作为生产稳定基础设施长期依赖。

因为这类 API 在后续升级中，最容易发生变化。

五、Deprecated API 的迁移周期怎么理解？

从 Flink 1.18 开始，按照 FLIP-321 的规则，不同稳定级别的废弃 API，会有不同的保留周期。

1. Public API

• 保证迁移周期：2 个 minor 版本
• 最早移除时间：下一个 major 版本

2. PublicEvolving API

• 保证迁移周期：1 个 minor 版本
• 最早移除时间：下一个 minor 版本

3. Experimental API

• 保证迁移周期：当前 minor 下的 1 个 patch
• 最早下一个 patch 就可能删除

这意味着什么？

这意味着如果你依赖的是 PublicEvolving 或 Experimental，那你根本不能抱着"以后再改"的心态。

生产中更合理的做法是：

• 每次升级前扫一遍 deprecated API
• 看 Javadoc 和 release note
• 提前安排替换周期
• 不要等删掉以后才临时救火

六、Flink 升级的本质：状态兼容

对 Flink 来说，升级最关键的不是代码能不能编译，而是：

新作业能不能正确加载旧作业的状态。

这就叫 Application State Compatibility。

如果状态兼容，升级可以成功；如果状态不兼容，savepoint 恢复就会失败。

所以真正决定 Flink 升级成败的，是状态匹配机制。

七、DataStream 程序恢复时如何匹配状态？

在 DataStream 模型下，Flink 从 savepoint 恢复时，需要把 savepoint 里保存的状态映射到新作业中的对应算子。

这个匹配依据就是：

Operator ID

1. 默认 ID 的问题

如果你没有手动指定 UID，Flink 会根据算子在拓扑中的位置自动生成默认 ID。

问题是，这种默认 ID 对拓扑结构非常敏感。你只要做了下面这些事：

• 插入一个新算子
• 调整一下链路顺序
• 改一下 chain
• 增减一个中间 operator

默认 ID 都可能变化。

一旦变化，savepoint 里的状态就找不到对应算子了，恢复直接失败。

2. 正确方式：显式设置 UID

示例代码如下：

DataStream<String> mappedEvents = events
    .map(new MyStatefulMapFunc())
    .uid("mapper-1");

这里的 uid("mapper-1") 就是显式指定 operator ID。

它的意义非常大：

• 升级时状态能稳定匹配
• 拓扑轻微调整后仍有恢复机会
• 降低 savepoint 恢复失败概率

八、为什么所有关键算子都必须加 UID？

很多人以为，只有自己写了 ValueState、ListState 的算子才需要 UID，其实不是。

原因有两个。

1. 不只是你写的状态算子有状态

Flink 中很多看起来"普通"的算子，其实内部也可能有状态，比如：

• window
• join
• aggregation
• 某些 runtime operator

也就是说，即便你没有显式写状态，算子内部依然可能有恢复需求。

2. 拓扑调整会影响默认 ID

如果你不设置 UID，后面加一个 filter、拆一个 chain、插一个 map，默认 ID 都可能变，最终导致状态恢复失败。

所以生产中真正稳妥的做法是：

所有未来可能升级的关键算子，统一显式设置 UID。

更进一步，你还可以直接启用：

ExecutionConfig.disableAutoGeneratedUIDs();

这样一来，凡是没写 UID 的算子，提交作业时就直接报错，能提前把风险拦住。

九、没有加 UID，还有救吗？

有补救方案，但非常麻烦。

Flink 提供了：

setUidHash(String hash)

你可以手工把旧版本生成的 legacy vertex hash 指定回去。

这个 hash 一般可以从：

• Flink Web UI
• Job 日志

中找到，通常是一个 32 位十六进制字符串。

但是我要直说：

这不是常规方案，而是补锅方案。

因为它的问题很多：

• 操作复杂
• 容易配错
• 对拓扑理解要求高
• 维护成本大

所以最好的做法仍然是：

从项目一开始就规范加 UID。

十、状态类型为什么不能随便改？

Flink 升级时有一条非常重要的限制：

不能直接修改算子状态的数据类型。

为什么？

因为 savepoint 里保存的是旧状态的序列化结果，恢复时 Flink 并不会自动帮你把旧类型转换成新类型。

比如你原来定义的是：

ValueState<Integer>

后来你改成：

ValueState<Long>

看起来只是小改动，但恢复时就可能失败。

如果必须改状态类型怎么办？

一种常见思路是：

1. 保留旧状态
2. 新增一个新类型状态
3. 在业务逻辑中逐步把旧状态迁移到新状态
4. 等迁移完成后，再下一次升级中移除旧状态

这其实是"业务层面的状态迁移"。

但这种方式需要你非常清楚：

• keyed state 分布
• 恢复过程
• 迁移顺序
• 重启后的幂等逻辑

所以一定要先在测试环境反复验证。

十一、哪些算子有内部状态，为什么改类型会出事？

除了用户自己定义的状态，Flink 还有很多 内部状态，例如这些算子：

• ReduceFunction
• WindowFunction
• AllWindowFunction
• JoinFunction
• CoGroupFunction
• 内置聚合：sum、min、max、minBy、maxBy

这些算子的状态类型，往往依赖于：

• 输入类型
• 输出类型
• key 类型

这意味着：

你即便没改状态定义，只要改了这些算子的输入或输出类型，也可能导致状态不兼容。

一个典型例子

原来你的窗口算子处理的是：

DataStream<OrderEvent>

后来你为了加字段，把前面改成了：

DataStream<EnrichedOrderEvent>

虽然你只是"多加了点字段"，但对于某些内部状态依赖输入类型的算子来说，它的状态结构已经变了，恢复就可能失败。

这类问题线上特别隐蔽，因为代码层面看上去只是一次普通重构。

十二、修改拓扑时哪些安全，哪些危险？

升级作业时，除了改逻辑，还经常会改拓扑，比如：

• 新增 filter
• 删除 map
• 多加一层转换
• 调整 chain
• 改并行度
• 替换聚合方式

这些操作不是绝对不能做，但风险不同。

1. 新增或删除无状态算子

通常问题不大。

比如：

• 新增一个 filter
• 删除一个纯 map

只要不影响状态算子的输入输出类型，一般都能恢复。

2. 新增有状态算子

可以新增，但它没有旧状态可恢复，因此会以默认状态启动。

3. 删除有状态算子

风险较大。

因为 savepoint 中还有它的状态，但新作业里已经没有这个算子了。默认情况下，Flink 会认为状态不完整，恢复可能失败。

如果你确定这份状态可以丢弃，就需要显式允许跳过 unmatched state。

4. 修改有内部状态算子的输入输出类型

高风险。

这是最容易被忽视的一类变更，也是最容易恢复失败的一类。

5. 修改 operator chaining

从较新的版本开始，Flink 对 chain 的兼容性已经比早期更好一些，支持：

• 把 stateful operator 从链中拆出来
• 向链中插入新算子
• 调整链内顺序

但前提仍然是：

相关算子必须有稳定 UID。

否则 chain 一改，默认 ID 变了，状态依然找不到。

十三、Table API / SQL 为什么升级更容易翻车？

如果说 DataStream 的升级已经够复杂，那 Table API / SQL 的升级往往更"玄学"。

为什么？

因为你写的是声明式逻辑，但 Flink 真正执行的是 planner 生成的物理执行计划。

只要下面这些因素发生变化：

• SQL 语句稍微改动
• Flink 版本变化
• 优化器规则变化
• planner 选择了新的执行算子

最终生成的执行拓扑就可能变。

这会带来什么后果？

• 状态表示形式变了
• operator 拓扑变了
• 状态恢复路径变了
• savepoint 可能就不兼容了

所以官方才会特别提醒：

对于 Table API / SQL，任何查询变更和 Flink 版本变更，都可能导致状态不兼容。

特别要注意 1.15.0 和 1.15.1

这两个版本在 Table API 上生成了 非确定性的 operator UID，会让状态恢复和 patch 升级都变得困难。

后来 Flink 引入了：

table.exec.uid.generation

用于控制 UID 生成行为。

这也侧面说明，SQL 场景下升级风险真的不能低估。

十四、Flink 框架跨版本升级的标准流程

如果你要升级的不只是作业代码，而是整个 Flink 集群版本，那么标准流程其实很清晰：

第一步：在旧版本作业上生成 Savepoint 并停作业

bin/flink stop [--savepointPath :savepointPath] :jobId

第二步：把集群升级到新的 Flink 版本

这一步包括：

• 替换 Flink 安装包
• 升级节点运行环境
• 检查部署参数
• 确认 state backend 和插件兼容

第三步：在新版本集群中从 Savepoint 恢复

bin/flink run -s :savepointPath [:runArgs]

本质上可以概括成一句话：

先在旧版本打 Savepoint，再在新版本恢复。

十五、原地升级与影子集群升级怎么选？

Flink 跨版本升级常见有两种方式。

1. 原地升级（In-place Upgrade）

流程是：

1. 打 savepoint
2. 停旧作业
3. 关闭旧集群
4. 升级 Flink 版本
5. 启动新集群
6. 从 savepoint 恢复

优点：

• 环境简单
• 运维路径短
• 资源占用少

缺点：

• 升级窗口风险集中
• 一旦出问题，回滚不够灵活

2. 影子集群升级（Shadow Copy Upgrade）

流程是：

1. 旧集群打 savepoint
2. 并行部署新版本 Flink 集群
3. 在新集群上恢复作业
4. 验证运行效果
5. 再下线旧集群

优点：

• 风险更低
• 可以灰度验证
• 回滚方便

缺点：

• 资源成本更高
• 运维复杂度更大

3. 实战建议

如果只是测试环境或小规模链路，原地升级可以接受。

如果是核心生产链路，我更建议：

优先采用影子集群升级。

因为它给你留出了验证空间，也给回滚留足了后路。

十六、迁移前必须检查的关键前提

迁移前有两个特别关键的点，很多人会漏。

1. RocksDB 半异步模式迁移不支持

如果你的旧作业：

• 使用 RocksDB state backend
• 且 checkpoint 使用的是 semi-asynchronous mode

那么迁移会失败。

官方建议是：

先切换到 fully-asynchronous mode，再打用于迁移的 savepoint。

2. Savepoint 路径必须在新环境中可访问

这点非常重要。

恢复时，不只是 savepoint 元数据文件要能访问，savepoint 中引用的底层状态文件也必须能访问，而且最好路径保持一致。

包括：

• state backend snapshot 文件
• savepoint 引用的额外状态文件
• State Processor API 修改后引用的文件

很多迁移失败，不是因为状态不兼容，而是：

新集群根本访问不到旧 savepoint 的底层文件。

十七、线上最容易踩的 8 个坑

这部分建议直接收藏。

坑 1：没有设置 UID，改了一个小拓扑就恢复失败

最常见，也最经典。

坑 2：状态类型改了，自己却没意识到

尤其是从 Integer 改 Long，或者 POJO 结构发生变化。

坑 3：前面加了个 map，后面窗口算子的输入类型被改变

表面是小重构，实际把内部状态结构改了。

坑 4：只打 Savepoint 不停作业，恢复后外部系统重复写入

特别是 Kafka、日志表、append 型存储，最危险。

坑 5：新集群访问不到旧 Savepoint 文件

命令没错，但底层文件丢了或路径不对。

坑 6：SQL 没怎么改，但 planner 换了执行计划

结果 savepoint 恢复失败。

坑 7：依赖 PublicEvolving 或 Experimental API 太深

升级时编译、运行、行为全可能变化。

坑 8：没有提前做恢复演练，直接在生产开干

这是最不应该发生的坑。

十八、生产环境最佳实践总结

如果你只想记住最关键的结论，那么请直接记下面这些。

1. 所有关键算子显式设置 UID

这是 Flink 可升级性的基础设施。

2. 尽量让所有未来可能变动的算子都设置 UID

不要只给"自己写了状态"的算子加。

3. 提交前禁用自动生成 UID

能大幅降低线上恢复失败概率。

4. 升级前先做 Savepoint 恢复演练

不要把生产当测试环境。

5. 优先使用 stop with savepoint

比只做 savepoint 更稳。

6. 升级前一定检查 Sink 的幂等性

尤其是涉及外部写入时。

7. 修改拓扑时重点关注内部状态算子的输入输出类型

这是最容易出问题的地方。

8. Table API / SQL 升级必须更谨慎

因为 planner 变化不一定是你肉眼能看出来的。

9. 核心链路优先影子集群升级

给验证和回滚留足空间。

10. Savepoint 底层文件路径必须提前验证

不要等恢复时报路径错误。

十九、写在最后

很多人以为 Flink 升级就是改版本号、打个包、重启一下作业。

但真正做过线上迁移的人都知道，Flink 升级的本质从来不是"换版本"，而是：

如何把旧作业的状态，安全、完整、稳定地交给新作业。

这背后考验的不是表面代码，而是你对以下几个核心机制的理解：

• Savepoint
• 状态兼容
• Operator UID
• 内部状态结构
• 外部写出一致性
• 集群升级策略
• SQL planner 风险

如果你只能记住三句话，我建议记住这三句：

第一句

Flink 升级成败的关键，不是代码能不能编译，而是状态能不能恢复。

第二句

所有关键算子都要显式设置 UID，这是线上可升级的生命线。

第三句

生产升级优先使用 stop with savepoint + 影子集群验证。

只要把这三件事做到位，你的 Flink 升级成功率会高很多。