Pigsty 完整指南：企业级 PostgreSQL 发行版的 HA、PITR 与 IaC 实战

• 数据库
• 运维
• 云原生
• 高可用
• 监控

项目定位：PostgreSQL In Great STYle

Pigsty 是一个企业级开源PostgreSQL 发行版，官方定位为 "Self-Host Postgres like a Pro"。名字本身即是设计哲学的浓缩：Postgres、Infras、Graphics、Service、Toolbox，it's allYours——数据库、基础设施、图形监控、服务接入、工具箱全部自持自管。

它解决的核心问题是云数据库（RDS）时代的痛点：托管数据库成本高、能力受限、难以深度定制。Pigsty 把一套完整的数据库交付能力打包成开源项目，让你在自有的裸金属 Linux 上，以接近 RDS 的体验获得数据库服务，同时保留对内核、参数、扩展的完全控制权。

从仓库根目录的 README.md 可以看到，Pigsty 的关键能力画像包括：

• 555 个 PostgreSQL 扩展与12 种 PostgreSQL 内核分支，打包覆盖16 个 Linux 发行版平台，开箱即用（battery-included）；
• 基于 Patroni + Etcd 的自愈式高可用（HA）、基于 pgBackRest 的预配置时间点恢复（PITR）、内置ACL 访问控制与CA/SSL 安全最佳实践；
• 基于VictoriaMetrics + Grafana技术栈的 PostgreSQL / 基础设施 / 节点三层面监控；
• 基于 HAProxy、PgBouncer 与 VIP 的自动路由、连接池化数据库服务接入；
• 一键部署、自动调优、本地软件源、IaC 配置以及 Vagrant / Terraform 环境支持；
• 可选的 Redis、MinIO、Etcd、Docker、DuckDB、FerretDB、Supabase 等附加模块；
• 无需 Docker 与 Kubernetes，直接运行于裸机 Linux，云中立、可自给自足的基础设施闭环。

核心特性：从可扩展到可负担

README 中归纳了八个维度的特性，它们共同定义了 Pigsty 的工程能力：

12 种 PostgreSQL 内核：一平台多引擎

Pigsty 最具辨识度的能力之一，是允许在同一个平台上以「就地替换」的方式部署多种 PostgreSQL 内核分支，并将其包装为完整的 RDS 服务。README 中列出的内核及定位如下：

说明：README 特性横幅中概括为 12 个内核，表格则细分到 13 行（Supabase 同时以应用模块与内核两种身份出现）；以其表格为准可更精确地理解各内核能力。

这些内核的配置入口在仓库中均有对应模板：例如 Citus 见 conf/ha/citus.yml，IvorySQL 见 conf/ivory.yml，PolarDB 见 conf/polar.yml，OrioleDB 见 conf/oriole.yml，pgEdge 见 conf/pgedge.yml。

快速开始：从零到可用 PostgreSQL 的三种路径

README 提供了三种安装 Pigsty 的方式，推荐运行环境为全新、干净的x86_64/aarch64Linux 节点（建议使用具备 nopass sudo 与 nopass ssh 的管理用户，而非 root）。

路径一：get 脚本（官方推荐，可指定版本）

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

该脚本会在节点上依次完成版本下载、MD5 校验、解压安装、Ansible 引导（bootstrap）与环境检测。README 展示了完整的安装日志流程：检测 region/kernel/machine/package/vendor/version、移动旧软件源、添加 Pigsty 与上游软件源、构建元数据缓存、安装 Ansible 与依赖集合，最终提示proceed with ./configure。

路径二：pig 命令行

curl -fsSL https://repo.pigsty.io/pig | bash # 安装 pig pig sty init # 安装最新 pigsty 源码到 ~/pigsty pig sty conf # 自动生成 pigsty.yml 配置文件 pig sty deploy # 运行 deploy.yml playbook

路径三：git 克隆源码

git clone https://github.com/pgsty/pigsty; cd pigsty; git checkout v4.4.0

注意：main分支为开发分支，使用前务必检出对应版本 tag。

配置与部署

安装完成后，进入 pigsty 家目录执行配置与部署：

./configure -g # 生成配置并随机密码 ./deploy.yml # 在当前节点部署一切

• ./configure是交互式配置向导，用于生成 pigsty.yml 清单文件（Ansible inventory，见仓库根 ansible.cfg 中inventory = pigsty.yml）；
• ./deploy.yml是核心 playbook。从源码看，它按顺序交织执行了IDENTITY → CA → REPO → NODE INIT → INFRA INIT → NODE MONITOR → ETCD INIT → MINIO INIT → PGSQL INIT九个阶段（deploy.yml），等价于依次运行infra.yml -l infra、node.yml -l all、etcd.yml -l etcd、minio.yml -l minio、pgsql.yml -l all五个 playbook。

