MySQL 8/9集群InnoDB Cluster自动化安装过程-Fgedu

FGDBA-MySQL 8/9 InnoDB Cluster 自动化安装工具是一款由风哥自主研发的、面向企业级生产环境的一键式 MySQL 8/9 InnoDB Cluster 自动化部署工具。

一、程序介绍
- 1.1 工具概述
- 1.2 作者信息
- 1.3 设计理念与背景
- 1.4 适用对象
二、功能特性
- 2.1 核心功能
- 2.2 增强特性
- 2.3 功能模块清单
- 2.4 技术实现亮点
三、支持环境
- 3.1 操作系统
- 3.2 硬件要求
- 3.3 软件依赖
- 3.4 网络与端口
- 3.5 集群规模
四、程序使用
- 4.1 目录结构
- 4.2 安装前准备
- 4.3 配置文件说明
- 4.4 命令行参数
- 4.5 基本使用流程
- 4.6 安装阶段说明
五、程序各种案例场景与操作过程
- 5.1 场景一：标准三节点 + 双 Router 全量安装
- 5.2 场景二：仅验证环境不安装
- 5.3 场景三：断点续装（跳过已完成阶段）
- 5.4 场景四：指定自定义集群名称
- 5.5 场景五：强制重新创建集群
- 5.6 场景六：指定非默认 SSH 端口
- 5.7 场景七：使用自定义配置文件
- 5.8 场景八：安装后的读写分离验证
- 5.9 场景九：集群日常维护操作
- 5.10 场景十：故障恢复操作
六、常用问题与排查
- 6.1 Python 环境问题
- 6.2 SSH 连接问题
- 6.3 MySQL 安装问题
- 6.4 MGR 集群问题
- 6.5 MySQL Shell 问题
- 6.6 InnoDB Cluster 问题
- 6.7 MySQL Router 问题
- 6.8 读写分离验证问题
- 6.9 日志文件位置
- 6.10 性能指标参考

一、程序介绍

1.1 工具概述

FGDBA-MySQL 8/9 InnoDB Cluster 自动化安装工具是一款由风哥自主研发的、面向企业级生产环境的一键式 MySQL 8/9 InnoDB Cluster 自动化部署工具。该工具基于 Python 3 编写，采用配置驱动（YAML 配置文件）的设计理念，通过 SSH 远程连接协议对多台目标主机进行并行操作，能够在一条命令内完成从底层系统参数调优、MySQL Server 二进制安装、MGR 组复制集群搭建、MySQL Shell 集群管理工具部署、InnoDB Cluster 元数据配置，到 MySQL Router 读写分离代理部署的完整高可用架构搭建工作。

工具采用经典的"三阶段架构"设计：

阶段一（MGR）：在 3 台及以上 MySQL Server 节点上部署二进制 MySQL 8/9，并配置 MGR（MySQL Group Replication）组复制，形成单主模式（Single-Primary）的高可用数据同步层。
阶段二（Shell + Cluster）：在集群节点上安装 MySQL Shell 管理工具，并通过 adoptFromGR 模式将已有的 MGR 集群整合升级为完整的 InnoDB Cluster，完成元数据初始化与集群管理用户创建。
阶段三（Router）：在 2 台及以上节点上安装 MySQL Router 代理层，实现读写分离与负载均衡，对外提供统一的访问端口。

整个安装过程采用多线程并行执行机制，相比传统的串行安装方式，整体部署时间可缩短 55% 以上。工具内置完善的错误处理、分阶段回滚、断点续装、符号链接检测、日志增强等机制，确保即使在复杂网络环境下也能安全、稳定、可重复地完成部署。

1.2 作者信息

作者：风哥
官方网站 http://www.fgedu.net.cn ， http://www.itpux.com
数据库教程 https://edu.51cto.com/lecturer/8020378.html
mysql MGR组复制集群一键安装教程 https://edu.51cto.com/course/40556.html

1.3 设计理念与背景

在企业级数据库运维场景中，MySQL InnoDB Cluster 架构的搭建涉及多个组件（MySQL Server、MySQL Shell、MySQL Router）、多台服务器（至少 3 台数据节点 + 2 台代理节点）、大量配置参数（系统内核参数、MySQL 参数、MGR 参数、Router 参数）以及繁琐的手工操作步骤。传统手工部署方式存在以下痛点：

步骤繁琐：完整搭建一套 InnoDB Cluster 需要上百个操作步骤，极易遗漏或出错。
容易出错：配置参数多且存在节点间依赖关系，任何一个参数配置错误都可能导致集群创建失败。
耗时漫长：串行安装 3 台 MySQL + 配置 MGR + 安装 Shell + 配置 Cluster + 安装 Router，熟练的 DBA 也需要 45 分钟以上。
难以重复：环境差异导致部署脚本难以在不同机器上重复使用。
回滚困难：安装中途失败后，手工清理残留环境非常麻烦。

基于上述背景，本工具的设计理念如下：

配置驱动：所有关键参数集中在配置文件中，一次配置、多节点复用，支持变量自动替换（如 {host_ip}）。
一键部署：单条命令即可完成全套架构部署，无需人工干预。
并行高效：多线程并行安装，大幅缩短部署时间。
安全可逆：失败时自动回滚，分阶段清理已安装组件，保证环境整洁。
断点续装：已成功安装的阶段可自动跳过，直接从失败处继续，避免重复劳动。
日志详尽：每个操作步骤均有详细日志记录，便于事后排查与审计。

1.4 适用对象

本工具适用于以下对象和场景：

企业 DBA 或运维工程师，需要快速搭建 MySQL InnoDB Cluster 高可用测试或生产环境。
数据库架构师，需要验证 InnoDB Cluster 的读写分离、自动故障转移等特性。
培训机构或教学环境，需要频繁创建/销毁 MySQL 高可用集群用于教学演示。
对 MySQL 高可用架构有一定了解，希望通过自动化手段提升部署效率与一致性的技术团队。

使用本工具前，建议操作者具备以下基础知识：

Linux 操作系统基础命令（文件操作、网络配置、服务管理）。
MySQL 数据库基础概念（实例、参数、复制）。
SSH 远程连接与基础网络知识。
YAML 配置文件的基本语法。

