PIGSTY on Pigsty v5.0

Pigsty v5.0 文档

Sat, 11 Jan 2025 00:00:00 +0000

Pigsty v5.0 文档聚焦 Pigsty 自身：架构、安装、部署、配置、运维，以及每个正式模块的完整手册。

v5.0 文档预览 OINK 0.6.0 本地优先

亮点特性

Mon, 01 Jan 0001 00:00:00 +0000

“PostgreSQL In Great STYle”: Postgres, Infras, Graphics, Service, Toolbox, it’s all Yours.

—— 开箱即用、本地优先的 PostgreSQL 发行版，开源 RDS 替代

价值主张

可扩展性：海量扩展 开箱即用：深度整合 PostGIS、TimescaleDB、Citus、PGVector 等 575 插件与 12 款 PG 内核。
可靠性：快速创建 高可用、故障自愈的 PostgreSQL 集群，自动预置 时间点恢复、访问控制、自签名 CA 与 TLS。
可观测性：基于 Victoria 与 Grafana 的可观测性技术栈，提供惊艳的监控最佳实践。模块化设计，可独立使用：画廊 & Demo。
可用性：交付稳定可靠，自动路由，事务池化、读写分离的高性能数据库服务，通过 HAProxy，Pgbouncer，VIP 提供灵活的接入模式。
可维护性：简单易用，基础设施即代码，管理SOP预案，自动调参，本地软件仓库，Vagrant 沙箱与 Terraform 模板，不停机迁移方案。
可组合性：模块化 架构设计，可复用的 Infra，多样的可选模块：Redis、Silo 对象存储、ETCD、DuckDB、Docker、Supabase。

总览

Pigsty 是一个更好的本地开源 RDS for PostgreSQL 替代：

历史沿革

Mon, 01 Jan 0001 00:00:00 +0000

历史起源

Pigsty 项目始于 2018 ～ 2019 年，起源于探探。探探是一个互联网交友 App —— 中国的 Tinder，现已被陌陌收购。探探这家公司是一个北欧风格的创业公司，有着一个瑞典工程师初创团队。

活动新闻

Mon, 01 Jan 0001 00:00:00 +0000

上手

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

发展规划

Mon, 01 Jan 0001 00:00:00 +0000

版本发布策略

Pigsty 使用语义化版本号，<主版本>.<次版本>.<修订号>。Alpha / Beta / RC 版本会在版本号后添加后缀，如 -a1，-b1，-c1。

加入社区

Mon, 01 Jan 0001 00:00:00 +0000

GitHub

我们的 GitHub 仓库地址是：https://github.com/pgsty/pigsty，欢迎点个 ⭐️ 关注我们。

我们欢迎任何人提交新 Issue 或创建 Pull Request，提出功能建议并参与 Pigsty 贡献。

隐私政策

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty软件

当您安装 Pigsty 软件时，如果在网络隔离的环境中使用离线软件包安装，我们不会收到任何关于您的数据。

如果您选择在线安装，那么在下载相关软件包时，我们的服务器或云供应商的服务器会自动在日志中记录来访机器的 IP 地址和/或主机名，和您下载的软件包名称。除非法律要求，我们不会与其他组织共享这些信息。（实话说，吃饱了撑着才会去看这些东西）

开源协议

Mon, 01 Jan 0001 00:00:00 +0000

协议摘要

Pigsty 项目主体使用 Apache-2.0 开源许可证；Pigsty 文档网站使用 CC by 4.0 许可证。项目协议地址：https://github.com/pgsty/pigsty/blob/main/LICENSE

Pigsty 项目主体

Pigsty 软件主体采用 Apache License 2.0 许可证。这是一种宽松的开源许可证，允许您自由地使用、修改和分发本软件，包括用于商业目的，而无需公开您的源代码或使用相同许可证。

赞助我们

Mon, 01 Jan 0001 00:00:00 +0000

赞助我们

Pigsty 是一个开源免费的自由软件，由 PostgreSQL 社区成员用热情浇灌而成，旨在整合 PostgreSQL 生态的力量，推广 PostgreSQL 的普及。如果我们的工作帮到了您，请考虑赞助或者支持一下我们的项目：

行业案例

Mon, 01 Jan 0001 00:00:00 +0000

根据 Google Analytics PV 与下载量，Pigsty 目前有约 10 万用户，一半来自中国大陆，一半来自全球其他地区。遍布互联网、云计算、金融、自动驾驶、制造业、科技创新、ISV 与军工等多个行业。如果您在使用 Pigsty 并且愿意与我们分享您的案例与 Logo，欢迎联系我们，我们提供一次的免费咨询支持。

