📚 课程目录第4章 MySQL Connector部署

4、MySQL Connector 部署：配置详解、启动连接器、全量与增量快照、常见参数调优

好，咱们进入第四章节。前面几章我们把 Debezium 集群的基础架构和部署环境搭好了，现在该真刀真枪地配置一个 MySQL 连接器了。

我个人习惯，每次配置一个新的连接器之前，都会先画一张简单的逻辑图，把数据流理清楚。这样后面调参的时候，心里才有底。

4.1 连接器配置详解

配置一个 MySQL 连接器，说白了就是告诉 Debezium 三件事：连哪个库、读哪个表、变更数据往哪发。下面这份配置是我在生产环境里常用的模板，你直接拿去改参数就能用。

{
  "name": "mysql-connector-orders",
  "config": {
    "connector.class": "io.debezium.connector.mysql.MySqlConnector",
    "database.hostname": "192.168.1.100",
    "database.port": "3306",
    "database.user": "debezium",
    "database.password": "Debezium@2024",
    "database.server.id": "184054",
    "database.server.name": "dbserver1",
    "database.include.list": "order_db",
    "table.include.list": "order_db.orders, order_db.order_items",
    "database.history.kafka.bootstrap.servers": "kafka1:9092,kafka2:9092,kafka3:9092",
    "database.history.kafka.topic": "schema-changes.order_db",
    "include.schema.changes": "true",
    "snapshot.mode": "initial",
    "tombstones.on.delete": "false",
    "decimal.handling.mode": "string",
    "time.precision.mode": "adaptive_time_microseconds",
    "max.batch.size": "2048",
    "max.queue.size": "8192",
    "poll.interval.ms": "500"
  }
}

核心参数解读：

database.server.id：每个连接器在 MySQL 里模拟一个 slave，这个 ID 必须全局唯一。我见过有人两台机器配了同一个 ID，结果 Binlog 拉取互相干扰，数据乱得一塌糊涂。
database.server.name：Kafka Topic 的前缀。比如配成 dbserver1，那 Topic 名就是 dbserver1.order_db.orders。
snapshot.mode：启动时是否做全量快照。默认 initial，就是先全量再增量。
decimal.handling.mode：我建议设成 string。用 double 会有精度丢失，做金融业务的兄弟应该深有体会。

4.2 启动连接器

配置写好了，怎么启动？最常用的方式是通过 Kafka Connect REST API。我个人习惯用 curl 提交，简单直接。

# 提交连接器配置
curl -i -X POST -H "Accept:application/json" -H "Content-Type:application/json" \
  http://localhost:8083/connectors/ \
  -d @mysql-connector-orders.json

# 检查连接器状态
curl http://localhost:8083/connectors/mysql-connector-orders/status

# 查看已注册的连接器列表
curl http://localhost:8083/connectors/

启动后，你可以通过 /status 接口看运行状态。返回的 JSON 里有个 state 字段，RUNNING 表示正常，FAILED 就得看 trace 信息排查了。

小技巧：启动连接器之前，先确认 MySQL 的 Binlog 格式是 ROW，且 binlog_row_image 设为 FULL。不然你可能会发现更新操作只记了主键，其他字段全是 null。嗯，这个坑我踩过。

4.3 全量与增量快照

快照是 Debezium 最核心的机制之一。说白了，就是先给你一张当前数据的“照片”，然后持续记录后续的每一次变化。

4.3.1 全量快照（Snapshot）

当连接器第一次启动，且 snapshot.mode 为 initial 时，Debezium 会执行以下步骤：

获取表结构的元数据，记录到 schema change topic。
对每个表执行 SELECT *，分批读取数据。
将每一行数据转换为 Kafka 消息，发送到对应的 Topic。
记录当前 Binlog 位置（GTID 或文件名+偏移量）。
快照完成后，自动切换为增量模式，从记录的 Binlog 位置开始消费。

这里有个细节：快照期间产生的数据变更怎么办？ Debezium 的处理方式是：先记录 Binlog 位置，再做全量快照。快照完成后，从那个位置开始消费增量。这样快照期间漏掉的数据，在增量阶段会补回来。设计得很巧妙，对吧？

4.3.2 增量快照（Incremental Snapshot）

全量快照有个问题：如果表很大（几亿行），快照时间会很长，而且会一直持有读锁。Debezium 从 1.6 版本开始引入了增量快照，允许你按需、分批地快照大表。

增量快照的核心思路是：把一张大表拆成多个 chunk，每个 chunk 独立快照，快照期间正常处理增量事件。这样既不会长时间锁表，也不会阻塞 Binlog 消费。

注意：增量快照需要表有主键或唯一索引，否则 Debezium 没法确定 chunk 的边界。如果你的表没有主键，我建议你先加上，不然增量快照跑不起来。

触发增量快照的方式是通过信号表：

-- 在信号表中插入一条记录
INSERT INTO debezium_signal (id, type, data) 
VALUES ('snapshot-001', 'execute-snapshot', 
        '{"data-collections": ["order_db.orders"], "type": "incremental"}');

我个人比较推荐用增量快照来处理大表。之前有个项目，订单表 3 亿行，全量快照跑了 40 分钟，业务方一直在投诉延迟。改成增量快照后，每 5 分钟快照 500 万行，对业务几乎无感。

4.4 常见参数调优

参数调优这件事，没有银弹。不同的业务场景，侧重点完全不一样。下面这张表是我根据经验整理的调优建议：

参数	默认值	调优建议	场景说明
`max.batch.size`	2048	增大到 4096~8192	高吞吐场景，减少网络交互次数
`max.queue.size`	8192	增大到 16384~32768	应对突发流量，防止背压导致延迟
`poll.interval.ms`	500	降低到 100~200	对延迟敏感的场景，比如金融交易
`snapshot.fetch.size`	2000	增大到 5000~10000	大表快照时，减少查询次数
`heartbeat.interval.ms`	0	设为 30000 (30秒)	低频变更的表，防止连接超时
`incremental.snapshot.chunk.size`	1024	增大到 2048~4096	增量快照时，提高单次处理行数

调优原则：

先监控，后调参：别一上来就改参数。先跑几天，看看 Kafka Connect 的监控指标，比如 outgoing byte rate、source record poll rate，找到瓶颈再动手。
一次只改一个参数：改完观察 10 分钟，确认效果。我曾经一次性改了 5 个参数，结果出问题了都不知道是哪个改坏的。
注意资源限制：增大 max.queue.size 会占用更多内存。如果你的 Kafka Connect 节点只有 4G 内存，别设太大。

4.5 避坑指南

最后，分享几个我在生产环境中遇到过的坑：

Binlog 过期导致连接器失败：MySQL 的 Binlog 默认只保留 7 天。如果连接器挂了超过 7 天，重启时会发现 Binlog 位置已经没了。解决办法是增大 expire_logs_days，或者用 GTID 模式。
表结构变更导致 schema 不匹配：Debezium 依赖 schema history topic 来记录表结构。如果这个 topic 被误删了，连接器启动时会报 schema 异常。我建议给 schema history topic 设置 cleanup.policy=compact，保留历史。
主从切换后连接器失效：MySQL 主从切换后，Binlog 文件名和位置会变。如果连接器用的是文件名+偏移量模式，就会找不到位置。用 GTID 模式可以完美解决这个问题。

我的建议：新项目一律用 GTID 模式。虽然配置起来多一步，但后期运维省心太多了。你想想看，主从切换、故障恢复这些场景，GTID 自动帮你处理了，多好。