二、功能特性

2.1 核心功能

本工具围绕 InnoDB Cluster 全栈架构的自动化部署，提供以下核心功能：

一键安装：单条命令即可完成 InnoDB Cluster 完整部署（MySQL Server + MGR + MySQL Shell + InnoDB Cluster + MySQL Router），无需分步手工执行。
三阶段架构：MGR 集群（数据同步层）→ MySQL Shell（集群管理层）→ MySQL Router（读写分离代理层），阶段清晰、职责分明。
智能部署：内置环境自动检测（网络连通性、端口可用性、磁盘空间、内存、软件包完整性）、配置自动生成、参数自动优化能力。
高可用支持：支持单主（Single-Primary）拓扑模式下的自动故障转移与读写分离，保障业务连续性。
配置驱动：所有关键参数通过集中管理，支持命令行参数覆盖配置文件，灵活适应不同环境。
完整回滚：任意阶段安装失败时，自动触发分阶段回滚机制，按组件级别清理已安装内容（集群销毁、元数据清理、Router 卸载、MySQL 卸载、系统配置还原），保证目标环境整洁可重复部署。
断点续装：工具会自动检测各阶段是否已成功安装，已成功的阶段自动跳过，直接从失败阶段继续执行，大幅减少重试成本。
日志增强：详细记录每个操作步骤的执行结果，生成独立的安装日志文件（按时间戳命名），并生成安装报告，便于事后排查与审计。
符号链接检测：在检测 MySQL Shell、MySQL Router 等组件是否已安装时，同时检查实际安装目录与符号链接，避免因符号链接失效导致的误判。
日志目录统一：MySQL Shell 与 MySQL Router 的日志统一写入 /mysql/log/ 目录下，便于集中查看与运维管理。

2.2 增强特性

除核心功能外，工具还提供以下增强特性：

前置检查完善：在正式安装前，对网络连通性（MySQL 端口、MGR 端口、X Protocol 端口）、MySQL Shell 可用性、Router 端口可用性（6446、6447、6450）、集群仲裁配置、Router 部署依赖等进行全面检测，提前发现问题。
并行安装：使用多线程对 3 台 MySQL Server 节点并行执行二进制安装，安装结果集中追踪，失败节点自动回滚。
Router 智能部署策略：采用非主节点优先策略，优化 Router 在各节点的分布，评估负载均衡，避免 Router 集中在主节点导致单点压力。
集群引导策略：自动选择最佳引导节点（Bootstrap Node），用于 InnoDB Cluster 的创建与 Router 的 Bootstrap 操作。
Router 端口冲突自动调整：当目标端口被占用时，自动递增寻找可用端口，避免端口冲突导致安装失败。
配置文件变量自动替换：支持 {host_ip} 等变量，在生成各节点配置文件时自动替换为对应主机的实际 IP 地址。
自动备份现有配置：检测到已存在的 MySQL 安装时，提供清理、跳过、取消三种交互选项，保留 LVM 挂载目录、安装程序包与错误日志，仅删除数据目录和配置文件。
LVM 逻辑卷自动创建：支持在安装前自动创建 LVM 卷组、逻辑卷并挂载到指定目录（如 /mysql、/backup），并格式化为 xfs 文件系统。
系统内核参数自动调优：自动配置 fs.file-max、net.core.somaxconn、vm.swappiness、vm.overcommit_memory、大页内存等内核参数。
安全基线自动配置：自动关闭防火墙（firewalld）与 SELinux，配置 NUMA、透明大页、IO 调度器等系统层设置。
测试库自动创建：安装完成后自动创建测试数据库（fgedudb）、测试表（fgtest_table）并插入测试数据，用于验证 MGR 数据同步与 Router 读写分离功能。
安装报告生成：安装结束后生成完整的安装报告，包含各阶段耗时、成功/失败节点、集群状态、连接信息等。
半同步复制插件支持：支持安装并配置半同步复制（Semi-Sync）插件。
集群扩容支持：提供 MGR 集群动态扩容（scale-up）能力，可向现有集群中添加新的数据节点。

2.3 功能模块清单

工具代码以 MySQLMGRInstall 类为核心，内部集成了以下功能模块：

模块一：参数解析与配置管理模块

负责命令行参数解析（argparse）与 YAML 配置文件的加载、校验、动态更新。命令行参数可覆盖配置文件中的对应项（如 SSH 凭据、集群成员 IP、集群名称等），实现"配置文件打底 + 命令行覆盖"的灵活配置方式。

模块二：环境检测模块

在安装前对目标主机进行全面体检，包括：网络连通性检测（MySQL 端口 3306、MGR 端口 33006、X Protocol 端口 33060）、MySQL Shell 可用性检测（同时检查实际安装目录与符号链接）、Router 端口可用性检测（6446、6447、6450）、集群仲裁配置检查、Router 部署验证与依赖检查、元数据版本检查。

模块三：并行安装模块

使用多线程（threading）对多台 MySQL Server 节点并行执行二进制解压、目录创建、初始化、配置文件生成、systemd 服务注册、启动、root 密码设置等操作。安装结果通过线程锁保护的结果字典集中追踪，失败节点自动回滚。MySQL Shell 与 MySQL Router 安装同样支持多节点并行。

模块四：MGR 组复制配置模块

在 MySQL Server 安装完成后，配置 MGR 组复制集群：创建复制用户、配置 group_replication 参数（group_name、local_address、group_seeds、autorejoin_tries、member_expel_timeout 等）、启动组复制、设置单主模式、验证成员状态。

模块五：InnoDB Cluster 配置模块

通过 MySQL Shell 的 adoptFromGR 模式，将已有的 MGR 集群整合升级为 InnoDB Cluster。包括：创建集群管理用户（clusteradmin）、执行 adoptFromGR 创建集群、元数据初始化、集群状态验证。

模块六：MySQL Router 智能部署模块

负责 MySQL Router 的二进制安装、Bootstrap 操作、配置生成。采用非主节点优先策略，优化 Router 分布；支持读写路由策略（first-available）与只读路由策略（round-robin 轮询负载均衡）；支持 REST API 监控端口（8081）。

模块七：错误处理与回滚机制

