准备

• 1: 硬件置备
• 2: Linux 系统
• 3: 软件置备
• 4: 管理用户
• 5: 沙箱环境
• 6: Vagrant
• 7: Terraform

    节点、规格、磁盘、网络、VIP、域名...

    支持的 Linux 操作系统发行版列表

    区域设置、防火墙、Ansible、Pigsty...

    用户、Sudo、SSH、可访问性...

    Ansible 101，pigsty 用户的基础知识

    用于学习和测试的四节点沙盒

    使用 vagrant 置备本地虚拟机

    使用 terraform 置备云服务器

1 - 硬件置备

节点

Pigsty 目前运行在具有 Linux 内核和 x86_64 / aarch64 架构的节点上。

“节点” 指的是 SSH 可访问 且提供裸 Linux 操作系统环境的资源。 它可以是物理机、虚拟机或配备 systemd、sudo 和 sshd 的类似操作系统的容器。

部署 pigsty 至少需要 1 个节点， 您可以准备更多并在 一次性 中设置所有内容，或稍后添加它们。 最小节点规格要求是 1C1G，建议至少使用 2C2G。 越高越好，没有上限。参数将根据可用资源自动调优。

规格

您需要多少个节点？这取决于您的资源和需求。

磁盘

Pigsty 将使用 /data 作为默认数据目录，如果您有专用的主数据磁盘，建议将其挂载到那里， 并为额外的磁盘驱动器使用 /data1、/data2、/dataN。

我们建议使用 ext4 或 xfs 作为数据磁盘的文件系统。它们对 PostgreSQL 有最佳性能。

虽然 ext4 有更多的数据恢复工具，但 xfs 对小文件更高效。 如果您运行 MinIO，建议使用 xfs，否则，建议使用 ext4 作为默认选项。

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

网络

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

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

执行标准（在线）安装 时需要互联网访问。 但 pigsty 可以通过离线软件包进行 离线安装， 在这种情况下不需要互联网访问。

VIP

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

要使用 L2 VIP 功能，您必须为它们明确分配一个 L2 VIP。 在您自己的硬件上运行时这不是大问题， 但在公有云环境中工作时可能成为问题。

域名

Pigsty 为以下具有 WebUI 的服务使用本地静态域名。 您可以为这些服务分配自定义域名，或使用真实域名。 只需在 infra_portal 中更改它们。

域名是可选的，要使用它们，用户有责任将以下记录添加到您的 /etc/hosts 文件（本地静态解析）， 或将它们添加到您的 DNS 服务器/公共 DNS 供应商。

10.10.10.10 h.pigsty g.pigsty p.pigsty a.pigsty

2 - Linux 系统

系统建议

Pigsty 推荐使用以下操作系统：RockyLinux 9.6， Ubuntu 24.04.2，与 Debian 12.11。

EL

Pigsty 支持 EL 8/9/10 兼容系统（RHEL / Rocky / Alma / Anolis / CentOS …… ），推荐使用 RockyLinux 9.6。

Ubuntu

Pigsty v3.7 支持 Ubuntu 24.04 / 22.04，建议使用 24.04.2。

Debian

Pigsty 可运行于 Debian 13 / 12 / 11 上，建议使用 12.11。

3 - 软件置备

Linux

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

我们推荐使用 RockyLinux 9.6、Debian 12.11 或 Ubuntu 24.04.5 作为默认操作系统选项。

我们强烈建议使用全新安装的操作系统环境，并将 en_US 设置为主要语言。

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

Pigsty 不使用容器，主要组件针对特定发行版主版本打包。

文件系统

Pigsty 建议使用 ext4 或 xfs 文件系统，两者在 PostgreSQL 用例上都有最好的性能表现。 如果您清楚知道自己在做什么，也可以考虑使用 zfs 这样的文件系统，但切勿使用 nfs 等网络文件系统运行数据库服务。

如果您需要使用到 MinIO，建议使用 xfs 文件系统，这是 MinIO 唯一推荐使用到文件系统。 它在大量小文件的场景中有更好的性能表现，但工具生态（例如数据恢复）略逊于 ext4。

如果您只是运行标准 PostgreSQL 服务，我们建议您默认使用 Linux ext4 文件系统。

防火墙

您的安全策略和防火墙设置应该允许访问所需的端口。

