1. 位点为什么会“丢”从一次真实故障说起Canal 的位点Position本质上是一个坐标告诉服务端“下一次该从 MySQL Binlog 的哪个字节继续读”。它不是一个简单的数字而是由LogPosition和内部的EntryPosition组合而成的复合结构。当 Canal 重启、主备切换或者客户端重新订阅时服务端必须能把这个坐标从 ZooKeeper 里读出来还原成 Java 对象才能接着上次的位置继续消费。这个“存进去”和“读出来”的过程就是序列化与反序列化。我遇到过最典型的问题是这样的Canal Server 重启后客户端收到的第一条消息时间戳比预期晚了好几分钟或者干脆报Could not find first log file name in binary log index file。排查下来十有八九是位点序列化链路出了问题——要么是EntryPosition里的journalName和position没被正确写入 ZooKeeper要么是反序列化时字段映射失败导致服务端拿了一个默认值或空值去请求 Binlog。更隐蔽的情况是位点写进去了但写的是旧值因为 ACK 提交的时机和持久化动作之间存在竞态。这篇文章聚焦 Canal 1.1.8 的位点序列化与反序列化链路把LogPosition、EntryPosition、MetaManager、ZooKeeperMetaManager这几个关键类拆开看然后给出一份可复制的客户端配置骨架最后用一次“保存位点—重启—恢复位点”的验证动作帮你定位序列化异常和位点丢失问题。适合正在用 Canal 做 MySQL 增量同步、并且需要自己排查位点问题的后端开发和运维同学。2. TaoToken 前置把模型对话和接入文档放在手边排查位点问题时经常需要对照 Canal 的协议定义和 JSON 结构。我习惯把 TaoToken 的模型对话页面开着遇到不确定的字段含义或者想快速验证一段 JSON 的解析逻辑直接丢进去问比翻源码快。它的接入文档里也有 API 调用的完整示例适合在写验证脚本时参考。如果你只是临时查一下LogPosition的字段定义用模型对话就够了如果要把位点查询做成自动化脚本走 API 接入更稳。地址如下模型对话https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentapi_docutm_campaignrewriteAPI Keys 管理https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite注意TaoToken 在这里的角色是辅助你查文档、验证 JSON 结构和生成排查脚本不是替代 Canal 本身。位点的真正读写还是在 Canal Server 和 ZooKeeper 之间完成。3. 可复制配置Canal 客户端位点持久化骨架先明确一点位点的序列化和反序列化主要发生在 Canal Server 侧客户端负责的是“提交 ACK”和“查询当前位点”。但客户端的配置会直接影响位点提交的频率和内容所以配置骨架必须包含 position 持久化相关的 settings。下面是一份基于 Java 客户端的配置示例实例名为trade_order_sync场景是交易订单表的增量同步。3.1 Canal Server 侧 instance.properties 关键项# conf/trade_order_sync/instance.properties canal.instance.master.address192.168.1.100:3306 canal.instance.dbUsernamecanal_user canal.instance.dbPasswordStrongPass!123 canal.instance.mysql.slaveId1234 canal.instance.filter.regextrade_db\\.orders$ canal.instance.tsdb.enabletrue # 位点相关通常留空由 ZooKeeper 管理 # 只有在需要强制从指定位置启动时才填写 # canal.instance.master.journal.namemysql-bin.000005 # canal.instance.master.position123456 # canal.instance.master.timestamp这里的关键是journal.name、position、timestamp三项默认不填Canal 启动时会去 ZooKeeper 的/otter/canal/destinations/trade_order_sync/cursor节点读取上次保存的位点。如果这个节点不存在才会使用 MySQL 当前的最新位点。3.2 客户端 ACK 与位点查询配置// Canal 客户端核心配置 CanalConnector connector CanalConnectors.newSingleConnector( new InetSocketAddress(127.0.0.1, 11111), trade_order_sync, , ); connector.connect(); connector.subscribe(trade_db\\.orders); // 关键批量拉取手动 ACK while (true) { Message message connector.getWithoutAck(1000, 5L, TimeUnit.SECONDS); long batchId message.getId(); int size message.getEntries().size(); if (batchId -1 || size 0) { Thread.sleep(1000); continue; } try { // 处理消息 for (CanalEntry.Entry entry : message.getEntries()) { if (entry.getEntryType() CanalEntry.EntryType.ROWDATA) { // 业务处理逻辑 } } // 处理成功后提交 ACK触发位点持久化 connector.ack(batchId); } catch (Exception e) { // 处理失败则回滚位点不会前进 connector.rollback(batchId); } }这段代码里connector.ack(batchId)是位点前进的触发点。Canal Server 收到 ACK 后会把当前批次对应的LogPosition序列化成 JSON写入 ZooKeeper。如果你把ack放在业务处理之前或者异常时没有rollback位点就会错乱。3.3 位点查询命令# 通过 Netty 端口查询当前位点 echo getBinaryLogPosition | nc 127.0.0.1 11111预期输出类似LogPosition[identityEntryPosition[journalNamemysql-bin.000005,position123456,serverId194,gtid,timestamp1713798000000,includedfalse],slaves[],transactionBitTransaction[txIds[],txBegins[]]]这个输出就是LogPosition.toString()的结果字段顺序和 JSON 序列化后的结构一致。4. 验证请求一次位点保存与恢复的完整动作光看配置不够得实际验证位点有没有被正确序列化和反序列化。下面这套动作可以在测试环境完整跑一遍。4.1 记录初始位点启动 Canal Server 后先查一次当前位点echo getBinaryLogPosition | nc 127.0.0.1 11111假设输出中journalNamemysql-bin.000005position123456。同时去 MySQL 执行SHOW MASTER STATUS;确认File和Position与 Canal 输出一致。如果不一致说明反序列化出来的位点有问题或者 Canal 还没开始消费。4.2 触发一次位点持久化往trade_db.orders表插入一条数据INSERT INTO trade_db.orders (order_id, amount, status) VALUES (TEST20240520001, 99.00, PAID);客户端消费到这条消息并ack后Canal Server 会把新的位点写入 ZooKeeper。此时去 ZK 查看zkCli.sh -server localhost:2181 get /otter/canal/destinations/trade_order_sync/cursor预期输出是一段 JSON{ identity: { journalName: mysql-bin.000005, position: 123789, serverId: 194, gtid: , timestamp: 1713798005000, included: false }, slaves: [], transaction: { txIds: [], txBegins: [] } }注意position应该比之前大了具体增量取决于插入语句产生的 Binlog 字节数。4.3 重启 Canal Server 验证恢复停掉 Canal Serversh bin/stop.sh再启动sh bin/startup.sh启动完成后再次查询位点echo getBinaryLogPosition | nc 127.0.0.1 11111如果输出的journalName和position与 ZK 中保存的一致说明反序列化成功位点恢复正确。如果输出的是 MySQL 当前最新位点说明 ZK 中的位点没有被读取到或者反序列化失败后走了默认逻辑。4.4 用 TaoToken 辅助验证 JSON 结构如果你不确定 ZK 里的 JSON 是否合法可以把内容复制到 TaoToken 的模型对话里让它帮你检查字段是否完整、类型是否匹配。比如问“这段 JSON 反序列化成 LogPosition 时哪些字段可能为 null” 它能快速指出identity缺失或position为字符串等问题。5. 本篇常见错排查5.1 报错Could not find first log file name in binary log index file这个报错说明反序列化出来的journalName指向了一个 MySQL 已经清理掉的 Binlog 文件。原因通常是ZooKeeper 中的位点太旧对应的 Binlog 已被expire_logs_days清理。反序列化时journalName字段映射失败变成了 null 或空字符串Canal 拿了一个无效值去请求。排查方法先查 ZK 中的cursor节点确认journalName的值。如果值本身就很旧说明是 Binlog 保留策略问题如果值是 null 或乱码说明序列化/反序列化链路有 bug。5.2 位点不前进一直重复消费客户端ack之后位点没变常见原因ack的batchId和getWithoutAck返回的不一致导致 Canal Server 认为 ACK 无效。客户端在ack之前抛了异常但没有调用rollback连接断开后 Canal Server 回滚了位点。ZooKeeper 写入失败但客户端没有感知到以为 ACK 成功了。验证方法在ack之后立刻查一次 ZK 中的cursor看position有没有变化。如果没有变化检查 Canal Server 日志中是否有updateCursor相关的 WARN 或 ERROR。5.3 反序列化后timestamp为 0 或负数EntryPosition.timestamp是事件的时间戳单位毫秒。如果反序列化后变成 0说明 JSON 中该字段缺失或类型不匹配。Fastjson 在映射时如果 JSON 中是字符串而 Java 字段是 Long可能会静默失败并赋默认值 0。排查时重点看 ZK 中的 JSON 里timestamp是不是被写成了字符串。5.4 主备切换后位点回退Canal 的 HA 架构中Active Server 挂掉后 Standby 会接管。如果 Standby 读取的位点比 Active 最后提交的位点旧就会重复消费。这通常是因为 Active 在挂掉前没有成功把最新位点写入 ZK。可以调整canal.instance.meta.zookeeper的超时参数或者降低 ACK 的批量大小让位点提交更频繁。提示不要手动去 ZK 里改cursor节点的值。如果确实需要调整位点应该在 Canal Server 停机状态下通过instance.properties中的canal.instance.master.journal.name和canal.instance.master.position指定初始位点启动后再让 ZK 接管。6. 长期编码与 Agent 场景的位点管理如果你在用 Canal 做长期的数据同步或者把 Canal 接入到 Agent 工作流里位点的稳定性直接决定数据一致性。这时候建议把位点监控做成常态化定期对比 Canal 当前位点和 MySQLSHOW MASTER STATUS的差距超过阈值就告警。对于需要频繁调整 Canal 配置、验证位点逻辑的团队可以用 TaoToken 的 Coding Plan 来辅助生成排查脚本和配置模板减少重复劳动。地址Coding Planhttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite最后说一个我踩过的坑Canal 1.1.8 在 GTID 模式下EntryPosition.gtid字段的序列化格式和普通模式不同。如果你的 MySQL 开了 GTID但 Canal 配置里没正确设置canal.instance.gtidontrue反序列化出来的gtid可能是空字符串导致位点恢复时走错分支。验证方法很简单在 ZK 的cursorJSON 里看gtid字段有没有值再对照 MySQL 的SHOW MASTER STATUS里的Executed_Gtid_Set。两者一致才算位点链路完全打通。
1. 位点为什么会“丢”从一次真实故障说起Canal 的位点Position本质上是一个坐标告诉服务端“下一次该从 MySQL Binlog 的哪个字节继续读”。它不是一个简单的数字而是由LogPosition和内部的EntryPosition组合而成的复合结构。当 Canal 重启、主备切换或者客户端重新订阅时服务端必须能把这个坐标从 ZooKeeper 里读出来还原成 Java 对象才能接着上次的位置继续消费。这个“存进去”和“读出来”的过程就是序列化与反序列化。我遇到过最典型的问题是这样的Canal Server 重启后客户端收到的第一条消息时间戳比预期晚了好几分钟或者干脆报Could not find first log file name in binary log index file。排查下来十有八九是位点序列化链路出了问题——要么是EntryPosition里的journalName和position没被正确写入 ZooKeeper要么是反序列化时字段映射失败导致服务端拿了一个默认值或空值去请求 Binlog。更隐蔽的情况是位点写进去了但写的是旧值因为 ACK 提交的时机和持久化动作之间存在竞态。这篇文章聚焦 Canal 1.1.8 的位点序列化与反序列化链路把LogPosition、EntryPosition、MetaManager、ZooKeeperMetaManager这几个关键类拆开看然后给出一份可复制的客户端配置骨架最后用一次“保存位点—重启—恢复位点”的验证动作帮你定位序列化异常和位点丢失问题。适合正在用 Canal 做 MySQL 增量同步、并且需要自己排查位点问题的后端开发和运维同学。2. TaoToken 前置把模型对话和接入文档放在手边排查位点问题时经常需要对照 Canal 的协议定义和 JSON 结构。我习惯把 TaoToken 的模型对话页面开着遇到不确定的字段含义或者想快速验证一段 JSON 的解析逻辑直接丢进去问比翻源码快。它的接入文档里也有 API 调用的完整示例适合在写验证脚本时参考。如果你只是临时查一下LogPosition的字段定义用模型对话就够了如果要把位点查询做成自动化脚本走 API 接入更稳。地址如下模型对话https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentapi_docutm_campaignrewriteAPI Keys 管理https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite注意TaoToken 在这里的角色是辅助你查文档、验证 JSON 结构和生成排查脚本不是替代 Canal 本身。位点的真正读写还是在 Canal Server 和 ZooKeeper 之间完成。3. 可复制配置Canal 客户端位点持久化骨架先明确一点位点的序列化和反序列化主要发生在 Canal Server 侧客户端负责的是“提交 ACK”和“查询当前位点”。但客户端的配置会直接影响位点提交的频率和内容所以配置骨架必须包含 position 持久化相关的 settings。下面是一份基于 Java 客户端的配置示例实例名为trade_order_sync场景是交易订单表的增量同步。3.1 Canal Server 侧 instance.properties 关键项# conf/trade_order_sync/instance.properties canal.instance.master.address192.168.1.100:3306 canal.instance.dbUsernamecanal_user canal.instance.dbPasswordStrongPass!123 canal.instance.mysql.slaveId1234 canal.instance.filter.regextrade_db\\.orders$ canal.instance.tsdb.enabletrue # 位点相关通常留空由 ZooKeeper 管理 # 只有在需要强制从指定位置启动时才填写 # canal.instance.master.journal.namemysql-bin.000005 # canal.instance.master.position123456 # canal.instance.master.timestamp这里的关键是journal.name、position、timestamp三项默认不填Canal 启动时会去 ZooKeeper 的/otter/canal/destinations/trade_order_sync/cursor节点读取上次保存的位点。如果这个节点不存在才会使用 MySQL 当前的最新位点。3.2 客户端 ACK 与位点查询配置// Canal 客户端核心配置 CanalConnector connector CanalConnectors.newSingleConnector( new InetSocketAddress(127.0.0.1, 11111), trade_order_sync, , ); connector.connect(); connector.subscribe(trade_db\\.orders); // 关键批量拉取手动 ACK while (true) { Message message connector.getWithoutAck(1000, 5L, TimeUnit.SECONDS); long batchId message.getId(); int size message.getEntries().size(); if (batchId -1 || size 0) { Thread.sleep(1000); continue; } try { // 处理消息 for (CanalEntry.Entry entry : message.getEntries()) { if (entry.getEntryType() CanalEntry.EntryType.ROWDATA) { // 业务处理逻辑 } } // 处理成功后提交 ACK触发位点持久化 connector.ack(batchId); } catch (Exception e) { // 处理失败则回滚位点不会前进 connector.rollback(batchId); } }这段代码里connector.ack(batchId)是位点前进的触发点。Canal Server 收到 ACK 后会把当前批次对应的LogPosition序列化成 JSON写入 ZooKeeper。如果你把ack放在业务处理之前或者异常时没有rollback位点就会错乱。3.3 位点查询命令# 通过 Netty 端口查询当前位点 echo getBinaryLogPosition | nc 127.0.0.1 11111预期输出类似LogPosition[identityEntryPosition[journalNamemysql-bin.000005,position123456,serverId194,gtid,timestamp1713798000000,includedfalse],slaves[],transactionBitTransaction[txIds[],txBegins[]]]这个输出就是LogPosition.toString()的结果字段顺序和 JSON 序列化后的结构一致。4. 验证请求一次位点保存与恢复的完整动作光看配置不够得实际验证位点有没有被正确序列化和反序列化。下面这套动作可以在测试环境完整跑一遍。4.1 记录初始位点启动 Canal Server 后先查一次当前位点echo getBinaryLogPosition | nc 127.0.0.1 11111假设输出中journalNamemysql-bin.000005position123456。同时去 MySQL 执行SHOW MASTER STATUS;确认File和Position与 Canal 输出一致。如果不一致说明反序列化出来的位点有问题或者 Canal 还没开始消费。4.2 触发一次位点持久化往trade_db.orders表插入一条数据INSERT INTO trade_db.orders (order_id, amount, status) VALUES (TEST20240520001, 99.00, PAID);客户端消费到这条消息并ack后Canal Server 会把新的位点写入 ZooKeeper。此时去 ZK 查看zkCli.sh -server localhost:2181 get /otter/canal/destinations/trade_order_sync/cursor预期输出是一段 JSON{ identity: { journalName: mysql-bin.000005, position: 123789, serverId: 194, gtid: , timestamp: 1713798005000, included: false }, slaves: [], transaction: { txIds: [], txBegins: [] } }注意position应该比之前大了具体增量取决于插入语句产生的 Binlog 字节数。4.3 重启 Canal Server 验证恢复停掉 Canal Serversh bin/stop.sh再启动sh bin/startup.sh启动完成后再次查询位点echo getBinaryLogPosition | nc 127.0.0.1 11111如果输出的journalName和position与 ZK 中保存的一致说明反序列化成功位点恢复正确。如果输出的是 MySQL 当前最新位点说明 ZK 中的位点没有被读取到或者反序列化失败后走了默认逻辑。4.4 用 TaoToken 辅助验证 JSON 结构如果你不确定 ZK 里的 JSON 是否合法可以把内容复制到 TaoToken 的模型对话里让它帮你检查字段是否完整、类型是否匹配。比如问“这段 JSON 反序列化成 LogPosition 时哪些字段可能为 null” 它能快速指出identity缺失或position为字符串等问题。5. 本篇常见错排查5.1 报错Could not find first log file name in binary log index file这个报错说明反序列化出来的journalName指向了一个 MySQL 已经清理掉的 Binlog 文件。原因通常是ZooKeeper 中的位点太旧对应的 Binlog 已被expire_logs_days清理。反序列化时journalName字段映射失败变成了 null 或空字符串Canal 拿了一个无效值去请求。排查方法先查 ZK 中的cursor节点确认journalName的值。如果值本身就很旧说明是 Binlog 保留策略问题如果值是 null 或乱码说明序列化/反序列化链路有 bug。5.2 位点不前进一直重复消费客户端ack之后位点没变常见原因ack的batchId和getWithoutAck返回的不一致导致 Canal Server 认为 ACK 无效。客户端在ack之前抛了异常但没有调用rollback连接断开后 Canal Server 回滚了位点。ZooKeeper 写入失败但客户端没有感知到以为 ACK 成功了。验证方法在ack之后立刻查一次 ZK 中的cursor看position有没有变化。如果没有变化检查 Canal Server 日志中是否有updateCursor相关的 WARN 或 ERROR。5.3 反序列化后timestamp为 0 或负数EntryPosition.timestamp是事件的时间戳单位毫秒。如果反序列化后变成 0说明 JSON 中该字段缺失或类型不匹配。Fastjson 在映射时如果 JSON 中是字符串而 Java 字段是 Long可能会静默失败并赋默认值 0。排查时重点看 ZK 中的 JSON 里timestamp是不是被写成了字符串。5.4 主备切换后位点回退Canal 的 HA 架构中Active Server 挂掉后 Standby 会接管。如果 Standby 读取的位点比 Active 最后提交的位点旧就会重复消费。这通常是因为 Active 在挂掉前没有成功把最新位点写入 ZK。可以调整canal.instance.meta.zookeeper的超时参数或者降低 ACK 的批量大小让位点提交更频繁。提示不要手动去 ZK 里改cursor节点的值。如果确实需要调整位点应该在 Canal Server 停机状态下通过instance.properties中的canal.instance.master.journal.name和canal.instance.master.position指定初始位点启动后再让 ZK 接管。6. 长期编码与 Agent 场景的位点管理如果你在用 Canal 做长期的数据同步或者把 Canal 接入到 Agent 工作流里位点的稳定性直接决定数据一致性。这时候建议把位点监控做成常态化定期对比 Canal 当前位点和 MySQLSHOW MASTER STATUS的差距超过阈值就告警。对于需要频繁调整 Canal 配置、验证位点逻辑的团队可以用 TaoToken 的 Coding Plan 来辅助生成排查脚本和配置模板减少重复劳动。地址Coding Planhttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite最后说一个我踩过的坑Canal 1.1.8 在 GTID 模式下EntryPosition.gtid字段的序列化格式和普通模式不同。如果你的 MySQL 开了 GTID但 Canal 配置里没正确设置canal.instance.gtidontrue反序列化出来的gtid可能是空字符串导致位点恢复时走错分支。验证方法很简单在 ZK 的cursorJSON 里看gtid字段有没有值再对照 MySQL 的SHOW MASTER STATUS里的Executed_Gtid_Set。两者一致才算位点链路完全打通。