追踪失败的步骤编号（failed_step）与失败的组件（failed_components），提供分阶段回滚能力：InnoDB Cluster 销毁、集群元数据清理、MySQL Router 卸载、MySQL 安装回滚、系统配置还原。保证失败后环境可整洁重试。

模块八：测试与验证模块

安装完成后自动创建测试库与测试数据，提供 MGR 集群状态验证、健康检查（health_check）、读写分离验证等能力。

2.4 技术实现亮点

Python 3 + paramiko：基于 paramiko 实现 SSH 远程连接与文件传输（SFTP），无需在目标主机预装 Agent。
YAML 配置驱动：使用 PyYAML 解析配置文件，结构清晰、可读性强、便于版本管理。
多线程并行：threading + Lock 实现多节点并行安装与结果同步。
进度回调：自定义 ProgressCallback 类，在文件传输时按 10% 步长显示进度。
日志分级：logging 模块同时输出到文件（按时间戳命名）与控制台，并关闭 paramiko 调试日志减少噪音。
断点续装：通过远程命令检测各阶段安装标志（如 mysqld 是否存在且服务活跃、mysqlsh 是否可执行、集群是否已创建），智能跳过已完成阶段。
符号链接双重检测：检测组件安装状态时同时检查实际目录与 /usr/bin 符号链接，避免误判。

三、支持环境

3.1 操作系统

本工具基于二进制方式安装 MySQL 8/9，对操作系统的要求如下：

操作系统	版本	支持状态	说明
RHEL（Red Hat Enterprise Linux）	9.x	推荐（主要测试环境）	官方推荐运行环境
Oracle Linux（OEL）	9.x	支持	与 RHEL 兼容
Kylin Linux（麒麟）	9.x	支持	国产化适配
CentOS Stream	9.x	兼容	社区版本
其他 RHEL 系衍生发行版	9.x	可能兼容	需自行验证

说明：

推荐使用 RHEL 9.x 系列，工具在该环境下经过充分测试。
操作系统需为 x86_64 架构。
建议使用最小化安装（Minimal Install）作为基础，由工具自动安装所需系统依赖包。
如需在国产化环境（如麒麟、统信 UOS）使用，请确认系统基于 RHEL 9 内核衍生。

3.2 硬件要求

每个节点的硬件资源配置建议如下：

资源	最低要求	推荐配置（生产）	说明
CPU	2 核	4 核及以上	MGR 对 CPU 有一定要求
内存	4 GB	8 GB 及以上	innodb_buffer_pool_size 建议设为物理内存的 50%-70%
磁盘	50 GB	100 GB 及以上（SSD）	数据目录建议使用 SSD，提升 IO 性能
网络	千兆网卡	万兆网卡	MGR 节点间通信对网络延迟敏感
磁盘类型	HDD	SSD	数据目录、binlog、redo log 建议 SSD

3.3 软件依赖

3.3.1 控制机（执行安装脚本的机器）Python 环境

包名	版本要求	用途
Python	3.6+（推荐 3.9+）	运行环境
paramiko	4.0.0	SSH 远程连接与文件传输
pyyaml	6.0	YAML 配置文件解析
cryptography	47.0.0	加密支持（paramiko 依赖）
invoke	3.0.3	命令执行辅助
bcrypt	5.0.0	SSH 密钥处理依赖
pynacl	1.6.2	加密依赖
cffi	2.0.0	CFFI 绑定
pycparser	2.23	C 解析器
typing_extensions	4.15.0	类型扩展

控制机需安装 Python 3 及上述扩展包。工具在 python-pkgs 目录中附带了离线安装包（.whl 与 .tar.gz），支持在无网络环境下离线安装。在线安装可使用 pip3 install -r requirements.txt。

3.3.2 目标主机系统依赖包

工具会在安装过程中自动通过 yum 安装以下系统包：

系统包	用途
libaio	Linux 异步 IO 库（MySQL 依赖）
numactl	NUMA 内存管理工具
perl	Perl 运行时（MySQL 部分脚本依赖）
net-tools	网络工具（含 netstat 等）
wget	文件下载工具
tar	解压工具
openssh-clients	SSH 客户端工具
socat	网络数据转发工具
openssl	加密库

3.3.3 MySQL 软件包

需提前将以下 MySQL 二进制安装包放置在每台目标主机的 /tmp 目录：

组件	软件包名称示例	放置位置	说明
MySQL Server	mysql-community-server-9.7.0-el9-x86_64.tar.gz	/tmp	数据库服务端
MySQL Shell	mysql-shell-9.7.0-linux-glibc2.28-x86_64.tar.gz	/tmp	集群管理工具
MySQL Router	mysql-router-9.7.0-linux-glibc2.28-x86_64.tar.gz	/tmp	读写分离代理

说明：工具支持在 /tmp 目录下自动扫描并选择匹配的安装包版本，无需严格固定文件名。

3.4 网络与端口

3.4.1 端口使用说明

端口	组件	用途	状态
22	SSH	远程管理与文件传输	必须开放
3306	MySQL Server	数据库连接端口	必须开放
33060	MySQL Server	X Protocol 端口（MySQL Shell 连接）	必须开放
33006	MGR	组复制成员间通信	必须开放
6446	MySQL Router	读写端口（连接主节点）	必须开放
6447	MySQL Router	只读端口（连接从节点，轮询）	必须开放
6450	MySQL Router	X Protocol 读写分离端口	可选开放
8081	MySQL Router	REST API 监控端口	可选开放
33066	MySQL Server	Admin 端口	内部使用

注意：配置文件中 MGR 通信端口为 33006（与部分文档示例中的 33061 不同，以实际中 group_replication_local_address 配置为准）。

3.4.2 网络配置建议

防火墙：安装环境建议关闭 firewalld（由工具自动配置），生产环境如需保留防火墙，请开放上表所有"必须开放"端口。
SELinux：安装前需关闭（由工具自动配置为 disabled）。
主机名：建议为每台节点设置独立主机名（如 mysql-01、mysql-02、mysql-03），并配置 /etc/hosts 互相解析。
网络延迟：MGR 节点间网络延迟建议低于 5ms，以保证集群稳定性。

3.5 集群规模

