跳转到主要内容

使用 Ansible 剧本完成部署

使用 Ansible 剧本部署与管理 Pigsty 集群

Pigsty 使用 Ansible 对集群进行管理，这是在 SRE 群体中非常流行的大规模/批量化/自动化运维工具。

Ansible 可以使用 声明式 的方式对服务器进行配置管理，所有模块的部署都是通过一系列幂等的 Ansible 剧本 实现的。

例如，在单机部署时，您会用到 deploy.yml 剧本。Pigsty 还有更多 内置剧本，您可以根据需要选择使用。

了解 Ansible 基础知识有助于更好的使用 Pigsty，但这 并非必须，特别是在单机部署时。

部署剧本

Pigsty 提供了一个 “一条龙” 部署剧本 deploy.yml，用于一次性部署核心链路：CA/软件仓库、NODE、INFRA、ETCD、PGSQL，以及配置中启用的 MINIO。Redis、Kafka、原生 MySQL 等可选模块即使已在清单中定义，也需要分别执行其模块剧本。

Playbook 命令 分组 infra [nodes] etcd minio [pgsql]
infra.yml ./infra.yml -l infra ✓ ✓
node.yml ./node.yml ✓
etcd.yml ./etcd.yml -l etcd ✓
minio.yml ./minio.yml -l minio ✓
pgsql.yml ./pgsql.yml ✓

这是最简单的部署方式，您也可以参考 定制指南 里的说明，一步来增量式地完成所有模块与节点的部署。

安装 Ansible

使用 Pigsty 安装脚本，或离线安装的 bootstrap 阶段，Pigsty 会自动为您安装 ansible 及其依赖。

如果您想手动安装 Ansible，可以参考以下说明，支持的 Ansible 最低版本为 2.9

Debian / Ubuntu
sudo apt install -y ansible python3-jmespath
EL
sudo dnf install -y ansible python3.12-jmespath python3-cryptography  # EL 8
sudo dnf install -y ansible python3-jmespath                           # EL 9
sudo dnf install -y ansible                                            # EL 10
MacOS
brew install ansible
pip3 install jmespath
修改默认密码！

请注意，目前 EL10 EPEL 仓库尚未提供完整的 Ansible 包，Pigsty PGSQL EL10 仓库中补充了这个包。

Ansible 在 macOS 上也可用。您可以使用 Homebrew 在 Mac 上安装 Ansible， 并将其用作管理节点来管理远程云服务器。如果您在云 VPS 上部署单节点 Pigsty 这很方便，但不建议在生产环境中使用。

执行剧本

Ansible 剧本（Playbook）是包含要执行的一系列任务定义的可执行 YAML 文件。 执行剧本需要您的环境变量 PATH 中有 ansible-playbook 可执行文件。 运行 ./node.yml 剧本本质上是执行 ansible-playbook node.yml 命令。

您可以使用一些参数来精细控制剧本的执行，其中以下 4 个参数 需要您了解，以便有效使用 Ansible：

目的 参数 描述
对象 -l|--limit <pattern> 限制在特定 分组 / 主机 / 模式 上执行
任务 -t|--tags <tags> 只运行具有特定标签的任务
参数 -e|--extra-vars <vars> 额外的命令行参数
配置 -i|--inventory <path> 使用特定的清单文件 
./node.yml                         # 在所有主机上运行 node 剧本
./pgsql.yml -l pg-test             # 在 pg-test 集群上运行 pgsql 剧本
./infra.yml -t repo_build          # 运行 infra.yml 的子任务 repo_build
./pgsql-rm.yml -e pg_rm_pkg=false  # 删除 pgsql，但保留软件包（不卸载软件）
./infra.yml -i conf/mynginx.yml    # 使用另外一个位置的配置文件

限制主机

剧本的 执行目标 可以通过 -l|--limit <selector> 限制。 当尝试在特定主机/节点或组/集群上运行剧本时，这很方便。 以下是主机限制的一些示例：

./pgsql.yml                              # 在所有主机上运行（危险！）
./pgsql.yml -l pg-test                   # 在 pg-test 集群上运行
./pgsql.yml -l 10.10.10.10               # 在单个主机 10.10.10.10 上运行
./pgsql.yml -l pg-*                      # 在匹配 glob 模式 `pg-*` 的主机/组上运行
./pgsql.yml -l '10.10.10.11,&pg-test'    # 在 pg-test 组的 10.10.10.11 上运行
./pgsql-rm.yml -l 'pg-test,!10.10.10.11' # 在 pg-test 上运行，除了 10.10.10.11

查看 Ansible 文档中的所有详细信息：Patterns: targeting hosts and groups

谨慎运行没有主机限制的剧本！

在大多数时候，缺少这个值可能会有危险，因为大多数剧本将在 all 主机上执行。请谨慎使用。

限制任务

执行任务 可以通过 -t|--tags <tags> 控制。 如果指定，将只执行具有给定标签的任务，而不是整个剧本。

./infra.yml -t repo          # 创建仓库
./node.yml  -t node_pkg      # 安装节点包
./pgsql.yml -t pg_install    # 安装 PG 包和扩展
./etcd.yml  -t etcd_config   # 重新渲染 ETCD 配置
./minio.yml -t minio_alias   # 写入 mcli 客户端别名

