这是本节的多页打印视图。 .

上手

在你的笔记本/云服务器上部署 Pigsty 单机版本，访问数据库以及 Web 用户界面

1: 快速上手 Pigsty 单机部署
2: Docker 部署
3: 从浏览器访问图形用户界面
4: 快速上手 PostgreSQL
5: 通过配置清单定制 Pigsty 部署
6: 使用 Ansible 剧本完成部署
7: 离线安装
8: 精简安装
9: 安全建议

Pigsty 采用可伸缩的架构设计，既可用于 超大规模生产环境，也可用于 单机开发演示环境，本文关注后者。

如果您打算学习了解 Pigsty，可以从 快速上手 单机部署开始。一台 1C/2G 的 Linux 虚拟机即可运行 Pigsty。

您可以利用一台 Linux MiniPC，云厂商提供的免费/优惠虚拟机，Windows 的 WSL，或者在自己的笔记本上创建虚拟机用于 Pigsty 部署。 Pigsty 提供了开箱即用的 Vagrant 模板与 Terraform 模版，可以帮助您一键在本地或云端置备 Linux 虚拟机。

单机版本的 Pigsty 包含了所有核心功能，575 个 PG 扩展，自包含的 Grafana / Victoria 监控，IaC 置备能力。以及本地 PITR 时间点恢复。如果您配备了外部的对象存储（用于 PostgreSQL PITR 备份），那么对于 Demo，个人网站，小型服务等场景，即使是单机环境，也可以提供一定程度的 数据持久性 保证。不过，单机无法实现 高可用 —— 故障自动切换至少需要 3 个节点。

如果您想要在没有互联网连接的环境中安装 Pigsty，请参考 离线安装 模式。如果您只需要 PostgreSQL 数据库本身，请参考 精简安装 模式。如果您准备开始进行严肃的多节点生产部署，请参考 部署指南。

快速开始

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

curl -fsSL https://repo.pigsty.cc/get | bash  # 安装 Pigsty 与依赖
cd ~/pigsty; ./configure -g                   # 生成配置（使用默认单机配置模板，-g 参数会生成随机密码）
./deploy.yml                                  # 执行部署剧本，完成部署

是的，就是这么简单。您完全可以在不了解任何细节的情况下，使用 预制配置模板 一键拉起 Pigsty。

接下来，您可以探索 图形用户界面，访问 PostgreSQL 数据库服务；或者进行 配置定制 并 执行剧本 部署更多集群。

1 - 快速上手 Pigsty 单机部署

快速上手 Pigsty，从一台全新的 Linux 主机开始，完成单机安装部署！

本文是 Pigsty 单节点安装指南单节点，生产环境的多节点高可用部署请参考部署文档。

Pigsty 单机安装分为三步走：安装，配置与部署。

摘要

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

选择 Pigsty 下载镜像：

pigsty.cc（中国）

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

pigsty.io（全球）

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

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

进入源码目录

cd ~/pigsty

生成配置清单

./configure -g

如果你已经准备好 pigsty.yml，可以跳过这一步。

执行部署剧本

./deploy.yml

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

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

视频样例：在线单机安装（Debian 13, x86_64）

demo/install-hero.cast

准备

安装 Pigsty 涉及一些 准备工作，以下是简略检查清单，单机部署时，许多限制可以放宽。

项目	要求	项目	要求
节点	单节点，至少 `1C2G`，上不封顶	磁盘	`/data` 作为默认主挂载点，建议使用 `xfs`
系统	`Linux` `x86_64` / `aarch64`，EL / Debian / Ubuntu	网络	静态 IPv4 内网地址
SSH	通过公钥 `nopass` SSH 登陆纳管节点	SUDO	sudo 权限，最好带有 `nopass` 免密选项

通常您只需要关注本机 IP 地址 —— 作为特例，单机部署时，如果没有静态 IP 地址，可使用 127.0.0.1 作为逃生窗口。

安装

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

选择 Pigsty 下载镜像：

pigsty.cc（中国）

curl -fsSL https://repo.pigsty.cc/get | bash            # 安装当前默认版本
curl -fsSL https://repo.pigsty.cc/get | bash -s v4.5.0  # 显式安装当前公开稳定版

pigsty.io（全球）

curl -fsSL https://repo.pigsty.io/get | bash            # 安装当前默认版本
curl -fsSL https://repo.pigsty.io/get | bash -s v4.5.0  # 显式安装当前公开稳定版

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

git clone https://github.com/pgsty/pigsty; cd pigsty;
git checkout v4.5.0;  # 使用 git 安装时，请务必检出已发布的 tag

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

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

配置

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

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

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

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

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

./configure                  # 使用默认模板，安装默认的 PG 18，带有必要扩展
./configure -v 17            # 使用 PG 17 的版本，而非默认的 PG18
./configure -c rich          # 创建本地软件仓库，下载所有扩展，安装主要扩展
./configure -c slim          # 最小安装模板，与 ./slim.yml 剧本一起使用
./configure -c app/supa      # 使用 app/supa 自托管 supabase 配置模板
./configure -c ivory         # 使用 ivorysql 内核而非原生 PG
./configure -i 10.11.12.13   # 显式指定主 IP 地址
./configure -r china         # 使用中国镜像而非默认仓库
./configure -c ha/full -s    # 使用 4 节点沙箱配置模板，不进行 IP 替换和探测

下面展示的是当前 main 分支（v5.0.0-preview）的输出；若安装其他版本，首行会显示对应版本号。

当前 main 分支的 configure 样例输出

示例 1 当前 main 分支的 configure 样例输出

vagrant@meta:~/pigsty$ ./configure
configure pigsty v4.5.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 = [email protected] 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 = [email protected] 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

配置脚本常用参数

-i | --ip , IPv4: 当前主机的首要内网 IP 地址，用于替换配置文件中的 IP 地址占位符 10.10.10.10。
-c | --conf , string: 指定 配置模板，填写相对于 conf/ 目录且不带 .yml 后缀的名称。
-v | --version , integer: 指定 PostgreSQL 大版本 14～19；PG19 当前为 Beta，建议使用专用 pg19 模板。
-r | --region , enum , defaultdefault: 指定上游软件源区域以加速下载：default、china 或 europe。
-n | --non-interactive , boolean , defaultfalse: 直接使用命令行参数提供首要 IP 地址，跳过交互式向导。
-x | --proxy , boolean , defaultfalse: 使用当前环境变量配置 proxy_env 变量。

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

修改默认密码！

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

部署

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

当您看到输出尾部如果带有 pgsql init done，PLAY RECAP 等字样，说明安装已经完成！

上游软件仓库变更可能导致在线安装失败！

Pigsty 使用的上游软件仓库（如 Linux / PGDG 仓库）可能会因为不恰当的更新，进入崩溃状态并导致部署失败（有过多次先例）！您可以选择等待上游仓库修复后安装，或者使用预制的 离线软件包 解决这个问题。

避免重复执行部署剧本！

警告：在已经完成部署的环境中再次完整运行 deploy.yml 可能会重启相关服务并覆盖配置，请务必注意！

界面

Pigsty 单机安装完成后，您在当前节点上通常会安装有四个功能模块： PGSQL、INFRA、NODE 和 ETCD。

ID	NODE	PGSQL	INFRA	ETCD
1	`10.10.10.10`	`pg-meta-1`	`infra-1`	`etcd-1`

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

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

您可以以当前节点作为基础，部署和监控 更多集群：向 配置清单 添加数据库集群的定义并运行：

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、DOCKER……

2 - Docker 部署

在 Docker 容器中快速拉起 Pigsty 单机环境，适合 macOS/Windows 用户体验学习