要访问 WebUI 服务，您必须允许 HTTP（80）/ HTTPS（443）访问。

要访问 PostgreSQL 数据库服务，您必须允许 postgres 的 5432 端口。

在典型的公有云 VPS 设置中，端口 22/80/443/5432 通常是开放的。

在典型的生产设置中，端口 22/80/443 从 LAN / 跳板机向 DBA/OPS 开放。 其他端口从内网访问。您必须确保它们在内部开放：使用的端口。

Ansible

Pigsty 使用 Ansible 从管理节点发起对所有被管理节点的控制。

您不需要关心细节，ansible 在 Bootstrap 阶段安装。

sudo apt install -y ansible python3-jmespath

sudo dnf install -y ansible python3-jmespath

sudo dnf install -y ansible python3.12-jmespath

sudo yum install -y ansible python-jmespath

brew install ansible
pip3 install jmespath

Ansible 只在管理节点上需要，您可以在 macOS 上运行 ansible 将您的笔记本电脑用作管理节点。

Pigsty

（推荐）您可以使用以下方式获取并提取最新稳定版本的 pigsty 源代码：

curl -fsSL https://repo.pigsty.io/get | bash -s v3.7.0; cd ~/pigsty

curl -fsSL https://repo.pigsty.cc/get | bash -s v3.7.0; cd ~/pigsty   # 中国镜像

要安装特定版本，将版本字符串作为第一个参数传递：

curl -fsSL https://repo.pigsty.io/get | bash -s v3.7.0; cd ~/pigsty

curl -fsSL https://repo.pigsty.cc/get | bash -s v3.7.0; cd ~/pigsty # 中国镜像

您也可以使用 git 从 GitHub 克隆 Pigsty 源代码仓库：

git clone https://github.com/pgsty/pigsty.git; cd ~/pigsty; git checkout v3.7.0

$ curl -fssL https://repo.pigsty.cc/get | bash -s v3.7.0
[v3.7.0] ===========================================
$ curl -fsSL https://repo.pigsty.cc/get | bash -s v3.7.0
[Docs] https://doc.pgsty.com
[Demo] https://g.pgsty.com
[Repo] https://github.com/pgsty/pigsty
[Download] ===========================================
[ OK ] version = v3.7.0 (from arg)
curl -fSL https://repo.pigsty.cc/src/pigsty-v3.7.0.tgz -o /tmp/pigsty-v3.7.0.tgz
[WARN] tarball = /tmp/pigsty-v3.7.0.tgz exists, size = 1472486, use it
[ OK ] md5sums = df64ac0c2b5aab39dd29698a640daf2e  /tmp/pigsty-v3.7.0.tgz
[Install] ===========================================
[ OK ] install = /home/vagrant/pigsty, from /tmp/pigsty-v3.7.0.tgz
[Bootstrap] ===========================================
[ OK ] ansible = ready
[ OK ] bootstrap = skip
you can run ./bootstrap to extrac offline package and install ansible
[TodoList] ===========================================
cd /home/vagrant/pigsty
./configure      # [可选] 预检和配置生成
./install.yml    # 部署配置描述的所有内容

您也可以从 GitHub Release Page 手动下载 pigsty 源代码（pigsty-<version>.tar.gz）：

wget https://repo.pigsty.io/src/pigsty-v3.7.0.tgz

wget https://pigsty.cc/pgsty/pigsty/releases/download/v3.7.0/pigsty-v3.7.0.tgz

wget https://github.com/pgsty/pigsty/releases/download/v3.7.0/pigsty-v3.7.0.tgz

如果您的环境没有互联网访问，请考虑与源代码压缩包一起下载离线软件包并将其上传到您的节点。

详情请查看 离线安装。

4 - 管理用户

用户

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

命名约定

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

提供密码

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

./install.yml -k -K

创建管理员用户

在服务器置备阶段，用户/供应商有责任创建并交付这样的管理员用户。 但如果您没有这样的管理员用户，或者该用户受到限制，您可以使用 pigsty 本身创建一个：

./node.yml -k -K -t node_admin -e ansible_user=[existing_admin_user]

Sudo 权限

所有 管理员用户 都应该在所有被管理节点上具有免密 sudo 权限。

如果您想从头开始配置具有免密 sudo 权限的管理员用户：

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

%dba ALL=(ALL) NOPASSWD: ALL

