安装部署

下载、配置、安装 Pigsty

Module:

PIGSTY

Categories:

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

简短版本

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

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

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

./bootstrap; ./configure; ./install.yml; # 准备依赖，生成配置，安装 Pigsty 三步走！

bootstrap：【可选】用于确保 Ansible 正常安装，如果 /tmp/pkg.tgz 离线包存在则使用它
configure：【可选】检测环境并自动生成相应的推荐配置文件，如果知道如何配置 Pigsty可以直接跳过
install.yml：根据生成的配置文件开始在当前节点上执行安装，

整个安装过程根据服务器规格/网络条件需 5 到 30 分钟不等，离线安装可以显著加速。

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

如果您觉得 Pigsty 的组件过于复杂，还可以考虑使用 最小化安装 ，仅安装高可用 PostgreSQL 集群所必需的组件。

视频样例：在线单机安装（EL9）

使用命令行工具

Pigsty 在 v3.2 后提供了命令行工具：pig，可用于安装 Pigsty，生成配置，执行部署等操作。

curl https://repo.pigsty.io/pig | bash  # 国际区域
curl https://repo.pigsty.cc/pig | bash  # 中国大陆

以上命令会自动安装 pig 命令行工具（目前支持 Linux amd64 / arm64），您可以直接使用 pig sty 子命令来完成上面的步骤：

pig sty init     # 默认安装嵌入的最新 Pigsty 版本
pig sty boot     # 执行 Bootstrap，安装 Ansible
pig sty conf     # 执行 Configure，生成配置文件
pig sty install  # 执行 install.yml 剧本完成部署

准备

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

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

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

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

避免使用 root 用户安装

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

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

./bootstrap   # 使用各种可选方式安装 Ansible 与 Jmespath 依赖，如果离线包存在则使用离线包

您也可以直接使用操作系统的包管理器安装所需的 Ansible 与 Jmespath 软件包：

sudo dnf install -y ansible python3.12-jmespath python3-cryptography

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

sudo apt install -y ansible python3-jmespath

brew install ansible

下载

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

curl -fsSL https://repo.pigsty.cc/get | bash            # 安装最新稳定版本 
curl -fsSL https://repo.pigsty.cc/get | bash -s v3.2.2  # 安装特定版本 3.2.0

一键下载脚本的样例输出

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

[v3.2.2] ===========================================
$ curl -fsSL https://repo.pigsty.cc/get | bash
[Site] https://pigsty.io
[Demo] https://demo.pigsty.cc
[Repo] https://github.com/Vonng/pigsty
[Docs] https://pigsty.io/docs/setup/install
[Download] ===========================================
[ OK ] version = v3.2.2 (from default)
curl -fSL https://repo.pigsty.cc/src/pigsty-v3.2.2.tgz -o /tmp/pigsty-v3.2.2.tgz
[WARN] tarball = /tmp/pigsty-v3.2.2.tgz exists, size = 1227379, use it
[ OK ] md5sums = xxxxxx  /tmp/pigsty-v3.2.2.tgz
[Install] ===========================================
[WARN] os user = root , it's recommended to install as a sudo-able admin
[WARN] pigsty already installed on '/root/pigsty', if you wish to overwrite:
sudo rm -rf /tmp/pigsty_bk; cp -r /root/pigsty /tmp/pigsty_bk; # backup old
sudo rm -rf /tmp/pigsty;    tar -xf /tmp/pigsty-v3.2.2.tgz -C /tmp/; # extract new
rsync -av --exclude='/pigsty.yml' --exclude='/files/pki/***' /tmp/pigsty/ /root/pigsty/; # rsync src
[TodoList] ===========================================
cd /root/pigsty
./bootstrap      # [OPTIONAL] install ansible & use offline package
./configure      # [OPTIONAL] preflight-check and config generation
./install.yml    # install pigsty modules according to your config.
[Complete] ===========================================

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

git clone https://github.com/Vonng/pigsty; cd pigsty; git checkout v3.2.2

检出特定版本使用

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

配置

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

提示: 如果您已经了解了如何配置 Pigsty，configure 这个步骤是可选的，可以跳过。 Pigsty 提供了许多开箱即用的预置 配置模板 供您参考。

./configure # 不带参数会自动推荐配置，并交互式问询
./configure [-i|--ip <ipaddr>]                     # 指定首要 IP 地址，如果不指定，将在检测到多个可用IP地址时问询。
            [-c|--conf <conf>]                     # 指定配置模板（相对于 conf/ 目录的配置名称，不带.yml 后缀），默认使用 meta 单节点模板
            [-v|--version <ver>]                   # 指定要安装 PostgreSQL 大版本，部分模板不适用此配置 
            [-r|--region <default|china|europe>]   # 选择镜像源区域，如果在 GFW 区域内，将被设置为 china
            [-n|--non-interactive]                 # 跳过交互式向导
            [-x|--proxy]                           # 将环境变量中的代理配置写入配置文件的 proxy_env 参数中

配置 / configure 过程的样例输出

$ ./configure
configure pigsty v3.2.2 begin
[ OK ] region = china
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] package = rpm,yum
[ OK ] vendor  = centos (CentOS Linux)
[ OK ] version = 7 (7)
[ OK ] sudo = vagrant ok
[ OK ] ssh = vagrant@127.0.0.1 ok
[WARN] Multiple IP address candidates found:
    (1) 192.168.121.110	    inet 192.168.121.110/24 brd 192.168.121.255 scope global noprefixroute dynamic eth0
    (2) 10.10.10.10	    inet 10.10.10.10/24 brd 10.10.10.255 scope global noprefixroute eth1
[ OK ] primary_ip = 10.10.10.10 (from demo)
[ OK ] admin = vagrant@10.10.10.10 ok
[WARN] mode = el7, CentOS 7.9 EOL @ 2024-06-30, deprecated, consider using el8 or el9 instead
[ OK ] configure pigsty done
proceed with ./install.yml

-i|--ip：当前主机的首要内网IP地址，用于替换配置文件中的 IP 地址占位符 10.10.10.10。
-c|--conf：用于指定使用的配置 配置模板，相对于 conf/ 目录，不带 .yml 后缀的配置名称。
-v|--version：用于指定要安装的 PostgreSQL 大版本，如 13、14、15、16、17，部分模板不支持此配置。
-r|--region：用于指定上游软件源的区域，加速下载： (default|china|europe)
-n|--non-interactive：直接使用命令行参数提供首要IP地址，跳过交互式向导。
-x|--proxy: 使用当前环境变量配置 proxy_env 变量（影响 http_proxy/HTTP_PROXY， HTTPS_PROXY， ALL_PROXY， NO_PROXY）。

如果您的机器网卡绑定了多个 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.10]
...
...
PLAY RECAP **************************************************************************************************************************************************************************
10.10.10.10                : ok=288  changed=215  unreachable=0    failed=0    skipped=64   rescued=0    ignored=0
localhost                  : ok=3    changed=0    unreachable=0    failed=0    skipped=4    rescued=0    ignored=0

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

-l: 限制执行的目标对象
-t: 限制要执行的任务
-e: 传入额外的命令行参数
-i: 指定使用不同于 pigsty.yml 的配置文件
…

避免重复执行安装剧本！

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

此剧本仅用于初始安装，安装完毕后可以用 rm 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，……