Pigsty 旨在运行于原生 Linux 系统上，但也可以在带有 systemd 的 Linux 容器环境中运行。如果您没有原生 Linux 环境（例如 macOS 或 Windows 用户），可以使用 Docker 快速拉起一个本地单机 Pigsty 环境进行测试与体验。

快速开始

进入 Pigsty 源码包的 docker/ 目录，使用以下一键命令启动 Pigsty：

cd ~/pigsty/docker
make launch          # 启动容器 + 生成配置 + 执行部署

部署完成后，您可以通过以下方式访问服务：

服务	地址	凭据
SSH	`ssh root@localhost -p 2222`	密码：`pigsty`
Web 界面	http://localhost:8080	-
Grafana	http://localhost:8080/ui	`admin` / `grafana_admin_password`
PostgreSQL	`psql 'postgres://dbuser_dba:<pg_admin_password>@localhost:5432/postgres'`	`pg_admin_password`

make launch 内部会执行 ./configure -g 生成随机密码，可通过以下命令查看：

cd ~/pigsty/docker
make pass | grep -E 'grafana_admin_password|pg_admin_password'

Web 界面与 PostgreSQL 服务

Web 界面与 PostgreSQL 服务仅在完成部署（./deploy.yml）后才可用。

准备

使用 Docker 部署 Pigsty 需要满足以下条件：

项目	要求	项目	要求
Docker	Docker 20.10+（Docker Desktop 或 CE）	CPU	至少 1 核
内存	至少 2GB	磁盘	至少 20GB 可用空间

请确保默认宿主机端口（2222/8080/8443/5432）可用，否则请先修改 .env 文件。

Docker 部署适用场景

在 macOS / Windows 等非 Linux 环境下快速体验 Pigsty
学习和测试 Pigsty 的功能特性，进行开发调试
快速构建一个本地开发用的 PostgreSQL 环境

Docker 部署不适用场景

生产环境部署：容器环境性能和稳定性不如原生 Linux
高可用集群：Docker 单机模式无法实现多节点高可用
大规模部署：建议使用原生 Linux 虚拟机或物理机

镜像

Pigsty 提供开箱即用的 Docker 镜像，发布在 Docker Hub。

镜像	拉取大小	解压大小	内容
`pgsty/pigsty`	~500MB	1.3GB	Debian 13 + systemd + SSH + pig + Ansible

同时支持 amd64（x86_64）和 arm64（Apple Silicon、AWS Graviton）架构
镜像标签按 Pigsty 版本命名。当前 main 分支的 Docker 配置默认值与站点口径均为 v5.0.0-preview；拉取或部署前仍应独立确认远端已有同名镜像
镜像内已预生成 docker 配置模板，可直接执行 ./deploy.yml 部署

镜像基于 Debian 13 (Trixie) 构建，预装了 pig CLI 工具和 Ansible，并已初始化好 Pigsty 源码。

启动

Pigsty 提供了开箱即用的 Docker 支持，位于源码的 docker/ 目录中。

最简单的方式是使用 make launch 一键启动，它会自动完成启动容器、生成配置、执行部署三个步骤：

cd ~/pigsty/docker
make launch          # 一键启动：up + config + deploy

或者分步执行，可以在每一步进行检查和调整：

cd ~/pigsty/docker
make up              # 启动容器
make exec            # 进入容器
./configure -c docker -g --ip 127.0.0.1  # 生成配置（可选，镜像已预配置）
./deploy.yml         # 执行部署

如果您想要使用本地构建的镜像而非从 Docker Hub 拉取，可以先执行构建：

cd ~/pigsty/docker
make build           # 本地构建镜像
make launch          # 启动容器 + 生成配置 + 执行部署

配置

您可以通过修改 .env 文件来自定义镜像版本和端口映射：

PIGSTY_VERSION=v4.5.0         # 当前 main 的源码默认值；拉取前核验远端标签
PIGSTY_SSH_PORT=2222          # SSH 端口
PIGSTY_HTTP_PORT=8080         # Nginx HTTP 端口
PIGSTY_HTTPS_PORT=8443        # Nginx HTTPS 端口
PIGSTY_PG_PORT=5432           # PostgreSQL 端口

端口映射说明：

环境变量	默认值	容器端口	说明
`PIGSTY_VERSION`	`v4.5.0`	-	当前 `main` 的源码默认值；远端标签需另行核验
`PIGSTY_SSH_PORT`	`2222`	22	SSH 访问端口
`PIGSTY_HTTP_PORT`	`8080`	80	Nginx HTTP 端口
`PIGSTY_HTTPS_PORT`	`8443`	443	Nginx HTTPS 端口
`PIGSTY_PG_PORT`	`5432`	5432	PostgreSQL 端口

如果默认端口已被占用，可以通过环境变量临时覆盖：

PIGSTY_HTTP_PORT=8888 docker compose up -d

命令

Pigsty Docker 提供了丰富的 Makefile 命令，方便您管理容器和镜像。

Docker Compose 命令

推荐使用 Docker Compose 方式运行，以下是常用命令：

make up           # 启动容器
make down         # 停止并删除容器
make start        # 启动已停止的容器
make stop         # 停止容器
make restart      # 重启容器
make pull         # 拉取最新镜像
make config       # 在容器内执行 ./configure
make deploy       # 在容器内执行 ./deploy.yml
make launch       # 一键启动：up + config + deploy

容器访问命令

make exec         # 进入容器 bash
make ssh          # 通过 SSH 进入容器
make log          # 查看容器日志
make status       # 查看 systemd 状态
make ps           # 查看进程列表
make conf         # 查看配置文件
make pass         # 查看配置中的密码

镜像构建命令

make build        # 本地构建镜像
make buildnc      # 不使用缓存构建镜像
make push         # 构建并推送多架构镜像

镜像管理命令

make save         # 导出镜像到 pigsty-<version>-<arch>.tgz
make load         # 从 tgz 文件导入镜像
make rmi          # 删除当前版本的 pigsty 镜像

容器清理命令

make clean        # 停止并删除容器
make purge        # 停止并删除容器，然后直接删除当前目录的 ./data

谨慎执行 make purge

当前 Makefile 不再提供倒计时确认；make purge 会在移除容器后直接执行 rm -rf -- ./data。请先确认当前目录与待删除数据，必要时先备份。

手动运行

如果您不想使用 Docker Compose，也可以直接使用 docker run 命令：

mkdir -p ./data
docker run -d --privileged --name pigsty \
  -p 2222:22 -p 8080:80 -p 5432:5432 \
  -v ./data:/data \
  pgsty/pigsty:<version>

docker exec -it pigsty ./configure -c docker -g --ip 127.0.0.1
docker exec -it pigsty ./deploy.yml

或者使用 Makefile 提供的 make run 命令：

make run          # 使用 docker run 启动
make exec         # 进入容器
make clean        # 停止并删除容器
make purge        # 删除容器并直接删除当前目录的 ./data

原理

Pigsty Docker 镜像基于 Debian 13 (Trixie)，启用了 systemd 作为 init 系统。这使得容器内的服务管理方式与原生 Linux 系统保持一致，可以使用 systemctl 管理服务。

镜像的关键特性：

systemd 支持：容器内运行完整的 systemd，可以正常使用服务管理
SSH 访问：预配置了 SSH 服务，root 密码为 pigsty
特权模式：需要 --privileged 参数以支持 systemd
数据持久化：通过 /data 卷挂载实现数据持久化
预装软件：预装 pig CLI 和 Ansible，已完成 Pigsty 源码初始化

镜像构建时会执行以下初始化步骤：

# 安装 pig CLI
RUN echo "deb [trusted=yes] https://repo.pigsty.cc/apt/infra/ generic main" \
    > /etc/apt/sources.list.d/pigsty.list \
    && apt-get update && apt-get install -y pig

# 初始化 Pigsty 源码并安装 Ansible
RUN pig sty init -v ${PIGSTY_VERSION} \
    && pig sty boot \
    && pig sty conf -c docker --ip 127.0.0.1