订阅服务

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 旨在聚集 PG 生态的合力，并用自动驾驶的数据库管控软件帮助用户用好世界上 最流行 的数据库 PostgreSQL。

尽管 Pigsty 本身已经解决了 PG 使用中的诸多问题。但想真正达到企业级服务的质量，原厂提供的专家支持与兜底服务不可或缺。我们深知专业的商业支持服务对于企业客户的重要性，因此，Pigsty 企业版在开源版本的基础上提供了一系列增值服务，帮助用户更好地用好 PostgreSQL 与 Pigsty，供有需求的客户按需选用。

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 是什么，不是什么？

Pigsty 是一个 PostgreSQL 数据库发行版，本地优先的开源 RDS 云数据库解决方案。 Pigsty 不是数据库管理系统（DBMS），而是管理 DBMS 的工具，发行版，解决方案，与最佳实践。

积木式架构

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 使用 模块化架构 与 声明式接口，您可以像 搭积木一样自由按需组合模块。

Pigsty 采用 模块化设计，可自由组合，按需使用（Use one or all），以适应不同场景的需求。
Pigsty 使用 配置清单 和 配置参数 描述整套部署环境，并通过 Ansible 剧本 实现部署与调整。
Pigsty 在可以在任意节点上运行，无论是物理裸机还是虚拟机，只要运行 兼容的操作系统 即可。

模块

Pigsty 采用模块化设计，有六个主要的默认模块：PGSQL、INFRA、NODE、ETCD、REDIS 和 MINIO。

集群模型图

Mon, 01 Jan 0001 00:00:00 +0000

在 Pigsty 中最大的实体概念叫做 部署（Deployment），一套部署中的主要实体与关系（E-R 图）如下所示：

一套部署也可以理解为一个 环境（Environment）。例如，生产环境（Prod），用户测试环境（UTA），预发环境（Staging），测试环境（Testing），开发环境（Devbox），等等。每个环境中，都对应着一份 Pigsty 配置清单，描述了环境中的所有实体与属性。

成本对比

Mon, 01 Jan 0001 00:00:00 +0000

总体概览

以下成本数据用于说明量级差异，云厂商价格与折扣会随时间、区域、实例规格和采购方式变化。

EC2	核·月	RDS	核·月
DHH 自建核月价格（192C 384G）	25.32	初级开源数据库 DBA 参考工资	15K/人·月
IDC 自建机房（独占物理机: 64C384G）	19.53	中级开源数据库 DBA 参考工资	30K/人·月
IDC 自建机房（容器，超卖500%）	7	高级开源数据库 DBA 参考工资	60K/人·月
UCloud 弹性虚拟机（8C16G，有超卖）	25	ORACLE 数据库授权	10000
阿里云弹性服务器 2x 内存（独占无超卖）	107	阿里云 RDS PG 2x 内存（独占）	260
阿里云弹性服务器 4x 内存（独占无超卖）	138	阿里云 RDS PG 4x 内存（独占）	320
阿里云弹性服务器 8x 内存（独占无超卖）	180	阿里云 RDS PG 8x 内存（独占）	410
AWS C5D.METAL 96C 200G (按月无预付)	100	AWS RDS PostgreSQL db.T2 (2x)	440
AWS C5D.METAL 96C 200G (预付三年)	80	AWS RDS PostgreSQL db.M5 (4x)	611
AWS C7A.METAL 192C 384G (预付三年)	104.8	AWS RDS PostgreSQL db.R6G (8x)	786

RDS成本参考

付费模式	价格	折合每年（万¥）
IDC 自建（单物理机）	¥7.5w / 5年	1.5
IDC 自建（2～3台组 HA）	¥15w / 5年	3.0 ~ 4.5
阿里云 RDS 按需	¥87.36/时	76.5
阿里云 RDS 月付（基准）	¥4.2w / 月	50
阿里云 RDS 年付（85折）	¥425095 / 年	42.5
阿里云 RDS 3年付（5折）	¥750168 / 3年	25
AWS 按需	$25,817 / 月	217
AWS 1年不预付	$22,827 / 月	191.7
AWS 3年全预付	12w$ + 17.5k$/月	175
AWS 中国/宁夏按需	¥197,489 / 月	237
AWS 中国/宁夏1年不预付	¥143,176 / 月	171
AWS 中国/宁夏3年全预付	¥647k + 116k/月	160.6

我们可以对比一下自建与云数据库的成本差异：

开源影响力

Mon, 01 Jan 0001 00:00:00 +0000