组件	最小数量	推荐数量	说明
MySQL Server（MGR 数据节点）	3 台	3-9 台	奇数台保证仲裁
MySQL Router（代理节点）	2 台	2-4 台	可与 MySQL Server 共享主机
MySQL Shell（管理工具）	3 台	与 Cluster 节点相同	建议安装在每个数据节点

四、程序使用

4.1 目录结构

工具的目录结构如下：

FGMySQLAutoInstall_IC1.2/
├── FGMySQLAutoInstall_IC.py    # 主程序脚本（自动化安装核心逻辑）
├── mysql_config.yaml            # 配置文件（所有参数集中管理）
├── requirements.txt             # Python 依赖包清单
├── docs/                        # 文档目录
│   ├── README.md                # 功能说明文档
│   ├── README2.md               # 详细说明手册（本文档）
│   └── INSTALL.md               # 安装指南（Step by Step）
├── logs/                        # 日志目录（安装日志按时间戳命名）
│   └── mysql_mgr_install_<时间戳>.log
├── python-pkgs/                 # Python 离线安装包目录
│   ├── paramiko-4.0.0-*.whl
│   ├── pyyaml-6.0-*.whl
│   └── ...（其他依赖）
└── __pycache__/                 # Python 编译缓存（自动生成）

安装后的 MySQL 相关目录结构（目标主机上）：

/mysql/
├── app/
│   ├── mysql/                   # MySQL Server 安装目录
│   ├── mysql-shell/             # MySQL Shell 安装目录
│   └── mysql-route/            # MySQL Router 安装目录
├── data/
│   ├── 3306/
│   │   ├── data/                # MySQL 数据目录
│   │   └── my.cnf               # MySQL 配置文件
│   └── mysqlrouter/             # Router 数据目录
└── log/
    ├── 3306/                    # MySQL 日志目录
    │   ├── fgedudb-error.err    # MySQL 错误日志
    │   ├── fgedudb-query.log    # 慢查询日志
    │   └── binlog/              # binlog 目录
    ├── mysqlsh/                 # MySQL Shell 日志
    └── mysqlrouter/             # MySQL Router 日志
/backup/                         # 备份目录（LVM 自动创建）

4.2 安装前准备

步骤一：准备控制机 Python 环境

# 安装 Python 3 与 pip（如未安装）
sudo yum install -y python3 python3-pip

# 在线安装依赖包
pip3 install -r requirements.txt

# 或离线安装（使用 python-pkgs 目录）
cd python-pkgs
pip3 install --no-index --find-links=. -r ../requirements.txt

步骤二：准备 MySQL 软件包

将 MySQL Server、MySQL Shell、MySQL Router 三类二进制包上传到每台目标主机的 /tmp 目录：

# 上传 MySQL Server 到所有数据节点
for ip in 192.168.1.51 192.168.1.52 192.168.1.53; do
    scp mysql-community-server-9.7.0-el9-x86_64.tar.gz root@$ip:/tmp/
done

# 上传 MySQL Shell 到所有数据节点
for ip in 192.168.1.51 192.168.1.52 192.168.1.53; do
    scp mysql-shell-9.7.0-linux-glibc2.28-x86_64.tar.gz root@$ip:/tmp/
done

# 上传 MySQL Router 到 Router 节点
for ip in 192.168.1.51 192.168.1.52; do
    scp mysql-router-9.7.0-linux-glibc2.28-x86_64.tar.gz root@$ip:/tmp/
done

步骤三：修改配置文件

编辑，根据实际环境修改以下关键配置项：

innodb_cluster.cluster_members：InnoDB Cluster 成员 IP 列表
innodb_cluster.mysql_routers：Router 节点 IP 列表
mgr.group_replication_group_seeds：MGR 种子节点列表
mysql.root_password：MySQL root 密码
ssh.username / ssh.password / ssh.port：SSH 连接凭据

说明：命令行参数会覆盖配置文件中的 IP 和 SSH 设置，因此也可以在执行命令时通过命令行参数指定，无需修改配置文件。

步骤四：验证前置条件

# 验证 Python 环境
python3 --version
pip3 list | grep paramiko

# 验证 SSH 连通性
for ip in 192.168.1.51 192.168.1.52 192.168.1.53; do
    ssh -o ConnectTimeout=5 root@$ip "hostname"
done

# 验证软件包
for ip in 192.168.1.51 192.168.1.52 192.168.1.53; do
    ssh root@$ip "ls -lh /tmp/mysql*.tar.*"
done

4.3 配置文件说明

配置文件采用 YAML 格式，包含以下主要配置段：

4.3.1 innodb_cluster（InnoDB Cluster 配置）

innodb_cluster:
  cluster_members:               # Cluster 成员 IP 列表（必须 3 台）
    - 192.168.1.51
    - 192.168.1.52
    - 192.168.1.53
  cluster_name: fgedu-innodb-cluster   # 集群名称
  mysql_routers:                 # Router 节点 IP 列表（至少 2 台）
    - 192.168.1.51
    - 192.168.1.52
  router_ports:
    classic: 6446                # 读写端口
    xprotocol: 6450              # X Protocol 读写分离端口
    admin: 6447                  # 只读端口
  cluster_admin_user: clusteradmin           # 集群管理用户
  cluster_admin_password: clusteradmin_123    # 集群管理用户密码
  topology_mode: Single-Primary   # 拓扑模式（Single-Primary 或 Multi-Primary）
  expel_timeout: 5                # 成员驱逐超时（秒）
  member_weight: 50               # 成员权重（故障转移选举权重）

4.3.2 mgr（MGR 组复制配置）

mgr:
  group_name: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa1   # MGR 组名（UUID 格式，所有节点一致）
  group_replication_mode: single-primary             # 复制模式
  group_replication_local_address: '{host_ip}:33006' # 本地通信地址（{host_ip} 自动替换）
  group_replication_group_seeds: 192.168.1.51:33006,192.168.1.52:33006,192.168.1.53:33006
  autorejoin_tries: 288             # 自动重连尝试次数（约 2 小时）
  member_expel_timeout: 5           # 成员驱逐超时
  member_weight: 50
  replication_user: mgr_repl        # MGR 复制用户
  replication_password: mgr_repl_123

4.3.3 mysql_shell（MySQL Shell 配置）

