Flink CDC 2.x 升级 3.x 迁移指南：三步法、配置映射表与 5 个高频坑

Flink CDC 2.x 升级 3.x 迁移指南：三步法、配置映射表与 5 个高频坑

【免费下载链接】flink-cdcFlink CDC is a streaming data integration tool项目地址: https://gitcode.com/GitHub_Trending/flin/flink-cdc

Apache Flink CDC 是面向 MySQL、PostgreSQL、Oracle 等数据库的实时数据集成工具，提供全量+增量同步、表路由和 Schema 变更自动传递能力。本文面向仍运行 Flink CDC 2.x 作业的运维与数据平台工程师，读完你可以按清单把现有作业改写为 3.x 的 YAML pipeline，并完成切换验证与回退准备。

为什么现在要动：2.x 的三个实际瓶颈

现象一：每加一个同步链路就要写代码。2.x 的作业用 Java/Scala 构建MySqlSource，再各自接 deserializer 和 sink。表多、链路多时，改一个过滤条件都要重新打包、重新提交，作业数量和代码仓库的 jar 成正比。3.x 怎么解：整条链路写成一份 YAML，用 CLI 直接提交，不再打包自定义代码。链路从"一个工程"变成"一个文件"，评审和备份都简单了。

现象二：源表加列后，下游要么不动，要么作业挂掉。2.x 的 DDL 不会自动传到目标端，需要自己写 deserializer 处理，多数团队的选择是不处理。3.x 怎么解：pipeline 内置 Schema 变更事件流，源端的ALTER TABLE会自动同步到 sink，前提是 sink 连接器支持该能力（如 Doris、StarRocks 的建表参数配合），上线前实测一次即可确认。

现象三：依赖版本对不上就启动失败。2.x 的 groupId 是com.ververica，SQL fat jar 和 connector jar 容易混用，Debezium 传递依赖冲突要靠人肉排查。3.x 怎么解：统一走org.apache.flink的 pipeline connector jar，source 和 sink 分别放两个 jar 到 Flink CDC 的lib目录即可，依赖管理从"看代码"变成"看目录"。

新旧写法速查表与架构主线

架构主线一句话：3.x 把"source → 路由/转换 → sink"固化为统一 pipeline 模型，所有 source 连接器产出统一的变更事件流，经过共享的路由与 transform 阶段再进入任意 sink。

以 MySQL 同步到 Doris 并合并分表为例，一份完整定义如下：

source: type: mysql hostname: 127.0.0.1 port: 3306 username: root password: 123456 tables: app_db.order\.* server-id: 5400-5403 server-time-zone: UTC route: - source-table: app_db.order\.* sink-table: ods_db.orders sink: type: doris fenodes: 127.0.0.1:8030 username: root password: "" pipeline: name: mysql-to-doris parallelism: 4

版本对应关系以官方文档为准，参见 pipeline-connectors/overview：CDC 3.6.x 支持 Flink 1.20.* 与 2.2.，CDC 3.5.x 支持 Flink 1.19.与 1.20.*。

三步迁移法：盘点、转换、切换

迁移流程可以压缩成三步，每步有一份可勾选清单：

第一步：盘点

• 枚举所有 2.x 作业，登记：源端库/表、目标端、server-id、时区、并行度。
• 用information_schema统计各表行数，作为切换后的比对基线。
• 确认 Flink 集群版本满足目标 CDC 版本要求（如 3.6.x 需 Flink 1.20.* 或 2.2.*），不满足先排升级。

第二步：转换

• 按上文模板为每个作业写 YAML：表名正则、route、pipeline.parallelism。
• server-id区间宽度不小于并行度，且与同集群其他作业不重叠。
• 把 MySQL JDBC 驱动 jar（mysql-connector-java-8.0.27）放进Flink CDC 的lib，不是 Flink 的lib。
• 在conf/config.yaml确认 checkpoint 间隔已开启（增量快照依赖它）。

第三步：切换