中国 PostgreSQL 生态项目影响力

GitHub Star 数降序排列，最后更新时间为北京时间 2026-08-13。

项目	Star	作者	类型	简介
`pgsty/pigsty`	5521	冯若航 @ PGSTY	发行版	开箱即用的 PostgreSQL 发行版
`polardb/PolarDB-for-PostgreSQL`	3191	阿里云	内核	阿里云开源 PolarDB for PostgreSQL 内核
`tensorchord/pgvecto.rs`	2181	TensorChord	扩展	Rust 编写的向量检索扩展
`tensorchord/VectorChord`	1770	TensorChord	扩展	下一代向量检索扩展
`Tencent/TBase`	1439	腾讯云	内核	腾讯分布式 HTAP 数据库内核
`apache/cloudberry`	1315	HashData	内核	开源 MPP 数据仓库内核
`IvorySQL/IvorySQL`	1051	济南瀚高	内核	Oracle 兼容 PostgreSQL 分支
`pgplex/pgschema`	995	陈天舟	工具	声明式 Postgres Schema 迁移 CLI
`amutu/zhparser`	869	Jov	扩展	基于 SCWS 的中文全文分词扩展
`opengauss-mirror/openGauss-server`	784	华为	内核	早期 PG 9.2 内核分叉
`HaloTech-Co-Ltd/openHalo`	437	易景羲和	内核	MySQL 协议兼容的 PostgreSQL 内核
`jaiminpan/pg_jieba`	417	Pan Jiamin	扩展	基于结巴分词的中文全文检索扩展
`alitrack/duckdb_fdw`	409	李红艳	扩展	DuckDB 外部数据源包装器
`tensorchord/VectorChord-bm25`	375	TensorChord	扩展	PostgreSQL 原生 BM25 排序索引
`pgsty/pg_exporter`	359	冯若航 @ PGSTY	工具	PostgreSQL 与 Pgbouncer 指标采集器
`ChenHuajun/pg_roaringbitmap`	286	陈华军 @ 苏宁	扩展	PostgreSQL RoaringBitmap 位图扩展
`pgsty/pig`	199	冯若航 @ PGSTY	工具	PostgreSQL 扩展包管理器
`tensorchord/pg_bestmatch.rs`	101	TensorChord	扩展	在 PostgreSQL 内生成 BM25 稀疏向量
`wublabdubdub/PDU-PostgreSQLDataUnloader`	101	张晨	工具	PostgreSQL 数据库救援与数据卸载工具
`tensorchord/pg_tokenizer.rs`	45	TensorChord	扩展	全文检索 tokenizer 扩展
`jaiminpan/pg_scws`	41	Pan Jiamin	扩展	基于 SCWS 的中文分词扩展
`pgsty/pgext`	31	冯若航 @ PGSTY	工具	PG 扩展目录与元数据工具

tooltip:
  trigger: axis
  axisPointer: { type: shadow }
  formatter: $fn:tipfmt
grid: { left: 320, right: 72, top: 20, bottom: 26 }
xAxis:
  type: value
  max: 5600
  name: GitHub Star
  nameLocation: middle
  nameGap: 24
  axisLabel: { formatter: $fn:fnum }
  splitLine: { show: true, lineStyle: { type: dashed, opacity: 0.45 } }
yAxis:
  type: category
  inverse: true
  axisLabel:
    align: right
    margin: 8
    width: 300
    overflow: truncate
    fontSize: 11
    fontFamily: monospace
  data:
    - 'pgsty/pigsty'
    - 'polardb/PolarDB-for-PostgreSQL'
    - 'tensorchord/pgvecto.rs'
    - 'tensorchord/VectorChord'
    - 'Tencent/TBase'
    - 'apache/cloudberry'
    - 'IvorySQL/IvorySQL'
    - 'pgplex/pgschema'
    - 'amutu/zhparser'
    - 'opengauss-mirror/openGauss-server'
    - 'HaloTech-Co-Ltd/openHalo'
    - 'jaiminpan/pg_jieba'
    - 'alitrack/duckdb_fdw'
    - 'tensorchord/VectorChord-bm25'
    - 'pgsty/pg_exporter'
    - 'ChenHuajun/pg_roaringbitmap'
    - 'pgsty/pig'
    - 'tensorchord/pg_bestmatch.rs'
    - 'wublabdubdub/PDU-PostgreSQLDataUnloader'
    - 'tensorchord/pg_tokenizer.rs'
    - 'jaiminpan/pg_scws'
    - 'pgsty/pgext'
