Canal group-instance模式：分库分表数据同步实战指南

1. 分库分表场景下的数据同步难题

分库分表这件事，做过的人都知道，拆开容易合上难。业务表一旦按照用户ID或者订单ID散落到多个物理库、多张物理表里，数据写入是痛快了，可下游要消费这些变更数据的时候，麻烦就来了。最典型的需求就是：上游订单库拆成了4个库、每个库8张表，下游的数仓或者搜索集群需要拿到一份完整的、按时间顺序排列的变更日志。这时候如果还用单实例的binlog订阅方式，就得起32个客户端分别去连32个源，维护成本高不说，位点管理、断点续传、故障恢复全是坑。

canal这套组件就是为解决MySQL增量日志订阅而生的，它伪装成MySQL的从库，向主库发送dump协议，拿到binlog之后解析成结构化的数据变更事件。单库单表的场景下，一个canal instance对应一个destination，配置简单直接。但到了分库分表场景，canal提供了一种叫group-instance的配置模式，通过一个group-instance.xml把多个物理实例的订阅任务编排在一起，对外呈现为一个逻辑上的合并数据流。这个机制在官方文档里着墨不多，很多人第一次看到group-instance.xml这个文件名的时候完全不知道它是干什么用的，更不清楚它和普通的instance.xml之间是什么关系。

我最早接触这个配置是在一个交易系统的实时数仓项目里，上游按商户维度拆了8个库，每个库16张订单表，总共128个物理分片。当时试过用DataX做批量同步，延迟太大；也试过自己写binlog解析程序，光是处理DDL变更和位点漂移就耗掉了两周。后来换成canal的group-instance模式，虽然踩了不少坑，但整体架构确实清爽了很多。这篇文章就把这套方案的来龙去脉、配置细节、实操步骤和踩坑经验完整梳理一遍，适合正在做分库分表数据同步的开发和运维同学参考，不管你是刚接触canal还是已经用过单实例模式，都能从中找到可以直接复用的配置模板和排查思路。

2. group-instance.xml到底解决了什么问题

2.1 从单实例模式说起

普通的canal instance配置长这样：在canal.properties里定义好destination，然后在conf目录下建一个以destination命名的文件夹，里面放instance.properties，指定源库的jdbc连接、binlog位置、订阅规则等。一个instance对应一个MySQL物理实例，canal server启动后会为每个instance创建一个CanalInstance对象，内部包含一个MySQLBinlogParser、一个EventSink、一个EventStore和一个MetaManager。这套模型在单库场景下运行得很好，位点管理精确到binlog文件名和position，重启后能准确恢复。

但分库分表之后，如果你有32个物理分片，就得配32个destination，每个destination一个instance.properties。canal server的内存占用会随着instance数量线性增长，每个instance都有自己的环形缓冲区、自己的工作线程池。更麻烦的是，这32个instance之间没有任何协调机制，它们各自独立地向客户端推送数据，客户端拿到的是32路乱序的事件流，需要自己做合并和排序。如果你的下游消费者需要全局有序，那就得在客户端维护一个复杂的多路归并逻辑，还得处理某一路延迟导致的数据空洞问题。

2.2 group-instance的核心设计思路

group-instance模式的核心思想是：把多个物理实例的订阅任务在canal server内部合并成一个逻辑instance，对外只暴露一个destination。客户端连接这个destination，拿到的是已经合并好的、按时间戳排序的事件流，不需要关心底层有多少个物理分片。

这个合并动作发生在canal server内部，具体来说是在CanalInstance的构建阶段。group-instance.xml里定义了一个instance列表，每个instance对应一个物理分片的订阅配置。canal server启动时，会为group中的每个子instance创建一个CanalInstanceWithGroup对象，这些子instance各自独立地拉取binlog、解析事件，然后把事件写入一个共享的EventStore。这个EventStore是一个基于内存的环形队列，支持多生产者单消费者模式。多个子instance作为生产者并发写入，客户端作为唯一消费者顺序读取。写入的时候会按照事件的时间戳进行排序插入，保证客户端拿到的事件流是全局有序的。

这里有一个关键的设计取舍：group-instance模式下的EventStore是内存态的，不像单实例模式可以配置为文件存储。这意味着如果canal server重启，内存中未消费的事件会丢失。官方给出的解释是，group模式本身就是为了实时合并场景设计的，如果客户端消费不过来，应该通过增加客户端消费能力来解决，而不是依赖服务端的持久化缓冲。这个取舍在实际使用中需要特别注意，后面讲配置的时候会详细说。

