预置剧本

MYSQL 模块提供两个剧本：mysql.yml 负责部署与收敛，mysql-rm.yml 负责受保护的退役与下线。前者重复执行会向声明状态收敛；后者是独立的生命周期操作，每次真实执行前都必须重新核对范围、备份与精确确认值。

mysql.yml

对选中集群执行「检查 → 安装 → 引导 → 接入 → 业务对象 → 备份 → 监控」的完整收敛：

./mysql.yml -l my-test --check     # 预检：校验声明与现场，不做变更
./mysql.yml -l my-test             # 收敛一个集群（必须选中全部成员）
./mysql.yml                        # 收敛清单中所有 MySQL 集群

使用约定：

• HA 集群必须整簇选择：-l 只选中部分成员会在预检被拒绝（防止拓扑分歧）；可以同时选中多个完整集群或不加 -l；
• 幂等：现场已符合声明时重跑为 changed=0，秒级完成；AdminAPI 成员操作（rejoin/Clone）之后的下一次运行可能出现一次收敛性 changed（复制种子钉回声明值），属预期行为；
• check 模式：对全新节点只能预演到软件包安装（后续步骤依赖已安装的现场），对已部署集群可完整预演；
• 首次三节点部署约 2 分钟：证书签发 → 配置初始化 → AdminAPI 建群 → 两个从库 Clone → 每成员 Router 引导 → 业务对象 → 备份与监控注册。

执行阶段与任务标签

mysql
├── mysql_check       # 校验身份、平台、凭据、参数与数据目录属主（always）
├── mysql_install     # 安装固定的 MySQL 8.4 平台软件包
├── mysql_bootstrap
│   ├── mysql_cert    # 签发并安装节点 TLS 叶证书
│   ├── mysql_config  # 渲染配置（含 mysql_parameters）、初始化空数据目录
│   ├── mysql_launch  # 启动/滚动重启 mysqld，收敛 root 与 AdminAPI 身份
│   └── mysql_cluster # 建立或收敛三节点 InnoDB Cluster（rejoin/Clone）
├── mysql_access
│   └── mysql_router  # 在 HA 成员上引导并校验 Router
├── mysql_provision   # 收敛平台身份与声明的业务库、用户
├── mysql_backup      # 安装备份脚本与每日定时器
├── mysql_monitor     # 配置 Exporter 并注册监控 Target
└── mysql_done        # 输出实例摘要

常用标签化运行：

./mysql.yml -l my-test -t mysql_provision    # 只收敛业务库与用户
./mysql.yml -l my-test -t mysql_backup       # 只收敛备份配置与定时器
./mysql.yml -l my-test -t mysql_monitor      # 只收敛 Exporter 与监控注册

参数与配置变更建议执行完整剧本（涉及滚动重启编排，见下节）。

配置变更与滚动重启

mysql_launch 阶段包含变更编排逻辑，当配置文件、证书或 systemd 单元发生变化时：

1. 健康前置检查：HA 集群必须 3 成员 ONLINE 才允许滚动重启，降级集群直接拒绝（先修复后变更）；
2. 从库先行：按当前运行时角色（而非 mysql_seq）排序，从库逐台重启并等待回归 ONLINE；
3. 主库殿后：最后重启主库，触发一次自动切换（秒级写中断）。

单机集群直接原地重启。配置渲染阶段的 mysqld --validate-config 保证非法参数在触碰服务之前失败。

安全护栏

mysql.yml 的预检与收敛在以下情况 主动拒绝，错误信息会说明原因与处置：

这些护栏能显著降低误操作风险，但不构成“绝不丢数据”的保证。绕过护栏的每个动作（如删除标记或清理数据目录）都必须是经过备份验证与精确范围确认的人工决定。

mysql-rm.yml

退役剧本接受三种范围，全部需要双重确认（mysql_safeguard=false + mysql_rm_confirm 精确等于目标名）：

# 退役 HA 集群中的一个成员（目标须可达：在线 SECONDARY 或已脱离集群的成员）
./mysql-rm.yml -l 10.10.10.13 --check -e mysql_safeguard=false -e mysql_rm_confirm=my-test-3
./mysql-rm.yml -l 10.10.10.13         -e mysql_safeguard=false -e mysql_rm_confirm=my-test-3

# 下线整个 HA 集群
./mysql-rm.yml -l my-test -e mysql_safeguard=false -e mysql_rm_confirm=my-test

# 下线单机实例
./mysql-rm.yml -l my-meta -e mysql_safeguard=false -e mysql_rm_confirm=my-meta

执行内容与边界：

• 单成员退役：用 AdminAPI（force: false）从集群摘除 ONLINE SECONDARY（或确认已脱离集群成员的摘除状态），随后停止本机服务。摘除脚本在目标机上执行，因此 要求目标可达；机器已死亡时改用手工强制摘除（见 替换故障成员）。不允许直接退役主库（先 setPrimaryInstance 切走），也不允许一次退役 3 成员中的 2 个；
• 整簇下线：停止 Router 与备份定时器 → 从库先停、主库最后 → 注销 Exporter 与监控 Target；
• 每个数据目录写入退役标记 .pigsty-mysql-retired，阻止普通 mysql.yml 重新接管；
• 保留一切数据：数据目录、备份、配置、证书、软件包、Metadata、Router 身份全部原样保留。彻底销毁是另一件事，请在确认备份后手工执行。

预览模式（--check）会完整展示将要发生的动作而不触碰现场。

剧本边界

以下操作 不属于 剧本职责，对应的人工流程见 日常管理：

• 计划内主从切换（setPrimaryInstance）；
• 不可达死机成员的强制摘除（removeInstance + force: true）；
• 完全停机后的仲裁重建（rebootClusterFromCompleteOutage）；
• 物理备份恢复（XtraBackup copy-back 手册）；
• 删除数据目录 / 备份 / 退役标记等销毁类动作；
• 拓扑变形（1→3、3→5）与成员改址。