# MySQL8/9 MGR组复制集群安装自动化全过程-Fgedu
> 本手册为 FGDBA-MySQL8/9 MGR 组复制自动化安装工具的详细使用说明文档，面向 DBA 工程师、运维人员以及数据库架构师，覆盖工具介绍、功能特性、支持环境、使用方法、典型应用场景与操作流程、常见问题与排障指引等内容。
—
## 一、程序介绍
### 1.1 工具概述
FGDBA-MySQL8/9 MGR 组复制自动化安装工具（以下简称”本工具”）是一款由风哥独立设计与研发的、面向企业级 MySQL 高可用架构场景的自动化部署辅助工具。本工具基于 Python 3 开发，借助 Paramiko 库实现远程 SSH 安全登录、文件传输与命令执行，结合 YAML 配置文件驱动整个安装与配置流程，能够在一台控制机上批量、并行地为多台目标 Linux 服务器完成 MySQL 8.X/9.X 二进制版本的安装、初始化、systemd 服务注册以及 MGR（MySQL Group Replication，组复制）集群的全自动搭建。
本工具定位于”一键部署、配置驱动、可观测、可恢复”，旨在将传统 DBA 在多节点 MGR 部署过程中需要手工执行的数十乃至上百条命令、配置文件编辑、插件加载、复制用户授权、Bootstrap 引导、Clone 克隆加入等繁琐步骤，统一收敛为一个可重复执行的命令行操作。这样既能显著降低人为操作失误风险，也能在测试环境、预生产环境、生产环境之间快速复制出标准化的 MySQL MGR 集群，为数据库高可用方案的落地提供可靠保障。
### 1.2 设计目标
本工具在设计之初即围绕以下目标展开：
1. **配置驱动**：所有可变参数（SSH 凭证、安装目录、数据目录、端口、MGR 组名、复制用户、内核参数、LVM 配置、测试库等）集中在 `配置文件` 文件中，便于版本管理、模板化复用与审计追溯。
2. **并行高效**：阶段一（独立 MySQL 安装）采用多线程并行方式在多台主机上同时执行，避免串行等待；阶段二（MGR 配置）严格遵循集群引导与 Clone 加入顺序，确保数据一致性。
3. **流程完整**：覆盖从前置条件检查、系统环境优化、依赖包安装、LVM 卷管理、二进制解压、数据库初始化、配置文件生成、systemd 注册、root 密码设置，到 MGR 插件加载、复制用户授权、Bootstrap 引导、Clone 克隆、健康检查视图创建、测试库与数据同步验证、安装报告生成的完整链路。
4. **健壮可恢复**：对每条远程命令提供三次重试机制；对已存在的 MySQL 安装提供检测、确认与受控清理；对 LVM 挂载点、安装包、错误日志等关键资源在清理时予以保留，避免误删数据；并支持在线扩容与故障节点重加入。
5. **可观测**：通过控制台实时日志输出、文件日志归档（`logs/` 目录）以及安装报告（`install_report_*.txt`）三重方式记录安装全过程，便于事后审计与问题定位。
6. **安全可控**：默认禁用防火墙与 SELinux 以简化安装；提供 `–verify-only` 仅验证模式；对涉及清理与覆盖安装的关键节点提供交互式确认。
### 1.3 工具定位与适用人群
本工具适用于以下场景与人群：
– 需要快速搭建 MySQL 8.X/9.X MGR 单主模式集群进行功能验证、性能测试的 DBA 与研发工程师；
– 需要在 RHEL9 / OEL9 / Kylin 系列 Linux 上标准化部署多节点 MySQL 高可用架构的运维团队；
– 需要在多套环境（开发、测试、预生产、生产）之间复用同一套部署模板的数据库架构师；
– 对 MySQL MGR 组复制原理有一定了解，希望减少手工部署工作量、提升部署一致性的技术人员。
### 1.4 作者信息
作者：风哥
官方网站 http://www.fgedu.net.cn， http://www.itpux.com
数据库教程 https://edu.51cto.com/lecturer/8020378.html
mysql MGR组复制集群一键安装教程 https://edu.51cto.com/course/40555.html
### 1.5 工具组成
本工具以一个目录的形式分发，典型目录结构如下：
“`
FGMySQLAutoInstall_MGR1.2/
├── FGMySQLAutoInstall_MGR.py # 主脚本，包含全部安装与配置逻辑
├── 配置文件 # 配置文件，所有可变参数集中维护
├── requirements.txt # Python 依赖清单
├── python-pkgs/ # 离线 Python 扩展包目录（.whl 与 .tar.gz）
│ ├── bcrypt-*.whl
│ ├── cffi-*.whl
│ ├── cryptography-*.whl
│ ├── invoke-*.whl
│ ├── paramiko-*.whl
│ ├── pycparser-*.whl
│ ├── pynacl-*.whl
│ ├── pip-*.tar.gz
│ ├── setuptools-*.tar.gz
│ └── typing_extensions-*.whl
├── docs/ # 文档目录
│ ├── README.md
│ ├── INSTALL.md
│ └── README2.md # 本说明手册
├── logs/ # 运行时自动生成，存放日志文件
└── install_report_*.txt # 运行时自动生成，存放安装报告
“`
—
## 二、功能特性
### 2.1 核心功能总览
本工具围绕 MySQL 8.X/9.X MGR 单主模式集群的”从零到可用”全流程，提供以下核心能力：
1. **配置驱动部署**：所有参数集中在 `配置文件`，命令行仅传入 IP、SSH 凭证等动态参数，便于模板化。
2. **多节点并行安装**：阶段一在多台主机上同时执行独立 MySQL 安装，显著缩短整体部署耗时。
3. **一键式端到端流程**：从环境检查到集群验证由脚本自动串联，无需人工介入中间步骤。
4. **MGR 单主模式自动搭建**：自动完成插件加载、复制用户创建、Bootstrap 引导、Clone 克隆加入、read_only 设置等。
5. **健康检查视图**：自动创建 `mysql.mgr_check` 视图，一条 SQL 即可查看集群健康状态、主从节点、离线节点、健康判定等。
6. **在线扩容**：通过 `scale_up_mgr_cluster()` 方法支持向既有集群动态加入新节点。
7. **故障自愈支持**：默认配置 `autorejoin_tries=288`，配合 `member_expel_timeout`、`unreachable_majority_timeout` 等参数，实现 24 小时内自动重加入。
8. **完善的日志与报告**：控制台实时输出、文件日志归档、安装报告三重记录，便于审计与排障。
9. **受控清理与覆盖安装**：检测到既有 MySQL 时提供交互式确认，清理时保留 LVM 挂载、安装包、错误日志。
10. **仅验证模式**：通过 `–verify-only` 仅执行前置条件检查，不进行实际安装，适合正式部署前预检。
### 2.2 前置条件检查模块
该模块在正式安装前对目标主机进行系统化体检，避免在不符合条件的主机上继续后续步骤，主要检查项包括：
– 网络连通性验证：通过 `nc` 或 `ping` 探测目标主机 22 端口与主机可达性。
– SSH 访问权限检查：使用配置的 SSH 凭证远程执行测试命令，验证登录与命令执行权限。
– 操作系统版本识别：读取 `/etc/redhat-release` 或 `/etc/os-release`，确认目标系统类型。
– CPU 核心数统计：通过 `nproc` 获取 CPU 核心数，用于后续性能评估。
– 内存容量统计：通过 `free -m` 获取物理内存与 Swap 大小。
– 磁盘空间统计：优先检查 `/mysql` 挂载点可用空间，否则回退到根分区。
– SELinux 状态检查：通过 `getenforce` 获取当前 SELinux 模式。
– 防火墙状态检查：通过 `systemctl is-active firewalld` 获取 firewalld 状态。
– 既有 MySQL 检测：检查 `mysqld` 进程、`mysql.service` 服务、安装目录与数据目录，判断是否存在冲突。
– 资源要求校验：将检查结果汇总并输出通过/失败计数，决定是否继续后续步骤。
### 2.3 系统环境配置模块
该模块负责将目标主机调整到适合 MySQL 运行的系统状态，主要包括：
– **依赖包安装**：自动安装 `libaio`、`numactl`、`perl`、`net-tools`、`wget`、`tar`、`openssh-clients`、`socat`、`openssl` 等运行依赖；如检测到本地光驱挂载，则自动配置本地 yum 仓库进行离线安装。
– **内核参数优化**：根据配置文件中的 `system.kernel` 段，向 `/etc/sysctl.d/mysql.conf` 写入 `fs.file-max`、`net.core.somaxconn`、`net.ipv4.tcp_max_syn_backlog`、`vm.swappiness`、`vm.nr_hugepages`、`vm.hugetlb_shm_group` 等参数，并执行 `sysctl -p` 立即生效。
– **资源限制配置**：向 `/etc/security/limits.d/mysql.conf` 写入 `mysql` 用户的 `nofile`、`nproc` 软硬限制（65535）。
– **防火墙处理**：根据 `system.security.firewall` 配置，默认关闭并禁用 firewalld。
– **SELinux 处理**：根据 `system.security.selinux` 配置，默认执行 `setenforce 0` 并将 `/etc/selinux/config` 中的 `SELINUX` 改为 `disabled`。
– **RemoveIPC 处理**：将 `systemd-logind` 的 `RemoveIPC` 设置为 `no`，避免 IPC 资源被回收影响 MySQL。
– **MySQL 用户与组**：通过 `groupadd` / `useradd` 创建 `mysql` 组与系统账户（shell 为 `/bin/false`）。
– **LVM 逻辑卷管理**：根据 `system.lvm` 列表，依次执行 `pvcreate`、`vgcreate`、`lvcreate`、`mkfs`、`mount`，并更新 `/etc/fstab` 实现开机自动挂载；支持 `skip` 字段跳过指定卷。
– **大页面配置**：读取配置的 `vm.nr_hugepages`，通过 `sysctl -w` 设置大页面数量，并将 `vm.hugetlb_shm_group` 设置为 mysql 组的 GID。
– **环境变量**：向 `/etc/profile.d/mysql.sh` 写入 `PATH`、`MYSQL_HOME`、`LD_LIBRARY_PATH`，使 MySQL 客户端命令全局可用。
### 2.4 MySQL 二进制安装模块
该模块负责将 MySQL 二进制包部署到目标主机，主要能力包括：
– **安装包检测**：在每台主机上依次扫描 `/tmp`、当前目录、`/root` 目录，识别 `.tar.xz` 与 `.tar.gz` 格式的 MySQL 安装包，并通过文件大小（大于 100MB）过滤非目标文件。
– **安装包解压**：根据扩展名选择 `tar -xJf`（xz）或 `tar -xzf`（gzip）解压至 `/mysql/app`；如解压后的目录名与预期不符，自动查找实际解压目录并执行重命名或软链接。
– **目录归属与权限**：将 `install_dir` 目录递归设置属主为 `mysql:mysql`，权限为 755。
– **数据库初始化**：以 `–initialize-insecure` 方式初始化数据目录，启用 `lower-case-table-names=1`，便于跨平台表名一致性。
– **配置文件生成**：根据 `install_mode` 生成单机模式、MR 主从模式或 MGR 模式的 `my.cnf`，自动注入 server-id、端口、目录、GTID、binlog、InnoDB、性能监控等参数；MGR 模式额外注入 `group_replication` 系列参数与 `mysql_clone`、`group_replication` 插件加载配置。
– **systemd 服务**：生成 `/etc/systemd/system/mysql.service`，设置 `Type=simple`、`User=mysql`、`LimitNOFILE=65535`、`TimeoutStartSec=300` 等，并执行 `daemon-reload`。
– **服务启动**：执行 `systemctl enable` 与 `systemctl start`，并通过循环 `systemctl status` 检测服务是否进入 `active (running)` 状态，最长等待约 40 秒。
– **root 密码设置**：先以空密码连接验证初始化成功，再关闭 `super_read_only`，创建 `root@%` 并授权，最后通过 `ALTER USER` 设置 `root@localhost` 密码，并用 `MYSQL_PWD` 方式验证连接。
### 2.5 MGR 组复制配置模块
该模块在阶段一独立安装完成后启动，负责将多个独立 MySQL 实例组装为 MGR 集群，主要步骤包括：
1. **/etc/hosts 配置**：获取每个节点主机名，备份原 `/etc/hosts`，删除旧的同名条目后追加新的 IP-主机名映射，保证节点间互访使用主机名。
2. **MGR 配置文件生成**：为每个节点生成包含 `loose-group_replication_*` 参数的 `my.cnf`，含组名、本地地址、种子地址、自动重加入次数、驱逐超时、流量控制等。
3. **插件加载与校验**：在所有节点检查并安装 `clone` 与 `group_replication` 插件，通过 `SHOW PLUGINS` 与 `INFORMATION_SCHEMA.PLUGINS` 校验状态。
4. **复制用户创建**：在所有节点为 `mgr_repl` 用户在 `%`、`127.0.0.1`、`localhost` 三种主机维度创建账户，并授予 `replication slave`、`replication client`、`connection_admin`、`backup_admin`、`group_replication_stream` 权限。
5. **节点重启**：重启所有节点 MySQL 服务以加载新的 MGR 配置参数。
6. **Bootstrap 引导**：在第一个节点依次执行 `SET GLOBAL group_replication_bootstrap_group=ON`、`START GROUP_REPLICATION`、`SET GLOBAL group_replication_bootstrap_group=OFF`，完成集群引导。
7. **复制源配置**：在主库执行 `CHANGE REPLICATION SOURCE TO … FOR CHANNEL ‘group_replication_recovery’`，为后续 Clone 恢复准备凭证。
8. **Clone 克隆加入**：其余节点依次设置 `super_read_only=OFF`、`clone_valid_donor_list`，并执行 `CLONE INSTANCE FROM ‘root’@’donor’:3306 IDENTIFIED BY …`；克隆完成后 MySQL 会自动关闭，脚本检测错误日志确认克隆成功，再启动 MySQL 并设置 `super_read_only=ON`，最后执行 `START GROUP_REPLICATION` 加入集群。
9. **健康检查视图**：在主库创建 `mysql.mgr_check` 视图，集成主节点、从节点、离线节点、节点计数、单主模式、健康判定等 12 个字段。
10. **集群状态验证**：通过 `SELECT * FROM mysql.mgr_check;` 输出集群最终健康状态。
### 2.6 测试与验证模块
– **测试库创建**：根据 `test` 配置段在主库创建 `fgedudb` 数据库、`fgtest_table` 表，并插入预设测试数据。
– **数据同步验证**：等待 15 秒后查询主库与所有从库的记录数，比对一致性；对 MGR 单主模式下从节点的复制延迟给出正常性说明。
– **集群信息汇总**：输出组名、集群成员、复制模式、GTID 模式、测试库信息、常用 MGR 检查命令、扩容方式、故障恢复 SQL 等运维提示。
### 2.7 健康检查与扩容模块
– **健康检查方法**：`health_check_mgr_cluster(detailed=False)` 优先查询 `mysql.mgr_check` 视图；若视图不存在则回退到原始 SQL 拼接查询，返回包含 `healthy`、`primary_node`、`secondary_nodes`、`offline_nodes`、`issues`、`warnings` 等字段的字典。
– **在线扩容方法**：`scale_up_mgr_cluster(new_hosts)` 对新节点执行阶段一独立安装、重新生成所有节点 MGR 配置、重启现有节点加载新配置、新节点执行 `RESET MASTER; START GROUP_REPLICATION;` 加入集群，最后调用健康检查方法验证。
– **故障自愈参数**：默认 `autorejoin_tries=288`（5 分钟一次，24 小时内持续尝试）、`member_expel_timeout=5`、`unreachable_majority_timeout=30`，支持节点短暂故障后自动恢复。
### 2.8 报告与日志模块
– **控制台日志**：通过 `logging.StreamHandler()` 实时输出 INFO/WARNING/ERROR 级别日志，便于观察进度。
– **文件日志**：通过 `logging.FileHandler()` 写入 `logs/mysql_mgr_install_YYYYMMDD_HHMMSS.log`，关闭 paramiko 子库的调试日志以减少噪声。
– **安装报告**：`generate_install_report(success)` 生成 `install_report_YYYYMMDD_HHMMSS.txt`，记录开始/结束时间、耗时、模式、状态、节点列表、关键配置参数与最近 20 条报告条目。
– **进度回调**：`ProgressCallback` 类在文件传输过程中按 10% 步进输出进度。
—
## 三、支持环境
### 3.1 控制机环境要求
控制机是执行本工具脚本的机器，需要满足以下条件：
| 项目 | 要求 | 说明 |
|——|——|——|
| 操作系统 | Linux（推荐 RHEL 8+/OEL 8+/CentOS 7+） | 需支持 Python 3 与 SSH 客户端 |
| Python 版本 | Python 3.6 及以上（推荐 3.9） | 脚本使用 typing、f-string 等新特性 |
| pip 版本 | pip 19 及以上 | 用于安装依赖 |
| 必需依赖 | pyyaml、paramiko | 通过 requirements.txt 或离线包安装 |
| 间接依赖 | bcrypt、cryptography、pynacl、cffi、pycparser、invoke、typing_extensions | paramiko 的传递依赖 |
| 网络要求 | 能 SSH 到所有目标服务器 22 端口 | 不要求控制机能访问公网（离线模式可用） |
| 权限要求 | 在控制机具备执行 python3 与读写配置文件的权限 | 无需 root |
| 磁盘空间 | 至少 2GB 可用 | 用于存放 MySQL 安制包与日志 |
### 3.2 目标服务器环境要求
目标服务器是实际承载 MySQL MGR 节点的机器，要求如下：
| 项目 | 要求 | 推荐配置 |
|——|——|———|
| 操作系统 | RHEL 9 / OEL 9 / Kylin V10 系列 | 同上 |
| 系统位数 | x86_64 | 与 MySQL 二进制包匹配 |
| CPU | 至少 4 核 | 8 核及以上 |
| 内存 | 至少 8GB | 16GB 及以上（InnoDB 缓冲池建议物理内存 50-70%） |
| Swap | 至少 2GB | 建议与内存相当或 4GB |
| 磁盘 | 至少 100GB 可用 | 200GB 及以上，建议独立数据盘与日志盘 |
| 网络 | 所有节点之间网络互通，延迟低 | 千兆及以上内网 |
| 端口 | 22（SSH）、3306（MySQL）、33006（MGR 通信） | 三类端口均需开放 |
| 权限 | 提供 root 用户 SSH 登录 | 或具备 sudo 权限的账户 |
| SELinux | 建议禁用 | 安装过程会自动处理 |
| 防火墙 | 安装过程可禁用，生产环境建议配置规则 | 仅放行必要端口 |
| LVM | 推荐为 `/mysql` 与 `/backup` 配置独立逻辑卷 | 便于后续扩容与备份 |
| 大页面 | 建议配置 1024 个 2MB 大页 | 与 `innodb_buffer_pool_size` 配合 |
| 依赖包 | libaio、numactl、perl、net-tools、wget、tar、openssh-clients、socat、openssl | 安装脚本会自动处理 |
### 3.3 MySQL 与插件版本要求
| 组件 | 版本 | 说明 |
|——|——|——|
| MySQL Server | 9.7.0 | 通过官方二进制包安装 |
| Group Replication 插件 | 随 MySQL 8.X/9.X 提供 | 通过 `group_replication.so` 加载 |
| Clone 插件 | 随 MySQL 8.X/9.X 提供 | 通过 `mysql_clone.so` 加载 |
| GTID 模式 | ON | MGR 强制要求 |
| 复制模式 | 单主模式（single-primary） | 本工具默认 |
| binlog 格式 | ROW | MGR 强制要求 |
### 3.4 Python 依赖清单
`requirements.txt` 中声明的依赖如下：
| 包名 | 最低版本 | 用途 |
|——|———|——|
| pyyaml | 6.0 | YAML 配置文件解析 |
| paramiko | 4.0 | SSH 连接、SFTP 文件传输、远程命令执行 |
| bcrypt | 5.0 | SSH 密钥派生 |
| cryptography | 47.0 | 加密算法支持 |
| pynacl | 1.6 | NaCl 加密绑定 |
| cffi | 2.0 | CFFI 绑定 |
| pycparser | 2.23 | C 语言解析器（cffi 依赖） |
| invoke | 3.0 | 命令执行辅助 |
| typing_extensions | 4.0 | 类型扩展 |
—
## 四、程序使用
### 4.1 命令行总览
本工具通过命令行方式调用，基本语法如下：
“`
python3 FGMySQLAutoInstall_MGR.py -mgr <ip1,ip2,ip3,…> -u <username> -p <password> [可选参数]
“`
### 4.2 参数详解
#### 必选参数
| 参数 | 简写 | 说明 | 示例 |
|——|——|——|——|
| –mgr-hosts | -mgr | MGR 集群服务器 IP 列表，逗号分隔，至少 3 台 | 192.168.1.52,192.168.1.53,192.168.1.54 |
| –username | -u | SSH 登录用户名，需具备 root 权限 | root |
| –password | -p | SSH 登录密码 | rootroot |
#### 可选参数
| 参数 | 简写 | 说明 | 默认值 |
|——|——|——|——–|
| –port | -P | SSH 端口 | 22 |
| –verify-only | 无 | 仅执行前置条件检查，不进行实际安装 | 未启用 |
| –config | -c | 配置文件路径 | 配置文件 |
#### 参数使用要点
– **-mgr**：IP 数量必须不少于 3；如需 1 主 1 从等小型拓扑，建议仍提供 3 节点以满足多数派要求；多个 IP 之间使用英文逗号分隔，不要加空格。
– **-u / -p**：SSH 凭据可为 root，也可为具备免密 sudo 的普通用户（推荐生产环境使用密钥替代密码登录）。
– **-P**：当目标 SSH 服务监听非 22 端口时使用，例如 `-P 2222`。
– **–verify-only**：用于正式部署前的环境体检，输出每台主机的网络、SSH、系统、资源、既有 MySQL 等检查结果。
– **-c**：可指定不同环境的配置文件，例如开发、测试、生产分别使用 `dev.yaml`、`test.yaml`、`prod.yaml`。
### 4.3 配置文件结构
`配置文件` 包含以下主要段落：
– **ssh**：SSH 用户名、密码、端口、超时、重试次数。
– **mysql**：安装目录、数据目录、日志目录、端口、root 密码、版本、my.cnf 自定义参数（含 `client`、`mysql`、`mysqldump` 子段）。
– **mgr**：组名、本地通信端口、节点权重、退出动作、流量控制、自动重加入次数、驱逐超时、不可达多数派超时、消息大小、复制用户与密码、是否开机启动、是否引导。
– **system**：依赖包列表、内核参数、安全设置（防火墙、SELinux、NUMA、透明大页、IO 调度）、LVM 卷列表。
– **test**：测试库、测试用户、测试表与测试数据。
### 4.4 安装前准备清单
正式执行安装前，请确认以下事项：
– [ ] 控制机已安装 Python 3.6 及以上版本；
– [ ] 控制机已通过 `pip3 install -r requirements.txt` 或离线包方式安装依赖；
– [ ] 已编辑 `配置文件`，调整安装目录、root 密码、复制密码、SSH 凭据等；
– [ ] 已在控制机 `/tmp` 或脚本当前目录准备 MySQL 8.X/9.X 二进制包（`.tar.xz` 或 `.tar.gz`）；
– [ ] 所有目标服务器已开机且网络互通；
– [ ] 所有目标服务器具备 root SSH 登录权限；
– [ ] 所有目标服务器 22、3306、33006 端口未被占用且可互通；
– [ ] 所有目标服务器磁盘空间充足（至少 100GB 可用）；
– [ ] 已通过 `–verify-only` 完成环境预检。
### 4.5 典型执行流程
“`
1. cd 进入工具根目录
2. 编辑 配置文件
3. 准备 MySQL 二进制包到 /tmp 或脚本目录
4. （可选）python3 FGMySQLAutoInstall_MGR.py -mgr <IPs> -u root -p <pwd> –verify-only
5. python3 FGMySQLAutoInstall_MGR.py -mgr <IPs> -u root -p <pwd>
6. 观察 logs/ 与 install_report_*.txt
7. 在主库执行 SELECT * FROM mysql.mgr_check; 验证
“`
### 4.6 安装完成后的常用运维命令
| 用途 | SQL |
|——|—–|
| 查看集群健康状态（推荐） | `SELECT * FROM mysql.mgr_check;` |
| 查看集群成员 | `SELECT MEMBER_HOST, MEMBER_STATE, MEMBER_ROLE FROM performance_schema.replication_group_members;` |
| 查看 MGR 参数 | `SHOW GLOBAL VARIABLES LIKE ‘group_replication_%’;` |
| 查看 MGR 状态 | `SHOW STATUS LIKE ‘group_replication_%’;` |
| 启动 MGR | `START GROUP_REPLICATION;` |
| 停止 MGR | `STOP GROUP_REPLICATION;` |
| 查看自动重加入配置 | `SHOW GLOBAL VARIABLES LIKE ‘group_replication_autorejoin%’;` |
| 查看 GTID 执行情况 | `SELECT @@GLOBAL.gtid_executed;` |
—
## 五、程序各种案例场景与操作过程
### 5.1 案例 1：MySQL 标准 3 节点 MGR 集群安装
**场景描述**：在 3 台全新 RHEL 9 服务器上部署一个 1 主 2 从的 MySQL 8.X/9.X MGR 集群。
**主机规划**：
| 角色 | IP | 主机名 | 端口 |
|——|—–|——–|——|
| 主节点（PRIMARY） | 192.168.1.52 | fgedudb52 | 3306 / 33006 |
| 从节点 1（SECONDARY） | 192.168.1.53 | fgedudb53 | 3306 / 33006 |
| 从节点 2（SECONDARY） | 192.168.1.54 | fgedudb54 | 3306 / 33006 |
**操作步骤**：
1. 在控制机准备环境：
“`bash
cd /fgedu/fgedudb/mysql/FGMySQLAutoInstall_MGR1.2
pip3 install -r requirements.txt # 或离线安装
vi 配置文件 # 调整密码、目录等
# 上传 mysql-9.7.0-linux-glibc2.28-x86_64.tar.xz 到 /tmp 或当前目录
“`
2. 执行环境预检：
“`bash
python3 FGMySQLAutoInstall_MGR.py \
-mgr 192.168.1.52,192.168.1.53,192.168.1.54 \
-u root -p rootroot –verify-only
“`
3. 执行正式安装：
“`bash
python3 FGMySQLAutoInstall_MGR.py \
-mgr 192.168.1.52,192.168.1.53,192.168.1.54 \
-u root -p rootroot
“`
4. 安装完成后验证：
“`bash
mysql -h 192.168.1.52 -u root -p -e “SELECT * FROM mysql.mgr_check;”
mysql -h 192.168.1.52 -u root -p -e “SELECT MEMBER_HOST, MEMBER_STATE, MEMBER_ROLE FROM performance_schema.replication_group_members;”
“`
**预期结果**：
– 三台主机 MySQL 服务均为 `active (running)`；
– `mysql.mgr_check` 中 `health_status` 为 `HEALTHY`；
– 主库 192.168.1.52 角色 PRIMARY，其余为 SECONDARY 且 ONLINE；
– 在主库插入数据，所有从库均可读到。
### 5.2 案例 2：MySQL大规模 5 节点 MGR 集群安装
**场景描述**：业务量较大，需要 1 主 4 从的 5 节点集群以提升读扩展与可用性。
**操作命令**：
“`bash
python3 FGMySQLAutoInstall_MGR.py \
-mgr 192.168.1.52,192.168.1.53,192.168.1.54,192.168.1.55,192.168.1.56 \
-u root -p rootroot
“`
**要点提示**：
– 5 节点集群可容忍 2 节点故障，仍保持多数派；
– 建议主节点 `member_weight` 设置较高值（如 100），保证优先当选主；
– 节点越多，Clone 克隆加入耗时越长，请预留充足时间；
– 建议为每个节点的 `/mysql` 与 `/backup` 配置独立 LVM 卷，便于后续扩容。
### 5.3 案例 3：MySQL指定非默认 SSH 端口安装
**场景描述**：出于安全考虑，目标服务器 SSH 监听 2222 端口。
**操作命令**：
“`bash
python3 FGMySQLAutoInstall_MGR.py \
-mgr 192.168.1.52,192.168.1.53,192.168.1.54 \
-u root -p rootroot -P 2222
“`
**要点提示**：脚本通过 `paramiko.SSHClient.connect(port=…)` 使用指定端口连接，无需额外修改 SSH 客户端配置。
### 5.4 案例 4：仅验证环境不安装
**场景描述**：正式部署前先体检目标环境，避免不符合要求时浪费安装时间。
**操作命令**：
“`bash
python3 FGMySQLAutoInstall_MGR.py \
-mgr 192.168.1.52,192.168.1.53,192.168.1.54 \
-u root -p rootroot –verify-only
“`
**预期输出**：每台主机依次输出网络、SSH、系统、CPU、内存、磁盘、Swap、SELinux、防火墙、MySQL 状态等检查项，最后汇总通过/失败计数。如有失败项，请按提示修复后再正式安装。
### 5.5 案例 5：使用自定义配置文件
**场景描述**：开发、测试、生产分别使用不同配置文件，便于参数隔离。
**操作命令**：
“`bash
python3 FGMySQLAutoInstall_MGR.py \
-mgr 192.168.1.52,192.168.1.53,192.168.1.54 \
-u root -p rootroot \
-c /etc/mysql-mgr/prod.yaml
“`
**要点提示**：脚本会将命令行传入的 SSH 用户名、密码、端口回写到指定的配置文件中，便于后续追溯；如不希望修改原配置，请提前备份。
### 5.6 案例 6：MySQL在线扩容既有集群
**场景描述**：现有 3 节点集群负载过高，需加入 2 个新节点。
**操作方式（Python API）**：
“`python
from FGMySQLAutoInstall_MGR import MySQLMGRInstall
installer = MySQLMGRInstall(config_path=’配置文件’)
installer.mgr_hosts = [‘192.168.1.52’, ‘192.168.1.53’, ‘192.168.1.54’]
installer.install_mode = ‘mgr’
installer.load_config()
installer.scale_up_mgr_cluster([‘192.168.1.55’, ‘192.168.1.56’])
“`
**操作方式（手动 SQL）**：
“`sql
— 在新节点完成独立安装后执行：
SET GLOBAL super_read_only=OFF;
SET GLOBAL clone_valid_donor_list=’192.168.1.52:3306′;
CLONE INSTANCE FROM ‘root’@’192.168.1.52’:3306 IDENTIFIED BY ‘fgedu123’;
— 等待 MySQL 自动重启
SET GLOBAL super_read_only=ON;
START GROUP_REPLICATION;
SELECT * FROM mysql.mgr_check;
“`
### 5.7 案例 7：MySQL故障节点手动恢复
**场景描述**：某从节点因网络抖动被驱逐出集群，自动重加入失败。
**操作步骤**：
“`sql
— 1. 在故障节点查看状态
SHOW STATUS LIKE ‘group_replication%’;
— 2. 停止并重新启动 MGR
STOP GROUP_REPLICATION;
START GROUP_REPLICATION;
— 3. 验证
SELECT * FROM mysql.mgr_check;
“`
### 5.8 案例 8：MySQL全集群离线后的强制重建
**场景描述**：所有节点同时离线，需要从数据最新的节点重新引导集群。
**操作步骤**：
“`sql
— 1. 在数据最新的节点执行 bootstrap
SET GLOBAL group_replication_bootstrap_group=ON;
START GROUP_REPLICATION;
SET GLOBAL group_replication_bootstrap_group=OFF;
— 2. 在其他节点依次启动 MGR
START GROUP_REPLICATION;
— 3. 验证
SELECT * FROM mysql.mgr_check;
“`
### 5.9 案例 9：MySQL数据同步验证
**操作步骤**：
“`bash
# 在主库插入数据
mysql -h 192.168.1.52 -u root -p -e \
“INSERT INTO fgedudb.fgtest_table (name, value) VALUES (‘sync_test’, 999);”
# 在所有从库验证
for host in 192.168.1.53 192.168.1.54; do
echo “=== $host ===”
mysql -h $host -u root -p -e \
“SELECT * FROM fgedudb.fgtest_table WHERE name=’sync_test’;”
done
“`
### 5.10 案例 10：清理既有 MySQL 后重新安装
**场景描述**：目标主机上已有旧版 MySQL 或残留数据，需要重新安装。
**操作步骤**：
1. 直接执行安装命令；
2. 脚本检测到既有 MySQL 后会提示是否继续；
3. 输入 `y` 确认后，脚本自动停止服务、清理 systemd、删除程序目录与数据目录、保留 LVM 挂载点、`/tmp` 安装包与 `.err` 错误日志；
4. 完成清理后继续执行全新安装。
—
## 六、常用问题与排查
### 6.1 网络与 SSH 类问题
**问题 1：无法 SSH 连接目标服务器**
排查步骤：
“`bash
ping <目标IP> # 检查网络可达
ssh -v root@<目标IP> # 查看 SSH 详细握手过程
systemctl status sshd # 在目标机检查 sshd 服务
firewall-cmd –list-all # 检查防火墙规则
getenforce # 检查 SELinux
“`
常见原因：网络不通、防火墙拦截 22 端口、sshd 未启动、SELinux 拦截、密码错误、密钥指纹未接受（脚本通过 `AutoAddPolicy` 自动接受）。
**问题 2：SSH 端口被修改**
排查步骤：通过 `ssh -p 2222 root@<IP>` 验证；脚本通过 `-P` 参数指定端口。
### 6.2 安装包与依赖类问题
**问题 3：未找到 MySQL 安装包**
排查步骤：
“`bash
ls -lh /tmp/mysql-9*.tar.* # 检查 /tmp
ls -lh /root/mysql-9*.tar.* # 检查 /root
ls -lh ./mysql-9*.tar.* # 检查脚本当前目录
“`
常见原因：安装包未上传、文件名不包含 `mysql` 关键字、文件大小小于 100MB（被脚本过滤）、格式非 `.tar.xz` / `.tar.gz`。
**问题 4：依赖包安装失败（yum/dnf 报错）**
排查步骤：
“`bash
yum repolist # 检查 yum 源
mount /dev/cdrom /mnt # 检查本地光驱
ls /etc/yum.repos.d/ # 检查仓库配置
“`
脚本会自动尝试挂载本地光驱并配置 `fgedudb.repo`；如仍失败，请配置可用的 yum 源后重试。
**问题 5：Python 依赖（paramiko 等）安装失败**
排查步骤：
“`bash
python3 -c “import paramiko; print(paramiko.__version__)”
pip3 install –no-index –find-links=python-pkgs pyyaml paramiko
“`
如离线安装仍失败，请检查 `python-pkgs/` 中是否缺少 `bcrypt`、`cryptography`、`pynacl`、`cffi`、`pycparser`、`invoke`、`typing_extensions` 等传递依赖。
### 6.3 系统配置类问题
**问题 6：SELinux 无法禁用**
排查步骤：
“`bash
getenforce # 查看当前模式
cat /etc/selinux/config | grep SELINUX= # 查看配置
setenforce 0 # 临时禁用
“`
如需重启后永久禁用，请确认 `/etc/selinux/config` 中 `SELINUX=disabled`。
**问题 7：防火墙未关闭导致端口不通**
排查步骤：
“`bash
systemctl is-active firewalld
firewall-cmd –list-ports
firewall-cmd –add-port=3306/tcp –permanent
firewall-cmd –add-port=33006/tcp –permanent
firewall-cmd –reload
“`
**问题 8：LVM 创建失败**
排查步骤：
“`bash
ls /dev/sd* # 检查物理设备
pvdisplay
vgdisplay
lvdisplay
“`
常见原因：`pv_devices` 设备不存在、设备已被其他 VG 占用、`size` 设置过大、文件系统已格式化但未挂载。
### 6.4 MySQL 安装与启动类问题
**问题 9：MySQL 服务启动失败**
排查步骤：
“`bash
systemctl status mysql.service -l
tail -100 /mysql/log/3306/fgedudb-error.err
ls -la /mysql/data/3306/data/
ls -la /mysql/data/3306/my.cnf
“`
常见原因：`my.cnf` 配置错误、数据目录权限不对（应为 `mysql:mysql`）、端口被占用、`innodb_buffer_pool_size` 超过物理内存、大页面配置不足。
**问题 10：root 密码设置失败**
排查步骤：
“`bash
/mysql/app/mysql/bin/mysql -u root -e “SELECT 1;” # 验证空密码登录
tail -50 /mysql/log/3306/fgedudb-error.err
“`
常见原因：`–initialize-insecure` 未成功、`super_read_only` 未关闭、`ALTER USER` 语法错误。
### 6.5 MGR 集群类问题
**问题 11：MGR 集群无法启动**
排查步骤：
“`bash
mysql -u root -p -e “SHOW STATUS LIKE ‘group_replication_primary_member’;”
tail -100 /mysql/log/3306/fgedudb-error.err | grep -i “group_replication”
# 在所有节点之间测试 33006 端口连通性
for h in 192.168.1.52 192.168.1.53 192.168.1.54; do
timeout 2 bash -c “</dev/tcp/$h/33006” && echo “$h:33006 OK” || echo “$h:33006 FAIL”
done
“`
常见原因：`group_name` 各节点不一致、`local_address` 端口不通、`server-id` 重复、GTID 未启用、`group_replication_group_seeds` 列表不完整。
**问题 12：节点 Clone 克隆失败**
排查步骤：
“`bash
# 在被克隆节点检查 3306 端口
timeout 2 bash -c “</dev/tcp/192.168.1.52/3306” && echo OK || echo FAIL
# 验证 donor 凭证
mysql -h 192.168.1.52 -u root -p -e “SELECT 1;”
# 检查 clone 状态
mysql -u root -p -e “SELECT * FROM performance_schema.clone_status;”
tail -100 /mysql/log/3306/fgedudb-error.err | grep -i clone
“`
常见原因：donor 端口不通、`clone_valid_donor_list` 未设置、root 密码不正确、donor 节点 `super_read_only` 未关闭、`mysqld` 自启动后未完全就绪即执行 Clone。
**问题 13：节点无法自动重加入**
排查步骤：
“`sql
SHOW GLOBAL VARIABLES LIKE ‘group_replication_autorejoin_tries’;
SHOW STATUS LIKE ‘group_replication_autorejoin%’;
STOP GROUP_REPLICATION;
START GROUP_REPLICATION;
“`
如自动重加入彻底失败，可手动 `STOP` 后 `START`；如仍失败，参考案例 8 进行强制 bootstrap。
### 6.6 数据同步类问题
**问题 14：从节点数据不同步**
排查步骤：
“`sql
— 在主库
SHOW MASTER STATUS;
SELECT @@GLOBAL.gtid_executed;
— 在从库
SHOW REPLICA STATUS\G
SELECT * FROM performance_schema.replication_applier_status_by_worker;
SELECT MEMBER_STATE FROM performance_schema.replication_group_members WHERE MEMBER_HOST='<从节点>’;
“`
MGR 单主模式下，从节点复制有秒级延迟属正常现象；如长时间不同步，请检查 `applier` 错误与网络延迟。
### 6.7 资源与性能类问题
**问题 15：磁盘空间不足**
排查步骤：
“`bash
df -h
du -sh /mysql/*
find / -type f -size +1G 2>/dev/null
“`
建议清理 binlog、慢查询日志、通用日志，并按保留策略定期清理。
**问题 16：内存不足导致 OOM**
排查步骤：
“`bash
free -m
dmesg | grep -i “out of memory”
cat /proc/<mysqld_pid>/status | grep -i vm
“`
建议调整 `innodb_buffer_pool_size` 至物理内存 50-70%，并配置大页面与 Swap。
### 6.8 日志与报告类问题
**问题 17：找不到安装日志或报告**
排查步骤：
“`bash
ls -lh logs/
ls -lh install_report_*.txt
“`
日志默认写入工具根目录的 `logs/` 与 `install_report_*.txt`；如执行时切换了工作目录，请到对应目录查找。
### 6.9 排查通用方法
1. 先看控制台 ERROR/WARNING 提示；
2. 再看 `logs/mysql_mgr_install_*.log` 完整日志；
3. 在目标主机查看 `/mysql/log/3306/fgedudb-error.err`；
4. 使用 `–verify-only` 重新体检环境；
5. 对单台主机单独排查（可临时在 `配置文件` 中只保留一个 IP）；
6. 必要时联系作者：风哥（QQ 113257174，微信 itpux-com）。
—
## 七、附录
### 7.1 安装流程阶段速查
| 阶段 | 主要动作 | 关键产物 |
|——|———-|———-|
| 0 | 配置 /etc/hosts | 节点互访基础 |
| 1 | 前置条件检查 | 检查报告 |
| 2 | 检查 MySQL 安装包 | 安装包路径与大小 |
| 3 | 检查既有 MySQL 并清理 | 干净环境 |
| 4 | 阶段一并行安装独立 MySQL | 各节点 mysqld 服务 |
| 5 | 阶段二配置 MGR | mgr_check 视图 |
| 6 | 创建测试数据库 | fgedudb.fgtest_table |
| 7 | 验证集群状态 | health_status=HEALTHY |
| 8 | 生成安装报告 | install_report_*.txt |
### 7.2 关键配置参数速查
| 参数 | 默认值 | 说明 |
|——|——–|——|
| mysql.install_dir | /mysql/app/mysql | 安装目录 |
| mysql.data_dir | /mysql/data/3306/data | 数据目录 |
| mysql.log_dir | /mysql/log/3306 | 日志目录 |
| mysql.port | 3306 | MySQL 端口 |
| mysql.root_password | fgedu123 | root 密码（生产请改） |
| mgr.group_name | aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa1 | MGR 组名 |
| mgr.local_address_port | 33006 | MGR 通信端口 |
| mgr.autorejoin_tries | 288 | 自动重加入次数 |
| mgr.member_expel_timeout | 5 | 驱逐超时（秒） |
| mgr.unreachable_majority_timeout | 30 | 多数派不可达超时 |
| ssh.username / password | root / rootroot | SSH 凭据（生产请改） |
### 7.3 健康检查视图字段速查
| 字段 | 含义 | 健康标准 |
|——|——|———-|
| primary_node | 主节点 | 非空 |
| secondary_nodes | 在线从节点列表 | 与规划一致 |
| offline_nodes | 离线节点列表 | 为空 |
| total_nodes / online_nodes | 总数 / 在线数 | 相等 |
| primary_count | 主节点数量 | 1 |
| single_primary_mode | 单主模式 | ON |
| health_status | 健康判定 | HEALTHY |
### 7.4 文档信息
作者：风哥
官方网站 http://www.fgedu.net.cn， http://www.itpux.com
数据库教程 https://edu.51cto.com/lecturer/8020378.html
mysql MGR组复制集群一键安装教程 https://edu.51cto.com/course/40555.html
本文由风哥教程整理发布,仅用于学习测试使用,转载注明出处:http://www.fgedu.net.cn/10327.html