2.3 与普通instance模式的对比

从表里可以看出来，group-instance模式最大的优势是简化了客户端的消费逻辑，把合并排序的复杂度从客户端转移到了canal server内部。但代价是服务端的复杂度和资源消耗增加了，而且引入了一个单点故障的风险——如果group中某个子instance挂了，整个group的数据流都会受影响。

2.4 什么场景下应该用group-instance

不是所有分库分表场景都适合用group-instance。如果你的下游消费者本身就是按分片维度处理的，比如每个分片的数据写入不同的下游表，那用普通instance模式更简单直接。但如果你需要的是全局有序的变更流，比如：

• 实时数仓的ODS层需要一份完整的订单变更记录，按时间顺序排列
• 搜索集群需要根据变更事件更新索引，且更新顺序影响最终结果
• 缓存系统需要按变更顺序刷新，避免旧值覆盖新值
• 审计系统需要一份全局有序的操作日志

这些场景下，group-instance模式能帮你省掉客户端多路归并的复杂逻辑。但要注意，全局有序的前提是各个源库的服务器时间要同步，如果时间偏差太大，合并出来的顺序可能不符合预期。建议在部署前先检查各源库的NTP同步状态，偏差控制在毫秒级以内。

3. group-instance.xml配置细节全拆解

3.1 配置文件的基本结构

group-instance.xml通常放在conf目录下，与具体的destination文件夹平级。它的结构大致如下：

<?xml version="1.0" encoding="UTF-8"?> <canal> <instance> <groupId>order-group</groupId> <instances> <instance> <name>order-db-0</name> <host>192.168.1.101</host> <port>3306</port> <username>canal</username> <password>canal_pass</password> <filterRegex>order_db_0\..*</filterRegex> </instance> <instance> <name>order-db-1</name> <host>192.168.1.102</host> <port>3306</port> <username>canal</username> <password>canal_pass</password> <filterRegex>order_db_1\..*</filterRegex> </instance> <!-- 更多子instance --> </instances> <eventStoreCapacity>65536</eventStoreCapacity> <mergeBufferSize>32768</mergeBufferSize> </instance> </canal>

这个结构看起来简单，但每个字段都有讲究。groupId是整个group的唯一标识，客户端连接的时候用的destination名称就是这个groupId。instances列表里的每个instance对应一个物理分片，name是子instance的标识，在日志和监控里会用到。host和port是源库的连接信息，username和password需要有REPLICATION SLAVE和REPLICATION CLIENT权限。

filterRegex是过滤规则，用来指定订阅哪些库哪些表。这里有个容易踩的坑：group模式下，每个子instance的filterRegex是独立生效的，但最终合并到客户端的事件流里，不同子instance的事件会混在一起。如果你的下游消费者需要区分事件来自哪个分片，需要在事件内容里自己加分片标识，比如在表名或者数据字段里带上分片信息。

3.2 子instance的位点管理

group模式下，每个子instance的位点信息是独立存储的。默认情况下，canal会把位点写入zookeeper或者本地文件，具体取决于canal.properties里的配置。如果用的是zookeeper，每个子instance会在/otter/canal/destinations/{groupId}/instances/{instanceName}/cursor路径下维护自己的位点。这个设计的好处是，如果某个子instance重启，它可以从自己的位点继续拉取，不会影响其他子instance。

但这里有一个需要注意的地方：group模式下，客户端的ack是group级别的，不是子instance级别的。也就是说，客户端消费到某个位点后，canal server会把这个ack广播给所有子instance，每个子instance根据自己的位点判断是否需要更新。这个机制在正常情况下没问题，但如果某个子instance长时间没有数据（比如那个分片一直没有写入），它的位点会落后很多，而客户端的ack又不会等它，导致这个子instance的位点一直不更新。下次它再有数据写入时，会从很旧的位点开始拉取，产生大量重复事件。

解决这个问题的办法是，在canal.properties里配置canal.instance.detecting.enable=true，开启空闲检测。当某个子instance超过一定时间没有数据时，canal会主动推进它的位点，避免位点落后太多。这个配置在group模式下几乎是必须的，我见过好几个项目因为没开这个配置，导致某个冷分片突然有数据时，客户端收到几万条重复事件。

