MySQL半同步复制要求至少一个从库写入relay log后主库才返回成功，兼顾一致性与性能；需主从版本一致、异步复制正常、时间同步，并分别安装启用master/slave插件，关键参数包括超时降级和等待从库数量。
MySQL 半同步复制（Semi-Synchronous Replication）能在主从延迟和数据一致性之间取得更好平衡：它要求至少一个从库确认收到并写入 relay log 后，主库才向客户端返回成功响应。相比异步复制更可靠，相比全同步复制性能损耗更小。
一、确认环境与前提条件
半同步复制是 MySQL 插件机制实现的，需确保：
- 主从实例版本一致（建议 5.7.6+ 或 8.0.x，低版本功能有限或存在已知 Bug）
- 主从已配置好标准异步复制，且 IO 线程和 SQL 线程均正常运行（
SHOW SLAVE STATUS\G中Slave_IO_Running和Slave_SQL_Running均为Yes） - 主从服务器时间同步（使用
ntpd或chrony），避免因时间偏差影响超时判断 - 主库和从库均开启
log_bin，从库还需开启relay_log（默认开启）
二、安装并启用半同步插件
主库和从库需分别安装对应插件（注意：主库装 rpl_semi_sync_master，从库装 rpl_semi_sync_slave）：
主库执行：
INSTALL PLUGIN rpl_semi_sync_master SONAME 'semisync_master.so'; SET GLOBAL rpl_semi_sync_master_enabled = 1; SET GLOBAL rpl_semi_sync_master_timeout = 10000; -- 超时设为 10 秒，单位毫秒
从库执行：
INSTALL PLUGIN rpl_semi_sync_slave SONAME 'semisync_slave.so'; SET GLOBAL rpl_semi_sync_slave_enabled = 1;
重启从库的 IO 线程使插件生效：
安装、修复、更新或打包一个基于 Python 和 PyMySQL 实现的 Windows `mysql` 命令。适用于用户希望在 PowerShell/CMD 中输入 `mysql` 时重定向到 Python 实现、需要交互式输入 MySQL 连接信息、需要同步到当前用户本地 bin 目录，或需要将该能力封装成可公开复用的 Codex skill。
STOP SLAVE IO_THREAD; START SLAVE IO_THREAD;
注意：semisync_master.so 和 semisync_slave.so 文件名可能因平台而异（如 Linux 下为 semisync_master.so，macOS 可能为 semisync_master.dylib），可通过 SELECT @@plugin_dir; 查看插件路径。
三、关键参数调优与行为理解
半同步不是“强一致”，而是“至少一个从库落盘即返回”，其可靠性依赖以下参数：
-
rpl_semi_sync_master_timeout：主库等待从库 ACK 的最大毫秒数。超时后自动降级为异步复制，避免事务长时间阻塞 -
rpl_semi_sync_master_wait_for_slave_count：MySQL 5.7.2+ 支持设置需等待的从库数量（默认 1），可设为 2 提升容错，但会增加延迟风险 ：决定等待时机（ AFTER_SYNC更安全，主库在刷盘 binlog 后等 ACK；AFTER_COMMIT兼容旧版，但极端情况下可能丢事务）-
rpl_semi_sync_master_enabled和rpl_semi_sync_slave_enabled动态开关，可在线启停
推荐生产配置（主库）：
SET GLOBAL rpl_semi_sync_master_enabled = 1; SET GLOBAL rpl_semi_sync_master_timeout = 10000; SET GLOBAL rpl_semi_sync_master_wait_for_slave_count = 1; SET GLOBAL rpl_semi_sync_master_wait_point = 'AFTER_SYNC';
四、验证与监控方法
不能只看“是否启用”，要确认实际是否生效：
- 主库检查：
SHOW VARIABLES LIKE 'rpl_semi_sync%';和SHOW STATUS LIKE 'Rpl_semi_sync%';，重点关注Rpl_semi_sync_master_status（ON/OFF）和Rpl_semi_sync_master_yes_transactions（成功半同步的事务数） - 从库检查：
SHOW VARIABLES LIKE 'rpl_semi_sync%';和SHOW STATUS LIKE 'Rpl_semi_sync_slave%';，确认Rpl_semi_sync_slave_status为 ON - 模拟网络中断测试：临时断开一个从库网络，观察主库是否在超时后自动切回异步（
Rpl_semi_sync_master_status变为 OFF），恢复后是否自动切回（需 IO 线程重连成功） - 配合监控工具（如 Prometheus + mysqld_exporter）采集
mysql_global_status_rpl_semi_sync_master_status指标，设置告警
注意：若主库显示 ON 但从库状态为 OFF，常见原因是未重启 IO 线程，或从库 relay log 损坏导致无法注册 ACK 回调。
不复杂但容易忽略：半同步只保障单次事务的 binlog 至少被一个从库接收，并不保证该从库已执行（SQL 线程可能延迟）。如需更高一致性，需结合 GTID、MHA 或 MySQL 8.0 的组复制方案。
