剧本列表
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.ymlpgsql-user.yml pgsql-db.ymlpgsql-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 | MinIO 部署 |
minio-rm.yml | MINIO | MinIO 移除 |
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参数用于防止误删 MinIO 集群 - 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_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 # 移除 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 集群
./minio-rm.yml -l <cls> # 移除 MinIO 集群
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 元数据。