MySQL集群部署需严格遵循主从角色划分、配置差异化、初始化顺序和权限隔离四步，否则易出现同步失败或连接错误。
mysql 集群不是装完就完事的，主从角色、配置差异、初始化顺序、权限隔离这四步错一步，后续同步就卡在 Seconds_Behind_Master: NULL 或直接报 ERROR 2003 (HY000): Can't connect to MySQL server。直接上 Playbook 不解决实际问题，得先理清节点职责和执行边界。
明确主库/从库角色并分组到 inventory
Ansible 不知道哪台是主、哪台是从，全靠 inventory 分组驱动逻辑分支。不能只写 [dbservers] 一把抓，必须拆开：
-
[mysql_masters]：仅含 1 台，用于写入 + 生成 binlog -
[mysql_slaves]：可多台，只读 + 拉取 relay log -
[mysql_arbiters]（可选）：仅部署 MGR 或仲裁服务，不存数据
变量也得按组隔离，比如 server-id 必须全局唯一：mysql_masters 组用 100，mysql_slaves 用 201、202 这类递增值，硬编码进 vars/main.yml 会锁死扩容能力。
用 my.cnf.j2 模板动态控制主从参数
Jinja2 模板里不能写死 log-bin 或 read_only，得靠 group_names 或自定义变量判断角色：
[mysqld]
server-id = {{ mysql_server_id | default(1) }}
{% if 'mysql_masters' in group_names %}
log-bin = /data/mysql/binlog/mysql-bin
binlog-format = ROW
skip-slave-start = 1
{% else %}
read_only = ON
relay-log = /data/mysql/relaylog/relay-bin
skip-slave-start = 0
{% endif %}
datadir = /data/mysql
socket = /tmp/mysql.sock
注意两点：skip-slave-start 在主库设为 1 防止误启复制；read_only 必须在从库开启，否则手动写入会破坏一致性。模板路径要配对 src: templates/my.cnf.j2，且目标目录 /etc/my.cnf 权限必须是 644，否则 mysqld 启动时拒绝读取。
初始化数据库前必须处理 mysqld --initialize-insecure 的权限与路径
MySQL 8.0 不再支持 mysql_install_db，改用 mysqld --initialize-insecure，但这个命令对用户和目录权限极其敏感：
- 必须用
mysql用户执行，不能用root直接跑 -
datadir目录需提前chown -R mysql:mysql /data/mysql - 首次运行后会生成临时 root 密码，但
--initialize-insecure跳过该步骤，适合自动化场景 - 命令必须加
--user=mysql和--basedir，否则报Failed to find valid data directory
对应 Ansible 任务写法：
- name: Initialize MySQL datadir
shell: >
/usr/local/mysql/bin/mysqld
--initialize-insecure
--user=mysql
--basedir=/usr/local/mysql
--datadir=/data/mysql
args:
creates: /data/mysql/mysql.sock
become_user: mysql
mysql_user 模块创建复制账号时必须指定 host 和 privs
主库上建复制用户，不能只写 host: localhost —— 从库连接主库走的是网络 IP，localhost 不匹配。常见错误是脚本里写成：
- mysql_user:
name: repl
password: "{{ repl_password }}"
priv: "*.*:REPLICATION SLAVE"
这默认 host: localhost，导致从库连不上。正确写法是：
- mysql_user:
name: repl
host: "%" # 允许任意IP连接（生产环境应限定为从库IP段）
password: "{{ repl_password }}"
priv: "*.*:REPLICATION SLAVE"
state: present
另外，mysql_user 模块在 MySQL 8.0 默认用 caching_sha2_password 插件，而旧客户端可能不兼容。如果遇到 Authentication plugin 'caching_sha2_password' cannot be loaded，得在 my.cnf.j2 加：
[mysqld] default_authentication_plugin = mysql_native_password
或者用 mysql_query 模块显式修改用户插件。
真正卡住人的地方，往往不是语法错误，而是主库没开 binlog 就去配从库、从库 server-id 和主库重复、或者 CHANGE MASTER TO 语句里 MASTER_LOG_FILE 指向了不存在的 binlog 文件——这些都得靠 mysql_replication 模块或手写 mysql_query 任务来衔接，而不是靠模板一锤定音。
