This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

入门

快速上手 Pigsty：根据需求进行规划，准备资源，置备服务器，创建管理用户，下载软件并完成安装。

1: 安装部署
2: 离线安装
3: 声明配置
4: 准备工作
5: 资源规划
6: 执行剧本
7: 置备机器
8: 安全考量
9: 常见问题

1 - 安装部署

下载、配置、安装 Pigsty

安装 Pigsty 四步走: 准备，下载，配置，以及安装。如果您没有互联网访问，请同时参阅 离线安装。

简短版本

准备一个安装了兼容操作系统的 Linux x86_64 节点，使用带有免密 sudo 权限的用户，执行以下命令：

curl -L https://get.pigsty.cc/latest | bash

该命令会下载并解压 Pigsty 源码至家目录，依次完成配置与安装即可完成安装。

cd ~/pigsty      # 下载源码包解压后进入 Pigsty 源码目录，完成后续 准备、配置、安装 三个步骤
./bootstrap      # 【可选项】用于确保 Ansible 正常安装，如果 /tmp/pkg.tgz 离线包则使用它
./configure      # 【可选项】执行环境检测，并生成相应的推荐配置文件，如果知道如何配置可以跳过
./install.yml    # 根据生成的配置文件开始在当前节点上执行安装，使用离线安装包大概需要10分钟完成

安装完成后，您可以通过域名，或80/443端口通过 Nginx 访问 WEB 界面，通过 5432 端口访问默认的 PostgreSQL 数据库服务。您可以继续使用 Pigsty 纳管更多节点，并部署各种模块。

准备

关于准备工作的完整详细说明，请参考 入门：准备工作 一节。

Pigsty 支持 Linux 内核与 x86_64/amd64 架构，运行于物理机、虚拟机环境中，要求使用静态IP地址。最低配置要求为 1C1G，推荐至少使用 2C4G 以上的机型，上不封顶，参数会自动优化适配。

我们强烈建议您使用刚安装完操作系统的全新节点部署，从而避免无谓的安装异常问题，建议使用 RockyLinux 8.9 或 Ubuntu 22.04.3，支持的完整操作系统列表请参考 兼容性。

在安装 Pigsty 的管理节点上，您需要拥有 ssh 登陆权限与 sudo 权限：如果您的部署涉及多个节点，您应当确保当前管理用户在当前管理节点上，可以通过 SSH 公钥免密登陆其他被管理的节点（包括本节点）。

Pigsty 依赖 Ansible 执行剧本，在执行安装前，您需要先安装 ansible 与 jmespath 软件包。您还可以通过 bootstrap 脚本完成这一任务，特别是当您没有互联网访问时。

sudo dnf install -y ansible python3.11-jmespath

sudo yum install -y ansible   # EL7 无需显式安装 Jmespath

sudo apt install -y ansible python3-jmespath

brew install ansible

避免使用 root 用户安装

尽管使用 root 用户安装 Pigsty 是可行的，但安全最佳实践是使用一个不同于根用户（root）与数据库超级用户 (postgres) 的专用管理员用户（如：dba）， Pigsty 安装过程中会默认创建由配置文件指定的可选管理员用户 dba

下载

您可以使用以下命令自动下载、解压 Pigsty 源码包至 ~/pigsty 目录下使用：

curl -L https://get.pigsty.cc/latest  | bash

一键下载脚本的样例输出

$ bash -c "$(curl -fsSL https://get.pigsty.cc/latest)"
[Checking] ===========================================
[ OK ] SOURCE from CDN due to GFW
FROM CDN    : bash -c "$(curl -fsSL https://get.pigsty.cc/latest)"
FROM GITHUB : bash -c "$(curl -fsSL https://raw.githubusercontent.com/Vonng/pigsty/master/bin/latest)"
[Downloading] ===========================================
[ OK ] download pigsty source code from CDN
[ OK ] $ curl -SL https://get.pigsty.cc/v2.6.0/pigsty-v2.6.0.tgz
....
MD5: xxxx  /tmp/pigsty-v2.6.0.tgz
[Extracting] ===========================================
[ OK ] extract '/tmp/pigsty-v2.6.0.tgz' to '/home/dba/pigsty'
[ OK ] $ tar -xf /tmp/pigsty-v2.6.0.tgz -C ~;
[Reference] ===========================================
Website:      https://pigsty.io
Public Demo:  https://demo.pigsty.cc
Github Repo:  https://github.com/Vonng/pigsty
[Proceeding] ===========================================
cd ~/pigsty      # entering pigsty home directory before proceeding
./bootstrap      # install ansible & download the optional offline packages
./configure      # preflight-check and generate config according to your env
./install.yml    # install pigsty on this node and init it as the admin node

安装最新Beta版本

默认的 latest 脚本将下载当前的最新稳定版本，将其替换为 beta 则会下载最新的测试版本。

对于没有互联网访问的环境，您可以参考 离线安装 的说明，提前下载好源码包，与可选的离线软件包，手工上传至目标服务器，并解压使用。 GitHub Release 页面提供下载，您也可以直接使用以下 URL：

GitHub： https://github.com/Vonng/pigsty/releases/download/v2.6.0/pigsty-v2.6.0.tgz
中国CDN： https://get.pigsty.cc/v2.6.0/pigsty-v2.6.0.tgz

curl https://get.pigsty.cc/v2.6.0/pigsty-v2.6.0.tgz -o pigsty.tgz
tar -xvf pigsty.tgz -C ~ ; cd ~/pigsty ;  # 手工下载，并解压至家目录中

你也可以使用 git 来下载 Pigsty 源代码，请务必检出特定版本后使用。

git clone https://github.com/Vonng/pigsty; cd pigsty;  git checkout v2.6.0;

检出特定版本使用

master 主干为活跃开发分支，使用 Git 时请务必检出特定版本后使用，可用版本请参考 发行注记。

配置

配置 / configure 会根据您当前的环境，自动生成推荐的（单机安装） pigsty.yml 配置文件。

提示: 如果您已经了解了如何配置 Pigsty，configure 这个步骤是可选的，可以跳过。

./configure # 不带参数会自动推荐配置，并交互式问询
./configure [-i|--ip <ipaddr>] [-m|--mode <name>]  # 选择首要 IP 地址与配置模板 
            [-r|--region <default|china|europe>]   # 选择镜像源区域
            [-n|--non-interactive]                 # 跳过交互式向导

配置 / configure 过程的样例输出

$ ./configure
configure pigsty v2.6.0 begin
[ OK ] region = china
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] package = rpm,dnf
[ OK ] vendor = rocky (Rocky Linux)
[ OK ] version = 8 (8.6)
[ OK ] sudo = dba ok
[ OK ] ssh = dba@127.0.0.1 ok   
[WARN] Multiple IP address candidates found: # 如果有多个 IP 地址，需要你选择一个（输入IP地址）
    (1) 10.10.10.10	    inet 10.10.10.10/16 brd 10.10.255.255 scope global noprefixroute eth0
    (2) 172.17.0.1	    inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0
    (3) 172.18.0.1	    inet 172.18.0.1/16 brd 172.18.255.255 scope global br-9847524528bc
[ OK ] primary_ip = 10.10.10.10 (from demo)
[ OK ] admin = dba@10.10.10.10 ok
[ OK ] config = el @ 10.10.10.10 [tiny -> oltp]
[ OK ] configure pigsty done
proceed with ./install.yml

-m|--mode：用于直接指定配置模板 : (auto|el|el7|ubuntu|debian|demo|prod|...)
-i|--ip：当前主机的首要内网IP地址，用于替换配置文件中的 IP 地址占位符 10.10.10.10。
-r|--region：用于指定上游软件源的区域，加速下载： (default|china|europe)
-n|--non-interactive：直接使用命令行参数提供首要IP地址，跳过交互式向导。

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

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

修改默认密码！

我们强烈建议您在安装前，事先修改配置文件中使用的默认密码与凭据，详情参考 安全考量。

安装

使用 install.yml 剧本，默认在当前节点上完成标准的单节点 Pigsty 安装。

./install.yml    # 一次性在所有节点上完成安装

安装过程的样例输出

[vagrant@meta pigsty]$ ./install.yml

PLAY [IDENTITY] ********************************************************************************************************************************

TASK [node_id : get node fact] *****************************************************************************************************************
changed: [10.10.10.12]
changed: [10.10.10.11]
changed: [10.10.10.13]
changed: [10.10.10.10]
...
...
PLAY RECAP **************************************************************************************************************************************************************************
10.10.10.10                : ok=288  changed=215  unreachable=0    failed=0    skipped=64   rescued=0    ignored=0
10.10.10.11                : ok=263  changed=194  unreachable=0    failed=0    skipped=88   rescued=0    ignored=1
10.10.10.12                : ok=263  changed=194  unreachable=0    failed=0    skipped=88   rescued=0    ignored=1
10.10.10.13                : ok=153  changed=121  unreachable=0    failed=0    skipped=53   rescued=0    ignored=1
localhost                  : ok=3    changed=0    unreachable=0    failed=0    skipped=4    rescued=0    ignored=0

这是一个 Ansible 剧本，您可以使用以下参数控制其执行的目标、任务、并传递额外的命令参数：

-l: 限制执行的目标对象
-t: 限制要执行的任务
-e: 传入额外的命令行参数
…

避免重复执行安装！

警告：在已经初始化的环境中再次运行 install.yml 会重置整个环境，所以请务必小心！

此剧本仅用于初始安装，安装完毕后可以用 chmod a-x install.yml 来避免此剧本的误执行。

用户界面

当安装完成后，当前节点会安装有四个 核心模块：PGSQL，INFRA，NODE，ETCD。

本机上的 PGSQL 模块提供了一个开箱即用的单机 PostgreSQL 数据库实例，默认可以使用以下连接串访问：

psql postgres://dbuser_dba:DBUser.DBA@10.10.10.10/meta     # DBA / 超级用户（IP直连）

psql postgres://dbuser_meta:DBUser.Meta@10.10.10.10/meta   # 业务管理员用户，读/写/DDL变更

psql postgres://dbuser_view:DBUser.View@pg-meta/meta       # 只读用户（走域名访问）

本机上的 INFRA 模块为您提供了监控基础设施，默认使用的域名与端口如下所示：

组件	端口	域名	说明	Demo地址
Nginx	80/443	`h.pigsty`	Web 服务总入口，本地YUM源	`home.pigsty.cc`
AlertManager	9093	`a.pigsty`	告警聚合/屏蔽页面	`a.pigsty.cc`
Grafana	3000	`g.pigsty`	Grafana 监控面板	`demo.pigsty.cc`
Prometheus	9090	`p.pigsty`	Prometheus 管理界面	`p.pigsty.cc`