在容器内执行 ./configure 时，使用 -c docker 参数会应用专门针对 Docker 环境优化的 配置模板：

使用 127.0.0.1 作为默认 IP 地址
针对容器环境进行了优化调整

常见问题

容器无法启动

确保 Docker 已正确安装且有足够的资源分配。在 Docker Desktop 中，建议分配至少 2GB 内存。检查是否有端口冲突，特别是 2222、8080、8443、5432 端口。

服务访问失败

Web 界面和 PostgreSQL 服务仅在部署完成后才可用。请确保 ./deploy.yml 已成功执行完成。可以通过 make status 检查容器内服务状态。

端口冲突

如果默认端口已被占用，可以通过修改 .env 文件或使用环境变量指定其他端口：

PIGSTY_HTTP_PORT=8888 PIGSTY_PG_PORT=5433 docker compose up -d

数据持久化

容器数据默认挂载到 ./data 目录。如果需要清空数据重新开始：

make purge        # 删除容器并直接删除当前目录的 ./data（无倒计时确认）

macOS 上的性能

在 macOS 上使用 Docker Desktop 时，由于虚拟化层的开销，性能会比原生 Linux 环境差。这是正常现象，Docker 部署主要用于开发测试，生产环境请使用 原生 Linux 安装。

Docker Hub：https://hub.docker.com/r/pgsty/pigsty
源码目录：https://github.com/pgsty/pigsty/tree/main/docker
快速上手：原生 Linux 安装
离线安装：离线安装
生产部署：部署指南

3 - 从浏览器访问图形用户界面

探索 Pigsty 提供的 Web 图形管理界面，Grafana 大盘，以及如何通过域名和 HTTPS 访问它们。

Pigsty 单机安装 完成后，您在当前节点上将安装有 INFRA 模块，它带有一套开箱即用的 Nginx Web 服务器。

其中的默认服务器配置提供了一个 WebUI 图形界面，用于展示监控仪表盘，并统一代理访问其他组件的 Web 界面。

访问

您可以通过在浏览器中键入部署节点 IP 地址来访问这个图形界面。在默认配置下，Nginx 将通过 80/443 标准端口对外提供服务。

IP 直接访问	域名（HTTP）	域名（HTTPS）	Demo
`http://10.10.10.10`	`http://i.pigsty`	`https://i.pigsty`	`https://demo.pigsty.cc`

监控

要访问 Pigsty 的监控系统大盘（Grafana），您可以访问服务器的 /ui 端点。

IP 直接访问	域名（HTTP）	域名（HTTPS）	Demo
`http://10.10.10.10/ui`	`http://i.pigsty/ui`	`https://i.pigsty/ui`	`https://demo.pigsty.cc/ui`

如果您的服务对互联网与办公网开放，我们建议您通过域名访问，并启用 HTTPS 加密，只需要少量配置工作即可实现。

端点

在默认配置下，Nginx 会在 80/443 端口的默认服务器上，通过不同的路径暴露以下端点：

端点	组件	原生端口	备注	公开演示
`/`	Nginx	`80/443`	首页、本地仓库、文件服务	`demo.pigsty.cc`
`/ui/`	Grafana	`3000`	Grafana 仪表盘入口	`demo.pigsty.cc/ui/`
`/vmetrics/`	VictoriaMetrics	`8428`	时序数据库 Web UI	`demo.pigsty.cc/vmetrics/`
`/vlogs/`	VictoriaLogs	`9428`	日志数据库 Web UI	`demo.pigsty.cc/vlogs/`
`/vtraces/`	VictoriaTraces	`10428`	链路追踪 Web UI	`demo.pigsty.cc/vtraces/`
`/vmalert/`	VMAlert	`8880`	告警规则管理	`demo.pigsty.cc/vmalert/`
`/alertmgr/`	AlertManager	`9059`	告警管理 Web UI	`demo.pigsty.cc/alertmgr/`
`/blackbox/`	Blackbox	`9115`	黑盒探测器
`/haproxy/*`	HAProxy	`9101`	负载均衡管理 Web UI
`/pev`	PEV2	`80`	PostgreSQL 执行计划可视化	`demo.pigsty.cc/pev`
`/nginx`	Nginx	`80`	Nginx 状态页（指标采集用）

域名访问

如果您有自己的域名，可以将其解析到 Pigsty 服务器的 IP 地址，从而通过域名访问 Pigsty 提供的各项服务。

如果您希望启用 HTTPS，则应当修改 infra_portal 参数中 home 服务器的配置：

all:
  vars:
    infra_portal:
      home : { domain: i.pigsty } # 将 i.pigsty 替换为你的域名

all:
  vars:
    infra_portal:  # domain 指定域名  # certbot 参数指定证书名称
      home : { domain: demo.pigsty.cc ,certbot: mycert }

您可以在部署完成后，执行 make cert 命令为该域名申请免费的 Let’s Encrypt 证书。如果您没有定义 certbot 字段，Pigsty 会默认使用本地 CA 签发自签名的 HTTPS 证书，在这种情况下，您必须首先信任 Pigsty 的自签名 CA 才可以在浏览器中正常访问。

您还可以将本地目录与其他上游服务挂载到 Nginx 上，更多管理预案，请参考 INFRA 管理 - Nginx。

4 - 快速上手 PostgreSQL

快速上手 PostgreSQL，使用命令行与图形客户端连接上 PostgreSQL 并开始使用。

PostgreSQL（简称 PG）是世界上最先进、最流行的开源关系型数据库，你可以用它来存储和检索多模态数据。

本指南面向有基础 Linux 基本命令行操作经验、但对 PostgreSQL 不太熟悉的开发者，带你快速上手 Pigsty 中的 PG。

我们假设您是个人用户，使用默认单机模式进行部署。关于生产环境多节点高可用集群的使用，请参考 生产服务接入。

基本知识

默认 单机安装 模板下，您将在当前节点上创建一个名为 pg-meta 的 PostgreSQL 数据库集群，只有一个主库实例。

PostgreSQL 监听在 5432 端口，集群中带有一个预置的数据库 meta 可供使用。

您可以在安装完毕后退出当前管理用户 ssh 会话，并重新登陆刷新环境变量后，通过简单地敲一个 pp 回车，通过命令行工具 psql 访问该数据库集群：

vagrant@pg-meta-1:~$ pp
psql (18.6 (Ubuntu 18.6-1.pgdg24.04+1))
Type "help" for help.

postgres=#

您也可以切换为操作系统的 postgres 用户，直接执行 psql 命令，即可连接到默认的 postgres 管理数据库上。

连接数据库

想要访问 PostgreSQL 数据库，您需要使用命令行工具或者图形化客户端工具，填入 PostgreSQL 的 连接字符串：

postgres://username:password@host:port/dbname

一些驱动和工具也可能会要求你分别填写这些参数，通常以下五项为必选项：

参数	说明	示例值	备注
`host`	数据库服务器地址	`10.10.10.10`	换为你的节点 IP 地址或域名，本机可以省略
`port`	端口号	`5432`	PG 默认端口，可以省略
`username`	用户名	`dbuser_dba`	Pigsty 默认的数据库管理员
`password`	密码	`DBUser.DBA`	Pigsty 默认的管理员密码，（请修改密码）
`dbname`	数据库名	`meta`	默认模板的数据库名称

个人使用时可以直接使用 Pigsty 默认的数据库超级用户 dbuser_dba 进行连接和管理，数据库管理用户 dbuser_dba 拥有数据库的全部权限。默认情况下，如果您在配置 Pigsty 时指定了 configure -g 参数，密码会随机生成，并保存在 ~/pigsty/pigsty.yml 文件中，可以通过以下命令查看：

