部署

• 1: 生产部署
• 2: 资源准备
• 3: 架构规划
• 4: 管理机制
• 5: 沙箱环境
• 6: Vagrant
• 7: Terraform
• 8: 安全考量

1 - 生产部署

本文是 Pigsty 生产环境多节点部署指南，部署单机版本 Demo/Dev 环境可以参考 快速上手 文档。

摘要

准备 几台 具有 SSH 权限 的 节点， 安装 兼容的 Linux 系统，使用具有免密 ssh 和 sudo 权限的 管理用户 执行：

• pigsty.cc（中国）
• pigsty.io（全球）

curl -fsSL https://repo.pigsty.cc/get | bash;

curl -fsSL https://repo.pigsty.io/get | bash;

该命令会执行 安装 脚本，下载并提取 Pigsty 源码至家目录并安装依赖，接下来依次完成 配置 与 部署 即可完成交付。

在执行 deploy.yml 进行部署前，您可能需要进一步审视与编辑 配置清单：pigsty.yml 文件，确认部署细节。

cd ~/pigsty      # 进入 Pigsty 目录
./configure -g   # 生成配置文件（可选，如果知道如何配置可以跳过）
./deploy.yml     # 执行部署剧本，根据生成的配置文件开始安装

安装完成后，您可以通过 IP / 域名 + 80/443 端口访问 Web 用户界面， 并通过 5432 端口访问 PostgreSQL 服务。

完整流程根据服务器规格/网络条件需 3~10 分钟，离线安装 时能够显著加速；无需监控时可使用 精简安装 进一步加速。

视频样例：20 节点生产仿真环境（Ubuntu 24.04 x86_64）

准备

在生产环境中部署安装 Pigsty 涉及一些 准备工作，以下为完整检查清单，供您参考。

安装

您可以使用以下命令自动安装 Pigsty 源码包 至 ~/pigsty 目录（推荐），部署所需依赖（Ansible）会自动安装。

• pigsty.cc（中国）
• pigsty.io（全球）

curl -fsSL https://repo.pigsty.cc/get | bash            # 安装当前默认版本
curl -fsSL https://repo.pigsty.cc/get | bash -s v4.4.0  # 安装特定版本

curl -fsSL https://repo.pigsty.io/get | bash            # 安装当前默认版本
curl -fsSL https://repo.pigsty.io/get | bash -s v4.4.0  # 安装特定版本

如果您不希望执行远程脚本，可以手动 下载 或克隆源码。使用 git 克隆安装时，请务必检出特定版本后再使用。

git clone https://github.com/pgsty/pigsty; cd pigsty;
git checkout v4.4.0;  # 使用 git 安装时，请务必检出特定版本

手工下载克隆安装时，请额外执行 bootstrap 脚本以手动安装 Ansible 等部署依赖，您也可以 自行安装。

./bootstrap           # 安装 ansible，用于执行后续部署

配置

在 Pigsty 中，部署的蓝图细节由 配置清单 所定义，也就是 pigsty.yml 配置文件，您可以通过声明式配置进行定制。

Pigsty 提供了 configure 脚本作为可选的 配置向导， 它将根据您的环境和输入，生成具有良好默认值的 配置清单：

./configure -g                # 使用配置向导生成配置文件，并且生成随机密码

配置过程生成的配置文件默认位于：~/pigsty/pigsty.yml，您可以在安装前进行检查，按需修改与定制。

有许多 配置模板 供您参考与使用，但您也完全可以跳过配置向导，直接编辑 pigsty.yml 配置文件进行定制。

./configure -c ha/full -g       # 使用四节点沙箱环境模板
./configure -c ha/trio -g       # 使用三节点最小 HA 模板
./configure -c ha/dual -g -v 18 # 使用两节点半高可用模板，使用 PG 18
./configure -c ha/simu -s       # 使用二十节点生产仿真模板，不检查 IP，不生成随机强密码

vagrant@meta:~/pigsty$ ./configure
configure pigsty v4.4.0 begin
[ OK ] region = china
[ OK ] kernel  = Linux
[ OK ] machine = x86_64
[ OK ] package = deb,apt
[ OK ] vendor  = ubuntu (Ubuntu)
[ OK ] version = 22 (22.04)
[ OK ] sudo = vagrant ok
[ OK ] ssh = vagrant@127.0.0.1 ok
[WARN] Multiple IP address candidates found:
    (1) 192.168.121.38	    inet 192.168.121.38/24 metric 100 brd 192.168.121.255 scope global dynamic eth0
    (2) 10.10.10.10	    inet 10.10.10.10/24 brd 10.10.10.255 scope global eth1
[ OK ] primary_ip = 10.10.10.10 (from demo)
[ OK ] admin = vagrant@10.10.10.10 ok
[ OK ] mode = meta (ubuntu22.04)
[ OK ] locale  = C.UTF-8
[ OK ] ansible = ready
[ OK ] pigsty configured
[WARN] don't forget to check it and change passwords!
proceed with ./deploy.yml

配置向导只会为您替换 当前节点 的 IP（如果您不想要替换，使用 -s 参数），所以对于一个多节点的部署，您需要自己替换其他节点的 IP 地址。 同时，你还需要按需对配置文件进行进一步的定制，例如修改默认密码、添加更多节点等。

配置脚本常用参数：

如果您的机器网卡绑定了多个 IP 地址，那么需要使用 -i|--ip <ipaddr> 显式指定一个当前节点的首要 IP 地址，或在交互式问询中提供。 该脚本将把 IP 占位符 10.10.10.10 替换为当前节点的主 IPv4 地址。选用的地址应为静态 IP 地址，请勿使用公网 IP 地址。

配置过程生成的配置文件默认位于：~/pigsty/pigsty.yml，您可以在安装前进行检查与修改定制。

部署

Pigsty 的 deploy.yml 剧本 会将 配置 中生成的蓝图应用至 所有的目标节点。

