MySQL GTID 自动定位与复制拓扑切换清单

MySQL GTID 的价值不只是把复制位置从“文件名+偏移量”换成一串编号。真正做主从切换时，它可以让副本根据自己已经执行的事务集自动请求缺少的事务，减少人工计算坐标的机会。稳妥的清单是：先确认所有节点的 GTID 模式和复制状态，再启用自动定位；切换前停止写入，选择已应用事务最完整的副本；切换后重指向下游并核对线程，旧源恢复时先作为副本回接。

官方文档：https://dev.mysql.com/doc/refman/8.4/en/

下面的命令按 MySQL 8.4 的 CHANGE REPLICATION SOURCE TO 语法书写。示例是操作清单，不代表已经在某个线上拓扑执行。

先确认 GTID 自动定位的前置条件

自动定位依赖 GTID 事务。MySQL 官方文档明确说明，启用 SOURCE_AUTO_POSITION 后，副本从复制数据流中获得同步所需的信息，不再依赖 SOURCE_LOG_FILE 与 SOURCE_LOG_POS。因此切换前先确认拓扑里没有尚未处理的匿名事务，并把检查结果保存到变更记录。

-- 在源库和候选副本上分别查看 GTID 模式与已执行事务集
SELECT @@GLOBAL.gtid_mode AS gtid_mode,
       @@GLOBAL.enforce_gtid_consistency AS enforce_gtid_consistency,
       @@GLOBAL.gtid_executed AS executed_gtid_set;

-- 在副本上查看 IO 线程、SQL 线程和当前延迟信息
SHOW REPLICA STATUS\G

重点看三件事：gtid_mode 是否处于可使用 GTID 的状态，enforce_gtid_consistency 是否已按拓扑要求配置，以及 SHOW REPLICA STATUS 中两个复制线程是否正常。若某个副本仍有匿名事务或线程报错，不要直接把它提升为新源。

把复制位置交给 GTID 集判断

在已经满足 GTID 前置条件的副本上，先停止复制，再打开自动定位，最后重新启动复制。SOURCE_AUTO_POSITION 默认不是开启状态，多源复制时还要对每个需要切换的通道单独设置。

-- 先停止当前通道，避免修改连接参数时仍在拉取事件
STOP REPLICA;

-- 让副本根据 GTID 集自动请求缺少的事务
CHANGE REPLICATION SOURCE TO
  SOURCE_AUTO_POSITION = 1;

-- 重新启动复制通道
START REPLICA;

-- 再次读取线程状态，记录切换前后的差异
SHOW REPLICA STATUS\G

这里的关键不是看到一个“切换成功”的提示，而是判断副本是否持续应用事务。对于已知的目标 GTID 集，可以使用等待函数让变更脚本等待副本追平；超时只说明当前未追平，不应被当成已经一致。

-- 等待副本执行到变更记录中的目标 GTID 集，60 秒后返回
SELECT WAIT_FOR_EXECUTED_GTID_SET('source-uuid:1-120', 60) AS wait_result;

不要把示例中的 GTID 集直接复制到生产环境。应从实际源库或变更记录取得目标集合，并把结果与候选副本的 @@GLOBAL.gtid_executed 对照。

主源故障时按清单切换拓扑

切换前先暂停应用写入或把写流量导向维护入口，然后比较候选副本的已应用事务集。选择更完整的副本作为新源，原因是 GTID 只能帮助副本请求缺失事务，不能替你解决两个节点已经产生不同写入的问题。

1. 确认旧源不再接受写入，并保留故障时间点和各副本的复制状态。
2. 选择已应用事务更完整且线程无报错的副本，把应用写入口切到它。
3. 在下游副本上停止复制，将源地址改为新源，并保留 SOURCE_AUTO_POSITION = 1。
4. 启动复制，等待 IO 线程和 SQL 线程恢复，再检查下游的 GTID 集是否继续增长。

-- 在需要改指向的下游副本上执行，主机名和账号按环境替换
STOP REPLICA;

-- 只改变新源连接信息，继续使用 GTID 自动定位
CHANGE REPLICATION SOURCE TO
  SOURCE_HOST = 'new-source.example',
  SOURCE_PORT = 3306,
  SOURCE_USER = 'repl_user',
  SOURCE_PASSWORD = 'replace-with-secret',
  SOURCE_AUTO_POSITION = 1;

-- 恢复通道并核对两个复制线程
START REPLICA;
SHOW REPLICA STATUS\G

密码示例只表示参数位置，实际变更中应使用受控凭据，不要把明文密码提交到脚本或文章以外的日志。多源或菱形拓扑还要保持各通道过滤规则一致，否则同一事务从不同通道到达时可能出现不一致。

旧源恢复后的回接边界

旧源重新可用时，不要立刻把它当成写源。官方切换流程建议先让旧源成为新源的副本，补上离线期间错过的写入。只有在确认数据分叉已经处理、复制线程稳定、应用写入口明确之后，才规划下一次角色切换。

如果旧源在脱离拓扑期间接受过独立写入，不能只依赖 GTID 自动跳过。相同 GTID 对应不同事务时，需要人工处理冲突，必要时将其中一个节点移出拓扑；如果只是旧源缺少新源事务，则先让它作为副本追平。涉及重新把旧源变回源库的场景，还要按官方流程评估是否需要在切换点执行 RESET BINARY LOGS AND GTIDS，不能把该语句当成通用修复按钮。

-- 旧源恢复后，先把它接到当前新源上作为副本
STOP REPLICA;
CHANGE REPLICATION SOURCE TO
  SOURCE_HOST = 'current-source.example',
  SOURCE_PORT = 3306,
  SOURCE_AUTO_POSITION = 1;
START REPLICA;

-- 回接后只核对状态，不把“线程启动”误判为“数据已追平”
SHOW REPLICA STATUS\G;
SELECT @@GLOBAL.gtid_executed AS rejoined_gtid_set;

切换前后的速查表

常见问题

开启 SOURCE_AUTO_POSITION 后还要填写 SOURCE_LOG_POS 吗？

不需要把文件和偏移量作为 GTID 自动定位的主要位置依据；但旧配置里若仍保留相关参数，应按当前版本文档和变更脚本确认是否清理，不能混用两套切换逻辑。

副本线程都是 Yes，就能马上提升为新源吗？

不能。线程正常只说明通道工作，仍要比较已执行 GTID 集，并确认应用写入已经停止或完成切换。

GTID 能自动解决双写冲突吗？

不能。GTID 能帮助识别已执行事务并避免同一 GTID 被重复执行，但两个节点对同一 GTID 产生不同事务时，仍需要人工冲突处理。