必须主从两端分别安装并启用rpl_semi_sync_master和rpl_semi_sync_slave插件,主库须先INSTALL PLUGIN再配置rpl_semi_sync_master_enabled=ON,否则启动报错;从库还需同时启用relay_log、read_only=ON,并执行STOP/START SLAVE IO_THREAD;最终需验证Rpl_semi_sync_master_status、Rpl_semi_sync_master_clients>0及Rpl_semi_sync_slave_status均为ON。

rpl_semi_sync_master 和 rpl_semi_sync_slave 插件必须在主从两端分别安装并启用,否则半同步形同虚设——只开主库插件或只配参数,复制仍是异步的。
主库必须先装插件再启配置,否则 mysqld 启动失败
MySQL 8.0 默认不加载半同步插件,rpl_semi_sync_master_enabled=ON 这类配置项只有在插件已安装的前提下才生效。如果先写配置再启动,mysqld 会直接报错退出,日志里出现类似 Unknown variable 'rpl_semi_sync_master_enabled' 的错误。
正确顺序是:
- 登录主库 MySQL,执行:
INSTALL PLUGIN rpl_semi_sync_master SONAME 'semisync_master.so'; - 确认安装成功:
SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'rpl_semi%';(应看到rpl_semi_sync_master状态为ACTIVE) - 再编辑
/etc/my.cnf或/etc/my.cnf.d/mysql-server.cnf,添加以下几行:
[mysqld] server-id = 1 log-bin = mysql-bin binlog-format = ROW rpl_semi_sync_master_enabled = ON rpl_semi_sync_master_timeout = 3000
rpl_semi_sync_master_timeout 单位是毫秒,设为 3000 表示等 3 秒,超时就退化为异步;这个值不能设为 0(会无限等待),也不建议设太高(影响写入延迟)。
从库要装 rpl_semi_sync_slave 插件 + 开启 read_only + 配 relay_log
从库只装 rpl_semi_sync_slave 插件还不够,必须同时满足三个条件才能参与半同步:
- 执行:
INSTALL PLUGIN rpl_semi_sync_slave SONAME 'semisync_slave.so';(注意不是semisync_master.so) - 配置文件中必须有
server-id(不能和主库重复),且开启relay_log(如relay-log = relay-bin) - 务必设置
read_only = ON(防止误写导致 GTID 冲突或数据不一致)
典型从库配置片段:
安装、修复、更新或打包一个基于 Python 和 PyMySQL 实现的 Windows `mysql` 命令。适用于用户希望在 PowerShell/CMD 中输入 `mysql` 时重定向到 Python 实现、需要交互式输入 MySQL 连接信息、需要同步到当前用户本地 bin 目录,或需要将该能力封装成可公开复用的 Codex skill。
[mysqld] server-id = 2 relay-log = relay-bin read_only = ON rpl_semi_sync_slave_enabled = ON
配置完后,需重启 IO 线程使插件生效:STOP SLAVE IO_THREAD; START SLAVE IO_THREAD;
验证状态必须查两个变量,缺一不可
仅看 Rpl_semi_sync_master_status 为 ON 不代表真正生效——它只说明主库插件已启用,但没确认是否有从库连上来参与半同步。
- 主库执行:
SHOW STATUS LIKE 'Rpl_semi_sync_master_status';和SHOW STATUS LIKE 'Rpl_semi_sync_master_clients';——前者为ON,后者 > 0 才算正常 - 从库执行:
SHOW STATUS LIKE 'Rpl_semi_sync_slave_status';——必须为ON,否则从库未以半同步方式运行 - 若任一返回
OFF,常见原因包括:插件名写错、plugin_dir路径下缺失.so文件、未重启 IO 线程、read_only未开、或主从时间不同步(影响超时判断)
MySQL 8.0.26+ 版本插件名可能不同
MySQL 8.0.26 及以后版本中,官方将插件重命名为 semisync_source 和 semisync_replica(对应旧版 rpl_semi_sync_master / rpl_semi_sync_slave),但变量名保持不变。若执行 INSTALL PLUGIN 报错 Plugin 'xxx' is not loaded,先查 SELECT @@plugin_dir;,再用 ls 确认实际插件文件名,避免硬套旧文档。
最容易被忽略的是:半同步只作用于默认复制通道(default),如果你用了多源复制或自定义通道,rpl_semi_sync_* 参数不会生效,也不会报错——这种情况下,得靠应用层兜底或换用 Group Replication。