./deploy.yml     # 一次性在所有节点上完成部署

......

TASK [pgsql : pgsql init done] *************************************************
ok: [10.10.10.11] => {
    "msg": "postgres://10.10.10.11/postgres | meta  | dbuser_meta dbuser_view "
}
......

TASK [pg_monitor : load grafana datasource meta] *******************************
changed: [10.10.10.11]

PLAY RECAP *********************************************************************
10.10.10.11                : ok=302  changed=232  unreachable=0    failed=0    skipped=65   rescued=0    ignored=1
localhost                  : ok=6    changed=3    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

界面

假设您使用 四节点 部署模版，那么 Pigsty 部署完成后，您的环境应该具有类似下面的部署结构：

INFRA 模块通过浏览器提供了一个 图形化管理界面，您可以直接通过这台节点上的 Nginx 的 80/443 端口访问。

PGSQL 模块提供了一个 PostgreSQL 数据库服务器，监听 5432 端口，也可通过 Pgbouncer / HAProxy 代理访问。

对于生产环境的多节点高可用 PostgreSQL 集群来说，您需要通过 服务接入 来使用数据库服务，实现流量自动路由。

更多

安装完成后，您可以探索 用户界面，并通过 5432 端口访问 PostgreSQL 服务。

您还可以使用 Pigsty 部署和监控 更多集群：向 配置清单 添加定义并运行：

bin/node-add   pg-test      # 将集群 pg-test 的 3 个节点纳入 Pigsty 管理
bin/pgsql-add  pg-test      # 初始化一个 3 节点的 pg-test 高可用 PG 集群
bin/redis-add  redis-ms     # 初始化 Redis 集群： redis-ms

大多数模块都需要先安装 NODE 模块。查看可用的 模块 了解详情：

PGSQL、INFRA、NODE、ETCD、 MINIO、REDIS、FERRET、DOCKER……

2 - 资源准备

Pigsty 运行在节点（物理机或虚拟机）之上，本文档介绍硬件相关的规划与准备。

节点

Pigsty 目前运行在 Linux 内核和 x86_64 / aarch64 架构的节点上。 "节点" 指的是 SSH 可访问 且提供裸 Linux 操作系统环境的资源。 它可以是物理机、虚拟机或配备 systemd、sudo 和 sshd 的类似操作系统的容器。

部署 Pigsty 至少需要 1 个节点，您可以准备更多，并在 执行部署剧本 中一次性部署所有节点，或稍后添加并单独部署。 最小节点规格要求是 1C1G，建议至少使用 1C2G。越高越好，没有上限。系统参数将根据可用资源自动调优。

所需节点的数量，取决于您的需求，更多详情请参考 架构规划。 尽管带有 外部备份 的 单机部署 也提供一定程度上的兜底， 但我们建议在生产部署中使用复数个节点，起作用的 高可用配置 至少需要 3 个节点才能工作，2 个节点则提供 半高可用。

磁盘

Pigsty 将使用 /data 作为默认数据目录，如果您有专用的主数据磁盘，建议将其挂载到那里，并为额外的磁盘驱动器使用 /data1、/data2、/dataN。 如果你想使用其他的数据目录，可以通过以下参数进行配置：

文件系统

您可以使用任何支持的 Linux 文件系统来格式化数据磁盘，但对于生产环境部署，我们建议使用 xfs。

xfs 是 linux 的标配之一，提供了最佳的性能，便利的 CoW 机制，允许你瞬间克隆大型数据库集群。使用 MinIO 时，必须使用 xfs 文件系统。 ext4 是另一个可用的选择，但缺乏 CoW 功能，但有着更为丰富的数据恢复工具生态。zfs 可以提供 RAID，快照功能，但性能折损较大且需要单独安装。 我们推荐您在这三种文件系统中按需权衡，择一使用。

如果有特殊需求，您也可以使用其他文件系统，但我们强烈不建议使用 NFS 网络文件系统来运行数据库服务。

Pigsty 的工作假设是 /data 目录属于 root:root，权限为 755。 管理员可以分配一级目录的所有权和权限。每个应用在其子目录中运行时将使用专用用户。 Pigsty 使用的目录结构说明，请参考 FHS 文档说明。

网络

Pigsty 默认使用在线安装模式，需要出站互联网访问。 使用 离线安装 模式则不再需要互联网访问。

在内网中，Pigsty 需要 静态网络 才能工作，您应该为每个节点明确分配一个 固定的 IPv4 地址。

IP 地址将用作节点的 唯一标识符，它应该是绑定到用于 内部 网络通信的主网络接口的主 IP 地址。

作为特例，单机部署 时如果没有固定 IP 地址，可以使用本地环回地址 127.0.0.1 作为变通。

VIP

Pigsty 支持 NODE 集群（keepalived）和 PGSQL 集群（vip-manager）的可选 L2 VIP。

要使用 L2 VIP 功能，您必须为节点集群/数据库集群明确分配指定一个 L2 VIP 地址。 在您自己的硬件上运行时这不是大问题，但在公有云环境中工作时可能成为问题。

CA

Pigsty 默认为每一套部署生成一套自签名的 CA 基础设施，用于签发环境中所有的加密证书。

如果您已经有了正规的企业 CA，或者已经有了自签名的 CA，您也可以选择使用已有的 CA 来签发 Pigsty 所需的证书。

域名

Pigsty 默认使用一个本地静态域名 i.pigsty 来访问 WebUI，这是可选的，你也可以直接使用 IP 地址访问。

对于生产环境部署来说，建议您使用域名来访问服务，只有使用域名，才能启用 HTTPS 支持，加密您的数据传输。 同时，域名访问允许您在同一个端口上运行多种不同的服务，并通过不同的域名进行区分。

