剧本列表

Pigsty v4.x 预置 Ansible 剧本导航与执行要点

本文汇总 Pigsty v4.x 各模块剧本入口与执行要点，详细任务标签请进入对应模块 playbook 文档。

模块剧本导航

模块	数量	剧本
`INFRA`	3	`deploy.yml` `infra.yml` `infra-rm.yml`
`NODE`	2	`node.yml` `node-rm.yml`
`ETCD`	2	`etcd.yml` `etcd-rm.yml`
`PGSQL`	7	`pgsql.yml` `pgsql-rm.yml` `pgsql-user.yml` `pgsql-db.yml` `pgsql-monitor.yml` `pgsql-migration.yml` `pgsql-pitr.yml`
`REDIS`	2	`redis.yml` `redis-rm.yml`
`MINIO`	2	`minio.yml` `minio-rm.yml`
`DOCKER`	1	`docker.yml`
`JUICE`	1	`juice.yml`
`VIBE`	1	`vibe.yml`
`KAFKA`	2	`kafka.yml` `kafka-rm.yml`
`MYSQL`（试点）	2	`mysql.yml` `mysql-rm.yml`

剧本总表

剧本	模块	主要用途
`deploy.yml`	`INFRA`	一次性部署核心链路（Infra/Node/Etcd/PGSQL，按配置启用 MINIO）
`infra.yml`	`INFRA`	初始化基础设施节点
`infra-rm.yml`	`INFRA`	移除基础设施组件
`node.yml`	`NODE`	节点纳管与基线配置
`node-rm.yml`	`NODE`	节点去纳管
`etcd.yml`	`ETCD`	ETCD 安装/扩容
`etcd-rm.yml`	`ETCD`	ETCD 移除/缩容
`pgsql.yml`	`PGSQL`	初始化 PostgreSQL 集群或新增实例
`pgsql-rm.yml`	`PGSQL`	移除 PostgreSQL 集群/实例
`pgsql-user.yml`	`PGSQL`	增加业务用户
`pgsql-db.yml`	`PGSQL`	增加业务数据库
`pgsql-monitor.yml`	`PGSQL`	纳管远程 PostgreSQL 监控
`pgsql-migration.yml`	`PGSQL`	生成迁移手册与脚本
`pgsql-pitr.yml`	`PGSQL`	时间点恢复（PITR）
`redis.yml`	`REDIS`	Redis 部署
`redis-rm.yml`	`REDIS`	Redis 移除
`minio.yml`	`MINIO`	Silo 部署
`minio-rm.yml`	`MINIO`	移除 Silo、配置与可选数据
`docker.yml`	`DOCKER`	Docker 引擎部署
`juice.yml`	`JUICE`	JuiceFS 实例部署/移除
`vibe.yml`	`VIBE`	VIBE 开发环境部署
`kafka.yml`	`KAFKA`	创建或收敛完整的 dynamic KRaft 集群
`kafka-rm.yml`	`KAFKA`	移除 Kafka 集群，或安全退役单个成员
`mysql.yml`	`MYSQL`	收敛原生 MySQL 8.4 单节点或三节点 InnoDB Cluster（试点）
`mysql-rm.yml`	`MYSQL`	停止/退役原生 MySQL 实例或集群并保留本地状态（试点）

辅助剧本

以下剧本不归属于特定模块，提供一些辅助功能。

剧本	说明
`cache.yml`	构建离线安装包缓存
`cert.yml`	使用 Pigsty CA 签发证书
`app.yml`	使用 Docker Compose 安装应用模板
`slim.yml`	最小化组件安装场景

剧本使用注意事项

保护机制

多个模块提供了防误删保险，通过 *_safeguard 参数控制：

PGSQL: pg_safeguard 参数用于防止误删 PostgreSQL 集群
ETCD: etcd_safeguard 参数用于防止误删 Etcd 集群
MINIO: minio_safeguard 参数用于防止误删 Silo 集群
REDIS: redis_safeguard 参数用于防止误删 Redis 实例
KAFKA: kafka_safeguard 参数用于阻止 Kafka 移除剧本
MYSQL（试点）: mysql_safeguard 与精确匹配的 mysql_rm_confirm 共同保护原生 MySQL 退役流程

PGSQL、ETCD、MINIO、REDIS 与 KAFKA 的角色默认值均显式为 false；生产环境可在已初始化的集群上设置为 true。原生 MySQL 试点相反：mysql_safeguard 默认是 true，且即使显式关闭，也必须提供与目标实例或集群完全一致的 mysql_rm_confirm。

当保护开关设置为 true 时，对应的 *-rm.yml 剧本会立即中止执行，防止误删。可以通过命令行参数强制覆盖：

./pgsql-rm.yml -l pg-test -e pg_safeguard=false
./etcd-rm.yml  -l etcd -e etcd_safeguard=false
./minio-rm.yml -l minio   -e minio_type=silo -e minio_safeguard=false
./redis-rm.yml -l redis-test -e redis_safeguard=false
./kafka-rm.yml -l kf-main -e kafka_safeguard=false
./mysql-rm.yml -l my-test -e mysql_safeguard=false -e mysql_rm_confirm=my-test