mysql_shell:
  install_dir: /mysql/app/mysql-shell   # 安装目录
  mysqlsh_path: /usr/bin/mysqlsh        # mysqlsh 可执行文件路径（符号链接）
  version: 9.7.0                        # 版本
  mysqlsh_options: --sql --log-level=INFO

4.3.4 mysql_router（MySQL Router 配置）

mysql_router:
  install_dir: /mysql/app/mysql-route    # 安装目录
  config_dir: /etc/mysqlrouter           # 配置目录
  log_dir: /mysql/log/mysqlrouter       # 日志目录
  data_dir: /mysql/data/mysqlrouter     # 数据目录
  bootstrap_user: clusteradmin          # Bootstrap 用户
  bootstrap_password: clusteradmin_123
  bootstrap_address: 192.168.1.51:3306  # Bootstrap 地址（主节点）
  routing_strategies:
    read_write: first-available        # 读写策略（优先第一个可用节点）
    read_only: round-robin             # 只读策略（轮询负载均衡）
  max_connections: 1024
  enable_rest_api: true                # 启用 REST API
  rest_port: 8081                      # 监控端口

4.3.5 mysql（MySQL Server 配置）

mysql:
  install_dir: /mysql/app/mysql         # 安装目录
  data_dir: /mysql/data/3306/data       # 数据目录
  log_dir: /mysql/log/3306             # 日志目录
  port: 3306                           # 端口
  root_password: fgedu123              # root 密码
  version: 9.7.0
  binary_package: /tmp/mysql-community-server-9.7.0-el9-x86_64.tar.gz
  my_cnf:                              # my.cnf 配置参数
    innodb_buffer_pool_size: 2G
    max_connections: 300
    # ... 更多参数

4.3.6 system（系统配置）

system:
  packages:                 # 系统依赖包
    - libaio
    - numactl
    - perl
    # ...
  lvm:                      # LVM 逻辑卷配置
    - vg_name: mysqlvg
      lv_name: mysqllv
      pv_devices: /dev/sdc
      mount_point: /mysql
      filesystem: xfs
      size: 50G
  kernel:                   # 内核参数
    fs.file-max: 655350
    net.core.somaxconn: 65535
    vm.swappiness: 1
    # ...
  security:                 # 安全配置
    firewall: disabled
    selinux: disabled
    numa: disabled

4.3.7 ssh（SSH 配置）

ssh:
  username: root
  password: rootroot
  port: 22
  timeout: 30
  retry_count: 3

4.3.8 test（测试库配置）

test:
  database: fgedudb
  user: fgedu
  password: fgedu123
  table: fgtest_table
  table_structure: 'id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(50), value INT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP'
  test_data:
    - name: fgtest01
      value: 100
    - name: fgtest02
      value: 200

4.4 命令行参数

必选参数

参数	全称	说明	示例
-ic	--ic-hosts	InnoDB Cluster 成员 IP（至少 3 台，逗号分隔）	-ic 192.168.1.51,192.168.1.52,192.168.1.53
-shell	--shell-hosts	MySQL Shell 安装 IP（通常与 -ic 相同）	-shell 192.168.1.51,192.168.1.52,192.168.1.53
-route	--route-hosts	MySQL Router 安装 IP（至少 2 台）	-route 192.168.1.51,192.168.1.52
-u	--username	SSH 用户名	-u root
-p	--password	SSH 密码	-p rootroot

可选参数

参数	全称	说明	默认值
-P	--port	SSH 端口	22
-c	--config	配置文件路径	mysql_config.yaml
--cluster-name	-	指定 InnoDB Cluster 名称（覆盖配置文件）	fgedu-innodb-cluster
--recreate-cluster	-	强制重新创建集群（删除现有集群）	False
--verify-only	-	仅验证环境不执行安装	False

4.5 基本使用流程

基本使用流程如下：

准备控制机 Python 环境与依赖包。
将 MySQL 软件包上传到各目标主机 /tmp 目录。
修改配置文件（或通过命令行参数指定）。
执行安装命令。
查看安装日志与安装报告。
验证集群状态与读写分离功能。
清理测试库与临时文件（生产环境）。

基本安装命令：

python FGMySQLAutoInstall_IC.py \
  -ic 192.168.1.51,192.168.1.52,192.168.1.53 \
  -shell 192.168.1.51,192.168.1.52,192.168.1.53 \
  -route 192.168.1.51,192.168.1.52 \
  -u root \
  -p rootroot

4.6 安装阶段说明

工具将 InnoDB Cluster 的部署分为三个阶段，每个阶段完成后自动进入下一阶段：

阶段	名称	内容	预计耗时
阶段一	MGR	并行安装 3 台 MySQL Server，配置 MGR 单主组复制集群	10-15 分钟
阶段二	Shell + Cluster	安装 MySQL Shell，通过 adoptFromGR 创建 InnoDB Cluster	5-8 分钟
阶段三	Router	安装 2 台 MySQL Router，Bootstrap 读写分离配置	5-8 分钟
合计	-	完整 InnoDB Cluster 部署	20-30 分钟

五、程序各种案例场景与操作过程

以下通过十个典型场景，详细说明工具的操作过程。

5.1 场景一：mysql标准三节点 + 双 Router 全量安装

场景描述：在 3 台服务器（192.168.1.51、192.168.1.52、192.168.1.53）上部署 MySQL 8/9 InnoDB Cluster，在 2 台服务器（192.168.1.51、192.168.1.52）上部署 MySQL Router，SSH 用户为 root，密码为 rootroot。

操作步骤：

确认软件包已上传：

for ip in 192.168.1.51 192.168.1.52 192.168.1.53; do
    ssh root@$ip "ls -lh /tmp/mysql*.tar.*"
done

执行安装命令：

python FGMySQLAutoInstall_IC.py \
  -ic 192.168.1.51,192.168.1.52,192.168.1.53 \
  -shell 192.168.1.51,192.168.1.52,192.168.1.53 \
  -route 192.168.1.51,192.168.1.52 \
  -u root \
  -p rootroot