如果您的部署提供 互联网访问，那么可以使用公共 DNS 供应商（如 Cloudflare、阿里云 DNS、AWS Route53 等）来管理您的域名解析。 将您的域名指向 Pigsty 节点的 公网 IP 地址 即可。 如果您的部署针对 局域网/办公网 开放，那么可以使用内部 DNS 服务器来管理域名解析。 将您的域名指向 Pigsty 节点的 办公网 IP 地址 即可。

如果您的访问仅限于本机，或特定的几台机器，那么可以使用本地静态解析来管理域名解析。 将以下记录添加到（用于访问 Pigsty WebUI 的机器） /etc/hosts 文件（本地静态解析）中，即可从浏览器中访问。

10.10.10.10 i.pigsty    # 替换为您计划使用的域名，与 Pigsty 节点的 IP 地址

Linux

Pigsty 运行在 Linux 操作系统上，它支持 14 种主流 Linux 发行版：兼容操作系统列表

我们推荐使用 RockyLinux 10.1、Debian 13.5 或 Ubuntu 26.04.0 / 24.04.4 作为默认操作系统选项。

在 MacOS 和 Windows 上，您可以用各种虚拟机软件或者 Docker systemd 镜像来安装 Pigsty。

我们 强烈建议 使用全新安装的操作系统环境，如果您的服务器已经运行了 Nginx / PostgreSQL 等服务，请考虑使用新的节点进行部署。

Locale

我们建议您将 en_US 设置为操作系统的主要语言，至少确保该 Locale 可用，从而确保 PG 日志打印英文。

一些发行版可能默认没有提供 en_US 区域设置，例如 Debian。使用以下命令启用 en_US 区域设置：

localedef -i en_US -f UTF-8 en_US.UTF-8
localectl set-locale LANG=en_US.UTF-8

对于 PostgreSQL 来说，我们强烈建议您默认使用 PG 17+ 内置的 C.UTF-8 作为默认排序规则。

在 配置向导 中如果检测到 PG 版本满足或者操作系统支持，就默认配置 C.UTF-8 作为排序规则。

Ansible

Pigsty 使用 Ansible 从管理节点发起对所有被管理节点的控制， 安装 Ansible 会介绍更多细节。

Pigsty 默认会在 Infra 节点上安装 Ansible，所以 Infra 节点是可以作为管理节点（或备用管理节点）使用。 在 单机部署 的时候，您当前执行安装的节点，既是运行 ansible 管理命令的 管理节点，也是部署基础设施的 INFRA节点。

Pigsty

您可以使用以下方式 安装 最新稳定版本的 Pigsty 源代码：

• pigsty.cc（中国）
• pigsty.io（全球）

curl -fsSL https://repo.pigsty.cc/get | bash;

curl -fsSL https://repo.pigsty.io/get | bash;

要 安装 最新特定版本的 Pigsty，可以使用 -s <version> 参数：

• pigsty.cc（中国）
• pigsty.io（全球）

curl -fsSL https://repo.pigsty.cc/get | bash -s <version>  # 安装特定版本（示例：v4.4.0）

curl -fsSL https://repo.pigsty.io/get | bash -s <version>  # 安装特定版本（示例：v4.4.0）

要 安装 最新 Beta 版本的 Pigsty 源代码，可以使用 beta 脚本：

• pigsty.cc（中国）
• pigsty.io（全球）

curl -fsSL https://repo.pigsty.cc/beta | bash;

curl -fsSL https://repo.pigsty.io/beta | bash;

如果你是开发者，或者想要获取最新的开发版本，可以直接 git 克隆 Pigsty 代码仓库：

git clone https://github.com/pgsty/pigsty.git;
cd pigsty; git checkout <tag>  # 使用特定版本（示例：v4.4.0）

如果您的环境没有互联网访问，也可以直接从 GitHub Release 页面，或者 Pigsty 仓库下载源码包：

wget https://repo.pigsty.cc/src/pigsty-v<version>.tgz
wget https://repo.pigsty.io/src/pigsty-v<version>.tgz

3 - 架构规划

Pigsty 采用 模块化架构，您可以像搭积木一样组合出自己想要的部署方案，并用简单的 声明式配置 表达您的意图。

常见方案

这里有一些常见的组合模式供您参考，您可以根据自己的需求进行进一步的定制与调整：

使用什么样的架构规划方案，取决于您对数据库可靠性的要求，以及手头可用的资源。 通常来说，严肃的生产环境部署至少需要 3 个节点以实现 高可用配置。 如果您只有 2 个节点，则可以使用 半高可用配置。

利弊权衡

• 若要使用 Pigsty 的监控系统，则至少需要 1 个 INFRA 节点，生产部署通常使用 2 个，大规模部署 3 个。
• 若要启用 PG 高可用，则至少需要 1 个 ETCD 节点，生产部署通常使用 3 个，大规模环境中 5 个，须奇数个。
• 若要启用对象存储（MinIO），则至少需要 1 个 MINIO 节点，严肃使用时通常使用 4+ 节点部署 MNMD 集群。
• PG 生产集群通常至少为两节点主从配置；严肃场景通常使用 3 节点；高只读负载可以有更多从库（几十个）
• 此外对于 PostgreSQL 来说，您还可以按需使用 离线实例，同步实例，备份集群，延迟集群等等高级配置。

单节点配置

最简单的配置，所有内容都在单个节点上运行，默认安装四个基本模块，通常用于 Demo，Devbox，或测试环境。

如果为备份/PITR 配置了外部 S3 / MinIO 备份仓库 提供兜底的 RTO/RPO，此配置亦可用于普通标准的生产环境。

单节点配置有多种变体：

• 充血版（rich）：生产版本的单机部署模版，带有本地 MinIO 对象存储，使用本地软件仓库，下载所有 PG 扩展。
• 瘦身版（slim）：只安装 PGSQL 和 ETCD，不安装监控设施 —— 精简安装 也可以扩充为 多节点高可用部署
• 监控版（infra）：与 slim 相反，只安装 INFRA 监控基础设施，不安装数据库服务，只用来监控其他实例。
• 内核替换：用衍生分支 pgsql、mssql、polar、ivory、mysql、pgtde、oriole、agens、pgedge 替换原生 PG

