Maxwell CDC 技术方案文档（MySQL → Kafka 实时同步）

Maxwell CDC 技术方案文档（MySQL → Kafka 实时同步）

在现代分布式系统中，有大量需求要求实时感知数据库的数据增删改，例如：

• 实时构建搜索索引
• 实时数据仓库 ETL
• 缓存自动刷新
• 审计日志收集
• 事件驱动架构（EDA）

传统批量 ETL 延迟高，不适合实时场景，因此应使用 CDC（Change Data Capture）实时变更捕获技术。

目录

1. 技术背景与方案目标
2. Maxwell 与 MySQL Binlog 基础说明
3. MySQL Binlog 环境准备
4. Maxwell 元数据与权限配置
5. Maxwell 安装与部署
6. Binlog 监听与事件验证（stdout）
7. Binlog 事件模型详解
8. 输出到 Kafka 的完整方案
9. Binlog 监听粒度与能力边界说明
10. 字段级过滤方案：Maxwell.js
11. 使用建议与注意事项
12. 参考资料

1. 技术背景与方案目标

在实际业务中（如缓存刷新、配置同步、数据变更感知等场景），系统通常需要 实时感知 MySQL 数据变更。

基于轮询或定时任务的方案存在：

• 延迟高
• 对数据库压力大
• 数据一致性窗口不可控

因此，本方案采用 MySQL Binlog + Maxwell + Kafka 的 CDC 架构，实现数据库变更的实时事件化。

2. Maxwell 与 MySQL Binlog 基础说明

Maxwell 是一个基于 MySQL Binlog 的 CDC（Change Data Capture）工具：

• 以 MySQL Replication Client 身份接入数据库
• 读取并解析 Binlog
• 将行级变更转换为 JSON 事件
• 输出到 stdout 或 Kafka 等下游系统

⚠️ 重要前提： Maxwell 监听的是 Binlog（ROW 模式），而不是某张表或某个字段。

3. MySQL Binlog 环境准备

3.1 修改 my.cnf，启用 Binlog

在 /etc/my.cnf 的 [mysqld] 模块下添加：

[mysqld]
server_id=1
# binlog 文件前缀
log-bin=mysql-bin
# binlog 模式
binlog_format=row
# 需要生成 binlog 的库，有几个库需要生成 binlog 则添加几行，如果不做该配置，则所有库都会生成 binlog
binlog-do-db=sys_base
binlog-do-db=vota_upgrade

修改完成后，重启 MySQL。

3.2 Binlog 文件说明

• Binlog 默认位于 /var/lib/mysql 目录下
• 未发生数据变更时，binlog 文件大小通常为 154 字节
• 每次 MySQL 重启都会生成新的 binlog 文件
• mysql-bin.index 记录当前使用的 binlog 文件

4. Maxwell 元数据与权限配置

4.1 初始化 Maxwell 元数据库

MySQL 中新建数据库用来存放 Maxwell 的元数据：

CREATE DATABASE maxwell;

4.2 创建 Maxwell 账号

CREATE USER 'maxwell'@'%' IDENTIFIED BY '123456';
GRANT ALL ON maxwell.* TO maxwell@'%';

4.3