工具自动执行以下流程：
- 加载配置文件并更新集群成员、Router 成员、MGR seeds 等参数。
- 前置条件检查（网络、端口、软件包、Shell 可用性、Router 端口、仲裁、依赖）。
- 断点续装检测（检查各阶段是否已完成）。
- 阶段一：并行安装 3 台 MySQL Server 并配置 MGR。
- 阶段二：安装 MySQL Shell 并通过 adoptFromGR 创建 InnoDB Cluster。
- 阶段三：安装 2 台 MySQL Router 并 Bootstrap。
- 创建测试库与测试数据。
- 验证集群状态并生成安装报告。
安装完成后，输出集群状态、节点角色、Router 端口、连接信息与管理命令。

5.2 场景二：仅验证环境不安装

场景描述：在正式安装前，先对目标环境进行体检，验证网络连通性、端口可用性、软件包完整性等，不执行任何安装操作。

操作命令：

python FGMySQLAutoInstall_IC.py \
  -ic 192.168.1.51,192.168.1.52,192.168.1.53 \
  -shell 192.168.1.51,192.168.1.52,192.168.1.53 \
  -route 192.168.1.51,192.168.1.52 \
  -u root \
  -p rootroot \
  --verify-only

说明：--verify-only 参数使工具仅更新配置文件并退出，不执行安装。可结合手动检查命令进一步验证：

# 检查端口占用
for ip in 192.168.1.51 192.168.1.52 192.168.1.53; do
    ssh root@$ip "ss -tlnp | grep -E '3306|33060|33006|6446|6447|6450'"
done

5.3 场景三：断点续装（跳过已完成阶段）

场景描述：上次安装过程中，阶段一（MGR）和阶段二（Shell + Cluster）已成功完成，但阶段三（Router）安装失败。重新执行时希望跳过已完成的阶段，直接从 Router 安装继续。

操作命令：

python FGMySQLAutoInstall_IC.py \
  -ic 192.168.1.51,192.168.1.52,192.168.1.53 \
  -shell 192.168.1.51,192.168.1.52,192.168.1.53 \
  -route 192.168.1.51,192.168.1.52 \
  -u root \
  -p rootroot

说明：工具内置断点续装机制，会自动检测：

阶段一是否完成：检查 mysqld 是否存在且 mysql.service 服务是否活跃。
阶段二-Shell 是否完成：检查安装目录下 mysqlsh 是否存在且可执行。
阶段二-Cluster 是否完成：检查 InnoDB Cluster 是否已创建。
阶段三是否完成：检查 Router 服务是否活跃。

已完成的阶段会显示"已安装完成，将跳过"，直接进入下一阶段。无需额外参数。

5.4 场景四：指定自定义集群名称

场景描述：希望将 InnoDB Cluster 命名为 mycluster，而非配置文件中的默认名称 fgedu-innodb-cluster。

操作命令：

python FGMySQLAutoInstall_IC.py \
  -ic 192.168.1.51,192.168.1.52,192.168.1.53 \
  -shell 192.168.1.51,192.168.1.52,192.168.1.53 \
  -route 192.168.1.51,192.168.1.52 \
  -u root \
  -p rootroot \
  --cluster-name mycluster

说明：--cluster-name 参数会覆盖配置文件中的 innodb_cluster.cluster_name，创建的 InnoDB Cluster 将使用指定的名称。

5.5 场景五：强制重新创建集群

场景描述：集群已存在但状态异常，需要删除现有集群并重新创建。

操作命令：

python FGMySQLAutoInstall_IC.py \
  -ic 192.168.1.51,192.168.1.52,192.168.1.53 \
  -shell 192.168.1.51,192.168.1.52,192.168.1.53 \
  -route 192.168.1.51,192.168.1.52 \
  -u root \
  -p rootroot \
  --recreate-cluster

说明：--recreate-cluster 参数会先销毁现有的 InnoDB Cluster 并清理元数据，然后重新创建集群。适用于集群状态损坏、元数据不一致等场景。

5.6 场景六：指定非默认 SSH 端口

场景描述：目标主机的 SSH 服务运行在 2222 端口，而非默认的 22 端口。

操作命令：

python FGMySQLAutoInstall_IC.py \
  -ic 192.168.1.51,192.168.1.52,192.168.1.53 \
  -shell 192.168.1.51,192.168.1.52,192.168.1.53 \
  -route 192.168.1.51,192.168.1.52 \
  -u root \
  -p rootroot \
  -P 2222

说明：-P（或 --port）参数指定 SSH 端口，默认为 22。该参数会写入配置文件的 ssh.port 字段。

5.7 场景七：使用自定义配置文件

场景描述：已准备了一份自定义配置文件 /opt/myconfig.yaml，希望使用该文件而非默认的 mysql_config.yaml。

操作命令：

python FGMySQLAutoInstall_IC.py \
  -ic 192.168.1.51,192.168.1.52,192.168.1.53 \
  -shell 192.168.1.51,192.168.1.52,192.168.1.53 \
  -route 192.168.1.51,192.168.1.52 \
  -u root \
  -p rootroot \
  -c /opt/myconfig.yaml

说明：-c（或 --config）参数指定配置文件路径。工具会读取该文件，并将命令行参数（SSH 凭据、集群成员、Router 成员等）写入该文件后再执行。

5.8 场景八：mysql安装后的读写分离验证

场景描述：安装完成后，验证 MySQL Router 的读写分离功能是否正常。

操作步骤：

通过 Router 读写端口（6446）查询，应连接到主节点（read_only=0）：

mysql -h 192.168.1.51 -P 6446 -u root -pfgedu123 -e "SELECT @@hostname, @@read_only;"
# 预期输出：主节点主机名，read_only=0

通过 Router 只读端口（6447）查询，应连接到从节点（read_only=1），且轮询负载均衡：

mysql -h 192.168.1.51 -P 6447 -u root -pfgedu123 -e "SELECT @@hostname, @@read_only;"
# 预期输出：从节点主机名，read_only=1
# 多次执行可观察到主机名在多个从节点间轮询

通过 X Protocol 端口（6450）测试读写分离：

# 写入数据（走主节点）
mysql -h 192.168.1.52 -P 6450 -u root -pfgedu123 -e "INSERT INTO fgedudb.fgtest_table VALUES (3,'fgedu03',300);"