双节点配置

双节点配置 将启用数据库复制和 半高可用 能力，提供更好的数据冗余，以及有限的故障转移支持：

双节点配置的高可用自动切换机制有限制，这种"半 HA"设置只能从特定节点故障中自动恢复：

• 如果 node-1 故障，无自动故障转移：需要手动提升 node-2
• 如果 node-2 故障，自动故障转移有效：node-1 自动提升

三节点配置

三节点模板 提供真正的基础高可用配置，可以容忍任意一个节点的故障，并从中自动恢复。

四节点配置

Pigsty 沙箱环境 使用的 标准四节点配置。

在这里我们出于演示目的，不配置 INFRA / ETCD 模块的高可用，您也可以对其进行进一步的调整

更多节点

如果您有着完善的虚拟化设施或充足的资源，完全可以 使用更多的节点，让每个模块都采用 独占式部署，从而获得最佳的可靠性，可观测性与性能表现。

4 - 管理机制

Pigsty 需要一个在所有被管理节点上具有免密 SSH 和 Sudo 权限的操作系统 管理用户。

这个用户需要能够通过 ssh 访问到所有被管理节点，并且能够在这些节点上执行 sudo 命令。

要想将节点纳入 Pigsty 中管理，

用户

通常我们会选择 dba 或 admin 这样的用户名称，并避免使用 root 与 postgres：

• 使用 root 进行部署是可行的，但不符合生产最佳实践。
• 使用 postgres （pg_dbsu）作为管理员用户是严格禁止的。

免密码

如果您可以接受为每个 ssh 和 sudo 命令输入密码，则免密码要求是可选的。

您可以在 执行剧本 时使用 -k|--ask-pass 来提示输入 SSH 密码， 以及 -K|--ask-become-pass 来提示输入 sudo 密码。

./deploy.yml -k -K

一些企业的安全策略可能不允许免密 ssh 或 sudo，在这种情况下，您可以使用上述选项。

或者考虑配置一个 sudo 密码缓存时间较长的 sudoers 规则，以减少密码提示的频率。

创建管理员用户

通常，您的服务器/虚拟机供应商会为您创建一个初始管理员用户。

如果你对这个用户不满意，Pigsty 的部署剧本可以为你创建一个 新的管理员用户。

假设您在节点上有 root 权限，或有一个现有的管理员用户，您可以使用 Pigsty 本身创建管理员用户：

./node.yml -k -K -t node_admin \
  -e ansible_user=[当前可登录的管理员名称] \
  -e node_admin_username=[你准备创建的管理员名称]

它将利用现有的管理员创建新的管理员，创建由以下参数描述的专用 dba（uid=88）用户，并正确配置 sudo / ssh。

Sudo

所有 管理员用户 都应该在所有被管理节点上具有 sudo 权限【最好带有免密码执行权限】。

如果您想从头开始配置具有免密 sudo 权限的管理员用户，可以编辑/创建 suoder 文件（假设用户名为 vagrant）：

echo '%vagrant ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/vagrant

假设您的管理员用户名选择是 dba，那么 /etc/sudoers.d/dba 内容应该是：

%dba ALL=(ALL) NOPASSWD: ALL

如果您的安全策略不允许免密码 sudo，请将 NOPASSWD: 部分删除：

%dba ALL=(ALL) ALL

Ansible 依赖 sudo 在被管理节点上以 root 权限执行命令。 在 sudo 不可用的环境中（比如 Docker 容器内）需要先安装 sudo 才能正确部署。

SSH

您的当前用户应该能够以相应的管理员用户身份免密 SSH 访问所有被管理节点。

您的当前用户可以是管理员用户本身，但不是必需的，只要您能以管理员用户身份 SSH。

SSH 配置是 Linux 101，但我们会在此处介绍基础知识，以防您不熟悉：

生成 SSH 密钥

如果您没有 SSH 密钥对，请生成一个：

ssh-keygen -t rsa -b 2048 -N '' -f ~/.ssh/id_rsa -q

如果您没有密钥对，Pigsty 会在 bootstrap 阶段为您完成此操作。

复制 SSH 密钥

您需要将生成的公钥分发到远程（和本地）服务器，并将其放入所有节点上管理员用户的 ~/.ssh/authorized_keys 文件中。 可以使用 ssh-copy-id 工具。

ssh-copy-id <ip>                        # 交互式密码输入
sshpass -p <password> ssh-copy-id <ip>  # 非交互式（谨慎使用）

使用别名

当无法直接 SSH 访问时（由于跳板机、其他端口、凭据等），考虑在 ~/.ssh/config 中配置 SSH 别名：

Host meta
    HostName 10.10.10.10
    User dba                      # 远程上不同的用户
    IdentityFile /etc/dba/id_rsa  # 不是普通密钥
    Port 24                       # 不是众所周知的端口

并在清单中引用别名，使用 ansible_host 指定真实的 SSH 别名：

nodes:
  hosts:          # 如果节点 `10.10.10.10` 需要 SSH 别名 `meta`
    10.10.10.10: { ansible_host: meta }  # 通过 `ssh meta` 访问

SSH 参数可以直接在 Ansible 中使用，详情请查看 Ansible Inventory Guide。 通过这种技术，您可以使用跳板机访问私有网络中的节点，或者使用不同的端口和凭据访问节点。 或者是利用本地笔记本作为管理节点。

验证可达性

您应该能够从管理节点通过当前用户免密 ssh 访问所有被管理节点。 远程用户（管理员用户）应该有权限运行免密 sudo 命令。 要验证免密 ssh sudo 是否工作，在管理节点上对所有被管理节点运行此命令：

ssh <ip|alias> 'sudo ls'

如果没有密码提示或错误，免密 ssh/sudo 按预期工作。

防火墙

在生产环境部署时，通常需要设置防火墙，以阻止未经授权的端口访问。