cat ~/pigsty/pigsty.yml | grep pg_admin_password

默认账号密码

Pigsty 的默认 单机模板 默认配置预置了以下数据库用户，可以开箱即用：

用户名	密码	角色	用途
`dbuser_dba`	`DBUser.DBA`	超级用户	数据库管理（请修改密码）
`dbuser_meta`	`DBUser.Meta`	业务管理员	应用读写（请修改密码）
`dbuser_view`	`DBUser.Viewer`	只读用户	数据查阅（请修改密码）

例如，你可以通过三个不同的连接串，使用三个不同的用户连接到 pg-meta 集群的 meta 数据库：

postgres://dbuser_dba:[email protected]:5432/meta
postgres://dbuser_meta:[email protected]:5432/meta
postgres://dbuser_view:[email protected]:5432/meta

请注意，这些默认密码会在 configure -g 时自动被替换为随机强密码，请注意将 IP 地址和密码替换为实际值。

使用命令行工具

psql 是 PostgreSQL 官方命令行客户端工具，功能强大，是 DBA 和开发者的首选工具。

在部署了 Pigsty 的服务器上，你可以直接使用 psql 连接本地数据库：

# 最简单的方式：使用 postgres 系统用户本地连接（无需密码）
sudo -u postgres psql

# 使用连接字符串（推荐，通用性最好）
psql 'postgres://dbuser_dba:[email protected]:5432/meta'

# 使用参数形式
psql -h 10.10.10.10 -p 5432 -U dbuser_dba -d meta

# 使用环境变量避免密码出现在命令行
export PGPASSWORD='DBUser.DBA'
psql -h 10.10.10.10 -p 5432 -U dbuser_dba -d meta

成功连接后，你会看到类似这样的提示符：

psql (18.6)
Type "help" for help.

meta=#

常用 psql 命令

进入 psql 后，可以执行 SQL 语句，也可以使用以 \ 开头的元命令：

命令	说明	命令	说明
`Ctrl+C`	中断查询	`Ctrl+D`	退出 psql
`\?`	显示所有元命令帮助	`\h`	显示 SQL 命令帮助
`\l`	列出所有数据库	`\c dbname`	切换到指定数据库
`\d table`	查看表结构	`\d+ table`	查看表的详细信息
`\du`	列出所有用户/角色	`\dx`	列出已安装的扩展
`\dn`	列出所有的模式	`\dt`	列出所有表

执行 SQL

在 psql 中直接输入 SQL 语句，以分号 ; 结尾：

-- 查看 PostgreSQL 版本
SELECT version();

-- 查看当前时间
SELECT now();

-- 创建一张测试表
CREATE TABLE test (id SERIAL PRIMARY KEY, name TEXT, created_at TIMESTAMPTZ DEFAULT now());

-- 插入数据
INSERT INTO test (name) VALUES ('hello'), ('world');

-- 查询数据
SELECT * FROM test;

-- 删除测试表
DROP TABLE test;

使用图形客户端

如果你更喜欢图形界面，以下是几款流行的 PostgreSQL 客户端：

Grafana

Pigsty INFRA 模块中自带了 Grafana，并预先配置好了 PostgreSQL 数据源（Meta）。您可以直接通过 浏览器图形界面，从 Grafana Explore 面板中使用 SQL 查询数据库，无需额外安装客户端工具。

Grafana 默认的用户名是 admin，密码可以在 配置清单 中的 grafana_admin_password 字段找到（默认 pigsty）。

DataGrip

DataGrip 是 JetBrains 出品的专业数据库 IDE，功能强大。 Intellij IDEA 自带的 Database Console 也可以使用类似的方式连接 PostgreSQL。

DBeaver

DBeaver 是免费开源的通用数据库工具，支持几乎所有主流数据库。这是一个多平台可用的桌面客户端。

pgAdmin

pgAdmin 是 PGDG 官方提供的 PostgreSQL 专用 GUI 工具，可以通过浏览器使用，也有桌面客户端版本。

Pigsty 在 软件模板：pgAdmin 中提供了使用 Docker 一键部署 pgAdmin 服务的配置模板。

查阅监控大盘

Pigsty 提供了许多 PostgreSQL 监控面板，覆盖从集群总览到单表分析的各个层面：

推荐先从 PGSQL Overview 开始浏览，面板中的许多元素都可以点击，您可以逐层深入，查阅每个集群、实例、数据库甚至是表，索引，函数等数据库内对象的详情信息。

尝试扩展插件

PostgreSQL 最强大的特性之一是其 扩展生态系统。扩展可以为数据库添加新的数据类型、函数、索引方法等能力。

Pigsty 提供 575 个扩展，涵盖时序、地理、向量、全文检索等 16 大类别，一键安装即可使用。你可以先从三个常用功能扩展开始，然后按需加装 timescaledb 等更多扩展。

postgis：地理信息系统，处理地图、位置数据（默认安装）
pgvector：向量数据库，支持 AI 嵌入向量相似度搜索（默认安装）
timescaledb：时序数据库，高效存储和查询时间序列数据（可选安装）

\dx                            -- psql 元命令，列出已经安装的扩展
TABLE pg_available_extensions; -- 查询已经安装，可以启用的扩展
CREATE EXTENSION postgis;      --  启用 postgis 扩展

下一步

恭喜你完成了 PostgreSQL 的基础上手！下一步，你可以开始对你的数据库进行一些 配置与定制。

5 - 通过配置清单定制 Pigsty 部署

使用声明式的配置文件，表达你需要的基础设施与集群。

除了使用 配置向导 自动生成配置，您也可以从零开始手工编写 Pigsty 配置文件。本教程将指导您从头开始，逐步构建一个复杂的 配置清单。

如果您事先在 配置清单 中定义好 NODE、INFRA、ETCD、MINIO 与 PGSQL，那么 deploy.yml 可以一次性完成这条核心链路的部署，但它隐藏了所有细节。Docker、Redis、Kafka、原生 MySQL、JUICE 与 VIBE 等可选模块需要另行执行各自的剧本。

所以本文档会把所有模块与剧本拆解开来，介绍如何从一个简单的配置，通过增量添加的方式，形成一套复杂完备的部署。

最小配置

最简单的有效配置文件可能如下所示，唯一的内容是定义 admin_ip 变量，这是当前安装 Pigsty 节点的 IP 地址（管理节点）

最简配置

all: { vars: { admin_ip: 10.10.10.10 } }

中国特色

# 天朝自有国情在此，额外配置 region: china 以使用国内的镜像源加速下载
all: { vars: { admin_ip: 10.10.10.10, region: china } }

这个配置不会部署任何东西，但是执行 ./deploy.yml 剧本时，会在 files/pki/ca 生成一套自签名的 CA，用于签发证书。

为了方便起见，我们还可以额外设置 region 参数，指定使用哪个区域的软件镜像源（default，china，europe）。

加入节点

Pigsty 的 NODE 模块负责管理集群中的节点。配置清单里存在的 IP 地址，都会被 Pigsty 纳入管理，安装 NODE 模块。

最简配置

all:  # 不要忘了将 10.10.10.10 替换为您的实际 IP 地址
  children: { nodes: { hosts: { 10.10.10.10: {} } } } 
  vars: 
    admin_ip: 10.10.10.10                   # 当前节点 IP 地址
    region: default                         # 全球默认软件仓库
    node_repo_modules: node,pgsql,infra     # 添加 node, pgsql, infra 软件仓库

中国特色

all:  # 不要忘了将 10.10.10.10 替换为您的实际 IP 地址                        
  children: { nodes: { hosts: { 10.10.10.10: {} } } } 
  vars:
    admin_ip: 10.10.10.10                 # 当前节点 IP 地址
    region: china                         # 使用中国镜像
    node_repo_modules: node,pgsql,infra   # 添加 node, pgsql, infra 软件仓库