限制执行范围

执行剧本时建议使用 -l 参数限制命令执行的对象范围：

./pgsql.yml -l pg-meta            # 限制在集群 pg-meta 上执行
./node.yml -l 10.10.10.10         # 限制在特定节点上执行
./redis.yml -l redis-test         # 限制在 redis-test 集群上执行

在大规模部署上批量执行时，建议先在单集群灰度验证，再分批执行到全局。

幂等性

大部分剧本都是幂等的，可以重复执行。但需要注意：

infra.yml 默认不会清除数据，可安全重复执行。所有 clean 参数（vmetrics_clean、vlogs_clean、vtraces_clean、grafana_clean、nginx_clean）默认均为 false
如需清除基础设施数据重建，需显式设置对应的 clean 参数为 true
重复执行 *-rm.yml 删除剧本需格外小心，确保在正确的目标上执行

任务标签

可以使用 -t 参数只执行特定的任务子集：

./pgsql.yml -l pg-test -t pg_service    # 只刷新集群 pg-test 的服务
./node.yml -t haproxy                   # 只在节点上设置 haproxy
./etcd.yml -t etcd_launch               # 只重启 etcd 服务

常用命令速查

INFRA 模块

./deploy.yml                     # 一次性部署核心链路
./infra.yml                      # 初始化基础设施
./infra-rm.yml                   # 移除基础设施
./cache.yml -l <infra-host>      # 从指定 Infra 节点的现有仓库创建离线安装包
./cert.yml -e cn=<name>          # 签发客户端证书

NODE 模块

./node.yml -l <cls|ip>           # 添加节点
./node-rm.yml -l <cls|ip>        # 移除节点
bin/node-add <cls|ip>            # 添加节点 (包装脚本)
bin/node-rm <cls|ip>             # 移除节点 (包装脚本)

ETCD 模块

./etcd.yml                       # 初始化 etcd 集群
./etcd-rm.yml -l etcd            # 默认删除该集群的本机数据与配置
bin/etcd-add <ip>                # 添加 etcd 成员 (包装脚本)
bin/etcd-rm <ip>                 # 移除 etcd 成员 (包装脚本)

PGSQL 模块

./pgsql.yml -l <cls>             # 初始化 PostgreSQL 集群
./pgsql-rm.yml -l <cls>          # 移除 PostgreSQL 集群
./pgsql-user.yml -l <cls> -e username=<user>   # 创建业务用户
./pgsql-db.yml -l <cls> -e dbname=<db>         # 创建业务数据库
./pgsql-monitor.yml -e clsname=<cls>           # 监控远程集群
./pgsql-migration.yml -e@files/migration/<cls>.yml  # 生成迁移手册
./pgsql-pitr.yml -l <cls> -e '{"pg_pitr": {}}'      # 执行 PITR 恢复

bin/pgsql-add <cls>              # 初始化集群 (包装脚本)
bin/pgsql-rm <cls>               # 移除集群 (包装脚本)
bin/pgsql-user <cls> <user>      # 创建用户 (包装脚本)
bin/pgsql-db <cls> <db>          # 创建数据库 (包装脚本)
bin/pgsql-svc <cls>              # 刷新服务 (包装脚本)
bin/pgsql-hba <cls>              # 重载 HBA (包装脚本)
bin/pgmon-add <cls>              # 监控远程集群 (包装脚本)

REDIS 模块

./redis.yml -l <cls>             # 初始化 Redis 集群
./redis-rm.yml -l <cls>          # 移除 Redis 集群

MINIO 模块

./minio.yml -l <cls>                       # 初始化 MINIO 模块的 Silo 集群
./minio-rm.yml -l <cls> -e minio_type=silo # 移除 Silo；该值必须显式确认

DOCKER 模块

./docker.yml -l <host>           # 安装 Docker
./app.yml -e app=<name>          # 部署 Docker Compose 应用

KAFKA 模块

./kafka.yml -l <cls>             # 创建/收敛完整 Kafka 集群
./kafka.yml -l <cls> --check     # 只读预检
./kafka-rm.yml -l <cls>          # 移除完整集群
./kafka-rm.yml -l <ip>           # 从集群退役单个成员

普通收敛的 -l 必须包含所选 Kafka 集群的全部已声明成员；kafka-rm.yml 才支持选择单个成员执行退役。

MYSQL 试点模块

./mysql.yml -l <cls> --check
./mysql.yml -l <cls>             # 只接受完整的 1 或 3 成员集群范围
./mysql-rm.yml -l <instance> --check \
  -e mysql_safeguard=false -e mysql_rm_confirm=<instance>
./mysql-rm.yml -l <cls> \
  -e mysql_safeguard=false -e mysql_rm_confirm=<cls>

mysql-rm.yml 会停止服务、写入退役标记并注销监控，但不会删除数据目录、备份、配置、证书、软件包或 InnoDB Cluster 元数据。