Ansible 依赖 sudo 在被管理节点上以 root 权限执行命令。 因此，在 sudo 不可用的环境中（比如在精简容器内），您可能需要先安装 sudo。

SSH

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

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

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

生成 SSH 密钥

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

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

复制 SSH 密钥

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

ssh-copy-id <ip>                        # 交互式密码输入

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

使用别名

当无法直接 SSH 访问时（由于跳板机、其他端口、凭据等…），考虑：

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

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

检查可访问性

您应该能够从管理节点通过当前用户免密 ssh 访问所有被管理节点。 远程用户（管理员用户）应该有权限运行免密 sudo 命令。

ssh <ip|alias> 'sudo ls'

5 - 沙箱环境

Pigsty 有一个沙盒，这是一个具有固定 IP 地址和其他标识符的 4 节点部署。

我们将使用它作为学习和测试目的的标准演示环境。

描述

沙盒由具有固定 IP 地址和身份的 4 个节点组成：

在 meta 节点上有一个主要的单例 PostgreSQL 集群：pg-meta， 它可以独立使用，还有一个可选的 L2 VIP 10.10.10.2 和集群 DNS pg-meta 绑定到它。

10.10.10.10 meta pg-meta-1
10.10.10.2  pg-meta

沙盒中还有三个额外的节点，组成一个 3 实例的 PostgreSQL HA 集群 pg-test。 有一个可选的 L2 VIP 10.10.10.3 和集群 DNS 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

在 meta 节点上还有一个 1 节点的 etcd 集群和 1 节点的 minio 集群。

10.10.10.10 minio-1
10.10.10.10 etcd-1

实现

您可以使用 Vagrant 创建本地沙盒，或使用 Terraform 创建云沙盒。

要使用本地 vagrant 模板：

make full9     # 使用 RockyLinux 9 创建 4 节点沙盒
make full12     # 使用 Debian 12 创建 4 节点沙盒
make full24     # 使用 Ubuntu 24.04 创建 4 节点沙盒

要使用云 terraform 模板，请使用 spec/aliyun-full.tf 作为示例， 阿里云 4 节点沙盒模板适用于所有发行版和 amd/arm。

make tu     # terraform up
make td     # terraform destroy
make tssh   # 将 ssh 别名写入 ~/.ssh/pigsty_config

6 - Vagrant

Pigsty 需要 Linux 环境，您可以使用 Vagrant 轻松创建本地 linux 虚拟机。

您还需要一个虚拟机提供商，（比如笔记本电脑的 VirtualBox 和服务器的 libvirt）

入门

您可以在 macOS 上使用 homebrew 安装 vagrant、virtualbox、ansible：

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

您已准备就绪！使用 make 快捷方式创建虚拟机：

make meta       # 1 节点开发箱，用于快速启动、开发、测试和实验
make full       # 4 节点沙盒，用于 HA 测试和功能演示
make simu       # 36 节点模拟箱，用于生产环境模拟
...
make meta9      # 使用 bento/rockylinux-9 镜像创建单例元节点
make full22     # 使用 generic/ubuntu2204 镜像创建 4 节点沙盒
make simu12     # 使用 generic/debian12 镜像创建 36 节点模拟环境

配置

您必须在启动前在 Vagrantfile 中定义虚拟机。 默认的 Vagrantfile 定义了一个 el9（bento/rockylinux-9）1 节点虚拟机，使用本地 virtualbox VM 提供商。

• vagrant/
  • spec/
    • meta.rb
    • full.rb
    • simu.rb
    • ......
  • Vagrantfile

我们在 vagrant/spec 文件夹中有一系列预定义的 VM 规格

每个规格文件包含一个描述 VM 节点的 Specs 变量。例如，full.rb 包含：

# full: pigsty 全功能 4 节点沙盒，用于 HA 测试、教程和实践

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

您可以使用规格与 config 脚本，它将根据规格和环境变量（资源、镜像、vm 提供商等…）渲染 Vagrantfile。

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

vagrant/config meta                # 使用 1 节点规格，默认 el8 镜像
vagrant/config dual el9            # 使用 2 节点规格，使用 el9 镜像
vagrant/config trio d12 2          # 使用 3 节点规格，使用 debian12 镜像，双倍 cpu/mem 资源
vagrant/config full u22 4          # 使用 4 节点规格，使用 ubuntu22 镜像，使用 4x cpu/mem 资源
vagrant/config simu u24 1 libvirt  # 使用 36 节点规格，使用 ubuntu24 镜像，使用 libvirt 作为提供商而不是 virtualbox