为了让这个配置更有用，我们添加了两个 全局参数：指定该节点要添加的软件源 node_repo_modules；以及使用哪个区域的镜像的 region。

上面的两个参数能够让节点使用正确的软件仓库，安装默认指定的必须包。在 NODE 模块中有许多可用的 定制项：您可以定制节点的名称，DNS，软件仓库，要安装的软件包，DNS，NTP，内核参数，调优模板，监控，日志采集等各种细节。但即使您什么都不改，默认配置也足够了。

接下来，执行 deploy.yml 剧本，或者更精确地执行 node.yml 剧本，将会把这里定义节点 “纳入 Pigsty 管理”，调整至默认配置描述的状态。

ID	NODE	INFRA	ETCD	PGSQL	说明
1	`10.10.10.10`	-	-	-	添加节点

加入基础设施

一套功能完备的 RDS 云数据库服务需要基础设施的支持，例如，监控系统（指标/日志采集，告警，可视化），NTP，DNS 等各种基础性服务。

现在，我们通过定义一个特殊的分组 infra，来部署 INFRA 模块。为 Pigsty 添加基础设施支持。

最简配置

all:  # 只是简单的改了个分组名 nodes -> infra，并添加新的实例变量 infra_seq
  children: { infra: { hosts: { 10.10.10.10: { infra_seq: 1 } } } } 
  vars: 
    admin_ip: 10.10.10.10
    region: default
    node_repo_modules: node,pgsql,infra

中国特色

all:  # 只是简单的改了个分组名 nodes -> infra，并添加新的实例变量 infra_seq
  children: { infra: { hosts: { 10.10.10.10: { infra_seq: 1 } } } } 
  vars:
    admin_ip: 10.10.10.10
    region: china
    node_repo_modules: node,pgsql,infra

同时，我们还分配了一个 身份参数：infra_seq，这是为了在多节点部署高可用 INFRA 模块时将不同的节点区分开来。

执行 infra.yml 剧本，将在 10.10.10.10 上安装 INFRA 和 NODE 模块。

./infra.yml   # 在 infra 分组上安装 INFRA 模块（连带安装 NODE 模块）

demo/infra.cast

只要 IP 地址存在，NODE 模块会隐含定义。NODE 模块也是幂等的，即使重复执行一次，也没有什么副作用。

安装完成后，您将拥有一套完整的可观测性基础设施，以及节点监控功能，但 PostgreSQL 数据库服务尚未部署。

如果您的目的就是设置这一套监控系统（Grafana + Victoria），那么到此为止就大功告成了！infra 模板就是为此设计的。 Pigsty 中的一切都是 模块化 的：您可以只部署监控基础设施，而不部署数据库服务；或者反过来 —— 在没有基础设施的情况下，运行高可用 PostgreSQL 集群 —— 精简安装。

ID	NODE	INFRA	ETCD	PGSQL	说明
1	`10.10.10.10`	`infra-1`	-	-	添加基础设施模块

部署数据库集群

要提供 PostgreSQL 服务，您还需要额外安装 PGSQL 模块和它所依赖的 ETCD 模块，这并不复杂，两行配置而已：

最简配置

all:
  children:
    infra:   { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:    { hosts: { 10.10.10.10: { etcd_seq:  1 } } } # 新增 etcd 集群
    pg-meta: { hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }, vars: { pg_cluster: pg-meta } } # 新增 pg 集群
  vars: { admin_ip: 10.10.10.10, region: default, node_repo_modules: node,pgsql,infra }

中国特色

all:
  children:
    infra:   { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:    { hosts: { 10.10.10.10: { etcd_seq:  1 } } } # 新增 etcd 集群
    pg-meta: { hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }, vars: { pg_cluster: pg-meta } } # 新增 pg 集群
  vars: { admin_ip: 10.10.10.10, region: china, node_repo_modules: node,pgsql,infra }

我们在这里添加了两个新的分组：etcd 与 pg-meta，分别定义了一个单节点的 etcd 集群和一个单节点的 PostgreSQL 集群。

您可以使用 ./deploy.yml 重新收敛核心链路中已定义的模块，也可以使用以下命令进行增量部署：

./etcd.yml  -l etcd      # 在 etcd 组上安装 ETCD 模块
./pgsql.yml -l pg-meta   # 在 pg-meta 组上安装 PGSQL 模块

PGSQL 模块依赖 ETCD 进行高可用共识，因此请确保先安装 ETCD 模块。执行完毕后，您就拥有一个可用的 PostgreSQL 服务了！

ID	NODE	INFRA	ETCD	PGSQL	说明
1	`10.10.10.10`	`infra-1`	`etcd-1`	`pg-meta-1`	添加 etcd 与 PostgreSQL 集群

至此，我们用 node.yml, infra.yml, etcd.yml 和 pgsql.yml 四个剧本，在单机上部署了完整的四个核心功能模块。

定义数据库与用户

您不仅可以定制在哪些节点上安装哪些模块，还可以定制 PostgreSQL 集群的内部细节，例如 数据库 与用户。

all:
  children:
    # 隐藏其他分组与变量以简化展示
    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_users:       # 定义数据库用户
          - { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user  }
        pg_databases:   # 定义业务数据库
          - { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database }

pg_users：这里定义一个名为 dbuser_meta 的新用户，密码为 DBUser.Meta
pg_databases：定义一个名为 meta 的新数据库，包含 Pigsty CMDB 模式（完全可选）。

Pigsty 提供了非常丰富的定制参数，覆盖了数据库与用户的方方面面。如果您事先定义好了上面两个参数描述所需的数据库与用户，那么它们会在 ./pgsql.yml 剧本执行时被自动创建。如果集群已经创建，您也可以进行增量变更，在现有集群上创建或修改用户与 数据库。

bin/pgsql-user pg-meta dbuser_meta      # 确保 pg-meta 集群中有用户 dbuser_meta
bin/pgsql-db   pg-meta meta             # 确保 pg-meta 集群中有数据库 meta

配置 PG 版本与扩展

您可以安装 不同大版本 的 PostgreSQL，以及多达 575 种 扩展插件。让我们卸载当前默认的 PG 18，并安装 PG 16：

./pgsql-rm.yml -l pg-meta   # 移除旧的 pg-meta 集群（因为它是 PG 18）

我们可以通过定制参数，让集群默认安装并启用一些常用的扩展：timescaledb、postgis 和 pgvector：

pg_extensions：安装 timescaledb、postgis、pgvector 扩展。
pg_libs：配置加载 timescaledb、pg_stat_statements、auto_explain 扩展动态库。
pg_databases：为 meta 数据库 创建启用 vector、postgis、timescaledb 扩展。

all:
  children:
    infra:   { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:    { hosts: { 10.10.10.10: { etcd_seq:  1 } } } # 新增 etcd 集群
    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_version: 16   # 指定 PG 版本为 16
        pg_extensions: [ timescaledb, postgis, pgvector ]      # 安装这些扩展
        pg_libs: 'timescaledb, pg_stat_statements, auto_explain'  # 预加载这些扩展动态库
        pg_databases:
          - { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [vector, postgis, timescaledb ] }
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user }
        
  vars:
    admin_ip: 10.10.10.10
    region: default
    node_repo_modules: node,pgsql,infra

./pgsql.yml -l pg-meta   # 安装 PG16 和扩展重新创建 pg-meta 集群

添加更多节点

我们可以向部署中添加更多节点，将其纳入 Pigsty 的管理之中，部署监控，配置仓库，安装软件 ……

一次添加整个集群，或者逐个添加节点
bin/node-add pg-test

bin/node-add 10.10.10.11
bin/node-add 10.10.10.12
bin/node-add 10.10.10.13

demo/node.cast

部署高可用PG集群