部署完成后，你将得到一个开箱即用的单节点（singleton）Pigsty 环境：WebUI 位于 80/443 端口，PostgreSQL 位于 5432 端口。

对于开发/测试场景，也可以在 Docker 容器内运行 Pigsty：cd docker; make launch（对应 docker/ 目录）。

架构：模块化设计的四大支柱与可选模块

Pigsty 采用模块化设计，核心是四个相互独立、可自由组合的模块：

组合规则非常简单：仅需主机监控时，INFRA+NODE即可；需要 HA PG 集群时，加入ETCD与PGSQL，并在多个节点上安装即可自动组成 HA 集群。默认 deploy.yml 会在当前节点部署INFRA、NODE、ETCD、PGSQL四者，交付开箱即用的 PostgreSQL 单实例（admin_ip:5432）。

节点同时可充当管理控制机，用于部署与监控更多节点和集群。README 还列出了 6 个可选附加模块，用于高级场景：

• MinIO：S3 兼容对象存储，作为 PGSQL 的可选集中备份服务器；
• Redis：支持单机主从、哨兵（sentinel）与原生集群三种模式；
• Ferret：原生支持 FerretDB，为 Postgres 增加 MongoDB 线级协议兼容；
• Docker：启动可选 Docker 守护进程，运行 Pigsty RDS 之外的无状态组件；
• Juice：JuiceFS，可将 S3/MinIO 乃至 PostgreSQL 挂载为多用户共享文件系统；
• Vibe：包含 VS Code Server、JupyterLab、Node.js 与 Claude Code 的 Vibe 编码环境。

除此之外，仓库还有 pro / beta / pilot 级别的更多模块方向，如 Kafka（对应角色 roles/kafka/）、MySQL、DuckDB、Kubernetes、Consul、Jupyter 等。

PostgreSQL RDS：声明式集群定义与一键创建

Pigsty 的数据库交付核心是「声明式清单 + 一条命令」。部署一个额外的 3 节点 HA 集群pg-test，只需在 pigsty.yml 的all.children下加入以下片段：

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: offline } vars: { pg_cluster: pg-test }

然后调用内置脚本一次创建：

bin/pgsql-add pg-test # init pg-test cluster

从 bin/pgsql-add 源码可见该脚本的分支行为：只给一个参数时创建整个集群（执行./pgsql.yml -l <cls>）；给出多个 IP 参数时为既有集群追加副本实例（先./pgsql.yml -l '&cls,ip1,ip2'初始化新实例，再./pgsql.yml -l 'cls,!ip...' -t pg_service重载既有实例的 HAProxy 服务以重路由流量）。这与 README 中「add replicas to cluster」的用法完全一致。

创建完成后，集群自带全部标配能力：

• 高可用：Patroni + Etcd 驱动，RPO = 0（同步模式），RPO < 1MB（异步模式），切换（switchover）RTO 约 2 秒，故障转移（failover）RTO 小于 30 秒——只要任一实例存活，集群持续对外服务；
• 时间点恢复：pgBackRest 驱动，可搭配本地 POSIX 文件系统或可选的 MinIO / S3；
• 服务接入：PgBouncer 池化 + HAProxy 暴露，自动路由读写流量，支持默认服务与自定义服务；
• 监控告警：由 INFRA 模块提供开箱即用的仪表盘与告警规则。

复杂定制：数据库、用户、服务与访问控制的完整语法

README 以集群pg-meta为例，给出了生产级复杂 PostgreSQL 定制的完整配置，涉及 pg_databases（数据库）、pg_users（用户/角色）、pg_services（服务）三类实体定义。以下按实体分类整理全部参数语义。

数据库定义（pg_databases）

name是唯一必填字段，其余均为可选：

用户/角色定义（pg_users）

name为唯一必填字段：

PostgreSQL 16+ 还支持角色定义的扩展格式进行细粒度授权：

roles: - dbrole_readwrite # 简单格式：直接授予角色 - name: dbrole_admin # 扩展格式：携带选项 state: grant # grant（默认）| revoke/absent admin: false # 是否带 admin 选项 inherit: true # 是否带 inherit 选项（PG16+） set: true # 是否带 set 选项（PG16+）

服务定义（pg_services）

自定义服务用于暴露额外的接入端口，README 中的standby示例可将 5435 端口的流量路由到同步副本的 pgbouncer（5435 → 6432 standby）：

