SeaTunnel MySQL CDC 到 Kafka 实战:Metadata 元数据注入与 Kafka Headers 字段整形
SeaTunnel MySQL CDC 到 Kafka 实战:Metadata 元数据注入与 Kafka Headers 字段整形
本篇文章基于 SeaTunnel 官方 recipe 文档(docs/en/getting-started/recipes/mysql-cdc-to-kafka.md),完整还原一条经过 Docker 端到端验证的 MySQL CDC → Kafka 实时同步管线:用 MySQL-CDC 源读取快照与 binlog 增量,用 Metadata 变换把库名、表名、变更类型暴露为普通字段,用 Sql 变换完成业务字段重命名与状态枚举翻译,最后由 Kafka sink 将 JSON 载荷写入 topic,同时把选定元数据字段搬进 Kafka Headers。读完本文你将掌握:整条管线的完整可运行配置、每个参数的含义与来源依据、kafka_headers_fields 对 payload 与 header 的双重影响,以及源码层面的校验机制与 E2E 断言细节。
管线总览
本 recipe 刻意把范围收窄:只记录 2026-07-16 在 Docker 环境中端到端验证通过的这一条 MySQL CDC 到 Kafka 作业。其数据流为:
MySQL-CDC源:读取shop.orders表的全量快照,以及后续 binlog 增量变更;Metadata变换:把数据库名、表名、行变更类型(RowKind)暴露为普通字段;Sql变换:重命名业务字段、翻译状态枚举、填充自定义字段;Kafkasink:以 JSON 格式写入载荷,同时把选定的元数据字段移动到 Kafka Headers 中。
对应的作业配置文件在仓库中可查:seatunnel-e2e/seatunnel-connector-v2-e2e/connector-kafka-e2e/src/test/resources/kafka/mysqlcdc_to_kafka_with_transforms.conf,E2E 测试类为 seatunnel-e2e/seatunnel-connector-v2-e2e/connector-kafka-e2e/src/test/java/org/apache/seatunnel/e2e/connector/kafka/KafkaRecipeIT.java。
验证环境前置条件
在作业启动之前,验证用的 Docker 运行环境已满足以下前提:
-
MySQL 的 GTID/binlog 配置就绪:验证环境通过
docker/server-gtids/my.cnf启用了 GTID 与 binlog。对于自建环境,可参照 MySQL-CDC 源连接器文档 中的标准配置开启二进制日志:server-id = 223344 log_bin = mysql-bin expire_logs_days = 10 binlog_format = row # mysql 5.6+ 要求 binlog_row_image = FULL binlog_row_image = FULL # 可选:启用 GTID(mysql 5.6+ 必须设为 ON) gtid_mode = on enforce_gtid_consistency = on -
MySQL JDBC 驱动 JAR 已放置到
MySQL-CDC插件的lib目录下(Zeta 引擎为${SEATUNNEL_HOME}/lib/)。 -
CDC 账号
st_user_source已创建,并具备SELECT、RELOAD、SHOW DATABASES、REPLICATION SLAVE、REPLICATION CLIENT、LOCK TABLES权限。创建与授权的参考 SQL(来自 MySQL-CDC 文档):CREATE USER 'user'@'localhost' IDENTIFIED BY 'password'; GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' IDENTIFIED BY 'password'; FLUSH PRIVILEGES;注意:recipe 验证中还额外使用了
LOCK TABLES权限,用于快照阶段的一致性保证;多个 CDC 作业并行时还需为每个作业分配互不重叠的server-id区间,否则 MySQL 会断开其中一个客户端连接。 -
Kafka topic
recipe_mysql_orders在 SeaTunnel 作业启动前已创建。Kafka sink 本身不会显式建 topic,是否自动创建取决于 broker 的auto.create.topics.enable开关,生产环境建议提前创建以控制分区数、副本、保留策略与 ACL。
验证用源表与数据
E2E 测试创建了如下 MySQL 表并加载两条初始记录:
CREATE TABLE orders (
id BIGINT NOT NULL PRIMARY KEY,
order_no VARCHAR(64) NOT NULL,
user_id BIGINT NOT NULL,
status INT NOT NULL,
amount DECIMAL(10, 2) NOT NULL
);
INSERT INTO orders (id, order_no, user_id, status, amount) VALUES
(1001, 'ORD-1001', 501, 0, 19.99),
(1002, 'ORD-1002', 502, 1, 29.99);
作业启动后,测试继续执行了以下增量变更:
UPDATE shop.orders SET status = 2, amount = 39.99 WHERE id = 1001;
INSERT INTO shop.orders (id, order_no, user_id, status, amount) VALUES
(1003, 'ORD-1003', 503, 0, 59.99);
即:快照阶段产生 2 条记录(1001、1002),增量阶段产生 1 条 UPDATE(1001)与 1 条 INSERT(1003)。
完整作业配置(Docker 验证版)
以下即 Docker 测试环境中验证通过的精确配置。其中主机名是该环境中的 Docker 网络别名(mysql_cdc_e2e、kafkaCluster),实际部署时替换为真实地址即可。
env {
parallelism = 1
job.mode = "STREAMING"
}
source {
MySQL-CDC {
plugin_output = "mysql_orders_raw"
url = "jdbc:mysql://mysql_cdc_e2e:3306/shop"
username = "st_user_source"
password = "mysqlpw"
server-id = 5601-5604
table-names = ["shop.orders"]
startup.mode = "initial"
schema-changes.enabled = false
}
}
transform {
Metadata {
plugin_input = "mysql_orders_raw"
plugin_output = "mysql_orders_with_meta"
metadata_fields {
Database = source_database
Table = source_table
RowKind = change_type
}
}
Sql {
plugin_input = "mysql_orders_with_meta"
plugin_output = "kafka_orders"
query = "select id as order_id, order_no, user_id, amount, case when status = 0 then 'CREATED' when status = 1 then 'PAID' when status = 2 then 'SHIPPED' else 'OTHER' end as status_name, source_database, source_table, change_type, CONCAT(source_database, '.', source_table) as source_name, 'mysql_cdc' as sync_source from dual where id is not null"
}
}
sink {
Kafka {
plugin_input = "kafka_orders"
bootstrap.servers = "kafkaCluster:9092"
topic = "recipe_mysql_orders"
format = json
partition_key_fields = ["order_id"]
kafka_headers_fields = ["source_database", "source_table", "change_type"]
}
}
下面对每个配置块逐项拆解。
env:流式运行环境
env {
parallelism = 1
job.mode = "STREAMING"
}
parallelism = 1:单并行度,保证单表 CDC 事件按序处理(快照 → binlog 增量无缝衔接);job.mode = "STREAMING":流式模式,作业常驻运行,持续消费 binlog。若需严格一致,可额外开启checkpoint.interval,为 Kafka 的 EXACTLY_ONCE 语义提供事务提交基准。
source:MySQL-CDC 源
MySQL-CDC {
plugin_output = "mysql_orders_raw"
url = "jdbc:mysql://mysql_cdc_e2e:3306/shop"
username = "st_user_source"
password = "mysqlpw"
server-id = 5601-5604
table-names = ["shop.orders"]
startup.mode = "initial"
schema-changes.enabled = false
}
| 参数 | 含义(依据 MySQL-CDC 文档) |
|---|---|
url |
JDBC 连接地址,示例 jdbc:mysql://host:3306/shop,必填 |
username / password |
连接 MySQL 的 CDC 账号与密码,必填 |
server-id |
CDC 读取器的数值 ID 或 ID 区间(如 5400 或 5400-5408),区间内每个 ID 在 MySQL 集群中必须唯一。多读取器或多表并行读取时,配置足够大的区间 |
table-names |
要监控的表,每项必须带库名前缀,如 shop.orders(与 table-pattern 二选一) |
startup.mode |
initial:启动时先同步历史快照,再同步增量数据(本 recipe 选择);其他可选值:earliest、latest、specific、timestamp |
schema-changes.enabled |
是否启用 schema 演进(DDL 传播),默认 false;当前仅支持 add column、drop column、rename column、modify column,本 recipe 显式关闭 |
从源码结构看,MySQL-CDC 源基于 Debezium Embedded Engine 实现:首次启动时先对配置表做一致性全量快照(通过 snapshot.split.size 默认 8096、snapshot.fetch.size 默认 1024 控制分片与抓取粒度),快照完成后自动切换到从快照起始时刻记录的 binlog 位置继续读取,保证切换过程不丢事件。
transform ①:Metadata 元数据注入
Metadata {
plugin_input = "mysql_orders_raw"
plugin_output = "mysql_orders_with_meta"
metadata_fields {
Database = source_database
Table = source_table
RowKind = change_type
}
}
Metadata 变换用于把数据行自带的元数据信息提取为普通字段(详见 Metadata 变换文档)。其唯一参数 metadata_fields 是「元数据键 → 输出字段名」的映射:
- 左侧必须是受支持的元数据键且严格区分大小写:
Database(库名)、Table(表名)、RowKind(行变更类型:+I插入、-U更新前、+U更新后、-D删除)、EventTime(事件时间戳,毫秒)、Delay(同步延迟)、Partition等;MySQL-CDC 还额外提供BinlogFile、BinlogPos、BinlogRow、Gtid(快照行这四个字段为null); - 右侧是自定义输出字段名,不能与输入表中已有的物理字段重名;
- 该变换只做“追加”,不修改原始数据字段。
在本 recipe 中仅暴露了后续 Kafka sink 与 SQL 变换真正会用到的三个字段:source_database、source_table、change_type。
在 MetadataTransform.java(seatunnel-transforms-v2/src/main/java/org/apache/seatunnel/transform/metadata/MetadataTransform.java)中可以看到两条启动期校验:左侧键若不是受支持的元数据字段会直接抛 cannot find metadata field 错误;右侧目标字段若与输入表已有字段冲突,则抛 metadata mapping field exists 错误,从源码层面保证映射配置的合法性。
transform ②:Sql 业务字段整形
Sql {
plugin_input = "mysql_orders_with_meta"
plugin_output = "kafka_orders"
query = "select id as order_id, order_no, user_id, amount, case when status = 0 then 'CREATED' when status = 1 then 'PAID' when status = 2 then 'SHIPPED' else 'OTHER' end as status_name, source_database, source_table, change_type, CONCAT(source_database, '.', source_table) as source_name, 'mysql_cdc' as sync_source from dual where id is not null"
}
Sql 变换使用内存 SQL 引擎对输入行做变换(详见 SQL 变换文档),核心参数:
plugin_input:输入表名,SQL 中引用的表名必须与之匹配;plugin_output:输出表名;query:查询 SQL,支持基础函数与条件过滤(如case when、CONCAT),暂不支持多源 JOIN 与 AGGREGATE 聚合;engine:可选,默认ZETA,也支持INTERNAL。
该 query 完成了四类整形:
- 业务字段重命名:
id as order_id; - 状态枚举翻译:
status0/1/2 映射为CREATED/PAID/SHIPPED,其余为OTHER,输出status_name; - 拼接源标识:
CONCAT(source_database, '.', source_table) as source_name; - 写入常量字段:
'mysql_cdc' as sync_source,用于下游标记数据来源管道。
sink:Kafka 写出与 Headers 搬运
Kafka {
plugin_input = "kafka_orders"
bootstrap.servers = "kafkaCluster:9092"
topic = "recipe_mysql_orders"
format = json
partition_key_fields = ["order_id"]
kafka_headers_fields = ["source_database", "source_table", "change_type"]
}
| 参数 | 含义(依据 Kafka sink 文档 与 KafkaSinkOptions.java) |
|---|---|
bootstrap.servers |
Kafka broker 地址列表,逗号分隔,必填 |
topic |
目标 topic,必填;也支持 ${字段名} 动态 topic |
format |
数据格式,默认 json,可选 text、canal_json、debezium_json、compatible_debezium_json、ogg_json、maxwell_json、avro、protobuf、native 等 |
partition_key_fields |
用哪些字段作为 Kafka 消息 key(JSON 形式,如 {"order_id":1001}),key 的哈希决定消息落入哪个分区,从而保证同一业务 key 的有序性;不配置则发送 null key,由 broker 轮询分发 |
kafka_headers_fields |
用哪些字段作为 Kafka 消息 Headers,字段值会被转为字符串作为 header 值 |
kafka_headers_fields 是这条 recipe 的关键点:配置为 header 的字段会从消息 value(payload)中被剔除,只出现在 Kafka 消息头中。在源码 KafkaSinkWriter.getSerializer()(seatunnel-connectors-v2/connector-kafka/src/main/java/org/apache/seatunnel/connectors/seatunnel/kafka/sink/KafkaSinkWriter.java)中,Header 字段会先经过存在性校验(Header field not found),并保证与 partition_key_fields、kafka_message_value_fields 不重叠;此外 format = native 时配置 kafka_headers_fields 会在作业初始化阶段直接抛 OPERATION_NOT_SUPPORTED,因为 NATIVE 格式下 headers 已编码在 value 字节数组中。
验证结果:E2E 断言清单
Docker E2E 测试(KafkaRecipeIT.java)对所有以下行为做了断言:
| # | 断言内容 |
|---|---|
| 1 | 快照阶段为 MySQL 初始行生成了 Kafka 记录 |
| 2 | 记录 1001 的 payload 中包含 order_id、status_name、source_name、sync_source 字段 |
| 3 | 快照记录 1001 的 Kafka Headers 中携带 source_database=shop、source_table=orders、change_type=+I |
| 4 | 在应用 kafka_headers_fields 后,同一快照记录的 JSON payload 中不再包含这三个元数据字段 |
| 5 | 执行 UPDATE shop.orders SET status = 2 ... WHERE id = 1001 后,1001 的最新记录携带 change_type=+U 且 status_name=SHIPPED |
| 6 | 插入 1003 后,1003 的最新记录携带 change_type=+I 且 status_name=CREATED |
也就是说:快照行 1001 在快照阶段以 status_name=CREATED 写出,UPDATE 后更新为 SHIPPED;新增行 1003 以 CREATED 写出——Sql 变换的状态翻译在快照与增量两条路径上都生效。
为什么每个环节这样设计
1. Metadata 只暴露 sink 真正消费的 CDC 字段
本验证作业仅暴露了后续 Kafka sink 或 SQL 变换会消费的三个字段:source_database、source_table、change_type。这样做的价值在于:CDC 源产生的行本身带有元数据,但默认不进入下游 schema;通过 Metadata 把它们“转正”为普通字段后,Sql 可以引用它们做拼接(source_name),Kafka sink 可以把它们搬进 headers。多表合并、来源追溯、按变更类型分流等场景都可以复用这一模式。
2. Sql 把业务整形集中在一处
在本次验证运行中,SQL 产生的结果如下:
- 快照阶段行
1001写出为status_name=CREATED; - 快照阶段行
1002写出为status_name=PAID; - UPDATE 之后行
1001变为status_name=SHIPPED; - INSERT 之后行
1003写出为status_name=CREATED; - 断言的记录同时包含
sync_source,快照行1001还包含source_name。
把状态枚举翻译、字段重命名、来源拼接统一放在 Sql 变换里,比在多个下游逐个处理更易维护,也让上游 CDC 事件保持“接近原始”的形态。
3. kafka_headers_fields 同时改变 Headers 与 payload
这一点在快照记录 1001 上被明确断言:source_database、source_table、change_type 三个字段被搬入 Kafka Headers 之后,在对应 JSON payload 中就不再出现。这是 Kafka sink 的既定行为——headers 字段与消息体字段是互斥的两个载体,下游消费方可通过 Headers API 快速路由/过滤,而无需解析完整 JSON;同时 payload 保持精简,只保留业务字段。
运行与验证方式
- 按 SeaTunnel 部署文档 完成本地安装;
- 将 MySQL JDBC 驱动放入
${SEATUNNEL_HOME}/lib/(Zeta 引擎),创建具备 CDC 权限的账号并开启 binlog/GTID; - 预先创建 Kafka topic(本 recipe 为
recipe_mysql_orders); - 将上文配置中的
mysql_cdc_e2e、kafkaCluster替换为真实主机名,保存为.conf作业文件; - 通过 SeaTunnel 提交作业(Zeta 引擎),随后在 MySQL 中执行增量 UPDATE/INSERT,用 Kafka 消费端工具观察 payload 与 headers 的变化,即可复现本文的全部断言结果。
相关文档
- MySQL-CDC 源连接器:权限、binlog 开启、全部 Source 参数与 FAQ
- Kafka sink 连接器:
kafka_headers_fields、partition_key_fields、semantics等参数的完整说明与更多示例 - Metadata 变换:受支持元数据键全集、
metadata_fields配置格式与多个组合示例 - Sql 变换:
query语法、支持的函数边界与结构体查询示例