Grafana 监控系统（g.pigsty / 3000端口）的默认用户名与密码为：admin / pigsty

您可以通过 IP地址 + 端口的方式直接访问这些服务。但我们更推荐您使用域名通过 Nginx 80/443 端口代理访问所有组件。使用域名访问 Pigsty WebUI 时，您需要配置 DNS 解析，或者修改本地的 /etc/hosts 静态解析文件。

如何通过域名访问 Pigsty WebUI ？

客户端可以通过几种不同的办法来使用域名访问：

通过 DNS 服务商解析互联网域名，适用于公网可访问的系统。
通过配置内网 DNS 服务器解析记录实现内网域名解析。
修改本机的 /etc/hosts 文件添加静态解析记录。（Windows下为：）

我们建议普通用户使用第三种方式，在使用浏览器访问 Web 系统的机器上，修改 /etc/hosts （需要 sudo 权限）或 C:\Windows\System32\drivers\etc\hosts（Windows）文件，添加以下的解析记录：

<your_public_ip_address>  h.pigsty a.pigsty p.pigsty g.pigsty

这里的 IP 地址是安装 Pigsty 服务的 对外IP地址。

如何配置服务端使用的域名？

服务器端域名使用 Nginx 进行配置，如果您想要替换默认的域名，在参数 infra_portal 中填入使用的域名即可。当您使用 http://g.pigsty 访问 Grafana 监控主页时，实际上是通过 Nginx 代理访问了 Grafana 的 WebUI：

http://g.pigsty ️-> http://10.10.10.10:80 (nginx) -> http://10.10.10.10:3000 (grafana)

如何使用 HTTPS 访问 Pigsty WebUI ？

Pigsty默认使用自动生成的自签名的 CA 证书为 Nginx 启用 SSL，如果您希望使用 HTTPS 访问这些页面，而不弹窗提示"不安全"，通常有三个选择：

在您的浏览器或操作系统中信任 Pigsty 自签名的 CA 证书： files/pki/ca/ca.crt
如果您使用 Chrome，可以在提示不安全的窗口键入 thisisunsafe 跳过提示
您可以考虑使用 Let’s Encrypt 或其他免费的 CA 证书服务，为 Pigsty Nginx 生成正式的 SSL证书。

你可以使用 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 模块，请确保节点被 Pigsty 纳管后再加装其他模块。更多细节请参考模块详情：

PGSQL，INFRA，NODE，ETCD，MINIO，REDIS，MONGO，DOCKER，……

2 - 离线安装

如何在没有互联网访问的环境中安装 Pigsty？以及如何制作离线软件安装包。

Pigsty 的 标准安装 流程需要访问互联网，然而生产环境的数据库服务器通常是与互联网隔离的。

因此 Pigsty 提供了离线安装的功能，允许您在没有互联网访问的环境中，同样完成安装与部署。

如果您有互联网访问，提前下载好预制的 离线软件包 也可以帮助您加速安装的过程，并增强安装过程的确定性与可靠性。

简短版本

在执行 标准安装 前首先下载好 Pigsty 软件包与 离线软件包 。

VERSION=v2.6.0   # Pigsty 版本号
DISTRO=el8       # 离线包系统版本可选值：el7, el8, el9, debian11, debian12, ubuntu20, ubuntu22
curl "https://get.pigsty.cc/${VERSION}/pigsty-${VERSION}.tgz"                      -o ~/pigsty.tgz  # 软件包，通常放置于 ~/pigsty.tgz
curl "https://get.pigsty.cc/${VERSION}/pigsty-pkg-${VERSION}.${distro}.x86_64.tgz" -o /tmp/pkg.tgz  # 离线包，默认放置于 /tmp/pkg.tgz

上传 Pigsty 软件包与离线软件包至管理节点，将离线包放置于 /tmp/pkg.tgz，然后通过 bootstrap 过程启用。

./bootstrap      # 变体：如果本机有互联网访问，使用 ./bootstrap -y 可自动下载对应系统的离线软件包

# 继续后面的配置与安装任务
./configure      # 执行环境检测，并生成相应的推荐配置文件，如果你知道如何配置 Pigsty 可以跳过
./install.yml    # 根据生成的配置文件开始在当前节点上执行安装，使用离线安装包大概需要10分钟完成

离线安装基本原理

Pigsty 会在安装过程中从互联网上游的 yum/apt 软件仓库，下载所需的 rpm/deb 包并构建一个本地软件源（默认位于 /www/pigsty）。

本地软件源由 Nginx 对外提供服务，后续无论是本机还是其他节点，都默认会使用本地软件源进行安装，而不再需要访问互联网。

使用本地软件源有三个主要好处：

本地软件源可以避免重复的下载请求与流量消耗，显著加速安装速度并提高安装过程的可靠性。
构建本地软件源会对当前可用软件版本取快照，确保部署环境内节点所安装软件版本的一致性。
构建好的本地软件源可以整体打包，复制到安装有相同操作系统的隔离环境中用于离线安装。

离线安装的原理是：首先在一台具有相同操作系统，且有互联网访问的节点上，完成 标准安装 流程。然后对构建好的本地软件源（默认位于 /www/pigsty ）取快照并打包，制作成为 离线软件包，供安装有同样操作系统的生产环境网络隔离节点使用。

当 Pigsty 执行安装时，如果发现本地软件源已经存在，就会进入离线安装模式。在此模式下，Pigsty 将跳过从互联网下载并构建本地软件源的过程，使用本地软件源完成整个安装过程，期间无需互联网访问。

进入离线安装模式的判定标准

判定本地软件源存在的标准是：默认位于 /www/pigsty/repo_complete 的标记文件存在。

这个标记文件会在标准安装过程中，下载完成后自动生成，说明这是一个可用的本地软件源。

删除本地软件源的 repo_complete 标记文件后，安装时将重新从上游下载 缺失的 软件包。

离线软件包

离线软件包是一个使用 gzip 与 tar 制作的标准 Tarball，以 .tgz 后缀结尾。通常放置于 /tmp/pkg.tgz 路径，并解压至 /www/pigsty 使用。 Pigsty 为支持的操作系统发行版提供了预制离线软件包。如果您使用相同的操作系统版本，可以开箱即用。

https://github.com/Vonng/pigsty/releases/download/v2.6.0/pigsty-pkg-v2.6.0.el7.x86_64.tgz      # EL 7.9
https://github.com/Vonng/pigsty/releases/download/v2.6.0/pigsty-pkg-v2.6.0.el8.x86_64.tgz      # EL 8.9
https://github.com/Vonng/pigsty/releases/download/v2.6.0/pigsty-pkg-v2.6.0.el9.x86_64.tgz      # EL 9.3
https://github.com/Vonng/pigsty/releases/download/v2.6.0/pigsty-pkg-v2.6.0.debian11.x86_64.tgz # Debian 11.8
https://github.com/Vonng/pigsty/releases/download/v2.6.0/pigsty-pkg-v2.6.0.debian12.x86_64.tgz # Debian 12.4
https://github.com/Vonng/pigsty/releases/download/v2.6.0/pigsty-pkg-v2.6.0.ubuntu20.x86_64.tgz # Ubuntu 20.04.6
https://github.com/Vonng/pigsty/releases/download/v2.6.0/pigsty-pkg-v2.6.0.ubuntu22.x86_64.tgz # Ubuntu 22.04.3

https://get.pigsty.cc/${VERSION}/pigsty-pkg-v2.6.0.el7.x86_64.tgz       # EL 7.9
https://get.pigsty.cc/${VERSION}/pigsty-pkg-v2.6.0.el8.x86_64.tgz       # EL 8.9
https://get.pigsty.cc/${VERSION}/pigsty-pkg-v2.6.0.el9.x86_64.tgz       # EL 9.3
https://get.pigsty.cc/${VERSION}/pigsty-pkg-v2.6.0.debian11.x86_64.tgz  # Debian 11.8
https://get.pigsty.cc/${VERSION}/pigsty-pkg-v2.6.0.debian12.x86_64.tgz  # Debian 12.4
https://get.pigsty.cc/${VERSION}/pigsty-pkg-v2.6.0.ubuntu20.x86_64.tgz  # Ubuntu 20.04.6
https://get.pigsty.cc/${VERSION}/pigsty-pkg-v2.6.0.ubuntu22.x86_64.tgz  # Ubuntu 22.04.3

离线软件包的适用系统版本

使用离线软件包安装时，请务必确保 OS 大版本精确匹配，尽可能确保系统小版本一致或尽可能接近。

OS 小版本不匹配的情况下通常也可以成功进行离线安装，但有概率出现部分软件包 依赖缺失或冲突。

这种情况请使用安装了相同小版本的系统预先 制作离线软件包 进行离线安装，或参考 常见问题 解决。

Bootstrap

Ansible 是 Pigsty 的核心依赖，离线安装首先需要解决如何在没有互联网访问或本地源的情况下，离线安装 Ansible 的问题。

Pigsty 的离线软件包中默认已经包含了 ansible 及其依赖，从离线软件包中提取并安装 ansible 的这一过程，称为 Bootstrap。

Bootstrap 过程的逻辑

检查安装的前提条件是否满足（操作系统，芯片架构，内核）
检查本地离线安装包（/tmp/pkg.tgz）是否存在？

是 -> 解压到 /www/pigsty 并配置本地FS软件源启用它。
否 -> 进一步决定是否从互联网下载离线软件包？
- 是 -> 从 GitHub 或 CDN 下载离线软件包并解压
- 否 -> 是否添加操作系统基础的上游源地址以供从互联网下载 ?
  - 是 -> 根据地区与操作系统版本写入对应的上游源：/etc/yum.repos.d/ 或 /etc/apt/source.list.d
  - 否 -> 用户自己搞定，或者当前系统的默认配置就带有 Ansible
- 现在，我们有了一个可用的本地软件源，可用来安装 Pigsty 所需的软件包，特别是 Ansible。
- 优先级顺序: 本地的 pkg.tgz > 下载的 pkg.tgz > 原始上游 > 默认配置

从上一步配置的软件源中，安装一些基本的重要软件，不同版本的软件略有不同：
- el7: ansible createrepo_c unzip wget yum-utils sshpass
- el8: ansible python3-jmespath python3.11-jmespath createrepo_c unzip wget dnf-utils sshpass modulemd-tools
- el9: ansible python3-jmespath python3.11-jmespath createrepo_c unzip wget dnf-utils sshpass modulemd-tools
- ubuntu/debian: ansible python3-jmespath dpkg-dev unzip wget sshpass acl
检查 ansible 是否成功安装。

