SeaTunnel MySQL CDC 到 Kafka 实战:Metadata 元数据注入与 Kafka Headers 字段整形

原创2026-09-17 17:29:042,201 阅读
文章标签:数据集成ETL大数据数据同步变更数据捕获流处理批处理

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 变换:重命名业务字段、翻译状态枚举、填充自定义字段;
  • Kafka sink:以 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 运行环境已满足以下前提:

  1. 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
    
  2. MySQL JDBC 驱动 JAR 已放置到 MySQL-CDC 插件的 lib 目录下(Zeta 引擎为 ${SEATUNNEL_HOME}/lib/)。

  3. 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 会断开其中一个客户端连接。

  4. 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 完成了四类整形:

  1. 业务字段重命名:id as order_id;
  2. 状态枚举翻译:status 0/1/2 映射为 CREATED/PAID/SHIPPED,其余为 OTHER,输出 status_name;
  3. 拼接源标识:CONCAT(source_database, '.', source_table) as source_name;
  4. 写入常量字段:'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 保持精简,只保留业务字段。

运行与验证方式

  1. 按 SeaTunnel 部署文档 完成本地安装;
  2. 将 MySQL JDBC 驱动放入 ${SEATUNNEL_HOME}/lib/(Zeta 引擎),创建具备 CDC 权限的账号并开启 binlog/GTID;
  3. 预先创建 Kafka topic(本 recipe 为 recipe_mysql_orders);
  4. 将上文配置中的 mysql_cdc_e2e、kafkaCluster 替换为真实主机名,保存为 .conf 作业文件;
  5. 通过 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 语法、支持的函数边界与结构体查询示例
登录后查看全文
seatunnel