默认情况下，你可以阻断办公网/互联网对节点的入站访问，只开放下列端口：

• 要通过 ssh 访问节点，您必须允许 SSH 端口 22 入站访问。
• 要访问 WebUI 服务，您必须允许 HTTP（80）/ HTTPS（443）入站访问。
• 要访问 PostgreSQL 数据库服务，您必须允许 PostgreSQL 的 5432 入站访问。

如果您通过其他端口访问 PostgreSQL 服务，请相应地允许它们。 Pigsty 组件使用的端口列表，请参考：使用的端口。

• 5432：PostgreSQL 数据库
• 6432：Pgbouncer 连接池
• 5433：PG 主要服务
• 5434：PG 副本服务
• 5436：PG 默认服务
• 5438：PG 离线服务

5 - 沙箱环境

Pigsty 提供了一个标准的四节点 沙箱环境，用于学习、测试与功能演示。

沙箱使用固定的 IP 地址和预定义的身份标识符，便于复现各种演示用例。

环境描述

默认的沙箱环境由 4 个节点组成，默认使用配置文件 ha/full.yml。

沙箱的配置可以概括表示为以下配置文件：

all:
  children:
    infra: { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:  { hosts: { 10.10.10.10: { etcd_seq:  1 } }, vars: { etcd_cluster: etcd } }
    minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }

    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:  { pg_cluster: pg-meta }

    pg-test:
      hosts:
        10.10.10.11: { pg_seq: 1, pg_role: primary }
        10.10.10.12: { pg_seq: 2, pg_role: replica }
        10.10.10.13: { pg_seq: 3, pg_role: replica }
      vars: { pg_cluster: pg-test }

  vars:
    version: v4.4.0
    admin_ip: 10.10.10.10
    region: default
    pg_version: 18

PostgreSQL 集群

沙箱带有一个位于 meta 节点上的单实例 PostgreSQL 集群 pg-meta：

10.10.10.10 meta pg-meta-1
10.10.10.2  pg-meta          # 可选的 L2 VIP

沙箱中还有一个由三个实例组成的 PostgreSQL 高可用集群 pg-test，部署在另外三个节点上：

10.10.10.11 node-1 pg-test-1
10.10.10.12 node-2 pg-test-2
10.10.10.13 node-3 pg-test-3
10.10.10.3  pg-test          # 可选的 L2 VIP

两个可选的 L2 VIP 分别绑定在 pg-meta 和 pg-test 集群的主实例上。

基础设施

在 meta 节点上还部署有：

• ETCD 集群：单节点 etcd 集群，为 PostgreSQL HA 提供 DCS 服务
• MinIO 集群：单节点 minio 集群，提供 S3 兼容的对象存储服务

10.10.10.10 etcd-1
10.10.10.10 minio-1

创建沙箱

Pigsty 提供了开箱即用的模板，您可以使用 Vagrant 在本地创建沙箱，或使用 Terraform 在云上创建沙箱。

当然，您也可以自己手工准备并置备这些节点。

本地沙箱（Vagrant）

本地沙箱使用 VirtualBox/libvirt 创建本地虚拟机，可以在您的 Mac / PC 上免费运行。

运行完整的 4 节点沙箱，您的机器应至少拥有 4 核 CPU 与 8GB 内存。

cd ~/pigsty
make full       # 使用默认 Ubuntu 24.04 镜像创建 4 节点沙箱
make full9      # 使用 RockyLinux 9 创建 4 节点沙箱
make full12     # 使用 Debian 12 创建 4 节点沙箱
make full24     # 使用 Ubuntu 24.04 创建 4 节点沙箱
make full26     # 使用 Ubuntu 26.04 创建 4 节点沙箱