3.3 EventStore容量与合并缓冲区

group-instance.xml里有两个关键参数：eventStoreCapacity和mergeBufferSize。eventStoreCapacity是整个group共享的EventStore容量，单位是事件条数。这个值需要根据你的峰值流量来估算。假设你的峰值QPS是5000，客户端消费延迟容忍是10秒，那EventStore至少需要容纳50000条事件。但实际配置时建议留一倍余量，设成100000左右。

mergeBufferSize是每个子instance的合并缓冲区大小。子instance从源库拉取到binlog事件后，先写入自己的合并缓冲区，然后再批量写入共享的EventStore。这个缓冲区的作用是减少锁竞争，提高写入效率。如果设得太小，子instance会频繁地争抢EventStore的写锁；设得太大，内存占用会增加，而且事件在缓冲区里停留时间过长，会增加端到端延迟。根据经验，mergeBufferSize设成eventStoreCapacity的1/4到1/2比较合适。

这两个参数在canal.properties里也有对应的全局配置，group-instance.xml里的配置会覆盖全局配置。建议在group-instance.xml里显式指定，避免不同group之间互相影响。

3.4 与canal.properties的配合

group-instance.xml不是独立生效的，它需要和canal.properties配合使用。在canal.properties里，你需要把canal.instance.global.mode设成group，然后指定canal.instance.global.group.file为group-instance.xml的路径。这样canal server启动时，就会加载这个group配置，而不是去扫描conf目录下的各个destination文件夹。

canal.instance.global.mode = group canal.instance.global.group.file = classpath:group-instance.xml canal.instance.global.lazy = false

这里canal.instance.global.lazy建议设成false，让canal server启动时就初始化所有子instance，而不是等到客户端连接时才初始化。虽然启动会慢一些，但可以避免第一个客户端连接时的长时间等待。

另外，canal.properties里的canal.instance.memory.buffer.size和canal.instance.memory.buffer.memunit这两个参数在group模式下会被group-instance.xml里的配置覆盖，但为了保险起见，还是建议在canal.properties里也设置一个合理的默认值。

4. 从零搭建group-instance同步链路

4.1 环境准备与权限配置

在开始配置之前，需要确保每个源库都创建了canal专用的账号，并授予必要的权限：

CREATE USER 'canal'@'%' IDENTIFIED BY 'canal_pass'; GRANT SELECT, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'canal'@'%'; FLUSH PRIVILEGES;

这里有个细节：canal需要SELECT权限来获取表的元数据信息，比如表结构、主键等。如果你的MySQL版本是8.0以上，还需要注意密码加密插件的问题，建议使用mysql_native_password插件创建账号，避免连接失败。

另外，每个源库的binlog_format必须是ROW模式，binlog_row_image建议设成FULL，这样canal才能拿到完整的行变更数据。binlog_format是STATEMENT或者MIXED的话，canal解析出来的事件可能不完整。

-- 检查binlog配置 SHOW VARIABLES LIKE 'binlog_format'; SHOW VARIABLES LIKE 'binlog_row_image';

如果这两个参数不符合要求，需要修改MySQL配置文件并重启实例。这个操作在生产环境需要谨慎，建议在业务低峰期进行。

4.2 编写group-instance.xml

假设我们有4个物理分片，分别部署在4个MySQL实例上，每个实例上有一个库，库名从order_db_0到order_db_3。group-instance.xml的完整配置如下：