• 提交作业：bash bin/flink-cdc.sh mysql-to-doris.yaml。
• Flink UI 确认作业 RUNNING 且首轮 checkpoint 完成。
• 在源端加一列做 DDL 实测，确认 sink 端表结构同步更新。
• 新旧并行运行、比对数据后，再停止旧作业并保存 savepoint。
• 旧作业的 jar 与 savepoint 归档保留，用于回退。

运行效果参考官方教程中的 MySQL 到 Doris 流式同步链路（含 Schema 变更与分表合并演示，见 mysql-to-doris 教程）：

踩坑实录：5 个最容易翻车的问题

坑 1：作业只读到存量数据，binlog 不动现象：启动后目标端有初始数据，增量一直为空。 根因：未启用 checkpoint。2.x/3.x 的增量快照算法都依赖 checkpoint 协调全量与增量顺序，没开 checkpoint 增量阶段不会推进（官方 FAQ 有同款问题记录，见 faq.md）。 解法：在conf/config.yaml开启execution.checkpointing.interval（如3s）后重启作业。

坑 2：连接报Authentication plugin 'caching_sha2_password'错误现象：启动即失败，日志指向认证插件。 根因：MySQL 8.x 默认认证方式需要较新的 JDBC 驱动，环境里混了旧版驱动。 解法：确认 8.0.27 版mysql-connector-java已放入 Flink CDC 的lib目录，并清掉同名旧 jar，避免版本混杂。

坑 3：增量数据时间戳整体偏移 8 小时现象：全量阶段正常，进入 binlog 阶段后时间字段差 8 小时。 根因：server-time-zone与 MySQL 服务器实际时区不一致。 解法：以服务器时区为准显式配置（如server-time-zone: Asia/Shanghai），不要留空猜默认值。

坑 4：新旧作业并行期间偶发 binlog 位点错乱现象：目标端偶发乱序或漏事件，无明确报错。 根因：MySQL 按server-id区分客户端，新旧作业（或多作业间）区间重叠会互相干扰位点。 解法：给新旧作业分配互不重叠的server-id区间；切换完成后先停旧作业再让新作业独占区间。

坑 5：拿 2.x 的 savepoint 直接恢复 3.x 作业失败现象：启动即报状态不兼容。 根因：两代作业算子拓扑不同，savepoint 不保证互通。 解法：接受重新全量+增量。提前确认源端 binlog 保留窗口大于全量耗时，切换窗口内不删 binlog，失败后可以无数据缺口地重来。

上线前验证项与回退预案

切换前逐项过一遍，阈值不达标不要停旧作业：

• 数据一致性：逐表比对源端与 sink 行数，要求 100% 相等（或差异率 <0.01% 且全部可解释为在途写入）。
• 同步延迟：源端写测试行，sink 端 P95 可见延迟 <5 秒，持续观察 30 分钟无回退。
• checkpoint：成功率 100%，无连续失败；失败会拖慢全量阶段并影响位点推进。
• DDL 传递：源端ALTER TABLE加列，sink 端结构实时更新且作业不重启。
• 告警就绪：对作业状态与同步延迟配置告警后再放生产流量。

回退预案：切换当天起，旧作业的代码、jar 和最后一个 savepoint 都保留在制品库中。若新作业 24 小时内出现指标不达标或反复重启，立即停止新作业，用旧 savepoint 重启 2.x 作业即可，它从上次位点续读，不做全量重扫。兜底措施是源端 binlog 保留窗口覆盖整个验证期（建议至少 3 倍验证时长），保证任何时刻重新拉起都能续上。

收尾

迁移的全部工作量就是：盘点 → 转换 → 切换，核心产出是一份份 YAML。建议今天就从第一步开始，先对现有 2.x 作业做一遍完整盘点，产出映射表和行数基线。

【免费下载链接】flink-cdcFlink CDC is a streaming data integration tool项目地址: https://gitcode.com/GitHub_Trending/flin/flink-cdc