bootstrap 脚本会帮助您自动解压位于 /tmp/pkg.tgz 的离线软件包，向节点添加并启用本地源，并安装 Ansible 及其依赖。

首先将离线软件包拷贝至生产环境管理节点上，并放置于 /tmp/pkg.tgz 路径下备用，然后执行 bootstrap 命令即可：

./bootstrap       # 解压 /tmp/pkg.tgz，创建并启用本地软件源，然后从中安装 Ansible

从离线软件包本地 Bootstrap 的样例输出

如果离线软件包存在于 /tmp/pkg.tgz， bootstrap 会直接使用它：

bootstrap pigsty v2.6.0 begin
[ OK ] region = china
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] release = 7.9.2009
[ OK ] sudo = vagrant ok
[ OK ] cache = /tmp/pkg.tgz exists
[ OK ] repo = extract from /tmp/pkg.tgz
[ OK ] repo file = use /etc/yum.repos.d/pigsty-local.repo
[ OK ] repo cache = created
[ OK ] install el7 utils
....(yum install ansible output)
[ OK ] ansible = ansible 2.9.27
[ OK ] boostrap pigsty complete
proceed with ./configure

如果您的环境有互联网访问，那么可以使用 bootstrap 的变体：

./bootstrap       # 如果 /tmp/pkg.tgz 不存在，添加全球/中国/欧洲的仓库镜像并尝试在线安装 Ansible
./bootstrap -y    # 如果 /tmp/pkg.tgz 不存在，从互联网下载预先制作好的离线软件包

从互联网下载离线软件包，在线 Bootstrap 的样例输出

从 Github / CDN 下载 pkg.tgz 并解压使用：

bootstrap pigsty v2.6.0 begin
[ OK ] region = china
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] release = 7.9.2009
[ OK ] sudo = vagrant ok
[ IN ] Cache /tmp/pkg.tgz not exists, download? (y/n):
=> y
[ OK ] download from Github https://get.pigsty.cc/v2.6.0/pigsty-pkg-v2.6.0.el7.x86_64.tgz to /tmp/pkg.tgz
....
[ OK ] repo = extract from /tmp/pkg.tgz
[ OK ] repo file = use /etc/yum.repos.d/pigsty-local.repo
[ OK ] repo cache = created
[ OK ] install el7 utils
...... (yum install createrepo_c sshpass unzip output)
==================================================================================================================
 Package                        Arch                Version                       Repository                 Size
==================================================================================================================
Installing:
 createrepo_c                   x86_64              0.10.0-20.el7                 pigsty-local               65 k
 sshpass                        x86_64              1.06-2.el7                    pigsty-local               21 k
 unzip                          x86_64              6.0-24.el7_9                  pigsty-local              172 k
Installing for dependencies:
 createrepo_c-libs              x86_64              0.10.0-20.el7                 pigsty-local               89 k

Transaction Summary
==================================================================================================================
...... (yum install ansible output)
==================================================================================================================
 Package                                      Arch            Version                 Repository             Size
==================================================================================================================
Installing:
 ansible                                      noarch          2.9.27-1.el7            pigsty-local           17 M
Installing for dependencies:
 PyYAML                                       x86_64          3.10-11.el7             pigsty-local          153 k
 libyaml                                      x86_64          0.1.4-11.el7_0          pigsty-local           55 k
 python-babel                                 noarch          0.9.6-8.el7             pigsty-local          1.4 M
 python-backports                             x86_64          1.0-8.el7               pigsty-local          5.8 k
 python-backports-ssl_match_hostname          noarch          3.5.0.1-1.el7           pigsty-local           13 k
 python-cffi                                  x86_64          1.6.0-5.el7             pigsty-local          218 k
 python-enum34                                noarch          1.0.4-1.el7             pigsty-local           52 k
 python-idna                                  noarch          2.4-1.el7               pigsty-local           94 k
 python-ipaddress                             noarch          1.0.16-2.el7            pigsty-local           34 k
 python-jinja2                                noarch          2.7.2-4.el7             pigsty-local          519 k
 python-markupsafe                            x86_64          0.11-10.el7             pigsty-local           25 k
 python-paramiko                              noarch          2.1.1-9.el7             pigsty-local          269 k
 python-ply                                   noarch          3.4-11.el7              pigsty-local          123 k
 python-pycparser                             noarch          2.14-1.el7              pigsty-local          104 k
 python-setuptools                            noarch          0.9.8-7.el7             pigsty-local          397 k
 python-six                                   noarch          1.9.0-2.el7             pigsty-local           29 k
 python2-cryptography                         x86_64          1.7.2-2.el7             pigsty-local          502 k
 python2-httplib2                             noarch          0.18.1-3.el7            pigsty-local          125 k
 python2-jmespath                             noarch          0.9.4-2.el7             pigsty-local           41 k
 python2-pyasn1                               noarch          0.1.9-7.el7             pigsty-local          100 k

Transaction Summary
==================================================================================================================
...
Complete!
[ OK ] ansible = ansible 2.9.27
[ OK ] boostrap pigsty complete
proceed with ./configure

制作离线软件包

Pigsty 提供了制作离线软件包的脚本 bin/cache 。默认会将 /www/pigsty 目录压缩打包，放置于 /tmp/pkg.tgz 下。

bin/cache [version=v2.6.0]
          [pkg_path=/tmp/pkg.tgz]
          [repo_dir=/www/pigsty]

制作完成后，将其拷贝至生产环境管理节点，参考 bootstrap 过程使用即可，您也可以手工完成这一过程：

sudo rm -rf /www/pigsty            # 谨慎清理先前遗留软件
sudo tar -xf /tmp/pkg.tgz -C /www  # 解压离线软件包至目录

制作离线软件安装包的样例输出

例如，在标准安装完成后的 Ubuntu 22.04 系统上执行 bin/cache 脚本，即可创建离线软件包（/tmp/pkg.tgz）。

vagrant@ubuntu22:~/pigsty$ bin/cache
[ OK ] create offline package on ubuntu22
[ OK ] pkg type = deb
[ OK ] repo dir = /www/pigsty
[ OK ] copy /www/pigsty to /tmp/pigsty-build/pigsty
[ OK ] grafana plugins = found, overwrite /tmp/pigsty-build/pigsty/plugins.tgz
knightss27-weathermap-panel  marcusolsson-dynamictext-panel	marcusolsson-json-datasource	marcusolsson-treemap-panel  volkovlabs-form-panel	 volkovlabs-image-panel
marcusolsson-calendar-panel  marcusolsson-hourly-heatmap-panel	marcusolsson-static-datasource	volkovlabs-echarts-panel    volkovlabs-grapi-datasource  volkovlabs-variable-panel
[ OK ] ubuntu 22 = no packages needs to be cleansed
[ OK ] package = making pigsty-pkg-v2.6.0.ubuntu22.x86_64.tgz

pigsty/
pigsty/liblua5.2-0_5.2.4-2_amd64.deb
.................. # 许多软件包
pigsty/distro-info-data_0.52ubuntu0.6_all.deb

[ OK ] package = finish pigsty-pkg-v2.6.0.ubuntu22.x86_64.tgz 48f9cb2dd2cabb61b115bfe2ac9e002d
-rw-rw-r-- 1 vagrant vagrant 1.2G Feb 29 03:09 /tmp/pkg.tgz
scp ubuntu22:/tmp/pkg.tgz v2.6.0/pigsty-pkg-v2.6.0.ubuntu22.x86_64.tgz

3 - 声明配置

使用声明式的配置来描述数据库集群与基础设施

Pigsty将基础设施和数据库视为代码：Database as Code & Infra as Code

你可以通过声明式的接口/配置文件来描述基础设施和数据库集群，你只需在配置清单（Inventory）中描述你的需求，然后用简单的幂等剧本使其生效即可。

配置清单

每一套 Pigsty 部署都有一个相应的 配置清单（Inventory）。它可以以 YAML 的形式存储在本地，并使用 git 管理；或从 CMDB 或任何 ansible 兼容的方式动态生成。

Pigsty 默认使用一个名为 pigsty.yml 的单体 YAML 配置文件作为默认的配置清单，它位于 Pigsty 源码主目录下，但你也可以通过命令行参数-i指定路径以使用别的配置清单。

清单由两部分组成：全局变量 和多个 组定义 。前者 all.vars 通常用于描述基础设施，并为集群设置全局默认参数。后者 all.children 则负责定义新的集群（PGSQL/Redis/MinIO/ETCD等等）。一个配置清单文件从最顶层来看大概如下所示：

all:                  # 顶层对象：all
  vars: {...}         # 全局参数
  children:           # 组定义
    infra:            # 组定义：'infra'
      hosts: {...}        # 组成员：'infra'
      vars:  {...}        # 组参数：'infra'
    etcd:    {...}    # 组定义：'etcd'
    pg-meta: {...}    # 组定义：'pg-meta'
    pg-test: {...}    # 组定义：'pg-test'
    redis-test: {...} # 组定义：'redis-test'
    # ...

在 Pigsty 的 files/pigsty 目录中，有许多不同场景的预置配置模板可供参考选用。

集群

每个组定义通常代表一个集群，可以是节点集群、PostgreSQL 集群、Redis 集群、Etcd 集群或 Minio 集群等。它们都使用相同的格式：hosts 和 vars。你可以用 all.children.<cls>.hosts 定义集群成员，并使用 all.children.<cls>.vars 中的集群参数描述集群。以下是名为 pg-test 的三节点 PostgreSQL 高可用集群的定义示例：

pg-test:   # 集群名称
  vars:    # 集群参数
    pg_cluster: pg-test
  hosts:   # 集群成员
    10.10.10.11: { pg_seq: 1, pg_role: primary } # 实例1，在 10.10.10.11 上，主库
    10.10.10.12: { pg_seq: 2, pg_role: replica } # 实例2，在 10.10.10.12 上，从库
    10.10.10.13: { pg_seq: 3, pg_role: offline } # 实例3，在 10.10.10.13 上，从库

你也可以为特定的主机/实例定义参数，也称为实例参数。它将覆盖集群参数和全局参数，实例参数通常用于为节点和数据库实例分配身份（实例号，角色）。

参数

全局变量、组变量和主机变量都是由一系列 键值对 组成的字典对象。每一对都是一个命名的参数，由一个字符串名作为键，和一个值组成。值是五种类型之一：布尔值、字符串、数字、数组或对象。查看配置参数以了解详细的参数语法语义。

