SeaTunnel 实战:MySQL CDC 实时同步到 Elasticsearch,实现过滤、清洗与自定义补字段
SeaTunnel 实战:MySQL CDC 实时同步到 Elasticsearch,实现过滤、清洗与自定义补字段
本教程基于 SeaTunnel 的 Zeta 引擎,演示如何将 MySQL 中的客户资料表(crm.customer_profile)持续实时同步到 Elasticsearch,并在同步过程中完成业务过滤(只保留管理范围内数据)、字段清洗(去除手机号中的连字符、去除姓名空格)、状态值映射(数字状态转可读状态名)以及来源元数据补充(库名、表名、变更类型、同步来源标记)。读完本文,你将掌握一条完整的「MySQL-CDC Source → Transform 链 → Elasticsearch Sink」流水线写法,理解每个配置项的底层含义,并能够直接复用到自己的实时数仓或搜索索引构建场景中。
流水线概览
本教程要实现的完整数据链路如下:
MySQL-CDCSource:读取crm.customer_profile表的初始快照与后续 binlog 增量变更;MetadataTransform:把库名(Database)、表名(Table)、行变更类型(RowKind)从行内元数据暴露为普通字段;ReplaceTransform:去掉手机号字段中的-字符;SqlTransform:负责行级过滤(id >= 1000)、状态映射(status→ACTIVE/FROZEN/OTHER)以及补充常量字段sync_source;ElasticsearchSink:按主键id将数据 upsert 写入索引recipe_customer_profile。
这条链路在 SeaTunnel 中完全通过一份 HOCON 配置文件声明,无需编写任何 Java/Python 代码,适合作为「CDC 入搜索索引」类任务的模板。
前置条件
在开始之前,需要依次完成以下准备工作,确保本地执行链路与环境就绪。
1. 确认本地运行链路正常
先完成 跑第一个任务,确认 SeaTunnel 的本地执行链路可以正常跑通,再继续本教程。
2. 安装并启用所需连接器
按照 部署 > 下载连接器插件 安装本教程需要的连接器,并在 config/plugin_config 中保留下面两项:
--seatunnel-connectors--
connector-cdc-mysql
connector-elasticsearch
--end--
然后执行安装脚本,并确认两个连接器的 JAR 已经落盘:
cd "${SEATUNNEL_HOME}"
sh bin/install-plugin.sh
ls connectors | grep -E 'connector-(cdc-mysql|elasticsearch)'
3. 为 Zeta 引擎准备 MySQL JDBC 驱动
使用 Zeta 引擎时,MySQL-CDC 连接器需要 MySQL Connector/J 驱动。把它放入 ${SEATUNNEL_HOME}/lib,并确认 JAR 已经可见:
ls "${SEATUNNEL_HOME}/lib" | grep 'mysql-connector'
4. 创建 CDC 专用数据库账号
CDC 任务需要一个有权限读取 binlog 的 MySQL 账号。出于安全考虑,不要授予修改表结构的权限(例如 ALTER、CREATE、DROP),只授予读取与复制所需的最小权限:
CREATE USER IF NOT EXISTS 'st_user_source'@'%' IDENTIFIED BY 'mysqlpw';
GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT, LOCK TABLES
ON *.* TO 'st_user_source'@'%';
FLUSH PRIVILEGES;
5. 检查 MySQL binlog 配置
CDC 依赖 binlog 才能读取行级变更,请确认以下三个变量满足要求:
SHOW VARIABLES WHERE variable_name IN ('log_bin', 'binlog_format', 'binlog_row_image');
期望值是 log_bin = ON、binlog_format = ROW、binlog_row_image = FULL。其中:
binlog_format = ROW才能记录每一行的实际变更内容;binlog_row_image = FULL保证 binlog 中携带完整的前镜像/后镜像数据,是 CDC 正确还原变更的基础。
6. 确认 Elasticsearch 可通过 HTTPS 认证访问
本示例基于 Elasticsearch 8.9.0(默认启用 HTTPS 与安全认证)。先用 SeaTunnel 进程可以访问的地址和账号检查连通性:
curl --cacert /path/to/http_ca.crt \
-u elastic:your_password https://elasticsearch.example.com:9200
把可信 CA 证书复制到每个 SeaTunnel 节点,并在任务配置的 tls_truststore_path 中填写对应的本地路径。从 ElasticsearchBaseOptions.java 的源码可以看到,Elasticsearch 连接器支持 tls_verify_certificate(默认 true)、tls_verify_hostname(默认 true)、tls_keystore_path、tls_truststore_path 等一整套 TLS 配置,还支持 auth_type(basic/api_key/api_key_encoded)多种认证方式,本教程使用最基础的 Basic 认证(username + password)。
准备源表数据
在 MySQL 中创建 crm 库和 customer_profile 表,并插入两条初始数据(注意其中一条 id = 900 故意不在后面的管理范围内,用于验证过滤逻辑):
CREATE DATABASE IF NOT EXISTS crm;
USE crm;
CREATE TABLE customer_profile (
id BIGINT NOT NULL PRIMARY KEY,
name VARCHAR(64) NOT NULL,
phone VARCHAR(32) NOT NULL,
email VARCHAR(128) NOT NULL,
status INT NOT NULL,
city VARCHAR(64) NOT NULL
);
INSERT INTO customer_profile (id, name, phone, email, status, city) VALUES
(1001, ' Alice Zhang ', '138-0000-1111', 'alice@example.com', 1, 'Shanghai'),
(900, 'Bob Li', '139-8888-2222', 'bob@example.com', 0, 'Beijing');
任务启动且初始快照已经可以在 Elasticsearch 中查询到之后,再执行下面两条增量变更,用于验证流式更新与增量插入:
UPDATE crm.customer_profile
SET name = ' Alice Zhang ', phone = '138-9999-0000', status = 2
WHERE id = 1001;
INSERT INTO crm.customer_profile (id, name, phone, email, status, city) VALUES
(1003, 'Carol Wang', '137-1234-8888', 'carol@example.com', 1, 'Hangzhou');
完整任务配置
下面给出整条链路的完整 HOCON 配置。请把示例中的主机名和凭据替换为 SeaTunnel 进程可以访问的实际值。并发运行的 MySQL CDC 任务必须使用不同的 server-id 范围,否则会在 MySQL 集群中造成 slave ID 冲突,导致任务失败。
env {
parallelism = 1
job.mode = "STREAMING"
}
source {
MySQL-CDC {
plugin_output = "mysql_customer_raw"
url = "jdbc:mysql://mysql.example.com:3306/crm"
username = "st_user_source"
password = "mysqlpw"
server-id = 5701-5704
table-names = ["crm.customer_profile"]
startup.mode = "initial"
schema-changes.enabled = false
}
}
transform {
Metadata {
plugin_input = "mysql_customer_raw"
plugin_output = "mysql_customer_with_meta"
metadata_fields {
Database = source_database
Table = source_table
RowKind = row_kind
}
}
Replace {
plugin_input = "mysql_customer_with_meta"
plugin_output = "mysql_customer_cleaned"
replace_fields = ["phone"]
pattern = "-"
replacement = ""
is_regex = false
}
Sql {
plugin_input = "mysql_customer_cleaned"
plugin_output = "es_customer_profile"
query = "select id, trim(name) as name, phone, email, city, case when status = 1 then 'ACTIVE' when status = 2 then 'FROZEN' else 'OTHER' end as status_name, source_database, source_table, row_kind, 'mysql_cdc' as sync_source from dual where id >= 1000"
}
}
sink {
Elasticsearch {
plugin_input = "es_customer_profile"
hosts = ["https://elasticsearch.example.com:9200"]
username = "elastic"
password = "elasticsearch"
tls_verify_certificate = true
tls_verify_hostname = true
tls_truststore_path = "/path/to/http_ca.crt"
index = "recipe_customer_profile"
primary_keys = ["id"]
max_batch_size = 1
schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"
data_save_mode = "APPEND_DATA"
}
}
把调整后的配置保存为 ${SEATUNNEL_HOME}/config/mysql-cdc-to-elasticsearch.conf,然后使用 Zeta local 模式提交:
cd "${SEATUNNEL_HOME}"
./bin/seatunnel.sh --config ./config/mysql-cdc-to-elasticsearch.conf -m local
在另一个终端中,分别在执行上面的增量 SQL 前后查询索引,观察文档变化:
curl --cacert /path/to/http_ca.crt -u elastic:your_password \
'https://elasticsearch.example.com:9200/recipe_customer_profile/_search?pretty&sort=id'
配置参数源码级解读
为了让读者不仅“能跑通”,还能理解每个参数为什么这样写,这里结合仓库源码逐一说明关键配置项。
MySQL-CDC Source 关键参数
| 参数 | 含义 | 源码依据 |
|---|---|---|
server-id |
本连接器在 MySQL 集群中注册的从库 ID,支持单个数字(5400)或范围(5400-5408)。不设置时会在 6500 到 2148492146 之间随机生成,官方建议显式指定 |
JdbcSourceOptions.java |
table-names |
要监听的表,格式为 库名.表名 |
同上文件 database-names/table-names 定义 |
startup.mode |
启动模式,可选 initial / earliest / latest / specific / timestamp,默认 initial(先做全量快照,再无缝衔接增量) |
MySqlIncrementalSourceOptions.java |
stop.mode |
停止模式,可选 never / latest / specific,默认 never(持续监听增量) |
同上文件 |
schema-changes.enabled |
是否把 DDL 变更事件下发给下游。本任务下游是 Elasticsearch 索引,不处理表结构变更,因此设为 false |
SourceOptions.java |
startup.mode = "initial" 意味着任务启动时会先对 crm.customer_profile 做一次一致性快照(这也是验证阶段能立刻看到 1001 文档的原因),快照完成后自动切换到 binlog 流式读取,全过程对应用无感。
Elasticsearch Sink 关键参数
| 参数 | 含义 | 源码依据 |
|---|---|---|
primary_keys |
用于生成文档 _id 的主键字段,CDC 变更按主键 upsert,保证更新/删除能命中同一文档 |
ElasticsearchSinkOptions.java |
max_batch_size |
单个 bulk 请求的最大文档数,默认 10。本示例显式设为 1,让每条变更立即可见,方便观察验证 |
同上文件 MAX_BATCH_SIZE(默认 10) |
schema_save_mode |
索引不存在时的处理策略,默认 CREATE_SCHEMA_WHEN_NOT_EXIST(自动建索引) |
同上文件 SCHEMA_SAVE_MODE |
data_save_mode |
数据写入策略,可选 DROP_DATA / APPEND_DATA / ERROR_WHEN_DATA_EXISTS,默认 APPEND_DATA |
同上文件 DATA_SAVE_MODE |
tls_verify_certificate / tls_verify_hostname |
HTTPS 证书与主机名校验开关,默认均为 true |
ElasticsearchBaseOptions.java |
tls_truststore_path |
PEM 或 JKS 信任库路径,运行 SeaTunnel 的操作系统用户必须可读 | 同上文件 TLS_TRUST_STORE_PATH |
需要注意,schema_save_mode 与 data_save_mode 组合时,SeaTunnel 会根据 primary_keys 自动决定使用 index(新建文档)还是 update(按 _id 更新)语义,这是 CDC 场景下“更新 1001 后旧文档被覆盖”这一行为的实现基础。
Metadata Transform 暴露的元数据字段
Metadata 转换用于把行内元数据提取为普通字段,本示例使用了三个最常用的 CDC 元数据 Key:
| 元数据 Key | 输出字段名 | 说明 |
|---|---|---|
Database |
source_database |
数据所属数据库名 |
Table |
source_table |
数据所属表名 |
RowKind |
row_kind |
行的变更类型:+I(插入)、-U(更新前)、+U(更新后)、-D(删除) |
根据 metadata.md 文档,MySQL-CDC 还支持 EventTime、Delay、SourceTimestamp、BinlogFile、BinlogPos、BinlogRow、Gtid 等更细粒度的元数据(其中 BinlogFile 等仅在 MySQL-CDC 下有效,且 startup.mode = initial 时快照行这些字段为 null)。Metadata 转换不会改变原有数据字段,只做“追加元数据列”,因此可以安全地串联在 Source 之后。
验证结果
任务运行后,在 Elasticsearch 的 _search 返回结果中确认以下内容:
- 快照阶段最终只写入了 1 条文档(
1001); 1001被保留下来,因为它的不可变主键属于id >= 1000的管理范围;900被过滤掉,因为它不在这个主键范围内;trim(name)把' Alice Zhang '变成了Alice Zhang(两侧空格被去除);Replace把138-0000-1111变成了13800001111(连字符被去除);- 初始写入的文档里包含
status_name=ACTIVE、source_database=crm、source_table=customer_profile、sync_source=mysql_cdc; - 更新
1001后,ES 中这条文档变成status_name=FROZEN、phone=13899990000、row_kind=+U(更新事件,且旧文档被按_id覆盖); - 插入
1003后,ES 中新增第二条文档,字段包括status_name=ACTIVE、phone=13712348888、row_kind=+I、sync_source=mysql_cdc(插入事件)。
为什么这条链路这样写
1. Replace 负责轻量清洗
在这份配置里,Replace 只做一件事:把手机号里的 - 去掉。它属于轻量级字符串清洗工具,按字段配置 pattern、replacement,并可用 is_regex 控制是否按正则匹配(本示例 is_regex = false,直接按字面量 - 匹配)。把这种简单、确定性的清洗放到 Replace,可以让 Sql 专注于更复杂的业务逻辑,两种 transform 各司其职。
2. Sql 负责业务过滤与补字段
Sql Transform 的 query 集中了全部业务规则:
- 行过滤:只保留
id >= 1000的主键范围; - 状态映射:
case when status = 1 then 'ACTIVE' when status = 2 then 'FROZEN' else 'OTHER' end把数字状态转成可读状态名; - 常量补字段:
'mysql_cdc' as sync_source新增来源标记字段; - 同时透传
Metadata阶段产出的source_database、source_table、row_kind字段。
这里特意使用不可变主键做过滤,这是一个非常重要的设计决策。不要在写入 upsert sink 之前直接用 is_deleted、status 这类可变字段过滤 CDC 更新:如果一条已经写入 ES 的记录后来不再满足过滤条件,上游不会自动为旧 ES 文档补发删除事件,结果就是“该删的没删”,索引里残留脏数据。对于软删除场景,正确做法有两种:
- 把删除标记(如
is_deleted)原样同步到 Elasticsearch,在查询时过滤; - 使用能将状态变化明确转换为删除事件的专用链路(如依赖
RowKind = -D的删除事件,或让下游 sink 识别删除标记并主动删除文档)。
3. Elasticsearch 写入配置的取舍
Sink 端这组参数组合起来产生了上述预期结果:
primary_keys = ["id"]:以id为文档_id,保证 upsert 语义(CDC 更新覆盖旧文档、按主键幂等);max_batch_size = 1:每条变更立即提交,便于在验证阶段逐个观察结果(生产环境建议调大以获得更高吞吐,源码默认值为 10);tls_verify_certificate = true和tls_verify_hostname = true:开启 HTTPS 证书与主机名校验,保证传输安全;schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST":索引不存在时自动创建;data_save_mode = "APPEND_DATA":在已有数据基础上追加/更新,不清空索引。
进一步阅读
本教程用到的组件都有独立的专题文档,可在仓库中继续深入:
MySQL-CDCsource 连接器:更多启动模式、GTID、表结构变更处理等高级选项;Elasticsearchsink 连接器:索引模板、动态索引、批量参数、向量字段等完整配置;Metadatatransform:全部元数据 Key 与 Knowledge Sync 元数据说明;Replacetransform:正则替换、多字段替换等用法;Sqltransform:SQL 表达式、函数与 UDF 支持。
此外,仓库中还有 multi-table-cdc.md、mysql-cdc-to-doris.md、mysql-cdc-to-kafka.md 等同类配方,可用于对比不同下游的 CDC 同步写法。