pg_services: - name: standby # 必填，实际服务名会加 pg_cluster 前缀，如 pg-meta-standby port: 5435 # 必填，暴露端口（类似 k8s NodePort） ip: "*" # 绑定地址，默认 * 全部 selector: "[]" # 必填，用 JMESPath 过滤清单选择成员 dest: default # 目标端口：default|postgres|pgbouncer|<port> check: /sync # 健康检查 URL 路径 backup: "[? pg_role == `primary`]" # 备用服务器选择器 maxconn: 3000 # 前端最大连接数 balance: roundrobin # haproxy 负载均衡算法（roundrobin/leastconn） #options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

访问控制、VIP 与定时任务

pg_hba_rules: - {user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes'} pg_vip_enabled: true pg_vip_address: 10.10.10.2/24 pg_crontab: # make a full backup 1 am everyday - '00 01 * * * /pg/bin/pg-backup full'

• pg_hba_rules以声明式数组追加 HBA 规则，addr支持local/localhost/intra/world等预定义集合与具体网段，auth支持ident/pwd/ssl/cert/trust/deny等；
• pg_vip_enabled+pg_vip_address启用绑定到主节点的 L2 VIP（keepalived 实现，见 roles/node/tasks/vip.yml）；
• pg_crontab通过 files/postgres/pg-backup 脚本编排 pgBackRest 定时全量/增量备份。

自定义场景：四种代表性配置模板

Pigsty 内置大量配置模板（conf/ 目录），README 展开讲解了三种典型场景，加上单节点默认模板共四种。

单节点 meta（conf/meta.yml）

默认 1 节点在线安装配置，包含 INFRA、NODE、PGSQL、ETCD、MINIO、DOCKER、APP 模块，附带基础扩展 postgis、pgvector。关键点：

• pg_extensions: [postgis, pgvector]声明集群级扩展，见 conf/meta.yml；
• 通过 files/cmdb.sql 作为meta数据库基线；
• 单节点模式下关闭本地软件源（repo_enabled: false），使用node_repo_modules: 'node,infra,pgsql'直接把软件源加入节点；
• 默认附带 pgadmin 应用（app: pgadmin），部署后可通过./app.yml启动（端口 8885）。

4 节点沙箱双 PG（conf/ha/full.yml）

四个节点部署两个 PG 集群：单实例pg-meta（10.10.10.10）+ 三节点 HA 集群pg-test（10.10.10.11/12/13），同时带有 redis-ms（主从）、redis-meta（3 哨兵）、redis-test（3 主 3 从原生集群）等模块。README 中的 4 节点示例即为该模板的精简版，其中pg-test的 3 节点定义与 README 完全一致。

安全增强与延迟副本（conf/ha/safe.yml）

4 节点安全增强模板：3 节点pg-meta集群 + 可选延迟副本pg-meta-delay（pg_upstream指向主集群、pg_delay: 1h，将数据滞后 1 小时用于误操作恢复）。其安全策略包括：

• pg_conf: crit.yml使用 templates/crit.yml 关键参数模板，强制校验（checksum enforced）、无数据丢失；
• patroni_ssl_enabled: true、pgbouncer_sslmode: require、pg_default_service_dest: postgres，SSL 全链路强制，默认服务直达 PostgreSQL；
• pg_libs加入$libdir/passwordcheck强制强密码策略，并装载 pgaudit、credcheck、set_user、anonymizer 等一批安全扩展；
• pg_default_roles/pg_default_hba_rules/pgb_default_hba_rules全量定制默认角色与两层 HBA 规则，所有用户强制设置过期时间（expire_in: 7300，约 20 年）；
• 全局密码一律使用显式强口令示例并提示更换，见 conf/ha/safe.yml。

Citus 水平分片（conf/ha/citus.yml）

在原生 PostgreSQL 上叠加 Citus 实现水平分片：13 节点（1 个协调节点组 + 6 个工作节点组，每组主备成对），README 展示了 10 节点 5 组的精简写法。关键参数：

pg_mode: citus # pgsql cluster mode: citus pg_shard: pg-citus # citus shard name pg_primary_db: test # citus 使用的 primary database pg_dbsu_password: DBUser.Postgres # 全集群 dbsu 密码访问 pg_extensions: [ 'citus postgis timescaledb pgvector' ] pg_libs: 'citus, timescaledb, pg_stat_statements, auto_explain'

每个节点通过pg_group分组、pg_cluster命名子集群、pg_vip_address分配组内 VIP；HBA 规则对集群成员网段放行trust、对内网强制ssl。

除上述实例类型外，Pigsty 还支持部署primary、replica、offline、delayed、sync standby等不同角色实例，并在同一部署内混用不同 PG 大版本与内核分支。用户、数据库、服务、HBA 等实体均可「以代码定义、一遍开通」。

自托管应用：以 Supabase 为例

Pigsty 同样用于自托管 Postgres 生态软件（Supabase、Odoo、Dify、Electric、GitLab 等）。README 给出启动自托管 Supabase 的四条命令：

./configure -c supabase # 使用 supabase 配置模板 ./deploy.yml # 安装 pigsty ./docker.yml # 安装 docker compose ./app.yml # 用 docker 启动 supabase 无状态部分

conf/supabase.yml 描述了一切所需：在pg-meta集群中预置 Supabase 角色（anon、authenticated、dashboard_user、service_role及supabase_admin、authenticator等 8 个用户）、两个数据库（postgres承载业务、_supabase承载内部分析），并在postgres库中创建 7 个 schema（extensions、auth、realtime、storage、graphql_public、supabase_functions、_realtime）与 14 个扩展（pgcrypto、pg_net、pgjwt、uuid-ossp、pgsodium、supabase_vault、pg_jsonschema、wrappers、http、pg_cron、timescaledb、pg_tle、vector、pgmq）。

配套机制包括：pg_libs装载timescaledb, pgsodium, plpgsql, plpgsql_check, pg_cron, pg_net, pg_stat_statements, auto_explain, pg_wait_sampling, pg_tle, plan_filter；HBA 规则放行 Docker 网段（172.17.0.0/16）与内网；定时任务supa-kick每分钟清理_analytics滞后（对应 files/postgres/supa-kick 脚本）；SQL 基线为 files/supabase.sql。

兼容性：受支持的 Linux 发行版矩阵

Pigsty 直接运行于裸机 Linux，聚焦主流 LTS 发行版。生产环境推荐 Rocky 9.7 / 10.1、Debian 13.6 / 12.14、Ubuntu 24.04.4 / 22.04.5。完整支持矩阵（README 中给出，仓库内有对应标识文件）：

注意：README 注明 EL 9/10 被锁定在 9.7/10.1，因为更新的上游小版本当前存在问题（broken）。对应发行版小版本同样体现在 templates/distro/ 的构建模板中。

源码级佐证：部署编排与工具链

围绕 README 的核心声明，仓库源码提供了多层次的实现证据：

1. 部署编排：deploy.yml 的九个阶段与各 playbook（infra.yml、node.yml、etcd.yml、minio.yml、pgsql.yml）一一对应，其中pgsql角色仅在pg_cluster is defined时执行，印证了「声明清单即部署范围」的 IaC 模型。

2. 集群创建工具：bin/pgsql-add 的1 参数创建 / N 参数扩容双分支逻辑，以及 bin/pgsql-rm 对应的销毁路径；bin/node-add 负责节点纳入管理（README 提示bin/pgsql-add前需先执行节点纳管）。

3. Makefile 速查：Makefile 将整个运维面浓缩为常用目标：make bootstrap（准备软件源与 Ansible）、make configure（交互配置）、make deploy（部署）、make infra（只装基础设施）、make pgsql-add（装 PG 集群）、make test-rw / test-ro（pgbench 压测）、make meta9 / full9 / simu9（拉起 1/4/20 节点 Vagrant 沙箱）等。

4. 监控资产：files/grafana/ 下的 pgsql、node、infra、redis、minio 等目录提供全套仪表盘 JSON（如 files/grafana/pgsql/pgsql-cluster.json、files/grafana/pgsql/pgsql-instance.json），告警规则见 files/victoria/rules/pgsql.yml；仪表盘由 files/grafana/grafana.py 统一管理（对应make di/dd/dc的 init/dump/clean 目标）。

5. 应用编排：app/目录（如 app/supabase/docker-compose.yml、app/minio/docker-compose.yml）承载各应用的 docker-compose 定义，由app.ymlplaybook 统一驱动，README 中「./app.yml启动应用」的链路因此得以闭环。

许可证

Pigsty 以Apache-2.0协议开源（见 LICENSE 与 NOTICE）。如需在自有节点上体验完整流程，可按上文「快速开始」章节的三条路径之一获取源码，再依次执行./configure -g与./deploy.yml完成单节点交付；生产级多节点与 HA 能力，则可通过修改 pigsty.yml 清单并调用 bin/pgsql-add 等工具逐步扩展。

• 数据库
• 运维
• 云原生
• 高可用
• 监控