绝大多数参数都有着合适的默认值，身份参数 除外；它们被用作标识符，并必须显式配置，例如 pg_cluster， pg_role，以及 pg_seq。

参数可以被更高优先级的同名参数定义覆盖，优先级如下所示：

命令行参数 > 剧本变量  >  主机变量（实例参数）  >  组变量（集群参数）  >  全局变量（全局参数） >  默认值

例如：

使用命令行参数 -e pg_clean=true 强制删除现有数据库
使用实例参数 pg_role 和 pg_seq 来为一个数据库实例分配角色与标号。
使用集群变量来为集群设置默认值，如集群名称 pg_cluster 和数据库版本 pg_version
使用全局变量为所有 PGSQL 集群设置默认值，如使用的默认参数和插件列表
如果没有显式配置 pg_version ，默认值 16 版本号会作为最后兜底的缺省值。

参考

Pigsty 带有 280+ 配置参数，分为以下32个参数组，详情请参考配置参数。

模块	参数组	描述	数量
`INFRA`	`META`	Pigsty 元数据	4
`INFRA`	`CA`	自签名公私钥基础设施 CA	3
`INFRA`	`INFRA_ID`	基础设施门户，Nginx域名	2
`INFRA`	`REPO`	本地软件仓库	9
`INFRA`	`INFRA_PACKAGE`	基础设施软件包	2
`INFRA`	`NGINX`	Nginx 网络服务器	7
`INFRA`	`DNS`	DNSMASQ 域名服务器	3
`INFRA`	`PROMETHEUS`	Prometheus 时序数据库全家桶	16
`INFRA`	`GRAFANA`	Grafana 可观测性全家桶	6
`INFRA`	`LOKI`	Loki 日志服务	4
`NODE`	`NODE_ID`	节点身份参数	5
`NODE`	`NODE_DNS`	节点域名 & DNS解析	5
`NODE`	`NODE_PACKAGE`	节点仓库源 & 安装软件包	5
`NODE`	`NODE_TUNE`	节点调优与内核特性开关	10
`NODE`	`NODE_ADMIN`	管理员用户与SSH凭证管理	7
`NODE`	`NODE_TIME`	时区，NTP服务与定时任务	5
`NODE`	`NODE_VIP`	可选的主机节点集群L2 VIP	8
`NODE`	`HAPROXY`	使用HAProxy对外暴露服务	10
`NODE`	`NODE_EXPORTER`	主机节点监控与注册	3
`NODE`	`PROMTAIL`	Promtail日志收集组件	4
`DOCKER`	`DOCKER`	Docker容器服务（可选）	4
`ETCD`	`ETCD`	ETCD DCS 集群	10
`MINIO`	`MINIO`	MINIO S3 对象存储	15
`REDIS`	`REDIS`	Redis 缓存	20
`PGSQL`	`PG_ID`	PG 身份参数	11
`PGSQL`	`PG_BUSINESS`	PG 业务对象定义	12
`PGSQL`	`PG_INSTALL`	安装 PG 软件包 & 扩展	10
`PGSQL`	`PG_BOOTSTRAP`	使用 Patroni 初始化 HA PG 集群	39
`PGSQL`	`PG_PROVISION`	创建 PG 数据库内对象	9
`PGSQL`	`PG_BACKUP`	使用 pgBackRest 设置备份仓库	5
`PGSQL`	`PG_SERVICE`	对外暴露服务, 绑定 vip, dns	9
`PGSQL`	`PG_EXPORTER`	PG 监控，服务注册	15

4 - 准备工作

如何准备部署 Pigsty 所需的节点，操作系统，管理员用户，端口，与所需权限。

与 Pigsty 部署有关的 101 入门知识。

节点准备

Pigsty 支持 Linux 内核与 x86_64/amd64 架构，适用于任意节点。

所谓节点（node），指 ssh 可达并提供裸操作系统环境的资源，例如物理机，虚拟机，或者启用了 systemd 与 sshd 的操作系统容器。

部署 Pigsty 最少需要一个节点。最低配置要求为 1C1G，推荐至少使用 2C4G 以上的机型，适用配置上不封顶，参数会自动优化适配。

作为 Demo，个人站点，或者开发环境时，可以使用单个节点。作为独立监控基础设施使用时，建议使用 1-2 个节点，作为高可用 PostgreSQL 数据库集群使用时，建议至少使用 3 个节点。用于核心场景时，建议使用至少 4-5 个节点。

充分利用 IaC 工具完成琐事

手工配置大规模生产环境繁琐且容易出错，我们建议您充分利用 Infra as Code 工具，解决此类问题。

您可以使用 Pigsty 提供的 Terraform 模板与 Vagrant 模板，使用 IaC 的方式一键创建所需的节点环境，完成好网络，操作系统，管理用户，权限，安全组的置备工作。

网络准备

Pigsty 要求节点使用 静态IPv4地址，即您应当为节点显式分配指定固定的 IP 地址，而不应当使用 DHCP 动态分配的地址。

节点使用的 IP 地址应当是节点用于内网通信的首要 IP 地址，并将作为节点的唯一身份标识符。

如果您希望使用可选的 Node VIP 与 PG VIP 功能，应当确保所有节点位于一个大二层网络中。

您的防火墙策略应当保证所需的端口在节点间开放，不同模块所需的具体端口列表请参考 节点：端口。

应该暴露哪些端口？

暴露端口的方法取决于您的网络安全策略实现，例如：公有云上的安全组策略，或本地 iptables 记录，防火墙配置等。如果您只是希望尝尝鲜，不在乎安全，并且希望一切越简单越好，那么您可以仅对外部用户按需开放 5432 端口（ PostgreSQL 数据库）与 3000 端口（Grafana 可视化界面）。

在 Infra节点 上的 Nginx 默认会对外暴露 80/443 端口提供 Web 服务，并通过域名对不同服务进行区分，这一端口应当对办公网络（或整个整个互联网）开放。

严肃的生产数据库服务端口通常不应当直接暴露在公网上，如果您确实需要这么做，建议首先查阅安全最佳实践，并小心行事。

操作系统准备

Pigsty 支持多种基于 Linux 内核的服务器操作系统发行版，我们建议使用 RockyLinux 8.9 或 Ubuntu 22.04.3 作为安装 Pigsty 的 OS。

Pigsty 支持 RHEL (7,8,9)，Debian (11,12)，Ubuntu (20,22) 以及多种与之兼容的操作系统发行版，完整操作系统列表请参考 兼容性。

在使用多个节点镜进行部署时，我们强烈建议您在所有用于 Pigsty 部署的节点上，使用相同版本的操作系统发行版与 Linux 内核版本

我们强烈建议使用干净，全新安装的最小化安装的服务器操作系统环境，并使用 en_US 作为首要语言。

如何安装并启用 en_US locale？

使用其他系统语言包时，如何确保 en_US 本地化规则集可用：

yum install -y glibc-locale-source glibc-langpack-en
localedef -i en_US -f UTF-8 en_US.UTF-8
localectl set-locale LANG=en_US.UTF-8

注：Pigsty 部署的 PostgreSQL 集群默认使用 C.UTF8 locale，但字符集定义使用 en_US 以确保 pg_trgm 扩展可以正常工作。如果您确实不需要此功能，可以配置 pg_lc_ctype 的值为 C.UTF8 ，以避免在系统语言包缺失的情况下，数据库初始化报错的问题。

管理用户准备

在安装 Pigsty 的节点上，您需要拥有一个 “管理用户” —— 拥有免密 ssh 登陆权限与免密 sudo 权限。

免密 sudo 是必选项，用于在安装过程中执行需要 sudo 权限的命令，例如安装软件包，配置系统参数等。

如何配置管理用户的免密码 sudo 权限？

假设您的管理用户名为 vagrant ，则可以创建 /etc/sudoers.d/vagrant 文件，并添加以下记录：

%vagrant ALL=(ALL) NOPASSWD: ALL

则 vagrant 用户即可免密 sudo 执行所有命令。如果你的用户名不是 vagrant，请将上面操作中的 vagrant 替换为您的用户名。

避免使用 root 用户安装

尽管使用 root 用户安装 Pigsty 是可行的，但我们不推荐这样做。

安全最佳实践是使用一个不同于根用户（root）与数据库超级用户 (postgres) 的专用管理员用户（如：dba）

Pigsty 提供了专用剧本任务，可以使用一个现有的管理用户（例如 root），输入 ssh/sudo 密码，创建一个专用的 管理员用户。

SSH 权限准备

除了免密 sudo 权限， Pigsty 还需要管理用户免密 ssh 登陆的权限。

对于单机安装的节点而言，这意味着本机上的管理用户可以通过 ssh 免密码登陆到本机上。如果的 Pigsty 部署涉及到多个节点，这意味着管理节点上的管理用户应当可以通过 ssh 免密码登陆到所有被 Pigsty 纳管的节点上（包括本机），并免密执行 sudo 命令。

单机安装时，在 configure 过程中，如果您的当前管理用户没有 SSH key，Pigsty 会尝试修复此问题：随机生成一对新的 id_rsa 密钥，并添加至本地 ~/.ssh/authroized_keys 文件确保本机管理用户的 SSH 登陆能力。

Pigsty 默认会为您在纳管的节点上创建一个可用的管理用户 dba (uid=88)，如果您已经使用了此用户，我们建议您修改 node_admin_username 使用新的用户名与其他 uid，或通过 node_admin_enabled 参数禁用。

如何配置管理用户的 ssh 免密码登陆？

假设您的管理用户名为 vagrant，则以 vagrant 用户身份执行以下命令，会为其生成公私钥对 ~/.ssh/id_rsa[.pub] 用于登陆。如果已经存在公私钥对，则无需生成新密钥对。

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

生成的公钥默认位于：/home/vagrant/.ssh/id_rsa.pub，私钥默认位于：/home/vagrant/.ssh/id_rsa，如果您操作系统用户名不叫 vagrant，将上面的 vagrant 替换为您的用户名即可。

您应当将公钥文件（id_rsa.pub）追加写入到需要登陆机器的对应用户上：/home/vagrant/.ssh/authorized_keys 文件中。如果您已经可以直接通过密码访问远程机器，可以直接通过ssh-copy-id的方式拷贝公钥：

ssh-copy-id <ip>                        # 输入密码以完成公钥拷贝
sshpass -p <password> ssh-copy-id <ip>  # 直接将密码嵌入命令中，避免交互式密码输入（注意安全！）

Pigsty 推荐将管理用户的创建，权限配置与密钥分发放在虚拟机的置备阶段完成，作为标准化交付内容的一部分。