要运行多个任务，指定多个标签并用逗号分隔 -t tag1,tag2：

./node.yml  -t node_repo,node_pkg   # 添加仓库，然后安装包
./pgsql.yml -t pg_hba,pg_reload     # 配置，然后重新加载 pg hba 规则

额外变量

您可以使用 CLI 参数在运行时覆盖配置参数，它具有 最高优先级。

额外的命令行参数可以通过 -e|--extra-vars KEY=VALUE 传递，可以多次使用：

# 使用另一个管理员用户创建管理员
./node.yml -e ansible_user=admin -k -K -t node_admin

# 初始化一个特定的 Redis 实例：10.10.10.11:6379
./redis.yml -l 10.10.10.10 -e redis_port=6379 -t redis

# 删除 PostgreSQL，但保留软件包和数据
./pgsql-rm.yml -e pg_rm_pkg=false -e pg_rm_data=false

对于复杂参数，可以使用 JSON 字符串，一次传递多个复杂参数。

# 添加仓库并安装包
./node.yml -t node_install -e '{"node_repo_modules":"infra","node_packages":["duckdb"]}'

指定清单

默认配置文件是 Pigsty 主目录中的 pigsty.yml。 您可以使用 -i <path> 参数指定不同的 配置清单 文件路径。

./pgsql.yml -i conf/rich.yml            # 根据 rich 配置初始化一个下载了所有扩展的单节点
./pgsql.yml -i conf/ha/full.yml         # 根据 full 配置初始化一个 4 节点集群
./pgsql.yml -i conf/app/supa.yml        # 根据 supa.yml 配置初始化一个 1 节点 Supabase 部署
更改默认清单文件

要永久更改 默认 配置文件，请修改 ansible.cfg 中的 inventory 参数。

便捷脚本

Pigsty 提供了一系列便捷脚本来简化常见操作，这些脚本位于 bin/ 目录下：

bin/node-add   <cls>            # 将节点纳入 Pigsty 管理：./node.yml -l <cls>
bin/node-rm    <cls>            # 从 Pigsty 移除节点：./node-rm.yml -l <cls>
bin/pgsql-add  <cls>            # 初始化 PG 集群：./pgsql.yml -l <cls>
bin/pgsql-rm   <cls>            # 移除 PG 集群：./pgsql-rm.yml -l <cls>
bin/pgsql-user <cls> <username> # 添加业务用户：./pgsql-user.yml -l <cls> -e username=<user>
bin/pgsql-db   <cls> <dbname>   # 添加业务数据库：./pgsql-db.yml -l <cls> -e dbname=<db>
bin/redis-add  <cls>            # 初始化 Redis 集群：./redis.yml -l <cls>
bin/redis-rm   <cls>            # 移除 Redis 集群：./redis-rm.yml -l <cls>

这些脚本是对 Ansible 剧本的简单封装，让您可以更方便地执行常见操作。

剧本列表

以下是 Pigsty 中的 内置剧本，您也轻松添加自己的剧本，或者按需定制修改剧本的实现逻辑。

模块 Playbook 功能
INFRA deploy.yml 在当前节点上一键部署 Pigsty
INFRA infra.yml 在基础设施节点上初始化 Pigsty 基础设施
INFRA infra-rm.yml 从基础设施节点移除基础设施组件
INFRA cache.yml 从目标节点制作离线安装包
INFRA cert.yml 使用 Pigsty 自签名 CA 颁发证书
NODE node.yml 初始化节点，将节点调整到所需状态
NODE node-rm.yml 从 Pigsty 移除节点
PGSQL pgsql.yml 初始化 HA PostgreSQL 集群，或添加新副本
PGSQL pgsql-rm.yml 移除 PostgreSQL 集群，或移除副本
PGSQL pgsql-db.yml 向现有 PostgreSQL 集群添加新业务数据库
PGSQL pgsql-user.yml 向现有 PostgreSQL 集群添加新业务用户
PGSQL pgsql-pitr.yml 在现有 PostgreSQL 集群上执行时间点恢复
PGSQL pgsql-monitor.yml 使用本地导出器监控远程 PostgreSQL 实例
PGSQL pgsql-migration.yml 为现有 PostgreSQL 生成迁移手册和脚本
PGSQL slim.yml 安装最小组件的 Pigsty
REDIS redis.yml 初始化 Redis 集群/节点/实例
REDIS redis-rm.yml 移除 Redis 集群/节点/实例
ETCD etcd.yml 初始化 ETCD 集群，或扩容新成员
ETCD etcd-rm.yml 移除 ETCD 集群与数据，或移除现有成员缩容
MINIO minio.yml 初始化 Silo 对象存储集群
MINIO minio-rm.yml 移除 Silo、配置与可选数据
DOCKER docker.yml 在节点上安装 Docker
DOCKER app.yml 使用 Docker Compose 安装应用程序
JUICE juice.yml 安装与配置 JuiceFS
VIBE vibe.yml 安装 Vibe 编码环境
KAFKA kafka.yml 创建或收敛 Kafka dynamic KRaft 集群
KAFKA kafka-rm.yml 移除 Kafka 集群或成员
MYSQL（试点） mysql.yml 部署原生 MySQL 8.4 单节点或三节点集群
MYSQL（试点） mysql-rm.yml 停止并退役原生 MySQL，保留本地状态