Pigsty v4.4 统一使用 Vagrant Cloud 上的 cloud-image/* Box。下表列出 4 节点本地沙箱可使用的 VirtualBox/libvirt 镜像版本。

VirtualBox

libvirt

更多详情请参考 Vagrant 文档。

云沙箱（Terraform）

云沙箱使用公有云 API 创建虚拟机，可以轻松创建和销毁，按需付费，非常适合快速测试。

使用 spec/aliyun-full.tf 模板在阿里云上创建 4 节点沙箱：

cd ~/pigsty/terraform
cp spec/aliyun-full.tf terraform.tf
terraform init
terraform apply

更多详情请参考 Terraform 文档。

其他规格

除了标准的 4 节点沙箱，Pigsty 还提供了其他规格的环境：

单节点开发箱（meta）

最简单的 1 节点环境，用于快速上手、开发和测试：

make meta       # 创建单节点开发箱

双节点环境（dual）

2 节点环境，用于测试主从复制：

make dual       # 创建 2 节点环境

三节点环境（trio）

3 节点环境，用于测试基本高可用：

make trio       # 创建 3 节点环境

生产仿真环境（simu）

20 节点的大型仿真环境，用于模拟生产环境进行完整测试：

make simu       # 创建 20 节点生产仿真环境

该环境包含：

• 3 个基础设施节点（meta1, meta2, meta3）
• 2 个 HAProxy 代理节点
• 4 个 MinIO 节点
• 5 个 ETCD 节点
• 6 个 PostgreSQL 节点（2 个集群，每个 3 节点）

6 - Vagrant

Vagrant 是一个流行的本地虚拟化工具，可以按照声明式的方式创建本地虚拟机。

Pigsty 需要 Linux 环境运行，您可以使用 Vagrant 轻松在本地创建 Linux 虚拟机进行测试。

安装依赖

首先，确保您的系统中已经安装了 Vagrant 和虚拟机软件（VirtualBox， libvirt，Hyper-V，Parallel，……）。

在 MacOS 上，您可以使用 Homebrew 一键安装 vagrant 与 virtualbox； 在 Linux 上，您可以使用 VirtualBox 或 vagrant-libvirt 作为虚拟机管理软件； 在 Windows 专业版上，可以使用 VirtualBox 与 Hyper-V 作为提供商。

• macOS
• 安装 Homebrew

brew install vagrant virtualbox ansible
# 安装 VirtualBox 后需要重启系统，并在系统偏好设置中允许其内核扩展。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

创建虚拟机

使用 Pigsty 提供的 make 快捷方式创建虚拟机：

cd ~/pigsty

make meta       # 1 节点开发箱，用于快速上手、开发和测试
make full       # 4 节点沙箱，用于高可用测试和功能演示
make simu       # 20 节点仿真环境，用于生产环境模拟

# 其他不常用的规格
make dual       # 2 节点环境
make trio       # 3 节点环境
make deci       # 10 节点环境

您可以使用变体别名指定不同的操作系统镜像：

make meta9      # 使用 RockyLinux 9.7 创建单节点
make full12     # 使用 Debian 12.14 创建 4 节点沙箱
make simu24     # 使用 Ubuntu 24.04.4 创建 20 节点仿真环境
make full26     # 使用 Ubuntu 26.04.0 创建 4 节点沙箱

可用的操作系统后缀：8（EL8）、9（EL9）、10（EL10）、12（Debian 12.14）、13（Debian 13.5）、22（Ubuntu 22.04.5）、24（Ubuntu 24.04.4）、26（Ubuntu 26.04.0）

构建环境

您还可以使用以下别名创建 Pigsty 构建环境，这些模板不会替换基础镜像：

make oss        # 4 节点 OSS 构建环境
make pro        # 6 节点 PRO 构建环境
make rpm        # 2 节点 EL9/10 构建环境
make deb        # 5 节点 Debian12/13 Ubuntu22/24/26 构建环境
make all        # 7 节点全量构建环境

规格配置

Pigsty 在 vagrant/spec/ 目录下提供了多种预定义的虚拟机规格：

每个规格文件包含一个描述虚拟机节点的 Specs 变量。例如，full.rb 包含 4 节点沙箱的定义：

# full: pigsty full-featured 4-node sandbox for HA-testing & tutorial & practices

Specs = [
  { "name" => "meta"   , "ip" => "10.10.10.10" ,  "cpu" => "2" ,  "mem" => "4096" ,  "image" => "cloud-image/ubuntu-24.04" },
  { "name" => "node-1" , "ip" => "10.10.10.11" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "cloud-image/ubuntu-24.04" },
  { "name" => "node-2" , "ip" => "10.10.10.12" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "cloud-image/ubuntu-24.04" },
  { "name" => "node-3" , "ip" => "10.10.10.13" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "cloud-image/ubuntu-24.04" },
]

simu 规格详情

simu.rb 提供了一个 20 节点的生产环境仿真配置：

• 3 x infra 节点（meta1-3）：4c16g
• 2 x haproxy 节点（proxy1-2）：1c2g
• 4 x minio 节点（minio1-4）：1c2g
• 5 x etcd 节点（etcd1-5）：1c2g
• 6 x pgsql 节点（pg-src-1-3，pg-dst-1-3）：2c4g

配置脚本

使用 vagrant/config 脚本可以根据规格和选项生成最终的 Vagrantfile：

cd ~/pigsty
vagrant/config [spec] [image] [scale] [provider]

# 示例
vagrant/config meta u24            # 使用 1 节点规格，Ubuntu 24.04.4 镜像
vagrant/config dual el9            # 使用 2 节点规格，RockyLinux 9.7 镜像
vagrant/config trio d12 2          # 使用 3 节点规格，Debian 12.14 镜像，双倍资源
vagrant/config full u22 4          # 使用 4 节点规格，Ubuntu 22.04.5 镜像，4 倍资源
vagrant/config simu u26 1 libvirt  # 使用 20 节点规格，Ubuntu 26.04.0 镜像，libvirt 提供商

镜像别名

config 脚本支持多种镜像别名：

资源缩放

您可以使用环境变量 VM_SCALE 来调整资源倍数，默认值为 1：

VM_SCALE=2 vagrant/config meta     # 将 meta 规格的 CPU/内存资源翻倍

例如，使用 VM_SCALE=4 配置 meta 规格，会将默认的 2c4g 调整为 8c16g：

Specs = [
  { "name" => "meta" , "ip" => "10.10.10.10", "cpu" => "8" , "mem" => "16384" , "image" => "cloud-image/ubuntu-24.04" },
]

虚拟机管理

Pigsty 提供了一系列 Makefile 快捷方式来管理虚拟机：

make           # 等于 make start
make new       # 销毁现有虚拟机，创建新的虚拟机
make ssh       # 将虚拟机 SSH 配置写入 ~/.ssh/（创建后必须执行）
make dns       # 将虚拟机 DNS 记录写入 /etc/hosts（可选）
make start     # 启动虚拟机并配置 SSH（up + ssh）
make up        # 使用 vagrant up 启动虚拟机
make halt      # 关闭虚拟机（别名：down, dw）
make clean     # 销毁虚拟机（别名：del, destroy）
make status    # 显示虚拟机状态（别名：st）
make pause     # 暂停虚拟机（别名：suspend）
make resume    # 恢复虚拟机
make nuke      # 使用 virsh 销毁所有虚拟机和卷（仅 libvirt）
make info      # 显示 libvirt 信息（虚拟机、网络、存储卷）

SSH 密钥

Pigsty Vagrant 模板默认使用您的 ~/.ssh/id_rsa[.pub] 作为虚拟机的 SSH 密钥。

在开始之前，请确保您有一个有效的 SSH 密钥对。如果没有，可以使用以下命令生成：

ssh-keygen -t rsa -b 2048 -N '' -f ~/.ssh/id_rsa -q

支持的镜像

Pigsty 统一使用 Vagrant Cloud 上的 cloud-image/* Box，VirtualBox 与 libvirt 均提供 amd64 / arm64 架构版本。

VirtualBox

libvirt

环境变量

您可以使用以下环境变量来控制 Vagrant 行为：

export VM_SPEC='meta'              # 规格名称
export VM_IMAGE='cloud-image/rocky-9' # 镜像名称
export VM_SCALE='1'                # 资源缩放倍数
export VM_PROVIDER='virtualbox'    # 虚拟化提供商
export VAGRANT_EXPERIMENTAL=disks  # 启用实验性磁盘功能

注意事项

echo "* 10.0.0.0/8" | sudo tee -a /etc/vbox/networks.conf

7 - Terraform

Terraform 是一个流行的"基础设施即代码"工具，您可以使用它在公有云上一键创建虚拟机。

Pigsty 提供了阿里云、AWS、腾讯云的 Terraform 模板作为示例。

快速开始

安装 Terraform

在 macOS 上，您可以使用 Homebrew 安装 Terraform：

brew install terraform

其他平台请参考 Terraform 官方安装指南。

初始化与应用

进入 Terraform 目录，选择模板，初始化提供商插件，然后应用配置：

cd ~/pigsty/terraform
cp spec/aliyun.tf terraform.tf         # 选择模板
terraform init                         # 安装云提供商插件（首次使用时）
terraform apply                        # 生成执行计划并创建资源

运行 apply 命令后，按提示输入 yes 确认，Terraform 将为您创建虚拟机及相关云资源。

获取 IP 地址

创建完成后，打印管理节点的公网 IP 地址：

terraform output | grep -Eo '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}'

配置 SSH 访问

使用 ssh 脚本自动配置 SSH 别名并分发密钥：

./ssh    # 写入 SSH 配置到 ~/.ssh/pigsty_config 并复制密钥

此脚本会将 Terraform 输出的 IP 地址写入 ~/.ssh/pigsty_config，并使用默认密码 PigstyDemo4 自动分发 SSH 密钥。

配置完成后，您可以直接使用主机名登录：

ssh meta    # 使用主机名而非 IP 登录

Include ~/.ssh/pigsty_config

销毁资源

测试完成后，可以一键销毁所有创建的云资源：

terraform destroy

模板规格

Pigsty 在 terraform/spec/ 目录下提供了多种预定义的云资源模板：

使用模板时，将模板文件复制为 terraform.tf：

cd ~/pigsty/terraform
cp spec/aliyun-full.tf terraform.tf   # 使用阿里云 4 节点沙箱模板
terraform init && terraform apply

变量配置

Pigsty 的 Terraform 模板使用变量来控制架构、操作系统发行版和资源配置：

架构与发行版

variable "architecture" {
  description = "架构类型 (amd64 或 arm64)"
  type        = string
  default     = "amd64"    # 注释此行以使用 arm64
  #default     = "arm64"   # 取消注释以使用 arm64
}

variable "distro" {
  description = "发行版代码 (el8,el9,el10,u22,u24,u26,d12,d13)"
  type        = string
  default     = "el9"       # 默认使用 Rocky Linux 9
}

资源配置

在 locals 块中可以配置以下资源参数：

locals {
  bandwidth        = 100                    # 公网带宽 (Mbps)
  disk_size        = 40                     # 系统盘大小 (GB)
  spot_policy      = "SpotWithPriceLimit"   # 竞价策略：NoSpot, SpotWithPriceLimit, SpotAsPriceGo
  spot_price_limit = 5                      # 最高竞价价格 (仅在 SpotWithPriceLimit 时有效)
}

阿里云配置

凭证设置

将您的阿里云凭证添加到环境变量中，例如在 ~/.bash_profile 或 ~/.zshrc 中：

export ALICLOUD_ACCESS_KEY="<your_access_key>"
export ALICLOUD_SECRET_KEY="<your_secret_key>"
export ALICLOUD_REGION="cn-shanghai"

支持的镜像

以下是阿里云中常用的 ECS 公共操作系统镜像 前缀：

OSS 存储配置

aliyun-s3.tf 模板会额外创建 OSS 存储桶及相关权限，用于 PostgreSQL 的 PITR 备份：

• OSS Bucket：创建名为 pigsty-oss 的私有存储桶
• RAM 用户：创建专用的 pigsty-oss-user 用户
• 访问密钥：生成 AccessKey 并保存到 ~/pigsty.sk
• IAM 策略：授予对存储桶的完全访问权限

AWS 配置

凭证设置

设置 AWS 配置和凭证文件：

# ~/.aws/config
[default]
region = cn-northwest-1

# ~/.aws/credentials
[default]
aws_access_key_id = <YOUR_AWS_ACCESS_KEY>
aws_secret_access_key = <AWS_ACCESS_SECRET>

如果需要使用 SSH 密钥，将密钥文件放置在：

~/.aws/pigsty-key
~/.aws/pigsty-key.pub

腾讯云配置

凭证设置

将腾讯云凭证添加到环境变量中：

export TENCENTCLOUD_SECRET_ID="<your_secret_id>"
export TENCENTCLOUD_SECRET_KEY="<your_secret_key>"
export TENCENTCLOUD_REGION="ap-beijing"

快捷命令

Pigsty 提供了一些 Makefile 快捷命令用于 Terraform 操作：

cd ~/pigsty/terraform

make u          # terraform apply -auto-approve + 配置 SSH
make d          # terraform destroy -auto-approve
make apply      # terraform apply（交互式确认）
make destroy    # terraform destroy（交互式确认）
make out        # terraform output
make ssh        # 运行 ssh 脚本配置 SSH 访问
make r          # 重置 terraform.tf 到版本库状态

注意事项

ssh root@<public_ip>

8 - 安全考量

Pigsty 默认配置面向受信内网中的开发、测试和演示。生产部署需要根据实际威胁模型完成凭据、网络、认证、证书、备份和审计配置。

安全机制及其边界见 安全与合规，可执行检查项见 合规实践。ha/safe 是加固配置示例，不替代逐项审查。

机密性

重要文件

重点保护以下资产：

• pigsty.yml 与其他 inventory：通常包含系统和业务凭据；
• files/pki/ca/ca.key：可以签发受部署信任的证书；
• 管理用户 SSH 私钥：默认可以在纳管节点上执行 sudo；
• 客户端证书私钥与备份加密密钥；
• 自动化过程中生成的 /pg/tmp/pg-user-*.sql。

应限制管理节点和配置仓库访问，避免把完整配置或私钥提交到公开仓库。CA 私钥和恢复所需配置应进行受控备份。

密码

生产部署必须替换所有公开默认凭据。建议先使用：

./configure -g

该选项不会替换 pgBackRest cipher_pass、ha/safe 中的全部 MinIO 示例凭据，也不会处理用户自定义值。应按照 默认凭据 复核生成结果。

PostgreSQL 默认使用 SCRAM-SHA-256 保存新设置或更新的口令。需要强制复杂度时，在 pg_libs 中预加载 passwordcheck，或配置 credcheck。账号有效期可以通过 expire_in 或 expire_at 声明。

凭据轮换还需要同步更新数据库用户、PgBouncer 用户列表、组件配置和使用方连接信息。执行前应准备回退方案。

网络边界

IP地址

PostgreSQL 默认监听 0.0.0.0。需要收敛监听地址时，可设置：

pg_listen: '${ip},${vip},${lo}'

监听地址不是唯一边界。生产环境应同时检查：

• 云安全组或上游防火墙；
• node_firewall_public_port；
• node_firewall_intranet 是否把过大的网段视为可信；
• PostgreSQL 与 PgBouncer HBA；
• Patroni REST API 的 allowlist。

演示配置 pigsty.yml 会额外向公网放行 5432，生产环境通常应移除。需要直接连接数据库时，应限制到明确的业务网段。

网络流量

• PostgreSQL 服务端默认启用 TLS，但内网 HBA 默认不强制 TLS；
• PgBouncer TLS 默认关闭，由 pgbouncer_sslmode 控制；
• Patroni REST API HTTPS 默认关闭，由 patroni_ssl_enabled 控制；
• Nginx 与 MinIO 默认启用 HTTPS；etcd 客户端和对等通信使用 TLS。

HBA 的 auth: ssl 只要求加密连接。客户端还应使用 sslmode=verify-full 和可信 CA 验证数据库服务端，详见 加密通信。

Grafana、VictoriaMetrics 等组件可能监听节点端口，默认防火墙不会将其直接开放到公网。对外访问应优先通过 Nginx，并限制管理页面的来源地址和身份。

身份认证与访问控制

• 使用 HBA 明确用户、数据库、来源地址和认证方式，避免宽泛的 world 规则；
• 为高权限远程用户使用 auth: cert，并建立客户端证书交付与吊销流程；
• 通过 内置角色 分配业务权限，不向普通业务账号授予超级用户；
• 为多业务共享集群设置 revokeconn: true，并检查实际数据库 ACL；
• 使用声明的数据库属主或受控管理角色创建对象，确保默认权限生效；
• 需要隔离离线查询时，显式为 dbrole_offline 的 HBA 规则设置 role: offline。

变更 HBA、用户或角色后，应同时核对配置清单和数据库中的实际状态。

完整性

Pigsty 默认启用页级数据校验和，用于发现写入后发生的页面损坏。校验和不能检测所有内存错误、逻辑错误和应用写入错误。

CRIT 模板 启用 Patroni 严格同步模式和更详细的连接日志。同步模式以不丢失已确认事务为目标，但依赖 synchronous_commit、同步副本状态和故障切换条件；没有同步副本时会阻塞写入。

watchdog 在 CRIT 中配置为 automatic，只有系统存在可用 watchdog 设备时才会启用。是否需要 required 模式应结合硬件和可用性要求评估。

可用性

• 关键集群通常应至少部署三个实例，并把实例分散到独立故障域；
• 使用 HAProxy、VIP 或 DNS 服务名接入，避免客户端绑定固定主库地址；
• etcd 应使用奇数节点，并分散到独立故障域；
• INFRA、DNS、监控和软件仓库也应根据可用性要求消除单点；
• 使用 pg_rpo 和 pg_rto 时，应理解其配置含义并通过演练验证目标。

副本只解决部分节点故障，不能替代备份。

备份与恢复

• 本地 pgBackRest 仓库默认不加密，并与数据库主机共享故障域；
• MinIO 仓库默认启用 AES-256-CBC，但 cipher_pass: pgBackRest 是公开值，必须替换；
• ha/safe 中的 pgBR.${pg_cluster} 也是示例值，不应作为最终密钥；
• 重要备份应保存到独立故障域，并评估对象锁、版本控制或离线副本；
• 定期执行全量恢复和 PITR 演练，验证 WAL、密钥、恢复时间和应用一致性。

具体机制见 数据安全 与 时间点恢复；配置与操作见 PGSQL 备份恢复。

审计与响应

默认 OLTP 模板记录 DDL、慢查询和 PostgreSQL 18 的连接授权事件；CRIT 模板进一步记录连接和断开事件。

pgaudit 需要安装、预加载并配置审计策略，单纯安装软件包不会产生 SQL 审计日志。启用 Vector 和 VictoriaLogs 后，还应根据要求调整日志保留周期、访问权限与归档方式。

指标、日志和告警只提供事件输入。生产环境还需建立告警分级、值班、事件判定、响应、取证和复盘流程。

主机与软件供应链

• 根据兼容性验证结果将 SELinux 从默认 permissive 调整为 enforcing；
• 禁用不需要的 SSH 口令和 root 远程登录，并考虑堡垒机或多因素认证；
• 审查管理用户和数据库系统用户的 sudo 范围；
• 及时升级受支持的 Pigsty 和上游组件版本；
• 核对软件仓库 GPG 公钥指纹，并按需要启用逐包签名验证。

供应链与漏洞响应说明见 合规实践。