SSH 例外情况

如果您的 SSH 访问有一些额外限制，例如，使用了跳板机，或者进行了某些定制化修改，无法通过简单的 ssh <ip> 方式访问，那么可以考虑使用 ssh 别名。

例如，如果您的服务器可以通过 ~/.ssh/config 中定义的别名，例如 meta 通过 ssh 访问，那么可以为 配置清单 中的节点配置 ansible_host 参数，指定 SSH Alias：

nodes:    
  hosts:  # 10.10.10.10 无法直接 ssh，但可以通过ssh别名 `meta` 访问
    10.10.10.10: { ansible_host: meta }

如果 SSH 别名无法满足您的需求，Ansible 还提供了一系列自定义 ssh 连接参数，可以精细控制 SSH 连接的行为。

最后，如果以下命令可以在管理节点上使用管理用户成功执行，意味着该目标节点上的管理用户与权限配置已经妥当：

ssh <ip|alias> 'sudo ls'

软件准备

在 管理节点 上，Pigsty 需要使用 Ansible 发起控制命令。如果您使用本地单机安装，那么管理节点和被管理的节点是同一台，需要安装 Ansible。对于普通节点，则无需安装 Ansible。

在 bootstrap 过程中，Pigsty 会尽最大努力自动为您完成安装 Ansible 这一任务，但您也可以选择手工安装 Ansible。手工安装 Ansible 的过程因不同操作系统发行版/大版本而异（通常涉及到额外的弱依赖 jmespath）：

sudo dnf install -y ansible python3.11-jmespath

sudo yum install -y ansible   # EL7 无需显式安装 Jmespath

sudo apt install -y ansible python3-jmespath

brew install ansible

为了安装 Pigsty，您还需要准备 Pigsty 源码包。您可以直接从 GitHub Release 页面下载特定版本，或使用以下命令获取最新稳定版本：

curl -L https://get.pigsty.cc/latest  | bash

如果您的环境没有互联网访问，也可以考虑直接从 GitHub Release 页面或其他渠道下载针对不同操作系统发行版预先制作的 离线安装包。

5 - 资源规划

如何明确您的需求，并根据需求规划置备所需的资源。

TBD

6 - 执行剧本

Pigsty 使用 Ansible 剧本来实现所需的安装部署管理功能，但如果只是使用的话，您并不需要了解太多细节。

在 Pigsty 中，剧本 / Playbooks 用于在节点上安装模块。

剧本可以视作可执行文件直接执行，例如：./install.yml.

剧本

以下是 Pigsty 中默认包含的剧本：

剧本	功能
`install.yml`	在当前节点上一次性完整安装 Pigsty
`infra.yml`	在 infra 节点上初始化 pigsty 基础设施
`infra-rm.yml`	从 infra 节点移除基础设施组件
`node.yml`	纳管节点，并调整节点到期望的状态
`node-rm.yml`	从 pigsty 中移除纳管节点
`pgsql.yml`	初始化 HA PostgreSQL 集群或添加新的从库实例
`pgsql-rm.yml`	移除 PostgreSQL 集群或移除从库实例
`pgsql-user.yml`	向现有的 PostgreSQL 集群添加新的业务用户
`pgsql-db.yml`	向现有的 PostgreSQL 集群添加新的业务数据库
`pgsql-monitor.yml`	监控纳管远程 postgres 实例
`pgsql-migration.yml`	为现有的 PostgreSQL 生成迁移手册和脚本
`redis.yml`	初始化 redis 集群/节点/实例
`redis-rm.yml`	移除 redis 集群/节点/实例
`etcd.yml`	初始化 etcd 集群（patroni HA DCS所需）
`minio.yml`	初始化 minio 集群（pgbackrest 备份仓库备选项）
`cert.yml`	使用 pigsty 自签名 CA 颁发证书（例如用于客户端）
`docker.yml`	在节点上安装 docker
`mongo.yml`	在节点上安装 Mongo/FerretDB

一次性安装

特殊的剧本 install.yml 实际上是一个复合剧本，它在当前环境上安装所有以下组件。


  playbook  / command / group         infra           nodes    etcd     minio     pgsql
[infra.yml] ./infra.yml [-l infra]   [+infra][+node] 
[node.yml]  ./node.yml                               [+node]  [+node]  [+node]   [+node]
[etcd.yml]  ./etcd.yml  [-l etcd ]                            [+etcd]
[minio.yml] ./minio.yml [-l minio]                                     [+minio]
[pgsql.yml] ./pgsql.yml                                                          [+pgsql]

请注意，NODE 和 INFRA 之间存在循环依赖：为了在 INFRA 上注册 NODE，INFRA 应该已经存在，而 INFRA 模块依赖于 INFRA节点上的 NODE 模块才能工作。

为了解决这个问题，INFRA 模块的安装剧本也会在 INFRA 节点上安装 NODE 模块。所以，请确保首先初始化 INFRA 节点。

如果您非要一次性初始化包括 INFRA 在内的所有节点，install.yml 剧本就是用来解决这个问题的：它会正确的处理好这里的循环依赖，一次性完成整个环境的初始化。

Ansible

执行剧本需要 ansible-playbook 可执行文件，该文件包含在 ansible rpm/deb 包中。

Pigsty 将在准备期间在尽最大努力尝试在当前节点安装 ansible。

您可以自己使用 yum / apt / brew install ansible 来安装 Ansible，它含在各大发行版的默认仓库中。

了解 ansible 对于使用 Pigsty 很有帮助，但也不是必要的。对于基本使用，您只需要注意三个参数就足够了：

-l|--limit <pattern> : 限制剧本在特定的组/主机/模式上执行目标（在哪里/Where）
-t|--tags <tags>: 只运行带有特定标签的任务（做什么/What）
-e|--extra-vars <vars>: 传递额外的命令行参数（怎么做/How）

指定执行对象

您可以使用 -l|-limit <selector> 限制剧本的执行目标。

缺少此值可能很危险，因为大多数剧本会在 all 分组，也就是所有主机上执行，使用时务必小心。

以下是一些主机限制的示例：

./pgsql.yml                              # 在所有主机上运行（非常危险！）
./pgsql.yml   -l pg-test                 # 在 pg-test 集群上运行
./pgsql.yml   -l 10.10.10.10             # 在单个主机 10.10.10.10 上运行
./pgsql.yml   -l pg-*                    # 在与通配符 `pg-*` 匹配的主机/组上运行
./pgsql.yml   -l '10.10.10.11,&pg-test'  # 在组 pg-test 的 10.10.10.10 上运行
/pgsql-rm.yml -l 'pg-test,!10.10.10.11'  # 在 pg-test 上运行，除了 10.10.10.11 以外
./pgsql.yml   -l pg-test                 # 在 pg-test 集群的主机上执行 pgsql 剧本

执行剧本子集

你可以使用 -t|--tags <tag> 执行剧本的子集。你可以在逗号分隔的列表中指定多个标签，例如 -t tag1,tag2。

如果指定了任务子集，将执行给定标签的任务，而不是整个剧本。以下是任务限制的一些示例：

./pgsql.yml -t pg_clean    # 如果必要，清理现有的 postgres
./pgsql.yml -t pg_dbsu     # 为 postgres dbsu 设置操作系统用户 sudo
./pgsql.yml -t pg_install  # 安装 postgres 包和扩展
./pgsql.yml -t pg_dir      # 创建 postgres 目录并设置 fhs
./pgsql.yml -t pg_util     # 复制工具脚本，设置别名和环境
./pgsql.yml -t patroni     # 使用 patroni 引导 postgres
./pgsql.yml -t pg_user     # 提供 postgres 业务用户
./pgsql.yml -t pg_db       # 提供 postgres 业务数据库
./pgsql.yml -t pg_backup   # 初始化 pgbackrest 仓库和 basebackup
./pgsql.yml -t pgbouncer   # 与 postgres 一起部署 pgbouncer sidecar
./pgsql.yml -t pg_vip      # 使用 vip-manager 将 vip 绑定到 pgsql 主库
./pgsql.yml -t pg_dns      # 将 dns 名称注册到 infra dnsmasq
./pgsql.yml -t pg_service  # 使用 haproxy 暴露 pgsql 服务
./pgsql.yml -t pg_exporter # 使用 haproxy 暴露 pgsql 服务
./pgsql.yml -t pg_register # 将 postgres 注册到 pigsty 基础设施

# 运行多个任务：重新加载 postgres 和 pgbouncer hba 规则
./pgsql.yml -t pg_hba,pgbouncer_hba,pgbouncer_reload

# 运行多个任务：刷新 haproxy 配置并重新加载
./node.yml -t haproxy_config,haproxy_reload

传递额外参数

您可以通过 -e|-extra-vars KEY=VALUE 传递额外的命令行参数。

命令行参数具有压倒性的优先级，以下是一些额外参数的示例：

./node.yml -e ansible_user=admin -k -K                  # 作为另一个用户运行剧本（带有 admin sudo 密码）
./pgsql.yml -e pg_clean=true                            # 在初始化 pgsql 实例时强制清除现有的 postgres
./pgsql-rm.yml -e pg_uninstall=true                     # 在 postgres 实例被删除后明确卸载 rpm
./redis.yml -l 10.10.10.11 -e redis_port=6379 -t redis  # 初始化一个特定的 redis 实例：10.10.10.11:6379
./redis-rm.yml -l 10.10.10.13 -e redis_port=6379        # 删除一个特定的 redis 实例：10.10.10.11:6379

大多数剧本都是幂等的，这意味着在未打开保护选项的情况下，一些部署剧本可能会 删除现有的数据库 并创建新的数据库。

请仔细阅读文档，多次校对命令，并小心操作。作者不对因误用造成的任何数据库损失负责。

7 - 置备机器

介绍 Pigsty 演示所使用的标准四节点沙箱环境，以及如何使用 Vagrant 与 Terraform 置备所需的虚拟机。

Pigsty 在节点上运行，这些节点可以是裸机或虚拟机。您可以手工置备它们，或使用 terraform 和 vagrant 这样的工具在云端或本地进行自动配置。

沙箱环境

Pigsty 带有一个演示沙箱，所谓沙箱，就是专门用来演示/测试的环境：IP地址和其他标识符都预先固定配置好，便于复现各种演示用例。

默认的沙箱环境由4个节点组成，配置文件请参考 demo.yml。

沙箱的 4 个节点有着固定的 IP 地址：10.10.10.10、10.10.10.11、10.10.10.12、10.10.10.13。

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

meta 10.10.10.10 pg-meta pg-meta-1

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