# 查询数据（走从节点）
mysql -h 192.168.1.51 -P 6450 -u root -pfgedu123 -e "SELECT * FROM fgedudb.fgtest_table;"

查看集群状态：

mysqlsh clusteradmin@192.168.1.51:6446 -e "cluster = dba.getCluster(); cluster.status();"

5.9 场景九：mysql集群日常维护操作

场景描述：安装完成后的日常运维操作。

查看集群状态：

mysqlsh clusteradmin@192.168.1.51:6446
# 在 MySQL Shell 中执行
cluster = dba.getCluster()
cluster.status()

查看 MGR 成员状态：

mysql -h 192.168.1.51 -P 3306 -u root -pfgedu123 -e "SELECT * FROM performance_schema.replication_group_members;"

Router 服务管理：

systemctl status mysqlrouter    # 查看状态
systemctl restart mysqlrouter   # 重启
systemctl stop mysqlrouter      # 停止
systemctl start mysqlrouter     # 启动

MySQL 服务管理：

systemctl status mysqld         # 查看状态
systemctl restart mysqld        # 重启
systemctl stop mysqld           # 停止
systemctl start mysqld          # 启动

5.10 场景十：mysql故障恢复操作

场景描述：集群出现节点故障或整体故障时的恢复操作。

单节点故障 - 重启 MGR 服务：

# 在故障节点上执行
mysql -u root -pfgedu123 -e "STOP GROUP_REPLICATION; START GROUP_REPLICATION;"

# 验证节点状态
mysql -u root -pfgedu123 -e "SELECT * FROM performance_schema.replication_group_members;"

集群整体故障 - 强制 bootstrap 重建（仅在拥有最新数据的节点执行）：

mysql -u root -pfgedu123 -e "SET GLOBAL group_replication_bootstrap_group=ON;"
mysql -u root -pfgedu123 -e "START GROUP_REPLICATION;"
mysql -u root -pfgedu123 -e "SET GLOBAL group_replication_bootstrap_group=OFF;"

Router 故障恢复：

# 重启 Router 服务
systemctl restart mysqlrouter

# 如需重新 Bootstrap
sudo mysqlrouter --bootstrap clusteradmin@192.168.1.51:3306 \
  --directory=/mysql/data/mysqlrouter --force

安装失败后的清理（重新安装前）：

# 清理测试库
mysql -h 192.168.1.51 -P 6446 -u clusteradmin -pclusteradmin_123 -e "DROP DATABASE IF EXISTS fgedudb;"
mysql -h 192.168.1.51 -P 6446 -u clusteradmin -pclusteradmin_123 -e "DROP USER IF EXISTS 'fgedu'@'%';"

# 清理临时文件
for ip in 192.168.1.51 192.168.1.52 192.168.1.53; do
    ssh root@$ip "rm -rf /tmp/mysql*.tar.*"
done

六、常用问题与排查

6.1 Python 环境问题

问题1：paramiko 安装失败

现象：pip3 install paramiko 报错。

排查与解决：

# 安装系统依赖
sudo yum install -y libffi-devel openssl-devel gcc gcc-c++

# 重新安装
pip3 install paramiko==4.0.0

# 或使用离线包安装
cd python-pkgs
pip3 install --no-index --find-links=. paramiko==4.0.0

问题2：pyyaml 版本不兼容

现象：加载配置文件时报 YAML 解析错误。

排查与解决：

pip3 uninstall pyyaml -y
pip3 install pyyaml==6.0

问题3：cryptography 安装失败

现象：cryptography 编译安装报错。

排查与解决：

sudo yum install -y libffi-devel openssl-devel
pip3 install cryptography==47.0.0

# 如仍有问题，设置环境变量
export CRYPTOGRAPHY_OPENSSL_NO_LEGACY=1

问题4：依赖包冲突

现象：离线安装时出现依赖冲突。

排查与解决：

pip3 install --ignore-installed --no-index --find-links=. paramiko==4.0.0

6.2 SSH 连接问题

问题1：SSH 连接超时

现象：工具提示网络连通性检查失败。

排查与解决：

# 检查网络连通性
ping <目标主机IP>
nc -zv -w 5 <目标主机IP> 22

# 检查 SSH 服务状态
ssh root@<目标主机IP> "systemctl status sshd"

问题2：Host key verification failed

现象：SSH 连接提示主机密钥验证失败。

排查与解决：

ssh-keygen -R <目标主机IP>
ssh-keyscan -H <目标主机IP> >> ~/.ssh/known_hosts

问题3：SSH 用户名或密码错误

现象：工具提示认证失败。

排查与解决：确认命令行 -u 和 -p 参数与目标主机的实际 SSH 凭据一致。

6.3 MySQL 安装问题

问题1：软件包未找到

现象：工具提示"主机 X 未找到 MySQL 安装包"。

排查与解决：

# 确认软件包已上传到 /tmp 目录
ssh root@<目标主机IP> "ls -lh /tmp/mysql*.tar.*"

# 如缺失，上传软件包
scp mysql-community-server-9.7.0-el9-x86_64.tar.gz root@<目标主机IP>:/tmp/

问题2：端口被占用

现象：MySQL 启动失败，提示端口 3306 已被占用。

排查与解决：

# 查看占用进程
ss -tlnp | grep :3306
# 或
sudo lsof -i :3306

# 停止占用进程或使用工具清理
# 工具检测到已存在 MySQL 时会提示清理选项（y=清理并安装, s=跳过, n=取消）

问题3：已存在 MySQL 安装

现象：工具检测到已存在的 MySQL 并提示选择。

排查与解决：根据提示选择：

输入 y：清理现有 MySQL（停止服务、删除数据目录与配置文件，保留 LVM 挂载、安装包与错误日志）后继续安装。
输入 s：跳过已安装阶段，继续后续安装（适用于断点续装）。
输入 n：取消安装。

6.4 MGR 集群问题

问题1：MGR 插件加载失败

现象：START GROUP_REPLICATION 报错，提示 group_replication.so 未找到。

排查与解决：

mysql -u root -pfgedu123 -e "INSTALL PLUGIN group_replication SONAME 'group_replication.so';"

问题2：MGR 组名称不匹配

现象：节点无法加入 MGR 集群。

排查与解决：