series:
  - name: Star
    type: bar
    barWidth: 20
    showBackground: true
    backgroundStyle: { color: "rgba(148, 163, 184, 0.16)" }
    itemStyle:
      color: $fn:barclr
      borderRadius: [0, 5, 5, 0]
    label:
      show: true
      position: right
      formatter: $fn:labfmt
      color: '#334155'
      fontWeight: 600
    data: [5521, 3191, 2181, 1770, 1439, 1315, 1051, 995, 869, 784, 437, 417, 409, 375, 359, 286, 199, 101, 101, 45, 41, 31]

PostgreSQL 发行版影响力指标

按 GitHub Star 数降序排列（商业产品无公开 Star 的统一置后），最后更新时间为北京时间 2026-08-13。

声明式配置 —— 基础设施即代码（IaC）

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 遵循 IaC 与 GitOPS 的理念：使用声明式的 配置清单 描述整个环境，并通过 幂等剧本 来实现。

用户用声明的方式通过参数来描述自己期望的状态，而剧本则以幂等的方式调整目标节点以达到这个状态。这类似于 Kubernetes 的 CRD & Operator，然而 Pigsty 在裸机和虚拟机上，通过 Ansible 实现了这样的功能。

PG 高可用

Mon, 01 Jan 0001 00:00:00 +0000

概览

Pigsty 的 PostgreSQL 集群带有开箱即用的高可用方案，由 Patroni、Etcd 和 HAProxy 提供核心能力。

当您的 PostgreSQL 集群含有两个或更多实例时，您无需任何配置即拥有了硬件故障自愈的数据库高可用能力 —— 只要集群中有任意实例存活，集群就可以对外提供完整的服务，而客户端只要连接至集群中的任意节点，即可获得完整的服务，而无需关心主从拓扑变化。

RPO 利弊权衡

Mon, 01 Jan 0001 00:00:00 +0000

RPO（Recovery Point Objective，恢复点目标）定义了在主库发生故障时，允许丢失的最大数据量。

对于金融交易这类数据完整性至关重要的场景，通常要求 RPO = 0，即不允许任何数据丢失；

部署

Mon, 01 Jan 0001 00:00:00 +0000

与 快速上手 不同，企业生产环境 Pigsty 部署需要更多 架构规划 与 准备工作。

本章将帮助您理解 Pigsty 的完整部署流程，并提供生产环境部署的最佳实践建议。

我们建议您在真实的生产环境部署之前，使用 Pigsty 提供的 沙箱环境 进行测试与演练，确保对部署流程有充分的了解。您可以使用 Vagrant 在本地快速创建一个四节点的 Pigsty 沙箱环境用于测试，或者利用 Terraform 在云端置备一个更大规模的仿真环境。

RTO 利弊权衡

Mon, 01 Jan 0001 00:00:00 +0000

RTO（Recovery Time Objective，恢复时间目标）定义了在主库发生故障时，系统恢复写入能力所需的最长时间。

对于核心交易系统这类可用性至关重要的场景，通常要求 RTO 尽可能短，例如一分钟内。

配置清单

Mon, 01 Jan 0001 00:00:00 +0000

每一套 Pigsty 部署都对应着一份 配置清单 （Inventory），描述了基础设施与数据库集群的关键属性。

配置文件

Pigsty 默认使用 Ansible YAML 配置格式，使用一个单一 YAML 配置文件 pigsty.yml 作为配置清单。

配置向导

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供了一个 configure 脚本作为 配置向导，它能根据当前环境，自动生成合适的 pigsty.yml 配置文件。

这是一个可选的脚本：如果您已经了解了如何配置 Pigsty，大可以直接编辑 pigsty.yml 配置文件，跳过向导。

配置参数

Mon, 01 Jan 0001 00:00:00 +0000

在 配置清单 中，您可以使用各种参数对 Pigsty 进行精细化定制。这些参数涵盖了从基础设施设置到数据库配置的各个方面。

参数列表

按照当前源码与参数参考页对账，Pigsty 的 10 个正式模块共有 373 个公开参数，用于精细控制系统的各个方面；完整列表见 参考-参数列表。原生 MySQL 8.4 试点模块的 13 个公开参数单列，不计入该合计。

配置模板

Mon, 01 Jan 0001 00:00:00 +0000

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

然而，直接编写配置文件可能会让新用户望而生畏。为此，我们提供了一些开箱即用的配置模板，涵盖了常见的使用场景。

元数据库

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 允许您使用 PostgreSQL 元数据库 作为动态配置源，取代静态的 YAML 配置文件，实现更强大的配置管理能力。