node-1 10.10.10.11 pg-test.pg-test-1
node-2 10.10.10.12 pg-test.pg-test-2
node-3 10.10.10.13 pg-test.pg-test-3

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

10.10.10.2 pg-meta
10.10.10.3 pg-test

在 meta 节点上，还有一个单实例的 etcd “集群”和一个单实例的 minio “集群”。

您可以在本地虚拟机或云虚拟机上运行沙箱。Pigsty 提供基于 Vagrant 的本地沙箱（使用 Virtualbox/libvirt 启动本地虚拟机）以及基于 Terraform 的云沙箱（使用云供应商 API 创建虚拟机）。

本地沙箱可以在您的 Mac/PC 上免费运行。运行完整的4节点沙箱，您的 Mac/PC 应至少拥有 4C/8G。
云沙箱可以轻松创建和共享，单需要一个公有云帐户才行。云上虚拟机可以按需创建/一键销毁，对于快速测试来说非常便宜省事。

此外，Pigsty 还提供了一个 42节点的生产仿真环境沙箱 prod.yml。

Vagrant

Vagrant 可以按照声明式的方式创建本地虚拟机。请查看 Vagrant 模板介绍以获取详情。

安装

确保您的操作系统中已经安装并可以使用 Vagrant 和 Virtualbox。

如果您使用的是 macOS，您可以使用 homebrew 一键命令安装它们，注意安装 Virtualbox 后需要重启系统。

如果你用的是 Linux，可以使用 virtualbox，也可以考虑使用 KVM: vagrant-libvirt。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install vagrant virtualbox ansible   # 在 MacOS 中可以轻松一键安装，但只有 x86_64 Intel 芯片的可以

配置

vagarnt/Vagranfile 是一个 Ruby 脚本文件，用来描述 Vagrant 要创建的虚拟机节点。Pigsty 提供了一些默认的配置模板：

模板	快捷方式	规格	注释
meta.rb	`v1`	4C8G x 1	单一 Meta 节点
full.rb	`v4`	2C4G + 1C2G x 3	完整的4节点沙盒示例
el7.rb	`v7`	2C4G + 1C2G x 3	EL7 3-节点测试环境
el8.rb	`v8`	2C4G + 1C2G x 3	EL8 3-节点测试环境
el9.rb	`v9`	2C4G + 1C2G x 3	EL9 3-节点测试环境
build.rb	`vb`	2C4G x 3	3-节点 EL7,8,9 构建环境
check.rb	`vc`	2C4G x 30	30 EL7-9, PG12-16 测试环境
minio.rb	`vm`	2C4G x 3 + Disk	3-节点 MinIO/etcd 测试环境
prod.rb	`vp`	2C4G x 42	42节点的生产模拟环境

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

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

您可以使用 vagrant/switch 脚本切换 Vagrant 配置文件，它会根据规格以及虚拟机软件类型，渲染生成最终的 Vagrantfile。

cd ~/pigsty
vagrant/switch <spec>

vagrant/switch meta     # singleton meta        | 别名：`make v1`
vagrant/switch full     # 4-node sandbox        | 别名：`make v4`
vagrant/switch el7      # 3-node el7 test       | 别名：`make v7`
vagrant/switch el8      # 3-node el8 test       | 别名：`make v8`
vagrant/switch el9      # 3-node el9 test       | 别名：`make v9`
vagrant/switch prod     # prod simulation       | 别名：`make vp`
vagrant/switch build    # building environment  | 别名：`make vd`
vagrant/switch minio    # 3-node minio env
vagrant/switch check    # 30-node check env

虚拟机管理

当您使用 vagrant/Vagrantfile 描述了所需的虚拟机后，你可以使用vagrant up命令创建这些虚拟机。

Pigsty 模板默认会使用你的 ~/.ssh/id_rsa[.pub] 作为这些虚拟机的默认ssh凭证。

在开始之前，请确保你有一个有效的ssh密钥对，你可以通过以下方式生成一对：ssh-keygen -t rsa -b 2048

此外，还有一些 makefile 快捷方式包装了 vagrant 命令，你可以使用它们来管理虚拟机。

make         # 等于 make start
make new     # 销毁现有虚拟机，根据规格创建新的
make ssh     # 将 SSH 配置写入到 ~/.ssh/ 中 （新虚拟机拉起后必须完成这一步）
make dns     # 将 虚拟机 DNS 记录写入到 /etc/hosts 中 （如果想使用名称访问虚拟机)
make start   # 等于先执行 up ，再执行 ssh 
make up      # 根据配置拉起虚拟机，或启动现有虚拟机
make halt    # 关停现有虚拟机 (down,dw)
make clean   # 销毁现有虚拟机 (clean/del/destroy)
make status  # 显示虚拟机状态 (st)
make pause   # 暂停虚拟机运行 (suspend,pause)
make resume  # 恢复虚拟机运行 (resume)
make nuke    # 使用 virsh 销毁所有虚拟机 (仅libvirt可用)

快捷方式

你可以使用以下的 Makefile 快捷方式使用 vagrant 拉起虚拟机环境。

make meta     # 单个元节点
make full     # 4-节点沙箱
make el7      # 3-节点 el7 测试环境
make el8      # 3-节点 el8 测试环境
make el9      # 3-节点 el9 测试环境
make prod     # 42 节点生产仿真环境
make build    # 3-节点 EL7,8,9 构建环境
make check    # 30-节点构建校验测试环境
make minio    # 3-节点 MinIO 测试环境

make meta  install  # 进行完整的单机安装
make full  install  # 进行4节点沙箱安装
make prod  install  # 进行42节点生产仿真环境安装
make check install  # 进行30节点本地测试环境安装
...

Terraform

Terraform是一个开源的实践“基础设施即代码”的工具：描述你想要的云资源，然后一键创建它们。

Pigsty 提供了 AWS，阿里云，腾讯云的 Terraform 模板，您可以使用它们在云上一键创建虚拟机。

在 MacOS 上，Terraform 可以使用 homebrew 一键安装：brew install terraform。你需要创建一个云帐户，获取 AccessKey 和 AccessSecret 凭证来继续下面的操作。

terraform/目录包含两个示例模板：一个 AWS 模板，一个阿里云模板，你可以按需调整它们，或者作为其他云厂商配置文件的参考，让我们用阿里云为例：

cd terraform                         # 进入 Terraform 模板目录
cp spec/alicloud.tf terraform.tf     # 使用 阿里云 Terraform 模板

在执行 terraform apply 拉起虚拟机之前，你要执行一次 terraform init 安装相应云厂商的插件。

terraform init      # 安装 terraform 云供应商插件：例如默认的 aliyun 插件 (第一次使用时安装即可)
terraform apply     # 生成执行计划，显示会创建的云资源：虚拟机，网络，安全组，等等等等……

运行 apply 子命令并按提示回答 yes 后，Terraform 将为你创建虚拟机以及其他云资源（网络，安全组，以及其他各种玩意）。

执行结束时，管理员节点的IP地址将被打印出来，你可以登录并开始完成 Pigsty 本身的安装

8 - 安全考量

Pigsty部署中与安全有关的考量

Pigsty 的默认配置已经足以覆盖绝大多数场景对于安全的需求。

Pigsty 已经提供了开箱即用的认证与访问控制模型，对于绝大多数场景已经足够安全。

如果您希望进一步加固系统的安全性，那么以下建议供您参考：

机密性

重要文件

保护你的 pigsty.yml 配置文件或CMDB

pigsty.yml 配置文件通常包含了高度敏感的机密信息，您应当确保它的安全。
严格控制管理节点的访问权限，仅限 DBA 或者 Infra 管理员访问。
严格控制 pigsty.yml 配置文件仓库的访问权限（如果您使用 git 进行管理）

保护你的 CA 私钥和其他证书，这些文件非常重要。

相关文件默认会在管理节点Pigsty源码目录的 files/pki 内生成。
你应该定期将它们备份到一个安全的地方存储。

密码

在生产环境部署时，必须更改这些密码，不要使用默认值！

grafana_admin_password : pigsty
pg_admin_password : DBUser.DBA
pg_monitor_password : DBUser.Monitor
pg_replication_password : DBUser.Replicator
patroni_password : Patroni.API
haproxy_admin_password : pigsty
minio_secret_key : minioadmin

如果您使用MinIO，请修改MinIO的默认用户密码，与pgbackrest中的引用

请修改 MinIO 普通用户的密码：minio_users.[pgbacrest].secret_key
请修改 pgbackrest 中对 MinIO 使用的备份用户密码：pgbackrest_repo.minio.s3_key_secret

如果您使用远程备份仓库，请务必启用备份加密，并设置加解密密码

设置 pgbackrest_repo.*.cipher_type 为 aes-256-cbc
设置密码时可以使用 ${pg_cluster} 作为密码的一部分，避免所有集群使用同一个密码

为 PostgreSQL 使用安全可靠的密码加密算法

使用 pg_pwd_enc 默认值 scram-sha-256 替代传统的 md5
这是默认行为，如果没有特殊理由（出于对历史遗留老旧客户端的支持），请不要将其修改回 md5

使用 passwordcheck 扩展强制执行强密码。

在 pg_libs 中添加 $lib/passwordcheck 来强制密码策略。

使用加密算法加密远程备份

在 pgbackrest_repo 的备份仓库定义中使用 repo_cipher_type 启用加密

为业务用户配置密码自动过期实践

你应当为每个业务用户设置一个密码自动过期时间，以满足合规要求。

配置自动过期后，请不要忘记在巡检时定期更新这些密码。