<?xml version="1.0" encoding="UTF-8"?> <canal> <instance> <groupId>order-group</groupId> <instances> <instance> <name>order-db-0</name> <host>192.168.1.101</host> <port>3306</port> <username>canal</username> <password>canal_pass</password> <filterRegex>order_db_0\..*</filterRegex> <connectionCharset>UTF-8</connectionCharset> <detectingEnable>true</detectingEnable> <detectingSQL>select 1</detectingSQL> <detectingInterval>5</detectingInterval> </instance> <instance> <name>order-db-1</name> <host>192.168.1.102</host> <port>3306</port> <username>canal</username> <password>canal_pass</password> <filterRegex>order_db_1\..*</filterRegex> <connectionCharset>UTF-8</connectionCharset> <detectingEnable>true</detectingEnable> <detectingSQL>select 1</detectingSQL> <detectingInterval>5</detectingInterval> </instance> <instance> <name>order-db-2</name> <host>192.168.1.103</host> <port>3306</port> <username>canal</username> <password>canal_pass</password> <filterRegex>order_db_2\..*</filterRegex> <connectionCharset>UTF-8</connectionCharset> <detectingEnable>true</detectingEnable> <detectingSQL>select 1</detectingSQL> <detectingInterval>5</detectingInterval> </instance> <instance> <name>order-db-3</name> <host>192.168.1.104</host> <port>3306</port> <username>canal</username> <password>canal_pass</password> <filterRegex>order_db_3\..*</filterRegex> <connectionCharset>UTF-8</connectionCharset> <detectingEnable>true</detectingEnable> <detectingSQL>select 1</detectingSQL> <detectingInterval>5</detectingInterval> </instance> </instances> <eventStoreCapacity>131072</eventStoreCapacity> <mergeBufferSize>65536</mergeBufferSize> </instance> </canal>

这里每个子instance都开启了空闲检测，检测间隔是5秒。detectingSQL用的是最简单的select 1，这个查询会走MySQL的查询缓存，对源库压力很小。如果你的源库负载很高，可以把检测间隔调大一些，比如10秒或15秒。

4.3 canal.properties的关键配置

canal.properties里除了前面提到的global.mode和global.group.file，还有几个参数需要关注：

# 服务端口 canal.port = 11111 # 是否开启metrics canal.metrics.pull.port = 11112 # zookeeper配置（如果使用zk管理位点） canal.zkServers = 192.168.1.200:2181 # 位点存储模式，建议用zookeeper canal.instance.global.mode = group canal.instance.global.group.file = classpath:group-instance.xml # 内存缓冲配置 canal.instance.memory.buffer.size = 131072 canal.instance.memory.buffer.memunit = 1024 # 是否开启gtid模式 canal.instance.gtidon = false

如果你的MySQL开启了GTID，可以把canal.instance.gtidon设成true，这样位点管理会更简单，不需要关心binlog文件名和position。但GTID模式下，canal对某些DDL语句的解析可能会有问题，建议先在测试环境验证。

4.4 启动与验证

配置完成后，启动canal server：

sh bin/startup.sh

启动日志里会打印每个子instance的初始化信息，包括连接的源库、起始位点、过滤规则等。如果某个子instance连接失败，日志里会有明确的错误提示，比如权限不足、网络不通、binlog格式不对等。

启动成功后，可以用canal自带的客户端工具验证：

sh bin/canal.sh -h 127.0.0.1 -p 11111 -d order-group

这个命令会连接到group destination，打印出收到的事件。如果配置正确，你应该能看到来自4个分片的事件按时间顺序排列。这里有个验证技巧：在源库上分别执行几条insert语句，观察客户端收到的事件顺序是否与执行顺序一致。如果发现乱序，检查各源库的时间同步状态。

5. 实操中遇到的典型问题与排查方法

5.1 子instance连接失败

这是最常见的问题，表现是canal server启动后，某个子instance一直处于重连状态。排查思路如下：

首先看日志里的错误信息。如果是Access denied，说明账号密码不对或者权限不足。检查canal账号是否有REPLICATION SLAVE权限，以及密码是否包含特殊字符导致解析错误。如果是Communications link failure，说明网络不通，检查防火墙规则和MySQL的bind-address配置。

还有一个容易被忽略的问题：MySQL的max_connections设得太小，canal的连接被拒绝。canal每个子instance会创建至少两个连接，一个用于dump binlog，一个用于查询元数据。如果分片很多，连接数会成倍增加。建议在MySQL侧预留足够的连接数，或者调整canal的连接池配置。

5.2 事件乱序或重复

事件乱序通常是因为各源库的时间不同步。canal合并事件时，是按照事件的时间戳排序的，如果某个源库的时间比其他的快了几秒，它的事件就会排到前面。解决办法是确保所有源库都配置了NTP同步，并且NTP服务器的时间偏差在毫秒级以内。

事件重复则通常是因为位点管理出了问题。前面提到过，如果某个子instance长时间没有数据，它的位点会落后，而客户端的ack又不会等它。当它再有数据时，会从旧位点开始拉取，产生重复事件。解决办法是开启空闲检测，让canal主动推进空闲子instance的位点。