概览

CMDB（Configuration Management Database，配置管理数据库）是一种将配置信息存储在数据库中进行管理的方式。

安全合规

Mon, 01 Jan 0001 00:00:00 +0000

数据库通常是信息系统中最敏感的组件：它保存着最有价值的数据，也因此是攻击与故障后果最严重的地方。数据库安全并不是某个可以一键开启的功能，而是一系列问题的答案之和：谁能连进来？连进来能做什么？流量会不会被窃听？操作有没有留痕？数据坏了、丢了、被删了，还能不能恢复？

安全模型

Mon, 01 Jan 0001 00:00:00 +0000

在讨论具体的安全特性之前，值得先回答两个更基本的问题：信任的根在哪里，以及 防线有几道。前者决定了你应该重点保护什么，后者决定了当某一道防线失守时，你还剩下什么。

身份认证

Mon, 01 Jan 0001 00:00:00 +0000

PostgreSQL 使用 pg_hba.conf 进行 基于主机的认证（Host-Based Authentication）：谁（用户）、从哪里（来源地址）、访问什么（数据库）、需要以何种方式证明身份（认证方法）。

访问控制

Mon, 01 Jan 0001 00:00:00 +0000

认证回答“你是谁”，授权回答“你能做什么”。

权限失控很少是因为缺少机制 —— PostgreSQL 的 GRANT 与 REVOKE 足够精细。问题在于缺少一套被默认执行的约定：业务上线时直接把账号设为属主；临时排障授予超级用户后没有及时回收；新表创建后遗漏授权，最终在生产环境触发权限错误。

加密通信

Mon, 01 Jan 0001 00:00:00 +0000

TLS 可以提供三类保护：传输加密、服务端身份验证 与 客户端身份验证。这三项能力需要分别配置：启用服务端 TLS 并不等于客户端已经验证了服务端身份，也不等于服务端要求客户端证书。

数据安全

Mon, 01 Jan 0001 00:00:00 +0000

网络边界、身份认证 和 权限控制 用于降低事件发生的概率；当硬件损坏、口令泄露或误操作已经发生时，还需要依靠数据层机制控制影响并完成恢复。

数据安全要回答四个问题：数据是完整的吗？丢了能恢复吗？被拿走了会泄密吗？发生了什么能查清吗？

合规实践

Mon, 01 Jan 0001 00:00:00 +0000

合规不是一个可以购买的产品，而是一种需要持续证明的状态。它由三部分组成：

配置：安全能力是否启用 —— 这部分由 Pigsty 直接提供；
流程：权限审批、变更管理、恢复演练等制度 —— 需要组织自行建立；
证据：能证明前两者持续有效的记录 —— Pigsty 的 配置清单、运行日志和 监控系统 可以提供其中一部分。

本页从上线前的加固清单开始，给出 Pigsty 安全能力与常见合规框架的映射关系。这些映射用于方案设计和差距分析，不构成等保测评结论、SOC 2 审计意见或法律建议。

快速上手 Pigsty 单机部署

Mon, 01 Jan 0001 00:00:00 +0000

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

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

摘要

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

Docker 部署

Mon, 01 Jan 0001 00:00:00 +0000

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

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

Mon, 01 Jan 0001 00:00:00 +0000

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

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

通过配置清单定制 Pigsty 部署

Mon, 01 Jan 0001 00:00:00 +0000

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

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

使用 Ansible 剧本完成部署

Mon, 01 Jan 0001 00:00:00 +0000

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

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

离线安装

Mon, 01 Jan 0001 00:00:00 +0000

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

概览

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

精简安装

Mon, 01 Jan 0001 00:00:00 +0000

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

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

精简安装适合以下场景

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

精简安装的局限性

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

概览

使用精简安装，您需要：

安全建议

Mon, 01 Jan 0001 00:00:00 +0000

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

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

密码

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

概念

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 是一个可移植、可扩展的开源 PostgreSQL 发行版，用于在本地环境中构建生产级数据库服务，方便进行声明式配置和自动化。它拥有庞大的生态系统，提供了一整套工具、脚本和最佳实践，让 PostgreSQL 真正达到企业级 RDS 的服务水准。

生产部署

Mon, 01 Jan 0001 00:00:00 +0000

本文是 Pigsty 生产环境多节点部署指南，部署单机版本 Demo/Dev 环境可以参考 快速上手 文档。

摘要

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

资源准备

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 运行在节点（物理机或虚拟机）之上，本文档介绍硬件相关的规划与准备。

节点