- { name: dbuser_meta , password: Pleas3-ChangeThisPwd ,expire_in: 7300 ,pgbouncer: true ,roles: [ dbrole_admin ]    ,comment: pigsty admin user }
- { name: dbuser_view , password: Make.3ure-Compl1ance  ,expire_in: 7300 ,pgbouncer: true ,roles: [ dbrole_readonly ] ,comment: read-only viewer for meta database }
- { name: postgres     ,superuser: true  ,expire_in: 7300                        ,comment: system superuser }
- { name: replicator ,replication: true  ,expire_in: 7300 ,roles: [pg_monitor, dbrole_readonly]   ,comment: system replicator }
- { name: dbuser_dba   ,superuser: true  ,expire_in: 7300 ,roles: [dbrole_admin]  ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 , comment: pgsql admin user }
- { name: dbuser_monitor ,roles: [pg_monitor] ,expire_in: 7300 ,pgbouncer: true ,parameters: {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment: pgsql monitor user }

不要将更改密码的语句记录到 postgres 日志或其他日志中

SET log_statement TO 'none';
ALTER USER "{{ user.name }}" PASSWORD '{{ user.password }}';
SET log_statement TO DEFAULT;

IP地址

为 postgres/pgbouncer/patroni 绑定指定的 IP 地址，而不是所有地址。

默认的 pg_listen 地址是 0.0.0.0，即所有 IPv4 地址。
考虑使用 pg_listen: '${ip},${vip},${lo}' 绑定到特定IP地址（列表）以增强安全性。

不要将任何端口直接暴露到公网IP上，除了基础设施出口Nginx使用的端口（默认80/443）

出于便利考虑，Prometheus/Grafana 等组件默认监听所有IP地址，可以直接从公网IP端口访问
您可以修改它们的配置文件，只监听内网IP地址，限制其只能通过 Nginx 门户通过域名访问，你也可以当使用安全组，防火墙规则来实现这些安全限制。
出于便利考虑，Redis服务器默认监听所有IP地址，您可以修改 redis_bind_address 只监听内网IP地址。

使用 HBA 限制 postgres 客户端访问

有一个增强安全性的配置模板：security.yml

限制 patroni 管理访问权限：仅 infra/admin 节点可调用控制API

默认情况下，这是通过 restapi.allowlist 限制的。

网络流量

使用 SSL 和域名，通过Nginx访问基础设施组件

Nginx SSL 由 nginx_sslmode 控制，默认为 enable。
Nginx 域名由 infra_portal.<component>.domain 指定。

使用 SSL 保护 Patroni REST API

patroni_ssl_enabled 默认为禁用。
由于它会影响健康检查和 API 调用。
注意这是一个全局选项，在部署前你必须做出决定。

使用 SSL 保护 Pgbouncer 客户端流量

pgbouncer_sslmode 默认为 disable
它会对 Pgbouncer 有显著的性能影响，所以这里是默认关闭的。

完整性

为关键场景下的 PostgreSQL 数据库集群配置一致性优先模式（例如与钱相关的库）

pg_conf 数据库调优模板，使用 crit.yml 将以一些可用性为代价，换取最佳的数据一致性。

使用crit节点调优模板，以获得更好的一致性。

node_tune 主机调优模板使用 crit ，可以以减少脏页比率，降低数据一致性风险。

启用数据校验和，以检测静默数据损坏。

pg_checksum 默认为 off，但建议开启。
当启用 pg_conf = crit.yml 数据库模板时，校验和是强制开启的。

记录建立/切断连接的日志

该配置默认关闭，但在 crit.yml 配置模板中是默认启用的。
可以手工配置集群，启用 log_connections 和 log_disconnections 功能参数。

如果您希望彻底杜绝PG集群在故障转移时脑裂的可能性，请启用watchdog

如果你的流量走默认推荐的 HAProxy 分发，那么即使你不启用 watchdog，你也不会遇到脑裂的问题。
如果你的机器假死，Patroni 被 kill -9 杀死，那么 watchdog 可以用来兜底：超时自动关机。
最好不要在基础设施节点上启用 watchdog。

可用性

对于关键场景的PostgreSQL数据库集群，请使用足够的节点/实例数量

你至少需要三个节点（能够容忍一个节点的故障）来实现生产级的高可用性。
如果你只有两个节点，你可以容忍特定备用节点的故障。
如果你只有一个节点，请使用外部的 S3/MinIO 进行冷备份和 WAL 归档存储。

对于 PostgreSQL，在可用性和一致性之间进行权衡

pg_rpo : 可用性与一致性之间的权衡
pg_rto : 故障概率与影响之间的权衡

不要直接通过固定的 IP 地址访问数据库；请使用 VIP、DNS、HAProxy 或它们的排列组合

使用 HAProxy 进行服务接入
在故障切换/主备切换的情况下，Haproxy 将处理客户端的流量切换。

在重要的生产部署中使用多个基础设施节点（例如，1~3）

小规模部署或要求宽松的场景，可以使用单一基础设施节点 / 管理节点。
大型生产部署建议设置至少两个基础设施节点互为备份。

使用足够数量的 etcd 服务器实例，并使用奇数个实例（1,3,5,7）

查看 ETCD 管理了解详细信息。

9 - 常见问题

Pigsty 下载，安装，部署常见问题答疑

这里列出了Pigsty用户在下载、安装、部署时常遇到的问题，如果您遇到了难以解决的问题，可以提交 Issue 或者联系我们。

如何获取Pigsty软件源码包？

使用以下命令一键安装 Pigsty： bash -c "$(curl -fsSL https://get.pigsty.cc/latest)"

上述命令会自动下载最新的稳定版本 pigsty.tgz 并解压到 ~/pigsty 目录。您也可以从以下位置手动下载 Pigsty 源代码的特定版本。

如果您需要在没有互联网的环境中安装，可以提前在有网络的环境中下载好，并通过 scp/sftp 或者 CDROM/USB 传输至生产服务器。

如何加速从上游仓库下载 RPM ?

考虑使用本地仓库镜像，仓库镜像在repo_upstream 参数中配置，你可以选择 region 来使用不同镜像站。

例如，您可以设置 region = china，这样将使用 baseurl 中键为 china 的 URL 而不是 default。

如果防火墙或GFW屏蔽了某些仓库，考虑使用proxy_env 来绕过。

软件包安装失败如何解决？

请注意，Pigsty 的预制 离线软件包 是针对 特定操作系统发行版小版本 打包的，因此如果您使用的操作系统版本没有精确对齐，我们不建议使用离线软件安装包，而是直接从上游下载符合当前操作系统实际情况的软件包版本。

如果在线安装无法解决包冲突问题，您首先可以尝试修改 Pigsty 使用的上游软件源。例如在 EL 系操作系统中， Pigsty 默认的上游软件源中使用 $releasever 这样的大版本占位符，它将被解析为具体的 7，8，9 大版本号，但是许多操作系统发行版都提供了 Vault，允许您使用特定某一个版本的软件包镜像。因此，您可以将 repo_upstream 参数中的 BaseURL 前段替换为具体的 Vault 小版本仓库，例如：

https://mirrors.aliyun.com/rockylinux/$releasever/ （原始 BaseURL 前缀，不带 vault ）
https://mirrors.tuna.tsinghua.edu.cn/centos-vault/7.6.1810/ （使用 7.6 而不是默认的 7.9）
https://mirrors.aliyun.com/rockylinux-vault/8.6/ （使用 8.6 而不是默认的 8.9）
https://mirrors.aliyun.com/rockylinux-vault/9.2/ （使用 9.2 而不是默认的 9.3）

在替换前请注意目标软件源的路径是否真实存在，例如 EPEL 不提供小版本特定的软件源。支持这种方式的上游源包括：base, updates, extras, centos-sclo, centos-sclo-rh, baseos, appstream, extras, crb, powertools, pgdg-common, pgdg1*

repo_upstream:
  - { name: pigsty-local   ,description: 'Pigsty Local'      ,module: local ,releases: [7,8,9] ,baseurl: { default: 'http://${admin_ip}/pigsty'  }} # used by intranet nodes
  - { name: pigsty-infra   ,description: 'Pigsty INFRA'      ,module: infra ,releases: [7,8,9] ,baseurl: { default: 'https://repo.pigsty.io/rpm/infra/$basearch' ,china: 'https://repo.pigsty.cc/rpm/infra/$basearch' }}
  - { name: pigsty-pgsql   ,description: 'Pigsty PGSQL'      ,module: pgsql ,releases: [7,8,9] ,baseurl: { default: 'https://repo.pigsty.io/rpm/pgsql/el$releasever.$basearch' ,china: 'https://repo.pigsty.cc/rpm/pgsql/el$releasever.$basearch' }}
  - { name: nginx          ,description: 'Nginx Repo'        ,module: infra ,releases: [7,8,9] ,baseurl: { default: 'https://nginx.org/packages/centos/$releasever/$basearch/' }}
  - { name: docker-ce      ,description: 'Docker CE'         ,module: infra ,releases: [7,8,9] ,baseurl: { default: 'https://download.docker.com/linux/centos/$releasever/$basearch/stable'        ,china: 'https://mirrors.aliyun.com/docker-ce/linux/centos/$releasever/$basearch/stable'  ,europe: 'https://mirrors.xtom.de/docker-ce/linux/centos/$releasever/$basearch/stable' }}
  - { name: base           ,description: 'EL 7 Base'         ,module: node  ,releases: [7    ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/os/$basearch/'                    ,china: 'https://mirrors.tuna.tsinghua.edu.cn/centos/$releasever/os/$basearch/'           ,europe: 'https://mirrors.xtom.de/centos/$releasever/os/$basearch/'           }}
  - { name: updates        ,description: 'EL 7 Updates'      ,module: node  ,releases: [7    ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/updates/$basearch/'               ,china: 'https://mirrors.tuna.tsinghua.edu.cn/centos/$releasever/updates/$basearch/'      ,europe: 'https://mirrors.xtom.de/centos/$releasever/updates/$basearch/'      }}
  - { name: extras         ,description: 'EL 7 Extras'       ,module: node  ,releases: [7    ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/extras/$basearch/'                ,china: 'https://mirrors.tuna.tsinghua.edu.cn/centos/$releasever/extras/$basearch/'       ,europe: 'https://mirrors.xtom.de/centos/$releasever/extras/$basearch/'       }}
  - { name: epel           ,description: 'EL 7 EPEL'         ,module: node  ,releases: [7    ] ,baseurl: { default: 'http://download.fedoraproject.org/pub/epel/$releasever/$basearch/'            ,china: 'https://mirrors.tuna.tsinghua.edu.cn/epel/$releasever/$basearch/'                ,europe: 'https://mirrors.xtom.de/epel/$releasever/$basearch/'                }}
  - { name: centos-sclo    ,description: 'EL 7 SCLo'         ,module: node  ,releases: [7    ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/sclo/$basearch/sclo/'             ,china: 'https://mirrors.aliyun.com/centos/$releasever/sclo/$basearch/sclo/'              ,europe: 'https://mirrors.xtom.de/centos/$releasever/sclo/$basearch/sclo/'    }}
  - { name: centos-sclo-rh ,description: 'EL 7 SCLo rh'      ,module: node  ,releases: [7    ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/sclo/$basearch/rh/'               ,china: 'https://mirrors.aliyun.com/centos/$releasever/sclo/$basearch/rh/'                ,europe: 'https://mirrors.xtom.de/centos/$releasever/sclo/$basearch/rh/'      }}
  - { name: baseos         ,description: 'EL 8+ BaseOS'      ,module: node  ,releases: [  8,9] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/BaseOS/$basearch/os/'         ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/BaseOS/$basearch/os/'          ,europe: 'https://mirrors.xtom.de/rocky/$releasever/BaseOS/$basearch/os/'     }}
  - { name: appstream      ,description: 'EL 8+ AppStream'   ,module: node  ,releases: [  8,9] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/AppStream/$basearch/os/'      ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/AppStream/$basearch/os/'       ,europe: 'https://mirrors.xtom.de/rocky/$releasever/AppStream/$basearch/os/'  }}
  - { name: extras         ,description: 'EL 8+ Extras'      ,module: node  ,releases: [  8,9] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/extras/$basearch/os/'         ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/extras/$basearch/os/'          ,europe: 'https://mirrors.xtom.de/rocky/$releasever/extras/$basearch/os/'     }}
  - { name: crb            ,description: 'EL 9 CRB'          ,module: node  ,releases: [    9] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/CRB/$basearch/os/'            ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/CRB/$basearch/os/'             ,europe: 'https://mirrors.xtom.de/rocky/$releasever/CRB/$basearch/os/'        }}
  - { name: powertools     ,description: 'EL 8 PowerTools'   ,module: node  ,releases: [  8  ] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/PowerTools/$basearch/os/'     ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/PowerTools/$basearch/os/'      ,europe: 'https://mirrors.xtom.de/rocky/$releasever/PowerTools/$basearch/os/' }}
  - { name: epel           ,description: 'EL 8+ EPEL'        ,module: node  ,releases: [  8,9] ,baseurl: { default: 'http://download.fedoraproject.org/pub/epel/$releasever/Everything/$basearch/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/epel/$releasever/Everything/$basearch/'     ,europe: 'https://mirrors.xtom.de/epel/$releasever/Everything/$basearch/'     }}
  - { name: pgdg-common    ,description: 'PostgreSQL Common' ,module: pgsql ,releases: [7,8,9] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/redhat/rhel-$releasever-$basearch' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/redhat/rhel-$releasever-$basearch' }}
  - { name: pgdg-extras    ,description: 'PostgreSQL Extra'  ,module: pgsql ,releases: [7,8,9] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' }}
  - { name: pgdg-el8fix    ,description: 'PostgreSQL EL8FIX' ,module: pgsql ,releases: [  8  ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-x86_64/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-x86_64/' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-x86_64/' } }
  - { name: pgdg-el9fix    ,description: 'PostgreSQL EL9FIX' ,module: pgsql ,releases: [    9] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-x86_64/'  ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-x86_64/' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-x86_64/' }}
  - { name: pgdg15         ,description: 'PostgreSQL 15'     ,module: pgsql ,releases: [7    ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/15/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/15/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/15/redhat/rhel-$releasever-$basearch' }}
  - { name: pgdg16         ,description: 'PostgreSQL 16'     ,module: pgsql ,releases: [  8,9] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/16/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' }}
  - { name: timescaledb    ,description: 'TimescaleDB'       ,module: pgsql ,releases: [7,8,9] ,baseurl: { default: 'https://packagecloud.io/timescale/timescaledb/el/$releasever/$basearch'  }}

在 Pigsty 配置文件中显式定义并覆盖 repo_upstream 后，（可清除 /www/pigsty/repo_complete 标记后）再次尝试安装。如果上游软件源与镜像源的软件没有解决问题，你可以考虑将上面的源替换为操作系统自带的软件源，再次尝试从上游直接安装。

最后如果以上手段都没有解决问题，你可以考虑移除 node_packages， infra_packages， pg_packages，pg_extensions 中出现冲突的软件包。或者移除、升级现有系统上的冲突软件包。

准备 / bootstrap 过程是干什么的？

检测环境是否就绪、用各种手段确保后续安装所必需的工具 ansible 被正确安装。

当你下载 Pigsty 源码后，可以进入目录并执行 bootstrap 脚本。它会检测你的节点环境，如果没有发现离线软件包，它会询问你要不要从互联网下载。

你可以选择“是”，直接使用离线软件包安装又快又稳定。你也可以选“否”跳过，在安装时直接从互联网上游下载最新的软件包，这样会极大减少出现 RPM/DEB 包冲突的概率。

如果使用了离线软件包，bootstrap 会直接从离线软件包中安装 ansible，否则会从上游下载 ansible 并安装，如果你没有互联网访问，又没有 DVD，或者内网软件源，那就只能用离线软件包来安装了。

配置 / configure 过程是干什么的？

配置 / configure 过程会检测你的节点环境并为你生成一个 pigsty 配置文件：pigsty.yml，默认根据你的操作系统（EL 7/8/9）选用相应的单机安装模板。

所有默认的配置模板都在 files/pigsty中，你可以使用 -m 直接指定想要使用的配置模板。如果您已经知道如何配置 Pigsty 了，那么完全可以跳过这一步，直接编辑 Pigsty 配置文件。

Pigsty配置文件是干什么的？

Pigsty主目录下的 pigsty.yml 是默认的配置文件，可以用来描述整套部署的环境，在 files/pigsty 有许多配置示例供你参考。

当执行剧本时，你可以使用 -i <path> 参数，选用其他位置的配置文件。例如，你想根据另一个专门的配置文件 redis.yml 来安装 redis：./redis.yml -i files/pigsty/redis.yml

如何使用 CMDB 作为配置清单？

默认的配置文件路径在 ansible.cfg 中指定为：inventory = pigsty.yml

你可以使用 bin/inventory_cmdb 切换到动态的 CMDB 清单，使用 bin/inventory_conf 返回到本地配置文件。你还需要使用 bin/inventory_load 将当前的配置文件清单加载到 CMDB。

如果使用 CMDB，你必须从数据库而不是配置文件中编辑清单配置，这种方式适合将 Pigsty 与外部系统相集成。

配置文件中的IP地址占位符是干什么的？

Pigsty 使用 10.10.10.10 作为当前节点 IP 的占位符，配置过程中会用当前节点的主 IP 地址替换它。

当 configure 检测到当前节点有多个 NIC 带有多个 IP 时，配置向导会提示使用哪个主要 IP，即 用户用于从内部网络访问节点的 IP，此 IP 将用于在配置文件模板中替换占位符 10.10.10.10。

请注意：不要使用公共 IP 作为主 IP，因为 Pigsty 会使用主 IP 来配置内部服务，例如 Nginx，Prometheus，Grafana，Loki，AlertManager，Chronyd，DNSMasq 等，除了 Nginx 之外的服务不应该对外界暴露端口。

配置文件中的哪些参数需要用户特殊关注？

Pigsty 提供了 280+ 配置参数，可以对整个环境与各个模块 infra/node/etcd/minio/pgsql 进行细致入微的定制。

通常在单节点安装中，你不需要对默认生成的配置文件进行任何调整。但如果需要，可以关注以下这些参数：

当访问 web 服务组件时，域名由 infra_portal 指定，有些服务只能通过 Nginx 代理使用域名访问。
Pigsty 假定存在一个 /data 目录用于存放所有数据；如果数据磁盘的挂载点与此不同，你可以使用 node_data 调整这些路径。
进行生产部署时，不要忘记在配置文件中更改密码，更多细节请参考安全考量。

在默认单机安装时，到底都安装了什么东西？

当您执行 make install 时，实际上是调用 Ansible 剧本 install.yml，根据配置文件中的参数，安装以下内容：

INFRA 模块：提供本地软件源，Nginx Web接入点，DNS服务器，NTP服务器，Prometheus与Grafana可观测性技术栈。
NODE 模块，将当前节点纳入 Pigsty 管理，部署 HAProxy 与监控。
ETCD 模块，部署一个单机 etcd 集群，作为 PG 高可用的 DCS
MINIO 模块是默认不安装的，它可以作为 PG 的备份仓库。
PGSQL 模块，一个单机 PostgreSQL 数据库实例。

安装遇到RPM冲突怎么办？

在安装 node/infra/pgsql 软件包期间，可能有微小的几率出现 rpm 冲突。特别是，如果您使用的 EL 7-9 小版本不同于 7.9, 8.9, 9.3 ，或者使用了一些冷门换皮魔改发行版的话，可能会出现这种情况。

解决这个问题的最简单方法是：不使用离线包进行安装，这将直接从上游仓库中下载最合适您当前系统的软件包。如果只有少数几个 RPM 包有问题，你可以使用一个小技巧快速修复：

rm -rf /www/pigsty/repo_complete    # 删除 repo_complete 标记文件，以标记此仓库为不完整（这样会重新从上游下载软件）
rm -rf SomeBrokenRPMPackages        # 删除有问题的 RPM 包
./infra.yml -t repo_upstream        # 写入上游仓库。你也可以使用 /etc/yum.repos.d/backup/*
./infra.yml -t repo_pkg             # 根据你当前的操作系统下载软件包

如何使用 Vagrant 创建本地虚拟机？

当你第一次使用 Vagrant 启动某个特定的操作系统仓库时，它会下载相应的 Box/Img 镜像文件，Pigsty 沙箱默认使用 generic/rocky9 镜像。

使用代理可能会增加下载速度。Box/Img 只需下载一次，在重建沙箱时会被重复使用。

阿里云上 CentOS 7.9 特有的 RPM 冲突问题

阿里云的 CentOS 7.9 额外安装的 nscd 可能会导致 RPM 冲突问题："Error: Package: nscd-2.17-307.el7.1.x86_64 (@base)"

遇见安装失败，RPM冲突报错不要慌，这是一个DNS缓存工具，把这个包卸载了就可以了：sudo yum remove nscd，或者使用 ansible 命令批量删除所有节点上的 nscd：

ansible all -b -a 'yum remove -y nscd'

腾讯云上 Rocky 9.x 特有的 RPM 冲突问题

腾讯云的 Rocky 9.x 需要额外的 annobin 软件包才可以正常完成 Pigsty 安装。

遇见安装失败，RPM冲突报错不要慌，进入 /www/pigsty 把这几个包手动下载下来就好了。

./infra.yml -t repo_upstream      # add upstream repos
cd /www/pigsty;                   # download missing packages
repotrack annobin gcc-plugin-annobin libuser
./infra.yml -t repo_create        # create repo

Ansible命令超时（Timeout waiting for xxx）

Ansible 命令的默认 ssh 超时时间是10秒。由于网络延迟或其他原因，某些命令可能需要超过这个时间。

你可以在 ansible 配置文件 ansible.cfg 中增加超时参数：

[defaults]
timeout = 10 # 将其修改为 60，120 或更高。

如果你的SSH连接非常慢，通常会是 DNS的问题，请检查sshd配置确保 UseDNS no。