您可以使用环境变量 VM_SCALE 扩展资源单位，默认值为 1。

例如，VM_SCALE=2 vagrant/config meta 将使 meta 规格的 cpu / mem 资源翻倍

Specs = [
  { "name" => "meta" , "ip" => "10.10.10.10", "cpu" => "8" , "mem" => "16384" , "image" => "bento/rockylinux-9" },
]

快捷方式

配置后，您可以使用 vagrant up 命令创建虚拟机。

Pigsty 模板将使用您的 ~/.ssh/id_rsa[.pub] 作为 vagrant 置备的默认 ssh 密钥。 在开始之前确保您有有效的 ssh 密钥对，您可以通过以下方式生成一个：ssh-keygen -t rsa -b 2048

有一些包装 vagrant 命令的快捷方式，您可以使用它们来管理虚拟机。

make         # = make start
make new     # 销毁现有 vm 并创建新的
make ssh     # 将 VM ssh 配置写入 ~/.ssh/     （必需）
make dns     # 将 VM DNS 记录写入 /etc/hosts （可选）
make start   # 启动 VM 并写入 ssh 配置    （up + ssh）
make up      # 使用 vagrant up 启动 VM
make halt    # 关闭 VM （down,dw）
make clean   # 销毁 VM （clean/del/destroy）
make status  # 显示 VM 状态 （st）
make pause   # 暂停 VM （suspend,pause）
make resume  # 恢复 VM （resume）
make nuke    # 使用 virsh 销毁所有 vm 和卷（如果使用 libvirt）

版本

Pigsty 目前使用以下 vagrant 盒子进行测试：

$ vagrant box list

el8 :  bento/rockylinux-8     (libvirt, 202502.21.0, (amd64))
el9 :  bento/rockylinux-9     (libvirt, 202502.21.0, (amd64))

d11 :  generic/debian11       (libvirt, 4.3.12, (amd64))
d12 :  generic/debian12       (libvirt, 4.3.12, (amd64))

u20 :  generic/ubuntu2004     (libvirt, 4.3.12, (amd64))
u22 :  generic/ubuntu2204     (libvirt, 4.3.12, (amd64))
u24 :  bento/ubuntu-24.04     (libvirt, 20250316.0.0, (amd64))

它们并非都有 arm64 架构支持，所以在使用 Apple Silicon MacOS 时要注意。

bento/rockylinux-9 (virtualbox, 202502.21.0, (arm64))
bento/ubuntu-24.04 (virtualbox, 202502.21.0, (arm64))

您可以在 https://app.vagrantup.com/bento/boxes 上找到支持的 Box 镜像

注意事项

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

7 - Terraform

Terraform 是一个流行的 IaC 工具。您可以使用一个命令在公有云上创建虚拟机。

阿里云和 AWS 模板用作示例提供商。您可以将 terraform.tf 作为示例。

入门

您可以在 macOS 上使用 homebrew 安装 terraform

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

然后初始化 terraform 云提供商，调整 terraform.tf 配置文件并应用它：

terraform init
terraform apply #-auto-approve

打印公共 IP 地址：

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

AWS 设置

您必须设置 aws 配置和凭据才能使用 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>

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

有一个 AWS（Amazon Web Services）的贡献示例，但它没有得到积极维护。

• spec/aws-cn.tf : AWS 4 节点 CentOS7 环境

阿里云设置

您可以将您的阿里云凭据添加到环境文件中，例如 ~/.bash_profile

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

示例配置文件：

• spec/aliyun-meta.tf : 阿里云 1 元节点模板，适用于所有发行版和 amd/arm（默认）
• spec/aliyun-full.tf : 阿里云 4 节点沙盒模板，适用于所有发行版和 amd/arm。
• spec/aliyun-oss.tf : 阿里云 5 节点构建模板，适用于所有发行版和 amd/arm。

以下是阿里云中使用的示例 ECS 公共操作系统镜像：

腾讯云设置

有一个腾讯云的贡献示例，但它没有得到积极维护。

• spec/tencentcloud.tf : 腾讯云 4 节点 CentOS7 环境