# 确保所有节点使用相同的 group_name
mysql -u root -pfgedu123 -e "SHOW GLOBAL VARIABLES LIKE 'group_replication_group_name';"

问题3：MGR 成员状态为 RECOVERING 或无法加入

现象：成员状态长时间停留在 RECOVERING。

排查与解决：

检查 MGR 通信端口（33006）是否开放。
检查复制用户（mgr_repl）密码是否一致。
检查网络延迟是否过高。
查看 MySQL 错误日志：/mysql/log/3306/fgedudb-error.err

6.5 MySQL Shell 问题

问题1：MySQL Shell 检测误判

现象：工具误判 MySQL Shell 已安装或未安装。

排查与解决：工具会同时检查实际安装目录（/mysql/app/mysql-shell/bin/mysqlsh）与符号链接（/usr/bin/mysqlsh）。如符号链接失效会自动清理。手动检查：

ls -la /mysql/app/mysql-shell/bin/mysqlsh
ls -la /usr/bin/mysqlsh

问题2：MySQL Shell 版本兼容性

现象：MySQL Shell 9.7 在 JavaScript 模式下出现 GraalVM 兼容性问题。

排查与解决：工具已将集群配置脚本从 JavaScript 模式迁移到 Python 模式，避免兼容性问题。确保使用与工具匹配的 MySQL Shell 版本（9.7.0）。

6.6 InnoDB Cluster 问题

问题1：集群创建失败

现象：adoptFromGR 创建集群时报错。

排查与解决：

# 检查 MySQL X Protocol 是否启用
mysql -u root -pfgedu123 -e "SHOW VARIABLES LIKE 'mysqlx_port';"
# 预期：33060

# 检查 clusteradmin 用户权限
mysql -u root -pfgedu123 -e "SHOW GRANTS FOR 'clusteradmin'@'%';"

# 查看 MySQL 错误日志
tail -100 /mysql/log/3306/fgedudb-error.err

问题2：元数据版本不一致

现象：工具提示元数据版本检查异常。

排查与解决：工具在安装前会检查 metadata_version。如版本不一致，可使用 --recreate-cluster 参数强制重新创建集群。

6.7 MySQL Router 问题

问题1：Bootstrap 失败

现象：Router Bootstrap 命令执行失败。

排查与解决：

# 检查 clusteradmin 用户权限与主节点连通性
mysql -h 192.168.1.51 -P 3306 -u clusteradmin -pclusteradmin_123 -e "SELECT 1;"

# 手动 Bootstrap 测试
sudo mysqlrouter --bootstrap clusteradmin@192.168.1.51:3306 \
  --directory=/mysql/data/mysqlrouter --force

# 查看端口是否开放
ssh root@192.168.1.51 "ss -tlnp | grep -E '6446|6447|6450'"

问题2：Router 端口冲突

现象：Router 启动失败，提示端口被占用。

排查与解决：

# 查看占用进程
sudo lsof -i :6446
sudo lsof -i :6447

# 工具内置端口冲突自动调整功能，会自动递增寻找可用端口
# 如需手动处理，停止占用进程后重启 Router
systemctl restart mysqlrouter

6.8 读写分离验证问题

问题1：读写端口返回从节点

现象：通过 6446 端口查询返回的是从节点（read_only=1）。

排查与解决：

# 检查集群状态，确认主节点是否在线
mysqlsh clusteradmin@192.168.1.51:6446 -e "cluster = dba.getCluster(); cluster.status();"

# 如主节点故障，Router 会自动切换到新的主节点
# 检查 Router 日志
tail -100 /mysql/log/mysqlrouter/mysqlrouter.log

问题2：只读端口返回主节点

现象：通过 6447 端口查询返回的是主节点。

排查与解决：

检查集群中是否有足够的从节点在线。
检查 Router 的只读路由策略配置（round-robin）。
如集群中只有一个节点在线（其他节点故障），Router 会将所有流量导向该节点。

6.9 日志文件位置

安装与运维过程中，相关日志文件位置如下：

日志类型	文件路径	说明
安装日志	logs/mysql_mgr_install_时间戳.log	工具执行的完整操作记录
MySQL 错误日志	/mysql/log/3306/fgedudb-error.err	MySQL Server 错误信息
MySQL 慢查询日志	/mysql/log/3306/fgedudb-query.log	慢查询记录（阈值 5 秒）
MySQL 通用日志	/mysql/log/3306/fgedudb-general.err	通用查询日志（默认关闭）
binlog 日志	/mysql/log/3306/binlog/fgedudb-binlog.*	二进制日志
MySQL Shell 日志	/mysql/log/mysqlsh/mysqlsh.log	Shell 操作日志
MySQL Router 日志	/mysql/log/mysqlrouter/mysqlrouter.log	Router 运行日志

6.10 性能指标参考

安装时间参考

阶段	时间范围	说明
阶段一（MGR）	10-15 分钟	并行安装 3 台 MySQL Server 并配置 MGR
阶段二（Shell + Cluster）	5-8 分钟	安装 MySQL Shell 并配置 InnoDB Cluster
阶段三（Router）	5-8 分钟	安装 MySQL Router（2 台）
总计	20-30 分钟	完整安装时间

并行效率对比

安装方式	耗时	效率
串行安装	约 45 分钟	基准
并行安装	约 20 分钟	提升 55%+

建议配置值

参数	建议值	说明
innodb_buffer_pool_size	物理内存的 50%-70%	根据服务器内存调整
max_connections	300-2048	根据并发量调整
innodb_io_capacity	2000-4000	根据磁盘 IO 能力调整
vm.swappiness	1-5	减少 swap 使用
fs.file-max	655350	文件描述符上限
net.core.somaxconn	65535	TCP 连接队列
member_expel_timeout	5-30	防止网络抖动误驱逐
autorejoin_tries	288	约 2 小时自动重连尝试

系统资源要求汇总

资源	最低要求	推荐配置
CPU	2 核	4 核+
内存	4 GB	8 GB+
磁盘	50 GB	100 GB+ SSD
网络	千兆网卡	万兆网卡

附录：

posted @ 2026-09-02 19:17 风哥数据库教程阅读(3) 评论(0) 收藏举报

刷新页面返回顶部