Pigsty 目前运行在 Linux 内核和 x86_64 / aarch64 架构的节点上。 "节点" 指的是 SSH 可访问 且提供裸 Linux 操作系统环境的资源。它可以是物理机、虚拟机或配备 systemd、sudo 和 sshd 的类似操作系统的容器。

架构规划

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 采用 模块化架构，您可以像搭积木一样组合出自己想要的部署方案，并用简单的 声明式配置 表达您的意图。

常见方案

这里有一些常见的组合模式供您参考，您可以根据自己的需求进行进一步的定制与调整：

方案	INFRA	ETCD	PGSQL	MINIO	说明
单机部署（`meta`）	1	1	1		单机部署默认配置，经典方案
单机部署（`slim`）		1	1		不要监控设施，只要数据库
基础设施（`infra`）	1				只要监控基础设施
单机部署（`rich`）	1	1	1	1	单机 + 对象存储 + 本地仓库/扩展

多节点方案	INFRA	ETCD	PGSQL	MINIO	说明
双节点（`dual`）	1	1	2		2节点半 HA，可容忍坏特定一个
三节点（`trio`）	3	3	3		标准3节点 HA，可容忍坏一个
四节点（`full`）	1	1	1+3		演示专用，1 INFRA/ETCD
生产部署（`simu`）	2	3	n	n	2个 INFRA，3个 ETCD
大规模生产（自定义）	3	5	n	n	3个 INFRA，5个 ETCD

使用什么样的架构规划方案，取决于您对数据库可靠性的要求，以及手头可用的资源。通常来说，严肃的生产环境部署至少需要 3 个节点以实现 高可用配置。如果您只有 2 个节点，则可以使用 半高可用配置。

管理机制

Mon, 01 Jan 0001 00:00:00 +0000

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

这个用户需要能够通过 ssh 访问到所有被管理节点，并且能够在这些节点上执行 sudo 命令。

要想将节点纳入 Pigsty 中管理，

沙箱环境

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供了一个标准的四节点 沙箱环境，用于学习、测试与功能演示。

沙箱使用固定的 IP 地址和预定义的身份标识符，便于复现各种演示用例。

环境描述

默认的沙箱环境由 4 个节点组成，默认使用配置文件 ha/full.yml。

Vagrant

Mon, 01 Jan 0001 00:00:00 +0000

Vagrant 是一个流行的本地虚拟化工具，可以按照声明式的方式创建本地虚拟机。

Pigsty 需要 Linux 环境运行，您可以使用 Vagrant 轻松在本地创建 Linux 虚拟机进行测试。

当前推荐并验证的基线为 Rocky Linux 9.8 / 10.2、Debian 12.15 / 13.6，以及 Ubuntu 22.04.5 / 24.04.4 / 26.04.0；Vagrant 的大版本别名会映射到对应的固定 Box 版本。

Terraform

Mon, 01 Jan 0001 00:00:00 +0000

Terraform 是一个流行的"基础设施即代码"工具，您可以使用它在公有云上一键创建虚拟机。

Pigsty 当前提供阿里云、AWS（全球与中国区）、Azure、GCP、腾讯云、Hetzner、Vultr、DigitalOcean 与 Linode 的 Terraform 示例模板；其中 aliyun-s3.tf 还会为 S3/pgBackRest 场景创建私有 OSS Bucket 与专用 RAM 读写凭据。

安全考量

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 默认配置面向受信内网中的开发、测试和演示。生产部署需要根据实际威胁模型完成凭据、网络、认证、证书、备份和审计配置。

安全机制及其边界见 安全与合规，可执行检查项见 合规实践。ha/safe 是加固配置示例，不替代逐项审查。

关于

Mon, 01 Jan 0001 00:00:00 +0000

参考

Mon, 01 Jan 0001 00:00:00 +0000

模块列表

Mon, 01 Jan 0001 00:00:00 +0000

正式模块