现在假设我们要在刚添加的三个新节点上，部署一套新的数据库集群 pg-test，采用三节点高可用架构，只需要：

all:
  children:
    infra:   { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:    { hosts: { 10.10.10.10: { etcd_seq: 1 } }, vars: { etcd_cluster: etcd } }
    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 }

demo/pgsql.cast

部署 Redis 集群

Pigsty 提供了可选的 Redis 支持，可作为 PostgreSQL 前端的缓存服务。

bin/redis-add redis-ms
bin/redis-add redis-meta
bin/redis-add redis-test

Redis 高可用设置需要使用集群模式或哨兵模式，详情请参阅 Redis 配置。

部署 Silo 对象存储集群

Pigsty 的 MINIO 模块 当前部署 Silo S3 兼容对象存储，可作为 PostgreSQL 的 备份存储仓库。模块、清单分组与剧本继续沿用 minio 兼容名称。

./minio.yml -l minio

严肃的生产环境 Silo 部署通常需要至少 4 个节点，每个节点配备 4 块硬盘（4N/16D）。

部署 Docker 模块

如果您想要使用容器运行一些 管理 PG 的工具 或者 使用 PostgreSQL 的软件，可以安装 DOCKER 模块。

./docker.yml -l infra

你可以使用预制的应用配置模板，一键拉起一些常见的软件工具，例如用于 PG 管理的 GUI 工具： Pgadmin：

./app.yml    -l infra -e app=pgadmin

甚至，您还可以用 Pigsty 自建 企业级质量的 Supabase，使用外面的高可用 PostgreSQL 集群作为底座，将无状态的部分运行在容器之中。

6 - 使用 Ansible 剧本完成部署

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

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

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

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

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

部署剧本

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

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

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

安装 Ansible

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

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

Debian / Ubuntu

sudo apt install -y ansible python3-jmespath

sudo dnf install -y ansible python3.12-jmespath python3-cryptography  # EL 8
sudo dnf install -y ansible python3-jmespath                           # EL 9
sudo dnf install -y ansible                                            # EL 10

MacOS

brew install ansible
pip3 install jmespath

修改默认密码！

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

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

执行剧本

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

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

目的	参数	描述
对象	`-l\|--limit <pattern>`	限制在特定分组 / 主机 / 模式上执行
任务	`-t\|--tags <tags>`	只运行具有特定标签的任务
参数	`-e\|--extra-vars <vars>`	额外的命令行参数
配置	`-i\|--inventory <path>`	使用特定的清单文件

./node.yml                         # 在所有主机上运行 node 剧本
./pgsql.yml -l pg-test             # 在 pg-test 集群上运行 pgsql 剧本
./infra.yml -t repo_build          # 运行 infra.yml 的子任务 repo_build
./pgsql-rm.yml -e pg_rm_pkg=false  # 删除 pgsql，但保留软件包（不卸载软件）
./infra.yml -i conf/mynginx.yml    # 使用另外一个位置的配置文件

限制主机

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

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

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

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

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

限制任务

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

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

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

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

额外变量

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

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

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

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

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

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

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

指定清单

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

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

更改默认清单文件

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

便捷脚本

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

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

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

剧本列表

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

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

7 - 离线安装

在没有互联网访问的环境中，使用离线安装包安装 Pigsty

Pigsty 默认从互联网上游安装所需软件包，但有些环境与互联网隔离。为了解决这个问题，Pigsty 支持使用 离线软件包 进行离线安装。您可以将其视作 Linux- 原生版本的 Docker 镜像。

概览

离线软件包 打包了所有需要的 RPM/DEB 软件包及其依赖；它是常规安装后的本地 APT / YUM 仓库的快照。

在 严肃的生产环境部署 中，我们 强烈推荐 您使用离线安装包进行安装。它可以确保后续所有新节点的软件版本与现有环境保持一致，并且可以避免上游变动导致的在线安装失败（相当常见！）确保您能独立自主运行它至地老天荒。

使用离线软件包的优点

可以简单方便的在互联网隔离的环境中交付实施。
一次性预下载所有软件包，可以有效加速安装过程。
无需担心上游依赖项的变动导致依赖错漏/安装失败。
如果有多个节点，那么所有软件包只需要下载一次，节省带宽资源。
可以通过本地仓库确保所有节点的软件版本一致，实行统一版本管理

使用离线软件包的缺点

离线安装包针对 特定的操作系统小版本制作，通常不能跨版本使用
仅为制作时刻的快照，可能不包含最新的更新和操作系统安全补丁。
离线安装包通常约 1GB 左右，而在线安装则是按需下载，更节省空间。

离线软件包

下表记录 v4.4.0 历史离线制品及其制作时使用的操作系统小版本；这些版本不代表 当前推荐操作系统。

Linux 发行版	系统代码	小版本	软件包
RockyLinux 9 x86_64	`el9.x86_64`	`9.7`	`pigsty-pkg-v4.4.0.el9.x86_64.tgz`
RockyLinux 9 aarch64	`el9.aarch64`	`9.7`	`pigsty-pkg-v4.4.0.el9.aarch64.tgz`
RockyLinux 10 x86_64	`el10.x86_64`	`10.1`	`pigsty-pkg-v4.4.0.el10.x86_64.tgz`
RockyLinux 10 aarch64	`el10.aarch64`	`10.1`	`pigsty-pkg-v4.4.0.el10.aarch64.tgz`
Debian 12 x86_64	`d12.x86_64`	`12.14`	`pigsty-pkg-v4.4.0.d12.x86_64.tgz`
Debian 12 aarch64	`d12.aarch64`	`12.14`	`pigsty-pkg-v4.4.0.d12.aarch64.tgz`
Debian 13 x86_64	`d13.x86_64`	`13.6`	`pigsty-pkg-v4.4.0.d13.x86_64.tgz`
Debian 13 aarch64	`d13.aarch64`	`13.6`	`pigsty-pkg-v4.4.0.d13.aarch64.tgz`
Ubuntu 26.04 x86_64	`u26.x86_64`	`26.04.0`	`pigsty-pkg-v4.4.0.u26.x86_64.tgz`
Ubuntu 26.04 aarch64	`u26.aarch64`	`26.04.0`	`pigsty-pkg-v4.4.0.u26.aarch64.tgz`
Ubuntu 24.04 x86_64	`u24.x86_64`	`24.04.4`	`pigsty-pkg-v4.4.0.u24.x86_64.tgz`
Ubuntu 24.04 aarch64	`u24.aarch64`	`24.04.4`	`pigsty-pkg-v4.4.0.u24.aarch64.tgz`
Ubuntu 22.04 x86_64	`u22.x86_64`	`22.04.5`	`pigsty-pkg-v4.4.0.u22.x86_64.tgz`
Ubuntu 22.04 aarch64	`u22.aarch64`	`22.04.5`	`pigsty-pkg-v4.4.0.u22.aarch64.tgz`

如果您使用的是上述历史制品精确匹配的操作系统小版本，可以使用对应的 v4.4.0 离线软件包。 v4.4.0 社区版在 GitHub 公开提供 Debian 13、EL 10、Ubuntu 24.04 三个平台的双架构离线包，共 6 个制品。 Debian 12、EL 9、Ubuntu 22.04、Ubuntu 26.04 的制品名称与校验和保留在此，离线包通过商业版提供。

社区版制品可以从 GitHub 发布页面 下载。v4.4.0 全部离线包的 MD5 校验和如下：

