SeaTunnel 实战:MySQL CDC 实时同步到 Elasticsearch,实现过滤、清洗与自定义补字段

原创2026-09-19 11:04:231,350 阅读
文章标签:数据集成ETL大数据数据同步变更数据捕获流处理批处理

SeaTunnel 实战:MySQL CDC 实时同步到 Elasticsearch,实现过滤、清洗与自定义补字段

本教程基于 SeaTunnel 的 Zeta 引擎,演示如何将 MySQL 中的客户资料表(crm.customer_profile)持续实时同步到 Elasticsearch,并在同步过程中完成业务过滤(只保留管理范围内数据)、字段清洗(去除手机号中的连字符、去除姓名空格)、状态值映射(数字状态转可读状态名)以及来源元数据补充(库名、表名、变更类型、同步来源标记)。读完本文,你将掌握一条完整的「MySQL-CDC Source → Transform 链 → Elasticsearch Sink」流水线写法,理解每个配置项的底层含义,并能够直接复用到自己的实时数仓或搜索索引构建场景中。

流水线概览

本教程要实现的完整数据链路如下:

  • MySQL-CDC Source:读取 crm.customer_profile 表的初始快照与后续 binlog 增量变更;
  • Metadata Transform:把库名(Database)、表名(Table)、行变更类型(RowKind)从行内元数据暴露为普通字段;
  • Replace Transform:去掉手机号字段中的 - 字符;
  • Sql Transform:负责行级过滤(id >= 1000)、状态映射(status → ACTIVE/FROZEN/OTHER)以及补充常量字段 sync_source;
  • Elasticsearch Sink:按主键 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 文档补发删除事件,结果就是“该删的没删”,索引里残留脏数据。对于软删除场景,正确做法有两种:

  1. 把删除标记(如 is_deleted)原样同步到 Elasticsearch,在查询时过滤;
  2. 使用能将状态变化明确转换为删除事件的专用链路(如依赖 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":在已有数据基础上追加/更新,不清空索引。

进一步阅读

本教程用到的组件都有独立的专题文档,可在仓库中继续深入:

此外,仓库中还有 multi-table-cdc.md、mysql-cdc-to-doris.md、mysql-cdc-to-kafka.md 等同类配方,可用于对比不同下游的 CDC 同步写法。

登录后查看全文
seatunnel