模块	类别	状态	文档入口	简介
`PGSQL`	核心	GA	`/docs/pgsql`	高可用 PostgreSQL 集群，内置备份、监控、SOP 与扩展生态。
`INFRA`	核心	GA	`/docs/infra`	本地软件仓库 + VictoriaMetrics/Logs/Traces + Grafana 等基础设施。
`NODE`	核心	GA	`/docs/node`	节点初始化与收敛：系统调优、管理员、HAProxy、Vector、Keepalived 等。
`ETCD`	核心	GA	`/docs/etcd`	PostgreSQL 高可用 DCS（服务发现、配置、选主元数据）。
`MINIO`	扩展	GA	`/docs/minio`	部署 Silo S3 兼容对象存储，可作为 PostgreSQL 备份仓库。
`REDIS`	扩展	GA	`/docs/redis`	Redis（默认）或 Valkey 的独立/哨兵/集群模式部署与监控。
`DOCKER`	扩展	GA	`/docs/docker`	Docker Daemon 及容器化应用运行基础能力。
`JUICE`	扩展	BETA	`/docs/juice`	JuiceFS 分布式文件系统，使用 PostgreSQL 作为元数据引擎。
`VIBE`	扩展	BETA	`/docs/vibe`	浏览器化开发环境，集成 Code-Server、JupyterLab、Node.js、Claude Code 与 Codex CLI。
`KAFKA`	扩展	BETA	`/docs/kafka`	Apache Kafka 4.x dynamic KRaft 集群部署、安全基线与监控。

核心模块

Pigsty 提供了四个基础功能模块，对于提供完整高可用的 PostgreSQL 服务非常重要：

文件结构

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty FHS

Pigsty 的主目录默认放置于 ~/pigsty，该目录下的文件结构如下所示：

- app/   {open=false}
  - 应用模板资源
- bin/   {open=false}
  - 管理与运维脚本
- files/
  - victoria/   {open=false}
    - 规则与运维脚本
  - grafana/   {open=false}
    - Grafana 仪表盘
  - postgres/   {open=false}
    - PostgreSQL 管理脚本
  - migration/   {open=false}
    - 数据迁移任务定义
  - pki/   {open=false}
    - 自签名 CA 与证书
- roles/   {open=false}
  - Ansible 角色实现
- templates/   {open=false}
  - Ansible 模板文件
- vagrant/   {open=false}
  - Vagrant 沙箱定义
- terraform/   {open=false}
  - Terraform 云资源模板
- configure
- ansible.cfg
- pigsty.yml
- *.yml

/infra 是 /data/infra 的运行时软链接，集中存放可观测性数据与生成的配置：

模板

Mon, 01 Jan 0001 00:00:00 +0000

您可以在 configure 时使用 -c 指定配置模板；参数值为相对 conf/ 的路径且不带 .yml 后缀。如果没有指定，将使用默认的 meta 模板。

分类	模板
单机模板	`meta`、`rich`、`fat`、`slim`、`infra`、`vibe`、`docker`
内核模板	`pgsql`、`pg19`、`mssql`、`polar`、`ivory`、`agens`、`pgedge`、`mysql`（OpenHalo）、`mongo`、`pgtde`、`oriole`
高可用模板	`ha/simu`、`ha/octo`、`ha/citus`、`ha/full`、`ha/safe`、`ha/trio`、`ha/dual`
应用模板	`supabase`、`app/odoo`、`app/dify`、`app/insforge`、`app/hindsight`、`app/electric`、`app/maybe`、`app/teable`、`app/mattermost`、`app/registry`、`app/immich`、`app/jumpserver`
其他模板	`demo/bare`、`demo/el`、`demo/debian`、`demo/demo`、`demo/kernel`、`demo/redis`、`demo/minio`、`demo/kafka`、`demo/mysql`（原生 MySQL 试点）、`demo/remote`、`demo/saas`、`demo/wool`、`build/oss`、`build/dev`

运维 SOP 索引

Mon, 01 Jan 0001 00:00:00 +0000

上手路线

顺序	要解决的问题	入口
1	Pigsty 由哪些模块组成？	积木式架构，PGSQL 架构，PGSQL 集群模型
2	怎么先跑起来？	快速上手，图形界面，快速上手 PostgreSQL
3	配置文件该怎么看？	声明式配置，配置清单，配置参数
4	生产部署要准备什么？	架构规划，资源准备，管理机制
5	怎么部署多节点集群？	生产部署，执行剧本，PGSQL 剧本
6	日常怎么管库？	PGSQL 日常管理，集群管理，用户管理，数据库管理
7	怎么验证可靠性？	PG 高可用，Patroni 管理，备份恢复，恢复操作

任务索引

