## 一、程序介绍
### 1.1 工具概述
FGDBA-MySQL8/9主从复制自动化安装工具是一款由风哥自主设计、研发并长期维护的 MySQL数据库主从复制架构自动化部署工具。该工具定位为”配置驱动型一键自动化安装”解决方案，面向 DBA 工程师、数据库运维人员以及需要在 Linux 平台上快速、标准、可重复地搭建 MySQL 8.X/9.X 主从复制环境的各类技术团队。
FGDBA-MySQL8/9主从复制自动化安装工具的核心思想是：将所有可调参数（包括主从 IP、SSH 凭据、MySQL 二进制版本、安装目录、数据目录、日志目录、端口、root 密码、复制账号、内核参数、LVM、防火墙、SELinux、NUMA、透明大页、IO 调度器、my.cnf 全量参数等）全部集中在一个 YAML 配置文件中，通过命令行参数指定主从 IP 列表与 SSH 凭据后，由控制机通过 SSH（基于 paramiko）远程登录各目标服务器，按照”环境检测 -> 系统配置 -> MySQL 安装 -> 主从配置 -> 健康检查”的固定流程自动完成全栈部署，无需人工干预。
该工具采用纯 Python 实现，依赖极少（仅需 pyyaml 与 paramiko），并自带离线安装包目录（`python-pkgs/`），支持在内网无外网的环境下离线部署。其设计目标是在保证生产级稳定性与可回滚性的前提下，将一台或多台全新 Linux 主机在 10~20 分钟内转变为一个具备 GTID、半同步复制、自动故障感知能力的 MySQL 8.X/9.X 主从集群。
### 1.2 作者信息
作者：风哥
官方网站 http://www.fgedu.net.cn， http://www.itpux.com
数据库教程 https://edu.51cto.com/lecturer/8020378.html
mysql主从集群一键安装教程 https://edu.51cto.com/course/40554.html
### 1.3 工具定位
本工具并非一个通用的 MySQL 生命周期管理平台，而是一个聚焦于”从零到一搭建 MySQL 8.X/9.X 主从复制集群”的自动化安装器。其适用场景包括但不限于：
– 新机房、新服务器上架后的 MySQL 标准化初始化部署；
– 开发、测试环境的快速重建与版本升级回归；
– 灾备环境搭建与复制拓扑重建；
– DBA 培训与教学演示；
– 数据库迁移项目的前期环境准备。
工具本身不承担后续的监控、备份、自动故障切换等职责（这部分建议配合 Orchestrator、MHA、ProxySQL 或企业自有平台使用），但其输出的标准化目录结构、统一 my.cnf 模板与清晰的日志，可以很好地与上述平台对接。
### 1.4 技术架构
工具采用”控制机 + 目标服务器”的两层架构：
1. **控制机**：运行FGMYSQL主从复制自动化工具的机器，负责读取 YAML 配置、调度安装流程、通过 paramiko 下发命令与文件、汇总各主机执行结果。控制机本身不需要安装 MySQL，但需要能够 SSH 到所有目标服务器。
2. **目标服务器**：实际承载 MySQL 服务的机器，分为主服务器（Master，可读写）与从服务器（Slave，只读）。控制机会以并行方式在多台目标服务器上同时执行安装，显著缩短整体部署时间。
安装过程中，控制机与目标服务器之间的所有交互均通过 SSH 通道完成（命令执行使用 `exec_command`，文件写入使用 SFTP），不依赖额外的 Agent 或中间件，保证了对目标服务器的零侵入与最小化依赖。
### 1.5 工具文件清单
| 文件/目录 | 用途说明 |
|———–|———-|
|FGMYSQL主从复制自动化工具| 主程序脚本，包含全部安装逻辑 |
| | 全量配置文件，所有可调参数集中在此 |
| `requirements.txt` | Python 依赖清单 |
| `python-pkgs/` | 离线安装包目录，包含 paramiko、cryptography、bcrypt、pynacl、pyyaml 等 wheel 包 |
| `docs/README.md` | 工具使用说明文档 |
| `docs/INSTALL.md` | 逐步安装与依赖配置指南 |
| `logs/` | 程序运行时自动生成的日志目录 |
—
## 二、功能与特性
### 2.1 核心功能
本工具围绕”MySQL 8.X/9.X 主从复制集群一键安装”这一核心目标，提供以下主要功能模块：
#### 2.1.1 配置驱动
– 所有参数集中在 中，使用 YAML 格式，结构清晰、可读性强；
– 命令行参数（`-mr`、`-u`、`-p`、`–port`）会自动回写到配置文件中，保证配置文件与实际执行参数一致；
– 支持通过 `-c/–config` 指定自定义配置文件路径，便于在多套环境（开发/测试/生产）间切换；
– 配置文件中的 `my_cnf`、`my_cnf_master`、`my_cnf_slave` 三段分别管理公共、主库专属、从库专属参数，工具会自动合并生成最终 `my.cnf`。
#### 2.1.2 并行安装
– 使用 Python `threading` 模块，为每台目标服务器创建独立线程并行执行安装；
– 各线程的执行结果通过共享字典与锁（`threading.Lock`）汇总到主线程；
– 任意一台主机安装失败，主流程会立即停止后续主从配置，并对失败主机执行 `cleanup` 回滚，避免遗留半成品环境；
– 并行安装大幅缩短整体部署时间，1 主 2 从的典型安装可在 10~20 分钟内完成。
#### 2.1.3 完整流程覆盖
工具覆盖从裸机到可用集群的全流程，包含以下六大阶段：
1. **阶段 0.5 / 1：检查现有 MySQL 与安装包**——在每台目标主机上搜索 `.tar.xz` 与 `.tar.gz` 格式的 MySQL 二进制包（搜索路径覆盖 `/tmp`、当前目录、`/root`），若发现多版本会交互式让用户选择统一版本；同时检测是否已存在旧版 MySQL 安装，按提示决定是否清理。
2. **阶段 2：并行安装 MySQL**——创建目录、解压二进制包、创建 mysql 用户、初始化数据库（带 `lower_case_table_names=1`）、生成 `my.cnf`、配置 systemd 服务、启动 MySQL、设置 root 密码。
3. **阶段 3：配置主从复制**——创建复制用户、安装半同步复制插件、在从库执行 `CHANGE REPLICATION SOURCE TO` 并启动复制。
4. **阶段 4：创建测试数据库**——在主库创建测试库与测试表并写入测试数据，用于验证复制链路是否正常。
5. **阶段 5：验证复制状态**——在主库执行 `SHOW BINARY LOG STATUS`、在从库执行 `SHOW REPLICA STATUS`，并检查半同步源端/复制端状态变量。
6. **阶段 6：输出安装完成信息**——汇总主从关系、复制模式、测试库信息、常用检查命令、生产环境提醒等。
#### 2.1.4 错误处理与回滚
– SSH 命令执行支持配置重试次数（默认 3 次）与超时（默认 30 秒），应对网络抖动；
– 关键操作失败后会调用 `cleanup(host)` 清理失败主机的残留文件与进程，避免干扰下次安装；
– 安装日志同时输出到控制台与 `logs/mysql_mr_install_YYYYMMDD_HHMMSS.log` 文件，便于事后排查；
– 对 paramiko 的内部调试日志统一降级为 WARNING，避免干扰主流程输出。
#### 2.1.5 半同步复制与 GTID
– 默认启用 GTID 模式（`gtid_mode=ON`、`enforce_gtid_consistency=ON`），保证事务唯一标识与一致性；
– 自动加载 `rpl_semi_sync_source` 与 `rpl_semi_sync_replica` 半同步复制插件，主库使用 `AFTER_SYNC` 等待点，从库启用半同步复制端；
– 主库 `server-id` 固定为 `33061`，从库自 `33062` 起递增，保证集群内唯一；
– 同时加载 `mysql_clone.so` 克隆插件，为后续快速扩从库提供基础。
#### 2.1.6 灵活拓扑
– 支持 1 主 1 从、1 主 2 从、1 主 3 从、1 主 4 从共 4 种拓扑规模；
– 从库数量仅由命令行 `-mr` 参数中 IP 列表的长度决定，无需修改代码；
– 从库 `server-id` 自动递增，无需手动维护。
### 2.2 功能特性详细说明
#### 2.2.1 环境检测模块
– **系统类型识别**：通过 `cat /etc/redhat-release` 等方式识别 RHEL9 / OEL9 / Kylin V10 等目标系统；
– **网络连通性测试**：使用 bash 的 `/dev/tcp` 特性测试目标主机端口可达性，不依赖 `telnet`/`nc`；
– **SSH 连接验证**：基于 paramiko 验证 SSH 用户名、密码、端口是否正确；
– **磁盘空间检查**：检查 MySQL 数据目录、安装目录所在分区的可用空间；
– **依赖包检查**：检查 `libaio`、`numactl`、`perl`、`net-tools`、`wget`、`tar`、`openssh-clients` 等是否已安装；
– **端口可用性检查**：检查 3306 端口是否被占用，避免与既有服务冲突；
– **本地安装包检测**：在控制机本地与目标主机本地搜索 MySQL 二进制包，无需提前上传到远程主机。
#### 2.2.2 系统配置模块
– **YUM 仓库清理**：自动清理冲突的 YUM 仓库配置（保留 `fgedudb.repo`），避免依赖包安装异常；
– **依赖包自动安装**：通过 `yum`/`dnf` 自动安装前述依赖包；
– **内核参数优化**：配置 `fs.file-max`、`net.core.somaxconn`、`net.ipv4.tcp_max_syn_backlog`、`net.ipv4.tcp_fin_timeout`、`vm.swappiness`、`vm.nr_hugepages`、`vm.min_free_kbytes`、`vm.overcommit_memory`、`vm.hugetlb_shm_group` 等关键参数；
– **防火墙关闭**：`systemctl stop firewalld && systemctl disable firewalld`；
– **SELinux 禁用**：`setenforce 0` 并修改 `/etc/selinux/config` 为 `disabled`；
– **透明大页禁用**：关闭 THP，避免 InnoDB 性能抖动；
– **IO 调度器优化**：将磁盘 IO 调度器设置为 `deadline`；
– **NUMA 禁用**：在 systemd 服务或内核启动参数中关闭 NUMA；
– **LVM 自动配置**：支持在指定块设备（如 `/dev/sdc`）上自动创建 PV、VG、LV，格式化为 xfs 并挂载到 `/mysql` 与 `/backup`，通过 `skip` 参数可跳过已配置的主机；
– **大页内存配置**：支持配置 `vm.nr_hugepages` 与 `hugetlb_shm_group`，为 InnoDB 大页内存使用做准备。
#### 2.2.3 MySQL 安装模块
– **二进制包自动检测**：支持 `.tar.xz` 与 `.tar.gz` 两种格式，优先按 `/tmp`、当前目录、`/root` 顺序搜索；
– **多版本选择**：检测到多个 MySQL 二进制包时，交互式让用户选择统一版本，所有主机安装一致版本；
– **解压安装**：解压到 `/mysql/app/mysql`，显示解压进度；
– **数据库初始化**：使用 `mysqld –initialize –lower-case-table-names=1` 初始化数据目录；
– **my.cnf 生成**：从 读取 `my_cnf`、`my_cnf_master`、`my_cnf_slave` 三段配置，自动合并为最终 `my.cnf`，落盘到 `/mysql/data/3306/my.cnf`；
– **systemd 服务**：生成 `/etc/systemd/system/mysql.service`，设置 `LimitNOFILE=65535`、`LimitNPROC=65535`、`TimeoutStartSec=300`；
– **root 密码设置**：启动 MySQL 后通过 `ALTER USER` 设置 root 密码，密码来源于配置文件。
#### 2.2.4 主从配置模块
– **复制用户创建**：在主库执行 `CREATE USER … REPLICATION SLAVE` 与 `GRANT REPLICATION SLAVE ON *.*`；
– **半同步插件安装**：在主库安装 `rpl_semi_sync_source`，在从库安装 `rpl_semi_sync_replica`；
– **克隆插件加载**：加载 `mysql_clone.so`，为后续克隆从库提供基础；
– **复制关系建立**：在从库执行 `CHANGE REPLICATION SOURCE TO … SOURCE_HOST=主库IP, SOURCE_USER=复制用户, SOURCE_PASSWORD=密码, …`，并启用 `GTID_AUTO_POSITION=1`；
– **复制启动与验证**：执行 `START REPLICA`，并检查 `Replica_IO_Running`、`Replica_SQL_Running` 是否为 Yes。
#### 2.2.5 健康检查模块
– **MySQL 服务状态检查**：`systemctl status mysql.service`；
– **MySQL 连接测试**：通过 `mysql -u root -p -e “SELECT VERSION()”` 验证登录；
– **复制状态检查**：主库 `SHOW BINARY LOG STATUS`，从库 `SHOW REPLICA STATUS`；
– **半同步状态验证**：`SHOW GLOBAL VARIABLES LIKE ‘rpl_semi_sync_source_enabled’` 与 `’rpl_semi_sync_replica_enabled’`；
– **数据一致性验证**：在主库创建测试库、测试表并写入数据，在从库查询验证同步结果。
### 2.3 支持环境
#### 2.3.1 控制机环境
| 项目 | 要求 |
|——|——|
| 操作系统 | Linux（推荐 RHEL/CentOS 7+，或与目标服务器同源系统） |
| Python 版本 | 3.6 及以上（RHEL9/OEL9 默认 Python 3.9 即可） |
| 必需依赖 | pyyaml >= 5.0、paramiko >= 2.0（离线包见 `python-pkgs/`） |
| 网络 | 能够 SSH 到所有目标服务器的 22 端口（或自定义端口） |
| 权限 | 具有目标服务器的 root SSH 登录权限 |
| 磁盘 | 至少预留 MySQL 二进制包大小（约 1GB）的临时空间 |
#### 2.3.2 目标服务器环境
| 项目 | 要求 |
|——|——|
| 操作系统 | RHEL9 / OEL9 / Kylin V10 系列 Linux（glibc 2.28+） |
| 内存 | 至少 4GB RAM（生产推荐 8GB+，工具默认 `innodb_buffer_pool_size=2G`） |
| 磁盘 | 至少 50GB 可用空间（数据目录与日志目录分开更佳） |
| 网络 | 所有目标服务器之间网络互通，且 3306 端口未被占用 |
| 权限 | 提供 root 用户 SSH 登录权限（工具会创建 mysql 系统用户） |
| 软件包 | `libaio`、`numactl`、`perl`、`net-tools`、`wget`、`tar`、`openssh-clients`（工具会自动安装） |
#### 2.3.3 软件版本依赖
| 依赖 | 最低版本 | 用途 |
|——|———|——|
| Python | 3.6 | 脚本运行环境 |
| pyyaml | 5.0 | YAML 配置文件解析 |
| paramiko | 2.0 | SSH 连接与文件传输 |
| MySQL 二进制包 | 8.X/9.X.0 | 目标数据库软件 |
| Linux glibc | 2.28 | MySQL 8.X/9.X 二进制包依赖 |
#### 2.3.4 不支持的场景
– 不支持 Windows、macOS 作为目标服务器；
– 不支持 MySQL 5.x、8.0 以下版本的二进制包（仅针对 9.x 设计）；
– 不支持非 root 用户安装（依赖 systemd、LVM、内核参数调整等特权操作）；
– 不支持跨大区、跨公网的高延迟链路作为主从复制通道（建议同机房或同专网）。
—
## 三、程序使用
### 3.1 前置准备
#### 3.1.1 控制机依赖安装
在线安装：
“`bash
pip3 install pyyaml paramiko
“`
离线安装（使用工具自带 `python-pkgs/`）：
“`bash
pip3 install –no-index –find-links=./python-pkgs pyyaml paramiko
“`
验证：
“`bash
python3 -c “import yaml, paramiko; print(‘pyyaml’, yaml.__version__); print(‘paramiko’, paramiko.__version__)”
“`
#### 3.1.2 准备 MySQL 二进制包
将 MySQL 8.X/9.X.0 二进制包放置在控制机的脚本同级目录或 `/tmp` 目录下，文件名形如 `mysql-8.X/9.X.0-linux-glibc2.28-x86_64.tar.xz`。工具会自动搜索 `.tar.xz` 与 `.tar.gz` 两种格式，无需提前上传到目标服务器。
#### 3.1.3 编辑配置文件
编辑 ，重点关注以下字段：
“`yaml
replication:
master_ip: “192.168.1.51” # 主服务器 IP（命令行 -mr 会覆盖）
slave_ips: # 从服务器 IP 列表（命令行 -mr 会覆盖）
– “192.168.1.52”
– “192.168.1.53”
replication_user: “fgedu_repl”
replication_password: “fgedu_repl_123”
mysql:
install_dir: /mysql/app/mysql
data_dir: /mysql/data/3306/data
port: 3306
socket: /tmp/mysql.sock
root_password: “fgedu123”
version: “8.X/9.X.0”
ssh:
username: root
password: “rootroot”
port: 22
timeout: 30
retry_count: 3
“`
其余 `system.kernel`、`system.lvm`、`system.security`、`system.timeout`、`mysql.my_cnf` 等字段可按需调整，未调整则使用工具内置的合理默认值。
### 3.2 命令行参数
| 参数 | 简写 | 是否必填 | 说明 |
|——|——|———-|——|
| `–master-replica` | `-mr` | 是 | 主从服务器 IP 列表，格式：`主IP,从1IP,从2IP,…`，至少 2 个 IP |
| `–username` | `-u` | 是 | SSH 用户名（通常为 root） |
| `–password` | `-p` | 是 | SSH 密码 |
| `–port` | | 否 | SSH 端口，默认 22 |
| `–verify-only` | | 否 | 仅验证环境不安装 |
| `–config` | `-c` | 否 | 配置文件路径，默认 |
查看帮助：
“`bash
python3 FGMySQLAutoInstall_MR.py –help
“`
### 3.3 基本使用
#### 3.3.1 安装 1 主 2 从（最常用）
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52,192.168.1.53 -u root -p rootroot
“`
说明：`192.168.1.51` 为主库（可读写），`192.168.1.52`、`192.168.1.53` 为从库（只读）。
#### 3.3.2 安装 1 主 1 从
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52 -u root -p rootroot
“`
#### 3.3.3 安装 1 主 3 从 / 1 主 4 从
“`bash
# 1 主 3 从
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52,192.168.1.53,192.168.1.54 -u root -p rootroot
# 1 主 4 从
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52,192.168.1.53,192.168.1.54,192.168.1.55 -u root -p rootroot
“`
#### 3.3.4 指定自定义 SSH 端口
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52 -u root -p rootroot –port 2222
“`
#### 3.3.5 仅验证环境不安装
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52,192.168.1.53 -u root -p rootroot –verify-only
“`
#### 3.3.6 使用自定义配置文件
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52 -u root -p rootroot -c /path/to/custom_config.yaml
“`
### 3.4 执行流程说明
执行安装命令后，工具会依次完成以下步骤：
1. 打印工具版本与作者信息；
2. 加载并解析 ，将命令行参数回写配置；
3. 检查各目标主机是否已存在 MySQL 安装，提示用户决定是否清理；
4. 在各目标主机搜索 MySQL 二进制包，多版本时交互选择统一版本；
5. 为每台主机创建独立线程并行执行：系统配置 -> 解压安装 -> 初始化 -> 生成 my.cnf -> 配置 systemd -> 启动 MySQL -> 设置 root 密码；
6. 等待所有线程完成，汇总失败主机并执行回滚；
7. 配置主从复制：创建复制用户、安装半同步插件、从库连接主库、启动复制；
8. 创建测试数据库与测试表，写入测试数据；
9. 验证主从复制状态与半同步状态；
10. 打印安装完成信息、主从关系图、常用检查命令、生产环境提醒。
### 3.5 输出与日志
– **控制台输出**：实时打印进度与状态；
– **日志文件**：`logs/mysql_mr_install_YYYYMMDD_HHMMSS.log`，完整记录所有操作与远程命令输出；
– **完成信息**：包含主从关系树形图、复制模式、测试库信息、常用检查命令。
—
## 四、案例场景与操作过程
### 4.1 场景一：MySQL标准 1 主 2 从生产部署
**背景**：某企业新采购 3 台服务器（192.168.1.51/52/53），需要部署一套 MySQL 8.X/9.X 主从复制集群用于业务系统。
**操作过程**：
1. 在控制机安装依赖：
“`bash
pip3 install –no-index –find-links=./python-pkgs pyyaml paramiko
“`
2. 将 MySQL 8.X/9.X.0 二进制包 `mysql-8.X/9.X.0-linux-glibc2.28-x86_64.tar.xz` 上传到控制机脚本同级目录；
3. 编辑 ，确认 `mysql.root_password`、`replication.replication_user/password` 已改为强密码；
4. 执行安装：
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52,192.168.1.53 -u root -p rootroot
“`
5. 观察输出，确认各阶段全部 SUCCESS；
6. 验证复制状态：
“`bash
# 主库
mysql -h 192.168.1.51 -u root -p -e “SHOW BINARY LOG STATUS;”
mysql -h 192.168.1.51 -u root -p -e “SHOW REPLICAS;”
# 从库
mysql -h 192.168.1.52 -u root -p -e “SHOW REPLICA STATUS\G”
mysql -h 192.168.1.53 -u root -p -e “SHOW REPLICA STATUS\G”
“`
确认 `Replica_IO_Running: Yes`、`Replica_SQL_Running: Yes`、`Seconds_Behind_Source: 0`。
### 4.2 场景二：MySQL 1 主 1 从最小化部署
**背景**：开发测试环境仅需 1 主 1 从即可。
**操作过程**：
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52 -u root -p rootroot
“`
执行过程与场景一一致，区别仅在于从库数量为 1，`server-id` 从 33062 开始。
### 4.3 场景三：MySQL 1 主 3 从高可用扩展
**背景**：业务读写分离需要 1 主 3 从。
**操作过程**：
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52,192.168.1.53,192.168.1.54 -u root -p rootroot
“`
工具会自动为 3 台从库分配 `server-id` 33062/33063/33064，并并行安装。
### 4.4 场景四：MySQL自定义 SSH 端口的安全主机
**背景**：目标服务器 SSH 端口改为 2222，密码登录。
**操作过程**：
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52 -u root -p rootroot –port 2222
“`
`–port` 参数会被回写到 的 `ssh.port` 字段，后续所有 SSH 操作均使用该端口。
### 4.5 场景五：仅验证环境不安装
**背景**：正式安装前先确认环境是否满足要求。
**操作过程**：
“`bash
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52,192.168.1.53 -u root -p rootroot –verify-only
“`
工具会完成配置加载、SSH 连接验证、安装包检测等前置检查，但不执行实际安装，便于提前发现问题。
### 4.6 场景六：使用自定义配置文件
**背景**：同时维护开发、测试、生产三套环境，使用不同配置文件。
**操作过程**：
“`bash
# 开发环境
python3 FGMySQLAutoInstall_MR.py -mr 10.0.0.11,10.0.0.12 -u root -p devpass -c config/dev.yaml
# 生产环境
python3 FGMySQLAutoInstall_MR.py -mr 192.168.1.51,192.168.1.52,192.168.1.53 -u root -p prodpass -c config/prod.yaml
“`
### 4.7 场景七：多版本 MySQL 安装包选择
**背景**：控制机 `/tmp` 目录下同时存在 MySQL 8.X/9.X.0 与另一版本二进制包。
**操作过程**：
执行安装命令后，工具会列出检测到的所有版本并提示：
“`
检测到多个MySQL版本，请选择要安装的版本:
[1] mysql-8.X/9.X.0-linux-glibc2.28-x86_64.tar.xz (xxx.xx MB)
[2] mysql-9.x.x-linux-glibc2.28-x86_64.tar.xz (yyy.yy MB)
请选择版本 (1-2):
“`
输入对应序号后，工具会统一所有主机的安装版本。
### 4.8 场景八：MySQL主从切换演练
**背景**：安装完成后，演练将主库从 192.168.1.51 切换到 192.168.1.52。
**操作过程**：
“`bash
# 1. 主库加读锁
mysql -h 192.168.1.51 -u root -p -e “FLUSH TABLES WITH READ LOCK; SET GLOBAL read_only=ON;”
# 2. 确认从库 192.168.1.52 已追上
mysql -h 192.168.1.52 -u root -p -e “SHOW REPLICA STATUS\G”
# 确认 Seconds_Behind_Source = 0
# 3. 提升从库为新主
mysql -h 192.168.1.52 -u root -p -e “STOP REPLICA; RESET REPLICA ALL; SET GLOBAL read_only=OFF; SET GLOBAL super_read_only=OFF;”
# 4. 其他从库指向新主
mysql -h 192.168.1.53 -u root -p -e “STOP REPLICA; CHANGE REPLICATION SOURCE TO SOURCE_HOST=’192.168.1.52′, SOURCE_USER=’fgedu_repl’, SOURCE_PASSWORD=’fgedu_repl_123′, SOURCE_AUTO_POSITION=1; START REPLICA;”
# 5. 验证
mysql -h 192.168.1.52 -u root -p -e “SHOW BINARY LOG STATUS;”
mysql -h 192.168.1.53 -u root -p -e “SHOW REPLICA STATUS\G”
“`
### 4.9 场景九：MySQL离线环境部署
**背景**：目标机房无外网，无法在线安装 Python 依赖。
**操作过程**：
1. 在有网机器上准备 `python-pkgs/` 目录（工具已自带），或使用 `pip3 download pyyaml paramiko -d ./python-pkgs` 下载；
2. 将整个工具目录连同 `python-pkgs/` 拷贝到控制机；
3. 在控制机执行：
“`bash
pip3 install –no-index –find-links=./python-pkgs pyyaml paramiko
“`
4. 将 MySQL 二进制包拷贝到控制机脚本同级目录或 `/tmp`；
5. 执行安装命令，流程与在线环境一致。
—
## 五、常用问题与排查
### 5.1 SSH 连接失败
**现象**：日志提示 `主机 x.x.x.x 连接失败` 或 `ERROR: …`。
**排查**：
“`bash
# 1. 检查网络连通性
ping <目标IP>
# 2. 检查 SSH 端口可达
bash -c “exec 3<>/dev/tcp/<目标IP>/22; echo OK”
# 3. 手工 SSH 登录验证
ssh root@<目标IP>
# 4. 检查防火墙
systemctl status firewalld
“`
**常见原因**：目标服务器防火墙未关闭、SSH 服务未启动、SSH 端口非 22、密码错误、`/etc/hosts.allow` 或 `fail2ban` 拦截。
### 5.2 未找到 MySQL 安装包
**现象**：日志提示 `所有主机都未找到MySQL安装包`。
**排查**：
“`bash
# 1. 确认安装包位置
ls -lh ./mysql-9*.tar.xz
ls -lh /tmp/mysql-9*.tar.xz
# 2. 确认文件大小大于 100MB（工具的过滤阈值）
ls -lh mysql-8.X/9.X.0-linux-glibc2.28-x86_64.tar.xz
“`
**常见原因**：文件名不含 `mysql`（被过滤）、文件大小小于 100MB（被过滤）、文件格式不是 `.tar.xz` 或 `.tar.gz`。
### 5.3 磁盘空间不足
**现象**：解压或初始化阶段报 `No space left on device`。
**排查**：
“`bash
df -h /mysql
df -h /tmp
df -h /
“`
**处理**：清理 `/var/log`、`/tmp` 残留文件，或在 的 `system.lvm` 中挂载更大的块设备到 `/mysql`。
### 5.4 端口 3306 被占用
**现象**：MySQL 启动失败，错误日志提示 `Port 3306 already in use`。
**排查**：
“`bash
netstat -tlnp | grep 3306
lsof -i:3306
“`
**处理**：停止占用端口的进程，或在 中修改 `mysql.port` 与 `my_cnf.port`。
### 5.5 依赖包安装失败
**现象**：`yum install` 阶段失败，提示 `No package xxx available`。
**排查**：
“`bash
yum repolist
# 确认是否有可用仓库
“`
**处理**：配置本地 YUM 源或内网镜像源，或在 的 `system.packages` 中移除缺失的包（前提是目标系统已有替代）。
### 5.6 MySQL 初始化失败
**现象**：`mysqld –initialize` 报错。
**排查**：
“`bash
# 查看数据目录是否为空
ls -la /mysql/data/3306/data
# 查看 mysql 用户是否创建
id mysql
# 查看权限
ls -ld /mysql/data/3306/data
“`
**处理**：清空数据目录后重试，确认目录属主为 `mysql:mysql`。
### 5.7 root 密码设置失败
**现象**：启动 MySQL 后执行 `ALTER USER` 报错。
**排查**：
“`bash
# 查看错误日志
tail -100 /mysql/log/3306/fgedudb-error.err
“`
**常见原因**：MySQL 未完全启动、root 初始密码未正确获取、`my.cnf` 中存在语法错误。
### 5.8 主从复制无法启动
**现象**：从库 `SHOW REPLICA STATUS` 中 `Replica_IO_Running` 或 `Replica_SQL_Running` 为 No。
**排查**：
“`bash
# 从库查看复制状态与错误
mysql -u root -p -e “SHOW REPLICA STATUS\G” | grep -E “Running|Last_Error”
# 检查网络
bash -c “exec 3<>/dev/tcp/<主库IP>/3306; echo OK”
# 检查复制用户
mysql -h <主库IP> -u root -p -e “SELECT user,host FROM mysql.user WHERE user=’fgedu_repl’;”
“`
**常见原因**：主库未创建复制用户、复制用户密码错误、主库 3306 端口未开放、GTID 模式不一致。
### 5.9 半同步插件加载失败
**现象**：`INSTALL PLUGIN rpl_semi_sync_source SONAME ‘semisync_source.so’` 报错。
**排查**：
“`bash
# 检查插件文件是否存在
ls -la /mysql/app/mysql/lib/plugin/semisync*.so
# 查看 MySQL 错误日志
tail -50 /mysql/log/3306/fgedudb-error.err
“`
**处理**：确认二进制包完整，必要时重新解压；检查 `my.cnf` 中 `plugin-load-add` 语法是否正确。
### 5.10 LVM 配置失败
**现象**：`pvcreate`/`vgcreate`/`lvcreate` 报错。
**排查**：
“`bash
# 确认块设备存在
ls -la /dev/sdc
# 确认设备未被占用
pvdisplay | grep /dev/sdc
“`
**处理**：如该主机已配置 LVM，可在 的对应 `system.lvm` 项中将 `skip` 设为 `true` 跳过。
### 5.11 安装中断后如何清理重试
**现象**：安装过程中因各种原因中断，再次执行时提示已存在 MySQL。
**处理**：
“`bash
# 1. 在目标主机停止 MySQL
systemctl stop mysql.service
pkill -9 mysqld
# 2. 清理数据目录与安装目录
rm -rf /mysql/data/3306/data/*
rm -rf /mysql/app/mysql/*
# 3. 重新执行安装命令
python3 FGMySQLAutoInstall_MR.py -mr … -u root -p …
“`
工具在检测到旧安装时会提示用户选择是否清理，按提示操作即可。
### 5.12 日志位置与查看
“`bash
# 安装日志
ls -lh logs/mysql_mr_install_*.log
tail -200 logs/mysql_mr_install_YYYYMMDD_HHMMSS.log
# MySQL 错误日志
ssh root@<目标IP> “tail -100 /mysql/log/3306/fgedudb-error.err”
# MySQL 慢查询日志
ssh root@<目标IP> “tail -50 /mysql/log/3306/fgedudb-query.err”
“`
—
## 六、附录
### 6.1 目录结构
“`
/mysql/
├── app/
│ └── mysql/ # MySQL 安装目录
├── data/
│ └── 3306/
│ ├── data/ # 数据文件目录
│ ├── my.cnf # 配置文件
│ └── mysql.pid # 进程 PID
├── log/
│ └── 3306/
│ ├── fgedudb-error.err # 错误日志
│ ├── fgedudb-query.err # 慢查询日志
│ ├── fgedudb-general.err# 通用日志
│ ├── binlog/ # 二进制日志
│ └── relaylog/ # 中继日志
/backup/ # 备份目录（LVM 可选）
“`
### 6.2 常用维护命令
“`bash
# 检查服务状态
systemctl status mysql.service
# 主库查看二进制日志状态
mysql -u root -p -e “SHOW BINARY LOG STATUS;”
# 主库查看从库列表
mysql -u root -p -e “SHOW REPLICAS;”
# 从库查看复制状态
mysql -u root -p -e “SHOW REPLICA STATUS\G”
# 从库停止/启动/重置复制
mysql -u root -p -e “STOP REPLICA;”
mysql -u root -p -e “START REPLICA;”
mysql -u root -p -e “RESET REPLICA;”
# 查看半同步状态
mysql -u root -p -e “SHOW GLOBAL VARIABLES LIKE ‘rpl_semi_sync%’;”
“`
### 6.3 安全建议
– 安装完成后立即修改 中的默认密码（root、复制用户、SSH 密码）；
– 生产环境关闭防火墙后应配置 iptables/firewalld 规则，仅允许可信 IP 访问 3306；
– 启用 SSH 密钥登录并禁用 root 密码登录；
– 定期备份 `/mysql/data/3306/data` 与 binlog；
– 为 MySQL 配置独立的备份账号与监控账号，遵循最小权限原则。
### 6.4 技术支持
如在使用过程中遇到问题，可通过以下方式联系作者获取支持：
作者：风哥
官方网站 http://www.fgedu.net.cn， http://www.itpux.com
数据库教程 https://edu.51cto.com/lecturer/8020378.html
mysql主从集群一键安装教程 https://edu.51cto.com/course/40554.html
本文由风哥教程整理发布,仅用于学习测试使用,转载注明出处:http://www.fgedu.net.cn/10327.html