7de8b932412f1863fd9c033a7be355d7  pigsty-pkg-v4.4.0.d12.aarch64.tgz
2e5006a8d35eb1c087dc0ed11cf14d14  pigsty-pkg-v4.4.0.d12.x86_64.tgz
955308c00d3890f6e82a6a83bc624760  pigsty-pkg-v4.4.0.d13.aarch64.tgz
350f31c66de0aafff3bd91c2c9d740a0  pigsty-pkg-v4.4.0.d13.x86_64.tgz
0b4817a8edbab0bdf37ecee730fb0412  pigsty-pkg-v4.4.0.el10.aarch64.tgz
4584a61e4456749e68d86e4817cfe526  pigsty-pkg-v4.4.0.el10.x86_64.tgz
21621daf510a532829c36464d48f9198  pigsty-pkg-v4.4.0.el9.aarch64.tgz
504afd5030e2738a25e1b4c570d0e654  pigsty-pkg-v4.4.0.el9.x86_64.tgz
461c999424dee587ca33fe1a63df40d7  pigsty-pkg-v4.4.0.u22.aarch64.tgz
20ccc5ab8f9f4648b05bcd304f9fb5fc  pigsty-pkg-v4.4.0.u22.x86_64.tgz
d092c48ee55116ed5e2c99a3d909ccdd  pigsty-pkg-v4.4.0.u24.aarch64.tgz
24fa5399d8421305961fcaf91325b382  pigsty-pkg-v4.4.0.u24.x86_64.tgz
36f69b699d8b3041d35384970e157631  pigsty-pkg-v4.4.0.u26.aarch64.tgz
330047d117b20f04317dce506edd5d9a  pigsty-pkg-v4.4.0.u26.x86_64.tgz

离线软件包是为特定的 Linux 操作系统小版本制作的

当操作系统小版本不匹配时，有概率能用，也有概率失败，我们建议你不要冒险尝试。

请务必注意，上表 v4.4.0 历史制品中的 EL9/EL10 安装包基于 9.7 / 10.1 制作，Debian 安装包基于 12.14 / 13.6 制作，Ubuntu 安装包基于 22.04.5 / 24.04.4 / 26.04.0 制作。跨操作系统小版本可能因 OpenSSL 或系统库版本变化导致安装失败。您需要在安装相同操作系统的环境中执行在线安装后制作离线安装包，或联系我们定制离线软件包。

使用离线软件包

离线安装的步骤：

下载 Pigsty 离线软件包，将其放到 /tmp/pkg.tgz
下载 Pigsty 源码包，解压并进入目录（假设解压到家目录：cd ~/pigsty）
./bootstrap，它将解压软件包并配置使用本地仓库（并从中离线安装 ansible）
./configure -g -c rich，您可以直接使用配置好离线安装的模板 rich，或者自行配置
照常运行 ./deploy.yml，从本地仓库安装核心链路所需软件；其他可选模块仍需执行各自的剧本

demo/install-offline.cast

警告

如果你在离线安装时遇到 “No package nginx available” 之类的错误，通常说明之前有过失败的安装尝试。删除 /www/pigsty 目录后重新执行部署即可。

如果您想要在自己的配置中，使用已经解包配置好的离线软件包，请修改并确保以下配置项：

repo_enabled：将此参数打开，设置为 true，则会构建本地软件源（在大部份配置中被显式关闭）
node_repo_modules：将此参数设置为 local，则环境中所有节点都从本地软件仓库安装
- 在大部份模板中，此参数被显式配置为：node,infra,pgsql，即直接从这些上游软件仓库安装。
- 将其设置为 local，则会使用本地软件仓库安装所有软件包，速度最快，没有其他仓库的变数干扰。
- 如果你想同时使用本地软件仓库和上游软件仓库，可以将其设置为 local,node,infra,pgsql

第一个参数如果打开，Pigsty 会创建 本地软件仓库，第二个参数如果包含 local，则环境中的所有节点会使用这个本地软件仓库。如果只包含 local，那么它会成为所有节点的唯一软件源，如果你还想要从其他上游软件仓库继续安装其他软件包，可以将其他仓库模块名称也添加进去，例如 local,node,infra,pgsql。

混合安装模式

如果您的环境有互联网访问，那么有一种混合方法可以融合离线安装与在线安装的优点。您可以使用离线软件包作为基础，并在线补足不匹配的增量软件包。

以 v4.4.0 历史制品为例，假设您使用的是 RockyLinux 9.6，但该离线软件包是为 RockyLinux 9.7 制作的。您可以使用 el9 离线软件包（虽然是针对 9.7 制作的），然后在执行正式安装前，执行 make repo-build 重新下载 9.6 对应的缺失软件包， Pigsty 将从上游仓库重新下载所需的增量。

制作离线软件包

如果您选择的操作系统不在默认列表中，您可以使用内置的 cache.yml 剧本制作自己的离线软件包：

找到一台运行完全相同操作系统版本，且可以访问互联网的节点
使用 rich 配置模板执行 在线安装（./configure -c rich），并确认目标 Infra 节点的 /www/pigsty 本地仓库已经生成；若尚未生成，可先对该节点执行 ./infra.yml -t repo
cd ~/pigsty; ./cache.yml -l <infra-host>：明确选择一个已经具备本地仓库的 Infra 节点，制作并取回离线软件包
默认制品位于 ~/pigsty/dist/${version}/pigsty-pkg-${version}.${os}.${arch}.tgz；将它复制到离线环境（ftp、scp、usb 等），再通过 bootstrap 解包使用

cache.yml 的当前默认值如下，可使用额外变量覆盖：

cache_pkg_name , defaultpigsty-pkg-${version}.${os}.${arch}.tgz: 离线包文件名模板
cache_pkg_dir , defaultdist/${version}: 管理节点上的输出目录
cache_repo , defaultpigsty: 从目标节点打包的本地仓库；多个仓库用逗号分隔

我们提供 付费服务，提供经过测试的预制 Linux 主版本。次版本制作离线软件包（¥200）。

Bootstrap

Pigsty 依赖 ansible 执行剧本，这个脚本负责用各种方式来确保 ansible 正确安装。

./bootstrap       # 确保 ansible 正确安装（如果有离线包，优先使用离线安装并解包使用）

通常在两种情况下，你需要运行这个脚本：

你不是通过 安装脚本 来安装 Pigsty 的，而是通过下载，git clone 源码包的方式安装的，因此没有安装 ansible。
你准备通过离线软件包来安装 Pigsty，需要使用这个脚本来从离线软件包中安装 ansible。

bootstrap 脚本将自动检测离线软件包是否存在（-p 指定，默认为 /tmp/pkg.tgz）。如果存在则解压使用它，然后从里面安装 ansible。如果离线包不存在，它会尝试从互联网安装 ansible。如果还是不行，那你就要自己想办法了！

我的 yum/apt 仓库文件跑到哪里去了？

引导程序默认会移走现有软件源配置，以确保只有所需的仓库被启用。您可以在 /etc/yum.repos.d/backup (EL) 或 /etc/apt/backup (Debian / Ubuntu) 中找回它们。

如果您想在 bootstrap 过程中保留现有软件源配置，请使用 -k|--keep 参数。

./bootstrap -k # 或 --keep

8 - 精简安装

只安装高可用 PostgreSQL 集群及其最小依赖的精简安装模式

如果您只想要高可用 PostgreSQL 数据库集群本身，而不需要监控、基础设施等功能，请考虑 精简安装。

精简安装没有 INFRA 模块，没有监控，没有 本地仓库，只有 ETCD 和 PGSQL 以及部分 NODE 功能。

精简安装适合以下场景

只需要 PostgreSQL 数据库本身，不需要可观测性基础设施。
资源极度受限的环境，不愿意承担基础设施开销（单机约 0.2 vCPU / 500MB 开销）
已有外部监控系统，希望统一使用自己的监控管理体系。
不需要 Grafana 可视化看板组件。

精简安装的局限性

没有 基础设施模块，无法使用 WebUI 和本地软件仓库功能。
离线安装 仅限单机模式使用，多节点精简安装只能在线安装。

概览

使用精简安装，您需要：