任务	先看	操作入口
准备服务器、磁盘、网络、VIP	资源准备，架构规划，Linux 兼容性	生产部署
准备 SSH、Sudo、管理用户	管理机制	生产部署
本地或云上搭沙箱	沙箱环境	Vagrant，Terraform
单机体验	快速上手	`./configure -g`，`./deploy.yml`
多节点生产部署	部署，生产部署	`./deploy.yml`，`./pgsql.yml`
离线环境部署	离线安装	软件仓库管理
选择配置模板	配置模板，模板列表	`./configure -c <template>`
规划集群名、库名、用户名	PGSQL 集群模型	`pg_cluster`，`pg_databases`，`pg_users`
创建数据库集群	集群实例配置	集群管理，`./pgsql.yml -l <cluster>`
新增业务用户	用户/角色配置	用户管理，`./pgsql-user.yml -l <cluster>`
新增业务数据库	数据库配置	数据库管理，`./pgsql-db.yml -l <cluster>`
配置访问入口	服务/接入	`pg_services`，`pg_default_services`
修改 HBA	HBA 配置	HBA 管理
主从切换	Patroni 管理	`patronictl switchover`
HA 故障演练	PG 高可用，RPO，RTO	3坏2应急处理
配置 VIP	HA 服务接入	配置 PG VIP
配置备份策略	备份策略	备份管理命令
做 PITR 时间点恢复	时间点恢复	恢复操作
误删数据、表、库	误删处理	手工恢复
克隆恢复集群	克隆数据库集群	Fork 实例
使用 Silo 存备份	MINIO 模块	Silo 配置，备份仓库
查看监控告警	监控系统	PGSQL 监控，PGSQL 仪表盘
排查数据库故障	PGSQL 常见问题	故障排查，组件管理
扩容、缩容 PG 集群	集群实例配置	集群管理
升级 PostgreSQL	版本升级	内核版本
安装或启用扩展	扩展插件	扩展管理
迁移已有数据库	数据迁移	迁移剧本
做安全加固	安全考量	访问控制，CA 与证书
管理域名与 Web 入口	域名管理	Nginx 管理
维护基础设施	INFRA 管理预案	`infra.yml`，`infra-rm.yml`
维护 Etcd	ETCD 配置	ETCD 管理，ETCD FAQ
部署应用模板	应用	Docker 模块，`./app.yml`

准备与部署

生产部署先看 架构规划 和 资源准备。这两篇解决节点数量、磁盘、文件系统、网络、VIP、域名、软件源这些问题。

任务教程

Sat, 11 Jan 2025 00:00:00 +0000

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

INFRA 模块中包含了哪些组件？

严格按当前源码区分，infra 角色直接管理以下组件：

Nginx：暴露 Grafana、VictoriaMetrics（VMUI）、Alertmanager 等 WebUI，并托管本地 YUM/APT 仓库。
DNSMasq：提供 DNS 注册与解析。
VictoriaMetrics 套件：VictoriaMetrics、VMAlert、VictoriaLogs 与 VictoriaTraces。
Alertmanager、Blackbox Exporter 与 Grafana：告警分发、黑盒探测与可视化。

infra.yml 还会串联 CA、软件仓库、NODE、HAProxy 与节点监控角色，因此会在 Infra 节点上配置自签名 CA、Chronyd、Node Exporter 和 Vector 等配套能力。ETCD、PostgreSQL 与 Docker 是独立模块，不由 infra.yml 部署；应分别运行 etcd.yml、pgsql.yml 与 docker.yml。

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

etcd集群起什么作用？

etcd 是一个分布式的、可靠的键-值存储，用于存放系统中最为关键的数据，Pigsty 使用 etcd 作为 Patroni 的 DCS（分布式配置存储）服务，用于存储 PostgreSQL 集群的高可用状态信息。

PIGSTY on Pigsty v5.0

Pigsty v5.0 文档

亮点特性

价值主张

总览

历史沿革

历史起源

活动新闻

最近新闻

上手

发展规划

版本发布策略

加入社区

GitHub

隐私政策

Pigsty软件

开源协议

协议摘要

Pigsty 项目主体

赞助我们

赞助我们

行业案例

订阅服务

常见问题

Pigsty 是什么，不是什么？

积木式架构

模块

集群模型图

成本对比

总体概览

RDS成本参考

开源影响力

中国 PostgreSQL 生态项目影响力

PostgreSQL 发行版影响力指标

声明式配置 —— 基础设施即代码（IaC）

PG 高可用

概览

RPO 利弊权衡

部署

RTO 利弊权衡

配置清单

配置文件

配置向导

配置参数

参数列表

配置模板

元数据库

概览

安全合规

安全模型

身份认证

访问控制

加密通信

数据安全

合规实践

快速上手 Pigsty 单机部署

摘要

Docker 部署

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

通过配置清单定制 Pigsty 部署

使用 Ansible 剧本完成部署

离线安装

概览

精简安装

概览

安全建议

密码

概念

生产部署

摘要

资源准备

节点

架构规划

常见方案

管理机制

沙箱环境

环境描述

Vagrant

Terraform

安全考量