还有一种情况是客户端消费失败后重试，导致重复消费。canal本身不保证exactly-once语义，只保证at-least-once。如果你的下游系统对重复敏感，需要在消费端做幂等处理，比如用主键去重或者用版本号判断。

5.3 内存溢出与GC频繁

group模式下，EventStore是内存态的，如果客户端消费速度跟不上生产速度，EventStore会逐渐填满，最终导致OOM。表现是canal server频繁Full GC，最终抛出OutOfMemoryError。

解决这个问题的根本办法是提高客户端消费能力，比如增加消费线程、优化消费逻辑、批量处理事件等。如果短期内无法提升消费能力，可以适当调大eventStoreCapacity，但这只是缓兵之计，治标不治本。

另外，mergeBufferSize设得太大也会导致内存占用过高。建议根据实际流量调整，不要盲目设大。可以通过canal的metrics接口监控EventStore的使用率，如果长期超过80%，就需要考虑扩容了。

5.4 DDL变更导致解析中断

分库分表场景下，DDL变更是个大麻烦。如果你在某个分片上执行了ALTER TABLE，canal解析到这个DDL事件后，需要重新获取表结构。如果此时其他分片也在执行DDL，或者表结构变更不兼容，canal可能会解析失败，导致数据流中断。

建议的做法是：DDL变更尽量在业务低峰期执行，并且确保所有分片的表结构变更是一致的。如果某个分片的表结构与其他分片不一致，canal在合并事件时可能会出错。另外，可以在canal.properties里配置canal.instance.filter.ddl=true，让canal过滤掉DDL事件，只同步DML事件。但这样做的代价是，下游系统无法感知表结构变更，需要自己维护表结构信息。

5.5 常见问题速查表

6. 性能调优与生产环境建议

6.1 批量拉取与批量消费

canal支持批量拉取binlog事件，通过canal.instance.memory.batch.mode和canal.instance.memory.batch.size两个参数控制。在group模式下，建议把batch.mode设成MEMSIZE，batch.size设成512或1024，这样可以减少网络往返次数，提高吞吐量。

客户端消费时，也建议批量拉取，一次拉取多条事件再处理。canal的客户端API支持getWithoutAck(batchSize)方法，可以一次拉取多条事件。但要注意，批量拉取的事件可能来自不同的子instance，处理时需要根据事件内容做区分。

6.2 监控与告警

生产环境必须配置监控，否则出了问题很难及时发现。canal提供了metrics接口，可以通过HTTP获取各种指标，包括：

• 每个子instance的位点延迟
• EventStore的使用率
• 客户端消费延迟
• 网络连接状态

建议把这些指标接入监控系统，设置合理的告警阈值。比如位点延迟超过30秒告警，EventStore使用率超过80%告警，客户端消费延迟超过60秒告警。

6.3 高可用部署

group-instance模式下，canal server本身是一个单点。如果canal server挂了，整个数据流就断了。建议部署两个canal server实例，通过zookeeper做选主，一个作为active，一个作为standby。当active挂掉后，standby会自动接管。

canal本身支持HA模式，在canal.properties里配置canal.instance.global.mode=group和canal.ha.enable=true，然后在zookeeper里创建相应的节点。具体配置可以参考官方文档，这里不展开。

6.4 我的实操心得

最后分享几个我在实际项目中总结的经验。第一，group-instance.xml里的子instance顺序不重要，canal内部会按照时间戳排序，但建议按照分片编号顺序排列，方便日志查看。第二，如果某个分片的流量特别大，可以考虑把它单独拆成一个group，避免影响其他分片。第三，定期检查各源库的binlog保留时间，如果canal的位点落后超过binlog保留时间，位点就会失效，需要重新初始化。第四，客户端消费时一定要做幂等处理，canal只保证at-least-once，不保证exactly-once。第五，如果下游是Kafka，可以考虑用canal的Kafka适配器，把事件直接写入Kafka，客户端从Kafka消费，这样可以解耦canal和客户端，提高整体稳定性。

这套方案我在两个项目中用过，一个是交易系统的实时数仓，一个是订单系统的搜索索引更新。整体运行稳定，端到端延迟控制在秒级。当然，过程中也踩了不少坑，上面提到的这些问题都是真实遇到过的。希望这些经验能帮到正在做类似事情的同行，少走一些弯路。