使用 slim.yml 精简安装配置模板（configure -c slim）
执行 slim.yml 剧本进行部署，而不是默认的 deploy.yml

curl https://repo.pigsty.cc/get | bash
./configure -g -c slim
./slim.yml

demo/install-slim.cast

说明

精简安装只安装/配置以下组件：

组件	必要性	描述
`patroni`	⚠️ 必需	引导高可用 PostgreSQL 集群
`etcd`	⚠️ 必需	Patroni 的元数据库依赖（DCS）
`pgbouncer`	✔️ 可选	PostgreSQL 连接池
`vip-manager`	✔️ 可选	L2 VIP 绑定到 PostgreSQL 集群主节点
`haproxy`	✔️ 可选	根据 Patroni 健康检查，自动路由服务
`chronyd`	✔️ 可选	与 NTP 服务器的时间同步
`tuned`	✔️ 可选	节点调优模板和内核参数管理

你可以通过进一步的配置，关闭所有可选组件，只保留必需组件 patroni 和 etcd。

因为缺少 Infra 模块的 Nginx 提供本地仓库服务，只有单机安装的时候可以进行 离线安装。

配置

精简安装的配置文件示例：conf/slim.yml：

ID	NODE	PGSQL	INFRA	ETCD
1	`10.10.10.10`	`pg-meta-1`	不安装基础设施模块	`etcd-1`

---
#==============================================================#
# File      :   slim.yml
# Desc      :   Pigsty slim installation config template
# Ctime     :   2020-05-22
# Mtime     :   2025-12-28
# Docs      :   https://pigsty.io/docs/conf/slim
# License   :   Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright :   2018-2026  Ruohang Feng / Vonng ([email protected])
#==============================================================#

# This is the config template for slim / minimal installation
# No monitoring & infra will be installed, just raw postgresql
#
# Usage:
#   curl https://repo.pigsty.io/get | bash
#   ./configure -c slim
#   ./slim.yml

all:
  children:

    etcd: # dcs service for postgres/patroni ha consensus
      hosts: # 1 node for testing, 3 or 5 for production
        10.10.10.10: { etcd_seq: 1 }  # etcd_seq required
        #10.10.10.11: { etcd_seq: 2 }  # assign from 1 ~ n
        #10.10.10.12: { etcd_seq: 3 }  # three-member cluster keeps an odd voter count
      vars: # cluster level parameter override roles/etcd
        etcd_cluster: etcd  # mark etcd cluster name etcd

    #----------------------------------------------#
    # PostgreSQL Cluster
    #----------------------------------------------#
    pg-meta:
      hosts:
        10.10.10.10: { pg_seq: 1, pg_role: primary }
        #10.10.10.11: { pg_seq: 2, pg_role: replica } # you can add more!
        #10.10.10.12: { pg_seq: 3, pg_role: replica, pg_offline_query: true }
      vars:
        pg_cluster: pg-meta
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }
        pg_databases:
          - { name: meta, baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [ vector ]}
        pg_hba_rules:   # https://pigsty.io/docs/pgsql/config/hba
          - { user: all ,db: all ,addr: intra ,auth: pwd ,title: 'everyone intranet access with password' ,order: 800 }
        pg_crontab:     # https://pigsty.io/docs/pgsql/admin/crontab
          - '00 01 * * * /pg/bin/pg-backup full'

  vars:
    version: v4.5.0                   # pigsty version string
    admin_ip: 10.10.10.10             # admin node ip address
    region: default                   # upstream mirror region: default,china,europe
    nodename_overwrite: false           # do not overwrite node hostname on single node mode
    node_repo_modules: node,infra,pgsql # add these repos directly to the singleton node
    node_tune: oltp                     # node tuning specs: oltp,olap,tiny,crit
    pg_conf: oltp.yml                   # pgsql tuning specs: {oltp,olap,tiny,crit}.yml
    pg_version: 18                      # Default PostgreSQL Major Version is 18
    pg_packages: [ pgsql-main, pgsql-common ]   # pg kernel and common utils
    #pg_extensions: [ pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-olap ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl]

    #----------------------------------------------#
    # PASSWORD : https://pigsty.io/docs/setup/security/
    #----------------------------------------------#
    grafana_admin_password: pigsty
    grafana_view_password: DBUser.Viewer
    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: S3User.MinIO
    etcd_root_password: Etcd.Root
...

部署

精简安装需要使用 slim.yml 剧本而不是 deploy.yml 剧本进行部署：

./slim.yml

高可用集群

精简安装模式也可以部署高可用集群，在 etcd 和 pg-meta 分组中添加更多节点即可，一个三节点的部署样例：

ID	NODE	PGSQL	INFRA	ETCD
1	`10.10.10.10`	`pg-meta-1`	不安装基础设施模块	`etcd-1`
2	`10.10.10.11`	`pg-meta-2`	不安装基础设施模块	`etcd-2`
3	`10.10.10.12`	`pg-meta-3`	不安装基础设施模块	`etcd-3`

all:
  children:
    etcd:
      hosts:
        10.10.10.10: { etcd_seq: 1 }
        10.10.10.11: { etcd_seq: 2 }  # <-- 新增
        10.10.10.12: { etcd_seq: 3 }  # <-- 新增

    pg-meta:
      hosts:
        10.10.10.10: { pg_seq: 1, pg_role: primary }
        10.10.10.11: { pg_seq: 2, pg_role: replica } # <-- 新增
        10.10.10.12: { pg_seq: 3, pg_role: replica } # <-- 新增
      vars:
        pg_cluster: pg-meta
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }
        pg_databases:
          - { name: meta, baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [ vector ]}
        pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # 每天凌晨 1 点执行全量备份
  vars:
    # 省略 ……

9 - 安全建议

快速上手和单机部署的基本安全检查。

默认配置适用于本地演示和受信内网中的开发测试。只要部署可能被其他主机访问，就应至少完成凭据、网络和关键文件三项检查。

生产环境还应参考 安全模型、合规实践 和 安全考量。

密码

Pigsty 的默认凭据公开记录在源码和文档中，不能直接用于生产。

配置向导可以随机化其识别的内置参数和示例凭据：

./configure -g

configure -g 不会替换以下内容：

pgBackRest 的 cipher_pass；
ha/safe 中的 Silo 用户和部分示例口令；
用户自行添加的数据库、对象存储或应用凭据。

生成完成后，应检查 pigsty.yml，逐项替换未覆盖的凭据。配置向导会在终端输出生成的密码，因此终端记录和自动化日志也应按敏感信息保护。

完整范围见 默认凭据。

防火墙

node_firewall_mode 默认为 zone，信任 node_firewall_intranet 定义的内网，并限制公网放行端口。

端口	服务	默认公网状态
`22`	SSH	放行
`80`	Nginx HTTP	放行
`443`	Nginx HTTPS	放行
`5432`	PostgreSQL	基础默认值不放行；演示配置 `pigsty.yml` 额外放行

生产部署通常应从演示配置中移除 5432。如果业务需要直接连接数据库，应在云安全组、防火墙和 HBA 中同时限制来源地址。

还应检查内网定义是否符合实际信任边界。默认 RFC 1918 地址段可能覆盖范围过大，办公网、容器网段和其他租户网络不应自动视为可信。

文件

以下文件和目录包含高敏感信息：

pigsty.yml：系统与业务凭据、节点和服务配置；
files/pki/ca/ca.key：本地 CA 私钥；
管理用户 SSH 私钥：用于访问纳管节点；
files/pki/misc/*.key：客户端证书私钥；
/pg/tmp/pg-user-*.sql：用户创建过程中生成的明文口令 SQL。

应限制管理节点和配置仓库访问，避免将完整配置或私钥提交到公开仓库，并为 CA 私钥和必要配置建立受控备份。