这是本节的多页打印视图。
点击此处打印 .
返回本页常规视图 .
Pigsty 中文文档 v4.3 “P ostgreSQL I n G reat STY le”: P ostgres, I nfras, G raphics, S ervice, T oolbox, it’s all Y ours.
—— 开箱即用、本地优先的 PostgreSQL 发行版,开源 RDS 替代
仓库 | 演示 | 博客 | 论坛 | 微信 | EN Docs
快速上手 最新版本的 Pigsty:curl -fsSL https://repo.pigsty.cc/get | bash -s v4.3.0
关于 :功能特性 | 历史沿革 | 活动新闻 | 加入社区 | 隐私政策 | 开源协议 | 赞助我们 | 服务订阅
概念 :系统架构 | 集群模型 | 监控系统 | IaC | HA | PITR | 服务接入 | 安全加固
上手 :单机安装 | 离线安装 | 资源准备 | 声明配置 | 执行剧本 | 安全考量 | 常见问题
部署 :架构规划 | 资源准备 | 生产部署 | 沙箱环境 | Vagrant | Terraform
参考 :操作系统 | 扩展列表 | 文件结构 | 同类产品 | 成本参考 | 应用模板 | 配置模板
模块 :PGSQL | INFRA | NODE | ETCD | MINIO | REDIS | FERRET | DOCKER | PILOT
1 - PIGSTY 2 - 关于 了解 Pigsty 项目本身的方方面面:功能特性、历史发展,开源协议,隐私政策,社区活动与新闻。
2.1 - 亮点特性 Pigsty 的价值主张与亮点功能特性。
“P ostgreSQL I n G reat STY le”: P ostgres, I nfras, G raphics, S ervice, T oolbox, it’s all Y ours.
—— 开箱即用、本地优先的 PostgreSQL 发行版,开源 RDS 替代
价值主张
总览 Pigsty 是一个更好的本地开源 RDS for PostgreSQL 替代:
开箱即用的RDS :从内核到 RDS 发行版,在 EL/Debian/Ubuntu 下提供 14-18 版本的生产级 PG 数据库服务。丰富的扩展插件 :提供无可比拟的 510 扩展,提供开箱即用的分布式的时序地理空间图文向量多模态数据库能力。灵活的模块架构 :灵活组合,自由扩展:Redis/Etcd/MinIO/Mongo;可独立使用,监控现有 RDS/主机/数据库。惊艳的观测能力 :基于现代可观测性技术栈 Prometheus/Grafana,提供令人惊艳,无可比拟的数据库观测能力。验证过的可靠性 :故障自愈的高可用架构:硬件故障自动切换,流量无缝衔接。并提供自动配置的 PITR 兜底删库!简单易用可维护 :声明式 API,GitOps 就位,傻瓜式操作,Database/Infra-as-Code 以及管理 SOP 封装管理复杂度!扎实的安全实践 :加密备份一应俱全,自带基础 ACL 最佳实践。只要硬件与密钥安全,您无需操心数据库的安全性!广泛的应用场景 :低代码数据应用开发,或使用预置的 Docker Compose 模板,一键拉起使用 PostgreSQL 的海量软件!开源的自由软件 :以云数据库1/10不到的成本拥有与更好的数据库服务!帮您真正“拥有”自己的数据,实现自主可控!PostgreSQL 整合了生态中的工具与最佳实践:
开箱即用的 PostgreSQL 发行版,深度整合地理、时序、分布式、图、向量、搜索、AI 等 510 个 扩展插件 ! 运行于裸操作系统之上,无需容器支持,支持主流操作系统: EL 8/9/10, Ubuntu 22.04/24.04/26.04 以及 Debian 12/13。 基于 patroni , haproxy , 与 etcd ,打造故障自愈的高可用架构:硬件故障自动切换,流量无缝衔接。 基于 pgBackRest 与可选的 MinIO 集群提供开箱即用的 PITR 时间点恢复,为软件缺陷与人为删库兜底。 基于 Ansible 提供声明式的 API 对复杂度进行抽象,以 Database-as-Code 的方式极大简化了日常运维管理操作。 Pigsty 用途广泛,可用作完整应用运行时,开发演示数据/可视化应用,大量使用 PG 的软件可用 Docker 模板一键拉起。 提供基于 Vagrant 的本地开发测试沙箱环境,与基于 Terraform 的云端自动部署方案,开发测试生产保持环境一致。 部署并监控专用的 Redis (主从,哨兵,集群),MinIO,Etcd,Haproxy,MongoDB (FerretDB ) 集群 开箱即用的RDS 让您立刻在本地拥有生产级的 PostgreSQL 数据库服务!
PostgreSQL 是一个足够完美的数据库内核,但它需要更多工具与系统的配合才能成为一个足够好的数据库服务(RDS),Pigsty 帮助 PostgreSQL 完成这一步飞跃。
Pigsty 为您解决使用 PostgreSQL 中会遇到的各种难题:内核扩展安装,连接池,负载均衡,服务接入,高可用 / 自动故障切换,日志收集,指标监控,告警,备份恢复,PITR,访问控制,参数调优,安全加密,证书签发,NTP,DNS,参数调优,配置管理,CMDB,管理预案… 您无需再为这些细节烦心劳神!
Pigsty 支持 PostgreSQL 14 ~ 18 主干内核与其他兼容分支,可运行于 EL / Debian / Ubuntu 以及 兼容操作系统发行版 上,在 x86_64 与 ARM64 芯片架构上可用,且无需容器支持。
除了数据库内核与大量开箱即用的扩展插件以外,Pigsty 还提供了数据库服务所需的完整基础设施与运行时,以及本地沙箱 / 生产环境 / 云 IaaS 自动部署方案。
Pigsty 可以一键从裸机开始拉起整套环境,触达软件交付的最后一公里。普通研发运维均可快速上手并兼职进行数据库管理,无需数据库专家即可自建企业级 RDS 服务!
丰富的扩展插件 超融合多模态,一切皆用 PostgreSQL,一个 PG 替换所有数据库!
PostgreSQL 的灵魂在于其丰富的 扩展生态 ,而 Pigsty 独一无二地深度整合了 PostgreSQL 生态中的 510 扩展 ,为您提供开箱即用的超融合多模态数据库!
插件间可以产生 协同效应 ,产生 1+1 远大于 2 的效果。
您可以使用 PostGIS 处理地理空间数据,使用 TimescaleDB 分析时序/事件流数据,并使用 Citus 将其原地升级为分布式地理时空数据库;
您可以用 PGVector 存储并搜索 AI 嵌入,用 ParadeDB 实现 ES 级全文检索,并同时使用精准的 SQL,全文检索,与模糊向量进行混合检索。
您还可以通过 pg_duckdb ,pg_mooncake 等分析扩展,实现专用 OLAP 数据库/数据湖仓的分析表现。
使用 PostgreSQL 单一组件替代 MySQL,Kafka,ElasticSearch,MongoDB,以及大数据分析技术栈已经成为一种最佳实践 —— 单一数据库选型能够显著降低系统复杂度,极大提高研发效能与敏捷性,实现程度惊人的软硬件,研发/运维人力降本增效。
灵活的模块架构 灵活组合,自由扩展,多数据库支持,监控现有 RDS/主机/数据库
Pigsty 中的组件被抽象可独立部署的 模块 ,并可自由组合以应对多变的需求场景。INFRA 模块带有完整的现代监控技术栈,而 NODE 模块则将节点调谐至指定状态并纳管。
在多个节点上安装 PGSQL 模块会自动组建出基于主从复制的高可用数据库集群,而同样的 ETCD 模块则为数据库高可用提供共识与元数据存储。
除了上述四个 核心模块 之外,Pigsty 还提供一系列选装功能模块:MINIO 模块可以提供本地对象存储能力,并作为集中式数据库备份仓库。
REDIS 模块能以独立主从,哨兵,原生集群的方式为数据库提供辅助。DOCKER 模块可用于拉起无状态的应用软件。
此外,Pigsty 还提供 PG 兼容 / 衍生内核的支持,您可以使用 Babelfish 提供 MS SQL Server 兼容性,使用 IvorySQL 提供 Oracle 兼容性,
使用 OpenHaloDB 提供 MySQL 兼容性,使用 OrioleDB 提供极致的 OLTP 性能。
不仅如此,你还可以使用 FerretDB 提供 MongoDB 兼容性,使用 Supabase 提供 Firebase 兼容,并使用 PolarDB 满足国产化合规要求。
更多专业版/试点模块将不断引入 Pigsty,如 GPSQL ,KAFKA ,DUCKDB ,VICTORIA ,TIGERBEETLE ,KUBERNETES ,CONSUL ,JUPYTER ,GREENPLUM ,CLOUDBERRY ,MYSQL , …
惊艳的观测能力 使用现代开源可观测性技术栈,提供无与伦比的监控最佳实践!
Pigsty 提供了基于开源的 Grafana / Prometheus 现代可观测性技术栈做 监控 的最佳实践:,Grafana 负责可视化呈现,VictoriaMetrics 用于收集监控指标,VictoriaLogs 用于日志收集与查询,Alertmanager 用于告警通知。Blackbox Exporter 负责检查服务可用性。整套系统同样被设计为一键拉起,开箱即用的 INFRA 模块。
Pigsty 所管理的任何组件都会被自动纳入监控之中,包括主机节点,负载均衡 HAProxy,数据库 Postgres,连接池 Pgbouncer,元数据库 ETCD,KV 缓存 Redis,对象存储 MinIO,……,以及整套监控基础设施本身。大量的 Grafana 监控面板与预置告警规则会让你的系统观测能力有质的提升,当然,这套系统也可以被复用于您的应用监控基础设施,或者监控已有的数据库实例或 RDS。
无论是故障分析还是慢查询优化、无论是水位评估还是资源规划,Pigsty 为您提供全面的数据支撑,真正做到数据驱动。在 Pigsty 中,超过三千类监控指标被用于描述整个系统的方方面面,并被进一步加工、聚合、处理、分析、提炼并以符合直觉的可视化模式呈现在您的面前。从全局大盘总览,到某个数据库实例中单个对象(表,索引,函数)的增删改查详情都能一览无余。您可以随意上卷下钻横向跳转,浏览系统现状与历史趋势,并预测未来的演变。
此外,Pigsty 的监控系统模块部分还可以 独立使用 ——用它来监控现有的主机节点与数据库实例,或者是云上的 RDS 服务。只需要一个连接串一行命令,您就可以获得极致的 PostgreSQL 可观测性体验。
访问 截图画廊 与 在线演示 获取更多详情。
久经考验的可靠性 开箱即用的高可用与时间点恢复能力,确保你的数据库坚如磐石!
对于软件缺陷或人为误操作造成的删表删库,Pigsty 提供了开箱即用的 PITR 时间点恢复能力,无需额外配置即默认启用。只要存储空间管够,基于 pgBackRest 的基础备份与 WAL 归档让您拥有快速回到过去任意时间点的能力。您可以使用本地目录/磁盘,亦或专用的 MinIO 集群或 S3 对象存储服务保留更长的回溯期限,丰俭由人。
更重要的是,Pigsty 让高可用与故障自愈成为 PostgreSQL 集群的标配,基于 patroni, etcd, 与 haproxy 打造的 高可用故障自愈架构 ,让您在面对硬件故障时游刃有余:主库故障自动切换的 RTO < 45s(可配置),一致性优先模式下确保数据零损失 RPO = 0。只要集群中有任意实例存活,集群就可以对外提供完整的服务,而客户端只要连接至集群中的任意节点,即可获得完整的服务。
Pigsty 内置了 HAProxy 负载均衡器用于自动流量切换,提供 DNS/VIP/LVS 等多种接入方式供客户端选用。故障切换与主动切换对业务侧除零星闪断外几乎无感知,应用不需要修改连接串重启。极小的维护窗口需求带来了极大的灵活便利:您完全可以在无需应用配合的情况下滚动维护升级整个集群。硬件故障可以等到第二天再抽空善后处置的特性,让研发,运维与 DBA 都能安心睡个好觉。
许多大型组织与核心机构已经在生产环境中长时间使用 Pigsty,最大的部署有 25K CPU 核心与 200+ PostgreSQL 超大规格实例;在这一部署案例中,六七年内经历了数十次硬件故障与各类事故,DBA 换了几茬,但依然可以保持比 99.999% 更高的可用性战绩。
简单易用可维护 Infra as Code, 数据库即代码,声明式的 API 将数据库管理的复杂度来封装。
Pigsty 使用声明式的接口对外提供服务,将系统的可控制性拔高到一个全新水平:用户通过配置清单告诉 Pigsty “我想要什么样的数据库集群”,而不用去操心到底需要怎样去做。从效果上讲,这类似于 K8S 中的 CRD 与 Operator,但 Pigsty 可用于任何节点上的数据库与基础设施:不论是容器,虚拟机,还是物理机。
无论是创建/销毁集群,添加/移除从库,还是新增数据库/用户/服务/扩展/黑白名单规则,您只需要修改配置清单并运行 Pigsty 提供的幂等剧本,而 Pigsty 负责将系统调整到您期望的状态。
用户无需操心配置的细节,Pigsty 将自动根据机器的硬件配置进行调优,您只需要关心诸如集群叫什么名字,有几个实例放在哪几台机器上,使用什么配置模版:事务/分析/核心/微型,这些基础信息,研发也可以自助服务。但如果您愿意跳入兔子洞中,Pigsty 也提供了丰富且精细的控制参数,满足最龟毛 DBA 的苛刻定制需求。
除此之外,Pigsty 本身的安装部署也是一键傻瓜式的,所有依赖被预先打包,在安装时可以无需互联网访问。而安装所需的机器资源,也可以通过 Vagrant 或 Terraform 模板自动获取,让您在十几分钟内就可以从零在本地笔记本或云端虚拟机上拉起一套完整的 Pigsty 部署。本地沙箱环境可以跑在1核2G 的微型虚拟机中,提供与生产环境完全一致的功能模拟,可以用于开发、测试、演示与学习。
扎实的安全实践 加密备份一应俱全,只要硬件与密钥安全,您无需操心数据库的安全性。
Pigsty 针对高标准,严要求的企业级场景设计 ,采用业界领先的 安全最佳实践 保护您的数据安全(机密性/完整性/可用性),默认配置下的安全性便足以满足绝大多数场景下的合规要求。
Pigsty 会创建自签名的 CA (或使用您提供的 CA)签发证书,加密网络通信。需要保护的敏感管理页面与 API 端点都受到密码保护。
数据库备份使用 AES 算法加密,数据库密码使用 scram-sha-256 算法加密,并提供插件强制执行密码强度策略。
Pigsty 提供了一套开箱即用,简单易用,便于扩展的 ACL 模型,提供读/写/管理/ETL 的权限区分,并带有遵循最小权限原则的 HBA 规则集,通过多重防护确保系统机密性。
Pigsty 默认启用数据库校验和避免静默数据腐坏,通过从库副本提供坏块兜底。提供 CRIT 数据零丢失配置模板,使用 watchdog 确保为高可用 Fencing 兜底。
您可以通过 audit 插件审计数据库操作,系统与数据库日志全部收集备查,以满足合规要求。
Pigsty 正确配置 SELinux 与防火墙配置,并遵循最小权限原则设计操作系统用户组与文件权限,确保系统安全基线符合合规要求。
而且在 Etcd,MinIO 等附属可选组件上的安全上也毫不妥协,etcd 与 minio 均使用 RBAC 模型与 TLS 加密通信,确保系统整体安全性。
合理配置的系统通过等保三级/SOC2 毫无问题,只要您遵循安全性最佳实践,内网部署并合理配置安全组与防火墙,数据库安全性将不再是您的痛点。
广泛的应用场景 使用预置的 Docker 模板,一键拉起使用 PostgreSQL 的海量软件!
在各类数据密集型应用中,数据库往往是最为棘手的部分。例如 Gitlab 企业版与社区版的核心区别就是底层 PostgreSQL 数据库的监控与高可用,如果您已经有了足够好的本地 PG RDS,完全可以拒绝为软件自带的土法手造数据库组件买单。
Pigsty 提供了 Docker 模块 与大量开箱即用的 Compose 模板 。您可以使用 Pigsty 管理的高可用 PostgreSQL (以及 Redis 与 MinIO)作为后端存储,以无状态的模式一键拉起这些软件:
Gitlab、Gitea、Wiki.js、NocoDB、Odoo、Jira、Confluence、Habour、Mastodon、Discourse、KeyCloak、MatterMost 等等。
如果您的应用需要一个靠谱的 PostgreSQL 数据库, Pigsty 也许是最简单的获取方案。
Pigsty 也提供了与 PostgreSQL 紧密联系的应用开发工具集:PGAdmin4、PGWeb、ByteBase、PostgREST、Kong、以及 EdgeDB、FerretDB、Supabase 这些使用 PostgreSQL 作为存储的"上层数据库"。
更奇妙的是,您完全可以基于 Pigsty 内置了的 Grafana 与 Postgres,以低代码的方式快速搭建起一个交互式的数据应用来,甚至还可以使用 Pigsty 内置的 ECharts 面板创造更有表现力的交互可视化作品。
Pigsty 为您的 AI 应用提供了一个功能强大的运行时,您的 Agent 可以在这个环境中利用 PostgreSQL 与可观测性世界的强大能力,快速构建起一个数据驱动的智能体。
开源的自由软件 Pigsty 是基于 Apache-2.0 开源的自由软件,由热爱 PostgreSQL 的社区成员用热情浇灌
Pigsty 是完全 开源免费 的自由软件,它允许您在缺乏数据库专家的情况下,用几乎接近纯硬件的成本来运行企业级的 PostgreSQL 数据库服务。
作为对比,数据库厂商的“企业级数据库服务”与公有云厂商提供的 RDS 会收取底层硬件资源几倍到十几倍不等的 溢价 作为 “服务费”。
很多用户选择上云,正是因为自己搞不定数据库;很多用户使用 RDS,是因为别无他选。
我们将打破云厂商的垄断,为用户提供一个云中立的,更好的 RDS 开源替代:
Pigsty 紧跟 PostgreSQL 上游主干,不会有供应商锁定,不会有恼人的 “授权费”,不会有节点数量限制,不会收集您的任何数据。您的所有的核心资产 —— 数据,都能"自主可控",掌握在自己手中。
Pigsty 本身旨在用数据库自动驾驶软件,替代大量无趣的人肉数据库运维工作,但再好的软件也没法解决所有的问题。
总会有一些的冷门低频疑难杂症需要专家介入处理。这也是为什么我们也提供专业的 订阅服务 ,来为有需要的企业级用户使用 PostgreSQL 提供兜底。
几万块的订阅咨询费不到顶尖 DBA 每年工资的几十分之一,让您彻底免除后顾之忧,把成本真正花在刀刃上。对于社区用户,我们亦 用爱发电 ,提供免费的支持与日常答疑。
2.2 - 历史沿革 Pigsty 项目的由来与动机,过去发展的历史,未来的目标与愿景。
历史起源 Pigsty 项目始于 2018 ~ 2019 年,起源于 探探 。
探探是一个互联网交友 App —— 中国的 Tinder,现已被陌陌收购。
探探这家公司是一个北欧风格的创业公司,有着一个瑞典工程师初创团队。
探探在技术上极有品味,使用 PostgreSQL 与 Go 作为核心技术栈。
探探整个系统架构参照 Instagram,一切围绕 PostgreSQL 数据库设计。
直到几百万日活,几百万 TPS,几百 TB 数据的量级下,数据组件 只用了 PostgreSQL 。
几乎所有的业务逻辑都使用 PG 存储过程实现 —— 甚至包括 100ms 的推荐算法!称得上当时中国最复杂的 PostgreSQL 规模场景用例。
探探这种深度使用 PostgreSQL 特性的非典型研发模式,对工程师与 DBA 的水平提出了极高的要求。
而 Pigsty,就是我们用这种真实世界的大规模,高标准数据库集群场景打磨出的开源项目 ——
沉淀着我们作为顶尖 PostgreSQL 专家的经验与最佳实践。
发展过程 在最开始,Pigsty 并没有现在这样的愿景、目标与版图。而是为了提供一个供我们自己使用的 PostgreSQL 监控系统。
我们调研了市面上所有的方案,开源的、商业的、云的,datadog, pgwatch,……,没有一个能满足我们对于可观测性的需求。
因此我决定自己动手,基于 Grafana 与 Prometheus 自己动手打造一个,这就是 Pigsty 的前身与雏形。
Pigsty 作为监控系统的效果相当惊艳,帮助我们解决了无数管理问题。
随后,研发人员希望在本地的开发机上也有这样的监控系统,于是我们使用 Ansible 编写了置备剧本,将这套系统从一次性建设任务转变为了可重复使用,可复制的软件。
新版本允许用户使用 Vagrant 和 Terraform,用 Infra as Code 的方式快速拉起本地 DevBox 开发机,或生产环境服务器,并自动完成 PostgreSQL 与监控系统的部署。
接下来,我们重新设计了生产环境的 PostgreSQL 架构,引入了 Patroni 与 pgBackRest 解决了数据库的 高可用 与 时间点恢复 问题。
开发了基于逻辑复制的不停机 迁移 方案,通过蓝绿部署将生产环境两百套数据库集群滚动升级至最新大版本。并将这些能力引入 Pigsty 中。
Pigsty 是我们做给自己使用的软件,“Eat dog food”最大的好处就是,我们自己既是开发者也更是用户 ——
我们自己作为甲方用户,非常了解自己需要什么,也不会在自己的需求上偷懒,更不用担心自己的工作全自动化后被开。
我们解决了一个又一个的问题,并将解决方案沉淀到 Pigsty 里。Pigsty 的定位,也从一个监控系统,逐渐发展成为一个开箱即用的 PostgreSQL 数据库发行版。
随即我们决定将 Pigsty 开源,并开始了一系列的技术分享与宣传,也开始有各行各业的外部用户使用起 Pigsty 并提出反馈意见。
全职创业 在 2022 年,Pigsty 项目获得了由陆奇博士发起的奇绩创坛的种子轮投资,我得以全职出来做这件事情。
作为一个开源项目,Pigsty 的发展相当不赖,在全职创业这几年里,Pigsty 在 Github 上的 Star 数从几百增长到了 4600+;上了 HN 头条推荐,增长开始滚起雪球。
2025 年 11 月,Pigsty 荣获 PostgreSQL 生态大会颁发的 Magneto Award 。2026 年,Pigsty 子项目 PGEXT.CLOUD 投中 PGCon.Dev 2026 演讲。
Pigsty 成为第一个站上这个 PostgreSQL 核心生态大会舞台上的中国开源项目。
从前 Pigsty 只能跑在 CentOS 7 上,现今已经基本覆盖了所有主流 Linux 发行版 (EL, Debian, Ubuntu),支持 16 个操作系统平台。
支持的 PG 大版本覆盖 14 - 18,维护、收录并整合了 PG 生态中的 500+ 扩展插件。
其中,我本人维护了这里超过一半(360+)的扩展插件,并提供开箱即用的 RPM/DEB 包。
算上 Pigsty 本身,“基于开源,回馈开源”,为 PG 生态做一些贡献。
Pigsty 的定位,也在不断发展的过程中,从一个 PostgreSQL 数据库发行版,进一步扩展到了 开源云数据库 。它真正对标的是云厂商的整个云数据库品牌。
公有云的反叛者 AWS、Azure、GCP、Aliyun 等公有云厂商为初创企业提供了许多便利,但它们是闭源的,并迫使用户以高额费用租赁基础资源。
我们认为,优秀的数据库服务,应该和优秀的数据库内核一样,普及到每一个用户手中,而不是必须花费高昂的代价去向赛博领主租赁。
云计算的敏捷与弹性价值主张很好,但它应该是自由、开源、普惠、本地优先的 ——
我们认为云计算宇宙中需要一个代表开源价值观的解决方案,在不牺牲云带来好处的前提下,将基础设施的控制权交还给用户。
因此,我们也在引领着一场 下云的运动与战役 ,作为公有云的反叛者,来重塑这个行业的价值观。
我们的愿景 我希望,未来的世界人人都有自由使用优秀服务的事实权利,而不是只能被圈养在几个赛博领主公有云巨头厂商的地盘上当赛博佃户甚至赛博农奴。
这正是 Pigsty 要做的事 —— 一个更好的,开源免费的 RDS 替代 。让用户能够在任何地方(包括云服务器)上,一键拉起比云 RDS 更好的数据库服务。
Pigsty 是对 PostgreSQL 的彻底补完,更是对云数据库的辛辣嘲讽 。
它本意是“猪圈”,但也是 P ostgres I n G reat STY le 的缩写,即“全盛状态下的 PostgreSQL ”。
Pigsty 本身是一款完全开源免费的软件,能够让您在没有数据库专家的情况下,自建水平达到 90 分的 PostgreSQL 数据库服务。
我们靠提供 精品咨询服务 来维持运营,为您搭建从 90 分到 100 分的体系,并提供质保、答疑、与兜底。
建设良好的系统也许跑个几年都不会遇到需要 “兜底” 的问题,但数据库的问题一但出现就不是小问题。
很多时候,专家的经验更是能够一言化腐朽为神奇,而我们为有需求的客户提供这样的精品咨询
—— 我们认为这是一种更加公正、合理、可持续的模式。
关于团队 我是冯若航,Pigsty 的作者,Pigsty 的所有代码几乎都由我 一人开发 。
软件领域依然存在个人英雄主义,独一无二的个体才能够创造出独一无二的作品 —— 我希望 Pigsty 成为这样的作品。
如果您对我感兴趣,这里是我的个人主页:https://vonng.com/
《墨天轮风云人物访谈录 —— 冯若航 》
《90后,辞职创业,说要卷死云数据库 》
2.3 - 活动新闻 与 Pigsty 和 PostgreSQL 相关的活动事件与新闻,以及最新活动预告!
最近新闻 2026-02-28 : Pigsty v4.2 正式发布!七款内核批量更新
2026-02-12 : Pigsty v4.1 正式发布!第一批支持 PostgreSQL 18.2 的发行版
2026-02-04 :Extension for Everyone 主题入选 PGCon.Dev 2026 演讲!
2026-02-03 : Pigsty v4.0 正式发布! 迈入 Agent 时代!
2026-01-30 : PIG v1.0 正式发布! 与 PGEXT.CLOUD 扩展目录同步上线
2025-12-02 : Pigsty v3.7.0 发布! PG18 成为默认版本,437 扩展,EL10/Debian13 支持
2025-11-29 :Pigsty 荣获 PostgreSQL Magneto Award !
第八届 PostgreSQL 生态大会(杭州) 演讲主题:“A World-Grade Postgres Meta Distribution”、AI 数据库考量、PostgreSQL 交付最佳实践 2025-08-15 : Pigsty v3.6.1 发布! 例行 PG 小版本更新,PGDG 中国区域镜像
2025-08-04 : Pigsty v3.6.0 发布! PostgreSQL 元发行版
2025-06-16 : Pigsty v3.5.0 发布! PG18 Beta 支持,421 扩展,监控升级,代码重构
2025-04-21 : Pigsty v3.4 发布! MySQL 兼容性
2025-03-07 : Pigsty v3.3.0 发布! 404 扩展
2025-01 :Pigsty v3.2.x 发布系列(v3.2.0 ~ v3.2.2)
390 扩展,Omnigres,Mooncake,Citus13/PG17,扩展管理 CLI,Grafana 强化,ARM64 扩展补完 发布说明:v3.2.2 / v3.2.1 / v3.2.0 PostgreSQL 包管理器 pig 发布!
2024-11 : Pigsty v3.1.0 发布! PG 17 上位,Supabase 自建,ARM/Ubuntu24 支持
2024-08 ~ 2024-10 :Pigsty v3.0.x 发布系列(v3.0.0 ~ v3.0.4)
2024-08 :Pigsty 补充软件仓库,提供 254 个额外的开箱即用的二进制 RPM/DEB 扩展!
PGCon.Dev 2024 参会记!
2024-05 : Pigsty v2.7 发布!
2024-02 : Pigsty v2.6 发布!
版本发布 Pigsty 发布注记
版本 发布时间 摘要 地址 v4.3.0 2026-04-19 占位稿:4 月 Infra / RPM 编号整理,Grafana 13,Cloudberry 2.1 待发布 v4.2.2 2026-03-23 Insforge 应用自建,Infra 包批量更新,新增 pdu,pgdog v4.2.2 v4.2.1 2026-03-06 弃用 PG 13 支持,464 扩展 v4.2.1 v4.2.0 2026-02-28 例行小版本更新,六大 PG 内核集中更新 v4.2.0 v4.1.0 2026-02-12 操作系统与数据库小版本更新,Agent Native CLI,批量 Bug 修复 v4.1.0 v4.0.0 2026-01-28 Victoria 可观测性,安全加固,JUICE/VIBE 模块,Apache-2.0 v4.0.0 v3.7.0 2025-12-02 PG18 成为默认,437 扩展,EL10/Debian13,PGEXT.CLOUD v3.7.0 v3.6.1 2025-08-15 例行 PG 小版本更新,PGDG 中国区域镜像 v3.6.1 v3.6.0 2025-07-30 pgactive,MinIO/ETCD 改进,安装简化,配置梳理 v3.6.0 v3.5.0 2025-06-16 PG18 Beta,421 扩展,监控升级,代码重构 v3.5.0 v3.4.1 2025-04-05 OpenHalo,OrioleDB,MySQL 兼容性,pgAdmin 改进 v3.4.1 v3.4.0 2025-03-30 备份增强,自动 Certbot 证书,Ivory 跨平台,AGE 扩展 v3.4.0 v3.3.0 2025-02-24 404扩展,Odoo/Dify/Supabase 应用模板,DocumentDB 支持 v3.3.0 v3.2.2 2025-01-23 390扩展,Omnigres 支持,Mooncake,Citus13 与 PG17 支持 v3.2.2 v3.2.1 2025-01-12 350扩展,Ivory4,Citus 强化,Odoo 模板 v3.2.1 v3.2.0 2024-12-24 扩展管理 CLI,Grafana 强化,ARM64 扩展补完 v3.2.0 v3.1.0 2024-11-22 PG 17 作为默认大版本,配置简化,Ubuntu 24 与 ARM 支持,MinIO 改进 v3.1.0 v3.0.4 2024-10-30 PG 17 扩展,OLAP 全家桶,pg_duckdb v3.0.4 v3.0.3 2024-09-27 PostgreSQL 17,Etcd 运维优化,IvorySQL 3.4,PostGIS 3.5 v3.0.3 v3.0.2 2024-09-07 精简安装模式,PolarDB 15支持,监控视图更新 v3.0.2 v3.0.1 2024-08-31 例行问题修复,Patroni 4支持,Oracle 兼容性改进 v3.0.1 v3.0.0 2024-08-25 333个扩展插件,可插拔内核,MSSQL,Oracle,PolarDB 兼容性 v3.0.0 v2.7.0 2024-05-20 扩展大爆炸,新增20+强力扩展插件,与多款 Docker 应用 v2.7.0 v2.6.0 2024-02-28 PG 16 作为默认大版本,引入 ParadeDB 与 DuckDB 等扩展 v2.6.0 v2.5.1 2023-12-01 例行小版本更新,PG16 重要扩展支持 v2.5.1 v2.5.0 2023-09-24 Ubuntu/Debian 支持:bullseye, bookworm, jammy, focal v2.5.0 v2.4.1 2023-09-24 Supabase/PostgresML 支持与各种新扩展:graphql, jwt, pg_net, vault v2.4.1 v2.4.0 2023-09-14 PG16,监控 RDS,服务咨询支持,新扩展:中文分词全文检索/图/HTTP/嵌入等 v2.4.0 v2.3.1 2023-09-01 带 HNSW 的 PGVector,PG 16 RC1, 文档翻新,中文文档,例行问题修复 v2.3.1 v2.3.0 2023-08-20 主机 VIP, ferretdb, nocodb, MySQL 存根,CVE 修复 v2.3.0 v2.2.0 2023-08-04 仪表盘 & 置备重做,UOS 兼容性 v2.2.0 v2.1.0 2023-06-10 支持 PostgreSQL 12 ~ 16beta v2.1.0 v2.0.2 2023-03-31 新增 pgvector 支持,修复 MinIO CVE v2.0.2 v2.0.1 2023-03-21 v2 错误修复,安全增强,升级 Grafana 版本 v2.0.1 v2.0.0 2023-02-28 架构大升级,兼容性、安全性、可维护性显著增强 v2.0.0 v1.5.1 2022-06-18 Grafana 安全性修复 v1.5.1 v1.5.0 2022-05-31 Docker 应用程序支持 v1.5.0 v1.4.1 2022-04-20 错误修复 & 英文文档完整翻译 v1.4.1 v1.4.0 2022-03-31 MatrixDB 支持,分离 INFRA/NODES/PGSQL/REDIS 模块 v1.4.0 v1.3.0 2021-11-30 PGCAT 重整 & PGSQL 增强 & Redis Beta 支持 v1.3.0 v1.2.0 2021-11-03 默认 PGSQL 版本升级至 14 v1.2.0 v1.1.0 2021-10-12 主页,JupyterLab, PGWEB, Pev2 & pgbadger v1.1.0 v1.0.0 2021-07-26 v1 正式版,监控系统重整 v1.0.0 v0.9.0 2021-04-04 Pigsty 图形界面,命令行界面,日志集成 v0.9.0 v0.8.0 2021-03-28 服务置备,定制对外暴露的数据库服务 v0.8.0 v0.7.0 2021-03-01 仅监控部署,监控现有 PostgreSQL 实例 v0.7.0 v0.6.0 2021-02-19 架构增强,将 PG 与 Consul 解耦 v0.6.0 v0.5.0 2021-01-07 支持在配置中定义业务数据库/用户 v0.5.0 v0.4.0 2020-12-14 支持 PostgreSQL 13,添加官方文档 v0.4.0 v0.3.0 2020-10-22 虚拟机置备方案正式定稿 v0.3.0 v0.2.0 2020-07-10 PG 监控系统第六版正式发布 v0.2.0 v0.1.0 2020-06-20 在生产仿真测试环境中验证通过 v0.1.0 v0.0.5 2020-08-19 离线安装模式:无需互联网访问即可交付 v0.0.5 v0.0.4 2020-07-27 将 Ansible 剧本重构为 Role Refactor playbooks into ansible roles v0.0.4 v0.0.3 2020-06-22 接口设计改进 v0.0.3 v0.0.2 2020-04-30 首次提交 v0.0.2 v0.0.1 2019-05-15 概念原型 v0.0.1
会议与演讲 日期 类型 活动 主题 2025-11-29 获奖&演讲 第八届 PostgreSQL 生态大会(杭州) PostgreSQL Magneto Award,世界级 Postgres 元发行版 2025-05-16 闪电演讲 PGConf.Dev 2025(蒙特利尔) Extension Delivery: 让您的 PGEXT 触达用户 2025-05-12 主题演讲 PGEXT.DAY, PGCon.Dev 2025 PostgreSQL 生态中缺失的包管理器与扩展仓库 2025-04-19 实战工坊 PostgreSQL 数据库技术峰会 使用 Pigsty 部署 PG 生态伙伴:Dify, Odoo, Supabase 2025-04-11 直播主持 OSCHINA 数智 Talk 刷屏的 MCP 是炒作还是革命? 2025-01-15 直播分享 开源老将与新秀第四期 PostgreSQL 扩展吞噬数据库世界?PG 包管理器 pig 与自建 RDS Pigsty 2025-01-09 颁奖典礼 OSCHINA 2024 年度杰出贡献专家 年度杰出贡献专家 2025-01-06 圆桌论坛 中国 PostgreSQL 数据库生态大会 PostgreSQL 扩展正在吞噬数据库世界 2024-11-23 播客 技术乱炖 Podcast 来自 Linux 基金会:为什么最近都在关注"卡脖子"? 2024-08-21 媒体专访 蓝色科技浪潮 Pigsty 作者冯若航专访:简化 PG 管理,推动中国开源社区 2024-08-15 技术大会 GOTC 全球开源技术峰会 PostgreSQL AI/ML/RAG 扩展生态与最佳实践 2024-07-12 主题演讲 第十三届 PG 中国技术大会 数据库世界的未来:扩展,服务,与 Postgres 2024-05-31 非正式会议 PGCon.Dev 2024 全球 PG 开发者大会 Unconference 内置 Prometheus 指标导出器 2024-05-28 专题研讨 PGCon.Dev 2024 全球 PG 开发者大会 扩展峰会 Extension in Core & Binary Packing 2024-05-10 直播辩论 三人行·云计算泥石流系列 第三期 公有云是骗局吗? 2024-04-17 直播辩论 三人行·云计算泥石流系列 第二期 云数据库是智商税吗? 2024-04-16 圆桌论坛 Cloudflare Immerse 深圳 赛博菩萨圆桌论坛 2024-04-12 技术大会 2024 数据技术嘉年华 Pigsty:解决 PostgreSQL 运维难题 2024-03-31 直播辩论 三人行·云计算泥石流系列 第一期 罗永浩卖云,我们却在下云? 2024-01-24 直播主持 OSCHINA 开源漫谈 第九期 DBA 会被云干掉吗? 2023-12-20 直播辩论 开源漫谈第七期 上云 or 下云,割韭菜还是降本增效? 2023-11-24 技术大会 大模型时代的向量数据库 圆桌讨论:大模型时代向量数据库新未来 2023-09-08 人物专访 墨天轮风云人物访谈 冯若航:不想当段子手的技术狂,不是一位好的开源创始人 2023-08-16 技术大会 DTCC 2023 DBA 之夜:PostgreSQL vs MySQL 的开源协议问题 2023-08-09 直播辩论 开源漫谈第一期 MySQL vs PostgreSQL,谁是世界第一? 2023-07-01 技术大会 SACC 2023 专题研讨会8:FinOps 实践:云成本管理与优化 2023-05-12 线下活动 PostgreSQL 中国社区 温州站线下沙龙 PG With DB4AI: 向量数据库 PGVECTOR & AI4DB: 数据库自动驾驶 Pigsty 2023-04-08 技术大会 数据库嘉年华 2023 更好的开源 RDS 替代:Pigsty 2023-04-01 技术大会 PostgreSQL 中国社区 西安站线下沙龙 PG 高可用与容灾最佳实践 2023-03-23 公开直播 Bytebase x Pigsty 管理 PostgreSQL 的最佳实践:Bytebase x Pigsty 2023-03-04 技术大会 PostgreSQL 中国技术大会 炮打 RDS,Pigsty v2.0 发布 2023-02-01 技术大会 DTCC 2022 开源 RDS 替代:开箱即用、自动驾驶的数据库发行版 Pigsty 2022-07-21 直播辩论 云吞噬开源,那开源有机会反击吗? 云吞噬开源,那开源有机会反击吗? 2022-07-04 人物专访 专题采访:创造者说 90 后,辞职创业,说要卷死云数据库 2022-06-28 公开直播 贝斯的圆桌趴 |DBA 福音 - SQL 审核最佳实践 2022-06-12 公开路演 奇绩创坛 S22 路演日 好用省钱的数据库发行版 Pigsty 2022-06-05 视频直播 PG 中文社区直播分享 Pigstyv1.5 快速上手新特性介绍与生产集群搭建
2.4 - 发展规划 未来功能的规划,新功能的发布节奏,待办事项列表。
版本发布策略 Pigsty 使用语义化版本号,<主版本>.<次版本>.<修订号>。Alpha / Beta / RC 版本会在版本号后添加后缀,如 -a1,-b1,-c1。
主版本更新意味着不兼容的基础性变化与重大新特性;次版本更新通常表示普通功能特性更新,较小的 API 变动;修订版本更新意味着 Bug 修复与软件包版本更新。
Pigsty 计划每年发布一次主版本更新,次版本更新通常跟随 PostgreSQL 小版本更新节奏,在 PostgreSQL 新版本发布后最迟一个月内跟进。
Pigsty 通常每年计划 4 - 6 个小版本,完整发布历史请参考 发行注记 。
使用具体的版本号进行部署
Pigsty 使用 main 主干分支进行开发,请始终使用带有版本号的 Release 。
除非您清楚知道自己在做什么,否则请勿使用 GitHub 的 main 分支,总是检出特定版本使用。
列入考虑的新特性 这里是我们的 活跃议题 与 路线图 。
扩展插件与软件包 关于扩展支持的路线图,可以在这里找到:https://pgext.cloud/e/roadmap
考虑纳入 暂不考虑 2.5 - 加入社区 Pigsty 是一个 Build in Public 的项目,我们在 GitHub 上非常活跃,中文区用户主要活跃于微信群组中。
GitHub 我们的 GitHub 仓库地址是:https://github.com/pgsty/pigsty ,欢迎点个 ⭐️ 关注 我们。
我们欢迎任何人 提交新 Issue 或创建 Pull Request ,提出功能建议并参与 Pigsty 贡献。
请注意,关于 Pigsty 文档的问题,请在 github.com/Vonng/pigsty.cc 仓库中提交 Issue 。
微信群组 中文区用户主要活跃于微信群组中,目前有七个活跃的群组,1群-4群已经满员,其他群需要添加小助手微信拉入。
加入微信社群,请用搜索 “Pigsty小助手”,(微信号 pigsty-cc) 备注或发送 “加群” ,小助手会将您拉入群组中。
海外社群 Telegram: https://t.me/joinchat/gV9zfZraNPM3YjFh
Discord: https://discord.gg/j5pG8qfKxU
您也可以通过邮件联系我: rh@vonng.com
社区求助 当您使用 Pigsty 遇到问题时,可以向社区求助,您提供的信息越丰富,就越有可能在社区得到帮助。
请参考 社区求助指南 ,尽可能提供足够的信息,以便社区成员帮助您解决问题。以下是求助提问的参考模板:
发生了什么事? (必选项 )
Pigsty 版本号与操作系统版本 (必选项 )
$ grep version pigsty.yml
$ cat /etc/os-release
$ uname -a
一些云厂商对标准操作系统发行版进行了定制,您可以告诉我们使用的是哪一家云厂商的什么操作系统镜像。
如果您在安装操作系统后对环境进行了定制与修改,或者在您的局域网中有特定的安全规则与防火墙配置,也请在提问时告知我们。
Pigsty 配置文件
请不要忘记抹掉任何敏感信息:密码,内部密钥,敏感配置等。
cat ~/pigsty/pigsty.yml
你期待发生什么?
请描述正常情况下应该发生什么事情,实际发生的情况与期待的情况有何偏离?
如何复现此问题?
请尽可能详细地告诉我们复现此问题的方法与步骤。
监控截图
如果你在使用 Pigsty 提供的监控系统,可以提供 相关 的截图。
错误日志
请尽可能提供与错误有关的日志。请不要粘贴类似 “Failed to start xxx service” 之类没有信息量的内容 。
您可以从 Grafana / VictoriaLogs 中查询日志,或从以下位置获取日志:
Syslog: /var/log/messages (rhel) or /var/log/syslog (debian) Postgres: /pg/log/postgres/* Patroni: /pg/log/patroni/* Pgbouncer: /pg/log/pgbouncer/* Pgbackrest: /pg/log/pgbackrest/* journalctl -u patroni
journalctl -u <service name>
您已经搜索过 Issue/网站/FAQ 了吗?
在 FAQ 中,我们提供了许多常见问题的解答,请在提问前检查
您也可以从 Github Issue 与 Discussion 中搜索相关问题:
有什么其他信息是我们需要知道的吗?
您提供的信息与上下文越丰富,我们越有可能帮助您解决问题。
2.6 - 隐私政策 Pigsty 软件与网站会收集哪些用户数据,以及我们将如何处理您的数据并保护您的隐私权?
Pigsty软件 当您安装 Pigsty 软件时,如果在网络隔离的环境中使用离线软件包安装,我们不会收到任何关于您的数据 。
如果您选择在线安装,那么在下载相关软件包时,我们的服务器或云供应商的服务器会自动在日志中记录来访机器的 IP 地址和/或主机名,和您下载的软件包名称。
除非法律要求,我们不会与其他组织共享这些信息。(实话说,吃饱了撑着才会去看这些东西)
Pigsty 使用的主域名为:pigsty.io ,中国大陆请使用中文备案镜像站点 pigsty.cc 。
Pigsty网站 当您访问我们的网站时,我们的服务器会自动在 Nginx 日志中记录您的 IP 地址和/或主机名。
仅当您决定通过完成调查或在我们的某个网站上注册为用户来向我们发送此类信息时,我们才会存储您的电子邮件地址、姓名和地点等信息
我们收集这些信息是为了帮助我们改进网站内容、定制网页布局以及出于技术和支持目的联系人员。除非法律要求,我们不会与其他组织共享您的电子邮件地址。
本网站使用 Google Analytics,这是 Google, Inc.(“Google”)提供的一项网络分析服务。谷歌分析使用“cookies”,即放置在您计算机上的文本文件,帮助网站分析用户如何使用该网站。
cookie 生成的有关您使用网站的信息(包括您的 IP 地址)将被传输至 Google 位于美国的服务器并由其存储。谷歌将使用这些信息来评估您对网站的使用情况,为网站运营商编制网站活动报告,并提供与网站活动和互联网使用相关的其他服务。
如果法律要求,或者第三方代表 Google 处理信息,Google 还可能会将此信息传输给第三方。 Google 不会将您的 IP 地址与 Google 持有的任何其他数据关联起来。
您可以通过在浏览器上选择适当的设置来拒绝使用 cookie,但请注意,如果您这样做,您可能无法使用本网站的全部功能。使用本网站即表示您同意 Google 以上述方式和目的处理有关您的数据。
如果您对此政策有任何疑问或意见,或要求删除个人数据,您可以通过发送邮件至 rh@vonng.com 与我们联系
2.7 - 开源协议 Pigsty 使用的开源协议 —— Apache-2.0,它授予您什么样的权利,又有哪些限制?
协议摘要 Pigsty 项目主体使用 Apache-2.0 开源许可证;Pigsty 文档网站使用 CC by 4.0 许可证。
项目协议地址:https://github.com/pgsty/pigsty/blob/main/LICENSE
Pigsty 项目主体 Pigsty 软件主体采用 Apache License 2.0 许可证。
这是一种宽松的开源许可证,允许您自由地使用、修改和分发本软件,包括用于商业目的,而无需公开您的源代码或使用相同许可证。
本协议授权您 本协议不提供 本协议的条件 商用 商标使用权 包含本许可证与版权声明 修改 责任与担保 声明对原始代码的修改 分发 专利授权 私人使用
Pigsty 文档网站 Pigsty 的文档与网站(包括但不限于:pigsty.cc ,pigsty.io ,pgsty.com )均使用 Creative Commons Attribution 4.0 International (CC BY 4.0) 许可证。
CC BY 4.0 是一种知识共享许可证,允许您自由地分享与演绎本站的内容,但是您必须给出 适当的署名 ,提供指向许可证的链接,并 指出是否有对原始内容进行了修改 。
本协议授权您 本协议不提供 本协议的条件 商用 商标使用权 署名(注明原作者) 修改 责任与担保 标明修改内容 分发 专利授权 提供许可证链接 私人使用
SBOM 清单 以下为 Pigsty 项目所使用或相关的开源软件及其开源协议。
510 个 PostgreSQL 扩展插件的许可证请参考 PostgreSQL 扩展许可证清单 。
必要性等级说明:
必选 :提供 Pigsty 关键性核心能力,不提供关闭停用选项建议 :Pigsty 默认启用 的组件,可以通过配置选项停用可选 :Pigsty 默认支持但不启用的组件,可通过配置启用Apache-2.0 许可证原文
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright (C) 2018-2026 Ruohang Feng, @Vonng (rh@vonng.com)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
2.8 - 赞助我们 Pigsty 的赞助者,投资人名单,感谢你们对本项目的支持!
赞助我们 Pigsty 是一个开源免费的自由软件,由 PostgreSQL 社区成员用热情浇灌而成,旨在整合 PostgreSQL 生态的力量,推广 PostgreSQL 的普及。
如果我们的工作帮到了您,请考虑赞助或者支持一下我们的项目:
直接打钱赞助我们,用最直接有力的鼓舞表达您的真挚支持! 考虑采购我们的 技术支持服务 ,我们可以提供专业的 PostgreSQL 高可用集群部署与维护服务,让您的预算花得物有所值! 通过文章,讲座,视频分享您使用 Pigsty 的案例与经验。 允许我们在 “这些用户使用了 Pigsty” 中提及您的组织。 向有需求的朋友,同事与客户提名/推荐我们的项目与服务。 关注我们的 微信公众号 并转发相关技术文章至群组与朋友圈。 天使投资人 Pigsty 是由 奇绩创坛 (原 YC 中国,MiraclePlus) S22 所投资的项目,感谢奇绩创坛与陆奇博士对本项目的支持!
赞助者 感谢我们的赞助者 Vercel,为 Pigsty 网站提供了赞助与网站托管基础设施。
2.9 - 行业案例 Pigsty 在各个领域与行业的客户/应用案例
根据 Google Analytics PV 与下载量,Pigsty 目前有约 10 万用户 ,一半来自中国大陆,一半来自全球其他地区。
遍布互联网、云计算、金融、自动驾驶、制造业、科技创新、ISV 与军工等多个行业。
如果您在 使用 Pigsty 并且愿意与我们分享您的案例与 Logo,欢迎联系我们,我们提供一次的免费咨询支持。
互联网 探探 :两百台+物理机,用于 PostgreSQL 与 Redis 服务
哔哩 :用于支持 PostgreSQL 创新业务
云厂商 Bitdeer :比特小鹿,提供 PG DBaaS
Oracle OCI :使用 Pigsty 交付 PostgreSQL 集群。
金融行业 AirWallex :监控 200+ GCP PostgreSQL 数据库
影视行业 影视飓风 :自建 PG RDS / Victoria Metrics
自动驾驶 Momenta :自动驾驶,管理自建 PostgreSQL 集群
制造业 华峰集团 :使用 Pigsty 交付 PostgreSQL 集群作为化工时序数据仓库
科技创新 北京领雾科技 :云上 PostgreSQL 下云自建
Motphys :自建 PostgreSQL 支持 Gitlab
赛陇生物科技 :自建 Supabase
杭州零码科技 :自建 PostgreSQL
ISV 内蒙古豪德天沐科技有限公司
上海元芳
DSG
军工 北京某部队
上海某部队
电科36所
机械工业研究所
航天一院
2.10 - 订阅服务 Pigsty 专业版/企业版订阅服务:当您遇到与 PostgreSQL 和 Pigsty 有关的疑难杂症时,订阅服务可以为您兜底。
Pigsty 旨在聚集 PG 生态的合力,并用自动驾驶的数据库管控软件帮助用户用好世界上 最流行 的数据库 PostgreSQL。
尽管 Pigsty 本身已经解决了 PG 使用中的诸多问题。但想真正达到企业级服务的质量,原厂提供的专家支持与兜底服务不可或缺。
我们深知专业的商业支持服务对于企业客户的重要性,因此,Pigsty 企业版在开源版本的基础上提供了一系列增值服务,帮助用户更好地用好 PostgreSQL 与 Pigsty,供有需求的客户按需选用。
如果您有下列需求,欢迎考虑 Pigsty 订阅服务:
在关键场景中运行数据库,需要严格 SLA 保障兜底。 希望对 Pigsty 与 PostgreSQL 相关疑难杂症提供兜底。 希望获取关于 PostgreSQL / Pigsty 生产环境最佳实践的指导。 希望有专家帮助解读监控图表,分析定位性能瓶颈与故障根因,给出意见。 希望根据现有资源与业务需求,规划满足安全/容灾/合规要求的数据库架构。 需要将其他数据库迁移至 PostgreSQL 数据库,或对历史遗留实例迁移与改造。 建设基于 Prometheus / Grafana 技术栈的可观测性体系,数据大盘,可视化应用。 希望支持国产信创操作系统/国产信创 ARM 芯片架构,提供中文/本地化界面支持。 下云并寻求 RDS for PostgreSQL 的开源替代 —— 云中立,无供应商锁定的解决方案。 希望获取关于 Redis / ETCD / MinIO,以及 TimescaleDB / Citus 等扩展的专业支持。 希望将 Pigsty 作为 SaaS / PaaS / DBaaS 对外销售,或基于此发行版提供技术服务/云服务。 订阅计划 除了 开源版 之外,Pigsty 提供两种不同的订阅服务档位:专业版 与 企业版 ,您可以根据自身的实际情况与需求选购。
开源免费 无规模限制,无质保承诺
许可协议:Apache-2.0
PG 支持:18(默认),14 - 18 可选
架构支持:x86_64,Arm64
OS 支持:三系最新小版本
EL 9.7 / 10.1 Debian 12.13 / 13.3 Ubuntu 26.04.0 / 24.04.4 / 22.04.5 功能:核心模块
SLA:无 SLA 承诺
社区公益支持答疑:
支持:无人天支持选项
仓库:全球 CF 托管仓库
起售价:150,000 ¥ / 年 普通用户的默认之选
许可协议:商业许可证
PG 支持:14 - 18
架构支持:x86_64,Arm64
OS 支持:八系大小版本
EL 8 / 9 / 10 兼容 Debian 12 / 13 Ubuntu 22 / 24 / 26 功能:所有模块 (信创除外)
SLA:工作日时效内响应
提供专家咨询服务:
支持:每年包含 1 人天
交付:标准离线软件包
仓库:中国大陆镜像站
起售价:400,000 ¥ / 年 严格 SLA 的关键场景
许可协议:商业许可证
PG 支持:14 - 18+(旧版本按需定制)
架构支持:x86_64,Arm64
OS 支持:按需定制
EL, Debian, Ubuntu 云上 Linux 操作系统 国产操作系统与 ARM 功能:所有模块
SLA:7 x 24 (< 1h)
提供企业级专家咨询服务:
软件缺陷修复 疑难杂症分析 专家答疑解惑 备份合规建议 升级路径支持 性能瓶颈定位 年度架构评估 扩展插件收录 DBaaS & OEM 用例 支持:每年包含 2 人天
仓库:中国大陆镜像站
交付:定制离线软件包
信创:PolarDB-O 支持
Pigsty开源版 Pigsty 开源版使用 Apache-2.0 许可证, 提供了完整核心功能,无需任何费用,但也不承诺任何质保服务。如果您发现了 Pigsty 的缺陷,我们非常欢迎您在 Github 上提出 Issue 。
针对开源版本,我们提供 PostgreSQL 18 在七个主流操作系统发行版当前小版本上的预制标准离线软件包:EL 9.7 / 10.1、Debian 12.13 / 13.3、Ubuntu 26.04.0 / 24.04.4 / 22.04.5,并提供 x86_64 与 aarch64 构建。
使用 Pigsty 开源版本,可以让初级研发工程师 / 运维工程师拥有专业 DBA 70%+ 的能力,在缺少数据库专家的情况下,也能够轻松搭建一个高可用,高性能,易维护,安全可靠的 PostgreSQL 数据库集群。
代号 操作系统发行版版本 x86_64aarch64PG18 PG17 PG16 PG15 PG14 EL10 RHEL 10 / Rocky10 / Alma10 el10.x86_64el10.aarch64EL9 RHEL 9 / Rocky9 / Alma9 el9.x86_64el9.aarch64U26 Ubuntu 26.04 (resolute) u26.x86_64u26.aarch64U24 Ubuntu 24.04 (noble) u24.x86_64u24.aarch64U22 Ubuntu 22.04 (jammy) u22.x86_64u22.aarch64D13 Debian 13 (trixie) d13.x86_64d13.aarch64D12 Debian 12 (bookworm) d12.x86_64d12.aarch64
= 首要支持, = 选配支持
Pigsty专业版 专业版订阅: 起售价格 ¥ 150,000 / 年
Pigsty 专业版订阅提供了完整的功能模块,以及对于 Pigsty 本身的质保。关于 PostgreSQL 本身与扩展插件的缺陷,我们将尽最大努力通过 PostgreSQL 全球开发者社区进行反馈与修复。
Pigsty 专业版构建于开源版基础之上,完全兼容开源版本的所有功能,并提供额外的功能模块,与更为宽广的数据库 / 操作系统版本兼容选项:我们将针对八个主流操作系统发行版(EL8/9/10、Debian 12/13、Ubuntu 22/24/26)的 所有小版本 提供构建选项。
Pigsty 专业版包含了对 PostgreSQL 14 - 18 的支持,并持续跟进上游 PostgreSQL 小版本更新(活跃大版本通常做到当日或准当日可用),确保您可以通过滚动升级的方式,平滑迁移到最新的 PostgreSQL 大版本上。
Pigsty 专业版订阅允许您使用中国大陆镜像站点软件仓库,无需翻墙代理即可访问;同时我们将针对您使用的精准操作系统大小版本定制离线软件安装包,确保在断网环境下也能正常安装交付,做到自主可控。
Pigsty 专业版订阅提供了标准的专家咨询服务,包括疑难杂症分析,DBA 答疑解惑,备份合规建议等,我们承诺在工作日(5x8)时效内响应您的问题,并且每年提供 1 人天支持,以及可选的人天加购选项。
Pigsty 专业版使用商业许可证,提供额外的功能模块、技术支持与质保服务。
Pigsty 专业版的起售价格 ¥150,000 / 年 ,相当于 9 vCPU 的 AWS 高可用 RDS PG 年费, 或月薪 一万元 的初级运维工程师。
代号 操作系统发行版版本 x86_64Arm64PG18 PG17 PG16 PG15 PG14 EL10 RHEL 10 / Rocky10 / Alma10 el10.x86_64el10.aarch64EL9 RHEL 9 / Rocky9 / Alma9 el9.x86_64el9.aarch64EL8 RHEL 8 / Rocky8 / Alma8 / Anolis8 el8.x86_64el8.aarch64U26 Ubuntu 26.04 (resolute) u26.x86_64u26.aarch64U24 Ubuntu 24.04 (noble) u24.x86_64u24.aarch64U22 Ubuntu 22.04 (jammy) u22.x86_64u22.aarch64D13 Debian 13 (trixie) d13.x86_64d13.aarch64D12 Debian 12 (bookworm) d12.x86_64d12.aarch64
Pigsty企业版 企业版订阅: 起售价格 ¥ 400,000 / 年
Pigsty 企业版订阅包含 Pigsty 专业版订阅提供的全部服务内容,和以下增值服务项:
Pigsty 企业版订阅提供最为广泛的数据库/操作系统版本支持范围,包括对过保操作系统(EL7, D11),国产操作系统,云厂商操作系统,以及过保数据库大版本(PG12+ 按需定制)的延长支持,以及对 Arm64 架构芯片的完整支持。
Pigsty 企业版订阅提供了信创,国产化解决方案,允许您在 Pigsty 中使用 PolarDB v2.0 (此内核许可需单独采购)内核替换原生 PostgreSQL 内核,以满足国产化合规要求。
Pigsty 企业版订阅提供了更高标准的企业级咨询服务,承诺 7x24 提供 (< 1h) 的响应时间 SLA,并可提供更多种类的咨询支持:版本升级,性能瓶颈定位,年度架构评估,扩展插件收录等。
Pigsty 企业版订阅每年自带 2 人天支持,以及可选的人天加购选项,用于解决各种更为棘手复杂耗时的问题。
Pigsty 企业版允许您将 Pigsty 用于 DBaaS 用途,建设云数据库服务对外出售。
Pigsty 企业版的起步价格为 ¥400,000 / 年 ,相当于 24 vCPU 的 AWS 高可用 RDS 年费,或月薪 三万元 的运维专家。
代号 操作系统发行版版本 x86_64aarch64PG18 PG17 PG16 PG15 PG14 PG13 PG12 EL10 RHEL 10 / Rocky10 / Alma10 el10.x86_64el10.aarch64EL9 RHEL 9 / Rocky9 / Alma9 el9.x86_64el9.aarch64EL8 RHEL 8 / Rocky8 / Alma8 / Anolis8 el8.x86_64el8.aarch64U26 Ubuntu 26.04 (resolute) u26.x86_64u26.aarch64U24 Ubuntu 24.04 (noble) u24.x86_64u24.aarch64U22 Ubuntu 22.04 (jammy) u22.x86_64u22.aarch64D13 Debian 13 (trixie) d13.x86_64d13.aarch64D12 Debian 12 (bookworm) d12.x86_64d12.aarch64D11 Debian 11 (bullseye) d11.x86_64d11.aarch64EL7 RHEL7 / CentOS7 / UOS … el7.x86_64-
Pigsty订阅说明 功能差异
Pigsty 专业版/企业版相比开源版本,包含以下额外功能:
命令行管理工具 : 解锁 Pigsty 命令行工具(pig)的完整功能系统定制能力 :针对精确的主流 Linux 操作系统发行版大小版本提供预制的离线安装包离线安装能力 :在没有互联网访问的环境中(断网环境)实现 Pigsty 的完整安装PG 内核多版本 :允许用户自由指定并安装 PostgreSQL 生命周期内大版本的内核(14 - 18)内核替换能力 :允许用户使用其他 PostgreSQL 系兼容内核,替换原生 PG 内核,以及离线安装这些内核的能力扩展支持能力 :针对 510 个可用 PG Extension,提供 PG 14-18 在主流操作系统上开箱即用的安装能力。完整功能模块 :提供所有功能模块:Supabase :可靠地自建生产级开源 FirebaseMinIO :企业 PB 级对象存储规划与自建DuckDB :提供完善的 DuckDB 支持,以及 PostgreSQL + DuckDB OLAP 扩展插件支持Kafka :提供高可用的 Kafka 集群部署与监控Kubernetes, VictoriaMetrics & VictoriaLogs 国产操作系统支持 :提供国产信创操作系统支持选项(仅限企业版订阅 )国产 ARM 架构支持 :提供国产 ARM64 架构支持选项(仅限企业版订阅 )中国大陆镜像仓库 :无需科学上网即可顺畅安装,提供境内 YUM/APT 仓库镜像与 DockerHub 访问代理。中文界面支持 :监控系统中文版界面支持(Beta)付费模式
Pigsty 订阅采用按年付费的模式,签订合同后,从合同约定日起计算一年的有效期。订阅合同到期前如果继续打款则视为自动续订。
连续订阅有折扣,第一次续签(第二年)享受 95 折优惠,第二次以及后续的续签享受订阅费用 9 折优惠,一次性订阅三年以上整体费用享受 85 折优惠。
在年度订阅合同终止后,您可以选择不续签订阅服务,Pigsty 将不再提供软件更新,技术支持,咨询服务,但您仍然可以继续使用已经安装版本的 Pigsty 专业版软件。
如果您订阅了 Pigsty 专业服务并选择不续订,在重新订阅时 无需 补齐中断期间的订阅费用,但所有折扣与优惠将重置。
Pigsty 的定价策略确保用户物有所值 —— 您可以立即获得顶尖 DBA 的数据库架构建设方案与管理最佳实践,并由其提供咨询答疑与服务支持兜底;
而付出的成本相比于全职雇佣数据库专家或使用云数据库极具竞争力。以下是市场上 企业级数据库专业服务市场定价参考 :
体面数据库专业服务的公允价格是 1 ~ 2 万元 / 年 ,计费单位为 vCPU ,即一个 CPU 线程(1 Intel 核 = 2 vCPU 线程)。
而 Pigsty 提供国内顶尖的 PostgreSQL 专家服务,并采用 按节点计费 的模式,在当下常见的高核数服务器节点上,能为用户带来无可比拟的 降本增效 体验。
Pigsty专家服务 除了 Pigsty 订阅,Pigsty 还提供按需采购的 Pigsty x PostgreSQL 专家服务 —— 业界顶级数据库专家坐堂问诊。
专家顾问:300,000 ¥ / 三年
在三年内,提供 10 次关于 PostgreSQL 与 Pigsty 的复杂案例处理,以及不限量答疑。
专家支持:30,000 ¥ / 人·天
业界顶级专家现场支持,可用于架构咨询,故障分析,问题排查,数据库体检,监控解读,迁移评估,教学培训,上下云参谋等连续耗时场景。
专家咨询:3000 ¥ / 例
咨询任何您想要了解的问题,关于 Pigsty, PostgreSQL,数据库,云计算,AI……
数据库老司机,云计算泥石流与您分享行业顶级洞察、认知与研判。
挂专家号:300 ¥ / 问题
给出一个关于 PostgreSQL / Pigsty / 数据库相关的问题的快速诊断意见与答复,不超过 5 分钟。
服务主体 Pigsty 目前由作者 冯若航 独资运营维护,商业主体为:
海南诸夏云数据有限公司 / 91460000MAE6L87B94 海口龙华辟技数据中心 / 92460000MAG0XJ569B 海口龙华越航科技中心 / 92460000MACCYGBQ1N PIGSTY® 与 PGSTY® 为海口龙华越航科技中心的注册商标。
商务咨询请发送邮件至 rh@vonng.com 。中国大陆地区用户欢迎添加微信号 RuohangFeng。
Pigsty 是奇绩创坛 S22 被投项目,原主体 磐吉云数(北京)科技有限责任公司 已经清算剥离 Pigsty 业务,与 Pigsty 无关。
2.11 - 常见问题 解答关于 Pigsty 项目本身的常见问题。
Pigsty 是什么,不是什么? Pigsty 是一个 PostgreSQL 数据库发行版,本地优先的开源 RDS 云数据库解决方案。
Pigsty 不是数据库管理系统(DBMS),而是管理 DBMS 的工具,发行版,解决方案,与最佳实践。
类比:数据库是车,那么 DBA 是司机,RDS 是出租车服务,Pigsty 则是自动驾驶软件。
Pigsty 解决什么问题? 用好数据库的能力 极为稀缺:要么高薪聘请数据库专家自建(雇司机),或从云厂商以天价租赁 RDS(打车),但现在你有新的选项:Pigsty(自动驾驶)。
Pigsty 帮用户用好数据库:让用户在没有 DBA 的情况下,以不到 RDS 1 / 10 的成本,自建质量效率更优的本地云数据库服务!
Pigsty 的目标用户是谁? Pigsty 有两类典型目标用户,基本盘是 中大型公司 超大规模自建企业级/生产级 PostgreSQL RDS / DBaaS 服务。
Pigsty 通过极致的可定制性,可以实现最苛刻场景的数据库管理需求,并提供企业级的支持与服务保障。
与此同时,Pigsty 也针对个人开发者,缺乏 DBA 中小企业以及开源社区提供 “开箱即用” 的 PG RDS 自建方案。
Pigsty 为什么能帮您用好数据库? Pigsty 沉淀了顶尖专家在最复杂,最大规模的甲方 PostgreSQL 场景中打磨得到的经验与最佳实践,产品化为可复制的软件:
一次性解决扩展安装,高可用,链接池,监控,备份恢复,参数优化,IaC 批量管理,一键安装,自动化运维等诸多问题。提前规避诸多陷阱,避免重复踩坑。
Pigsty 为何比 RDS 好用? Pigsty 提供远超 RDS 的特性集与基础设施支持,包括 510 扩展插件与 8+ 内核支持。
Pigsty 提供 PG 生态中独一无二的专业级监控系统,与久经复杂场景打磨考验的架构最佳实践,简单易用。
且用探探,苹果,阿里等顶级甲方场景打磨而成,用激情与热爱持续浇灌,深度与成熟度绝非 RDS 大锅饭可比。
Pigsty 为何比 RDS 省钱? Pigsty 允许您使用 10 ¥/核·月的纯硬件资源,运行 400¥-1400¥/核·月的 RDS 云数据库,并省去 DBA 的工资。通常,成规模的 Pigsty 部署总拥有成本(TCO)能比 RDS 低 90% 以上。
Pigsty 能够同时降低软件许可/服务/人力的开销,自建无需加人,让您将成本花在刀刃上。
Pigsty 对研发有什么帮助? Pigsty 整合了 PG 生态最全的扩展(510),提供了 All in PG 解决方案:单一组件替代 Redis, Kafka, MySQL, ES, 向量数据库,OLAP / 大数据分析等专用组件。
极大提高研发效能与敏捷性的同时降低复杂度成本,而且研发能在 Pigsty 的加持下实现自助管理,自主 DevOps,无需 DBA。
Pigsty 对运维有什么帮助? Pigsty 故障自愈的高可用架构确保硬件故障无需当场处理,让运维与 DBA 睡个好觉;监控助力问题分析与性能优化;IaC 赋能超大规模集群自动化管理。
运维在 Pigsty 加持下能兼职 DBA,而 DBA 则可以跳过系统建设阶段,节省大量工时并专注于高价值工作,或喝茶看报,学习 PG。
Pigsty 的作者是谁? Pigsty 主体由冯若航一人开发,这是一位专注于 PostgreSQL 领域 10 年的开源贡献者,数据库专家与布道师,
曾任职于阿里,探探,苹果,全栈专家。现为一人公司创始人,提供专业咨询服务。
同时他也是技术 KOL,微信数据库个人公众号榜首 《非法加冯》 的主理人,全网粉丝六万+。
Pigsty 的生态位与影响力如何? Pigsty 全球 PostgreSQL 生态中最有影响力的中国开源项目,共有约十万用户,一半来自海外。
Pigsty 也是 PostgreSQL 生态最活跃的开源项目之一,目前在扩展分发与监控系统上占据碾压性优势。
PGEXT.Cloud 是由 Pigsty 维护的 PostgreSQL 扩展仓库,拥有全球最多的 PostgreSQL 扩展分发量。
目前已经成为多家国际 PostgreSQL 厂商的软件供应链上游。
Pigsty 目前是 PostgreSQL 生态的主要发行版之一,也是云厂商 RDS 的挑战者,目前已经广泛应用于军工,政企,医疗,互联网,金融,制造业等各个行业。
Pigsty 适合什么规模的客户? Pigsty 源于超大规模 PostgreSQL 自动化管理的需求,但已针对易用性进行深度优化,缺乏专业 DBA 能力的个人开发者与中小型企业也可以轻松上手使用。
最大规模部署为 25K vCPU,450万 QPS,六年+,最小规模部署可完整运行于 1c1g 虚拟机上作为 Demo / Devbox 使用。
Pigsty 提供哪些能力? Pigsty 专注于整合 PostgreSQL 生态,提供 PostgreSQL 的最佳实践,但同时也支持一系列与 PostgreSQL 配合良好的开源软件。例如:
Etcd, Redis, MinIO, DuckDB, Prometheus FerretDB, Babelfish, IvorySQL, PolarDB, OrioleDB OpenHalo, Supabase, Greenplum, Dify, Odoo, … Pigsty 适用于哪些场景? 运行大规模 PostgreSQL 集群用于业务 自建 RDS,对象存储,缓存,数仓,Supabase, … 自建 Odoo,Dify,Wiki,GitLab 等企业级应用 运行监控基础设施,监控现有数据库与主机 同时组合使用多种 PG 扩展插件 大屏开发与交互式数据应用 Demo,数据可视化,Web 建站 Pigsty 开源免费吗? Pigsty 是 100% 的开源软件 + 自由软件,在遵循开源许可证的前提下,您可以将其免费地,自由的用于各种商业目的。
我们珍视软件自由,对于非 DBaaS / OEM 用例,我们执行更为宽松的等效 Apache 2.0 许可证。请参阅许可证以获取更多详细信息。
Pigsty 提供商业支持吗? Pigsty 软件本身开源免费,并提供丰俭由人的商业订阅,为 Pigsty & PostgreSQL 提供质保。
订阅提供更宽广的 OS/PG/芯片架构支持范围,以及专家咨询与支持。
Pigsty 商业订阅交付业界顶尖的管理/技术经验/解决方案,
帮助您节省宝贵的时间,替您扛雷,并为疑难杂症兜底。
Pigsty 支持国产信创吗? Pigsty 软件本身不属于数据库,不受信创名录限制,且已有多个部队用例。但 Pigsty 开源版不提供任何形式的信创支持。
商业版订阅提供与阿里云合作的国产信创解决方案,支持使用具有信创资质的 PolarDB-O(需单独采购)作为 RDS 内核,能够运行于信创操作系统/芯片环境。
Pigsty 可以换 Logo 贴牌为自己的产品吗? 再分发 Pigsty 时,您必须保留原作品中的版权声明、专利声明、商标声明和归属声明,
并且需要在修改的文件中附上显著的变更说明,同时保留 LICENSE 文件的内容。
在此前提下,您可以更换 PIGSTY 的 Logo 与商标,但不得宣传为 “自己原创的作品”。
我们在企业版本中提供对 OEM 与贴牌的商业授权支持。
Pigsty 的服务主体 Pigsty 是奇绩创坛 S22 被投项目,原主体 磐吉云数(北京)科技有限责任公司 已经清算剥离 Pigsty 业务,与 Pigsty 无关。
Pigsty 目前由作者冯若航个人独资运营维护,商业主体为:
海南诸夏云数据有限公司 / 91460000MAE6L87B94 海口龙华辟技数据中心 / 92460000MAG0XJ569B 海口龙华越航科技中心 / 92460000MACCYGBQ1N PIGSTY® 与 PGSTY® 为海口龙华越航科技中心的注册商标。
2.12 - 发布注记 Pigsty 历史版本发布说明
Pigsty 当前文档对应的准备发布版本为 v4.3.0 。
版本 发布日期 摘要 发布页面 v4.3.0 2026-05-01 510 扩展,Infra / PGSQL / 内核包批量更新,Ubuntu 26 支持 待发布 v4.2.2 2026-03-23 Insforge 应用自建,Infra 包批量更新,新增 pdu,pgdog,tigerfs v4.2.2 v4.2.1 2026-03-06 移除 PG13 支持,新增扩展,问题修复 v4.2.1 v4.2.0 2026-02-28 例行小版本更新,六大 PG 内核集中更新 v4.2.0 v4.1.0 2026-02-12 大小版本更新支持,Agent-Native CLI,默认防火墙安全策略收紧 v4.1.0 v4.0.0 2026-01-28 Victoria 可观测性,安全加固,JUICE/VIBE 模块,容器支持,Apache-2.0 v4.0.0 v3.7.0 2025-12-02 PG18 成为默认,437 个扩展,EL10 与 Debian13 支持,PGEXT.CLOUD v3.7.0 v3.6.1 2025-08-15 例行 PG 小版本更新,PGDG 中国区域镜像,EL9,D13 存根 v3.6.1 v3.6.0 2025-07-30 pgactive,MinIO / ETCD 改进,安装简化,配置梳理 v3.6.0 v3.5.0 2025-06-16 PG18 beta,421 扩展,监控升级,代码重构 v3.5.0 v3.4.1 2025-04-05 OpenHalo & OrioleDB,MySQL 兼容,pgAdmin 改进 v3.4.1 v3.4.0 2025-03-30 备份改进,自动证书,AGE,Ivory 全平台,本地化,架构与参数改进 v3.4.0 v3.3.0 2025-02-24 404 扩展,扩展目录,App 剧本,Nginx 定制,DocumentDB 支持 v3.3.0 v3.2.2 2025-01-23 390扩展,Omnigres 支持,Mooncake,Citus13 与 PG17 支持 v3.2.2 v3.2.1 2025-01-12 350扩展,Ivory4,Citus 强化,Odoo 模板 v3.2.1 v3.2.0 2024-12-24 扩展管理 CLI,Grafana 强化,ARM64 扩展补完 v3.2.0 v3.1.0 2024-11-24 PG 17 升默认大版本,配置简化,Ubuntu24 与 ARM 支持,Supabase,MinIO 改进 v3.1.0 v3.0.4 2024-10-30 PG 17 扩展,OLAP 全家桶,pg_duckdb v3.0.4 v3.0.3 2024-09-27 PostgreSQL 17,Etcd 运维优化,IvorySQL 3.4,PostGIS 3.5 v3.0.3 v3.0.2 2024-09-07 精简安装模式,PolarDB 15支持,监控视图更新 v3.0.2 v3.0.1 2024-08-31 例行问题修复,Patroni 4支持,Oracle 兼容性改进 v3.0.1 v3.0.0 2024-08-25 333个扩展插件,可插拔内核,MSSQL,Oracle,PolarDB 兼容性 v3.0.0 v2.7.0 2024-05-20 扩展大爆炸,新增20+强力扩展插件,与多款 Docker 应用 v2.7.0 v2.6.0 2024-02-28 PG 16 作为默认大版本,引入 ParadeDB 与 DuckDB 等扩展 v2.6.0 v2.5.1 2023-12-01 例行小版本更新,PG16 重要扩展支持 v2.5.1 v2.5.0 2023-09-24 Ubuntu/Debian 支持:bullseye, bookworm, jammy, focal v2.5.0 v2.4.1 2023-09-24 Supabase/PostgresML 支持与各种新扩展:graphql, jwt, pg_net, vault v2.4.1 v2.4.0 2023-09-14 PG16,监控 RDS,服务咨询支持,新扩展:中文分词全文检索/图/HTTP/嵌入等 v2.4.0 v2.3.1 2023-09-01 带 HNSW 的 PGVector,PG 16 RC1, 文档翻新,中文文档,例行问题修复 v2.3.1 v2.3.0 2023-08-20 主机 VIP, ferretdb, nocodb, MySQL 存根,CVE 修复 v2.3.0 v2.2.0 2023-08-04 仪表盘 & 置备重做,UOS 兼容性 v2.2.0 v2.1.0 2023-06-10 支持 PostgreSQL 12 ~ 16beta v2.1.0 v2.0.2 2023-03-31 新增 pgvector 支持,修复 MinIO CVE v2.0.2 v2.0.1 2023-03-21 v2 错误修复,安全增强,升级 Grafana 版本 v2.0.1 v2.0.0 2023-02-28 架构大升级,兼容性、安全性、可维护性显著增强 v2.0.0 v1.5.1 2022-06-18 Grafana 安全性修复 v1.5.1 v1.5.0 2022-05-31 Docker 应用程序支持 v1.5.0 v1.4.1 2022-04-20 错误修复 & 英文文档完整翻译 v1.4.1 v1.4.0 2022-03-31 MatrixDB 支持,分离 INFRA/NODES/PGSQL/REDIS 模块 v1.4.0 v1.3.0 2021-11-30 PGCAT 重整 & PGSQL 增强 & Redis Beta 支持 v1.3.0 v1.2.0 2021-11-03 默认 PGSQL 版本升级至 14 v1.2.0 v1.1.0 2021-10-12 主页,JupyterLab, PGWEB, Pev2 & pgbadger v1.1.0 v1.0.0 2021-07-26 v1 正式版,监控系统重整 v1.0.0 v0.9.0 2021-04-04 Pigsty 图形界面,命令行界面,日志集成 v0.9.0 v0.8.0 2021-03-28 服务置备,定制对外暴露的数据库服务 v0.8.0 v0.7.0 2021-03-01 仅监控部署,监控现有 PostgreSQL 实例 v0.7.0 v0.6.0 2021-02-19 架构增强,将 PG 与 Consul 解耦 v0.6.0 v0.5.0 2021-01-07 支持在配置中定义业务数据库/用户 v0.5.0 v0.4.0 2020-12-14 支持 PostgreSQL 13,添加官方文档 v0.4.0 v0.3.0 2020-10-22 虚拟机置备方案正式定稿 v0.3.0 v0.2.0 2020-07-10 PG 监控系统第六版正式发布 v0.2.0 v0.1.0 2020-06-20 在生产仿真测试环境中验证通过 v0.1.0 v0.0.5 2020-08-19 离线安装模式:无需互联网访问即可交付 v0.0.5 v0.0.4 2020-07-27 将 Ansible 剧本重构为 Role v0.0.4 v0.0.3 2020-06-22 接口设计改进 v0.0.3 v0.0.2 2020-04-30 首次提交 v0.0.2 v0.0.1 2019-05-15 概念原型 v0.0.1
v4.3.0 亮点
新增约 50 个 PostgreSQL 扩展,总可用数量达到 510 个 支持 Ubuntu 26.04 x86_64/arm64 新架构,弃用 Ubuntu 20.04 支持;小版本更新至 Debian 13.4 / Ubuntu 24.04.4 内核更新:Supabase 更新至最新版本,pgEdge 更新至 PG 18,PolarDB 更新至 PG 17 Grafana 更新至 13.0.0,MinIO 使用修复 CVE 后的 pgsty 分支。 vagrant 模板统一切换至 cloud-image 系列镜像。 问题修复
PostgreSQL 用户名校验放宽,允许 @.- 几个字符出现在用户名中。 修复 IPv6 nameserver 解析,避免 DNS 配置只匹配提取 IPv4 的旧 DNS Server。 VictoriaTraces Grafana 数据源路径改为 /select/jaeger。 Vagrant 磁盘探测更稳健,新增 EL vagrant 镜像 guest 网络修复脚本 bin/el-fix。 PostgreSQL 与扩展包变更汇总
包名 旧版本 新版本 备注 block_copy_command- 0.1.5 新增;PG 14-18;Rust/pgrx 0.17.0 cloudberry2.0.0 2.1.0 内核包组;RPM release 2 修复 initdb errno 问题 cloudberry-backup- 2.1.0 新增 Cloudberry 备份工具包 cloudberry-pxf- 2.1.0 新增 Cloudberry PXF 包 credcheck4.6 4.7 升级;PG 14-18;PGDG datasketches- 1.7.0 新增;PG 14-18 ddl_historization0.0.7 0.2 升级 documentdb0.109 0.110 升级到上游版本;PG 15-18 external_file- 1.2 新增;PG 14-18 logical_ddl- 0.1.0 新增;PG 14-18 nominatim_fdw1.1.0 1.2 升级 onesparse- 1.0.0 新增;仅 PG 18 orioledbbeta15 1.7 beta15 1.7 配套 OriolePG 17.18 oriolepg17.16 17.18 内核补丁集更新 parray_gin- 1.5.0 新增后升级;PG 14-18 pg_accumulator- 1.1.3 新增;PG 14-18 pg_anon3.0.1 3.0.13 升级;Rust/pgrx 0.16.1 -> 0.17.0 pg_background1.8 1.9.2 仅 DEB pg_bikram_sambat- 0.1.0 新增;Bikram Sambat 日期类型与 AD/BS 转换函数 pg_byteamagic- 0.2.4 新增;PG 14-18 pg_cardano1.1.1 1.2.0 升级;Rust/pgrx 0.17.0 pg_clickhouse0.1.5 0.2.0 升级 pg_datasentinel- 1.0 新增;PG 15-18 pg_dbms_job1.5 2.0 升级;PG 14-18;PGDG pg_dispatch- 0.1.5 新增;PG 14-18 pg_failover_slots1.2.0 1.2.1 升级 pg_fsql- 1.1.0 新增;PG 14-18 pg_incremental1.4.1 1.5.0 升级 pg_isok- 1.4.1 新增;PG 14-18 pg_ivm1.13 1.14 升级;PG 14-18 pg_kazsearch- 2.0.0 新增;PG 16-18;Rust/pgrx 0.17.0 pg_liquid- 0.1.7 新增;PG 14-18 pg_pathcheck- 0.9.1 新增;PG 17-18;需 shared_preload_libraries pg_query_rewrite- 0.0.5 新增;PG 14-18 pg_regresql- 2.0.0 新增;PG 14-18 pg_rrf- 0.0.3 新增;PG 14-17;Rust/pgrx 0.16.1 -> 0.17.0 pg_savior0.0.1 0.1.0 升级;高风险 DDL/DML 防护 hook;需 preload 或 LOAD pg_search0.22.2 0.23.1 升级;PG 15-18;pgrx 0.18.0 pg_slug_gen- 1.0.0 新增;PG 15-18 pg_stat_ch- 0.3.6 新增后升级;PG 16-18;EL8 break pg_store_plans1.9 1.10 升级 pg_strict1.0.3 1.0.5 升级;Rust/pgrx 0.16.1 -> 0.17.0 pg_text_semver- 1.2.1 新增;PG 14-18 pg_textsearch0.5.0 1.1.0 升级;PG 17-18;需 shared_preload_libraries pg_trickle0.16.0 0.40.0 升级;仅 PG 18;pgrx 0.18.0 pg_tzf0.2.3 0.2.4 升级;Rust/pgrx 0.17.0 pg_vectorize0.26.0 0.26.1 升级;Rust/pgrx 0.16.1 -> 0.17.0 pg_variables- 1.2.5 新增;PG 14-18 pg_when- 0.1.9 新增;PG 14-18;Rust/pgrx 0.17.0 pgxicor0.1.0 0.1.1 升级 pgcalendar- 1.1.0 新增;PG 14-18 pgclone- 4.0.0 新增后升级;PG 14-18 pgelog- 1.0.2 新增;PG 14-18 pglinter1.1.1 1.1.2 升级;Rust/pgrx 0.16.1 -> 0.17.0 pglock- 1.0.0 新增;PG 14-18 pgmq1.11.0 1.11.1 升级;PG 14-18 pgmqtt- 0.1.0 新增;PG 14-18;Rust/pgrx 0.16.1 -> 0.17.0 pgproto- 0.5.0 新增后升级;原生 Protobuf 支持 pghydro- 6.6 新增;PG 14-18 pgx_ulid0.2.2 0.2.3 升级;Rust/pgrx 0.17.0 plv83.2.4 3.2.4-2 仅 RPM;EL10 构建修复 PolarDB15.15 17.9.1.0 PG 15 -> 17 postgresbson- 2.0.2 新增;PG 14-18 postgis3.6.2 3.6.3 仅 DEB prefix1.2.10 1.2.11 升级;PG 14-18;PGDG provsql- 1.2.3 新增;PG 14-18 rdf_fdw- 2.5.0 新增后升级;PG 14-18 rdkit- 202503.6 新增;PG 14-18 re2- 0.1.1 新增;PG 16-18 storage_engine- 1.3.4 新增后升级;PG 14-18;列式与行压缩表访问方法 supautils3.1.0 3.2.1 升级 system_stats3.2 4.0 升级 timescaledb2.25.2 2.26.4 升级;TSL 小版本更新 ulak- 0.0.2 新增;PG 14-18 wrappers0.5.7 0.6.0 升级;Rust/pgrx 0.16.1 -> 0.17.0
基础设施软件包更新
包名 旧版本 新版本 备注 alertmanager0.31.1 0.32.1 agentsview0.15.0 0.26.0 claude2.1.81 2.1.123 通过 8118 代理下载并核验 code1.112.0 1.118.1 直链元数据更新 code-server4.112.0 4.117.0 直链元数据更新 codex0.116.0 0.125.0 从预发布链收敛到稳定版后继续升级 crush0.51.2 0.64.0 直链元数据更新 dblab0.34.3 0.38.0 duckdb1.5.0 1.5.2 etcd3.6.9 3.6.10 统一软件包版本 garage2.2.0 2.3.0 genai-toolbox0.27.0 1.1.0 上游已更名为 mcp-toolbox golang1.26.1 1.26.2 grafana12.4.1 13.0.1 主版本升级后继续刷新元数据 grafana-infinity-ds3.7.4 3.8.0 grafana-plugins12.3.0 13.0.0 Noarch 插件包,手工归集 grafana-victoriametrics-ds0.23.1 0.24.0 hugo0.158.0 0.161.1 maddy0.8.2 0.9.3 mcli20260321000000 20260417000000 pgsty 分支,修复 cve minio20260325000000 20260417000000 pgsty 分支,修复 cve mongodb_exporter0.49.0 0.50.0 node_exporter1.10.2 1.11.1 nodejs24.14.0 24.15.0 维持在 24.x 策略线 npgsqlrest3.11.1 3.12.0 opencode1.2.27 1.14.30 改为版本化缓存并重新构建 pg_exporter1.2.1 1.2.2 直链元数据更新 pgflo0.0.15 - 已移除 pgschema1.7.4 1.9.0 pig1.3.2 1.4.1 仅更新元信息 postgrest14.7 14.10 prometheus3.10.0 3.11.3 rainfrog0.3.17 0.3.18 rclone1.73.2 1.73.5 直链元数据更新 rustfs1.0.0-alpha.89 1.0.0-b1 预发布版本线 sabiql1.8.2 1.11.1 seaweedfs4.17 4.22 sqlcmd1.9.0 1.10.0 stalwart0.15.5 0.16.2 tigerbeetle0.16.77 0.17.2 tigerfs0.5.0 0.6.0 timescaledb-tools0.18.2 0.19.0 重新构建 timescaledb-tune uv0.10.12 0.11.8 victoria-logs1.48.0 1.50.0 主包 victoria-metrics1.138.0 1.142.0 victoria-metrics-cluster1.138.0 1.142.0 VictoriaMetrics 配套组件 victoria-traces0.8.0 0.8.2 vip-manager4.0.0 4.2.0 直链元数据更新 vlagent1.48.0 1.50.0 VictoriaLogs 配套组件 vlogscli1.48.0 1.50.0 VictoriaLogs 配套组件 vmutils1.138.0 1.142.0 VictoriaMetrics 配套组件 vector0.54.0 0.55.0 直链元数据更新 v2ray5.47.0 5.48.0 xray26.2.6 26.3.27
校验和
58a914fce7bc521b65e167f66e7961a3 pigsty-v4.3.0.tgz
9ce070efb0420057a83c632b2856d1b3 pigsty-pkg-v4.3.0.d12.aarch64.tgz
bf21c36d3aff94a1a6353130597ffa85 pigsty-pkg-v4.3.0.d12.x86_64.tgz
81b4790c4e5567cee9d1beadd06e48e6 pigsty-pkg-v4.3.0.d13.aarch64.tgz
06baab9341ab683eaeea2e066b28a0f4 pigsty-pkg-v4.3.0.d13.x86_64.tgz
fb4bf751df5e09f547c49b8ab7cac9a0 pigsty-pkg-v4.3.0.el10.aarch64.tgz
a3e752c8148122d1eaea74a6d8d8df0d pigsty-pkg-v4.3.0.el10.x86_64.tgz
cb2a9af36615513e66fd5ac3e9f4d797 pigsty-pkg-v4.3.0.el9.aarch64.tgz
e24641a879dec7a8eea74dab42f85920 pigsty-pkg-v4.3.0.el9.x86_64.tgz
6b675fd8d9e039193481f0838aa4b92c pigsty-pkg-v4.3.0.u22.aarch64.tgz
c0e344ccb9d190a619591e5d46116424 pigsty-pkg-v4.3.0.u22.x86_64.tgz
3e0ec9534cf595201ec79eb1fc6549d8 pigsty-pkg-v4.3.0.u24.aarch64.tgz
0a3d19513eca9615bdd66a4b2bf66f1d pigsty-pkg-v4.3.0.u24.x86_64.tgz
683a10ff8fd993358d6befa9f4e02913 pigsty-pkg-v4.3.0.u26.aarch64.tgz
fd1ea5cd5554bfe91fadd51ad80860e3 pigsty-pkg-v4.3.0.u26.x86_64.tgz
v4.2.2 亮点特性
Insforge 2.0.1 自建模板 Infra 软件包批量更新,MinIO/MCLI 更新至 20260321 新增 infra 软件包:tigerfs, pgstream, sql-studio, rainfog, crush 更新 PG 工具:数据恢复 pdu,连接池 pgdog 更新 PG 扩展:pg_search, pgsentinel, pg_track_optimizer, pgcollection, pg_ttl_index, pg_clickhouse 更新 PG 内核:IvorySQL 5.1 -> 5.3 PostgreSQL 软件包更新
包名 旧版本 新版本 备注 pg_search 0.21.12 0.22.2 pgsentinel 1.4.0 1.4.1 仅更新 rpm pg_track_optimizer 0.9.1 0.9.2 pgcollection 1.0.0 2.0.0 pg_ttl_index 2.0.0 3.0.0 pg_clickhouse 0.1.4 0.1.5 pdu 3.0.25.12 新增 pgdog 0.1.32 新增
基础设施软件包更新
名称 旧版本 新版本 备注 grafana12.4.0 12.4.1 pgbackrest_exporter0.22.0 0.23.0 redis_exporter1.81.0 1.82.0 victoria-logs1.47.0 1.48.0 vlagent1.47.0 1.48.0 vlogscli1.47.0 1.48.0 victoria-traces0.7.1 0.8.0 duckdb1.4.4 1.5.0 pg_timetable6.2.0 6.3.0 pgschema1.4.2 1.7.4 pgstream- 1.0.1 新增 tigerbeetle0.16.75 0.16.77 grafana-victorialogs-ds0.26.2 0.26.3 grafana-infinity-ds3.7.3 3.7.4 caddy2.11.1 2.11.2 npgsqlrest3.10.0 3.11.1 postgrest14.5 14.7 opencode1.2.17 1.2.27 pev21.20.2 1.21.0 golang1.26.0 1.26.1 vector0.53.0 0.54.0 rclone1.73.1 1.73.2 code-server4.109.5 4.112.0 code1.109.4 1.112.0 seaweedfs4.15 4.17 uv0.10.8 0.10.12 codex0.110.0 0.116.0 v2ray5.44.1 5.47.0 sabiql1.6.2 1.8.2 sql-studio- 0.1.51 新增 rainfrog- 0.3.17 新增 agentsview0.10.0 0.15.0 crush- 0.51.2 新增 tigerfs- 0.5.0 新增 victoria-metrics1.137.0 1.138.0 victoria-metrics-cluster1.137.0 1.138.0 vmutils1.137.0 1.138.0 hugo0.157.0 0.158.0 rustfs1.0.0-alpha.85 1.0.0-alpha.89 mysqld_exporter0.18.0 0.19.0 pg_exporter1.2.0 1.2.1 pig1.3.1 1.3.2 minio20260214 20260321 mcli20260213 20260321 claude2.1.68 2.1.81 ivroysql5.1 5.3
校验和
0d9f907ff626203578c687d1418b38ba pigsty-pkg-v4.2.2.d12.aarch64.tgz
4129baf773c3005f4d697cf452f927a0 pigsty-pkg-v4.2.2.d12.x86_64.tgz
40d5a0d9c2a97615bf0421bae42458ae pigsty-pkg-v4.2.2.d13.aarch64.tgz
cf91113a2296ad11fff79802ac9b1483 pigsty-pkg-v4.2.2.d13.x86_64.tgz
dbccfeb3978ffb928bd0b501c3c0d42d pigsty-pkg-v4.2.2.el10.aarch64.tgz
8c848a4e3fa93c2455285fbcad5ddd78 pigsty-pkg-v4.2.2.el10.x86_64.tgz
7c15c9a36f7d2dd740019c20e8c75a4b pigsty-pkg-v4.2.2.el9.aarch64.tgz
7d6e9e529236a0db2382f42660790ed9 pigsty-pkg-v4.2.2.el9.x86_64.tgz
8f64bb14885ce330603172b186062671 pigsty-pkg-v4.2.2.u22.aarch64.tgz
16d4c36c9e1ff848848c34a257b1025c pigsty-pkg-v4.2.2.u22.x86_64.tgz
401230741af5b04f163ffc8e688315ab pigsty-pkg-v4.2.2.u24.aarch64.tgz
5312aa0841694fc560778b9377a32c89 pigsty-pkg-v4.2.2.u24.x86_64.tgz
cabeeb898b56b26c0855f33d5e60411a pigsty-v4.2.2.tgz
v4.2.1 这是一个维护版本,新增了 3 个扩展插件,
主要变更
新增扩展 :pg_eviltransform 加入 GIS 包组,pg_pinyin 加入 FTS 包组,pg_qos 加入 Admin 包组 —— 均支持 PG 14–18。移除 PG13 :所有平台变体(EL7/8/9/10、Debian 12/13、Ubuntu 22/24,x86_64 与 aarch64)中的 pgdg13、pgdg13-nonfree 仓库条目和 PG13 包别名(pg13-*)全部移除。配置模板(fat.yml、pro.yml、dev.yml、el.yml、debian.yml)不再引用 PG13 包或仓库。扩展版本注释更新为仅覆盖 PG 14–18。 Percona 仓库 :Origin URL 从 ppg-18.1 更新为 ppg-18.3,跟踪最新 Percona PostgreSQL 发行版。Nginx 仓库 :Debian/Ubuntu 平台上 Nginx 上游 APT 仓库的模块标签从 infra 修正为 nginx。UV Venv 修复 :roles/node/tasks/pkg.yml 现在会先检查虚拟环境是否已存在,避免重复执行 uv venv 导致的冗余创建或重新置备报错。Docker 镜像 :Pigsty Docker 镜像基础包中新增 less。Demo 配置 :el.yml 和 debian.yml 示例配置的默认防火墙规则新增 5432 端口,支持直接访问 PostgreSQL。兼容性说明
PostgreSQL 13 已于 2025-11-13 到达生命周期终点 。
PGDG YUM 仓库已经归档移除 pg13 / pg12 目录。
如果您在 EL 系统上安装 Pigsty (即使没有使用 PG 13 版本),也有可能因为仓库访问失败而导致安装或更新失败。
您可以选择直接使用 Pigsty v4.2.1,或者手工修改 roles/node_id/vars/ 您对应操作系统 repo_upstream_default 变量,移除仓库定义中的 pg13 一行即可。
此外,EL8 仍然在 Pigsty 的兼容操作系统中,但从此版本开始将不再发布 el8 的离线软件包。
本版本没有其他破坏性 API 或配置变更。
7 个提交 ,84 文件变更,+4,925 / -5,351 行(v4.2.0..v4.2.1,2026-03-04 ~ 2026-03-06)
PostgreSQL 软件包更新
包名 旧版本 新版本 备注 timescaledb 2.25.1 2.25.2 vchord 1.1.0 1.1.1 新增 clang 构建依赖,修复错误 vchord_bm25 0.3.0-1 0.3.0-2 修复版本注入问题 aggs_for_vecs 1.4.0 1.4.1 pg_search 0.21.9 0.21.12 pg_pinyin - 0.0.2 新增扩展 pg_eviltransform - 0.0.2 新增扩展 pg_qos - 1.0.0 新增扩展,QoS 资源治理
基础设施软件包更新
名称 旧版本 新版本 备注 asciinema3.1.0 3.2.0 grafana-infinity-ds3.7.2 3.7.3 victoria-metrics1.136.0 1.137.0 victoria-metrics-cluster1.136.0 1.137.0 vmutils1.136.0 1.137.0 hugo0.155.3 0.157.0 opencode1.2.15 1.2.17 rustfs1.0.0-alpha.83 1.0.0-alpha.85 seaweedfs4.13 4.15 tigerbeetle0.16.74 0.16.75 uv0.10.4 0.10.8 codex0.105.0 0.110.0 claude2.1.59 2.1.68 xray- 26.2.6 新增 gost- 2.12.0 新增 sabiql- 1.6.2 新增 agentsview- 0.10.0 新增
校验和
262b7671424a38b208872582fe835ef8 pigsty-v4.2.1.tgz
62edcca1d1e572a247be018e1c26eda8 pigsty-pkg-v4.2.1.d12.aarch64.tgz
1d55367e2fd9106e6f18b7ee112be736 pigsty-pkg-v4.2.1.d12.x86_64.tgz
f122b1e5ba8a7ae8e3dc6e6dd53eba65 pigsty-pkg-v4.2.1.d13.aarch64.tgz
617a76bfc8df8766e78abf24339152eb pigsty-pkg-v4.2.1.d13.x86_64.tgz
908509b350403ad1a4a27a88795fee06 pigsty-pkg-v4.2.1.el10.aarch64.tgz
70cb4afd90ed7aea6ab43a264f8eb4a8 pigsty-pkg-v4.2.1.el10.x86_64.tgz
98fbd67334f5c674b12e6af81ef76923 pigsty-pkg-v4.2.1.el9.aarch64.tgz
687fa741ccd9dcf611a2aa964bcf1de8 pigsty-pkg-v4.2.1.el9.x86_64.tgz
a2a30f4b1146b3e79be91d5be57615b6 pigsty-pkg-v4.2.1.u22.aarch64.tgz
7a1f571bd8526106775c175ba728eee1 pigsty-pkg-v4.2.1.u22.x86_64.tgz
a5574071bac1955798265f71ad73c3d4 pigsty-pkg-v4.2.1.u24.aarch64.tgz
59a7632c650a3c034f1fe6cd589d7ab5 pigsty-pkg-v4.2.1.u24.x86_64.tgz
v4.2.0 亮点特性
离线小版本跟进 PostgreSQL 紧急小版本:18.3、17.9、16.13、15.17、14.22。 PostgreSQL 扩展总数达到 461 个。 PG 内核更新:Babelfish、AgensGraph、pgEdge、OriolePG、OpenHalo、Cloudberry。 Babelfish 模板切换到 Pigsty 自建维护的 PG17 兼容版本,移除对 WiltonDB 仓库的依赖。 更新 Supabase 镜像与自建模板至最新版本,使用自行维护的 MinIO 分支 pgsty/minio 主要变更
mssql 模板切换到 Babelfish PG17 默认:pg_version: 17,pg_packages: [babelfish, pgsql-common, sqlcmd],并移除额外 mssql repo 依赖。pg_home_map 调整:mssql 指向 /usr/babelfish-$v/,gpsql 指向 /usr/local/cloudberry,统一内核路径语义。package_map 新增 cloudberry 独立映射,并修复 babelfish* 组件别名到版本化包名(RPM/DEB)。Redis 默认主目录从 /data 调整为 /data/redis;部署阶段阻止旧默认值继续使用,redis_remove 增加旧路径兼容清理。 configure 支持 -o 绝对路径输出并自动建目录;区域探测改为三态(境内/境外/离线回退),修复 behind_gfw() 卡住问题。修复 Debian/Ubuntu 默认仓库 URL(updates/backports/security 对应关系)与中国区镜像组件字段,避免节点初始化拉包失败。 Supabase 应用栈例行升级(含 PostgREST 14.5、Vector 0.53.0 等)并补齐 S3 协议访问密钥变量。 Rich/Sample 模板显式补全 dbuser_meta 默认值;node.sh 中 systemd 自动补全逻辑简化。 pgbackrest 初始化增加重试(2 次、间隔 5 秒),缓解 stanza-create 与 archive-push 锁竞争失败。Vibe 模板更新:内置 @anthropic-ai/claude-code、@openai/codex、happy-coder 等 npm 工具,默认示例补入 age 扩展。 PG 软件更新
PostgreSQL 18.3, 17.9, 16.13, 15.17, 14.22 RPM Changelog 2026-02-27 DEB Changelog 2026-02-27 核心升级:timescaledb 2.25.0 -> 2.25.1,citus 14.0.0-3 -> 14.0.0-4,pg_search -> 0.21.9 新增/重建:pgedge 17.9,spock 5.0.5,lolor 1.2.2,snowflake 2.4,babelfish 5.5.0,cloudberry 2.0.0 内核配套:oriolepg 17.11 -> 17.16,orioledb beta12 -> beta14,openhalo 14.10 -> 1.0(14.18) 包名 旧版本 新版本 备注 timescaledb2.25.0 2.25.1 citus14.0.0-3 14.0.0-4 使用最新官方版本重新构建 age1.7.0 1.7.0 新增 PG 17 的 1.7.0 版本支持 pgmq1.10.0 1.10.1 当前没有该扩展包 pg_search0.21.7 / 0.21.6 0.21.9 RPM/DEB 旧版本不同 oriolepg17.11 17.16 OriolePG 内核更新 orioledbbeta12 beta14 配套 OriolePG 17.16 openhalo14.10 1.0 更新并重命名,14.18 pgedge- 17.9 新增多主边缘分布式内核 spock- 5.0.5 新增,pgEdge 核心扩展 lolor- 1.2.2 新增,pgEdge 核心扩展 snowflake- 2.4 新增,pgEdge 核心扩展 babelfishpg- 5.5.0 新增 BabelfishPG 包组 babelfish- 5.5.0 新增 Babelfish 兼容包 antlr4-runtime413- 4.13 新增 Babelfish 依赖运行时 cloudberry- 2.0.0 仅 RPM 构建 pg_background- 1.8 仅 DEB 构建
基础设施软件更新
名称 旧版本 新版本 grafana12.3.2 12.4.0 prometheus3.9.1 3.10.0 mongodb_exporter0.47.2 0.49.0 victoria-metrics1.135.0 1.136.0 victoria-metrics-cluster1.135.0 1.136.0 vmutils1.135.0 1.136.0 victoria-logs1.45.0 1.47.0 vlagent1.45.0 1.47.0 vlogscli1.45.0 1.47.0 loki3.6.5 3.6.7 promtail3.6.5 3.6.7 logcli3.6.5 3.6.7 grafana-victorialogs-ds0.24.1 0.26.2 grafana-victoriametrics-ds0.21.0 0.23.1 grafana-infinity-ds3.7.0 3.7.2 redis_exporter1.80.2 1.81.0 etcd3.6.7 3.6.8 dblab0.34.2 0.34.3 tigerbeetle0.16.72 0.16.74 seaweedfs4.09 4.13 rustfs1.0.0-alpha.82 1.0.0-alpha.83 uv0.10.0 0.10.4 kafka4.1.1 4.2.0 npgsqlrest3.7.0 3.10.0 postgrest14.4 14.5 caddy2.10.2 2.11.1 rclone1.73.0 1.73.1 pev21.20.1 1.20.2 genai-toolbox0.25.0 0.27.0 opencode1.1.59 1.2.15 claude2.1.37 2.1.59 codex0.104.0 0.105.0 code1.109.2 1.109.4 code-server4.108.2 4.109.2 nodejs24.13.1 24.14.0 pig1.1.2 1.3.0 stalwart- 0.15.5 maddy- 0.8.2
API 变化
pg_mode 增加 agens 与 pgedge。mssql 默认配置改为 pg_version: 17 + pg_packages: [babelfish, pgsql-common, sqlcmd]。pg_home_map 与 package_map 的内核/包别名映射更新(Babelfish / OpenHalo / IvorySQL / Cloudberry / pgEdge 家族)。redis_fs_main 默认值改为 /data/redis,并新增部署保护与移除兼容策略。configure 输出路径与区域探测逻辑更新,增加离线回退告警;SSH 探测统一超时参数。grafana.ini.j2 跟进 Grafana 12.4 新配置项与废弃项调整。兼容性说明
存量 Redis 配置如果仍使用 redis_fs_main: /data,请先改为 /data/redis 再执行部署。 Grafana 12.4 后 data link 合并行为变化,本版本已将关键链接下沉到字段 override 规避冲突;如有自定义看板,建议同步检查。 26 个提交 ,122 文件变更,+2,116 / -2,215 行(v4.1.0..v4.2.0,2026-02-15 ~ 2026-02-28)
校验和
24a90427a7e7351ca1a43a7d53289970 pigsty-v4.2.0.tgz
d980edf5eeb0419d4f1aa7feb0100e14 pigsty-pkg-v4.2.0.d12.aarch64.tgz
24bc237d841457fbdcc899e1d0a3f87e pigsty-pkg-v4.2.0.d12.x86_64.tgz
e395b38685e2ecbe9c3a2850876d9b7b pigsty-pkg-v4.2.0.d13.aarch64.tgz
c5c8776f9bead9f29528b26058801f83 pigsty-pkg-v4.2.0.d13.x86_64.tgz
28ea40434bd06135fc8adc0df1c8407d pigsty-pkg-v4.2.0.el10.aarch64.tgz
58ad715ac20dc1717d1687daecfcf625 pigsty-pkg-v4.2.0.el10.x86_64.tgz
008f955439ea311581dd0ebcf5b8bd34 pigsty-pkg-v4.2.0.el8.aarch64.tgz
2acfd127a517b09f07540f808fe9547a pigsty-pkg-v4.2.0.el8.x86_64.tgz
58e62a92f35291a40e3f05839a1b6bc4 pigsty-pkg-v4.2.0.el9.aarch64.tgz
d311bfdf5d5f60df5fe6cb3d4ced4f9c pigsty-pkg-v4.2.0.el9.x86_64.tgz
c98972fe9226657ac1faa7b72a22498b pigsty-pkg-v4.2.0.u22.aarch64.tgz
44a174ee9ba030ac1ea386cf0b85f6e7 pigsty-pkg-v4.2.0.u22.x86_64.tgz
143e404f4681c7d0bbd78ef7982cd652 pigsty-pkg-v4.2.0.u24.aarch64.tgz
00dfa86f477f3adff984906211ab3190 pigsty-pkg-v4.2.0.u24.x86_64.tgz
v4.1.0 curl https://pigsty.cc/get | bash -s v4.1.0
72 个提交 ,252 文件变更,+5,744 / -5,015 行(v4.0.0..v4.1.0,2026-02-02 ~ 2026-02-13)
亮点特性
新增 7 个扩展,总计 451 个扩展支持。 pig 从传统脚本接口升级为 Agent-Native CLI (1.0.0 -> 1.1.0),支持主动暴露上下文并提供 JSON/YAML 输出。pig 新增 PostgreSQL / OS 大小版本更新 统一能力(覆盖 major/minor 升级流程)。pg_exporter 升级到 v1.2.0 (1.1.2 -> 1.2.0),并修复 PG17/18 指标链路与单位换算。防火墙默认安全策略更新:node_firewall_mode 默认改为 zone,node_firewall_public_port 默认从 [22,80,443,5432] 收敛为 [22,80,443]。 PostgreSQL 小版本更新:18.2、17.8、16.12、15.16、14.21。 EL 默认小版本更新到 EL 9.7 / EL 10.1,Debian 默认小版本更新到 12.13 / 13.3。 集中修复 PGSQL / PGCAT Grafana 看板可用性:$dsn 动态数据源、schema 级跳转、Age 指标、链接映射与语义一致性。 新增 Mattermost 一键应用模板,支持数据库、目录、门户与可选 PGFS/JuiceFS 方案。 重构 infra-rm 卸载逻辑,新增 deregister 分段清理能力,可回收 Victoria target、Grafana datasource、Vector 日志配置。 优化 PostgreSQL 默认 autovacuum 阈值,减少小表高频 vacuum/analyze。 修复 FD 上限链路:新增 fs.nr_open=8M 并统一 LimitNOFILE=8M,避免 systemd/setrlimit 导致服务启动失败。 调整 Vibe 默认体验:Jupyter 默认关闭,Claude Code 改由 npm 包统一安装管理。 版本更新
Pigsty 版本:v4.0.0 -> v4.1.0 pig CLI:1.0.0 -> 1.1.0(Agent-Native + 大小版本更新支持)pg_exporter:1.1.2 -> 1.2.0默认 EL 小版本:9.6/10.0 -> 9.7/10.1 默认 Debian 小版本:12.12/13.1 -> 12.13/13.3 扩展更新
RPM Changelog 2026-02-12 DEB Changelog 2026-02-12 timescaledb 2.24.0 -> 2.25.0 pg_search 0.21.4 -> 0.21.7 pgmq 1.9.0 -> 1.10.0 pg_textsearch 0.4.0 -> 0.5.0 pljs 1.0.4 -> 1.0.5 pg_track_optimizer 0.9.1(新增) nominatim_fdw 1.1.0(新增) pg_utl_smtp 1.0.0(新增) pg_strict 1.0.2(新增) pgmb 1.0.0(新增) pg_pwhash(新增支持) informix_fdw(新增支持) INFRA 组件版本
Infra Changelog 2026-02-12
软件包 版本 软件包 版本 victoria-metrics 1.135.0 victoria-logs 1.45.0 vector 0.53.0 grafana 12.3.2 alertmanager 0.31.1 etcd 3.6.7 duckdb 1.4.4 pg_exporter 1.2.0 pig 1.1.0 claude 2.1.37 opencode 1.1.59 uv 0.10.0 code-server 4.108.2 caddy 2.10.2 hugo 0.155.2 cloudflared 2026.2.0 headscale 0.28.0
API 变化
io_method / io_workers 模板生效条件从 pg_version >= 17 更正为 pg_version >= 18。idle_replication_slot_timeout / initdb --no-data-checksums 的 PG18 守卫条件修正。maintenance_io_concurrency 生效范围放宽至 PG13+。autovacuum_vacuum_threshold:oltp/crit/tiny 从 50 提升到 500,olap 提升到 1000。autovacuum_analyze_threshold:oltp/crit/tiny 从 50 提升到 250,olap 提升到 500。checkpoint_completion_target 默认从 0.90 提升到 0.95。Node tuned 模板新增 fs.nr_open=8388608,并统一 fs.file-max / fs.nr_open / LimitNOFILE 层级关系。 postgres、patroni、minio 的 systemd LimitNOFILE 从 16777216 调整为 8388608。 node_sysctl_params 默认加入 fs.nr_open: 8388608。node_firewall_mode 默认值从 none 调整为 zone:默认启用防火墙,内网信任,公网仅开放 node_firewall_public_port;如需完全自管防火墙请设为 none。node_firewall_public_port 默认值从 [22,80,443,5432] 调整为 [22,80,443],数据库端口 5432 需要按需显式添加。注意防火墙规则为“只增不删”,存量节点若已放行 5432 需手工移除;单机体验模板(如 meta / vibe)会显式覆盖并保留 5432 以便远程使用。bin/validate 新增 pg_databases[*].parameters 与 pg_hba_rules[*].order 校验支持,并修复 HBA 错误未正确返回失败的问题。infra-rm.yml 新增 deregister、config、env 等分段标签。Vibe 默认 jupyter_enabled=false,npm_packages 默认加入 @anthropic-ai/claude-code、happy-coder,并新增 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。 PgBouncer 参数别名收敛:pool_size_reserve -> pool_reserve,pool_max_db_conn -> pool_connlimit。 兼容性修复(去重归并)
注:同一问题的重复回补(反复引入后再次修复)仅计一次,以下按问题域归并。 修复 Redis replicaof 判空逻辑与 systemd 停止行为。 修复 pg_migration 脚本 schema/table/sequence 全限定、标识符 quoting 与日志格式字符串安全问题。 修复 pgsql role handler 重启对象与变量使用错误。 修复 blackbox 配置文件名清理项与 pgAdmin pgpass 文件格式。 pg_exporter 启动改为非阻断,避免 exporter 启动失败拖慢主流程。VIP 地址解析逻辑简化,未显式 CIDR 时默认掩码 24。 MinIO 健康检查重试从 3 提升到 5。 节点主机名设置改用 hostname 模块,替代 shell 调用。 修复 app/electric 与 app/pg_exporter 的 .env 格式为标准 KEY=VALUE。 修复 pigsty.yml 的 pg_crontab 语法错误。 更新 ETCD 文档,明确默认 TLS 与可选 mTLS 的语义差异。 修复 repo-add 参数传递、Debian 中国镜像组件兼容性、bin/psql.py 的 Python3 兼容性。 加固 redis exporter 凭据文件权限,减少敏感信息暴露风险。 pgsql-user.yml 隐藏用户凭据日志输出并对敏感步骤启用 no_log。修复 pg_monitor 注册 Victoria target 的 gate 条件。 pg_remove 备份清理改为集群级目录,避免误删其他集群备份。提交清单(v4.0.0..v4.1.0,共 72,2026-02-02 ~ 2026-02-13)
7410de401 v4.1.0 release
fa31213ce conf(node): default firewall to zone with single-node 5432 override
bb8382c58 update default extension list to 451
770d01959 hide user credential in pgsql-user playbook
7219a896c pg_monitor: fix victoria registration gate conditions
084c98432 remove one cluster in backup dir during pg_remove
7005617f1 pgsql: drop legacy pgbouncer pool parameter aliases
f8165a886 docs(roles): fix typos and align juice role documentation
06a589218 chore(meta): normalize platform versions for current lint schema
e0a208248 fix(roles): harden redis exporter file permissions
fd0469881 terraform/vagrant: parameterize aliyun region/zone, fix vagrant scripts
74c59aabe grafana: fix dashboard links, descriptions, and overrides
443e58724 conf: clean legacy params and fix template references
536c4b39d adjust grafana dashboard dead links
f3b9866ce grafana(pgsql): fix panel typos and title consistency
bcb69be11 grafana(pgsql): fix drilldown links and variable mappings
1ce4374a1 grafana: fill pglog panel titles and normalize wording
2d127f9f4 grafana: fix minio traffic metrics and pigsty dashboard links
9d3ca0118 grafana: align victoria instance dashboards with query scope
55bc61622 grafana: fix infra dashboard copy, links, and table semantics
607b75535 grafana(node): fix panel drilldown links and clean dashboard metadata
1321de532 grafana(redis): fix dashboard links and blocked-clients panel semantics
91e0c8437 fix(grafana): correct Redis alert drill-down dashboard links
0fde78c02 fix(tooling): improve Python3 compatibility and enforce vagrant scale lower bound
fa3454a52 fix(bootstrap): use Debian-compatible components for CN apt mirror
36c95c749 fix(cli): restore repo-add execution and HBA validation failure propagation
797385929 add macbook local vagrant image override
f9c928e32 fix(grafana): restore reverted dashboard bugfixes
c11af8b6a Bump version to v4.1.0
307a236ba update extension list
f17024807 override el9/u24 vagrant box for convient testing
c2ada1283 terraform: bump Aliyun Debian images to 12.13/13.3
25bd8210f fix(node): add daemon_reload to systemd tasks for keepalived, chronyd, and cron
6f2576fd0 fix(node): set default fs.nr_open via node_sysctl_params
43a71245e add pg_bgwriter_buffers_backend for pg 17-
da832a47b fix(monitor): keep checkpointer metrics for checkpoint stats
90434ca8a fix(monitor): add pg_bgwriter fallback for checkpointer metrics
e2d75e787 fix(monitor): use pg_checkpointer metrics for checkpoint stats
a0b7474f8 fix grafana dashboard metrics and lengend
27ddacbc6 vagrant: refresh box selector and OS shortcuts
26e108788 fix(monitor): correct unit for time metrics scaled by pg_exporter
ee90044b5 fix(pgsql): correct min_parallel scan size params in oltp/crit templates
d439464b2 pgsql: fix pg_version guards for PG18-only settings
26320f120 docs: recommend RockyLinux 10.1
1e9b9f33a terraform: bump Aliyun Rocky images to 9.7/10.1
d6e9c7122 monitor: optimize table/index bloat estimators
42d45d32e fix(grafana): align panel semantics across node/infra/redis
3972d2c45 fix(grafana/pgsql): align dashboard semantics for query monitoring
cb52375ac bump checkpoint_completion_target from 0.90 to 0.95
13115a95d fix legend in pgsql-persist checkpoint panel
102cd2edb fix(pg_migration): make template logging format-safe
c402f0e6d fix: correct io_method/io_workers version guard from PG17 to PG18
3bf676546 vibe: disable jupyter by default and install claude-code via npm_packages
613c4efa9 fix: set fs.nr_open in tuned profiles and reduce LimitNOFILE to 8M
07e499d4d new app conf template matter most
4cc68ed61 Refine infra removal playbook
7cfb98f69 fix: app docker .env file format
9b36b1875 Fix config templates and validation
318d85e6e Simplify VIP parsing and make pg_exporter non-blocking
571cd9e70 Use hostname module for nodename
de98f073c Fix blackbox config filename and pgpass format
4bff01100 Fix redis replicaof guard and systemd stop
38445b68d minio: increase health check retries
c99854969 docs(etcd): clarify TLS vs mTLS
41229124a fix pgsql roles typo
e575d17c6 fix pg_migration scripts to use fully qualified identifiers
ec4207202 fix pgsql-schema broken links
a237e6c99 tune autovacuum threshold to reduce small table vacuum frequency
e80754760 fix pgcat-database links to pgcat-table https://github.com/pgsty/pigsty/issues/690
0060f5346 fix pgsql-database / pgsql-databases age metric fix https://github.com/pgsty/pigsty/issues/695
43cdf72bc fix pigsty.yml typo
0d9db7b08 fix: update datasource to $dsn - fix https://github.com/pgsty/pigsty/issues/692#issuecomment-3835461620
致谢
感谢 @l2dy 为本项目提出诸多改进意见与 Issue。 校验和
8bc75e8df0e3830931f2ddab71b89630 pigsty-v4.1.0.tgz
da10de99d819421630f430d01bc9de62 pigsty-pkg-v4.1.0.d12.aarch64.tgz
e1f2ed2da0d6b8c360f9fa2faaa7e175 pigsty-pkg-v4.1.0.d12.x86_64.tgz
382bb38a81c138b1b3e7c194211c2138 pigsty-pkg-v4.1.0.d13.aarch64.tgz
13ceaa728901cc4202687f03d25f1479 pigsty-pkg-v4.1.0.d13.x86_64.tgz
92d061de4d495d05d42f91e4283e7502 pigsty-pkg-v4.1.0.el10.aarch64.tgz
be629ea91adf86bbd7e1c59b659d0069 pigsty-pkg-v4.1.0.el10.x86_64.tgz
c14be706119ba33dd06c71dda6c02298 pigsty-pkg-v4.1.0.el8.aarch64.tgz
0c8b6952ffc00e3b169896129ea39184 pigsty-pkg-v4.1.0.el8.x86_64.tgz
cfcc63b9ecc525165674f58f9365aa19 pigsty-pkg-v4.1.0.el9.aarch64.tgz
34f733080bfa9c8515d1573c35f3e870 pigsty-pkg-v4.1.0.el9.x86_64.tgz
ad52ce9bf25e4d834e55873b3f9ada51 pigsty-pkg-v4.1.0.u22.aarch64.tgz
300b2185c61a03ea7733248e526f3342 pigsty-pkg-v4.1.0.u22.x86_64.tgz
2e561e6ae9abb14796872059d2f694a8 pigsty-pkg-v4.1.0.u24.aarch64.tgz
c462bb4cb2359e771ffcad006888fbd4 pigsty-pkg-v4.1.0.u24.x86_64.tgz
v4.0.0 curl https://pigsty.cc/get | bash -s v4.0.0
318 个提交 ,604 文件变更,+118,655 / -327,552 行,发布页面: https://github.com/pgsty/pigsty/releases/tag/v4.0.0
亮点特性
可观测性革命 :Prometheus → VictoriaMetrics(10x 性能提升),Loki + Promtail → VictoriaLogs + Vector安全加固 :自动生成强密码、etcd RBAC、防火墙/SELinux 模式、权限收紧、Nginx Basic Auth容器支持 :支持在 Docker 容器中运行 Pigsty 本身新增模块 :JUICE,提供将 PG 挂载为文件系统并进行 PITR 的能力新增模块 :VIBE,提供 Claude Code、JupyterLab、VS Code Server、Node.js 的配置与可观测性数据库管理 : pg_databases state(create/absent/recreate)、strategy 瞬间克隆数据库PITR 与分叉 : /pg/bin/pg-fork CoW 瞬间克隆、pg-pitr 增强支持 PITR 前备份高可用增强 : pg_rto_plan 提供四档 RTO 预置参数(fast/norm/safe/wide),pg_crontab 定时任务多云 Terraform :AWS、Azure、GCP、Hetzner、DigitalOcean、Linode、Vultr、腾讯云模板许可证变更 :AGPL-3.0 → Apache-2.0基础设施软件包更新
MinIO 开始使用 pgsty/minio fork RPM/DEB
软件包 版本 软件包 版本 victoria-metrics 1.134.0 victoria-logs 1.43.1 vector 0.52.0 grafana 12.3.1 alertmanager 0.30.1 etcd 3.6.7 duckdb 1.4.4 pg_exporter 1.1.2 pgbackrest_exporter 0.22.0 blackbox_exporter 0.28.0 node_exporter 1.10.2 minio 20251203 pig 1.0.0 claude 2.1.19 opencode 1.1.34 uv 0.9.26 asciinema 3.1.0 prometheus 3.9.1 pushgateway 1.11.2 juicefs 1.4.0 code-server 4.100.2 caddy 2.10.2 hugo 0.154.5 cloudflared 2026.1.1 headscale 0.27.1
新增模块
JUICE 模块 :JuiceFS 分布式文件系统,使用 PostgreSQL 作为元数据引擎,支持利用 PITR 恢复文件系统VIBE 模块 :AI 辅助编程沙箱环境(整合了 Code-Server、JupyterLab、Node.js 与 Claude Code)Code-Server:浏览器中的 VS Code JupyterLab:交互式计算环境 Node.js:JavaScript 运行时环境 Claude Code:AI 编程助手 CLI 配置,内置 OpenTelemetry 可观测性 PostgreSQL 扩展
新扩展 : pg_textsearch 0.4.0, pg_clickhouse 0.1.3, pg_ai_query 0.1.1, etcd_fdw , pg_ttl_index 0.1.0, pljs 1.0.4, pg_retry 1.0.0, pg_weighted_statistics 1.0.0, pg_enigma 0.5.0, pglinter 1.0.1, documentdb_extended_rum 0.109, mobilitydb_datagen 1.3.0
重要更新 :timescaledb 2.24.0, pg_search 0.21.4, citus 14.0.0, documentdb 0.109, age 1.7.0, pg_duckdb 1.1.1, vchord 1.0.0, vchord_bm25 0.3.0, pg_biscuit 2.2.2, pg_anon 2.5.1, wrappers 0.5.7, pg_vectorize 0.26.0, pg_session_jwt 0.4.0, pg_partman 5.4.0, pgmq 1.9.0, pg_bulkload 3.1.23, pg_timeseries 0.2.0, pg_convert 0.1.0, pgBackRest 2.58
破坏性变更
可观测性栈
旧组件 新组件 Prometheus VictoriaMetrics Loki VictoriaLogs Promtail Vector
参数变更
移除 替代 node_disable_firewallnode_firewall_mode (off/none/zone)node_disable_selinuxnode_selinux_mode (disabled/permissive/enforcing)pg_pwd_enc已移除,统一使用 scram-sha-256 infra_pip_packagesnode_pip_packagescode_home/jupyter_homevibe_data
默认值变更
参数 变化 grafana_cleantrue → false effective_io_concurrency1000 → 200 install.yml重命名为 deploy.yml
可观测性
使用全新的 VictoriaMetrics 替代 Prometheus,用几分之一的资源实现数倍的性能 使用全新的日志收集方案:VictoriaLogs + Vector,取代 Promtail + Loki 统一调整了所有组件的日志格式,PG 日志使用 UTC 时间戳(log_timezone) 调整了 PostgreSQL 日志的轮换方式,使用按周循环截断日志轮转模式 在 PG 日志中记录超过 1MB 的临时文件分配,在特定模版中启用 PG 17/18 日志新参数 新增了 Nginx / Syslog / PG CSV / Pgbackrest / Grafana / Redis / etcd / MinIO 等日志的 Vector 解析配置 注册数据源现在会在所有 Infra 节点上进行,Victoria 数据源将自动注册入 Grafana 新增 grafana_pgurl 参数,允许指定 Grafana 使用 PG 作为后端存储元数据库 新增 grafana_view_password 参数,指定 Grafana Meta 数据源使用的密码 pgbackrest_exporter 的默认选项现在设置 120 秒的内部缓存间隔(原本为 600s)grafana_clean 参数的默认值现在由 true 改为 false,即默认不清除新增指标收集器 pg_timeline,收集更实时的时间线指标 pg_timeline_id pg_exporter 更新至 1.1.2,新增 pg_timeline 采集器,修复大量历史遗留问题新增 node-vector 仪表盘,监控 Vector 日志收集器状态 新增 node-juice 仪表盘,监控 JuiceFS 分布式文件系统状态 新增 claude-code 仪表盘,监控 Claude Code AI 编程助手使用情况 PGSQL Cluster/Instance 仪表盘新增版本横幅显示 所有仪表盘使用 compact JSON 格式,大幅减少文件体积 接口改进
install.yml 剧本现在重命名为 deploy.yml 以更符合语义新增 vibe.yml 剧本,用于部署 VIBE AI 编程沙箱环境 pg_databases 数据库制备功能改进添加删库能力:可以使用 state 字段指定 create, absent, recreate 三种状态 添加克隆能力:数据库定义中使用 strategy 参数指定克隆方法 支持较新版本引入的 locale 配置参数:locale_provider,icu_locale,icu_rules,builtin_locale 支持 is_template 参数,将数据库标记为模板数据库 添加了更多类型检查,避免了字符类参数的注入 允许在 extension 中指定 state: absent 以删除扩展 pg_users 用户制备功能改进,新增参数 admin,类似 roles,但是带有 ADMIN OPTION 权限可以转授pg_hba 支持 order 字段,允许指定 HBA 规则的排序优先级,支持 IPv6 的 localhost 访问新增 infra_extra_services 参数用于首页额外服务入口导航 参数优化
pg_io_method 参数:auto, sync, worker, io_uring 四种方式可选,默认 workermaintenance_io_concurrency 设置为 100(如果使用 SSD)effective_io_concurrency 从 1000 减小为 200file_copy_method 参数为 PG18 默认设置为 clone,提供瞬间克隆数据库的能力idle_replication_slot_timeout 默认 7d,crit 模板 3dlog_lock_failures:oltp, crit 模版开启track_cost_delay_timing:olap, crit 模版开启log_connections:oltp/olap 开启认证日志,crit 开启全部日志新增 pg_rto_plan 参数,整合 Patroni 与 HAProxy 的 RTO 相关配置(fast/norm/safe/wide) pg_crontab 参数:为 postgres dbsu 配置定时任务对于 PG17+,如果 pg_checksums 开关关闭,在 Patroni 初始化集群时显式禁用校验和 Crit 模板启用 Patroni 严格同步模式 PITR 默认 archive_mode 改为 preserve,确保恢复后保留归档能力 pg-pitr 支持恢复前自动备份数据修复了 duckdb.allow_community_extensions 总是生效的问题 允许通过 node_firewall_intranet 指定 HBA 信任的 “内网网段” 现在 pg_hba 与 pgbouncer_hba 支持 IPv6 的 localhost 访问 架构改进
在 Infra 节点上,设置固定的 /infra 软连接指向 Infra 数据目录 /data/infra 现在 Infra 的数据默认放置于 /data/infra 目录下,这使得在容器中使用更为便利 本地软件仓库现在放置于 /data/nginx/pigsty,/www 现在作为软链接指向 /data/nginx 确保兼容 DNS 解析记录现在放置于 /infra/hosts 目录下,解决了 Ansible SELinux 竞态问题 默认首页域名从 h.pigsty 更名为 i.pigsty,新增中文首页支持 新增了 /pg/bin/pg-fork 脚本,用于快速创建 CoW 副本数据库实例 调整 /pg/bin/pg-pitr 脚本,现在可以用于实例级别的 PITR 恢复,支持恢复前自动备份 新增 /pg/bin/pg-drop-role 脚本,用于安全删除用户角色 新增 bin/pgsql-ext 脚本,用于安装 PostgreSQL 扩展 恢复 pg-vacuum 和 pg-repack 脚本 新增剧本 juice.yml:部署 JuiceFS 分布式文件系统实例 新增剧本 vibe.yml:部署 VIBE AI 编程沙箱环境(含 Code-Server、JupyterLab、Claude Code) 显式安装 cron/cronie 包,确保定时任务功能在最小化安装的系统上可用 UV Python 包管理器从 infra 模块迁移至 node 模块,新增 node_uv_env 参数指定虚拟环境路径 pg_remove/pg_pitr 移除 etcd 元数据的任务,现在不再依赖 admin_ip 管理节点,而在 etcd 集群上执行36 节点仿真模板 simu 简化为 20 节点的版本 适配上游变化,移除 PGDG sysupdate 仓库,移除 EL 系统上所有 llvmjit 的相关包 为 EPEL 10 / PGDG 9/10 仓库使用操作系统完整版本号(major.minor) 允许在仓库定义中指定 meta 参数,覆盖 yum 仓库的定义元数据 确保 Vagrant libvirt 模板默认带有 128GB 磁盘,以 xfs 挂载于 /data 确保 pgbouncer 不再将 0.0.0.0 监听地址修改为 * 新增 10 节点、Citus 等 Vagrant 配置模板 恢复 EL7 系统兼容性支持 多云 Terraform 模板:AWS、Azure、GCP、Hetzner、DigitalOcean、Linode、Vultr、腾讯云 安全改进
configure 现在支持 -g 参数自动生成随机强密码,避免使用默认密码带来的安全隐患更改了 MinIO 模块的默认密码,避免与众所周知的默认密码冲突 移除 node_disable_firewall,新增 node_firewall_mode,支持 off, none, zone 三种模式 移除 node_disable_selinux,新增 node_selinux_mode,支持 disabled, permissive, enforcing 三种模式 为 HAProxy、Nginx、DNSMasq、Redis 等组件配置了正确的 SELinux 上下文 启用了针对 etcd 的 RBAC,每个集群现在只能管理自己的 PostgreSQL 数据库集群 etcd root 密码现在放置于 /etc/etcd/etcd.pass 文件中,仅对管理员可读 将 admin_ip 添加到 Patroni API 允许访问的 IP 列表白名单中 总是创建 admin 系统用户组,patronictl 配置收紧为仅限 admin 组用户访问 新增 node_admin_sudo 参数,允许指定/调整数据库管理员的 sudo 权限模式(all/nopass) 收回了所有非 root 用户对可执行脚本的拥有权限 新增 Nginx Basic Auth 支持,可以为 Nginx Server 设置可选的 HTTP Basic Auth 修复 ownca 证书有效期问题,确保了 Chrome 可以识别自签名证书 新增 vip_auth_pass 参数用于 VRRP 认证 修复了若干 ansible copy content 字段为空时报错的问题 修复了 pg_pitr 中遗留的一些问题,确保 Patroni 集群恢复时没有竞态条件 使用 mode 0700 保护 files/pki/ca 目录 问题修复
修复 ownca 证书有效期 Chrome 兼容性问题 修复 Vector 0.52 syslog_raw 解析问题 修复 pg_pitr 多副本 clonefrom 时序问题 修复 Ansible SELinux dnsmasq 竞态条件 修复 EL9 aarch64 patroni & llvmjit 问题 修复 Debian groupadd 路径问题 修复空 sudoers 文件生成问题 修复 pgbouncer pid 路径(/run/postgresql) 修复 duckdb.allow_community_extensions 始终生效问题 因上游问题隐藏 EL8 上的 pg_partman 扩展 修复 HAProxy 服务模板变量路径 修复 Redis remove 任务变量名 移除 MinIO reload handler 无效处理器 修正 vmetrics_port 默认值为 8428 修复 pg-failover-callback 脚本处理所有 Patroni 回调事件 修复 pg-vacuum 事务块处理逻辑 添加 PG16+ 并行逻辑复制支持 修复 FerretDB 证书配置和服务重启策略 修正 Polar Exporter 监控指标类型定义 修复代理环境变量未传递问题 修复移除模式下 postgres 服务配置 更新 Docker 默认数据目录路径 修复 EL10 系统上的缓存问题 修复 etcd/MinIO 移除时 systemd 服务和 DNS 条目清理 新增参数
参数 类型 默认值 说明 node_firewall_modeenum none (v4.0) 防火墙模式:off/none/zone(v4.1 起默认 zone) node_selinux_modeenum permissive SELinux 模式 node_firewall_intranetstring - HBA 信任的内网网段 node_admin_sudoenum nopass 管理员 sudo 权限级别 pg_io_methodenum worker I/O 方法:auto/sync/worker/io_uring pg_rto_plandict - RTO 预设:fast/norm/safe/wide pg_crontablist [] postgres dbsu 定时任务 vip_auth_passstring - VRRP 认证密码 grafana_pgurlstring - Grafana PG 后端连接字符串 grafana_view_passwordstring DBUser.Viewer Grafana Meta 数据源密码 infra_extra_serviceslist [] 首页额外服务入口 juice_cachepath /data/juice JuiceFS 共享缓存目录 juice_instancesdict {} JuiceFS 实例定义 vibe_datapath /fs VIBE 工作空间目录 code_enabledbool true 是否启用 Code-Server code_portport 8443 Code-Server 监听端口 code_datapath /data/code Code-Server 数据目录 code_passwordstring Vibe.Coding Code-Server 登录密码 code_galleryenum openvsx 扩展市场:openvsx/microsoft jupyter_enabledbool true 是否启用 JupyterLab jupyter_portport 8888 JupyterLab 监听端口 jupyter_datapath /data/jupyter JupyterLab 数据目录 jupyter_passwordstring Vibe.Coding JupyterLab 登录 Token jupyter_venvpath /data/venv Python 虚拟环境路径 claude_enabledbool true 是否启用 Claude Code 配置 claude_envdict {} Claude Code 额外环境变量 nodejs_enabledbool true 是否启用 Node.js 安装 nodejs_registrystring '' npm registry,自动配置中国镜像 node_uv_envpath /data/venv 节点 UV 虚拟环境路径,空则跳过 node_pip_packagesstring '' UV 虚拟环境中安装的 pip 包
兼容性
操作系统 x86_64 aarch64 EL 8/9/10 ✅ ✅ Debian 11/12/13 ✅ ✅ Ubuntu 22.04/24.04 ✅ ✅
PostgreSQL : 13, 14, 15, 16, 17, 18
校验和
9f42b8c64180491b59bd03016c26e8ca pigsty-v4.0.0.tgz
db9797c3c8ae21320b76a442c1135c7b pigsty-pkg-v4.0.0.d12.aarch64.tgz
1eed26eee42066ca71b9aecbf2ca1237 pigsty-pkg-v4.0.0.d12.x86_64.tgz
03540e41f575d6c3a7c63d1d30276d49 pigsty-pkg-v4.0.0.d13.aarch64.tgz
36a6ee284c0dd6d9f7d823c44280b88f pigsty-pkg-v4.0.0.d13.x86_64.tgz
f2b6ec49d02916944b74014505d05258 pigsty-pkg-v4.0.0.el10.aarch64.tgz
73f64c349366fe23c022f81fe305d6da pigsty-pkg-v4.0.0.el10.x86_64.tgz
287f767fbb66a9aaca9f0f22e4f20491 pigsty-pkg-v4.0.0.el8.aarch64.tgz
c0886aab454bd86245f3869ef2ab4451 pigsty-pkg-v4.0.0.el8.x86_64.tgz
094ab31bcf4a3cedbd8091bc0f3ba44c pigsty-pkg-v4.0.0.el9.aarch64.tgz
235ccba44891b6474a76a81750712544 pigsty-pkg-v4.0.0.el9.x86_64.tgz
f2791c96db4cc17a8a4008fc8d9ad310 pigsty-pkg-v4.0.0.u22.aarch64.tgz
3099c4453eef03b766d68e04b8d5e483 pigsty-pkg-v4.0.0.u22.x86_64.tgz
49a93c2158434f1adf0d9f5bcbbb1ca5 pigsty-pkg-v4.0.0.u24.aarch64.tgz
4acaa5aeb39c6e4e23d781d37318d49b pigsty-pkg-v4.0.0.u24.x86_64.tgz
v3.7.0 亮点特性
PostgreSQL 18 深度支持,成为默认 PG 大版本,扩展已就位! 新增 EL10 / Debian 13 操作系统支持,总数达 14 个! 新增 PostgresQL 扩展数量,总数达到 437 个! 支持了 Ansible 2.19 破坏性重构以后的版本! Supabase,PolarDB, IvorySQL, Percona 内核更新至最新版本! 优化了 PG 默认参数的设置逻辑,更充分利用资源。 版本更新
PostgreSQL 18.1, 17.7, 16.11, 15.15, 14.20, 13.23 Patroni 4.1.0 Pgbouncer 1.25.0 pg_exporter 1.0.3 pgbackrest 2.57.0 Supabase 2025-11 PolarDB 15.15.5.0 FerretDB 2.7.0 DuckDB 1.4.2 Etcd 3.6.6 pig 0.7.4 更多软件版本更新信息,请参考:
API 变化
为并行执行的相关参数设置了更合理的优化策略,详见 调参说明 在 rich 与 full 模板中,不再默认安装 citus 扩展,因为 citus 尚未支持 PG 18 PG 参数模板中,新增 duckdb 系列扩展存根。 为 min_wal_size, max_wal_size, max_slot_wal_keep_size 设置 200,2000,3000 GB 的封顶上限值。 为 temp_file_limit 设置 200 GB 的封顶上限,OLAP 设置为 2 TB。 适当增大连接池默认链接数量 新增 prometheus_port 参数,且默认值为 9058,避开与 EL10 RHEL Web Console 端口的冲突。 修改 alertmanager_port 参数的默认值为 9059,避开与 Kafka SSL 端口的潜在冲突。 新增 pg_pkg 的 pg_pre 子任务,在安装 PG 包前移除 el9+ 上导致 LLVM 冲突的 bpftool, python3-perf 在 Debian / Ubuntu 的默认仓库定义中新增 llvm 仓库模块 修复了 infra-rm.yml 移除软件包的逻辑 兼容性修复
修复了 Ubuntu/Debian 信任 CA 时 Warning 返回码错误的问题。 修复了 Ansible 2.19 引入的大量兼容性问题,确保在新老版本上正常运行。 为 seq 类变量添加了 int 类型转换,确保兼容 将大量 with_items 修改为 loop 语法,确保兼容 为密钥交换变量添加一层列表嵌套,避免在新版本下针对字符串进行字符迭代。 将 range 用例显式转换为 list 后使用 修改了 name,port 等标记保留的变量命名 将 play_hosts 修改为 ansible_play_hosts 为部分字符串类型添加了 string 强制类型转换,避免运行时错误。 EL10 逻辑适配: 修复了 EL10 缺少 ansible-collection-community-crypto 无法生成密钥的问题 修复了 EL10 缺少 ansible 逻辑包的问题 移除 modulemd_tools flamegraph timescaledb-tool 使用 java-21-openjdk 替代 java-17-openjdk aarch64 YUM 仓库名称问题 Debian 13 逻辑适配 使用 bind9-dnsutils 替代 dnsutils Ubuntu 24 修复 临时移除了上游依赖崩溃的 tcpdump 包 校验和
e00d0c2ac45e9eff1cc77927f9cd09df pigsty-v3.7.0.tgz
987529769d85a3a01776caefefa93ecb pigsty-pkg-v3.7.0.d12.aarch64.tgz
2d8272493784ae35abeac84568950623 pigsty-pkg-v3.7.0.d12.x86_64.tgz
090cc2531dcc25db3302f35cb3076dfa pigsty-pkg-v3.7.0.d13.x86_64.tgz
ddc54a9c4a585da323c60736b8560f55 pigsty-pkg-v3.7.0.el10.aarch64.tgz
d376e75c490e8f326ea0f0fbb4a8fd9b pigsty-pkg-v3.7.0.el10.x86_64.tgz
8c2deeba1e1d09ef3d46d77a99494e71 pigsty-pkg-v3.7.0.el8.aarch64.tgz
9795e059bd884b9d1b2208011abe43cd pigsty-pkg-v3.7.0.el8.x86_64.tgz
08b860155d6764ae817ed25f2fcf9e5b pigsty-pkg-v3.7.0.el9.aarch64.tgz
1ac430768e488a449d350ce245975baa pigsty-pkg-v3.7.0.el9.x86_64.tgz
e033aaf23690755848db255904ab3bcd pigsty-pkg-v3.7.0.u22.aarch64.tgz
cc022ea89181d89d271a9aaabca04165 pigsty-pkg-v3.7.0.u22.x86_64.tgz
0e978598796db3ce96caebd76c76e960 pigsty-pkg-v3.7.0.u24.aarch64.tgz
48223898ace8812cc4ea79cf3178476a pigsty-pkg-v3.7.0.u24.x86_64.tgz
v3.6.1 curl https://repo.pigsty.cc/get | bash -s v3.6.1
亮点特性
PostgreSQL 17.6, 16.10, 15.14, 14.19, 13.22, 以及 18 Beta 3 支持 在中国大陆地区使用 Pigsty 提供的 PGDG APT/YUM 镜像解决更新断供问题。 新的网站首页: https://pgsty.com 增加了 el10, debian 13 的实现存根,以及 el10 的 Terraform 镜像 基础设施软件包更新
Grafana 12.1.0 pg_exporter 1.0.2 pig 0.6.1 vector 0.49.0 redis_exporter 1.75.0 mongo_exporter 0.47.0 victoriametrics 1.123.0 victorialogs: 1.28.0 grafana-victoriametrics-ds 0.18.3 grafana-victorialogs-ds 0.19.3 grafana-infinity-ds 3.4.1 etcd 3.6.4 ferretdb 2.5.0 tigerbeetle 0.16.54 genai-toolbox 0.12.0 数据库软件包更新
API 变更
从 node_kernel_modules 默认值中移除 br_filter 内核模块。 在添加 PGDG YUM 源时使用操作大版本号,不再使用小版本号。 校验和
045977aff647acbfa77f0df32d863739 pigsty-pkg-v3.6.1.d12.aarch64.tgz
636b15c2d87830f2353680732e1af9d2 pigsty-pkg-v3.6.1.d12.x86_64.tgz
700a9f6d0db9c686d371bf1c05b54221 pigsty-pkg-v3.6.1.el8.aarch64.tgz
2aff03f911dd7be363ba38a392b71a16 pigsty-pkg-v3.6.1.el8.x86_64.tgz
ce07261b02b02b36a307dab83e460437 pigsty-pkg-v3.6.1.el9.aarch64.tgz
d598d62a47bbba2e811059a53fe3b2b5 pigsty-pkg-v3.6.1.el9.x86_64.tgz
13fd68752e59f5fd2a9217e5bcad0acd pigsty-pkg-v3.6.1.u22.aarch64.tgz
c25ccfb98840c01eb7a6e18803de55bb pigsty-pkg-v3.6.1.u22.x86_64.tgz
0d71e58feebe5299df75610607bf428c pigsty-pkg-v3.6.1.u24.aarch64.tgz
4fbbab1f8465166f494110c5ec448937 pigsty-pkg-v3.6.1.u24.x86_64.tgz
083d8680fa48e9fec3c3fcf481d25d2f pigsty-v3.6.1.tgz
v3.6.0 curl https://repo.pigsty.cc/get | bash -s v3.6.0
亮点特性
全新文档站: https://doc.pgsty.com 新增 pgsql-pitr 剧本与备份/恢复教程,改善 PITR 体验, 新增内核支持:Percona PG TDE (PG17) 优化 Supabase 自建体验,更新至最新版本,并解决了一系列官方模板的问题 简化安装步骤,默认使用在线安装,更加高效简单,bootstrap 过程(安装 ansible)嵌入安装脚本中 设计改进
改善了 Etcd 模块的实现,新增独立的 etcd-rm.yml 剧本与扩缩容 SOP 脚本。 改善了 MinIO 模块的实现,支持 HTTP 模式,创建不同属性的三个桶供开箱即用 重新调整梳理了所有配置模板,使用更为便利 针对中国大陆使用速度更快的 Docker Registry 镜像站 优化了 tuned 操作系统参数模板,针对现代硬件与 NVMe 磁盘优化 新增扩展 pgactive 用于多主复制与亚秒级故障切换 调整 pg_fs_main / pg_fs_backup 默认值,简化文件目录结构设计 问题修复
修复了 pgbouncer 配置文件的错误 by @housei-zzy 修复了 OrioleDB 在 Debian 平台上的问题 修复了 tuned shm 配置参数的问题 离线软件包直接使用 PGDG 源,避免使用断开同步的镜像站点 修复了 IvorySQL libxcrypt 依赖的问题 替换了破损与缓慢的 EPEL 软件仓库站点 修复了 haproxy_enabled 标记位的功能 基础设施软件包更新
新增 Victoria Metrics / Victoria Logs 相关包
genai-toolbox 0.9.0 (new) victoriametrics 1.120.0 -> 1.121.0 (重构) vmutils 1.121.0 (重命名 victoria-metrics-utils) grafana-victoriametrics-ds 0.15.1 -> 0.17.0 victorialogs 1.24.0 -> 1.25.1 (重构) vslogcli 1.24.0 -> 1.25.1 vlagent 1.25.1 (新增) grafana-victorialogs-ds 0.16.3 -> 0.18.1 prometheus 3.4.1 -> 3.5.0 grafana 12.0.0 -> 12.0.2 vector 0.47.0 -> 0.48.0 grafana-infinity-ds 3.2.1 -> 3.3.0 keepalived_exporter 1.7.0 blackbox_exporter 0.26.0 -> 0.27.0 redis_exporter 1.72.1 -> 1.77.0 rclone 1.69.3 -> 1.70.3 数据库软件包更新
PostgreSQL 18 Beta2 更新 pg_exporter 1.0.1,更新至最新依赖并提供 Docker 镜像 pig 0.6.0,更新了最新扩展与仓库列表,带有 pig install 子命令 vip-manager 3.0.0 -> 4.0.0 ferretdb 2.2.0 -> 2.3.1 dblab 0.32.0 -> 0.33.0 duckdb 1.3.1 -> 1.3.2 etcd 3.6.1 -> 3.6.3 ferretdb 2.2.0 -> 2.4.0 juicefs 1.2.3 -> 1.3.0 tigerbeetle 0.16.41 -> 0.16.50 pev2 1.15.0 -> 1.16.0 PG 扩展包更新
OrioleDB 1.5 beta12 OriolePG 17.11 plv8 3.2.3 -> 3.2.4 postgresql_anonymizer 2.1.1 -> 2.3.0 pgvectorscale 0.7.1 -> 0.8.0 wrappers 0.5.0 -> 0.5.3 supautils 2.9.1 -> 2.10.0 citus 13.0.3 -> 13.1.0 timescaledb 2.20.0 -> 2.21.1 vchord 0.3.0 -> 0.4.3 pgactive 2.1.5 (new) documentdb 0.103.0 -> 0.105.0 pg_search 0.17.0 API 变更
pg_fs_backup:重命名为 pg_fs_backup,默认值为 /data/backups。pg_rm_bkup:重命名为 pg_rm_backup,默认值为 true。pg_fs_main:现在默认值调整为 /data/postgres。nginx_cert_validity:新增参数,用于控制 Nginx 自签名证书的有效期,默认为 397d。minio_buckets:默认值调整为创建名为 pgsql、meta、data 的三个桶。minio_users:移除 dba 用户,新增 s3user_meta 和 s3user_data 用户,分别对应 meta 和 data 桶。minio_https:新增参数,允许配置 MinIO 使用 HTTP 模式。minio_provision:新增参数,允许跳过 MinIO 置备阶段(跳过桶和用户的创建)。minio_safeguard:新增参数,启用后会在执行 minio-rm.yml 时中止操作。minio_rm_data:新增参数,控制在执行 minio-rm.yml 时是否删除 minio 数据目录。minio_rm_pkg:新增参数,控制在执行 minio-rm.yml 时是否卸载 minio 软件包。etcd_learner:新增参数,允许 etcd 以学习者身份初始化。etcd_rm_data:新增参数,控制在执行 etcd-rm.yml 时是否删除 etcd 数据目录。etcd_rm_pkg:新增参数,控制在执行 etcd-rm.yml 时是否卸载 etcd 软件包。校验和
df64ac0c2b5aab39dd29698a640daf2e pigsty-v3.6.0.tgz
cea861e2b4ec7ff5318e1b3c30b470cb pigsty-pkg-v3.6.0.d12.aarch64.tgz
2f253af87e19550057c0e7fca876d37c pigsty-pkg-v3.6.0.d12.x86_64.tgz
0158145b9bbf0e4a120b8bfa8b44f857 pigsty-pkg-v3.6.0.el8.aarch64.tgz
07330d687d04d26e7d569c8755426c5a pigsty-pkg-v3.6.0.el8.x86_64.tgz
311df5a342b39e3288ebb8d14d81e0d1 pigsty-pkg-v3.6.0.el9.aarch64.tgz
92aad54cc1822b06d3e04a870ae14e29 pigsty-pkg-v3.6.0.el9.x86_64.tgz
c4fadf1645c8bbe3e83d5a01497fa9ca pigsty-pkg-v3.6.0.u22.aarch64.tgz
5477ed6be96f156a43acd740df8a9b9b pigsty-pkg-v3.6.0.u22.x86_64.tgz
196169afc1be02f93fcc599d42d005ca pigsty-pkg-v3.6.0.u24.aarch64.tgz
dbe5c1e8a242a62fe6f6e1f6e6b6c281 pigsty-pkg-v3.6.0.u24.x86_64.tgz
v3.5.0 亮点特性
支持 PG 18 (Beta),扩展更新,总数达到 421 个 OrioleDB 与 OpenHalo 内核在全平台上可用 可使用 pig do 子命令代替 bin 脚本 Supabase 自建加强,解决若干遗留问题,例如复制延迟与密钥分发 代码重构与架构优化,优化了 Postgres 与 Pgbouncer 默认参数 更新了 Grafana 12, pg_exporter 1.0 与相关插件,翻修面板 curl https://repo.pigsty.cc/get | bash -s v3.5.0
支持 PostgreSQL 18 通过 pg_exporter 1.0.0 支持 PG18 监控指标 通过 pig 0.4.1 支持 PG18 安装 Alias。 提供 pg18 配置模板 重构 pgsql 模块 PGSQL 重构,将 PG 监控抽离为单独的 pg_monitor 角色,移除 clean 逻辑 去除冗余重复的任务,合并同类项,精简配置。移除 dir/utils 任务块 所有扩展默认安装至 extensions 模式中(与 supabase 安全实践保持一致) 重命名模板文件,移除所有 .j2 后缀 为所有模板中的 monitor 函数添加 SET 命令清空 search_path,遵循 Supabase 安全最佳实践。 调整 pgbouncer 默认参数,增大默认链接池大小,设置链接池清理查询。 新增参数 pgbouncer_ignore_param,允许配置 pgbouncer 忽略的参数列表 新增任务 pg_key 用于生成 pgsodium 所需的服务端密钥 针对 PG 17 默认启用 sync_replication_slots 重新调整了子任务标签,使其更符合配置小节的拆分逻辑 重构 pg_remove 模块 重命名参数:pg_rm_data, pg_rm_bkup, pg_rm_pkg 用于控制删除的内容 重新调整角色代码结构,使用更清楚的标签进行划分 新增 pg_monitor 模块 pgbouncer_exporter 现在不再和 pg_exporter 共享配置文件新增了 TimescaleDB, Citus,pg_wait_event 的监控指标。 使用 pg_exporter 1.0.0,更新了 PG16/17/18 相关监控指标。 使用更为紧凑,全新设计的指标收集器配置文件。 Supabase 加强 (感谢来自 @lawso017 的贡献!) 将 Supabase 容器镜像与数据库模式更新至最新版本 现在默认支持 pgsodium 服务端密钥加载 通过 supa-kick 定时任务解决 logflare 无法及时更新复制进度的问题 为 monitor 模式中的函数添加 set search_path 子句以遵循安全最佳实践 CLI 新增 pig do 命令,允许通过命令行工具替代 bin/ 中的 Shell 脚本 监控系统更新 更新 Grafana 大版本至 12.0.0,更新相关插件/数据源软件包 更新 Postgres 数据源 uid 命名方式(以适应新的 uid 长度限制与字符限制) 新增了 Static Datasource 更新了现有 Dashboard,修复若干遗留问题 基础设施软件包更新
pig 0.4.2 duckdb 1.3.0 etcd 3.6.0 vector 0.47.0 minio 20250422221226 mcli 20250416181326 pev 1.5.0 rclone 1.69.3 mtail 3.0.8 (new) 可观测性软件包更新
grafana 12.0.0 grafana-victorialogs-ds 0.16.3 grafana-victoriametrics-ds 0.15.1 grafana-infinity-ds 3.2.1 grafana_plugins 12.0.0 prometheus 3.4.0 pushgateway 1.11.1 nginx_exporter 1.4.2 pg_exporter 1.0.0 pgbackrest_exporter 0.20.0 redis_exporter 1.72.1 keepalived_exporter 1.6.2 victoriametrics 1.117.1 victoria_logs 1.22.2 数据库软件包更新
PostgreSQL 17.5, 16.9, 15.13, 14.18, 13.21 PostgreSQL 18beta1 支持 pgbouncer 1.24.1 pgbackrest 2.55 pgbadger 13.1 Postgres 扩展包更新
spat 0.1.0a4 新扩展 pgsentinel 1.1.0 新扩展 pgdd 0.6.0 (pgrx 0.14.1) 新扩展 convert 0.0.4 (pgrx 0.14.1) 新扩展 pg_tokenizer.rs 0.1.0 (pgrx 0.13.1) pg_render 0.1.2 (pgrx 0.12.8) pgx_ulid 0.2.0 (pgrx 0.12.7) pg_idkit 0.3.0 (pgrx 0.14.1) pg_ivm 1.11.0 orioledb 1.4.0 beta11 新增 debian/ubuntu 支持 openhalo 14.10 新增 debian/ubuntu 支持 omnigres 20250507 (在 d12/u22 编译最新版本失败) citus 12.0.3 timescaledb 2.20.0 (移除 PG14 支持) supautils 2.9.2 pg_envvar 1.0.1 pgcollection 1.0.0 aggs_for_vecs 1.4.0 pg_tracing 0.1.3 pgmq 1.5.1 tzf-pg 0.2.0 (pgrx 0.14.1) pg_search 0.15.18 (pgrx 0.14.1) anon 2.1.1 (pgrx 0.14.1) pg_parquet 0.4.0 (0.14.1) pg_cardano 1.0.5 (pgrx 0.12) -> 0.14.1 pglite_fusion 0.0.5 (pgrx 0.12.8) -> 14.1 vchord_bm25 0.2.1 (pgrx 0.13.1) vchord 0.3.0 (pgrx 0.13.1) pg_vectorize 0.22.1 (pgrx 0.13.1) wrappers 0.4.6 (pgrx 0.12.9) timescaledb-toolkit 1.21.0 (pgrx 0.12.9) pgvectorscale 0.7.1 (pgrx 0.12.9) pg_session_jwt 0.3.1 (pgrx 0.12.6) -> 0.12.9 pg_timetable 5.13.0 ferretdb 2.2.0 documentdb 0.103.0 (新增 aarch64 支持) pgml 2.10.0 (pgrx 0.12.9) sqlite_fdw 2.5.0 (fix pg17 deb) tzf 0.2.2 0.14.1 (rename src) pg_vectorize 0.22.2 (pgrx 0.13.1) wrappers 0.5.0 (pgrx 0.12.9) 校验和
ab91bc05c54b88c455bf66533c1d8d43 pigsty-v3.6.0.tgz
4c9fabc2d1f0ed733145af2b6aff2f48 pigsty-pkg-v3.5.0.d12.x86_64.tgz
796d47de12673b2eb9882e527c3b6ba0 pigsty-pkg-v3.5.0.el8.x86_64.tgz
a53ef2cede1363f11e9faaaa43718fdc pigsty-pkg-v3.5.0.el9.x86_64.tgz
36da28f97a845fdc0b7bbde2d3812a67 pigsty-pkg-v3.5.0.u22.x86_64.tgz
8551b3e04b38af382163e6857778437d pigsty-pkg-v3.5.0.u24.x86_64.tgz
v3.4.1 GitHub 发布页面:v3.4.1
在 EL 系统上增加了对 MySQL 协议兼容 PostgreSQL 内核的支持:openHalo 在 EL 系统上增加了对 OLTP 增强 PostgreSQL 内核的支持:orioledb 优化了 pgAdmin 9.2 应用模板,具有自动服务器列表更新和 pgpass 密码填充功能 将 PG 默认最大连接数增加到 250、500、1000 从 EL8 中删除了有依赖错误的 mysql_fdw 扩展 基础设施更新
pig 0.3.4 etcd 3.5.21 restic 0.18.0 ferretdb 2.1.0 tigerbeetle 0.16.34 pg_exporter 0.8.1 node_exporter 1.9.1 grafana 11.6.0 zfs_exporter 3.8.1 mongodb_exporter 0.44.0 victoriametrics 1.114.0 minio 20250403145628 mcli 20250403170756 扩展更新
将 pg_search 升级到 0.15.13 将 citus 升级到 13.0.3 将 timescaledb 升级到 2.19.1 将 pgcollection RPM 升级到 1.0.0 将 pg_vectorize RPM 升级到 0.22.1 将 pglite_fusion RPM 升级到 0.0.4 将 aggs_for_vecs RPM 升级到 1.4.0 将 pg_tracing RPM 升级到 0.1.3 将 pgmq RPM 升级到 1.5.1 校验和
471c82e5f050510bd3cc04d61f098560 pigsty-v3.4.1.tgz
4ce17cc1b549cf8bd22686646b1c33d2 pigsty-pkg-v3.4.1.d12.aarch64.tgz
c80391c6f93c9f4cad8079698e910972 pigsty-pkg-v3.4.1.d12.x86_64.tgz
811bf89d1087512a4f8801242ca8bed5 pigsty-pkg-v3.4.1.el9.x86_64.tgzz
9fe2e6482b14a3e60863eeae64a78945 pigsty-pkg-v3.4.1.u22.x86_64.tgz
v3.4.0 GitHub 发布页面:v3.4.0
介绍博客:Pigsty v3.4 MySQL 兼容性和全面增强
新功能
增加了新的 pgBackRest 备份监控指标和仪表板 增强了 Nginx 服务器配置选项,支持自动 Certbot 签发 现在优先使用 PostgreSQL 内置的 C/C.UTF-8 区域设置 IvorySQL 4.4 现在在所有平台上完全支持(RPM/DEB 在 x86/ARM 上) 增加了新的软件包:Juicefs、Restic、TimescaleDB EventStreamer Apache AGE 图数据库扩展现在在 EL 上完全支持 PostgreSQL 13–17 改进了 app.yml playbook:无需额外配置即可启动标准 Docker 应用 升级 Supabase、Dify 和 Odoo 应用模板到最新版本 增加 electric 应用模板,本地优先的 PostgreSQL 同步引擎 基础设施包
+restic 0.17.3+juicefs 1.2.3+timescaledb-event-streamer 0.12.0Prometheus 3.2.1AlertManager 0.28.1blackbox_exporter 0.26.0node_exporter 1.9.0mysqld_exporter 0.17.2kafka_exporter 1.9.0redis_exporter 1.69.0pgbackrest_exporter 0.19.0-2DuckDB 1.2.1etcd 3.5.20FerretDB 2.0.0tigerbeetle 0.16.31vector 0.45.0VictoriaMetrics 1.113.0VictoriaLogs 1.17.0rclone 1.69.1pev2 1.14.0grafana-victorialogs-ds 0.16.0grafana-victoriametrics-ds 0.14.0grafana-infinity-ds 3.0.0PostgreSQL 相关
Patroni 4.0.5PolarDB 15.12.3.0-e1e6d85bIvorySQL 4.4pgbackrest 2.54.2pev2 1.14Babelfish 13.17PostgreSQL 扩展
pgspider_ext 1.3.0(新扩展)apache age 13–17 el rpm (1.5.0)timescaledb 2.18.2 → 2.19.0citus 13.0.1 → 13.0.2documentdb 1.101-0 → 1.102-0pg_analytics 0.3.4 → 0.3.7pg_search 0.15.2 → 0.15.8pg_ivm 1.9 → 1.10emaj 4.4.0 → 4.6.0pgsql_tweaks 0.10.0 → 0.11.0pgvectorscale 0.4.0 → 0.6.0 (pgrx 0.12.5)pg_session_jwt 0.1.2 → 0.2.0 (pgrx 0.12.6)wrappers 0.4.4 → 0.4.5 (pgrx 0.12.9)pg_parquet 0.2.0 → 0.3.1 (pgrx 0.13.1)vchord 0.2.1 → 0.2.2 (pgrx 0.13.1)pg_tle 1.2.0 → 1.5.0supautils 2.5.0 → 2.6.0sslutils 1.3 → 1.4pg_profile 4.7 → 4.8pg_snakeoil 1.3 → 1.4pg_jsonschema 0.3.2 → 0.3.3pg_incremental 1.1.1 → 1.2.0pg_stat_monitor 2.1.0 → 2.1.1ddl_historization 0.7 → 0.0.7(错误修复)pg_sqlog 3.1.7 → 1.6(错误修复)pg_random 删除开发后缀(错误修复)asn1oid 1.5 → 1.6table_log 0.6.1 → 0.6.4接口变更
增加了新的 Docker 参数:docker_data 和 docker_storage_driver(#521 由 @waitingsong 提供) 增加了新的基础设施参数:alertmanager_port,让您指定 AlertManager 端口 增加了新的基础设施参数:certbot_sign,在 nginx 初始化期间申请证书?(默认为 false) 增加了新的基础设施参数:certbot_email,指定通过 Certbot 请求证书时使用的邮箱 增加了新的基础设施参数:certbot_options,指定 Certbot 的额外参数 更新 IvorySQL,从 IvorySQL 4.4 开始将其默认二进制文件放在 /usr/ivory-4 下 将 pg_lc_ctype 和其他区域相关参数的默认值从 en_US.UTF-8 更改为 C 对于 PostgreSQL 17,如果使用 UTF8 编码与 C 或 C.UTF-8 区域,PostgreSQL 的内置本地化规则现在优先 configure 自动检测 PG 版本和环境是否都支持 C.utf8,并相应调整区域相关选项将默认 IvorySQL 二进制路径设置为 /usr/ivory-4 更新 pg_packages 的默认值为 pgsql-main patroni pgbouncer pgbackrest pg_exporter pgbadger vip-manager 更新 repo_packages 的默认值为 [node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-utility, extra-modules] 从 /etc/profile.d/node.sh 中删除 LANG 和 LC_ALL 环境变量设置 现在使用 bento/rockylinux-8 和 bento/rockylinux-9 作为 EL 的 Vagrant box 镜像 增加了新别名 extra_modules,包含额外的可选模块 更新 PostgreSQL 别名:postgresql、pgsql-main、pgsql-core、pgsql-full GitLab 仓库现在包含在可用模块中 Docker 模块已合并到基础设施模块中 node.yml playbook 现在包含 node_pip 任务,在每个节点上配置 pip 镜像pgsql.yml playbook 现在包含 pgbackrest_exporter 任务,用于收集备份指标Makefile 现在允许使用 META/PKG 环境变量增加 /pg/spool 目录作为 pgBackRest 的临时存储 默认禁用 pgBackRest 的 link-all 选项 默认为 MinIO 仓库启用块级增量备份 错误修复
修复 pg-backup 中的退出状态码(#532 由 @waitingsong 提供) 在 pg-tune-hugepage 中,限制 PostgreSQL 仅使用大页面(#527 由 @waitingsong 提供) 修复 pg-role 任务中的逻辑错误 纠正大页面配置参数的类型转换 修复 slim 模板中 node_repo_modules 的默认值问题 校验和
768bea3bfc5d492f4c033cb019a81d3a pigsty-v3.4.0.tgz
7c3d47ef488a9c7961ca6579dc9543d6 pigsty-pkg-v3.4.0.d12.aarch64.tgz
b5d76aefb1e1caa7890b3a37f6a14ea5 pigsty-pkg-v3.4.0.d12.x86_64.tgz
42dacf2f544ca9a02148aeea91f3153a pigsty-pkg-v3.4.0.el8.aarch64.tgz
d0a694f6cd6a7f2111b0971a60c49ad0 pigsty-pkg-v3.4.0.el8.x86_64.tgz
7caa82254c1b0750e89f78a54bf065f8 pigsty-pkg-v3.4.0.el9.aarch64.tgz
8f817e5fad708b20ee217eb2e12b99cb pigsty-pkg-v3.4.0.el9.x86_64.tgz
8b2fcaa6ef6fd8d2726f6eafbb488aaf pigsty-pkg-v3.4.0.u22.aarch64.tgz
83291db7871557566ab6524beb792636 pigsty-pkg-v3.4.0.u22.x86_64.tgz
c927238f0343cde82a4a9ab230ecd2ac pigsty-pkg-v3.4.0.u24.aarch64.tgz
14cbcb90693ed5de8116648a1f2c3e34 pigsty-pkg-v3.4.0.u24.x86_64.tgz
v3.3.0 可用扩展总数增加到 404 ! PostgreSQL 二月小版本更新:17.4、16.8、15.12、14.17、13.20 新功能:app.yml 脚本,用于自动安装 Odoo、Supabase、Dify 等应用。 新功能:在 infra_portal 中进一步自定义 Nginx 配置。 新功能:增加 Certbot 支持,快速申请免费 HTTPS 证书。 新功能:pg_default_extensions 现在支持纯文本扩展列表。 新功能:默认仓库现在包含 mongo、redis、groonga、haproxy 等。 新参数:node_aliases,为节点添加命令别名。 修复:解决 Bootstrap 脚本中的默认 EPEL 仓库地址问题。 改进:为 Debian Security 仓库添加阿里云镜像。 改进:IvorySQL 内核的 pgBackRest 备份支持。 改进:PolarDB 的 ARM64 和 Debian/Ubuntu 支持。 pg_exporter 0.8.0 现在支持 pgbouncer 1.24 中的新指标。 新功能:git、docker、systemctl 等常用命令的自动补全 #506 #507 由 @waitingsong 提供。 改进:优化 pgbouncer 配置模板中的 ignore_startup_parameters #488 由 @waitingsong 提供。 新主页设计:Pigsty 的网站现在拥有全新的外观。 扩展目录:RPM/DEB 二进制包的详细信息和下载链接。 扩展构建:pig CLI 现在自动设置 PostgreSQL 扩展构建环境。 更多版本信息请参考 GitHub 发布页面 。
v3.2.2 变更内容
升级 IvorySQL 至4.2版本(基于 PostgreSQL 17.2) 为 PolarDB 内核添加 Arm64 和 Debian 支持 在默认infra_packages中添加 certbot 和 certbot-nginx 增加 pgbouncer 的 max_prepared_statements 参数至256 移除pgxxx-citus包别名 在pg_extensions中默认隐藏pgxxx-olap类别(因为存在两对扩展冲突) v3.2.1 亮点特性
PG 扩展插件数量提升至350个,新增强力 Rust 扩展 anon。 IvorySQL 支持更新至 PG17 兼容的4.0版本 使用 Pigsty 编译的 Citus,TimescaleDB 与 PGroonga。 添加 Odoo 一键自建模板与新 app.yml 剧本 新增 13 扩展插件:
新增 pg_anon 2.0.0 新增 omnisketch 1.0.2 新增 ddsketch 1.0.1 新增 pg_duration 1.0.1 新增 ddl_historization 0.0.7 新增 data_historization 1.1.0 新增 schedoc 0.0.1 新增 floatfile 1.3.1 新增 pg_upless 0.0.3 新增 pg_task 1.0.0 新增 pg_readme 0.7.0 新增 vasco 0.1.0 新增 pg_xxhash 0.0.1 更新扩展版本
lower_quantile 1.0.3 quantile 1.1.8 sequential_uuids 1.0.3 pgmq 1.5.0 (subdir) floatvec 1.1.1 pg_parquet 0.2.0 wrappers 0.4.4 pg_later 0.3.0 topn fix for deb.arm64 add age 17 on debian powa + pg17, 5.0.1 h3 + pg17 ogr_fdw + pg17 age + pg17 1.5 on debian pgtap + pg17 1.3.3 repmgr topn + pg17 pg_partman 5.2.4 credcheck 3.0 ogr_fdw 1.1.5 ddlx 0.29 postgis 3.5.1 tdigest 1.4.3 pg_repack 1.5.2 v3.2.0 亮点特性
Pigsty 命令行工具:pig 0.2.0,可用于管理扩展插件。 提供五大发行版上 390 个扩展 的 ARM64 扩展支持 Supabase 发布周最新版本更新,全发行版均可自建。 Grafana 更新至 11.4,新增 infinity 数据源。 软件包变化
新增扩展
更新扩展
pgvectorscale 0.4.0 -> 0.5.1 pg_parquet 0.1.0 -> 0.1.1 pg_polyline 0.0.1 pg_cardano 1.0.2 -> 1.0.3 pg_vectorize 0.20.0 pg_duckdb 0.1.0 -> 0.2.0 pg_search 0.13.0 -> 0.13.1 aggs_for_vecs 1.3.1 -> 1.3.2 pgoutput 被标记为新的 PostgreSQL Contrib 扩展基础设施
新增 promscale 0.17.0 新增 grafana-plugins 11.4 新增 grafana-infinity-plugins 新增 grafana-victoriametrics-ds 新增 grafana-victorialogs-ds vip-manager 2.8.0 -> 3.0.0 vector 0.42.0 -> 0.43.0 grafana 11.3 -> 11.4 prometheus 3.0.0 -> 3.0.1 (软件包名从 prometheus2 变更为 prometheus) nginx_exporter 1.3.0 -> 1.4.0 mongodb_exporter 0.41.2 -> 0.43.0 VictoriaMetrics 1.106.1 -> 1.107.0 VictoriaLogs 1.0.0 -> 1.3.2 pg_timetable 5.9.0 -> 5.10.0 tigerbeetle 0.16.13 -> 0.16.17 pg_export 0.7.0 -> 0.7.1 缺陷修复
el8.aarch64 添加 python3-cdiff 修复 patroni 依赖错漏问题 el9.aarch64 添加 timescaledb-tools,修复官方仓库缺失问题 el9.aarch64 添加 pg_filedump,修复官方仓库缺失问题 移除扩展
pg_mooncake 因为与 pg_duckdb 冲突而被移除。pg_top 因为出现太多版本出现缺失,因质量问题而淘汰。hunspell_pt_pt 因为与 PG 官方字典文件冲突而被淘汰。pg_timeit 因为无法在 AARCH64 架构上使用而被淘汰。pgdd 因为缺乏维护,PG 17 与 pgrx 版本老旧而被标记为弃用。old_snapshot 与 adminpack 被标记为 PG 17 不可用。pgml 被设置为默认不下载不安装。API 变化
repo_url_packages 参数现在默认值为空数组,因为所有软件包现在都通过操作系统包管理器进行安装。grafana_plugin_cache 参数弃用,现在 Grafana 插件通过操作系统包管理器进行安装grafana_plugin_list 参数弃用,现在 Grafana 插件通过操作系统包管理器进行安装原名为 prod 的 36 节点仿真模板现在重命名为 simu。 原本在 node_id/vars 针对每个发行版代码生成的配置,现在同样针对 aarch64 生成。 infra_packages 中默认添加命令行管理工具 pigconfigure 命令同样会修改自动生成配置文件中 pgsql-xxx 别名的版本号。adminpack 在 PG 17 中被移除,因此从 Pigsty 默认扩展中被移除。问题修复
软件包校验和
8fdc6a60820909b0a2464b0e2b90a3a6 pigsty-v3.2.0.tgz
d2b85676235c9b9f2f8a0ad96c5b15fd pigsty-pkg-v3.2.0.el9.aarch64.tgz
649f79e1d94ec1845931c73f663ae545 pigsty-pkg-v3.2.0.el9.x86_64.tgz
c42da231067f25104b71a065b4a50e68 pigsty-pkg-v3.2.0.d12.aarch64.tgz
ebb818f98f058f932b57d093d310f5c2 pigsty-pkg-v3.2.0.d12.x86_64.tgz
24c0be1d8436f3c64627c12f82665a17 pigsty-pkg-v3.2.0.u22.aarch64.tgz
0b9be0e137661e440cd4f171226d321d pigsty-pkg-v3.2.0.u22.x86_64.tgz
v3.1.0 亮点特性
PostgreSQL 17 现已成为默认使用的主要版本 (17.2) Ubuntu 24.04 系统支持 arm 架构支持:EL9, Debian12, Ubuntu 22.04 Supabase 一键自建,新的剧本 supabase.yml MinIO 最佳实践改进,配置模板与 Vagrant 模板 提供了一系列开箱即用的配置模板与文档说明。 允许在 configure 过程中使用 -v|--version 指定使用的 PG 大版本。 调整 PG 默认插件策略:默认安装 pg_repack, wal2json 以及 pgvector 三个关键扩展。 大幅简化 repo_packages 本地软件源构建逻辑,允许在 repo_packages 中使用软件包组别名 提供了 Babelfish,IvorySQL,PolarDB 的软件源镜像,简化三者的安装。 默认启用数据库校验和。 修复 ETCD 与 MINIO 日志面板 软件升级
PostgreSQL 17.2, 16.6, 15.10, 14.15, 13.18, 12.22 PostgreSQL 扩展版本变动请参考:/ext/ Patroni 4.0.4 MinIO 20241107 / MCLI 20241117 Rclone 1.68.2 Prometheus: 2.54.0 -> 3.0.0 VictoriaMetrics 1.102.1 -> 1.106.1 VictoriaLogs v0.28.0 -> 1.0.0 vslogcli 1.0.0 MySQL Exporter 0.15.1 -> 0.16.0 Redis Exporter 1.62.0 -> 1.66.0 MongoDB Exporter 0.41.2 -> 0.42.0 Keepalived Exporter 1.3.3 -> 1.4.0 DuckDB 1.1.2 -> 1.1.3 etcd 3.5.16 -> 3.5.17 tigerbeetle 16.8 -> 0.16.13 API 变更
repo_upstream:针对每个具体的操作系统发行版生成默认值:roles/node_id/varsrepo_packages:允许使用 package_map 中定义的别名。repo_extra_packages:新增未指定时的默认值,允许使用 package_map 中定义的别名。pg_checksum:默认值修改为 true,默认打开。pg_packages:默认值修改为:postgresql, wal2json pg_repack pgvector, patroni pgbouncer pgbackrest pg_exporter pgbadger vip-managerpg_extensions:默认值修改为空数组 []。infra_portal:允许为 home 服务器指定 path,替代默认的本地仓库路径 nginx_home (/www)校验和
e62f9ce9f89a58958609da7b234bf2f2 pigsty-v3.1.0.tgz
v3.0.4 特性
针对 PostgreSQL 17 编译了所有支持的 Pigsty 扩展插件 提供了全新的 OLAP 扩展支持:pg_duckdb 与 pg_parquet 简化并优化了最新版本 Supabase 自建的流程 新增参数 docker_image,允许在 Docker 安装后自动拉取镜像。 扩展
欢迎查阅我们最新的 PostgreSQL 扩展目录: /ext/
统计项 总计 PGDG PIGSTY MISC MISS PG17 PG16 PG15 PG14 PG13 PG12 EL 系统扩展 338 134 130 4 7 298 334 336 328 319 310 Deb 系统扩展 326 109 143 74 19 290 322 324 316 307 300 RPM 软件包 313 122 129 4 6 275 309 311 303 294 285 DEB 软件包 298 93 142 64 19 264 294 296 288 279 272
版本升级
新的 PGSQL 扩展
升级与跟进 PG 扩展
pg_search 0.11.0 pg_analytics 0.2.0 plv8 3.2.3 supautils 2.5.0 icu_ext 1.9.0 redis_fdw 17 pg_failover_slots 1.1.0 pg_later 0.1.3 plprql 1.0.0 pg_vectorize 0.18.3 unit 7.7 -> 7.9 log_fdw 1.4 pg_duckdb 0.1.0 pg_graphql 1.5.9 (+17) pg_jsonschema 0.3.2 (+17) pgvectorscale 0.4.0 (+17) wrappers 0.4.3 +pg17 pg_ivm 1.9 pg_timeseries 0.1.6 pgmq 1.4.4 pg_protobuf 16 17 pg_uuidv7 1.6 pg_readonly pgddl 0.28 pg_safeupdate pg_stat_monitor 2.1 pg_profile 4.7 system_stats 3.2 pg_auth_mon 3.0 login_hook 1.6 logerrors 2.1.3 pg-orphaned pgnodemx 1.7 sslutils 1.4 (deb+pg16,17) timestamp9 (deb) 修复不支持 PG16/17的扩展
pg_mon pg_uri agg_for_vecs quantile lower_quantile pg_protobuf acl pg_emailaddr pg_zstd smlar geohash pgsmcrypto (+17) pg_tiktoken (+17) pg_idkit (+17) 基础设施软件包
Grafana 11.3 duckdb 1.1.2 etcd 3.5.16 ferretdb 1.24.0 minio 20241013133411 mcli 2024101313411 pushgateway 1.10 tigerbeetle 0.16.8 mongodb_exporter 0.41.2 redis_exporter 1.64.1 vector 0.41.1 vip-manager 2.7 sealos 5.0.1 v3.0.3 特性
提供对最新发布的 PostgreSQL 17 支持。 优化了 etcd 配置,监控,与告警规则 (Oracle 兼容的)IvorySQL 3.4 支持,与 PostgreSQL 16.4 同步 版本升级
PostGIS 3.5 Grafana 11.2 duckdb 1.1 pg_search 0.10.2 pg_analytics 0.1.4 v3.0.2 特性
精简安装模式 :使用 slim.yml 进行最精简的 HA PGSQL 部署。PolarDB PG 15 的原生支持。优化 monitor.pg_table_bloat 与 monitor.pg_index_bloat,使用安全定义包装函数规避 PolarDB 统计视图权限问题。 在各模块的监控注册阶段,尊重 prometheus_enabled 与 grafana_enabled 配置选项,关闭时不再注册。 在 /etc/profile.d/pgsql.sh 中添加 PGDATABASE 与 PGPORT 环境变量,设置为 pg_primary_db(默认postgres) 变更
在 Pigsty PGSQL 仓库中移除 PolarDB 11 与 CloudberryDB 1.5.4 的 RPM/APT 包。 使用专用的仓库分发 PolarDB 15 与 CloudberryDB 1.6.0 的 RPM/APT 包。 问题修复
修复 Redis 的 /etc/tmp.files.d 文件名错误。 在管理 pgbouncer 用户时,设置 PGHOST 与 PGPORT 环境变量。 临时移除 pg_snakeoil 扩展支持,因为 EL8 上游源 clamv 出现依赖缺失问题。 移除 pgsql 角色的 Notify / Handler,以兼容更老的 Ansible 2.9 版本。 v3.0.1 特性改进
PolarDB Oracle 兼容性模式支持(需要第三方商业闭源内核) 使用 Oracle 兼容的 SQL 语法改写监控视图与相关 SQL 语句 Patroni 4 支持与适配 新增扩展 pg_analytics,通过 duckdb 为 PG 加装分析能力 添加新扩展:odbc_fdw 与 jdbc_fdw,提供通用的外部数据源连接能力 仓库添加新内核 cloudberrydb (Greenplum 原班开发者的开源分支) 仓库添加新工具 walminer,从 WAL(replica 等级)中提取原始 SQL。(高级特性需自行购买 License) 更新执行计划可视化工具 Pev2 版本至 1.12.1 新增 Grafana 插件:volkovlabs-rss-datasource 在 PGCAT databases 监控面板中添加了已安装和待安装的扩展插件 PGSQL 主库初始化后,会重启一次以便 pg_param & pg_files 生效,因此 Supabase PG / PolarDB 集群置备后无需重启。 问题修复
修复了 Grafana 11.1.4 面板插件默认不加载的问题 修复了特定操作系统上 BlackBox Exporter Ping 探针失效的问题 确保 /var/run/postgresql 与 /var/run/redis 临时目录总是在重启后自动创建 修复了 cache.yml 剧本没有正确移除老旧的 patroni 3.0.4 RPM 包问题 修复了个别告警规则中的描述信息错误 移除了 Patroni 配置文件中过时的 Bootstrap User/HBA 参数 v3.0.0 亮点特性
Pigsty v3 提供了史无前例的 333 个可用扩展插件。
包括 121 个扩展 RPM包 与 133 个 DEB包 ,数量已经超过了 PGDG 官方仓库提供的扩展数量总和(135 RPM/ 109 DEB)。
而且,Pigsty 还将 EL 系统与 Debian 生态的独有 PG 扩展插件相互移植,实现了两大发行版的插件生态大对齐。
- timescaledb periods temporal_tables emaj table_version pg_cron pg_later pg_background pg_timetable
- postgis pgrouting pointcloud pg_h3 q3c ogr_fdw geoip #pg_geohash #mobilitydb
- pgvector pgvectorscale pg_vectorize pg_similarity pg_tiktoken pgml #smlar
- pg_search pg_bigm zhparser hunspell
- hydra pg_lakehouse pg_duckdb duckdb_fdw pg_fkpart pg_partman plproxy #pg_strom citus
- pg_hint_plan age hll rum pg_graphql pg_jsonschema jsquery index_advisor hypopg imgsmlr pg_ivm pgmq pgq #rdkit
- pg_tle plv8 pllua plprql pldebugger plpgsql_check plprofiler plsh #pljava plr pgtap faker dbt2
- prefix semver pgunit md5hash asn1oid roaringbitmap pgfaceting pgsphere pg_country pg_currency pgmp numeral pg_rational pguint ip4r timestamp9 chkpass #pg_uri #pgemailaddr #acl #debversion #pg_rrule
- topn pg_gzip pg_http pg_net pg_html5_email_address pgsql_tweaks pg_extra_time pg_timeit count_distinct extra_window_functions first_last_agg tdigest aggs_for_arrays pg_arraymath pg_idkit pg_uuidv7 permuteseq pg_hashids
- sequential_uuids pg_math pg_random pg_base36 pg_base62 floatvec pg_financial pgjwt pg_hashlib shacrypt cryptint pg_ecdsa pgpcre icu_ext envvar url_encode #pg_zstd #aggs_for_vecs #quantile #lower_quantile #pgqr #pg_protobuf
- pg_repack pg_squeeze pg_dirtyread pgfincore pgdd ddlx pg_prioritize pg_checksums pg_readonly safeupdate pg_permissions pgautofailover pg_catcheck preprepare pgcozy pg_orphaned pg_crash pg_cheat_funcs pg_savior table_log pg_fio #pgpool pgagent
- pg_profile pg_show_plans pg_stat_kcache pg_stat_monitor pg_qualstats pg_store_plans pg_track_settings pg_wait_sampling system_stats pg_meta pgnodemx pg_sqlog bgw_replstatus pgmeminfo toastinfo pagevis powa pg_top #pg_statviz #pgexporter_ext #pg_mon
- passwordcheck supautils pgsodium pg_vault anonymizer pg_tde pgsmcrypto pgaudit pgauditlogtofile pg_auth_mon credcheck pgcryptokey pg_jobmon logerrors login_hook set_user pg_snakeoil pgextwlist pg_auditor noset #sslutils
- wrappers multicorn mysql_fdw tds_fdw sqlite_fdw pgbouncer_fdw mongo_fdw redis_fdw pg_redis_pubsub kafka_fdw hdfs_fdw firebird_fdw aws_s3 log_fdw #oracle_fdw #db2_fdw
- orafce pgtt session_variable pg_statement_rollback pg_dbms_metadata pg_dbms_lock pgmemcache #pg_dbms_job #babelfish
- pglogical pgl_ddl_deploy pg_failover_slots wal2json wal2mongo decoderbufs decoder_raw mimeo pgcopydb pgloader pg_fact_loader pg_bulkload pg_comparator pgimportdoc pgexportdoc #repmgr #slony
- gis-stack rag-stack fdw-stack fts-stack etl-stack feat-stack olap-stack supa-stack stat-stack json-stack
Pigsty v3 允许您更换 PostgreSQL 内核,目前支持了 SQL Server 兼容的 Babelfish (线缆协议级仿真),Oracle 兼容的 IvorySQL,以及 PG 版的 RAC PolarDB;此外,现在自托管 Supabase 也在 Debian 系统中可用。
您可以让 Pigsty 中带有 HA,IaC,PITR,监控的生产级 PostgreSQL 集群仿真 MSSQL (via Babelfish),Oracle via (IvorySQL),Oracle RAC (via PolarDB), MongoDB(via FerretDB),以及 Firebase (via Supabase)。
我们现在提供 Pigsty Pro 专业版 ,在开源版的功能基础上提供增值服务。专业版提供额外的功能模块:MSSQL,Oracle,Mongo,K8S,Victoria,Kafka,TigerBeetle 等……,并提供更广泛的 PG 大版本、操作系统、芯片架构的支持。
提供针对全系操作系统精准小版本定制的离线安装包,以及 EL7,Debian 11,Ubuntu 20.04 等过保老系统的支持;此外,专业版还提供内核可插拔定制服务,并对 PolarDB PG 的原生部署、监控管控支持以满足“国产化”需要。
使用以下命令快速安装体验:
curl -fsSL https://repo.pigsty.cc/get | bash
cd ~/pigsty; ./bootstrap; ./configure; ./install.yml
重大变更
本次 Pigsty 发布调整大版本号,从 2.x 升级到 3.0,带有一些重大变更:
首要支持操作系统调整为:EL 8 / EL 9 / Debian 12 / Ubuntu 22.04
EL7 / Debian 11 / Ubuntu 20.04 等系统进入弃用阶段,不再提供支持 有在这些系统上运行需求的用户请考虑我们的 订阅服务 默认使用在线安装,不再提供离线软件包,从而解决操作系统小版本兼容性问题。
bootstrap 过程现在不再询问是否下载离线安装包,但如果 /tmp/pkg.tgz 存在,仍然会自动使用离线安装包。有离线安装需求请自行制作离线软件包或考虑我们的 订阅服务 Pigsty 使用的上游软件仓库进行统一调整,地址变更,并对所有软件包进行 GPG 签名与校验
标准仓库: https://repo.pigsty.io/{apt/yum} 国内镜像: https://repo.pigsty.cc/{apt/yum} API 参数变更与配置模板变更
EL 系与 Debian 系配置模板现在收拢统一,有差异的参数统一放置于 roles/node_id/vars/ 目录进行管理。 配置目录变更,所有配置文件模板统一放置在 conf 目录下,并分为 default, dbms, demo, build 四大类。 其他新特性
PG OLAP 分析能力史诗级加强:DuckDB 1.0.0,DuckDB FDW,以及 PG Lakehouse,Hydra 移植至 Deb 系统中。 PG 向量检索与全文检索能力加强:Vectorscale 提供 DiskANN 向量索引,Hunspell 分词字典支持,pg_search 0.8.6。 帮助 ParadeDB 解决了软件包构建问题,现在我们在 Debian/Ubuntu 上也能提供这一扩展。 Supabase 所需的扩展在 Debian/Ubuntu 上全部可用,Supabase 现在可在全 OS 上自托管。 提供了场景化预置扩展堆栈的能力,如果您不知道安装哪些扩展,我们准备了针对特定应用场景的扩展推荐包(Stack)。 针对所有 PostgreSQL 生态的扩展,制作了元数据表格、文档、索引、名称映射,针对 EL 与 Deb 进行对齐,确保扩展可用性。 为了解决 DockerHub 被 Ban 的问题,我们加强了 proxy_env 参数的功能并简化其配置方式。 建设了一个专用的新软件仓库,提供了 12-17 版本的全部扩展插件,其中,PG16 的扩展仓库会在 Pigsty 默认的版本中实装。 现有软件仓库升级改造,使用标准的签名与校验机制,确保软件包的完整性与安全性。APT 仓库采用新的标准布局通过 reprepro 构建。 提供了 1,2,3,4,43 节点的沙箱环境:meta, dual, trio, full, prod,以及针对 7 大 OS Distro 的快捷配置模板。 PG Exporter 新增了 PostgreSQL 17 与 pgBouncer 1.23 新监控指标收集器的定义,与使用这些指标的 Grafana Panel 监控面板修缮,修复了各种问题,为 PGSQL Pgbouncer 与 PGSQL Patroni 监控面板添加了日志仪表盘。 使用全新的 cache.yml Ansible 剧本,替换了原有制作离线软件包的 bin/cache 与 bin/release-pkg 脚本。 API 变更
新参数选项: pg_mode 现在支持的模式有 pgsql, citus, gpsql, mssql, ivory, polar,用于指定 PostgreSQL 集群的模式pgsql: 标准 PostgreSQL 高可用集群citus: Citus 水平分布式 PostgreSQL 原生高可用集群gpsql: 用于 Greenplum 与 GP 兼容数据库的监控(专业版)mssql: 安装 Babelfish,提供 Microsoft SQL Server 兼容性模式的标准 PostgreSQL 高可用集群,线缆协议级支持,扩展不可用ivory: 安装 IvorySQL 提供的 Oracle 兼容性 PostgreSQL 高可用集群,Oracle 语法/数据类型/函数/存储过程兼容,扩展不可用 (专业版)polar: 安装 PolarDB for PostgreSQL (PG RAC)开源版本,提供国产化数据库能力支持,扩展不可用。(专业版) 新参数: pg_parameters,用于在实例级别指定 postgresql.auto.conf 中的参数,覆盖集群配置,实现不同实例成员的个性化配置。 新参数: pg_files,用于将额外的文件拷贝到 PGDATA 数据目录,针对需要 License 文件的商业版 PostgreSQL 分叉内核设计。 新参数: repo_extra_packages,用于额外指定需要下载的软件包,与 repo_packages 共同使用,便于指定 OS 版本独有的扩展列表。 参数重命名: patroni_citus_db 重命名为 pg_primary_db,用于指定集群中的主要数据库(在 Citus 模式中使用) 参数强化:proxy_env 中的代理服务器配置会写入 Docker Daemon,解决科学上网问题,configure -x 选项会自动在配置中写入当前环境中的代理服务器配置。 参数强化:infra_portal 参数现在支持指定 path 选项,对外暴露本机上的目录,提供 web 服务。 参数强化:repo_url_packages 中的 repo.pigsty.io 会在区域为中国时自动替换为 repo.pigsty.cc,解决科学上网问题,此外,现在可以指定下载后的文件名称。 参数强化:pg_databases.extensions 中的 extension 字段现在可以支持字典与扩展名字符串两种模式,字典模式提供 version 支持,允许安装特定版本的扩展。 参数强化:repo_upstream 参数如果没有显式覆盖定义,将从 rpm.yml 或 deb.yml 中定义的 repo_upstream_default 提取对应系统的默认值。 参数强化:repo_packages 参数如果没有显式覆盖定义,将从 rpm.yml 或 deb.yml 中定义的 repo_packages_default 提取对应系统的默认值。 参数强化:infra_packages 参数如果没有显式覆盖定义,将从 rpm.yml 或 deb.yml 中定义的 infra_packages_default 提取对应系统的默认值。 参数强化:node_default_packages 参数如果没有显式覆盖定义,将从 rpm.yml 或 deb.yml 中定义的 node_packages_default 提取对应系统的默认值。 参数强化:pg_packages 与 pg_extensions 中的扩展现在都会从 rpm.yml 或 deb.yml 中定义的 pg_package_map 执行一次查找与翻译。 参数强化:node_packages 与 pg_extensions 参数中指定的软件包在安装时会升级至最新版本, node_packages 中现在默认值变为 [openssh-server],帮助修复 OpenSSH CVE 参数强化:pg_dbsu_uid 会自动根据操作系统类型调整为 26 (EL)或 543 (Debian),避免了手工调整。 设置了 pgbouncer 默认参数,max_prepared_statements = 128 启用了事物池化模式下的准备语句支持,并设置 server_lifetime 为 600, 修改了 patroni 模板默认参数,统一增大 max_worker_processes +8 可用后端进程,提高 max_wal_senders 与 max_replication_slots 至 50,并增大 OLAP 模板临时文件的大小限制为主磁盘的 1/5 版本升级
截止至发布时刻,Pigsty 主要组件的版本升级如下:
Pigsty 重新编译了所有 PostgreSQL 扩展插件,PostgreSQL 扩展插件的最新版本,可用的 333 个扩展插件请参考 扩展列表
新应用
Pigsty 现在提供开箱即用的 Dify 与 Odoo 两款使用 PostgreSQL 软件的 Docker Compose 模板:
Dify : AI 智能体工作流编排与 LLMOps,使用 PostgreSQL 作为元数据库,PGVector 作为向量存储。Odoo : 企业级开源 ERP 系统,使用 PostgreSQL 作为底层数据库。Pigsty 专业版现在提供试点的 Kubernetes 部署支持与 Kafka KRaft 集群部署与监控支持
KUBE : 使用 cri-dockerd 或 containerd 部署由 Pigsty 托管的 Kubernetes 集群KAFKA :部署由 Kraft 协议支持的高可用 Kafka 集群问题修复
修复了 Ubuntu / Debian 系统中,节点重启后可能出现的 postgresql-common 服务自动启动替代默认数据库集群的缺陷 通过 node_packages 中的默认值 [openssh-server],CVE-2024-6387 可以在 Pigsty 安装过程中被自动修复。 修复了 Loki 解析 Nginx 日志标签基数过大导致的内存消耗问题。 修复了 EL8 系统中上游 Ansible 依赖变化导致的 bootstrap 失效问题(python3.11-jmespath 升级至 python3.12-jmespath) v2.7.0 亮点特性
新增了大量强力扩展插件,特别是一些使用 rust 与 pgrx 进行开发的强力扩展:
当然,也有一些使用原生 C 和 C++ 开发的强力扩展:
parquet_s3_fdw 1.1.0:从 S3 存取 Parquet 格式文件,作为湖仓之用plv8 3.2.2:使用 V8 引擎,允许在 PostgreSQL 中使用 Javascript 语言编写存储过程md5hash 1.0.1:用于存储原生 MD5 哈希数据类型,而非文本。pg_tde 1.0 alpha:PostgreSQL 的实验性加密存储引擎。pg_dirtyread 2.6:从 PostgreSQL 表中读取未清理的死元组,用于脏读新的 deb PGDG 扩展:pg_roaringbitmap, pgfaceting, mobilitydb, pgsql-http, pg_hint_plan, pg_statviz, pg_rrule 新的 rpm PGDG 扩展:pg_profile, pg_show_plans, 使用 PGDG 的 pgsql_http, pgsql_gzip, pg_net, pg_bigm 替代 Pigsty 维护的 RPM。 新特性
允许 Pigsty 在特定 Docker 虚拟机镜像中运行。 针对 Ubuntu 与 EL 系操作系统发行版准备了 INFRA & PGSQL 模块的 arm64 软件包 新安装脚本,可从 cloudflare 下载软件,可以指定版本,提供更完善的提示信息。 新增的 PGSQL PITR 监控面板,用于在 PITR 过程中提供更好的可观测性 针对在 Docker 虚拟机镜像中运行 Pigsty 进行了一系列铺垫与准备。 新增了 防呆设计 ,避免在非 Pigsty 纳管的节点上运行 pgsql.yml 剧本 (AdamYLK ) 针对每个支持的发行版大版本配置了独立的配置文件:el7, el8, el9, debian11, debian12, ubuntu20, ubuntu22 软件版本升级
PostgreSQL 16.3 Patroni 3.3.0 pgBackRest 2.51 VIP-Manager v2.5.0 Haproxy 2.9.7 Grafana 10.4.2 Prometheus 2.51 Loki & Promtail: 3.0.0 (警告:大版本非兼容性变更!) Alertmanager 0.27.0 BlackBox Exporter 0.25.0 Node Exporter 1.8.0 pgBackrest Exporter 0.17.0 duckdb 0.10.2 etcd 3.5.13 minio-20240510014138 / mcli-20240509170424 pev2 v1.8.0 -> v1.11.0 pgvector 0.6.1 -> 0.7.0pg_tle: v1.3.4 -> v1.4.0 hydra: v1.1.1 -> v1.1.2 duckdb_fdw: v1.1.0 重新针对 libduckdb 0.10.2 进行编译 pg_bm25 0.5.6 -> pg_search 0.7.0 pg_analytics: 0.5.6 -> 0.6.1 pg_graphql: 1.5.0 -> 1.5.4 pg_net 0.8.0 -> 0.9.1 pg_sparse (deprecated) Docker 应用模板
缺陷修复
修复了 pg_exporters 角色中的变量空白问题。 修复了 minio_cluster 变量没有在全局配置中注释掉的问题 修复了 EL7 模板中的 postgis34 插件名称问题,应该使用 postgis33 修复了 EL8 python3.11-cryptography 依赖名的问题,上游现在变更为 python3-cryptography。 修复了 /pg/bin/pg-role 无法在非交互式 Shell 模式下获取操作系统用户名的问题 修复了 /pg/bin/pg-pitr 无法正确提示 -X -P 选项的问题 API 变更
新参数 node_write_etc_hosts,用于控制是否向目标节点的 /etc/hosts 文件写入静态 DNS 解析记录 新增了 prometheus_sd_dir 参数,用于指定 Prometheus 静态服务发现的目标文件目录 configure 脚本新增了 -x|--proxy 参数,用于将当前环境的代理信息写入配置文件 by @waitingsong in https://github.com/Vonng/pigsty/pull/405 不再使用 Promtail & Loki 解析 Infra 节点上的 Nginx 日志细节标签,因为这样会导致标签基数爆炸。 在 Prometheus 配置中使用 alertmanager API v2 替代 v1 在 PGSQL 模块中,使用 /pg/cert/ca.crt 代替 /etc/pki/ca.crt,降低对节点根证书的依赖。 新的贡献者
完整的变更日志 :https://github.com/Vonng/pigsty/compar
离线软件包校验和
ec271a1d34b2b1360f78bfa635986c3a pigsty-pkg-v2.7.0.el8.x86_64.tgz
f3304bfd896b7e3234d81d8ff4b83577 pigsty-pkg-v2.7.0.debian12.x86_64.tgz
5b071c2a651e8d1e68fc02e7e922f2b3 pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz
v2.6.0 亮点特性
软件配置变更
使用 node_repo_modules 替换 node_repo_method 参数,并移除 node_repo_local_urls 参数。 暂时关闭 Grafana 统一告警功能,避免 “Database Locked” 错误。 新增 node_repo_modules 参数,用于指定在节点上添加的上游仓库源。 移除 node_local_repo_urls,其功能由 node_repo_modules & repo_upstream 替代。 移除 node_repo_method 参数,其功能由 node_repo_modules 替代。 在 repo_upstream 添加新的 local 源,并通过 node_repo_modules 使用,替代 node_local_repo_urls 的功能 重排 node_default_packages,infra_packages,pg_packages,pg_extensions 参数默认值。 在 repo_upstream 中替换 repo_upstream.baseurl 时,如果 EL8/9 PGDG 小版本特定的仓库可用,使用 major.minor 而不是 major 替换 $releasever,提高小版本兼容性。 软件版本升级
Grafana 10.3 Prometheus 2.47 node_exporter 1.7.0 HAProxy 2.9.5 Loki / Promtail 2.9.4 minio-20240216110548 / mcli-20240217011557 etcd 3.5.11 Redis 7.2.4 Bytebase 2.13.2 DuckDB 0.10.0 FerretDB 1.19 Metabase:新 Docker 应用模板 PostgreSQL 扩展插件
PostgreSQL 小版本升级: 16.2, 15.6, 14.11, 13.14, 12.18 PostgreSQL 16: 现在被提升为默认主版本 pg_exporter 0.6.1:安全修复 Patroni 3.2.2 pgBadger 12.4 pgBackRest 2.50 vip-manager 2.3.0 PostGIS 3.4.2 TimescaleDB 2.14.1 向量扩展 PGVector 0.6.0:新增并行创建 HNSW 索引功能 新增扩展插件 duckdb_fdw v1.1,支持读写 DuckDB 数据 v1.1 新增扩展插件 pgsql-gzip ,用于支持 Gzip 压缩解压缩 v1.0.0 新增扩展插件 pg_sparse ,高效处理稀疏向量(ParadeDB) v0.5.6 新增扩展插件 pg_bm25 ,用于支持高质量全文检索 BM25 算法的插件(ParadeDB) v0.5.6 新增扩展插件 pg_analytics ,支持 SIMD 与列式存储的 PG 分析插件(ParadeDB) v0.5.6 升级 AIML 插件 pgml 至 v2.8.1,新增 PG 16 支持。 升级列式存储插件 hydra 版本至 v1.1.1,新增 PG 16 支持。 升级图扩展插件 age 至 v1.5.0,新增 PG 16 支持。 升级 GraphQL 插件 pg_graphql 版本至 v1.5.0,支持 Supabase。 330e9bc16a2f65d57264965bf98174ff pigsty-v2.6.0.tgz
81abcd0ced798e1198740ab13317c29a pigsty-pkg-v2.6.0.debian11.x86_64.tgz
7304f4458c9abd3a14245eaf72f4eeb4 pigsty-pkg-v2.6.0.debian12.x86_64.tgz
f914fbb12f90dffc4e29f183753736bb pigsty-pkg-v2.6.0.el7.x86_64.tgz
fc23d122d0743d1c1cb871ca686449c0 pigsty-pkg-v2.6.0.el8.x86_64.tgz
9d258dbcecefd232f3a18bcce512b75e pigsty-pkg-v2.6.0.el9.x86_64.tgz
901ee668621682f99799de8932fb716c pigsty-pkg-v2.6.0.ubuntu20.x86_64.tgz
39872cf774c1fe22697c428be2fc2c22 pigsty-pkg-v2.6.0.ubuntu22.x86_64.tgz
v2.5.1 跟进 PostgreSQL v16.1, v15.5, 14.10, 13.13, 12.17, 11.22 小版本例行更新。
现在 PostgreSQL 16 的所有重要扩展已经就位(新增 pg_repack 与 timescaledb 支持)
软件更新:PostgreSQL to v16.1, v15.5, 14.10, 13.13, 12.17, 11.22 Patroni v3.2.0 PgBackrest v2.49 Citus 12.1 TimescaleDB 2.13 Grafana v10.2.0 FerretDB 1.15 SealOS 4.3.7 Bytebase 2.11.1 移除 PGCAT 监控面板中查询对 monitor 模式前缀(允许用户将 pg_stat_statements 扩展装到别的地方) 新的配置模板 wool.yml,为阿里云免费99 ECS 单机针对设计。 为 EL9 新增 python3-jmespath 软件包,解决 Ansible 依赖更新后 bootstrap 缺少 jmespath 的问题 31ee48df1007151009c060e0edbd74de pigsty-pkg-v2.5.1.el7.x86_64.tgz
a40f1b864ae8a19d9431bcd8e74fa116 pigsty-pkg-v2.5.1.el8.x86_64.tgz
c976cd4431fc70367124fda4e2eac0a7 pigsty-pkg-v2.5.1.el9.x86_64.tgz
7fc1b5bdd3afa267a5fc1d7cb1f3c9a7 pigsty-pkg-v2.5.1.debian11.x86_64.tgz
add0731dc7ed37f134d3cb5b6646624e pigsty-pkg-v2.5.1.debian12.x86_64.tgz
99048d09fa75ccb8db8e22e2a3b41f28 pigsty-pkg-v2.5.1.ubuntu20.x86_64.tgz
431668425f8ce19388d38e5bfa3a948c pigsty-pkg-v2.5.1.ubuntu22.x86_64.tgz
v2.5.0 curl https://get.pigsty.cc/latest | bash
亮点特性
Ubuntu / Debian 支持: bullseye, bookworm, jammy, focal
使用 CDN repo.pigsty.cc 软件源,提供 rpm/deb 软件包下载。
Anolis 操作系统支持(兼容 EL 8.8)。
使用 PostgreSQL 16 替代 PostgreSQL 14 作为备选主要支持版本
新增了 PGSQL Exporter / PGSQL Patroni 监控面板,重做 PGSQL Query 面板
扩展更新:
PostGIS 版本至 3.4(EL8/EL9),EL7 仍使用 PostGIS 3.3 移除 pg_embedding,因为开发者不再对其进行维护,建议使用 pgvector 替换。 新扩展(EL):点云插件 pointcloud 支持,Ubuntu 原生带有此扩展。 新扩展(EL): imgsmlr, pg_similarity,pg_bigm 用于搜索。 重新编译 pg_filedump 为 PG 大版本无关的软件包。 新收纳 hydra 列存储扩展,不再默认安装 citus 扩展。 软件更新:
Grafana 更新至 v10.1.5 Prometheus 更新至 v2.47 Promtail/Loki 更新至 v2.9.1 Node Exporter 更新至 v1.6.1 Bytebase 更新至 v2.10.0 patroni 更新至 v3.1.2 pgbouncer 更新至 v1.21.0 pg_exporter 更新至 v0.6.0 pgbackrest 更新至 v2.48.0 pgbadger 更新至 v12.2 pg_graphql 更新至 v1.4.0 pg_net 更新至 v0.7.3 ferretdb 更新至 v0.12.1 sealos 更新至 4.3.5 Supabase 支持更新至 20231013070755 Ubuntu 支持说明
Pigsty 支持了 Ubuntu 22.04 (jammy) 与 20.04 (focal) 两个 LTS 版本,并提供相应的离线软件安装包。
相比 EL 系操作系统,一些参数的默认值需要显式指定调整,详情请参考 ubuntu.yml
repo_upstream:按照 Ubuntu/Debian 的包名进行了调整repo_packages:按照 Ubuntu/Debian 的包名进行了调整node_repo_local_urls:默认值为 ['deb [trusted=yes] http://${admin_ip}/pigsty ./']node_default_packages:zlib -> zlib1g, readline -> libreadline-devvim-minimal -> vim-tiny, bind-utils -> dnsutils, perf -> linux-tools-generic,新增软件包 acl,确保 Ansible 权限设置正常工作 infra_packages:所有含 _ 的包要替换为 - 版本,此外 postgresql-client-16 用于替换 postgresql16pg_packages:Ubuntu 下惯用 - 替代 _,不需要手工安装 patroni-etcd 包。pg_extensions:扩展名称与 EL 系不太一样,Ubuntu 下缺少 passwordcheck_cracklib 扩展。pg_dbsu_uid: Ubuntu 下 Deb 包不显式指定 uid,需要手动指定,Pigsty 默认分配为 543API 变更
默认值变化:
repo_modules 现在的默认值为 infra,node,pgsql,redis,minio,启用所有上游源
repo_upstream 发生变化,现在添加了 Pigsty Infra/MinIO/Redis/PGSQL 模块化软件源
repo_packages 发生变化,移除未使用的 karma,mtail,dellhw_exporter,移除了 PG14 主要扩展,新增了 PG16 主要扩展,添加了 virtualenv 包。
node_default_packages 发生变化,默认安装 python3-pip 组件。
pg_libs: timescaledb 从 shared_preload_libraries 中移除,现在默认不自动启用。
pg_extensions 发生变化,不再默认安装 Citus 扩展,默认安装 passwordcheck_cracklib 扩展,EL8,9 PostGIS 默认版本升级至 3.4
- pg_repack_${pg_version}* wal2json_${pg_version}* passwordcheck_cracklib_${pg_version}*
- postgis34_${pg_version}* timescaledb-2-postgresql-${pg_version}* pgvector_${pg_version}*
Patroni 所有模板默认移除 wal_keep_size 参数,避免触发 Patroni 3.1.1 的错误,其功能由 min_wal_size 覆盖。
87e0be2edc35b18709d7722976e305b0 pigsty-pkg-v2.5.0.el7.x86_64.tgz
e71304d6f53ea6c0f8e2231f238e8204 pigsty-pkg-v2.5.0.el8.x86_64.tgz
39728496c134e4352436d69b02226ee8 pigsty-pkg-v2.5.0.el9.x86_64.tgz
e3f548a6c7961af6107ffeee3eabc9a7 pigsty-pkg-v2.5.0.debian11.x86_64.tgz
1e469cc86a19702e48d7c1a37e2f14f9 pigsty-pkg-v2.5.0.debian12.x86_64.tgz
cc3af3b7c12f98969d3c6962f7c4bd8f pigsty-pkg-v2.5.0.ubuntu20.x86_64.tgz
c5b2b1a4867eee624e57aed58ac65a80 pigsty-pkg-v2.5.0.ubuntu22.x86_64.tgz
v2.4.1 Supabase 支持:开源的 Firebase 替代,现可使用 Pigsty 本地托管的 PostgreSQL 实例作为数据存储。PostgresML 支持:使用 SQL 完成经典机器学习算法,训练、微调、调用大语言模型(hugging face)。FerretDB v1.10 支持,在 PostgreSQL 上提供 MongoDB API 与协议兼容能力。GraphQL 扩展: pg_graphql :从现有模式中反射出 GraphQL 模式,提供库内 GraphQL 查询能力。 JWT 支持扩展:pgjwt 允许您使用 SQL 验证签发 JWT (JSON Web Tokens)。 密钥存储扩展: vault 可以在提供一个安全存储加密密钥的保险柜。 数据恢复扩展:pg_filedump :可用于快速从 PostgreSQL 二进制文件中恢复数据 图数据库扩展:Apache age ,为 PostgreSQL 添加 OpenCypher 查询支持,类似 Neo4J 中文分词扩展:zhparser ,为中文全文检索提供分词能力,类似 ElasticSearch。 高效位图扩展:pg_roaringbitmap ,在 PostgreSQL 中提供 roaring bitmap 的支持,高效计数聚合统计。 向量嵌入替代:pg_embedding ,提供了不同于 pgvector 的另一种 HNSW 替代实现。 可信语言扩展:pg_tle ,由 AWS 出品的,允许您打包分发管理由可信存储过程语言编写的函数。 HTTP 客户端扩展:pgsql-http :使用 SQL 接口,curl API,发起 HTTP 请求,与各类系统交互。 异步 HTTP 扩展: pg_net 允许您使用 SQL 发起非阻塞的 HTTP/HTTPS 请求。 列式存储引擎:hydra 针对分析场景打造的向量化列存储引擎,原地替代 Citus 列存插件。 其他 PGDG 扩展:新收录8个由 PGDG 维护的扩展插件,Pigsty 支持的插件总数达到 150+。 PostgreSQL 16 内核支持,监控云端 RDS / PolarDB for PostgreSQL。 亮点特性
Supabase 支持:开源的 Firebase 替代,现可使用 Pigsty 托管的 PostgreSQL 实例存储数据。PostgresML 支持:在 PostgreSQL 运行各类模型(hugging face),向量操作,经典机器学习算法。GraphQL 支持扩展: pg_graphql :从现有模式中反射出 GraphQL 模式,提供库内 GraphQL 查询能力。 异步 HTTP 客户端扩展: pg_net 允许您使用 SQL 发起非阻塞的 HTTP/HTTPS 请求 JWT 支持扩展:pgjwt 允许您使用 SQL 验证签发 JWT (JSON Web Tokens) 密钥存储扩展: vault 可以在保险柜里存储加密密钥 将 FerretDB 版本升级至 v1.10 新增组件:pg_filedump :可用于快速从 PostgreSQL 二进制文件中恢复数据 减少 EL9 离线软件包的大小,移除非必须依赖项 proj-data* 修复了 Patroni 3.1.1 的错误 efabe7632d8994f3fb58f9838b8f9d7d pigsty-pkg-v2.5.0.el7.x86_64.tgz # 1.1G
ea78957e8c8434b120d1c8c43d769b56 pigsty-pkg-v2.5.0.el8.x86_64.tgz # 1.4G
4ef280a7d28872814e34521978b851bb pigsty-pkg-v2.5.0.el9.x86_64.tgz # 1.3G
v2.4.0 使用 bash -c "$(curl -fsSL https://get.pigsty.cc/latest)" 快速上手。
最新特性
PostgreSQL 16 正式发布,Pigsty 提供支持。 可以监控云数据库,RDS for PostgreSQL,以及 PolarDB,提供全新的 PGRDS 监控面板 正式提供商业支持与咨询服务。并发布首个 LTS 版本,为订阅客户提供最长5年的支持。 新扩展插件:Apache AGE, openCypher graph query engine on PostgreSQL 新扩展插件:zhparser, full text search for Chinese language 新扩展插件:pg_roaringbitmap, roaring bitmap for PostgreSQL 新扩展插件:pg_embedding, hnsw alternative to pgvector 新扩展插件:pg_tle, admin / manage stored procedure extensions 新扩展插件:pgsql-http, issue http request with SQL interface 新增插件: pg_auth_mon pg_checksums pg_failover_slots pg_readonly postgresql-unit pg_store_plans pg_uuidv7 set_user Redis 改进:支持 Redis 哨兵监控,配置主从集群的自动高可用。 API 变化
新增参数,REDIS.redis_sentinel_monitor,用于指定 Sentinel 集群监控的主库列表 问题修复
修复 Grafana 10.1 注册数据源时缺少 uid 的问题 MD5 (pigsty-pkg-v2.4.0.el7.x86_64.tgz) = 257443e3c171439914cbfad8e9f72b17
MD5 (pigsty-pkg-v2.4.0.el8.x86_64.tgz) = 41ad8007ffbfe7d5e8ba5c4b51ff2adc
MD5 (pigsty-pkg-v2.4.0.el9.x86_64.tgz) = 9a950aed77a6df90b0265a6fa6029250
v2.3.1 使用 bash -c "$(curl -fsSL https://get.pigsty.cc/latest)" 快速开始。
最新特性
pgvector 更新至 0.5,添加 hnsw 算法支持。支持 PostgreSQL 16 RC1 (el8/el9) 默认包中添加了 SealOS 用于快速部署 Kubernetes 集群。 问题修复
修复了 infra.repo.repo_pkg 任务:当 repo_packages 中包名包含 * 时,下载可能会受到 /www/pigsty 现有内容的影响。 将 vip_dns_suffix 的默认值由 .vip 调整为空字符串,即集群本身的名称将默认作为节点集群的 L2 VIP modprobe watchdog and chown watchdog if patroni_watchdog_mode is required当 pg_dbsu_sudo = limit and patroni_watchdog_mode = required 时,授予数据库 dbsu 以下命令的 sudo 执行权限/usr/bin/sudo /sbin/modprobe softdog:在启动 Patroni 服务时确保 softdog 内核模块启用/usr/bin/sudo /bin/chown {{ pg_dbsu }} /dev/watchdog:在启动 Patroni 服务时,确保 watchdog 属主正确 文档更新
向英文文档中添加了更新内容。 添加了简体中文版本的内置文档,修复了 pigsty.cc 文档站的中文文档。 软件更新
PostgreSQL 16 RC1 for EL8/EL9 PGVector 0.5.0,支持 hnsw 索引 TimescaleDB 2.11.2 grafana 10.1.0 loki & promtail 2.8.4 redis-stack 7.2 on el7/8 mcli-20230829225506 / minio-20230829230735 ferretdb 1.9 sealos 4.3.3 pgbadger 1.12.2 ce69791eb622fa87c543096cdf11f970 pigsty-pkg-v2.3.1.el7.x86_64.tgz
495aba9d6d18ce1ebed6271e6c96b63a pigsty-pkg-v2.3.1.el8.x86_64.tgz
38b45582cbc337ff363144980d0d7b64 pigsty-pkg-v2.3.1.el9.x86_64.tgz
v2.3.0 相关文章:《Pigsty v2.3 发布:应用生态丰富 》
发布注记:https://github.com/Vonng/pigsty/releases/tag/v2.3.0
使用 bash -c "$(curl -fsSL https://get.pigsty.cc/latest)" 快速开始。
亮点特性
INFRA: 添加了对 NODE/PGSQL VIP 的监控支持 PGSQL: 通过小版本升级修复了 PostgreSQL CVE-2023-39417 : 15.4, 14.9, 13.12, 12.16,以及 Patroni v3.1.0 NODE: 允许用户使用 keepalived 为一个节点集群绑定 L2 VIP REPO: Pigsty 专用 yum 源优化精简,全站默认使用 HTTPS: get.pigsty.cc 与 demo.pigsty.cc APP: 升级 app/bytebase 版本至 v2.6.0, app/ferretdb 版本至 v1.8;添加新的应用模板:nocodb ,开源的 Airtable。 REDIS: 升级版本至 v7.2,并重制了 Redis 监控面板。 MONGO: 添加基于 FerretDB 1.8 实现的基本支持。 MYSQL: 添加了 Prometheus / Grafana / CA 中的代码存根,便于后续纳管。 API 变化
新增一个新的参数组 NODE.NODE_VIP:包含 8 个新参数
NODE.VIP.vip_enabled:在此节点集群上启用 vip 吗?NODE.VIP.vip_address:ipv4 格式的节点 vip 地址,如果启用了 vip,则必需NODE.VIP.vip_vrid:必需,整数,1-255 在相同 VLAN 中应该是唯一的NODE.VIP.vip_role:master/backup,默认为备份,用作初始角色NODE.VIP.vip_preempt:可选,true/false,默认为 false,启用 vip 抢占NODE.VIP.vip_interface:节点 vip 网络接口监听,eth0 默认NODE.VIP.vip_dns_suffix:节点 vip dns 名称后缀,默认为空字符串NODE.VIP.vip_exporter_port:keepalived 导出器监听端口,默认为 9650MD5 (pigsty-pkg-v2.3.0.el7.x86_64.tgz) = 81db95f1c591008725175d280ad23615
MD5 (pigsty-pkg-v2.3.0.el8.x86_64.tgz) = 6f4d169b36f6ec4aa33bfd5901c9abbe
MD5 (pigsty-pkg-v2.3.0.el9.x86_64.tgz) = 4bc9ae920e7de6dd8988ca7ee681459d
v2.2.0 相关文章:《Pigsty v2.2 发布 —— 监控系统大升级 》
发布注记:https://github.com/Vonng/pigsty/releases/tag/v2.2.0
快速开始: bash -c "$(curl -fsSL https://get.pigsty.cc/latest)"
亮点特性
监控面板重做: https://demo.pigsty.cc Vagrant 沙箱重做:支持 libvirt 与新的配置模板 Pigsty EL Yum 仓库:统一收纳零碎 RPM,简化安装构建流程。 操作系统兼容性:新增信创操作系统 UOS-v20-1050e 支持 新的配置模板:42 节点的生产仿真配置 统一使用官方 PGDG citus 软件包(el7) 软件升级
PostgreSQL 16 beta2 Citus 12 / PostGIS 3.3.3 / TimescaleDB 2.11.1 / PGVector 0.44 patroni 3.0.4 / pgbackrest 2.47 / pgbouncer 1.20 grafana 10.0.3 / loki/promtail/logcli 2.8.3 etcd 3.5.9 / haproxy v2.8.1 / redis v7.0.12 minio 20230711212934 / mcli 20230711233044 Bug 修复
修复了 Docker 组权限的问题 29434bd 将 infra 操作系统用户组作为额外的组,而不是首要用户组。 修复了 Redis Sentinel Systemd 服务的自动启用状态 5c96feb 放宽了 bootstrap & configure 的检查,特别是当 /etc/redhat-release 不存在的时候。 升级到 Grafana 10,修复了 Grafana 9.x CVE-2023-1410 在 CMDB pglog 模式中添加了 PG 14 - 16 的 command tags 与 错误代码。 API 变化
新增1个变量
INFRA.NGINX.nginx_exporter_enabled:现在用户可以通过设置这个参数来禁用 nginx_exporter。默认值变化:
repo_modules: node,pgsql,infra:redis 现在由 pigsty-el 仓库提供,不再需要 redis 模块。repo_upstream:新增 pigsty-el:与具体 EL 版本无关的 RPM: 例如 grafana, minio, pg_exporter, 等等…… 新增 pigsty-misc:与具体 EL 版本有关的 RPM: 例如 redis, prometheus 全家桶,等等…… 移除 citus:现在 PGDG 中有完整的 EL7 - EL9 citus 12 支持 移除 remi:redis 现在由 pigsty-el 仓库提供,不再需要 redis 模块。 repo_packages:ansible python3 python3-pip python3-requests python3-jmespath python3.11-jmespath dnf-utils modulemd-tools # el7: python36-requests python36-idna yum-utils grafana loki logcli promtail prometheus2 alertmanager karma pushgateway node_exporter blackbox_exporter nginx_exporter redis_exporter redis etcd minio mcli haproxy vip-manager pg_exporter nginx createrepo_c sshpass chrony dnsmasq docker-ce docker-compose-plugin flamegraph lz4 unzip bzip2 zlib yum pv jq git ncdu make patch bash lsof wget uuid tuned perf nvme-cli numactl grubby sysstat iotop htop rsync tcpdump netcat socat ftp lrzsz net-tools ipvsadm bind-utils telnet audit ca-certificates openssl openssh-clients readline vim-minimal postgresql13* wal2json_13* pg_repack_13* passwordcheck_cracklib_13* postgresql12* wal2json_12* pg_repack_12* passwordcheck_cracklib_12* timescaledb-tools postgresql15 postgresql15* citus_15* pglogical_15* wal2json_15* pg_repack_15* pgvector_15* timescaledb-2-postgresql-15* postgis33_15* passwordcheck_cracklib_15* pg_cron_15* postgresql14 postgresql14* citus_14* pglogical_14* wal2json_14* pg_repack_14* pgvector_14* timescaledb-2-postgresql-14* postgis33_14* passwordcheck_cracklib_14* pg_cron_14* postgresql16* wal2json_16* pgvector_16* pg_squeeze_16* postgis34_16* passwordcheck_cracklib_16* pg_cron_16* patroni patroni-etcd pgbouncer pgbadger pgbackrest pgloader pg_activity pg_partman_15 pg_permissions_15 pgaudit17_15 pgexportdoc_15 pgimportdoc_15 pg_statement_rollback_15* orafce_15* mysqlcompat_15 mongo_fdw_15* tds_fdw_15* mysql_fdw_15 hdfs_fdw_15 sqlite_fdw_15 pgbouncer_fdw_15 multicorn2_15* powa_15* pg_stat_kcache_15* pg_stat_monitor_15* pg_qualstats_15 pg_track_settings_15 pg_wait_sampling_15 system_stats_15 plprofiler_15* plproxy_15 plsh_15* pldebugger_15 plpgsql_check_15* pgtt_15 pgq_15* pgsql_tweaks_15 count_distinct_15 hypopg_15 timestamp9_15* semver_15* prefix_15* rum_15 geoip_15 periods_15 ip4r_15 tdigest_15 hll_15 pgmp_15 extra_window_functions_15 topn_15 pg_background_15 e-maj_15 pg_catcheck_15 pg_prioritize_15 pgcopydb_15 pg_filedump_15 pgcryptokey_15 logerrors_15 pg_top_15 pg_comparator_15 pg_ivm_15* pgsodium_15* pgfincore_15* ddlx_15 credcheck_15 safeupdate_15 pg_squeeze_15* pg_fkpart_15 pg_jobmon_15 repo_url_packages:node_default_packages:lz4,unzip,bzip2,zlib,yum,pv,jq,git,ncdu,make,patch,bash,lsof,wget,uuid,tuned,nvme-cli,numactl,grubby,sysstat,iotop,htop,rsync,tcpdump netcat,socat,ftp,lrzsz,net-tools,ipvsadm,bind-utils,telnet,audit,ca-certificates,openssl,readline,vim-minimal,node_exporter,etcd,haproxy,python3,python3-pip infra_packagesgrafana,loki,logcli,promtail,prometheus2,alertmanager,karma,pushgateway node_exporter,blackbox_exporter,nginx_exporter,redis_exporter,pg_exporter nginx,dnsmasq,ansible,postgresql15,redis,mcli,python3-requests PGSERVICE in .pigsty 被移除了,取而代之的是 PGDATABASE=postgres,这用户只需 IP 地址就可以从管理节点访问特定实例。目录结构变化:
bin/dns and bin/ssh 现在被移动到 vagrant/ 目录中。MD5 ( pigsty-pkg-v2.2.0.el7.x86_64.tgz) = 5fb6a449a234e36c0d895a35c76add3c
MD5 ( pigsty-pkg-v2.2.0.el8.x86_64.tgz) = c7211730998d3b32671234e91f529fd0
MD5 ( pigsty-pkg-v2.2.0.el9.x86_64.tgz) = 385432fe86ee0f8cbccbbc9454472fdd
v2.1.0 相关文章:Pigsty v2.1 发布:向量扩展 / PG12-16 支持
发布注记:https://github.com/Vonng/pigsty/releases/tag/v2.1.0
Highlight
PostgreSQL 16 beta 支持,以及 12 ~ 15 的支持。 为 PG 12 - 15 新增了 PGVector 扩展支持,用于存储 AI 嵌入。 为 Grafana 添加了额外6个默认的扩展面板/数据源插件。 添加 bin/profile 脚本用于执行远程 Profiling,生成火焰图。 添加 bin/validate 用于校验 pigsty.yml 配置文件合法性。 添加 bin/repo-add 用于快速向节点添加软件源定义。 PostgreSQL 16 可观测性:添加了 pg_stat_io 支持与相关监控面板 软件升级
PostgreSQL 15.3 , 14.8, 13.11, 12.15, 11.20, and 16 beta1 pgBackRest 2.46 / pgbouncer 1.19 Redis 7.0.11 Grafana v9.5.3 Loki / Promtail / Logcli 2.8.2 Prometheus 2.44 TimescaleDB 2.11.0 minio-20230518000536 / mcli-20230518165900 Bytebase v2.2.0 改进增强
当添加本地用户的公钥时,所有的 id*.pub 都会被添加到远程机器上(例如椭圆曲线算法生成的密钥文件) v2.0.2 https://github.com/Vonng/pigsty/releases/tag/v2.0.2
亮点
使用开箱即用的 pgvector 存储 AI Embedding、索引、检索向量。
变更
新扩展插件 pgvector 用于存储 AI 嵌入,并执行向量相似度搜索。 修复 MinIO CVE-2023-28432 ,使用 20230324 新提供的 policy API. 为 DNSMASQ systemd 服务添加动态重载命令 更新 PEV 版本至 v1.8 更新 grafana 版本至 v9.4.7 更新 MinIO 与 MCLI 版本至 20230324 更新 bytebase 版本至 v1.15.0 更新监控面板并修复死链接 更新了阿里云 Terraform 模板,默认使用 RockyLinux 9 使用 Grafana v9.4 的 Provisioning API 为众多管理任务添加了 asciinema 视频 修复了 EL8 PostgreSQL 的破损依赖:移除 anonymizer_15 faker_15 pgloader MD5 ( pigsty-pkg-v2.0.2.el7.x86_64.tgz) = d46440a115d741386d29d6de646acfe2
MD5 ( pigsty-pkg-v2.0.2.el8.x86_64.tgz) = 5fa268b5545ac96b40c444210157e1e1
MD5 ( pigsty-pkg-v2.0.2.el9.x86_64.tgz) = c8b113d57c769ee86a22579fc98e8345
v2.0.1 https://github.com/Vonng/pigsty/releases/tag/v2.0.1
安全性改进,与对 v2.0.0 的 BUG 修复。
改进
更换猪头 logo 以符合 PostgreSQL 商标政策。 将 grafana 版本升级至 v9.4,界面更佳且修复了 bug。 将 patroni 版本升级至 v3.0.1,其中包含了一些 bug 修复。 修改:将 grafana systemd 服务文件回滚到 rpm 默认的版本。 使用缓慢的 copy 代替 rsync 来复制 grafana 仪表板,更加可靠。 增强:bootstrap 执行后会添加回默认 repo 文件。 添加 asciinema 视频,用于各种管理任务。 安全增强模式:限制监控用户权限。 新的配置模板:dual.yml,用于双节点部署。 在 crit.yml 模板中启用 log_connections 和 log_disconnections。 在 crit.yml 模板中的 pg_libs 中启用 $lib/passwordcheck。 明确授予 pg_monitor 角色监视视图权限。 从 dbuser_monitor 中移除默认的 dbrole_readonly 以限制监控用户的权限 现在 patroni 监听在 {{ inventory_hostname }} 而不是 0.0.0.0 现在你可以使用 pg_listen 控制 postgres/pgbouncer 监听的地址 现在你可以在 pg_listen 中使用 ${ip}, ${lo}, ${vip} 占位符 将 Aliyun terraform 镜像从 centos 7.9 提升到 rocky Linux 9 将 bytebase 版本升级到 v1.14.0 BUG 修复
为 alertmanager 添加缺失的 advertise 地址。 解决使用 bin/pgsql-user 创建数据库用户时,pg_mode 变量缺失问题。 在 redis.yml 中为 Redis 集群加入任务添加 -a password 选项。 在 infra-rm.yml.remove infra data 任务中补充缺失的默认值。 修复 prometheus 监控对象定义文件的属主为 prometheus 用户。 使用 管理员用户 而不是 root 去删除 DCS 中的元数据。 修复了由 grafana 9.4 bug 导致的问题:Meta 数据源缺失。 注意事项
EL8 pgdg 上游官方源处于依赖破损状态,请小心使用。涉及到的软件包: postgis33_15, pgloader, postgresql_anonymizer_15*, postgresql_faker_15
如何升级?
cd ~/pigsty; tar -zcf /tmp/files.tgz files; rm -rf ~/pigsty # backup files dir and remove
cd ~; bash -c " $( curl -fsSL https://get.pigsty.cc/latest) " # get latest pigsty source
cd ~/pigsty; rm -rf files; tar -xf /tmp/files.tgz -C ~/pigsty # restore files dir
Checksums
MD5 ( pigsty-pkg-v2.0.1.el7.x86_64.tgz) = 5cfbe98fd9706b9e0f15c1065971b3f6
MD5 ( pigsty-pkg-v2.0.1.el8.x86_64.tgz) = c34aa460925ae7548866bf51b8b8759c
MD5 ( pigsty-pkg-v2.0.1.el9.x86_64.tgz) = 055057cebd93c473a67fb63bcde22d33
特别感谢 @cocoonkid 提供的反馈。
v2.0.0 相关文章:
Pigsty v2.0.0 正式发布!
从 v2.0.0 开始,PIGSTY 现在是 “PostgreSQL In Great STYle"的首字母缩写,即"全盛状态的 PostgreSQL”。
curl -fsSL https://get.pigsty.cc/latest | bash
Download directly from GitHub Release bash -c " $( curl -fsSL https://raw.githubusercontent.com/Vonng/pigsty/master/bin/get) "
# or download tarball directly with curl (EL9)
curl -L https://github.com/Vonng/pigsty/releases/download/v2.0.0/pigsty-v2.0.0.tgz -o ~/pigsty.tgz
curl -L https://github.com/Vonng/pigsty/releases/download/v2.0.0/pigsty-pkg-v2.0.0.el9.x86_64.tgz -o /tmp/pkg.tgz
# EL7: https://github.com/Vonng/pigsty/releases/download/v2.0.0/pigsty-pkg-v2.0.0.el7.x86_64.tgz
# EL8: https://github.com/Vonng/pigsty/releases/download/v2.0.0/pigsty-pkg-v2.0.0.el8.x86_64.tgz
亮点
完美整合 PostgreSQL 15, PostGIS 3.3, Citus 11.2, TimescaleDB 2.10,分布式地理时序超融合数据库。 OS 兼容性大幅增强:支持 EL7,8,9,以及 RHEL, CentOS, Rocky, OracleLinux, AlmaLinux 等兼容发行版。 安全性改进:自签名 CA,全局网络流量 SSL 加密,密码 scram-sha-256 认证,备份采用 AES 加密,重制的 HBA 规则系统。 Patroni 升级至3.0,提供原生的高可用 Citus 分布式集群支持,默认启用 FailSafe 模式,无惧 DCS 故障致全局主库瘫痪。 提供基于 pgBackRest 的开箱即用的时间点恢复 PITR 支持,默认支持本地文件系统与专用 MinIO/S3 集群备份。 新模块 ETCD,可独立部署,简易扩缩容,自带监控高可用,彻底取代 Consul 作为高可用 PG 的 DCS。 新模块 MINIO,可独立部署,支持多盘多节点部署,用作 S3 本地替代,亦用于集中式 PostgreSQL 备份仓库。 大幅精简配置文件参数,无需默认值即可使用;模板自动根据机器规格调整主机与 PG 参数,HBA/服务的定义更简洁泛用。 受 Grafana 与 MinIO 影响,软件协议由 Apache License 2.0 变更为 AGPL 3.0 兼容性
支持 EL7, EL8, EL9 三个大版本,并提供三个版本对应的离线软件包,默认开发测试环境由 EL7 升级至 EL9。 支持更多 EL 兼容 Linux 发行版:RHEL, CentOS, RockyLinux, AlmaLinux, OracleLinux 等… 源码包与离线软件包的命名规则发生改变,现在版本号,操作系统版本号,架构都会体现在包名中。 PGSQL:PostgreSQL 15.2, PostGIS 3.3, Citus 11.2, TimescaleDB 2.10 现可同时使用,协同工作。PGSQL:Patroni 升级至 3.0 版本,作为 PGSQL 的高可用组件。默认使用 ETCD 作为 DCS,取代 Consul,减少一个 Consul Agent 失效点。 因为 vip-manager 升级至 2.1 并使用 ETCDv3 API,彻底弃用 ETCDv2 API,Patroni 同理 提供原生的高可用 Citus 分布式集群支持。使用完全开源所有功能的 Citus 11.2。 默认启用 FailSafe 模式,无惧 DCS 故障致全局主库瘫痪。 PGSQL:引入 pgBackrest v2.44 提供开箱即用的 PostgreSQL 时间点恢复 PITR 功能默认使用主库上的备份目录创建备份仓库,滚动保留两天的恢复窗口。 默认备选备份仓库为专用 MinIO/S3 集群,滚动保留两周的恢复窗口,本地使用需要启用 MinIO 模块。 ETCD 现在作为一个独立部署的模块,带有完整的扩容/缩容方案与监控。MINIO 现在成为一个独立部署的模块,支持多盘多节点部署,用作 S3 本地替代,亦可用作集中式备份仓库。NODE 模块现在包含 haproxy, docker, node_exporter, promtail 功能组件chronyd 现在取代 ntpd 成为所有节点默认的 NTP 服务。HAPROXY 现从属于 NODE 的一部分,而不再是 PGSQL 专属,可以 NodePort 的方式对外暴露服务。 现在 PGSQL 模块可以使用专用的集中式 HAPROXY 集群统一对外提供服务。 INFRA 模块现在包含 dnsmasq, nginx, prometheus, grafana, loki 等组件Infra 模块中的 DNSMASQ 服务器默认启用,并添加为所有节点的默认 DNS 服务器之一。 添加了 blackbox_exporter 用于主机 PING 探测,pushgateway 用于批处理任务指标。 loki 与 promtail 现在使用 Grafana 默认的软件包,使用官方的 Grafana Echarts 面板插件提供针对 PostgreSQL 15 的新增可观测性位点的监控支持,添加 Patroni 监控 软件版本升级PostgreSQL 15.2 / PostGIS 3.3 / TimescaleDB 2.10 / Citus 11.2 Patroni 3.0 / Pgbouncer 1.18 / pgBackRest 2.44 / vip-manager 2.1 HAProxy 2.7 / Etcd 3.5 / MinIO 20230131022419 / mcli 20230128202938 Prometheus 2.42 / Grafana 9.3 / Loki & Promtail 2.7 / Node Exporter 1.5 安全性
启用了一个完整的本地自签名 CA:pigsty-ca,用于签发内网组件所使用的证书。 创建用户/修改密码的操作将不再会在日志文件中留下痕迹。 Nginx 默认启用 SSL 支持(如需 HTTPS,您需要在系统中信任pigsty-ca,或使用 Chrome thisisunsafe) ETCD 全面启用 SSL 加密客户端与服务端对等通信 PostgreSQL 添加并默认启用了 SSL 支持,管理链接默认都使用 SSL 访问。 Pgbouncer 添加了 SSL 支持,出于性能考虑默认不启用。 Patroni 添加了 SSL 支持,并默认限制了管理 API 只能从本机与管理节点使用密码认证方可访问。 PostgreSQL 的默认密码认证方式由 md5 改为 scram-sha-256。 Pgbouncer 添加了认证查询支持,可以动态管理连接池用户。 pgBackRest 使用远端集中备份存储仓库时,默认使用 AES-256-CBC 加密备份数据。 提供高安全等级配置模板:强制使用全局 SSL,并要求使用管理员证书登陆。 所有默认 HBA 规则现在全部在配置文件中显式定义。 可维护性
现有的配置模板可根据机器规格(CPU/内存/存储)自动调整优化。 现在可以动态配置 Postgres/Pgbouncer/Patroni/pgBackRest 的日志目录:默认为:/pg/log/<type>/ 原有的 IP 地址占位符 10.10.10.10 被替换为一个专用变量:${admin_ip},可在多处引用,便于切换备用管理节点。 您可以指定 region 来使用不同地区的上游镜像源,以加快软件包的下载速度。 现在允许用户定义更细粒度的上游源地址,您可以根据不同的 EL 版本、架构,以及地区,使用不同的上游源。 提供了阿里云与 AWS 中国地区的 Terraform 模板,可用于一键拉起所需的 EC2 虚拟机。 提供了多种不同规格的 Vagrant 沙箱模板:meta, full, el7/8/9, minio, build, citus 添加了新的专用剧本:pgsql-monitor.yml 用于监控现有的 Postgres 实例或 RDS。 添加了新的专用剧本:pgsql-migration.yml,使用逻辑复制无缝迁移现有实例至 Pigsty 管理的集群。 添加了一系列专用 Shell 实用命令,封装常见运维操作,方便用户使用。 优化了所有 Ansible Role 的实现,使其更加简洁、易读、易维护,无需默认参数即可使用。 允许在业务数据库/用户的层次上定义额外的 Pgbouncer 参数。 API 变更
Pigsty v2.0 进行了大量变更,新增64个参数,移除13个参数,重命名17个参数。
新增的参数
INFRA.META.admin_ip:主元节点 IP 地址INFRA.META.region:上游镜像区域:default|china|europeINFRA.META.os_version:企业版 Linux 发行版本:7,8,9INFRA.CA.ca_cn:CA 通用名称,默认为 pigsty-caINFRA.CA.cert_validity:证书有效期,默认为 20 年INFRA.REPO.repo_enabled:在 infra 节点上构建本地 yum 仓库吗?INFRA.REPO.repo_upstream:上游 yum 仓库定义列表INFRA.REPO.repo_home:本地 yum 仓库的主目录,通常与 nginx_home ‘/www’ 相同INFRA.NGINX.nginx_ssl_port:https 监听端口INFRA.NGINX.nginx_ssl_enabled:启用 nginx https 吗?INFRA.PROMTETHEUS.alertmanager_endpoint:altermanager 端点(ip|domain):端口格式NODE.NODE_TUNE.node_hugepage_ratio:内存 hugepage 比率,默认禁用,值为 0NODE.HAPROXY.haproxy_service:要公开的 haproxy 服务列表PGSQL.PG_ID.pg_mode:pgsql 集群模式:pgsql,citus,gpsqlPGSQL.PG_BUSINESS.pg_dbsu_password:dbsu 密码,默认为空字符串表示没有 dbsu 密码PGSQL.PG_INSTALL.pg_log_dir:postgres 日志目录,默认为 /pg/data/logPGSQL.PG_BOOTSTRAP.pg_storage_type:SSD|HDD,默认为 SSDPGSQL.PG_BOOTSTRAP.patroni_log_dir:patroni 日志目录,默认为 /pg/logPGSQL.PG_BOOTSTRAP.patroni_ssl_enabled:使用 SSL 保护 patroni RestAPI 通信?PGSQL.PG_BOOTSTRAP.patroni_username:patroni rest api 用户名PGSQL.PG_BOOTSTRAP.patroni_password:patroni rest api 密码(重要:请更改此密码)PGSQL.PG_BOOTSTRAP.patroni_citus_db:由 patroni 管理的 citus 数据库,默认为 postgresPGSQL.PG_BOOTSTRAP.pg_max_conn:postgres 最大连接数,auto 将使用推荐值PGSQL.PG_BOOTSTRAP.pg_shmem_ratio:postgres 共享内存比率,默认为 0.25,范围 0.1~0.4PGSQL.PG_BOOTSTRAP.pg_rto:恢复时间目标,故障转移的 ttl,默认为 30sPGSQL.PG_BOOTSTRAP.pg_rpo:恢复点目标,默认最多丢失 1MB 数据PGSQL.PG_BOOTSTRAP.pg_pwd_enc:密码加密算法:md5|scram-sha-256PGSQL.PG_BOOTSTRAP.pgbouncer_log_dir:pgbouncer 日志目录,默认为 /var/log/pgbouncerPGSQL.PG_BOOTSTRAP.pgbouncer_auth_query:如果启用,查询 pg_authid 表以检索 biz 用户,而不是填充用户列表PGSQL.PG_BOOTSTRAP.pgbouncer_sslmode:pgbouncer 客户端的 SSL:disable|allow|prefer|require|verify-ca|verify-fullPGSQL.PG_BOOTSTRAP.pg_service_provider:专用的 haproxy 节点组名称,或者默认为本地节点的空字符串PGSQL.PG_BOOTSTRAP.pg_default_service_dest:如果 svc.dest=‘default’,则为默认服务目标PGSQL.PG_BACKUP.pgbackrest_enabled:启用 pgbackrest 吗?PGSQL.PG_BACKUP.pgbackrest_clean:初始化期间删除 pgbackrest 数据吗?PGSQL.PG_BACKUP.pgbackrest_log_dir:pgbackrest 日志目录,默认为 /pg/logPGSQL.PG_BACKUP.pgbackrest_method:pgbackrest 备份仓库方法,local 或 minioPGSQL.PG_BACKUP.pgbackrest_repo:pgbackrest 备份仓库配置PGSQL.PG_DNS.pg_dns_suffix:pgsql dns 后缀,默认为空字符串PGSQL.PG_DNS.pg_dns_target:auto, primary, vip, none 或 ad hoc ipETCD.etcd_seq:etcd 实例标识符,必需ETCD.etcd_cluster:etcd 集群和组名称,默认为 etcdETCD.etcd_safeguard:防止清除正在运行的 etcd 实例吗?ETCD.etcd_clean:在初始化期间清除现有的 etcd 吗?ETCD.etcd_data:etcd 数据目录,默认为 /data/etcdETCD.etcd_port:etcd 客户端端口,默认为 2379ETCD.etcd_peer_port:etcd 对等端口,默认为 2380ETCD.etcd_init:etcd 初始集群状态,新建或已存在ETCD.etcd_election_timeout:etcd 选举超时,默认为 1000msETCD.etcd_heartbeat_interval:etcd 心跳间隔,默认为 100msMINIO.minio_seq:minio 实例标识符,必须参数MINIO.minio_cluster:minio 集群名称,默认为 minioMINIO.minio_clean:初始化时清理 minio 吗?默认为 falseMINIO.minio_user:minio 操作系统用户,默认为 minioMINIO.minio_node:minio 节点名模式MINIO.minio_data:minio 数据目录,使用 {x…y} 来指定多个驱动器MINIO.minio_domain:minio 外部域名,默认为 sss.pigstyMINIO.minio_port:minio 服务端口,默认为 9000MINIO.minio_admin_port:minio 控制台端口,默认为 9001MINIO.minio_access_key:根访问密钥,默认为 minioadminMINIO.minio_secret_key:根秘密密钥,默认为 minioadminMINIO.minio_extra_vars:minio 服务器的额外环境变量MINIO.minio_alias:本地 minio 部署的别名MINIO.minio_buckets:待创建的 minio 存储桶列表MINIO.minio_users:待创建的 minio 用户列表移除的参数
INFRA.CA.ca_homedir:CA 主目录,现在固定为 /etc/pki/INFRA.CA.ca_cert:CA 证书文件名,现在固定为 ca.keyINFRA.CA.ca_key:CA 密钥文件名,现在固定为 ca.keyINFRA.REPO.repo_upstreams:已被 repo_upstream 替代PGSQL.PG_INSTALL.pgdg_repo:现在由节点 playbooks 负责PGSQL.PG_INSTALL.pg_add_repo:现在由节点 playbooks 负责PGSQL.PG_IDENTITY.pg_backup:未使用且与部分名称冲突PGSQL.PG_IDENTITY.pg_preflight_skip:不再使用,由 pg_id 替代DCS.dcs_name:由于使用 etcd 而被移除DCS.dcs_servers:被 ad hoc 组 etcd 替代DCS.dcs_registry:由于使用 etcd 而被移除DCS.dcs_safeguard:被 etcd_safeguard 替代DCS.dcs_clean:被 etcd_clean 替代重命名的参数
nginx_upstream -> infra_portalrepo_address -> repo_endpointpg_hostname -> node_id_from_pgpg_sindex -> pg_grouppg_services -> pg_default_servicespg_services_extra -> pg_servicespg_hba_rules_extra -> pg_hba_rulespg_hba_rules -> pg_default_hba_rulespgbouncer_hba_rules_extra -> pgb_hba_rulespgbouncer_hba_rules -> pgb_default_hba_rulesvip_mode -> pg_vip_enabledvip_address -> pg_vip_addressvip_interface -> pg_vip_interfacenode_packages_default -> node_default_packagesnode_packages_meta -> infra_packagesnode_packages_meta_pip -> infra_packages_pipnode_data_dir -> node_dataChecksums
MD5 (pigsty-pkg-v2.0.0-rc1.el7.x86_64.tgz) = af4b5db9dc38c860de609956a8f1f0d3
MD5 (pigsty-pkg-v2.0.0-rc1.el8.x86_64.tgz) = 5b7152e142df3e3cbc06de30bd70e433
MD5 (pigsty-pkg-v2.0.0-rc1.el9.x86_64.tgz) = 1362e2a5680fc1a3a014cc4f304100bd
特别感谢意大利用户 @alemacci 在 SSL 加密,备份,多操作系统发行版适配与自适应参数模版上的贡献!
v1.5.1 亮点
重要:修复了 PG14.0-14.3 中 CREATE INDEX|REINDEX CONCURRENTLY 可能导致索引数据损坏的问题。
Pigsty v1.5.1 升级默认 PostgreSQL 版本至 14.4 强烈建议尽快更新。
软件升级
postgres 升级至 to 14.4 haproxy 升级至 to 2.6.0 grafana 升级至 to 9.0.0 prometheus 升级至 2.36.0 patroni 升级至 2.1.4 问题修复
修复了pgsql-migration.yml中的 TYPO 移除了 HAProxy 配置文件中的 PID 配置项 移除了默认软件包中的 i686 软件包 默认启用所有 Systemd Redis Service 默认启用所有 Systemd Patroni Service API 变更
grafana_database 与 grafana_pgurl 被标记为过时 API,将从后续版本移除New Apps
wiki.js : 使用 Postgres 搭建本地维基百科 FerretDB: 使用 Postgres 提供 MongoDB API v1.5.0 亮点概述
完善的 Docker 支持:在管理节点上默认启用并提供诸多开箱即用的软件模板:bytebase, pgadmin, pgweb, postgrest, minio 等。 基础设施自我监控:Nginx, ETCD, Consul, Prometheus, Grafana, Loki 自我监控 CMDB 升级:兼容性改善,支持 Redis 集群/Greenplum 集群元数据,配置文件可视化。 服务发现改进:可以使用 Consul 自动发现所有待监控对象,并纳入 Prometheus 中。 更好的冷备份支持:默认定时备份任务,添加pg_probackup备份工具,一键创建延时从库。 ETCD 现在可以用作 PostgreSQL/Patroni 的 DCS 服务,作为 Consul 的备选项。 Redis 剧本/角色改善:现在允许对单个 Redis 实例,而非整个 Redis 节点进行初始化与移除。 详细变更列表
监控面板
CMDB Overview:可视化 Pigsty CMDB Inventory。 DCS Overview:查阅 Consul 与 ETCD 集群的监控指标。 Nginx Overview:查阅 Pigsty Web 访问指标与访问日志。 Grafana Overview:Grafana 自我监控 Prometheus Overview:Prometheus 自我监控 INFRA Dashboard 进行重制,反映基础设施整体状态 监控架构
现在允许使用 Consul 进行服务发现(当所有服务注册至 Consul 时) 现在所有的 Infra 组件会启用自我监控,并通过infra_register角色注册至 Prometheus 与 Consul 中。 指标收集器 pg_exporter 更新至 v0.5.0,添加新功能,scale 与 default,允许为指标指定一个倍乘因子,以及指定默认值。 pg_bgwriter, pg_wal, pg_query, pg_db, pgbouncer_stat 关于时间的指标,单位由默认的毫秒或微秒统一缩放至秒。pg_table 中的相关计数器指标,现在配置有默认值 0,替代原有的NaN。pg_class指标收集器默认移除,相关指标添加至 pg_table 与 pg_index 收集器中。pg_table_size 指标收集器现在默认启用,默认设置有300秒的缓存时间。部署方案
新增可选软件包 docker.tgz,带有常用应用镜像:Pgadmin, Pgweb, Postgrest, ByteBase, Kong, Minio 等。 新增角色 ETCD,可以在 DCS Servers 指定的节点上自动部署 ETCD 服务,并自动纳入监控。 允许通过 pg_dcs_type 指定 PG 高可用使用的 DCS 服务,Consul(默认),ETCD(备选) 允许通过 node_crontab 参数,为节点配置定时任务,例如数据库备份、VACUUM,统计收集等。 新增了 pg_checksum 选项,启用时,数据库集群将启用数据校验和(此前只有crit模板默认启用) 新增了pg_delay选项,当实例为 Standby Cluster Leader 时,此参数可以用于配置一个延迟从库 新增了软件包 pg_probackup,默认角色replicator现在默认赋予了备份相关函数所需的权限。 Redis 部署现在拆分为两个部分:Redis 节点与 Redis 实例,通过redis_port参数可以精确控制一个具体实例。 Loki 与 Promtail 现在使用 frpm 制作的 RPM 软件包进行安装。 DCS3 配置模板现在使用一个3节点的pg-meta集群,与一个单节点的延迟从库。 软件升级
升级 PostgreSQL 至 14.3 升级 Redis 至 6.2.7 升级 PG Exporter 至 0.5.0 升级 Consul 至 1.12.0 升级 vip-manager 至 v1.0.2 升级 Grafana 至 v8.5.2 升级 Loki & Promtail 至 v2.5.0,使用 frpm 打包。 问题修复
修复了 Loki 与 Promtail 默认配置文件名的问题 修复了 Loki 与 Promtail 环境变量无法正确展开的问题 对英文文档进行了一次完整的翻译与修缮,文档依赖的 JS 资源现在直接从本地获取,无需互联网访问。 API 变化
新参数
node_data_dir:主要的数据挂载路径,如果不存在会被创建。node_crontab_overwrite:覆盖 /etc/crontab 而非追加内容。node_crontab:要被追加或覆盖的 node crontab 内容。nameserver_enabled:在这个基础设施节节点上启用 nameserver 吗?prometheus_enabled:在这个基础设施节节点上启用 prometheus 吗?grafana_enabled:在这个基础设施节节点上启用 grafana 吗?loki_enabled:在这个基础设施节节点上启用 loki 吗?docker_enable:在这个基础设施节点上启用 docker 吗?consul_enable:启用 consul 服务器/代理吗?etcd_enable:启用 etcd 服务器/客户端吗?pg_checksum:启用 pg 集群数据校验和吗?pg_delay:备份集群主库复制重放时的应用延迟。参数重制
现在 *_clean 是布尔类型的参数,用于在初始化期间清除现有实例。
*_safeguard 也是布尔类型的参数,用于在执行任何剧本时,避免清除正在运行的实例。
pg_exists_action -> pg_cleanpg_disable_purge -> pg_safeguarddcs_exists_action -> dcs_cleandcs_disable_purge -> dcs_safeguard参数重命名
node_ntp_config -> node_ntp_enablednode_admin_setup -> node_admin_enablednode_admin_pks -> node_admin_pk_listnode_dns_hosts -> node_etc_hosts_defaultnode_dns_hosts_extra -> node_etc_hostsnode_dns_server -> node_dns_methodnode_local_repo_url -> node_repo_local_urlsnode_packages -> node_packages_defaultnode_extra_packages -> node_packagesnode_packages_meta -> node_packages_metanode_meta_pip_install -> node_packages_meta_pipnode_sysctl_params -> node_tune_paramsapp_list -> nginx_indexesgrafana_plugin -> grafana_plugin_methodgrafana_cache -> grafana_plugin_cachegrafana_plugins -> grafana_plugin_listgrafana_git_plugin_git -> grafana_plugin_githaproxy_admin_auth_enabled -> haproxy_auth_enabledpg_shared_libraries -> pg_libsdcs_type -> pg_dcs_typev1.4.1 日常错误修复 / Docker 支持 / 英文文档
现在,默认在元节点上启用 docker。您可以使用它启动海量的各类软件
现在提供英文文档。
Bug 修复
v1.4.0 架构
将系统解耦为4大类别:INFRA、NODES、PGSQL、REDIS,这使得 pigsty 更加清晰、更易于扩展。 单节点部署 = INFRA + NODES + PGSQL 部署 pgsql 集群 = NODES + PGSQL 部署 redis 集群 = NODES + REDIS 部署其他数据库 = NODES + xxx(例如 MONGO、KAFKA…待定) 可访问性
为中国大陆提供 CDN。 使用 bash -c "$(curl -fsSL http://get.pigsty.cc/latest)" 获取最新源代码。 使用新的 download 脚本下载并提取包。 监控增强
将监控系统分为5大类别:INFRA、NODES、REDIS、PGSQL、APP 默认启用日志记录 模型和标签为所有仪表板添加了一个隐藏的ds prometheus 数据源变量,因此您只需选择一个新的数据源而不是修改 Grafana 数据源和仪表板。 为所有指标添加了一个ip标签,并将其用作数据库指标和节点指标之间的连接键。 INFRA 监控Infra 主仪表板:INFRA 概览 添加日志仪表板:日志实例 PGLOG 分析和 PGLOG 会话现在被视为一个示例 Pigsty APP。 NODES 监控应用如果您完全不关心数据库,现在可以单独使用 Pigsty 作为主机监控软件! 包括4个核心仪表板:节点概览 & 节点集群 & 节点实例 & 节点警报 为节点引入新的身份变量:node_cluster 和 nodename 变量pg_hostname现在意味着将主机名设置为与 postgres 实例名相同,以保持向后兼容性 变量nodename_overwrite 控制是否用 nodename 覆盖节点的主机名 变量nodename_exchange 将 nodename 写入彼此的/etc/hosts 所有节点指标引用都经过修订,通过ip连接 节点监控目标在/etc/prometheus/targets/nodes下单独管理 PGSQL 监控增强完全新的 PGSQL 集群,简化并专注于集群中的重要内容。 新仪表板 PGSQL 数据库是集群级对象监控。例如整个集群而不是单个实例的表和查询。 PGSQL 警报仪表板现在只关注 pgsql 警报。 PGSQL Shard 已添加到 PGSQL 中。 Redis 监控增强 MatrixDB 支持
通过pigsty-matrix.yml playbook 可以部署 MatrixDB(Greenplum 7) MatrixDB 监控仪表板:PGSQL MatrixDB 添加示例配置:pigsty-mxdb.yml 监控增强
将监控系统分为5大类别:INFRA、NODES、REDIS、PGSQL、APP 默认启用日志记录 模型和标签为所有仪表板添加了一个隐藏的ds prometheus 数据源变量,因此您只需选择一个新的数据源而不是修改 Grafana 数据源和仪表板。 为所有指标添加了一个ip标签,并将其用作数据库指标和节点指标之间的连接键。 INFRA 监控Infra 主仪表板:INFRA 概览 添加日志仪表板:日志实例 PGLOG 分析和 PGLOG 会话现在被视为一个示例 Pigsty APP。 NODES 监控应用如果您完全不关心数据库,现在可以单独使用 Pigsty 作为主机监控软件! 包括4个核心仪表板:节点概览 & 节点集群 & 节点实例 & 节点警报 为节点引入新的身份变量:node_cluster 和 nodename 变量pg_hostname现在意味着将主机名设置为与 postgres 实例名相同,以保持向后兼容性 变量nodename_overwrite 控制是否用 nodename 覆盖节点的主机名 变量nodename_exchange 将 nodename 写入彼此的/etc/hosts 所有节点指标引用都经过修订,通过ip连接 节点监控目标在/etc/prometheus/targets/nodes下单独管理 PGSQL 监控增强完全新的 PGSQL 集群,简化并专注于集群中的重要内容。 新仪表板 PGSQL 数据库是集群级对象监控。例如整个集群而不是单个实例的表和查询。 PGSQL 警报仪表板现在只关注 pgsql 警报。 PGSQL Shard 已添加到 PGSQL 中。 Redis 监控增强 MatrixDB 支持
通过pigsty-matrix.yml playbook 可以部署 MatrixDB(Greenplum 7) MatrixDB 监控仪表板:PGSQL MatrixDB 添加示例配置:pigsty-mxdb.yml 置备改进
现在 pigsty 的工作流如下:
infra.yml ---> 在单一的元节点上安装 pigsty
| 然后将更多节点加入 pigsty 的管理下
|
nodes.yml ---> 为 pigsty 准备节点(节点设置、dcs、node_exporter、promtail)
| 然后选择一个 playbook 在这些节点上部署数据库集群
|
^--> pgsql.yml 在已准备好的节点上安装 postgres
^--> redis.yml 在已准备好的节点上安装 redis
infra-demo.yml =
infra.yml -l meta +
nodes.yml -l pg-test +
pgsql.yml -l pg-test +
infra-loki.yml + infra-jupyter.yml + infra-pgweb.yml
nodes.yml:用于设置和准备 pigsty 的节点,在节点上设置 node、node_exporter、consul agent node-remove.yml 用于节点注销pgsql.yml:现在只在已准备好的节点上工作pgsql-remove 现在只负责 postgres 本身(dcs 和节点监控由 node.yml 负责)添加一系列新选项以在 greenplum/matrixdb 中重用 postgres 角色 redis.yml:现在在已准备好的节点上工作而 redis-remove.yml 现在从节点上移除 redis。 pgsql-matrix.yml 现在在已准备好的节点上安装 matrixdb(Greenplum 7)。软件升级
PostgreSQL 14.2 PostGIS 3.2 TimescaleDB 2.6 Patroni 2.1.3 (Prometheus 指标 + 故障转移插槽) HAProxy 2.5.5 (修复统计错误,更多指标) PG 导出器 0.4.1 (超时参数等) Grafana 8.4.4 Prometheus 2.33.4 Greenplum 6.19.4 / MatrixDB 4.4.0 Loki 现在作为 rpm 包提供,而不是 zip 存档。 错误修复
删除 patroni 的 consul 依赖,这使其更容易迁移到新的 consul 集群 修复 prometheus bin/new 脚本的默认数据目录路径:从 /export/prometheus 更改为 /data/prometheus 在 vip-manager systemd 服务中添加重新启动秒数 修复错别字和任务 API 变更
新增变量
node_cluster:节点集群的身份变量nodename_overwrite:如果设置,则 nodename 将设置为节点的主机名nodename_exchange:交换 play 主机之间的节点主机名(在 /etc/hosts 中)node_dns_hosts_extra:可以通过单个实例/集群轻松覆盖的额外静态 dns 记录patroni_enabled:如果禁用,postgres & patroni 的引导过程不会在 postgres 角色期间执行pgbouncer_enabled:如果禁用,pgbouncer 在 postgres 角色期间不会启动pg_exporter_params:生成监控目标 url 时为 pg_exporter 提供的额外 url 参数。pg_provision:布尔值变量,表示是否执行 postgres 角色的资源配置部分(模板,数据库,用户)no_cmdb:用于 infra.yml 和 infra-demo.yml 播放书,不会在元节点上创建 cmdb。MD5 (app.tgz) = f887313767982b31a2b094e5589a75ea
MD5 (matrix.tgz) = 3d063437c482d94bd7e35df1a08bbc84
MD5 (pigsty.tgz) = e143b88ebea1474f9ebaffddc6072c49
MD5 (pkg.tgz) = 73e8f5ce995b1f1760cb63c1904fb91b
v1.3.1 监控
PGSQL & PGCAT 仪表盘改进 优化 pgcat 实例 & pgcat 数据库的布局 在 pgsql 实例仪表盘中添加关键指标面板,与 pgsql 集群保持一致 在 pgcat 数据库中添加表/索引膨胀面板,移除 pgcat 膨胀仪表盘 在 pgcat 数据库仪表盘中添加索引信息 修复在 grafana 8.3 中的损坏面板 在 nginx 主页中添加 redis 索引 部署
新的 infra-demo.yml 剧本用于一次性引导 使用 infra-jupyter.yml 剧本部署可选的 jupyter lab 服务器 使用 infra-pgweb.yml 剧本部署可选的 pgweb 服务器 在 meta 节点上新的 pg 别名,可以从 admin 用户启动 postgres 集群(除了 postgres) 根据 timescaledb-tune 的建议调整所有 patroni 配置模板中的 max_locks_per_transactions 在配置模板中添加 citus.node_conninfo: 'sslmode=prefer' 以便在没有 SSL 的情况下使用 citus 在 pgdg14 包列表中添加所有扩展(除了 pgrouting) 将 node_exporter 升级到 v1.3.1 将 PostgREST v9.0.0 添加到包列表。从 postgres 模式生成 API。 错误修复
Grafana 的安全漏洞(升级到 v8.3.1 问题 ) 修复 pg_instance & pg_service 在 register 角色中从剧本的中间开始时的问题 修复在没有 pg_cluster 变量存在的主机上 nginx 主页渲染问题 在升级到 grafana 8.3.1 时修复样式问题 v1.3.0 【功能增强】Redis 部署(集群、哨兵、主从) 【功能增强】Redis 监控Redis 总览仪表盘 Redis 集群仪表盘 Redis 实例仪表盘
-【功能增强】 监控:PGCAT 大修 新仪表盘:PGCAT 实例 新仪表盘:PGCAT 数据库仪表盘 重做仪表盘:PGCAT 表格 【功能增强】 监控:PGSQL 增强新面板:PGSQL 集群,添加 10 个关键指标面板(默认切换) 新面板:PGSQL 实例,添加 10 个关键指标面板(默认切换) 简化 & 重新设计:PGSQL 服务 在 PGCAT & PGSL 仪表盘之间添加交叉引用
-【功能增强】 监控部署 现在 grafana 数据源在仅监控部署期间自动注册
-【功能增强】 软件升级 将 PostgreSQL 13 添加到默认包列表 默认升级到 PostgreSQL 14.1 添加 greenplum rpm 和依赖项 添加 redis rpm & 源代码包 将 perf 添加为默认包 v1.2.0 【功能增强】默认使用 PostgreSQL 14 版本 【功能增强】默认使用 TimescaleDB 2.5 扩展现在 timescaledb 和 postgis 默认在 cmdb 中启用 【功能增强】 新增仅监控模式:仅通过可连接的 URL,您可以使用 pigsty 监控现有的 pg 实例 pg_exporter 将在本地的 meta 节点上部署 新仪表板 PGSQL Cluster Monly 用于远程集群 【功能增强】软件升级grafana 升级到 8.2.2 pev2 升级到 v0.11.9 promscale 升级到 0.6.2 pgweb 升级到 0.11.9 新增扩展:pglogical、pg_stat_monitor、orafce
-【功能增强】自动检测机器规格并使用适当的 node_tune 和 pg_conf 模板
-【功能增强】重做与膨胀相关的视图,现在公开更多信息
-【功能增强】删除 timescale 和 citus 的内部监控
-【功能增强】新剧本 pgsql-audit.yml 用于创建审计报告
-【BUG 修复】现在 pgbouncer_exporter 资源所有者是 {{ pg_dbsu }} 而不是 postgres
-【BUG 修复】 修复在执行 REINDEX TABLE CONCURRENTLY 时 pg_exporter 在 pg_table pg_index 上的重复指标
-【功能增强】现在所有配置模板都减少到两个:auto 和 demo。(已删除:pub4, pg14, demo4, tiny, oltp) 如果 vagrant 是默认用户,则配置 pigsty-demo,否则使用 pigsty-auto。 如何从 v1.1.1 升级
在 1.2.0 中没有 API 变更。您仍然可以使用旧的 pigsty.yml 配置文件 (PG13)。
对于基础设施部分,重新执行 repo 将完成大部分工作。
至于数据库,您仍然可以使用现有的 PG13 实例。就地升级在涉及到像 PostGIS 和 Timescale 这样的扩展时非常棘手。我强烈推荐使用逻辑复制进行数据库迁移。
新的剧本 pgsql-migration.yml 将使这一过程变得容易得多。它将创建一系列的脚本,帮助您近乎零停机时间地迁移您的集群。
v1.1.1 【功能增强】 用 timescale 版本替换 timescaledb 的 apache 版本 【功能增强】 升级 prometheus 到 2.30 【BUG 修复】 现在 pg_exporter 配置目录的属主是 {{ pg_dbsu }},而不再是 prometheus 如何从 v1.1.0 升级?
这个版本的主要变动是 TimescaleDB,使用 TimescaleDB License (TSL)的官方版本替代了 PGDG 仓库中的 Apache License v2 的版本。
stop/pause postgres instance with timescaledb
yum remove -y timescaledb_13
[ timescale_timescaledb]
name = timescale_timescaledb
baseurl = https://packagecloud.io/timescale/timescaledb/el/7/$basearch
repo_gpgcheck = 0
gpgcheck = 0
enabled = 1
yum install timescaledb-2-postgresql13
v1.1.0 【增强功能】 增加 pg_dummy_filesize 以创建文件系统空间占位符 【增强功能】 主页大改版 【增强功能】 增加 Jupyter Lab 整合 【增强功能】 增加 pgweb 控制台整合 【增强功能】 增加 pgbadger 支持 【增强功能】 增加 pev2 支持,解释可视化工具 【增强功能】 增加 pglog 工具 【增强功能】 更新默认的 pkg.tgz 软件版本:PostgreSQL 升级至 v13.4(支持官方的 pg14) pgbouncer 升级至 v1.16(指标定义更新) Grafana 升级至 v8.1.4 Prometheus 升级至 v2.2.29 node_exporter 升级至 v1.2.2 haproxy 升级至 v2.1.1 consul 升级至 v1.10.2 vip-manager 升级至 v1.0.1 API 变更
nginx_upstream 现在持有不同的结构。(不兼容)新的配置条目:app_list,渲染至主页的导航条目 新的配置条目:docs_enabled,在默认服务器上设置本地文档 新的配置条目:pev2_enabled,设置本地的 pev2 工具 新的配置条目:pgbadger_enabled,创建日志概要/报告目录 新的配置条目:jupyter_enabled,在元节点上启用 Jupyter Lab 服务器 新的配置条目:jupyter_username,指定运行 Jupyter Lab 的用户 新的配置条目:jupyter_password,指定 Jupyter Lab 的默认密码 新的配置条目:pgweb_enabled,在元节点上启用 pgweb 服务器 新的配置条目:pgweb_username,指定运行 pgweb 的用户 将内部标记 repo_exist 重命名为 repo_exists 现在 repo_address 的默认值为 pigsty 而非 yum.pigsty 现在 haproxy 的访问点为 http://pigsty 而非 http://h.pigsty v1.0.1 2021-09-14
文档更新 错误修复:pgsql-remove 不会移除主实例 错误修复:用 pg_cluster + pg_seq 替换 pg_instanceStart-At-Task 可能因为 pg_instance 未定义而失败 错误修复:从默认共享预加载库中移除 cituscitus 会强制 max_prepared_transaction 的值为非零 错误修复:在 configure 中进行 ssh sudo 检查:现在使用 ssh -t sudo -n ls 进行权限检查 笔误修复:pg-backup 脚本的笔误 警报调整:移除 NTP 合理性检查警报(与 ClockSkew 重复) 导出器调整:移除 collector.systemd 以减少开销 v1.0.0 v1 正式发布,监控系统全面改进
亮点
监控系统全面改进在 Grafana 8.0 上新增仪表盘 新的度量定义,增加 PG14 支持 简化的标签系统:静态标签集:(job, cls, ins) 新的警报规则与衍生度量 同时监控多个数据库 实时日志搜索 & csvlog 分析 链接丰富的仪表盘,点击图形元素进行深入|汇总 架构变更将 citus 和 timescaledb 加入默认安装部分 增加对 PostgreSQL 14beta2 的支持 简化 haproxy 管理页面索引 通过添加新的角色 register 来解耦基础设施和 pgsql 添加新角色 loki 和 promtail 用于日志记录 为管理员节点上的管理员用户添加新角色 environ 以设置环境 默认使用 static 服务发现用于 prometheus(而不是 consul) 添加新角色 remove 以优雅地移除集群和实例 升级 prometheus 和 grafana 的配置逻辑 升级到 vip-manager 1.0,node_exporter 1.2,pg_exporter 0.4,grafana 8.0 现在,每个实例上的每个数据库都可以自动注册为 grafana 数据源 将 consul 注册任务移到 register 角色,更改 consul 服务标签 添加 cmdb.sql 作为 pg-meta 基线定义(CMDB & PGLOG) 应用框架可扩展框架用于新功能 核心应用:PostgreSQL 监控系统:pgsql 核心应用:PostgreSQL 目录浏览器:pgcat 核心应用:PostgreSQL Csvlog 分析器:pglog 添加示例应用 covid 用于可视化 covid-19 数据 添加示例应用 isd 用于可视化 isd 数据 其他添加 jupyterlab,为数据科学提供完整的 python 环境 添加 vonng-echarts-panel 以恢复对 Echarts 的支持 添加 wrap 脚本 createpg,createdb,createuser 添加 cmdb 动态库存脚本:load_conf.py,inventory_cmdb,inventory_conf 移除过时的剧本:pgsql-monitor,pgsql-service,node-remove 等…. API 变更
新变量: node_meta_pip_install 新变量: grafana_admin_username 新变量: grafana_database 新变量: grafana_pgurl 新变量: pg_shared_libraries 新变量: pg_exporter_auto_discovery 新变量: pg_exporter_exclude_database 新变量: pg_exporter_include_database 变量重命名: grafana_url 为 grafana_endpoint Bug 修复
修复默认时区 Asia/Shanghai (CST) 问题 修复 pgbouncer & patroni 的 nofile 限制 当执行标签 pgbouncer 时,pgbouncer 的用户列表和数据库列表将会被生成 v0.9.0 v0.9 极大简化了安装流程,进行了大量日志相关改进,开发了命令行工具(Beta),并修复了一系列问题。
新功能
一键安装模式:
/bin/bash -c " $( curl -fsSL https://pigsty.cc/install) "
开发命令行工具 pigsty-cli封装常用 Ansible 命令,目前 pigsty-cli 处于 Beta 状态
使用 Loki 与 Promtail 收集日志:
默认收集 Postgres,Pgbouncer,Patroni 日志 新增部署脚本infra-loki.yml 与 pgsql-promtail.yml 定义基于日志的监控指标 使用 Grafana 制作日志相关可视化面板。 监控组件可以使用二进制安装,使用files/get_bin.sh下载监控二进制组件。
飞升模式:
当集群元节点初始化完成后,可以使用bin/upgrade升级为动态 Inventory
使用 pg-meta 上的数据库代替 YAML 配置文件。
问题修复
集中修复日志相关问题:修复了 HAProxy 健康检查造成 PG 日志中大量 connection reset by peer的问题。 修复了 HAProxy 健康检查造成 Patroni 日志中大量出现Connect Reset Exception 的问题 修复了 Patroni 日志时间戳格式,去除毫秒时间戳,附加完整时区信息。 为dbuser_monitor配置1秒的log_min_duration_statement,避免监控查询出现在日志中。 重构 Grafana 角色在保持 API 不变的前提下重构 Grafana 角色。 使用 CDN 下载预打包的 Grafana 插件,加速插件下载 其他问题修复修复了pgbouncer-create-user 未能正确处理 md5 密码的问题。 完善了数据库与用户创建 SQL 模版中参数空置检查。 修复了 NODE DNS 配置时如果手工中断执行,DNS 配置可能出错的问题。 重构了 Makefile 快捷方式 Makefile 中的错别字 参数变更
node_disable_swap 默认为 False,默认不会关闭 SWAP。node_sysctl_params 不再有默认修改的系统参数。grafana_plugin 的默认值install 现在意味着当插件缓存不存在时,从 CDN 下载。repo_url_packages 现在从 Pigsty CDN 下载额外的 RPM 包,解决墙内无法访问的问题。proxy_env.no_proxy现在将 Pigsty CDN 加入到 NOPROXY 列表中。grafana_customize 现在默认为false,启用意味着安装 Pigsty Pro 版 UI(默认不开源所以不要启用)node_admin_pk_current,新增选项,启用后会将当前用户的~/.ssh/id_rsa.pub添加至管理员的 Key 中loki_clean:新增选项,安装 Loki 时是否清除现有数据loki_data_dir:新增选项,指明安装 Loki 时的数据目录promtail_enabled 是否启用 Promtail 日志收集服务?promtail_clean 是否在安装 promtail 时移除已有状态信息?promtail_port promtail 使用的默认端口,默认为9080promtail_status_file 保存 Promtail 状态信息的文件位置promtail_send_url 用于接收日志的 loki 服务 endpointv0.8.0 v0.8 针对 服务(Service) 接入部分进行了彻底的重做。现在除了默认的primary, replica服务外,用户可以自行定义新的服务。服务的接口可以支持多种不同的实现,例如 L4 DPKG VIP 可作为 Haproxy 的替代品与 Pigsty 集成。同时,针对用户反馈的一些问题进行了集中处理与改进。
改动内容
v0.8 是供给方案定稿版本,此后供给系统的 API 将保持稳定。
API 变更
原有vip与haproxy角色的所有配置项,现在迁移至service角色中。
#------------------------------------------------------------------------------
# SERVICE PROVISION
#------------------------------------------------------------------------------
pg_weight : 100 # default load balance weight (instance level)
# - service - #
pg_services : # how to expose postgres service in cluster?
# primary service will route {ip|name}:5433 to primary pgbouncer (5433->6432 rw)
- name : primary # service name {{ pg_cluster }}_primary
src_ip : "*"
src_port : 5433
dst_port : pgbouncer # 5433 route to pgbouncer
check_url : /primary # primary health check, success when instance is primary
selector : "[]" # select all instance as primary service candidate
# replica service will route {ip|name}:5434 to replica pgbouncer (5434->6432 ro)
- name : replica # service name {{ pg_cluster }}_replica
src_ip : "*"
src_port : 5434
dst_port : pgbouncer
check_url : /read-only # read-only health check. (including primary)
selector : "[]" # select all instance as replica service candidate
selector_backup : "[? pg_role == `primary`]" # primary are used as backup server in replica service
# default service will route {ip|name}:5436 to primary postgres (5436->5432 primary)
- name : default # service's actual name is {{ pg_cluster }}-{{ service.name }}
src_ip : "*" # service bind ip address, * for all, vip for cluster virtual ip address
src_port : 5436 # bind port, mandatory
dst_port: postgres # target port : postgres|pgbouncer|port_number , pgbouncer(6432) by default
check_method: http # health check method : only http is available for now
check_port: patroni # health check port : patroni|pg_exporter|port_number , patroni by default
check_url : /primary # health check url path, / as default
check_code : 200 # health check http code, 200 as default
selector : "[]" # instance selector
haproxy : # haproxy specific fields
maxconn : 3000 # default front-end connection
balance : roundrobin # load balance algorithm (roundrobin by default)
default_server_options : 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'
# offline service will route {ip|name}:5438 to offline postgres (5438->5432 offline)
- name : offline # service name {{ pg_cluster }}_replica
src_ip : "*"
src_port : 5438
dst_port : postgres
check_url : /replica # offline MUST be a replica
selector : "[? pg_role == `offline` || pg_offline_query ]" # instances with pg_role == 'offline' or instance marked with 'pg_offline_query == true'
selector_backup : "[? pg_role == `replica` && !pg_offline_query]" # replica are used as backup server in offline service
pg_services_extra : [] # extra services to be added
# - haproxy - #
haproxy_enabled : true # enable haproxy among every cluster members
haproxy_reload : true # reload haproxy after config
haproxy_policy : roundrobin # roundrobin, leastconn
haproxy_admin_auth_enabled : false # enable authentication for haproxy admin?
haproxy_admin_username : admin # default haproxy admin username
haproxy_admin_password : admin # default haproxy admin password
haproxy_exporter_port : 9101 # default admin/exporter port
haproxy_client_timeout : 3h # client side connection timeout
haproxy_server_timeout : 3h # server side connection timeout
# - vip - #
vip_mode : none # none | l2 | l4
vip_reload : true # whether reload service after config
# vip_address: 127.0.0.1 # virtual ip address ip (l2 or l4)
# vip_cidrmask: 24 # virtual ip address cidr mask (l2 only)
# vip_interface: eth0 # virtual ip network interface (l2 only)
新增选项
# - localization - #
pg_encoding : UTF8 # default to UTF8
pg_locale : C # default to C
pg_lc_collate : C # default to C
pg_lc_ctype : en_US.UTF8 # default to en_US.UTF8
pg_reload : true # reload postgres after hba changes
vip_mode : none # none | l2 | l4
vip_reload : true # whether reload service after config
移除选项
haproxy_check_port # Haproxy相关参数已经被Service定义覆盖
haproxy_primary_port
haproxy_replica_port
haproxy_backend_port
haproxy_weight
haproxy_weight_fallback
vip_enabled # vip_enabled参数被vip_mode覆盖
服务管理
pg_services 与 pg_services_extra 定义了集群中的服务 ,每一个服务的定义结构如下例所示:
一个服务必须指定以下内容:
名称 :服务的完整名称以数据库集群名为前缀,以service.name为后缀,通过-连接。例如在pg-test集群中name=primary的服务,其完整服务名称为pg-test-primary。
端口 :在 Pigsty 中,服务默认采用 NodePort 的形式对外暴露,因此暴露端口为必选项。但如果使用外部负载均衡服务接入方案,您也可以通过其他的方式区分服务。
选择器 :选择器指定了服务的成员,采用 JMESPath 的形式,从所有集群实例成员中筛选变量。默认的[]选择器会选取所有的集群成员。
此外selector_backup会选择或标记用于 backup 的实例列表(当集群中所有其他成员失效时方才接管服务)
# default service will route {ip|name}:5436 to primary postgres (5436->5432 primary)
- name : default # service's actual name is {{ pg_cluster }}-{{ service.name }}
src_ip : "*" # service bind ip address, * for all, vip for cluster virtual ip address
src_port : 5436 # bind port, mandatory
dst_port: postgres # target port : postgres|pgbouncer|port_number , pgbouncer(6432) by default
check_method: http # health check method : only http is available for now
check_port: patroni # health check port : patroni|pg_exporter|port_number , patroni by default
check_url : /primary # health check url path, / as default
check_code : 200 # health check http code, 200 as default
selector : "[]" # instance selector
haproxy : # haproxy specific fields
maxconn : 3000 # default front-end connection
balance : roundrobin # load balance algorithm (roundrobin by default)
default_server_options : 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'
数据库管理
数据库现在可以对 locale 的细分选项:lc_ctype与lc_collate分别进行指定。支持这一功能的主要原因是 PG 的扩展插件pg_trgm需要在lc_ctype!=C的环境中才能正常支持中文。
旧接口定义
pg_databases :
- name : meta # name is the only required field for a database
owner : postgres # optional, database owner
template : template1 # optional, template1 by default
encoding : UTF8 # optional, UTF8 by default
locale : C # optional, C by default
allowconn : true # optional, true by default, false disable connect at all
revokeconn : false # optional, false by default, true revoke connect from public # (only default user and owner have connect privilege on database)
tablespace : pg_default # optional, 'pg_default' is the default tablespace
connlimit : -1 # optional, connection limit, -1 or none disable limit (default)
extensions : # optional, extension name and where to create
- {name: postgis, schema : public}
parameters : # optional, extra parameters with ALTER DATABASE
enable_partitionwise_join : true
pgbouncer : true # optional, add this database to pgbouncer list? true by default
comment : pigsty meta database # optional, comment string for database
新的接口定义
pg_databases :
- name : meta # name is the only required field for a database
# owner: postgres # optional, database owner
# template: template1 # optional, template1 by default
# encoding: UTF8 # optional, UTF8 by default , must same as template database, leave blank to set to db default
# locale: C # optional, C by default , must same as template database, leave blank to set to db default
# lc_collate: C # optional, C by default , must same as template database, leave blank to set to db default
# lc_ctype: C # optional, C by default , must same as template database, leave blank to set to db default
allowconn : true # optional, true by default, false disable connect at all
revokeconn : false # optional, false by default, true revoke connect from public # (only default user and owner have connect privilege on database)
# tablespace: pg_default # optional, 'pg_default' is the default tablespace
connlimit : -1 # optional, connection limit, -1 or none disable limit (default)
extensions : # optional, extension name and where to create
- {name: postgis, schema : public}
parameters : # optional, extra parameters with ALTER DATABASE
enable_partitionwise_join : true
pgbouncer : true # optional, add this database to pgbouncer list? true by default
comment : pigsty meta database # optional, comment string for database
v0.7.0 v0.7 针对接入已有数据库实例 进行了改进,现在用户可以采用 仅监控部署(Monly Deployment) 模式使用 Pigsty。同时新增了专用于管理数据库与用户、以及单独部署监控的剧本,并对数据库与用户的定义进行改进。
Features
Bug Fix
API 变更
新增选项
prometheus_sd_target : batch # batch|single 监控目标定义文件采用单体还是每个实例一个
exporter_install : none # none|yum|binary 监控Exporter的安装模式
exporter_repo_url : '' # 如果设置,这里的REPO连接会加入目标的Yum源中
node_exporter_options : '--no-collector.softnet --collector.systemd --collector.ntp --collector.tcpstat --collector.processes' # Node Exporter默认的命令行选项
pg_exporter_url : '' # 可选,PG Exporter监控对象的URL
pgbouncer_exporter_url : '' # 可选,PGBOUNCER EXPORTER监控对象的URL
移除选项
exporter_binary_install : false # 功能被 exporter_install 覆盖
定义结构变更
pg_default_roles # 变化细节参考 用户管理。
pg_users # 变化细节参考 用户管理。
pg_databases # 变化细节参考 数据库管理。
重命名选项
pg_default_privilegs -> pg_default_privileges # 很明显这是一个错别字
仅监控模式
有时用户不希望使用 Pigsty 供给方案,只希望使用 Pigsty 监控系统管理现有 PostgreSQL 实例。
Pigsty 提供了仅监控部署(monly, monitor-only 模式,剥离供给方案部分,可用于监控现有 PostgreSQL 集群。
仅监控模式的部署流程与标准模式大体上保持一致,但省略了很多步骤
在元节点 上完成基础设施初始化的部分与标准流程保持一致,仍然通过./infra.yml完成。 不需要在数据库节点 上完成 基础设施初始化 。 不需要在数据库节点 上执行数据库初始化的绝大多数任务,而是通过专用的./pgsql-monitor.yml 完成仅监控系统部署。 实际使用的配置项大大减少,只保留基础设施相关变量,与 监控系统相关的少量变量。 数据库管理
Database provisioning interface enhancement #33
旧接口定义
pg_databases : # create a business database 'meta'
- name : meta
schemas : [ meta] # create extra schema named 'meta'
extensions : [ {name : postgis}] # create extra extension postgis
parameters : # overwrite database meta's default search_path
search_path : public, monitor
新的接口定义
pg_databases :
- name : meta # name is the only required field for a database
owner : postgres # optional, database owner
template : template1 # optional, template1 by default
encoding : UTF8 # optional, UTF8 by default
locale : C # optional, C by default
allowconn : true # optional, true by default, false disable connect at all
revokeconn : false # optional, false by default, true revoke connect from public # (only default user and owner have connect privilege on database)
tablespace : pg_default # optional, 'pg_default' is the default tablespace
connlimit : -1 # optional, connection limit, -1 or none disable limit (default)
extensions : # optional, extension name and where to create
- {name: postgis, schema : public}
parameters : # optional, extra parameters with ALTER DATABASE
enable_partitionwise_join : true
pgbouncer : true # optional, add this database to pgbouncer list? true by default
comment : pigsty meta database # optional, comment string for database
接口变更
Add new options: template , encoding, locale, allowconn, tablespace, connlimit Add new option revokeconn, which revoke connect privileges from public for this database Add comment field for database 数据库变更
在运行中集群中创建新数据库可以使用pgsql-createdb.yml剧本,在配置中定义完新数据库后,执行以下剧本。
./pgsql-createdb.yml -e pg_database = <your_new_database_name>
通过-e pg_datbase=告知需要创建的数据库名称,则该数据库即会被创建(或修改)。具体执行的命令参见集群主库/pg/tmp/pg-db-{{ database.name}}.sql文件。
用户管理
User provisioning interface enhancement #34
旧接口定义
pg_users :
- username : test # example production user have read-write access
password : test # example user's password
options : LOGIN # extra options
groups : [ dbrole_readwrite ] # dborole_admin|dbrole_readwrite|dbrole_readonly
comment : default test user for production usage
pgbouncer : true # add to pgbouncer
新接口定义
pg_users :
# complete example of user/role definition for production user
- name : dbuser_meta # example production user have read-write access
password : DBUser.Meta # example user's password, can be encrypted
login : true # can login, true by default (should be false for role)
superuser : false # is superuser? false by default
createdb : false # can create database? false by default
createrole : false # can create role? false by default
inherit : true # can this role use inherited privileges?
replication : false # can this role do replication? false by default
bypassrls : false # can this role bypass row level security? false by default
connlimit : -1 # connection limit, -1 disable limit
expire_at : '2030-12-31' # 'timestamp' when this role is expired
expire_in : 365 # now + n days when this role is expired (OVERWRITE expire_at)
roles : [ dbrole_readwrite] # dborole_admin|dbrole_readwrite|dbrole_readonly
pgbouncer : true # add this user to pgbouncer? false by default (true for production user)
parameters : # user's default search path
search_path : public
comment : test user
接口变更
username field rename to namegroups field rename to rolesoptions now split into separated configration entries:
login, superuser, createdb, createrole, inherit, replication,bypassrls,connlimitexpire_at and expire_in optionspgbouncer option for user is now false by default用户管理
在运行中集群中创建新数据库可以使用pgsql-createuser.yml剧本,在配置中定义完新数据库后,执行以下剧本。
./pgsql-createuser.yml -e pg_user = <your_new_user_name>
通过-e pg_user=告知需要创建的数据库名称,则该数据库即会被创建(或修改)。具体执行的命令参见集群主库/pg/tmp/pg-user-{{ user.name}}.sql文件。
v0.6.0 v0.6 对数据库供给方案进行了修改与调整,根据用户的反馈添加了一系列实用功能与修正。针对监控系统的移植性进行优化,便于与其他外部数据库供给方案对接。
BUG 修复
修复了新版本 Patroni 重启后会重置 PG HBA 的问题 修复了 PG Overview Dashboard 标题中的别字 修复了沙箱集群pg-test的默认主库,原来为pg-test-2,应当为pg-test-1 修复了过时代码注释 功能改进
改造 Prometheus 与监控供给方式允许在无基础设施的情况下对已有 PG 集群进行监控部署,便于监控系统与其他供给方案集成。#11 基于 Inventory 渲染所有监控对象的静态列表,用于静态服务发现。#11 Prometheus 添加了静态对象模式,用于替代动态服务发现,集中进行身份管理 #11 监控 Exporter 现在添加了service_registry选项,Consul 服务注册变为可选项 #13 Exporter 现在可以通过拷贝二进制的方式直接安装:exporter_binary_install,#14 Exporter 现在具有xxx_enabled选项,控制是否启用该组件。 Haproxy 供给重构与改进 #8 新增了全局 HAProxy 管理界面导航,默认域名h.pigsty 允许将主库加入只读服务集中,当集群中所有从库宕机时自动承接读流量。 #8 允许位 Haproxy 实例管理界面启用认证 haproxy_admin_auth_enabled 允许通过配置项调整每个服务对应后端的流量权重. #10 访问控制模型改进。#7 添加了默认角色dbrole_offline,用于慢查询,ETL,交互式查询场景。 修改默认 HBA 规则,允许dbrole_offline分组的用户访问pg_role == 'offline'及pg_offline_query == true的实例。 软件更新 Release v0.6PostgreSQL 13.2 Prometheus 2.25 PG Exporter 0.3.2 Node Exporter 1.1 Consul 1.9.3 更新默认 PG 源:PostgreSQL 现在默认使用浙江大学的镜像,加速下载安装 接口变更
新增选项
service_registry : consul # 服务注册机制:none | consul | etcd | both
prometheus_options : '--storage.tsdb.retention=30d' # prometheus命令行选项
prometheus_sd_method : consul # Prometheus使用的服务发现机制:static|consul
prometheus_sd_interval : 2s # Prometheus服务发现刷新间隔
pg_offline_query : false # 设置后将允许dbrole_offline角色连接与查询该实例
node_exporter_enabled : true # 设置后将安装配置Node Exporter
pg_exporter_enabled : true # 设置后将安装配置PG Exporter
pgbouncer_exporter_enabled : true # 设置后将安装配置Pgbouncer Exporter
dcs_disable_purge : false # 双保险,强制 dcs_exists_action = abort 避免误删除DCS实例
pg_disable_purge : false # 双保险,强制 pg_exists_action = abort 避免误删除数据库实例
haproxy_weight : 100 # 配置实例的相对负载均衡权重
haproxy_weight_fallback : 1 # 配置集群主库在只读服务中的相对权重
移除选项
prometheus_metrics_path # 与 exporter_metrics_path 重复
prometheus_retention # 功能被 prometheus_options 覆盖
v0.5.0 Pigsty 现在有了官方网站啦:pigsty.cc 🎉 !
亮点特性
Pigsty 官方 文档站 正式上线! 添加了数据库模板的定制支持,用户可以通过配置文件定制所需的数据库内部对象。 对默认 访问控制 模型进行了改进 重构了 HBA 管理的逻辑,现在将由 Pigsty 替代 Patroni 直接负责生成 HBA 将 Grafana 监控系统的供给方案从 sqlite 改为 JSON 文件静态 Provision 将pg-cluster-replication面板加入 Pigsty 开源免费套餐。 最新的经过测试的离线安装包:pkg.tgz (v0.5) 定制数据库
您是否烦恼过单实例多租户的问题?比如总有研发拿着 PostgreSQL 当 MySQL 使,明明是一个 Schema 就能解决的问题,非要创建一个新的数据库出来,在一个实例中创建出几十个不同的 DB。
不要忧伤,不要心急。Pigsty 已经提供数据库内部对象的 Provision 方案,您可以轻松地在配置文件中指定所需的数据库内对象,包括:
角色 数据库属主 额外的模式 额外的扩展插件 数据库级的自定义配置参数 数据库属主 额外的模式 额外的扩展插件 数据库级的自定义配置参数 默认权限默认情况下这里配置的权限会应用至所有由 超级用户 和 管理员用户创建的对象上。 默认扩展 默认模式 配置样例
# 通常是每个DB集群配置的变量
pg_users :
- username : test
password : test
comment : default test user
groups : [ dbrole_readwrite ] # dborole_admin|dbrole_readwrite|dbrole_readonly
pg_databases : # create a business database 'test'
- name : test
extensions : [ {name : postgis}] # create extra extension postgis
parameters : # overwrite database meta's default search_path
search_path : public,monitor
# 通常是整个环境统一配置的全局变量
# - system roles - #
pg_replication_username : replicator # system replication user
pg_replication_password : DBUser.Replicator # system replication password
pg_monitor_username : dbuser_monitor # system monitor user
pg_monitor_password : DBUser.Monitor # system monitor password
pg_admin_username : dbuser_admin # system admin user
pg_admin_password : DBUser.Admin # system admin password
# - default roles - #
pg_default_roles :
- username : dbrole_readonly # sample user :
options : NOLOGIN # role can not login
comment : role for readonly access # comment string
- username: dbrole_readwrite # sample user : one object for each user
options : NOLOGIN
comment : role for read-write access
groups : [ dbrole_readonly ] # read-write includes read-only access
- username: dbrole_admin # sample user : one object for each user
options : NOLOGIN BYPASSRLS # admin can bypass row level security
comment : role for object creation
groups : [ dbrole_readwrite,pg_monitor,pg_signal_backend]
# NOTE: replicator, monitor, admin password are overwritten by separated config entry
- username : postgres # reset dbsu password to NULL (if dbsu is not postgres)
options : SUPERUSER LOGIN
comment : system superuser
- username : replicator
options : REPLICATION LOGIN
groups : [ pg_monitor, dbrole_readonly]
comment : system replicator
- username : dbuser_monitor
options : LOGIN CONNECTION LIMIT 10
comment : system monitor user
groups : [ pg_monitor, dbrole_readonly]
- username : dbuser_admin
options : LOGIN BYPASSRLS
comment : system admin user
groups : [ dbrole_admin]
- username : dbuser_stats
password : DBUser.Stats
options : LOGIN
comment : business read-only user for statistics
groups : [ dbrole_readonly]
# object created by dbsu and admin will have their privileges properly set
pg_default_privilegs :
- GRANT USAGE ON SCHEMAS TO dbrole_readonly
- GRANT SELECT ON TABLES TO dbrole_readonly
- GRANT SELECT ON SEQUENCES TO dbrole_readonly
- GRANT EXECUTE ON FUNCTIONS TO dbrole_readonly
- GRANT INSERT, UPDATE, DELETE ON TABLES TO dbrole_readwrite
- GRANT USAGE, UPDATE ON SEQUENCES TO dbrole_readwrite
- GRANT TRUNCATE, REFERENCES, TRIGGER ON TABLES TO dbrole_admin
- GRANT CREATE ON SCHEMAS TO dbrole_admin
- GRANT USAGE ON TYPES TO dbrole_admin
# schemas
pg_default_schemas : [ monitor]
# extension
pg_default_extensions :
- { name: 'pg_stat_statements', schema : 'monitor' }
- { name: 'pgstattuple', schema : 'monitor' }
- { name: 'pg_qualstats', schema : 'monitor' }
- { name: 'pg_buffercache', schema : 'monitor' }
- { name: 'pageinspect', schema : 'monitor' }
- { name: 'pg_prewarm', schema : 'monitor' }
- { name: 'pg_visibility', schema : 'monitor' }
- { name: 'pg_freespacemap', schema : 'monitor' }
- { name: 'pg_repack', schema : 'monitor' }
- name : postgres_fdw
- name : file_fdw
- name : btree_gist
- name : btree_gin
- name : pg_trgm
- name : intagg
- name : intarray
# postgres host-based authentication rules
pg_hba_rules :
- title : allow meta node password access
role : common
rules :
- host all all 10.10.10.10/32 md5
- title : allow intranet admin password access
role : common
rules :
- host all +dbrole_admin 10.0.0.0/8 md5
- host all +dbrole_admin 172.16.0.0/12 md5
- host all +dbrole_admin 192.168.0.0/16 md5
- title : allow intranet password access
role : common
rules :
- host all all 10.0.0.0/8 md5
- host all all 172.16.0.0/12 md5
- host all all 192.168.0.0/16 md5
- title : allow local read-write access (local production user via pgbouncer)
role : common
rules :
- local all +dbrole_readwrite md5
- host all +dbrole_readwrite 127.0.0.1/32 md5
- title : allow read-only user (stats, personal) password directly access
role : replica
rules :
- local all +dbrole_readonly md5
- host all +dbrole_readonly 127.0.0.1/32 md5
pg_hba_rules_extra : []
# pgbouncer host-based authentication rules
pgbouncer_hba_rules :
- title : local password access
role : common
rules :
- local all all md5
- host all all 127.0.0.1/32 md5
- title : intranet password access
role : common
rules :
- host all all 10.0.0.0/8 md5
- host all all 172.16.0.0/12 md5
- host all all 192.168.0.0/16 md5
pgbouncer_hba_rules_extra : []
数据库模板
权限模型
v0.5 改善了默认的权限模型,主要是针对单实例多租户的场景进行优化,并收紧权限控制。
撤回了普通业务用户对非所属数据库的默认CONNECT权限 撤回了非管理员用户对所属数据库的默认CREATE权限 撤回了所有用户在public模式下的默认创建权限。 供给方式
原先 Pigsty 采用直接拷贝 Grafana 自带的 grafana.db 的方式完成监控系统的初始化。
这种方式虽然简单粗暴管用,但不适合进行精细化的版本控制管理。在 v0.5 中,Pigsty 采用了 Grafana API 完成了监控系统面板供给的工作。
您所需的就是在grafana_url中填入带有用户名密码的 Grafana URL。
因此,监控系统可以背方便地添加至已有的 Grafana 中。
v0.4.0 第二个公开测试版 v0.4 现已正式发行!
监控系统
Pigsty v0.4 对监控系统进行了整体升级改造,精心挑选了10个面板作为标准的 Pigsty 开源内容。同时,针对 Grafana 7.3的不兼容升级进行了大量适配改造工作。使用升级的pg_exporter v0.3.1作为默认指标导出器,调整了监控报警规则的监控面板连接。
Pigsty 开源版
Pigsty 开源版选定了以下10个 Dashboard 作为开源内容。其他 Dashboard 作为可选的商业支持内容提供。
PG Overview PG Cluster PG Service PG Instance PG Database PG Query PG Table PG Table Catalog PG Table Detail Node 尽管进行了少量阉割,这10个监控面板所涵盖的内容仍然可以吊打所有同类软件。
软件升级
Pigsty v0.4 进行了大量软件适配工作,包括:
Upgrade to PostgreSQL 13.1, Patroni 2.0.1-4, add citus to repo. Upgrade to pg_exporter 0.3.1 Upgrade to Grafana 7.3, Ton’s of compatibility work Upgrade to prometheus 2.23, with new UI as default Upgrade to consul 1.9 其他改进
Update prometheus alert rules Fix alertmanager info links Fix bugs and typos. add a simple backup script 离线安装包
v0.4 的离线安装包(CentOS 7.8)已经可以从 Github 下载:pkg.tgz v0.3.0 首个 Pigsty 公开测试版本现在已经释出!
监控系统
Pigsty v0.3 包含以下8个监控面板作为开源内容:
PG Overview PG Cluster PG Service PG Instance PG Database PG Table Overview PG Table Catalog Node 离线安装包
v0.3 离线安装包(CentOS 7.8)已经可以从 Github 下载:pkg.tgz 2.13 - 同类对比 本文列出了与 Pigsty 生态位有重叠的产品与项目,并比较其在特性上的差异。
与 RDS 对比 Pigsty 是使用 Apache-2.0 开源的本地优先 RDS 替代,可以部署在您自己的物理机/虚拟机上,也可以部署在云服务器上。
因此,我们选择了全球份额第一的亚马逊云 AWS RDS for PostgreSQL ,以及中国市场份额第一的阿里云 RDS for PostgreSQL 作为参照对象。
阿里云 RDS 与 AWS RDS 均为闭源云数据库服务,通过租赁模式,仅在公有云上对外提供,以下对比基于最新的 PostgreSQL 16 主干版本进行,对比截止日期为 2024 年 2 月份。
功能特性 指标 Pigsty Aliyun RDS AWS RDS 大版本支持 14 - 18 13 - 18 13 - 18 只读从库 支持任意数量只读从库 备实例不对用户开放 备实例不对用户开放读写分离 支持端口区分读写流量 独立收费组件 独立收费组件快慢分离 支持离线 ETL 实例 未见相关特性 未见相关特性异地灾备 支持备份集群 支持多可用区部署 支持多可用区部署延迟从库 支持延迟实例 未见相关特性 未见相关特性负载均衡 HAProxy / LVS 独立收费组件 独立收费组件连接池 Pgbouncer 独立收费组件:RDS 独立收费组件:RDS Proxy高可用 Patroni / etcd 需高可用版提供支持 需高可用版提供支持时间点恢复 pgBackRest / MinIO 提供备份支持 提供备份支持指标监控 VictoriaMetrics / Exporter 免费基础版/收费进阶版 免费基础版/收费进阶版日志采集 VictoriaLogs / Vector 基础支持 基础支持可视化系统 Grafana / Echarts 提供基本监控 提供基本监控告警聚合通知 AlterManager 基础支持 基础支持
重要扩展 这里列出了一些重要扩展,对比基于最新的 PostgreSQL 16 主干版本进行,截止至 2024-02-28
扩展名称 Pigsty RDS / PGDG 官方仓库阿里云 RDS AWS RDS 加装扩展 自由加装 不允许 不允许地理空间 PostGIS 3.4.2 PostGIS 3.3.4 / Ganos 6.1 PostGIS 3.4.1雷达点云 PG PointCloud 1.2.5 Ganos PointCloud 6.1向量嵌入 PGVector 0.6.1 / Svector 0.5.6 pase 0.0.1 PGVector 0.6机器学习 PostgresML 2.8.1时序扩展 TimescaleDB 2.14.2水平分布式 Citus 12.1列存扩展 Hydra 1.1.1全文检索 pg_bm25 0.5.6图数据库 Apache AGE 1.5.0GraphQL PG GraphQL 1.5.0OLAP pg_analytics 0.5.6消息队列 pgq 3.5.0DuckDB duckdb_fdw 1.1模糊分词 zhparser 1.1 / pg_bigm 1.2 zhparser 1.0 / pg_jieba pg_bigm 1.2CDC 抽取 wal2json 2.5.3 wal2json 2.5膨胀治理 pg_repack 1.5.0 pg_repack 1.4.8 pg_repack 1.5.0
AWS RDS PG 可用扩展 AWS RDS for PostgreSQL 16 可用扩展(已刨除 PG 自带扩展)
name pg16 pg15 pg14 pg13 pg12 pg11 pg10 amcheck 1.3 1.3 1.3 1.2 1.2 yes 1 auto_explain yes yes yes yes yes yes yes autoinc 1 1 1 1 null null null bloom 1 1 1 1 1 1 1 bool_plperl 1 1 1 1 null null null btree_gin 1.3 1.3 1.3 1.3 1.3 1.3 1.2 btree_gist 1.7 1.7 1.6 1.5 1.5 1.5 1.5 citext 1.6 1.6 1.6 1.6 1.6 1.5 1.4 cube 1.5 1.5 1.5 1.4 1.4 1.4 1.2 dblink 1.2 1.2 1.2 1.2 1.2 1.2 1.2 dict_int 1 1 1 1 1 1 1 dict_xsyn 1 1 1 1 1 1 1 earthdistance 1.1 1.1 1.1 1.1 1.1 1.1 1.1 fuzzystrmatch 1.2 1.1 1.1 1.1 1.1 1.1 1.1 hstore 1.8 1.8 1.8 1.7 1.6 1.5 1.4 hstore_plperl 1 1 1 1 1 1 1 insert_username 1 1 1 1 null null null intagg 1.1 1.1 1.1 1.1 1.1 1.1 1.1 intarray 1.5 1.5 1.5 1.3 1.2 1.2 1.2 isn 1.2 1.2 1.2 1.2 1.2 1.2 1.1 jsonb_plperl 1 1 1 1 1 null null lo 1.1 1.1 1.1 1.1 1.1 1.1 1.1 ltree 1.2 1.2 1.2 1.2 1.1 1.1 1.1 moddatetime 1 1 1 1 null null null old_snapshot 1 1 1 null null null null pageinspect 1.12 1.11 1.9 1.8 1.7 1.7 1.6 pg_buffercache 1.4 1.3 1.3 1.3 1.3 1.3 1.3 pg_freespacemap 1.2 1.2 1.2 1.2 1.2 1.2 1.2 pg_prewarm 1.2 1.2 1.2 1.2 1.2 1.2 1.1 pg_stat_statements 1.1 1.1 1.9 1.8 1.7 1.6 1.6 pg_trgm 1.6 1.6 1.6 1.5 1.4 1.4 1.3 pg_visibility 1.2 1.2 1.2 1.2 1.2 1.2 1.2 pg_walinspect 1.1 1 null null null null null pgcrypto 1.3 1.3 1.3 1.3 1.3 1.3 1.3 pgrowlocks 1.2 1.2 1.2 1.2 1.2 1.2 1.2 pgstattuple 1.5 1.5 1.5 1.5 1.5 1.5 1.5 plperl 1 1 1 1 1 1 1 plpgsql 1 1 1 1 1 1 1 pltcl 1 1 1 1 1 1 1 postgres_fdw 1.1 1.1 1.1 1 1 1 1 refint 1 1 1 1 null null null seg 1.4 1.4 1.4 1.3 1.3 1.3 1.1 sslinfo 1.2 1.2 1.2 1.2 1.2 1.2 1.2 tablefunc 1 1 1 1 1 1 1 tcn 1 1 1 1 1 1 1 tsm_system_rows 1 1 1 1 1 1 1.1 tsm_system_time 1 1 1 1 1 1 1.1 unaccent 1.1 1.1 1.1 1.1 1.1 1.1 1.1 uuid-ossp 1.1 1.1 1.1 1.1 1.1 1.1 1.1
Aliyun RDS PG 可用扩展 阿里云 RDS for PostgreSQL 16 可用扩展(已刨除 PG 自带扩展)
name pg16 pg15 pg14 pg13 pg12 pg11 pg10 ali_desc bloom 1 1 1 1 1 1 1 提供一种基于布鲁姆过滤器的索引访问方法。 btree_gin 1.3 1.3 1.3 1.3 1.3 1.3 1.2 提供一个为多种数据类型和所有 enum 类型实现 B 树等价行为的 GIN 操作符类示例。 btree_gist 1.7 1.7 1.6 1.5 1.5 1.5 1.5 提供一个为多种数据类型和所有 enum 类型实现 B 树等价行为的 GiST 操作符类示例。 citext 1.6 1.6 1.6 1.6 1.6 1.5 1.4 提供一种大小写不敏感的字符串类型。 cube 1.5 1.5 1.5 1.4 1.4 1.4 1.2 提供一种数据类型来表示多维立方体。 dblink 1.2 1.2 1.2 1.2 1.2 1.2 1.2 跨库操作表。 dict_int 1 1 1 1 1 1 1 附加全文搜索词典模板的示例。 earthdistance 1.1 1.1 1.1 1.1 1.1 1.1 1.1 提供两种不同的方法来计算地球表面的大圆距离。 fuzzystrmatch 1.2 1.1 1.1 1.1 1.1 1.1 1.1 判断字符串之间的相似性和距离。 hstore 1.8 1.8 1.8 1.7 1.6 1.5 1.4 在单一 PostgreSQL 值中存储键值对。 intagg 1.1 1.1 1.1 1.1 1.1 1.1 1.1 提供一个整数聚集器和一个枚举器。 intarray 1.5 1.5 1.5 1.3 1.2 1.2 1.2 提供一些有用的函数和操作符来操纵不含空值的整数数组。 isn 1.2 1.2 1.2 1.2 1.2 1.2 1.1 按照一个硬编码的前缀列表对输入进行验证,也被用来在输出时连接号码。 ltree 1.2 1.2 1.2 1.2 1.1 1.1 1.1 用于表示存储在一个层次树状结构中的数据的标签。 pg_buffercache 1.4 1.3 1.3 1.3 1.3 1.3 1.3 提供一种方法实时检查共享缓冲区。 pg_freespacemap 1.2 1.2 1.2 1.2 1.2 1.2 1.2 检查空闲空间映射(FSM)。 pg_prewarm 1.2 1.2 1.2 1.2 1.2 1.2 1.1 提供一种方便的方法把数据载入到操作系统缓冲区或者 PostgreSQL 缓冲区。 pg_stat_statements 1.1 1.1 1.9 1.8 1.7 1.6 1.6 提供一种方法追踪服务器执行的所有 SQL 语句的执行统计信息。 pg_trgm 1.6 1.6 1.6 1.5 1.4 1.4 1.3 提供字母数字文本相似度的函数和操作符,以及支持快速搜索相似字符串的索引操作符类。 pgcrypto 1.3 1.3 1.3 1.3 1.3 1.3 1.3 为 PostgreSQL 提供了密码函数。 pgrowlocks 1.2 1.2 1.2 1.2 1.2 1.2 1.2 提供一个函数来显示一个指定表的行锁定信息。 pgstattuple 1.5 1.5 1.5 1.5 1.5 1.5 1.5 提供多种函数来获得元组层的统计信息。 plperl 1 1 1 1 1 1 1 提供 perl 过程语言。 plpgsql 1 1 1 1 1 1 1 提供 SQL 过程语言。 pltcl 1 1 1 1 1 1 1 提供 tcl 过程语言。 postgres_fdw 1.1 1.1 1.1 1 1 1 1 跨库操作表。 sslinfo 1.2 1.2 1.2 1.2 1.2 1.2 1.2 提供当前客户端提供的 SSL 证书的有关信息。 tablefunc 1 1 1 1 1 1 1 包括多个返回表的函数。 tsm_system_rows 1 1 1 1 1 1 1 提供表采样方法 SYSTEM_ROWS。 tsm_system_time 1 1 1 1 1 1 1 提供了表采样方法 SYSTEM_TIME。 unaccent 1.1 1.1 1.1 1.1 1.1 1.1 1.1 文本搜索字典,它能从词位中移除重音(附加符号)。 uuid-ossp 1.1 1.1 1.1 1.1 1.1 1.1 1.1 提供函数使用几种标准算法之一产生通用唯一标识符(UUID)。 xml2 1.1 1.1 1.1 1.1 1.1 1.1 1.1 提供 XPath 查询和 XSLT 功能。
性能对比 指标 Pigsty Aliyun RDS AWS RDS 最佳性能 PGTPC on NVME SSD 评测 sysbench oltp_rwRDS PG 性能白皮书 sysbench oltp 场景 每核 QPS 4000 ~ 8000存储规格:最高档容量 32TB / NVME SSD 32 TB / ESSD PL3 64 TB / io2 EBS Block Express 存储规格:最高档 IOPS 4K 随机读:最大3M,随机写 2000~350K 4K 随机读:最大 1M 16K 随机 IOPS: 256K 存储规格:最高档延迟 4K 随机读:75µs,随机写 15µs 4K 随机读:200µs 500µs / 推断为16K 随机 IO 存储规格:最高档可靠性 UBER < 1e-18,折合18个9 MTBF: 200万小时 5DWPD,持续三年 可靠性 9个9, 合 UBER 1e-9 存储与数据可靠性 持久性 :99.999%,5个9 (0.001% 年故障率) io2 说明 存储规格:最高档成本 31.5 ¥/TB·月 ( 5年质保均摊 / 3.2T / 企业级 / MLC ) 3200¥/TB·月 (原价 6400¥,包月4000¥) 3年预付整体打5折才有此价格 1900 ¥/TB·月 使用最大规格 65536GB / 256K IOPS 最大优惠
可观测性 Pigsty 提供了近 3000 类监控指标,提供了 50+ 监控面板,覆盖了数据库监控、主机监控、连接池监控、负载均衡监控等方方面面,为用户提供无与伦比的可观测性体验。
Pigsty 提供了 638 与 PostgreSQL 有关的监控指标,而 AWS RDS 只有 99 个,阿里云 RDS 更是只有个位数指标:
此外,也有一些项目提供了监控 PostgreSQL 的能力,但都相对比较简单初级:
可维护性 指标 Pigsty Aliyun RDS AWS RDS 系统易用性 简单 简单 简单 配置管理 配置文件 / CMDB 基于 Ansible Inventory 可使用 Terraform 可使用 Terraform 变更方式 幂等剧本 基于 Ansible Playbook 控制台点击操作 控制台点击操作 参数调优 自动根据节点适配 四种预置模板 OLTP, OLAP, TINY, CRIT Infra as Code 原生支持 可使用 Terraform 可使用 Terraform 可定制参数点 Pigsty Parameters 283 个服务与支持 提供商业订阅支持兜底 提供售后工单支持 提供售后工单支持 无互联网部署 可离线安装部署 N/A N/A 数据库迁移 提供从现有 v10+ PG 实例基于逻辑复制不停机迁移至 Pigsty 托管实例的剧本 提供上云辅助迁移 Aliyun RDS 数据同步
成本 经验上看,软硬件资源的部分 RDS 单位成本是自建的 5 ~ 15 倍,租售比通常在一个月。详情请参考 成本分析 。
要素 指标 Pigsty Aliyun RDS AWS RDS 成本 软件授权/服务费用 免费,硬件约 20 - 40 ¥/核·月 200 ~ 400 ¥/核·月 400 ~ 1300 ¥/核·月 服务支持费用 服务约 100 ¥/ 核·月 包含在 RDS 成本中
其他本地数据库管控软件 一些提供管理 PostgreSQL 能力的软件与供应商
其他 Kubernetes Operator Pigsty 拒绝在生产环境中使用 Kubernetes 管理数据库,因此与这些方案在生态位上存在差异。
PGO StackGres CloudNativePG TemboOperator PostgresOperator PerconaOperator Kubegres KubeDB KubeBlocks 更多信息请参阅:
2.13.1 - 成本对比 本文提供了一组成本数据,供您评估 Pigsty 自建,使用云数据库 RDS 所需的成本,以及常规的 DBA 薪酬参考。
总体概览 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
我们可以对比一下自建与云数据库的成本差异:
方式 折合每年(万元) IDC 托管服务器 64C / 384G / 3.2TB NVME SSD 660K IOPS (2~3台) 3.0 ~ 4.5 阿里云 RDS PG 高可用版 pg.x4m.8xlarge.2c, 64C / 256GB / 3.2TB ESSD PL3 25 ~ 50 AWS RDS PG 高可用版 db.m5.16xlarge, 64C / 256GB / 3.2TB io1 x 80k IOPS 160 ~ 217
ECS 成本参考 排除 NVMe SSD / ESSD PL3 后的纯算力价格对比 以阿里云为例,纯算力包月模式的价格是自建基准的 5 ~ 7 倍,预付五年的价格是自建的 2 倍
付费模式 单价(¥/核·月) 相对于标准价格 自建溢价倍率 按量付费(1.5倍) ¥ 202 160 % 9.2 ~ 11.2 包月(标准价格) ¥ 126 100 % 5.7 ~ 7.0 预付一年(65折) ¥ 83.7 66 % 3.8 ~ 4.7 预付二年(55折) ¥ 70.6 56 % 3.2 ~ 3.9 预付三年(44折) ¥ 55.1 44 % 2.5 ~ 3.1 预付四年(35折) ¥ 45 35 % 2.0 ~ 2.5 预付五年(30折) ¥ 38.5 30 % 1.8 ~ 2.1 DHH @ 2023 ¥ 22.0 探探 IDC 自建 ¥ 18.0
含 NVMe SSD / ESSD PL3 情况下的等效价格对比 包含常用规格后的 NVMe SSD 规格之后,纯算力包月模式的价格是自建基准的 11 ~ 14 倍,预付五年的价格是自建的 9 倍左右。
付费模式 单价(¥/核·月) + 40GB ESSD PL3 自建溢价比例 按量付费(1.5倍) ¥ 202 ¥ 362 14.3 ~ 18.6 包月(标准价格) ¥ 126 ¥ 286 11.3 ~ 14.7 预付一年(65折) ¥ 83.7 ¥ 244 9.6 ~ 12.5 预付二年(55折) ¥ 70.6 ¥ 230 9.1 ~ 11.8 预付三年(44折) ¥ 55.1 ¥ 215 8.5 ~ 11.0 预付四年(35折) ¥ 45 ¥ 205 8.1 ~ 10.5 预付五年(30折) ¥ 38.5 ¥ 199 7.9 ~ 10.2 DHH @ 2023 ¥ 25.3 探探 IDC 自建 ¥ 19.5
DHH 案例:192核配12.8TB Gen4 SSD (1c:66);探探案例: 64核配3.2T Gen3 MLC SSD (1c:50)。
云上价格每核配比40GB ESSD PL3(1核:4x 内存:40x 磁盘)计算。
EBS成本参考 评估因素 本地 PCI-E NVME SSD Aliyun ESSD PL3 AWS io2 Block Express 容量 32TB 32 TB 64 TB IOPS 4K 随机读:600K ~ 1.1M 4K 随机写 200K ~ 350K 4K 随机读:最大 1M 16K 随机 IOPS: 256K 延迟 4K 随机读:75µs 4K 随机写:15µs 4K 随机读: 200µs 随机 IO:500µs 上下文推断为16K 可靠性 UBER < 1e-18,折合18个9 MTBF: 200万小时 5DWPD,持续三年 数据可靠性 9个9 存储与数据可靠性 持久性 :99.999%,5个9 (0.001% 年故障率) io2 说明 成本 **16 ¥/TB·**月 ( 5年均摊 / 3.2T MLC ) 5 年质保,¥3000 零售 **3200¥/TB·**月 (原价 6400¥,包月4000¥) 3年预付整体打5折才有此价格 **1900 ¥/TB·**月 使用最大规格 65536GB 256K IOPS 最优惠状态 SLA 5年质保 出问题直接换新 Aliyun RDS SLA 可用性 99.99%: 月费 15% 99%: 月费 30% 95%: 月费 100%Amazon RDS SLA 可用性 99.95%: 月费 15% 99%: 月费 25% 95%: 月费 100%
S3成本参考 Date $/GB·月 ¥/TB·5年 HDD ¥/TB SSD ¥/TB 2006 .030.150 63000 2800 2010 .110.140 58800 1680 2012 .120.095 39900 420 15400 2014 .040.030 12600 371 9051 2016 .120.023 9660 245 3766 2023 .120.023 9660 105 280 其他参考价 高性能存储 顶配底折价 与采购 NVMe SSD 价格参考 S3 Express 0.160 67200 DHH 12T 1400 EBS io2 0.125 + IOPS 114000 Shannon 3.2T 900
下云合集 曾几何时,“上云 ”近乎成为技术圈的政治正确,整整一代应用开发者的视野被云遮蔽。就让我们用实打实的数据分析与亲身经历,讲清楚公有云租赁模式的价值与陷阱 —— 在这个降本增效的时代中,供您借鉴与参考 —— 请看 《云计算泥石流:合订本 》
云基础资源篇
云商业模式篇
下云奥德赛篇
云故障复盘篇
RDS 翻车篇
云厂商画像篇
2.13.2 - 开源影响力 PG 生态开源项目的影响力比较,以 GitHub Star 数为主要指标。
中国 PostgreSQL 生态项目影响力 GitHub Star 数降序排列,最后更新时间为北京时间 2026-05-01。
PostgreSQL 发行版影响力指标 按 GitHub Star 数降序排列(商业产品无公开 Star 的统一置后),最后更新时间为北京时间 2026-05-01。
其他资源 3 - 概念 理解 Pigsty 的核心概念、架构设计与设计理念,掌握高可用、备份恢复、安全合规等关键能力。
Pigsty 是一个可移植、可扩展的开源 PostgreSQL 发行版,用于在本地环境中构建生产级数据库服务,方便进行声明式配置和自动化。它拥有庞大的生态系统,提供了一整套工具、脚本和最佳实践,让 PostgreSQL 真正达到企业级 RDS 的服务水准。
Pigsty 名字源自 P ostgreSQL I n G reat STY le,也可理解为 P ostgres, I nfras, G raphics, S ervice, T oolbox, it’s all Y ours —— 属于您的 PostgreSQL 图形化自建工具箱。您可以在 GitHub 上找到源代码,访问 官方文档 了解更多信息,或在 在线演示 中体验 Web 界面 。
为什么需要 Pigsty,它能做什么? PostgreSQL 是一个足够完美的数据库内核,但它需要更多工具与系统的配合才能成为一个足够好的数据库服务。在生产环境中,您需要管理数据库的方方面面:高可用、备份恢复、监控告警、访问控制、参数调优、扩展安装、连接池化、负载均衡……
如果这些复杂的运维工作都能自动化处理,是不是会更容易一些?这正是 Pigsty 诞生的原因。
Pigsty 为您提供:
开箱即用的 PostgreSQL 发行版
Pigsty 深度整合了 PostgreSQL 生态中的 510 扩展插件 ,为您提供开箱即用的分布式、时序、地理、空间、图、向量、搜索等多模态数据库能力。从内核到 RDS 发行版,在 EL/Debian/Ubuntu 下提供 14-18 版本的生产级数据库服务。
故障自愈的高可用架构
基于 Patroni、Etcd 和 HAProxy 打造的 高可用架构 ,让硬件故障自动切换,流量无缝衔接。主库故障恢复时间 RTO < 45s,数据恢复点 RPO ≈ 0。您可以在无需应用配合的情况下滚动维护升级整个集群。
完整的时间点恢复能力
基于 pgBackRest 与可选的 MinIO 集群,提供开箱即用的 PITR 时间点恢复 能力。让您拥有快速回到过去任意时间点的能力,为软件缺陷与人为删库兜底。
灵活的服务接入与流量管理
通过 HAProxy、Pgbouncer、VIP 提供灵活的 服务接入 模式,实现读写分离、连接池化、自动路由。交付稳定可靠、自动路由、事务池化的高性能数据库服务。
惊艳的可观测性
基于 Prometheus 与 Grafana 的现代可观测性技术栈,提供无与伦比的 监控最佳实践 。超过三千类监控指标描述系统的方方面面,从全局大盘到单个对象的增删改查都能一览无余。
声明式的配置管理
遵循 基础设施即代码 的理念,使用声明式配置描述整个环境。您只需告诉 Pigsty “想要什么样的数据库集群”,无需操心具体如何实现,系统会自动调整到期望状态。
模块化的架构设计
采用模块化 架构 设计,可自由组合以适应不同场景。除了核心的 PostgreSQL 模块外,还提供 Redis、MinIO、Etcd、FerretDB 等可选模块,以及对多种 PG 兼容内核的支持。
扎实的安全最佳实践
采用业界领先的安全最佳实践:自签名 CA 签发证书加密通信,AES 加密备份,scram-sha-256 加密密码,开箱即用的 ACL 模型,遵循最小权限原则的 HBA 规则集,确保数据安全。
简单易用的部署方案
所有依赖被预先打包,可在无互联网访问的环境中一键安装。本地沙箱环境可运行在 1核2G 的微型虚拟机中,提供与生产环境完全一致的功能模拟。提供基于 Vagrant 的本地沙箱与基于 Terraform 的云端部署方案。
Pigsty 不是什么 Pigsty 并不是传统的、包罗万象的 PaaS(平台即服务)系统。
Pigsty 不提供基础硬件资源 。它运行在您提供的节点之上,无论是裸金属、虚拟机还是云主机,但它本身不创建或管理这些资源(尽管提供了 Terraform 模板来简化云资源的准备)。
Pigsty 不是容器编排系统 。它直接运行在操作系统之上,不需要 Kubernetes 或 Docker 作为基础设施。当然,它可以与这些系统共存,并提供 Docker 模块来运行无状态应用。
Pigsty 不是通用的数据库管理工具 。它专注于 PostgreSQL 及其生态,虽然也支持 Redis、Etcd、MinIO 等周边组件,但核心始终是围绕 PostgreSQL 构建的。
Pigsty 不会锁定您 。它基于开源组件构建,不修改 PostgreSQL 内核,不引入专有协议。您随时可以脱离 Pigsty 继续使用管理好的 PostgreSQL 集群。
Pigsty 不限制您应该或不应该如何构建数据库服务。例如:
Pigsty 为您提供了良好的参数默认值和配置模板,但您可以覆盖任何参数。 Pigsty 提供了声明式 API,但您依然可以使用底层工具(Ansible、Patroni、pgBackRest 等)进行手动管理。 Pigsty 可以管理完整的生命周期,也可以只使用其中的监控系统来观测现有的数据库实例或 RDS。 Pigsty 提供的抽象层次不同于硬件层面,它工作在数据库服务层面,聚焦于如何让 PostgreSQL 以最佳状态交付价值,而不是重新发明轮子。
PostgreSQL 部署方式的演进 要理解 Pigsty 的价值,让我们回顾一下 PostgreSQL 部署方式的演进历程。
手工部署时代 在传统的部署方式中,DBA 需要手工安装配置 PostgreSQL,手工设置复制,手工配置监控,手工处理故障。这种方式的问题显而易见:
效率低下 :每个实例都需要重复大量手工操作,容易出错。缺乏标准化 :不同 DBA 配置的数据库可能千差万别,难以维护。可靠性差 :故障处理依赖人工介入,恢复时间长,容易出现人为失误。观测性弱 :缺乏统一的监控体系,问题发现和定位困难。托管数据库时代 为了解决这些问题,云厂商提供了托管数据库服务(RDS)。云 RDS 确实解决了部分运维问题,但也带来了新的挑战:
成本高昂 :托管服务通常收取硬件成本数倍到十几倍的"服务费"。供应商锁定 :迁移困难,受制于特定云平台。功能受限 :无法使用某些高级特性,扩展插件受限,参数调整受限。数据主权 :数据存储在云端,自主可控性降低。本地 RDS 时代 Pigsty 代表了第三种方式:在本地环境中构建媲美甚至超越云 RDS 的数据库服务。
Pigsty 结合了前两种方式的优点:
自动化程度高 :一键部署,自动配置,故障自愈,像云 RDS 一样便捷。完全自主可控 :运行在您自己的基础设施上,数据完全掌握在自己手中。成本极低 :以接近纯硬件的成本运行企业级数据库服务。功能完整 :无限制地使用 PostgreSQL 的全部能力和生态扩展。开放架构 :基于开源组件,无供应商锁定,可随时迁移。这种方式特别适合:
私有云与混合云 :需要在本地环境中运行数据库的企业。成本敏感型用户 :希望降低数据库 TCO 的组织。高安全要求场景 :需要完全自主可控的关键数据。PostgreSQL 深度用户 :需要使用高级特性和丰富扩展的场景。开发与测试 :需要在本地快速搭建与生产环境一致的数据库。接下来 现在您已经了解了 Pigsty 的基本概念,可以:
查看 系统架构 了解 Pigsty 的模块化设计 了解 集群模型 理解 Pigsty 如何组织数据库集群 学习 高可用 机制掌握故障自愈的原理 探索 时间点恢复 了解如何应对数据误删 研究 服务接入 理解如何稳定交付数据库服务 体验 基础设施即代码 感受声明式配置的魅力 或直接开始 快速上手 在几分钟内部署您的第一个 Pigsty 环境 3.1 - 积木式架构 Pigsty 的模块化架构介绍 —— 声明式组合,按需定制,自由部署。
Pigsty 使用 模块化架构 与 声明式接口 ,您可以像 搭积木一样自由按需组合模块 。
模块 Pigsty 采用模块化设计,有六个主要的默认模块:PGSQL 、INFRA 、NODE 、ETCD 、REDIS 和 MINIO 。
PGSQL :由 Patroni、Pgbouncer、HAproxy、PgBackrest 等驱动的自治高可用 Postgres 集群。INFRA :本地软件仓库、Nginx、Grafana、Victoria、AlertManager、Blackbox Exporter 可观测性全家桶。NODE :调整节点到所需状态、名称、时区、NTP、ssh、sudo、haproxy、docker、vector、keepalivedETCD :分布式键值存储,用作高可用 Postgres 集群的 DCS:共识选主/配置管理/服务发现。REDIS :Redis 服务器,支持独立主从、哨兵、集群模式,并带有完整的监控支持。MINIO :与 S3 兼容的简单对象存储服务器,可作为 PG 数据库备份的可选目的地。你可以声明式地自由组合它们。如果你想要主机监控,在基础设施节点上安装 INFRA 模块,并在纳管节点上安装 NODE 模块就足够了。
ETCD 和 PGSQL 模块用于搭建高可用 PG 集群,将模块安装在多个节点上,可以自动形成一个高可用的数据库集群。
您可以复用 Pigsty 基础架构并开发您自己的模块,REDIS 和 MINIO 可以作为一个样例。后续还会有更多的模块加入,例如对 Mongo 与 MySQL 的初步支持已经提上了日程。
请注意,所有模块都强依赖 NODE 模块:在 Pigsty 中节点必须先安装 NODE 模块,被 Pigsty 纳管后方可部署其他模块。
当节点(默认)使用本地软件源进行安装时,NODE 模块对 INFRA 模块有弱依赖。因此安装 INFRA 模块的管理节点/基础设施节点会在 deploy.yml 剧本中完成 Bootstrap 过程,解决循环依赖。
单机安装 默认情况下,Pigsty 将在单个 节点 (物理机/虚拟机) 上安装。deploy.yml 剧本将在当前 节点上安装 INFRA 、ETCD 、PGSQL 和可选的 MINIO 模块,
这将为你提供一个功能完备的可观测性技术栈全家桶 (Prometheus、Grafana、Loki、AlertManager、PushGateway、BlackboxExporter 等),以及一个内置的 PostgreSQL 单机实例作为 CMDB,也可以开箱即用。 (集群名 pg-meta,库名为 meta)。
这个节点现在会有完整的自我监控系统、可视化工具集,以及一个自动配置有 PITR 的 Postgres 数据库(HA 不可用,因为你只有一个节点)。你可以使用此节点作为开发箱、测试、运行演示以及进行数据可视化和分析。或者,还可以把这个节点当作管理节点,部署纳管更多的节点!
监控 安装的 单机元节点 可用作管理节点 和监控中心 ,以将更多节点和数据库服务器置于其监视和控制之下。
Pigsty 的监控系统可以独立使用,如果你想安装 Prometheus / Grafana 可观测性全家桶,Pigsty 为你提供了最佳实践!
它为 主机节点 和 PostgreSQL数据库 提供了丰富的仪表盘。
无论这些节点或 PostgreSQL 服务器是否由 Pigsty 管理,只需简单的配置,你就可以立即拥有生产级的监控和告警系统,并将现有的主机与 PostgreSQL 纳入监管。
高可用PG集群 Pigsty 帮助您在任何地方 拥有 您自己的生产级高可用 PostgreSQL RDS 服务。
要创建这样一个高可用 PostgreSQL 集群/RDS 服务,你只需用简短的配置来描述它,并运行剧本来创建即可:
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 }
$ bin/pgsql-add pg-test # 初始化集群 'pg-test'
不到10分钟,您将拥有一个服务接入,监控,备份 PITR,高可用配置齐全的 PostgreSQL 数据库集群。
硬件故障由 patroni、etcd 和 haproxy 提供的自愈高可用架构来兜底,在主库故障的情况下,默认会在 45 秒内执行自动故障转移(Failover)。
客户端无需修改配置重启应用:Haproxy 利用 patroni 健康检查进行流量分发,读写请求会自动分发到新的集群主库中,并避免脑裂的问题。
这一过程十分丝滑,例如在从库故障,或主动切换(switchover)的情况下,客户端只有一瞬间的当前查询闪断,
软件故障、人为错误和 数据中心级灾难由 pgbackrest 和可选的 MinIO 集群来兜底。这为您提供了本地/云端的 PITR 能力,并在数据中心失效的情况下提供了跨地理区域复制,与异地容灾功能。
3.1.1 - 节点 节点(node)是对硬件资源/操作系统的抽象,可以是物理机,裸金属、虚拟机、或者容器与 pods。
节点(node) 是对硬件资源/操作系统的抽象,可以是物理机,裸金属、虚拟机、或者容器与 pods。
只要装着 Linux 操作系统 (以及 systemd 守护进程),能使用 CPU/内存/磁盘/网络 等标准资源,即可视作节点。
节点上可以安装 模块 ,Pigsty 中存在几种不同类型节点,主要区别就在于安装了不同的模块。
在 单机部署 Pigsty 时,多者合而为一,当前节点将同时作为普通节点,管理节点、基础设施节点、ETCD 节点,以及数据库节点。
普通节点 使用 Pigsty 管理节点,可在其上安装模块。node.yml 剧本将调整节点至所需状态。
普通节点上可能会运行以下服务:
组件 端口 描述 状态 node_exporter9100节点监控指标导出器 ✅ 默认启用 haproxy9101HAProxy 负载均衡器(管理端口) ✅ 默认启用 vector9598日志收集代理 ✅ 默认启用 docker9323启用容器支持 ⚠️ 按需启用 keepalivedn/a管理节点集群 L2 VIP ⚠️ 按需启用 keepalived_exporter9650监控 Keepalived 状态 ⚠️ 按需启用
这里,node_exporter 会向监控系统暴露主机上的各类监控指标,vector 会向日志收集系统发送日志,haproxy 则提供负载均衡功能,对外暴露服务。
这三项服务默认开启。而 Docker ,keepalived 及 keepalived_exporter 这三项服务作为可选项,可按需启用。
ADMIN节点 一套 Pigsty 部署中有且只有一个 管理节点 ,管理节点是执行 Ansible 剧本,发起控制/部署命令的节点。
该节点拥有对所有其他节点的 ssh/sudo 访问权限。管理节点的安全至关重要,请确保它的访问受到严格控制。
在 单机安装 的 配置过程 中,当前安装节点就是管理节点。
但也有其他的可能,例如,如果你的笔记本可以 ssh 访问所有被管理节点,并且安装了 Ansible,那么在这种情况下,
您的笔记本电脑就可以作为一个管理节点 —— 尽管这对于生产环境来说不太合适。
例如,您使用自己的笔记本电脑,管理一台云端上部署了 Pigsty 的虚拟机,这时候,您的笔记本电脑就是管理节点。
在严肃的生产环境中,管理节点通常是 1-2 台 DBA 专用的 管控机 。在资源受限的环境中,则通常会复用 INFRA节点 作为管理节点。
因为所有的 INFRA 节点上都默认安装了 Ansible,可以作为额外的备用的管理节点。
INFRA节点 一套 Pigsty 部署可能有 1 个或多个 INFRA 节点,大型生产环境可能有 2-3 个。
配置清单中的 infra 分组指定哪些节点是 INFRA 节点,这些节点上会部署 INFRA 模块,包含下列组件:
组件 端口 描述 nginx80/443Web 图形界面,本地软件仓库 grafana3000可视化平台 victoriaMetrics8428时序数据库(收存监控指标) victoriaLogs9428日志收集服务器 victoriaTraces10428链路追踪收集服务器 vmalert8880告警与衍生指标计算规则 alertmanager9059告警聚合分发/屏蔽管理 blackbox_exporter9115黑盒探测,ping 节点 / vip dnsmasq53内部 DNS 域名解析 chronyd123NTP 时间服务器 ansible-执行剧本,发起管理
其中,Nginx 作为当前模块的入口,提供 Web 图形界面和本地软件仓库服务。
如果你部署多个 INFRA 节点,每个 Infra 节点上的服务是相互独立的。
但你确实可以从任意一个 Infra 节点上的 Grafana 访问所有的监控数据源。
Pigsty 使用 Apache-2.0 许可证开源,但请注意其中的 Grafana 组件使用 AGPLv3 许可证。
ETCD节点 ETCD 模块为 PostgreSQL 高可用提供分布式共识服务(DCS)。
配置清单 中的 etcd 分组指定哪些节点是 ETCD 节点,ETCD 节点上运行着 etcd 服务器,监听以下两个端口:
组件 端口 描述 etcd2379ETCD 分布式键值存储(客户端端口) etcd2380ETCD 集群 Peer 通信端口
MINIO节点 MINIOn 模块为 PostgreSQL 提供了一个可选的 备份存储仓库 。
配置清单中的 minio 分组指定哪些节点是 MinIO 节点,这些节点上会运行 MinIO 服务器,监听以下端口:
组件 端口 描述 minio9000MinIO S3 API 服务端口 minio9001MinIO 管理控制台端口
PGSQL节点 安装了 PGSQL 模块的节点被称为 PGSQL 节点。节点与 PostgreSQL 实例为 1:1 部署,也就是每个节点上只运行一个 PG 实例。
PGSQL 节点可从相应 PostgreSQL 实例借用 身份 —— 由 node_id_from_pg 控制,默认为 true,即节点名会被设置为 PG 实例名。
PGSQL 节点在 普通节点 的基础上,还会额外运行以下组件:
组件 端口 描述 状态 postgres5432PostgreSQL 数据库服务器 ✅ 默认启用 pgbouncer6432Pgbouncer 连接池 ✅ 默认启用 patroni8008Patroni 高可用管理组件 ✅ 默认启用 pg_exporter9630Postgres 监控指标导出器 ✅ 默认启用 pgbouncer_exporter9631PGBouncer 监控指标导出器 ✅ 默认启用 pgbackrest_exporter9854Pgbackrest 监控指标导出器 ✅ 默认启用 vip-managern/a将 L2 VIP 绑定在集群主库节点上 ⚠️ 按需启用 {{ pg_cluster }}-primary5433通过 haproxy 对外暴露数据库服务:主连接池:读/写服务 ✅ 默认启用 {{ pg_cluster }}-replica5434通过 haproxy 对外暴露数据库服务:副本连接池:只读服务 ✅ 默认启用 {{ pg_cluster }}-default5436通过 haproxy 对外暴露数据库服务:主直连服务 ✅ 默认启用 {{ pg_cluster }}-offline5438通过 haproxy 对外暴露数据库服务:离线直连:离线读服务 ✅ 默认启用 {{ pg_cluster }}-<service>543x通过 haproxy 对外暴露数据库服务:PostgreSQL 定制服务 ⚠️按需定制
其中,vip-manager 只有当用户配置了 PG VIP 时才会启用。
在 pg_services 中可以定义更多的 自定义服务 ,这些服务会被 haproxy 对外暴露,并使用更多的服务端口。
3.1.2 - INFRA 架构 Pigsty 中基础设施模块的架构,组件与功能详解。
运行生产级别高可用 PostgreSQL 集群,通常需要一套完善的基础设施服务(底座)来支撑,例如监控告警、日志收集、时间同步、DNS 解析,本地软件仓库等。
Pigsty 提供了 INFRA 模块 来解决这个问题 —— 这是一个 可选模块 ,但我们强烈推荐启用它。
概览 下图是 单机部署 时的架构示意图,图中右半部分即为 INFRA 模块 所包含的组件,其中包括:
Nginx Nginx 是 Pigsty 所有 WebUI 类服务的访问入口,默认使用 80 / 443 端口对外提供 HTTP / HTTPS 服务。在线演示
带有 WebUI 的基础设施组件可以通过 Nginx 统一对外暴露服务,例如 Grafana 、VictoriaMetrics (VMUI)、AlertManager ,
以及 HAProxy 控制台,此外,本地软件仓库 等静态文件资源也通过 Nginx 对内外提供服务。
Nginx 会根据 infra_portal 中的定义,配置本地 Web 服务器或反向代理服务器。
infra_portal :
home : { domain : i.pigsty }
默认情况下将对外暴露 Pigsty 的管理首页:i.pigsty,上面不同的端点挂载代理了不同的组件:
Pigsty 允许对 Nginx 进行丰富的定制,将其作为本地文件服务器,或者反向代理服务器,配置自签名或者真正的 HTTPS 证书。
更多信息,请参阅:教程:Nginx:向外代理暴露Web服务 与 教程:Certbot:申请与更新HTTPS证书
Repo Pigsty 会在安装时,默认在 Infra 节点上创建一个 本地软件仓库 ,以加速后续软件安装。在线演示
该软件仓库默认位于 /www/pigsty 目录,
由 Nginx 对外提供服务,挂载在 /pigsty 路径上:
Pigsty 支持 离线安装 ,实质上是将做好的本地软件仓库提前复制到目标环境中。
当 Pigsty 执行生产部署,需要创建本地软件仓库时,如果发现本地已经存在 /www/pigsty/repo_complete 标记文件,则会跳过从上游下载软件包的步骤,直接使用已有的软件包,避免联网下载。
更多信息,请参阅:配置:INFRA - REPO
Grafana Grafana 是 Pigsty 监控系统的核心组件,用于可视化展示监控指标、日志与各种信息。在线演示
Grafana 默认监听 3000 端口,挂载于 Nginx /ui 路径点上代理访问:
Pigsty 预置了基于 VictoriaMetrics / Logs / Traces 的大量监控面板,并通过 URL 跳转实现一键下钻上卷,帮助快速定位故障。
Grafana 亦可作为低代码可视化平台使用,因此默认安装 ECharts 、victoriametrics-datasource、victorialogs-datasource 等插件,
同时将 Vector / Victoria 数据源统一注册为 vmetrics-*、vlogs-*、vtraces-*,方便扩展自定义仪表板。
更多信息请参阅:配置:INFRA - GRAFANA 。
VictoriaMetrics VictoriaMetrics 是 Pigsty 的时序数据库,负责拉取并存储所有监控指标。在线演示
默认监听 8428 端口,挂载于 Nginx /vmetrics 路径上,亦可通过 p.pigsty 域名直接访问:
VictoriaMetrics 完全兼容 Prometheus API,支持 PromQL 查询、远程读写协议以及 Alertmanager API。
内置的 VMUI 提供即席查询界面,可直接探索指标数据,也可作为 Grafana 的数据源使用。
更多信息请参阅:配置:INFRA - VMETRICS
VictoriaLogs VictoriaLogs 是 Pigsty 的日志平台,集中存储来自所有节点的结构化日志。在线演示
默认监听 9428 端口,挂载于 Nginx /vlogs 路径上:
所有纳管节点默认运行 Vector Agent,负责收集系统日志、PostgreSQL 日志、Patroni 日志、Pgbouncer 日志等,结构化处理后推送至 VictoriaLogs 。
内置 Web UI 支持日志检索与过滤,也可配合 Grafana 的 victorialogs-datasource 插件进行可视化分析。
更多信息请参阅:配置:INFRA - VLOGS
VictoriaTraces VictoriaTraces 用于收集链路追踪数据与慢 SQL 记录。在线演示
默认监听 10428 端口,挂载于 Nginx /vtraces 路径上:
VictoriaTraces 提供 Jaeger 兼容接口,可用于分析服务调用链路与数据库慢查询。
结合 Grafana 面板,能够快速定位性能瓶颈,追溯问题根因。
更多信息请参阅:配置:INFRA - VTRACES
VMAlert VMAlert 是告警规则计算引擎,负责评估告警规则并将触发的事件推送至 Alertmanager 。在线演示
默认监听 8880 端口,挂载于 Nginx /vmalert 路径上:
VMAlert 从 VictoriaMetrics 读取指标数据,周期性执行告警规则评估。
Pigsty 预置了 PGSQL、NODE、REDIS 等模块的告警规则,覆盖常见故障场景,开箱即用。
更多信息请参阅:配置:INFRA - VMALERT
AlertManager AlertManager 负责告警事件的聚合、去重、分组与分发。在线演示
默认监听 9059 端口,挂载于 Nginx /alertmgr 路径上,亦可通过 a.pigsty 域名直接访问:
AlertManager 支持多种通知渠道:邮件、Webhook、Slack、PagerDuty、企业微信等。
通过配置告警路由规则,可实现按严重程度、模块类型进行差异化分发,支持静默、抑制等高级功能。
更多信息请参阅:配置:INFRA - AlertManager
BlackboxExporter Blackbox Exporter 用于主动探测目标的可达性,实现黑盒监控。
默认监听 9115 端口,挂载于 Nginx /blackbox 路径上:
支持 ICMP Ping、TCP 端口、HTTP/HTTPS 端点等多种探测方式。
可用于监控 VIP 可达性、服务端口存活、外部依赖健康状态等场景,是判断故障影响范围的重要手段。
更多信息请参阅:配置:INFRA - BLACKBOX
Ansible Ansible 是 Pigsty 的核心编排工具,所有部署、配置、管理操作均通过 Ansible Playbook 完成。
Pigsty 在安装时会自动在管理节点(Infra 节点)上安装 Ansible 。
它采用声明式配置风格与幂等剧本设计:同一剧本可重复执行,系统会自动收敛至期望状态,无需担心副作用。
Ansible 的核心优势:
无 Agent :通过 SSH 远程执行,无需在目标节点安装额外软件。声明式 :描述期望状态,而非执行步骤,配置即文档。幂等性 :多次执行结果一致,支持部分失败后重试。更多信息请参阅:剧本:Pigsty Playbook
DNSMASQ DNSMASQ 在 INFRA节点 上提供环境内的 DNS 解析服务,将域名解析到对应 IP 地址。
DNSMASQ 默认监听 53 端口(UDP/TCP),为环境内所有节点提供 DNS 解析服务,解析记录位于 的 /infra/hosts 目录中。
其他模块在部署时会自动将域名注册到 INFRA 节点的 DNSMASQ 服务中,您可以按需使用。
DNS 是完全可选的模块,Pigsty 本身不依赖它即可正常运行 。
客户端节点可将 INFRA 节点配置为 DNS 服务器,即可通过域名访问各服务,无需记忆 IP 地址。
更多信息请参阅:配置:INFRA - DNS 与 教程:DNS:配置域名解析
Chronyd Chronyd 提供 NTP 时间同步服务,确保环境内所有节点时钟一致。默认监听 123 端口(UDP),作为环境内的时间源。
时间同步对分布式系统至关重要:日志排查需要时间戳对齐,证书校验依赖时钟准确,PostgreSQL 流复制也对时钟偏移敏感。
在隔离网络环境中,INFRA 节点可作为内部 NTP 服务器,其他节点同步至此。
在 Pigsty 中,默认所有节点都会启动 chonyd 服务用于时间同步。默认使用 pool.ntp.org 公共 NTP 服务器作为上游时间源。
Chronyd 本质上归属 Node 模块 管理,但在网络隔离的环境中,你使用 admin_ip 指向 INFRA 节点上的 Chronyd 服务作为内部时间源。
此时 INFRA节点 上的 Chronyd 服务将充当内部时间同步基础设施的角色。
更多信息请参阅:配置:NODE - TIME
INFRA节点与普通节点 在 Pigsty 中,节点与基础设施的关系是 弱循环依赖 :node_monitor → infra → node
NODE模块 本身不依赖 INFRA模块 ,但节点模块中的监控功能(node_monitor)需要依赖基础设施模块提供的监控平台与服务。
因此,在 infra.yml 和 deploy 剧本中,
采用了一种 “交织部署” 的技术:
如果您不追求 “一次性” 部署所有节点,也可以采用 分阶段部署 的方式,先初始化 INFRA 节点,然后再初始化其他普通节点即可。
节点与基础设施是如何耦合的? 普通节点会通过 admin_ip 参数来引用某个 INFRA节点 作为它们的基础设施提供者。
例如,当你配置了全局的 admin_ip = 10.10.10.10,那么通常意味着所有节点都会使用这个 IP 上的基础设施服务。
这样的设计允许你快速,批量的切换节点的基础设施提供者 —— 以下是 可能 引用 ${admin_ip} 的配置参数列表:
例如,当节点安装软件的时候,local 仓库指向的就是 admin_ip:80/pigsty 上的 Nginx 本地软件仓库。DNS 服务器指向的也是 admin_ip:53 上的 DNSMASQ 。
但这并不是强制要求的,例如,节点完全可以忽略并不使用 local 仓库,直接从互联网上游源安装(大部分单机配置模板);DNS 服务器也完全可以不配置与不使用,Pigsty 本身并无对 DNS 服务器的依赖。
INFRA节点与ADMIN节点 通常发起管理的 ADMIN节点 会与基础设施节点(INFRA节点 )重合。
在 单机部署 就是这样的。在多节点部署中,如果有多个 INFRA 节点,管理节点通常是 infra 分组中的第一个,其余作为备用。
不过,也有例外存在。您可能会出于各种原因,将两者分离开来:
例如在 大规模生产环境部署 中,一种经典模式是使用 1-2 台归属于 DBA 组的专用管理主机(微型虚拟机即可),
作为整个环境的控制中枢,并使用 2-3 台高配置的物理机(或者更多!),作为整个环境的监控基础设施。这时候管理节点就与基础设施节点分离开来了。
这时候,你在配置文件中填入的 admin_ip 应该指向某个 INFRA 节点的 IP 地址,而不是当前 ADMIN 节点的 IP 地址。
这是因为历史遗留原因:Pigsty 设计之初,ADMIN 节点 与 INFRA 节点 是强绑定的概念,后来才逐渐演化出分离的能力,因此参数名称未做修改。
另一种常见的情况是 本地管理云节点 ,例如,您可以在自己的笔记本上安装 Ansible,然后填入你的云节点作为 “被管理对象”。
在这种情况下,您的笔记本充当 ADMIN 节点,而云服务器充当 INFRA 节点。
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 , ansible_host : your_ssh_alias } } } # <--- 利用 ansible_host 指向云节点(填入 ssh 别名)
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } } # ssh 连接会使用 ssh your_ssh_alias
pg-meta : { hosts : { 10.10.10.10 : { pg_seq: 1, pg_role: primary } }, vars : { pg_cluster : pg-meta } }
vars :
version : v4.3.0
admin_ip : 10.10.10.10
region : default
多个 INFRA 节点 默认情况下,Pigsty 只需要一个 INFRA 节点即可满足大部分需求。INFRA 模块挂了,也不会影响其他节点上的数据库服务。
但是,在一些对监控与告警要求极高的生产环境中,您可能希望部署多个 INFRA 节点,来提升基础设施的可用性。
一种常见的部署是使用两个 Infra 节点,提供一份冗余副本,并互相监控对方…
或者使用更多,部署分布式的 Victoria 集群实现无限水平扩展。
每个 Infra 节点都是 独立 的,Nginx 指向的都是本机上的服务。
VictoriaMetrics 也是独立抓取环境中所有服务的监控指标,
日志会默认推送到所有 VictoriaLogs 日志采集端点上。
唯一的例外是 Grafana,每一个 Grafana 中都会注册所有的 VictoriaMetrics / Logs / Traces / PostgreSQL 实例作为数据源。
因此每一个 Grafana 实例都能看到完整的监控数据。
如果您对 Grafana 进行修改,例如添加新的仪表板,或者修改数据源配置,这些变更只会影响当前节点上的 Grafana 实例。
如果您希望所有节点上的 Grafana 保持一致,可以使用一个 PostgreSQL 数据库作为共享存储,详情参考 教程:配置 Grafana 高可用 。
3.1.3 - PGSQL 架构 PostgreSQL 模块的组件交互与数据流。
PGSQL 模块在生产环境中以 集群 的形式组织,这些 集群 是由一组通过 主-备 关联的数据库 实例 组成的 逻辑实体 。
概览 PGSQL 模块 包含下列组件,协同提供生产级 PostgreSQL 高可用集群服务:
其中 vip-manager 为按需启用的组件。此外,PGSQL 还会使用到其他模块中的组件:
如果用类比来形容,PostgreSQL 数据库内核就是 CPU,而整个 PGSQL 模块将其封装为一台完整的计算机。
Patroni 与 Etcd 组成 高可用子系统 ,pgBackRest 与 MinIO 组成 备份恢复子系统 。
HAProxy 与 Pgbouncer 、vip-manager 组成 接入子系统 。
各种 Exporter 与 Vector 构成 可观测性子系统 ;
最后还可以替换不同的 内核 CPU 与 扩展卡 。
组件交互
高可用子系统 高可用 子系统由 Patroni 与 etcd 组成,负责 PostgreSQL 集群的故障检测、自动切换与配置管理。
工作原理 :Patroni 在每个节点上运行,托管本地 PostgreSQL 进程,并将集群状态(领导者、成员、配置)写入 etcd 。
当主库故障时,Patroni 通过 etcd 协调选举,选出最健康的从库提升为新主库,整个过程自动完成,RTO 通常在 45 秒内。
关键交互 :
更多信息请参阅:高可用 与 配置:PGSQL - PG_BOOTSTRAP
服务接入子系统 接入子系统由 HAProxy 、Pgbouncer 与 vip-manager 组成,负责对外暴露服务、路由流量与连接池化。
有多种不同的接入方法,一种典型的流量路径是:客户端 → DNS/VIP → HAProxy (543x) → Pgbouncer (6432) → PostgreSQL (5432)
服务端口 :
5433 primary:读写服务,路由至主库 Pgbouncer 5434 replica:只读服务,路由至从库 Pgbouncer 5436 default:默认服务,直连主库(绕过连接池)5438 offline:离线服务,直连离线从库(ETL/分析)关键特性 :
更多信息请参阅:服务接入 与 配置:PGSQL - PG_ACCESS
备份恢复子系统 备份恢复子系统由 pgBackRest 组成(可选配 MinIO 作为远程仓库),负责数据备份与时间点恢复(PITR )。
备份类型 :
全量备份 :完整的数据库副本增量/差异备份 :仅备份变更的数据块WAL 归档 :持续归档事务日志,支持任意时间点恢复存储后端 :
local(默认):本地磁盘,备份存储在 pg_fs_backup 挂载点minio:S3 兼容对象存储,支持集中化备份管理与异地容灾关键交互 :
更多信息请参阅:PITR 、备份恢复 与 配置:PGSQL - PG_BACKUP
可观测性子系统 可观测性子系统由三个 Exporter 与 Vector 组成,负责指标采集与日志收集。
数据流向 :
指标 :Exporter → VictoriaMetrics(INFRA)→ Grafana 仪表盘日志 :Vector → VictoriaLogs(INFRA)→ Grafana 日志查询pg_exporter / pgbouncer_exporter 通过本地 Unix Socket 连接目标服务,与 HA 拓扑解耦。在 精简安装 模式下,可禁用这些组件。
更多信息请参阅:配置:PGSQL - PG_MONITOR
PostgreSQL PostgreSQL 是 PGSQL 模块的核心,默认监听 5432 端口提供关系型数据库服务,采用与 节点 1:1 对应的部署模型。
Pigsty 目前支持 PostgreSQL 14 - 18(生命周期内的大版本),使用 PGDG 官方仓库 提供的二进制包安装。
Pigsty 还允许您使用其他的 PG 内核分支 替换默认的 PostgreSQL 内核,
并在 PG 内核上加装多达 510 个扩展插件。
PostgreSQL 进程默认由 高可用 Agent —— Patroni 托管拉起。
当一个集群中只有一个节点时,该实例即为主库;当集群包含多个节点时,其余实例会自动作为从库加入:
通过物理复制,实时从主库同步数据变更。从库可以承载只读请求,并在主库故障时自动接管。
您可以直接访问 PostgreSQL,或者通过 HAProxy 与 Pgbouncer 连接池来访问。
更多信息请参阅:配置:PGSQL - PG_BOOTSTRAP
Patroni Patroni 是 PostgreSQL 高可用控制组件,默认监听 8008 端口。
Patroni 接管 PostgreSQL 的启动、停止、配置与健康状态,将领导者、成员信息写入 etcd 。
它负责自动故障转移、保持复制因子、协调参数变更,并提供 REST API 供 HAProxy 、监控与管理员查询。
HAProxy 通过 Patroni 健康检查端点判断实例角色,将流量路由至正确的主库或从库。
vip-manager 监视 etcd 中的领导者键,在主库切换时自动漂移 VIP。
更多信息请参阅:配置:PGSQL - PG_BOOTSTRAP
Pgbouncer Pgbouncer 是轻量级连接池中间件,默认监听 6432 端口,与 PostgreSQL 数据库与节点保持 1:1 部署。
Pgbouncer 以无状态方式运行在每个实例上,通过本地 Unix Socket 连接 PostgreSQL ,默认通过 Transaction Pooling 的方式
对 PG 连接进行池化管理,能够吸收大量客户端的瞬时连接请求,稳定数据库会话,降低锁征用,显著提升高并发状态下的性能表现。
Pigsty 默认让生产流量(读写服务 5433 / 只读服务 5434)经由 Pgbouncer ,
仅默认服务(5436)与离线服务(5438)绕过连接池直连 PostgreSQL 。
连接池模式由 pgbouncer_poolmode 控制,默认为 transaction(事务级复用),可通过 pgbouncer_enabled 关闭连接池。
更多信息请参阅:配置:PGSQL - PG_ACCESS
pgBackRest pgBackRest 是专业的 PostgreSQL 备份恢复工具,也是 PG 生态的最强备份工具之一,支持全量/增量/差异备份与 WAL 归档。
Pigsty 使用 pgBackRest 实现 PostgreSQL 的 PITR 能力,
您可以在备份保留的时间窗口内,将集群回滚到任意时间点。
pgBackRest 与 PostgreSQL 配合,在主库上创建备份仓库,执行备份与归档任务。
默认使用本地备份仓库(pgbackrest_method = local),也可配置为 MinIO 等对象存储,实现集中化备份管理。
初始化完成后可通过 pgbackrest_init_backup 自动发起首次全量备份。
恢复过程与 Patroni 集成,支持将副本引导为新的主库或备库。
更多信息请参阅:备份恢复 与 配置:PGSQL - PG_BACKUP
HAProxy HAProxy 是服务入口与负载均衡器,对外暴露多个数据库服务端口。
端口 服务名 目标 说明 9101管理接口 - HAProxy 统计与管理页面 5433primary 主库 Pgbouncer 读写服务,路由至主库连接池 5434replica 从库 Pgbouncer 只读服务,路由至从库连接池 5436default 主库 Postgres 默认服务,直连主库(绕过连接池) 5438offline 离线库 Postgres 离线服务,直连离线从库(ETL/分析)
HAProxy 通过 Patroni REST API 提供的健康检查信息判断实例角色,将流量路由至对应的主库或从库。
服务定义由 pg_default_services 与 pg_services 组合而成。
可通过 pg_service_provider 指定专用的 HAProxy 节点组承载更高流量,
默认使用本地节点上的 HAProxy 对外发布服务。
更多信息请参阅:服务接入 与 配置:PGSQL - PG_ACCESS
vip-manager vip-manager 负责将 L2 VIP 绑定到当前主库节点,这是一个可选的组件,如果您的网络支持 L2 VIP,可以考虑启用。
vip-manager 在每个 PG 节点上运行,监视 etcd 中由 Patroni 写入的领导者键,
将 pg_vip_address 绑定到当前主库节点的网卡上。
当集群发生故障转移时,vip-manager 会立即释放旧主机上的 VIP,并在新主机上重新绑定,从而将流量切换到新的主库。
该组件可选,通过 pg_vip_enabled 启用。
启用后需确保所有节点处于同一 VLAN,否则 VIP 无法正确漂移。
通常公有云网络环境不支持 L2 VIP,建议仅在本地自建环境与私有云环境中启用。
更多信息请参阅:教程:VIP 配置 与 配置:PGSQL - PG_ACCESS
pg_exporter pg_exporter 导出 PostgreSQL 监控指标,默认监听 9630 端口。
pg_exporter 运行在每个 PG 节点上,通过本地 Unix Socket 连接 PostgreSQL ,
导出覆盖会话、缓冲命中、复制延迟、事务率等丰富指标,供 INFRA 节点上的 VictoriaMetrics 抓取。
采集配置由 pg_exporter_config 指定,
支持自动数据库发现(pg_exporter_auto_discovery ),
并可通过 pg_exporter_cache_ttls 配置阶梯式缓存策略。
您可以通过参数禁用这个组件,在 精简安装 中,这个组件不会被启用。
更多信息请参阅:配置:PGSQL - PG_MONITOR
pgbouncer_exporter pgbouncer_exporter 导出 Pgbouncer 连接池指标,默认监听 9631 端口。
pgbouncer_exporter 使用的同样是 pg_exporter 的二进制程序,但是使用专用的指标配置文件,支持 pgbouncer 1.8 - 1.25+。
pgbouncer_exporter 读取 Pgbouncer 的统计视图,提供连接池利用率、等待队列与命中率指标。
若禁用 Pgbouncer ,本组件也同时关闭。在 精简安装 中,这个组件也不会被启用。
更多信息请参阅:配置:PGSQL - PG_MONITOR
pgbackrest_exporter pgbackrest_exporter 导出备份状态指标,默认监听 9854 端口。
pgbackrest_exporter 解析 pgBackRest 状态,生成最近备份时间、大小、类型等指标。结合告警策略可快速发现备份过期或失败,保障数据安全。
请注意,当备份很多,或者使用大型网络存储库时,采集过程开销较大,因此 pgbackrest_exporter 默认设置了 2分钟的采集间隔。
最慢情况下,您可能要在一个备份完成后的 2 分钟后,才能在监控系统中看到最新的备份状态。
更多信息请参阅:配置:PGSQL - PG_MONITOR
etcd etcd 是分布式一致性存储(DCS),为 Patroni 提供集群元数据存储与领导者选举能力。
etcd 由独立的 ETCD 模块 部署管理,不属于 PGSQL 模块本身,但对 PostgreSQL 高可用至关重要。
Patroni 将集群状态、领导者信息、配置参数写入 etcd,所有节点通过 etcd 达成共识。
vip-manager 也从 etcd 读取领导者键,实现 VIP 的自动漂移。
更多信息请参阅:ETCD 模块
vector Vector 是高性能日志采集组件,由 NODE 模块 部署,负责收集 PostgreSQL 相关日志。
Vector 常驻在节点上,跟踪 PostgreSQL 、Pgbouncer 、Patroni 与 pgBackRest 的日志目录,
将结构化日志发送至 INFRA 节点上的 VictoriaLogs 进行集中存储与查询。
更多信息请参阅:NODE 模块
3.2 - 集群模型图 Pigsty 是如何将不同种类的功能抽象成为模块的,以及这些模块的逻辑模型,实体关系图。
在 Pigsty 中最大的实体概念叫做 部署(Deployment) ,一套部署中的主要实体与关系(E-R 图)如下所示:
一套部署也可以理解为一个 环境(Environment) 。例如,生产环境(Prod),用户测试环境(UTA),预发环境(Staging),测试环境(Testing),开发环境(Devbox),等等。
每个环境中,都对应着一份 Pigsty 配置清单 ,描述了环境中的所有实体与属性。
通常来说,一套环境中也会带有一套共用的基础设施(INFRA ),广义的基础设施还包括 ETCD (高可用 DCS)以及 MINIO (集中式备份仓库),
同时供环境中的多套 PostgreSQL 数据库集群(以及其他数据库模块组件)使用。(例外:也有 不带基础设施的部署 )
在 Pigsty 中,几乎所有数据库模块都是以 “集群 "(Cluster)的方式组织起来的。每一个集群都是一个 Ansible 分组,包含有若干节点资源。
例如 PostgreSQL 高可用数据库集群,Redis,Etcd / MinIO 这些数据库都是以集群的形式存在。一套环境中可以包含多个集群。
3.2.1 - PGSQL 集群模型 介绍 Pigsty 中 PostgreSQL 集群的实体-关系模型,E-R 关系图,实体释义与命名规范。
PGSQL 模块在生产环境中以集群 的形式组织,这些集群 是由一组由主-备 关联的数据库实例 组成的逻辑实体 。
每个集群都是一个自治 的业务单元,由至少一个 主库实例 组成,并通过服务向外暴露能力。
在 Pigsty 的 PGSQL 模块中有四种核心实体:
集群 (Cluster):自治的 PostgreSQL 业务单元,用作其他实体的顶级命名空间。服务 (Service):对外暴露能力的命名抽象,路由流量,并使用节点端口暴露服务。实例 (Instance):由在单个节点上的运行进程和数据库文件组成的单一 PostgreSQL 服务器。节点 (Node):运行 Linux + Systemd 环境的硬件资源抽象,可以是裸机、VM、容器或 Pod。辅以“数据库”“角色”两个业务实体,共同组成完整的逻辑视图。如下图所示:
具体样例 让我们来看两个具体的例子,以四节点的 Pigsty 沙箱环境 为例,在这个环境中,有一套三节点的 pg-test 集群。
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 }
上面的配置片段定义了一个如下所示的 高可用 PostgreSQL 集群,该集群中的相关实体包括:
集群 Cluster pg-testPostgreSQL 3 节点高可用集群 实例 Instance pg-test-11 号 PostgreSQL 实例,默认为主库 pg-test-22 号 PostgreSQL 实例,初始为从库 pg-test-33 号 PostgreSQL 实例,初始为从库 服务 Service pg-test-primary读写服务(路由到主库 pgbouncer) pg-test-replica只读服务(路由到从库 pgbouncer) pg-test-default直连读写服务(路由到主库 postgres) pg-test-offline离线读取服务(路由到专用 postgres) 节点 Nodes node-110.10.10.11 1 号节点,对应 pg-test-1 PG 实例node-210.10.10.12 2 号节点,对应 pg-test-2 PG 实例node-310.10.10.13 3 号节点,对应 pg-test-3 PG 实例
身份参数 Pigsty 使用 PG_ID 参数组为 PGSQL 模块的每个实体赋予确定的身份。以下三项为必选参数:
参数 类型 级别 说明 形式 pg_clusterstring集群 PG 集群名称,必选身份参数 有效的 DNS 名称,满足正则表达式 [a-zA-Z0-9-]+ pg_seqint实例 PG 实例编号,必选身份参数 自然数,可从 0 或 1 开始分配,集群内不重复 pg_roleenum实例 PG 实例角色,必选身份参数 枚举值,可为 primary,replica,offline
只要在集群层面定义了集群名称,实例层面分配了实例编号与角色,Pigsty 就能自动根据规则为每个实体生成唯一标识符。
实体 生成规则 示例 实例 {{ pg_cluster }}-{{ pg_seq }}pg-test-1,pg-test-2,pg-test-3服务 {{ pg_cluster }}-{{ pg_role }}pg-test-primary,pg-test-replica,pg-test-offline节点 显示指定覆盖,或自动从 PG 实例借用 pg-test-1,pg-test-2,pg-test-3
因为 Pigsty 采用节点与 PG 实例 1:1 的独占部署模型,因此默认情况下,主机节点的标识符会直接借用 PG 实例的标识符(node_id_from_pg )。
当然您也可以显式指定 nodename 进行覆盖,或者关闭 nodename_overwrite ,直接使用当前默认值。
分片身份参数 当你使用多套 PostgreSQL (分片 / Sharding)集群服务同一业务时,还会使用到另外两个身份参数:pg_shard 与 pg_group 。
在这种情况下,这一组 PostgreSQL 集群将拥有相同的 pg_shard 名称,以及各自的 pg_group 编号,例如下面的 Citus 集群 :
在这种情况下,pg_cluster 集群名通常由:{{ pg_shard }}{{ pg_group }} 组合而成,例如 pg-citus0、pg-citus1 等。
all :
children :
pg-citus0 : # citus 0号分片
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus0 , pg_group : 0 }
pg-citus1 : # citus 1号分片
hosts : { 10.10.10.11 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus1 , pg_group : 1 }
pg-citus2 : # citus 2号分片
hosts : { 10.10.10.12 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus2 , pg_group : 2 }
pg-citus3 : # citus 3号分片
hosts : { 10.10.10.13 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus3 , pg_group : 3 }
Pigsty 专门为水平分片集群提供专门的监控面板,便于对比各分片的性能与负载情况,但这需要您使用上述实体命名规则。
还有一些其他的身份参数,可能在特殊场景会使用到,例如,指定备份集群/级联复制上游的 pg_upstream ,指定 Greenplum 集群身份的 gp_role ,
指定外部监控实例的 pg_exporters ,指定实例为离线查询库的 pg_offline_query 等,请参考 PG_ID 参数文档 。
监控标签体系 Pigsty 提供了一套开箱即用的监控系统,在这个系统中使用上面的 身份参数 来标识各个 PostgreSQL 实体对象。
pg_up{cls="pg-test", ins="pg-test-1", ip="10.10.10.11", job="pgsql"}
pg_up{cls="pg-test", ins="pg-test-2", ip="10.10.10.12", job="pgsql"}
pg_up{cls="pg-test", ins="pg-test-3", ip="10.10.10.13", job="pgsql"}
例如,上面的 cls,ins,ip 三个标签,分别对应集群名、实例名与节点 IP,这三个核心实体的标识符。
它们与 job 标签,在 所有 VictoriaMetrics 采集的原生监控指标,以及 VictoriaLogs 日志流中都会出现并可用。
采集 PostgreSQL 指标的 job 名固定为 pgsql;
用于监控远程 PG 实例的 job 名固定为 pgrds。
采集 PostgreSQL CSV 日志的 job 名固定为 postgres;
采集 pgbackrest 日志的 job 名固定为 pgbackrest,其余 PG 组件通过 job: syslog 采集日志。
此外,还有一些普通实体身份标签,会在实体相关的特定监控指标中出现,例如:
datname: 数据库名,如果一个监控指标属于某个具体的数据库,则会带上这个标签。relname: 表名,如果一个监控指标属于某个具体的表,则会带上这个标签。idxname: 索引名,如果一个监控指标属于某个具体的索引,则会带上这个标签。funcname: 函数名,如果一个监控指标属于某个具体的函数,则会带上这个标签。seqname: 序列名,如果一个监控指标属于某个具体的序列,则会带上这个标签。query: 查询指纹,如果一个监控指标属于某个具体的查询,则会带上这个标签。3.2.2 - ETCD 集群模型 介绍 Pigsty 中 ETCD 集群的实体-关系模型,E-R 关系图,实体释义与命名规范。
ETCD 模块在生产环境中以集群 的形式组织,这些集群 是由一组通过 Raft 共识协议关联的 ETCD 实例 组成的逻辑实体 。
每个集群都是一个自治 的分布式键值存储单元,由至少一个 ETCD 实例 组成,通过客户端端口向外暴露服务能力。
在 Pigsty 的 ETCD 模块中有三种核心实体:
集群 (Cluster):自治的 ETCD 服务单元,用作其他实体的顶级命名空间。实例 (Instance):单个 ETCD 服务器进程,在节点上运行,参与 Raft 共识。节点 (Node):运行 Linux + Systemd 环境的硬件资源抽象,隐含式声明。相比于 PostgreSQL 集群,ETCD 集群模型更为简单,没有服务(Service)和复杂的角色(Role)区分。
所有 ETCD 实例在功能上是对等的,通过 Raft 协议选举出 Leader,其余为 Follower。
在扩容的中间状态,还允许不参与投票的 Learner 实例成员存在。
具体样例 让我们来看一个具体的例子,以三节点的 ETCD 集群为例:
etcd :
hosts :
10.10.10.10 : { etcd_seq : 1 }
10.10.10.11 : { etcd_seq : 2 }
10.10.10.12 : { etcd_seq : 3 }
vars :
etcd_cluster : etcd
上面的配置片段定义了一个如下所示的三节点 ETCD 集群,该集群中的相关实体包括:
集群 Cluster etcdETCD 三节点高可用集群 实例 Instance etcd-11 号 ETCD 实例 etcd-22 号 ETCD 实例 etcd-33 号 ETCD 实例 节点 Nodes 10.10.10.101 号节点,对应 etcd-1 实例 10.10.10.112 号节点,对应 etcd-2 实例 10.10.10.123 号节点,对应 etcd-3 实例
身份参数 Pigsty 使用 ETCD 参数组为 ETCD 模块的每个实体赋予确定的身份。以下两项为必选参数:
参数 类型 级别 说明 形式 etcd_clusterstring集群 ETCD 集群名称,必选身份参数 有效的 DNS 名称,默认为固定值 etcd etcd_seqint实例 ETCD 实例编号,必选身份参数 自然数,从 1 开始分配,集群内不重复
只要在集群层面定义了集群名称,实例层面分配了实例编号,Pigsty 就能自动根据规则为每个实体生成唯一标识符。
实体 生成规则 示例 实例 {{ etcd_cluster }}-{{ etcd_seq }}etcd-1,etcd-2,etcd-3
ETCD 模块不会为主机节点赋予额外的身份标识,节点使用其原有的主机名或 IP 地址进行标识。
端口协议 每个 ETCD 实例会监听以下两个端口:
ETCD 集群默认启用 TLS 加密通信,并使用 RBAC 认证机制。客户端需要使用正确的证书和密码才能访问 ETCD 服务。
集群规模 ETCD 作为分布式协调服务,集群规模直接影响其可用性,需要有超过半数(仲裁数)的节点存活才能维持服务。
集群规模 仲裁数 容忍故障数 适用场景 1 节点 1 0 开发、测试、演示 3 节点 2 1 中小规模生产环境 5 节点 3 2 大规模生产环境
因此,偶数节点的 ETCD 集群没有意义,超过五节点的 ETCD 集群并不常见,因此通常使用的规格就是单节点、三节点、五节点。
监控标签体系 Pigsty 提供了一套开箱即用的监控系统,在这个系统中使用上面的 身份参数 来标识各个 ETCD 实体对象。
etcd_up{cls="etcd", ins="etcd-1", ip="10.10.10.10", job="etcd"}
etcd_up{cls="etcd", ins="etcd-2", ip="10.10.10.11", job="etcd"}
etcd_up{cls="etcd", ins="etcd-3", ip="10.10.10.12", job="etcd"}
例如,上面的 cls,ins,ip 三个标签,分别对应集群名、实例名与节点 IP,这三个核心实体的标识符。
它们与 job 标签,在 所有 VictoriaMetrics 采集的 ETCD 监控指标中都会出现并可用。
采集 ETCD 指标的 job 名固定为 etcd。
3.2.3 - MINIO 集群模型 介绍 Pigsty 中 MinIO 集群的实体-关系模型,E-R 关系图,实体释义与命名规范。
MinIO 模块在生产环境中以集群 的形式组织,这些集群 是由一组分布式 MinIO 实例 组成的逻辑实体 ,共同提供高可用的对象存储服务。
每个集群都是一个自治 的 S3 兼容对象存储单元,由至少一个 MinIO 实例 组成,通过 S3 API 端口向外暴露服务能力。
在 Pigsty 的 MinIO 模块中有三种核心实体:
集群 (Cluster):自治的 MinIO 服务单元,用作其他实体的顶级命名空间。实例 (Instance):单个 MinIO 服务器进程,在节点上运行,管理本地磁盘存储。节点 (Node):运行 Linux + Systemd 环境的硬件资源抽象,隐含式声明。此外,MinIO 还有 存储池 (Pool)的概念,用于集群平滑扩容。
一个集群可以包含多个存储池,每个存储池由一组节点和磁盘组成。
部署模式 MinIO 支持三种主要部署模式,适用于不同的场景:
模式 代号 说明 适用场景 单机单盘 SNSD 单节点,单个数据目录,或单块磁盘 开发、测试、演示 单机多盘 SNMD 单节点,使用多块磁盘,通常至少 4 块盘 资源受限的小规模部署 多机多盘 MNMD 多节点,每节点多块磁盘 生产环境推荐
单机单盘模式可以使用任意目录作为存储,适合快速体验;单机多盘和多机多盘模式需要使用真实的磁盘挂载点,否则会拒绝启动。
具体样例 让我们来看一个多机多盘模式的具体例子,以四节点的 MinIO 集群为例:
minio :
hosts :
10.10.10.10 : { minio_seq : 1 }
10.10.10.11 : { minio_seq : 2 }
10.10.10.12 : { minio_seq : 3 }
10.10.10.13 : { minio_seq : 4 }
vars :
minio_cluster : minio
minio_data : '/data{1...4}'
minio_node : '${minio_cluster}-${minio_seq}.pigsty'
上面的配置片段定义了一个四节点的 MinIO 集群,每个节点使用四块磁盘,该集群中的相关实体包括:
集群 Cluster minioMinIO 四节点高可用集群 实例 Instance minio-11 号 MinIO 实例,管理 4 块磁盘 minio-22 号 MinIO 实例,管理 4 块磁盘 minio-33 号 MinIO 实例,管理 4 块磁盘 minio-44 号 MinIO 实例,管理 4 块磁盘 节点 Nodes 10.10.10.101 号节点,对应 minio-1 实例 10.10.10.112 号节点,对应 minio-2 实例 10.10.10.123 号节点,对应 minio-3 实例 10.10.10.134 号节点,对应 minio-4 实例
身份参数 Pigsty 使用 MINIO 参数组为 MinIO 模块的每个实体赋予确定的身份。以下两项为必选参数:
参数 类型 级别 说明 形式 minio_clusterstring集群 MinIO 集群名称,必选身份参数 有效的 DNS 名称,默认为 minio minio_seqint实例 MinIO 实例编号,必选身份参数 自然数,从 1 开始分配,集群内不重复
只要在集群层面定义了集群名称,实例层面分配了实例编号,Pigsty 就能自动根据规则为每个实体生成唯一标识符。
实体 生成规则 示例 实例 {{ minio_cluster }}-{{ minio_seq }}minio-1,minio-2,minio-3,minio-4
MinIO 模块不会为主机节点赋予额外的身份标识,节点使用其原有的主机名或 IP 地址进行标识。
minio_node 参数用于生成 MinIO 集群内部的节点名称(写入 /etc/hosts 供集群发现使用),而非主机节点的身份。
核心配置参数 除身份参数外,以下参数对 MinIO 集群配置至关重要:
这些参数共同决定了 MinIO 的核心配置 MINIO_VOLUMES:
单机单盘 :直接使用 minio_data 的值,如 /data/minio单机多盘 :使用 minio_data 展开的多个目录,如 /data{1...4}多机多盘 :组合 minio_node 与 minio_data,如 https://minio-{1...4}.pigsty:9000/data{1...4}端口与服务 每个 MinIO 实例会监听以下端口:
MinIO 默认启用 HTTPS 加密通信(由 minio_https 控制)。这对于 pgBackREST 等备份工具访问 MinIO 是必需的。
多节点 MinIO 集群可以通过访问 任意一个节点 来访问其服务。最佳实践是使用负载均衡器(如 HAProxy + VIP)统一接入点。
资源置备 MinIO 集群部署后,Pigsty 会自动创建以下资源(由 minio_provision 控制):
默认存储桶 (由 minio_buckets 定义):
存储桶 用途 pgsqlPostgreSQL pgBackREST 备份存储 meta元数据存储,启用版本控制 data通用数据存储
默认用户 (由 minio_users 定义):
用户 默认密码 策略 用途 pgbackrestS3User.BackuppgsqlPostgreSQL 备份专用用户 s3user_metaS3User.Metameta访问 meta 存储桶 s3user_dataS3User.Datadata访问 data 存储桶
pgbackrest 是 PostgreSQL 集群备份时使用的用户,s3user_meta 和 s3user_data 是未实际使用的保留用户。
监控标签体系 Pigsty 提供了一套开箱即用的监控系统,在这个系统中使用上面的 身份参数 来标识各个 MinIO 实体对象。
minio_up{cls="minio", ins="minio-1", ip="10.10.10.10", job="minio"}
minio_up{cls="minio", ins="minio-2", ip="10.10.10.11", job="minio"}
minio_up{cls="minio", ins="minio-3", ip="10.10.10.12", job="minio"}
minio_up{cls="minio", ins="minio-4", ip="10.10.10.13", job="minio"}
例如,上面的 cls,ins,ip 三个标签,分别对应集群名、实例名与节点 IP,这三个核心实体的标识符。
它们与 job 标签,在 所有 VictoriaMetrics 采集的 MinIO 监控指标中都会出现并可用。
采集 MinIO 指标的 job 名固定为 minio。
3.2.4 - REDIS 集群模型 介绍 Pigsty 中 Redis 集群的实体-关系模型,E-R 关系图,实体释义与命名规范。
Redis 模块在生产环境中以集群 的形式组织,这些集群 是由一组 Redis 实例 组成的逻辑实体 ,部署在一个或多个节点 上。
每个集群都是一个自治 的高性能缓存/存储单元,由至少一个 Redis 实例 组成,通过端口向外暴露服务能力。
在 Pigsty 的 Redis 模块中有三种核心实体:
集群 (Cluster):自治的 Redis 服务单元,用作其他实体的顶级命名空间。实例 (Instance):单个 Redis 服务器进程,在节点上的特定端口运行。节点 (Node):运行 Linux + Systemd 环境的硬件资源抽象,可以承载多个 Redis 实例,隐含式声明。与 PostgreSQL 不同,Redis 采用 单机多实例 的部署模型:一个物理/虚拟机节点上通常会部署 多个 Redis 实例,
以充分利用多核 CPU。因此,节点与实例是 1:N 的关系。此外,生产中通常不建议设置单个内存规模大于 12GB 的 Redis 实例。
工作模式 Redis 有三种不同的工作模式,由 redis_mode 参数指定:
模式 代号 说明 高可用机制 主从模式 standalone经典主从复制,默认模式 需配合 Sentinel 实现 哨兵模式 sentinel为主从模式提供高可用监控与自动故障转移 本身的多节点仲裁 原生集群模式 clusterRedis 原生分布式集群,无需哨兵即可高可用 内置自动故障转移
主从模式 :默认模式,通过 replica_of 参数设置主从复制关系。需要额外的 Sentinel 集群提供高可用。哨兵模式 :不存储业务数据,专门用于监控主从模式的 Redis 集群,实现自动故障转移,本身多节点即可高可用。原生集群模式 :数据自动分片到多个主节点,每个主节点可以有多个从节点,内置高可用能力,无需哨兵支持。具体样例 让我们来看三种模式的具体例子:
主从集群 一个节点上部署一主一从的经典主从集群:
redis-ms :
hosts :
10.10.10.10 :
redis_node : 1
redis_instances :
6379 : { }
6380 : { replica_of : '10.10.10.10 6379' }
vars :
redis_cluster : redis-ms
redis_password : 'redis.ms'
redis_max_memory : 64MB
集群 Cluster redis-msRedis 主从集群 节点 Nodes redis-ms-110.10.10.10 1 号节点,承载 2 个实例实例 Instance redis-ms-1-6379主库实例,监听 6379 端口 redis-ms-1-6380从库实例,监听 6380 端口,复制自 6379
哨兵集群 一个节点上部署三个哨兵实例,用于监控主从集群。哨兵集群通过 redis_sentinel_monitor 参数指定要监控的主从集群列表:
redis-sentinel :
hosts :
10.10.10.11 :
redis_node : 1
redis_instances : { 26379 : {}, 26380 : {}, 26381 : {} }
vars :
redis_cluster : redis-sentinel
redis_password : 'redis.sentinel'
redis_mode : sentinel
redis_max_memory : 16MB
redis_sentinel_monitor :
- { name: redis-ms, host: 10.10.10.10, port: 6379, password: redis.ms, quorum : 2 }
原生集群 下面的配置片段定义了由两个节点,六个实例组成的 Redis 原生分布式集群(最小规格,3主3从):
redis-test :
hosts :
10.10.10.12 : { redis_node: 1, redis_instances : { 6379 : {}, 6380 : {}, 6381 : {} } }
10.10.10.13 : { redis_node: 2, redis_instances : { 6379 : {}, 6380 : {}, 6381 : {} } }
vars :
redis_cluster : redis-test
redis_password : 'redis.test'
redis_mode : cluster
redis_max_memory : 32MB
该配置将创建一个 3 主 3 从 的原生 Redis 集群。
集群 Cluster redis-testRedis 原生集群(3 主 3 从) 实例 Instance redis-test-1-6379节点 1 上的实例,监听 6379 端口 redis-test-1-6380节点 1 上的实例,监听 6380 端口 redis-test-1-6381节点 1 上的实例,监听 6381 端口 redis-test-2-6379节点 2 上的实例,监听 6379 端口 redis-test-2-6380节点 2 上的实例,监听 6380 端口 redis-test-2-6381节点 2 上的实例,监听 6381 端口 节点 Nodes redis-test-110.10.10.12 1 号节点,承载 3 个实例redis-test-210.10.10.13 2 号节点,承载 3 个实例
身份参数 Pigsty 使用 REDIS 参数组为 Redis 模块的每个实体赋予确定的身份。以下三项为必选参数:
参数 类型 级别 说明 形式 redis_clusterstring集群 Redis 集群名称,必选身份参数 有效的 DNS 名称,满足 [a-z][a-z0-9-]* redis_nodeint节点 Redis 节点编号,必选身份参数 自然数,从 1 开始分配,集群内不重复 redis_instancesdict节点 Redis 实例定义,必选身份参数 JSON 对象,Key 为端口号,Value 为实例配置
只要在集群层面定义了集群名称,节点层面分配了节点编号与实例定义,Pigsty 就能自动根据规则为每个实体生成唯一标识符。
实体 生成规则 示例 实例 {{ redis_cluster }}-{{ redis_node }}-{{ port }}redis-ms-1-6379,redis-ms-1-6380
Redis 模块不会为主机节点赋予额外的身份标识,节点使用其原有的主机名或 IP 地址进行标识。
redis_node 参数用于实例命名,而非主机节点的身份。
实例定义 redis_instances 是一个 JSON 对象,Key 为 端口号 ,Value 为该实例的 配置项 :
redis_instances :
6379 : { } # 主库实例,无需额外配置
6380 : { replica_of : '10.10.10.10 6379' } # 从库实例,指定上游主库
6381 : { replica_of : '10.10.10.10 6379' } # 从库实例,指定上游主库
每个 Redis 实例会监听一个唯一的端口,端口在节点上唯一不重复,您可以任意选择端口号,
但请不要使用系统保留端口(小于 1024),或者与 Pigsty 使用的端口 冲突。
实例配置中的 replica_of 参数用于在主从模式下设置复制关系,格式为 '<ip> <port>',用于指定一个 Redis 从库的上游主库地址与端口。
此外,每个 Redis 节点上会运行一个 Redis Exporter,用于汇总采集当前节点上 所有本地实例 的监控指标:
Redis 模块的单机多实例部署模型带有一些局限性:
节点独占 :一个节点只能属于一个 Redis 集群,不能同时分配给不同的 Redis 集群。端口唯一 :同一节点上的 Redis 实例必须使用不同的端口号,避免端口冲突。密码共享 :同一节点上的多个 Redis 实例无法设置不同的密码(受 redis_exporter 限制)。手动高可用 :主从模式的 Redis 集群需要额外配置 Sentinel 才能实现自动故障转移。监控标签体系 Pigsty 提供了一套开箱即用的监控系统,在这个系统中使用上面的 身份参数 来标识各个 Redis 实体对象。
redis_up{cls="redis-ms", ins="redis-ms-1-6379", ip="10.10.10.10", job="redis"}
redis_up{cls="redis-ms", ins="redis-ms-1-6380", ip="10.10.10.10", job="redis"}
例如,上面的 cls,ins,ip 三个标签,分别对应集群名、实例名与节点 IP,这三个核心实体的标识符。
它们与 job 标签,在 所有 VictoriaMetrics 采集的 Redis 监控指标中都会出现并可用。
采集 Redis 指标的 job 名固定为 redis。
3.2.5 - INFRA 集群模型 介绍 Pigsty 中 INFRA 基础设施节点的实体-关系模型,组件构成与命名规范。
INFRA 模块在 Pigsty 中承担着特殊的角色:它不是传统意义上的"集群",而是由一组 基础设施节点 构成的管理中枢,为整个 Pigsty 部署提供核心服务。
每个 INFRA 节点都是一个自治 的基础设施服务单元,运行着 Nginx、Grafana、VictoriaMetrics 等核心组件,共同为纳管的数据库集群提供可观测性与管理能力。
在 Pigsty 的 INFRA 模块中有两种核心实体:
节点 (Node):运行基础设施组件的服务器,可以是裸机、VM、容器或 Pod。组件 (Component):在节点上运行的各类基础设施服务,如 Nginx、Grafana、VictoriaMetrics 等。INFRA 节点通常承担管理节点(Admin Node)的角色,是 Pigsty 的控制平面所在。
组件构成 每个 INFRA 节点上运行着以下核心组件:
这些组件共同构成了 Pigsty 的可观测性基础设施。
具体样例 让我们来看一个具体的例子,以双节点的 INFRA 部署为例:
infra :
hosts :
10.10.10.10 : { infra_seq : 1 }
10.10.10.11 : { infra_seq : 2 }
上面的配置片段定义了一个双节点的 INFRA 部署:
分组 Group infraINFRA 基础设施节点分组 节点 Nodes infra-110.10.10.10 1 号 INFRA 节点infra-210.10.10.11 2 号 INFRA 节点
在生产环境中,建议部署至少两个 INFRA 节点,以实现基础设施组件的冗余。
身份参数 Pigsty 使用 INFRA_ID 参数组为 INFRA 模块的每个实体赋予确定的身份。以下一项为必选参数:
参数 类型 级别 说明 形式 infra_seqint节点 INFRA 节点序号,必选身份参数 自然数,从 1 开始分配,分组内不重复
只要在节点层面分配了节点序号,Pigsty 就能自动根据规则为每个实体生成唯一标识符。
实体 生成规则 示例 节点 infra-{{ infra_seq }}infra-1,infra-2
INFRA 模块会为节点赋予 infra-N 形式的标识,用于监控系统中区分多个基础设施节点。
但这并不改变节点本身的主机名或系统身份,节点仍然使用其原有的主机名或 IP 地址进行标识。
服务门户 INFRA 节点通过 Nginx 提供统一的 Web 服务入口。infra_portal 参数定义了通过 Nginx 暴露的服务列表。
默认配置只定义了首页服务器:
infra_portal :
home : { domain : i.pigsty }
Pigsty 会自动为启用的组件(如 Grafana、VictoriaMetrics、AlertManager 等)配置反向代理端点。如果需要通过独立域名访问这些服务,可以显式添加配置:
infra_portal :
home : { domain : i.pigsty }
grafana : { domain: g.pigsty, endpoint : "${admin_ip}:3000" , websocket : true }
prometheus : { domain: p.pigsty, endpoint : "${admin_ip}:8428" } # VMUI
alertmanager : { domain: a.pigsty, endpoint : "${admin_ip}:9059" }
域名 服务 说明 i.pigstyHome Pigsty 首页 g.pigstyGrafana 监控可视化平台 p.pigstyVictoriaMetrics 时序数据库 Web UI a.pigstyAlertmanager 告警管理界面
建议通过域名访问 Pigsty 服务,而不是直接使用 IP + 端口的方式。
部署规模 INFRA 节点的数量取决于部署规模和高可用需求:
部署规模 INFRA 节点数 说明 开发测试 1 单节点部署,所有组件在同一节点 小规模生产 1-2 单节点或双节点,可与其他服务共用节点 中规模生产 2-3 独立的 INFRA 节点,组件冗余部署 大规模生产 3+ 多 INFRA 节点,可根据组件分离部署
单机部署 时,INFRA 组件与 PGSQL、ETCD 等模块共用同一个节点。
通常在小规模部署中,INFRA 节点通常还承担着 “管理节点 ” / “备用管理节点”,以及本地软件仓库(/www/pigsty)的角色。
在更大规模的部署中,这些职责可以剥离至专用节点。
监控标签体系 Pigsty 的监控系统会采集 INFRA 组件自身的指标。与数据库模块不同,INFRA 模块的每个组件 都被视为独立的监控对象,通过 cls(类)标签区分不同组件类型。
标签 说明 示例 cls组件类型,每种组件各自构成一个"类" nginxins实例名,格式为 {组件类型}-{infra_seq} nginx-1ip运行该组件的 INFRA 节点 IP 地址 10.10.10.10jobVictoriaMetrics 采集任务名,固定为 infra infra
以双节点 INFRA 部署(infra_seq: 1 和 infra_seq: 2)为例,各组件的监控标签如下:
组件 clsins 示例端口 Nginx nginxnginx-1,nginx-29113Grafana grafanagrafana-1,grafana-23000VictoriaMetrics vmetricsvmetrics-1,vmetrics-28428VictoriaLogs vlogsvlogs-1,vlogs-29428VictoriaTraces vtracesvtraces-1,vtraces-210428VMAlert vmalertvmalert-1,vmalert-28880Alertmanager alertmanageralertmanager-1,alertmanager-29059Blackbox blackboxblackbox-1,blackbox-29115
所有 INFRA 组件的监控指标都使用统一的 job="infra" 标签,通过 cls 标签区分组件类型:
nginx_up{cls="nginx", ins="nginx-1", ip="10.10.10.10", job="infra"}
grafana_info{cls="grafana", ins="grafana-1", ip="10.10.10.10", job="infra"}
vm_app_version{cls="vmetrics", ins="vmetrics-1", ip="10.10.10.10", job="infra"}
vlogs_rows_ingested_total{cls="vlogs", ins="vlogs-1", ip="10.10.10.10", job="infra"}
alertmanager_alerts{cls="alertmanager", ins="alertmanager-1", ip="10.10.10.10", job="infra"}
3.3 - 声明式配置 —— 基础设施即代码(IaC) Pigsty 使用基础设施即代码(IaC)的理念管理所有组件,针对大规模集群提供声明式管理能力。
Pigsty 遵循 IaC 与 GitOPS 的理念:使用声明式的 配置清单 描述整个环境,并通过 幂等剧本 来实现。
用户用声明的方式通过 参数 来描述自己期望的状态,而剧本则以幂等的方式调整目标节点以达到这个状态。
这类似于 Kubernetes 的 CRD & Operator,然而 Pigsty 在裸机和虚拟机上,通过 Ansible 实现了这样的功能。
Pigsty 诞生之初是为了解决超大规模 PostgreSQL 集群的运维管理问题,背后的想法很简单 —— 我们需要有在十分钟内在就绪的服务器上复刻整套基础设施(100+数据库集群 + PG/Redis + 可观测性)的能力。
任何 GUI + ClickOps 都无法在如此短的时间内完成如此复杂的任务,这让 CLI + IaC 成为唯一的选择 —— 它提供了精确,高效的控制能力。
配置清单 pigsty.yml 文件描述了整个部署的状态,无论是 生产环境(prod),预发环境(staging), 测试环境(test),还是 开发环境(devbox),
基础设施的区别仅在于配置清单的不同,而部署交付的逻辑则是完全相同的。
您可以使用 git 对这份部署的 “种子/基因” 进行版本控制与审计,而且,Pigsty 甚至支持将配置清单以数据库表的形式存储在 PostgreSQL CMDB 中,
更进一步从 Infra as Code 升级为 Infra as Data,无缝与您现有的工作流程集成与对接。
IaC 面向专业用户与企业场景而设计,但也针对个人开发者,SMB 进行了深度优化。
即使您并非专业 DBA,也无需了解这几百个调节开关与旋钮,所有参数都带有表现良好的默认值,
您完全可以在 零配置 的情况下,获得一个开箱即用的单机数据库节点;
简单地再添加两行 IP 地址,就能获得一套企业级的高可用的 PostgreSQL 集群。
声明模块 以下面的默认配置片段为例,这段配置描述了一个节点 10.10.10.10,其上安装了 INFRA 、NODE 、ETCD 和 PGSQL 模块。
# 监控、告警、DNS、NTP 等基础设施集群...
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
# minio 集群,兼容 s3 的对象存储
minio : { hosts : { 10.10.10.10 : { minio_seq: 1 } }, vars : { minio_cluster : minio } }
# etcd 集群,用作 PostgreSQL 高可用所需的 DCS
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
# PGSQL 示例集群: pg-meta
pg-meta : { hosts : { 10.10.10.10 : { pg_seq: 1, pg_role: primary }, vars : { pg_cluster : pg-meta } }
要真正安装这些模块,执行以下剧本:
./infra.yml -l 10.10.10.10 # 在节点 10.10.10.10 上初始化 infra 模块
./etcd.yml -l 10.10.10.10 # 在节点 10.10.10.10 上初始化 etcd 模块
./minio.yml -l 10.10.10.10 # 在节点 10.10.10.10 上初始化 minio 模块
./pgsql.yml -l 10.10.10.10 # 在节点 10.10.10.10 上初始化 pgsql 模块
声明集群 您可以声明 PostgreSQL 数据库集群,在多个节点上安装 PGSQL 模块,并使其成为一个服务单元:
例如,要在以下三个已被 Pigsty 纳管的节点上,部署一个使用流复制组建的三节点高可用 PostgreSQL 集群,
您可以在配置文件 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 # 创建 pg-test 集群
你可以使用不同的实例角色,例如 主库 (primary),从库 (replica),离线从库 (offline),延迟从库 (delayed),同步备库 (sync standby);
以及不同的集群:例如 备份集群 (Standby Cluster),Citus 集群 ,甚至是 Redis / MinIO / Etcd 集群
定制集群内容 您不仅可以使用声明式的方式定义集群,还可以定义集群中的数据库、用户、服务、HBA 规则等内容,例如,下面的配置文件对默认的 pg-meta 单节点数据库集群的内容进行了深度定制:
包括:声明了六个业务数据库与七个业务用户,添加了一个额外的 standby 服务(同步备库,提供无复制延迟的读取能力),定义了一些额外的 pg_hba 规则,一个指向集群主库的 L2 VIP 地址,与自定义的备份策略。
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role: primary , pg_offline_query : true } }
vars :
pg_cluster : pg-meta
pg_databases : # define business databases on this cluster, array of database definition
- name : meta # REQUIRED, `name` is the only mandatory field of a database definition
baseline : cmdb.sql # optional, database sql baseline path, (relative path among ansible search path, e.g files/)
pgbouncer : true # optional, add this database to pgbouncer database list? true by default
schemas : [ pigsty] # optional, additional schemas to be created, array of schema names
extensions: # optional, additional extensions to be installed : array of `{name[,schema]}`
- { name: postgis , schema : public }
- { name : timescaledb }
comment : pigsty meta database # optional, comment string for this database
owner : postgres # optional, database owner, postgres by default
template : template1 # optional, which template to use, template1 by default
encoding : UTF8 # optional, database encoding, UTF8 by default. (MUST same as template database)
locale : C # optional, database locale, C by default. (MUST same as template database)
lc_collate : C # optional, database collate, C by default. (MUST same as template database)
lc_ctype : C # optional, database ctype, C by default. (MUST same as template database)
tablespace : pg_default # optional, default tablespace, 'pg_default' by default.
allowconn : true # optional, allow connection, true by default. false will disable connect at all
revokeconn : false # optional, revoke public connection privilege. false by default. (leave connect with grant option to owner)
register_datasource : true # optional, register this database to grafana datasources? true by default
connlimit : -1 # optional, database connection limit, default -1 disable limit
pool_auth_user : dbuser_meta # optional, all connection to this pgbouncer database will be authenticated by this user
pool_mode : transaction # optional, pgbouncer pool mode at database level, default transaction
pool_size : 64 # optional, pgbouncer pool size at database level, default 64
pool_reserve : 32 # optional, pgbouncer pool size reserve at database level, default 32
pool_size_min : 0 # optional, pgbouncer pool size min at database level, default 0
pool_connlimit : 100 # optional, max database connections at database level, default 100
- { name: grafana ,owner: dbuser_grafana ,revokeconn: true ,comment : grafana primary database }
- { name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment : bytebase primary database }
- { name: kong ,owner: dbuser_kong ,revokeconn: true ,comment : kong the api gateway database }
- { name: gitea ,owner: dbuser_gitea ,revokeconn: true ,comment : gitea meta database }
- { name: wiki ,owner: dbuser_wiki ,revokeconn: true ,comment : wiki meta database }
pg_users : # define business users/roles on this cluster, array of user definition
- name : dbuser_meta # REQUIRED, `name` is the only mandatory field of a user definition
password : DBUser.Meta # optional, password, can be a scram-sha-256 hash string or plain text
login : true # optional, can log in, true by default (new biz ROLE should be false)
superuser : false # optional, is superuser? false by default
createdb : false # optional, can create database? false by default
createrole : false # optional, can create role? false by default
inherit : true # optional, can this role use inherited privileges? true by default
replication : false # optional, can this role do replication? false by default
bypassrls : false # optional, can this role bypass row level security? false by default
pgbouncer : true # optional, add this user to pgbouncer user-list? false by default (production user should be true explicitly)
connlimit : -1 # optional, user connection limit, default -1 disable limit
expire_in : 3650 # optional, now + n days when this role is expired (OVERWRITE expire_at)
expire_at : '2030-12-31' # optional, YYYY-MM-DD 'timestamp' when this role is expired (OVERWRITTEN by expire_in)
comment : pigsty admin user # optional, comment string for this user/role
roles: [dbrole_admin] # optional, belonged roles. default roles are : dbrole_{admin,readonly,readwrite,offline}
parameters : {} # optional, role level parameters with `ALTER ROLE SET`
pool_mode : transaction # optional, pgbouncer pool mode at user level, transaction by default
pool_connlimit : -1 # optional, max database connections at user level, default -1 disable limit
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly], comment : read-only viewer for meta database}
- {name: dbuser_grafana ,password: DBUser.Grafana ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for grafana database }
- {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for bytebase database }
- {name: dbuser_kong ,password: DBUser.Kong ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for kong api gateway }
- {name: dbuser_gitea ,password: DBUser.Gitea ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for gitea service }
- {name: dbuser_wiki ,password: DBUser.Wiki ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for wiki.js service }
pg_services : # extra services in addition to pg_default_services, array of service definition
# standby service will route {ip|name}:5435 to sync replica's pgbouncer (5435->6432 standby)
- name: standby # required, service name, the actual svc name will be prefixed with `pg_cluster`, e.g : pg-meta-standby
port : 5435 # required, service exposed port (work as kubernetes service node port mode)
ip : "*" # optional, service bind ip address, `*` for all ip by default
selector : "[]" # required, service member selector, use JMESPath to filter inventory
dest : default # optional, destination port, default|postgres|pgbouncer|<port_number>, 'default' by default
check : /sync # optional, health check url path, / by default
backup : "[? pg_role == `primary`]" # backup server selector
maxconn : 3000 # optional, max allowed front-end connection
balance: roundrobin # optional, haproxy load balance algorithm (roundrobin by default, other : 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'
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_vip_interface : eth1
node_crontab : # make a full backup 1 am everyday
- '00 01 * * * postgres /pg/bin/pg-backup full'
声明访问控制 您还可以通过声明式的配置,深度定制 Pigsty 的访问控制能力。例如下面的配置文件对 pg-meta 集群进行了深度安全定制:
使用三节点核心集群模板:crit.yml,确保数据一致性有限,故障切换数据零丢失。
启用了 L2 VIP,并将数据库与连接池的监听地址限制在了本地环回 IP + 内网 IP + VIP 三个特定地址。
模板强制启用了 Patroni 的 SSL API,与 Pgbouncer 的 SSL,并在 HBA 规则中强制要求使用 SSL 访问数据库集群。
同时还在 pg_libs 中启用了 $libdir/passwordcheck 扩展,来强制执行密码强度安全策略。
最后,还单独声明了一个 pg-meta-delay 集群,作为 pg-meta 在一个小时前的延迟镜像从库,用于紧急数据误删恢复。
pg-meta : # 3 instance postgres cluster `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 , pg_offline_query : true }
vars :
pg_cluster : pg-meta
pg_conf : crit.yml
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 for meta database }
pg_databases :
- {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions : [ {name: postgis, schema : public}, {name: timescaledb}]}
pg_default_service_dest : postgres
pg_services :
- { name: standby ,src_ip : "*" ,port: 5435 , dest: default ,selector : "[]" , backup : "[? pg_role == `primary`]" }
pg_vip_enabled : true
pg_vip_address : 10.10.10.2 /24
pg_vip_interface : eth1
pg_listen : '${ip},${vip},${lo}'
patroni_ssl_enabled : true
pgbouncer_sslmode : require
pgbackrest_method : minio
pg_libs : 'timescaledb, $libdir/passwordcheck, pg_stat_statements, auto_explain' # add passwordcheck extension to enforce strong password
pg_default_roles : # default roles and users in postgres cluster
- { name: dbrole_readonly ,login: false ,comment : role for global read-only access }
- { name: dbrole_offline ,login: false ,comment : role for restricted read-only access }
- { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly] ,comment : role for global read-write access }
- { name: dbrole_admin ,login: false ,roles: [pg_monitor, dbrole_readwrite] ,comment : role for object creation }
- { 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 }
pg_default_hba_rules : # postgres host-based auth rules by default
- {user : '${dbsu}' ,db: all ,addr: local ,auth: ident ,title : 'dbsu access via local os user ident' }
- {user : '${dbsu}' ,db: replication ,addr: local ,auth: ident ,title : 'dbsu replication from local os ident' }
- {user : '${repl}' ,db: replication ,addr: localhost ,auth: ssl ,title : 'replicator replication from localhost' }
- {user : '${repl}' ,db: replication ,addr: intra ,auth: ssl ,title : 'replicator replication from intranet' }
- {user : '${repl}' ,db: postgres ,addr: intra ,auth: ssl ,title : 'replicator postgres db from intranet' }
- {user : '${monitor}' ,db: all ,addr: localhost ,auth: pwd ,title : 'monitor from localhost with password' }
- {user : '${monitor}' ,db: all ,addr: infra ,auth: ssl ,title : 'monitor from infra host with password' }
- {user : '${admin}' ,db: all ,addr: infra ,auth: ssl ,title : 'admin @ infra nodes with pwd & ssl' }
- {user : '${admin}' ,db: all ,addr: world ,auth: cert ,title : 'admin @ everywhere with ssl & cert' }
- {user: '+dbrole_readonly',db: all ,addr: localhost ,auth: ssl ,title : 'pgbouncer read/write via local socket' }
- {user: '+dbrole_readonly',db: all ,addr: intra ,auth: ssl ,title : 'read/write biz user via password' }
- {user: '+dbrole_offline' ,db: all ,addr: intra ,auth: ssl ,title : 'allow etl offline tasks from intranet' }
pgb_default_hba_rules : # pgbouncer host-based authentication rules
- {user : '${dbsu}' ,db: pgbouncer ,addr: local ,auth: peer ,title : 'dbsu local admin access with os ident' }
- {user: 'all' ,db: all ,addr: localhost ,auth: pwd ,title : 'allow all user local access with pwd' }
- {user : '${monitor}' ,db: pgbouncer ,addr: intra ,auth: ssl ,title : 'monitor access via intranet with pwd' }
- {user : '${monitor}' ,db: all ,addr: world ,auth: deny ,title : 'reject all other monitor access addr' }
- {user : '${admin}' ,db: all ,addr: intra ,auth: ssl ,title : 'admin access via intranet with pwd' }
- {user : '${admin}' ,db: all ,addr: world ,auth: deny ,title : 'reject all other admin access addr' }
- {user: 'all' ,db: all ,addr: intra ,auth: ssl ,title : 'allow all user intra access with pwd' }
# OPTIONAL delayed cluster for pg-meta
pg-meta-delay : # delayed instance for pg-meta (1 hour ago)
hosts : { 10.10.10.13 : { pg_seq: 1, pg_role: primary, pg_upstream: 10.10.10.10, pg_delay : 1h } }
vars : { pg_cluster : pg-meta-delay }
Citus 分布式集群 下面是一个四节点的 Citus 分布式集群的声明式配置:
all :
children :
pg-citus0 : # citus coordinator, pg_group = 0
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus0 , pg_group : 0 }
pg-citus1 : # citus data node 1
hosts : { 10.10.10.11 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus1 , pg_group : 1 }
pg-citus2 : # citus data node 2
hosts : { 10.10.10.12 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus2 , pg_group : 2 }
pg-citus3 : # citus data node 3, with an extra replica
hosts :
10.10.10.13 : { pg_seq: 1, pg_role : primary }
10.10.10.14 : { pg_seq: 2, pg_role : replica }
vars : { pg_cluster: pg-citus3 , pg_group : 3 }
vars : # global parameters for all citus clusters
pg_mode: citus # pgsql cluster mode : citus
pg_shard: pg-citus # citus shard name : pg-citus
patroni_citus_db : meta # citus distributed database name
pg_dbsu_password : DBUser.Postgres # all dbsu password access for citus cluster
pg_users : [ { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles : [ dbrole_admin ] } ]
pg_databases : [ { name: meta ,extensions : [ { name : citus }, { name: postgis }, { name: timescaledb } ] } ]
pg_hba_rules :
- { user: 'all' ,db: all ,addr: 127.0.0.1/32 ,auth: ssl ,title : 'all user ssl access from localhost' }
- { user: 'all' ,db: all ,addr: intra ,auth: ssl ,title : 'all user ssl access from intranet' }
Redis 集群 下面给出了 Redis 主从集群、哨兵集群、以及 Redis Cluster 的声明配置样例
redis-ms : # redis classic primary & replica
hosts : { 10.10.10.10 : { redis_node: 1 , redis_instances : { 6379 : { }, 6380 : { replica_of : '10.10.10.10 6379' } } } }
vars : { redis_cluster: redis-ms ,redis_password: 'redis.ms' ,redis_max_memory : 64MB }
redis-meta : # redis sentinel x 3
hosts : { 10.10.10.11 : { redis_node: 1 , redis_instances : { 26379 : { } ,26380 : { } ,26381 : { } } } }
vars :
redis_cluster : redis-meta
redis_password : 'redis.meta'
redis_mode : sentinel
redis_max_memory : 16MB
redis_sentinel_monitor : # primary list for redis sentinel, use cls as name, primary ip:port
- { name: redis-ms, host: 10.10.10.10, port: 6379 ,password: redis.ms, quorum : 2 }
redis-test: # redis native cluster : 3m x 3s
hosts :
10.10.10.12 : { redis_node: 1 ,redis_instances : { 6379 : { } ,6380 : { } ,6381 : { } } }
10.10.10.13 : { redis_node: 2 ,redis_instances : { 6379 : { } ,6380 : { } ,6381 : { } } }
vars : { redis_cluster: redis-test ,redis_password: 'redis.test' ,redis_mode: cluster, redis_max_memory : 32MB }
ETCD 集群 下面给出了一个三节点的 Etcd 集群声明式配置样例:
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 } # odd number please
vars : # cluster level parameter override roles/etcd
etcd_cluster : etcd # mark etcd cluster name etcd
etcd_safeguard : false # safeguard against purging
etcd_clean : true # purge etcd during init process
MinIO 集群 下面给出了一个三节点的 MinIO 集群声明式配置样例:
minio :
hosts :
10.10.10.10 : { minio_seq : 1 }
10.10.10.11 : { minio_seq : 2 }
10.10.10.12 : { minio_seq : 3 }
vars :
minio_cluster : minio
minio_data : '/data{1...2}' # 每个节点使用两块磁盘
minio_node : '${minio_cluster}-${minio_seq}.pigsty' # 节点名称的模式
haproxy_services :
- name : minio # [必选] 服务名称,需要唯一
port : 9002 # [必选] 服务端口,需要唯一
options :
- option httpchk
- option http-keep-alive
- http-check send meth OPTIONS uri /minio/health/live
- http-check expect status 200
servers :
- { name: minio-1 ,ip: 10.10.10.10 , port: 9000 , options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
- { name: minio-2 ,ip: 10.10.10.11 , port: 9000 , options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
- { name: minio-3 ,ip: 10.10.10.12 , port: 9000 , options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
3.3.1 - 配置清单 使用声明式的配置文件描述你需要的基础设施与集群
每一套 Pigsty 部署都对应着一份 配置清单 (Inventory),描述了基础设施与数据库集群的关键属性。
配置文件 Pigsty 默认使用 Ansible YAML 配置格式 ,
使用一个单一 YAML 配置文件 pigsty.yml 作为配置清单。
~/pigsty
^---- pigsty.yml # <---- 默认配置文件
您可以直接修改该配置文件来定制您的部署,或者使用 Pigsty 提供的 配置向导 configure 脚本自动生成合适的配置文件。
配置结构 配置清单使用标准的 Ansible YAML 配置格式 ,由两部分组成:全局参数 (all.vars)和多个 组 (all.children)。
您可以在 all.children 中定义新集群,并使用全局变量描述基础设施:all.vars,它看起来像这样:
all : # 顶级对象:all
vars : {...} # 全局参数
children : # 组定义
infra : # 组定义:'infra'
hosts : {...} # 组成员:'infra'
vars : {...} # 组参数:'infra'
etcd : {...} # 组定义:'etcd'
pg-meta : {...} # 组定义:'pg-meta'
pg-test : {...} # 组定义:'pg-test'
redis-test : {...} # 组定义:'redis-test'
# ...
集群定义 每个 Ansible 组可能代表一个集群,可以是节点集群、PostgreSQL 集群、Redis 集群、Etcd 集群或 MinIO 集群等…
集群定义由两部分组成:集群成员 (hosts )与 集群参数 (vars )。
您可以在 <cls>.hosts 中定义集群成员,并在 <cls>.vars 中使用 配置参数 描述集群。
下面是一个 3 节点高可用 PostgreSQL 集群的定义示例:
all :
children : # ansible 组列表
pg-test : # ansible 组名
hosts : # ansible 组内实例(集群成员)
10.10.10.11 : { pg_seq: 1, pg_role : primary } # 主机 1
10.10.10.12 : { pg_seq: 2, pg_role : replica } # 主机 2
10.10.10.13 : { pg_seq: 3, pg_role : offline } # 主机 3
vars : # ansible 组变量(集群参数)
pg_cluster : pg-test
集群级别的 vars (集群参数)将覆盖全局参数,实例级别的 vars 将覆盖集群参数和全局参数。
拆分配置 如果您的部署规模较大,或者希望更好地组织配置文件,
可以将配置清单 拆分为多个文件 ,便于管理与维护。
inventory/
├── hosts.yml # 主机和集群定义
├── group_vars/
│ ├── all.yml # 全局默认变量 (对应 all.vars)
│ ├── infra.yml # infra 组变量
│ ├── etcd.yml # etcd 组变量
│ └── pg-meta.yml # pg-meta 集群变量
└── host_vars/
├── 10.10.10.10.yml # 特定主机变量
└── 10.10.10.11.yml
您可以将集群成员定义放在 hosts.yml 文件中,将集群层面的 配置参数 放在 group_vars 目录下的对应文件中。
切换配置 您可以在执行剧本的时候,通过 -i 参数,临时指定另外的配置清单文件。
./pgsql.yml -i another_config.yml
./infra.yml -i nginx_config.yml
此外,Ansible 支持多种配置方式,您可以使用本地 yaml|ini 配置文件,或者是 CMDB 与任意的动态配置脚本作为配置源。
在 Pigsty 中,我们通过 Pigsty 主目录中的 ansible.cfg
指定同目录下的 pigsty.yml 作为默认的 配置清单 ,您可按需修改。
[defaults]
inventory = pigsty.yml
此外,Pigsty 还支持使用 CMDB 元数据库 来存储配置清单,便于与现有系统对接整合。
3.3.2 - 配置向导 使用 configure 脚本根据当前环境自动生成推荐的配置文件。
Pigsty 提供了一个 configure 脚本作为 配置向导 ,它能根据当前环境,自动生成合适的 pigsty.yml 配置文件。
这是一个 可选 的脚本:如果您已经了解了如何配置 Pigsty,大可以直接编辑 pigsty.yml 配置文件,跳过向导。
快速开始 进入 pigsty 源码家目录中,执行 ./configure 即可自动运行配置向导。不带任何参数时,默认使用 meta 单节点配置模板:
cd ~/pigsty
./configure # 交互式配置向导,自动检测环境并生成配置
该命令会以选定的模板为基础,检测当前节点的 IP 地址与区域,并生成适合当前环境的 pigsty.yml 配置文件。
功能说明 configure 脚本会根据环境与输入执行以下调整,并在当前目录下生成 pigsty.yml 配置文件。
检测当前节点 IP 地址,如果有多个 IP,则要求用户输入一个 首要的 IP 地址 作为当前节点的身份标识 使用 IP 地址替换配置模板中的占位符 10.10.10.10 ,并将其配置为 admin_ip 参数的值。 检测当前区域,将 region 设置为 default (全球默认仓库)或 china (使用中国镜像仓库) 针对小微实例(vCPU < 4),为 node_tune 和 pg_conf 参数使用 tiny 参数模板,优化资源使用。 如果指定了 -v PG 大版本,将 pg_version 以及所有 PG 别名参数设置为对应大版本。 如果指定了 -g 参数,将所有默认密码替换为随机生成的强密码,提升安全性。(强烈推荐 ) 当 PG 大版本 ≥ 17 时优先使用内置的 C.UTF-8 Locale,次选由操作系统支持的 C.UTF-8 。 检测当前环境中,用于执行部署的核心依赖 ansible 是否可用 同时检测部署目标节点是否 ssh 可达,并可以使用 sudo 执行命令。(-s 跳过) 使用示例 # 基本用法
./configure # 交互式配置向导
./configure -i 10.10.10.10 # 指定主 IP 地址
# 指定配置模板
./configure -c meta # 使用默认单节点模板(默认)
./configure -c rich # 使用功能丰富的单节点模板
./configure -c slim # 使用精简模板(仅 PGSQL + ETCD)
./configure -c ha/full # 使用 4 节点高可用沙箱模板
./configure -c ha/trio # 使用 3 节点高可用模板
./configure -c app/supa # 使用 Supabase 自托管模板
# 指定 PostgreSQL 版本
./configure -v 18 # 使用 PostgreSQL 18(默认)
./configure -v 16 # 使用 PostgreSQL 16
./configure -c rich -v 15 # rich 模板 + PG 15
# 区域与代理
./configure -r china # 使用中国镜像源
./configure -r europe # 使用欧洲镜像源
./configure -x # 导入当前代理环境变量
# 跳过与自动化
./configure -s # 跳过 IP 探测,保留占位符
./configure -n -i 10.10.10.10 # 非交互模式,指定 IP
./configure -c ha/full -s # 4 节点模板,跳过 IP 替换
# 安全增强
./configure -g # 生成随机密码
./configure -c meta -g -i 10.10.10.10 # 完整生产配置
# 指定输出与 SSH 端口
./configure -o prod.yml # 输出到 prod.yml
./configure -p 2222 # 使用 SSH 端口 2222
命令参数 ./configure
[ -c| --conf <template>] # 配置模板名称(meta|rich|slim|ha/full|...)
[ -i| --ip <ipaddr>] # 指定主 IP 地址
[ -v| --version <pgver>] # PostgreSQL 大版本号(14|15|16|17|18)
[ -r| --region <region>] # 上游软件仓库区域(default|china|europe)
[ -o| --output <file>] # 输出配置文件路径(默认:pigsty.yml)
[ -s| --skip] # 跳过 IP 地址探测与替换
[ -x| --proxy] # 从环境变量导入代理设置
[ -n| --non-interactive] # 非交互模式(不询问任何问题)
[ -p| --port <port>] # 指定 SSH 端口
[ -g| --generate] # 生成随机密码
[ -h| --help] # 显示帮助信息
参数详解 参数 说明 -c, --conf从 conf/<template>.yml 生成配置文件,支持子目录如 ha/full -i, --ip用指定 IP 替换配置模板中的占位符 10.10.10.10 -v, --version指定 PostgreSQL 大版本号(14-18),不指定时保持模板默认值 -r, --region设置软件仓库镜像区域:default(默认)、china(中国镜像)、europe(欧洲镜像) -o, --output指定输出文件路径,默认为 pigsty.yml -s, --skip跳过 IP 地址探测与替换,保留模板中的 10.10.10.10 占位符 -x, --proxy将当前环境的代理变量(HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY)写入配置 -n, --non-interactive非交互模式,不询问任何问题(需配合 -i 指定 IP) -p, --port指定 SSH 端口(非默认 22 端口时使用) -g, --generate为配置文件中的密码生成随机值,提高安全性(强烈推荐)
执行流程 configure 脚本按照以下顺序执行检测与配置:
┌─────────────────────────────────────────────────────────────┐
│ configure 执行流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. check_region 检测网络区域(GFW 检测) │
│ ↓ │
│ 2. check_version 验证 PostgreSQL 版本号 │
│ ↓ │
│ 3. check_kernel 检测操作系统内核(Linux/Darwin) │
│ ↓ │
│ 4. check_machine 检测 CPU 架构(x86_64/aarch64) │
│ ↓ │
│ 5. check_package_manager 检测包管理器(dnf/yum/apt) │
│ ↓ │
│ 6. check_vendor_version 检测 OS 发行版与版本 │
│ ↓ │
│ 7. check_sudo 检测免密 sudo 权限 │
│ ↓ │
│ 8. check_ssh 检测免密 SSH 到本机 │
│ ↓ │
│ 9. check_proxy 处理代理环境变量 │
│ ↓ │
│ 10. check_ipaddr 探测/输入主 IP 地址 │
│ ↓ │
│ 11. check_admin 验证管理员 SSH + Sudo 权限 │
│ ↓ │
│ 12. check_conf 选择配置模板 │
│ ↓ │
│ 13. check_config 生成配置文件 │
│ ↓ │
│ 14. check_utils 检测 Ansible 等工具是否安装 │
│ ↓ │
│ ✓ 配置完成,输出 pigsty.yml │
│ │
└─────────────────────────────────────────────────────────────┘
自动化行为 区域检测 脚本会自动检测网络环境,判断是否在中国大陆(GFW 内):
# 通过访问 Google 判断网络环境
curl -I -s --connect-timeout 1 www.google.com
如果无法访问 Google,自动设置 region: china 使用国内镜像 如果可以访问,使用 region: default 默认镜像 可通过 -r 参数手动指定区域 IP 地址处理 脚本按以下优先级确定主 IP 地址:
命令行参数 :如果通过 -i 指定了 IP,直接使用单 IP 探测 :如果当前节点只有一个 IP,自动使用演示 IP 检测 :如果检测到 10.10.10.10,自动选择(用于沙箱环境)交互式输入 :多个 IP 时,提示用户选择或输入[ WARN] Multiple IP address candidates found:
( 1) 192.168.1.100 inet 192.168.1.100/24 scope global eth0
( 2) 10.10.10.10 inet 10.10.10.10/24 scope global eth1
[ IN ] INPUT primary_ip address ( of current meta node, e.g 10.10.10.10) :
= > 10.10.10.10
低端硬件优化 当检测到 CPU 核心数 ≤ 4 时,脚本会自动调整配置:
[ WARN] replace oltp template with tiny due to cpu < 4
这样可以确保在低配虚拟机上也能顺利运行。
Locale 设置 脚本会在以下情况自动启用 C.UTF-8 作为默认 Locale:
PostgreSQL 版本 ≥ 17(内置 Locale Provider 支持) 或者 当前系统支持 C.UTF-8 / C.utf8 Localepg_locale : C.UTF-8
pg_lc_collate : C.UTF-8
pg_lc_ctype : C.UTF-8
中国区特殊处理 当区域设置为 china 时,脚本会自动:
启用 docker_registry_mirrors Docker 镜像加速 启用 PIP_MIRROR_URL Python 镜像加速 密码生成 使用 -g 参数时,脚本会为以下密码生成 24 位随机字符串:
密码参数 说明 grafana_admin_passwordGrafana 管理员密码 pg_admin_passwordPostgreSQL 管理员密码 pg_monitor_passwordPostgreSQL 监控用户密码 pg_replication_passwordPostgreSQL 复制用户密码 patroni_passwordPatroni API 密码 haproxy_admin_passwordHAProxy 管理密码 minio_secret_keyMinIO Secret Key etcd_root_passwordETCD Root 密码
同时还会替换以下占位符密码:
DBUser.Meta → 随机密码DBUser.Viewer → 随机密码S3User.Backup → 随机密码S3User.Meta → 随机密码S3User.Data → 随机密码$ ./configure -g
[ INFO] generating random passwords...
grafana_admin_password : xK9mL2nP4qR7sT1vW3yZ5bD8
pg_admin_password : aB3cD5eF7gH9iJ1kL2mN4oP6
...
[ INFO] random passwords generated, check and save them
配置模板 脚本从 conf/ 目录读取配置模板,支持以下模板:
核心模板 模板 说明 meta默认模板 :单节点安装,包含 INFRA + NODE + ETCD + PGSQLrich功能丰富版:包含几乎所有扩展、MinIO、本地仓库 slim精简版:仅 PostgreSQL + ETCD,无监控基础设施 fat完整版:rich 基础上安装更多扩展 pgsql纯 PostgreSQL 模板 infra纯基础设施模板
高可用模板 (ha/) 模板 说明 ha/dual2 节点高可用集群 ha/trio3 节点高可用集群 ha/full4 节点完整沙箱环境 ha/safe安全加固版高可用配置 ha/simu42 节点大规模仿真环境
应用模板 (app/) 模板 说明 supabaseSupabase 自托管配置 app/difyDify AI 平台配置 app/odooOdoo ERP 配置 app/teableTeable 表格数据库配置 app/registryDocker Registry 配置
特殊内核模板/模式 模板 说明 ivoryIvorySQL:Oracle 兼容 PostgreSQL mssqlBabelfish:SQL Server 兼容 PostgreSQL polarPolarDB:阿里云开源分布式 PostgreSQL citusCitus:分布式 PostgreSQL orioleOrioleDB:新一代存储引擎
演示模板 (demo/) 模板 说明 demo/demo演示环境配置 demo/redisRedis 集群演示 demo/minioMinIO 集群演示
输出示例 $ ./configure
configure pigsty v4.0.0 begin
[ OK ] region = china
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] package = rpm,dnf
[ OK ] vendor = rocky ( Rocky Linux)
[ OK ] version = 9 ( 9.5)
[ OK ] sudo = vagrant ok
[ OK ] ssh = vagrant@127.0.0.1 ok
[ WARN] Multiple IP address candidates found:
( 1) 192.168.121.193 inet 192.168.121.193/24 brd 192.168.121.255 scope global dynamic noprefixroute 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
[ OK ] mode = meta ( el9)
[ 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
环境变量 脚本支持以下环境变量:
环境变量 说明 默认值 PIGSTY_HOMEPigsty 安装目录 ~/pigstyMETADB_URL元数据库连接 URL service=metaHTTP_PROXYHTTP 代理 - HTTPS_PROXYHTTPS 代理 - ALL_PROXY通用代理 - NO_PROXY代理白名单 内置默认值
注意事项 免密访问 :运行 configure 前,确保当前用户具有免密 sudo 权限和免密 SSH 到本机的能力。可以通过 bootstrap 脚本自动配置。
IP 地址选择 :请选择内网 IP 作为主 IP 地址,不要使用公网 IP 或 127.0.0.1。
密码安全 :生产环境务必 修改配置文件中的默认密码,或使用 -g 参数生成随机密码。
配置检查 :脚本执行完成后,建议检查生成的 pigsty.yml 文件,确认配置符合预期。
多次执行 :可以多次运行 configure 重新生成配置,每次会覆盖现有的 pigsty.yml。
macOS 限制 :在 macOS 上运行时,脚本会跳过部分 Linux 特有的检测,并使用占位符 IP 10.10.10.10。macOS 只能作为管理节点使用。
常见问题 如何使用自定义配置模板? 将您的配置文件放到 conf/ 目录下,然后使用 -c 参数指定:
cp my-config.yml ~/pigsty/conf/myconf.yml
./configure -c myconf
如何为多集群生成不同配置? 使用 -o 参数指定不同的输出文件:
./configure -c ha/full -o cluster-a.yml
./configure -c ha/trio -o cluster-b.yml
然后在执行剧本时指定配置文件:
./deploy.yml -i cluster-a.yml
非交互模式下如何处理多 IP? 必须使用 -i 参数明确指定 IP 地址:
./configure -n -i 10.10.10.10
如何保留模板中的占位符 IP? 使用 -s 参数跳过 IP 替换:
./configure -c ha/full -s # 保留 10.10.10.10 占位符
相关文档 配置清单 :了解 Ansible 配置清单的结构配置参数 :了解 Pigsty 参数的层级与优先级配置模板 :查看所有可用的配置模板安装部署 :了解完整的安装流程元数据库 :使用 PostgreSQL 作为动态配置源3.3.3 - 配置参数 使用配置参数对 Pigsty 进行精细化定制
在 配置清单 中,您可以使用各种参数对 Pigsty 进行精细化定制。这些参数涵盖了从基础设施设置到数据库配置的各个方面。
参数列表 Pigsty 提供了约 380+ 个配置参数,分布在 8 个默认模块中,用于精细控制系统的各个方面,完整列表见 参考-参数列表 。
模块 参数组 参数数 说明 PGSQL 9 123 PostgreSQL 数据库集群的核心配置 INFRA 10 82 基础设施组件:软件源、Nginx、DNS、监控、Grafana 等 NODE 11 83 主机节点调优:身份、DNS、包、调优、安全、管理员、时间、VIP 等 ETCD 2 13 分布式配置存储与服务发现 REDIS 1 21 Redis 缓存与数据结构服务器 MINIO 2 21 S3 兼容对象存储服务 FERRET 1 9 MongoDB 兼容数据库 FerretDB DOCKER 1 8 Docker 容器引擎
参数形式 参数 是用于描述实体的 键值对 。键 (Key)是字符串,值 (Value)可以是五种类型之一:布尔值、字符串、数字、数组或对象。
all : # <------- 顶级对象:all
vars :
admin_ip : 10.10.10.10 # <------- 全局配置参数
children :
pg-meta : # <------- pg-meta 分组
vars :
pg_cluster : pg-meta # <------- 集群级别参数
hosts :
10.10.10.10 : # <------- 主机节点 IP
pg_seq : 1
pg_role : primary # <------- 实例级别参数
参数优先级 参数可以在不同级别设置,具有以下优先级:
级别 位置 描述 优先级 命令行 -e 命令行参数通过命令行传入 最高 (5) 主机/实例 <group>.hosts.<host>特定于单个主机的参数 较高 (4) 分组/集群 <group>.vars组/集群中主机共享的参数 中等 (3) 全局 all.vars所有主机共享的参数 较低 (2) 默认 <roles>/default/main.yml角色实现默认值 最低 (1)
以下是关于参数优先级的一些示例:
执行剧本时,使用命令行参数 -e grafana_clean=true 来抹除 Grafana 数据 使用主机变量上的实例级别参数 pg_role 覆盖 pg 实例角色 使用组变量上的集群级别参数 pg_cluster 覆盖 pg 集群名称。 使用全局变量上的全局参数 node_ntp_servers 指定全局 NTP 服务器 如果没有设置 pg_version ,Pigsty 将使用 pgsql 角色实现的默认值(默认为 18) 除了身份参数 外,每个参数都有适当的默认值,因此无需显式设置。
身份参数 身份参数是特殊的参数,它们会作为实体的 ID 标识符,因此 没有默认值 ,必须 显式设置 。
模块 身份参数 PGSQLpg_cluster, pg_seq, pg_role, …NODEnodename, node_clusterETCDetcd_cluster, etcd_seqMINIOminio_cluster, minio_seqREDISredis_cluster, redis_node, redis_instancesINFRAinfra_seq
例外是,etcd_cluster 与 minio_cluster 有默认值。
它假设每套部署只有一套 etcd 集群用于 DCS,和一套可选 MinIO 集群用于集中备份存储,因此为其分配了默认的集群名称 etcd 与 minio。
但您依然可以使用其他名称部署多套 etcd 或 MinIO 集群。
3.3.4 - 配置模板 使用预制的配置模板,快速生成适配当前环境的配置文件
在 Pigsty 中,部署的蓝图细节由 配置清单 所定义,也就是 pigsty.yml 配置文件,您可以通过声明式配置进行定制。
然而,直接编写配置文件可能会让新用户望而生畏。为此,我们提供了一些开箱即用的配置模板,涵盖了常见的使用场景。
每一个模板都是一个预定义的 pigsty.yml 配置文件,包含了适用于特定场景的合理默认值。
您可以根据自己的需要,选择一个模板作为定制起点,然后根据需要进行修改,以满足您的具体需求。
使用模板 Pigsty 提供了 configure 脚本作为可选的配置向导,它将根据您的环境和输入,生成具有良好默认值的 配置清单 。
使用 ./configure -c <conf> 指定配置模板,其中 <conf> 是相对于 conf 目录的路径(可省略 .yml 后缀)。
./configure # 默认使用 meta.yml 配置模板
./configure -c meta # 显式指定使用 meta.yml 单节点模板
./configure -c rich # 使用包含全部扩展与 MinIO 的富功能模板
./configure -c slim # 使用最小化的单节点模板
# 使用不同的数据库内核
./configure -c pgsql # 原生 PostgreSQL 内核,基础功能 (14~18)
./configure -c citus # Citus 分布式高可用 PostgreSQL (14~17)
./configure -c mssql # Babelfish 内核,兼容 SQL Server 协议 (17)
./configure -c polar # PolarDB PG 内核,Aurora/RAC 风格 (17)
./configure -c ivory # IvorySQL 内核,兼容 Oracle 语法 (18)
./configure -c mysql # OpenHalo 内核,兼容 MySQL (14)
./configure -c pgtde # Percona PostgreSQL Server 透明加密 (18)
./configure -c oriole # OrioleDB 内核,OLTP 增强 (17)
./configure -c supabase # Supabase 自托管配置 (15~18)
# 使用多节点高可用模板
./configure -c ha/dual # 使用 2 节点高可用模板
./configure -c ha/trio # 使用 3 节点高可用模板
./configure -c ha/full # 使用 4 节点高可用模板
如果不指定模板,Pigsty 默认使用 meta.yml 单节点配置模板。
模板列表 主要模板 以下是单节点配置模板,可用于在单台服务器上安装 Pigsty:
数据库内核模板 适用于各类数据库管理系统与内核的模板:
您可以后续添加更多节点,或使用 高可用模板 在一开始就规划好集群。
高可用模板 您可以配置 Pigsty 在多节点上运行,组成高可用(HA)集群:
应用模板 您可以使用以下模板运行 Docker 应用/软件:
演示模板 除主要模板外,Pigsty 还提供了一组面向不同场景的演示模板:
构建模板 以下配置模板用于开发和测试目的:
模板 说明 build.ymlEL 9/10、Debian 12/13、Ubuntu 22.04/24.04/26.04 开源构建配置
3.3.5 - 元数据库 使用 PostgreSQL 作为 CMDB 元数据库,存储 Ansible 配置清单。
Pigsty 允许您使用 PostgreSQL 元数据库 作为动态配置源,取代静态的 YAML 配置文件,实现更强大的配置管理能力。
概览 CMDB (Configuration Management Database,配置管理数据库)是一种将配置信息存储在数据库中进行管理的方式。
在 Pigsty 中,默认的配置源是一个静态 YAML 文件 pigsty.yml,
它作为 Ansible 的 配置清单 使用。
这种方式简单直接,但当基础设施规模扩大、需要复杂精细的管理与外部集成时,单一的静态文件难以满足需求。
特性 静态 YAML 文件 CMDB 元数据库 查询能力 手工搜索/grep SQL 任意条件查询,聚合分析 版本控制 依赖 Git 或手工备份 数据库事务,审计日志,时间旅行快照 权限控制 文件系统权限,粗粒度 PostgreSQL 数据库精细访问控制 并发编辑 需要锁文件或合并冲突 数据库事务天然支持并发 外部集成 需要解析 YAML 标准 SQL 接口,任意语言轻松对接 规模扩展 文件过大时难以维护 管理规模伸缩至物理极限 动态生成 静态文件,修改后需手动应用 即时生效,实时反映配置变更
Pigsty 在样板数据库 pg-meta.meta 的模式基线定义中,提供了 Pigsty CMDB 的数据库模式。
工作原理 CMDB 的核心思想是用一个 动态脚本 替换静态配置文件。
Ansible 支持使用可执行脚本作为配置清单,只要脚本输出符合 JSON 格式的清单数据即可。
当您启用 CMDB 后,Pigsty 会创建一个名为 inventory.sh 的动态清单脚本:
#!/bin/bash
psql ${ METADB_URL } -AXtwc 'SELECT text FROM pigsty.inventory;'
这个脚本的作用很简单:每次 Ansible 需要读取配置清单时,它会从 PostgreSQL 数据库的 pigsty.inventory 视图中查询配置数据,并以 JSON 格式返回。
整体架构如下:
flowchart LR
conf["bin/inventory_conf"]
tocmdb["bin/inventory_cmdb"]
load["bin/inventory_load"]
ansible["🚀 Ansible"]
subgraph static["📄 静态配置模式"]
yml[("pigsty.yml")]
end
subgraph dynamic["🗄️ CMDB 动态模式"]
sh["inventory.sh"]
cmdb[("PostgreSQL CMDB")]
end
conf -->|"切换"| yml
yml -->|"加载配置"| load
load -->|"写入"| cmdb
tocmdb -->|"切换"| sh
sh --> cmdb
yml --> ansible
cmdb --> ansible 数据模型 CMDB 的数据库模式定义在 files/cmdb.sql 文件中,所有对象都位于 pigsty 模式下。
核心数据表 表名 说明 主键 pigsty.group集群/分组定义,对应 Ansible 的 group clspigsty.host主机定义,属于某个分组 (cls, ip)pigsty.global_var全局变量,对应 all.vars keypigsty.group_var分组变量,对应 all.children.<cls>.vars (cls, key)pigsty.host_var主机变量,对应主机级别的变量 (cls, ip, key)pigsty.default_var默认变量定义,存储参数的元信息 keypigsty.job作业记录表,记录执行的任务 id
表结构详解 集群表 pigsty.group
CREATE TABLE pigsty . group (
cls TEXT PRIMARY KEY , -- 集群名称,主键
ctime TIMESTAMPTZ DEFAULT now (), -- 创建时间
mtime TIMESTAMPTZ DEFAULT now () -- 修改时间
);
主机表 pigsty.host
CREATE TABLE pigsty . host (
cls TEXT NOT NULL REFERENCES pigsty . group ( cls ), -- 所属集群
ip INET NOT NULL , -- 主机 IP 地址
ctime TIMESTAMPTZ DEFAULT now (),
mtime TIMESTAMPTZ DEFAULT now (),
PRIMARY KEY ( cls , ip )
);
全局变量表 pigsty.global_var
CREATE TABLE pigsty . global_var (
key TEXT PRIMARY KEY , -- 变量名
value JSONB NULL , -- 变量值(JSON 格式)
mtime TIMESTAMPTZ DEFAULT now () -- 修改时间
);
分组变量表 pigsty.group_var
CREATE TABLE pigsty . group_var (
cls TEXT NOT NULL REFERENCES pigsty . group ( cls ),
key TEXT NOT NULL ,
value JSONB NULL ,
mtime TIMESTAMPTZ DEFAULT now (),
PRIMARY KEY ( cls , key )
);
主机变量表 pigsty.host_var
CREATE TABLE pigsty . host_var (
cls TEXT NOT NULL ,
ip INET NOT NULL ,
key TEXT NOT NULL ,
value JSONB NULL ,
mtime TIMESTAMPTZ DEFAULT now (),
PRIMARY KEY ( cls , ip , key ),
FOREIGN KEY ( cls , ip ) REFERENCES pigsty . host ( cls , ip )
);
核心视图 CMDB 提供了一系列视图,用于查询和展示配置数据:
视图名 说明 pigsty.inventory核心视图 :生成 Ansible 动态清单 JSONpigsty.raw_config原始配置的 JSON 格式展示 pigsty.global_config全局配置视图,合并默认值和全局变量 pigsty.group_config分组配置视图,包含主机列表和分组变量 pigsty.host_config主机配置视图,合并分组和主机级别变量 pigsty.pg_clusterPostgreSQL 集群视图 pigsty.pg_instancePostgreSQL 实例视图 pigsty.pg_databasePostgreSQL 数据库定义视图 pigsty.pg_usersPostgreSQL 用户定义视图 pigsty.pg_servicePostgreSQL 服务定义视图 pigsty.pg_hbaPostgreSQL HBA 规则视图 pigsty.pg_remote远程 PostgreSQL 实例视图
pigsty.inventory 是最核心的视图,它将数据库中的配置数据转换为 Ansible 所需的 JSON 格式:
SELECT text FROM pigsty . inventory ;
工具脚本 Pigsty 提供了三个便利脚本来管理 CMDB:
inventory_load 将 YAML 配置文件解析并导入到 CMDB 中:
bin/inventory_load # 加载默认的 pigsty.yml 到默认 CMDB
bin/inventory_load -p /path/to/conf.yml # 指定配置文件路径
bin/inventory_load -d "postgres://..." # 指定数据库连接 URL
bin/inventory_load -n myconfig # 指定配置名称
脚本会执行以下操作:
清空 pigsty 模式中的现有数据 解析 YAML 配置文件 将全局变量写入 global_var 表 将集群定义写入 group 表 将集群变量写入 group_var 表 将主机定义写入 host 表 将主机变量写入 host_var 表 环境变量
PIGSTY_HOME:Pigsty 安装目录,默认为 ~/pigstyMETADB_URL:数据库连接 URL,默认为 service=metainventory_cmdb 切换 Ansible 使用 CMDB 作为配置源:
脚本会执行以下操作:
创建动态清单脚本 ${PIGSTY_HOME}/inventory.sh 修改 ansible.cfg 将 inventory 设置为 inventory.sh 生成的 inventory.sh 内容如下:
#!/bin/bash
psql ${ METADB_URL } -AXtwc 'SELECT text FROM pigsty.inventory;'
inventory_conf 切换回使用静态 YAML 配置文件:
脚本会修改 ansible.cfg 将 inventory 设置回 pigsty.yml。
使用流程 首次启用 CMDB 初始化 CMDB 模式 (通常在安装 Pigsty 时已自动完成):psql -f ~/pigsty/files/cmdb.sql
加载配置到数据库 :切换到 CMDB 模式 :验证配置 :ansible all --list-hosts # 列出所有主机
ansible-inventory --list # 查看完整清单
查询配置 启用 CMDB 后,您可以使用 SQL 灵活查询配置:
-- 查看所有集群
SELECT cls FROM pigsty . group ;
-- 查看某集群的所有主机
SELECT ip FROM pigsty . host WHERE cls = 'pg-meta' ;
-- 查看全局变量
SELECT key , value FROM pigsty . global_var ;
-- 查看某集群的变量
SELECT key , value FROM pigsty . group_var WHERE cls = 'pg-meta' ;
-- 查看所有 PostgreSQL 集群
SELECT cls , name , pg_databases , pg_users FROM pigsty . pg_cluster ;
-- 查看所有 PostgreSQL 实例
SELECT cls , ins , ip , seq , role FROM pigsty . pg_instance ;
-- 查看所有数据库定义
SELECT cls , datname , owner , encoding FROM pigsty . pg_database ;
-- 查看所有用户定义
SELECT cls , name , login , superuser FROM pigsty . pg_users ;
修改配置 您可以直接通过 SQL 修改配置:
-- 添加新集群
INSERT INTO pigsty . group ( cls ) VALUES ( 'pg-new' );
-- 添加集群变量
INSERT INTO pigsty . group_var ( cls , key , value )
VALUES ( 'pg-new' , 'pg_cluster' , '"pg-new"' );
-- 添加主机
INSERT INTO pigsty . host ( cls , ip ) VALUES ( 'pg-new' , '10.10.10.20' );
-- 添加主机变量
INSERT INTO pigsty . host_var ( cls , ip , key , value )
VALUES ( 'pg-new' , '10.10.10.20' , 'pg_seq' , '1' ),
( 'pg-new' , '10.10.10.20' , 'pg_role' , '"primary"' );
-- 修改全局变量
UPDATE pigsty . global_var SET value = '"new-value"' WHERE key = 'some_param' ;
-- 删除集群(级联删除主机和变量)
DELETE FROM pigsty . group WHERE cls = 'pg-old' ;
修改后立即生效,无需重新加载或重启任何服务。
切换回静态配置 如需切换回静态配置文件模式:
高级用法 配置导出 将 CMDB 中的配置导出为 YAML 格式:
psql service = meta -AXtwc "SELECT jsonb_pretty(jsonb_build_object('all', jsonb_build_object('children', children, 'vars', vars))) FROM pigsty.raw_config;"
或者使用 ansible-inventory 命令:
ansible-inventory --list --yaml > exported_config.yml
配置审计 利用 mtime 字段追踪配置变更:
-- 查看最近修改的全局变量
SELECT key , value , mtime FROM pigsty . global_var
ORDER BY mtime DESC LIMIT 10 ;
-- 查看某时间点之后的变更
SELECT * FROM pigsty . group_var
WHERE mtime > '2024-01-01' :: timestamptz ;
与外部系统集成 CMDB 使用标准 PostgreSQL,可以轻松与其他系统集成:
Web 管理界面 :通过 REST API(如 PostgREST)暴露配置数据CI/CD 流水线 :在部署脚本中直接读写数据库监控告警 :基于配置数据生成监控规则ITSM 系统 :与企业 CMDB 系统同步注意事项 数据一致性 :修改配置后,需要重新执行相应的 Ansible 剧本才能将变更应用到实际环境
备份 :CMDB 中的配置数据非常重要,请确保定期备份
权限 :建议为 CMDB 配置适当的数据库访问权限,避免误操作
事务 :批量修改配置时,建议在事务中进行,以便出错时回滚
连接池 :inventory.sh 脚本每次执行都会建立新连接,如果 Ansible 执行频繁,建议考虑使用连接池
小结 CMDB 是 Pigsty 配置管理的高级方案,适用于需要管理大量集群、复杂查询、外部集成或精细权限控制的场景。通过将配置数据存储在 PostgreSQL 中,您可以充分利用数据库的强大能力来管理基础设施配置。
功能 说明 数据存储 PostgreSQL pigsty 模式 动态清单 inventory.sh 脚本配置加载 bin/inventory_load切换到 CMDB bin/inventory_cmdb切换到 YAML bin/inventory_conf核心视图 pigsty.inventory
3.4 - PG 高可用 Pigsty 使用 Patroni 实现了 PostgreSQL 的高可用,确保主库不可用时自动进行故障转移,由从库接管。
概览 Pigsty 的 PostgreSQL 集群带有开箱即用的高可用方案,由 Patroni 、Etcd 和 HAProxy 强力驱动。
当您的 PostgreSQL 集群含有两个或更多实例时,您无需任何配置即拥有了硬件故障自愈的数据库高可用能力 —— 只要集群中有任意实例存活,集群就可以对外提供完整的服务,而客户端只要连接至集群中的任意节点,即可获得完整的服务,而无需关心主从拓扑变化。
在默认配置下,主库故障恢复时间目标 RTO ≈ 45s,数据恢复点目标 RPO < 1MB;从库故障 RPO = 0,RTO ≈ 0 (闪断);在一致性优先模式下,可确保故障切换数据零损失:
RPO = 0。以上指标均可通过参数,根据您的实际硬件条件与可靠性要求 按需配置 。
Pigsty 内置了 HAProxy 负载均衡器用于自动流量切换,提供 DNS/VIP/LVS 等多种接入方式供客户端选用。故障切换与主动切换对业务侧除零星闪断外几乎无感知,应用不需要修改连接串重启。
极小的维护窗口需求带来了极大的灵活便利:您完全可以在无需应用配合的情况下滚动维护升级整个集群。硬件故障可以等到第二天再抽空善后处置的特性,让研发,运维与 DBA 都能在故障时安心睡个好觉。
许多大型组织与核心机构已经在生产环境中长时间使用 Pigsty,最大的部署有 25K CPU 核心与 220+ PostgreSQL 超大规格实例(64c / 512g / 3TB NVMe SSD);在这一部署案例中,五年内经历了数十次硬件故障与各类事故,但依然可以保持高于 99.999% 的总体可用性战绩。
高可用(High-Availability)解决什么问题?
将数据安全 C/IA 中的可用性提高到一个新高度:RPO ≈ 0, RTO < 45s。 获得无缝滚动维护的能力,最小化维护窗口需求,带来极大便利。 硬件故障可以立即自愈,无需人工介入,运维 DBA 可以睡个好觉。 从库可以用于承载只读请求,分担主库负载,让资源得以充分利用。 高可用有什么代价?
基础设施依赖:高可用需要依赖 DCS (etcd/zk/consul) 提供共识。 起步门槛增加:一个有意义的高可用部署环境至少需要 三个节点 。 额外的资源消耗:一个新从库就要消耗一份额外资源,不算大问题。 复杂度代价显著升高:备份成本显著加大,需要使用工具压制复杂度。 高可用的局限性
因为复制实时进⾏,所有变更被⽴即应⽤⾄从库。因此基于流复制的高可用方案⽆法应对⼈为错误与软件缺陷导致的数据误删误改。(例如:DROP TABLE,或 DELETE 数据)
此类故障需要使用 延迟集群 ,或使用先前的基础备份与 WAL 归档进行 时间点恢复 。
配置策略 RTO RPO 单机 + 什么也不做 数据永久丢失,无法恢复 数据全部丢失 单机 + 基础备份 取决于备份大小与带宽(几小时) 丢失上一次备份后的数据(几个小时到几天)单机 + 基础备份 + WAL 归档 取决于备份大小与带宽(几小时) 丢失最后尚未归档的数据(几十 MB)主从 + 手工故障切换 十分钟 丢失复制延迟中的数据(约百 KB)主从 + 自动故障切换 一分钟内 丢失复制延迟中的数据(约百 KB)主从 + 自动故障切换 + 同步提交 一分钟内 无数据丢失
原理 在 Pigsty 中,高可用架构的实现原理如下:
PostgreSQL 使⽤标准流复制搭建物理从库,主库故障时由从库接管。 Patroni 负责管理 PostgreSQL 服务器进程,处理高可用相关事宜。 Etcd 提供分布式配置存储(DCS)能力,并用于故障后的领导者选举 Patroni 依赖 Etcd 达成集群领导者共识,并对外提供健康检查接口。 HAProxy 对外暴露集群服务,并利⽤ Patroni 健康检查接口,自动分发流量至健康节点。 vip-manager 提供一个可选的二层 VIP,从 Etcd 中获取领导者信息,并将 VIP 绑定在集群主库所在节点上。 当主库故障时,将触发新一轮领导者竞选,集群中最为健康的从库将胜出(LSN 位点最高,数据损失最小者),并被提升为新的主库。 胜选从库提升后,读写流量将立即路由至新的主库。
主库故障影响是 写服务短暂不可用 :从主库故障到新主库提升期间,写入请求将被阻塞或直接失败,不可用时长通常在 15秒 ~ 30秒,通常不会超过 1 分钟。
当从库故障时,只读流量将路由至其他从库,如果所有从库都故障,只读流量才会最终由主库承载。
从库故障的影响是 部分只读查询闪断 :当前从库上正在运行查询将由于连接重置而中止,并立即由其他可用从库接管。
故障检测由 Patroni 和 Etcd 共同完成,集群领导者将持有一个租约,
如果集群领导者因为故障而没有及时续租(10s),租约将会被释放,并触发 故障切换 (Failover) 与新一轮集群选举。
即使没有出现任何故障,您依然可以主动通过 主动切换 (Switchover)变更集群的主库。
在这种情况下,主库上的写入查询将会闪断,并立即路由至新主库执行。这一操作通常可用于滚动维护/升级数据库服务器。
3.4.1 - RPO 利弊权衡 针对 RPO (Recovery Point Objective)进行利弊权衡,在可用性与数据损失之间找到最佳平衡点。
RPO (Recovery Point Objective,恢复点目标)定义了在主库发生故障时,允许丢失的最大数据量 。
对于金融交易这类数据完整性至关重要的场景,通常要求 RPO = 0,即不允许任何数据丢失;
然而更为严格的 RPO 指标是有代价的,它会引入更高的写入延迟,降低系统吞吐量,并且存在从库故障导致主库不可用的风险。
因此对于常规场景,通常可以接受一定量的数据丢失(例如允许丢失不超过 1MB 的数据),以换取更高的可用性与性能。
利弊权衡 通常在异步复制场景下,从库和主库之间会存在一定的复制延迟(取决于网络和吞吐量,正常在 10KB-100KB / 100µs-10ms 的数量级),
这意味着当主库发生故障时,从库可能还没有完全同步主库的最新数据。这时候如果出现故障切换,新的主库可能会丢失一些尚未复制的数据。
潜在数据丢失量的上限由 pg_rpo 参数控制,默认为 1048576 (1MB),这意味着在故障转移期间最多可以容忍 1MiB 的数据丢失。
当集群主库宕机时,如果有任何一个从库的复制延迟在这个值以内,Pigsty 将自动提升该从库为新的主库。
然而当所有从库副本的复制延迟都超出这个阈值时,Pigsty 将拒绝进行 [自动故障切换 ] 以避免数据丢失。
此时需要人工介入进行决策 —— 等待主库恢复(可能永远也不会恢复),还是接受数据损失并强制提升一个从库为新的主库。
您需要根据业务的需求偏好配置这个值,在 可用性 和 一致性 之间进行 利弊权衡 。
增大这个值可以提高自动故障切换的成功率,但也会增加潜在的数据丢失量上限。
当您指定 pg_rpo = 0 时,Pigsty 将启用 同步复制 ,确保主库在确认至少一个从库持久化数据后才返回写入成功。
这种配置能确保没有复制延迟,但会带来显著的写入延迟,并降低整体的吞吐量。
flowchart LR
A([主库故障]) --> B{同步复制?}
B -->|否| C{延迟 < RPO?}
B -->|是| D{同步从库<br/>可用?}
C -->|是| E[有损自动故障切换<br/>RPO < 1MB]
C -->|否| F[拒绝自动切换<br/>等待主库恢复<br/>或人工介入决策]
D -->|是| G[无损自动故障切换<br/>RPO = 0]
D -->|否| H{严格模式?}
H -->|否| C
H -->|是| F
style A fill:#dc3545,stroke:#b02a37,color:#fff
style E fill:#F0AD4E,stroke:#146c43,color:#fff
style G fill:#198754,stroke:#146c43,color:#fff
style F fill:#BE002F,stroke:#565e64,color:#fff 保护模式 Pigsty 提供三种保护模式,以帮助用户在不同的 RPO 要求下进行利弊权衡,类似于 Oracle Data Guard 的数据保护模式。
最大性能(Maximum Performance)
默认模式 ,异步复制,事务提交仅需本地 WAL 持久化,无需等待从库,从库故障对主库完全透明,不影响服务主库故障时可能丢失尚未发送/接收的 WAL(通常 < 1MB,正常网络条件通常在 10ms/100ms,10KB/100KB 量级) 针对性能优化,适用于常规业务场景,容许在故障时损失少量数据。 最大可用性(Maximum Availability)
配置有 pg_rpo = 0 ,启用 Patroni 同步提交模式: synchronous_mode: true 正常情况下等待至少一个从库确认,实现零数据丢失。当 所有 同步从库故障时,自动降级为异步模式继续服务 兼顾数据安全与服务可用性,是生产环境 核心业务 的推荐配置 最大保护(Maximum Protection)
使用 crit.yml 模板,启用 Patroni 严格同步模式:synchronous_mode: true / synchronous_mode_strict: true 当所有同步从库故障时,主库将拒绝写入 以防止数据丢失,事务必须在至少一个从库持久化后才返回成功。 适用于金融交易、医疗记录等对数据完整性要求极高的场景 名称 最大性能 Performance最大可用 Availability最大保护 Protection复制方式 异步复制 同步复制 严格同步复制 数据丢失 可能丢失 (复制延迟量)正常零丢失,降级少量丢失 零丢失 主库写延迟 最低 中等 (+1 次网络往返)中等 (+1 次网络往返)吞吐量 最高 降低 降低 从库故障影响 无影响 自动降级,继续服务 主库停写 RPO < 1MB = 0(正常)/ < 1MB(降级) = 0 适用场景 常规业务、性能优先 重要业务、安全优先 金融核心、安全合规第一 配置方法 默认配置 pg_rpo = 0pg_conf : crit.yml
实现原理 三种保护模式的区别在于 Patroni 的两个核心参数:synchronous_mode 与 synchronous_mode_strict 如何配置:
synchronous_mode :Patroni 是否启用同步复制,如果启用,再看 synchronous_mode_strict 是否启用严格同步模式。synchronous_mode_strict = false ,默认配置,允许当从库故障时降级为异步模式,主库继续服务 (最大可用性)synchronous_mode_strict = true ,禁止降级,主库停止写入 直到同步从库恢复(最大保护)模式 synchronous_modesynchronous_mode_strict复制模式 从库故障行为 最大性能 false- 异步复制 无影响 最大可用 truefalse同步复制 自动降级为异步 最大保护 truetrue严格同步复制 主库拒绝写入
通常情况下,您只需要将 pg_rpo 参数设置为 0,即可打开 synchronous_mode 开关,启用 最大可用性模式 。
如果您使用 pg_conf = crit.yml 模板,则会同时额外打开 synchronous_mode_strict 严格模式开关,启用 最大保护模式 。
此外,您可以启用 watchdog ,在节点/Patroni 假死场景下直接 Fencing 主库而不是降级,实现与 Oracle 最大保护模式相同的行为表现
当然,您可以直接按需 配置 这些 Patroni 参数,您还可以参阅 Patroni 与 PostgreSQL 文档,通过配置实现更强的数据保护,例如:
可以指定 同步从库列表 ,配置更多同步从库以提高容灾能力,使用法定人数同步,甚至要求所有从库都执行同步提交。 您可以 配置 synchronous_commit : 'remote_apply',严格确保主从读写一致性。(Oracle 最大保护模式相当于 remote_write) 配置建议 最大性能模式 (异步复制)是 Pigsty 默认使用的模式,对于绝大多数业务来说已经足够使用。
容许故障时丢失少量数据(正常在 几 KB - 几百 KB 的数量级),换来更大的性能吞吐量与服务可用性水平,是常规业务场景的推荐配置。
在这种情况下,您可以通过 pg_rpo 参数调整允许的最大数据丢失量,以适应不同的业务需求。
最大可用性模式 (同步复制)适用于对据完整性要求高的场景,不允许数据丢失。
在这种模式下,最少需要一主一从的两节点 PostgreSQL 集群才有意义。
将 pg_rpo 设置为 0 即可启用该模式。
最大保护模式 (严格同步复制) 适用于金融交易、医疗记录等对数据完整性要求极高的场景,我们建议至少使用一主二从的三节点集群,
因为两节点的情况下,只要从库故障,主库就会停止写入,导致业务不可用,这会降低系统的整体可靠性。而三节点的规格下,如果只有一个从库故障,主库仍然可以继续服务。
3.4.2 - RTO 利弊权衡 针对 RTO (Recovery Time Objective)进行利弊权衡,在故障恢复速度与误切风险之间找到最佳平衡点。
RTO (Recovery Time Objective,恢复时间目标)定义了在主库发生故障时,系统恢复写入能力所需的最长时间 。
对于核心交易系统这类可用性至关重要的场景,通常要求 RTO 尽可能短,例如一分钟内。
然而更短的 RTO 指标是有代价的,它会增加误切风险:网络抖动可能被误判为故障,导致不必要的故障切换。
因此对于跨机房/跨地域部署的场景,通常需要放宽 RTO 要求(例如 1-2 分钟),以降低误切风险。
利弊权衡 故障切换时的不可用时长上限由 pg_rto 参数控制。Pigsty 提供了四种预设的 RTO 模式:
fast、norm、safe、wide,分别针对不同的网络条件与部署场景进行了优化,默认使用 norm 模式(约 45 秒)。
您也可以使用秒数直接指定 RTO 上限,系统会自动映射到最接近的模式。
当主库发生故障时,整个恢复流程涉及多个阶段:Patroni 检测故障、DCS 锁过期、新主选举、执行 promote、HAProxy 感知新主。
减小 RTO 意味着缩短各阶段的超时时间,这会使集群对网络抖动更加敏感,从而增加误切风险。
您需要根据实际网络条件选择合适的模式,在 恢复速度 与 误切风险 之间取得平衡。
网络质量越差,越应该选择保守的模式;网络质量越好,越可以选择激进的模式。
flowchart LR
A([主库故障]) --> B{Patroni<br/>检测到?}
B -->|PG崩溃| C[尝试本地重启]
B -->|节点宕机| D[等待 TTL 过期]
C -->|成功| E([本地恢复])
C -->|失败/超时| F[释放 Leader 锁]
D --> F
F --> G[从库竞选]
G --> H[执行 Promote]
H --> I[HAProxy 感知]
I --> J([服务恢复])
style A fill:#dc3545,stroke:#b02a37,color:#fff
style E fill:#198754,stroke:#146c43,color:#fff
style J fill:#198754,stroke:#146c43,color:#fff 四种模式 Pigsty 提供四种 RTO 模式,以帮助用户在不同的网络条件下进行利弊权衡。
名称 fast norm safe wide 适用场景 同机柜 同机房内(默认) 同省跨机房 跨地域/跨洲 网络条件 < 1ms,极稳定 1-5ms,正常 10-50ms,跨机房 100-200ms,公网 目标 RTO 30s 45s 90s 150s 误切风险 较高 中等 较低 极低 配置方法 pg_rto: fastpg_rto: normpg_rto: safepg_rto: wide
fast:同机柜/同交换机
适用于网络延迟极低(< 1ms)且非常稳定的场景,例如同机柜或同交换机部署 平均 RTO: 14s ,最坏情况: 29s ,TTL 仅 20s,检测间隔 5s 对网络质量要求最高,任何抖动都可能触发切换,误切风险较高 norm:同机房(默认)
默认模式 ,适用于同机房部署,网络延迟 1-5ms,质量正常,丢包率合理平均 RTO: 21s ,最坏情况: 43s ,TTL 为 30s,提供合理的容错窗口 平衡了恢复速度与稳定性,适合绝大多数生产环境 safe:同省跨机房
适用于同省/同区域跨机房部署,网络延迟 10-50ms,可能存在偶发抖动 平均 RTO: 43s ,最坏情况: 91s ,TTL 为 60s,更长的容错窗口 主库重启等待时间较长(60s),给予更多本地恢复机会,误切风险较低 wide:跨地域/跨洲
适用于跨地域甚至跨大洲部署,网络延迟 100-200ms,可能有公网级别的丢包率 平均 RTO: 92s ,最坏情况: 207s ,TTL 为 120s,极宽的容错窗口 牺牲恢复速度换取极低的误切率,适合异地容灾场景 RTO时序图 Patroni / PG HA 有两条关键故障路径:主动故障检测 (PG 崩溃后 Patroni 检测到并尝试重启)与 被动租约过期 (节点宕机后等待 TTL 过期触发选举)。
实现原理 四种 RTO 模式的区别在于以下 10 个 Patroni 与 HAProxy HA 相关参数如何配置。
组件 参数 fast norm safe wide 说明 patronittl20 30 60 120 Leader 锁生存时间(秒) loop_wait5 5 10 20 HA 循环检查间隔(秒) retry_timeout5 10 20 30 DCS 操作重试超时(秒) primary_start_timeout15 25 45 95 主库重启等待时间(秒) safety_margin5 5 10 15 Watchdog 安全边际(秒) haproxyinter1s 2s 3s 4s 正常状态检查间隔 fastinter0.5s 1s 1.5s 2s 状态变化期检查间隔 downinter1s 2s 3s 4s DOWN 状态检查间隔 rise3 3 3 3 标记 UP 所需连续成功次数 fall3 3 3 3 标记 DOWN 所需连续失败次数
Patroni 参数 ttl :Leader 锁生存时间,主库须在此时间内续租,否则锁过期触发选举,直接决定被动故障的检测延迟。loop_wait :Patroni 主循环间隔,每个循环执行一次健康检查与状态同步,影响故障发现的及时性。retry_timeout :DCS 操作重试超时,网络分区时 Patroni 在此期间持续重试,超时后主库主动降级防止脑裂。primary_start_timeout :PG 崩溃后 Patroni 尝试本地重启的等待时间,超时后释放 Leader 锁触发切换。safety_margin :Watchdog 安全边际,确保故障时有足够时间触发系统重启,避免脑裂。HAProxy 参数 inter :正常状态下的健康检查间隔,服务状态稳定时使用。fastinter :状态变化期的检查间隔,检测到状态变化时使用更短间隔加速确认。downinter :DOWN 状态下的检查间隔,服务标记为 DOWN 后使用此间隔探测恢复。rise :标记 UP 所需连续成功次数,新主上线后需连续通过 rise 次检查才能接收流量。fall :标记 DOWN 所需连续失败次数,服务需连续失败 fall 次才会被标记为 DOWN。关键约束 Patroni 核心约束 :确保主库能在 TTL 过期前完成降级,防止脑裂。
l o o p _ w a i t + 2 × r e t r y _ t i m e o u t ≤ t t l loop\_wait + 2 \times retry\_timeout \leq ttl l oo p _ w ai t + 2 × re t ry _ t im eo u t ≤ ttl 数据汇总 配置建议 fast 模式 适用于对 RTO 要求极高的场景,但需要确保网络质量足够好(延迟 < 1ms,极低丢包率)。
建议仅在同机柜或同交换机部署时使用,并在生产环境充分测试后再启用。
norm 模式 (默认 )是 Pigsty 默认使用的配置,对于绝大多数同机房部署的业务来说已经足够使用。
平均 21 秒的恢复时间在可接受范围内,同时提供了合理的容错窗口,避免网络抖动导致的误切。
safe 模式 适用于同城跨机房部署,网络延迟较高或存在偶发抖动的场景。
更长的容错窗口可以有效避免网络抖动导致的误切,是跨机房容灾的推荐配置。
wide 模式 适用于跨地域甚至跨大洲部署,网络延迟高且可能存在公网级别的丢包率。
这种场景下,稳定性比恢复速度更重要,因此使用极宽的容错窗口来确保极低的误切率。
模式 目标 RTO 被动检测 RTO 主动检测 RTO 场景 fast3016 / 23 / 291 / 24 / 29同交换机,高质量网络 norm4527 / 34 / 412 / 35 / 41默认,同机房,标准网络 safe9053 / 66 / 783 / 61 / 73同城双活 / 跨机房容灾 wide150104 / 127 / 1504 / 122 / 145异地容灾 / 跨国部署 default32622 / 34 / 462 / 314 / 326Patroni 默认参数
通常只需将 pg_rto 设为模式名称,Pigsty 会自动配置 Patroni 与 HAProxy 参数。
为了保持向后兼容性,Pigsty 仍然支持直接使用秒数配置 RTO,但效果相当于指定 norm 模式。
配置模式实际上是从 pg_rto_plan 中加载对应参数集,您可以修改或覆盖此配置以实现自定义 RTO 策略。
pg_rto_plan : # [ttl, loop, retry, start, margin, inter, fastinter, downinter, rise, fall]
fast : [ 20 , 5 , 5 , 15 , 5 , '1s' , '0.5s' , '1s' , 3 , 3 ] # rto < 30s
norm : [ 30 , 5 , 10 , 25 , 5 , '2s' , '1s' , '2s' , 3 , 3 ] # rto < 45s
safe : [ 60 , 10 , 20 , 45 , 10 , '3s' , '1.5s' , '3s' , 3 , 3 ] # rto < 90s
wide : [ 120 , 20 , 30 , 95 , 15 , '4s' , '2s' , '4s' , 3 , 3 ] # rto < 150s
3.4.3 - 故障切换模型 详细分析三种经典故障检测/恢复路径下,最差,最优,平均 RTO 的计算逻辑与结果
Patroni 故障按故障对象分类可以分为以下 10 类,按照检测路径不同,可以进一步归纳为五类,在本节内详细展开。
# 故障场景 描述 最终走哪条路径 1 PG 进程崩溃 crash、OOM killed 主动检测 2 PG 拒绝连接 max_connections 主动检测 3 PG 假活 进程在但无响应 主动检测 (检测超时)4 Patroni 进程崩溃 kill -9、OOM 被动检测 5 Patroni 假活 进程在但卡住 Watchdog 6 节点宕机 断电、硬件故障 被动检测 7 节点假活 IO hang、CPU 饥饿 Watchdog 8 主库 ↔ DCS 网络中断 防火墙、交换机故障 网络分区 9 存储故障 磁盘坏、磁盘满、挂载失败 主动检测 或 Watchdog 10 手动切换 Switchover/Failover 手动触发
但是在 RTO 计算上,最终所有故障都会收敛到两条路径上,本节深入探讨了这两种情况下的 RTO 上下限与均值。
flowchart LR
A([主库故障]) --> B{Patroni<br/>检测到?}
B -->|PG崩溃| C[尝试本地重启]
B -->|节点宕机| D[等待 TTL 过期]
C -->|成功| E([本地恢复])
C -->|失败/超时| F[释放 Leader 锁]
D --> F
F --> G[从库竞选]
G --> H[执行 Promote]
H --> I[HAProxy 感知]
I --> J([服务恢复])
style A fill:#dc3545,stroke:#b02a37,color:#fff
style E fill:#198754,stroke:#146c43,color:#fff
style J fill:#198754,stroke:#146c43,color:#fff 3.4.3.1 - 被动故障切换 节点宕机,导致领导者租约过期触发集群领导竞选的故障路径
RTO 时序图
故障模型 项目 最好 最坏 平均 说明 租约过期 ttl - loopttlttl - loop/2最好:即将刷新时宕机 最坏:刚刷新完就宕机 从库检测 0looploop / 2最好:恰好在检测点 最坏:刚错过检测点 抢锁提拔 021最好:直接抢锁提升 最坏:API 超时+Promote 健康检查 (rise-1) × fastinter(rise-1) × fastinter + inter(rise-1) × fastinter + inter/2最好:检查前状态变化 最坏:检查后瞬间状态变化
被动故障与主动故障的核心区别 :
场景 Patroni 状态 租约处理 主要等待时间 主动故障 (PG 崩溃)存活,健康 主动尝试重启 PG,超时后释放租约 primary_start_timeout被动故障 (节点宕机)随节点一起死亡 无法主动释放,只能等待 TTL 过期 ttl
在被动故障场景中,Patroni 随节点一起宕机,无法主动释放 Leader Key 。
DCS 中的租约只能等待 TTL 自然过期后触发集群选举。
时序分析 阶段 1:租约过期 Patroni 主库会在每个 loop_wait 周期刷新 Leader Key,将 TTL 重置为配置值。
时间线:
t-loop t t+ttl-loop t+ttl
| | | |
上次刷新 故障发生 最好情况 最坏情况
|←── loop ──→| | |
|←──────────── ttl ─────────────────────→|
最好情况 :故障发生在即将刷新租约之前(距上次刷新已过 loop),剩余 TTL = ttl - loop最坏情况 :故障发生在刚刷新租约之后,需等待完整 ttl平均情况 :ttl - loop/2T e x p i r e = { t t l − l o o p 最好 t t l − l o o p / 2 平均 t t l 最坏 T_{expire} = \begin{cases}
ttl - loop & \text{最好} \\
ttl - loop/2 & \text{平均} \\
ttl & \text{最坏}
\end{cases} T e x p i re = ⎩ ⎨ ⎧ ttl − l oo p ttl − l oo p /2 ttl 最好 平均 最坏 阶段 2:从库检测 从库在 loop_wait 周期醒来后检查 DCS 中的 Leader Key 状态。
时间线:
租约过期 从库醒来
| |
|←── 0~loop ─→|
最好情况 :租约过期时从库恰好醒来,等待 0最坏情况 :租约过期后从库刚进入睡眠,等待 loop平均情况 :loop/2T d e t e c t = { 0 最好 l o o p / 2 平均 l o o p 最坏 T_{detect} = \begin{cases}
0 & \text{最好} \\
loop/2 & \text{平均} \\
loop & \text{最坏}
\end{cases} T d e t ec t = ⎩ ⎨ ⎧ 0 l oo p /2 l oo p 最好 平均 最坏 阶段 3:抢锁提拔 从库发现 Leader Key 过期后,开始竞选过程,获得 Leader Key 的从库执行 pg_ctl promote,将自己提升为新主库。
通过 Rest API,并行发起查询,查询各从库的复制位置,通常 10ms,硬编码 2 秒超时。 比较 WAL 位置,确定最优候选,各从库尝试创建 Leader Key(CAS 原子操作) 执行 pg_ctl promote 提升自己为主库(很快,通常忽略不计) 选举流程:
从库A ──→ 查询复制位置 ──→ 比较 ──→ 尝试抢锁 ──→ 成功
从库B ──→ 查询复制位置 ──→ 比较 ──→ 尝试抢锁 ──→ 失败
最好情况 :单从库或直接抢到锁并提升,常数开销 0.1s最坏情况 :DCS API 调用超时:2s平均情况 :1s 常数开销T e l e c t = { 0.1 最好 1 平均 2 最坏 T_{elect} = \begin{cases}
0.1 & \text{最好} \\
1 & \text{平均} \\
2 & \text{最坏}
\end{cases} T e l ec t = ⎩ ⎨ ⎧ 0.1 1 2 最好 平均 最坏 阶段 4:健康检查 HAProxy 检测新主库上线,需要连续 rise 次健康检查成功。
检测时序:
新主提升 首次检查 第二次检查 第三次检查(UP)
| | | |
|←─ 0~inter ─→|←─ fast ─→|←─ fast ─→|
最好情况 :新主提升时恰好赶上检查,(rise-1) × fastinter最坏情况 :新主提升后刚错过检查,(rise-1) × fastinter + inter平均情况 :(rise-1) × fastinter + inter/2T h a p r o x y = { ( r i s e − 1 ) × f a s t i n t e r 最好 ( r i s e − 1 ) × f a s t i n t e r + i n t e r / 2 平均 ( r i s e − 1 ) × f a s t i n t e r + i n t e r 最坏 T_{haproxy} = \begin{cases}
(rise-1) \times fastinter & \text{最好} \\
(rise-1) \times fastinter + inter/2 & \text{平均} \\
(rise-1) \times fastinter + inter & \text{最坏}
\end{cases} T ha p ro x y = ⎩ ⎨ ⎧ ( r i se − 1 ) × f a s t in t er ( r i se − 1 ) × f a s t in t er + in t er /2 ( r i se − 1 ) × f a s t in t er + in t er 最好 平均 最坏 RTO 公式 将各阶段时间相加,得到总 RTO:
最好情况
R T O m i n = t t l − l o o p + 0.1 + ( r i s e − 1 ) × f a s t i n t e r RTO_{min} = ttl - loop + 0.1 + (rise-1) \times fastinter RT O min = ttl − l oo p + 0.1 + ( r i se − 1 ) × f a s t in t er 平均情况
R T O a v g = t t l + 1 + i n t e r / 2 + ( r i s e − 1 ) × f a s t i n t e r RTO_{avg} = ttl + 1 + inter/2 + (rise-1) \times fastinter RT O a vg = ttl + 1 + in t er /2 + ( r i se − 1 ) × f a s t in t er 最坏情况
R T O m a x = t t l + l o o p + 2 + i n t e r + ( r i s e − 1 ) × f a s t i n t e r RTO_{max} = ttl + loop + 2 + inter + (rise-1) \times fastinter RT O ma x = ttl + l oo p + 2 + in t er + ( r i se − 1 ) × f a s t in t er 模型计算 将四种 RTO 模型的参数带入上面的公式:
pg_rto_plan : # [ttl, loop, retry, start, margin, inter, fastinter, downinter, rise, fall]
fast : [ 20 , 5 , 5 , 15 , 5 , '1s' , '0.5s' , '1s' , 3 , 3 ] # rto < 30s
norm : [ 30 , 5 , 10 , 25 , 5 , '2s' , '1s' , '2s' , 3 , 3 ] # rto < 45s
safe : [ 60 , 10 , 20 , 45 , 10 , '3s' , '1.5s' , '3s' , 3 , 3 ] # rto < 90s
wide : [ 120 , 20 , 30 , 95 , 15 , '4s' , '2s' , '4s' , 3 , 3 ] # rto < 150s
四种模式计算结果 (单位:秒,格式:min / avg / max)
阶段 fast norm safe wide 租约过期 15 / 17 / 2025 / 27 / 3050 / 55 / 60100 / 110 / 120从库检测 0 / 3 / 50 / 3 / 50 / 5 / 100 / 10 / 20抢锁提拔 0 / 1 / 20 / 1 / 20 / 1 / 20 / 1 / 2健康检查 1 / 2 / 22 / 3 / 43 / 5 / 64 / 6 / 8总计 16 / 23 / 2927 / 34 / 4153 / 66 / 78104 / 127 / 150
3.4.3.2 - 主动故障检测 PostgreSQL 主库进程崩溃,Patroni 存活并尝试重启,超时后触发故障切换的路径
RTO 时序图
故障模型 项目 最好 最坏 平均 说明 故障检测 0looploop/2最好:PG 恰好在检测前崩溃 最坏:PG 刚检测完就崩溃 重启超时 0startstart最好:PG 瞬间自愈 最坏:等满 start 超时才释放租约 从库检测 0looploop/2最好:恰好在检测点 最坏:刚错过检测点 抢锁提拔 021最好:直接抢锁提升 最坏:API 超时 + Promote 健康检查 (rise-1) × fastinter(rise-1) × fastinter + inter(rise-1) × fastinter + inter/2最好:检查前状态变化 最坏:检查后瞬间状态变化
主动故障与被动故障的核心区别 :
场景 Patroni 状态 租约处理 主要等待时间 主动故障 (PG 崩溃)存活,健康 主动尝试重启 PG,超时后释放租约 primary_start_timeout被动故障 (节点宕机)随节点一起死亡 无法主动释放,只能等待 TTL 过期 ttl
在主动故障场景中,Patroni 仍然存活,能够主动检测到 PG 崩溃并尝试重启 。
如果重启成功,服务自愈;如果超时仍未恢复,Patroni 会主动释放 Leader Key ,触发集群选举。
时序分析 阶段 1:故障检测 Patroni 在每个 loop_wait 周期检查 PostgreSQL 状态(通过 pg_isready 或检查进程)。
时间线:
上次检测 PG崩溃 下次检测
| | |
|←── 0~loop ─→| |
最好情况 :PG 恰好在 Patroni 检测前崩溃,立即被发现,等待 0最坏情况 :PG 刚检测完就崩溃,需等待下一个周期,等待 loop平均情况 :loop/2T d e t e c t = { 0 最好 l o o p / 2 平均 l o o p 最坏 T_{detect} = \begin{cases}
0 & \text{最好} \\
loop/2 & \text{平均} \\
loop & \text{最坏}
\end{cases} T d e t ec t = ⎩ ⎨ ⎧ 0 l oo p /2 l oo p 最好 平均 最坏 阶段 2:重启超时 Patroni 检测到 PG 崩溃后,会尝试重启 PostgreSQL。此阶段有两种可能的结果:
时间线:
检测到崩溃 尝试重启 重启成功/超时
| | |
|←──── 0 ~ start ────────→|
路径 A:自愈成功 (最好情况)
PG 成功重启,服务恢复 不触发故障切换,RTO 极短 等待时间:0(相对于 Failover 路径) 路径 B:需要 Failover (平均/最坏情况)
等待 primary_start_timeout 超时后 PG 仍未恢复 Patroni 主动释放 Leader Key 等待时间:start T r e s t a r t = { 0 最好(自愈成功) s t a r t 平均(需要 Failover) s t a r t 最坏 T_{restart} = \begin{cases}
0 & \text{最好(自愈成功)} \\
start & \text{平均(需要 Failover)} \\
start & \text{最坏}
\end{cases} T res t a r t = ⎩ ⎨ ⎧ 0 s t a r t s t a r t 最好(自愈成功) 平均(需要 Failover ) 最坏 注意 :平均情况假设需要进行故障切换。如果 PG 能够快速自愈,则整体 RTO 会大幅降低。
阶段 3:从库检测 从库在 loop_wait 周期醒来后检查 DCS 中的 Leader Key 状态。当主库 Patroni 释放 Leader Key 后,从库发现后开始竞选。
时间线:
租约释放 从库醒来
| |
|←── 0~loop ─→|
最好情况 :租约释放时从库恰好醒来,等待 0最坏情况 :租约释放后从库刚进入睡眠,等待 loop平均情况 :loop/2T s t a n d b y = { 0 最好 l o o p / 2 平均 l o o p 最坏 T_{standby} = \begin{cases}
0 & \text{最好} \\
loop/2 & \text{平均} \\
loop & \text{最坏}
\end{cases} T s t an d b y = ⎩ ⎨ ⎧ 0 l oo p /2 l oo p 最好 平均 最坏 阶段 4:抢锁提拔 从库发现 Leader Key 空缺后,开始竞选过程,获得 Leader Key 的从库执行 pg_ctl promote,将自己提升为新主库。
通过 Rest API,并行发起查询,查询各从库的复制位置,通常 10ms,硬编码 2 秒超时。 比较 WAL 位置,确定最优候选,各从库尝试创建 Leader Key(CAS 原子操作) 执行 pg_ctl promote 提升自己为主库(很快,通常忽略不计) 选举流程:
从库A ──→ 查询复制位置 ──→ 比较 ──→ 尝试抢锁 ──→ 成功
从库B ──→ 查询复制位置 ──→ 比较 ──→ 尝试抢锁 ──→ 失败
最好情况 :单从库或直接抢到锁并提升,常数开销 0.1s最坏情况 :DCS API 调用超时:2s平均情况 :1s 常数开销T e l e c t = { 0.1 最好 1 平均 2 最坏 T_{elect} = \begin{cases}
0.1 & \text{最好} \\
1 & \text{平均} \\
2 & \text{最坏}
\end{cases} T e l ec t = ⎩ ⎨ ⎧ 0.1 1 2 最好 平均 最坏 阶段 5:健康检查 HAProxy 检测新主库上线,需要连续 rise 次健康检查成功。
检测时序:
新主提升 首次检查 第二次检查 第三次检查(UP)
| | | |
|←─ 0~inter ─→|←─ fast ─→|←─ fast ─→|
最好情况 :新主提升时恰好赶上检查,(rise-1) × fastinter最坏情况 :新主提升后刚错过检查,(rise-1) × fastinter + inter平均情况 :(rise-1) × fastinter + inter/2T h a p r o x y = { ( r i s e − 1 ) × f a s t i n t e r 最好 ( r i s e − 1 ) × f a s t i n t e r + i n t e r / 2 平均 ( r i s e − 1 ) × f a s t i n t e r + i n t e r 最坏 T_{haproxy} = \begin{cases}
(rise-1) \times fastinter & \text{最好} \\
(rise-1) \times fastinter + inter/2 & \text{平均} \\
(rise-1) \times fastinter + inter & \text{最坏}
\end{cases} T ha p ro x y = ⎩ ⎨ ⎧ ( r i se − 1 ) × f a s t in t er ( r i se − 1 ) × f a s t in t er + in t er /2 ( r i se − 1 ) × f a s t in t er + in t er 最好 平均 最坏 RTO 公式 将各阶段时间相加,得到总 RTO:
最好情况 (PG 瞬间自愈)
R T O m i n = 0 + 0 + 0 + 0.1 + ( r i s e − 1 ) × f a s t i n t e r ≈ ( r i s e − 1 ) × f a s t i n t e r RTO_{min} = 0 + 0 + 0 + 0.1 + (rise-1) \times fastinter \approx (rise-1) \times fastinter RT O min = 0 + 0 + 0 + 0.1 + ( r i se − 1 ) × f a s t in t er ≈ ( r i se − 1 ) × f a s t in t er 平均情况 (需要 Failover)
R T O a v g = l o o p + s t a r t + 1 + i n t e r / 2 + ( r i s e − 1 ) × f a s t i n t e r RTO_{avg} = loop + start + 1 + inter/2 + (rise-1) \times fastinter RT O a vg = l oo p + s t a r t + 1 + in t er /2 + ( r i se − 1 ) × f a s t in t er 最坏情况
R T O m a x = l o o p × 2 + s t a r t + 2 + i n t e r + ( r i s e − 1 ) × f a s t i n t e r RTO_{max} = loop \times 2 + start + 2 + inter + (rise-1) \times fastinter RT O ma x = l oo p × 2 + s t a r t + 2 + in t er + ( r i se − 1 ) × f a s t in t er 模型计算 将四种 RTO 模型的参数带入上面的公式:
pg_rto_plan : # [ttl, loop, retry, start, margin, inter, fastinter, downinter, rise, fall]
fast : [ 20 , 5 , 5 , 15 , 5 , '1s' , '0.5s' , '1s' , 3 , 3 ] # rto < 30s
norm : [ 30 , 5 , 10 , 25 , 5 , '2s' , '1s' , '2s' , 3 , 3 ] # rto < 45s
safe : [ 60 , 10 , 20 , 45 , 10 , '3s' , '1.5s' , '3s' , 3 , 3 ] # rto < 90s
wide : [ 120 , 20 , 30 , 95 , 15 , '4s' , '2s' , '4s' , 3 , 3 ] # rto < 150s
四种模式计算结果 (单位:秒,格式:min / avg / max)
阶段 fast norm safe wide 故障检测 0 / 3 / 50 / 3 / 50 / 5 / 100 / 10 / 20重启超时 0 / 15 / 150 / 25 / 250 / 45 / 450 / 95 / 95从库检测 0 / 3 / 50 / 3 / 50 / 5 / 100 / 10 / 20抢锁提拔 0 / 1 / 20 / 1 / 20 / 1 / 20 / 1 / 2健康检查 1 / 2 / 22 / 3 / 43 / 5 / 64 / 6 / 8总计 1 / 24 / 292 / 35 / 413 / 61 / 734 / 122 / 145
与被动故障对比 阶段 主动故障(PG 崩溃) 被动故障(节点宕机) 说明 检测机制 Patroni 主动检测 TTL 被动过期 主动检测更快发现故障 核心等待 startttlstart 通常小于 ttl,但需要额外的故障检测时间 租约处理 主动释放 被动过期 主动释放更及时 自愈可能 ✅ 有 ❌ 无 主动检测可尝试本地恢复
RTO 对比 (平均情况):
模式 主动故障(PG 崩溃) 被动故障(节点宕机) 差异 fast 24s 23s +1s norm 35s 34s +1s safe 61s 66s -5s wide 122s 127s -5s
分析 :在 fast 和 norm 模式下,主动故障的 RTO 略高于被动故障,因为需要等待 primary_start_timeout(start);
但在 safe 和 wide 模式下,由于 start < ttl - loop,主动故障反而更快。
不过主动故障有自愈的可能性,最好情况下 RTO 可以极短。
3.4.4 - 服务接入 Pigsty 使用 HAProxy 提供服务接入,并提供可选的 pgBouncer 池化连接,以及可选的 L2 VIP 与 DNS 接入。
分离读写操作,正确路由流量,稳定可靠地交付 PostgreSQL 集群提供的能力。
服务 是一种抽象:它是数据库集群对外提供能力的形式,并封装了底层集群的细节。
服务对于生产环境中的 稳定接入 至关重要,在 高可用 集群自动故障时方显其价值,单机用户 通常不需要操心这个概念。
单机用户 “服务” 的概念是给生产环境用的,个人用户/单机集群可以不折腾,直接拿实例名/IP 地址访问数据库。
例如,Pigsty 默认的单节点 pg-meta.meta 数据库,就可以直接用下面三个不同的用户连接上去。
psql postgres://dbuser_dba:DBUser.DBA@10.10.10.10/meta # 直接用 DBA 超级用户连上去
psql postgres://dbuser_meta:DBUser.Meta@10.10.10.10/meta # 用默认的业务管理员用户连上去
psql postgres://dbuser_view:DBUser.View@pg-meta/meta # 用默认的只读用户走实例域名连上去
服务概述 在真实世界生产环境中,我们会使用基于复制的主从数据库集群。集群中有且仅有一个实例作为领导者(主库 )可以接受写入。
而其他实例(从库 )则会从持续从集群领导者获取变更日志,与领导者保持一致。同时,从库还可以承载只读请求,在读多写少的场景下可以显著分担主库的负担,
因此对集群的写入请求与只读请求进行区分,是一种十分常见的实践。
此外对于高频短连接的生产环境,我们还会通过连接池中间件(Pgbouncer)对请求进行池化,减少连接与后端进程的创建开销。但对于 ETL 与变更执行等场景,我们又需要绕过连接池,直接访问数据库。
同时,高可用集群在故障时会出现故障切换(Failover),故障切换会导致集群的领导者出现变更。因此高可用的数据库方案要求写入流量可以自动适配集群的领导者变化。
这些不同的访问需求(读写分离,池化与直连,故障切换自动适配)最终抽象出 服务 (Service)的概念。
通常来说,数据库集群都必须提供这种最基础的服务:
对于生产数据库集群,至少应当提供这两种服务:
读写服务(primary) :写入数据:只能由主库所承载。只读服务(replica) :读取数据:可以由从库承载,没有从库时也可由主库承载此外,根据具体的业务场景,可能还会有其他的服务,例如:
默认直连服务(default) :允许(管理)用户,绕过连接池直接访问数据库的服务离线从库服务(offline) :不承接线上只读流量的专用从库,用于 ETL 与分析查询同步从库服务(standby) :没有复制延迟的只读服务,由 同步备库 /主库处理只读查询延迟从库服务(delayed) :访问同一个集群在一段时间之前的旧数据,由 延迟从库 来处理接入服务 Pigsty 的服务交付边界止步于集群的 HAProxy,用户可以用各种手段访问这些负载均衡器。
典型的做法是使用 DNS 或 VIP 接入,将其绑定在集群所有或任意数量的负载均衡器上。
你可以使用不同的 主机 & 端口 组合,它们以不同的方式提供 PostgreSQL 服务。
主机
类型 样例 描述 集群域名 pg-test通过集群域名访问(由 dnsmasq @ infra 节点解析) 集群 VIP 地址 10.10.10.3通过由 vip-manager 管理的 L2 VIP 地址访问,绑定到主节点 实例主机名 pg-test-1通过任何实例主机名访问(由 dnsmasq @ infra 节点解析) 实例 IP 地址 10.10.10.11访问任何实例的 IP 地址
端口
Pigsty 使用不同的 端口 来区分 pg services
端口 服务 类型 描述 5432 postgres 数据库 直接访问 postgres 服务器 6432 pgbouncer 中间件 访问 postgres 前先通过连接池中间件 5433 primary 服务 访问主 pgbouncer (或 postgres) 5434 replica 服务 访问备份 pgbouncer (或 postgres) 5436 default 服务 访问主 postgres 5438 offline 服务 访问离线 postgres
组合
# 通过集群域名访问
postgres://test@pg-test:5432/test # DNS -> L2 VIP -> 主直接连接
postgres://test@pg-test:6432/test # DNS -> L2 VIP -> 主连接池 -> 主
postgres://test@pg-test:5433/test # DNS -> L2 VIP -> HAProxy -> 主连接池 -> 主
postgres://test@pg-test:5434/test # DNS -> L2 VIP -> HAProxy -> 备份连接池 -> 备份
postgres://dbuser_dba@pg-test:5436/test # DNS -> L2 VIP -> HAProxy -> 主直接连接 (用于管理员)
postgres://dbuser_stats@pg-test:5438/test # DNS -> L2 VIP -> HAProxy -> 离线直接连接 (用于 ETL/个人查询)
# 通过集群 VIP 直接访问
postgres://test@10.10.10.3:5432/test # L2 VIP -> 主直接访问
postgres://test@10.10.10.3:6432/test # L2 VIP -> 主连接池 -> 主
postgres://test@10.10.10.3:5433/test # L2 VIP -> HAProxy -> 主连接池 -> 主
postgres://test@10.10.10.3:5434/test # L2 VIP -> HAProxy -> 备份连接池 -> 备份
postgres://dbuser_dba@10.10.10.3:5436/test # L2 VIP -> HAProxy -> 主直接连接 (用于管理员)
postgres://dbuser_stats@10.10.10.3::5438/test # L2 VIP -> HAProxy -> 离线直接连接 (用于 ETL/个人查询)
# 直接指定任何集群实例名
postgres://test@pg-test-1:5432/test # DNS -> 数据库实例直接连接 (单例访问)
postgres://test@pg-test-1:6432/test # DNS -> 连接池 -> 数据库
postgres://test@pg-test-1:5433/test # DNS -> HAProxy -> 连接池 -> 数据库读/写
postgres://test@pg-test-1:5434/test # DNS -> HAProxy -> 连接池 -> 数据库只读
postgres://dbuser_dba@pg-test-1:5436/test # DNS -> HAProxy -> 数据库直接连接
postgres://dbuser_stats@pg-test-1:5438/test # DNS -> HAProxy -> 数据库离线读/写
# 直接指定任何集群实例 IP 访问
postgres://test@10.10.10.11:5432/test # 数据库实例直接连接 (直接指定实例, 没有自动流量分配)
postgres://test@10.10.10.11:6432/test # 连接池 -> 数据库
postgres://test@10.10.10.11:5433/test # HAProxy -> 连接池 -> 数据库读/写
postgres://test@10.10.10.11:5434/test # HAProxy -> 连接池 -> 数据库只读
postgres://dbuser_dba@10.10.10.11:5436/test # HAProxy -> 数据库直接连接
postgres://dbuser_stats@10.10.10.11:5438/test # HAProxy -> 数据库离线读-写
# 智能客户端:通过URL读写分离
postgres://test@10.10.10.11:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs= primary
postgres://test@10.10.10.11:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs= prefer-standby
3.5 - 时间点恢复 Pigsty 使用 pgBackRest 实现了 PostgreSQL 时间点恢复,允许用户回滚至备份策略容许范围内的任意时间点。
当您不小心删除了数据、表、甚至整个数据库时,PITR 能力让您回到过去任意时刻,避免软件缺陷与人为失误导致的数据损失。
—— 这个曾经只有资深 DBA 才能施展的『魔法』,现在对所有用户都可以轻松做到零配置开箱即用。
概览 Pigsty 的 PostgreSQL 集群带有自动配置的时间点恢复(PITR)方案,基于 pgBackRest 与可选的对象存储仓库 MinIO 提供。
高可用方案 可以解决硬件故障,但却对软件缺陷与人为失误导致的数据删除/覆盖写入/删库等问题却无能为力。
对于这种情况,Pigsty 提供了开箱即用的 时间点恢复 (Point in Time Recovery, PITR)能力,无需额外配置即默认启用。
Pigsty 为您提供了基础备份与 WAL 归档的默认配置,您可以使用本地目录与磁盘,亦或专用的 MinIO 集群或 S3 对象存储服务来存储备份并实现异地容灾。
当您使用本地磁盘时,默认保留恢复至过去一天内的任意时间点的能力。当您使用 MinIO 或 S3 时,默认保留恢复至过去一周内的任意时间点的能力。
只要存储空间管够,您尽可保留任意长地可恢复时间段,丰俭由人。
时间点恢复解决什么问题? 容灾能⼒增强:RPO 从 ∞ 降⾄ ⼗⼏MB, RTO 从 ∞ 降⾄ ⼏⼩时/⼏刻钟。 确保数据安全:C/I/A 中的 数据完整性 :避免误删导致的数据⼀致性问题。 确保数据安全:C/I/A 中的 数据可⽤性 :提供对“永久不可⽤”这种灾难情况的兜底 单实例配置策略 事件 RTO RPO 什么也不做宕机 永久丢失 全部丢失 基础备份宕机 取决于备份大小与带宽(几小时) 丢失上一次备份后的数据(几个小时到几天) 基础备份 + WAL 归档宕机 取决于备份大小与带宽(几小时) 丢失最后尚未归档的数据(几十 MB)
时间点恢复有什么代价? 降低数据安全中的 C:机密性 ,产生额外泄漏点,需要额外对备份进⾏保护。 额外的资源消耗:本地存储或⽹络流量 / 带宽开销,通常并不是⼀个问题。 复杂度代价升⾼:⽤户需要付出备份管理成本。 时间点恢复的局限性 如果只有 PITR 用于故障恢复,则 RTO 与 RPO 指标相比 高可用方案 更为逊色,通常应两者组合使用。
RTO :如果只有单机 + PITR,恢复时长取决于备份大小与网络/磁盘带宽,从十几分钟到几小时,几天不等。RPO :如果只有单机 + PITR,宕机时可能丢失少量数据,一个或几个 WAL 日志段文件可能尚未归档,损失 16 MB 到⼏⼗ MB 不等的数据。除了 PITR 之外,您还可以在 Pigsty 中使用 延迟集群 来解决人为失误或软件缺陷导致的数据误删误改问题。
原理 时间点恢复允许您将集群恢复回滚至过去的“任意时刻”,避免软件缺陷与人为失误导致的数据损失。要做到这一点,首先需要做好两样准备工作:基础备份 与 WAL归档 。
拥有 基础备份 ,允许用户将数据库恢复至备份时的状态,而同时拥有从某个基础备份开始的 WAL 归档 ,允许用户将数据库恢复至基础备份时刻之后的任意时间点。
详细原理,请参阅:基础备份与时间点恢复 ;具体操作,请参考 PGSQL管理:备份恢复 。
基础备份 Pigsty 使用 pgbackrest 管理 PostgreSQL 备份。pgBackRest 将在所有集群实例上初始化空仓库,但只会在集群主库上实际使用仓库。
pgBackRest 支持三种备份模式:全量备份 ,增量备份 ,差异备份,其中前两者最为常用。
全量备份将对数据库集群取一个当前时刻的全量物理快照,增量备份会记录当前数据库集群与上一次全量备份之间的差异。
Pigsty 为备份提供了封装命令:/pg/bin/pg-backup [full|incr]。您可以通过 Crontab 或任何其他任务调度系统,按需定期制作基础备份。
WAL归档 Pigsty 默认在集群主库上启⽤了 WAL 归档,并使⽤ pgbackrest 命令行工具持续推送 WAL 段⽂件至备份仓库。
pgBackRest 会⾃动管理所需的 WAL ⽂件,并根据备份的保留策略及时清理过期的备份,与其对应的 WAL 归档⽂件。
如果您不需要 PITR 功能,可以通过 配置集群 : archive_mode: off 来关闭 WAL 归档,移除 node_crontab 来停止定期备份任务。
实现 默认情况下,Pigsty 提供了两种预置 备份策略 :默认使用本地文件系统备份仓库,在这种情况下每天进行一次全量备份,确保用户任何时候都能回滚至一天内的任意时间点。备选策略使用专用的 MinIO 集群或 S3 存储备份,每周一全备,每天一增备,默认保留两周的备份与 WAL 归档。
Pigsty 使用 pgBackRest 管理备份,接收 WAL 归档,执行 PITR。备份仓库可以进行灵活配置(pgbackrest_repo ):默认使用主库本地文件系统(local),但也可以使用其他磁盘路径,或使用自带的可选 MinIO 服务(minio)与云上 S3 服务。
pgbackrest_enabled : true # 在 pgsql 主机上启用 pgBackRest 吗?
pgbackrest_clean : true # 初始化时删除 pg 备份数据?
pgbackrest_log_dir : /pg/log/pgbackrest # pgbackrest 日志目录,默认为 `/pg/log/pgbackrest`
pgbackrest_method : local # pgbackrest 仓库方法:local, minio, [用户定义...]
pgbackrest_repo : # pgbackrest 仓库:https://pgbackrest.org/configuration.html#section-repository
local : # 默认使用本地 posix 文件系统的 pgbackrest 仓库
path : /pg/backup # 本地备份目录,默认为 `/pg/backup`
retention_full_type : count # 按计数保留完整备份
retention_full : 2 # 使用本地文件系统仓库时,最多保留 3 个完整备份,至少保留 2 个
minio : # pgbackrest 的可选 minio 仓库
type : s3 # minio 是与 s3 兼容的,所以使用 s3
s3_endpoint : sss.pigsty # minio 端点域名,默认为 `sss.pigsty`
s3_region : us-east-1 # minio 区域,默认为 us-east-1,对 minio 无效
s3_bucket : pgsql # minio 桶名称,默认为 `pgsql`
s3_key : pgbackrest # pgbackrest 的 minio 用户访问密钥
s3_key_secret : S3User.Backup # pgbackrest 的 minio 用户秘密密钥
s3_uri_style : path # 对 minio 使用路径风格的 uri,而不是主机风格
path : /pgbackrest # minio 备份路径,默认为 `/pgbackrest`
storage_port : 9000 # minio 端口,默认为 9000
storage_ca_file : /etc/pki/ca.crt # minio ca 文件路径,默认为 `/etc/pki/ca.crt`
bundle : y # 将小文件打包成一个文件
cipher_type : aes-256-cbc # 为远程备份仓库启用 AES 加密
cipher_pass : pgBackRest # AES 加密密码,默认为 'pgBackRest'
retention_full_type : time # 在 minio 仓库上按时间保留完整备份
retention_full : 14 # 保留过去 14 天的完整备份
# 您还可以添加其他的可选备份仓库,例如 S3,用于异地容灾
Pigsty 参数 pgbackrest_repo 中的目标仓库会被转换为 /etc/pgbackrest/pgbackrest.conf 配置文件中的仓库定义。
例如,如果您定义了一个美西区的 S3 仓库用于存储冷备份,可以使用下面的参考配置。
s3 : # ------> /etc/pgbackrest/pgbackrest.conf
repo1-type : s3 # ----> repo1-type=s3
repo1-s3-region : us-west-1 # ----> repo1-s3-region=us-west-1
repo1-s3-endpoint : s3-us-west-1.amazonaws.com # ----> repo1-s3-endpoint=s3-us-west-1.amazonaws.com
repo1-s3-key : '<your_access_key>' # ----> repo1-s3-key=<your_access_key>
repo1-s3-key-secret : '<your_secret_key>' # ----> repo1-s3-key-secret=<your_secret_key>
repo1-s3-bucket : pgsql # ----> repo1-s3-bucket=pgsql
repo1-s3-uri-style : host # ----> repo1-s3-uri-style=host
repo1-path : /pgbackrest # ----> repo1-path=/pgbackrest
repo1-bundle : y # ----> repo1-bundle=y
repo1-cipher-type : aes-256-cbc # ----> repo1-cipher-type=aes-256-cbc
repo1-cipher-pass : pgBackRest # ----> repo1-cipher-pass=pgBackRest
repo1-retention-full-type : time # ----> repo1-retention-full-type=time
repo1-retention-full : 90 # ----> repo1-retention-full=90
恢复 您可以直接使用以下封装命令可以用于 PostgreSQL 数据库集群的 时间点恢复 。
Pigsty 默认使用增量差分并行恢复,允许您以最快速度恢复到指定时间点。
pg-pitr # 恢复到WAL存档流的结束位置(例如在整个数据中心故障的情况下使用)
pg-pitr -i # 恢复到最近备份完成的时间(不常用)
pg-pitr --time= "2022-12-30 14:44:44+08" # 恢复到指定的时间点(在删除数据库或表的情况下使用)
pg-pitr --name= "my-restore-point" # 恢复到使用 pg_create_restore_point 创建的命名恢复点
pg-pitr --lsn= "0/7C82CB8" -X # 在LSN之前立即恢复
pg-pitr --xid= "1234567" -X -P # 在指定的事务ID之前立即恢复,然后将集群直接提升为主库
pg-pitr --backup= latest # 恢复到最新的备份集
pg-pitr --backup= 20221108-105325 # 恢复到特定备份集,备份集可以使用 pgbackrest info 列出
pg-pitr # pgbackrest --stanza=pg-meta restore
pg-pitr -i # pgbackrest --stanza=pg-meta --type=immediate restore
pg-pitr -t "2022-12-30 14:44:44+08" # pgbackrest --stanza=pg-meta --type=time --target="2022-12-30 14:44:44+08" restore
pg-pitr -n "my-restore-point" # pgbackrest --stanza=pg-meta --type=name --target=my-restore-point restore
pg-pitr -b 20221108-105325F # pgbackrest --stanza=pg-meta --type=name --set=20221230-120101F restore
pg-pitr -l "0/7C82CB8" -X # pgbackrest --stanza=pg-meta --type=lsn --target="0/7C82CB8" --target-exclusive restore
pg-pitr -x 1234567 -X -P # pgbackrest --stanza=pg-meta --type=xid --target="0/7C82CB8" --target-exclusive --target-action=promote restore
在执行 PITR 时,您可以使用 Pigsty 监控系统观察集群 LSN 位点状态,判断是否成功恢复到指定的时间点,事务点,LSN 位点,或其他点位。
3.5.1 - 时间点恢复的工作原理 本文解释 PITR 的工作机制,帮助您建立正确的心智模型:基础备份、WAL 归档、恢复窗口与事务边界
时间点恢复(PITR)的核心原理是:基础备份 + WAL 归档 = 任意时间点恢复能力 。
在 Pigsty 中,这一能力由 pgBackRest 实现,并通过 定时备份 + WAL 归档 自动运行。
三要素 要素 作用 Pigsty 实现 基础备份 提供一致的物理快照,决定恢复起点 pg-backup + pgbackrest + pg_crontabWAL 归档 记录备份后的所有变更,决定恢复路径 archive_mode=on + archive_command=pgbackrest ... archive-push恢复目标 指定恢复停止位置 pg_pitr 参数 / pg-pitr 脚本 / pgbackrest restore
基础备份 基础备份 是数据库在某一时刻的物理快照,是 PITR 的恢复起点。Pigsty 通过 pgBackRest 生成基础备份,并提供 pg-backup 脚本封装常用操作。
备份类型 类型 说明 恢复开销 全量备份 (Full)复制全部数据文件 恢复最快,空间占用最大 差异备份 (Differential)相对最近一次全量备份的变化 恢复需要全量 + 差异 增量备份 (Incremental)相对最近一次任意备份的变化 空间最省,恢复需要完整链路
Pigsty 的默认行为 pg-backup 默认执行增量备份 ,若不存在全量备份会自动补一次全量。备份任务通过 pg_crontab 配置,写入 postgres 用户的 crontab。 脚本会自动识别节点角色,只有主库实际执行 ,从库会直接退出。 备份频率越高,需要重放的 WAL 越少,恢复速度越快。
更多细节请参阅 备份机制 与 备份策略 。
WAL 归档 WAL (Write-Ahead Log)记录了数据库的每一次变更。PITR 通过持续归档 WAL,确保能够把数据库从基础备份重放到指定时刻。
Pigsty 的归档链路 Pigsty 默认开启 WAL 归档,并将归档动作交给 pgBackRest:
archive_mode = onarchive_command = pgbackrest --stanza=<cluster> archive-push %ppgBackRest 会持续接收 WAL 段文件,并依据保留策略自动清理过期归档。
恢复时,pgBackRest 负责通过 archive-get 拉取所需 WAL。
关键影响 归档延迟 会缩短恢复窗口的右边界。仓库不可用 会导致归档中断,直接影响 PITR 能力。更多细节请参阅 备份机制 与 备份仓库 。
恢复目标与事务边界 PITR 的恢复目标由 PostgreSQL 的 recovery_target_* 系列参数定义,Pigsty 通过 pg_pitr 或 pg-pitr 进行封装。
目标类型 目标类型 参数 说明 常见场景 latest 无 恢复到 WAL 归档流末尾 机房灾难后的最新恢复 time time恢复到指定时间点 误删数据 xid xid恢复到指定事务 ID 错误事务回滚 lsn lsn恢复到指定 LSN 精确回退 name name恢复到命名恢复点 预设检查点 immediate type: immediate第一一致点停止 最快恢复
包含与排除 恢复目标默认是包含 (inclusive)的。
若要回退到目标点之前 ,在 pg_pitr 中设置 exclusive: true,对应 PostgreSQL 的 recovery_target_inclusive = false。
事务边界 PITR 会保留目标点前的已提交事务 ,并回滚未提交事务。
gantt
title 事务边界与恢复目标
dateFormat X
axisFormat %s
section 事务 A
BEGIN → COMMIT (已提交) :done, a1, 0, 2
section 事务 B
BEGIN → 未提交 :active, b1, 1, 4
section 恢复
恢复目标点 :milestone, m1, 2, 0 更多操作细节请参阅 恢复操作 。
恢复窗口 恢复窗口 由两个边界决定:
左边界 :最早可用的基础备份右边界 :最新已归档的 WAL
窗口长短取决于备份频率、备份保留与 WAL 归档保留策略:
local 仓库默认保留 2 个全量备份 ,窗口通常为 24~48 小时 。minio 仓库默认按时间保留 14 天 备份,窗口通常为 1~2 周 。具体策略配置请参阅 备份策略 与 备份仓库 。
时间线 时间线 (Timeline)用于区分不同历史分支。以下操作会生成新时间线:
PITR 恢复 从库提升(Promote) 故障切换(Failover) gitGraph
commit id: "初始状态"
commit id: "写入数据"
commit id: "继续写入"
branch Timeline-2
checkout Timeline-2
commit id: "PITR 恢复点1"
commit id: "新写入"
branch Timeline-3
checkout Timeline-3
commit id: "PITR 恢复点2"
commit id: "继续运行"
checkout main
commit id: "原时间线继续" 当仓库存在多个时间线时,可通过 timeline 指定目标;Pigsty 默认使用 latest。
更多细节请参阅 恢复操作 。
3.5.2 - 时间点恢复的实现架构 Pigsty PITR 的实现架构:pgBackRest、备份仓库与执行机制
Pigsty 使用 pgBackRest 作为 PostgreSQL 备份与恢复引擎,提供开箱即用的时间点恢复(PITR)能力。
本文从架构层面说明:备份由谁执行、数据流向哪里、仓库如何组织、故障切换后如何保持连续性 。
概览 PITR 架构由三条主线构成:备份执行链路 、WAL 归档链路 、恢复执行链路 。
链路 入口 引擎 终点 备份 pg-backup + pg_crontabpgbackrest backup备份仓库 backup/ WAL 归档 PostgreSQL archive_command pgbackrest archive-push备份仓库 archive/ 恢复 pg_pitr / pg-pitr / pgsql-pitr.ymlpgbackrest restore目标数据目录
更多执行细节见 备份机制 与 恢复操作 。
组件与职责 组件 角色 描述 PostgreSQL 数据源 产生数据文件与 WAL 归档流 pgBackRest 备份引擎 执行备份、接收/拉取 WAL、执行恢复 pg-backup 备份入口 Pigsty 封装脚本,执行 pgbackrest backup pg_pitr / pg-pitr 恢复入口 Pigsty 封装参数/脚本,执行 pgbackrest restore 备份仓库 存储后端 保存 backup/ 与 archive/,支持 local / minio / s3 等仓库 pgbackrest_exporter 监控输出 导出备份状态指标,默认监听 9854 端口
数据流 flowchart TB
subgraph cluster["PostgreSQL 集群"]
direction TB
primary["Primary<br/>PostgreSQL"]
pb["pgBackRest"]
cron["pg-backup / pg_crontab"]
end
repo["备份仓库<br/>local / minio / s3"]
restore["恢复目标数据目录"]
cron --> pb
primary -->|base backup| pb
primary -->|WAL archive| pb
pb -->|backup/archive| repo
repo -->|restore/archive-get| pb
pb -->|restore| restore 要点:
备份 由 pg-backup 触发,执行 pgbackrest backup 将基础备份写入仓库。归档 由 PostgreSQL 的 archive_command 触发,持续将 WAL 段写入仓库。恢复 从仓库读取备份与 WAL,通过 pgbackrest restore 重建数据目录。部署与角色 pgBackRest 安装在 所有 PostgreSQL 节点 上,但只有 主库 实际执行备份:
pg-backup 会自动检测节点角色,从库执行时直接退出。发生 故障切换 后,新主库自动接管备份与归档,备份连续性不受影响。 这使得备份链路与高可用拓扑解耦,避免因主从切换导致备份中断。
仓库与隔离 Stanza(集群标识) pgBackRest 使用 stanza 隔离不同集群的备份,Pigsty 将其映射为 pg_cluster:
备份仓库
├── pg-meta/
│ ├── backup/
│ └── archive/
└── pg-test/
├── backup/
└── archive/
仓库类型 Pigsty 通过 pgbackrest_method 选择仓库,通过
pgbackrest_repo 定义仓库参数:
类型 特点 适用场景 local 本地磁盘,恢复最快 开发/测试、单机部署 minio 对象存储,集中式备份 生产环境、异地容灾 s3 云对象存储 云上部署、跨区域容灾
生产环境建议使用远程仓库(MinIO/S3),以避免主机故障导致 数据与备份同时丢失 。
详见 备份仓库 。
配置映射 Pigsty 会将 pgbackrest_repo 定义渲染为 /etc/pgbackrest/pgbackrest.conf。
备份日志位于 /pg/log/pgbackrest/,恢复过程生成临时配置并记录恢复日志。
更多细节请参阅 备份机制 。
可观测性 pgbackrest_exporter 会导出备份状态指标(最近备份时间、类型、大小等),默认启用,监听端口 9854。
您可以通过 pgbackrest_exporter_enabled 控制该组件。
相关文档 3.5.3 - 时间点恢复的策略权衡 PITR 策略设计中的利弊权衡:仓库选择、空间规划与策略推荐
设计 PITR 策略时,最核心的权衡来自三个维度:
备份仓库位置 、恢复窗口长度 、恢复速度与空间成本 。
本文帮助您在这些维度之间做出可操作的选择。
本地 vs 远程 备份仓库的位置是 PITR 策略设计的第一步。
本地仓库 将备份存储在主库本地磁盘(pgbackrest_method = local):
优势
配置简单,开箱即用 恢复速度快(本地 I/O) 无外部依赖 劣势
无异地容灾能力,主机故障时备份可能一同丢失 受限于本地磁盘容量 备份与生产数据位于同一故障域 远程仓库 将备份存储到 MinIO / S3 等对象存储(pgbackrest_method = minio|s3):
优势
异地容灾,备份独立于数据库主机 容量几乎无限,多集群可共享 可配合加密、版本控制等安全策略 劣势
恢复速度受网络带宽影响 依赖对象存储的可用性 部署与运维成本更高 如何选择 场景 推荐仓库 理由 开发测试 local 简单够用,容灾要求低 单机生产 minio / s3 主机故障仍可恢复 集群生产 local + minio 兼顾恢复速度与异地容灾 关键业务 多远程仓库 多地容灾,最高保护
仓库配置细节请参阅 备份仓库 。
空间 vs 窗口 恢复窗口越长,所需存储空间越大。窗口长度由 备份保留策略 + WAL 归档保留 决定。
影响因素 因素 影响 数据库规模 决定全量备份基准空间 变更速率 影响增量备份与 WAL 归档大小 备份频率 频率越高,恢复越快,但空间增长更快 保留时间 保留越久,恢复窗口越长,空间需求越大
直观示例 假设数据库 100GB,每天变更 10GB:
每日全量备份(保留 2 份)
全量备份:100GB × 2 ≈ 200GB WAL 归档:10GB × 2 ≈ 20GB 总计:约 2~3 倍数据库空间 周全量 + 每日增量(保留 14 天)
全量备份:100GB × 2 ≈ 200GB 增量备份:约 10GB × 12 ≈ 120GB WAL 归档:10GB × 14 ≈ 140GB 总计:约 4~5 倍数据库空间 空间与窗口的关系是刚性约束,无法通过配置“同时更长窗口 + 更少空间”。
策略选择 每日全量备份 最简单可靠的策略 ,也是 Pigsty 本地仓库的默认思路:
每天一次全量备份 保留 2 份备份 恢复窗口约 24~48 小时 适用场景:
数据库规模中小(< 500GB) 备份窗口充足 对存储空间不敏感 全量 + 增量备份 空间优化策略 ,适合大库或需要更长恢复窗口:
每周一次全量备份 其他日期执行增量备份 保留 14 天 适用场景:
数据库规模较大 使用对象存储 需要 1~2 周恢复窗口 flowchart TD
A{"数据库大小<br/>< 100GB?"} -->|是| B["每日全量备份"]
A -->|否| C{"数据库大小<br/>< 500GB?"}
C -->|否| D["全量 + 增量备份"]
C -->|是| E{"备份窗口<br/>充足?"}
E -->|是| F["每日全量备份"]
E -->|否| G["全量 + 增量备份"] 推荐配置 开发测试环境 pg_crontab :
- '00 01 * * * /pg/bin/pg-backup full'
pgbackrest_method : local
恢复窗口:24~48 小时 特点:配置最简,成本最低 生产集群 pg_crontab :
- '00 01 * * 1 /pg/bin/pg-backup full'
- '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup'
pgbackrest_method : minio
恢复窗口:7~14 天 特点:异地容灾,适合生产环境 关键业务 双仓库策略 (本地 + 远程):
pgbackrest_method : local
pgbackrest_repo :
local : { path: /pg/backup, retention_full : 2 }
minio : { type: s3, retention_full_type: time, retention_full : 14 }
更多配置细节请参阅 备份策略 与 备份仓库 。
3.5.4 - 时间点恢复的典型场景 PITR 的典型应用场景:误删数据、误删表/库、批量错误、分支恢复与机房级灾难
PITR 的价值不在于“回滚数据库”本身,而在于把不可逆的人为/软件错误变回可恢复的问题 。
它覆盖的场景从“误删一张表”到“整个机房不可用”,本质上解决的是逻辑错误与灾难恢复 。
整体认知(Overview) PITR 解决以下问题:
场景类型 典型问题 推荐策略 恢复目标 误删/误更新数据(DML) DELETE/UPDATE 无条件执行,脚本误操作分支恢复优先 time / xid误删表/库/Schema(DDL) DROP TABLE/DATABASE、错误迁移分支恢复 time / name批量错误/发布事故 Bug 批量污染数据,修复脚本失败 分支恢复 + 验证 time / xid数据审计/问题复盘 需要查看历史状态,核对差异 分支恢复(只读) time / lsn机房级灾难/全量丢失 硬件故障、勒索、机房断电 原地恢复或重建集群 latest / time
一个简单的判断原则 只要写入已经造成业务错误,就应该考虑 PITR 。需要在线验证或只恢复部分数据 → 分支恢复 。必须尽快恢复服务 → 原地恢复 (可接受停机)。flowchart TD
A["发现问题"] --> B{"能否停机?"}
B -->|能| C["原地恢复<br/>最短恢复路径"]
B -->|不能| D["分支恢复<br/>先验证后切换"]
C --> E["恢复成功后重建备份"]
D --> F["验证/导出/切流量"] 场景详情 误删/误更新数据(DML) 典型问题 :
DELETE 缺少 WHERE错误的 UPDATE 覆盖关键字段 批处理脚本逻辑错误导致脏数据扩散 处理思路 :
止损 :暂停相关应用或写入作业,防止数据继续被污染。定位时间点 :结合日志、监控、业务反馈,确定错误发生时间。选择策略 :能停机:原地恢复到错误之前 不能停机:分支恢复,导出正确数据再合并回主库 恢复目标建议 :
有明确事务:xid + exclusive: true 仅知道时间:time + exclusive: true pg_pitr : { xid : "250000" , exclusive : true }
# 或
pg_pitr : { time : "2025-01-15 14:30:00+08" , exclusive : true }
误删表 / 误删库(DDL) 典型问题 :
DROP TABLE / DROP DATABASE执行了错误迁移脚本 清理测试数据时误删生产对象 为何推荐分支恢复 :
DDL 操作不可逆,原地恢复意味着全库回滚 ,风险高。
分支恢复可将误删对象导出并导回原库,影响最小。
推荐流程 :
创建分支集群并 PITR 到误删前 校验表结构/数据正确性 pg_dump 导出目标对象导回生产库 sequenceDiagram
participant O as 原集群
participant B as 分支集群
O->>B: 创建分支集群
Note over B: PITR 到误删之前
B->>O: 导出表/库并导回
Note over B: 验证完成后销毁分支 批量错误 / 发布事故 典型问题 :
某次版本发布写入错误数据 ETL 或批处理作业造成全量污染 修复脚本执行失败或影响范围不清晰 处理原则 :
优先分支恢复 :先验证恢复点,再决定是否切流量对比原库与分支库数据差异,确认影响范围 建议流程 :
确定错误发布的时间窗口 分支恢复到“错误发生前” 校验关键业务表 决定导回部分数据,或整体切流量 这个场景通常需要结合业务复盘,因此分支恢复更安全、更可控。
数据审计 / 问题复盘 典型问题 :
需要查看某一时刻的数据状态 排查“历史正确状态”以比对差异 推荐方式 :分支恢复(只读)
优点 :
不影响生产 可多次尝试不同时间点 适合审计、核对与取证 pg_pitr : { time : "2025-01-15 10:00:00+08" } # 创建只读分支
机房级灾难 / 全量丢失 这是 PITR 的终极兜底场景 。当高可用无法应对时(主从同时不可用、机房断电、勒索攻击),PITR 是最后防线。
关键前提 :
必须使用远程仓库(MinIO/S3) 。
本地仓库在主机故障时会与数据一同丢失,无法恢复。
恢复流程 :
准备新主机或新机房资源 还原集群配置并指向远程仓库 执行 PITR 恢复(通常 latest) 验证数据后恢复服务 ./pgsql-pitr.yml -l pg-meta # 恢复到 WAL 归档末尾
原地恢复 vs 分支恢复 维度 原地恢复 分支恢复 是否停机 需要停机 无需停机 风险 高(直接影响生产) 低(可验证后操作) 复杂度 低 中(需要新集群与数据导出) 推荐场景 快速恢复服务、容灾 误操作恢复、审计、复杂场景
对于绝大多数生产场景,分支恢复是默认推荐策略 。
只有在 必须尽快恢复服务 时,才建议原地恢复。
相关文档 3.6 - 监控系统 Pigsty 的监控系统是如何架构与实现的,被监控的目标对象又是如何被自动纳入管理的。
Pigsty 监控系统由指标、日志与告警三部分组成,默认随部署开箱可用。
它既可以监控由 Pigsty 托管的数据库集群,也可以监控已有 PostgreSQL 集群与外部 RDS 服务。
监控目标 Pigsty 监控覆盖的核心对象包括:
PostgreSQL 集群与实例(SQL 性能、连接、复制、事务、检查点、WAL) 基础设施组件(Grafana、VictoriaMetrics、Alertmanager、Nginx 等) 宿主机节点(CPU、内存、磁盘、网络、内核) 关键中间件(ETCD、MINIO、REDIS、FERRET、JUICE、VIBE 等) 技术栈 纳管方式 Pigsty 支持三种监控纳管方式:
继续阅读 3.7 - 安全合规 认证、授权、加密、审计与合规基线,覆盖数据库与基础设施安全。
Pigsty 的安全目标是 CIA 三元组 :
机密性 :防止未授权访问与泄露完整性 :防止数据被篡改或静默损坏可用性 :防止故障导致业务中断Pigsty 的安全理念:
默认安全 :开箱即用的安全基线,配置少、覆盖广。纵深防御 :多层保护叠加,单点失守不致系统失守。最小权限 :角色与权限模型贯彻最小授权原则。可合规 :安全能力与流程结合即可通过合规检查。默认安全基线(解决什么问题) 安全选项 默认值 解决的问题 密码加密 pg_pwd_enc: scram-sha-256防止弱哈希与明文泄露 数据校验 pg_checksum: true检测静默数据损坏 HBA 分层 管理员外网必须 ssl 防止外网明文访问 本地 CA ca_create: true统一证书信任链 备份恢复 pgbackrest_enabled: true防止误删误改不可恢复 Nginx HTTPS nginx_sslmode: enable防止 Web 入口明文泄露 MinIO HTTPS minio_https: true防止备份链路窃听 OS 基线 SELinux permissive 为强制模式预留基础
默认配置以“可用、可扩展”为先,生产环境应根据合规要求加固。
加固路线图 Pigsty 提供安全增强模板 conf/ha/safe.yml,可快速将默认基线升级到更高安全级别:
强制 SSL 与证书认证 密码强度与过期策略 连接与断开日志 防火墙与 SELinux 加固 本章内容 章节 说明 核心问题 纵深防御 七层安全模型与基线 安全体系整体如何落地? 身份认证 HBA 规则、密码策略、证书认证 如何验证用户身份? 访问控制 角色系统、权限模型、数据库隔离 如何控制用户权限? 加密通信 TLS、本地 CA、证书管理 如何保护传输与证书? 数据安全 校验和、备份、加密与恢复 数据如何完整可恢复? 合规清单 等保三级与 SOC2 对照 如何满足合规要求?
相关话题 3.7.1 - 七层安全模型 Pigsty 的纵深防御模型:从物理到用户的多层安全基线。
安全不是一道墙,而是一座城。Pigsty 采用纵深防御 策略,在七个层次上构建多重保护,即使某一层被突破,仍有其他层提供保护。
这种分层思路解决三类核心风险:
边界被突破 :降低“单点失守导致全盘失守”的概率。内部滥用 :即使内部账号被盗,也能通过最小权限限制破坏范围。不可预期故障 :硬件、软件、人为错误都能被“多层兜底”。概览
L1 物理与介质安全 物理层失守时,唯一的对抗手段是数据本身的自我保护。
解决的问题
Pigsty 支持
数据校验和 :默认开启 pg_checksum: true,可发现坏块/内存错误导致的数据损坏。可选透明加密 :通过 pg_tde 等扩展实现数据静态加密,防止介质泄露。L2 网络安全 控制“谁能接触到服务”,降低攻击面。
解决的问题
Pigsty 支持
防火墙分区 :node_firewall_mode 可启用 zone,内网信任、公网受限。监听收敛 :pg_listen 可限制监听地址,避免全网暴露。TLS 能力 :HBA 支持 ssl/cert,保证连接加密与身份校验。L3 边界安全 “统一入口”是可审计、可控制、可封禁的基础。
解决的问题
Pigsty 支持
HAProxy 入口 :数据库流量统一入口,便于封禁/限流/切换。Nginx 网关 :基础设施服务统一 HTTPS 入口(nginx_sslmode)。集中管理口令 :HAProxy 管理口令、Grafana 管理口令统一在配置中声明。L4 主机安全 数据库安全的地基:最小权限、访问隔离、系统加固。
解决的问题
Pigsty 支持
SELinux 模式 :node_selinux_mode 可切换 enforcing 强制模式。最小权限管理员 :node_admin_sudo 支持 limit 限制 sudo 命令集。敏感文件权限 :CA 私钥目录默认 0700,私钥文件 0600。L5 应用安全 认证是所有数据库安全的“第一道闸门”。
解决的问题
Pigsty 支持
HBA 分层控制 :默认规则按来源与角色分层,管理员外网访问必须 ssl。SCRAM 密码哈希 :pg_pwd_enc: scram-sha-256 默认启用。密码强度检查 :passwordcheck/credcheck 可启用,阻止弱口令。证书认证 :auth: cert 支持客户端证书认证。L6 数据安全 保障数据在“可用、可恢复、可追责”。
解决的问题
Pigsty 支持
pgBackRest 备份 :默认启用,支持本地与 MinIO 仓库。备份加密 :MinIO 仓库支持 AES-256-CBC(cipher_type)。PITR 恢复 :结合归档可恢复到任意时间点。审计日志 :模板启用 DDL/连接/慢查询日志,可选 pgaudit。L7 用户安全 最小权限不是口号,而是默认行为。
解决的问题
Pigsty 支持
四层 RBAC :dbrole_readonly/readwrite/admin/offline。默认权限策略 :对象创建即自动授予正确权限。数据库隔离 :revokeconn: true 可隔离跨库访问。公共权限收敛 :撤销 public 模式 CREATE 权限。安全加固路径 Pigsty 提供安全增强模板:conf/ha/safe.yml。它将常见加固项集中封装:
强制 SSL、证书认证 密码强度与过期策略 连接与断开日志 防火墙与 SELinux 加固 这条路径可以作为“从默认到合规”的快速升级方案。
接下来 3.7.2 - 身份认证 HBA 规则、密码策略与证书认证,回答“谁能连进来、如何证明身份”。
身份认证解决三个核心问题:
你是谁 :身份是否唯一可识别?你怎么证明 :密码/证书是否足够安全?你从哪里来 :来源是否受控?Pigsty 使用 HBA 规则 + 密码/证书 完成身份认证,并以 SCRAM 为默认密码哈希方案。
认证链路 flowchart LR
C[客户端] --> HBA[HBA 规则]
HBA --> A1[密码 SCRAM]
HBA --> A2[证书认证]
HBA --> A3[本地 ident/peer]
A1 --> RBAC[角色与权限]
A2 --> RBAC
A3 --> RBAC HBA 决定“谁能从哪里来 ”,认证方式决定“如何证明身份 ”。
HBA 分层模型 Pigsty 默认 HBA 规则已经分层:
本地 使用 ident/peer,最安全。内网 使用 scram 密码认证。外网管理员 必须走 ssl。这解决了“同一个用户在不同来源使用不同认证强度 ”的问题。
HBA 规则的关键能力
顺序优先 :支持 order 排序,数值越小优先级越高。地址别名 :local / localhost / intra / world 等。角色条件 :primary/replica/offline 可精细化控制。密码认证 默认密码哈希算法:
pg_pwd_enc : scram-sha-256
解决的问题
兼容性
如需兼容老客户端可使用 md5,但会降低安全性。
密码强度与轮换 Pigsty 支持启用密码强度检查扩展:
pg_libs : '$libdir/passwordcheck, pg_stat_statements, auto_explain'
pg_extensions : [ passwordcheck, credcheck ]
通过 expire_in 控制账号过期时间:
pg_users :
- { name: dbuser_app, password: 'StrongPwd', expire_in : 365 }
解决的问题
证书认证 证书认证解决“密码被钓鱼/被拷贝 ”的风险。
HBA auth: cert 要求客户端证书。 证书 CN 通常对应数据库用户名。 Pigsty 内置 cert.yml 用于签发客户端证书。 PgBouncer 认证 PgBouncer 使用独立 HBA 规则与 TLS 设置:
pgbouncer_sslmode : disable # 默认关闭,可设为 require/verify-full
pgb_default_hba_rules : [ ...] # 独立规则
这解决了“连接池入口与数据库入口不同步”的问题。
默认账号与风险 用户 默认密码 风险 dbuser_dbaDBUser.DBA管理账号默认密码 dbuser_monitorDBUser.Monitor监控账号易被滥用 replicatorDBUser.Replicator复制账号被滥用可导致数据外泄
生产环境必须修改默认密码。
安全建议 对外入口全部启用 ssl/cert。 内网用户使用 scram,避免 md5。 启用 passwordcheck 强制复杂度。 定期轮换口令(expire_in)。 接下来 3.7.3 - 访问控制 Pigsty 提供开箱即用的角色与权限模型,贯彻最小权限原则。
访问控制解决两个核心问题:
你能做什么 :读/写/DDL 的权限边界你能访问哪些数据 :跨库、跨模式的隔离边界Pigsty 通过 RBAC 角色体系 + 默认权限策略 将“最小权限”落实为默认行为。
四层角色模型 flowchart TB
subgraph Admin["dbrole_admin(管理员)"]
A1["可执行 DDL / CREATE / ALTER"]
A2["继承 dbrole_readwrite"]
end
subgraph RW["dbrole_readwrite(读写)"]
RW1["可 INSERT/UPDATE/DELETE"]
RW2["继承 dbrole_readonly"]
end
subgraph RO["dbrole_readonly(只读)"]
RO1["可 SELECT 所有表"]
end
subgraph Offline["dbrole_offline(离线)"]
OFF1["仅离线实例可用"]
end
Admin --> RW --> RO 解决的问题
生产账号天然拥有过高权限 DDL 与 DML 不分离导致误操作风险 默认角色与系统用户 Pigsty 默认提供四个角色与四个系统用户(来自源码默认值):
角色/用户 属性 继承/角色 描述 dbrole_readonlyNOLOGIN- 全局只读访问 dbrole_offlineNOLOGIN- 受限只读(离线实例) dbrole_readwriteNOLOGINdbrole_readonly全局读写访问 dbrole_adminNOLOGINpg_monitor, dbrole_readwrite管理员 / 对象创建 postgresSUPERUSER- 系统超级用户 replicatorREPLICATIONpg_monitor, dbrole_readonly复制用户 dbuser_dbaSUPERUSERdbrole_admin管理员用户 dbuser_monitor- pg_monitor, dbrole_readonly监控用户
这套默认角色可以覆盖绝大多数业务场景。
默认权限策略 Pigsty 在初始化时写入默认权限(pg_default_privileges),确保新建对象自动具备合理权限。
解决的问题
新建对象未授权导致应用不可用 误授权给 PUBLIC 导致全库暴露 思路
只读角色:SELECT/EXECUTE 读写角色:INSERT/UPDATE/DELETE 管理员角色:DDL 权限 对象所有权与 DDL 规范 默认权限仅对“管理员角色创建的对象 ”自动生效。
这意味着:
必须使用 dbuser_dba/postgres 执行 DDL 或业务管理员先 SET ROLE dbrole_admin 否则新对象会脱离默认权限体系,破坏最小权限原则。
数据库隔离 数据库级别支持 revokeconn,可做到跨库隔离:
pg_databases :
- { name: appdb, owner: dbuser_app, revokeconn : true }
解决的问题
一个账号可以“穿透”访问所有数据库 多租户数据库缺乏边界 公共权限收敛 Pigsty 初始化时撤销 public 模式的 CREATE 权限:
REVOKE CREATE ON SCHEMA public FROM PUBLIC;
解决的问题
非授权用户随意创建对象 “影子表/影子函数”带来的安全风险 离线角色的作用 dbrole_offline 只能访问离线实例(pg_role=offline 或 pg_offline_query=true)。
解决的问题
ETL/分析任务影响生产性能 个人账号在主库执行高危查询 最佳实践 业务账号默认使用 dbrole_readwrite 或 dbrole_readonly。 生产 DDL 必须经由管理员角色。 多租户业务启用 revokeconn 隔离。 报表/ETL 使用 dbrole_offline。 接下来 3.7.4 - 加密通信与本地 CA Pigsty 内置自签 CA,签发 TLS 证书并加密通信流量。
加密通信解决三个问题:
窃听 :防止明文流量被监听篡改 :防止中间人修改数据冒充 :防止服务端/客户端被伪造Pigsty 通过 本地 CA + TLS 为数据库与基础设施组件提供统一的信任根。
本地 CA 的作用 Pigsty 默认会在管理节点生成自签 CA:
files/pki/ca/ca.key # CA 私钥(必须严格保护)
files/pki/ca/ca.crt # CA 根证书(可分发)
源码默认值:
ca_create: true:找不到 CA 时自动生成。ca_cn: pigsty-ca:CA 证书 CN 固定为 pigsty-ca。根证书有效期约 100 年(自签)。 由 CA 签发的服务器/客户端证书有效期 cert_validity: 7300d(20 年)。 证书覆盖范围 本地 CA 会签发多种组件证书,统一信任链:
组件 目的 典型路径 PostgreSQL / PgBouncer 连接加密 /pg/cert/Patroni API 通信 /pg/cert/etcd DCS 加密 /etc/etcd/MinIO 对象存储 HTTPS ~minio/.minio/certs/Nginx Web 入口 HTTPS /etc/nginx/conf.d/cert/
解决的问题 :不同组件自建证书会产生信任碎片,统一 CA 可以一次分发,多处复用。
信任分发 Pigsty 安装时会将 ca.crt 分发到所有节点并加入系统信任:
证书路径:/etc/pki/ca.crt EL 系列:/etc/pki/ca-trust/source/anchors/ Debian/Ubuntu:/usr/local/share/ca-certificates/ 这样可以让系统内的客户端自动信任 Pigsty 签发的证书。
使用外部 CA 如果你已有企业 CA,可以直接替换:
files/pki/ca/ca.key
files/pki/ca/ca.crt
建议设置:
解决的问题 :防止系统误生成新的自签 CA,导致证书信任链混乱。
客户端证书认证 证书认证可以替代或增强密码认证:
Pigsty 自带 cert.yml 用于签发客户端证书:
./cert.yml -e cn = dbuser_dba
./cert.yml -e cn = dbuser_monitor
默认生成在:
files/pki/misc/<cn>.key
files/pki/misc/<cn>.crt
密钥保护与轮换 CA 私钥默认 0600 权限,并在 0700 目录中保存。 一旦 CA 私钥泄露,必须重新生成 CA 并重签所有证书。 建议在重大升级或密钥泄露事件后进行证书轮换。 接下来 3.7.5 - 数据安全 数据完整性、备份与恢复、加密与审计。
数据安全关注三件事:完整性、可恢复性、保密性 。Pigsty 在默认配置中已启用关键能力,并支持按需加固。
数据完整性 解决的问题
磁盘坏块、内存错误导致的静默损坏 意外写入导致的数据污染 Pigsty 支持
数据校验和 :默认 pg_checksum: true,初始化时启用 data-checksums。副本兜底 :主库坏块可从从库恢复(与 HA 配合使用)。可恢复性(备份与 PITR) 解决的问题
Pigsty 支持
pgBackRest 默认启用 :pgbackrest_enabled: true。本地仓库 :默认保留 2 份完整备份。远程仓库 :可接入 MinIO,支持对象存储与多副本。PITR :结合 WAL 归档进行任意时间点恢复。数据保密性 解决的问题
Pigsty 支持
备份加密 :MinIO 仓库支持 AES-256-CBC(cipher_type)。透明加密(可选) :通过 pg_tde 等扩展实现数据静态加密。密钥隔离 :建议将 cipher_pass 与 CA 私钥分离管理。审计与可追溯 解决的问题
Pigsty 支持
日志收集 :模板默认启用 logging_collector。DDL 审计 :log_statement: ddl。慢查询 :log_min_duration_statement。连接日志 :log_connections(PG18+)。审计扩展 :pgaudit、pgauditlogtofile 可选。加固建议 对远程备份强制加密与专用密钥。 定期演练 PITR,验证恢复链路。 对关键业务启用 pgaudit。 结合 高可用 形成“备份 + 副本”双层兜底。 接下来 3.7.6 - 合规清单 以 SOC2 与等保三级为切入点,映射 Pigsty 安全能力与证据准备。
合规不是“开关”,而是 配置 + 流程 + 证据 的组合:
配置 :安全能力是否启用(HBA/TLS/审计/备份)流程 :是否有权限管理、变更、备份演练等制度证据 :日志、配置快照、备份报告、监控告警本页以 SOC2 与等保三级为切入点,说明 Pigsty 的安全能力与合规映射。
默认凭证清单(必须修改) 来自源码默认值:
组件 默认用户名 默认密码 PostgreSQL 管理员 dbuser_dbaDBUser.DBAPostgreSQL 监控 dbuser_monitorDBUser.MonitorPostgreSQL 复制 replicatorDBUser.ReplicatorPatroni API postgresPatroni.APIHAProxy 管理 adminpigstyGrafana 管理 adminpigstyMinIO Root minioadminS3User.MinIOetcd Root rootEtcd.Root
生产环境必须修改。
证据准备(建议) 证据类型 说明 Pigsty 支持 配置快照 HBA、角色、TLS、备份策略 pigsty.yml / inventory 配置访问控制 角色与权限 pg_default_roles / pg_default_privileges连接审计 连接、断开、DDL log_connections / log_statement备份报告 完整备份与恢复记录 pgBackRest 日志与任务 监控告警 异常事件记录 Prometheus + Grafana 证书管理 CA/证书分发记录 files/pki/ / /etc/pki/ca.crt
SOC2 视角(示例映射) SOC2 的核心是 安全、可用性、机密性 。以下为常见控制点的概念映射:
控制点(SOC2) 解决的问题 Pigsty 能力 需要流程 CC6 逻辑访问控制 未授权访问 HBA + RBAC + 默认权限 权限审批与定期审计 CC6 认证强度 弱口令/复用 SCRAM + passwordcheck 密码轮换策略 CC6 传输加密 明文传输 TLS/CA、ssl/cert 强制 TLS 政策 CC7 系统监控 异常未发现 Prometheus/Grafana 告警处理流程 CC7 审计追踪 无法追责 连接/DDL/慢查日志、pgaudit 日志留存与审查 CC9 业务连续性 数据不可恢复 pgBackRest + PITR 定期恢复演练
以上为概念映射,实际 SOC2 需要配合组织制度与审计证据。
等保三级(GB/T 22239-2019)映射 等保三级关注“身份鉴别、访问控制、审计、数据安全、通信安全、主机安全、网络边界”等。以下为核心控制点与 Pigsty 能力的对应关系:
控制点 解决的问题 Pigsty 能力 需要配置/流程 身份鉴别唯一性 账号混用 唯一用户 + SCRAM 账号管理流程 口令复杂度 弱口令 passwordcheck/credcheck启用扩展 口令定期更换 长期风险 expire_in密码轮换制度 访问控制 越权访问 RBAC + 默认权限 权限审批 最小权限 权限膨胀 四层角色模型 账号分级 通信保密性 明文泄露 TLS/CA、HBA ssl/cert 强制 TLS 安全审计 无法追责 连接/DDL/慢查日志 + pgaudit 日志留存 数据完整性 静默损坏 pg_checksum: true- 数据备份恢复 数据丢失 pgBackRest + PITR 演练与验收 主机安全 主机被攻破 SELinux/防火墙 加固策略 边界安全 暴露入口 HAProxy/Nginx 统一入口 网络分区 安全管理制度 缺乏流程 - 制度与审批
提示 :等保三级不仅是技术问题,还需要完善的制度与运维流程支撑。
合规加固配置片段 # 强制 SSL / 证书
pg_hba_rules :
- { user: '+dbrole_readonly', db: all, addr: intra, auth : ssl }
- { user: dbuser_dba, db: all, addr: world, auth : cert }
# 密码强度
pg_libs : '$libdir/passwordcheck, pg_stat_statements, auto_explain'
pg_extensions : [ passwordcheck, credcheck ]
# PgBouncer / Patroni TLS
pgbouncer_sslmode : require
patroni_ssl_enabled : true
# 操作系统安全
node_firewall_mode : zone
node_selinux_mode : enforcing
合规检查清单 部署前 部署后(必做) 定期维护 接下来 4 - 上手 在你的笔记本/云服务器上部署 Pigsty 单机版本,访问数据库以及 Web 用户界面
Pigsty 采用可伸缩的架构设计,既可用于 超大规模生产环境 ,也可用于 单机开发演示环境 ,本文关注后者。
如果您打算学习了解 Pigsty,可以从 快速上手 单机部署开始。一台 1C/2G 的 Linux 虚拟机即可运行 Pigsty。
您可以利用一台 Linux MiniPC,云厂商提供的免费/优惠虚拟机,Windows 的 WSL,或者在自己的笔记本上创建虚拟机用于 Pigsty 部署。
Pigsty 提供了开箱即用的 Vagrant 模板与 Terraform 模版,可以帮助您一键在本地或云端置备 Linux 虚拟机。
单机版本的 Pigsty 包含了所有核心功能,510 个 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 数据库服务 ;或者进行 配置定制 并 执行剧本 部署更多集群。
4.1 - 快速上手 Pigsty 单机部署 快速上手 Pigsty,从一台全新的 Linux 主机开始,完成单机安装部署!
本文是 Pigsty 单节点安装指南,生产环境的多节点高可用部署请参考 部署 文档。
Pigsty 单机安装分为三步走:安装 ,配置 与 部署 。
摘要 准备 一台具有 SSH 权限 的 节点 ,
安装 兼容的 Linux 系统 ,使用具有免密 ssh 和 sudo 权限的 管理用户 执行:
pigsty.cc(中国)
pigsty.io(全球) curl -fsSL https://repo.pigsty.cc/get | bash;
curl -fsSL https://repo.pigsty.io/get | bash;
该命令会执行 安装 脚本,下载并提取 Pigsty 源码至家目录并安装依赖,接下来依次完成 配置 与 部署 即可完成交付。
cd ~/pigsty # 进入 Pigsty 目录
./configure -g # 生成配置文件(可选,如果知道如何配置可以跳过)
./deploy.yml # 执行部署剧本,根据生成的配置文件开始安装
安装完成后,您可以通过 IP / 域名 + 80/443 端口访问 Web 用户界面 ,
并通过 5432 端口访问 PostgreSQL 服务 。
完整流程根据服务器规格/网络条件需 3~10 分钟,离线安装 时能够显著加速;无需监控时可使用 精简安装 进一步加速。
视频样例:在线单机安装(Debian 13, x86_64)
准备 安装 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.cc(中国)
pigsty.io(全球) curl -fsSL https://repo.pigsty.cc/get | bash # 安装当前默认版本
curl -fsSL https://repo.pigsty.cc/get | bash -s v4.3.0 # 安装特定版本(示例:v4.3.0)
curl -fsSL https://repo.pigsty.io/get | bash # 安装当前默认版本
curl -fsSL https://repo.pigsty.io/get | bash -s v4.3.0 # 安装特定版本(示例:v4.3.0)
如果您不希望执行远程脚本,可以手动 下载 或克隆源码。使用 git 克隆安装时,请务必检出特定版本后再使用。
git clone https://github.com/pgsty/pigsty; cd pigsty;
git checkout v4.3.0; # 使用 git 安装时,请务必检出特定版本(示例:v4.3.0)
手工下载克隆安装时,请额外执行 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 替换和探测
配置 / configure 过程的样例输出 vagrant@meta:~/pigsty$ ./configure
configure pigsty v4.3.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 = vagrant@127.0.0.1 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 = vagrant@10.10.10.10 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当前主机的首要内网 IP 地址,用于替换配置文件中的 IP 地址占位符 10.10.10.10 -c|--conf用于指定使用的 配置模板 ,相对于 conf/ 目录,不带 .yml 后缀的配置名称 -v|--version用于指定要安装的 PostgreSQL 大版本,如 13、14、15、16、17、18 -r|--region用于指定上游软件源的区域,加速下载: (default|china|europe) -n|--non-interactive直接使用命令行参数提供首要 IP 地址,跳过交互式向导 -x|--proxy使用当前环境变量配置 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 。
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 、FERRET 、DOCKER ……
4.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_passwordPostgreSQL 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 版本一致:v4.3.0、latest 等 镜像内已预生成 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 = <version> # 镜像版本标签(示例:v4.3.0 或 latest)
PIGSTY_SSH_PORT = 2222 # SSH 端口
PIGSTY_HTTP_PORT = 8080 # Nginx HTTP 端口
PIGSTY_HTTPS_PORT = 8443 # Nginx HTTPS 端口
PIGSTY_PG_PORT = 5432 # PostgreSQL 端口
端口映射说明 :
环境变量 默认值 容器端口 说明 PIGSTY_VERSION<version>- 镜像版本标签(如 v4.3.0 / latest) PIGSTY_SSH_PORT222222 SSH 访问端口 PIGSTY_HTTP_PORT808080 Nginx HTTP 端口 PIGSTY_HTTPS_PORT8443443 Nginx HTTPS 端口 PIGSTY_PG_PORT54325432 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 # 删除容器并清空数据(会提示确认)
手动运行 如果您不想使用 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 # 删除容器并清空数据
原理 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 # 删除容器并清空数据(会提示确认)
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 安装 离线安装 :离线安装 生产部署 :部署指南 4.3 - 从浏览器访问图形用户界面 探索 Pigsty 提供的 Web 图形管理界面,Grafana 大盘,以及如何通过域名和 HTTPS 访问它们。
Pigsty 单机安装 完成后,您在当前节点上将安装有 INFRA 模块,它带有一套开箱即用的 Nginx Web 服务器。
其中的默认服务器配置提供了一个 WebUI 图形界面,用于展示监控仪表盘,并统一代理访问其他组件的 Web 界面。
访问 您可以通过在浏览器中键入部署节点 IP 地址来访问这个图形界面。在默认配置下,Nginx 将通过 80/443 标准端口对外提供服务。
监控 要访问 Pigsty 的监控系统大盘(Grafana),您可以访问服务器的 /ui 端点。
如果您的服务对互联网与办公网开放,我们建议您通过 域名 访问,并启用 HTTPS 加密,只需要少量配置工作即可实现。
端点 在默认配置下,Nginx 会在 80/443 端口的默认服务器上,通过不同的路径暴露以下端点:
域名访问 如果您有自己的域名,可以将其解析到 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.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.2 ( Ubuntu 18.2-1.pgdg24.04+2))
Type "help" for help.
postgres = #
您也可以切换为操作系统的 postgres 用户,直接执行 psql 命令,即可连接到默认的 postgres 管理数据库上。
连接数据库 想要访问 PostgreSQL 数据库,您需要使用 命令行工具 或者 图形化客户端 工具,填入 PostgreSQL 的 连接字符串 :
postgres://username:password@host:port/dbname
一些驱动和工具也可能会要求你分别填写这些参数,通常以下五项为必选项:
参数 说明 示例值 备注 host数据库服务器地址 10.10.10.10换为你的节点 IP 地址或域名,本机可以省略 port端口号 5432PG 默认端口,可以省略 username用户名 dbuser_dbaPigsty 默认的数据库管理员 password密码 DBUser.DBAPigsty 默认的管理员密码,(请修改密码 ) dbname数据库名 meta默认模板的数据库名称
个人使用时可以直接使用 Pigsty 默认的数据库超级用户 dbuser_dba 进行连接和管理,数据库管理用户 dbuser_dba 拥有数据库的全部权限。
默认情况下,如果您在配置 Pigsty 时指定了 configure -g 参数,密码会随机生成,并保存在 ~/pigsty/pigsty.yml 文件中,可以通过以下命令查看:
cat ~/pigsty/pigsty.yml | grep pg_admin_password
默认账号密码 Pigsty 的默认 单机模板 默认配置预置了以下数据库用户,可以开箱即用:
用户名 密码 角色 用途 dbuser_dbaDBUser.DBA超级用户 数据库管理(请修改密码 ) dbuser_metaDBUser.Meta业务管理员 应用读写(请修改密码 ) dbuser_viewDBUser.Viewer只读用户 数据查阅(请修改密码 )
例如,你可以通过三个不同的连接串,使用三个不同的用户连接到 pg-meta 集群的 meta 数据库:
postgres://dbuser_dba:DBUser.DBA@10.10.10.10:5432/meta
postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
postgres://dbuser_view:DBUser.Viewer@10.10.10.10:5432/meta
请注意,这些默认密码会在 configure -g 时自动被替换为随机强密码,请注意将 IP 地址和密码替换为实际值。
使用命令行工具 psql 是 PostgreSQL 官方命令行客户端工具,功能强大,是 DBA 和开发者的首选工具。
在部署了 Pigsty 的服务器上,你可以直接使用 psql 连接本地数据库:
# 最简单的方式:使用 postgres 系统用户本地连接(无需密码)
sudo -u postgres psql
# 使用连接字符串(推荐,通用性最好)
psql 'postgres://dbuser_dba:DBUser.DBA@10.10.10.10: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.2)
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 提供了 PG 生态中独一无二的 510 扩展 ,涵盖时序、地理、向量、全文检索等 16 大类别,一键安装即可使用。
你可以先从三个最强大常用的功能扩展开始,然后按需 加装 timescaledb 等更多扩展。
\ dx -- psql 元命令,列出已经安装的扩展
TABLE pg_available_extensions ; -- 查询已经安装,可以启用的扩展
CREATE EXTENSION postgis ; -- 启用 postgis 扩展
下一步 恭喜你完成了 PostgreSQL 的基础上手!下一步,你可以开始对你的数据库进行一些 配置与定制 。
4.5 - 通过配置清单定制 Pigsty 部署 使用声明式的配置文件,表达你需要的基础设施与集群。
除了使用 配置向导 自动生成配置,您也可以从零开始手工编写 Pigsty 配置文件。
本教程将指导您从头开始,逐步构建一个复杂的 配置清单 。
如果您事先就在 配置清单 中定义好了一切,那么只要 deploy.yml 剧本一把梭,即可完成所有部署工作,但它隐藏了所有细节。
所以本文档会把所有模块与剧本拆解开来,介绍如何从一个简单的配置,通过增量添加的方式,形成一套复杂完备的部署。
最小配置 最简单的有效配置文件可能如下所示,唯一的内容是定义 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 管理”,调整至默认配置描述的状态。
加入基础设施 一套功能完备的 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 模块)
只要 IP 地址存在,NODE 模块会隐含定义。NODE 模块也是幂等的,即使重复执行一次,也没有什么副作用。
安装完成后,您将拥有一套完整的可观测性基础设施,以及节点监控功能,但 PostgreSQL 数据库服务尚未部署。
如果您的目的就是设置这一套监控系统(Grafana + Victoria),那么到此为止就大功告成了!infra 模板就是为此设计的。
Pigsty 中的一切都是 模块化 的:您可以只部署监控基础设施,而不部署数据库服务;
或者反过来 —— 在没有基础设施的情况下,运行高可用 PostgreSQL 集群 —— 精简安装 。
部署数据库集群 要提供 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 服务了!
至此,我们用 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 }
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,以及多达 510 种 扩展插件 。让我们卸载当前默认的 PG 18,并安装 PG 16:
./pgsql-rm.yml -l pg-meta # 移除旧的 pg-meta 集群(因为它是 PG 18)
我们可以通过定制参数,让集群默认安装并启用一些常用的扩展:timescaledb、postgis 和 pgvector:
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
部署高可用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 }
部署 Redis 集群 Pigsty 提供了可选的 Redis 支持,可作为 PostgreSQL 前端的缓存服务。
bin/redis-add redis-ms
bin/redis-add redis-meta
bin/redis-add redis-test
Redis 高可用设置需要使用集群模式或哨兵模式,详情请参阅 Redis 配置 。
部署 MinIO 集群 Pigsty 提供了可选的开源对象存储,S3 替代 —— MinIO 支持,可作为 PostgreSQL 的 备份存储仓库 。
严肃的生产环境 MinIO 部署通常需要至少 4 个节点,每个节点配备 4 块硬盘(4N/16D)。
部署 Docker 模块 如果您想要使用容器运行一些 管理 PG 的工具 或者 使用 PostgreSQL 的软件 ,可以安装 DOCKER 模块。
你可以使用预制的应用配置模板,一键拉起一些常见的软件工具,例如用于 PG 管理的 GUI 工具: Pgadmin :
./app.yml -l infra -e app = pgadmin
甚至,您还可以用 Pigsty 自建 企业级质量的 Supabase ,使用外面的高可用 PostgreSQL 集群作为底座,将无状态的部分运行在容器之中。
4.6 - 使用 Ansible 剧本完成部署 使用 Ansible 剧本部署与管理 Pigsty 集群
Pigsty 使用 Ansible 对集群进行管理,这是在 SRE 群体中非常流行的大规模/批量化/自动化运维工具。
Ansible 可以使用 声明式 的方式对服务器进行配置管理,所有模块的部署都是通过一系列幂等的 Ansible 剧本 实现的。
例如,在单机部署时,您会用到 deploy.yml 剧本。Pigsty 还有更多 内置剧本 ,您可以根据需要选择使用。
了解 Ansible 基础知识有助于更好的使用 Pigsty,但这 并非必须 ,特别是在单机部署时。
部署剧本 Pigsty 提供了一个 “一条龙” 部署剧本 deploy.yml ,一次性在当前环境上安装所有模块(如果在配置中定义):
Playbook 命令 分组 infra[nodes]etcdminio[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
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
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_purge # 销毁 ETCD 集群
./minio.yml -t minio_alias # 写入 MinIO CLI 配置
要运行多个任务,指定多个标签并用逗号分隔 -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 部署
便捷脚本 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 中的 内置剧本 ,您也轻松添加自己的剧本,或者按需定制修改剧本的实现逻辑。
4.7 - 离线安装 在没有互联网访问的环境中,使用离线安装包安装 Pigsty
Pigsty 默认从互联网上游 安装 所需软件包,但有些环境与互联网隔离。
为了解决这个问题,Pigsty 支持使用 离线软件包 进行离线安装。
您可以将其视作 Linux- 原生版本的 Docker 镜像。
概览 离线软件包 打包了所有需要的 RPM/DEB 软件包及其依赖;它是常规 安装 后的本地 APT / YUM 仓库的快照。
在 严肃的生产环境部署 中,我们 强烈推荐 您使用离线安装包进行安装。
它可以确保后续所有新节点的软件版本与现有环境保持一致,
并且可以避免上游变动导致的在线安装失败(相当常见!)
确保您能独立自主运行它至地老天荒。
使用离线软件包的优点
可以简单方便的在互联网隔离的环境中交付实施。 一次性预下载所有软件包,可以有效加速安装过程。 无需担心上游依赖项的变动导致依赖错漏/安装失败。 如果有多个节点,那么所有软件包只需要下载一次,节省带宽资源。 可以通过本地仓库确保所有节点的软件版本一致,实行统一版本管理 使用离线软件包的缺点
离线安装包针对 特定的操作系统小版本制作 ,通常不能跨版本使用 仅为制作时刻的快照,可能不包含最新的更新和操作系统安全补丁。 离线安装包通常约 1GB 左右,而在线安装则是按需下载,更节省空间。 离线软件包 我们通常为以下 Linux 发行版 发布离线软件包,使用较新的操作系统次要版本。
如果您使用的是上述列表中给出的操作系统(精确匹配的小版本),那么建议使用离线软件包。
Pigsty 为这些系统提供了开箱即用的预制离线软件包,在 GitHub 上提供免费下载。
您可以从 GitHub 发布页面 下载对应资产,离线包文件名遵循以下模式;v4.3.0 校验和待正式发布后补充:
b1924a907f3db2411109745cc03f4316 pigsty-pkg-v4.3.0.d12.aarch64.tgz
20b71530b96c8c611dcd6b0a052c67de pigsty-pkg-v4.3.0.d12.x86_64.tgz
e1d0ac623a608c749158803616aaeced pigsty-pkg-v4.3.0.d13.aarch64.tgz
27b6360815ff234db0376338d1ce944f pigsty-pkg-v4.3.0.d13.x86_64.tgz
08cde469c86017c14f808fd127e51a87 pigsty-pkg-v4.3.0.el10.aarch64.tgz
371c1d5229b1584650bda42a570cdc47 pigsty-pkg-v4.3.0.el10.x86_64.tgz
07472f5069f92c96d6b65147e0658c26 pigsty-pkg-v4.3.0.el9.aarch64.tgz
153e2dc5904171975babd1d2dbcce480 pigsty-pkg-v4.3.0.el9.x86_64.tgz
70a3a4faecfc4691ee9b528b8c35ee08 pigsty-pkg-v4.3.0.u22.aarch64.tgz
6968bc55aedcff922cff59b5893f3e12 pigsty-pkg-v4.3.0.u22.x86_64.tgz
59699d34aaaf178a12a044740f4cc56e pigsty-pkg-v4.3.0.u24.aarch64.tgz
935666f192390d52cbde0593e2e253dc pigsty-pkg-v4.3.0.u24.x86_64.tgz
84ef45377c5a6fac7f7285ebd7a71404 pigsty-pkg-v4.3.0.u26.x86_64.tgz
离线软件包是为特定的 Linux 操作系统小版本制作的
当操作系统小版本不匹配时,有概率能用,也有概率失败,我们建议你不要冒险尝试。
请务必注意,Pigsty 提供的 EL9/EL10 安装包基于 9.7 / 10.1 制作,Debian 安装包基于 12.13 / 13.4 制作。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 ,它将从本地仓库安装所有内容
警告
如果你在离线安装时遇到 “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。
混合安装模式
如果您的环境有互联网访问,那么有一种混合方法可以融合离线安装与在线安装的优点。
您可以使用离线软件包作为基础,并在线补足不匹配的增量软件包。
例如,假设您使用的是 RockyLinux 9.6,但官方离线软件包是为 RockyLinux 9.7 制作的。
您可以使用 el9 离线软件包(虽然是针对 9.7 制作的),然后在执行正式安装前,执行 make repo-build 重新下载 9.6 对应的缺失软件包,
Pigsty 将从上游仓库重新下载所需的 增量 。
制作离线软件包 如果您选择的操作系统不在默认列表中,您可以使用内置的 cache.yml 剧本制作自己的离线软件包:
找到一台运行完全相同操作系统版本,且可以访问互联网的节点 使用 rich 配置模板执行 在线安装 (configure -c rich) cd ~/pigsty; ./cache.yml:制作并获取离线软件包到 ~/pigsty/dist/${version}/将离线软件包复制到没有互联网访问的环境中(ftp、scp、usb 等),通过 bootstrap 解包使用 我们提供 付费服务 ,提供经过测试的预制 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
4.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
说明 精简安装只安装/配置以下组件:
组件 必要性 描述 patroni⚠️ 必需 引导高可用 PostgreSQL 集群 etcd⚠️ 必需 Patroni 的元数据库依赖(DCS) pgbouncer✔️ 可选 PostgreSQL 连接池 vip-manager✔️ 可选 L2 VIP 绑定到 PostgreSQL 集群主节点 haproxy✔️ 可选 根据 Patroni 健康检查,自动路由 服务 chronyd✔️ 可选 与 NTP 服务器的时间同步 tuned✔️ 可选 节点调优模板和内核参数管理
你可以通过进一步的配置,关闭所有可选组件,只保留必需组件 patroni 和 etcd。
因为缺少 Infra 模块的 Nginx 提供本地仓库服务,只有单机安装的时候可以进行 离线安装 。
配置 精简安装的配置文件示例:conf/slim.yml :
---
#==============================================================#
# 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 (rh@vonng.com)
#==============================================================#
# 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 } # odd number please
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.3.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 剧本进行部署:
高可用集群 精简安装模式也可以部署高可用集群,在 etcd 和 pg-meta 分组中添加更多节点即可,一个三节点的部署样例:
ID NODE PGSQL INFRA ETCD 1 10.10.10.10pg-meta-1不安装基础设施模块 etcd-12 10.10.10.11pg-meta-2不安装基础设施模块 etcd-23 10.10.10.12pg-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 ]}
node_crontab : [ '00 01 * * * postgres /pg/bin/pg-backup full' ] # make a full backup every 1am
vars :
# 省略 ……
4.9 - 安全建议 单机部署,快速上手时的三点安全加固建议
对于单机部署的 Demo/Dev 场景,只要您 修改了默认密码 ,Pigsty 的默认配置已经足够安全。
如果您的部署对互联网开放,可以考虑添加 防火墙 规则,限制端口访问与来源 IP,进一步加固安全性。
除此之外,我们建议您保护好 Pigsty 的 关键文件 (配置文件与 CA 私钥)防止未授权访问并定期备份。
对于有着严格安全要求的企业级生产环境,请参考 部署-安全加固 文档进行进阶配置。
密码 Pigsty 是一个开源项目,默认密码众所周知 。如果您的部署面向互联网或者办公网开放,请务必修改所有默认密码!
为了避免手动修改密码的繁琐,Pigsty 的 配置向导 提供了自动生成随机强密码的功能,使用 configure 的 -g 参数即可。
$ ./configure -g
configure pigsty v4.3.0 begin
[ OK ] region = china
[ WARN] kernel = Darwin, can be used as admin node only
[ OK ] machine = arm64
[ OK ] package = brew ( macOS)
[ WARN] primary_ip = default placeholder 10.10.10.10 ( macOS)
[ OK ] mode = meta ( unknown distro)
[ OK ] locale = C.UTF-8
[ OK ] generating random passwords...
grafana_admin_password : CdG0bDcfm3HFT9H2cvFuv9w7
pg_admin_password : 86WqSGdokjol7WAU9fUxY8IG
pg_monitor_password : 0X7PtgMmLxuCd2FveaaqBuX9
pg_replication_password : 4iAjjXgEY32hbRGVUMeFH460
patroni_password : DsD38QLTSq36xejzEbKwEqBK
haproxy_admin_password : uhdWhepXrQBrFeAhK9sCSUDo
minio_secret_key : z6zrYUN1SbdApQTmfRZlyWMT
etcd_root_password : Bmny8op1li1wKlzcaAmvPiWc
DBUser.Meta : U5v3CmeXICcMdhMNzP9JN3KY
DBUser.Viewer : 9cGQF1QMNCtV3KlDn44AEzpw
S3User.Backup : 2gjgSCFYNmDs5tOAiviCqM2X
S3User.Meta : XfqkAKY6lBtuDMJ2GZezA15T
S3User.Data : OygorcpCbV7DpDmqKe3G6UOj
[ OK ] random passwords generated, check and save them
[ OK ] ansible = ready
[ OK ] pigsty configured
[ WARN] don' t forget to check it and change passwords!
proceed with ./deploy.yml
我们建议在规划部署之前,就修改所有默认密码,确保部署完成后系统即处于安全状态。事后修改密码是一个繁琐的工作:
防火墙 在互联网或者办公网开放的部署场景中,强烈建议配置 防火墙规则 ,限制访问 IP 范围与端口。
您可以使用云厂商提供的安全组功能,或者使用 Linux 发行版自带的防火墙服务(如 firewalld、ufw、iptables 等)来实现。
方向: 协议 端口 服务 说明 入站 TCP 22 SSH 允许 ssh 登陆管理 入站 TCP 80 Nginx 允许 Nginx HTTP 访问 入站 TCP 443 Nginx 允许 Nginx HTTPS 访问 入站 TCP 5432 PostgreSQL 远程公网访问数据库,按需启用
Pigsty 默认支持配置防火墙规则,允许 22/80/443/5432 从外部网络访问,但这并非默认启用。
文件 在 Pigsty 中,您需要特别保护以下文件:
pigsty.yml :Pigsty 主配置文件,包含所有节点的访问信息与密码files/pki/ca/ca.key :Pigsty 自签名 CA 的私钥,用于签发部署中所有的 SSL 证书(部署时自动生成)我们建议您严格控制这两个文件的访问权限,并定期进行备份,将它们存储在一个安全的位置。
5 - 部署 在严肃生产环境中进行多节点、高可用的 Pigsty 规划、准备与部署工作。
与 快速上手 不同,严肃企业生产环境 Pigsty 部署需要更多 架构规划 与 准备工作 。
本章将帮助您理解 Pigsty 的完整部署流程,并提供生产环境部署的最佳实践建议。
我们建议您在真实的生产环境部署之前,使用 Pigsty 提供的 沙箱环境 进行测试与演练,确保对部署流程有充分的了解。
您可以使用 Vagrant 在本地快速创建一个四节点的 Pigsty 沙箱环境用于测试,或者利用 Terraform 在云端置备一个更大规模的仿真环境。
对于生产环境部署,您通常需要准备至少三个 节点 以实现高可用。您需要进一步了解 Pigsty 的 相关概念 以及常见操作的管理 SOP。
包括如何通过 参数配置 进行定制,如何执行 Ansible 剧本 进行部署。以及如何加固部署的 安全性 以满足企业合规要求。
5.1 - 生产部署 如何在 Linux 主机上安装 Pigsty?
本文是 Pigsty 生产环境多节点部署指南,部署单机版本 Demo/Dev 环境可以参考 快速上手 文档。
摘要 准备 几台 具有 SSH 权限 的 节点 ,
安装 兼容的 Linux 系统 ,使用具有免密 ssh 和 sudo 权限的 管理用户 执行:
pigsty.cc(中国)
pigsty.io(全球) curl -fsSL https://repo.pigsty.cc/get | bash;
curl -fsSL https://repo.pigsty.io/get | bash;
该命令会执行 安装 脚本,下载并提取 Pigsty 源码至家目录并安装依赖,接下来依次完成 配置 与 部署 即可完成交付。
在执行 deploy.yml 进行部署前,您可能需要进一步审视与编辑 配置清单 :pigsty.yml 文件,确认部署细节。
cd ~/pigsty # 进入 Pigsty 目录
./configure -g # 生成配置文件(可选,如果知道如何配置可以跳过)
./deploy.yml # 执行部署剧本,根据生成的配置文件开始安装
安装完成后,您可以通过 IP / 域名 + 80/443 端口访问 Web 用户界面 ,
并通过 5432 端口访问 PostgreSQL 服务 。
完整流程根据服务器规格/网络条件需 3~10 分钟,离线安装 时能够显著加速;无需监控时可使用 精简安装 进一步加速。
视频样例:20 节点生产仿真环境(Ubuntu 24.04 x86_64)
准备 在生产环境中部署安装 Pigsty 涉及一些 准备工作 ,以下为完整检查清单,供您参考。
项目 要求 项目 要求 节点 至少 1C2G,上不封顶 规格 多个同质节点,2 / 3 / 4 / 或更多 磁盘 /data 作为默认主挂载点FS 推荐使用 xfs,按需使用 ext4 / zfs VIP L2 VIP,可选 (云环境不可用) 网络 静态 IPv4 地址,单节点无固定 IP 可使用 127.0.0.1 CA 可以使用自签名 CA 或指定已有证书 域名 本地 / 公网域名,可选,默认 i.pigsty 自签名域名 内核 Linux x86_64 / aarch64Linux el8, el9, el10, d12, d13, u22, u24, u26Locale C.UTF-8 或 C防火墙 端口:80 / 443 / 22 / 5432 (可选) 用户 避免使用 root 和 postgres Sudo sudo 权限,最好带有 nopass 免密选项 SSH 通过公钥 nopass SSH 登陆纳管节点 可达性 ssh <ip|alias> sudo ls 无错误
安装 您可以使用以下命令自动安装 Pigsty 源码包 至 ~/pigsty 目录(推荐),部署所需依赖(Ansible)会自动安装。
pigsty.cc(中国)
pigsty.io(全球) curl -fsSL https://repo.pigsty.cc/get | bash # 安装当前默认版本
curl -fsSL https://repo.pigsty.cc/get | bash -s v4.3.0 # 安装特定版本
curl -fsSL https://repo.pigsty.io/get | bash # 安装当前默认版本
curl -fsSL https://repo.pigsty.io/get | bash -s v4.3.0 # 安装特定版本
如果您不希望执行远程脚本,可以手动 下载 或克隆源码。使用 git 克隆安装时,请务必检出特定版本后再使用。
git clone https://github.com/pgsty/pigsty; cd pigsty;
git checkout v4.3.0; # 使用 git 安装时,请务必检出特定版本
手工下载克隆安装时,请额外执行 bootstrap 脚本以手动安装 Ansible 等部署依赖,您也可以 自行安装 。
./bootstrap # 安装 ansible,用于执行后续部署
配置 在 Pigsty 中,部署的蓝图细节由 配置清单 所定义,也就是 pigsty.yml 配置文件,您可以通过声明式配置进行定制。
Pigsty 提供了 configure 脚本作为可选的 配置向导 ,
它将根据您的环境和输入,生成具有良好默认值的 配置清单 :
./configure -g # 使用配置向导生成配置文件,并且生成随机密码
配置过程生成的配置文件默认位于:~/pigsty/pigsty.yml,您可以在安装前进行检查,按需修改与定制。
有许多 配置模板 供您参考与使用,但您也完全可以跳过配置向导,直接编辑 pigsty.yml 配置文件进行定制。
./configure -c ha/full -g # 使用四节点沙箱环境模板
./configure -c ha/trio -g # 使用三节点最小 HA 模板
./configure -c ha/dual -g -v 18 # 使用两节点半高可用模板,使用 PG 18
./configure -c ha/simu -s # 使用二十节点生产仿真模板,不检查 IP,不生成随机强密码
配置 / configure 过程的样例输出 vagrant@meta:~/pigsty$ ./configure
configure pigsty v4.3.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 = vagrant@127.0.0.1 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 = vagrant@10.10.10.10 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
配置向导只会为您替换 当前节点 的 IP(如果您不想要替换,使用 -s 参数),所以对于一个多节点的部署,您需要自己替换其他节点的 IP 地址。
同时,你还需要按需对配置文件进行进一步的定制,例如修改默认密码、添加更多节点等。
配置脚本常用参数 :
参数 说明 -c|--conf用于指定使用的 配置模板 ,相对于 conf/ 目录,不带 .yml 后缀的配置名称 -v|--version用于指定要安装的 PostgreSQL 大版本,如 13、14、15、16、17、18 -r|--region用于指定上游软件源的区域,加速下载: (default|china|europe) -n|--non-interactive直接使用命令行参数提供首要 IP 地址,跳过交互式向导 -x|--proxy使用当前环境变量配置 proxy_env 变量
如果您的机器网卡绑定了多个 IP 地址,那么需要使用 -i|--ip <ipaddr> 显式指定一个当前节点的首要 IP 地址,或在交互式问询中提供。
该脚本将把 IP 占位符 10.10.10.10 替换为当前节点的主 IPv4 地址。选用的地址应为静态 IP 地址,请勿使用公网 IP 地址。
配置过程生成的配置文件默认位于:~/pigsty/pigsty.yml,您可以在安装前进行检查与修改定制。
修改默认密码!
我们强烈建议您在安装前,事先修改配置文件中使用的默认密码与凭据,详情参考 安全加固 。
部署 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 部署完成后,您的环境应该具有类似下面的部署结构:
ID NODE PGSQL INFRA ETCD 1 10.10.10.10pg-meta-1infra-1etcd-12 10.10.10.11pg-test-1- - 3 10.10.10.12pg-test-2- - 4 10.10.10.13pg-test-3- -
INFRA 模块通过浏览器提供了一个 图形化管理界面 ,您可以直接通过这台节点上的 Nginx 的 80/443 端口访问。
PGSQL 模块提供了一个 PostgreSQL 数据库服务器 ,监听 5432 端口,也可通过 Pgbouncer / HAProxy 代理访问 。
对于生产环境的多节点高可用 PostgreSQL 集群来说,您需要通过 服务接入 来使用数据库服务,实现流量自动路由。
更多 安装完成后,您可以探索 用户界面 ,并通过 5432 端口访问 PostgreSQL 服务 。
您还可以使用 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 模块。查看可用的 模块 了解详情:
PGSQL 、INFRA 、NODE 、ETCD 、
MINIO 、REDIS 、FERRET 、DOCKER ……
5.2 - 资源准备 生产部署的准备工作,包括硬件,节点、磁盘、网络、VIP、域名、软件、文件系统等……
Pigsty 运行在节点(物理机或虚拟机)之上,本文档介绍硬件相关的规划与准备。
节点 Pigsty 目前运行在 Linux 内核和 x86_64 / aarch64 架构的节点上。
"节点 " 指的是 SSH 可访问 且提供裸 Linux 操作系统环境的资源。
它可以是物理机、虚拟机或配备 systemd、sudo 和 sshd 的类似操作系统的容器。
部署 Pigsty 至少需要 1 个节点,您可以准备更多,并在 执行部署剧本 中一次性部署所有节点,或稍后添加并单独部署。
最小节点规格要求是 1C1G,建议至少使用 1C2G。越高越好,没有上限。系统参数将根据可用资源自动调优 。
所需节点的数量,取决于您的需求,更多详情请参考 架构规划 。
尽管带有 外部备份 的 单机部署 也提供一定程度上的兜底,
但我们建议在生产部署中使用复数个节点,起作用的 高可用配置 至少需要 3 个节点才能工作,2 个节点则提供 半高可用 。
磁盘 Pigsty 将使用 /data 作为默认数据目录,如果您有专用的主数据磁盘,建议将其挂载到那里,并为额外的磁盘驱动器使用 /data1、/data2、/dataN。
如果你想使用其他的数据目录,可以通过以下参数进行配置:
文件系统 您可以使用任何支持的 Linux 文件系统来格式化数据磁盘,但对于生产环境部署,我们建议使用 xfs 。
xfs 是 linux 的标配之一,提供了最佳的性能,便利的 CoW 机制,允许你瞬间克隆大型数据库集群。使用 MinIO 时,必须使用 xfs 文件系统。
ext4 是另一个可用的选择,但缺乏 CoW 功能,但有着更为丰富的数据恢复工具生态。zfs 可以提供 RAID,快照功能,但性能折损较大且需要单独安装。
我们推荐您在这三种文件系统中按需权衡,择一使用。
如果有特殊需求,您也可以使用其他文件系统,但我们强烈不建议使用 NFS 网络文件系统来运行数据库服务。
Pigsty 的工作假设是 /data 目录属于 root:root,权限为 755。
管理员可以分配一级目录的所有权和权限。每个应用在其子目录中运行时将使用专用用户。
Pigsty 使用的目录结构说明,请参考 FHS 文档说明。
网络 Pigsty 默认使用在线安装模式,需要出站互联网访问。
使用 离线安装 模式则不再需要互联网访问。
在内网中,Pigsty 需要 静态网络 才能工作,您应该为每个节点明确分配一个 固定的 IPv4 地址。
IP 地址将用作节点的 唯一标识符 ,它应该是绑定到用于 内部 网络通信的主网络接口的主 IP 地址。
作为特例,单机部署 时如果没有固定 IP 地址,可以使用本地环回地址 127.0.0.1 作为变通。
永远不要使用公网 IP 作为标识符
使用公网 IP 地址作为节点标识符可能导致安全和连接问题,请务必使用内网 IP 地址作为标识。
VIP Pigsty 支持 NODE 集群(keepalived)和 PGSQL 集群(vip-manager)的可选 L2 VIP。
要使用 L2 VIP 功能,您必须为节点集群/数据库集群明确分配指定一个 L2 VIP 地址。
在您自己的硬件上运行时这不是大问题,但在公有云环境中工作时可能成为问题。
L2 VIP 需要 L2 网络
要使用可选的节点 VIP 和 PG VIP 功能,请确保所有节点位于同一 L2 网络内。
CA Pigsty 默认为每一套部署生成一套自签名的 CA 基础设施 ,用于签发环境中所有的加密证书。
如果您已经有了正规的企业 CA,或者已经有了自签名的 CA,您也可以选择使用已有的 CA 来签发 Pigsty 所需的证书。
域名 Pigsty 默认使用一个本地静态域名 i.pigsty 来访问 WebUI,这是可选的,你也可以直接使用 IP 地址访问。
对于生产环境部署来说,建议您使用域名来访问服务,只有使用域名,才能启用 HTTPS 支持,加密您的数据传输。
同时,域名访问允许您在同一个端口上运行多种不同的服务,并通过不同的域名进行区分。
如果您的部署提供 互联网访问 ,那么可以使用公共 DNS 供应商(如 Cloudflare、阿里云 DNS、AWS Route53 等)来管理您的域名解析。
将您的域名指向 Pigsty 节点的 公网 IP 地址 即可。
如果您的部署针对 局域网/办公网 开放,那么可以使用内部 DNS 服务器来管理域名解析。
将您的域名指向 Pigsty 节点的 办公网 IP 地址 即可。
如果您的访问仅限于本机,或特定的几台机器,那么可以使用本地静态解析来管理域名解析。
将以下记录添加到(用于访问 Pigsty WebUI 的机器) /etc/hosts 文件(本地静态解析)中,即可从浏览器中访问。
10.10.10.10 i.pigsty # 替换为您计划使用的域名,与 Pigsty 节点的 IP 地址
Linux Pigsty 运行在 Linux 操作系统上,它支持 14 种主流 Linux 发行版:兼容操作系统列表
我们推荐使用 RockyLinux 10.1 、Debian 13.3 或 Ubuntu 26.04.0 / 24.04.4 作为默认操作系统选项。
在 MacOS 和 Windows 上,您可以用各种虚拟机软件或者 Docker systemd 镜像来安装 Pigsty。
我们 强烈建议 使用全新安装的操作系统环境,如果您的服务器已经运行了 Nginx / PostgreSQL 等服务,请考虑使用新的节点进行部署。
在所有节点上使用相同的操作系统版本
多节点部署时,请确保所有节点使用相同的 Linux 发行版,架构与版本。异构节点部署虽然可能可以工作,但不受支持且可能导致不可预见的问题。
Locale 我们建议您将 en_US 设置为操作系统的主要语言,至少确保该 Locale 可用 ,从而确保 PG 日志打印英文。
一些发行版可能默认没有提供 en_US 区域设置,例如 Debian。使用以下命令启用 en_US 区域设置:
localedef -i en_US -f UTF-8 en_US.UTF-8
localectl set-locale LANG = en_US.UTF-8
对于 PostgreSQL 来说,我们强烈建议您默认使用 PG 17+ 内置的 C.UTF-8 作为默认排序规则。
在 配置向导 中如果检测到 PG 版本满足或者操作系统支持,就默认配置 C.UTF-8 作为排序规则。
Ansible Pigsty 使用 Ansible 从管理节点发起对所有被管理节点的控制,
安装 Ansible 会介绍更多细节。
Pigsty 默认会在 Infra 节点上安装 Ansible,所以 Infra 节点是可以作为管理节点(或备用管理节点)使用。
在 单机部署 的时候,您当前执行安装的节点,既是运行 ansible 管理命令的 管理节点 ,也是部署基础设施的 INFRA节点 。
Pigsty 您可以使用以下方式 安装 最新稳定版本的 Pigsty 源代码:
pigsty.cc(中国)
pigsty.io(全球) curl -fsSL https://repo.pigsty.cc/get | bash;
curl -fsSL https://repo.pigsty.io/get | bash;
要 安装 最新特定版本的 Pigsty,可以使用 -s <version> 参数:
pigsty.cc(中国)
pigsty.io(全球) curl -fsSL https://repo.pigsty.cc/get | bash -s <version> # 安装特定版本(示例:v4.3.0)
curl -fsSL https://repo.pigsty.io/get | bash -s <version> # 安装特定版本(示例:v4.3.0)
要 安装 最新 Beta 版本的 Pigsty 源代码,可以使用 beta 脚本:
pigsty.cc(中国)
pigsty.io(全球) curl -fsSL https://repo.pigsty.cc/beta | bash;
curl -fsSL https://repo.pigsty.io/beta | bash;
如果你是开发者,或者想要获取最新的开发版本,可以直接 git 克隆 Pigsty 代码仓库:
git clone https://github.com/pgsty/pigsty.git;
cd pigsty; git checkout <tag> # 使用特定版本(示例:v4.3.0)
如果您的环境没有互联网访问,也可以直接从 GitHub Release 页面,或者 Pigsty 仓库下载源码包:
wget https://repo.pigsty.cc/src/pigsty-v<version>.tgz
wget https://repo.pigsty.io/src/pigsty-v<version>.tgz
5.3 - 架构规划 使用多少个节点?为哪些模块配置高可用?如何根据可用的资源与业务需求进行规划?
Pigsty 采用 模块化架构 ,您可以像搭积木一样组合出自己想要的部署方案,并用简单的 声明式配置 表达您的意图。
常见方案 这里有一些常见的组合模式供您参考,您可以根据自己的需求进行进一步的定制与调整:
使用什么样的架构规划方案,取决于您对数据库可靠性的要求,以及手头可用的资源。
通常来说,严肃的生产环境部署至少需要 3 个节点以实现 高可用配置 。
如果您只有 2 个节点,则可以使用 半高可用配置 。
专家咨询服务:架构规划
我们提供 架构咨询服务 (¥2,000)为您筹划合适的 Pigsty 配置方案。
利弊权衡 若要使用 Pigsty 的监控系统,则至少需要 1 个 INFRA 节点,生产部署通常使用 2 个,大规模部署 3 个。 若要启用 PG 高可用,则至少需要 1 个 ETCD 节点,生产部署通常使用 3 个,大规模环境中 5 个,须奇数个。 若要启用对象存储(MinIO),则至少需要 1 个 MINIO 节点 ,严肃使用时通常使用 4+ 节点部署 MNMD 集群。 PG 生产集群通常至少为两节点主从配置;严肃场景通常使用 3 节点;高只读负载可以有更多从库(几十个) 此外对于 PostgreSQL 来说,您还可以按需使用 离线实例,同步实例,备份集群,延迟集群等等高级配置。 单节点配置 最简单的配置,所有内容都在单个节点上运行,默认安装四个基本模块,通常用于 Demo,Devbox,或测试环境。
如果为备份/PITR 配置了外部 S3 / MinIO 备份仓库 提供兜底的 RTO/RPO,此配置亦可用于普通标准的生产环境。
单节点配置有多种变体:
双节点配置 双节点配置 将启用数据库复制和 半高可用 能力,提供更好的数据冗余,以及有限的故障转移支持:
双节点配置的高可用自动切换机制有限制,这种"半 HA"设置只能从特定节点故障中自动恢复:
如果 node-1 故障,无自动故障转移:需要手动提升 node-2 如果 node-2 故障,自动故障转移有效:node-1 自动提升 三节点配置 三节点模板 提供真正的基础高可用配置,可以容忍任意一个节点的故障,并从中自动恢复。
ID NODE PGSQL INFRA ETCD 1 node-1pg-meta-1infra-1etcd-12 node-2pg-meta-2infra-2etcd-23 node-3pg-meta-3infra-3etcd-3
四节点配置 Pigsty 沙箱环境 使用的 标准四节点配置 。
ID NODE PGSQL INFRA ETCD 1 node-1pg-meta-1infra-1etcd-12 node-2pg-test-13 node-3pg-test-24 node-4pg-test-3
在这里我们出于演示目的,不配置 INFRA / ETCD 模块的高可用,您也可以对其进行进一步的调整
ID NODE PGSQL INFRA ETCD MINIO 1 node-1pg-meta-1infra-1etcd-1minio-12 node-2pg-test-1infra-2etcd-23 node-3pg-test-2etcd-34 node-4pg-test-3
更多节点 如果您有着完善的虚拟化设施或充足的资源,完全可以 使用更多的节点 ,让每个模块都采用 独占式部署 ,从而获得最佳的可靠性,可观测性与性能表现。
ID NODE INFRA ETCD MINIO PGSQL 1 10.10.10.10infra-1pg-meta-12 10.10.10.11infra-2pg-meta-23 10.10.10.21etcd-14 10.10.10.22etcd-25 10.10.10.23etcd-36 10.10.10.31minio-17 10.10.10.32minio-28 10.10.10.33minio-39 10.10.10.34minio-410 10.10.10.40pg-src-111 10.10.10.41pg-src-212 10.10.10.42pg-src-313 10.10.10.50pg-test-114 10.10.10.51pg-test-215 10.10.10.52pg-test-316 ……
5.4 - 管理机制 关于管理用户、管理节点,Sudo、SSH、可达性验证,以及防火墙的配置与准备
Pigsty 需要一个在所有被管理节点上具有免密 SSH 和 Sudo 权限的操作系统 管理用户 。
这个用户需要能够通过 ssh 访问到所有被管理节点,并且能够在这些节点上执行 sudo 命令。
要想将节点纳入 Pigsty 中管理,
用户 通常我们会选择 dba 或 admin 这样的用户名称,并避免使用 root 与 postgres:
使用 root 进行部署是可行的,但不符合生产最佳实践。 使用 postgres (pg_dbsu )作为管理员用户是严格禁止的。 免密码 如果您可以接受为每个 ssh 和 sudo 命令输入密码,则免密码要求是可选的。
您可以在 执行剧本 时使用 -k|--ask-pass 来提示输入 SSH 密码,
以及 -K|--ask-become-pass 来提示输入 sudo 密码。
一些企业的安全策略可能不允许免密 ssh 或 sudo,在这种情况下,您可以使用上述选项。
或者考虑配置一个 sudo 密码缓存时间较长的 sudoers 规则,以减少密码提示的频率。
创建管理员用户 通常,您的服务器/虚拟机供应商会为您创建一个初始管理员用户。
如果你对这个用户不满意,Pigsty 的部署剧本可以为你创建一个 新的管理员用户 。
假设您在节点上有 root 权限,或有一个现有的管理员用户,您可以使用 Pigsty 本身创建管理员用户:
./node.yml -k -K -t node_admin \
-e ansible_user =[ 当前可登录的管理员名称] \
-e node_admin_username =[ 你准备创建的管理员名称]
它将利用现有的管理员创建新的管理员,创建由以下参数描述的专用 dba(uid=88)用户,并正确配置 sudo / ssh。
Sudo 所有 管理员用户 都应该在所有被管理节点上具有 sudo 权限【最好带有免密码执行权限】。
如果您想从头开始配置具有免密 sudo 权限的管理员用户,可以编辑/创建 suoder 文件(假设用户名为 vagrant):
echo '%vagrant ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/vagrant
假设您的管理员用户名选择是 dba,那么 /etc/sudoers.d/dba 内容应该是:
%dba ALL =( ALL) NOPASSWD: ALL
如果您的安全策略不允许免密码 sudo,请将 NOPASSWD: 部分删除:
Ansible 依赖 sudo 在被管理节点上以 root 权限执行命令。
在 sudo 不可用的环境中(比如 Docker 容器内)需要先安装 sudo 才能正确部署。
SSH 您的当前用户应该能够以相应的管理员用户身份免密 SSH 访问所有被管理节点。
您的当前用户可以是管理员用户本身,但不是必需的,只要您能以管理员用户身份 SSH。
SSH 配置是 Linux 101,但我们会在此处介绍基础知识,以防您不熟悉:
生成 SSH 密钥 如果您没有 SSH 密钥对,请生成一个:
ssh-keygen -t rsa -b 2048 -N '' -f ~/.ssh/id_rsa -q
如果您没有密钥对,Pigsty 会在 bootstrap 阶段为您完成此操作。
复制 SSH 密钥 您需要将生成的公钥分发到远程(和本地)服务器,并将其放入所有节点上管理员用户的 ~/.ssh/authorized_keys 文件中。
可以使用 ssh-copy-id 工具。
ssh-copy-id <ip> # 交互式密码输入
sshpass -p <password> ssh-copy-id <ip> # 非交互式(谨慎使用)
使用别名 当无法直接 SSH 访问时(由于跳板机、其他端口、凭据等),考虑在 ~/.ssh/config 中配置 SSH 别名:
Host meta
HostName 10.10.10.10
User dba # 远程上不同的用户
IdentityFile /etc/dba/id_rsa # 不是普通密钥
Port 24 # 不是众所周知的端口
并在清单中引用别名,使用 ansible_host 指定真实的 SSH 别名:
nodes :
hosts : # 如果节点 `10.10.10.10` 需要 SSH 别名 `meta`
10.10.10.10 : { ansible_host : meta } # 通过 `ssh meta` 访问
SSH 参数可以直接在 Ansible 中使用,详情请查看 Ansible Inventory Guide 。
通过这种技术,您可以使用跳板机访问私有网络中的节点,或者使用不同的端口和凭据访问节点。
或者是利用本地笔记本作为管理节点。
验证可达性 您应该能够从管理节点通过当前用户免密 ssh 访问所有被管理节点。
远程用户(管理员用户)应该有权限运行免密 sudo 命令。
要验证免密 ssh sudo 是否工作,在管理节点上对所有被管理节点运行此命令:
如果没有密码提示或错误,免密 ssh/sudo 按预期工作。
防火墙 在生产环境部署时,通常需要设置防火墙,以阻止未经授权的端口访问。
默认情况下,你可以阻断办公网/互联网对节点的入站访问,只开放下列端口:
要通过 ssh 访问节点,您必须允许 SSH 端口 22 入站访问。 要访问 WebUI 服务,您必须允许 HTTP(80)/ HTTPS(443)入站访问。 要访问 PostgreSQL 数据库服务,您必须允许 PostgreSQL 的 5432 入站访问。 如果您通过其他端口访问 PostgreSQL 服务,请相应地允许它们。
Pigsty 组件使用的端口列表,请参考:使用的端口 。
5432:PostgreSQL 数据库6432:Pgbouncer 连接池5433:PG 主要服务5434:PG 副本服务5436:PG 默认服务5438:PG 离线服务5.5 - 沙箱环境 用于学习、测试与演示的 Pigsty 标准四节点沙箱环境
Pigsty 提供了一个标准的四节点 沙箱环境 ,用于学习、测试与功能演示。
沙箱使用固定的 IP 地址和预定义的身份标识符,便于复现各种演示用例。
环境描述 默认的沙箱环境由 4 个节点组成,默认使用配置文件 ha/full.yml 。
ID IP 地址 节点名 PostgreSQL INFRA ETCD MINIO 1 10.10.10.10metapg-meta-1infra-1etcd-1minio-12 10.10.10.11node-1pg-test-13 10.10.10.12node-2pg-test-24 10.10.10.13node-3pg-test-3
沙箱的配置可以概括表示为以下配置文件:
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
minio : { hosts : { 10.10.10.10 : { minio_seq: 1 } }, vars : { minio_cluster : minio } }
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 }
vars :
version : v4.3.0
admin_ip : 10.10.10.10
region : default
pg_version : 18
PostgreSQL 集群 沙箱带有一个位于 meta 节点上的单实例 PostgreSQL 集群 pg-meta:
10.10.10.10 meta pg-meta-1
10.10.10.2 pg-meta # 可选的 L2 VIP
沙箱中还有一个由三个实例组成的 PostgreSQL 高可用集群 pg-test,部署在另外三个节点上:
10.10.10.11 node-1 pg-test-1
10.10.10.12 node-2 pg-test-2
10.10.10.13 node-3 pg-test-3
10.10.10.3 pg-test # 可选的 L2 VIP
两个可选的 L2 VIP 分别绑定在 pg-meta 和 pg-test 集群的主实例上。
基础设施 在 meta 节点上还部署有:
ETCD 集群 :单节点 etcd 集群,为 PostgreSQL HA 提供 DCS 服务MinIO 集群 :单节点 minio 集群,提供 S3 兼容的对象存储服务10.10.10.10 etcd-1
10.10.10.10 minio-1
创建沙箱 Pigsty 提供了开箱即用的模板,您可以使用 Vagrant 在本地创建沙箱,或使用 Terraform 在云上创建沙箱。
当然,您也可以自己手工准备并置备这些节点。
本地沙箱(Vagrant) 本地沙箱使用 VirtualBox/libvirt 创建本地虚拟机,可以在您的 Mac / PC 上免费运行。
运行完整的 4 节点沙箱,您的机器应至少拥有 4 核 CPU 与 8GB 内存 。
cd ~/pigsty
make full # 使用默认 RockyLinux 9 镜像创建 4 节点沙箱
make full9 # 使用 RockyLinux 9 创建 4 节点沙箱
make full12 # 使用 Debian 12 创建 4 节点沙箱
make full24 # 使用 Ubuntu 24.04 创建 4 节点沙箱
make full26 # 使用 Ubuntu 26.04 创建 4 节点沙箱
Pigsty v4.3 统一使用 Vagrant Cloud 上的 cloud-image/* Box。下表列出 4 节点本地沙箱可使用的 VirtualBox/libvirt 镜像版本。
VirtualBox libvirt 更多详情请参考 Vagrant 文档。
云沙箱使用公有云 API 创建虚拟机,可以轻松创建和销毁,按需付费,非常适合快速测试。
使用 spec/aliyun-full.tf 模板在阿里云上创建 4 节点沙箱:
cd ~/pigsty/terraform
cp spec/aliyun-full.tf terraform.tf
terraform init
terraform apply
更多详情请参考 Terraform 文档。
其他规格 除了标准的 4 节点沙箱,Pigsty 还提供了其他规格的环境:
最简单的 1 节点环境,用于快速上手、开发和测试:
双节点环境(dual) 2 节点环境,用于测试主从复制:
三节点环境(trio) 3 节点环境,用于测试基本高可用:
生产仿真环境(simu) 20 节点的大型仿真环境,用于模拟生产环境进行完整测试:
make simu # 创建 20 节点生产仿真环境
该环境包含:
3 个基础设施节点(meta1, meta2, meta3) 2 个 HAProxy 代理节点 4 个 MinIO 节点 5 个 ETCD 节点 6 个 PostgreSQL 节点(2 个集群,每个 3 节点) 5.6 - Vagrant 使用 Vagrant 在本地创建虚拟机环境
Vagrant 是一个流行的本地虚拟化工具,可以按照声明式的方式创建本地虚拟机。
Pigsty 需要 Linux 环境运行,您可以使用 Vagrant 轻松在本地创建 Linux 虚拟机进行测试。
安装依赖 首先,确保您的系统中已经安装了 Vagrant 和虚拟机软件(VirtualBox , libvirt ,Hyper-V,Parallel,……)。
在 MacOS 上,您可以使用 Homebrew 一键安装 vagrant 与 virtualbox;
在 Linux 上,您可以使用 VirtualBox 或 vagrant-libvirt 作为虚拟机管理软件;
在 Windows 专业版上,可以使用 VirtualBox 与 Hyper-V 作为提供商。
brew install vagrant virtualbox ansible
# 安装 VirtualBox 后需要重启系统,并在系统偏好设置中允许其内核扩展。 /bin/bash -c " $( curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) " 创建虚拟机 使用 Pigsty 提供的 make 快捷方式创建虚拟机:
cd ~/pigsty
make meta # 1 节点开发箱,用于快速上手、开发和测试
make full # 4 节点沙箱,用于高可用测试和功能演示
make simu # 20 节点仿真环境,用于生产环境模拟
# 其他不常用的规格
make dual # 2 节点环境
make trio # 3 节点环境
make deci # 10 节点环境
您可以使用变体别名指定不同的操作系统镜像:
make meta9 # 使用 RockyLinux 9.7 创建单节点
make full12 # 使用 Debian 12.13 创建 4 节点沙箱
make simu24 # 使用 Ubuntu 24.04 创建 20 节点仿真环境
make full26 # 使用 Ubuntu 26.04 创建 4 节点沙箱
可用的操作系统后缀:8(EL8)、9(EL9)、10(EL10)、12(Debian 12)、13(Debian 13)、22(Ubuntu 22.04)、24(Ubuntu 24.04)、26(Ubuntu 26.04)
构建环境 您还可以使用以下别名创建 Pigsty 构建环境,这些模板不会替换基础镜像:
make oss # 3 节点 OSS 构建环境
make pro # 5 节点 PRO 构建环境
make rpm # 3 节点 EL8/9/10 构建环境
make deb # 4 节点 Debian12/13 Ubuntu22/24 构建环境
make all # 7 节点全量构建环境
规格配置 Pigsty 在 vagrant/spec/ 目录下提供了多种预定义的虚拟机规格:
每个规格文件包含一个描述虚拟机节点的 Specs 变量。例如,full.rb 包含 4 节点沙箱的定义:
# full: pigsty full-featured 4-node sandbox for HA-testing & tutorial & practices
Specs = [
{ "name" => "meta" , "ip" => "10.10.10.10" , "cpu" => "2" , "mem" => "4096" , "image" => "cloud-image/ubuntu-24.04" },
{ "name" => "node-1" , "ip" => "10.10.10.11" , "cpu" => "1" , "mem" => "2048" , "image" => "cloud-image/ubuntu-24.04" },
{ "name" => "node-2" , "ip" => "10.10.10.12" , "cpu" => "1" , "mem" => "2048" , "image" => "cloud-image/ubuntu-24.04" },
{ "name" => "node-3" , "ip" => "10.10.10.13" , "cpu" => "1" , "mem" => "2048" , "image" => "cloud-image/ubuntu-24.04" },
]
simu 规格详情 simu.rb 提供了一个 20 节点的生产环境仿真配置:
3 x infra 节点(meta1-3):4c16g 2 x haproxy 节点(proxy1-2):1c2g 4 x minio 节点(minio1-4):1c2g 5 x etcd 节点(etcd1-5):1c2g 6 x pgsql 节点(pg-src-1-3,pg-dst-1-3):2c4g 配置脚本 使用 vagrant/config 脚本可以根据规格和选项生成最终的 Vagrantfile:
cd ~/pigsty
vagrant/config [ spec] [ image] [ scale] [ provider]
# 示例
vagrant/config meta u24 # 使用 1 节点规格,Ubuntu 24.04 镜像
vagrant/config dual el9 # 使用 2 节点规格,RockyLinux 9.7 镜像
vagrant/config trio d12 2 # 使用 3 节点规格,Debian 12.13 镜像,双倍资源
vagrant/config full u22 4 # 使用 4 节点规格,Ubuntu 22.04 镜像,4 倍资源
vagrant/config simu u26 1 libvirt # 使用 20 节点规格,Ubuntu 26.04 镜像,libvirt 提供商
镜像别名 config 脚本支持多种镜像别名:
发行版 别名 Vagrant Box Rocky 8 el8, rocky8, r8cloud-image/rocky-8Rocky 9 el9, rocky9, el, r9cloud-image/rocky-9Rocky 10 el10, rocky10, r10cloud-image/rocky-10Debian 12 d12, debian12, deb12cloud-image/debian-12Debian 13 d13, debian13, deb13cloud-image/debian-13Ubuntu 22.04 u22, ubuntu22, ubuntu2204cloud-image/ubuntu-22.04Ubuntu 24.04 u24, ubuntu24, ubuntu2404, ubuntucloud-image/ubuntu-24.04Ubuntu 26.04 u26, ubuntu26, ubuntu2604cloud-image/ubuntu-26.04AlmaLinux 8 alma8cloud-image/almalinux-8AlmaLinux 9 alma9cloud-image/almalinux-9AlmaLinux 10 alma10cloud-image/almalinux-10
资源缩放 您可以使用环境变量 VM_SCALE 来调整资源倍数,默认值为 1:
VM_SCALE = 2 vagrant/config meta # 将 meta 规格的 CPU/内存资源翻倍
例如,使用 VM_SCALE=4 配置 meta 规格,会将默认的 2c4g 调整为 8c16g:
Specs = [
{ "name" => "meta" , "ip" => "10.10.10.10" , "cpu" => "8" , "mem" => "16384" , "image" => "cloud-image/ubuntu-24.04" },
]
simu 规格不支持缩放
simu 规格不支持资源缩放,scale 参数会被自动忽略,因为其资源配置已经针对仿真场景优化。
虚拟机管理 Pigsty 提供了一系列 Makefile 快捷方式来管理虚拟机:
make # 等于 make start
make new # 销毁现有虚拟机,创建新的虚拟机
make ssh # 将虚拟机 SSH 配置写入 ~/.ssh/(创建后必须执行)
make dns # 将虚拟机 DNS 记录写入 /etc/hosts(可选)
make start # 启动虚拟机并配置 SSH(up + ssh)
make up # 使用 vagrant up 启动虚拟机
make halt # 关闭虚拟机(别名:down, dw)
make clean # 销毁虚拟机(别名:del, destroy)
make status # 显示虚拟机状态(别名:st)
make pause # 暂停虚拟机(别名:suspend)
make resume # 恢复虚拟机
make nuke # 使用 virsh 销毁所有虚拟机和卷(仅 libvirt)
make info # 显示 libvirt 信息(虚拟机、网络、存储卷)
SSH 密钥 Pigsty Vagrant 模板默认使用您的 ~/.ssh/id_rsa[.pub] 作为虚拟机的 SSH 密钥。
在开始之前,请确保您有一个有效的 SSH 密钥对。如果没有,可以使用以下命令生成:
ssh-keygen -t rsa -b 2048 -N '' -f ~/.ssh/id_rsa -q
支持的镜像 Pigsty v4.3 统一使用 Vagrant Cloud 上的 cloud-image/* Box,VirtualBox 与 libvirt 均提供 amd64 / arm64 架构版本。
VirtualBox libvirt 环境变量 您可以使用以下环境变量来控制 Vagrant 行为:
export VM_SPEC = 'meta' # 规格名称
export VM_IMAGE = 'cloud-image/rocky-9' # 镜像名称
export VM_SCALE = '1' # 资源缩放倍数
export VM_PROVIDER = 'virtualbox' # 虚拟化提供商
export VAGRANT_EXPERIMENTAL = disks # 启用实验性磁盘功能
注意事项 VirtualBox 网络配置
使用较旧版本的 VirtualBox 作为 Vagrant 提供商时,需要额外配置才能使用 10.x.x.x CIDR 作为 Host-Only 网络:
echo "* 10.0.0.0/8" | sudo tee -a /etc/vbox/networks.conf
第一次下载镜像较慢
第一次使用 Vagrant 启动特定操作系统时,会下载相应的 Box 镜像文件(通常 1-2 GB)。下载完成后,镜像会被缓存,后续创建虚拟机时会直接复用。
libvirt 提供商
如果您使用 libvirt 作为提供商,可以使用 make info 查看虚拟机、网络和存储卷信息,使用 make nuke 强制销毁所有相关资源。
5.7 - Terraform 使用 Terraform 在公有云上创建虚拟机环境
Terraform 是一个流行的"基础设施即代码"工具,您可以使用它在公有云上一键创建虚拟机。
Pigsty 提供了阿里云、AWS、腾讯云的 Terraform 模板作为示例。
快速开始 在 macOS 上,您可以使用 Homebrew 安装 Terraform:
其他平台请参考 Terraform 官方安装指南 。
初始化与应用 进入 Terraform 目录,选择模板,初始化提供商插件,然后应用配置:
cd ~/pigsty/terraform
cp spec/aliyun.tf terraform.tf # 选择模板
terraform init # 安装云提供商插件(首次使用时)
terraform apply # 生成执行计划并创建资源
运行 apply 命令后,按提示输入 yes 确认,Terraform 将为您创建虚拟机及相关云资源。
获取 IP 地址 创建完成后,打印管理节点的公网 IP 地址:
terraform output | grep -Eo '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}'
配置 SSH 访问 使用 ssh 脚本自动配置 SSH 别名并分发密钥:
./ssh # 写入 SSH 配置到 ~/.ssh/pigsty_config 并复制密钥
此脚本会将 Terraform 输出的 IP 地址写入 ~/.ssh/pigsty_config,并使用默认密码 PigstyDemo4 自动分发 SSH 密钥。
配置完成后,您可以直接使用主机名登录:
使用 SSH 配置文件
如果您希望使用 ~/.ssh/pigsty_config 中的配置,请确保在 ~/.ssh/config 中包含以下内容:
Include ~/.ssh/pigsty_config
销毁资源 测试完成后,可以一键销毁所有创建的云资源:
模板规格 Pigsty 在 terraform/spec/ 目录下提供了多种预定义的云资源模板:
使用模板时,将模板文件复制为 terraform.tf:
cd ~/pigsty/terraform
cp spec/aliyun-full.tf terraform.tf # 使用阿里云 4 节点沙箱模板
terraform init && terraform apply
变量配置 Pigsty 的 Terraform 模板使用变量来控制架构、操作系统发行版和资源配置:
架构与发行版 variable "architecture" {
description = "架构类型 (amd64 或 arm64)"
type = string
default = "amd64" # 注释此行以使用 arm64
#default = "arm64" # 取消注释以使用 arm64
}
variable "distro" {
description = "发行版代码 (el8,el9,el10,u22,u24,u26,d12,d13)"
type = string
default = "el9" # 默认使用 Rocky Linux 9
}
资源配置 在 locals 块中可以配置以下资源参数:
locals {
bandwidth = 100 # 公网带宽 (Mbps)
disk_size = 40 # 系统盘大小 (GB)
spot_policy = "SpotWithPriceLimit" # 竞价策略:NoSpot, SpotWithPriceLimit, SpotAsPriceGo
spot_price_limit = 5 # 最高竞价价格 (仅在 SpotWithPriceLimit 时有效)
}
阿里云配置 凭证设置 将您的阿里云凭证添加到环境变量中,例如在 ~/.bash_profile 或 ~/.zshrc 中:
export ALICLOUD_ACCESS_KEY = "<your_access_key>"
export ALICLOUD_SECRET_KEY = "<your_secret_key>"
export ALICLOUD_REGION = "cn-shanghai"
支持的镜像 以下是阿里云中常用的 ECS 公共操作系统镜像 前缀:
发行版 代码 x86_64 镜像前缀 aarch64 镜像前缀 CentOS 7.9 el7centos_7_9_x64- Rocky 8.10 el8rockylinux_8_10_x64rockylinux_8_10_arm64Rocky 9.7 el9rockylinux_9_7_x64rockylinux_9_7_arm64Rocky 10.1 el10rockylinux_10_1_x64rockylinux_10_1_arm64Debian 11.11 d11debian_11_11_x64- Debian 12.13 d12debian_12_13_x64debian_12_13_arm64Debian 13.3 d13debian_13_3_x64debian_13_3_arm64Ubuntu 22.04 u22ubuntu_22_04_x64_20Gubuntu_22_04_arm64_20GUbuntu 24.04 u24ubuntu_24_04_x64_20Gubuntu_24_04_arm64_20GUbuntu 26.04 u26ubuntu_26_04_x64_20Gubuntu_26_04_arm64_20GAnolis 8.9 an8anolisos_8_9_x64- Alibaba Cloud Linux 3 al3aliyun_3_0_x64-
OSS 存储配置 aliyun-s3.tf 模板会额外创建 OSS 存储桶及相关权限,用于 PostgreSQL 的 PITR 备份:
OSS Bucket :创建名为 pigsty-oss 的私有存储桶RAM 用户 :创建专用的 pigsty-oss-user 用户访问密钥 :生成 AccessKey 并保存到 ~/pigsty.skIAM 策略 :授予对存储桶的完全访问权限AWS 配置 凭证设置 设置 AWS 配置和凭证文件:
# ~/.aws/config
[ default]
region = cn-northwest-1
# ~/.aws/credentials
[ default]
aws_access_key_id = <YOUR_AWS_ACCESS_KEY>
aws_secret_access_key = <AWS_ACCESS_SECRET>
如果需要使用 SSH 密钥,将密钥文件放置在:
~/.aws/pigsty-key
~/.aws/pigsty-key.pub
AWS 模板需要调整
AWS 模板是社区贡献的示例,可能需要根据您的具体需求进行调整。
腾讯云配置 凭证设置 将腾讯云凭证添加到环境变量中:
export TENCENTCLOUD_SECRET_ID = "<your_secret_id>"
export TENCENTCLOUD_SECRET_KEY = "<your_secret_key>"
export TENCENTCLOUD_REGION = "ap-beijing"
腾讯云模板需要调整
腾讯云模板是社区贡献的示例,可能需要根据您的具体需求进行调整。
快捷命令 Pigsty 提供了一些 Makefile 快捷命令用于 Terraform 操作:
cd ~/pigsty/terraform
make u # terraform apply -auto-approve + 配置 SSH
make d # terraform destroy -auto-approve
make apply # terraform apply(交互式确认)
make destroy # terraform destroy(交互式确认)
make out # terraform output
make ssh # 运行 ssh 脚本配置 SSH 访问
make r # 重置 terraform.tf 到版本库状态
注意事项 云资源费用
使用 Terraform 创建的云资源会产生费用。测试完成后,请及时使用 terraform destroy 销毁资源,避免不必要的开支。
建议使用按量付费的实例类型进行测试。模板默认使用竞价实例(Spot Instance)以降低成本。
默认密码
所有模板中虚拟机的默认 root 密码为 PigstyDemo4。在生产环境中,请务必修改此密码或使用 SSH 密钥认证。
安全组配置
Terraform 模板会自动创建安全组并开放必要的端口(默认开放所有 TCP 端口)。在生产环境中,请根据实际需求调整安全组规则,遵循最小权限原则。
SSH 访问
创建完成后,使用以下命令 SSH 登录到管理节点:
您也可以使用 ./ssh 或 make ssh 将 SSH 别名写入配置文件,然后使用 ssh meta 登录。
5.8 - 安全考量 Pigsty 部署中与安全有关的考量
Pigsty 的默认配置已经足以覆盖绝大多数场景对于安全的需求。
Pigsty 已经提供了开箱即用的 认证 与 访问控制 模型,对于绝大多数场景已经足够安全。
如果您希望进一步加固系统的安全性,那么以下建议供您参考:
机密性 重要文件 保护你的 pigsty.yml 配置文件或 CMDB
pigsty.yml 配置文件通常包含了高度敏感的机密信息,您应当确保它的安全。严格控制管理节点的访问权限,仅限 DBA 或者 Infra 管理员访问。 严格控制 pigsty.yml 配置文件仓库的访问权限(如果您使用 git 进行管理) 保护你的 CA 私钥和其他证书,这些文件非常重要。
相关文件默认会在管理节点 Pigsty 源码目录的 files/pki 内生成。 你应该定期将它们备份到一个安全的地方存储。 密码 在生产环境部署时,必须更改这些密码,不要使用默认值!
如果您使用 MinIO,请修改 MinIO 的默认用户密码,与 pgbackrest 中的引用
如果您使用远程备份仓库,请务必启用备份加密,并设置加解密密码
设置 [pgbackrest_repo.*.cipher_type](/docs/pgsql/param#pgbackrest_repo) 为 aes-256-cbc` 设置密码时可以使用 ${pg_cluster} 作为密码的一部分,避免所有集群使用同一个密码 为 PostgreSQL 使用安全可靠的密码加密算法
使用 pg_pwd_enc 默认值 scram-sha-256 替代传统的 md5 这是默认行为,如果没有特殊理由(出于对历史遗留老旧客户端的支持),请不要将其修改回 md5 使用 passwordcheck 扩展强制执行强密码 。
在 pg_libs 中添加 $libdir/passwordcheck 来强制密码策略。 使用加密算法加密远程备份
为业务用户配置密码自动过期实践
不要将更改密码的语句记录到 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 客户端访问
限制 patroni 管理访问权限:仅 infra/admin 节点可调用控制 API
网络流量 使用 SSL 和域名,通过 Nginx 访问基础设施组件
使用 SSL 保护 Patroni REST API
使用 SSL 保护 Pgbouncer 客户端流量
完整性 为关键场景下的 PostgreSQL 数据库集群配置一致性优先模式(例如与钱相关的库)
pg_conf 数据库调优模板,使用 crit.yml 将以一些可用性为代价,换取最佳的数据一致性。使用 crit 节点调优模板,以获得更好的一致性。
启用数据校验和,以检测静默数据损坏。
记录建立/切断连接的日志
在 PG 18+ 的 oltp.yml / olap.yml 模板中,log_connections 默认开启(authorization)。 在 crit.yml 模板中,log_connections 与 log_disconnections 默认都开启,审计级别更严格。 您也可以手工 配置集群 ,按需调整这两个参数。 如果您希望彻底杜绝 PG 集群在故障转移时脑裂的可能性,请启用 watchdog
如果你的流量走默认推荐的 HAProxy 分发,那么即使你不启用 watchdog,你也不会遇到脑裂的问题。 如果你的机器假死,Patroni 被 kill -9 杀死,那么 watchdog 可以用来兜底:超时自动关机。 最好不要在基础设施节点上启用 watchdog。 可用性 对于关键场景的 PostgreSQL 数据库集群,请使用足够的节点/实例数量
你至少需要三个节点(能够容忍一个节点的故障)来实现生产级的高可用性。 如果你只有两个节点,你可以容忍特定备用节点的故障。 如果你只有一个节点,请使用外部的 S3/MinIO 进行冷备份和 WAL 归档存储。 对于 PostgreSQL,在可用性和一致性之间进行权衡
不要直接通过固定的 IP 地址访问数据库;请使用 VIP、DNS、HAProxy 或它们的排列组合
使用 HAProxy 进行服务 接入 在故障切换/主备切换的情况下,Haproxy 将处理客户端的流量切换。 在重要的生产部署中使用多个基础设施节点(例如,1~3)
小规模部署或要求宽松的场景,可以使用单一基础设施节点 / 管理节点。 大型生产部署建议设置至少两个基础设施节点互为备份。 使用足够数量的 etcd 服务器实例,并使用奇数个实例(1,3,5,7)
6 - 参考信息 7 - 参考 详细的参考信息与列表:支持的操作系统,模块,参数,监控指标,数据库扩展,同类对比,术语表等。
7.1 - Linux 兼容性 Pigsty 兼容的 Linux 操作系统发行版大版本,以及芯片架构指令集
Pigsty 运行于 Linux 操作系统上,支持 amd64/x86_64 与 arm64/aarch64 架构,支持 EL ,Debian ,Ubuntu 三大主流 Linux 发行版。
Pigsty 不使用任何虚拟化容器化技术,直接运行于裸操作系统上。我们为三大主流 Linux 发行版生命周期内的主流大版本与两种架构提供支持。
概述 Pigsty 推荐使用的操作系统版本:RockyLinux 10.1 / 9.7、Ubuntu 26.04.0 / 24.04.4 / 22.04.5、Debian 13.3 / 12.13。
EL Pigsty 支持 RHEL / Rocky / Alma / Anolis / CentOS 8、9、10 版本。
推荐使用 RockyLinux 10.1 与 9.7
请注意,PGDG Yum 仓库 从 EL9 / EL10 开始,针对 EL 小版本 进行构建,目前支持的小版本为:9.6, 9.7, 10.0, 10.1。
建议离线安装包/自建离线仓库与系统 EL 小版本 (例如 RockyLinux 9.7 / 10.1)保持一致,跨小版本可能因 OpenSSL 等依赖版本跳变导致不可用。
EL8 即将不再支持
EL8 将于 2029 年进入 EOL,建议尽早规划升级。鉴于 EL10 适配已经完成,我们将在下个版本移除对 EL8 的支持。
EL 7 @ 2024-06
Red Hat Enterprise Linux 7 已经于 2024年6月停止维护,PGDG 也不再为 PostgreSQL 16/17/18 提供 EL7 二进制包支持。
如需在老旧操作系统上获得运行支持,请考虑我们的 专业订阅服务 。
Ubuntu Pigsty 支持 Ubuntu 26.04 / 24.04 / 22.04:
推荐使用 Ubuntu 26.04.0 / 24.04.4 / 22.04.5 LTS
Ubuntu 26.04 是最新 LTS 基线;如果您希望采用更保守的 Ubuntu 生产环境基线,也可以继续使用 Ubuntu 24.04。
Debian Pigsty 支持 Debian 12 / 13,推荐使用最新的 Debian 13.3
Debian 11 EOL @ 2024-07
Debian 11 已经于 2024-07 进入 EOL。如需在老旧操作系统上获得扩展支持,请考虑我们的 专业订阅服务 。
Vagrant 当您使用本地虚拟机部署 Pigsty 时,可以考虑使用以下 Vagrant 操作系统镜像,这也是 Pigsty 开发测试使用的镜像。
当您使用云服务器部署 Pigsty 时,可以考虑在 Terraform 中使用以下操作系统基础镜像,以 阿里云 为例:
x86_64 镜像 Rocky 8.10 rockylinux_8_10_x64_20G_alibase_20240923.vhdRocky 9.7 rockylinux_9_7_x64_20G_alibase_20260119.vhdRocky 10.1 rockylinux_10_1_x64_20G_alibase_20260119.vhdUbuntu 22.04.5 ubuntu_22_04_x64_20G_alibase_20240926.vhdUbuntu 24.04.4 ubuntu_24_04_x64_20G_alibase_20240923.vhdDebian 12.13 debian_12_13_x64_20G_alibase_20241201.vhdDebian 13.3 debian_13_3_x64_20G_alibase_20250101.vhd
aarch64 镜像 Rocky 8.10 rockylinux_8_10_arm64_20G_alibase_20251120.vhdRocky 9.7 rockylinux_9_7_arm64_20G_alibase_20260119.vhdRocky 10.1 rockylinux_10_1_arm64_20G_alibase_20260119.vhdUbuntu 22.04.5 ubuntu_22_04_arm64_20G_alibase_20251126.vhdUbuntu 24.04.4 ubuntu_24_04_arm64_20G_alibase_20251126.vhdDebian 12.13 debian_12_13_arm64_20G_alibase_20250825.vhdDebian 13.3 debian_13_3_arm64_20G_alibase_20251121.vhd
7.2 - 模块列表 本文列出了 Pigsty 中可用的功能模块,以及后续的功能模块规划。
正式模块 模块 类别 状态 文档入口 简介 PGSQL核心 GA /docs/pgsql高可用 PostgreSQL 集群,内置备份、监控、SOP 与扩展生态。 INFRA核心 GA /docs/infra本地软件仓库 + VictoriaMetrics/Logs/Traces + Grafana 等基础设施。 NODE核心 GA /docs/node节点初始化与收敛:系统调优、管理员、HAProxy、Vector、Docker 等。 ETCD核心 GA /docs/etcdPostgreSQL 高可用 DCS(服务发现、配置、选主元数据)。 MINIO扩展 GA /docs/minioS3 兼容对象存储,可作为 PostgreSQL 备份仓库。 REDIS扩展 GA /docs/redisRedis 独立/哨兵/集群模式部署与监控。 FERRET扩展 GA /docs/ferretFerretDB 模块(MONGO API 兼容),为 PG 提供 MongoDB 协议访问。 DOCKER扩展 GA /docs/dockerDocker Daemon 及容器化应用运行基础能力。 JUICE扩展 BETA /docs/juiceJuiceFS 分布式文件系统,使用 PostgreSQL 作为元数据引擎。 VIBE扩展 BETA /docs/vibe浏览器化开发环境,集成 Code-Server、JupyterLab、Node.js 与 Claude Code。
核心模块 Pigsty 提供了四个 基础 功能模块,对于提供完整高可用的 PostgreSQL 服务非常重要:
PGSQL :带有高可用,时间点恢复,IaC,SOP,监控系统,以及 510 个扩展插件的自治的 PostgreSQL 集群。INFRA :本地软件仓库、Prometheus、Grafana、Loki、AlertManager、PushGateway、Blackbox Exporter…NODE :调整节点到所需状态、名称、时区、NTP、ssh、sudo、haproxy、docker、vector、keepalivedETCD :分布式键值存储,用作高可用 Postgres 集群的 DCS:共识选主/配置管理/服务发现。尽管这四个模块通常会同时安装,但单独使用也是可行的 —— 只有 NODE 模块通常是必选的。
扩展模块 Pigsty 提供了六个 扩展 功能模块,它们对于核心功能来说并非必须,但可以用于增强 PostgreSQL 的能力:
MINIO :S3 兼容的简单对象存储服务器,可作为可选的 PostgreSQL 数据库备份仓库,带有生产部署支持与监控。REDIS :Redis 服务器,高性能数据结构服务器,支持独立主从、哨兵、集群模式生产部署,并带有完善的监控支持。MONGO :FerretDB 原生部署支持 —— 它为 PostgreSQL 添加了 MongoDB 线缆协议级别的 API 兼容支持!DOCKER :Docker Daemon 服务,允许用户一键拉起容器化的无状态软件工具模板,为 Pigsty 加装各种功能!JUICE :JuiceFS 分布式文件系统模块,以 PostgreSQL 作为元数据引擎,提供可共享的 POSIX 存储能力。VIBE :浏览器化开发环境模块,集成 Code-Server、JupyterLab、Node.js 与 Claude Code,开箱即用。生态模块 以下模块与 PostgreSQL 生态紧密相关,属于可选生态能力,不计入上述 10 个正式模块:
7.3 - 文件结构 Pigsty 的文件系统结构是如何设计与组织的,以及各个模块使用的目录结构。
Pigsty FHS Pigsty 的主目录默认放置于 ~/pigsty,该目录下的文件结构如下所示:
#------------------------------------------------------------------------------
# pigsty
# ^-----@app # 额外的示例应用资源
# ^-----@bin # bin 脚本
# ^-----@docs # 文档(可docsify化)
# ^-----@files # ansible 文件资源
# ^-----@victoria # Victoria 规则与运维脚本(bin/rules)
# ^-----@grafana # grafana 仪表盘
# ^-----@postgres # /pg/bin/ 脚本
# ^-----@migration # pgsql 迁移任务定义
# ^-----@pki # 自签名 CA 和证书
# ^-----@roles # ansible 剧本实现
# ^-----@templates # ansible 模板文件
# ^-----@vagrant # Vagrant 沙箱虚拟机定义模板
# ^-----@terraform # Terraform 云虚拟机申请模板
# ^-----configure # 配置向导脚本
# ^-----ansible.cfg # ansible 默认配置文件
# ^-----pigsty.yml # pigsty 默认配置文件
# ^-----*.yml # ansible 剧本
#------------------------------------------------------------------------------
# /infra -> /data/infra # infra 运行时目录软链接
# /data/infra # root:infra 0771
# ^-----@metrics # VictoriaMetrics TSDB 数据
# ^-----@logs # VictoriaLogs 数据
# ^-----@traces # VictoriaTraces 数据
# ^-----@alertmgr # AlertManager 数据
# ^-----@rules # 规则定义(含 agent.yml)
# ^-----@targets # FileSD 监控目标
# ^-----@dashboards # Grafana 仪表盘定义
# ^-----@datasources # Grafana 数据源定义
# ^-----prometheus.yml # Victoria 的 Prometheus 兼容配置
#------------------------------------------------------------------------------
CA FHS Pigsty 的 自签名 CA 位于 Pigsty 主目录下的 files/pki/。
你必须妥善保管 CA 的密钥文件 :files/pki/ca/ca.key,该密钥是在 deploy.yml 或 infra.yml 的 ca 角色负责生成的。
# pigsty/files/pki # (local_user) 0755
# ^-----@ca # (local_user) 0700
# ^-----@ca.key # 0600,非常重要:保守其秘密
# ^-----@ca.crt # 0644,非常重要:在所有地方都受信任
# ^-----@csr # (local_user) 0755,签名请求 csr
# ^-----@misc # (local_user) 0755,杂项证书,已签发证书
# ^-----@etcd # (local_user) 0755,etcd 服务器证书
# ^-----@minio # (local_user) 0755,minio 服务器证书
# ^-----@nginx # (local_user) 0755,nginx SSL 证书
# ^-----@infra # (local_user) 0755,infra 客户端证书
# ^-----@pgsql # (local_user) 0755,pgsql 服务器证书
# ^-----@mongo # (local_user) 0755,mongodb/ferretdb 服务器证书
# ^-----@mysql # (local_user) 0755,mysql 服务器证书(占位符)
被 Pigsty 所管理的节点将安装以下证书文件:
/etc/pki/ca.crt # root:root 0644,所有节点都添加的根证书
/etc/pki/ca-trust/source/anchors/ca.crt # 软链接到系统受信任的锚点
所有 infra 节点都会有以下证书:
/etc/pki/infra.crt # root:infra 0644,infra 节点证书
/etc/pki/infra.key # root:infra 0640,infra 节点密钥
当您的管理节点出现故障时,files/pki 目录与 pigsty.yml 文件应当在备份的管理节点上可用。你可以用 rsync 做到这一点。
# run on meta-1, rsync to meta2
cd ~/pigsty;
rsync -avz ./ meta-2:~/pigsty
INFRA FHS infra 角色会创建 infra_data(默认 /data/infra)并建立 /infra -> /data/infra 软链接。/data/infra 的权限为 root:infra 0771,子目录默认权限为 *:infra 0750,覆盖项如下:
# /infra -> /data/infra
# /data/infra # root:infra 0771
# ^-----@pgadmin # 5050:5050 0700
# ^-----@alertmgr # prometheus:infra 0700
# ^-----@conf # root:infra 0750
# ^-----patronictl.yml # root:admin 0640
# ^-----@tmp # root:infra 0750
# ^-----@hosts # dnsmasq:dnsmasq 0755(DNS 记录)
# ^-----default # root:root 0644
# ^-----@datasources # root:infra 0750
# ^-----*.json # 0600(register 生成)
# ^-----@dashboards # grafana:infra 0750
# ^-----@metrics # victoria:infra 0750
# ^-----@logs # victoria:infra 0750
# ^-----@traces # victoria:infra 0750
# ^-----@bin # victoria:infra 0750
# ^-----check|new|reload|status # root:infra 0755
# ^-----@rules # victoria:infra 0750
# ^-----agent.yml # victoria:infra 0644
# ^-----infra.yml # victoria:infra 0644
# ^-----node.yml # victoria:infra 0644
# ^-----pgsql.yml # victoria:infra 0644
# ^-----redis.yml # victoria:infra 0644
# ^-----etcd.yml # victoria:infra 0644
# ^-----minio.yml # victoria:infra 0644
# ^-----kafka.yml # victoria:infra 0644
# ^-----mysql.yml # victoria:infra 0644
# ^-----@targets # victoria:infra 0750
# ^-----@infra # infra 组件目标(文件 0640)
# ^-----@node # 节点目标(文件 0640)
# ^-----@ping # ping 目标(文件 0640)
# ^-----@etcd # etcd 目标(文件 0640)
# ^-----@pgsql # pgsql 目标(文件 0640)
# ^-----@pgrds # pgrds 目标(文件 0640)
# ^-----@redis # redis 目标(文件 0640)
# ^-----@minio # minio 目标(文件 0640)
# ^-----@mongo # mongo 目标(文件 0640)
# ^-----@juice # juicefs 目标(文件 0640)
# ^-----@mysql # mysql 目标(文件 0640)
# ^-----@kafka # kafka 目标(文件 0640)
# ^-----@docker # docker 目标(文件 0640)
# ^-----@patroni # patroni SSL 目标(文件 0640)
# ^-----prometheus.yml # victoria:infra 0644
上述结构由以下实现生成:roles/infra/tasks/dir.yml、roles/infra/tasks/victoria.yml、roles/infra/tasks/register.yml、roles/infra/tasks/dns.yml、roles/infra/tasks/env.yml。
NODE FHS 节点的数据目录由参数 node_data 指定,默认为 /data,由 root:root 持有,权限为 0755。
每个组件的默认数据目录都位于这个数据库目录下,如下所示:
/data # root:root 0755
# ^-----@postgres # postgres:postgres 0700(默认 pg_fs_main)
# ^-----@backups # postgres:postgres 0700(默认 pg_fs_backup)
# ^-----@redis # redis:redis 0700(多实例共用)
# ^-----@minio # minio:minio 0750(单机单盘模式)
# ^-----@etcd # etcd:etcd 0700(etcd_data)
# ^-----@infra # root:infra 0771(infra 模块数据目录)
# ^-----@docker # root:root 0755(Docker 数据目录)
# ^-----@... # 其他组件的数据目录
Victoria FHS 监控配置已经从旧的 /etc/prometheus 目录布局迁移为 /infra 运行时布局。主配置模板位于 roles/infra/templates/victoria/prometheus.yml ,渲染结果为 /infra/prometheus.yml。
files/victoria/bin/* 与 files/victoria/rules/* 会被同步到 /infra/bin/ 与 /infra/rules/,各模块再向 /infra/targets/* 注册 FileSD 目标。
# /infra
# ^-----prometheus.yml # Victoria 主配置(Prometheus 兼容格式)0644
# ^-----@bin # 工具脚本(check/new/reload/status)0755
# ^-----@rules # 记录与告警规则(*.yml 0644)
# ^-----agent.yml # Agent 预聚合规则
# ^-----infra.yml # infra 规则和告警
# ^-----etcd.yml # etcd 规则和告警
# ^-----node.yml # node 规则和告警
# ^-----pgsql.yml # pgsql 规则和告警
# ^-----redis.yml # redis 规则和告警
# ^-----minio.yml # minio 规则和告警
# ^-----kafka.yml # kafka 规则和告警
# ^-----mysql.yml # mysql 规则和告警
# ^-----@targets # FileSD 服务发现目标(*.yml 0640)
# ^-----@infra # infra 静态目标
# ^-----@node # node 静态目标
# ^-----@pgsql # pgsql 静态目标
# ^-----@pgrds # pgsql 远程 RDS 目标
# ^-----@redis # redis 静态目标
# ^-----@minio # minio 静态目标
# ^-----@mongo # mongo 静态目标
# ^-----@mysql # mysql 静态目标
# ^-----@etcd # etcd 静态目标
# ^-----@ping # ping 静态目标
# ^-----@kafka # kafka 静态目标
# ^-----@juice # juicefs 静态目标
# ^-----@docker # docker 静态目标
# ^-----@patroni # patroni 静态目标(启用 SSL 时)
# /etc/default/vmetrics # vmetrics 启动参数(victoria:infra 0644)
# /etc/default/vlogs # vlogs 启动参数(victoria:infra 0644)
# /etc/default/vtraces # vtraces 启动参数(victoria:infra 0644)
# /etc/default/vmalert # vmalert 启动参数(victoria:infra 0644)
# /etc/alertmanager.yml # 告警组件主配置(prometheus:infra 0644)
# /etc/default/alertmanager # 告警组件环境变量(prometheus:infra 0640)
# /etc/blackbox.yml # 黑盒探测主配置(prometheus:infra 0644)
# /etc/default/blackbox_exporter # 黑盒探测环境变量(prometheus:infra 0644)
Postgres FHS 以下参数与 PostgreSQL 数据库目录结构相关:
pg_dbsu_home : Postgres 默认用户的家目录,默认为/var/lib/pgsqlpg_bin_dir : Postgres 二进制目录,默认为/usr/pgsql/bin/pg_data :Postgres 数据库目录,默认为/pg/datapg_fs_main :Postgres 主数据目录,默认为/data/postgrespg_fs_backup :Postgres 备份盘挂载点,默认为 /data/backups(可选,也可以选择备份到主数据盘上的子目录)pg_cluster_dir :派生变量,{{ pg_fs_main }}/{{ pg_cluster }}-{{ pg_version }}pg_backup_dir :派生变量,{{ pg_fs_backup }}/{{ pg_cluster }}-{{ pg_version }}#--------------------------------------------------------------#
# 工作假设:
# {{ pg_fs_main }} 主数据目录,默认位置:`/data/postgres` [SSD]
# {{ pg_fs_backup }} 备份数据盘,默认位置:`/data/backups` [HDD]
#--------------------------------------------------------------#
# 默认配置(pg_cluster=pg-test, pg_version=18):
# pg_fs_main = /data/postgres 高速SSD
# pg_fs_backup = /data/backups 廉价HDD (可选)
#
# /pg -> /data/postgres/pg-test-18
# /pg/data -> /data/postgres/pg-test-18/data
# /pg/backup -> /data/backups/pg-test-18/backup
#--------------------------------------------------------------#
- name : create pgsql directories
tags : pg_dir
become : true
block :
- name : create pgsql directories
file : path={{ item.path }} state=directory owner={{ item.owner|default(pg_dbsu) }} group={{ item.group|default('postgres') }} mode={{ item.mode }}
with_items :
- { path : "{{ pg_fs_main }}" ,mode : "0700" }
- { path : "{{ pg_fs_backup }}" ,mode : "0700" }
- { path : "{{ pg_cluster_dir }}" ,mode : "0700" }
- { path : "{{ pg_cluster_dir }}/bin" ,mode : "0700" }
- { path : "{{ pg_cluster_dir }}/log" ,mode : "0750" }
- { path : "{{ pg_cluster_dir }}/tmp" ,mode : "0700" }
- { path : "{{ pg_cluster_dir }}/cert" ,mode : "0700" }
- { path : "{{ pg_cluster_dir }}/conf" ,mode : "0700" }
- { path : "{{ pg_cluster_dir }}/data" ,mode : "0700" }
- { path : "{{ pg_cluster_dir }}/spool" ,mode : "0700" }
- { path : "{{ pg_backup_dir }}/backup" ,mode : "0700" }
- { path : "/var/run/postgresql" ,owner: root, group: root, mode : "0755" }
- name : link pgsql directories
file : src={{ item.src }} dest={{ item.dest }} state=link
with_items :
- { src : "{{ pg_backup_dir }}/backup" ,dest : "{{ pg_cluster_dir }}/backup" }
- { src : "{{ pg_cluster_dir }}" ,dest : "/pg" }
数据文件结构
# 真实目录
{{ pg_fs_main }} /data/postgres # postgres:postgres 0700,主数据目录
{{ pg_cluster_dir }} /data/postgres/pg-test-18 # postgres:postgres 0700,集群目录
/data/postgres/pg-test-18/bin # postgres:postgres 0700(脚本文件 root:postgres 0755)
/data/postgres/pg-test-18/log # postgres:postgres 0750,日志目录
/data/postgres/pg-test-18/tmp # postgres:postgres 0700,临时文件
/data/postgres/pg-test-18/cert # postgres:postgres 0700,证书
/data/postgres/pg-test-18/conf # postgres:postgres 0700,配置索引
/data/postgres/pg-test-18/data # postgres:postgres 0700,主数据目录
/data/postgres/pg-test-18/spool # postgres:postgres 0700,pgBackRest spool
/data/postgres/pg-test-18/backup # -> /data/backups/pg-test-18/backup
{{ pg_fs_backup }} /data/backups # postgres:postgres 0700,可选备份盘目录/挂载点
{{ pg_backup_dir }} /data/backups/pg-test-18 # postgres:postgres 0700,集群备份目录
/data/backups/pg-test-18/backup # postgres:postgres 0700,实际备份位置
# 软链接
/pg -> /data/postgres/pg-test-18 # pg 根软链接
/pg/data -> /data/postgres/pg-test-18/data # pg 数据目录
/pg/backup -> /data/backups/pg-test-18/backup # pg 备份目录
二进制文件结构
在 EL 兼容发行版上(使用 yum),PostgreSQL 默认安装位置为
/usr/pgsql-${ pg_version } /
Pigsty 会创建一个名为 /usr/pgsql 的软连接,指向由 pg_version 参数指定的实际版本,例如
/usr/pgsql -> /usr/pgsql-18
因此,默认的 pg_bin_dir 是 /usr/pgsql/bin/,而该路径会被添加至系统的 PATH 环境变量中,定义文件为:/etc/profile.d/pgsql.sh.
export PATH = "/usr/pgsql/bin:/pg/bin: $PATH "
export PGHOME = /usr/pgsql
export PGDATA = /pg/data
在 Ubuntu/Debian 上,PostgreSQL Deb 包的默认安装位置是:
/usr/lib/postgresql/${ pg_version } /bin
Pgbouncer FHS Pgbouncer 使用与 {{ pg_dbsu }}(默认为 postgres)相同的用户运行,配置文件位于/etc/pgbouncer。
pgbouncer.ini:连接池主配置文件(postgres:postgres 0640)database.txt:定义连接池中的数据库(postgres:postgres 0600)useropts.txt:业务用户连接参数(postgres:postgres 0600)userlist.txt:由 /pg/bin/pgb-user 维护的用户密码文件pgb_hba.conf:连接池访问控制文件(postgres:postgres 0600)/etc/pgbouncer/ # postgres:postgres 0750
/etc/pgbouncer/pgbouncer.ini # postgres:postgres 0640
/etc/pgbouncer/database.txt # postgres:postgres 0600
/etc/pgbouncer/useropts.txt # postgres:postgres 0600
/etc/pgbouncer/userlist.txt # postgres:postgres (由 pgb-user 维护)
/etc/pgbouncer/pgb_hba.conf # postgres:postgres 0600
/pg/log/pgbouncer # postgres:postgres 0750
/var/run/postgresql # {{ pg_dbsu }}:postgres 0755(tmpfiles 维护)
Redis FHS Pigsty 提供了对 Redis 部署与监控的基础支持。
Redis 二进制通常由系统包管理器安装(服务调用路径为 /bin/*,在多数发行版上由 /usr/bin/* 软链接兼容):
redis-server
redis-cli
redis-sentinel
redis-check-rdb
redis-check-aof
redis-benchmark
/usr/libexec/redis-shutdown
对于一个名为 redis-test-1-6379 的 Redis 实例,与其相关的资源如下所示:
/usr/lib/systemd/system/redis-test-1-6379.service # root:root 0644(Debian系为 /lib/systemd/system)
/etc/redis/ # redis:redis 0700
/etc/redis/redis-test-1-6379.conf # redis:redis 0700
/data/redis/ # redis:redis 0700
/data/redis/redis-test-1-6379 # redis:redis 0700
/data/redis/redis-test-1-6379/redis-test-1-6379.rdb # RDB 文件
/data/redis/redis-test-1-6379/redis-test-1-6379.aof # AOF 文件
/var/log/redis/ # redis:redis 0700
/var/log/redis/redis-test-1-6379.log # 日志
/var/run/redis/ # redis:redis 0700(开机 tmpfiles 为 0755)
/var/run/redis/redis-test-1-6379.pid # PID
对于 Ubuntu / Debian 而言,systemd 服务的默认目录不是 /usr/lib/systemd/system/ 而是 /lib/systemd/system/
7.4 - 参数列表 Pigsty v4.x 配置参数总览与模块参数导航
本文是 Pigsty v4.x 的参数导航页,不重复展开每个参数的详细解释。
参数细节请进入各模块的 param 页面查看。
按照当前文档口径,正式模块合计约 360 个参数,分布在 10 个模块中。
模块参数导航 模块 参数组 参数量 说明 PGSQL9 125 PostgreSQL 高可用集群配置 INFRA10 72 软件仓库与 Victoria 可观测基础设施 NODE11 73 节点初始化、系统调优与运维基线 ETCD2 13 ETCD 集群与移除保护参数 MINIO2 21 MinIO 部署与移除参数 REDIS2 21 Redis 部署与移除参数 FERRET1 9 FerretDB(Mongo API)参数 DOCKER1 8 Docker 引擎参数 JUICE1 2 JuiceFS 实例与缓存参数 VIBE1 16 Code/Jupyter/Node.js/Claude 配置
参数组速览 使用建议 首次部署优先阅读:NODE 、INFRA 、PGSQL 生产环境务必审查:*_safeguard、密码凭据、端口与网络暴露参数 变更前先在单集群小范围验证,再扩展到全局参数 7.5 - 剧本列表 Pigsty v4.x 预置 Ansible 剧本导航与执行要点
本文汇总 Pigsty v4.x 各模块剧本入口与执行要点,详细任务标签请进入对应模块 playbook 文档。
模块剧本导航 模块 数量 剧本 INFRA3 deploy.yml infra.yml infra-rm.ymlNODE2 node.yml node-rm.ymlETCD2 etcd.yml etcd-rm.ymlPGSQL7 pgsql.yml pgsql-rm.ymlpgsql-user.yml pgsql-db.ymlpgsql-monitor.yml pgsql-migration.yml pgsql-pitr.ymlREDIS2 redis.yml redis-rm.ymlMINIO2 minio.yml minio-rm.ymlFERRET1 mongo.ymlDOCKER1 docker.ymlJUICE1 juice.ymlVIBE1 vibe.yml
剧本总表 辅助剧本 以下剧本不归属于特定模块,提供一些辅助功能。
剧本使用注意事项 保护机制 多个模块提供了防误删保险,通过 *_safeguard 参数控制:
默认情况下,这些 safeguard 参数均未启用(未定义)。建议在生产环境中为已初始化的集群显式设置为 true。
当保护开关设置为 true 时,对应的 *-rm.yml 剧本会立即中止执行,防止误删。可以通过命令行参数强制覆盖:
./pgsql-rm.yml -l pg-test -e pg_safeguard = false
./etcd-rm.yml -l etcd -e etcd_safeguard = false
./minio-rm.yml -l minio -e minio_safeguard = false
限制执行范围 执行剧本时建议使用 -l 参数限制命令执行的对象范围:
./pgsql.yml -l pg-meta # 限制在集群 pg-meta 上执行
./node.yml -l 10.10.10.10 # 限制在特定节点上执行
./redis.yml -l redis-test # 限制在 redis-test 集群上执行
在大规模部署上批量执行时,建议先在单集群灰度验证,再分批执行到全局。
幂等性 大部分剧本都是幂等的,可以重复执行。但需要注意:
infra.yml 默认不会 清除数据,可安全重复执行。所有 clean 参数(vmetrics_clean、vlogs_clean、vtraces_clean、grafana_clean、nginx_clean)默认均为 false如需清除基础设施数据重建,需显式设置对应的 clean 参数为 true 重复执行 *-rm.yml 删除剧本需格外小心,确保在正确的目标上执行 任务标签 可以使用 -t 参数只执行特定的任务子集:
./pgsql.yml -l pg-test -t pg_service # 只刷新集群 pg-test 的服务
./node.yml -t haproxy # 只在节点上设置 haproxy
./etcd.yml -t etcd_launch # 只重启 etcd 服务
常用命令速查 INFRA 模块 ./deploy.yml # 一次性完整部署 Pigsty
./infra.yml # 初始化基础设施
./infra-rm.yml # 移除基础设施
./cache.yml # 从现有仓库创建离线安装包
./cert.yml -e cn = <name> # 签发客户端证书
NODE 模块 ./node.yml -l <cls| ip> # 添加节点
./node-rm.yml -l <cls| ip> # 移除节点
bin/node-add <cls| ip> # 添加节点 (包装脚本)
bin/node-rm <cls| ip> # 移除节点 (包装脚本)
ETCD 模块 ./etcd.yml # 初始化 etcd 集群
./etcd-rm.yml # 移除 etcd 集群
bin/etcd-add <ip> # 添加 etcd 成员 (包装脚本)
bin/etcd-rm <ip> # 移除 etcd 成员 (包装脚本)
PGSQL 模块 ./pgsql.yml -l <cls> # 初始化 PostgreSQL 集群
./pgsql-rm.yml -l <cls> # 移除 PostgreSQL 集群
./pgsql-user.yml -l <cls> -e username = <user> # 创建业务用户
./pgsql-db.yml -l <cls> -e dbname = <db> # 创建业务数据库
./pgsql-monitor.yml -e clsname = <cls> # 监控远程集群
./pgsql-migration.yml -e@files/migration/<cls>.yml # 生成迁移手册
./pgsql-pitr.yml -l <cls> -e '{"pg_pitr": {}}' # 执行 PITR 恢复
bin/pgsql-add <cls> # 初始化集群 (包装脚本)
bin/pgsql-rm <cls> # 移除集群 (包装脚本)
bin/pgsql-user <cls> <user> # 创建用户 (包装脚本)
bin/pgsql-db <cls> <db> # 创建数据库 (包装脚本)
bin/pgsql-svc <cls> # 刷新服务 (包装脚本)
bin/pgsql-hba <cls> # 重载 HBA (包装脚本)
bin/pgmon-add <cls> # 监控远程集群 (包装脚本)
REDIS 模块 ./redis.yml -l <cls> # 初始化 Redis 集群
./redis-rm.yml -l <cls> # 移除 Redis 集群
MINIO 模块 ./minio.yml -l <cls> # 初始化 MinIO 集群
./minio-rm.yml -l <cls> # 移除 MinIO 集群
FERRET 模块 ./mongo.yml -l ferret # 安装 FerretDB
DOCKER 模块 ./docker.yml -l <host> # 安装 Docker
./app.yml -e app = <name> # 部署 Docker Compose 应用
7.6 - 端口列表 Pigsty 中各个组件使用的端口一览,以及相关的配置参数与组件状态。
以下为 Pigsty 中各模块组件使用的默认端口及其对应参数,您可以按需调整,或者作为内部防火墙精细配置的参考。
公网开放端口建议 如果您使用防火墙 zone 模式,建议通过 node_firewall_public_port 仅开放最小必要端口:
最小管理面:22, 80, 443(推荐) 需要公网直连数据库:额外开放 5432 不建议直接对公网开放:etcd(2379/2380)、patroni(8008)、各类 exporter(9xxx)、minio(9000/9001)、redis(6379)、ferretdb(27017/27018)等内部组件端口。
node_firewall_mode : zone
node_firewall_public_port : [ 22 , 80 , 443 ]
# node_firewall_public_port: [22, 80, 443, 5432] # only if public DB access is required
8 - 应用 基于 Pigsty v4.3 的应用模板与数据应用说明:使用 Docker Compose 拉起无状态应用,并将状态托管到外部 PostgreSQL / MinIO。
Pigsty v4.3 的“应用”分为两类:
软件模板(Software Templates) :~/pigsty/app/<name> 下的 Docker Compose 模板,用于拉起无状态业务组件。数据应用(Applets) :基于 PostgreSQL + Grafana 的分析样例,偏教学/演示属性。v4.3 应用模型 在 v4.3 中,推荐使用以下流程部署应用:
curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./bootstrap
./configure -c <template> # 例如 app/dify、app/odoo、app/registry、supabase
vi pigsty.yml # 修改密码、域名、IP、密钥
./deploy.yml # 部署基础设施与数据库
./docker.yml # 安装 Docker
./app.yml # 拉起应用
app.yml 会将 app/<name> 模板复制到 /opt/<name>,并按 apps.<name>.conf 覆盖 .env,最后执行 docker compose up -d。
维护中的配置模板 当前 v4.3 在源码中提供了以下应用配置模板(conf/app/*.yml 与 conf/supabase.yml):
app/difyapp/odooapp/teableapp/mattermostapp/electricapp/maybeapp/registrysupabase这些模板开箱即用,且与 ./configure -c ...、./app.yml 工作流保持一致。
轻量 Compose 应用 对于 gitea、postgrest、pgweb、wiki、kong、bytebase 等应用,也可直接使用对应目录下的 Compose 模板:
cd ~/pigsty/app/<name>
make up
如果你希望统一纳入 Pigsty IaC,可使用:
关于历史 Applet pglog、covid、db-engine、sf-survey、cloud、isd 等数据应用保留为参考示例,适合学习数据建模与可视化思路。
它们不再是 v4.3 的主线“应用交付”方式;请优先使用上面的软件模板工作流。
8.1 - Supabase 企业级自建 使用 Pigsty 自托管企业级 supabase,带有监控,高可用,PITR,IaC 以及 510 PG 扩展。
Supabase 很好,拥有属于你自己的 supabase 则好上加好。
Pigsty 可以帮助您在自己的服务器上(物理机/虚拟机/云服务器),一键自建企业级 supabase
—— 更多扩展,更好性能,更深入的控制,更合算的成本。
Pigsty 是 Supabase 官网文档上列举的三种自建部署之一:Self-hosting: Third-Party Guides
本教程需要您有 Linux 基础知识,否则建议直接使用 Supabase 云服务或 “Docker Compose” 自建。
简短版本 准备 Linux 系统 ,执行 Pigsty 标准单机安装 流程,选择 supabase 配置模板,依次执行:
curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./configure -c supabase # 使用 supabase 配置(请在 pigsty.yml 中更改凭据)
vi pigsty.yml # 编辑域名、密码、密钥...
./deploy.yml # 标准单机部署 pigsty
./docker.yml # 安装 docker 模块
./app.yml # 使用 docker 启动 supabase 无状态部分(可能较慢)
安装完毕后,使用浏览器访问 8000 端口造访 Supa Studio,用户名 supabase,密码 pigsty。
检查清单 目录 Supabase是什么? Supabase 是一个 BaaS (Backend as Service),开源的 Firebase,是 AI Agent 时代最火爆的数据库 + 后端解决方案。
Supabase 对 PostgreSQL 进行了封装,并提供了身份认证,消息传递,边缘函数,对象存储,并基于 PG 数据库模式自动生成 REST API 与 GraphQL API。
Supabase 旨在为开发者提供一条龙式的后端解决方案,减少开发和维护后端基础设施的复杂性。
它能让开发者告别绝大部分后端开发的工作,只需要懂数据库设计与前端即可快速出活!
开发者只要用 Vibe Coding 糊个前端与数据库模式设计,就可以快速完成一个完整的应用。
目前,Supabase 是 PostgreSQL 开源生态 中人气最高的开源项目,在 GitHub 上已有 九万 Star。
Supabase 还为小微创业者提供了"慷慨"的免费云服务额度 —— 免费的 500 MB 空间,对于存个用户表,浏览数之类的东西绰绰有余。
为什么要自建? 既然 Supabase 云服务这么香,为什么要自建呢?
最直观的原因是我们在《云数据库是智商税吗? 》中提到过的:当你的数据/计算规模超出云计算适用光谱(Supabase:4C/8G/500MB 免费存储),成本很容易出现爆炸式增长。
而且在当下,足够可靠的 本地企业级 NVMe SSD 在性价比上与 云端存储 有着三到四个数量级的优势,而自建能更好地利用这一点。
另一个重要的原因是 功能 , Supabase 云服务的功能受限 —— 很多强力 PG 扩展因为多租户安全挑战与许可证的原因无法以云服务的形式。
故而尽管 扩展是 PostgreSQL 的核心特色 ,在 Supabase 云服务上也依然只有 64 个扩展可用。
而通过 Pigsty 自建的 Supabase 则提供了多达 510 个开箱即用的 PG 扩展。
此外,自主可控与规避供应商锁定也是自建的重要原因 —— 尽管 Supabase 虽然旨在提供一个无供应商锁定的 Google Firebase 开源替代,但实际上自建高标准企业级的 Supabase 门槛并不低。
Supabase 内置了一系列由他们自己开发维护的 PG 扩展插件,并计划将原生的 PostgreSQL 内核替换为收购的 OrioleDB ,而这些内核与扩展在 PGDG 官方仓库中并没有提供。
这实际上是某种隐性的供应商锁定,阻止了用户使用除了 supabase/postgres Docker 镜像之外的方式自建,Pigsty 则提供开源,透明,通用的方案解决这个问题。
我们将所有 Supabase 自研与用到的 10 个缺失的扩展打成开箱即用的 RPM/DEB 包,确保它们在所有 主流Linux操作系统发行版 上都可用:
扩展 说明 pg_graphql提供 PG 内的 GraphQL 支持 (RUST),Rust 扩展,由 PIGSTY 提供 pg_jsonschema提供 JSON Schema 校验能力,Rust 扩展,由 PIGSTY 提供 wrappersSupabase 提供的外部数据源包装器捆绑包,Rust 扩展,由 PIGSTY 提供 index_advisor查询索引建议器,SQL 扩展,由 PIGSTY 提供 pg_net用 SQL 进行异步非阻塞 HTTP/HTTPS 请求的扩展 (supabase),C 扩展,由 PIGSTY 提供 vault在 Vault 中存储加密凭证的扩展 (supabase),C 扩展,由 PIGSTY 提供 pgjwtJSON Web Token API 的 PG 实现 (supabase),SQL 扩展,由 PIGSTY 提供 pgsodium表数据加密存储 TDE,扩展,由 PIGSTY 提供 supautils用于在云环境中确保数据库集群的安全,C 扩展,由 PIGSTY 提供 pg_plan_filter使用执行计划代价过滤阻止特定查询语句,C 扩展,由 PIGSTY 提供
同时,我们在 Supabase 自建部署中默认 安装 绝大多数扩展,您可以参考可用扩展列表按需 启用 。
同时,Pigsty 还会负责好底层 高可用 PostgreSQL 数据库集群,高可用 MinIO 对象存储集群的自动搭建,甚至是 Docker 容器底座的部署与 Nginx 反向代
理,域名配置 与 HTTPS证书签发 。 您可以使用 Docker Compose 拉起任意数量的无状态 Supabase 容器集群,并将状态存储在外部 Pigsty 自托管数据库服务中。
在这一自建部署架构中,您获得了使用不同内核的自由(PG 15-18,OrioleDB),加装 510 个扩展的自由,扩容与伸缩 Supabase / Postgres / MinIO 的自由,
免于数据库运维杂务的自由,以及免于供应商锁定,本地运行到地老天荒的自由。 而相比于使用云服务需要付出的代价,不过是准备服务器和多敲几行命令而已。
单节点自建快速上手 让我们先从单节点 Supabase 部署开始,我们会在后面进一步介绍多节点高可用部署的方法。
准备 一台全新 Linux 服务器 ,使用 Pigsty 提供的 supabase 配置模板执行 标准安装 ,
然后额外运行 docker.yml 与 app.yml 拉起无状态部分的 Supabase 容器即可(默认端口 8000/8433)。
curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./configure -c supabase # 使用 supabase 配置(请在 pigsty.yml 中更改凭据)
vi pigsty.yml # 编辑域名、密码、密钥...
./deploy.yml # 安装 pigsty
./docker.yml # 安装 docker compose 组件
./app.yml # 使用 docker 启动 supabase 无状态部分
在部署 Supabase 前请根据实际情况修改自动生成的 pigsty.yml 配置文件中的参数(域名与密码)
如果只是本地开发测试,可以先跳过,我们将在后面介绍如何通过修改配置文件来进一步定制。
如果配置无误,大约十分钟后,就可以在本地网络通过 http://<your_ip_address>:8000 访问到 Supabase Studio 图形管理界面了。
默认的用户名与密码分别是: supabase 与 pigsty。
注意事项:
在中国大陆地区,Pigsty 默认使用 1Panel 与 1ms 提供的 DockerHub 镜像站点下载 Supabase 相关镜像,可能会较慢。 你也可以自行配置 代理 与 镜像站 ,cd /opt/supabase; docker compose pull 手动拉取镜像。我们亦提供包含完整离线安装方案的 Supabase 自建专家咨询服务。 如果你需要使用的对象存储功能,那么需要通过域名与 HTTPS 访问 Supabase,否则会出现报错。 对于严肃的生产部署,请 务必 修改所有默认密码! 自建关键技术决策 以下是一些自建 Supabase 会涉及到的关键技术决策,供您参考:
使用默认的单节点部署 Supabase 无法享受到 PostgreSQL / MinIO 的高可用能力。
尽管如此,单节点部署相比官方纯 Docker Compose 方案依然要有显著优势: 例如开箱即用的监控系统,自由安装扩展的能力,各个组件的扩缩容能力,以及提供兜底数据库时间点恢复能力等。
如果您只有一台服务器,或者选择在云服务器上自建,Pigsty 建议您使用外部的 S3 替代本地的 MinIO 作为对象存储,存放 PostgreSQL 的备份,并承载 Supabase Storage 服务。
这样的部署在故障时可以在单机部署条件下,提供一个兜底级别的 RTO (小时级恢复时长)/ RPO (MB 级数据损失)容灾水平。
在严肃的生产部署中,Pigsty 建议使用至少3~4个节点的部署策略,确保 MinIO 与 PostgreSQL 都使用满足企业级高可用要求的多节点部署。
在这种情况下,您需要相应准备更多节点与磁盘,并相应调整 pigsty.yml 配置清单中的集群配置,以及 supabase 集群配置中的接入信息,使用高可用接入点访问服务。
Supabase 的部分功能需要发送邮件,所以要用到 SMTP 服务。除非单纯用于内网,否则对于严肃的生产部署,建议使用 SMTP 云服务。自建的邮件服务器发送的邮件容易被标记为垃圾邮件导致拒收。
如果您的服务直接向公网暴露,我们强烈建议您使用真正的域名与 HTTPS 证书,并通过 Nginx 门户 访问。
接下来,我们会依次讨论一些进阶主题。如何在单节点部署的基础上,进一步提升 Supabase 的安全性、可用性与性能。
进阶主题:安全加固 Pigsty 基础组件
对于严肃的生产部署,我们强烈建议您修改 Pigsty 基础组件的密码。因为这些默认值是公开且众所周知的,不改密码上生产无异于裸奔:
以上密码为 Pigsty 组件模块的密码,强烈建议在安装部署前就设置完毕。
Supabase 密钥
除了 Pigsty 组件的密码,你还需要 修改 Supabase 的密钥 ,包括
这里请您务必参照 Supabase教程:保护你的服务 里的说明:
Supabase 部分的凭据修改后,您可以重启 Docker Compose 容器以应用新的配置:
./app.yml -t app_config,app_launch # 使用剧本
cd /opt/supabase; make up # 手工执行
进阶主题:域名接入 如果你在本机或局域网内使用 Supabase,那么可以选择 IP:Port 直连 Kong 对外暴露的 HTTP 8000 端口访问 Supabase。
你可以使用一个内网静态解析的域名,但对于严肃的生产部署,我们建议您使用真域名 + HTTPS 来访问 Supabase。
在这种情况下,您的服务器应当有一个公网 IP 地址,你应当拥有一个域名,使用云/DNS/CDN 供应商提供的 DNS 解析服务,将其指向安装节点的公网 IP(可选默认下位替代:本地 /etc/hosts 静态解析)。
比较简单的做法是,直接批量替换占位域名(supa.pigsty)为你的实际域名,假设为 supa.pigsty.cc:
sed -ie 's/supa.pigsty/supa.pigsty.cc/g' ~/pigsty/pigsty.yml
如果你没有事先配置好,那么重载 Nginx 和 Supabase 的配置生效即可:
make cert # 申请 certbot 免费 HTTPS 证书
./app.yml # 重载 Supabase 配置
修改后的配置应当类似下面的片段:
all :
vars :
certbot_sign : true # 使用 certbot 签发真实证书
infra_portal :
home : i.pigsty.cc # 替换为你的域名!
supa :
domain : supa.pigsty.cc # 替换为你的域名!
endpoint : "10.10.10.10:8000"
websocket : true
certbot : supa.pigsty.cc # 证书名称,通常与域名一致即可
children :
supabase :
vars :
apps :
supabase : # supabase 应用定义
conf : # 覆盖 /opt/supabase/.env
SITE_URL : https://supa.pigsty.cc # <------- 修改为您的外部域名
API_EXTERNAL_URL : https://supa.pigsty.cc # <------- 否则 storage API 可能无法正常工作!
SUPABASE_PUBLIC_URL : https://supa.pigsty.cc # <------- 别忘了在 infra_portal 中配置!
完整的域名/HTTPS 配置可以参考 证书管理 教程,您也可以使用 Pigsty 自带的本地静态解析与自签发 HTTPS 证书作为下位替代。
进阶主题:外部对象存储 您可以使用 S3 或 S3 兼容的服务,来作为 PGSQL 备份与 Supabase 使用的对象存储。这里我们使用一个 阿里云 OSS 对象存储作为例子。
Pigsty 提供了一个 terraform/spec/aliyun-s3.tf 模板,
可以用于在阿里云上拉起一台服务器,以及一个 OSS 存储桶。
首先,我们修改 all.children.supa.vars.apps.[supabase].conf 中 S3 相关的配置,将其指向阿里云 OSS 存储桶:
# if using s3/minio as file storage
S3_BUCKET : data # 替换为 S3 兼容服务的连接信息
S3_ENDPOINT : https://sss.pigsty:9000 # 替换为 S3 兼容服务的连接信息
S3_ACCESS_KEY : s3user_data # 替换为 S3 兼容服务的连接信息
S3_SECRET_KEY : S3User.Data # 替换为 S3 兼容服务的连接信息
S3_FORCE_PATH_STYLE : true # 替换为 S3 兼容服务的连接信息
S3_REGION : stub # 替换为 S3 兼容服务的连接信息
S3_PROTOCOL : https # 替换为 S3 兼容服务的连接信息
同样使用以下命令重载 Supabase 配置:
./app.yml -t app_config,app_launch
您同样可以使用 S3 作为 PostgreSQL 的备份仓库,在 all.vars.pgbackrest_repo 新增一个 aliyun 备份仓库的定义:
all :
vars :
pgbackrest_method : aliyun # pgbackrest 备份方法:local,minio,[其他用户定义的仓库...],本例中将备份存储到 MinIO 上
pgbackrest_repo: # pgbackrest 备份仓库 : https://pgbackrest.org/configuration.html#section-repository
aliyun : # 定义一个新的备份仓库 aliyun
type : s3 # 阿里云 oss 是 s3-兼容的对象存储
s3_endpoint : oss-cn-beijing-internal.aliyuncs.com
s3_region : oss-cn-beijing
s3_bucket : pigsty-oss
s3_key : xxxxxxxxxxxxxx
s3_key_secret : xxxxxxxx
s3_uri_style : host
path : /pgbackrest
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest.MyPass # 设置一个加密密码,pgBackRest 备份仓库的加密密码
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for the last 14 days
然后在 all.vars.pgbackrest_mehod 中指定使用 aliyun 备份仓库,重置 pgBackrest 备份:
./pgsql.yml -t pgbackrest
Pigsty 会将备份仓库切换到外部对象存储上,更多备份配置可以参考 PostgreSQL 备份 文档。
进阶主题:使用SMTP 你可以使用 SMTP 来发送邮件,修改 supabase 应用配置,添加 SMTP 信息:
all :
children :
supabase : # supa group
vars : # supa group vars
apps : # supa group app list
supabase : # the supabase app
conf : # the supabase app conf entries
SMTP_HOST : smtpdm.aliyun.com:80
SMTP_PORT : 80
SMTP_USER : no_reply@mail.your.domain.com
SMTP_PASS : your_email_user_password
SMTP_SENDER_NAME : MySupabase
SMTP_ADMIN_EMAIL : adminxxx@mail.your.domain.com
ENABLE_ANONYMOUS_USERS : false
不要忘了使用 app.yml 来重载配置
进阶主题:真·高可用 经过这些配置,您拥有了一个带公网域名,HTTPS 证书,SMTP,PITR 备份,监控,IaC,以及 510 个扩展的企业级 Supabase (基础单机版)。
高可用的配置请参考 Pigsty 其他部份的文档,如果您懒得阅读学习,我们提供手把手扶上马的 Supabase 自建专家咨询服务 —— ¥2000 元免去折腾与下载的烦恼。
单节点的 RTO / RPO 依赖外部对象存储服务提供兜底,如果您的这个节点挂了,外部 S3 存储中保留了备份,您可以在新的节点上重新部署 Supabase,然后从备份中恢复。
这样的部署在故障时可以提供一个最低标准的 RTO (小时级恢复时长)/ RPO (MB 级数据损失)兜底容灾水平 兜底。
如果想要达到 RTO < 30s,切换零数据丢失,那么需要使用多节点进行高可用部署,这涉及到:
ETCD : DCS 需要使用三个节点或以上,才能容忍一个节点的故障。PGSQL : PGSQL 同步提交不丢数据模式,建议使用至少三个节点。INFRA :监控基础设施故障影响稍小,建议生产环境使用双副本Supabase 无状态容器本身也可以是多节点的副本,可以实现高可用。 在这种情况下,您还需要修改 PostgreSQL 与 MinIO 的接入点,使用 DNS / L2 VIP / HAProxy 等 高可用接入点
关于这些部分,您只需参考 Pigsty 中各个模块的文档进行配置部署即可。
建议您参考 conf/ha/trio.yml 与 conf/ha/safe.yml 中的配置,将集群规模升级到三节点或以上。
8.2 - Odoo:自建开源 ERP 如何拉起开箱即用的企业级应用全家桶 Odoo,并使用 Pigsty 管理其后端 PostgreSQL 数据库。
Odoo 是一个开源企业资源规划 (ERP) 软件,提供一整套业务应用程序,包括 CRM、销售、采购、库存、生产、会计和其他管理功能。Odoo 是一个典型的 Web 应用程序,使用 PostgreSQL 作为底层数据库。
您的所有业务,都在一个平台上,简单、高效且实惠
公开演示(不一定开放):http://odoo.pigsty.io, 用户名: test@pigsty.io, 密码: pigsty
快速开始 在运行兼容操作系统的全新 Linux x86 / ARM 服务器上执行:
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap # 安装 ansible
./configure -c app/odoo # 使用 odoo 配置(请在 pigsty.yml 中更改凭据)
./deploy.yml # 安装 pigsty
./docker.yml # 安装 docker compose
./app.yml # 使用 docker 启动 odoo 无状态部分
Odoo 默认监听在 8069 端口,您可以通过浏览器访问 http://<ip>:8069。默认的用户名和密码都是 admin。
您可以在浏览器所在主机(/etc/hosts)添加一条解析记录 odoo.pigsty 指向您的服务器,这样您就可以通过 http://odoo.pigsty 访问 Odoo 网络界面了。
如果您想要通过 SSL/HTTPS 访问 Odoo,您需要使用真正的 SSL 证书,或者信任 Pigsty 自动生成的自签名 CA 证书。(当然,在 Chrome 浏览器中,您也可以使用敲击键入 thisisunsafe 来绕过证书验证)
配置模板 conf/app/odoo.yml 定义了一个模板配置文件,包含单个 Odoo 实例所需的资源。
all :
children :
# Odoo 应用程序(默认用户名和密码:admin/admin)
odoo :
hosts : { 10.10.10.10 : {} }
vars :
app : odoo # 指定要安装的应用程序名称(在 apps 中)
apps : # 定义所有应用程序
odoo : # 应用程序名称,应该有对应的 ~/pigsty/app/odoo 文件夹
file : # 要创建的可选目录
- { path: /data/odoo ,state: directory, owner: 100, group : 101 }
- { path: /data/odoo/webdata ,state: directory, owner: 100, group : 101 }
- { path: /data/odoo/addons ,state: directory, owner: 100, group : 101 }
conf : # 覆盖 /opt/<app>/.env 配置文件
PG_HOST : 10.10.10.10 # postgres 主机
PG_PORT : 5432 # postgres 端口
PG_USERNAME : odoo # postgres 用户
PG_PASSWORD : DBUser.Odoo # postgres 密码
ODOO_PORT : 8069 # odoo 应用程序端口
ODOO_DATA : /data/odoo/webdata # odoo webdata
ODOO_ADDONS : /data/odoo/addons # odoo 插件
ODOO_DBNAME : odoo # odoo 数据库名称
ODOO_VERSION : 19.0 # odoo 镜像版本
# Odoo 数据库
pg-odoo :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-odoo
pg_users :
- { name: odoo ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_admin ] ,createdb: true ,comment : admin user for odoo service }
- { name: odoo_ro ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_readonly ] ,comment : read only user for odoo service }
- { name: odoo_rw ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_readwrite ] ,comment : read write user for odoo service }
pg_databases :
- { name: odoo ,owner: odoo ,revokeconn: true ,comment : odoo main database }
pg_hba_rules :
- { user: all ,db: all ,addr: 172.17.0.0/16 ,auth: pwd ,title : 'allow access from local docker network' }
- { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title : 'allow grafana dashboard access cmdb from infra nodes' }
node_crontab : [ '00 01 * * * postgres /pg/bin/pg-backup full' ] # 每天凌晨 1 点进行完整备份
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }
vars : # 全局变量
version : v4.3.0 # pigsty 版本字符串
admin_ip : 10.10.10.10 # 管理节点 ip 地址
region : default # 上游镜像区域:default|china|europe
node_tune : oltp # 节点调优规格:oltp,olap,tiny,crit
pg_conf : oltp.yml # pgsql 调优规格:{oltp,olap,tiny,crit}.yml
docker_enabled : true # 在应用程序组上启用 docker
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
proxy_env : # 下载包和拉取 docker 镜像时的全局代理环境
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.tsinghua.edu.cn"
#http_proxy: 127.0.0.1:12345 # 在此处添加代理环境以下载包或拉取镜像
#https_proxy: 127.0.0.1:12345 # 通常代理格式为 http://user:pass@proxy.xxx.com
#all_proxy: 127.0.0.1:12345
infra_portal : # 域名和上游服务器
home : { domain : i.pigsty }
minio : { domain: m.pigsty ,endpoint : "${admin_ip}:9001" ,scheme: https ,websocket : true }
odoo : # nginx server config for odoo
domain : odoo.pigsty # 替换为您自己的域名!
endpoint : "10.10.10.10:8069" # odoo 服务端点:IP:PORT
websocket : true # 添加 websocket 支持
certbot : odoo.pigsty # certbot 证书名称,使用 `make cert` 申请
repo_enabled : false
node_repo_modules : node,infra,pgsql
pg_version : 18
#----------------------------------#
# 凭据:务必更改这些密码!
#----------------------------------#
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
基础 检查 .env 文件中的可配置环境变量:
# https://hub.docker.com/_/odoo#
PG_HOST = 10.10.10.10
PG_PORT = 5432
PG_USER = dbuser_odoo
PG_PASS = DBUser.Odoo
ODOO_PORT = 8069
然后使用以下命令启动 odoo:
make up # docker compose up
访问 http://ddl.pigsty 或 http://10.10.10.10:8887
Makefile make up # 在最小模式下使用 docker compose 启动 odoo
make run # 使用 docker 启动 odoo,本地数据目录和外部 PostgreSQL
make view # 打印 odoo 访问点
make log # tail -f odoo 日志
make info # 使用 jq 检查 odoo
make stop # 停止 odoo 容器
make clean # 移除 odoo 容器
make pull # 拉取最新的 odoo 镜像
make rmi # 移除 odoo 镜像
make save # 保存 odoo 镜像到 /tmp/docker/odoo.tgz
make load # 从 /tmp/docker/odoo.tgz 加载 odoo 镜像
使用外部 PostgreSQL 您可以为 Odoo 使用外部 PostgreSQL。Odoo 将在设置期间创建自己的数据库,因此您不需要这样做
pg_users : [ { name: dbuser_odoo ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_admin ] ,comment : admin user for odoo database } ]
pg_databases : [ { name: odoo ,owner: dbuser_odoo ,revokeconn: true ,comment : odoo primary database } ]
并使用以下命令创建业务用户和数据库:
bin/pgsql-user pg-meta dbuser_odoo
#bin/pgsql-db pg-meta odoo # odoo 将在设置期间创建数据库
检查连接性:
psql postgres://dbuser_odoo:DBUser.Odoo@10.10.10.10:5432/odoo
暴露 Odoo 服务 通过 nginx 门户 暴露 odoo Web 服务:
infra_portal : # 域名和上游服务器
home : { domain : h.pigsty }
grafana : { domain: g.pigsty ,endpoint : "${admin_ip}:3000" , websocket : true }
vmetrics : { domain: v.pigsty ,endpoint : "${admin_ip}:8428" }
alertmanager : { domain: a.pigsty ,endpoint : "${admin_ip}:9059" }
blackbox : { endpoint : "${admin_ip}:9115" }
vlogs : { endpoint : "${admin_ip}:9428" }
odoo : { domain: odoo.pigsty, endpoint : "127.0.0.1:8069" , websocket : true } # <------ 添加这一行
./infra.yml -t nginx # 设置 nginx 基础设施门户
Odoo 插件 社区中有很多 Odoo 模块可用,您可以通过下载并将它们放在 addons 文件夹中来安装它们。
volumes :
- ./addons:/mnt/extra-addons
您可以将 ./addons 目录挂载到容器中的 /mnt/extra-addons,然后下载并解压到 addons 文件夹,
要启用插件模块,首先进入 开发者模式
设置 -> 通用设置 -> 开发者工具 -> 激活开发者模式
然后转到 > 应用程序 -> 更新应用程序列表,然后您可以找到额外的插件并从面板安装。
常用的 免费 插件:会计套件
演示 查看公共演示:http://odoo.pigsty.io ,用户名:test@pigsty.io,密码:pigsty
如果您想通过 SSL 访问 odoo,您必须在浏览器中信任 files/pki/ca/ca.crt(或在 chrome 中使用肮脏的黑客 thisisunsafe)
8.3 - Dify:AI 工作流平台 如何使用 Pigsty 自建 AI Workflow LLMOps 平台 —— Dify,并使用外部 PostgreSQL,PGVector,Redis 作为存储?
Dify 是一个生成式 AI 应用创新引擎和开源 LLM 应用开发平台。它提供从 Agent 构建到 AI 工作流编排、RAG 检索和模型管理的能力,帮助用户轻松构建和运营生成式 AI 原生应用程序。
Pigsty 提供对自托管 Dify 的支持,允许您使用单个命令部署 Dify,同时将关键状态存储在外部管理的 PostgreSQL 中。您可以在同一个 PostgreSQL 实例中使用 pgvector 作为向量数据库,进一步简化部署。
app/dify 模板最后验证的 Dify 版本:v1.8.1(2025-09-08)
快速开始 在运行 兼容操作系统 的全新 Linux x86 / ARM 服务器上执行:
curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./bootstrap # 安装 Pigsty 依赖
./configure -c app/dify # 使用 Dify 配置模板
vi pigsty.yml # 编辑密码、域名、密钥等
./deploy.yml # 安装 Pigsty
./docker.yml # 安装 Docker 和 Compose
./app.yml # 安装 Dify
Dify 默认监听端口 5001。您可以通过浏览器访问 http://<ip>:5001 并设置您的初始用户凭据来登录。
Dify 启动后,您可以安装各种扩展、配置系统模型并开始使用它!
为什么要自托管 自托管 Dify 有很多原因,但主要动机是数据安全。Dify 提供的 DockerCompose 模板使用基本的默认数据库镜像,缺乏企业级功能,如高可用性、灾难恢复、监控、IaC 和 PITR 能力。
Pigsty 为 Dify 优雅地解决了这些问题,基于配置文件使用单个命令部署所有组件,并使用镜像解决中国地区访问挑战。这使得 Dify 部署和交付变得非常顺畅。它一次性处理 PostgreSQL 主数据库、PGVector 向量数据库、MinIO 对象存储、Redis、Prometheus 监控、Grafana 可视化、Nginx 反向代理和免费 HTTPS 证书。
Pigsty 确保所有 Dify 状态都存储在外部管理的服务中,包括 PostgreSQL 中的元数据和文件系统中的其他数据。通过 Docker Compose 启动的 Dify 实例成为可以随时销毁和重建的无状态应用程序,大大简化了运维。
安装 让我们从单节点 Dify 部署开始。我们稍后将介绍生产高可用部署方法。
首先,使用 Pigsty 的 标准安装过程 安装 Dify 所需的 PostgreSQL 实例:
curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./bootstrap # 准备 Pigsty 依赖
./configure -c app/dify # 使用 Dify 应用程序模板
vi pigsty.yml # 编辑配置文件,修改域名和密码
./deploy.yml # 安装 Pigsty 和各种数据库
当您使用 ./configure -c app/dify 命令时,Pigsty 会根据 conf/app/dify.yml 模板和您当前的环境自动生成配置文件。
您应该根据实际需要在生成的 pigsty.yml 配置文件中修改密码、域名和其他相关参数,然后使用 ./deploy.yml 执行标准安装过程。
接下来,运行 docker.yml 安装 Docker 和 Docker Compose,然后使用 app.yml 完成 Dify 部署:
./docker.yml # 安装 Docker 和 Docker Compose
./app.yml # 使用 Docker 部署 Dify 无状态组件
您可以在本地网络上通过 http://<your_ip_address>:5001 访问 Dify Web 管理界面。
首次登录时会提示设置默认用户名、邮箱和密码。
您也可以使用本地解析的占位符域名 dify.pigsty,或按照下面的配置使用带有 HTTPS 证书的真实域名。
配置 当您使用 ./configure -c app/dify 命令进行配置时,Pigsty 会根据 conf/app/dify.yml 模板和您当前的环境自动生成配置文件。以下是默认配置的详细说明:
all :
children :
# Dify 应用程序
dify :
hosts : { 10.10.10.10 : {} }
vars :
app : dify # 指定要安装的应用程序名称(在 apps 中)
apps : # 定义所有应用程序
dify : # 应用程序名称,应该有对应的 ~/pigsty/app/dify 文件夹
file : # 要创建的数据目录
- { path: /data/dify ,state: directory ,mode : 0755 }
conf : # 覆盖 /opt/dify/.env 配置文件
# 更改域名、镜像、代理、密钥
NGINX_SERVER_NAME : dify.pigsty
# 用于签名和加密的密钥,使用 `openssl rand -base64 42` 生成(务必更改!)
SECRET_KEY : sk-somerandomkey
# 默认使用端口 5001 暴露 DIFY nginx 服务
DIFY_PORT : 5001
# dify 文件存储位置?默认是 ./volume,我们将使用上面创建的另一个卷
DIFY_DATA : /data/dify
# 代理和镜像设置
#PIP_MIRROR_URL: https://pypi.tuna.tsinghua.edu.cn/simple
#SANDBOX_HTTP_PROXY: http://10.10.10.10:12345
#SANDBOX_HTTPS_PROXY: http://10.10.10.10:12345
# 数据库凭据
DB_USERNAME : dify
DB_PASSWORD : difyai123456
DB_HOST : 10.10.10.10
DB_PORT : 5432
DB_DATABASE : dify
VECTOR_STORE : pgvector
PGVECTOR_HOST : 10.10.10.10
PGVECTOR_PORT : 5432
PGVECTOR_USER : dify
PGVECTOR_PASSWORD : difyai123456
PGVECTOR_DATABASE : dify
PGVECTOR_MIN_CONNECTION : 2
PGVECTOR_MAX_CONNECTION : 10
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta
pg_users :
- { name: dify ,password: difyai123456 ,pgbouncer: true ,roles: [ dbrole_admin ] ,superuser: true ,comment : dify superuser }
pg_databases :
- { name: dify ,owner: dify ,revokeconn: true ,comment : dify main database }
- { name: dify_plugin ,owner: dify ,revokeconn: true ,comment : dify plugin_daemon database }
pg_hba_rules :
- { user: dify ,db: all ,addr: 172.17.0.0/16 ,auth: pwd ,title : 'allow dify access from local docker network' }
node_crontab : [ '00 01 * * * postgres /pg/bin/pg-backup full' ] # 每天凌晨 1 点进行完整备份
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }
vars : # 全局变量
version : v4.3.0 # pigsty 版本字符串
admin_ip : 10.10.10.10 # 管理节点 ip 地址
region : default # 上游镜像区域:default|china|europe
node_tune : oltp # 节点调优规格:oltp,olap,tiny,crit
pg_conf : oltp.yml # pgsql 调优规格:{oltp,olap,tiny,crit}.yml
docker_enabled : true # 在应用程序组上启用 docker
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
proxy_env : # 下载包和拉取 docker 镜像时的全局代理环境
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.tsinghua.edu.cn"
#http_proxy: 127.0.0.1:12345 # 在此处添加代理环境以下载包或拉取镜像
#https_proxy: 127.0.0.1:12345 # 通常代理格式为 http://user:pass@proxy.xxx.com
#all_proxy: 127.0.0.1:12345
infra_portal : # 域名和上游服务器
home : { domain : i.pigsty }
#minio : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
dify : # dify 的 nginx 服务器配置
domain : dify.pigsty # 替换为您自己的域名!
endpoint : "10.10.10.10:5001" # dify 服务端点:IP:PORT
websocket : true # 添加 websocket 支持
certbot : dify.pigsty # certbot 证书名称,使用 `make cert` 申请
repo_enabled : false
node_repo_modules : node,infra,pgsql
pg_version : 18
#----------------------------------#
# 凭据:务必更改这些密码!
#----------------------------------#
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
检查清单 以下是您需要关注的配置项检查清单:
硬件/软件:准备所需的机器资源 :Linux x86_64/arm64 服务器,主流 Linux 操作系统 的全新安装 网络/权限:SSH 免密登录访问权限,用户具有 免密 sudo 权限 确保机器在内网中有静态 IPv4 网络地址且可访问互联网 如果通过公网访问,确保您有可用的域名指向当前节点的 公网 IP 地址 确保使用 app/dify 配置模板并根据需要修改参数configure -c app/dify,并输入节点的内网主 IP 地址,或通过 -i <primary_ip> 命令行参数指定 您是否修改了所有密码相关的配置参数?【可选】 您是否修改了 PostgreSQL 集群业务用户密码和使用这些密码的应用程序配置?默认用户名 dify 和密码 difyai123456 是 Pigsty 为 Dify 生成的,请根据实际情况修改 在 Dify 的配置块中,请相应修改 DB_USERNAME、DB_PASSWORD、PGVECTOR_USER、PGVECTOR_PASSWORD 等参数 您是否修改了 Dify 的默认加密密钥?您可以使用 openssl rand -base64 42 随机生成密码字符串并填入 SECRET_KEY 参数 您是否修改了 Dify 使用的域名?将占位符域名 dify.pigsty 替换为您的实际域名,例如 dify.pigsty.cc 您可以使用 sed -ie 's/dify.pigsty/dify.pigsty.cc/g' pigsty.yml 修改 Dify 的域名 域名和 SSL 如果您想使用带有 HTTPS 证书的真实域名,需要在 pigsty.yml 配置文件中修改:
all :
children : # 集群定义
dify : # Dify 组
vars : # Dify 组变量
apps : # 应用程序配置
dify : # Dify 应用程序定义
conf : # Dify 应用程序配置
NGINX_SERVER_NAME : dify.pigsty
vars : # 全局参数
#certbot_sign: true # 使用 Certbot 申请免费 HTTPS 证书
certbot_email : your@email.com # 证书申请邮箱,用于过期通知,可选
infra_portal : # 配置 Nginx 服务器
dify : # Dify 服务器定义
domain : dify.pigsty # 请在此处替换为您自己的域名!
endpoint : "10.10.10.10:5001" # 请在此处指定 Dify 的 IP 和端口(默认自动配置)
websocket : true # Dify 需要启用 websocket
certbot : dify.pigsty # 指定 Certbot 证书名称
使用以下命令申请 Nginx 证书:
# 申请证书,也可以手动执行 /etc/nginx/sign-cert 脚本
make cert
# 上述 Makefile 快捷命令实际执行以下剧本任务:
./infra.yml -t nginx_certbot,nginx_reload -e certbot_sign = true
执行 app.yml 剧本重新部署 Dify 服务以使 NGINX_SERVER_NAME 配置生效。
文件备份 您可以使用 restic 备份 Dify 的文件存储(默认位于 /data/dify 目录),使用以下命令进行备份:
export RESTIC_REPOSITORY = /data/backups/dify # 指定 dify 备份目录
export RESTIC_PASSWORD = some-strong-password # 指定备份加密密码
mkdir -p ${ RESTIC_REPOSITORY } # 创建 dify 备份目录
restic init
创建 Restic 备份仓库后,您可以使用以下命令备份 Dify:
export RESTIC_REPOSITORY = /data/backups/dify # 指定 dify 备份目录
export RESTIC_PASSWORD = some-strong-password # 指定备份加密密码
restic backup /data/dify # 将 /dify 数据目录备份到仓库
restic snapshots # 查看备份快照列表
restic restore -t /data/dify 0b11f778 # 将快照 xxxxxx 恢复到 /data/dify
restic check # 定期检查仓库完整性
另一种更可靠的方法是使用 JuiceFS 将 MinIO 对象存储挂载到 /data/dify 目录,这样您就可以使用 MinIO/S3 存储文件状态。
如果您想将所有数据存储在 PostgreSQL 中,请考虑"使用 JuiceFS 将文件系统数据存储在 PostgreSQL 中"
例如,您可以创建另一个 dify_fs 数据库并将其用作 JuiceFS 的元数据存储:
METAURL = postgres://dify:difyai123456@:5432/dify_fs
OPTIONS =(
--storage postgres
--bucket :5432/dify_fs
--access-key dify
--secret-key difyai123456
${ METAURL }
jfs
)
juicefs format " ${ OPTIONS [@] } " # 创建 PG 文件系统
juicefs mount ${ METAURL } /data/dify -d # 后台挂载到 /data/dify 目录
juicefs bench /data/dify # 测试性能
juicefs umount /data/dify # 停止挂载
参考 Dify 自托管常见问题
8.5 - NocoDB:开源 Airtable 使用 NocoDB 将 PostgreSQL 数据库转变为智能电子表格,无代码数据库应用平台。
NocoDB 是一个开源的 Airtable 替代方案,可以将任何数据库转变为智能电子表格。
它提供了丰富的用户界面,让您无需编写代码即可创建强大的数据库应用。NocoDB 支持 PostgreSQL、MySQL、SQL Server 等多种数据库,是构建内部工具和数据管理系统的理想选择。
快速开始 在 Pigsty 软件模板目录中提供了 NocoDB 的 Docker Compose 配置文件:
检查并修改 .env 配置文件(根据需要调整数据库连接等配置)。
启动服务:
make up # 使用 Docker Compose 启动 NocoDB
访问 NocoDB:
管理命令 Pigsty 提供了便捷的 Makefile 命令来管理 NocoDB 服务:
make up # 启动 NocoDB 服务
make run # 使用 Docker 启动(连接外部 PostgreSQL)
make view # 显示 NocoDB 访问地址
make log # 查看容器日志
make info # 查看服务详细信息
make stop # 停止服务
make clean # 停止并移除容器
make pull # 拉取最新镜像
make rmi # 移除 NocoDB 镜像
make save # 保存镜像到 /tmp/nocodb.tgz
make load # 从 /tmp/nocodb.tgz 加载镜像
连接 PostgreSQL NocoDB 可以连接到 Pigsty 管理的 PostgreSQL 数据库。
在 NocoDB 界面中添加新项目时,选择「External Database」,然后输入 PostgreSQL 连接信息:
主机:10.10.10.10
端口:5432
数据库名:your_database
用户名:your_username
密码:your_password
SSL:禁用(或根据实际情况启用)
连接成功后,NocoDB 会自动读取数据库的表结构,您可以通过可视化界面进行数据管理。
功能特性 智能电子表格界面 :类似 Excel/Airtable 的用户体验多种视图 :网格、表单、看板、日历、画廊视图协作功能 :团队协作、权限管理、评论API 支持 :自动生成 REST API集成能力 :支持 Webhook、Zapier 等集成数据导入导出 :支持 CSV、Excel 等格式公式和验证 :支持复杂的数据计算和验证规则配置说明 NocoDB 的配置在 .env 文件中:
# 数据库连接(NocoDB 元数据存储)
NC_DB = pg://postgres:DBUser.Postgres@10.10.10.10:5432/nocodb
# JWT 密钥(建议修改)
NC_AUTH_JWT_SECRET = your-secret-key
# 其他配置
NC_PUBLIC_URL = http://nocodb.pigsty
NC_DISABLE_TELE = true
数据持久化 NocoDB 的元数据默认存储在外部 PostgreSQL 数据库中,应用数据也可以存储在 PostgreSQL 中。
如果使用本地存储,数据会保存在 /data/nocodb 目录中。
安全建议 修改默认密钥 :在 .env 文件中修改 NC_AUTH_JWT_SECRET使用强密码 :为管理员账户设置强密码配置 HTTPS :生产环境建议启用 HTTPS限制访问 :通过防火墙或 Nginx 限制访问权限定期备份 :定期备份 NocoDB 元数据库相关链接 8.6 - Teable:AI 无代码数据库 使用 Pigsty v4.3 自建 Teable,并接入外部 PostgreSQL 与 MinIO。
Teable 是面向团队协作的无代码数据库平台。
Pigsty v4.3 提供 app/teable 模板(conf/app/teable.yml),默认依赖 PostgreSQL + MinIO + Docker (不依赖 Redis)。
快速开始 curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/teable
vi pigsty.yml # 修改密码、域名、邮件参数
./deploy.yml # 安装基础设施、PostgreSQL、MinIO
./docker.yml
./app.yml
默认入口:
http://<IP>:8890http://tea.pigsty关键配置 模板会将以下参数写入 /opt/teable/.env:
POSTGRES_HOST/POSTGRES_PORT/POSTGRES_DB/POSTGRES_USER/POSTGRES_PASSWORDPRISMA_DATABASE_URLPUBLIC_ORIGIN(对外访问地址)PUBLIC_DATABASE_PROXYTEABLE_PORT(默认 8890)运维命令 cd /opt/teable
make up
make log
make down
参考 8.7 - Gitea:自建简易代码托管平台 使用 Pigsty 的 Compose 模板部署 Gitea,并接入外部 PostgreSQL。
Gitea 是轻量级开源 Git 托管平台。
Pigsty 的 app/gitea 模板默认就是 PostgreSQL 外部数据库模式 ,通过 .env 中 GITEA_DB_* 参数连接数据库。
快速开始 cd ~/pigsty/app/gitea
vi .env # 检查域名、端口、数据库连接
make up
默认入口:
Web:http://git.pigsty 或 http://<IP>:8889 SSH:<IP>:2222 数据库准备 bin/pgsql-user pg-meta dbuser_gitea
bin/pgsql-db pg-meta gitea
连接串示例:
postgres://dbuser_gitea:DBUser.Gitea@10.10.10.10:5432/gitea
常用命令 make up
make log
make stop
make clean
参考 8.8 - Wiki.js:维基百科站 如何使用 Wiki.js 搭建你自己的开源维基百科,并使用 Pigsty 管理的 PG 作为持久数据存储
公开 Demo 地址:http://wiki.pigsty.cc
太长;不看 cd app/wiki ; docker-compose up -d
准备数据库 # postgres://dbuser_wiki:DBUser.Wiki@10.10.10.10:5432/wiki
- { name: wiki, owner: dbuser_wiki, revokeconn: true , comment : wiki the api gateway database }
- { name: dbuser_wiki, password: DBUser.Wiki , pgbouncer: true , roles : [ dbrole_admin ] }
bin/createuser pg-meta dbuser_wiki
bin/createdb pg-meta wiki
容器配置 version : "3"
services :
wiki :
container_name : wiki
image : requarks/wiki:2
environment :
DB_TYPE : postgres
DB_HOST : 10.10.10.10
DB_PORT : 5432
DB_USER : dbuser_wiki
DB_PASS : DBUser.Wiki
DB_NAME : wiki
restart : unless-stopped
ports :
- "9002:3000"
Access Default Port for wiki: 9002 # add to nginx_upstream
- { name: wiki , domain: wiki.pigsty.cc , endpoint : "127.0.0.1:9002" }
./infra.yml -t nginx_config
ansible all -b -a 'nginx -s reload'
8.9 - Mattermost:开源团队协作 使用 Pigsty v4.3 部署 Mattermost,并将状态托管到外部 PostgreSQL。
Mattermost 是开源团队协作平台,可作为 Slack 的私有化替代方案。
Pigsty v4.3 提供 app/mattermost 配置模板(conf/app/mattermost.yml),默认将应用状态存放到外部 PostgreSQL,并将文件目录持久化到主机路径。
快速开始 curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/mattermost
vi pigsty.yml # 修改密码、域名
./deploy.yml
./docker.yml
./app.yml
默认访问地址:
http://<IP>:8065http://mm.pigsty首次访问需要在 Web 页面初始化管理员账号。
默认存储与连接 模板默认配置:
PostgreSQL 连接:POSTGRES_URL=postgres://dbuser_mattermost:DBUser.Mattermost@<IP>:5432/mattermost?... 持久化目录:/data/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes} 运维命令 cd /opt/mattermost
make up
make restart
make log
make stop
参考 8.10 - Maybe:个人财务管理 使用 Pigsty v4.3 自建 Maybe,并将数据存储到外部 PostgreSQL。
Maybe 是开源个人财务管理工具。
Pigsty v4.3 提供 app/maybe 配置模板(conf/app/maybe.yml)。该模板会把 Maybe 作为无状态容器部署,并将业务数据落到外部 PostgreSQL。
快速开始 curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/maybe
vi pigsty.yml # 必改:SECRET_KEY_BASE、数据库密码、域名
./deploy.yml
./docker.yml
./app.yml
默认访问地址:
http://<IP>:5002http://maybe.pigsty关键配置 在模板的 apps.maybe.conf 中重点关注:
SECRET_KEY_BASE:必须替换为随机密钥(例如 openssl rand -hex 64)DB_HOST/DB_PORT/DB_USERNAME/DB_PASSWORD/DB_DATABASEAPP_DOMAIN 与 MAYBE_PORT运维命令 app/maybe/Makefile 默认在 /opt/maybe 工作,请在部署后执行:
cd /opt/maybe
make up
make restart
make log
make db-setup
参考 8.11 - Metabase:BI 分析工具 使用 Metabase 进行快速的商业智能分析,友好的用户界面让团队自主探索数据。
Metabase 是一个快速、易用的开源商业智能工具,让您的团队无需 SQL 知识即可探索和可视化数据。
Metabase 提供友好的用户界面和丰富的图表类型,支持连接多种数据库,是企业数据分析的理想选择。
快速开始 在 Pigsty 软件模板目录中提供了 Metabase 的 Docker Compose 配置文件:
检查并修改 .env 配置文件:
启动服务:
make up # 使用 Docker Compose 启动 Metabase
访问 Metabase:
管理命令 Pigsty 提供了便捷的 Makefile 命令来管理 Metabase 服务:
make up # 启动 Metabase 服务
make run # 使用 Docker 启动(连接外部 PostgreSQL)
make view # 显示 Metabase 访问地址
make log # 查看容器日志
make info # 查看服务详细信息
make stop # 停止服务
make clean # 停止并移除容器
make pull # 拉取最新镜像
make rmi # 移除 Metabase 镜像
make save # 保存镜像到文件
make load # 从文件加载镜像
连接 PostgreSQL Metabase 可以连接到 Pigsty 管理的 PostgreSQL 数据库。
在 Metabase 初始化或添加数据库时,选择「PostgreSQL」,然后输入连接信息:
数据库类型:PostgreSQL
名称:自定义名称(如 "生产数据库")
主机:10.10.10.10
端口:5432
数据库名:your_database
用户名:dbuser_meta
密码:DBUser.Meta
连接成功后,Metabase 会自动扫描数据库结构,您可以开始创建问题和仪表板。
功能特性 无需 SQL :通过可视化界面构建查询丰富的图表类型 :折线图、柱状图、饼图、地图等交互式仪表板 :创建美观的数据仪表板自动刷新 :定时更新数据和仪表板权限管理 :精细的用户和数据访问控制SQL 模式 :高级用户可以直接编写 SQL嵌入功能 :将图表嵌入到其他应用告警功能 :数据变化自动通知配置说明 Metabase 的配置在 .env 文件中:
# Metabase 元数据库(建议使用 PostgreSQL)
MB_DB_TYPE = postgres
MB_DB_DBNAME = metabase
MB_DB_PORT = 5432
MB_DB_USER = dbuser_metabase
MB_DB_PASS = DBUser.Metabase
MB_DB_HOST = 10.10.10.10
# 应用配置
JAVA_OPTS = -Xmx2g
建议 :为 Metabase 使用独立的 PostgreSQL 数据库存储元数据。
数据持久化 Metabase 的元数据(用户、问题、仪表板等)存储在配置的数据库中。
如果使用 H2 数据库(默认),数据会保存在 /data/metabase 目录。强烈建议在生产环境中使用 PostgreSQL 作为元数据库。
性能优化 使用 PostgreSQL :替代默认的 H2 数据库增加内存 :通过 JAVA_OPTS=-Xmx4g 增加 JVM 内存数据库索引 :为常查询的字段创建索引结果缓存 :启用 Metabase 的查询结果缓存定时更新 :合理设置仪表板的自动刷新频率安全建议 修改默认凭据 :修改元数据库的用户名和密码启用 HTTPS :生产环境配置 SSL 证书配置认证 :启用 SSO 或 LDAP 认证限制访问 :通过防火墙限制访问定期备份 :备份 Metabase 元数据库相关链接 8.12 - Kong:API 网关 使用 Pigsty Compose 模板部署 Kong(PostgreSQL 后端)。
Kong 是开源 API Gateway。
Pigsty 的 app/kong 模板使用 PostgreSQL 作为配置存储,并自动执行一次迁移任务(kong-migration)。
快速开始 cd ~/pigsty/app/kong
vi .env # 检查 KONG_PG_* 与端口配置
make
默认端口:
Proxy HTTP:8000 Proxy HTTPS:8443 Admin API:8001 数据库准备 bin/pgsql-user pg-meta dbuser_kong
bin/pgsql-db pg-meta kong
连接串示例:
postgres://dbuser_kong:DBUser.Kong@10.10.10.10:5432/kong
常用命令 make log
make stop
make clean
make pull
参考 8.13 - Registry:容器镜像缓存 使用 Pigsty v4.3 部署 Docker Registry Pull-Through Cache 与可选 Web UI。
Pigsty v4.3 提供 app/registry 配置模板(conf/app/registry.yml),用于部署:
Docker Registry 缓存服务(默认 5000) 可选管理 UI(默认 5080) 快速开始 curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/registry
vi pigsty.yml # 修改域名、证书与端口(如需)
./deploy.yml
./docker.yml
./app.yml
默认入口:
Registry API:http://<IP>:5000 或 http://d.pigsty Registry UI:http://<IP>:5080 或 http://dui.pigsty 镜像数据目录默认为 /data/registry。
Docker 客户端配置 如果你使用 HTTP(无 TLS),Docker 需要显式信任该仓库:
{
"registry-mirrors" : [ "http://d.pigsty" ],
"insecure-registries" : [ "d.pigsty:5000" ]
}
修改 /etc/docker/daemon.json 后重启 Docker:
运维命令 app/registry/Makefile 默认在 /opt/registry 工作:
cd /opt/registry
make up
make status
make health
make log
参考 8.15 - ByteBase:模式迁移 使用 Pigsty 提供的 Docker Compose 模板部署 Bytebase,并接入外部 PostgreSQL。
Bytebase 是数据库 Schema 变更与版本管理工具。
Pigsty 在 app/bytebase 中提供了可直接使用的 Compose 模板,默认监听 8887,并通过 BB_PGURL 连接外部 PostgreSQL。
快速开始 cd ~/pigsty/app/bytebase
vi .env # 检查 BB_PORT / BB_DOMAIN / BB_PGURL
make up
访问:
http://ddl.pigstyhttp://<IP>:8887首次启动后,请按 Bytebase 向导初始化管理员账号。
外部 PostgreSQL 默认连接串示例:
postgresql://dbuser_bytebase:DBUser.Bytebase@10.10.10.10:5432/bytebase?sslmode= prefer
可先在 Pigsty 中创建业务用户与数据库:
bin/pgsql-user pg-meta dbuser_bytebase
bin/pgsql-db pg-meta bytebase
常用命令 make up
make log
make info
make stop
make clean
参考 8.16 - PGAdmin:GUI 工具 使用 Docker 拉起 PgAdmin4,并加载 Pigsty 服务器列表
pgAdmin 是最受欢迎且功能丰富的 PostgreSQL 开源管理和开发平台,PostgreSQL 是世界上最先进的开源数据库。
快速开始 Pigsty 内置(但可选)支持 pgAdmin,它使用 Docker Compose 启动 pgadmin:
./docker.yml
./app.yml -e app = pgadmin
pgadmin 的默认端口是 8885,您可以通过 IP:端口访问它:http://10.10.10.10:8885。
默认凭据在 .env 中定义,用户名:admin@pigsty.cc,密码:pigsty。
自定义 在 /opt/pgadmin/.env 中自定义 pgadmin 配置并使用 docker compose 管理它。
您还可以自定义 apps 参数并使用以下方式覆盖默认 .env 配置:
all :
children :
infra :
hosts :
10.10.10.10 : { infra_seq : 1 }
vars :
docker_enabled : true
app : pgadmin # 指定要安装的应用程序名称(pgadmin)(在 apps 中)
apps : # 定义所有应用程序
pgadmin : # pgadmin 应用程序的定义
conf : # 覆盖 /opt/pgadmin/.env
PGADMIN_DEFAULT_EMAIL : your@email.com
PGADMIN_DEFAULT_PASSWORD : yourPassword
PGADMIN_LISTEN_ADDRESS : 0.0.0.0
PGADMIN_PORT : 8885
PGADMIN_SERVER_JSON_FILE : /pgadmin4/servers.json
PGADMIN_REPLACE_SERVERS_ON_STARTUP : true
要启动应用程序,运行:
域名和证书 要通过 nginx(而不是直接访问端口 8885)访问 pgadmin,请使用以下方式配置 基础设施门户 :
all :
vars :
infra_portal :
home : { domain : h.pigsty }
grafana : { domain: g.pigsty ,endpoint : "${admin_ip}:3000" , websocket : true }
vmetrics : { domain: v.pigsty ,endpoint : "${admin_ip}:8428" }
alertmanager : { domain: a.pigsty ,endpoint : "${admin_ip}:9059" }
blackbox : { endpoint : "${admin_ip}:9115" }
vlogs : { endpoint : "${admin_ip}:9428" }
# 在此处添加 pgadmin 上游服务器定义
pgadmin : { domain: adm.pigsty ,endpoint : "127.0.0.1:8885" }
然后运行 make nginx 更新 nginx 配置,并在 /etc/hosts 或 本地 / 公共 DNS 服务器中配置 本地静态 DNS 记录 <your_ip_address> adm.pigsty。
Pigsty 将自动为 infra_portal 中列出的域名签发自签名 SSL 证书。
如果您想使用真实域名,请定义 certbot 条目并运行 make cert,查看 SSL 证书 了解详情。
all :
vars : # 确保您的域名(adm.pigsty.cc)解析到您的公网 IP
certbot_sign : true # 使用 certbot 签发真实 HTTPS 证书(需要互联网访问!)
infra_portal :
pgadmin : { domain: adm.pigsty.cc ,endpoint : "127.0.0.1:8885" , certbot : adm.pigsty.cc }
使用方法 Pigsty 的 Pgadmin 应用模板默认使用 8885 端口,您可以通过以下地址访问:
http://adm.pigsty 或 http://10.10.10.10:8885
默认用户名与密码: admin@pigsty.cc / pigsty
make up # 使用 docker compose 启动 pgadmin
make run # 使用 docker 启动 pgadmin
make view # 打印 pgadmin 访问点
make log # tail -f pgadmin 日志
make info # 使用 jq 检查 pgadmin
make stop # 停止 pgadmin 容器
make clean # 移除 pgadmin 容器
make conf # 使用 pigsty pg 服务器列表配置 pgadmin
make dump # 从 pgadmin 容器导出 servers.json
make pull # 拉取最新的 pgadmin 镜像
make rmi # 移除 pgadmin 镜像
make save # 保存 pgadmin 镜像到 /tmp/pgadmin.tgz
make load # 从 /tmp 加载 pgadmin 镜像
Demo 公开 Demo 地址:http://adm.pigsty.cc
默认用户名与密码: admin@pigsty.cc / pigsty
8.17 - PGWeb:网页客户端 使用 Docker 拉起 PGWEB,以便从浏览器进行小批量在线数据查询
PGWeb客户端工具 PGWeb 是一款基于浏览器的 PG 客户端工具,使用以下命令,在元节点上拉起 PGWEB 服务,默认为主机8886端口。可使用域名: http://cli.pigsty 访问,公开 Demo:http://cli.pigsty.cc。
# docker stop pgweb; docker rm pgweb
docker run --init --name pgweb --restart always --detach --publish 8886:8081 sosedoff/pgweb
用户需要自行填写数据库连接串,例如默认 CMDB 的连接串:
postgres://dbuser_dba:DBUser.DBA@10.10.10.10:5432/meta?sslmode=disable
公开 Demo 地址:http://cli.pigsty.cc
使用 Docker Compose 拉起 PGWEB 容器:
cd ~/pigsty/app/pgweb ; docker-compose up -d
接下来,访问您本机的 8886 端口,即可看到 PGWEB 的 UI 界面: http://10.10.10.10:8886
您可以尝试使用下面的 URL 连接串,通过 PGWEB 连接至数据库实例并进行探索。
postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta?sslmode= disable
postgres://test:test@10.10.10.11:5432/test?sslmode= disable
快捷方式 make up # pull up pgweb with docker-compose
make run # launch pgweb with docker
make view # print pgweb access point
make log # tail -f pgweb logs
make info # introspect pgweb with jq
make stop # stop pgweb container
make clean # remove pgweb container
make pull # pull latest pgweb image
make rmi # remove pgweb image
make save # save pgweb image to /tmp/pgweb.tgz
make load # load pgweb image from /tmp
8.18 - PostgREST:自动 API 使用 Pigsty Compose 模板部署 PostgREST,基于 PostgreSQL 模式自动生成 REST API。
PostgREST 可以将 PostgreSQL schema 直接暴露为 REST API。
Pigsty 提供 app/postgrest 模板,默认端口 8884。
快速开始 cd ~/pigsty/app/postgrest
vi .env # 检查 DB_URI / DB_SCHEMA / JWT
make up
默认入口:
http://<IP>:8884若配置了入口域名,可通过 http://api.pigsty 访问 关键配置 .env 常用参数:
POSTGREST_DB_URI:数据库连接串POSTGREST_DB_SCHEMA:暴露的 schema(默认 pigsty)POSTGREST_DB_ANON_ROLE:匿名角色POSTGREST_JWT_SECRET:JWT 密钥Swagger UI(可选) 可单独拉起 Swagger UI 预览 API:
docker run --rm --name swagger -p 8882:8080 \
-e API_URL = http://10.10.10.10:8884 \
swaggerapi/swagger-ui
访问 http://<IP>:8882。
常用命令 make up
make log
make stop
make clean
参考 8.19 - Electric:PostgreSQL 同步引擎 使用 Pigsty v4.3 自建 Electric,同步 PostgreSQL 数据到前端应用,支持部分复制与实时分发。
Electric 是 PostgreSQL 同步引擎,专注于将数据库变更高效分发到前端/边缘应用。
Pigsty 在 v4.3 提供了 app/electric 配置模板(conf/app/electric.yml),可一键完成数据库、容器与入口配置。
快速开始 curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/electric
vi pigsty.yml # 修改域名、密码、密钥
./deploy.yml
./docker.yml
./app.yml
默认访问地址:
http://<IP>:8002http://elec.pigsty(按模板默认域名)指标端口默认 8003(ELECTRIC_PROMETHEUS_PORT)。
关键配置 conf/app/electric.yml 会在 apps.electric.conf 中覆盖 /opt/electric/.env。常见参数:
DATABASE_URL:Electric 使用的 PostgreSQL 连接串(需要复制权限)ELECTRIC_PORT:Electric HTTP 服务端口(默认 8002)ELECTRIC_PROMETHEUS_PORT:指标端口(默认 8003)ELECTRIC_INSECURE:开发环境可设为 true,生产环境建议关闭并使用密钥运维命令 cd /opt/electric
make up
make logs
make down
参考 8.20 - Jupyter:笔记本 AI IDE 使用 Jupyter Lab 并访问 PostgreSQL 数据库,组合使用 SQL 与 Python 的能力进行数据分析。
Jupyter Lab 是基于 IPython Notebook 的完整数据科学研发环境,可用于数据分析与可视化。
Pigsty 提供了 Docker Compose 模板,可以一键在容器中启动 Jupyter Lab 服务,并方便地访问 PostgreSQL 数据库。
快速开始 在 Pigsty 软件模板目录中提供了 Jupyter 的 Docker Compose 配置文件:
修改默认密码,编辑 .env 文件中的 JUPYTER_TOKEN 参数(默认值为 pigsty)。
创建数据目录并启动服务:
make dir # 创建 /data/jupyter 目录并设置权限
make up # 使用 Docker Compose 启动服务
访问 Jupyter Lab:
管理命令 Pigsty 提供了便捷的 Makefile 命令来管理 Jupyter 服务:
make up # 启动 Jupyter Lab 服务
make dir # 创建 /data/jupyter 数据目录
make log # 查看容器日志
make info # 显示服务信息
make stop # 停止服务
make clean # 停止并移除容器
make pull # 拉取最新镜像
make save # 保存 Docker 镜像到文件
make load # 从文件加载 Docker 镜像
访问 PostgreSQL 数据库 在 Jupyter Lab 中访问 PostgreSQL 数据库需要先安装驱动。
在 Jupyter Lab 的 Terminal 中执行:
pip install psycopg2-binary psycopg2
然后在 Notebook 中使用 psycopg2 驱动访问 PostgreSQL:
import psycopg2
# 连接到 PostgreSQL 数据库
conn = psycopg2 . connect ( 'postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta' )
# 执行查询
cursor = conn . cursor ()
cursor . execute ( "SELECT date, new_cases FROM covid.country_history WHERE country_code = 'CN';" )
data = cursor . fetchall ()
# 处理数据
for row in data :
print ( row )
你也可以使用其他 Python 数据分析库,如 Pandas、SQLAlchemy 等:
import pandas as pd
from sqlalchemy import create_engine
# 使用 SQLAlchemy 连接
engine = create_engine ( 'postgresql://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta' )
# 使用 Pandas 读取数据
df = pd . read_sql ( "SELECT * FROM covid.country_history WHERE country_code = 'CN'" , engine )
print ( df . head ())
配置说明 Jupyter 服务的配置在 .env 文件中:
JUPYTER_TOKEN = pigsty # Jupyter Lab 访问 Token(密码)
如果需要修改端口或其他配置,可以编辑 docker-compose.yml 文件:
services :
jupyter :
image : jupyter/scipy-notebook:latest
ports :
- "8888:8888"
volumes :
- /data/jupyter:/home/jovyan/work
environment :
- JUPYTER_TOKEN=${JUPYTER_TOKEN}
安装额外的 Python 包 Jupyter 容器支持使用 pip 或 conda 安装 Python 包。
在 Jupyter Lab 的 Terminal 中执行:
# 使用 pip 安装
pip install numpy pandas matplotlib seaborn scikit-learn
# 使用 conda 安装
conda install -c conda-forge geopandas
# 使用国内镜像加速(可选)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy
数据持久化 Jupyter 的数据存储在 /data/jupyter 目录中,该目录会被挂载到容器的 /home/jovyan/work 路径。
所有保存在 work 目录下的 Notebook 和数据文件都会持久化保存在宿主机上,即使容器重启或删除也不会丢失。
安全建议 强烈建议修改默认的 Token(密码)!
编辑 .env 文件,修改 JUPYTER_TOKEN 的值 重启服务:make up 如果在生产环境中使用 Jupyter Lab,还应该:
使用强密码或禁用 Token 认证 配置 HTTPS 访问 限制网络访问权限 定期备份数据目录 相关链接 8.21 - 数据应用 基于 PostgreSQL 的数据可视化应用
8.22 - PGLOG:PG自带日志分析应用 Pigsty 自带的,用于分析 PostgreSQL CSV 日志样本的一个样例 Applet
PGLOG 是 Pigsty 自带的一个样例应用,固定使用 MetaDB 中pglog.sample表作为数据来源。您只需要将日志灌入该表,然后访问相关 Dashboard 即可。
Pigsty 提供了一些趁手的命令,用于拉取 csv 日志,并灌入样本表中。在元节点上,默认提供下列快捷命令:
catlog [ node = localhost] [ date = today] # 打印CSV日志到标准输出
pglog # 从标准输入灌入CSVLOG
pglog12 # 灌入PG12格式的CSVLOG
pglog13 # 灌入PG13格式的CSVLOG
pglog14 # 灌入PG14格式的CSVLOG (=pglog)
catlog | pglog # 分析当前节点当日的日志
catlog node-1 '2021-07-15' | pglog # 分析node-1在2021-07-15的csvlog
接下来,您可以访问以下的连接,查看样例日志分析界面。
catlog命令从特定节点拉取特定日期的 CSV 数据库日志,写入stdout
默认情况下,catlog会拉取当前节点当日的日志,您可以通过参数指定节点与日期。
组合使用pglog与catlog,即可快速拉取数据库 CSV 日志进行分析。
catlog | pglog # 分析当前节点当日的日志
catlog node-1 '2021-07-15' | pglog # 分析node-1在2021-07-15的csvlog
8.23 - NOAA ISD 全球气象站历史数据查询 以 ISD 数据集为例,展现如何将数据导入数据库中
如果您拥有数据库后不知道干点什么,不妨参试试这个开源项目:Vonng/isd
您可以直接复用监控系统 Grafana,以交互式的方式查阅近30000个地面气象站过去120年间的亚小时级气象数据。
这是一个功能完成的数据应用,可以查询全球30000个地表气象站从1901年来的气象观测记录。
项目地址:https://github.com/Vonng/isd
在线 Demo 地址:https://demo.pigsty.cc/d/isd-overview
快速上手 克隆本仓库
git clone https://github.com/Vonng/isd.git; cd isd;
准备一个 PostgreSQL 实例
该 PostgreSQL 实例应当启用了 PostGIS 扩展。使用 PGURL 环境变量传递数据库连接信息:
# Pigsty 默认使用的管理员账号是 dbuser_dba,密码是 DBUser.DBA
export PGURL = postgres://dbuser_dba:DBUser.DBA@127.0.0.1:5432/meta?sslmode= disable
psql " ${ PGURL } " -c 'SELECT 1' # 检查连接是否可用
获取并导入 ISD 气象站元数据
这是一份每日更新的气象站元数据,包含了气象站的经纬度、海拔、名称、国家、省份等信息,使用以下命令下载并导入。
make reload-station # 相当于先下载最新的Station数据再加载:get-station + load-station
获取并导入最新的 isd.daily 数据
isd.daily 是一个每日更新的数据集,包含了全球各气象站的日观测数据摘要,使用以下命令下载并导入。
请注意,直接从 NOAA 网站下载的原始数据需要经过解析 方可入库,所以你需要下载或构建一个 ISD 数据 Parser。
make get-parser # 从 Github 下载 Parser 二进制,当然你也可以用 make build 直接用 go 构建。
make reload-daily # 下载本年度最新的 isd.daily 数据并导入数据库中
加载解析好的 CSV 数据集
ISD Daily 数据集有一些脏数据与 重复数据 ,如果你不想手工解析处理清洗,这里也提供了一份解析好的稳定 CSV 数据集。
该数据集包含了截止到 2023-06-24 的 isd.daily 数据,你可以直接下载并导入 PostgreSQL 中,不需要 Parser,
make get-stable # 从 Github 上获取稳定的 isd.daily 历史数据集。
make load-stable # 将下载好的稳定历史数据集加载到 PostgreSQL 数据库中。
更多数据 ISD 数据集有两个部分是每日更新的,气象站元数据,以及最新年份的 isd.daily (如 2023 年的 Tarball)。
你可以使用以下命令下载并刷新这两个部分。如果数据集没有更新,那么这些命令不会重新下载同样的数据包
make reload # 实际上是:reload-station + reload-daily
你也可以使用以下命令下载并加载特定年份的 isd.daily 数据:
bin/get-daily 2022 # 获取 2022 年的每日气象观测摘要 (1900-2023)
bin/load-daily " ${ PGURL } " 2022 # 加载 2022 年的每日气象观测摘要 (1900-2023)
除了每日摘要 isd.daily, ISD 还提供了一份更详细的亚小时级原始观测记录 isd.hourly,下载与加载的方式与前者类似:
bin/get-hourly 2022 # 下载特定某一年的小时级观测记录(例如2022年,可选 1900-2023)
bin/load-hourly " ${ PGURL } " 2022 # 加载特定某一年的小时级观测记录
数据 数据集概要 ISD 提供了四个数据集:亚小时级原始观测数据,每日统计摘要数据,月度统计摘要,年度统计摘要
数据集 备注 ISD Hourly 亚小时级观测记录 ISD Daily 每日统计摘要 ISD Monthly 没有用到,因为可以从 isd.daily 计算生成 ISD Yearly 没有用到,因为可以从 isd.daily 计算生成
每日摘要数据集
压缩包大小 2.8GB (截止至 2023-06-24) 表大小 24GB,索引大小 6GB,PostgreSQL 中总大小约为 30GB 如果启用了 timescaledb 压缩,总大小可以压缩到 4.5 GB。 亚小时级观测数据级
压缩包总大小 117GB 灌入数据库后表大小 1TB+,索引大小 600GB+,总大小 1.6TB 数据库模式 气象站元数据表
CREATE TABLE isd . station
(
station VARCHAR ( 12 ) PRIMARY KEY ,
usaf VARCHAR ( 6 ) GENERATED ALWAYS AS ( substring ( station , 1 , 6 )) STORED ,
wban VARCHAR ( 5 ) GENERATED ALWAYS AS ( substring ( station , 7 , 5 )) STORED ,
name VARCHAR ( 32 ),
country VARCHAR ( 2 ),
province VARCHAR ( 2 ),
icao VARCHAR ( 4 ),
location GEOMETRY ( POINT ),
longitude NUMERIC GENERATED ALWAYS AS ( Round ( ST_X ( location ):: NUMERIC , 6 )) STORED ,
latitude NUMERIC GENERATED ALWAYS AS ( Round ( ST_Y ( location ):: NUMERIC , 6 )) STORED ,
elevation NUMERIC ,
period daterange ,
begin_date DATE GENERATED ALWAYS AS ( lower ( period )) STORED ,
end_date DATE GENERATED ALWAYS AS ( upper ( period )) STORED
);
每日摘要表
CREATE TABLE IF NOT EXISTS isd . daily
(
station VARCHAR ( 12 ) NOT NULL , -- station number 6USAF+5WBAN
ts DATE NOT NULL , -- observation date
-- 气温 & 露点
temp_mean NUMERIC ( 3 , 1 ), -- mean temperature ℃
temp_min NUMERIC ( 3 , 1 ), -- min temperature ℃
temp_max NUMERIC ( 3 , 1 ), -- max temperature ℃
dewp_mean NUMERIC ( 3 , 1 ), -- mean dew point ℃
-- 气压
slp_mean NUMERIC ( 5 , 1 ), -- sea level pressure (hPa)
stp_mean NUMERIC ( 5 , 1 ), -- station pressure (hPa)
-- 可见距离
vis_mean NUMERIC ( 6 ), -- visible distance (m)
-- 风速
wdsp_mean NUMERIC ( 4 , 1 ), -- average wind speed (m/s)
wdsp_max NUMERIC ( 4 , 1 ), -- max wind speed (m/s)
gust NUMERIC ( 4 , 1 ), -- max wind gust (m/s)
-- 降水 / 雪深
prcp_mean NUMERIC ( 5 , 1 ), -- precipitation (mm)
prcp NUMERIC ( 5 , 1 ), -- rectified precipitation (mm)
sndp NuMERIC ( 5 , 1 ), -- snow depth (mm)
-- FRSHTT (Fog/Rain/Snow/Hail/Thunder/Tornado) 雾/雨/雪/雹/雷/龙卷
is_foggy BOOLEAN , -- (F)og
is_rainy BOOLEAN , -- (R)ain or Drizzle
is_snowy BOOLEAN , -- (S)now or pellets
is_hail BOOLEAN , -- (H)ail
is_thunder BOOLEAN , -- (T)hunder
is_tornado BOOLEAN , -- (T)ornado or Funnel Cloud
-- 统计聚合使用的记录数
temp_count SMALLINT , -- record count for temp
dewp_count SMALLINT , -- record count for dew point
slp_count SMALLINT , -- record count for sea level pressure
stp_count SMALLINT , -- record count for station pressure
wdsp_count SMALLINT , -- record count for wind speed
visib_count SMALLINT , -- record count for visible distance
-- 气温标记
temp_min_f BOOLEAN , -- aggregate min temperature
temp_max_f BOOLEAN , -- aggregate max temperature
prcp_flag CHAR , -- precipitation flag: ABCDEFGHI
PRIMARY KEY ( station , ts )
); -- PARTITION BY RANGE (ts);
亚小时级原始观测数据表
ISD Hourly CREATE TABLE IF NOT EXISTS isd . hourly
(
station VARCHAR ( 12 ) NOT NULL , -- station id
ts TIMESTAMP NOT NULL , -- timestamp
-- air
temp NUMERIC ( 3 , 1 ), -- [-93.2,+61.8]
dewp NUMERIC ( 3 , 1 ), -- [-98.2,+36.8]
slp NUMERIC ( 5 , 1 ), -- [8600,10900]
stp NUMERIC ( 5 , 1 ), -- [4500,10900]
vis NUMERIC ( 6 ), -- [0,160000]
-- wind
wd_angle NUMERIC ( 3 ), -- [1,360]
wd_speed NUMERIC ( 4 , 1 ), -- [0,90]
wd_gust NUMERIC ( 4 , 1 ), -- [0,110]
wd_code VARCHAR ( 1 ), -- code that denotes the character of the WIND-OBSERVATION.
-- cloud
cld_height NUMERIC ( 5 ), -- [0,22000]
cld_code VARCHAR ( 2 ), -- cloud code
-- water
sndp NUMERIC ( 5 , 1 ), -- mm snow
prcp NUMERIC ( 5 , 1 ), -- mm precipitation
prcp_hour NUMERIC ( 2 ), -- precipitation duration in hour
prcp_code VARCHAR ( 1 ), -- precipitation type code
-- sky
mw_code VARCHAR ( 2 ), -- manual weather observation code
aw_code VARCHAR ( 2 ), -- auto weather observation code
pw_code VARCHAR ( 1 ), -- weather code of past period of time
pw_hour NUMERIC ( 2 ), -- duration of pw_code period
-- misc
-- remark TEXT,
-- eqd TEXT,
data JSONB -- extra data
) PARTITION BY RANGE ( ts );
解析器 NOAA ISD 提供的原始数据是高度压缩的专有格式,需要通过解析器加工,才能转换为数据库表的格式。
针对 Daily 与 Hourly 两份数据集,这里提供了两个 Parser: isdd and isdh 。
这两个解析器都以年度数据压缩包作为输入,产生 CSV 结果作为输出,以管道的方式工作,如下所示:
NAME
isd -- Intergrated Surface Dataset Parser
SYNOPSIS
isd daily [ -i <input| stdin>] [ -o <output| stout>] [ -v]
isd hourly [ -i <input| stdin>] [ -o <output| stout>] [ -v] [ -d raw| ts-first| hour-first]
DESCRIPTION
The isd program takes noaa isd daily/hourly raw tarball data as input.
and generate parsed data in csv format as output. Works in pipe mode
cat data/daily/2023.tar.gz | bin/isd daily -v | psql ${ PGURL } -AXtwqc "COPY isd.daily FROM STDIN CSV;"
isd daily -v -i data/daily/2023.tar.gz | psql ${ PGURL } -AXtwqc "COPY isd.daily FROM STDIN CSV;"
isd hourly -v -i data/hourly/2023.tar.gz | psql ${ PGURL } -AXtwqc "COPY isd.hourly FROM STDIN CSV;"
OPTIONS
-i <input> input file, stdin by default
-o <output> output file, stdout by default
-p <profpath> pprof file path, enable if specified
-d de-duplicate rows for hourly dataset ( raw, ts-first, hour-first)
-v verbose mode
-h print help
用户界面 这里提供了几个使用 Grafana 制作的 Dashboard,可以用于探索 ISD 数据集,查询气象站与历史气象数据。
ISD Overview
全局概览,总体指标与气象站导航。
ISD Country
展示单个国家/地区内所有的气象站。
ISD Station
展示单个气象站的详细信息,元数据,天/月/年度汇总指标。
ISD Station Dashboard
ISD Detail
展示一个气象站原始亚小时级观测指标数据,需要 isd.hourly 数据集。
ISD Station Dashboard
8.24 - COVID-19 数据大盘 Pigsty 自带的,用于展示世界卫生组织官方 COVID 疫情数据的一个样例 Applet
Covid 是 Pigsty 自带的,用于展示世界卫生组织官方疫情数据大盘的一个样例 Applet。
您可以查阅每个国家与地区 COVID-19 的感染与死亡案例,以及全球的疫情趋势。
概览 GitHub 仓库地址:https://github.com/Vonng/pigsty-app/tree/master/covid
在线 Demo 地址:https://demo.pigsty.cc/d/covid
安装 在管理节点上进入应用目录,执行make以完成安装。
其他一些子任务:
make reload # download latest data and pour it again
make ui # install grafana dashboards
make sql # install database schemas
make download # download latest data
make load # load downloaded data into database
make reload # download latest data and pour it into database
8.25 - StackOverflow 调研 分析 StackOverflow 最近七年全球开发者调研数据中关于数据库的部分
概览 GitHub 仓库地址:https://github.com/Vonng/pigsty-app/tree/master/db
在线 Demo 地址:https://demo.pigsty.cc/d/sf-survey
8.27 - 云上算力价格计算器 分析阿里云 / AWS 上算力与存储的价格 (ECS/ESSD)
概览 GitHub 仓库地址:https://github.com/Vonng/pigsty-app/tree/master/cloud
在线 Demo 地址:https://demo.pigsty.cc/d/ecs
文章地址:《剖析算力成本:阿里云真降价了吗? 》
数据源 Aliyun ECS 价格可以在 价格计算器 - 定价详情 - 价格下载 中获取 CSV 原始数据。
模式 下载 阿里云 价格明细并导入分析
CREATE EXTENSION file_fdw ;
CREATE SERVER fs FOREIGN DATA WRAPPER file_fdw ;
DROP FOREIGN TABLE IF EXISTS aliyun_ecs CASCADE ;
CREATE FOREIGN TABLE aliyun_ecs
(
"region" text ,
"system" text ,
"network" text ,
"isIO" bool ,
"instanceId" text ,
"hourlyPrice" numeric ,
"weeklyPrice" numeric ,
"standard" numeric ,
"monthlyPrice" numeric ,
"yearlyPrice" numeric ,
"2yearPrice" numeric ,
"3yearPrice" numeric ,
"4yearPrice" numeric ,
"5yearPrice" numeric ,
"id" text ,
"instanceLabel" text ,
"familyId" text ,
"serverType" text ,
"cpu" text ,
"localStorage" text ,
"NvmeSupport" text ,
"InstanceFamilyLevel" text ,
"EniTrunkSupported" text ,
"InstancePpsRx" text ,
"GPUSpec" text ,
"CpuTurboFrequency" text ,
"InstancePpsTx" text ,
"InstanceTypeId" text ,
"GPUAmount" text ,
"InstanceTypeFamily" text ,
"SecondaryEniQueueNumber" text ,
"EniQuantity" text ,
"EniPrivateIpAddressQuantity" text ,
"DiskQuantity" text ,
"EniIpv6AddressQuantity" text ,
"InstanceCategory" text ,
"CpuArchitecture" text ,
"EriQuantity" text ,
"MemorySize" numeric ,
"EniTotalQuantity" numeric ,
"PhysicalProcessorModel" text ,
"InstanceBandwidthRx" numeric ,
"CpuCoreCount" numeric ,
"Generation" text ,
"CpuSpeedFrequency" numeric ,
"PrimaryEniQueueNumber" text ,
"LocalStorageCategory" text ,
"InstanceBandwidthTx" text ,
"TotalEniQueueQuantity" text
) SERVER fs OPTIONS ( filename '/tmp/aliyun-ecs.csv' , format 'csv' , header 'true' );
AWS EC2 同理,可以从 Vantage 下载价格清单:
DROP FOREIGN TABLE IF EXISTS aws_ec2 CASCADE ;
CREATE FOREIGN TABLE aws_ec2
(
"name" TEXT ,
"id" TEXT ,
"Memory" TEXT ,
"vCPUs" TEXT ,
"GPUs" TEXT ,
"ClockSpeed" TEXT ,
"InstanceStorage" TEXT ,
"NetworkPerformance" TEXT ,
"ondemand" TEXT ,
"reserve" TEXT ,
"spot" TEXT
) SERVER fs OPTIONS ( filename '/tmp/aws-ec2.csv' , format 'csv' , header 'true' );
DROP VIEW IF EXISTS ecs ;
CREATE VIEW ecs AS
SELECT "region" AS region ,
"id" AS id ,
"instanceLabel" AS name ,
"familyId" AS family ,
"CpuCoreCount" AS cpu ,
"MemorySize" AS mem ,
round ( "5yearPrice" / "CpuCoreCount" / 60 , 2 ) AS ycm5 , -- ¥ / (core·month)
round ( "4yearPrice" / "CpuCoreCount" / 48 , 2 ) AS ycm4 , -- ¥ / (core·month)
round ( "3yearPrice" / "CpuCoreCount" / 36 , 2 ) AS ycm3 , -- ¥ / (core·month)
round ( "2yearPrice" / "CpuCoreCount" / 24 , 2 ) AS ycm2 , -- ¥ / (core·month)
round ( "yearlyPrice" / "CpuCoreCount" / 12 , 2 ) AS ycm1 , -- ¥ / (core·month)
round ( "standard" / "CpuCoreCount" , 2 ) AS ycmm , -- ¥ / (core·month)
round ( "hourlyPrice" / "CpuCoreCount" * 720 , 2 ) AS ycmh , -- ¥ / (core·month)
"CpuSpeedFrequency" :: NUMERIC AS freq ,
"CpuTurboFrequency" :: NUMERIC AS freq_turbo ,
"Generation" AS generation
FROM aliyun_ecs
WHERE system = 'linux' ;
DROP VIEW IF EXISTS ec2 ;
CREATE VIEW ec2 AS
SELECT id ,
name ,
split_part ( id , '.' , 1 ) as family ,
split_part ( id , '.' , 2 ) as spec ,
( regexp_match ( split_part ( id , '.' , 1 ), '^[a-zA-Z]+(\d)[a-z0-9]*' ))[ 1 ] as gen ,
regexp_substr ( "vCPUs" , '^[0-9]+' ):: int as cpu ,
regexp_substr ( "Memory" , '^[0-9]+' ):: int as mem ,
CASE spot
WHEN 'unavailable' THEN NULL
ELSE round (( regexp_substr ( "spot" , '([0-9]+.[0-9]+)' ):: NUMERIC * 7 . 2 ), 2 ) END AS spot ,
CASE ondemand
WHEN 'unavailable' THEN NULL
ELSE round (( regexp_substr ( "ondemand" , '([0-9]+.[0-9]+)' ):: NUMERIC * 7 . 2 ), 2 ) END AS ondemand ,
CASE reserve
WHEN 'unavailable' THEN NULL
ELSE round (( regexp_substr ( "reserve" , '([0-9]+.[0-9]+)' ):: NUMERIC * 7 . 2 ), 2 ) END AS reserve ,
"ClockSpeed" AS freq
FROM aws_ec2 ;
9 - 模板 开箱即用的配置模板,针对具体场景的配置示例,以及配置文件的详细解释。
Pigsty 提供了多种开箱即用的配置模板,适用于不同的使用场景。
您可以在 configure 时使用 -c 指定一个配置模板。如果没有指定配置模板,将会使用默认的 meta 模版。
9.1 - 单机模版 9.2 - meta Pigsty 默认使用的配置模板,单节点,覆盖核心功能,标准单机配置,在线安装,本地备份仓库。
meta 配置模板是 Pigsty 默认使用的模板,它的目标是在当前单节点上完成 Pigsty 核心功能 —— PostgreSQL 的部署。
为了实现最好的兼容性,meta 模板仅下载安装包含 最小必需 软件集合,以便在所有操作系统发行版与芯片架构上实现这一目标。
配置概览 配置名称: meta 节点数量: 单节点 配置说明:Pigsty 默认使用的单节点安装配置模板,带有较完善的关键配置参数说明,与最小可用功能集合。 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta ,slim ,fat , 使用方式:此配置模板为 Pigsty 默认配置模板,因此在 配置 时无需显式指定 -c meta 参数:
./configure [ -i <primary_ip>]
例如,如果您想要安装 PG 16,而非默认的 PostgreSQL 18,可以在 configure 中使用 -v 参数:
./configure -v 16 # or 17,15,14,13....
配置内容 源文件地址:pigsty/conf/meta.yml
---
#==============================================================#
# File : meta.yml
# Desc : Pigsty default 1-node online install config
# Ctime : 2020-05-22
# Mtime : 2026-02-04
# Docs : https://pigsty.io/docs/conf/meta
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the default 1-node configuration template, with:
# INFRA, NODE, PGSQL, ETCD, MINIO, DOCKER, APP (pgadmin)
# with basic pg extensions: postgis, pgvector
#
# Work with PostgreSQL 14-18 on all supported platform
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure
# ./deploy.yml
all :
#==============================================================#
# Clusters, Nodes, and Modules
#==============================================================#
children :
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql
#----------------------------------------------#
# this is an example single-node postgres cluster with pgvector installed, with one biz database & two biz users
pg-meta :
hosts :
10.10.10.10 : { pg_seq: 1, pg_role : primary } # <---- primary instance with read-write capability
#x.xx.xx.xx: { pg_seq: 2, pg_role: replica } # <---- read only replica for read-only online traffic
#x.xx.xx.xy: { pg_seq: 3, pg_role: offline } # <---- offline instance of ETL & interactive queries
vars :
pg_cluster : pg-meta
# install, load, create pg extensions: https://pigsty.io/docs/pgsql/ext/
pg_extensions : [ postgis, pgvector ]
# define business users/roles : https://pigsty.io/docs/pgsql/config/user
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 }
# define business databases : https://pigsty.io/docs/pgsql/config/db
pg_databases :
- name : meta
baseline : cmdb.sql
comment : "pigsty meta database"
schemas : [ pigsty]
# define extensions in database : https://pigsty.io/docs/pgsql/ext/create
extensions : [ postgis, 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'
# define (OPTIONAL) L2 VIP that bind to primary
#pg_vip_enabled: true
#pg_vip_address: 10.10.10.2/24
#pg_vip_interface: eth1
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra
#----------------------------------------------#
infra :
hosts :
10.10.10.10 : { infra_seq : 1 }
vars :
repo_enabled: false # disable in 1-node mode : https://pigsty.io/docs/infra/admin/repo
#repo_extra_packages: [ pg18-main ,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]
#----------------------------------------------#
# ETCD : https://pigsty.io/docs/etcd
#----------------------------------------------#
etcd :
hosts :
10.10.10.10 : { etcd_seq : 1 }
vars :
etcd_cluster : etcd
etcd_safeguard : false # prevent purging running etcd instance?
#----------------------------------------------#
# MINIO : https://pigsty.io/docs/minio
#----------------------------------------------#
#minio:
# hosts:
# 10.10.10.10: { minio_seq: 1 }
# vars:
# minio_cluster: minio
# minio_users: # list of minio user to be created
# - { access_key: pgbackrest ,secret_key: S3User.Backup ,policy: pgsql }
# - { access_key: s3user_meta ,secret_key: S3User.Meta ,policy: meta }
# - { access_key: s3user_data ,secret_key: S3User.Data ,policy: data }
#----------------------------------------------#
# DOCKER : https://pigsty.io/docs/docker
# APP : https://pigsty.io/docs/app
#----------------------------------------------#
# launch example pgadmin app with: ./app.yml (http://10.10.10.10:8885 admin@pigsty.cc / pigsty)
app :
hosts : { 10.10.10.10 : {} }
vars :
docker_enabled : true # enabled docker with ./docker.yml
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
app : pgadmin # specify the default app name to be installed (in the apps)
apps: # define all applications, appname : definition
pgadmin : # pgadmin app definition (app/pgadmin -> /opt/pgadmin)
conf : # override /opt/pgadmin/.env
PGADMIN_DEFAULT_EMAIL : admin@pigsty.cc
PGADMIN_DEFAULT_PASSWORD : pigsty
#==============================================================#
# Global Parameters
#==============================================================#
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
pgadmin : { domain: adm.pigsty ,endpoint : "${admin_ip}:8885" }
#minio : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
nodename_overwrite : false # do not overwrite node hostname on single node mode
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
node_etc_hosts : [ '${admin_ip} i.pigsty sss.pigsty' ]
node_repo_modules : 'node,infra,pgsql' # add these repos directly to the singleton node
#node_repo_modules: local # use this if you want to build & user local repo
node_repo_remove : true # remove existing node repo for node managed by pigsty
#node_packages: [openssh-server] # packages to be installed current nodes with the latest version
node_firewall_public_port : [ 22 , 80 , 443 , 5432 ] # expose 5432 for demo convenience, remove in production!
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # default postgres version
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
pg_safeguard : false # prevent purging running postgres instance?
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]
#----------------------------------------------#
# BACKUP : https://pigsty.io/docs/pgsql/backup
#----------------------------------------------#
# if you want to use minio as backup repo instead of 'local' fs, uncomment this, and configure `pgbackrest_repo`
# you can also use external object storage as backup repo
#pgbackrest_method: minio # if you want to use minio as backup repo instead of 'local' fs, uncomment this
#pgbackrest_repo: # pgbackrest repo: https://pgbackrest.org/configuration.html#section-repository
# local: # default pgbackrest repo with local posix fs
# path: /pg/backup # local backup directory, `/pg/backup` by default
# retention_full_type: count # retention full backups by count
# retention_full: 2 # keep 2, at most 3 full backup when using local fs repo
# minio: # optional minio repo for pgbackrest
# type: s3 # minio is s3-compatible, so s3 is used
# s3_endpoint: sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
# s3_region: us-east-1 # minio region, us-east-1 by default, useless for minio
# s3_bucket: pgsql # minio bucket name, `pgsql` by default
# s3_key: pgbackrest # minio user access key for pgbackrest
# s3_key_secret: S3User.Backup # minio user secret key for pgbackrest
# s3_uri_style: path # use path style uri for minio rather than host style
# path: /pgbackrest # minio backup path, default is `/pgbackrest`
# storage_port: 9000 # minio port, 9000 by default
# storage_ca_file: /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
# block: y # Enable block incremental backup
# bundle: y # bundle small files into a single file
# bundle_limit: 20MiB # Limit for file bundles, 20MiB for object storage
# bundle_size: 128MiB # Target size for file bundles, 128MiB for object storage
# cipher_type: aes-256-cbc # enable AES encryption for remote backup repo
# cipher_pass: pgBackRest # AES encryption password, default is 'pgBackRest'
# retention_full_type: time # retention full backup by time on minio repo
# retention_full: 14 # keep full backup for last 14 days
# s3: # any s3 compatible service is fine
# type: s3
# s3_endpoint: oss-cn-beijing-internal.aliyuncs.com
# s3_region: oss-cn-beijing
# s3_bucket: <your_bucket_name>
# s3_key: <your_access_key>
# s3_key_secret: <your_secret_key>
# s3_uri_style: host
# path: /pgbackrest
# bundle: y # bundle small files into a single file
# bundle_limit: 20MiB # Limit for file bundles, 20MiB for object storage
# bundle_size: 128MiB # Target size for file bundles, 128MiB for object storage
# cipher_type: aes-256-cbc # enable AES encryption for remote backup repo
# cipher_pass: pgBackRest # AES encryption password, default is 'pgBackRest'
# retention_full_type: time # retention full backup by time on minio repo
# retention_full: 14 # keep full backup for last 14 days
#----------------------------------------------#
# 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
... 配置解读 meta 模板是 Pigsty 的 默认入门配置 ,专为快速上手设计。
适用场景 :
首次体验 Pigsty 的用户 开发测试环境的快速部署 单机运行的小型生产环境 作为更复杂部署的基础模板 关键特性 :
在线安装模式,不构建本地软件源(repo_enabled: false) 默认安装 PostgreSQL 18,带有 postgis 和 pgvector 扩展 包含完整的监控基础设施(Grafana、Prometheus、Loki 等) 预置 Docker 与 pgAdmin 应用示例 MinIO 备份存储默认禁用,可按需启用 注意事项 :
默认密码为示例密码,生产环境 务必修改 单节点模式的 etcd 无高可用保障,适合开发测试 如需构建本地软件源,请使用 rich 模板 9.3 - rich 功能丰富的单节点配置,构建本地软件源,下载所有扩展,启用 MinIO 备份,预置完整示例
配置模板 rich 是 meta 的增强版本,专为需要完整功能体验的用户设计。
如果您希望构建本地软件源、使用 MinIO 存储备份、运行 Docker 应用,或需要预置业务数据库,可以使用此模板。
配置概览 配置名称: rich 节点数量: 单节点 配置说明:功能丰富的单节点配置,在 meta 基础上增加本地软件源、MinIO 备份、完整扩展、Docker 应用示例 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta ,slim ,fat 此模板相比 meta 的主要增强:
构建本地软件源(repo_enabled: true),下载所有 PG 扩展 启用单节点 MinIO 作为 PostgreSQL 备份存储 预置 TimescaleDB、pgvector、pg_wait_sampling 等扩展 包含详细的用户/数据库/服务定义注释示例 添加 Redis 主从实例示例 预置 pg-test 三节点高可用集群配置存根 启用方式:
./configure -c rich [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/rich.yml
---
#==============================================================#
# File : rich.yml
# Desc : Pigsty feature-rich 1-node online install config
# Ctime : 2020-05-22
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/conf/rich
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the enhanced version of default meta.yml, which has:
# - almost all available postgres extensions
# - build local software repo for entire env
# - 1 node minio used as central backup repo
# - cluster stub for 3-node pg-test / ferret / redis
# - stub for nginx, certs, and website self-hosting config
# - detailed comments for database / user / service
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c rich
# ./deploy.yml
all :
#==============================================================#
# Clusters, Nodes, and Modules
#==============================================================#
children :
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql
#----------------------------------------------#
# this is an example single-node postgres cluster with pgvector installed, with one biz database & two biz users
pg-meta :
hosts :
10.10.10.10 : { pg_seq: 1, pg_role : primary } # <---- primary instance with read-write capability
#x.xx.xx.xx: { pg_seq: 2, pg_role: replica } # <---- read only replica for read-only online traffic
#x.xx.xx.xy: { pg_seq: 3, pg_role: offline } # <---- offline instance of ETL & interactive queries
vars :
pg_cluster : pg-meta
# install, load, create pg extensions: https://pigsty.io/docs/pgsql/ext/
pg_extensions : [ postgis, timescaledb, pgvector, pg_wait_sampling ]
pg_libs : 'timescaledb, pg_stat_statements, auto_explain, pg_wait_sampling'
# define business users/roles : https://pigsty.io/docs/pgsql/config/user
pg_users :
- name : dbuser_meta # REQUIRED, `name` is the only mandatory field of a user definition
password : DBUser.Meta # optional, the password. can be a scram-sha-256 hash string or plain text
pgbouncer : true # optional, add this user to the pgbouncer user-list? false by default (production user should be true explicitly)
comment : pigsty admin user # optional, comment string for this user/role
roles: [ dbrole_admin ] # optional, belonged roles. default roles are : dbrole_{admin|readonly|readwrite|offline}
#state: create # optional, create|absent, 'create' by default, use 'absent' to drop user
#login: true # optional, can log in, true by default (new biz ROLE should be false)
#superuser: false # optional, is superuser? false by default
#createdb: false # optional, can create databases? false by default
#createrole: false # optional, can create role? false by default
#inherit: true # optional, can this role use inherited privileges? true by default
#replication: false # optional, can this role do replication? false by default
#bypassrls: false # optional, can this role bypass row level security? false by default
#connlimit: -1 # optional, user connection limit, default -1 disable limit
#expire_in: 3650 # optional, now + n days when this role is expired (OVERWRITE expire_at)
#expire_at: '2030-12-31' # optional, YYYY-MM-DD 'timestamp' when this role is expired (OVERWRITTEN by expire_in)
#parameters: {} # optional, role level parameters with `ALTER ROLE SET`
#pool_mode: transaction # optional, pgbouncer pool mode at user level, transaction by default
#pool_connlimit: -1 # optional, max database connections at user level, default -1 disable limit
# Enhanced roles syntax (PG16+): roles can be string or object with options:
# - dbrole_readwrite # simple string: GRANT role
# - { name: role, admin: true } # GRANT WITH ADMIN OPTION
# - { name: role, set: false } # PG16: REVOKE SET OPTION
# - { name: role, inherit: false } # PG16: REVOKE INHERIT OPTION
# - { name: role, state: absent } # REVOKE membership
- { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly], comment : read-only viewer for meta database }
#- {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for bytebase database }
#- {name: dbuser_remove ,state: absent } # use state: absent to remove a user
# define business databases : https://pigsty.io/docs/pgsql/config/db
pg_databases : # define business databases on this cluster, array of database definition
- name : meta # REQUIRED, `name` is the only mandatory field of a database definition
#state: create # optional, create|absent|recreate, create by default
baseline: cmdb.sql # optional, database sql baseline path, (relative path among the ansible search path, e.g. : files/)
schemas : [ pigsty ] # optional, additional schemas to be created, array of schema names
extensions: # optional, additional extensions to be installed : array of `{name[,schema]}`
- vector # install pgvector for vector similarity search
- postgis # install postgis for geospatial type & index
- timescaledb # install timescaledb for time-series data
- { name: pg_wait_sampling, schema : monitor } # install pg_wait_sampling on monitor schema
comment : pigsty meta database # optional, comment string for this database
#pgbouncer: true # optional, add this database to the pgbouncer database list? true by default
#owner: postgres # optional, database owner, current user if not specified
#template: template1 # optional, which template to use, template1 by default
#strategy: FILE_COPY # optional, clone strategy: FILE_COPY or WAL_LOG (PG15+), default to PG's default
#encoding: UTF8 # optional, inherited from template / cluster if not defined (UTF8)
#locale: C # optional, inherited from template / cluster if not defined (C)
#lc_collate: C # optional, inherited from template / cluster if not defined (C)
#lc_ctype: C # optional, inherited from template / cluster if not defined (C)
#locale_provider: libc # optional, locale provider: libc, icu, builtin (PG15+)
#icu_locale: en-US # optional, icu locale for icu locale provider (PG15+)
#icu_rules: '' # optional, icu rules for icu locale provider (PG16+)
#builtin_locale: C.UTF-8 # optional, builtin locale for builtin locale provider (PG17+)
#tablespace: pg_default # optional, default tablespace, pg_default by default
#is_template: false # optional, mark database as template, allowing clone by any user with CREATEDB privilege
#allowconn: true # optional, allow connection, true by default. false will disable connect at all
#revokeconn: false # optional, revoke public connection privilege. false by default. (leave connect with grant option to owner)
#register_datasource: true # optional, register this database to grafana datasources? true by default
#connlimit: -1 # optional, database connection limit, default -1 disable limit
#pool_auth_user: dbuser_meta # optional, all connection to this pgbouncer database will be authenticated by this user
#pool_mode: transaction # optional, pgbouncer pool mode at database level, default transaction
#pool_size: 64 # optional, pgbouncer pool size at database level, default 64
#pool_reserve: 32 # optional, pgbouncer pool size reserve at database level, default 32
#pool_size_min: 0 # optional, pgbouncer pool size min at database level, default 0
#pool_connlimit: 100 # optional, max database connections at database level, default 100
#- {name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment: bytebase primary database }
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'
# define (OPTIONAL) L2 VIP that bind to primary
#pg_vip_enabled: true
#pg_vip_address: 10.10.10.2/24
#pg_vip_interface: eth1
#----------------------------------------------#
# PGSQL HA Cluster Example: 3-node pg-test
#----------------------------------------------#
#pg-test:
# hosts:
# 10.10.10.11: { pg_seq: 1, pg_role: primary } # primary instance, leader of cluster
# 10.10.10.12: { pg_seq: 2, pg_role: replica } # replica instance, follower of leader
# 10.10.10.13: { pg_seq: 3, pg_role: replica, pg_offline_query: true } # replica with offline access
# vars:
# pg_cluster: pg-test # define pgsql cluster name
# pg_users: [{ name: test , password: test , pgbouncer: true , roles: [ dbrole_admin ] }]
# pg_databases: [{ name: test }]
# # define business service here: https://pigsty.io/docs/pgsql/service
# pg_services: # extra services in addition to pg_default_services, array of service definition
# # standby service will route {ip|name}:5435 to sync replica's pgbouncer (5435->6432 standby)
# - name: standby # required, service name, the actual svc name will be prefixed with `pg_cluster`, e.g: pg-meta-standby
# port: 5435 # required, service exposed port (work as kubernetes service node port mode)
# ip: "*" # optional, service bind ip address, `*` for all ip by default
# selector: "[]" # required, service member selector, use JMESPath to filter inventory
# dest: default # optional, destination port, default|postgres|pgbouncer|<port_number>, 'default' by default
# check: /sync # optional, health check url path, / by default
# backup: "[? pg_role == `primary`]" # backup server selector
# maxconn: 3000 # optional, max allowed front-end connection
# balance: roundrobin # optional, haproxy load balance algorithm (roundrobin by default, other: 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'
# pg_vip_enabled: true
# pg_vip_address: 10.10.10.3/24
# pg_vip_interface: eth1
# pg_crontab: # make a full backup on monday 1am, and an incremental backup during weekdays
# - '00 01 * * 1 /pg/bin/pg-backup full'
# - '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup'
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra
#----------------------------------------------#
infra :
hosts :
10.10.10.10 : { infra_seq : 1 }
vars :
repo_enabled: true # build local repo, and install everything from it : https://pigsty.io/docs/infra/admin/repo
# and download all extensions into local repo
repo_extra_packages : [ pg18-main ,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]
#----------------------------------------------#
# ETCD : https://pigsty.io/docs/etcd
#----------------------------------------------#
etcd :
hosts :
10.10.10.10 : { etcd_seq : 1 }
vars :
etcd_cluster : etcd
etcd_safeguard : false # prevent purging running etcd instance?
#----------------------------------------------#
# MINIO : https://pigsty.io/docs/minio
#----------------------------------------------#
minio :
hosts :
10.10.10.10 : { minio_seq : 1 }
vars :
minio_cluster : minio
minio_users : # list of minio user to be created
- { access_key: pgbackrest ,secret_key: S3User.Backup ,policy : pgsql }
- { access_key: s3user_meta ,secret_key: S3User.Meta ,policy : meta }
- { access_key: s3user_data ,secret_key: S3User.Data ,policy : data }
#----------------------------------------------#
# DOCKER : https://pigsty.io/docs/docker
# APP : https://pigsty.io/docs/app
#----------------------------------------------#
# OPTIONAL, launch example pgadmin app with: ./app.yml & ./app.yml -e app=bytebase
app :
hosts : { 10.10.10.10 : {} }
vars :
docker_enabled : true # enabled docker with ./docker.yml
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
app : pgadmin # specify the default app name to be installed (in the apps)
apps: # define all applications, appname : definition
# Admin GUI for PostgreSQL, launch with: ./app.yml
pgadmin : # pgadmin app definition (app/pgadmin -> /opt/pgadmin)
conf : # override /opt/pgadmin/.env
PGADMIN_DEFAULT_EMAIL : admin@pigsty.cc # default user name
PGADMIN_DEFAULT_PASSWORD : pigsty # default password
# Schema Migration GUI for PostgreSQL, launch with: ./app.yml -e app=bytebase
bytebase :
conf :
BB_DOMAIN : http://ddl.pigsty # replace it with your public domain name and postgres database url
BB_PGURL : "postgresql://dbuser_bytebase:DBUser.Bytebase@10.10.10.10:5432/bytebase?sslmode=prefer"
#----------------------------------------------#
# REDIS : https://pigsty.io/docs/redis
#----------------------------------------------#
# OPTIONAL, launch redis clusters with: ./redis.yml
redis-ms :
hosts : { 10.10.10.10 : { redis_node: 1 , redis_instances : { 6379 : { }, 6380 : { replica_of : '10.10.10.10 6379' } } } }
vars : { redis_cluster: redis-ms ,redis_password: 'redis.ms' ,redis_max_memory : 64MB }
#==============================================================#
# Global Parameters
#==============================================================#
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
certbot_sign : false # enable certbot to sign https certificate for infra portal
certbot_email : your@email.com # replace your email address to receive expiration notice
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
pgadmin : { domain: adm.pigsty ,endpoint : "${admin_ip}:8885" }
bytebase : { domain: ddl.pigsty ,endpoint : "${admin_ip}:8887" }
minio : { domain: m.pigsty ,endpoint : "${admin_ip}:9001" ,scheme: https ,websocket : true }
#website: # static local website example stub
# domain: repo.pigsty # external domain name for static site
# certbot: repo.pigsty # use certbot to sign https certificate for this static site
# path: /www/pigsty # path to the static site directory
#supabase: # dynamic upstream service example stub
# domain: supa.pigsty # external domain name for upstream service
# certbot: supa.pigsty # use certbot to sign https certificate for this upstream server
# endpoint: "10.10.10.10:8000" # path to the static site directory
# websocket: true # add websocket support
# certbot: supa.pigsty # certbot cert name, apply with `make cert`
#----------------------------------------------#
# 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
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
nodename_overwrite : false # do not overwrite node hostname on single node mode
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
node_etc_hosts : # add static domains to all nodes /etc/hosts
- '${admin_ip} i.pigsty sss.pigsty'
- '${admin_ip} adm.pigsty ddl.pigsty repo.pigsty supa.pigsty'
node_repo_modules : local # use pre-made local repo rather than install from upstream
node_repo_remove : true # remove existing node repo for node managed by pigsty
#node_packages: [openssh-server] # packages to be installed current nodes with latest version
#node_timezone: Asia/Hong_Kong # overwrite node timezone
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # default postgres version
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
pg_safeguard : false # prevent purging running postgres instance?
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]
#----------------------------------------------#
# BACKUP : https://pigsty.io/docs/pgsql/backup
#----------------------------------------------#
# if you want to use minio as backup repo instead of 'local' fs, uncomment this, and configure `pgbackrest_repo`
# you can also use external object storage as backup repo
pgbackrest_method : minio # if you want to use minio as backup repo instead of 'local' fs, uncomment this
pgbackrest_repo: # pgbackrest repo : https://pgbackrest.org/configuration.html#section-repository
local : # default pgbackrest repo with local posix fs
path : /pg/backup # local backup directory, `/pg/backup` by default
retention_full_type : count # retention full backups by count
retention_full : 2 # keep 2, at most 3 full backups when using local fs repo
minio : # optional minio repo for pgbackrest
type : s3 # minio is s3-compatible, so s3 is used
s3_endpoint : sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
s3_region : us-east-1 # minio region, us-east-1 by default, useless for minio
s3_bucket : pgsql # minio bucket name, `pgsql` by default
s3_key : pgbackrest # minio user access key for pgbackrest [CHANGE ACCORDING to minio_users.pgbackrest]
s3_key_secret : S3User.Backup # minio user secret key for pgbackrest [CHANGE ACCORDING to minio_users.pgbackrest]
s3_uri_style : path # use path style uri for minio rather than host style
path : /pgbackrest # minio backup path, default is `/pgbackrest`
storage_port : 9000 # minio port, 9000 by default
storage_ca_file : /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
block : y # Enable block incremental backup
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for the last 14 days
s3 : # you can use cloud object storage as backup repo
type : s3 # Add your object storage credentials here!
s3_endpoint : oss-cn-beijing-internal.aliyuncs.com
s3_region : oss-cn-beijing
s3_bucket : <your_bucket_name>
s3_key : <your_access_key>
s3_key_secret : <your_secret_key>
s3_uri_style : host
path : /pgbackrest
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for the last 14 days
...
配置解读 rich 模板是 Pigsty 的 完整功能展示配置 ,适合需要深入体验所有功能的用户。
适用场景 :
需要构建本地软件源的离线环境 需要使用 MinIO 作为 PostgreSQL 备份存储 需要预先规划多个业务数据库和用户 需要运行 Docker 应用(pgAdmin、Bytebase 等) 希望了解配置参数完整用法的学习者 与 meta 的主要区别 :
启用本地软件源构建(repo_enabled: true) 启用 MinIO 存储备份(pgbackrest_method: minio) 预装 TimescaleDB、pg_wait_sampling 等额外扩展 包含详细的参数注释,便于理解配置含义 预置高可用集群存根配置(pg-test) 注意事项 :
ARM64 架构部分扩展不可用,请按需调整 构建本地软件源需要较长时间和较大磁盘空间 默认密码为示例密码,生产环境务必修改 9.4 - slim 精简安装配置模板,不部署监控基础设施,直接从互联网安装 PostgreSQL
slim 配置模板提供 精简安装 能力,在不部署 Infra 监控基础设施的前提下,直接从互联网安装 PostgreSQL 高可用集群。
当您只需要一个可用的数据库实例,不需要监控系统时,可以考虑使用 精简安装 模式。
配置概览 配置名称: slim 节点数量: 单节点 配置说明:精简安装配置模板,不部署监控基础设施,直接安装 PostgreSQL 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c slim [ -i <primary_ip>]
./slim.yml # 执行精简安装
配置内容 源文件地址:pigsty/conf/slim.yml
---
#==============================================================#
# 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 (rh@vonng.com)
#==============================================================#
# 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 } # odd number please
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.3.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 模板是 Pigsty 的 精简安装配置 ,专为快速部署裸 PostgreSQL 集群设计。
适用场景 :
仅需要 PostgreSQL 数据库,不需要监控系统 资源有限的小型服务器或边缘设备 快速部署测试用的临时数据库 已有监控系统,只需要 PostgreSQL 高可用集群 关键特性 :
使用 slim.yml 剧本而非 deploy.yml 进行安装 从互联网直接安装软件,不构建本地软件源 保留核心 PostgreSQL 高可用能力(Patroni + etcd + HAProxy) 最小化软件包下载,加快安装速度 默认使用 PostgreSQL 18 与 meta 的区别 :
slim 使用专用的 slim.yml 剧本,跳过 Infra 模块安装安装速度更快,资源占用更少 适合"只要数据库"的场景 注意事项 :
精简安装后无法通过 Grafana 查看数据库状态 如需监控功能,请使用 meta 或 rich 模板 可按需添加从库实现高可用 9.5 - fat 功能全测试模板,单节点安装所有扩展,构建包含 PG 14-18 全版本的本地软件源。
fat 配置模板是 Pigsty 的 功能全测试模板 (Feature-All-Test),在单节点上安装所有扩展插件,并构建包含 PostgreSQL 14-18 全部五个大版本所有扩展的本地软件源。
这是一个用于测试与开发的全功能配置,适合需要完整软件包缓存或测试全部扩展的场景。
配置概览 配置名称: fat 节点数量: 单节点 配置说明:功能全测试模板,安装所有扩展,构建包含 PG 14-18 全版本的本地软件源 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta ,slim ,fat 启用方式:
./configure -c fat [ -i <primary_ip>]
如需指定特定 PostgreSQL 版本:
./configure -c fat -v 16 # 使用 PostgreSQL 16
配置内容 源文件地址:pigsty/conf/fat.yml
---
#==============================================================#
# File : fat.yml
# Desc : Pigsty Feature-All-Test config template
# Ctime : 2020-05-22
# Mtime : 2025-12-28
# Docs : https://pigsty.io/docs/conf/fat
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the 4-node sandbox for pigsty
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c fat [-v 18|17|16|15]
# ./deploy.yml
all :
#==============================================================#
# Clusters, Nodes, and Modules
#==============================================================#
children :
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql
#----------------------------------------------#
# this is an example single-node postgres cluster with pgvector installed, with one biz database & two biz users
pg-meta :
hosts :
10.10.10.10 : { pg_seq: 1, pg_role : primary } # <---- primary instance with read-write capability
#x.xx.xx.xx: { pg_seq: 2, pg_role: replica } # <---- read only replica for read-only online traffic
#x.xx.xx.xy: { pg_seq: 3, pg_role: offline } # <---- offline instance of ETL & interactive queries
vars :
pg_cluster : pg-meta
# install, load, create pg extensions: https://pigsty.io/docs/pgsql/ext/
pg_extensions : [ pg18-main ,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]
pg_libs : 'timescaledb, pg_stat_statements, auto_explain, pg_wait_sampling'
# define business users/roles : https://pigsty.io/docs/pgsql/config/user
pg_users :
- name : dbuser_meta # REQUIRED, `name` is the only mandatory field of a user definition
password : DBUser.Meta # optional, the password. can be a scram-sha-256 hash string or plain text
pgbouncer : true # optional, add this user to the pgbouncer user-list? false by default (production user should be true explicitly)
comment : pigsty admin user # optional, comment string for this user/role
roles: [ dbrole_admin ] # optional, belonged roles. default roles are : dbrole_{admin|readonly|readwrite|offline}
#state: create # optional, create|absent, 'create' by default, use 'absent' to drop user
#login: true # optional, can log in, true by default (new biz ROLE should be false)
#superuser: false # optional, is superuser? false by default
#createdb: false # optional, can create databases? false by default
#createrole: false # optional, can create role? false by default
#inherit: true # optional, can this role use inherited privileges? true by default
#replication: false # optional, can this role do replication? false by default
#bypassrls: false # optional, can this role bypass row level security? false by default
#connlimit: -1 # optional, user connection limit, default -1 disable limit
#expire_in: 3650 # optional, now + n days when this role is expired (OVERWRITE expire_at)
#expire_at: '2030-12-31' # optional, YYYY-MM-DD 'timestamp' when this role is expired (OVERWRITTEN by expire_in)
#parameters: {} # optional, role level parameters with `ALTER ROLE SET`
#pool_mode: transaction # optional, pgbouncer pool mode at user level, transaction by default
#pool_connlimit: -1 # optional, max database connections at user level, default -1 disable limit
# Enhanced roles syntax (PG16+): roles can be string or object with options:
# - dbrole_readwrite # simple string: GRANT role
# - { name: role, admin: true } # GRANT WITH ADMIN OPTION
# - { name: role, set: false } # PG16: REVOKE SET OPTION
# - { name: role, inherit: false } # PG16: REVOKE INHERIT OPTION
# - { name: role, state: absent } # REVOKE membership
- { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly], comment : read-only viewer for meta database }
#- {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for bytebase database }
#- {name: dbuser_remove ,state: absent } # use state: absent to remove a user
# define business databases : https://pigsty.io/docs/pgsql/config/db
pg_databases : # define business databases on this cluster, array of database definition
- name : meta # REQUIRED, `name` is the only mandatory field of a database definition
#state: create # optional, create|absent|recreate, create by default
baseline: cmdb.sql # optional, database sql baseline path, (relative path among the ansible search path, e.g. : files/)
schemas : [ pigsty ] # optional, additional schemas to be created, array of schema names
extensions: # optional, additional extensions to be installed : array of `{name[,schema]}`
- vector # install pgvector for vector similarity search
- postgis # install postgis for geospatial type & index
- timescaledb # install timescaledb for time-series data
- { name: pg_wait_sampling, schema : monitor } # install pg_wait_sampling on monitor schema
comment : pigsty meta database # optional, comment string for this database
#pgbouncer: true # optional, add this database to the pgbouncer database list? true by default
#owner: postgres # optional, database owner, current user if not specified
#template: template1 # optional, which template to use, template1 by default
#strategy: FILE_COPY # optional, clone strategy: FILE_COPY or WAL_LOG (PG15+), default to PG's default
#encoding: UTF8 # optional, inherited from template / cluster if not defined (UTF8)
#locale: C # optional, inherited from template / cluster if not defined (C)
#lc_collate: C # optional, inherited from template / cluster if not defined (C)
#lc_ctype: C # optional, inherited from template / cluster if not defined (C)
#locale_provider: libc # optional, locale provider: libc, icu, builtin (PG15+)
#icu_locale: en-US # optional, icu locale for icu locale provider (PG15+)
#icu_rules: '' # optional, icu rules for icu locale provider (PG16+)
#builtin_locale: C.UTF-8 # optional, builtin locale for builtin locale provider (PG17+)
#tablespace: pg_default # optional, default tablespace, pg_default by default
#is_template: false # optional, mark database as template, allowing clone by any user with CREATEDB privilege
#allowconn: true # optional, allow connection, true by default. false will disable connect at all
#revokeconn: false # optional, revoke public connection privilege. false by default. (leave connect with grant option to owner)
#register_datasource: true # optional, register this database to grafana datasources? true by default
#connlimit: -1 # optional, database connection limit, default -1 disable limit
#pool_auth_user: dbuser_meta # optional, all connection to this pgbouncer database will be authenticated by this user
#pool_mode: transaction # optional, pgbouncer pool mode at database level, default transaction
#pool_size: 64 # optional, pgbouncer pool size at database level, default 64
#pool_reserve: 32 # optional, pgbouncer pool size reserve at database level, default 32
#pool_size_min: 0 # optional, pgbouncer pool size min at database level, default 0
#pool_connlimit: 100 # optional, max database connections at database level, default 100
#- {name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment: bytebase primary database }
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'
# define (OPTIONAL) L2 VIP that bind to primary
pg_vip_enabled : true
pg_vip_address : 10.10.10.2 /24
pg_vip_interface : eth1
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra
#----------------------------------------------#
infra :
hosts :
10.10.10.10 : { infra_seq : 1 }
vars :
repo_enabled: true # build local repo : https://pigsty.io/docs/infra/admin/repo
#repo_extra_packages: [ pg18-main ,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]
repo_packages : [
node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-utility, extra-modules,
pg18-full,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,
pg17-full,pg17-time,pg17-gis,pg17-rag,pg17-fts,pg17-olap,pg17-feat,pg17-lang,pg17-type,pg17-util,pg17-func,pg17-admin,pg17-stat,pg17-sec,pg17-fdw,pg17-sim,pg17-etl,
pg16-full,pg16-time,pg16-gis,pg16-rag,pg16-fts,pg16-olap,pg16-feat,pg16-lang,pg16-type,pg16-util,pg16-func,pg16-admin,pg16-stat,pg16-sec,pg16-fdw,pg16-sim,pg16-etl,
pg15-full,pg15-time,pg15-gis,pg15-rag,pg15-fts,pg15-olap,pg15-feat,pg15-lang,pg15-type,pg15-util,pg15-func,pg15-admin,pg15-stat,pg15-sec,pg15-fdw,pg15-sim,pg15-etl,
pg14-full,pg14-time,pg14-gis,pg14-rag,pg14-fts,pg14-olap,pg14-feat,pg14-lang,pg14-type,pg14-util,pg14-func,pg14-admin,pg14-stat,pg14-sec,pg14-fdw,pg14-sim,pg14-etl,
infra-extra, kafka, java-runtime, sealos, tigerbeetle, polardb, ivorysql
]
#----------------------------------------------#
# ETCD : https://pigsty.io/docs/etcd
#----------------------------------------------#
etcd :
hosts :
10.10.10.10 : { etcd_seq : 1 }
vars :
etcd_cluster : etcd
etcd_safeguard : false # prevent purging running etcd instance?
#----------------------------------------------#
# MINIO : https://pigsty.io/docs/minio
#----------------------------------------------#
minio :
hosts :
10.10.10.10 : { minio_seq : 1 }
vars :
minio_cluster : minio
minio_users : # list of minio user to be created
- { access_key: pgbackrest ,secret_key: S3User.Backup ,policy : pgsql }
- { access_key: s3user_meta ,secret_key: S3User.Meta ,policy : meta }
- { access_key: s3user_data ,secret_key: S3User.Data ,policy : data }
#----------------------------------------------#
# DOCKER : https://pigsty.io/docs/docker
# APP : https://pigsty.io/docs/app
#----------------------------------------------#
# OPTIONAL, launch example pgadmin app with: ./app.yml & ./app.yml -e app=bytebase
app :
hosts : { 10.10.10.10 : {} }
vars :
docker_enabled : true # enabled docker with ./docker.yml
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
app : pgadmin # specify the default app name to be installed (in the apps)
apps: # define all applications, appname : definition
# Admin GUI for PostgreSQL, launch with: ./app.yml
pgadmin : # pgadmin app definition (app/pgadmin -> /opt/pgadmin)
conf : # override /opt/pgadmin/.env
PGADMIN_DEFAULT_EMAIL : admin@pigsty.cc # default user name
PGADMIN_DEFAULT_PASSWORD : pigsty # default password
# Schema Migration GUI for PostgreSQL, launch with: ./app.yml -e app=bytebase
bytebase :
conf :
BB_DOMAIN : http://ddl.pigsty # replace it with your public domain name and postgres database url
BB_PGURL : "postgresql://dbuser_bytebase:DBUser.Bytebase@10.10.10.10:5432/bytebase?sslmode=prefer"
#==============================================================#
# Global Parameters
#==============================================================#
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
certbot_sign : false # enable certbot to sign https certificate for infra portal
certbot_email : your@email.com # replace your email address to receive expiration notice
infra_portal : # domain names and upstream servers
home : { domain : i.pigsty }
pgadmin : { domain: adm.pigsty ,endpoint : "${admin_ip}:8885" }
bytebase : { domain: ddl.pigsty ,endpoint : "${admin_ip}:8887" ,websocket : true }
minio : { domain: m.pigsty ,endpoint : "${admin_ip}:9001" ,scheme: https ,websocket : true }
#website: # static local website example stub
# domain: repo.pigsty # external domain name for static site
# certbot: repo.pigsty # use certbot to sign https certificate for this static site
# path: /www/pigsty # path to the static site directory
#supabase: # dynamic upstream service example stub
# domain: supa.pigsty # external domain name for upstream service
# certbot: supa.pigsty # use certbot to sign https certificate for this upstream server
# endpoint: "10.10.10.10:8000" # path to the static site directory
# websocket: true # add websocket support
# certbot: supa.pigsty # certbot cert name, apply with `make cert`
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
nodename_overwrite : true # overwrite node hostname on multi-node template
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
node_etc_hosts : # add static domains to all nodes /etc/hosts
- 10.10.10.10 i.pigsty sss.pigsty
- 10.10.10.10 adm.pigsty ddl.pigsty repo.pigsty supa.pigsty
node_repo_modules : local,node,infra,pgsql # use pre-made local repo rather than install from upstream
node_repo_remove : true # remove existing node repo for node managed by pigsty
#node_packages: [openssh-server] # packages to be installed current nodes with latest version
#node_timezone: Asia/Hong_Kong # overwrite node timezone
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # default postgres version
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
pg_safeguard : false # prevent purging running postgres instance?
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]
#----------------------------------------------#
# BACKUP : https://pigsty.io/docs/pgsql/backup
#----------------------------------------------#
# if you want to use minio as backup repo instead of 'local' fs, uncomment this, and configure `pgbackrest_repo`
# you can also use external object storage as backup repo
pgbackrest_method : minio # if you want to use minio as backup repo instead of 'local' fs, uncomment this
pgbackrest_repo: # pgbackrest repo : https://pgbackrest.org/configuration.html#section-repository
local : # default pgbackrest repo with local posix fs
path : /pg/backup # local backup directory, `/pg/backup` by default
retention_full_type : count # retention full backups by count
retention_full : 2 # keep 2, at most 3 full backups when using local fs repo
minio : # optional minio repo for pgbackrest
type : s3 # minio is s3-compatible, so s3 is used
s3_endpoint : sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
s3_region : us-east-1 # minio region, us-east-1 by default, useless for minio
s3_bucket : pgsql # minio bucket name, `pgsql` by default
s3_key : pgbackrest # minio user access key for pgbackrest [CHANGE ACCORDING to minio_users.pgbackrest]
s3_key_secret : S3User.Backup # minio user secret key for pgbackrest [CHANGE ACCORDING to minio_users.pgbackrest]
s3_uri_style : path # use path style uri for minio rather than host style
path : /pgbackrest # minio backup path, default is `/pgbackrest`
storage_port : 9000 # minio port, 9000 by default
storage_ca_file : /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
block : y # Enable block incremental backup
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for the last 14 days
s3 : # you can use cloud object storage as backup repo
type : s3 # Add your object storage credentials here!
s3_endpoint : oss-cn-beijing-internal.aliyuncs.com
s3_region : oss-cn-beijing
s3_bucket : <your_bucket_name>
s3_key : <your_access_key>
s3_key_secret : <your_secret_key>
s3_uri_style : host
path : /pgbackrest
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for the last 14 days
#----------------------------------------------#
# 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
...
配置解读 fat 模板是 Pigsty 的 全功能测试配置 ,专为完整性测试和离线包构建设计。
关键特性 :
全扩展安装 :安装 PostgreSQL 18 的所有分类扩展包多版本软件源 :本地软件源包含 PostgreSQL 14-18 全部五个大版本完整组件栈 :包含 MinIO 备份、Docker 应用、VIP 等功能企业级组件 :包含 Kafka、PolarDB、IvorySQL、TigerBeetle 等软件源内容 :
分类 说明 PostgreSQL 14-18 五个大版本的内核和全部扩展 扩展分类包 time, gis, rag, fts, olap, feat, lang, type, util, func, admin, stat, sec, fdw, sim, etl企业组件 Kafka、Java 运行时、Sealos、TigerBeetle 数据库内核 PolarDB、IvorySQL
与 rich 的区别 :
fat 包含 PostgreSQL 14-18 全部五个版本,rich 只包含当前默认版本fat 包含额外的企业组件(Kafka、PolarDB、IvorySQL 等)fat 需要更大的磁盘空间和更长的构建时间适用场景 :
Pigsty 开发测试与功能验证 构建完整的多版本离线软件包 需要测试全部扩展兼容性的场景 企业环境预先缓存所有软件包 注意事项 :
需要较大磁盘空间(建议 100GB+)用于存储所有软件包 构建本地软件源需要较长时间 部分扩展在 ARM64 架构不可用 默认密码为示例密码,生产环境务必修改 9.6 - infra 仅安装可观测性基础设施,不包含 PostgreSQL 与 etcd 的专用配置模板
infra 配置模板仅部署 Pigsty 的可观测性基础设施组件(VictoriaMetrics/Grafana/Loki/Nginx 等),不包含 PostgreSQL 与 etcd。
适用于需要独立监控栈的场景,例如监控外部 PostgreSQL/RDS 实例或其他数据源。
配置概览 配置名称: infra 节点数量: 单节点或多节点 配置说明:仅安装可观测性基础设施,不包含 PostgreSQL 与 etcd 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c infra [ -i <primary_ip>]
./infra.yml # 仅执行 infra 剧本
配置内容 源文件地址:pigsty/conf/infra.yml
---
#==============================================================#
# File : infra.yml
# Desc : Infra Only Config
# Ctime : 2025-12-16
# Mtime : 2025-12-30
# Docs : https://pigsty.io/docs/conf/infra
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for deploy victoria stack alone
# tutorial: https://pigsty.io/docs/infra
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c infra
# ./infra.yml
all :
children :
infra :
hosts :
10.10.10.10 : { infra_seq : 1 }
#10.10.10.11: { infra_seq: 2 } # you can add more nodes if you want
#10.10.10.12: { infra_seq: 3 } # don't forget to assign unique infra_seq for each node
vars :
docker_enabled : true # enabled docker with ./docker.yml
docker_registry_mirrors : [ "https://docker.1panel.live" , "https://docker.1ms.run" , "https://docker.xuanyuan.me" , "https://registry-1.docker.io" ]
pg_exporters : # bin/pgmon-add pg-rds
20001 : { pg_cluster: pg-rds ,pg_seq: 1 ,pg_host: 10.10.10.10 ,pg_exporter_url : 'postgres://postgres:postgres@10.10.10.10:5432/postgres' }
vars : # global variables
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
repo_enabled : false # online installation without repo
node_repo_modules : node,infra,pgsql # add these repos directly
#haproxy_enabled: false # enable haproxy on infra node?
#vector_enabled: false # enable vector on infra node?
# DON't FORGET TO CHANGE DEFAULT PASSWORDS!
grafana_admin_password : pigsty
haproxy_admin_password : pigsty
... 配置解读 infra 模板是 Pigsty 的 纯监控栈配置 ,专为独立部署可观测性基础设施设计。
适用场景 :
监控外部 PostgreSQL 实例(RDS、自建等) 需要独立的监控/告警平台 已有 PostgreSQL 集群,仅需添加监控 作为多集群监控的中央控制台 包含组件 :
VictoriaMetrics :时序数据库,存储监控指标VictoriaLogs :日志聚合系统VictoriaTraces :链路追踪系统Grafana :可视化仪表盘Alertmanager :告警管理Nginx :反向代理和 Web 入口不包含组件 :
PostgreSQL 数据库集群 etcd 分布式协调服务 MinIO 对象存储 监控外部实例 :
配置完成后,可通过 pgsql-monitor.yml 剧本添加外部 PostgreSQL 实例的监控:
pg_exporters :
20001 : { pg_cluster: pg-foo, pg_seq: 1, pg_host : 10.10.10.100 }
20002 : { pg_cluster: pg-bar, pg_seq: 1, pg_host : 10.10.10.101 }
注意事项 :
此模板不会安装任何数据库 如需完整功能,请使用 meta 或 rich 模板 可根据需要添加多个 infra 节点实现高可用 9.7 - vibe VIBE AI 编程沙箱配置模板,集成 Code-Server、JupyterLab、Claude Code 与 JuiceFS 的 Web 开发环境
vibe 配置模板提供了一个开箱即用的 AI 编程沙箱 ,集成了 Code-Server(Web VS Code)、JupyterLab、Claude Code 可观测能力、JuiceFS 分布式文件系统,以及功能丰富的 PostgreSQL 数据库。
配置概览 配置名称: vibe 节点数量: 单节点 配置说明:VIBE AI 编程沙箱,Code-Server + JupyterLab + Claude Code + JuiceFS + PostgreSQL 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c vibe [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/vibe.yml
---
#==============================================================#
# File : vibe.yml
# Desc : Pigsty ai vibe coding sandbox
# Ctime : 2026-01-19
# Mtime : 2026-02-28
# Docs : https://pigsty.io/docs/conf/vibe
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# VIBE CODING SANDBOX
# PostgreSQL with related extensions
# Code-Server, Jupyter, Claude Code
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c vibe
# ./deploy.yml
# ./juice.yml # pgfs: juicefs on pgsql, mount on /fs
# ./vibe.yml # code-server, jupyter, and claude-code
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
pgsql : { hosts : { 10.10.10.10 : { pg_seq: 1, pg_role: primary } } ,vars : { pg_cluster : pgsql }}
# optional modules
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#redis-ms:
# hosts: { 10.10.10.10: { redis_node: 1 , redis_instances: { 6379: { }, 6380: { replica_of: '10.10.10.10 6379' } } } }
# vars: { redis_cluster: redis-ms ,redis_password: 'redis.ms' ,redis_max_memory: 64MB }
vars :
#----------------------------------------------#
# INFRA: https://pigsty.io/docs/infra
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
dns_enabled : false # disable dns service
#blackbox_enabled: false # disable blackbox exporter
#alertmanager_enabled: false # disable alertmanager
infra_extra_services : # home page navigation entries
- { name: Code Server ,url: '/code' ,desc: 'VS Code Server' ,icon : 'code' }
- { name: Jupyter ,url: '/jupyter' ,desc: 'Jupyter Notebook' ,icon : 'jupyter' }
- { name: Claude Code ,url: '/ui/d/claude-code' ,desc: 'Claude Observability' ,icon : 'claude' }
#----------------------------------------------#
# NODE: https://pigsty.io/docs/node
#----------------------------------------------#
nodename_overwrite : false # do not overwrite node hostname on single node mode
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
node_dns_method : none # do not setup dns
node_repo_modules : node,infra,pgsql # add these repos directly to the singleton node
node_packages : [ openssh-server, juicefs, restic, rclone, uv, opencode, golang, asciinema, tmux ]
docker_enabled : true # enable docker service
node_firewall_mode: zone # default : trust intranet, expose selected public ports
node_firewall_public_port : [ 22 , 80 , 443 , 5432 ] # expose 5432 for remote access, remove in production!
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
#----------------------------------------------#
# PGSQL: https://pigsty.io/docs/pgsql
#----------------------------------------------#
pg_version : 18 # Default PostgreSQL Major Version is 18
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
pg_packages : [ pgsql-main, patroni, pgbackrest, pg_exporter, pgbackrest_exporter ]
pg_extensions : [ pg18-main ,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]
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 : [ postgis, timescaledb, vector, age ]}
pg_libs : 'timescaledb, pg_stat_statements, auto_explain, pg_wait_sampling'
pg_hba_rules :
- { user: all ,db: all ,addr: intra ,auth: pwd ,title: 'everyone intranet access with password' ,order : 800 }
# WARNING: devbox only. Remove world access in production.
- { user: all ,db: all ,addr: world ,auth: pwd ,title: 'everyone world access with password' ,order : 900 }
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am
patroni_mode : remove # remove patroni after deployment
pgbouncer_enabled : false # disable pgbouncer pool
pgbouncer_exporter_enabled : false # disable pgbouncer_exporter on pgsql hosts?
pgbackrest_exporter_enabled : false # disable pgbackrest_exporter
pg_default_services : [] # do not provision pg services
#pg_reload: false # do not reload patroni/service
#----------------------------------------------#
# 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
#----------------------------------------------#
# OPTIONAL VIBE COMPONENTS
#----------------------------------------------#
code_enabled : true # install & enable code-server via vibe role
code_password : DBUser.Meta
jupyter_enabled : true # enable jupyter (disabled by default, enable for vibe sandbox)
jupyter_password : DBUser.Meta
juice_instances :
jfs :
path : /fs
meta : postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
data : --storage postgres --bucket 10.10.10.10:5432/meta --access-key dbuser_meta --secret-key DBUser.Meta
port : 9567
# install npm packages : ./vibe.yml -t nodejs_pkg
npm_packages :
- '@anthropic-ai/claude-code' # claude code
- '@openai/codex' # openai codex
- 'happy-coder' # remote control
#- 'openclaw@latest' # in-case you need one
# setup claude code environment: ./vibe.yml -t claude
#claude_env:
# ANTHROPIC_BASE_URL: https://open.bigmodel.cn/api/anthropic
# ANTHROPIC_API_URL: https://open.bigmodel.cn/api/anthropic
# ANTHROPIC_AUTH_TOKEN: your_api_service_token
# ANTHROPIC_DEFAULT_OPUS_MODEL: "glm-5"
# ANTHROPIC_DEFAULT_SONNET_MODEL: "glm-5"
# ANTHROPIC_DEFAULT_HAIKU_MODEL: "glm-4.7-flash"
...
配置解读 vibe 模板是一个面向 AI 时代的 Web 编程沙箱 ,让您可以在浏览器中完成开发、数据分析、AI 应用构建等任务。
核心组件 :
组件 说明 访问方式 Code-Server VS Code 的 Web 版本,功能完整的代码编辑器 http://<ip>/codeJupyterLab 交互式数据科学笔记本,支持 Python/SQL http://<ip>/jupyterClaude Code AI 编程助手运行环境与可观测性入口(可通过 claude_env 定制) 终端 / 仪表盘 JuiceFS 基于 PostgreSQL 的分布式文件系统 挂载点 /fs PostgreSQL 18 功能丰富的数据库,安装 pg18-main + 全类别扩展包组 5432 端口
模板显式安装的节点工具 (node_packages):
openssh-server, juicefs, restic, rcloneuv, opencode, golangasciinema, tmuxPostgreSQL 扩展 :
此模板通过分类包组安装 PostgreSQL 18 的完整扩展集合:
pg18-main, 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
meta 业务库默认创建扩展为 postgis、timescaledb、vector,其余扩展可按需启用。
VIBE 模块组件 VIBE 模块在 v4.2 系列中提供 AI 编程沙箱能力;vibe.yml 显式开启 Code-Server 与 Jupyter,并预留 Claude 自定义入口。
Code-Server :浏览器中的 VS Code
完整的 VS Code 功能,支持扩展安装 通过 Nginx 反向代理提供 HTTPS 访问 支持 Open VSX 和 Microsoft 扩展商店 模板显式参数:code_enabled, code_password 其余可选参数:code_port, code_data, code_gallery JupyterLab :交互式计算环境
支持 Python/SQL/Markdown 笔记本 预配置 Python venv 数据科学库 通过 Nginx 反向代理提供 HTTPS 访问 模板显式参数:jupyter_enabled, jupyter_password 其余可选参数:jupyter_port, jupyter_data, jupyter_venv Claude Code :AI 编程助手
使用模块默认行为完成 Claude 运行环境配置 可通过 claude_env 覆盖模型端点与 API 密钥 提供 claude-code 仪表盘监控使用情况 JuiceFS 文件系统 此模板使用 JuiceFS 提供分布式文件系统能力,特别之处在于:元数据和数据都存储在 PostgreSQL 中 。
架构特点 :
元数据引擎 :使用 PostgreSQL 存储文件系统元数据数据存储 :使用 PostgreSQL 大对象(Large Object)存储文件数据挂载点 :默认挂载到 /fs 目录(由 juice_instances.jfs.path 控制)监控端口 :9567 提供 Prometheus 指标使用场景 :
代码项目的持久化存储 Jupyter Notebook 的工作目录 AI 模型和数据集的存储 多实例间的文件共享(扩展到多节点时) 配置示例 :
juice_instances :
jfs :
path : /fs
meta : postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
data : --storage postgres --bucket 10.10.10.10:5432/meta --access-key dbuser_meta --secret-key DBUser.Meta
port : 9567
部署步骤 # 1. 下载 Pigsty
curl https://repo.pigsty.io/get | bash
# 2. 使用 vibe 配置模板
./configure -c vibe
# 3. 修改密码(重要!)
vi pigsty.yml
# 修改 code_password, jupyter_password 等
# 4. 部署基础设施和 PostgreSQL
./deploy.yml
# 5. 部署 JuiceFS 文件系统
./juice.yml
# 6. 部署 VIBE 模块(Code-Server、JupyterLab、Claude Code)
./vibe.yml
访问方式 部署完成后,通过浏览器访问:
# Code-Server (VS Code Web)
http://<ip>/code
# 密码:DBUser.Meta(请修改)
# JupyterLab
http://<ip>/jupyter
# 密码:DBUser.Meta(请修改)
# Claude Code 仪表盘
http://<ip>/ui/d/claude-code
# Grafana 默认用户名:admin,密码:pigsty
# PostgreSQL
psql postgres://dbuser_meta:DBUser.Meta@<ip>:5432/meta
适用场景 AI 应用开发 :构建 RAG、Agent、LLM 应用数据科学 :使用 JupyterLab 进行数据分析和可视化远程开发 :在云服务器上搭建 Web IDE 环境教学演示 :提供一致的开发环境供学员使用快速原型 :快速验证想法,无需配置本地环境Claude Code 可观测性 :监控 AI 编程助手的使用情况注意事项 必须修改密码 :code_password 和 jupyter_password 默认值仅供测试网络安全 :此模板默认开放 5432(node_firewall_public_port)且包含 addr: world HBA 规则,生产环境请收紧资源需求 :建议至少 2 核 4GB 内存,SSD 磁盘精简架构 :此模板禁用了 Patroni、PgBouncer 等高可用组件,适合单节点开发环境Claude API :使用 Claude Code 需要配置 claude_env 中的 API 密钥9.8 - docker Pigsty Docker 容器化单机模板,适用于在容器内快速启动与体验 Pigsty。
docker 配置模板用于在 Docker 容器内运行 Pigsty,提供最小可用的单节点基础设施与 PostgreSQL 能力。
配置概览 配置名称: docker 节点数量: 单节点(容器环境) 配置说明:容器内快速体验模板,使用 127.0.0.1 与精简系统能力,适配 Docker 场景。 适用系统:容器镜像内置环境(建议配合官方 Pigsty Docker 镜像) 适用架构:x86_64, aarch64 相关配置:meta 、vibe 启用方式:
./configure -c docker -i 127.0.0.1 -g
配置内容 源文件地址:pigsty/conf/docker.yml
---
#==============================================================#
# File : docker.yml
# Desc : Pigsty docker coding environment
# Ctime : 2026-01-19
# Mtime : 2026-01-27
# Docs : https://pigsty.io/docs/conf/docker
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# DOCKER CONFIG, use 127.0.0.1 inside docker
# mount the /data volume when running docker container
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c docker -i 127.0.0.1 -g
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
pgsql : { hosts : { 10.10.10.10 : { pg_seq: 1, pg_role: primary }} ,vars : { pg_cluster : pgsql }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
vars :
#----------------------------------------------#
# Infra
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: china # upstream mirror region : default|china|europe
dns_enabled : false # disable dnsmasq service on single node
infra_portal :
home : { domain : i.pigsty }
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,10.10.10.10,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
#----------------------------------------------#
# Node
#----------------------------------------------#
nodename : pigsty
node_id_from_pg : false
node_tune : oltp
node_write_etc_hosts : false
node_dns_method : none
node_ntp_enabled : false
node_kernel_modules : []
node_repo_remove : true
node_repo_modules : 'node,infra,pgsql'
#----------------------------------------------#
# PGSQL: https://pigsty.io/docs/pgsql
#----------------------------------------------#
pg_version : 18 # Default PostgreSQL Major Version is 18
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
pg_extensions : [ pg18-main ,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]
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 : [ postgis, timescaledb, vector ]}
pg_libs : 'timescaledb, pg_stat_statements, auto_explain, pg_wait_sampling'
pg_hba_rules :
- { user: all ,db: all ,addr: intra ,auth: pwd ,title: 'everyone intranet access with password' ,order : 800 }
- { user: all ,db: all ,addr: world ,auth: pwd ,title: 'everyone world access with password' ,order : 900 }
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am
#pg_reload: false # do not reload patroni/service
#----------------------------------------------#
# 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
#----------------------------------------------#
# OPTIONAL
#----------------------------------------------#
#code_password: DBUser.Meta
#jupyter_password: DBUser.Meta
#juice_instances: # dict of juicefs filesystems to deploy
# jfs:
# path : /fs
# meta : postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
# data : --storage postgres --bucket 10.10.10.10:5432/meta --access-key dbuser_meta --secret-key DBUser.Meta
# port : 9567
#node_packages: [ openssh-server, tmux, juicefs, restic, rclone, uv, code-server ]
#npm_packages: [ '@anthropic-ai/claude-code' , 'happy-coder' ]
#claude_env:
# ANTHROPIC_BASE_URL: https://open.bigmodel.cn/api/anthropic
# ANTHROPIC_API_URL: https://open.bigmodel.cn/api/anthropic
# ANTHROPIC_AUTH_TOKEN: your_api_service_token
# ANTHROPIC_MODEL: glm-4.7
# ANTHROPIC_SMALL_FAST_MODEL: glm-4.5-air
...
配置解读 docker 模板主要面向容器内开发与验证,默认配置特征如下:
关闭本地仓库构建(repo_enabled: false),避免容器内额外仓库构建成本。 精简节点行为:关闭 NTP、内核模块加载与 hosts 覆写(node_ntp_enabled: false、node_kernel_modules: []、node_write_etc_hosts: false)。 默认 PostgreSQL 18,预置较完整扩展集合(pg18-* 扩展包组)。 允许内网与公网密码访问(pg_hba_rules 包含 intra 与 world),便于演示与测试。 预留可选能力(注释项):Code-Server、Jupyter、JuiceFS、Claude CLI 相关参数可按需启用。 注意事项:
这是开发/演示导向模板,生产环境请收紧 pg_hba_rules 与密码策略。 容器运行时建议挂载 /data,以持久化 PostgreSQL 与组件数据。
9.9 - 内核模版 9.10 - pgsql 原生 PostgreSQL 内核,支持 PostgreSQL 14 到 18 的多版本部署
pgsql 配置模板使用原生 PostgreSQL 内核,是 Pigsty 的默认数据库内核,支持 PostgreSQL 14 到 18 版本。
配置概览 配置名称: pgsql 节点数量: 单节点 配置说明:原生 PostgreSQL 内核配置模板 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c pgsql [ -i <primary_ip>]
如需指定非默认 PostgreSQL 版本(如 16):
./configure -c pgsql -v 16
配置内容 源文件地址:pigsty/conf/pgsql.yml
---
#==============================================================#
# File : pgsql.yml
# Desc : 1-node PostgreSQL Config template
# Ctime : 2025-02-23
# Mtime : 2025-12-28
# Docs : https://pigsty.io/docs/conf/pgsql
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for basical PostgreSQL Kernel.
# Nothing special, just a basic setup with one node.
# tutorial: https://pigsty.io/docs/pgsql/kernel/postgres
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c pgsql
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# PostgreSQL Cluster
#----------------------------------------------#
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 : 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 : [ postgis, timescaledb, vector ]}
pg_extensions : [ postgis, timescaledb, pgvector, pg_wait_sampling ]
pg_libs : 'timescaledb, pg_stat_statements, auto_explain, pg_wait_sampling'
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 :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
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
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # Default PostgreSQL Major Version is 18
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
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]
#repo_extra_packages: [ pg18-main ,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
...
配置解读 pgsql 模板是 Pigsty 的 标准内核配置 ,使用社区原生 PostgreSQL。
版本支持 :
PostgreSQL 18(默认) PostgreSQL 17、16、15、14 适用场景 :
需要使用最新 PostgreSQL 特性 需要最广泛的扩展支持 标准生产环境部署 与 meta 模板功能相同,显式声明使用原生内核 与 meta 的区别 :
pgsql 模板显式声明使用原生 PostgreSQL 内核适合需要明确区分不同内核类型的场景 9.11 - mssql Babelfish(PG17)内核模板,提供 Microsoft SQL Server 协议与 T-SQL 兼容能力
mssql 配置模板使用 Babelfish(PG17) 内核替代原生 PostgreSQL,提供 Microsoft SQL Server 线缆协议(TDS)与 T-SQL 语法兼容能力。
从 Pigsty v4.2 以来,Babelfish 由 Pigsty 直接构建,不再使用 WiltonDB 仓库,可在所有 支持的 Linux 平台 上使用。
完整教程请参考:Babelfish (MSSQL) 内核使用说明
配置概览 配置名称: mssql 节点数量: 单节点 配置说明:Babelfish(PG17)配置模板,提供 SQL Server 协议兼容 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c mssql [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/mssql.yml
---
#==============================================================#
# File : mssql.yml
# Desc : Babelfish (MSSQL Wire-Compatible) template
# Ctime : 2020-08-01
# Mtime : 2026-02-21
# Docs : https://pigsty.io/docs/conf/mssql
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for Babelfish Kernel made by Pigsty
# Which is a PostgreSQL 17 fork with SQL Server Compatibility
# tutorial: https://pigsty.io/docs/pgsql/kernel/babelfish
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c mssql
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# Babelfish Database Cluster
#----------------------------------------------#
pg-meta :
hosts :
10.10.10.10 : { pg_seq: 1, pg_role : primary }
vars :
pg_cluster : pg-meta
pg_users :
- {name: dbuser_mssql ,password: DBUser.MSSQL ,superuser: true, pgbouncer: true ,roles: [dbrole_admin], comment : superuser & owner for babelfish }
pg_databases :
- name : mssql
baseline : mssql.sql
extensions : [ uuid-ossp, babelfishpg_common, babelfishpg_tsql, babelfishpg_tds, babelfishpg_money ]
owner : dbuser_mssql
parameters : { 'babelfishpg_tsql.migration_mode' : 'multi-db' }
comment : babelfish cluster, a MSSQL compatible pg cluster
pg_crontab : # https://pigsty.io/docs/pgsql/admin/crontab
- '00 01 * * * /pg/bin/pg-backup full'
# Babelfish Ad Hoc Settings
pg_mode : mssql # Microsoft SQL Server Compatible Mode
pg_version : 17
pg_packages : [ babelfish, pgsql-common, sqlcmd ]
pg_libs : 'babelfishpg_tds, pg_stat_statements, auto_explain' # add timescaledb to shared_preload_libraries
pg_hba_rules : # https://pigsty.io/docs/pgsql/config/hba
- { user: dbuser_mssql ,db: mssql ,addr: intra ,auth: md5 ,title: 'allow mssql dbsu intranet access' ,order : 525 } # <--- use md5 auth method for mssql user
- { user: all ,db: all ,addr: intra ,auth: md5 ,title: 'everyone intranet access with md5 pwd' ,order : 800 }
pg_default_services : # route primary & replica service to mssql port 1433
- { name: primary ,port: 5433 ,dest: 1433 ,check: /primary ,selector : "[]" }
- { name: replica ,port: 5434 ,dest: 1433 ,check: /read-only ,selector : "[]" , backup : "[? pg_role == `primary` || pg_role == `offline` ]" }
- { name: default ,port: 5436 ,dest: postgres ,check: /primary ,selector : "[]" }
- { name: offline ,port: 5438 ,dest: postgres ,check: /replica ,selector : "[? pg_role == `offline` || pg_offline_query ]" , backup : "[? pg_role == `replica` && !pg_offline_query]" }
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
nodename_overwrite : false # do not overwrite node hostname on single node mode
node_repo_modules : node,infra,pgsql # extra mssql repo is required
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 17 # Babelfish kernel is compatible with postgres 17
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#----------------------------------------------#
# 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
... 配置解读 mssql 模板让您可以使用 SQL Server Management Studio (SSMS) 或其他 SQL Server 客户端工具连接 PostgreSQL(Babelfish 协议层)。
关键特性 :
使用 TDS 协议(端口 1433),兼容 SQL Server 客户端 支持 T-SQL 语法,迁移成本低 保留 PostgreSQL 的 ACID 特性和扩展生态(底层为 PG17) 支持 multi-db 和 single-db 两种迁移模式 默认包组为 babelfish + pgsql-common + sqlcmd 默认创建扩展:uuid-ossp、babelfishpg_common、babelfishpg_tsql、babelfishpg_tds、babelfishpg_money、pg_hint_plan、system_stats、tds_fdw v4.2.0 起支持主流平台全覆盖(EL8/9/10、Debian 12/13、Ubuntu 22/24/26;x86_64 / aarch64) 连接方式 :
# 使用 sqlcmd 命令行工具
sqlcmd -S 10.10.10.10,1433 -U dbuser_mssql -P DBUser.MSSQL -d mssql
# 使用 SSMS 或 Azure Data Studio
# Server: 10.10.10.10,1433
# Authentication: SQL Server Authentication
# Login: dbuser_mssql
# Password: DBUser.MSSQL
适用场景 :
从 SQL Server 迁移到 PostgreSQL 需要同时支持 SQL Server 和 PostgreSQL 客户端的应用 希望利用 PostgreSQL 生态同时保持 T-SQL 兼容性 注意事项 :
Babelfish 内核基于 PostgreSQL 17,不支持 PG18+ 专有特性 默认迁移模式为 multi-db(babelfishpg_tsql.migration_mode),可按需改为 single-db 部分 T-SQL 语法可能存在兼容性差异,请参考 Babelfish 兼容性文档 需要使用 md5 认证方式(而非 scram-sha-256) 9.12 - polar PolarDB for PostgreSQL 内核,提供 Aurora 风格的存算分离能力
polar 配置模板使用阿里云 PolarDB for PostgreSQL 数据库内核替代原生 PostgreSQL,提供"云原生" Aurora 风格的存算分离能力。
完整教程请参考:PolarDB for PostgreSQL (POLAR) 内核使用说明 ;所有内核分支的差异与版本口径见 PGSQL 内核总览 。
配置概览 配置名称: polar 节点数量: 单节点 配置说明:使用 PolarDB for PostgreSQL 内核 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c polar [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/polar.yml
---
#==============================================================#
# File : polar.yml
# Desc : Pigsty 1-node PolarDB Kernel Config Template
# Ctime : 2020-08-05
# Mtime : 2026-04-15
# Docs : https://pigsty.io/docs/conf/polar
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for PolarDB PG Kernel,
# Which is a PostgreSQL 17 fork with RAC flavor features
# tutorial: https://pigsty.io/docs/pgsql/kernel/polardb
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c polar
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# PolarDB Database Cluster
#----------------------------------------------#
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 : pigsty admin user }
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment : read-only viewer for meta database }
pg_databases :
- {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas : [ pigsty]}
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'
# PolarDB Ad Hoc Settings
pg_version : 17 # PolarDB PG is based on PG 17
pg_mode : polar # PolarDB PG Compatible mode
pg_packages : [ polardb, pgsql-common ] # Replace PG kernel with PolarDB kernel
pg_exporter_exclude_database : 'template0,template1,postgres,polardb_admin'
pg_default_roles : # PolarDB require replicator as superuser
- { name: dbrole_readonly ,login: false ,comment : role for global read-only access }
- { name: dbrole_offline ,login: false ,comment : role for restricted read-only access }
- { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly] ,comment : role for global read-write access }
- { name: dbrole_admin ,login: false ,roles: [pg_monitor, dbrole_readwrite] ,comment : role for object creation }
- { name: postgres ,superuser: true ,comment : system superuser }
- { name: replicator ,superuser: true ,replication: true ,roles: [pg_monitor, dbrole_readonly] ,comment : system replicator } # <- superuser is required for replication
- { name: dbuser_dba ,superuser: true ,roles: [dbrole_admin] ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 ,comment : pgsql admin user }
- { name: dbuser_monitor ,roles: [pg_monitor] ,pgbouncer: true ,parameters : {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment : pgsql monitor user }
vars : # global variables
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
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
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 17 # PolarDB is compatible with PG 17
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#----------------------------------------------#
# 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
... 配置解读 polar 模板使用阿里云开源的 PolarDB for PostgreSQL 内核,提供云原生数据库能力。
关键特性 :
适用场景 :
需要存算分离架构的云原生场景 读多写少的业务负载 需要快速扩展读副本的场景 评估 PolarDB 特性的测试环境 注意事项 :
PolarDB 当前基于 PostgreSQL 17 复制用户需要超级用户权限(与原生 PostgreSQL 不同) 部分 PostgreSQL 扩展可能存在兼容性问题 当前模板已提供 x86_64 与 aarch64 软件包支持 9.13 - cloudberry Cloudberry 配置模板占位页(暂未提供该模板)。
当前版本暂未提供 cloudberry 配置模板。
如果你需要该模板,请先参考:
9.14 - ivory IvorySQL 内核,提供 Oracle 语法与 PL/SQL 兼容能力
ivory 配置模板使用瀚高的 IvorySQL 数据库内核替代原生 PostgreSQL,提供 Oracle 语法与 PL/SQL 兼容能力。
完整教程请参考:IvorySQL (Oracle兼容) 内核使用说明
配置概览 配置名称: ivory 节点数量: 单节点 配置说明:使用 IvorySQL Oracle 兼容内核 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c ivory [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/ivory.yml
---
#==============================================================#
# File : ivory.yml
# Desc : IvorySQL 4 (Oracle Compatible) template
# Ctime : 2024-08-05
# Mtime : 2026-02-26
# Docs : https://pigsty.io/docs/conf/ivory
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for IvorySQL 5 Kernel,
# Which is a PostgreSQL 18 fork with Oracle Compatibility
# tutorial: https://pigsty.io/docs/pgsql/kernel/ivorysql
# Oracle compatible port (PGSQL Wire) is 1521
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c ivory
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# IvorySQL Database Cluster
#----------------------------------------------#
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 : pigsty admin user }
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment : read-only viewer for meta database }
pg_databases :
- {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas : [ pigsty]}
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'
# IvorySQL Ad Hoc Settings
pg_mode : ivory # Use IvorySQL Oracle Compatible Mode
pg_packages : [ ivorysql, pgsql-common ] # install IvorySQL instead of postgresql kernel
pg_libs : 'liboracle_parser, pg_stat_statements, auto_explain' # pre-load oracle parser
vars : # global variables
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
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
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # IvorySQL kernel is compatible with postgres 18
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#----------------------------------------------#
# 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
... 配置解读 ivory 模板使用瀚高开源的 IvorySQL 内核,提供 Oracle 数据库兼容能力。
关键特性 :
支持 Oracle PL/SQL 语法 兼容 Oracle 数据类型(NUMBER、VARCHAR2 等) 支持 Oracle 风格的包(Package) 保留 PostgreSQL 的所有标准功能 适用场景 :
从 Oracle 迁移到 PostgreSQL 需要同时支持 Oracle 和 PostgreSQL 语法的应用 希望利用 PostgreSQL 生态同时保持 PL/SQL 兼容性 评估 IvorySQL 特性的测试环境 注意事项 :
IvorySQL 5 基于 PostgreSQL 18 使用 liboracle_parser 需要加载到 shared_preload_libraries pgbackrest 在 Oracle 兼容模式下可能存在校验问题,PITR 能力受限主要支持 EL8/EL9 系统,其他系统支持程度请参考官方文档 9.15 - agens AgensGraph 内核模板,提供属性图模型与 Cypher 查询能力
agens 配置模板使用 AgensGraph 数据库内核替代原生 PostgreSQL,提供属性图模型与 Cypher 查询能力。
完整教程请参考:AgensGraph 内核使用说明
配置概览 配置名称: agens 节点数量: 单节点 配置说明:AgensGraph(PG16)图数据库内核配置 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 、pgsql 启用方式:
./configure -c agens [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/agens.yml
---
#==============================================================#
# File : agens.yml
# Desc : 1-node AgensGraph (Graph DB) template
# Ctime : 2026-02-26
# Mtime : 2026-02-26
# Docs : https://pigsty.io/docs/conf/agens
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for AgensGraph Kernel,
# Which is a PostgreSQL 16 fork with graph capabilities.
# tutorial: https://pigsty.io/docs/pgsql/kernel/agensgraph
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c agens
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# AgensGraph Database Cluster
#----------------------------------------------#
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 : pigsty admin user }
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment : read-only viewer for meta database }
pg_databases :
- {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas : [ pigsty]}
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'
# AgensGraph Ad Hoc Settings
pg_mode : agens # AgensGraph compatible mode
pg_packages : [ agensgraph, pgsql-common ] # install AgensGraph kernel package + common utils
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
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
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 16 # AgensGraph kernel is compatible with postgres 16
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#----------------------------------------------#
# 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
...
配置解读 agens 模板在 pg-meta 集群中启用 pg_mode: agens,并使用 agensgraph 内核包替换标准 PostgreSQL 内核。
关键特性 :
属性图模型能力(Vertex / Edge) 支持 Cypher 查询语法,可与 SQL 混合使用 兼容 PostgreSQL 生态与常规运维方式 默认基于 PostgreSQL 16 兼容内核 适用场景 :
图关系分析与路径查询 社交关系、风控关联、知识图谱等图数据场景 需要在 PostgreSQL 体系中引入图查询能力 注意事项 :
AgensGraph 当前模板固定使用 pg_version: 16 默认模板为单节点快速启用,生产场景建议按需扩展高可用拓扑 图模型与 Cypher 语义请结合 AgensGraph 官方文档进行设计 9.16 - pgedge pgEdge 内核模板,提供面向边缘场景的多主分布式 PostgreSQL 能力
pgedge 配置模板使用 pgEdge 数据库内核替代原生 PostgreSQL,提供面向边缘场景的分布式与多主复制能力。
完整教程请参考:pgEdge 内核使用说明 ;所有内核分支的差异与版本口径见 PGSQL 内核总览 。
配置概览 配置名称: pgedge 节点数量: 单节点 配置说明:pgEdge(PG18)分布式内核配置模板 适用系统:d12, d13, u22, u24, u26(PG18 包);EL/RPM 平台请以当前 PGSQL 仓库的 pgedge_18 包可用性为准 适用架构:x86_64, aarch64 相关配置:meta 、pgsql 启用方式:
./configure -c pgedge [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/pgedge.yml
---
#==============================================================#
# File : pgedge.yml
# Desc : 1-node pgEdge (Distributed PG) template
# Ctime : 2026-02-26
# Mtime : 2026-02-26
# Docs : https://pigsty.io/docs/conf/pgedge
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for pgEdge Kernel,
# Which is a PostgreSQL 18 compatible fork.
# tutorial: https://pigsty.io/docs/pgsql/kernel/pgedge
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c pgedge
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# pgEdge Database Cluster
#----------------------------------------------#
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 : pigsty admin user }
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment : read-only viewer for meta database }
pg_databases :
- {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions : [ spock, snowflake, lolor]}
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'
# pgEdge Ad Hoc Settings
pg_mode : pgedge # pgEdge compatible mode
pg_packages : [ pgedge, pgsql-common ] # install pgEdge kernel package + common utils
pg_extensions : [ spock, snowflake, lolor ] # ensure pgEdge extension packages are installed
pg_libs : 'spock, lolor, pg_stat_statements, auto_explain' # preload required libs for pgEdge logical replication
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
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
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # pgEdge kernel is compatible with postgres 18
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#----------------------------------------------#
# 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
...
配置解读 pgedge 模板在 pg-meta 集群中启用 pg_mode: pgedge,并预装 pgEdge 核心扩展用于逻辑复制与边缘分布式场景。
关键特性 :
适用场景 :
多地域边缘部署与就近写入 需要多主逻辑复制与冲突处理能力 从单节点验证逐步扩展到分布式拓扑 注意事项 :
当前模板用于单节点内核验证,生产多主需额外规划节点拓扑与复制策略 默认 pg_version: 18,建议与目标集群版本保持一致 进行跨地域复制前,请先评估网络时延与冲突处理策略 9.17 - mysql OpenHalo 内核,提供 MySQL 协议与语法兼容能力
mysql 配置模板使用 OpenHalo 数据库内核替代原生 PostgreSQL,提供 MySQL 线缆协议与 SQL 语法兼容能力。
配置概览 配置名称: mysql 节点数量: 单节点 配置说明:OpenHalo MySQL 兼容内核配置 适用系统:el8, el9, el10, d12, d13, u22, u24 适用架构:x86_64 相关配置:meta 启用方式:
./configure -c mysql [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/mysql.yml
---
#==============================================================#
# File : mysql.yml
# Desc : 1-node OpenHaloDB (MySQL Compatible) template
# Ctime : 2025-04-03
# Mtime : 2026-02-26
# Docs : https://pigsty.io/docs/conf/mysql
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for OpenHalo PG Kernel,
# Which is a PostgreSQL 14 fork with MySQL Wire Compatibility
# tutorial: https://pigsty.io/docs/pgsql/kernel/openhalo
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c mysql
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# OpenHalo Database Cluster
#----------------------------------------------#
# connect with mysql client: mysql -h 10.10.10.10 -u dbuser_meta -D mysql (the actual database is 'postgres', and 'mysql' is a schema)
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 : pigsty admin user }
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment : read-only viewer for meta database }
pg_databases :
- {name: postgres, extensions : [ aux_mysql]} # the mysql compatible database
- {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas : [ pigsty]}
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'
# OpenHalo Ad Hoc Setting
pg_mode : mysql # MySQL Compatible Mode by HaloDB
pg_version : 14 # The current HaloDB is compatible with PG Major Version 14
pg_packages : [ openhalo, pgsql-common ] # install openhalodb instead of postgresql kernel
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
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
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 14 # OpenHalo is compatible with PG 14
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#----------------------------------------------#
# 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
... 配置解读 mysql 模板使用 OpenHalo 内核,让您可以使用 MySQL 客户端工具连接 PostgreSQL。
关键特性 :
使用 MySQL 协议(端口 3306),兼容 MySQL 客户端 支持 MySQL SQL 语法子集 保留 PostgreSQL 的 ACID 特性和存储引擎 同时支持 PostgreSQL 和 MySQL 两种协议连接 连接方式 :
# 使用 MySQL 客户端
mysql -h 10.10.10.10 -P 3306 -u dbuser_meta -pDBUser.Meta
# 同时保留 PostgreSQL 连接能力
psql postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
适用场景 :
从 MySQL 迁移到 PostgreSQL 需要同时支持 MySQL 和 PostgreSQL 客户端的应用 希望利用 PostgreSQL 生态同时保持 MySQL 兼容性 注意事项 :
OpenHalo 基于 PostgreSQL 14,不支持更高版本特性 部分 MySQL 语法可能存在兼容性差异 仅支持 EL8/EL9 系统 不支持 ARM64 架构 9.18 - pgtde Percona PostgreSQL 内核,提供透明数据加密 (pg_tde) 能力
pgtde 配置模板使用 Percona PostgreSQL 数据库内核,提供透明数据加密 (Transparent Data Encryption, TDE) 能力。
配置概览 配置名称: pgtde 节点数量: 单节点 配置说明:Percona PostgreSQL 透明数据加密配置 适用系统:el8, el9, el10, d12, d13, u22, u24 适用架构:x86_64 相关配置:meta 启用方式:
./configure -c pgtde [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/pgtde.yml
---
#==============================================================#
# File : pgtde.yml
# Desc : PG TDE with Percona PostgreSQL 1-node template
# Ctime : 2025-07-04
# Mtime : 2025-12-28
# Docs : https://pigsty.io/docs/conf/pgtde
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for Percona PostgreSQL Distribution
# With pg_tde extension, which is compatible with PostgreSQL 18.1
# tutorial: https://pigsty.io/docs/pgsql/kernel/percona
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c pgtde
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# Percona Postgres Database Cluster
#----------------------------------------------#
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 : 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 tde database
schemas : [ pigsty]
extensions : [ vector, postgis, pg_tde ,pgaudit, { name: pg_stat_monitor, schema: monitor } ]
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'
# Percona PostgreSQL TDE Ad Hoc Settings
pg_packages : [ percona-main, pgsql-common ] # install percona postgres packages
pg_libs : 'pg_tde, pgaudit, pg_stat_statements, pg_stat_monitor, auto_explain'
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
nodename_overwrite : false # do not overwrite node hostname on single node mode
node_repo_modules : node,infra,pgsql,percona
node_tune : oltp
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # Default Percona TDE PG Major Version is 18
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#----------------------------------------------#
# 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
... 配置解读 pgtde 模板使用 Percona PostgreSQL 内核,提供企业级透明数据加密能力。
关键特性 :
透明数据加密 :数据在磁盘上自动加密,对应用透明密钥管理 :支持本地密钥和外部密钥管理系统 (KMS)表级加密 :可选择性加密敏感表完整兼容 :与原生 PostgreSQL 完全兼容适用场景 :
需要满足数据安全合规要求(如 PCI-DSS、HIPAA) 存储敏感数据(如个人信息、金融数据) 需要静态数据加密的场景 对数据安全有严格要求的企业环境 使用方法 :
-- 创建加密表
CREATE TABLE sensitive_data (
id SERIAL PRIMARY KEY ,
ssn VARCHAR ( 11 )
) USING pg_tde ;
-- 或对现有表启用加密
ALTER TABLE existing_table SET ACCESS METHOD pg_tde ;
注意事项 :
Percona PostgreSQL 基于 PostgreSQL 18 加密会带来一定性能开销(通常 5-15%) 需要妥善管理加密密钥 不支持 ARM64 架构 9.19 - oriole OrioleDB 内核,提供无膨胀的 OLTP 增强存储引擎
oriole 配置模板使用 OrioleDB 存储引擎替代 PostgreSQL 默认的 Heap 存储,提供无膨胀、高性能的 OLTP 能力。
配置概览 配置名称: oriole 节点数量: 单节点 配置说明:OrioleDB 无膨胀存储引擎配置 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64 相关配置:meta 启用方式:
./configure -c oriole [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/oriole.yml
---
#==============================================================#
# File : oriole.yml
# Desc : 1-node OrioleDB (OLTP Enhancement) template
# Ctime : 2025-04-05
# Mtime : 2025-12-28
# Docs : https://pigsty.io/docs/conf/oriole
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for OrioleDB Kernel,
# Which is a Patched PostgreSQL 17 fork without bloat
# tutorial: https://pigsty.io/docs/pgsql/kernel/orioledb
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c oriole
# ./deploy.yml
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# OrioleDB Database Cluster
#----------------------------------------------#
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 : pigsty admin user }
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment : read-only viewer for meta database }
pg_databases :
- {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty], extensions : [ orioledb]}
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'
# OrioleDB Ad Hoc Settings
pg_mode : oriole # oriole compatible mode
pg_packages : [ oriole, pgsql-common ] # install OrioleDB kernel
pg_libs : 'orioledb, pg_stat_statements, auto_explain' # Load OrioleDB Extension
vars : # global variables
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
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
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 17 # OrioleDB Kernel is based on PG 17
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#----------------------------------------------#
# 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
... 配置解读 oriole 模板使用 OrioleDB 存储引擎,从根本上解决 PostgreSQL 表膨胀问题。
关键特性 :
无膨胀设计 :使用 UNDO 日志而非多版本并发控制 (MVCC)无需 VACUUM :消除 autovacuum 带来的性能抖动行级 WAL :更高效的日志记录和复制压缩存储 :内置数据压缩,减少存储空间适用场景 :
高频更新的 OLTP 工作负载 对写入延迟敏感的应用 需要稳定响应时间(消除 VACUUM 影响) 大表频繁更新导致膨胀的场景 使用方法 :
-- 创建使用 OrioleDB 存储的表
CREATE TABLE orders (
id SERIAL PRIMARY KEY ,
customer_id INT ,
amount DECIMAL ( 10 , 2 )
) USING orioledb ;
-- 对现有表无法直接转换,需要重建
注意事项 :
OrioleDB 基于 PostgreSQL 17 需要将 orioledb 添加到 shared_preload_libraries 部分 PostgreSQL 特性可能不完全支持 不支持 ARM64 架构 9.20 - mongo DocumentDB + FerretDB(Mongo Wire 协议兼容)配置模板,基于 PostgreSQL 提供 Mongo 风格服务。
mongo 配置模板用于部署 FerretDB 与 DocumentDB 兼容栈,在 PostgreSQL 之上提供 Mongo Wire 协议兼容能力。
完整教程请参考:FerretDB / Mongo 兼容层使用说明
配置概览 配置名称: mongo 节点数量: 单节点(默认) 配置说明:基于 PostgreSQL 18 + FerretDB + DocumentDB 的 Mongo 兼容模板。 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 、pgsql 启用方式:
./configure -c mongo
./deploy.yml
./mongo.yml -l ferret
配置内容 源文件地址:pigsty/conf/mongo.yml
---
#==============================================================#
# File : mongo.yml
# Desc : DocumentDB & FerretDB (MongoDB Compatible) template
# Ctime : 2025-02-23
# Mtime : 2026-01-17
# Docs : https://pigsty.io/docs/ferret
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for FerretDB & DocumentDB
# That is a Mongo Wire-Compatible Layer upon PostgreSQL
# This config template works with PostgreSQL 16, 17, 18
# tutorial: https://pigsty.io/docs/ferret
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c mongo
# ./deploy.yml
# ./mongo.yml -l ferret
all :
children :
infra : { hosts : { 10.10.10.10 : { infra_seq: 1 }} ,vars : { repo_enabled : false }}
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 }} ,vars : { etcd_cluster : etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------#
# FerretDB Database Cluster
#----------------------------------#
# ./mongo.yml -l ferret
ferret :
hosts :
10.10.10.10 : { mongo_seq : 1 }
vars :
mongo_cluster : ferret
mongo_pgurl : 'postgres://dbuser_dba:DBUser.DBA@10.10.10.10:5432/postgres'
# mongosh 'mongodb://dbuser_dba:DBUser.DBA@10.10.10.10:27017'
#----------------------------------#
# PGSQL Database Cluster
#----------------------------------#
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 : pigsty admin user }
- { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment : read-only viewer }
pg_databases :
- { name: postgres, extensions : [ documentdb, postgis, vector, pg_cron, rum ]} # run on the postgres database
pg_hba_rules :
- { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title : 'allow grafana dashboard access cmdb from infra nodes' }
# WARNING: demo/dev only. Avoid world access for dbsu in production.
- { user: postgres , db: all ,addr: world ,auth: pwd ,title : 'dbsu password access everywhere' }
- { user: all ,db: all ,addr: localhost ,order: 1 ,auth: trust ,title : 'documentdb localhost trust access' }
- { user: all ,db: all ,addr: local ,order: 1 ,auth: trust ,title : 'documentdb local trust access' }
- { user: all ,db: all ,addr: intra ,auth: pwd ,title: 'everyone intranet access with password' ,order : 800 }
pg_parameters : { cron.database_name : postgres }
pg_extensions : [ documentdb, postgis, pgvector, pg_cron, rum ]
pg_libs : 'pg_documentdb, pg_documentdb_core, pg_documentdb_extended_rum, pg_cron, pg_stat_statements, auto_explain'
pg_crontab : # https://pigsty.io/docs/pgsql/admin/crontab
- '00 01 * * * /pg/bin/pg-backup full'
vars : # global variables
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
nodename_overwrite : false # do not overwrite node hostname
node_repo_modules : node,infra,pgsql # add these repos directly to the nodes (consider add 'mongo' too)
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # default postgres version (16,17,18)
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#----------------------------------------------#
# 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
...
配置解读 mongo 模板包含两个核心分组:
pg-meta:PostgreSQL 主库,默认安装 documentdb、postgis、pgvector、pg_cron、rum。ferret:Mongo 协议兼容服务层,使用 mongo_pgurl(默认连接 postgres 库)访问 PostgreSQL。关键特征:
默认使用 PostgreSQL 18(可改为 16/17/18)。 在 postgres 数据库直接启用 documentdb 相关能力,便于快速验证。 预加载库包含 pg_documentdb、pg_documentdb_core、pg_documentdb_extended_rum、pg_cron。 默认 HBA 规则包含本地 trust 与内网密码访问,便于开发测试。 注意事项:
模板中包含面向开发环境的宽松访问规则(如 world 访问示例),生产环境请按需收紧。 若需多节点与高可用,应在此模板基础上扩展拓扑与安全策略。 9.21 - supabase 使用 Pigsty 托管的 PostgreSQL 自建 Supabase 开源 Firebase 替代方案
supabase 配置模板提供了自建 Supabase 的参考配置,使用 Pigsty 托管的 PostgreSQL 作为底层存储。
更多细节,请参考 Supabase 自建教程
配置概览 配置名称: supabase 节点数量: 单节点 配置说明:使用 Pigsty 托管的 PostgreSQL 自建 Supabase 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta ,rich 启用方式:
./configure -c supabase [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/supabase.yml
---
#==============================================================#
# File : supabase.yml
# Desc : Pigsty configuration for self-hosting supabase
# Ctime : 2023-09-19
# Mtime : 2026-04-10
# Docs : https://pigsty.io/docs/conf/supabase
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# supabase is available on el8/el9/u22/u24/u26/d12 with pg15,16,17,18
# tutorial: https://pigsty.io/docs/app/supabase
# Usage:
# curl https://repo.pigsty.io/get | bash # install pigsty
# ./configure -c supabase # use this supabase conf template
# ./deploy.yml # install pigsty & pgsql & minio
# ./docker.yml # install docker & docker compose
# ./app.yml # launch supabase with docker compose
all :
children :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra
#----------------------------------------------#
infra :
hosts :
10.10.10.10 : { infra_seq : 1 }
vars :
repo_enabled : false # disable local repo
#----------------------------------------------#
# ETCD : https://pigsty.io/docs/etcd
#----------------------------------------------#
etcd :
hosts :
10.10.10.10 : { etcd_seq : 1 }
vars :
etcd_cluster : etcd
etcd_safeguard : false # enable to prevent purging running etcd instance
#----------------------------------------------#
# MINIO : https://pigsty.io/docs/minio
#----------------------------------------------#
minio :
hosts :
10.10.10.10 : { minio_seq : 1 }
vars :
minio_cluster : minio
minio_users : # list of minio user to be created
- { access_key: pgbackrest ,secret_key: S3User.Backup ,policy : pgsql }
- { access_key: s3user_meta ,secret_key: S3User.Meta ,policy : meta }
- { access_key: s3user_data ,secret_key: S3User.Data ,policy : data }
#----------------------------------------------#
# PostgreSQL cluster for Supabase self-hosting
#----------------------------------------------#
pg-meta :
hosts :
10.10.10.10 : { pg_seq: 1, pg_role : primary }
vars :
pg_cluster : pg-meta
pg_users :
# supabase roles: anon, authenticated, dashboard_user
- { name: anon ,login : false }
- { name: authenticated ,login : false }
- { name: dashboard_user ,login: false ,replication: true ,createdb: true ,createrole : true }
- { name: service_role ,login: false ,bypassrls : true }
# supabase users: please use the same password
- { name: supabase_admin ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: true ,roles: [ dbrole_admin ] ,superuser: true ,replication: true ,createdb: true ,createrole: true ,bypassrls : true }
- { name: authenticator ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: false ,roles : [ dbrole_admin, authenticated ,anon ,service_role ] }
- { name: supabase_auth_admin ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: false ,roles: [ dbrole_admin ] ,createrole : true }
- { name: supabase_storage_admin ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: false ,roles: [ dbrole_admin, authenticated ,anon ,service_role ] ,createrole : true }
- { name: supabase_functions_admin ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: false ,roles: [ dbrole_admin ] ,createrole : true }
- { name: supabase_replication_admin ,password: 'DBUser.Supa' ,replication: true ,roles : [ dbrole_admin ]}
- { name: supabase_etl_admin ,password: 'DBUser.Supa' ,replication: true ,roles : [ pg_read_all_data, dbrole_readonly ]}
- { name: supabase_read_only_user ,password: 'DBUser.Supa' ,bypassrls: true ,roles : [ pg_read_all_data, dbrole_readonly ]}
pg_databases :
- name : postgres
baseline : supabase.sql
owner : supabase_admin
comment : supabase postgres database
schemas : [ extensions ,auth ,realtime ,storage ,graphql_public ,supabase_functions ,_analytics ,_realtime ]
extensions :
- { name: pgcrypto ,schema : extensions } # cryptographic functions
- { name: pg_net ,schema : extensions } # async HTTP
- { name: pgjwt ,schema : extensions } # json web token API for postgres
- { name: uuid-ossp ,schema : extensions } # generate universally unique identifiers (UUIDs)
- { name: pgsodium ,schema : extensions } # pgsodium is a modern cryptography library for Postgres.
- { name: supabase_vault ,schema : extensions } # Supabase Vault Extension
- { name: pg_graphql ,schema: extensions } # pg_graphql : GraphQL support
- { name: pg_jsonschema ,schema: extensions } # pg_jsonschema : Validate json schema
- { name: wrappers ,schema: extensions } # wrappers : FDW collections
- { name: http ,schema: extensions } # http : allows web page retrieval inside the database.
- { name: pg_cron ,schema: extensions } # pg_cron : Job scheduler for PostgreSQL
- { name: timescaledb ,schema: extensions } # timescaledb : Enables scalable inserts and complex queries for time-series data
- { name: pg_tle ,schema: extensions } # pg_tle : Trusted Language Extensions for PostgreSQL
- { name: vector ,schema: extensions } # pgvector : the vector similarity search
- { name: pgmq ,schema: extensions } # pgmq : A lightweight message queue like AWS SQS and RSMQ
# supabase required extensions
pg_libs : 'timescaledb, pgsodium, plpgsql, plpgsql_check, pg_cron, pg_net, pg_stat_statements, auto_explain, pg_wait_sampling, pg_tle, plan_filter'
pg_extensions : [ pg18-main ,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]
pg_parameters : { cron.database_name : postgres }
pg_hba_rules : # supabase hba rules, require access from docker network
- { user: all ,db: postgres ,addr: intra ,auth: pwd ,title: 'allow supabase access from intranet' ,order : 50 }
- { user: all ,db: postgres ,addr: 172.17.0.0/16 ,auth: pwd ,title: 'allow access from local docker network' ,order : 50 }
pg_crontab :
- '00 01 * * * /pg/bin/pg-backup full' # make a full backup every 1am
- '* * * * * /pg/bin/supa-kick' # kick supabase _analytics lag per minute : https://github.com/pgsty/pigsty/issues/581
#----------------------------------------------#
# Supabase
#----------------------------------------------#
# ./docker.yml
# ./app.yml
# the supabase stateless containers (default username & password: supabase/pigsty)
supabase :
hosts :
10.10.10.10 : {}
vars :
docker_enabled : true # enable docker on this group
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
app : supabase # specify app name (supa) to be installed (in the apps)
apps : # define all applications
supabase : # the definition of supabase app
conf : # override /opt/supabase/.env
# IMPORTANT: CHANGE JWT_SECRET AND REGENERATE CREDENTIAL ACCORDING!!!!!!!!!!!
# https://supabase.com/docs/guides/self-hosting/docker#securing-your-services
JWT_SECRET : your-super-secret-jwt-token-with-at-least-32-characters-long
ANON_KEY : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyAgCiAgICAicm9sZSI6ICJhbm9uIiwKICAgICJpc3MiOiAic3VwYWJhc2UtZGVtbyIsCiAgICAiaWF0IjogMTY0MTc2OTIwMCwKICAgICJleHAiOiAxNzk5NTM1NjAwCn0.dc_X5iR_VP_qT0zsiyj_I_OZ2T9FtRU2BBNWN8Bu4GE
SERVICE_ROLE_KEY : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyAgCiAgICAicm9sZSI6ICJzZXJ2aWNlX3JvbGUiLAogICAgImlzcyI6ICJzdXBhYmFzZS1kZW1vIiwKICAgICJpYXQiOiAxNjQxNzY5MjAwLAogICAgImV4cCI6IDE3OTk1MzU2MDAKfQ.DaYlNEoUrrEn2Ig7tqibS-PHK5vgusbcbo7X36XVt4Q
PG_META_CRYPTO_KEY : your-encryption-key-32-chars-min
DASHBOARD_USERNAME : supabase
DASHBOARD_PASSWORD : pigsty
# 32~64 random characters string for logflare
LOGFLARE_PUBLIC_ACCESS_TOKEN : 1234567890abcdef1234567890abcdef
LOGFLARE_PRIVATE_ACCESS_TOKEN : fedcba0987654321fedcba0987654321
# postgres connection string (use the correct ip and port)
POSTGRES_HOST : 10.10.10.10 # point to the local postgres node
POSTGRES_PORT : 5436 # access via the 'default' service, which always route to the primary postgres
POSTGRES_DB : postgres # the supabase underlying database
POSTGRES_PASSWORD : DBUser.Supa # password for supabase_admin and multiple supabase users
# expose supabase via domain name
SITE_URL : https://supa.pigsty # <------- Change This to your external domain name
API_EXTERNAL_URL : https://supa.pigsty # <------- Otherwise the storage api may not work!
SUPABASE_PUBLIC_URL : https://supa.pigsty # <------- DO NOT FORGET TO PUT IT IN infra_portal!
# if using s3/minio as file storage
S3_BUCKET : data
S3_ENDPOINT : https://sss.pigsty:9000
S3_ACCESS_KEY : s3user_data
S3_SECRET_KEY : S3User.Data
S3_FORCE_PATH_STYLE : true
S3_PROTOCOL : https
S3_REGION : stub
S3_PROTOCOL_ACCESS_KEY_ID : s3user_data
S3_PROTOCOL_ACCESS_KEY_SECRET : S3User.Data
MINIO_DOMAIN_IP : 10.10.10.10 # sss.pigsty domain name will resolve to this ip statically
# if using SMTP (optional)
#SMTP_ADMIN_EMAIL: admin@example.com
#SMTP_HOST: supabase-mail
#SMTP_PORT: 2500
#SMTP_USER: fake_mail_user
#SMTP_PASS: fake_mail_password
#SMTP_SENDER_NAME: fake_sender
#ENABLE_ANONYMOUS_USERS: false
#==============================================================#
# Global Parameters
#==============================================================#
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
certbot_sign : false # enable certbot to sign https certificate for infra portal
certbot_email : your@email.com # replace your email address to receive expiration notice
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
pgadmin : { domain: adm.pigsty ,endpoint : "${admin_ip}:8885" }
bytebase : { domain: ddl.pigsty ,endpoint : "${admin_ip}:8887" }
#minio : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
# Nginx / Domain / HTTPS : https://pigsty.io/docs/infra/admin/portal
supa : # nginx server config for supabase
domain : supa.pigsty # REPLACE IT WITH YOUR OWN DOMAIN!
endpoint : "10.10.10.10:8000" # supabase service endpoint: IP:PORT
websocket : true # add websocket support
certbot : supa.pigsty # certbot cert name, apply with `make cert`
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
nodename_overwrite : false # do not overwrite node hostname on single node mode
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
node_etc_hosts : # add static domains to all nodes /etc/hosts
- 10.10.10.10 i.pigsty sss.pigsty supa.pigsty
node_repo_modules : node,pgsql,infra # use pre-made local repo rather than install from upstream
node_repo_remove : true # remove existing node repo for node managed by pigsty
#node_packages: [openssh-server] # packages to be installed current nodes with latest version
#node_timezone: Asia/Hong_Kong # overwrite node timezone
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # default postgres version
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
pg_safeguard : false # prevent purging running postgres instance?
pg_default_schemas: [ monitor, extensions ] # add new schema : extensions
pg_default_extensions : # default extensions to be created
- { name: pg_stat_statements ,schema : monitor }
- { name: pgstattuple ,schema : monitor }
- { name: pg_buffercache ,schema : monitor }
- { name: pageinspect ,schema : monitor }
- { name: pg_prewarm ,schema : monitor }
- { name: pg_visibility ,schema : monitor }
- { name: pg_freespacemap ,schema : monitor }
- { name: pg_wait_sampling ,schema : monitor }
# move default extensions to `extensions` schema for supabase
- { name: postgres_fdw ,schema : extensions }
- { name: file_fdw ,schema : extensions }
- { name: btree_gist ,schema : extensions }
- { name: btree_gin ,schema : extensions }
- { name: pg_trgm ,schema : extensions }
- { name: intagg ,schema : extensions }
- { name: intarray ,schema : extensions }
- { name: pg_repack ,schema : extensions }
#----------------------------------------------#
# BACKUP : https://pigsty.io/docs/pgsql/backup
#----------------------------------------------#
minio_endpoint : https://sss.pigsty:9000 # explicit overwrite minio endpoint with haproxy port
pgbackrest_method: minio # pgbackrest repo method : local,minio,[user-defined...]
pgbackrest_repo: # pgbackrest repo : https://pgbackrest.org/configuration.html#section-repository
local : # default pgbackrest repo with local posix fs
path : /pg/backup # local backup directory, `/pg/backup` by default
retention_full_type : count # retention full backups by count
retention_full : 2 # keep 2, at most 3 full backups when using local fs repo
minio : # optional minio repo for pgbackrest
type : s3 # minio is s3-compatible, so s3 is used
s3_endpoint : sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
s3_region : us-east-1 # minio region, us-east-1 by default, useless for minio
s3_bucket : pgsql # minio bucket name, `pgsql` by default
s3_key : pgbackrest # minio user access key for pgbackrest
s3_key_secret : S3User.Backup # minio user secret key for pgbackrest <------------------ HEY, DID YOU CHANGE THIS?
s3_uri_style : path # use path style uri for minio rather than host style
path : /pgbackrest # minio backup path, default is `/pgbackrest`
storage_port : 9000 # minio port, 9000 by default
storage_ca_file : /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
block : y # Enable block incremental backup
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest' <----- HEY, DID YOU CHANGE THIS?
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for the last 14 days
s3 : # you can use cloud object storage as backup repo
type : s3 # Add your object storage credentials here!
s3_endpoint : oss-cn-beijing-internal.aliyuncs.com
s3_region : oss-cn-beijing
s3_bucket : <your_bucket_name>
s3_key : <your_access_key>
s3_key_secret : <your_secret_key>
s3_uri_style : host
path : /pgbackrest
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for the last 14 days
#----------------------------------------------#
# 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
...
安装过程
配置解读 supabase 模板提供了完整的 Supabase 自建方案,让您可以在自己的基础设施上运行这个开源 Firebase 替代品。
架构组成 :
PostgreSQL :Pigsty 托管的生产级 PostgreSQL(支持高可用)Docker 容器 :Supabase 无状态服务(Auth、Storage、Realtime、Edge Functions 等)MinIO :S3 兼容的对象存储,用于文件存储和 PostgreSQL 备份Nginx :反向代理和 HTTPS 终止关键特性 :
使用 Pigsty 管理的 PostgreSQL 替代 Supabase 自带的数据库容器 支持 PostgreSQL 高可用(可扩展为三节点集群) 安装全部 Supabase 所需扩展(pg_net、pgjwt、pg_graphql、vector 等) 集成 MinIO 对象存储用于文件上传和备份 支持 HTTPS 和 Let’s Encrypt 自动证书 部署步骤 :
curl https://repo.pigsty.io/get | bash # 下载 Pigsty
./configure -c supabase # 使用 supabase 配置模板
./deploy.yml # 安装 Pigsty、PostgreSQL、MinIO
./docker.yml # 安装 Docker
./app.yml # 启动 Supabase 容器
访问方式 :
# Supabase Studio
https://supa.pigsty ( 用户名: supabase, 密码: pigsty)
# 直接连接 PostgreSQL
psql postgres://supabase_admin:DBUser.Supa@10.10.10.10:5432/postgres
适用场景 :
需要自建 BaaS (Backend as a Service) 平台 希望完全掌控数据和基础设施 需要企业级 PostgreSQL 高可用和备份 对 Supabase 云服务有合规或成本考虑 注意事项 :
必须修改 JWT_SECRET :使用至少 32 字符的随机字符串,并重新生成 ANON_KEY 和 SERVICE_ROLE_KEY需要配置正确的域名(SITE_URL、API_EXTERNAL_URL) 生产环境建议启用 HTTPS(可使用 certbot 自动签发证书) Docker 网络需要能访问 PostgreSQL(已配置 172.17.0.0/16 HBA 规则) 9.22 - ha/citus 13 节点 Citus 分布式 PostgreSQL 集群,1 协调组 + 5 工作组高可用配置,提供水平扩展与分片能力
ha/citus 配置模板部署一套完整的 Citus 分布式 PostgreSQL 集群 ,包含 1 个基础设施节点、1 组协调节点和 5 组工作节点(共 12 个 Citus 节点),提供透明的水平扩展与数据分片能力。
配置概览 配置名称: ha/citus 节点数量: 13 节点(1 基础设施 + 1 协调组 × 2 + 5 工作组 × 2) 配置说明:Citus 分布式 PostgreSQL 高可用集群 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64 相关配置:meta ,ha/trio 启用方式:
备注:这是一个 13 节点模板,您需要在生成配置后修改各节点的 IP 地址
配置内容 源文件地址:pigsty/conf/ha/citus.yml
---
#==============================================================#
# File : citus.yml
# Desc : 13-node Citus (6-group Distributive) Config Template
# Ctime : 2020-05-22
# Mtime : 2025-01-20
# Docs : https://pigsty.io/docs/conf/citus
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# This is the config template for Citus Distributive Cluster
# tutorial: https://pigsty.io/docs/pgsql/kernel/citus
# we will use the local repo for cluster bootstrapping
#
# Topology:
# - pg-citus0: coordinator (10.10.10.10) VIP: 10.10.10.19
# - pg-citus1: worker group 1 (10.10.10.21, 22) VIP: 10.10.10.29
# - pg-citus2: worker group 2 (10.10.10.31, 32) VIP: 10.10.10.39
# - pg-citus3: worker group 3 (10.10.10.41, 42) VIP: 10.10.10.49
# - pg-citus4: worker group 4 (10.10.10.51, 52) VIP: 10.10.10.59
# - pg-citus5: worker group 5 (10.10.10.61, 62) VIP: 10.10.10.69
# - pg-citus6: worker group 6 (10.10.10.71, 72) VIP: 10.10.10.79
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c citus
# ./deploy.yml
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_users :
- { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles: [dbrole_admin ] ,comment : pigsty admin user }
pg_databases :
- name : meta
baseline : cmdb.sql
comment : "pigsty meta database"
schemas : [ pigsty]
extensions : [ postgis, vector ]
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every day 1am
#----------------------------------------------------------#
# pg-citus: 6 cluster groups, 12 nodes total
#----------------------------------------------------------#
pg-citus :
hosts :
# coordinator (group 0) on infra node
10.10.10.21 : { pg_group: 0, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.29/24 ,pg_seq: 1, pg_role : primary }
10.10.10.22 : { pg_group: 0, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.29/24 ,pg_seq: 2, pg_role : replica }
# worker group 2
10.10.10.31 : { pg_group: 1, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.39/24 ,pg_seq: 1, pg_role : primary }
10.10.10.32 : { pg_group: 1, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.39/24 ,pg_seq: 2, pg_role : replica }
# worker group 3
10.10.10.41 : { pg_group: 2, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.49/24 ,pg_seq: 1, pg_role : primary }
10.10.10.42 : { pg_group: 2, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.49/24 ,pg_seq: 2, pg_role : replica }
# worker group 4
10.10.10.51 : { pg_group: 3, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.59/24 ,pg_seq: 1, pg_role : primary }
10.10.10.52 : { pg_group: 3, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.59/24 ,pg_seq: 2, pg_role : replica }
# worker group 5
10.10.10.61 : { pg_group: 4, pg_cluster: pg-citus5 ,pg_vip_address: 10.10.10.69/24 ,pg_seq: 1, pg_role : primary }
10.10.10.62 : { pg_group: 4, pg_cluster: pg-citus5 ,pg_vip_address: 10.10.10.69/24 ,pg_seq: 2, pg_role : replica }
# worker group 6
10.10.10.71 : { pg_group: 5, pg_cluster: pg-citus6 ,pg_vip_address: 10.10.10.79/24 ,pg_seq: 1, pg_role : primary }
10.10.10.72 : { pg_group: 5, pg_cluster: pg-citus6 ,pg_vip_address: 10.10.10.79/24 ,pg_seq: 2, pg_role : replica }
vars :
pg_mode: citus # pgsql cluster mode : citus
pg_shard: pg-citus # citus shard name : pg-citus
pg_primary_db : citus # primary database used by citus
pg_dbsu_password : DBUser.Postgres # enable dbsu password access for citus
pg_extensions : [ citus, postgis, pgvector, topn, pg_cron, hll ]
pg_libs : 'citus, pg_cron, pg_stat_statements'
pg_users : [ { name: dbuser_citus ,password: DBUser.Citus ,pgbouncer: true ,roles : [ dbrole_admin ] }]
pg_databases : [ { name: citus ,owner: dbuser_citus ,extensions : [ citus, vector, topn, pg_cron, hll ] }]
pg_parameters :
cron.database_name : citus
citus.node_conninfo : 'sslrootcert=/pg/cert/ca.crt sslmode=verify-full'
pg_hba_rules :
- { user: 'all' ,db: all ,addr: 127.0.0.1/32 ,auth: ssl ,title : 'all user ssl access from localhost' }
- { user: 'all' ,db: all ,addr: intra ,auth: ssl ,title : 'all user ssl access from intranet' }
pg_vip_enabled : true
pg_vip_interface : eth1
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every day 1am
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0
admin_ip : 10.10.10.10
region : default
infra_portal :
home : { domain : i.pigsty }
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
nodename_overwrite : true
node_repo_modules : node,infra,pgsql
node_tune : oltp
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # PostgreSQL 14-18
pg_conf : oltp.yml
pg_packages : [ pgsql-main, pgsql-common ]
#----------------------------------------------#
# 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
...
集群拓扑 此配置部署一套完整的 Citus 分布式集群,拓扑结构如下:
集群 节点 IP 地址 VIP 角色 pg-meta 1 10.10.10.10 - 基础设施 + CMDB pg-citus1 2 10.10.10.21, 22 10.10.10.29 协调节点(group 0) pg-citus2 2 10.10.10.31, 32 10.10.10.39 工作节点(group 1) pg-citus3 2 10.10.10.41, 42 10.10.10.49 工作节点(group 2) pg-citus4 2 10.10.10.51, 52 10.10.10.59 工作节点(group 3) pg-citus5 2 10.10.10.61, 62 10.10.10.69 工作节点(group 4) pg-citus6 2 10.10.10.71, 72 10.10.10.79 工作节点(group 5)
架构说明 :
pg-meta :基础设施节点,运行 Grafana、Prometheus、etcd 等监控组件,同时部署一个独立的 CMDB 数据库pg-citus1 :Citus 协调节点(group 0),负责接收客户端查询并路由到工作节点,1 主 1 从高可用配置pg-citus2~6 :Citus 工作节点(group 1~5),存储分片数据,每组 1 主 1 从,通过 Patroni 实现自动故障转移VIP :每个节点组配置 L2 VIP,由 vip-manager 管理,确保故障转移时客户端连接自动切换配置解读 ha/citus 模板部署生产级 Citus 分布式集群,适合需要水平扩展的大规模数据场景。
关键特性 :
水平扩展 :5 个工作组可线性扩展存储和计算能力高可用 :每个工作组 1 主 1 从,支持自动故障转移L2 VIP :每组配置虚拟 IP,故障切换对应用透明SSL 加密 :节点间通信使用 SSL 证书加密透明分片 :数据自动分布到多个工作节点预装扩展 :
pg_extensions : [ citus, postgis, pgvector, topn, pg_cron, hll ]
pg_libs : 'citus, pg_cron, pg_stat_statements'
安全配置 :
启用 pg_dbsu_password,允许超级用户密码访问(Citus 节点间通信需要) HBA 规则要求所有连接使用 SSL 认证 节点间使用证书验证:sslmode=verify-full 部署步骤 # 1. 下载 Pigsty
curl https://repo.pigsty.io/get | bash
# 2. 使用 ha/citus 配置模板
./configure -c ha/citus
# 3. 修改 IP 地址和密码
vi pigsty.yml
# 4. 部署完整集群
./deploy.yml
部署完成后,Citus 会自动注册所有工作节点。可通过以下命令验证:
-- 连接到任意协调节点
psql - h 10 . 10 . 10 . 29 - U dbuser_citus - d citus
-- 查看工作节点状态
SELECT * FROM citus_get_active_worker_nodes ();
-- 查看分片分布
SELECT * FROM citus_shards ;
使用示例 创建分布式表 :
-- 创建表
CREATE TABLE events (
tenant_id INT ,
event_id BIGSERIAL ,
event_time TIMESTAMPTZ DEFAULT now (),
payload JSONB ,
PRIMARY KEY ( tenant_id , event_id )
);
-- 按 tenant_id 分片
SELECT create_distributed_table ( 'events' , 'tenant_id' );
-- 插入数据(自动路由到对应分片)
INSERT INTO events ( tenant_id , payload )
VALUES ( 1 , '{"type": "click"}' );
-- 查询(自动并行执行)
SELECT tenant_id , count ( * )
FROM events
GROUP BY tenant_id ;
创建引用表 (小表复制到所有节点):
CREATE TABLE tenants (
tenant_id INT PRIMARY KEY ,
name TEXT
);
SELECT create_reference_table ( 'tenants' );
适用场景 多租户 SaaS :按租户 ID 分片,实现租户数据隔离和并行查询实时分析 :大规模事件数据的实时聚合分析时序数据 :结合 TimescaleDB 处理海量时序数据水平扩展 :单表数据量超过单机容量时的扩展方案注意事项 PostgreSQL 版本 :Citus 支持 PostgreSQL 14~18,此模板默认使用 PG18分布列选择 :合理选择分布列(通常是租户 ID 或时间戳)对性能至关重要跨分片限制 :外键约束必须包含分布列,部分 DDL 操作有限制网络要求 :需要配置正确的 pg_vip_interface(默认 eth1)架构限制 :Citus 扩展不支持 ARM64 架构
9.23 - 高可用模板 9.24 - ha/simu 20 节点生产环境仿真配置,用于大规模部署测试
ha/simu 配置模板是一个 20 节点的生产环境仿真配置,需要强大的宿主机方可运行。
配置概览 配置名称: ha/simu 节点数量: 20 节点,pigsty/vagrant/spec/simu.rb 配置说明:20 节点的生产环境仿真配置,需要强大的宿主机方可运行。 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 启用方式:
./configure -c ha/simu [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/ha/simu.yml
---
#==============================================================#
# File : simu.yml
# Desc : Pigsty Simubox: a 20 node prod simulation env
# Ctime : 2023-07-20
# Mtime : 2026-01-19
# Docs : https://pigsty.io/docs/conf/simu
# License : Apache-2.0 @ https://pigsty.io/docs/about/license
# Copyright : 2018-2025 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
all :
children :
#==========================================================#
# infra: 3 nodes
#==========================================================#
# ./infra.yml -l infra
# ./docker.yml -l infra (optional)
infra :
hosts :
10.10.10.10 : { infra_seq : 1 }
10.10.10.11 : { infra_seq: 2, repo_enabled : false }
10.10.10.12 : { infra_seq: 3, repo_enabled : false }
vars :
docker_enabled : true
node_tune : oltp # use oltp template for infra nodes
pg_conf : oltp.yml # use oltp template for infra pgsql
pg_exporters : # bin/pgmon-add pg-meta2/pg-src2/pg-dst2
20001 : {pg_cluster: pg-meta2 ,pg_seq: 1 ,pg_host: 10.10.10.10, pg_databases : [ { name : meta }]}
20002 : {pg_cluster: pg-meta2 ,pg_seq: 2 ,pg_host: 10.10.10.11, pg_databases : [ { name : meta }]}
20003 : {pg_cluster: pg-meta2 ,pg_seq: 3 ,pg_host: 10.10.10.12, pg_databases : [ { name : meta }]}
20004 : {pg_cluster: pg-src2 ,pg_seq: 1 ,pg_host: 10.10.10.31, pg_databases : [ { name : src }]}
20005 : {pg_cluster: pg-src2 ,pg_seq: 2 ,pg_host: 10.10.10.32, pg_databases : [ { name : src }]}
20006 : {pg_cluster: pg-src2 ,pg_seq: 3 ,pg_host: 10.10.10.33, pg_databases : [ { name : src }]}
20007 : {pg_cluster: pg-dst2 ,pg_seq: 1 ,pg_host: 10.10.10.41, pg_databases : [ { name : dst }]}
20008 : {pg_cluster: pg-dst2 ,pg_seq: 2 ,pg_host: 10.10.10.42, pg_databases : [ { name : dst }]}
20009 : {pg_cluster: pg-dst2 ,pg_seq: 3 ,pg_host: 10.10.10.43, pg_databases : [ { name : dst }]}
#==========================================================#
# etcd: 5 nodes dedicated etcd cluster
#==========================================================#
# ./etcd.yml -l etcd;
etcd :
hosts :
10.10.10.25 : { etcd_seq : 1 }
10.10.10.26 : { etcd_seq : 2 }
10.10.10.27 : { etcd_seq : 3 }
10.10.10.28 : { etcd_seq : 4 }
10.10.10.29 : { etcd_seq : 5 }
vars :
etcd_cluster : etcd
#==========================================================#
# minio: 4 nodes dedicated minio cluster
#==========================================================#
# ./minio.yml -l minio;
minio :
hosts :
10.10.10.21 : { minio_seq : 1 }
10.10.10.22 : { minio_seq : 2 }
10.10.10.23 : { minio_seq : 3 }
10.10.10.24 : { minio_seq : 4 }
vars :
minio_cluster : minio
minio_data : '/data{1...4}' # 4 node x 4 disk
minio_users : # list of minio user to be created
- { access_key: pgbackrest ,secret_key: S3User.Backup ,policy : pgsql }
- { access_key: s3user_meta ,secret_key: S3User.Meta ,policy : meta }
- { access_key: s3user_data ,secret_key: S3User.Data ,policy : data }
#==========================================================#
# proxy: 2 nodes used as dedicated haproxy server
#==========================================================#
# ./node.yml -l proxy
proxy :
hosts :
10.10.10.18 : { vip_role : master }
10.10.10.19 : { vip_role : backup }
vars :
vip_enabled : true
vip_address : 10.10.10.20
vip_vrid : 20
vip_interface : eth1
haproxy_services: # expose minio service : sss.pigsty:9000
- name : minio # [REQUIRED] service name, unique
port : 9000 # [REQUIRED] service port, unique
balance : leastconn # Use leastconn algorithm and minio health check
options : [ "option httpchk" , "option http-keep-alive" , "http-check send meth OPTIONS uri /minio/health/live" , "http-check expect status 200" ]
servers : # reload service with ./node.yml -t haproxy_config,haproxy_reload
- { name: minio-1 ,ip: 10.10.10.21 ,port: 9000 ,options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
- { name: minio-2 ,ip: 10.10.10.22 ,port: 9000 ,options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
- { name: minio-3 ,ip: 10.10.10.23 ,port: 9000 ,options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
- { name: minio-4 ,ip: 10.10.10.24 ,port: 9000 ,options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
#==========================================================#
# pg-meta: reuse infra node as meta cmdb
#==========================================================#
# ./pgsql.yml -l pg-meta
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_vip_enabled : true
pg_vip_address : 10.10.10.2 /24
pg_vip_interface : eth1
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 for meta database }
- {name: dbuser_grafana ,password: DBUser.Grafana ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for grafana database }
- {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for bytebase database }
- {name: dbuser_kong ,password: DBUser.Kong ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for kong api gateway }
- {name: dbuser_gitea ,password: DBUser.Gitea ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for gitea service }
- {name: dbuser_wiki ,password: DBUser.Wiki ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for wiki.js service }
- {name: dbuser_noco ,password: DBUser.Noco ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for nocodb service }
pg_databases :
- { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions : [ {name : vector}]}
- { name: grafana ,owner: dbuser_grafana ,revokeconn: true ,comment : grafana primary database }
- { name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment : bytebase primary database }
- { name: kong ,owner: dbuser_kong ,revokeconn: true ,comment : kong the api gateway database }
- { name: gitea ,owner: dbuser_gitea ,revokeconn: true ,comment : gitea meta database }
- { name: wiki ,owner: dbuser_wiki ,revokeconn: true ,comment : wiki meta database }
- { name: noco ,owner: dbuser_noco ,revokeconn: true ,comment : nocodb database }
pg_libs : 'pg_stat_statements, auto_explain' # add timescaledb to shared_preload_libraries
#==========================================================#
# pg-src: dedicate 3 node source cluster
#==========================================================#
# ./pgsql.yml -l pg-src
pg-src :
hosts :
10.10.10.31 : { pg_seq: 1, pg_role : primary }
10.10.10.32 : { pg_seq: 2, pg_role : replica }
10.10.10.33 : { pg_seq: 3, pg_role : replica }
vars :
pg_cluster : pg-src
pg_vip_enabled : true
pg_vip_address : 10.10.10.3 /24
pg_vip_interface : eth1
pg_users : [ { name: test , password: test , pgbouncer: true , roles : [ dbrole_admin ] }]
pg_databases : [ { name : src }]
#==========================================================#
# pg-dst: dedicate 3 node destination cluster
#==========================================================#
# ./pgsql.yml -l pg-dst
pg-dst :
hosts :
10.10.10.41 : { pg_seq: 1, pg_role : primary }
10.10.10.42 : { pg_seq: 2, pg_role : replica }
10.10.10.43 : { pg_seq: 3, pg_role : replica }
vars :
pg_cluster : pg-dst
pg_vip_enabled : true
pg_vip_address : 10.10.10.4 /24
pg_vip_interface : eth1
pg_users : [ { name: test , password: test , pgbouncer: true , roles : [ dbrole_admin ] } ]
pg_databases : [ { name : dst } ]
#==========================================================#
# redis-meta: reuse the 5 etcd nodes as redis sentinel
#==========================================================#
# ./redis.yml -l redis-meta
redis-meta :
hosts :
10.10.10.25 : { redis_node: 1 , redis_instances : { 26379 : {} } }
10.10.10.26 : { redis_node: 2 , redis_instances : { 26379 : {} } }
10.10.10.27 : { redis_node: 3 , redis_instances : { 26379 : {} } }
10.10.10.28 : { redis_node: 4 , redis_instances : { 26379 : {} } }
10.10.10.29 : { redis_node: 5 , redis_instances : { 26379 : {} } }
vars :
redis_cluster : redis-meta
redis_password : 'redis.meta'
redis_mode : sentinel
redis_max_memory : 256MB
redis_sentinel_monitor : # primary list for redis sentinel, use cls as name, primary ip:port
- { name: redis-src, host: 10.10.10.31, port: 6379 ,password: redis.src, quorum : 1 }
- { name: redis-dst, host: 10.10.10.41, port: 6379 ,password: redis.dst, quorum : 1 }
#==========================================================#
# redis-src: reuse pg-src 3 nodes for redis
#==========================================================#
# ./redis.yml -l redis-src
redis-src :
hosts :
10.10.10.31 : { redis_node: 1 , redis_instances : {6379 : { } }}
10.10.10.32 : { redis_node: 2 , redis_instances : {6379 : { replica_of: '10.10.10.31 6379' }, 6380 : { replica_of : '10.10.10.32 6379' } }}
10.10.10.33 : { redis_node: 3 , redis_instances : {6379 : { replica_of: '10.10.10.31 6379' }, 6380 : { replica_of : '10.10.10.33 6379' } }}
vars :
redis_cluster : redis-src
redis_password : 'redis.src'
redis_max_memory : 64MB
#==========================================================#
# redis-dst: reuse pg-dst 3 nodes for redis
#==========================================================#
# ./redis.yml -l redis-dst
redis-dst :
hosts :
10.10.10.41 : { redis_node: 1 , redis_instances : {6379 : { } }}
10.10.10.42 : { redis_node: 2 , redis_instances : {6379 : { replica_of : '10.10.10.41 6379' } }}
10.10.10.43 : { redis_node: 3 , redis_instances : {6379 : { replica_of : '10.10.10.41 6379' } }}
vars :
redis_cluster : redis-dst
redis_password : 'redis.dst'
redis_max_memory : 64MB
#==========================================================#
# pg-tmp: reuse proxy nodes as pgsql cluster
#==========================================================#
# ./pgsql.yml -l pg-tmp
pg-tmp :
hosts :
10.10.10.18 : { pg_seq: 1 ,pg_role : primary }
10.10.10.19 : { pg_seq: 2 ,pg_role : replica }
vars :
pg_cluster : pg-tmp
pg_users : [ { name: test , password: test , pgbouncer: true , roles : [ dbrole_admin ] } ]
pg_databases : [ { name : tmp } ]
#==========================================================#
# pg-etcd: reuse etcd nodes as pgsql cluster
#==========================================================#
# ./pgsql.yml -l pg-etcd
pg-etcd :
hosts :
10.10.10.25 : { pg_seq: 1 ,pg_role : primary }
10.10.10.26 : { pg_seq: 2 ,pg_role : replica }
10.10.10.27 : { pg_seq: 3 ,pg_role : replica }
10.10.10.28 : { pg_seq: 4 ,pg_role : replica }
10.10.10.29 : { pg_seq: 5 ,pg_role : offline }
vars :
pg_cluster : pg-etcd
pg_users : [ { name: test , password: test , pgbouncer: true , roles : [ dbrole_admin ] } ]
pg_databases : [ { name : etcd } ]
#==========================================================#
# pg-minio: reuse minio nodes as pgsql cluster
#==========================================================#
# ./pgsql.yml -l pg-minio
pg-minio :
hosts :
10.10.10.21 : { pg_seq: 1 ,pg_role : primary }
10.10.10.22 : { pg_seq: 2 ,pg_role : replica }
10.10.10.23 : { pg_seq: 3 ,pg_role : replica }
10.10.10.24 : { pg_seq: 4 ,pg_role : replica }
vars :
pg_cluster : pg-minio
pg_users : [ { name: test , password: test , pgbouncer: true , roles : [ dbrole_admin ] } ]
pg_databases : [ { name : minio } ]
#==========================================================#
# ferret: reuse pg-src as mongo (ferretdb)
#==========================================================#
# ./mongo.yml -l ferret
ferret :
hosts :
10.10.10.31 : { mongo_seq : 1 }
10.10.10.32 : { mongo_seq : 2 }
10.10.10.33 : { mongo_seq : 3 }
vars :
mongo_cluster : ferret
mongo_pgurl : 'postgres://test:test@10.10.10.31:5432/src'
#============================================================#
# Global Variables
#============================================================#
vars :
#==========================================================#
# INFRA
#==========================================================#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
minio : { domain: m.pigsty ,endpoint : "10.10.10.21:9001" ,scheme: https ,websocket : true }
postgrest : { domain: api.pigsty ,endpoint : "127.0.0.1:8884" }
pgadmin : { domain: adm.pigsty ,endpoint : "127.0.0.1:8885" }
pgweb : { domain: cli.pigsty ,endpoint : "127.0.0.1:8886" }
bytebase : { domain: ddl.pigsty ,endpoint : "127.0.0.1:8887" }
jupyter : { domain: lab.pigsty ,endpoint : "127.0.0.1:8888" , websocket : true }
supa : { domain: supa.pigsty ,endpoint : "10.10.10.10:8000" , websocket : true }
#==========================================================#
# NODE
#==========================================================#
node_id_from_pg : true # use nodename rather than pg identity as hostname
node_tune : tiny # use small node template
node_firewall_mode: zone # default : trust intranet, expose selected public ports
node_timezone : Asia/Hong_Kong # use Asia/Hong_Kong Timezone
node_dns_servers : # DNS servers in /etc/resolv.conf
- 10.10.10.10
- 10.10.10.11
node_etc_hosts :
- 10.10.10.10 i.pigsty
- 10.10.10.20 sss.pigsty # point minio service domain to the L2 VIP of proxy cluster
node_ntp_servers : # NTP servers in /etc/chrony.conf
- pool cn.pool.ntp.org iburst
- pool 10.10.10.10 iburst
node_admin_ssh_exchange : false # exchange admin ssh key among node cluster
#==========================================================#
# PGSQL
#==========================================================#
pg_conf : tiny.yml
pgbackrest_method : minio # USE THE HA MINIO THROUGH A LOAD BALANCER
pg_dbsu_ssh_exchange : false # do not exchange dbsu ssh key among pgsql cluster
pgbackrest_repo: # pgbackrest repo : https://pgbackrest.org/configuration.html#section-repository
local : # default pgbackrest repo with local posix fs
path : /pg/backup # local backup directory, `/pg/backup` by default
retention_full_type : count # retention full backups by count
retention_full : 2 # keep 2, at most 3 full backup when using local fs repo
minio : # optional minio repo for pgbackrest
type : s3 # minio is s3-compatible, so s3 is used
s3_endpoint : sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
s3_region : us-east-1 # minio region, us-east-1 by default, useless for minio
s3_bucket : pgsql # minio bucket name, `pgsql` by default
s3_key : pgbackrest # minio user access key for pgbackrest
s3_key_secret : S3User.Backup # minio user secret key for pgbackrest
s3_uri_style : path # use path style uri for minio rather than host style
path : /pgbackrest # minio backup path, default is `//pgbackrest`
storage_port : 9000 # minio port, 9000 by default
storage_ca_file : /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
block : y # Enable block incremental backup
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for last 14 days
pg_crontab : # make a full backup on monday 1am, and an incremental backup during weekdays
- '00 01 * * * /pg/bin/pg-backup'
- '00 05 * * * /pg/bin/pg-vacuum'
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 }
#==========================================================#
# Repo
#==========================================================#
repo_packages : [
node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-utility, extra-modules,
pg18-core ,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
...
配置解读 ha/simu 模板是一个 大规模生产环境仿真配置 ,用于测试和验证复杂场景。
架构组成 :
2 节点高可用 INFRA(监控/告警/Nginx/DNS) 5 节点高可用 ETCD 和 MinIO(多磁盘) 2 节点 Proxy(HAProxy + Keepalived VIP) 多套 PostgreSQL 集群:pg-meta:2 节点高可用 pg-v14~v18:单节点多版本测试 pg-pitr:单节点 PITR 测试 pg-test:4 节点高可用 pg-src/pg-dst:3+2 节点复制测试 pg-citus:10 节点分布式集群 多种 Redis 模式:主从、哨兵、集群 适用场景 :
大规模部署测试与验证 高可用故障演练 性能基准测试 新功能预览与评估 注意事项 :
需要强大的宿主机(推荐 64GB+ 内存) 使用 Vagrant 虚拟机模拟 9.25 - ha/full 四节点完整功能演示环境,带有两套 PostgreSQL 集群、MinIO、Redis 等组件示例
ha/full 配置模板是 Pigsty 推荐的沙箱演示环境,使用四个节点部署两套 PostgreSQL 集群,用于测试和演示 Pigsty 各方面的能力。
Pigsty 大部分教程和示例都基于此模板的沙箱环境。
配置概览 配置名称: ha/full 节点数量: 四节点 配置说明:四节点完整功能演示环境,带有两套 PostgreSQL 集群、MinIO、Redis 等组件示例 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:ha/trio ,ha/safe ,demo/demo 启用方式:
./configure -c ha/full [ -i <primary_ip>]
配置生成后,需要修改其他三个节点的 IP 地址。
配置内容 源文件地址:pigsty/conf/ha/full.yml
---
#==============================================================#
# File : full.yml
# Desc : Pigsty Local Sandbox 4-node Demo Config
# Ctime : 2020-05-22
# Mtime : 2026-01-16
# Docs : https://pigsty.io/docs/conf/full
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
all :
#==============================================================#
# Clusters, Nodes, and Modules
#==============================================================#
children :
# infra: monitor, alert, repo, etc..
infra :
hosts :
10.10.10.10 : { infra_seq : 1 }
vars :
docker_enabled : true # enabled docker with ./docker.yml
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
#repo_extra_packages: [ pg18-main ,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]
# etcd cluster for HA postgres DCS
etcd :
hosts :
10.10.10.10 : { etcd_seq : 1 }
vars :
etcd_cluster : etcd
# minio (single node, used as backup repo)
minio :
hosts :
10.10.10.10 : { minio_seq : 1 }
vars :
minio_cluster : minio
minio_users : # list of minio user to be created
- { access_key: pgbackrest ,secret_key: S3User.Backup ,policy : pgsql }
- { access_key: s3user_meta ,secret_key: S3User.Meta ,policy : meta }
- { access_key: s3user_data ,secret_key: S3User.Data ,policy : data }
# postgres cluster: pg-meta
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 : pigsty admin user }
- { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [ dbrole_readonly ] ,comment : read-only viewer for meta database }
pg_databases :
- { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas : [ pigsty ] }
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'
pg_vip_enabled : true
pg_vip_address : 10.10.10.2 /24
pg_vip_interface : eth1
# pgsql 3 node ha cluster: pg-test
pg-test :
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary } # primary instance, leader of cluster
10.10.10.12 : { pg_seq: 2, pg_role : replica } # replica instance, follower of leader
10.10.10.13 : { pg_seq: 3, pg_role: replica, pg_offline_query : true } # replica with offline access
vars :
pg_cluster : pg-test # define pgsql cluster name
pg_users : [ { name: test , password: test , pgbouncer: true , roles : [ dbrole_admin ] }]
pg_databases : [ { name : test }]
pg_vip_enabled : true
pg_vip_address : 10.10.10.3 /24
pg_vip_interface : eth1
pg_crontab : # make a full backup on monday 1am, and an incremental backup during weekdays
- '00 01 * * 1 /pg/bin/pg-backup full'
- '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup'
#----------------------------------#
# redis ms, sentinel, native cluster
#----------------------------------#
redis-ms : # redis classic primary & replica
hosts : { 10.10.10.10 : { redis_node: 1 , redis_instances : { 6379 : { }, 6380 : { replica_of : '10.10.10.10 6379' } } } }
vars : { redis_cluster: redis-ms ,redis_password: 'redis.ms' ,redis_max_memory : 64MB }
redis-meta : # redis sentinel x 3
hosts : { 10.10.10.11 : { redis_node: 1 , redis_instances : { 26379 : { } ,26380 : { } ,26381 : { } } } }
vars :
redis_cluster : redis-meta
redis_password : 'redis.meta'
redis_mode : sentinel
redis_max_memory : 16MB
redis_sentinel_monitor : # primary list for redis sentinel, use cls as name, primary ip:port
- { name: redis-ms, host: 10.10.10.10, port: 6379 ,password: redis.ms, quorum : 2 }
redis-test: # redis native cluster : 3m x 3s
hosts :
10.10.10.12 : { redis_node: 1 ,redis_instances : { 6379 : { } ,6380 : { } ,6381 : { } } }
10.10.10.13 : { redis_node: 2 ,redis_instances : { 6379 : { } ,6380 : { } ,6381 : { } } }
vars : { redis_cluster: redis-test ,redis_password: 'redis.test' ,redis_mode: cluster, redis_max_memory : 32MB }
#==============================================================#
# Global Parameters
#==============================================================#
vars :
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
#minio : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
#----------------------------------#
# MinIO Related Options
#----------------------------------#
node_etc_hosts : [ '${admin_ip} i.pigsty sss.pigsty' ]
pgbackrest_method : minio # if you want to use minio as backup repo instead of 'local' fs, uncomment this
pgbackrest_repo: # pgbackrest repo : https://pgbackrest.org/configuration.html#section-repository
local : # default pgbackrest repo with local posix fs
path : /pg/backup # local backup directory, `/pg/backup` by default
retention_full_type : count # retention full backups by count
retention_full : 2 # keep 2, at most 3 full backup when using local fs repo
minio : # optional minio repo for pgbackrest
type : s3 # minio is s3-compatible, so s3 is used
s3_endpoint : sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
s3_region : us-east-1 # minio region, us-east-1 by default, useless for minio
s3_bucket : pgsql # minio bucket name, `pgsql` by default
s3_key : pgbackrest # minio user access key for pgbackrest
s3_key_secret : S3User.Backup # minio user secret key for pgbackrest
s3_uri_style : path # use path style uri for minio rather than host style
path : /pgbackrest # minio backup path, default is `/pgbackrest`
storage_port : 9000 # minio port, 9000 by default
storage_ca_file : /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
block : y # Enable block incremental backup
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for last 14 days
#----------------------------------#
# Repo, Node, Packages
#----------------------------------#
repo_remove : true # remove existing repo on admin node during repo bootstrap
node_repo_remove : true # remove existing node repo for node managed by pigsty
repo_extra_packages : [ pg18-main ] #,pg18-core ,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]
pg_version : 18 # default postgres version
#pg_extensions: [pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl ,pg18-olap]
#----------------------------------------------#
# 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
...
配置解读 ha/full 模板是 Pigsty 的 完整功能演示配置 ,展示了多种组件的协同工作。
组件概览 :
组件 节点分布 说明 INFRA 节点1 监控/告警/Nginx/DNS ETCD 节点1 DCS 服务 MinIO 节点1 S3 兼容存储 pg-meta 节点1 单节点 PostgreSQL pg-test 节点2-4 三节点高可用 PostgreSQL redis-ms 节点1 Redis 主从模式 redis-meta 节点2 Redis 哨兵模式 redis-test 节点3-4 Redis 原生集群模式
适用场景 :
Pigsty 功能演示与学习 开发测试环境 评估高可用架构 Redis 不同模式对比测试 与 ha/trio 的区别 :
增加了第二套 PostgreSQL 集群(pg-test) 增加了三种模式的 Redis 集群示例 基础设施使用单节点(而非三节点) 注意事项 :
9.26 - ha/safe 安全加固的高可用配置模板,采用高标准的安全最佳实践
ha/safe 配置模板基于 ha/trio 模板修改,是一个安全加固的专用配置模板,采用高标准的安全最佳实践。
配置概览 配置名称: ha/safe 节点数量: 三节点(可选添加延迟副本) 配置说明:安全加固的高可用配置模板,采用高标准的安全最佳实践 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64(部分安全扩展在 ARM64 不可用) 相关配置:ha/trio ,ha/full 启用方式:
./configure -c ha/safe [ -i <primary_ip>]
安全加固措施 ha/safe 模板实现了以下安全加固:
强制 SSL 加密 :PostgreSQL 和 PgBouncer 均启用 SSL强密码策略 :使用 passwordcheck 扩展强制密码复杂度用户过期时间 :所有用户设置 20 年过期时间最小化连接范围 :限制 PostgreSQL/Patroni/PgBouncer 监听地址严格 HBA 规则 :强制 SSL 认证,管理员需证书认证审计日志 :记录连接和断开事件延迟副本 :可选的 1 小时延迟副本,用于误操作恢复关键模板 :使用 crit.yml 调优模板,零数据丢失配置内容 源文件地址:pigsty/conf/ha/safe.yml
---
#==============================================================#
# File : safe.yml
# Desc : Pigsty 3-node security enhance template
# Ctime : 2020-05-22
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/conf/safe
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
#===== SECURITY ENHANCEMENT CONFIG TEMPLATE WITH 3 NODES ======#
# * 3 infra nodes, 3 etcd nodes, single minio node
# * 3-instance pgsql cluster with an extra delayed instance
# * crit.yml templates, no data loss, checksum enforced
# * enforce ssl on postgres & pgbouncer, use postgres by default
# * enforce an expiration date for all users (20 years by default)
# * enforce strong password policy with passwordcheck extension
# * enforce changing default password for all users
# * log connections and disconnections
# * restrict listen ip address for postgres/patroni/pgbouncer
all :
children :
infra : # infra cluster for proxy, monitor, alert, etc
hosts : # 1 for common usage, 3 nodes for production
10.10.10.10 : { infra_seq : 1 } # identity required
10.10.10.11 : { infra_seq: 2, repo_enabled : false }
10.10.10.12 : { infra_seq: 3, repo_enabled : false }
vars : { patroni_watchdog_mode : 'off' }
minio : # minio cluster, s3 compatible object storage
hosts : { 10.10.10.10 : { minio_seq : 1 } }
vars : { minio_cluster : minio }
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 } # odd number please
vars : # cluster level parameter override roles/etcd
etcd_cluster : etcd # mark etcd cluster name etcd
etcd_safeguard : false # safeguard against purging
pg-meta : # 3 instance postgres cluster `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 , pg_offline_query : true }
vars :
pg_cluster : pg-meta
pg_conf : crit.yml
pg_users :
- { 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 }
pg_databases :
- { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [ pigsty ] ,extensions : [ { name : vector } ] }
pg_services :
- { name: standby , ip : "*" ,port: 5435 , dest: default ,selector : "[]" , backup : "[? pg_role == `primary`]" }
pg_crontab : # https://pigsty.io/docs/pgsql/admin/crontab
- '00 01 * * * /pg/bin/pg-backup full'
pg_listen : '${ip},${vip},${lo}'
pg_vip_enabled : true
pg_vip_address : 10.10.10.2 /24
pg_vip_interface : eth1
# OPTIONAL delayed cluster for pg-meta
#pg-meta-delay: # delayed instance for pg-meta (1 hour ago)
# hosts: { 10.10.10.13: { pg_seq: 1, pg_role: primary, pg_upstream: 10.10.10.10, pg_delay: 1h } }
# vars: { pg_cluster: pg-meta-delay }
####################################################################
# Parameters #
####################################################################
vars : # global variables
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
patroni_ssl_enabled : true # secure patroni RestAPI communications with SSL?
pgbouncer_sslmode: require # pgbouncer client ssl mode : disable|allow|prefer|require|verify-ca|verify-full, disable by default
pg_default_service_dest : postgres # default service destination to postgres instead of pgbouncer
pgbackrest_method: minio # pgbackrest repo method : local,minio,[user-defined...]
#----------------------------------#
# MinIO Related Options
#----------------------------------#
minio_users : # and configure `pgbackrest_repo` & `minio_users` accordingly
- { access_key: dba , secret_key: S3User.DBA.Strong.Password, policy : consoleAdmin }
- { access_key: pgbackrest , secret_key: Min10.bAckup ,policy : readwrite }
pgbackrest_repo: # pgbackrest repo : https://pgbackrest.org/configuration.html#section-repository
local : # default pgbackrest repo with local posix fs
path : /pg/backup # local backup directory, `/pg/backup` by default
retention_full_type : count # retention full backups by count
retention_full : 2 # keep 2, at most 3 full backup when using local fs repo
minio : # optional minio repo for pgbackrest
s3_key : pgbackrest # <-------- CHANGE THIS, SAME AS `minio_users` access_key
s3_key_secret : Min10.bAckup # <-------- CHANGE THIS, SAME AS `minio_users` secret_key
cipher_pass : 'pgBR.${pg_cluster}' # <-------- CHANGE THIS, you can use cluster name as part of password
type : s3 # minio is s3-compatible, so s3 is used
s3_endpoint : sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
s3_region : us-east-1 # minio region, us-east-1 by default, useless for minio
s3_bucket : pgsql # minio bucket name, `pgsql` by default
s3_uri_style : path # use path style uri for minio rather than host style
path : /pgbackrest # minio backup path, default is `/pgbackrest`
storage_port : 9000 # minio port, 9000 by default
storage_ca_file : /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
block : y # Enable block incremental backup
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for last 14 days
#----------------------------------#
# Access Control
#----------------------------------#
# add passwordcheck extension to enforce strong password policy
pg_libs : '$libdir/passwordcheck, pg_stat_statements, auto_explain'
pg_extensions :
- passwordcheck, supautils, pgsodium, pg_vault, pg_session_jwt, anonymizer, pgsmcrypto, pgauditlogtofile, pgaudit #, pgaudit17, pgaudit16, pgaudit15, pgaudit14
- pg_auth_mon, credcheck, pgcryptokey, pg_jobmon, logerrors, login_hook, set_user, pgextwlist, pg_auditor, sslutils, noset #pg_tde #pg_snakeoil
pg_default_roles : # default roles and users in postgres cluster
- { name: dbrole_readonly ,login: false ,comment : role for global read-only access }
- { name: dbrole_offline ,login: false ,comment : role for restricted read-only access }
- { name: dbrole_readwrite ,login: false ,roles: [ dbrole_readonly ] ,comment : role for global read-write access }
- { name: dbrole_admin ,login: false ,roles: [ pg_monitor, dbrole_readwrite ] ,comment : role for object creation }
- { 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 }
pg_default_hba_rules : # postgres host-based auth rules by default, order by `order`
- { user : '${dbsu}' ,db: all ,addr: local ,auth: ident ,title: 'dbsu access via local os user ident' ,order : 100 }
- { user : '${dbsu}' ,db: replication ,addr: local ,auth: ident ,title: 'dbsu replication from local os ident' ,order : 150 }
- { user : '${repl}' ,db: replication ,addr: localhost ,auth: ssl ,title: 'replicator replication from localhost' ,order : 200 }
- { user : '${repl}' ,db: replication ,addr: intra ,auth: ssl ,title: 'replicator replication from intranet' ,order : 250 }
- { user : '${repl}' ,db: postgres ,addr: intra ,auth: ssl ,title: 'replicator postgres db from intranet' ,order : 300 }
- { user : '${monitor}' ,db: all ,addr: localhost ,auth: pwd ,title: 'monitor from localhost with password' ,order : 350 }
- { user : '${monitor}' ,db: all ,addr: infra ,auth: ssl ,title: 'monitor from infra host with password' ,order : 400 }
- { user : '${admin}' ,db: all ,addr: infra ,auth: ssl ,title: 'admin @ infra nodes with pwd & ssl' ,order : 450 }
- { user : '${admin}' ,db: all ,addr: world ,auth: cert ,title: 'admin @ everywhere with ssl & cert' ,order : 500 }
- { user: '+dbrole_readonly',db: all ,addr: localhost ,auth: ssl ,title: 'pgbouncer read/write via local socket' ,order : 550 }
- { user: '+dbrole_readonly',db: all ,addr: intra ,auth: ssl ,title: 'read/write biz user via password' ,order : 600 }
- { user: '+dbrole_offline' ,db: all ,addr: intra ,auth: ssl ,title: 'allow etl offline tasks from intranet' ,order : 650 }
pgb_default_hba_rules : # pgbouncer host-based authentication rules, order by `order`
- { user : '${dbsu}' ,db: pgbouncer ,addr: local ,auth: peer ,title: 'dbsu local admin access with os ident' ,order : 100 }
- { user: 'all' ,db: all ,addr: localhost ,auth: pwd ,title: 'allow all user local access with pwd' ,order : 150 }
- { user : '${monitor}' ,db: pgbouncer ,addr: intra ,auth: ssl ,title: 'monitor access via intranet with pwd' ,order : 200 }
- { user : '${monitor}' ,db: all ,addr: world ,auth: deny ,title: 'reject all other monitor access addr' ,order : 250 }
- { user : '${admin}' ,db: all ,addr: intra ,auth: ssl ,title: 'admin access via intranet with pwd' ,order : 300 }
- { user : '${admin}' ,db: all ,addr: world ,auth: deny ,title: 'reject all other admin access addr' ,order : 350 }
- { user: 'all' ,db: all ,addr: intra ,auth: ssl ,title: 'allow all user intra access with pwd' ,order : 400 }
#----------------------------------#
# Repo, Node, Packages
#----------------------------------#
repo_remove : true # remove existing repo on admin node during repo bootstrap
node_repo_remove : true # remove existing node repo for node managed by pigsty
#node_selinux_mode: enforcing # set selinux mode: enforcing,permissive,disabled
node_firewall_mode: zone # firewall mode : zone (default), off (disable), none (skip & self-managed)
repo_extra_packages : [ pg18-main ] #,pg18-core ,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]
pg_version : 18 # default postgres version
#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_username: admin
grafana_admin_password : You.Have2Use-A_VeryStrongPassword
grafana_view_password : DBUser.Viewer
#pg_admin_username: dbuser_dba
pg_admin_password : PessWorb.Should8eStrong-eNough
#pg_monitor_username: dbuser_monitor
pg_monitor_password : MekeSuerYour.PassWordI5secured
#pg_replication_username: replicator
pg_replication_password : doNotUseThis-PasswordFor.AnythingElse
#patroni_username: postgres
patroni_password : don.t-forget-to-change-thEs3-password
#haproxy_admin_username: admin
haproxy_admin_password : GneratePasswordWith-pwgen-s-16-1
minio_secret_key : S3User.MinIO
etcd_root_password : Etcd.Root
...
配置解读 ha/safe 模板是 Pigsty 的 安全加固配置 ,专为对安全性有较高要求的生产环境设计。
安全特性汇总 :
安全措施 说明 SSL 加密 PostgreSQL/PgBouncer/Patroni 全链路 SSL 强密码策略 passwordcheck 扩展强制密码复杂度用户过期 所有用户 20 年过期(expire_in: 7300) 严格 HBA 管理员远程访问需要证书认证 备份加密 MinIO 备份启用 AES-256-CBC 加密 审计日志 pgaudit 扩展记录 SQL 审计日志延迟副本 1 小时延迟副本用于误操作恢复
适用场景 :
金融、医疗、政务等高安全要求行业 需要满足合规审计要求的环境 对数据安全有极高要求的关键业务 注意事项 :
部分安全扩展在 ARM64 架构不可用,请酌情启用 所有默认密码必须修改为强密码 建议配合定期安全审计使用 9.27 - ha/trio 三节点标准高可用配置模板,允许任意一台服务器宕机。
三节点是实现真正高可用的最小规格。ha/trio 模板使用三节点标准 HA 架构,INFRA、ETCD、PGSQL 三个核心模块均采用三节点部署,允许任意一台服务器宕机。
配置概览 配置名称: ha/trio 节点数量: 三节点 配置说明:三节点标准高可用架构,允许任意一台服务器宕机 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:ha/dual ,ha/full ,ha/safe 启用方式:
./configure -c ha/trio [ -i <primary_ip>]
配置生成后,需要将占位 IP 10.10.10.11 和 10.10.10.12 修改为实际的节点 IP 地址。
配置内容 源文件地址:pigsty/conf/ha/trio.yml
---
#==============================================================#
# File : trio.yml
# Desc : Pigsty 3-node security enhance template
# Ctime : 2020-05-23
# Mtime : 2026-01-20
# Docs : https://pigsty.io/docs/conf/trio
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# 3 infra node, 3 etcd node, 3 pgsql node, and 1 minio node
all : # top level object
#==============================================================#
# Clusters, Nodes, and Modules
#==============================================================#
children :
#----------------------------------#
# infra: monitor, alert, repo, etc..
#----------------------------------#
infra : # infra cluster for proxy, monitor, alert, etc
hosts : # 1 for common usage, 3 nodes for production
10.10.10.10 : { infra_seq : 1 } # identity required
10.10.10.11 : { infra_seq: 2, repo_enabled : false }
10.10.10.12 : { infra_seq: 3, repo_enabled : false }
vars :
patroni_watchdog_mode : 'off' # do not fencing infra
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 } # odd number please
vars : # cluster level parameter override roles/etcd
etcd_cluster : etcd # mark etcd cluster name etcd
etcd_safeguard : false # safeguard against purging
minio : # minio cluster, s3 compatible object storage
hosts : { 10.10.10.10 : { minio_seq : 1 } }
vars : { minio_cluster : minio }
pg-meta : # 3 instance postgres cluster `pg-meta`
hosts : # pg-meta-3 is marked as offline readable replica
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 , pg_offline_query : true }
vars : # cluster level parameters
pg_cluster : pg-meta
pg_users : # https://pigsty.io/docs/pgsql/config/user
- { 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 for meta database }
pg_databases :
- { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [ pigsty ] ,extensions : [ { name : 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'
pg_vip_enabled : true
pg_vip_address : 10.10.10.2 /24
pg_vip_interface : eth1
#==============================================================#
# Global Parameters
#==============================================================#
vars :
#----------------------------------#
# Meta Data
#----------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
minio : { domain: m.pigsty ,endpoint : "${admin_ip}:9001" ,scheme: https ,websocket : true }
#----------------------------------#
# Repo, Node, Packages
#----------------------------------#
repo_remove : true # remove existing repo on admin node during repo bootstrap
node_repo_remove : true # remove existing node repo for node managed by pigsty
repo_extra_packages : [ pg18-main ] #,pg18-core ,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]
pg_version : 18 # default postgres version
#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]
#----------------------------------#
# MinIO Related Options
#----------------------------------#
node_etc_hosts :
- '${admin_ip} i.pigsty' # static dns record that point to repo node
- '${admin_ip} sss.pigsty' # static dns record that point to minio
pgbackrest_method : minio # if you want to use minio as backup repo instead of 'local' fs, uncomment this
pgbackrest_repo: # pgbackrest repo : https://pgbackrest.org/configuration.html#section-repository
local : # default pgbackrest repo with local posix fs
path : /pg/backup # local backup directory, `/pg/backup` by default
retention_full_type : count # retention full backups by count
retention_full : 2 # keep 2, at most 3 full backup when using local fs repo
minio : # optional minio repo for pgbackrest
type : s3 # minio is s3-compatible, so s3 is used
s3_endpoint : sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
s3_region : us-east-1 # minio region, us-east-1 by default, useless for minio
s3_bucket : pgsql # minio bucket name, `pgsql` by default
s3_key : pgbackrest # minio user access key for pgbackrest
s3_key_secret : S3User.Backup # minio user secret key for pgbackrest
s3_uri_style : path # use path style uri for minio rather than host style
path : /pgbackrest # minio backup path, default is `/pgbackrest`
storage_port : 9000 # minio port, 9000 by default
storage_ca_file : /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
block : y # Enable block incremental backup
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for last 14 days
#----------------------------------------------#
# 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
...
配置解读 ha/trio 模板是 Pigsty 的 标准高可用配置 ,提供真正的故障自动恢复能力。
架构说明 :
三节点 INFRA:Prometheus/Grafana/Nginx 分布式部署 三节点 ETCD:DCS 多数派选举,容忍单点故障 三节点 PostgreSQL:一主两从,自动故障转移 单节点 MinIO:可按需扩展为多节点 高可用保障 :
ETCD 三节点可容忍一节点故障,保持多数派 PostgreSQL 主库故障时,Patroni 自动选举新主 L2 VIP 随主库漂移,应用无需修改连接配置 适用场景 :
生产环境最小高可用部署 需要自动故障转移的关键业务 作为更大规模部署的基础架构 扩展建议 :
需要更强数据安全性,参考 ha/safe 模板 需要更多演示功能,参考 ha/full 模板 生产环境建议启用 pgbackrest_method: minio 远程备份 9.28 - ha/dual 双节点配置模板,有限高可用部署,允许宕机特定一台服务器。
ha/dual 模板使用双节点部署,实现一主一备的"半高可用"架构。如果您只有两台服务器,这是一个务实的选择。
配置概览 配置名称: ha/dual 节点数量: 双节点 配置说明:两节点有限高可用部署,允许特定一台服务器宕机 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:ha/trio ,slim 启用方式:
./configure -c ha/dual [ -i <primary_ip>]
配置生成后,需要将占位 IP 10.10.10.11 修改为实际的备库节点 IP 地址。
配置内容 源文件地址:pigsty/conf/ha/dual.yml
---
#==============================================================#
# File : dual.yml
# Desc : Pigsty deployment example for two nodes
# Ctime : 2020-05-22
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/conf/dual
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# It is recommended to use at least three nodes in production deployment.
# But sometimes, there are only two nodes available, that's dual.yml for
#
# In this setup, we have two nodes, .10 (admin_node) and .11 (pgsql_primary):
#
# If .11 is down, .10 will take over since the dcs:etcd is still alive
# If .10 is down, .11 (pgsql primary) will still be functioning as a primary if:
# - Only dcs:etcd is down
# - Only pgsql is down
# if both etcd & pgsql are down (e.g. node down), the primary will still demote itself.
all :
children :
# infra cluster for proxy, monitor, alert, etc..
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
# etcd cluster for ha postgres
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
# minio cluster, optional backup repo for pgbackrest
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }
# postgres cluster 'pg-meta' with single primary instance
pg-meta :
hosts :
10.10.10.10 : { pg_seq: 1, pg_role : replica }
10.10.10.11 : { pg_seq: 2, pg_role : primary } # <----- use this as primary by default
vars :
pg_cluster : pg-meta
pg_databases : [ { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [ pigsty ] ,extensions : [ { name : vector }] } ]
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 for meta database }
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'
pg_vip_enabled : true
pg_vip_address : 10.10.10.2 /24
pg_vip_interface : eth1
vars : # global parameters
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
infra_portal : # domain names and upstream servers
home : { domain : i.pigsty }
#minio : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
#----------------------------------#
# Repo, Node, Packages
#----------------------------------#
repo_remove : true # remove existing repo on admin node during repo bootstrap
node_repo_remove : true # remove existing node repo for node managed by pigsty
repo_extra_packages : [ pg18-main ] #,pg18-core ,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]
pg_version : 18 # default postgres version
#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
...
配置解读 ha/dual 模板是 Pigsty 的 双节点有限高可用配置 ,专为只有两台服务器的场景设计。
架构说明 :
节点 A (10.10.10.10):管理节点,运行 Infra + etcd + PostgreSQL 备库节点 B (10.10.10.11):数据节点,仅运行 PostgreSQL 主库故障场景分析 :
故障节点 影响 是否自动恢复 节点 B 宕机 主库切换到节点 A 自动 节点 A etcd 宕机 主库继续运行(无 DCS) 需人工 节点 A pgsql 宕机 主库继续运行 需人工 节点 A 完全宕机 主库降级为单机 需人工
适用场景 :
仅有两台服务器的预算受限环境 可接受部分故障场景需要人工介入 作为三节点高可用的过渡方案 注意事项 :
真正的高可用需要至少三节点(DCS 需要多数派) 建议尽快升级到三节点架构 L2 VIP 需要网络环境支持(同一广播域)
9.29 - 应用模版 9.30 - app/odoo 使用 Pigsty 托管的 PostgreSQL 部署 Odoo 开源 ERP 系统
app/odoo 配置模板提供了自建 Odoo 开源 ERP 系统的参考配置,使用 Pigsty 托管的 PostgreSQL 作为数据库。
更多细节,请参考 Odoo 部署教程
配置概览 配置名称: app/odoo 节点数量: 单节点 配置说明:使用 Pigsty 托管的 PostgreSQL 部署 Odoo ERP 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c app/odoo [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/app/odoo.yml
---
#==============================================================#
# File : odoo.yml
# Desc : pigsty config for running 1-node odoo app
# Ctime : 2025-01-11
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/app/odoo
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# tutorial: https://pigsty.io/docs/app/odoo
# how to use this template:
#
# curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
# ./bootstrap # prepare local repo & ansible
# ./configure -c app/odoo # Use this odoo config template
# vi pigsty.yml # IMPORTANT: CHANGE CREDENTIALS!!
# ./deploy.yml # install pigsty & pgsql & minio
# ./docker.yml # install docker & docker-compose
# ./app.yml # install odoo
all :
children :
# the odoo application (default username & password: admin/admin)
odoo :
hosts : { 10.10.10.10 : {} }
vars :
app : odoo # specify app name to be installed (in the apps)
apps : # define all applications
odoo : # app name, should have corresponding ~/pigsty/app/odoo folder
file : # optional directory to be created
- { path: /data/odoo ,state: directory, owner: 100, group : 101 }
- { path: /data/odoo/webdata ,state: directory, owner: 100, group : 101 }
- { path: /data/odoo/addons ,state: directory, owner: 100, group : 101 }
conf : # override /opt/<app>/.env config file
PG_HOST : 10.10.10.10 # postgres host
PG_PORT : 5432 # postgres port
PG_USERNAME : odoo # postgres user
PG_PASSWORD : DBUser.Odoo # postgres password
ODOO_PORT : 8069 # odoo app port
ODOO_DATA : /data/odoo/webdata # odoo webdata
ODOO_ADDONS : /data/odoo/addons # odoo plugins
ODOO_DBNAME : odoo # odoo database name
ODOO_VERSION : 19.0 # odoo image version
# the odoo database
pg-odoo :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-odoo
pg_users :
- { name: odoo ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_admin ] ,createdb: true ,comment : admin user for odoo service }
- { name: odoo_ro ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_readonly ] ,comment : read only user for odoo service }
- { name: odoo_rw ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_readwrite ] ,comment : read write user for odoo service }
pg_databases :
- { name: odoo ,owner: odoo ,revokeconn: true ,comment : odoo main database }
pg_hba_rules :
- { user: all ,db: all ,addr: 172.17.0.0/16 ,auth: pwd ,title : 'allow access from local docker network' }
- { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title : 'allow grafana dashboard access cmdb from infra nodes' }
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }
vars : # global variables
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
docker_enabled : true # enable docker on app group
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
proxy_env : # global proxy env when downloading packages & pull docker images
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.tsinghua.edu.cn"
#http_proxy: 127.0.0.1:12345 # add your proxy env here for downloading packages or pull images
#https_proxy: 127.0.0.1:12345 # usually the proxy is format as http://user:pass@proxy.xxx.com
#all_proxy: 127.0.0.1:12345
infra_portal : # domain names and upstream servers
home : { domain : i.pigsty }
minio : { domain: m.pigsty ,endpoint : "${admin_ip}:9001" ,scheme: https ,websocket : true }
odoo : # nginx server config for odoo
domain : odoo.pigsty # REPLACE WITH YOUR OWN DOMAIN!
endpoint : "10.10.10.10:8069" # odoo service endpoint: IP:PORT
websocket : true # add websocket support
certbot : odoo.pigsty # certbot cert name, apply with `make cert`
repo_enabled : false
node_repo_modules : node,infra,pgsql
pg_version : 18
#----------------------------------------------#
# 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
... 配置解读 app/odoo 模板提供了 Odoo 开源 ERP 系统的一键部署方案。
Odoo 是什么 :
全球最流行的开源 ERP 系统 覆盖 CRM、销售、采购、库存、财务、HR 等企业管理模块 支持数千个社区和官方应用扩展 提供 Web 界面和移动端支持 关键特性 :
使用 Pigsty 管理的 PostgreSQL 替代 Odoo 自带的数据库 支持 Odoo 19.0 最新版本 数据持久化到独立目录 /data/odoo 支持自定义插件目录 /data/odoo/addons 访问方式 :
# Odoo Web 界面
http://odoo.pigsty:8069
# 默认管理员账号
用户名: admin
密码: admin ( 首次登录时设置)
适用场景 :
中小企业 ERP 系统 替代 SAP、Oracle ERP 等商业解决方案 需要自定义业务流程的企业应用 注意事项 :
Odoo 容器以 uid=100, gid=101 运行,数据目录需要正确的权限 首次访问时需要创建数据库和设置管理员密码 生产环境建议启用 HTTPS 可通过 /data/odoo/addons 安装自定义模块 9.31 - app/dify 使用 Pigsty 托管的 PostgreSQL 部署 Dify AI 应用开发平台
app/dify 配置模板提供了自建 Dify AI 应用开发平台的参考配置,使用 Pigsty 托管的 PostgreSQL 和 pgvector 作为向量存储。
更多细节,请参考 Dify 部署教程
配置概览 配置名称: app/dify 节点数量: 单节点 配置说明:使用 Pigsty 托管的 PostgreSQL 部署 Dify 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c app/dify [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/app/dify.yml
---
#==============================================================#
# File : dify.yml
# Desc : pigsty config for running 1-node dify app
# Ctime : 2025-02-24
# Mtime : 2026-01-18
# Docs : https://pigsty.io/docs/app/dify
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# Last Verified Dify Version: v1.8.1 on 2025-09-08
# tutorial: https://pigsty.io/docs/app/dify
# how to use this template:
#
# curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
# ./bootstrap # prepare local repo & ansible
# ./configure -c app/dify # use this dify config template
# vi pigsty.yml # IMPORTANT: CHANGE CREDENTIALS!!
# ./deploy.yml # install pigsty & pgsql & minio
# ./docker.yml # install docker & docker-compose
# ./app.yml # install dify with docker-compose
#
# To replace domain name:
# sed -ie 's/dify.pigsty/dify.pigsty.cc/g' pigsty.yml
all :
children :
# the dify application
dify :
hosts : { 10.10.10.10 : {} }
vars :
app : dify # specify app name to be installed (in the apps)
apps : # define all applications
dify : # app name, should have corresponding ~/pigsty/app/dify folder
file : # data directory to be created
- { path: /data/dify ,state: directory ,mode : 0755 }
conf : # override /opt/dify/.env config file
# change domain, mirror, proxy, secret key
NGINX_SERVER_NAME : dify.pigsty
# A secret key for signing and encryption, gen with `openssl rand -base64 42` (CHANGE PASSWORD!)
SECRET_KEY : sk-somerandomkey
# expose DIFY nginx service with port 5001 by default
DIFY_PORT : 5001
# where to store dify files? the default is ./volume, we'll use another volume created above
DIFY_DATA : /data/dify
# proxy and mirror settings
#PIP_MIRROR_URL: https://pypi.tuna.tsinghua.edu.cn/simple
#SANDBOX_HTTP_PROXY: http://10.10.10.10:12345
#SANDBOX_HTTPS_PROXY: http://10.10.10.10:12345
# database credentials
DB_USERNAME : dify
DB_PASSWORD : difyai123456
DB_HOST : 10.10.10.10
DB_PORT : 5432
DB_DATABASE : dify
VECTOR_STORE : pgvector
PGVECTOR_HOST : 10.10.10.10
PGVECTOR_PORT : 5432
PGVECTOR_USER : dify
PGVECTOR_PASSWORD : difyai123456
PGVECTOR_DATABASE : dify
PGVECTOR_MIN_CONNECTION : 2
PGVECTOR_MAX_CONNECTION : 10
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta
pg_users :
- { name: dify ,password: difyai123456 ,pgbouncer: true ,roles: [ dbrole_admin ] ,superuser: true ,comment : dify superuser }
pg_databases :
- { name: dify ,owner: dify ,comment : dify main database }
- { name: dify_plugin ,owner: dify ,comment : dify plugin daemon database }
pg_hba_rules :
- { user: dify ,db: all ,addr: 172.17.0.0/16 ,auth: pwd ,title : 'allow dify access from local docker network' }
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }
vars : # global variables
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
docker_enabled : true # enable docker on app group
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
proxy_env : # global proxy env when downloading packages & pull docker images
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.tsinghua.edu.cn"
#http_proxy: 127.0.0.1:12345 # add your proxy env here for downloading packages or pull images
#https_proxy: 127.0.0.1:12345 # usually the proxy is format as http://user:pass@proxy.xxx.com
#all_proxy: 127.0.0.1:12345
infra_portal : # domain names and upstream servers
home : { domain : i.pigsty }
#minio : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
dify : # nginx server config for dify
domain : dify.pigsty # REPLACE WITH YOUR OWN DOMAIN!
endpoint : "10.10.10.10:5001" # dify service endpoint: IP:PORT
websocket : true # add websocket support
certbot : dify.pigsty # certbot cert name, apply with `make cert`
repo_enabled : false
node_repo_modules : node,infra,pgsql
pg_version : 18
#----------------------------------------------#
# 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
...
配置解读 app/dify 模板提供了 Dify AI 应用开发平台的一键部署方案。
Dify 是什么 :
开源的 LLM 应用开发平台 支持 RAG、Agent、Workflow 等 AI 应用模式 提供可视化的 Prompt 编排和应用构建界面 支持多种 LLM 后端(OpenAI、Claude、本地模型等) 关键特性 :
使用 Pigsty 管理的 PostgreSQL 替代 Dify 自带的数据库 使用 pgvector 作为向量存储(替代 Weaviate/Qdrant) 支持 HTTPS 和自定义域名 数据持久化到独立目录 /data/dify 访问方式 :
# Dify Web 界面
http://dify.pigsty:5001
# 或通过 Nginx 代理
https://dify.pigsty
适用场景 :
企业内部 AI 应用开发平台 RAG 知识库问答系统 LLM 驱动的自动化工作流 AI Agent 开发与部署 注意事项 :
必须修改 SECRET_KEY,使用 openssl rand -base64 42 生成 需要配置 LLM API 密钥(如 OpenAI API Key) Docker 网络需要能访问 PostgreSQL(已配置 172.17.0.0/16 HBA 规则) 建议配置代理以加速 Python 包下载 9.32 - app/electric 使用 Pigsty 托管的 PostgreSQL 部署 Electric 实时同步服务
app/electric 配置模板提供了部署 Electric SQL 实时同步服务的参考配置,实现 PostgreSQL 到客户端的实时数据同步。
配置概览 配置名称: app/electric 节点数量: 单节点 配置说明:使用 Pigsty 托管的 PostgreSQL 部署 Electric 实时同步 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c app/electric [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/app/electric.yml
---
#==============================================================#
# File : electric.yml
# Desc : pigsty config for running 1-node electric app
# Ctime : 2025-03-29
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/app/electric
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# tutorial: https://pigsty.io/docs/app/electric
# quick start: https://electric-sql.com/docs/quickstart
# how to use this template:
#
# curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
# ./bootstrap # prepare local repo & ansible
# ./configure -c app/electric # use this electric config template
# vi pigsty.yml # IMPORTANT: CHANGE CREDENTIALS!!
# ./deploy.yml # install pigsty & pgsql & minio
# ./docker.yml # install docker & docker-compose
# ./app.yml # install electric with docker-compose
all :
children :
# infra cluster for proxy, monitor, alert, etc..
infra :
hosts : { 10.10.10.10 : { infra_seq : 1 } }
vars :
app : electric
apps : # define all applications
electric : # app name, should have corresponding ~/pigsty/app/electric folder
conf: # override /opt/electric/.env config file : https://electric-sql.com/docs/api/config
DATABASE_URL : 'postgresql://electric:DBUser.Electric@10.10.10.10:5432/electric?sslmode=require'
ELECTRIC_PORT : 8002
ELECTRIC_PROMETHEUS_PORT : 8003
ELECTRIC_INSECURE : true
#ELECTRIC_SECRET: 1U6ItbhoQb4kGUU5wXBLbxvNf
# etcd cluster for ha postgres
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
# minio cluster, s3 compatible object storage
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }
# postgres example cluster: pg-meta
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta
pg_users :
- {name: electric ,password: DBUser.Electric ,pgbouncer: true , replication: true ,roles: [dbrole_admin] ,comment : electric main user }
pg_databases : [ { name: electric , owner : electric }]
pg_hba_rules :
- { user: electric , db: replication ,addr: infra ,auth: ssl ,title : 'allow electric intranet/docker ssl access' }
#==============================================================#
# Global Parameters
#==============================================================#
vars :
#----------------------------------#
# Meta Data
#----------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
docker_enabled : true # enable docker on app group
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
infra_portal : # domain names and upstream servers
home : { domain : i.pigsty }
electric :
domain : elec.pigsty
endpoint : "${admin_ip}:8002"
websocket: true # apply free ssl cert with certbot : make cert
certbot : odoo.pigsty # <----- replace with your own domain name!
#----------------------------------#
# Safe Guard
#----------------------------------#
# you can enable these flags after bootstrap, to prevent purging running etcd / pgsql instances
etcd_safeguard : false # prevent purging running etcd instance?
pg_safeguard : false # prevent purging running postgres instance? false by default
#----------------------------------#
# Repo, Node, Packages
#----------------------------------#
repo_enabled : false
node_repo_modules : node,infra,pgsql
pg_version : 18 # default postgres version
#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
...
配置解读 app/electric 模板提供了 Electric SQL 实时同步服务的一键部署方案。
Electric 是什么 :
PostgreSQL 到客户端的实时数据同步服务 支持离线优先 (Local-first) 应用架构 通过逻辑复制实时同步数据变更 提供 HTTP API 供前端应用消费 关键特性 :
使用 Pigsty 管理的 PostgreSQL 作为数据源 通过逻辑复制 (Logical Replication) 捕获数据变更 支持 SSL 加密连接 内置 Prometheus 指标端点 访问方式 :
# Electric API 端点
http://elec.pigsty:8002
# Prometheus 指标
http://elec.pigsty:8003/metrics
适用场景 :
构建离线优先 (Local-first) 应用 需要实时数据同步到客户端 移动应用和 PWA 的数据同步 协作应用的实时更新 注意事项 :
Electric 用户需要 replication 权限 需要启用 PostgreSQL 逻辑复制 生产环境建议使用 SSL 连接(已配置 sslmode=require) 9.33 - app/maybe 使用 Pigsty 托管的 PostgreSQL 部署 Maybe 个人财务管理系统
app/maybe 配置模板提供了部署 Maybe 开源个人财务管理系统的参考配置,使用 Pigsty 托管的 PostgreSQL 作为数据库。
配置概览 配置名称: app/maybe 节点数量: 单节点 配置说明:使用 Pigsty 托管的 PostgreSQL 部署 Maybe 财务管理 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c app/maybe [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/app/maybe.yml
---
#==============================================================#
# File : maybe.yml
# Desc : pigsty config for running 1-node maybe app
# Ctime : 2025-09-08
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/app/maybe
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# tutorial: https://pigsty.io/docs/app/maybe
# how to use this template:
#
# curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
# ./bootstrap # prepare local repo & ansible
# ./configure -c app/maybe # Use this maybe config template
# vi pigsty.yml # IMPORTANT: CHANGE CREDENTIALS!!
# ./deploy.yml # install pigsty & pgsql
# ./docker.yml # install docker & docker-compose
# ./app.yml # install maybe
all :
children :
# the maybe application (personal finance management)
maybe :
hosts : { 10.10.10.10 : {} }
vars :
app : maybe # specify app name to be installed (in the apps)
apps : # define all applications
maybe : # app name, should have corresponding ~/pigsty/app/maybe folder
file : # optional directory to be created
- { path: /data/maybe ,state: directory ,mode : 0755 }
- { path: /data/maybe/storage ,state: directory ,mode : 0755 }
conf : # override /opt/<app>/.env config file
# Core Configuration
MAYBE_VERSION : latest # Maybe image version
MAYBE_PORT : 5002 # Port to expose Maybe service
MAYBE_DATA : /data/maybe # Data directory for Maybe
APP_DOMAIN : maybe.pigsty # Domain name for Maybe
# REQUIRED: Generate with: openssl rand -hex 64
SECRET_KEY_BASE : sk-somerandomkey # Secret key for maybe
# Database Configuration
DB_HOST : 10.10.10.10 # PostgreSQL host
DB_PORT : 5432 # PostgreSQL port
DB_USERNAME : maybe # PostgreSQL username
DB_PASSWORD : MaybeFinance2025 # PostgreSQL password (CHANGE THIS!)
DB_DATABASE : maybe_production # PostgreSQL database name
# Optional: API Integration
#SYNTH_API_KEY: # Get from synthfinance.com
# the maybe database
pg-maybe :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-maybe
pg_users :
- { name: maybe ,password: MaybeFinance2025 ,pgbouncer: true ,roles: [ dbrole_admin ] ,createdb: true ,comment : admin user for maybe service }
- { name: maybe_ro ,password: MaybeFinance2025 ,pgbouncer: true ,roles: [ dbrole_readonly ] ,comment : read only user for maybe service }
- { name: maybe_rw ,password: MaybeFinance2025 ,pgbouncer: true ,roles: [ dbrole_readwrite ] ,comment : read write user for maybe service }
pg_databases :
- { name: maybe_production ,owner: maybe ,revokeconn: true ,comment : maybe main database }
pg_hba_rules :
- { user: maybe ,db: all ,addr: 172.17.0.0/16 ,auth: pwd ,title : 'allow maybe access from local docker network' }
- { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title : 'allow grafana dashboard access cmdb from infra nodes' }
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }
vars : # global variables
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
docker_enabled : true # enable docker on app group
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
proxy_env : # global proxy env when downloading packages & pull docker images
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.tsinghua.edu.cn"
#http_proxy: 127.0.0.1:12345 # add your proxy env here for downloading packages or pull images
#https_proxy: 127.0.0.1:12345 # usually the proxy is format as http://user:pass@proxy.xxx.com
#all_proxy: 127.0.0.1:12345
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
minio : { domain: m.pigsty ,endpoint : "${admin_ip}:9001" ,scheme: https ,websocket : true }
maybe : # nginx server config for maybe
domain : maybe.pigsty # REPLACE WITH YOUR OWN DOMAIN!
endpoint : "10.10.10.10:5002" # maybe service endpoint: IP:PORT
websocket : true # add websocket support
repo_enabled : false
node_repo_modules : node,infra,pgsql
#----------------------------------------------#
# 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
... 配置解读 app/maybe 模板提供了 Maybe 开源个人财务管理系统的一键部署方案。
Maybe 是什么 :
开源的个人和家庭财务管理系统 支持多账户、多币种资产追踪 提供投资组合分析和净值计算 美观现代的 Web 界面 关键特性 :
使用 Pigsty 管理的 PostgreSQL 替代 Maybe 自带的数据库 数据持久化到独立目录 /data/maybe 支持 HTTPS 和自定义域名 提供多用户权限管理 访问方式 :
# Maybe Web 界面
http://maybe.pigsty:5002
# 或通过 Nginx 代理
https://maybe.pigsty
适用场景 :
个人或家庭财务管理 投资组合追踪和分析 多账户资产汇总 替代 Mint、YNAB 等商业服务 注意事项 :
必须修改 SECRET_KEY_BASE,使用 openssl rand -hex 64 生成 首次访问时需要注册管理员账号 可选配置 Synth API 以获取股票价格数据 9.34 - app/teable 使用 Pigsty 托管的 PostgreSQL 部署 Teable 开源 Airtable 替代品
app/teable 配置模板提供了部署 Teable 开源无代码数据库的参考配置,使用 Pigsty 托管的 PostgreSQL 作为数据库。
配置概览 配置名称: app/teable 节点数量: 单节点 配置说明:使用 Pigsty 托管的 PostgreSQL 部署 Teable 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c app/teable [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/app/teable.yml
---
#==============================================================#
# File : teable.yml
# Desc : pigsty config for running 1-node teable app
# Ctime : 2025-02-24
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/app/teable
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# tutorial: https://pigsty.io/docs/app/teable
# how to use this template:
#
# curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
# ./bootstrap # prepare local repo & ansible
# ./configure -c app/teable # use this teable config template
# vi pigsty.yml # IMPORTANT: CHANGE CREDENTIALS!!
# ./deploy.yml # install pigsty & pgsql & minio
# ./docker.yml # install docker & docker-compose
# ./app.yml # install teable with docker-compose
#
# To replace domain name:
# sed -ie 's/teable.pigsty/teable.pigsty.cc/g' pigsty.yml
all :
children :
# the teable application
teable :
hosts : { 10.10.10.10 : {} }
vars :
app : teable # specify app name to be installed (in the apps)
apps : # define all applications
teable : # app name, ~/pigsty/app/teable folder
conf : # override /opt/teable/.env config file
# https://github.com/teableio/teable/blob/develop/dockers/examples/standalone/.env
# https://help.teable.io/en/deploy/env
POSTGRES_HOST : "10.10.10.10"
POSTGRES_PORT : "5432"
POSTGRES_DB : "teable"
POSTGRES_USER : "dbuser_teable"
POSTGRES_PASSWORD : "DBUser.Teable"
PRISMA_DATABASE_URL : "postgresql://dbuser_teable:DBUser.Teable@10.10.10.10:5432/teable"
PUBLIC_ORIGIN : "http://tea.pigsty"
PUBLIC_DATABASE_PROXY : "10.10.10.10:5432"
TIMEZONE : "UTC"
# Need to support sending emails to enable the following configurations
#BACKEND_MAIL_HOST: smtp.teable.io
#BACKEND_MAIL_PORT: 465
#BACKEND_MAIL_SECURE: true
#BACKEND_MAIL_SENDER: noreply.teable.io
#BACKEND_MAIL_SENDER_NAME: Teable
#BACKEND_MAIL_AUTH_USER: username
#BACKEND_MAIL_AUTH_PASS: password
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta
pg_users :
- { name: dbuser_teable ,password: DBUser.Teable ,pgbouncer: true ,roles: [ dbrole_admin ] ,superuser: true ,comment : teable superuser }
pg_databases :
- { name: teable ,owner: dbuser_teable ,comment : teable database }
pg_hba_rules :
- { user: teable ,db: all ,addr: 172.17.0.0/16 ,auth: pwd ,title : 'allow teable access from local docker network' }
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
minio : { hosts : { 10.10.10.10 : { minio_seq: 1 } }, vars : { minio_cluster : minio } }
vars : # global variables
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
docker_enabled : true # enable docker on app group
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
proxy_env : # global proxy env when downloading packages & pull docker images
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.tsinghua.edu.cn"
#http_proxy: 127.0.0.1:12345 # add your proxy env here for downloading packages or pull images
#https_proxy: 127.0.0.1:12345 # usually the proxy is format as http://user:pass@proxy.xxx.com
#all_proxy: 127.0.0.1:12345
infra_portal : # domain names and upstream servers
home : { domain : i.pigsty }
#minio : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
teable : # nginx server config for teable
domain : tea.pigsty # REPLACE IT WITH YOUR OWN DOMAIN!
endpoint : "10.10.10.10:8890" # teable service endpoint: IP:PORT
websocket : true # add websocket support
certbot : tea.pigsty # certbot cert name, apply with `make cert`
repo_enabled : false
node_repo_modules : node,infra,pgsql
node_etc_hosts : [ '${admin_ip} i.pigsty sss.pigsty' ]
pg_version : 18
#----------------------------------------------#
# 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
...
配置解读 app/teable 模板提供了 Teable 开源无代码数据库的一键部署方案。
Teable 是什么 :
开源的 Airtable 替代品 基于 PostgreSQL 的无代码数据库 支持表格、看板、日历、表单等多种视图 提供 API 和自动化工作流 关键特性 :
使用 Pigsty 管理的 PostgreSQL 作为底层存储 数据实际存储在真实的 PostgreSQL 表中 支持 SQL 直接查询数据 可与其他 PostgreSQL 工具和扩展集成 访问方式 :
# Teable Web 界面
http://tea.pigsty:8890
# 或通过 Nginx 代理
https://tea.pigsty
# 同时可以直接 SQL 访问底层数据
psql postgresql://dbuser_teable:DBUser.Teable@10.10.10.10:5432/teable
适用场景 :
需要 Airtable 类似功能但希望自建 团队协作数据管理 需要同时支持 API 和 SQL 访问 希望数据存储在真实 PostgreSQL 中 注意事项 :
Teable 用户需要 superuser 权限 需要正确配置 PUBLIC_ORIGIN 为外部访问地址 支持邮件通知(可选配置 SMTP) 9.35 - app/mattermost Mattermost 应用模板,使用 Pigsty 托管 PostgreSQL + Docker 一键部署团队协作系统。
app/mattermost 配置模板用于部署 Mattermost,默认将应用与数据库放在同一节点,使用 Pigsty 提供 PostgreSQL、Nginx 与监控能力。
配置概览 配置名称: app/mattermost 节点数量: 单节点(默认) 配置说明:Mattermost + PostgreSQL + Docker 的开箱即用模板。 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:app/odoo 、app/registry 、supabase 启用方式:
./configure -c app/mattermost
./deploy.yml
./docker.yml
./app.yml
配置内容 源文件地址:pigsty/conf/app/mattermost.yml
---
#==============================================================#
# File : mattermost.yml
# Desc : pigsty config for running 1-node mattermost app
# Ctime : 2026-02-04
# Mtime : 2026-02-04
# Docs : https://pigsty.io/docs/app/mattermost
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# tutorial: https://pigsty.io/docs/app/mattermost
# how to use this template:
#
# curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
# ./bootstrap # prepare local repo & ansible
# ./configure -c app/mattermost # use this mattermost config template
# vi pigsty.yml # IMPORTANT: CHANGE CREDENTIALS!!
# ./deploy.yml # install pigsty & pgsql
# ./docker.yml # install docker & docker-compose
# ./app.yml # install mattermost
#
# Design Notes:
# - Mattermost data/config/logs/plugins/bleve-indexes are persisted under /data/mattermost (host paths).
# - If you enable JuiceFS (PGFS), /data/mattermost becomes a mountpoint backed by PostgreSQL.
# This is optional and must be prepared with ./juice.yml before ./app.yml.
# - Storing file data in PostgreSQL increases DB size, WAL, and IO load; monitor bloat and backup cost.
all :
children :
# the mattermost application
mattermost :
hosts : { 10.10.10.10 : {} }
vars :
app : mattermost # specify app name to be installed (in the apps)
apps : # define all applications
mattermost : # app name, should have corresponding ~/pigsty/app/mattermost folder
file : # data directory to be created
- { path: /data/mattermost ,state: directory ,owner: 2000 ,group: 2000 ,mode : 0755 }
- { path: /data/mattermost/config ,state: directory ,owner: 2000 ,group: 2000 ,mode : 0755 }
- { path: /data/mattermost/data ,state: directory ,owner: 2000 ,group: 2000 ,mode : 0755 }
- { path: /data/mattermost/logs ,state: directory ,owner: 2000 ,group: 2000 ,mode : 0755 }
- { path: /data/mattermost/plugins ,state: directory ,owner: 2000 ,group: 2000 ,mode : 0755 }
- { path: /data/mattermost/client/plugins ,state: directory ,owner: 2000 ,group: 2000 ,mode : 0755 }
- { path: /data/mattermost/bleve-indexes ,state: directory ,owner: 2000 ,group: 2000 ,mode : 0755 }
conf : # override /opt/mattermost/.env config file
DOMAIN : mm.pigsty
APP_PORT : 8065
TZ : UTC
# postgres connection string
POSTGRES_URL : 'postgres://dbuser_mattermost:DBUser.Mattermost@10.10.10.10:5432/mattermost?sslmode=disable&connect_timeout=10'
# image version
MATTERMOST_IMAGE : mattermost-team-edition
MATTERMOST_IMAGE_TAG : latest
# data directories
MATTERMOST_CONFIG_PATH : /data/mattermost/config
MATTERMOST_DATA_PATH : /data/mattermost/data
MATTERMOST_LOGS_PATH : /data/mattermost/logs
MATTERMOST_PLUGINS_PATH : /data/mattermost/plugins
MATTERMOST_CLIENT_PLUGINS_PATH : /data/mattermost/client/plugins
MATTERMOST_BLEVE_INDEXES_PATH : /data/mattermost/bleve-indexes
MM_BLEVESETTINGS_INDEXDIR : /data/mattermost/bleve-indexes
# the mattermost database
pg-mattermost :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-mattermost
pg_users :
- { name: dbuser_mattermost ,password: DBUser.Mattermost ,pgbouncer: true ,roles: [ dbrole_admin ] ,createdb: true ,comment : admin user for mattermost }
pg_databases :
- { name: mattermost ,owner: dbuser_mattermost ,revokeconn: true ,comment : mattermost main database }
pg_hba_rules :
- { user: dbuser_mattermost ,db: all ,addr: 172.17.0.0/16 ,auth: pwd ,title : 'allow mattermost access from local docker network' }
- { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title : 'allow grafana dashboard access cmdb from infra nodes' }
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }
vars : # global variables
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
docker_enabled : true # enable docker on app group
#docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
proxy_env : # global proxy env when downloading packages & pull docker images
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.tsinghua.edu.cn"
#http_proxy: 127.0.0.1:12345 # add your proxy env here for downloading packages or pull images
#https_proxy: 127.0.0.1:12345 # usually the proxy is format as http://user:pass@proxy.xxx.com
#all_proxy: 127.0.0.1:12345
# Optional: PGFS with JuiceFS (store Mattermost file data in PostgreSQL)
# 1) Uncomment and adjust the block below
# 2) Run: ./juice.yml -l <host>
# 3) Ensure /data/mattermost is mounted before ./app.yml
#
#juice_cache: /data/juice
#juice_instances:
# pgfs:
# path : /data/mattermost
# meta : postgres://dbuser_mattermost:DBUser.Mattermost@10.10.10.10:5432/mattermost
# data : --storage postgres --bucket 10.10.10.10:5432/mattermost --access-key dbuser_mattermost --secret-key DBUser.Mattermost
# port : 9567
# owner : 2000
# group : 2000
# mode : '0755'
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty }
mattermost : # nginx server config for mattermost
domain : mm.pigsty # REPLACE WITH YOUR OWN DOMAIN!
endpoint : "${admin_ip}:8065" # mattermost service endpoint: IP:PORT
websocket : true # add websocket support
certbot : mm.pigsty # certbot cert name, apply with `make cert`
repo_enabled : false
node_repo_modules : node,infra,pgsql
pg_version : 18
#----------------------------------------------#
# 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
...
配置解读 app/mattermost 模板定义了三个关键部分:
mattermost 组:应用主机与 apps.mattermost 参数,包含 .env 覆写与数据目录声明。pg-mattermost 组:独立 PostgreSQL 集群、数据库与应用账号。infra/etcd 组:Pigsty 基础设施依赖。关键特征:
默认开启 docker_enabled: true,并通过 ./docker.yml 完成容器运行时准备。 Nginx 门户默认暴露 mm.pigsty(infra_portal.mattermost),支持 WebSocket。 预置本地 Docker 网段 HBA 规则(172.17.0.0/16)供应用访问数据库。 可选启用 JuiceFS(注释块)将 /data/mattermost 挂载到 PostgreSQL 后端存储。 注意事项:
请在部署前修改数据库口令、域名与应用密码等敏感信息。 若开放公网访问,建议配合 HTTPS、ACL 与防火墙规则。 9.36 - app/registry 使用 Pigsty 部署 Docker Registry 镜像代理和私有仓库
app/registry 配置模板提供了部署 Docker Registry 镜像代理的参考配置,可用作 Docker Hub 镜像加速或私有镜像仓库。
配置概览 配置名称: app/registry 节点数量: 单节点 配置说明:部署 Docker Registry 镜像代理和私有仓库 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c app/registry [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/app/registry.yml
---
#==============================================================#
# File : registry.yml
# Desc : pigsty config for running Docker Registry Mirror
# Ctime : 2025-07-01
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/app/registry
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# tutorial: https://pigsty.io/docs/app/registry
# how to use this template:
#
# curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
# ./configure -c app/registry # use this registry config template
# vi pigsty.yml # IMPORTANT: CHANGE DOMAIN & CREDENTIALS!
# ./deploy.yml # install pigsty
# ./docker.yml # install docker & docker-compose
# ./app.yml # install registry with docker-compose
#
# To replace domain name:
# sed -ie 's/registry.pigsty/registry.your-domain.com/g' pigsty.yml
#==============================================================#
# Usage Instructions:
#==============================================================#
#
# 1. Deploy the registry:
# ./configure -c app/registry && ./deploy.yml && ./docker.yml && ./app.yml
#
# 2. Configure Docker clients to use the mirror:
# Edit /etc/docker/daemon.json:
# {
# "registry-mirrors": ["https://registry.your-domain.com"],
# "insecure-registries": ["registry.your-domain.com"]
# }
#
# 3. Restart Docker daemon:
# sudo systemctl restart docker
#
# 4. Test the registry:
# docker pull nginx:latest # This will now use your mirror
#
# 5. Access the web UI (optional):
# https://registry-ui.your-domain.com
#
# 6. Monitor the registry:
# curl https://registry.your-domain.com/v2/_catalog
# curl https://registry.your-domain.com/v2/nginx/tags/list
#
#==============================================================#
all :
children :
# the docker registry mirror application
registry :
hosts : { 10.10.10.10 : {} }
vars :
app : registry # specify app name to be installed
apps : # define all applications
registry :
file : # create data directory for registry
- { path: /data/registry ,state: directory ,mode : 0755 }
conf : # environment variables for registry
REGISTRY_DATA : /data/registry
REGISTRY_PORT : 5000
REGISTRY_UI_PORT : 5080
REGISTRY_STORAGE_DELETE_ENABLED : true
REGISTRY_LOG_LEVEL : info
REGISTRY_PROXY_REMOTEURL : https://registry-1.docker.io
REGISTRY_PROXY_TTL : 168h
# basic infrastructure
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
vars :
#----------------------------------------------#
# INFRA : https://pigsty.io/docs/infra/param
#----------------------------------------------#
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
# Docker Registry Mirror service configuration
registry : # nginx server config for registry
domain : d.pigsty # REPLACE IT WITH YOUR OWN DOMAIN!
endpoint : "10.10.10.10:5000" # registry service endpoint: IP:PORT
websocket : false # registry doesn't need websocket
certbot : d.pigsty # certbot cert name, apply with `make cert`
# Optional: Registry Web UI
registry-ui : # nginx server config for registry UI
domain : dui.pigsty # REPLACE IT WITH YOUR OWN DOMAIN!
endpoint : "10.10.10.10:5080" # registry UI endpoint: IP:PORT
websocket : false # UI doesn't need websocket
certbot : d.pigsty # certbot cert name for UI
#----------------------------------------------#
# NODE : https://pigsty.io/docs/node/param
#----------------------------------------------#
repo_enabled : false
node_repo_modules : node,infra,pgsql
node_tune: oltp # node tuning specs : oltp,olap,tiny,crit
#----------------------------------------------#
# PGSQL : https://pigsty.io/docs/pgsql/param
#----------------------------------------------#
pg_version : 18 # Default PostgreSQL Major Version is 18
pg_conf: oltp.yml # pgsql tuning specs : {oltp,olap,tiny,crit}.yml
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
...
配置解读 app/registry 模板提供了 Docker Registry 镜像代理的一键部署方案。
Registry 是什么 :
Docker 官方的镜像仓库实现 可作为 Docker Hub 的拉取代理(Pull-through Cache) 也可作为私有镜像仓库使用 支持镜像缓存和本地存储 关键特性 :
作为 Docker Hub 的代理缓存,加速镜像拉取 缓存镜像到本地存储 /data/registry 提供 Web UI 界面查看缓存的镜像 支持自定义缓存过期时间 配置 Docker 客户端 :
# 编辑 /etc/docker/daemon.json
{
"registry-mirrors" : [ "https://d.pigsty" ] ,
"insecure-registries" : [ "d.pigsty" ]
}
# 重启 Docker
sudo systemctl restart docker
访问方式 :
# Registry API
https://d.pigsty/v2/_catalog
# Web UI
http://dui.pigsty:5080
# 拉取镜像(自动使用代理)
docker pull nginx:latest
适用场景 :
加速 Docker 镜像拉取(尤其在中国大陆) 减少对外网络依赖 企业内部私有镜像仓库 离线环境镜像分发 注意事项 :
需要足够的磁盘空间存储缓存镜像 默认缓存 7 天(REGISTRY_PROXY_TTL: 168h) 可配置 HTTPS 证书(通过 certbot)
9.37 - 其他模版 9.38 - demo/el Enterprise Linux (RHEL/Rocky/Alma) 专用配置模板
demo/el 配置模板是针对 Enterprise Linux 系列发行版(RHEL、Rocky Linux、Alma Linux、Oracle Linux)优化的配置模板。
配置概览 配置名称: demo/el 节点数量: 单节点 配置说明:Enterprise Linux 专用配置模板 适用系统:el8, el9, el10 适用架构:x86_64, aarch64 相关配置:meta ,demo/debian 启用方式:
./configure -c demo/el [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/demo/el.yml
---
#==============================================================#
# File : el.yml
# Desc : Default parameters for EL System in Pigsty
# Ctime : 2020-05-22
# Mtime : 2026-03-04
# Docs : https://pigsty.io/docs/conf/el
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
#==============================================================#
# Sandbox (4-node) #
#==============================================================#
# admin user : vagrant (nopass ssh & sudo already set) #
# 1. meta : 10.10.10.10 (2 Core | 4GB) pg-meta #
# 2. node-1 : 10.10.10.11 (1 Core | 1GB) pg-test-1 #
# 3. node-2 : 10.10.10.12 (1 Core | 1GB) pg-test-2 #
# 4. node-3 : 10.10.10.13 (1 Core | 1GB) pg-test-3 #
# (replace these ip if your 4-node env have different ip addr) #
# VIP 2: (l2 vip is available inside same LAN ) #
# pg-meta ---> 10.10.10.2 ---> 10.10.10.10 #
# pg-test ---> 10.10.10.3 ---> 10.10.10.1{1,2,3} #
#==============================================================#
all :
##################################################################
# CLUSTERS #
##################################################################
# meta nodes, nodes, pgsql, redis, pgsql clusters are defined as
# k:v pair inside `all.children`. Where the key is cluster name
# and value is cluster definition consist of two parts:
# `hosts`: cluster members ip and instance level variables
# `vars` : cluster level variables
##################################################################
children : # groups definition
# infra cluster for proxy, monitor, alert, etc..
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
# etcd cluster for ha postgres
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
# minio cluster, s3 compatible object storage
minio : { hosts : { 10.10.10.10 : { minio_seq: 1 } }, vars : { minio_cluster : minio } }
#----------------------------------#
# pgsql cluster: pg-meta (CMDB) #
#----------------------------------#
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role: primary , pg_offline_query : true } }
vars :
pg_cluster : pg-meta
# define business databases here: https://pigsty.io/docs/pgsql/config/db
pg_databases : # define business databases on this cluster, array of database definition
- name : meta # REQUIRED, `name` is the only mandatory field of a database definition
#state: create # optional, create|absent|recreate, create by default
baseline: cmdb.sql # optional, database sql baseline path, (relative path among ansible search path, e.g : files/)
schemas : [ pigsty] # optional, additional schemas to be created, array of schema names
extensions: # optional, additional extensions to be installed : array of `{name[,schema]}`
- { name : vector } # install pgvector extension on this database by default
comment : pigsty meta database # optional, comment string for this database
#pgbouncer: true # optional, add this database to pgbouncer database list? true by default
#owner: postgres # optional, database owner, current user if not specified
#template: template1 # optional, which template to use, template1 by default
#strategy: FILE_COPY # optional, clone strategy: FILE_COPY or WAL_LOG (PG15+), default to PG's default
#encoding: UTF8 # optional, inherited from template / cluster if not defined (UTF8)
#locale: C # optional, inherited from template / cluster if not defined (C)
#lc_collate: C # optional, inherited from template / cluster if not defined (C)
#lc_ctype: C # optional, inherited from template / cluster if not defined (C)
#locale_provider: libc # optional, locale provider: libc, icu, builtin (PG15+)
#icu_locale: en-US # optional, icu locale for icu locale provider (PG15+)
#icu_rules: '' # optional, icu rules for icu locale provider (PG16+)
#builtin_locale: C.UTF-8 # optional, builtin locale for builtin locale provider (PG17+)
#tablespace: pg_default # optional, default tablespace, pg_default by default
#is_template: false # optional, mark database as template, allowing clone by any user with CREATEDB privilege
#allowconn: true # optional, allow connection, true by default. false will disable connect at all
#revokeconn: false # optional, revoke public connection privilege. false by default. (leave connect with grant option to owner)
#register_datasource: true # optional, register this database to grafana datasources? true by default
#connlimit: -1 # optional, database connection limit, default -1 disable limit
#pool_auth_user: dbuser_meta # optional, all connection to this pgbouncer database will be authenticated by this user
#pool_mode: transaction # optional, pgbouncer pool mode at database level, default transaction
#pool_size: 64 # optional, pgbouncer pool size at database level, default 64
#pool_reserve: 32 # optional, pgbouncer pool size reserve at database level, default 32
#pool_size_min: 0 # optional, pgbouncer pool size min at database level, default 0
#pool_connlimit: 100 # optional, max database connections at database level, default 100
#- { name: grafana ,owner: dbuser_grafana ,revokeconn: true ,comment: grafana primary database }
#- { name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment: bytebase primary database }
#- { name: kong ,owner: dbuser_kong ,revokeconn: true ,comment: kong the api gateway database }
#- { name: gitea ,owner: dbuser_gitea ,revokeconn: true ,comment: gitea meta database }
#- { name: wiki ,owner: dbuser_wiki ,revokeconn: true ,comment: wiki meta database }
# define business users here: https://pigsty.io/docs/pgsql/config/user
pg_users : # define business users/roles on this cluster, array of user definition
- name : dbuser_meta # REQUIRED, `name` is the only mandatory field of a user definition
password : DBUser.Meta # optional, password, can be a scram-sha-256 hash string or plain text
pgbouncer : true # optional, add this user to pgbouncer user-list? false by default (production user should be true explicitly)
comment : pigsty admin user # optional, comment string for this user/role
roles: [ dbrole_admin ] # optional, belonged roles. default roles are : dbrole_{admin,readonly,readwrite,offline}
#login: true # optional, can log in, true by default (new biz ROLE should be false)
#superuser: false # optional, is superuser? false by default
#createdb: false # optional, can create database? false by default
#createrole: false # optional, can create role? false by default
#inherit: true # optional, can this role use inherited privileges? true by default
#replication: false # optional, can this role do replication? false by default
#bypassrls: false # optional, can this role bypass row level security? false by default
#connlimit: -1 # optional, user connection limit, default -1 disable limit
#expire_in: 3650 # optional, now + n days when this role is expired (OVERWRITE expire_at)
#expire_at: '2030-12-31' # optional, YYYY-MM-DD 'timestamp' when this role is expired (OVERWRITTEN by expire_in)
#parameters: {} # optional, role level parameters with `ALTER ROLE SET`
#pool_mode: transaction # optional, pgbouncer pool mode at user level, transaction by default
#pool_connlimit: -1 # optional, max database connections at user level, default -1 disable limit
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly], comment : read-only viewer for meta database}
#- {name: dbuser_grafana ,password: DBUser.Grafana ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for grafana database }
#- {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for bytebase database }
#- {name: dbuser_gitea ,password: DBUser.Gitea ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for gitea service }
#- {name: dbuser_wiki ,password: DBUser.Wiki ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for wiki.js service }
# define business service here: https://pigsty.io/docs/pgsql/service
pg_services : # extra services in addition to pg_default_services, array of service definition
# standby service will route {ip|name}:5435 to sync replica's pgbouncer (5435->6432 standby)
- name: standby # required, service name, the actual svc name will be prefixed with `pg_cluster`, e.g : pg-meta-standby
port : 5435 # required, service exposed port (work as kubernetes service node port mode)
ip : "*" # optional, service bind ip address, `*` for all ip by default
selector : "[]" # required, service member selector, use JMESPath to filter inventory
dest : default # optional, destination port, default|postgres|pgbouncer|<port_number>, 'default' by default
check : /sync # optional, health check url path, / by default
backup : "[? pg_role == `primary`]" # backup server selector
maxconn : 3000 # optional, max allowed front-end connection
balance: roundrobin # optional, haproxy load balance algorithm (roundrobin by default, other : 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'
# define pg extensions: https://pigsty.io/docs/pgsql/ext/
pg_libs : 'pg_stat_statements, auto_explain' # add timescaledb to shared_preload_libraries
#pg_extensions: [] # extensions to be installed on this cluster
# define HBA rules here: https://pigsty.io/docs/pgsql/config/hba
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_vip_interface : eth1
pg_crontab : # make a full backup 1 am everyday
- '00 01 * * * /pg/bin/pg-backup full'
#----------------------------------#
# pgsql cluster: pg-test (3 nodes) #
#----------------------------------#
# pg-test ---> 10.10.10.3 ---> 10.10.10.1{1,2,3}
pg-test : # define the new 3-node cluster pg-test
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary } # primary instance, leader of cluster
10.10.10.12 : { pg_seq: 2, pg_role : replica } # replica instance, follower of leader
10.10.10.13 : { pg_seq: 3, pg_role: replica, pg_offline_query : true } # replica with offline access
vars :
pg_cluster : pg-test # define pgsql cluster name
pg_users : [ { name: test , password: test , pgbouncer: true , roles : [ dbrole_admin ] }]
pg_databases : [ { name : test }] # create a database and user named 'test'
node_tune : tiny
pg_conf : tiny.yml
pg_vip_enabled : true
pg_vip_address : 10.10.10.3 /24
pg_vip_interface : eth1
pg_crontab : # make a full backup on monday 1am, and an incremental backup during weekdays
- '00 01 * * 1 /pg/bin/pg-backup full'
- '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup'
#----------------------------------#
# redis ms, sentinel, native cluster
#----------------------------------#
redis-ms : # redis classic primary & replica
hosts : { 10.10.10.10 : { redis_node: 1 , redis_instances : { 6379 : { }, 6380 : { replica_of : '10.10.10.10 6379' } } } }
vars : { redis_cluster: redis-ms ,redis_password: 'redis.ms' ,redis_max_memory : 64MB }
redis-meta : # redis sentinel x 3
hosts : { 10.10.10.11 : { redis_node: 1 , redis_instances : { 26379 : { } ,26380 : { } ,26381 : { } } } }
vars :
redis_cluster : redis-meta
redis_password : 'redis.meta'
redis_mode : sentinel
redis_max_memory : 16MB
redis_sentinel_monitor : # primary list for redis sentinel, use cls as name, primary ip:port
- { name: redis-ms, host: 10.10.10.10, port: 6379 ,password: redis.ms, quorum : 2 }
redis-test: # redis native cluster : 3m x 3s
hosts :
10.10.10.12 : { redis_node: 1 ,redis_instances : { 6379 : { } ,6380 : { } ,6381 : { } } }
10.10.10.13 : { redis_node: 2 ,redis_instances : { 6379 : { } ,6380 : { } ,6381 : { } } }
vars : { redis_cluster: redis-test ,redis_password: 'redis.test' ,redis_mode: cluster, redis_max_memory : 32MB }
####################################################################
# VARS #
####################################################################
vars : # global variables
#================================================================#
# VARS: INFRA #
#================================================================#
#-----------------------------------------------------------------
# META
#-----------------------------------------------------------------
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
language: en # default language : en, zh
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
#-----------------------------------------------------------------
# CA
#-----------------------------------------------------------------
ca_create : true # create ca if not exists? or just abort
ca_cn : pigsty-ca # ca common name, fixed as pigsty-ca
cert_validity : 7300d # cert validity, 20 years by default
#-----------------------------------------------------------------
# INFRA_IDENTITY
#-----------------------------------------------------------------
#infra_seq: 1 # infra node identity, explicitly required
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
infra_data : /data/infra # default data path for infrastructure data
#-----------------------------------------------------------------
# REPO
#-----------------------------------------------------------------
repo_enabled : true # create a yum repo on this infra node?
repo_home : /www # repo home dir, `/www` by default
repo_name : pigsty # repo name, pigsty by default
repo_endpoint : http://${admin_ip}:80 # access point to this repo by domain or ip:port
repo_remove : true # remove existing upstream repo
repo_modules : infra,node,pgsql # which repo modules are installed in repo_upstream
repo_upstream : # where to download
- { name: pigsty-local ,description: 'Pigsty Local' ,module: local ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://${admin_ip}/pigsty' }} # used by intranet nodes
- { name: pigsty-infra ,description: 'Pigsty INFRA' ,module: infra ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://repo.pigsty.io/yum/infra/$basearch' ,china : 'https://repo.pigsty.cc/yum/infra/$basearch' }}
- { name: pigsty-pgsql ,description: 'Pigsty PGSQL' ,module: pgsql ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://repo.pigsty.io/yum/pgsql/el$releasever.$basearch' ,china : 'https://repo.pigsty.cc/yum/pgsql/el$releasever.$basearch' }}
- { name: nginx ,description: 'Nginx Repo' ,module: infra ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://nginx.org/packages/rhel/$releasever/$basearch/' }}
- { name: docker-ce ,description: 'Docker CE' ,module: infra ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,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: baseos ,description: 'EL 8+ BaseOS' ,module: node ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,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,10] ,arch: [x86_64, aarch64] ,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,10] ,arch: [x86_64, aarch64] ,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: powertools ,description: 'EL 8 PowerTools' ,module: node ,releases: [8 ] ,arch: [x86_64, aarch64] ,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: crb ,description: 'EL 9 CRB' ,module: node ,releases: [ 9,10] ,arch: [x86_64, aarch64] ,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: epel ,description: 'EL 8+ EPEL' ,module: node ,releases: [8,9 ] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://mirrors.edge.kernel.org/fedora-epel/$releasever/Everything/$basearch/' ,china: 'https://mirrors.aliyun.com/epel/$releasever/Everything/$basearch/' ,europe : 'https://mirrors.xtom.de/epel/$releasever/Everything/$basearch/' }}
- { name: epel ,description: 'EL 10 EPEL' ,module: node ,releases: [ 10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://mirrors.edge.kernel.org/fedora-epel/$releasever.0/Everything/$basearch/' ,china: 'https://mirrors.aliyun.com/epel/$releasever.0/Everything/$basearch/' ,europe : 'https://mirrors.xtom.de/epel/$releasever.0/Everything/$basearch/' }}
- { name: pgdg-common ,description: 'PostgreSQL Common' ,module: pgsql ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/common/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/common/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/common/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-el8fix ,description: 'PostgreSQL EL8FIX' ,module: pgsql ,releases: [8 ] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-$basearch/' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-$basearch/' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-$basearch/' }}
- { name: pgdg-el9fix ,description: 'PostgreSQL EL9FIX' ,module: pgsql ,releases: [ 9 ] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-$basearch/' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-$basearch/' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-$basearch/' }}
- { name: pgdg-el10fix ,description: 'PostgreSQL EL10FIX' ,module: pgsql ,releases: [ 10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rocky10-sysupdates/redhat/rhel-10-$basearch/' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/common/pgdg-rocky10-sysupdates/redhat/rhel-10-$basearch/' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rocky10-sysupdates/redhat/rhel-10-$basearch/' }}
- { name: pgdg14 ,description: 'PostgreSQL 14' ,module: pgsql ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/14/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/14/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/14/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg15 ,description: 'PostgreSQL 15' ,module: pgsql ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/15/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/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,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/16/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg17 ,description: 'PostgreSQL 17' ,module: pgsql ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/17/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/17/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/17/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg18 ,description: 'PostgreSQL 18' ,module: pgsql ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/18/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/18/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-beta ,description: 'PostgreSQL Testing' ,module: beta ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/testing/19/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/testing/19/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/testing/19/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-extras ,description: 'PostgreSQL Extra' ,module: extra ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/extras/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/extras/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/extras/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg14-nonfree ,description: 'PostgreSQL 14+' ,module: extra ,releases: [8,9,10] ,arch: [x86_64 ] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/non-free/14/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/non-free/14/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/14/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg15-nonfree ,description: 'PostgreSQL 15+' ,module: extra ,releases: [8,9,10] ,arch: [x86_64 ] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/non-free/15/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/non-free/15/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/15/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg16-nonfree ,description: 'PostgreSQL 16+' ,module: extra ,releases: [8,9,10] ,arch: [x86_64 ] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/non-free/16/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/non-free/16/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/16/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg17-nonfree ,description: 'PostgreSQL 17+' ,module: extra ,releases: [8,9,10] ,arch: [x86_64 ] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg18-nonfree ,description: 'PostgreSQL 18+' ,module: extra ,releases: [8,9,10] ,arch: [x86_64 ] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/non-free/18/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.aliyun.com/postgresql/repos/yum/non-free/18/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/18/redhat/rhel-$releasever-$basearch' }}
- { name: timescaledb ,description: 'TimescaleDB' ,module: extra ,releases: [8,9 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packagecloud.io/timescale/timescaledb/el/$releasever/$basearch' }}
- { name: percona ,description: 'Percona TDE' ,module: percona ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://repo.pigsty.io/yum/percona/el$releasever.$basearch' ,china: 'https://repo.pigsty.cc/yum/percona/el$releasever.$basearch' ,origin : 'http://repo.percona.com/ppg-18.1/yum/release/$releasever/RPMS/$basearch' }}
- { name: wiltondb ,description: 'WiltonDB' ,module: mssql ,releases: [8,9 ] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://repo.pigsty.io/yum/mssql/el$releasever.$basearch', china: 'https://repo.pigsty.cc/yum/mssql/el$releasever.$basearch' , origin : 'https://download.copr.fedorainfracloud.org/results/wiltondb/wiltondb/epel-$releasever-$basearch/' }}
- { name: groonga ,description: 'Groonga' ,module: groonga ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packages.groonga.org/almalinux/$releasever/$basearch/' }}
- { name: mysql ,description: 'MySQL' ,module: mysql ,releases: [8,9 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://repo.mysql.com/yum/mysql-8.4-community/el/$releasever/$basearch/' }}
- { name: mongo ,description: 'MongoDB' ,module: mongo ,releases: [8,9 ] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/8.0/$basearch/' ,china : 'https://mirrors.aliyun.com/mongodb/yum/redhat/$releasever/mongodb-org/8.0/$basearch/' }}
- { name: redis ,description: 'Redis' ,module: redis ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://rpmfind.net/linux/remi/enterprise/$releasever/redis72/$basearch/' }}
- { name: grafana ,description: 'Grafana' ,module: grafana ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://rpm.grafana.com', china : 'https://mirrors.aliyun.com/grafana/yum/' }}
- { name: kubernetes ,description: 'Kubernetes' ,module: kube ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://pkgs.k8s.io/core:/stable:/v1.33/rpm/', china : 'https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.33/rpm/' }}
- { name: gitlab-ee ,description: 'Gitlab EE' ,module: gitlab ,releases: [8,9 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packages.gitlab.com/gitlab/gitlab-ee/el/$releasever/$basearch' }}
- { name: gitlab-ce ,description: 'Gitlab CE' ,module: gitlab ,releases: [8,9 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packages.gitlab.com/gitlab/gitlab-ce/el/$releasever/$basearch' }}
- { name: clickhouse ,description: 'ClickHouse' ,module: click ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://packages.clickhouse.com/rpm/stable/', china : 'https://mirrors.aliyun.com/clickhouse/rpm/stable/' }}
repo_packages : [ node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-utility, extra-modules ]
repo_extra_packages : [ pgsql-main ]
repo_url_packages : []
#-----------------------------------------------------------------
# INFRA_PACKAGE
#-----------------------------------------------------------------
infra_packages : # packages to be installed on infra nodes
- grafana,grafana-plugins,grafana-victorialogs-ds,grafana-victoriametrics-ds,victoria-metrics,victoria-logs,victoria-traces,vmutils,vlogscli,alertmanager
- node_exporter,blackbox_exporter,nginx_exporter,pg_exporter,pev2,nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli,restic,certbot,python3-certbot-nginx
#-----------------------------------------------------------------
# NGINX
#-----------------------------------------------------------------
nginx_enabled : true # enable nginx on this infra node?
nginx_clean : false # clean existing nginx config during init?
nginx_exporter_enabled : true # enable nginx_exporter on this infra node?
nginx_exporter_port : 9113 # nginx_exporter listen port, 9113 by default
nginx_sslmode : enable # nginx ssl mode? disable,enable,enforce
nginx_cert_validity : 397d # nginx self-signed cert validity, 397d by default
nginx_home : /www # nginx content dir, `/www` by default (soft link to nginx_data)
nginx_data : /data/nginx # nginx actual data dir, /data/nginx by default
nginx_users : { admin : pigsty } # nginx basic auth users : name and pass dict
nginx_port : 80 # nginx listen port, 80 by default
nginx_ssl_port : 443 # nginx ssl listen port, 443 by default
certbot_sign : false # sign nginx cert with certbot during setup?
certbot_email : your@email.com # certbot email address, used for free ssl
certbot_options : '' # certbot extra options
#-----------------------------------------------------------------
# DNS
#-----------------------------------------------------------------
dns_enabled : true # setup dnsmasq on this infra node?
dns_port : 53 # dns server listen port, 53 by default
dns_records : # dynamic dns records resolved by dnsmasq
- "${admin_ip} i.pigsty"
- "${admin_ip} m.pigsty supa.pigsty api.pigsty adm.pigsty cli.pigsty ddl.pigsty"
#-----------------------------------------------------------------
# VICTORIA
#-----------------------------------------------------------------
vmetrics_enabled : true # enable victoria-metrics on this infra node?
vmetrics_clean : false # whether clean existing victoria metrics data during init?
vmetrics_port : 8428 # victoria-metrics listen port, 8428 by default
vmetrics_scrape_interval : 10s # victoria global scrape interval, 10s by default
vmetrics_scrape_timeout : 8s # victoria global scrape timeout, 8s by default
vmetrics_options : >-
-retentionPeriod=15d
-promscrape.fileSDCheckInterval=5s
vlogs_enabled : true # enable victoria-logs on this infra node?
vlogs_clean : false # clean victoria-logs data during init?
vlogs_port : 9428 # victoria-logs listen port, 9428 by default
vlogs_options : >-
-retentionPeriod=15d
-retention.maxDiskSpaceUsageBytes=50GiB
-insert.maxLineSizeBytes=1MB
-search.maxQueryDuration=120s
vtraces_enabled : true # enable victoria-traces on this infra node?
vtraces_clean : false # clean victoria-trace data during inti?
vtraces_port : 10428 # victoria-traces listen port, 10428 by default
vtraces_options : >-
-retentionPeriod=15d
-retention.maxDiskSpaceUsageBytes=50GiB
vmalert_enabled : true # enable vmalert on this infra node?
vmalert_port : 8880 # vmalert listen port, 8880 by default
vmalert_options : '' # vmalert extra server options
#-----------------------------------------------------------------
# PROMETHEUS
#-----------------------------------------------------------------
blackbox_enabled : true # setup blackbox_exporter on this infra node?
blackbox_port : 9115 # blackbox_exporter listen port, 9115 by default
blackbox_options : '' # blackbox_exporter extra server options
alertmanager_enabled : true # setup alertmanager on this infra node?
alertmanager_port : 9059 # alertmanager listen port, 9059 by default
alertmanager_options : '' # alertmanager extra server options
exporter_metrics_path : /metrics # exporter metric path, `/metrics` by default
#-----------------------------------------------------------------
# GRAFANA
#-----------------------------------------------------------------
grafana_enabled : true # enable grafana on this infra node?
grafana_port : 3000 # default listen port for grafana
grafana_clean : false # clean grafana data during init?
grafana_admin_username : admin # grafana admin username, `admin` by default
grafana_admin_password : pigsty # grafana admin password, `pigsty` by default
grafana_auth_proxy : false # enable grafana auth proxy?
grafana_pgurl : '' # external postgres database url for grafana if given
grafana_view_password : DBUser.Viewer # password for grafana meta pg datasource
#================================================================#
# VARS: NODE #
#================================================================#
#-----------------------------------------------------------------
# NODE_IDENTITY
#-----------------------------------------------------------------
#nodename: # [INSTANCE] # node instance identity, use hostname if missing, optional
node_cluster : nodes # [CLUSTER] # node cluster identity, use 'nodes' if missing, optional
nodename_overwrite : true # overwrite node's hostname with nodename?
nodename_exchange : false # exchange nodename among play hosts?
node_id_from_pg : true # use postgres identity as node identity if applicable?
#-----------------------------------------------------------------
# NODE_DNS
#-----------------------------------------------------------------
node_write_etc_hosts : true # modify `/etc/hosts` on target node?
node_default_etc_hosts : # static dns records in `/etc/hosts`
- "${admin_ip} i.pigsty"
node_etc_hosts : [] # extra static dns records in `/etc/hosts`
node_dns_method: add # how to handle dns servers : add,none,overwrite
node_dns_servers : [ '${admin_ip}' ] # dynamic nameserver in `/etc/resolv.conf`
node_dns_options : # dns resolv options in `/etc/resolv.conf`
- options single-request-reopen timeout:1
#-----------------------------------------------------------------
# NODE_PACKAGE
#-----------------------------------------------------------------
node_repo_modules : local # upstream repo to be added on node, local by default
node_repo_remove : true # remove existing repo on node?
node_packages : [ openssh-server] # packages to be installed current nodes with latest version
node_default_packages : # default packages to be installed on all nodes
- lz4,unzip,bzip2,pv,jq,git,ncdu,make,patch,bash,lsof,wget,uuid,tuned,nvme-cli,numactl,sysstat,iotop,htop,rsync,tcpdump
- python3,python3-pip,socat,lrzsz,net-tools,ipvsadm,telnet,ca-certificates,openssl,keepalived,etcd,haproxy,chrony,pig
- zlib,yum,audit,bind-utils,readline,vim-minimal,node_exporter,grubby,openssh-server,openssh-clients,chkconfig,vector
node_uv_env : /data/venv # uv venv path, empty string to skip
node_pip_packages : '' # pip packages to install in uv venv
#-----------------------------------------------------------------
# NODE_SEC
#-----------------------------------------------------------------
node_selinux_mode: permissive # set selinux mode : enforcing,permissive,disabled
node_firewall_mode: zone # firewall mode : zone (default), off (disable), none (skip & self-managed)
node_firewall_intranet : # which intranet cidr considered as internal network
- 10.0.0.0 /8
- 192.168.0.0 /16
- 172.16.0.0 /12
node_firewall_public_port : # expose these ports to public network in (zone, strict) mode
- 22 # enable ssh access
- 80 # enable http access
- 443 # enable https access
- 5432 # enable postgres access
#-----------------------------------------------------------------
# NODE_TUNE
#-----------------------------------------------------------------
node_disable_numa : false # disable node numa, reboot required
node_disable_swap : false # disable node swap, use with caution
node_static_network : true # preserve dns resolver settings after reboot
node_disk_prefetch : false # setup disk prefetch on HDD to increase performance
node_kernel_modules : [ softdog, ip_vs, ip_vs_rr, ip_vs_wrr, ip_vs_sh ]
node_hugepage_count : 0 # number of 2MB hugepage, take precedence over ratio
node_hugepage_ratio : 0 # node mem hugepage ratio, 0 disable it by default
node_overcommit_ratio : 0 # node mem overcommit ratio, 0 disable it by default
node_tune: oltp # node tuned profile : none,oltp,olap,crit,tiny
node_sysctl_params : # sysctl parameters in k:v format in addition to tuned
fs.nr_open : 8388608
#-----------------------------------------------------------------
# NODE_ADMIN
#-----------------------------------------------------------------
node_data : /data # node main data directory, `/data` by default
node_admin_enabled : true # create a admin user on target node?
node_admin_uid : 88 # uid and gid for node admin user
node_admin_username : dba # name of node admin user, `dba` by default
node_admin_sudo : nopass # admin sudo privilege, all,nopass. nopass by default
node_admin_ssh_exchange : true # exchange admin ssh key among node cluster
node_admin_pk_current : true # add current user's ssh pk to admin authorized_keys
node_admin_pk_list : [] # ssh public keys to be added to admin user
node_aliases : {} # extra shell aliases to be added, k:v dict
#-----------------------------------------------------------------
# NODE_TIME
#-----------------------------------------------------------------
node_timezone : '' # setup node timezone, empty string to skip
node_ntp_enabled : true # enable chronyd time sync service?
node_ntp_servers : # ntp servers in `/etc/chrony.conf`
- pool pool.ntp.org iburst
node_crontab_overwrite : true # overwrite or append to `/etc/crontab`?
node_crontab : [ ] # crontab entries in `/etc/crontab`
#-----------------------------------------------------------------
# NODE_VIP
#-----------------------------------------------------------------
vip_enabled : false # enable vip on this node cluster?
# vip_address: [IDENTITY] # node vip address in ipv4 format, required if vip is enabled
# vip_vrid: [IDENTITY] # required, integer, 1-254, should be unique among same VLAN
vip_role : backup # optional, `master|backup`, backup by default, use as init role
vip_preempt : false # optional, `true/false`, false by default, enable vip preemption
vip_interface : eth0 # node vip network interface to listen, `eth0` by default
vip_dns_suffix : '' # node vip dns name suffix, empty string by default
vip_exporter_port : 9650 # keepalived exporter listen port, 9650 by default
#-----------------------------------------------------------------
# HAPROXY
#-----------------------------------------------------------------
haproxy_enabled : true # enable haproxy on this node?
haproxy_clean : false # cleanup all existing haproxy config?
haproxy_reload : true # reload haproxy after config?
haproxy_auth_enabled : true # enable authentication for haproxy admin page
haproxy_admin_username : admin # haproxy admin username, `admin` by default
haproxy_admin_password : pigsty # haproxy admin password, `pigsty` by default
haproxy_exporter_port : 9101 # haproxy admin/exporter port, 9101 by default
haproxy_client_timeout : 24h # client side connection timeout, 24h by default
haproxy_server_timeout : 24h # server side connection timeout, 24h by default
haproxy_services : [] # list of haproxy service to be exposed on node
#-----------------------------------------------------------------
# NODE_EXPORTER
#-----------------------------------------------------------------
node_exporter_enabled : true # setup node_exporter on this node?
node_exporter_port : 9100 # node exporter listen port, 9100 by default
node_exporter_options : '--no-collector.softnet --no-collector.nvme --collector.tcpstat --collector.processes'
#-----------------------------------------------------------------
# VECTOR
#-----------------------------------------------------------------
vector_enabled : true # enable vector log collector?
vector_clean : false # purge vector data dir during init?
vector_data : /data/vector # vector data dir, /data/vector by default
vector_port : 9598 # vector metrics port, 9598 by default
vector_read_from : beginning # vector read from beginning or end
vector_log_endpoint : [ infra ] # if defined, sending vector log to this endpoint.
#================================================================#
# VARS: DOCKER #
#================================================================#
docker_enabled : false # enable docker on this node?
docker_data : /data/docker # docker data directory, /data/docker by default
docker_storage_driver : overlay2 # docker storage driver, can be zfs, btrfs
docker_cgroups_driver: systemd # docker cgroup fs driver : cgroupfs,systemd
docker_registry_mirrors : [] # docker registry mirror list
docker_exporter_port : 9323 # docker metrics exporter port, 9323 by default
docker_image : [] # docker image to be pulled after bootstrap
docker_image_cache : /tmp/docker/*.tgz # docker image cache glob pattern
#================================================================#
# VARS: ETCD #
#================================================================#
#etcd_seq: 1 # etcd instance identifier, explicitly required
etcd_cluster : etcd # etcd cluster & group name, etcd by default
etcd_safeguard : false # prevent purging running etcd instance?
etcd_data : /data/etcd # etcd data directory, /data/etcd by default
etcd_port : 2379 # etcd client port, 2379 by default
etcd_peer_port : 2380 # etcd peer port, 2380 by default
etcd_init : new # etcd initial cluster state, new or existing
etcd_election_timeout : 1000 # etcd election timeout, 1000ms by default
etcd_heartbeat_interval : 100 # etcd heartbeat interval, 100ms by default
etcd_root_password : Etcd.Root # etcd root password for RBAC, change it!
#================================================================#
# VARS: MINIO #
#================================================================#
#minio_seq: 1 # minio instance identifier, REQUIRED
minio_cluster : minio # minio cluster identifier, REQUIRED
minio_user : minio # minio os user, `minio` by default
minio_https : true # use https for minio, true by default
minio_node : '${minio_cluster}-${minio_seq}.pigsty' # minio node name pattern
minio_data : '/data/minio' # minio data dir(s), use {x...y} to specify multi drivers
#minio_volumes: # minio data volumes, override defaults if specified
minio_domain : sss.pigsty # minio external domain name, `sss.pigsty` by default
minio_port : 9000 # minio service port, 9000 by default
minio_admin_port : 9001 # minio console port, 9001 by default
minio_access_key : minioadmin # root access key, `minioadmin` by default
minio_secret_key : S3User.MinIO # root secret key, `S3User.MinIO` by default
minio_extra_vars : '' # extra environment variables
minio_provision : true # run minio provisioning tasks?
minio_alias : sss # alias name for local minio deployment
#minio_endpoint: https://sss.pigsty:9000 # if not specified, overwritten by defaults
minio_buckets : # list of minio bucket to be created
- { name : pgsql }
- { name: meta ,versioning : true }
- { name : data }
minio_users : # list of minio user to be created
- { access_key: pgbackrest ,secret_key: S3User.Backup ,policy : pgsql }
- { access_key: s3user_meta ,secret_key: S3User.Meta ,policy : meta }
- { access_key: s3user_data ,secret_key: S3User.Data ,policy : data }
#================================================================#
# VARS: REDIS #
#================================================================#
#redis_cluster: <CLUSTER> # redis cluster name, required identity parameter
#redis_node: 1 <NODE> # redis node sequence number, node int id required
#redis_instances: {} <NODE> # redis instances definition on this redis node
redis_fs_main : /data/redis # redis main data directory, `/data/redis` by default
redis_exporter_enabled : true # install redis exporter on redis nodes?
redis_exporter_port : 9121 # redis exporter listen port, 9121 by default
redis_exporter_options : '' # cli args and extra options for redis exporter
redis_mode: standalone # redis mode : standalone,cluster,sentinel
redis_conf : redis.conf # redis config template path, except sentinel
redis_bind_address : '0.0.0.0' # redis bind address, empty string will use host ip
redis_max_memory : 1GB # max memory used by each redis instance
redis_mem_policy : allkeys-lru # redis memory eviction policy
redis_password : '' # redis password, empty string will disable password
redis_rdb_save : [ '1200 1' ] # redis rdb save directives, disable with empty list
redis_aof_enabled : false # enable redis append only file?
redis_rename_commands : {} # rename redis dangerous commands
redis_cluster_replicas : 1 # replica number for one master in redis cluster
redis_sentinel_monitor : [] # sentinel master list, works on sentinel cluster only
#================================================================#
# VARS: PGSQL #
#================================================================#
#-----------------------------------------------------------------
# PG_IDENTITY
#-----------------------------------------------------------------
pg_mode: pgsql #CLUSTER # pgsql cluster mode : pgsql,citus,gpsql,mssql,mysql,ivory,polar
# pg_cluster: #CLUSTER # pgsql cluster name, required identity parameter
# pg_seq: 0 #INSTANCE # pgsql instance seq number, required identity parameter
# pg_role: replica #INSTANCE # pgsql role, required, could be primary,replica,offline
# pg_instances: {} #INSTANCE # define multiple pg instances on node in `{port:ins_vars}` format
# pg_upstream: #INSTANCE # repl upstream ip addr for standby cluster or cascade replica
# pg_shard: #CLUSTER # pgsql shard name, optional identity for sharding clusters
# pg_group: 0 #CLUSTER # pgsql shard index number, optional identity for sharding clusters
# gp_role: master #CLUSTER # greenplum role of this cluster, could be master or segment
pg_offline_query : false #INSTANCE # set to true to enable offline queries on this instance
#-----------------------------------------------------------------
# PG_BUSINESS
#-----------------------------------------------------------------
# postgres business object definition, overwrite in group vars
pg_users : [] # postgres business users
pg_databases : [] # postgres business databases
pg_services : [] # postgres business services
pg_hba_rules : [] # business hba rules for postgres
pgb_hba_rules : [] # business hba rules for pgbouncer
# global credentials, overwrite in global vars
pg_dbsu_password : '' # dbsu password, empty string means no dbsu password by default
pg_replication_username : replicator
pg_replication_password : DBUser.Replicator
pg_admin_username : dbuser_dba
pg_admin_password : DBUser.DBA
pg_monitor_username : dbuser_monitor
pg_monitor_password : DBUser.Monitor
#-----------------------------------------------------------------
# PG_INSTALL
#-----------------------------------------------------------------
pg_dbsu : postgres # os dbsu name, postgres by default, better not change it
pg_dbsu_uid : 26 # os dbsu uid and gid, 26 for default postgres users and groups
pg_dbsu_sudo : limit # dbsu sudo privilege, none,limit,all,nopass. limit by default
pg_dbsu_home : /var/lib/pgsql # postgresql home directory, `/var/lib/pgsql` by default
pg_dbsu_ssh_exchange : true # exchange postgres dbsu ssh key among same pgsql cluster
pg_version : 18 # postgres major version to be installed, 18 by default
pg_bin_dir : /usr/pgsql/bin # postgres binary dir, `/usr/pgsql/bin` by default
pg_log_dir : /pg/log/postgres # postgres log dir, `/pg/log/postgres` by default
pg_packages : # pg packages to be installed, alias can be used
- pgsql-main pgsql-common
pg_extensions : [] # pg extensions to be installed, alias can be used
#-----------------------------------------------------------------
# PG_BOOTSTRAP
#-----------------------------------------------------------------
pg_data : /pg/data # postgres data directory, `/pg/data` by default
pg_fs_main : /data/postgres # postgres main data directory, `/data/postgres` by default
pg_fs_backup : /data/backups # postgres backup data directory, `/data/backups` by default
pg_storage_type : SSD # storage type for pg main data, SSD,HDD, SSD by default
pg_dummy_filesize : 64MiB # size of `/pg/dummy`, hold 64MB disk space for emergency use
pg_listen : '0.0.0.0' # postgres/pgbouncer listen addresses, comma separated list
pg_port : 5432 # postgres listen port, 5432 by default
pg_localhost : /var/run/postgresql # postgres unix socket dir for localhost connection
patroni_enabled : true # if disabled, no postgres cluster will be created during init
patroni_mode: default # patroni working mode : default,pause,remove
pg_namespace : /pg # top level key namespace in etcd, used by patroni & vip
patroni_port : 8008 # patroni listen port, 8008 by default
patroni_log_dir : /pg/log/patroni # patroni log dir, `/pg/log/patroni` by default
patroni_ssl_enabled : false # secure patroni RestAPI communications with SSL?
patroni_watchdog_mode: 'off' # patroni watchdog mode : automatic,required,off. off by default
patroni_username : postgres # patroni restapi username, `postgres` by default
patroni_password : Patroni.API # patroni restapi password, `Patroni.API` by default
pg_etcd_password : '' # etcd password for this pg cluster, '' to use pg_cluster
pg_primary_db : postgres # primary database name, used by citus,etc... ,postgres by default
pg_parameters : {} # extra parameters in postgresql.auto.conf
pg_files : [] # extra files to be copied to postgres data directory (e.g. license)
pg_conf: oltp.yml # config template : oltp,olap,crit,tiny. `oltp.yml` by default
pg_max_conn : auto # postgres max connections, `auto` will use recommended value
pg_shared_buffer_ratio : 0.25 # postgres shared buffers ratio, 0.25 by default, 0.1~0.4
pg_io_method : worker # io method for postgres, auto,fsync,worker,io_uring, worker by default
pg_rto: norm # shared rto mode for patroni & haproxy : fast,norm,safe,wide
pg_rpo : 1048576 # recovery point objective in bytes, `1MiB` at most by default
pg_libs : 'pg_stat_statements, auto_explain' # preloaded libraries, `pg_stat_statements,auto_explain` by default
pg_delay : 0 # replication apply delay for standby cluster leader
pg_checksum : true # enable data checksum for postgres cluster?
pg_encoding : UTF8 # database cluster encoding, `UTF8` by default
pg_locale : C # database cluster local, `C` by default
pg_lc_collate : C # database cluster collate, `C` by default
pg_lc_ctype : C # database character type, `C` by default
#pgsodium_key: "" # pgsodium key, 64 hex digit, default to sha256(pg_cluster)
#pgsodium_getkey_script: "" # pgsodium getkey script path, pgsodium_getkey by default
#-----------------------------------------------------------------
# PG_PROVISION
#-----------------------------------------------------------------
pg_provision : true # provision postgres cluster after bootstrap
pg_init : pg-init # provision init script for cluster template, `pg-init` by default
pg_default_roles : # default roles and users in postgres cluster
- { name: dbrole_readonly ,login: false ,comment : role for global read-only access }
- { name: dbrole_offline ,login: false ,comment : role for restricted read-only access }
- { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly] ,comment : role for global read-write access }
- { name: dbrole_admin ,login: false ,roles: [pg_monitor, dbrole_readwrite] ,comment : role for object creation }
- { name: postgres ,superuser: true ,comment : system superuser }
- { name: replicator ,replication: true ,roles: [pg_monitor, dbrole_readonly] ,comment : system replicator }
- { name: dbuser_dba ,superuser: true ,roles: [dbrole_admin] ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 ,comment : pgsql admin user }
- { name: dbuser_monitor ,roles: [pg_monitor] ,pgbouncer: true ,parameters : {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment : pgsql monitor user }
pg_default_privileges : # default privileges when created by admin user
- GRANT USAGE ON SCHEMAS TO dbrole_readonly
- GRANT SELECT ON TABLES TO dbrole_readonly
- GRANT SELECT ON SEQUENCES TO dbrole_readonly
- GRANT EXECUTE ON FUNCTIONS TO dbrole_readonly
- GRANT USAGE ON SCHEMAS TO dbrole_offline
- GRANT SELECT ON TABLES TO dbrole_offline
- GRANT SELECT ON SEQUENCES TO dbrole_offline
- GRANT EXECUTE ON FUNCTIONS TO dbrole_offline
- GRANT INSERT ON TABLES TO dbrole_readwrite
- GRANT UPDATE ON TABLES TO dbrole_readwrite
- GRANT DELETE ON TABLES TO dbrole_readwrite
- GRANT USAGE ON SEQUENCES TO dbrole_readwrite
- GRANT UPDATE ON SEQUENCES TO dbrole_readwrite
- GRANT TRUNCATE ON TABLES TO dbrole_admin
- GRANT REFERENCES ON TABLES TO dbrole_admin
- GRANT TRIGGER ON TABLES TO dbrole_admin
- GRANT CREATE ON SCHEMAS TO dbrole_admin
pg_default_schemas : [ monitor ] # default schemas to be created
pg_default_extensions : # default extensions to be created
- { name: pg_stat_statements ,schema : monitor }
- { name: pgstattuple ,schema : monitor }
- { name: pg_buffercache ,schema : monitor }
- { name: pageinspect ,schema : monitor }
- { name: pg_prewarm ,schema : monitor }
- { name: pg_visibility ,schema : monitor }
- { name: pg_freespacemap ,schema : monitor }
- { name: postgres_fdw ,schema : public }
- { name: file_fdw ,schema : public }
- { name: btree_gist ,schema : public }
- { name: btree_gin ,schema : public }
- { name: pg_trgm ,schema : public }
- { name: intagg ,schema : public }
- { name: intarray ,schema : public }
- { name : pg_repack }
pg_reload : true # reload postgres after hba changes
pg_default_hba_rules : # postgres default host-based authentication rules, order by `order`
- {user : '${dbsu}' ,db: all ,addr: local ,auth: ident ,title: 'dbsu access via local os user ident' ,order : 100 }
- {user : '${dbsu}' ,db: replication ,addr: local ,auth: ident ,title: 'dbsu replication from local os ident' ,order : 150 }
- {user : '${repl}' ,db: replication ,addr: localhost ,auth: pwd ,title: 'replicator replication from localhost',order : 200 }
- {user : '${repl}' ,db: replication ,addr: intra ,auth: pwd ,title: 'replicator replication from intranet' ,order : 250 }
- {user : '${repl}' ,db: postgres ,addr: intra ,auth: pwd ,title: 'replicator postgres db from intranet' ,order : 300 }
- {user : '${monitor}' ,db: all ,addr: localhost ,auth: pwd ,title: 'monitor from localhost with password' ,order : 350 }
- {user : '${monitor}' ,db: all ,addr: infra ,auth: pwd ,title: 'monitor from infra host with password',order : 400 }
- {user : '${admin}' ,db: all ,addr: infra ,auth: ssl ,title: 'admin @ infra nodes with pwd & ssl' ,order : 450 }
- {user : '${admin}' ,db: all ,addr: world ,auth: ssl ,title: 'admin @ everywhere with ssl & pwd' ,order : 500 }
- {user: '+dbrole_readonly',db: all ,addr: localhost ,auth: pwd ,title: 'pgbouncer read/write via local socket',order : 550 }
- {user: '+dbrole_readonly',db: all ,addr: intra ,auth: pwd ,title: 'read/write biz user via password' ,order : 600 }
- {user: '+dbrole_offline' ,db: all ,addr: intra ,auth: pwd ,title: 'allow etl offline tasks from intranet',order : 650 }
pgb_default_hba_rules : # pgbouncer default host-based authentication rules, order by `order`
- {user : '${dbsu}' ,db: pgbouncer ,addr: local ,auth: peer ,title: 'dbsu local admin access with os ident',order : 100 }
- {user: 'all' ,db: all ,addr: localhost ,auth: pwd ,title: 'allow all user local access with pwd' ,order : 150 }
- {user : '${monitor}' ,db: pgbouncer ,addr: intra ,auth: pwd ,title: 'monitor access via intranet with pwd' ,order : 200 }
- {user : '${monitor}' ,db: all ,addr: world ,auth: deny ,title: 'reject all other monitor access addr' ,order : 250 }
- {user : '${admin}' ,db: all ,addr: intra ,auth: pwd ,title: 'admin access via intranet with pwd' ,order : 300 }
- {user : '${admin}' ,db: all ,addr: world ,auth: deny ,title: 'reject all other admin access addr' ,order : 350 }
- {user: 'all' ,db: all ,addr: intra ,auth: pwd ,title: 'allow all user intra access with pwd' ,order : 400 }
#-----------------------------------------------------------------
# PG_BACKUP
#-----------------------------------------------------------------
pgbackrest_enabled : true # enable pgbackrest on pgsql host?
pgbackrest_log_dir : /pg/log/pgbackrest # pgbackrest log dir, `/pg/log/pgbackrest` by default
pgbackrest_method: local # pgbackrest repo method : local,minio,[user-defined...]
pgbackrest_init_backup : true # take a full backup after pgbackrest is initialized?
pgbackrest_repo: # pgbackrest repo : https://pgbackrest.org/configuration.html#section-repository
local : # default pgbackrest repo with local posix fs
path : /pg/backup # local backup directory, `/pg/backup` by default
retention_full_type : count # retention full backups by count
retention_full : 2 # keep 2, at most 3 full backups when using local fs repo
minio : # optional minio repo for pgbackrest
type : s3 # minio is s3-compatible, so s3 is used
s3_endpoint : sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
s3_region : us-east-1 # minio region, us-east-1 by default, useless for minio
s3_bucket : pgsql # minio bucket name, `pgsql` by default
s3_key : pgbackrest # minio user access key for pgbackrest
s3_key_secret : S3User.Backup # minio user secret key for pgbackrest
s3_uri_style : path # use path style uri for minio rather than host style
path : /pgbackrest # minio backup path, default is `/pgbackrest`
storage_port : 9000 # minio port, 9000 by default
storage_ca_file : /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
block : y # Enable block incremental backup
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for the the last 14 days
#-----------------------------------------------------------------
# PG_ACCESS
#-----------------------------------------------------------------
pgbouncer_enabled : true # if disabled, pgbouncer will not be launched on pgsql host
pgbouncer_port : 6432 # pgbouncer listen port, 6432 by default
pgbouncer_log_dir : /pg/log/pgbouncer # pgbouncer log dir, `/pg/log/pgbouncer` by default
pgbouncer_auth_query : false # query postgres to retrieve unlisted business users?
pgbouncer_poolmode: transaction # pooling mode : transaction,session,statement, transaction by default
pgbouncer_sslmode : disable # pgbouncer client ssl mode, disable by default
pgbouncer_ignore_param : [ extra_float_digits, application_name, TimeZone, DateStyle, IntervalStyle, search_path ]
pg_weight : 100 #INSTANCE # relative load balance weight in service, 100 by default, 0-255
pg_service_provider : '' # dedicate haproxy node group name, or empty string for local nodes by default
pg_default_service_dest : pgbouncer # default service destination if svc.dest='default'
pg_default_services : # postgres default service definitions
- { name: primary ,port: 5433 ,dest: default ,check: /primary ,selector : "[]" }
- { name: replica ,port: 5434 ,dest: default ,check: /read-only ,selector : "[]" , backup : "[? pg_role == `primary` || pg_role == `offline` ]" }
- { name: default ,port: 5436 ,dest: postgres ,check: /primary ,selector : "[]" }
- { name: offline ,port: 5438 ,dest: postgres ,check: /replica ,selector : "[? pg_role == `offline` || pg_offline_query ]" , backup : "[? pg_role == `replica` && !pg_offline_query]" }
pg_vip_enabled : false # enable a l2 vip for pgsql primary? false by default
pg_vip_address : 127.0.0.1 /24 # vip address in `<ipv4>/<mask>` format, require if vip is enabled
pg_vip_interface : eth0 # vip network interface to listen, eth0 by default
pg_dns_suffix : '' # pgsql dns suffix, '' by default
pg_dns_target : auto # auto, primary, vip, none, or ad hoc ip
#-----------------------------------------------------------------
# PG_MONITOR
#-----------------------------------------------------------------
pg_exporter_enabled : true # enable pg_exporter on pgsql hosts?
pg_exporter_config : pg_exporter.yml # pg_exporter configuration file name
pg_exporter_cache_ttls : '1,10,60,300' # pg_exporter collector ttl stage in seconds, '1,10,60,300' by default
pg_exporter_port : 9630 # pg_exporter listen port, 9630 by default
pg_exporter_params : 'sslmode=disable' # extra url parameters for pg_exporter dsn
pg_exporter_url : '' # overwrite auto-generate pg dsn if specified
pg_exporter_auto_discovery : true # enable auto database discovery? enabled by default
pg_exporter_exclude_database : 'template0,template1,postgres' # csv of database that WILL NOT be monitored during auto-discovery
pg_exporter_include_database : '' # csv of database that WILL BE monitored during auto-discovery
pg_exporter_connect_timeout : 200 # pg_exporter connect timeout in ms, 200 by default
pg_exporter_options : '' # overwrite extra options for pg_exporter
pgbouncer_exporter_enabled : true # enable pgbouncer_exporter on pgsql hosts?
pgbouncer_exporter_port : 9631 # pgbouncer_exporter listen port, 9631 by default
pgbouncer_exporter_url : '' # overwrite auto-generate pgbouncer dsn if specified
pgbouncer_exporter_options : '' # overwrite extra options for pgbouncer_exporter
pgbackrest_exporter_enabled : true # enable pgbackrest_exporter on pgsql hosts?
pgbackrest_exporter_port : 9854 # pgbackrest_exporter listen port, 9854 by default
pgbackrest_exporter_options : >
--collect.interval=120
--log.level=info
#-----------------------------------------------------------------
# PG_REMOVE
#-----------------------------------------------------------------
pg_safeguard : false # stop pg_remove running if pg_safeguard is enabled, false by default
pg_rm_data : true # remove postgres data during remove? true by default
pg_rm_backup : true # remove pgbackrest backup during primary remove? true by default
pg_rm_pkg : true # uninstall postgres packages during remove? true by default
...
配置解读 demo/el 模板是针对 Enterprise Linux 系列发行版优化的配置。
支持的发行版 :
RHEL 8/9/10 Rocky Linux 8/9/10 Alma Linux 8/9/10 Oracle Linux 8/9 关键特性 :
使用 EPEL 和 PGDG 软件源 针对 YUM/DNF 包管理器优化 支持 EL 系列特定的软件包名称 适用场景 :
企业生产环境(推荐 RHEL/Rocky/Alma) 需要长期支持和稳定性保障 使用红帽生态系统的环境 9.39 - demo/debian Debian/Ubuntu 专用配置模板
demo/debian 配置模板是针对 Debian 和 Ubuntu 发行版优化的配置模板。
配置概览 配置名称: demo/debian 节点数量: 单节点 配置说明:Debian/Ubuntu 专用配置模板 适用系统:d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta ,demo/el 启用方式:
./configure -c demo/debian [ -i <primary_ip>]
配置内容 源文件地址:pigsty/conf/demo/debian.yml
---
#==============================================================#
# File : debian.yml
# Desc : Default parameters for Debian/Ubuntu in Pigsty
# Ctime : 2020-05-22
# Mtime : 2026-03-04
# Docs : https://pigsty.io/docs/conf/debian
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
#==============================================================#
# Sandbox (4-node) #
#==============================================================#
# admin user : vagrant (nopass ssh & sudo already set) #
# 1. meta : 10.10.10.10 (2 Core | 4GB) pg-meta #
# 2. node-1 : 10.10.10.11 (1 Core | 1GB) pg-test-1 #
# 3. node-2 : 10.10.10.12 (1 Core | 1GB) pg-test-2 #
# 4. node-3 : 10.10.10.13 (1 Core | 1GB) pg-test-3 #
# (replace these ip if your 4-node env have different ip addr) #
# VIP 2: (l2 vip is available inside same LAN ) #
# pg-meta ---> 10.10.10.2 ---> 10.10.10.10 #
# pg-test ---> 10.10.10.3 ---> 10.10.10.1{1,2,3} #
#==============================================================#
all :
##################################################################
# CLUSTERS #
##################################################################
# meta nodes, nodes, pgsql, redis, pgsql clusters are defined as
# k:v pair inside `all.children`. Where the key is cluster name
# and value is cluster definition consist of two parts:
# `hosts`: cluster members ip and instance level variables
# `vars` : cluster level variables
##################################################################
children : # groups definition
# infra cluster for proxy, monitor, alert, etc..
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
# etcd cluster for ha postgres
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
# minio cluster, s3 compatible object storage
minio : { hosts : { 10.10.10.10 : { minio_seq: 1 } }, vars : { minio_cluster : minio } }
#----------------------------------#
# pgsql cluster: pg-meta (CMDB) #
#----------------------------------#
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role: primary , pg_offline_query : true } }
vars :
pg_cluster : pg-meta
# define business databases here: https://pigsty.io/docs/pgsql/config/db
pg_databases : # define business databases on this cluster, array of database definition
- name : meta # REQUIRED, `name` is the only mandatory field of a database definition
#state: create # optional, create|absent|recreate, create by default
baseline: cmdb.sql # optional, database sql baseline path, (relative path among ansible search path, e.g : files/)
schemas : [ pigsty] # optional, additional schemas to be created, array of schema names
extensions: # optional, additional extensions to be installed : array of `{name[,schema]}`
- { name : vector } # install pgvector extension on this database by default
comment : pigsty meta database # optional, comment string for this database
#pgbouncer: true # optional, add this database to pgbouncer database list? true by default
#owner: postgres # optional, database owner, current user if not specified
#template: template1 # optional, which template to use, template1 by default
#strategy: FILE_COPY # optional, clone strategy: FILE_COPY or WAL_LOG (PG15+), default to PG's default
#encoding: UTF8 # optional, inherited from template / cluster if not defined (UTF8)
#locale: C # optional, inherited from template / cluster if not defined (C)
#lc_collate: C # optional, inherited from template / cluster if not defined (C)
#lc_ctype: C # optional, inherited from template / cluster if not defined (C)
#locale_provider: libc # optional, locale provider: libc, icu, builtin (PG15+)
#icu_locale: en-US # optional, icu locale for icu locale provider (PG15+)
#icu_rules: '' # optional, icu rules for icu locale provider (PG16+)
#builtin_locale: C.UTF-8 # optional, builtin locale for builtin locale provider (PG17+)
#tablespace: pg_default # optional, default tablespace, pg_default by default
#is_template: false # optional, mark database as template, allowing clone by any user with CREATEDB privilege
#allowconn: true # optional, allow connection, true by default. false will disable connect at all
#revokeconn: false # optional, revoke public connection privilege. false by default. (leave connect with grant option to owner)
#register_datasource: true # optional, register this database to grafana datasources? true by default
#connlimit: -1 # optional, database connection limit, default -1 disable limit
#pool_auth_user: dbuser_meta # optional, all connection to this pgbouncer database will be authenticated by this user
#pool_mode: transaction # optional, pgbouncer pool mode at database level, default transaction
#pool_size: 64 # optional, pgbouncer pool size at database level, default 64
#pool_reserve: 32 # optional, pgbouncer pool size reserve at database level, default 32
#pool_size_min: 0 # optional, pgbouncer pool size min at database level, default 0
#pool_connlimit: 100 # optional, max database connections at database level, default 100
#- { name: grafana ,owner: dbuser_grafana ,revokeconn: true ,comment: grafana primary database }
#- { name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment: bytebase primary database }
#- { name: kong ,owner: dbuser_kong ,revokeconn: true ,comment: kong the api gateway database }
#- { name: gitea ,owner: dbuser_gitea ,revokeconn: true ,comment: gitea meta database }
#- { name: wiki ,owner: dbuser_wiki ,revokeconn: true ,comment: wiki meta database }
# define business users here: https://pigsty.io/docs/pgsql/config/user
pg_users : # define business users/roles on this cluster, array of user definition
- name : dbuser_meta # REQUIRED, `name` is the only mandatory field of a user definition
password : DBUser.Meta # optional, password, can be a scram-sha-256 hash string or plain text
pgbouncer : true # optional, add this user to pgbouncer user-list? false by default (production user should be true explicitly)
comment : pigsty admin user # optional, comment string for this user/role
roles: [ dbrole_admin ] # optional, belonged roles. default roles are : dbrole_{admin,readonly,readwrite,offline}
#login: true # optional, can log in, true by default (new biz ROLE should be false)
#superuser: false # optional, is superuser? false by default
#createdb: false # optional, can create database? false by default
#createrole: false # optional, can create role? false by default
#inherit: true # optional, can this role use inherited privileges? true by default
#replication: false # optional, can this role do replication? false by default
#bypassrls: false # optional, can this role bypass row level security? false by default
#connlimit: -1 # optional, user connection limit, default -1 disable limit
#expire_in: 3650 # optional, now + n days when this role is expired (OVERWRITE expire_at)
#expire_at: '2030-12-31' # optional, YYYY-MM-DD 'timestamp' when this role is expired (OVERWRITTEN by expire_in)
#parameters: {} # optional, role level parameters with `ALTER ROLE SET`
#pool_mode: transaction # optional, pgbouncer pool mode at user level, transaction by default
#pool_connlimit: -1 # optional, max database connections at user level, default -1 disable limit
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly], comment : read-only viewer for meta database}
#- {name: dbuser_grafana ,password: DBUser.Grafana ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for grafana database }
#- {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for bytebase database }
#- {name: dbuser_gitea ,password: DBUser.Gitea ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for gitea service }
#- {name: dbuser_wiki ,password: DBUser.Wiki ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for wiki.js service }
# define business service here: https://pigsty.io/docs/pgsql/service
pg_services : # extra services in addition to pg_default_services, array of service definition
# standby service will route {ip|name}:5435 to sync replica's pgbouncer (5435->6432 standby)
- name: standby # required, service name, the actual svc name will be prefixed with `pg_cluster`, e.g : pg-meta-standby
port : 5435 # required, service exposed port (work as kubernetes service node port mode)
ip : "*" # optional, service bind ip address, `*` for all ip by default
selector : "[]" # required, service member selector, use JMESPath to filter inventory
dest : default # optional, destination port, default|postgres|pgbouncer|<port_number>, 'default' by default
check : /sync # optional, health check url path, / by default
backup : "[? pg_role == `primary`]" # backup server selector
maxconn : 3000 # optional, max allowed front-end connection
balance: roundrobin # optional, haproxy load balance algorithm (roundrobin by default, other : 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'
# define pg extensions: https://pigsty.io/docs/pgsql/ext/
pg_libs : 'pg_stat_statements, auto_explain' # add timescaledb to shared_preload_libraries
#pg_extensions: [] # extensions to be installed on this cluster
# define HBA rules here: https://pigsty.io/docs/pgsql/config/hba
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_vip_interface : eth1
pg_crontab : # make a full backup 1 am everyday
- '00 01 * * * /pg/bin/pg-backup full'
#----------------------------------#
# pgsql cluster: pg-test (3 nodes) #
#----------------------------------#
# pg-test ---> 10.10.10.3 ---> 10.10.10.1{1,2,3}
pg-test : # define the new 3-node cluster pg-test
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary } # primary instance, leader of cluster
10.10.10.12 : { pg_seq: 2, pg_role : replica } # replica instance, follower of leader
10.10.10.13 : { pg_seq: 3, pg_role: replica, pg_offline_query : true } # replica with offline access
vars :
pg_cluster : pg-test # define pgsql cluster name
pg_users : [ { name: test , password: test , pgbouncer: true , roles : [ dbrole_admin ] }]
pg_databases : [ { name : test }] # create a database and user named 'test'
node_tune : tiny
pg_conf : tiny.yml
pg_vip_enabled : true
pg_vip_address : 10.10.10.3 /24
pg_vip_interface : eth1
pg_crontab : # make a full backup on monday 1am, and an incremental backup during weekdays
- '00 01 * * 1 /pg/bin/pg-backup full'
- '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup'
#----------------------------------#
# redis ms, sentinel, native cluster
#----------------------------------#
redis-ms : # redis classic primary & replica
hosts : { 10.10.10.10 : { redis_node: 1 , redis_instances : { 6379 : { }, 6380 : { replica_of : '10.10.10.10 6379' } } } }
vars : { redis_cluster: redis-ms ,redis_password: 'redis.ms' ,redis_max_memory : 64MB }
redis-meta : # redis sentinel x 3
hosts : { 10.10.10.11 : { redis_node: 1 , redis_instances : { 26379 : { } ,26380 : { } ,26381 : { } } } }
vars :
redis_cluster : redis-meta
redis_password : 'redis.meta'
redis_mode : sentinel
redis_max_memory : 16MB
redis_sentinel_monitor : # primary list for redis sentinel, use cls as name, primary ip:port
- { name: redis-ms, host: 10.10.10.10, port: 6379 ,password: redis.ms, quorum : 2 }
redis-test: # redis native cluster : 3m x 3s
hosts :
10.10.10.12 : { redis_node: 1 ,redis_instances : { 6379 : { } ,6380 : { } ,6381 : { } } }
10.10.10.13 : { redis_node: 2 ,redis_instances : { 6379 : { } ,6380 : { } ,6381 : { } } }
vars : { redis_cluster: redis-test ,redis_password: 'redis.test' ,redis_mode: cluster, redis_max_memory : 32MB }
####################################################################
# VARS #
####################################################################
vars : # global variables
#================================================================#
# VARS: INFRA #
#================================================================#
#-----------------------------------------------------------------
# META
#-----------------------------------------------------------------
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default,china,europe
language: en # default language : en, zh
proxy_env : # global proxy env when downloading packages
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
#-----------------------------------------------------------------
# CA
#-----------------------------------------------------------------
ca_create : true # create ca if not exists? or just abort
ca_cn : pigsty-ca # ca common name, fixed as pigsty-ca
cert_validity : 7300d # cert validity, 20 years by default
#-----------------------------------------------------------------
# INFRA_IDENTITY
#-----------------------------------------------------------------
#infra_seq: 1 # infra node identity, explicitly required
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
infra_data : /data/infra # default data path for infrastructure data
#-----------------------------------------------------------------
# REPO
#-----------------------------------------------------------------
repo_enabled : true # create a yum repo on this infra node?
repo_home : /www # repo home dir, `/www` by default
repo_name : pigsty # repo name, pigsty by default
repo_endpoint : http://${admin_ip}:80 # access point to this repo by domain or ip:port
repo_remove : true # remove existing upstream repo
repo_modules : infra,node,pgsql # which repo modules are installed in repo_upstream
repo_upstream : # where to download
- { name: pigsty-local ,description: 'Pigsty Local' ,module: local ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://${admin_ip}/pigsty ./' }}
- { name: pigsty-pgsql ,description: 'Pigsty PgSQL' ,module: pgsql ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://repo.pigsty.io/apt/pgsql/${distro_codename} ${distro_codename} main' , china : 'https://repo.pigsty.cc/apt/pgsql/${distro_codename} ${distro_codename} main' }}
- { name: pigsty-infra ,description: 'Pigsty Infra' ,module: infra ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://repo.pigsty.io/apt/infra/ generic main' ,china : 'https://repo.pigsty.cc/apt/infra/ generic main' }}
- { name: nginx ,description: 'Nginx' ,module: infra ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://nginx.org/packages/${distro_name} ${distro_codename} nginx' }}
- { name: docker-ce ,description: 'Docker' ,module: infra ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://download.docker.com/linux/${distro_name} ${distro_codename} stable' ,china : 'https://mirrors.aliyun.com/docker-ce/linux/${distro_name} ${distro_codename} stable' }}
- { name: base ,description: 'Debian Basic' ,module: node ,releases: [11,12,13 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://deb.debian.org/debian/ ${distro_codename} main non-free-firmware' ,china : 'https://mirrors.aliyun.com/debian/ ${distro_codename} main restricted universe multiverse' }}
- { name: updates ,description: 'Debian Updates' ,module: node ,releases: [11,12,13 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://deb.debian.org/debian/ ${distro_codename}-updates main non-free-firmware' ,china : 'https://mirrors.aliyun.com/debian/ ${distro_codename}-updates main restricted universe multiverse' }}
- { name: security ,description: 'Debian Security' ,module: node ,releases: [11,12,13 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://security.debian.org/debian-security ${distro_codename}-security main non-free-firmware' ,china : 'https://mirrors.aliyun.com/debian-security/ ${distro_codename}-security main non-free-firmware' }}
- { name: base ,description: 'Ubuntu Basic' ,module: node ,releases: [ 22,24,26] ,arch: [x86_64 ] ,baseurl : { default : 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename} main universe multiverse restricted' ,china : 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename} main restricted universe multiverse' }}
- { name: updates ,description: 'Ubuntu Updates' ,module: node ,releases: [ 22,24,26] ,arch: [x86_64 ] ,baseurl : { default : 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}-backports main restricted universe multiverse' ,china : 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}-updates main restricted universe multiverse' }}
- { name: backports ,description: 'Ubuntu Backports' ,module: node ,releases: [ 22,24,26] ,arch: [x86_64 ] ,baseurl : { default : 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}-security main restricted universe multiverse' ,china : 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}-backports main restricted universe multiverse' }}
- { name: security ,description: 'Ubuntu Security' ,module: node ,releases: [ 22,24,26] ,arch: [x86_64 ] ,baseurl : { default : 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}-updates main restricted universe multiverse' ,china : 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}-security main restricted universe multiverse' }}
- { name: base ,description: 'Ubuntu Basic' ,module: node ,releases: [ 22,24,26] ,arch: [ aarch64] ,baseurl : { default : 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename} main universe multiverse restricted' ,china : 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename} main restricted universe multiverse' }}
- { name: updates ,description: 'Ubuntu Updates' ,module: node ,releases: [ 22,24,26] ,arch: [ aarch64] ,baseurl : { default : 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}-backports main restricted universe multiverse' ,china : 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}-updates main restricted universe multiverse' }}
- { name: backports ,description: 'Ubuntu Backports' ,module: node ,releases: [ 22,24,26] ,arch: [ aarch64] ,baseurl : { default : 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}-security main restricted universe multiverse' ,china : 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}-backports main restricted universe multiverse' }}
- { name: security ,description: 'Ubuntu Security' ,module: node ,releases: [ 22,24,26] ,arch: [ aarch64] ,baseurl : { default : 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}-updates main restricted universe multiverse' ,china : 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}-security main restricted universe multiverse' }}
- { name: pgdg ,description: 'PGDG' ,module: pgsql ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://apt.postgresql.org/pub/repos/apt/ ${distro_codename}-pgdg main' ,china : 'https://mirrors.aliyun.com/postgresql/repos/apt/ ${distro_codename}-pgdg main' }}
- { name: pgdg-beta ,description: 'PGDG Beta' ,module: beta ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://apt.postgresql.org/pub/repos/apt/ ${distro_codename}-pgdg-testing main 19' ,china : 'https://mirrors.aliyun.com/postgresql/repos/apt/ ${distro_codename}-pgdg-testing main 19' }}
- { name: timescaledb ,description: 'TimescaleDB' ,module: extra ,releases: [11,12,13,22,24 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packagecloud.io/timescale/timescaledb/${distro_name}/ ${distro_codename} main' }}
- { name: citus ,description: 'Citus' ,module: extra ,releases: [11,12, 22 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packagecloud.io/citusdata/community/${distro_name}/ ${distro_codename} main' } }
- { name: percona ,description: 'Percona TDE' ,module: percona ,releases: [ 12,13,22,24 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://repo.pigsty.io/apt/percona ${distro_codename} main' ,china : 'https://repo.pigsty.cc/apt/percona ${distro_codename} main' ,origin : 'http://repo.percona.com/ppg-18.1/apt ${distro_codename} main' }}
- { name: wiltondb ,description: 'WiltonDB' ,module: mssql ,releases: [ 22,24 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://repo.pigsty.io/apt/mssql/ ${distro_codename} main' ,china : 'https://repo.pigsty.cc/apt/mssql/ ${distro_codename} main' ,origin : 'https://ppa.launchpadcontent.net/wiltondb/wiltondb/ubuntu/ ${distro_codename} main' }}
- { name: groonga ,description: 'Groonga Debian' ,module: groonga ,releases: [11,12,13 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packages.groonga.org/debian/ ${distro_codename} main' }}
- { name: groonga ,description: 'Groonga Ubuntu' ,module: groonga ,releases: [ 22,24 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://ppa.launchpadcontent.net/groonga/ppa/ubuntu/ ${distro_codename} main' }}
- { name: mysql ,description: 'MySQL' ,module: mysql ,releases: [11,12, 22,24 ] ,arch: [x86_64 ] ,baseurl : { default : 'https://repo.mysql.com/apt/${distro_name} ${distro_codename} mysql-8.0 mysql-tools' , china : 'https://mirrors.tuna.tsinghua.edu.cn/mysql/apt/${distro_name} ${distro_codename} mysql-8.0 mysql-tools' }}
- { name: mongo ,description: 'MongoDB' ,module: mongo ,releases: [ 12, 22,24 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://repo.mongodb.org/apt/${distro_name} ${distro_codename}/mongodb-org/8.0 multiverse' , china : 'https://mirrors.aliyun.com/mongodb/apt/${distro_name} ${distro_codename}/mongodb-org/8.0 multiverse' }}
- { name: redis ,description: 'Redis' ,module: redis ,releases: [11,12, 22,24 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packages.redis.io/deb ${distro_codename} main' }}
- { name: llvm ,description: 'LLVM' ,module: llvm ,releases: [11,12,13,22,24 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://apt.llvm.org/${distro_codename}/ llvm-toolchain-${distro_codename} main' ,china : 'https://mirrors.tuna.tsinghua.edu.cn/llvm-apt/${distro_codename}/ llvm-toolchain-${distro_codename} main' }}
- { name: haproxyd ,description: 'Haproxy Debian' ,module: haproxy ,releases: [11,12 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://haproxy.debian.net/ ${distro_codename}-backports-3.1 main' }}
- { name: haproxyu ,description: 'Haproxy Ubuntu' ,module: haproxy ,releases: [ 24,26] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://ppa.launchpadcontent.net/vbernat/haproxy-3.1/ubuntu/ ${distro_codename} main' }}
- { name: grafana ,description: 'Grafana' ,module: grafana ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://apt.grafana.com stable main' ,china : 'https://mirrors.aliyun.com/grafana/apt/ stable main' }}
- { name: kubernetes ,description: 'Kubernetes' ,module: kube ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /', china : 'https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.33/deb/ /' }}
- { name: gitlab-ee ,description: 'Gitlab EE' ,module: gitlab ,releases: [11,12,13,22,24 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packages.gitlab.com/gitlab/gitlab-ee/${distro_name}/ ${distro_codename} main' }}
- { name: gitlab-ce ,description: 'Gitlab CE' ,module: gitlab ,releases: [11,12,13,22,24 ] ,arch: [x86_64, aarch64] ,baseurl : { default : 'https://packages.gitlab.com/gitlab/gitlab-ce/${distro_name}/ ${distro_codename} main' }}
- { name: clickhouse ,description: 'ClickHouse' ,module: click ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://packages.clickhouse.com/deb/ stable main', china : 'https://mirrors.aliyun.com/clickhouse/deb/ stable main' }}
repo_packages : [ node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-utility, extra-modules ]
repo_extra_packages : [ pgsql-main ]
repo_url_packages : []
#-----------------------------------------------------------------
# INFRA_PACKAGE
#-----------------------------------------------------------------
infra_packages : # packages to be installed on infra nodes
- grafana,grafana-plugins,grafana-victorialogs-ds,grafana-victoriametrics-ds,victoria-metrics,victoria-logs,victoria-traces,vmutils,vlogscli,alertmanager
- node-exporter,blackbox-exporter,nginx-exporter,pg-exporter,pev2,nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli,restic,certbot,python3-certbot-nginx
#-----------------------------------------------------------------
# NGINX
#-----------------------------------------------------------------
nginx_enabled : true # enable nginx on this infra node?
nginx_clean : false # clean existing nginx config during init?
nginx_exporter_enabled : true # enable nginx_exporter on this infra node?
nginx_exporter_port : 9113 # nginx_exporter listen port, 9113 by default
nginx_sslmode : enable # nginx ssl mode? disable,enable,enforce
nginx_cert_validity : 397d # nginx self-signed cert validity, 397d by default
nginx_home : /www # nginx content dir, `/www` by default (soft link to nginx_data)
nginx_data : /data/nginx # nginx actual data dir, /data/nginx by default
nginx_users : { admin : pigsty } # nginx basic auth users : name and pass dict
nginx_port : 80 # nginx listen port, 80 by default
nginx_ssl_port : 443 # nginx ssl listen port, 443 by default
certbot_sign : false # sign nginx cert with certbot during setup?
certbot_email : your@email.com # certbot email address, used for free ssl
certbot_options : '' # certbot extra options
#-----------------------------------------------------------------
# DNS
#-----------------------------------------------------------------
dns_enabled : true # setup dnsmasq on this infra node?
dns_port : 53 # dns server listen port, 53 by default
dns_records : # dynamic dns records resolved by dnsmasq
- "${admin_ip} i.pigsty"
- "${admin_ip} m.pigsty supa.pigsty api.pigsty adm.pigsty cli.pigsty ddl.pigsty"
#-----------------------------------------------------------------
# VICTORIA
#-----------------------------------------------------------------
vmetrics_enabled : true # enable victoria-metrics on this infra node?
vmetrics_clean : false # whether clean existing victoria metrics data during init?
vmetrics_port : 8428 # victoria-metrics listen port, 8428 by default
vmetrics_scrape_interval : 10s # victoria global scrape interval, 10s by default
vmetrics_scrape_timeout : 8s # victoria global scrape timeout, 8s by default
vmetrics_options : >-
-retentionPeriod=15d
-promscrape.fileSDCheckInterval=5s
vlogs_enabled : true # enable victoria-logs on this infra node?
vlogs_clean : false # clean victoria-logs data during init?
vlogs_port : 9428 # victoria-logs listen port, 9428 by default
vlogs_options : >-
-retentionPeriod=15d
-retention.maxDiskSpaceUsageBytes=50GiB
-insert.maxLineSizeBytes=1MB
-search.maxQueryDuration=120s
vtraces_enabled : true # enable victoria-traces on this infra node?
vtraces_clean : false # clean victoria-trace data during inti?
vtraces_port : 10428 # victoria-traces listen port, 10428 by default
vtraces_options : >-
-retentionPeriod=15d
-retention.maxDiskSpaceUsageBytes=50GiB
vmalert_enabled : true # enable vmalert on this infra node?
vmalert_port : 8880 # vmalert listen port, 8880 by default
vmalert_options : '' # vmalert extra server options
#-----------------------------------------------------------------
# PROMETHEUS
#-----------------------------------------------------------------
blackbox_enabled : true # setup blackbox_exporter on this infra node?
blackbox_port : 9115 # blackbox_exporter listen port, 9115 by default
blackbox_options : '' # blackbox_exporter extra server options
alertmanager_enabled : true # setup alertmanager on this infra node?
alertmanager_port : 9059 # alertmanager listen port, 9059 by default
alertmanager_options : '' # alertmanager extra server options
exporter_metrics_path : /metrics # exporter metric path, `/metrics` by default
#-----------------------------------------------------------------
# GRAFANA
#-----------------------------------------------------------------
grafana_enabled : true # enable grafana on this infra node?
grafana_port : 3000 # default listen port for grafana
grafana_clean : false # clean grafana data during init?
grafana_admin_username : admin # grafana admin username, `admin` by default
grafana_admin_password : pigsty # grafana admin password, `pigsty` by default
grafana_auth_proxy : false # enable grafana auth proxy?
grafana_pgurl : '' # external postgres database url for grafana if given
grafana_view_password : DBUser.Viewer # password for grafana meta pg datasource
#================================================================#
# VARS: NODE #
#================================================================#
#-----------------------------------------------------------------
# NODE_IDENTITY
#-----------------------------------------------------------------
#nodename: # [INSTANCE] # node instance identity, use hostname if missing, optional
node_cluster : nodes # [CLUSTER] # node cluster identity, use 'nodes' if missing, optional
nodename_overwrite : true # overwrite node's hostname with nodename?
nodename_exchange : false # exchange nodename among play hosts?
node_id_from_pg : true # use postgres identity as node identity if applicable?
#-----------------------------------------------------------------
# NODE_DNS
#-----------------------------------------------------------------
node_write_etc_hosts : true # modify `/etc/hosts` on target node?
node_default_etc_hosts : # static dns records in `/etc/hosts`
- "${admin_ip} i.pigsty"
node_etc_hosts : [] # extra static dns records in `/etc/hosts`
node_dns_method: add # how to handle dns servers : add,none,overwrite
node_dns_servers : [ '${admin_ip}' ] # dynamic nameserver in `/etc/resolv.conf`
node_dns_options : # dns resolv options in `/etc/resolv.conf`
- options single-request-reopen timeout:1
#-----------------------------------------------------------------
# NODE_PACKAGE
#-----------------------------------------------------------------
node_repo_modules : local # upstream repo to be added on node, local by default
node_repo_remove : true # remove existing repo on node?
node_packages : [ openssh-server] # packages to be installed current nodes with latest version
node_default_packages : # default packages to be installed on all nodes
- lz4,unzip,bzip2,pv,jq,git,ncdu,make,patch,bash,lsof,wget,uuid,tuned,nvme-cli,numactl,sysstat,iotop,htop,rsync,tcpdump
- python3,python3-pip,socat,lrzsz,net-tools,ipvsadm,telnet,ca-certificates,openssl,keepalived,etcd,haproxy,chrony,pig
- zlib1g,acl,dnsutils,libreadline-dev,vim-tiny,node-exporter,openssh-server,openssh-client,vector
node_uv_env : /data/venv # uv venv path, empty string to skip
node_pip_packages : '' # pip packages to install in uv venv
#-----------------------------------------------------------------
# NODE_SEC
#-----------------------------------------------------------------
node_selinux_mode: permissive # set selinux mode : enforcing,permissive,disabled
node_firewall_mode: zone # firewall mode : zone (default), off (disable), none (skip & self-managed)
node_firewall_intranet : # which intranet cidr considered as internal network
- 10.0.0.0 /8
- 192.168.0.0 /16
- 172.16.0.0 /12
node_firewall_public_port : # expose these ports to public network in (zone, strict) mode
- 22 # enable ssh access
- 80 # enable http access
- 443 # enable https access
- 5432 # enable postgres access
#-----------------------------------------------------------------
# NODE_TUNE
#-----------------------------------------------------------------
node_disable_numa : false # disable node numa, reboot required
node_disable_swap : false # disable node swap, use with caution
node_static_network : true # preserve dns resolver settings after reboot
node_disk_prefetch : false # setup disk prefetch on HDD to increase performance
node_kernel_modules : [ softdog, ip_vs, ip_vs_rr, ip_vs_wrr, ip_vs_sh ]
node_hugepage_count : 0 # number of 2MB hugepage, take precedence over ratio
node_hugepage_ratio : 0 # node mem hugepage ratio, 0 disable it by default
node_overcommit_ratio : 0 # node mem overcommit ratio, 0 disable it by default
node_tune: oltp # node tuned profile : none,oltp,olap,crit,tiny
node_sysctl_params : # sysctl parameters in k:v format in addition to tuned
fs.nr_open : 8388608
#-----------------------------------------------------------------
# NODE_ADMIN
#-----------------------------------------------------------------
node_data : /data # node main data directory, `/data` by default
node_admin_enabled : true # create a admin user on target node?
node_admin_uid : 88 # uid and gid for node admin user
node_admin_username : dba # name of node admin user, `dba` by default
node_admin_sudo : nopass # admin sudo privilege, all,nopass. nopass by default
node_admin_ssh_exchange : true # exchange admin ssh key among node cluster
node_admin_pk_current : true # add current user's ssh pk to admin authorized_keys
node_admin_pk_list : [] # ssh public keys to be added to admin user
node_aliases : {} # extra shell aliases to be added, k:v dict
#-----------------------------------------------------------------
# NODE_TIME
#-----------------------------------------------------------------
node_timezone : '' # setup node timezone, empty string to skip
node_ntp_enabled : true # enable chronyd time sync service?
node_ntp_servers : # ntp servers in `/etc/chrony.conf`
- pool pool.ntp.org iburst
node_crontab_overwrite : true # overwrite or append to `/etc/crontab`?
node_crontab : [ ] # crontab entries in `/etc/crontab`
#-----------------------------------------------------------------
# NODE_VIP
#-----------------------------------------------------------------
vip_enabled : false # enable vip on this node cluster?
# vip_address: [IDENTITY] # node vip address in ipv4 format, required if vip is enabled
# vip_vrid: [IDENTITY] # required, integer, 1-254, should be unique among same VLAN
vip_role : backup # optional, `master|backup`, backup by default, use as init role
vip_preempt : false # optional, `true/false`, false by default, enable vip preemption
vip_interface : eth0 # node vip network interface to listen, `eth0` by default
vip_dns_suffix : '' # node vip dns name suffix, empty string by default
vip_exporter_port : 9650 # keepalived exporter listen port, 9650 by default
#-----------------------------------------------------------------
# HAPROXY
#-----------------------------------------------------------------
haproxy_enabled : true # enable haproxy on this node?
haproxy_clean : false # cleanup all existing haproxy config?
haproxy_reload : true # reload haproxy after config?
haproxy_auth_enabled : true # enable authentication for haproxy admin page
haproxy_admin_username : admin # haproxy admin username, `admin` by default
haproxy_admin_password : pigsty # haproxy admin password, `pigsty` by default
haproxy_exporter_port : 9101 # haproxy admin/exporter port, 9101 by default
haproxy_client_timeout : 24h # client side connection timeout, 24h by default
haproxy_server_timeout : 24h # server side connection timeout, 24h by default
haproxy_services : [] # list of haproxy service to be exposed on node
#-----------------------------------------------------------------
# NODE_EXPORTER
#-----------------------------------------------------------------
node_exporter_enabled : true # setup node_exporter on this node?
node_exporter_port : 9100 # node exporter listen port, 9100 by default
node_exporter_options : '--no-collector.softnet --no-collector.nvme --collector.tcpstat --collector.processes'
#-----------------------------------------------------------------
# VECTOR
#-----------------------------------------------------------------
vector_enabled : true # enable vector log collector?
vector_clean : false # purge vector data dir during init?
vector_data : /data/vector # vector data dir, /data/vector by default
vector_port : 9598 # vector metrics port, 9598 by default
vector_read_from : beginning # vector read from beginning or end
vector_log_endpoint : [ infra ] # if defined, sending vector log to this endpoint.
#================================================================#
# VARS: DOCKER #
#================================================================#
docker_enabled : false # enable docker on this node?
docker_data : /data/docker # docker data directory, /data/docker by default
docker_storage_driver : overlay2 # docker storage driver, can be zfs, btrfs
docker_cgroups_driver: systemd # docker cgroup fs driver : cgroupfs,systemd
docker_registry_mirrors : [] # docker registry mirror list
docker_exporter_port : 9323 # docker metrics exporter port, 9323 by default
docker_image : [] # docker image to be pulled after bootstrap
docker_image_cache : /tmp/docker/*.tgz # docker image cache glob pattern
#================================================================#
# VARS: ETCD #
#================================================================#
#etcd_seq: 1 # etcd instance identifier, explicitly required
etcd_cluster : etcd # etcd cluster & group name, etcd by default
etcd_safeguard : false # prevent purging running etcd instance?
etcd_data : /data/etcd # etcd data directory, /data/etcd by default
etcd_port : 2379 # etcd client port, 2379 by default
etcd_peer_port : 2380 # etcd peer port, 2380 by default
etcd_init : new # etcd initial cluster state, new or existing
etcd_election_timeout : 1000 # etcd election timeout, 1000ms by default
etcd_heartbeat_interval : 100 # etcd heartbeat interval, 100ms by default
etcd_root_password : Etcd.Root # etcd root password for RBAC, change it!
#================================================================#
# VARS: MINIO #
#================================================================#
#minio_seq: 1 # minio instance identifier, REQUIRED
minio_cluster : minio # minio cluster identifier, REQUIRED
minio_user : minio # minio os user, `minio` by default
minio_https : true # use https for minio, true by default
minio_node : '${minio_cluster}-${minio_seq}.pigsty' # minio node name pattern
minio_data : '/data/minio' # minio data dir(s), use {x...y} to specify multi drivers
#minio_volumes: # minio data volumes, override defaults if specified
minio_domain : sss.pigsty # minio external domain name, `sss.pigsty` by default
minio_port : 9000 # minio service port, 9000 by default
minio_admin_port : 9001 # minio console port, 9001 by default
minio_access_key : minioadmin # root access key, `minioadmin` by default
minio_secret_key : S3User.MinIO # root secret key, `S3User.MinIO` by default
minio_extra_vars : '' # extra environment variables
minio_provision : true # run minio provisioning tasks?
minio_alias : sss # alias name for local minio deployment
#minio_endpoint: https://sss.pigsty:9000 # if not specified, overwritten by defaults
minio_buckets : # list of minio bucket to be created
- { name : pgsql }
- { name: meta ,versioning : true }
- { name : data }
minio_users : # list of minio user to be created
- { access_key: pgbackrest ,secret_key: S3User.Backup ,policy : pgsql }
- { access_key: s3user_meta ,secret_key: S3User.Meta ,policy : meta }
- { access_key: s3user_data ,secret_key: S3User.Data ,policy : data }
#================================================================#
# VARS: REDIS #
#================================================================#
#redis_cluster: <CLUSTER> # redis cluster name, required identity parameter
#redis_node: 1 <NODE> # redis node sequence number, node int id required
#redis_instances: {} <NODE> # redis instances definition on this redis node
redis_fs_main : /data/redis # redis main data directory, `/data/redis` by default
redis_exporter_enabled : true # install redis exporter on redis nodes?
redis_exporter_port : 9121 # redis exporter listen port, 9121 by default
redis_exporter_options : '' # cli args and extra options for redis exporter
redis_mode: standalone # redis mode : standalone,cluster,sentinel
redis_conf : redis.conf # redis config template path, except sentinel
redis_bind_address : '0.0.0.0' # redis bind address, empty string will use host ip
redis_max_memory : 1GB # max memory used by each redis instance
redis_mem_policy : allkeys-lru # redis memory eviction policy
redis_password : '' # redis password, empty string will disable password
redis_rdb_save : [ '1200 1' ] # redis rdb save directives, disable with empty list
redis_aof_enabled : false # enable redis append only file?
redis_rename_commands : {} # rename redis dangerous commands
redis_cluster_replicas : 1 # replica number for one master in redis cluster
redis_sentinel_monitor : [] # sentinel master list, works on sentinel cluster only
#================================================================#
# VARS: PGSQL #
#================================================================#
#-----------------------------------------------------------------
# PG_IDENTITY
#-----------------------------------------------------------------
pg_mode: pgsql #CLUSTER # pgsql cluster mode : pgsql,citus,gpsql,mssql,mysql,ivory,polar
# pg_cluster: #CLUSTER # pgsql cluster name, required identity parameter
# pg_seq: 0 #INSTANCE # pgsql instance seq number, required identity parameter
# pg_role: replica #INSTANCE # pgsql role, required, could be primary,replica,offline
# pg_instances: {} #INSTANCE # define multiple pg instances on node in `{port:ins_vars}` format
# pg_upstream: #INSTANCE # repl upstream ip addr for standby cluster or cascade replica
# pg_shard: #CLUSTER # pgsql shard name, optional identity for sharding clusters
# pg_group: 0 #CLUSTER # pgsql shard index number, optional identity for sharding clusters
# gp_role: master #CLUSTER # greenplum role of this cluster, could be master or segment
pg_offline_query : false #INSTANCE # set to true to enable offline queries on this instance
#-----------------------------------------------------------------
# PG_BUSINESS
#-----------------------------------------------------------------
# postgres business object definition, overwrite in group vars
pg_users : [] # postgres business users
pg_databases : [] # postgres business databases
pg_services : [] # postgres business services
pg_hba_rules : [] # business hba rules for postgres
pgb_hba_rules : [] # business hba rules for pgbouncer
# global credentials, overwrite in global vars
pg_dbsu_password : '' # dbsu password, empty string means no dbsu password by default
pg_replication_username : replicator
pg_replication_password : DBUser.Replicator
pg_admin_username : dbuser_dba
pg_admin_password : DBUser.DBA
pg_monitor_username : dbuser_monitor
pg_monitor_password : DBUser.Monitor
#-----------------------------------------------------------------
# PG_INSTALL
#-----------------------------------------------------------------
pg_dbsu : postgres # os dbsu name, postgres by default, better not change it
pg_dbsu_uid : 543 # os dbsu uid and gid, 26 for default postgres users and groups
pg_dbsu_sudo : limit # dbsu sudo privilege, none,limit,all,nopass. limit by default
pg_dbsu_home : /var/lib/pgsql # postgresql home directory, `/var/lib/pgsql` by default
pg_dbsu_ssh_exchange : true # exchange postgres dbsu ssh key among same pgsql cluster
pg_version : 18 # postgres major version to be installed, 18 by default
pg_bin_dir : /usr/pgsql/bin # postgres binary dir, `/usr/pgsql/bin` by default
pg_log_dir : /pg/log/postgres # postgres log dir, `/pg/log/postgres` by default
pg_packages : # pg packages to be installed, alias can be used
- pgsql-main pgsql-common
pg_extensions : [] # pg extensions to be installed, alias can be used
#-----------------------------------------------------------------
# PG_BOOTSTRAP
#-----------------------------------------------------------------
pg_data : /pg/data # postgres data directory, `/pg/data` by default
pg_fs_main : /data/postgres # postgres main data directory, `/data/postgres` by default
pg_fs_backup : /data/backups # postgres backup data directory, `/data/backups` by default
pg_storage_type : SSD # storage type for pg main data, SSD,HDD, SSD by default
pg_dummy_filesize : 64MiB # size of `/pg/dummy`, hold 64MB disk space for emergency use
pg_listen : '0.0.0.0' # postgres/pgbouncer listen addresses, comma separated list
pg_port : 5432 # postgres listen port, 5432 by default
pg_localhost : /var/run/postgresql # postgres unix socket dir for localhost connection
patroni_enabled : true # if disabled, no postgres cluster will be created during init
patroni_mode: default # patroni working mode : default,pause,remove
pg_namespace : /pg # top level key namespace in etcd, used by patroni & vip
patroni_port : 8008 # patroni listen port, 8008 by default
patroni_log_dir : /pg/log/patroni # patroni log dir, `/pg/log/patroni` by default
patroni_ssl_enabled : false # secure patroni RestAPI communications with SSL?
patroni_watchdog_mode: 'off' # patroni watchdog mode : automatic,required,off. off by default
patroni_username : postgres # patroni restapi username, `postgres` by default
patroni_password : Patroni.API # patroni restapi password, `Patroni.API` by default
pg_etcd_password : '' # etcd password for this pg cluster, '' to use pg_cluster
pg_primary_db : postgres # primary database name, used by citus,etc... ,postgres by default
pg_parameters : {} # extra parameters in postgresql.auto.conf
pg_files : [] # extra files to be copied to postgres data directory (e.g. license)
pg_conf: oltp.yml # config template : oltp,olap,crit,tiny. `oltp.yml` by default
pg_max_conn : auto # postgres max connections, `auto` will use recommended value
pg_shared_buffer_ratio : 0.25 # postgres shared buffers ratio, 0.25 by default, 0.1~0.4
pg_io_method : worker # io method for postgres, auto,fsync,worker,io_uring, worker by default
pg_rto: norm # shared rto mode for patroni & haproxy : fast,norm,safe,wide
pg_rpo : 1048576 # recovery point objective in bytes, `1MiB` at most by default
pg_libs : 'pg_stat_statements, auto_explain' # preloaded libraries, `pg_stat_statements,auto_explain` by default
pg_delay : 0 # replication apply delay for standby cluster leader
pg_checksum : true # enable data checksum for postgres cluster?
pg_encoding : UTF8 # database cluster encoding, `UTF8` by default
pg_locale : C # database cluster local, `C` by default
pg_lc_collate : C # database cluster collate, `C` by default
pg_lc_ctype : C # database character type, `C` by default
#pgsodium_key: "" # pgsodium key, 64 hex digit, default to sha256(pg_cluster)
#pgsodium_getkey_script: "" # pgsodium getkey script path, pgsodium_getkey by default
#-----------------------------------------------------------------
# PG_PROVISION
#-----------------------------------------------------------------
pg_provision : true # provision postgres cluster after bootstrap
pg_init : pg-init # provision init script for cluster template, `pg-init` by default
pg_default_roles : # default roles and users in postgres cluster
- { name: dbrole_readonly ,login: false ,comment : role for global read-only access }
- { name: dbrole_offline ,login: false ,comment : role for restricted read-only access }
- { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly] ,comment : role for global read-write access }
- { name: dbrole_admin ,login: false ,roles: [pg_monitor, dbrole_readwrite] ,comment : role for object creation }
- { name: postgres ,superuser: true ,comment : system superuser }
- { name: replicator ,replication: true ,roles: [pg_monitor, dbrole_readonly] ,comment : system replicator }
- { name: dbuser_dba ,superuser: true ,roles: [dbrole_admin] ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 ,comment : pgsql admin user }
- { name: dbuser_monitor ,roles: [pg_monitor] ,pgbouncer: true ,parameters : {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment : pgsql monitor user }
pg_default_privileges : # default privileges when created by admin user
- GRANT USAGE ON SCHEMAS TO dbrole_readonly
- GRANT SELECT ON TABLES TO dbrole_readonly
- GRANT SELECT ON SEQUENCES TO dbrole_readonly
- GRANT EXECUTE ON FUNCTIONS TO dbrole_readonly
- GRANT USAGE ON SCHEMAS TO dbrole_offline
- GRANT SELECT ON TABLES TO dbrole_offline
- GRANT SELECT ON SEQUENCES TO dbrole_offline
- GRANT EXECUTE ON FUNCTIONS TO dbrole_offline
- GRANT INSERT ON TABLES TO dbrole_readwrite
- GRANT UPDATE ON TABLES TO dbrole_readwrite
- GRANT DELETE ON TABLES TO dbrole_readwrite
- GRANT USAGE ON SEQUENCES TO dbrole_readwrite
- GRANT UPDATE ON SEQUENCES TO dbrole_readwrite
- GRANT TRUNCATE ON TABLES TO dbrole_admin
- GRANT REFERENCES ON TABLES TO dbrole_admin
- GRANT TRIGGER ON TABLES TO dbrole_admin
- GRANT CREATE ON SCHEMAS TO dbrole_admin
pg_default_schemas : [ monitor ] # default schemas to be created
pg_default_extensions : # default extensions to be created
- { name: pg_stat_statements ,schema : monitor }
- { name: pgstattuple ,schema : monitor }
- { name: pg_buffercache ,schema : monitor }
- { name: pageinspect ,schema : monitor }
- { name: pg_prewarm ,schema : monitor }
- { name: pg_visibility ,schema : monitor }
- { name: pg_freespacemap ,schema : monitor }
- { name: postgres_fdw ,schema : public }
- { name: file_fdw ,schema : public }
- { name: btree_gist ,schema : public }
- { name: btree_gin ,schema : public }
- { name: pg_trgm ,schema : public }
- { name: intagg ,schema : public }
- { name: intarray ,schema : public }
- { name : pg_repack }
pg_reload : true # reload postgres after hba changes
pg_default_hba_rules : # postgres default host-based authentication rules, order by `order`
- {user : '${dbsu}' ,db: all ,addr: local ,auth: ident ,title: 'dbsu access via local os user ident' ,order : 100 }
- {user : '${dbsu}' ,db: replication ,addr: local ,auth: ident ,title: 'dbsu replication from local os ident' ,order : 150 }
- {user : '${repl}' ,db: replication ,addr: localhost ,auth: pwd ,title: 'replicator replication from localhost',order : 200 }
- {user : '${repl}' ,db: replication ,addr: intra ,auth: pwd ,title: 'replicator replication from intranet' ,order : 250 }
- {user : '${repl}' ,db: postgres ,addr: intra ,auth: pwd ,title: 'replicator postgres db from intranet' ,order : 300 }
- {user : '${monitor}' ,db: all ,addr: localhost ,auth: pwd ,title: 'monitor from localhost with password' ,order : 350 }
- {user : '${monitor}' ,db: all ,addr: infra ,auth: pwd ,title: 'monitor from infra host with password',order : 400 }
- {user : '${admin}' ,db: all ,addr: infra ,auth: ssl ,title: 'admin @ infra nodes with pwd & ssl' ,order : 450 }
- {user : '${admin}' ,db: all ,addr: world ,auth: ssl ,title: 'admin @ everywhere with ssl & pwd' ,order : 500 }
- {user: '+dbrole_readonly',db: all ,addr: localhost ,auth: pwd ,title: 'pgbouncer read/write via local socket',order : 550 }
- {user: '+dbrole_readonly',db: all ,addr: intra ,auth: pwd ,title: 'read/write biz user via password' ,order : 600 }
- {user: '+dbrole_offline' ,db: all ,addr: intra ,auth: pwd ,title: 'allow etl offline tasks from intranet',order : 650 }
pgb_default_hba_rules : # pgbouncer default host-based authentication rules, order by `order`
- {user : '${dbsu}' ,db: pgbouncer ,addr: local ,auth: peer ,title: 'dbsu local admin access with os ident',order : 100 }
- {user: 'all' ,db: all ,addr: localhost ,auth: pwd ,title: 'allow all user local access with pwd' ,order : 150 }
- {user : '${monitor}' ,db: pgbouncer ,addr: intra ,auth: pwd ,title: 'monitor access via intranet with pwd' ,order : 200 }
- {user : '${monitor}' ,db: all ,addr: world ,auth: deny ,title: 'reject all other monitor access addr' ,order : 250 }
- {user : '${admin}' ,db: all ,addr: intra ,auth: pwd ,title: 'admin access via intranet with pwd' ,order : 300 }
- {user : '${admin}' ,db: all ,addr: world ,auth: deny ,title: 'reject all other admin access addr' ,order : 350 }
- {user: 'all' ,db: all ,addr: intra ,auth: pwd ,title: 'allow all user intra access with pwd' ,order : 400 }
#-----------------------------------------------------------------
# PG_BACKUP
#-----------------------------------------------------------------
pgbackrest_enabled : true # enable pgbackrest on pgsql host?
pgbackrest_log_dir : /pg/log/pgbackrest # pgbackrest log dir, `/pg/log/pgbackrest` by default
pgbackrest_method: local # pgbackrest repo method : local,minio,[user-defined...]
pgbackrest_init_backup : true # take a full backup after pgbackrest is initialized?
pgbackrest_repo: # pgbackrest repo : https://pgbackrest.org/configuration.html#section-repository
local : # default pgbackrest repo with local posix fs
path : /pg/backup # local backup directory, `/pg/backup` by default
retention_full_type : count # retention full backups by count
retention_full : 2 # keep 2, at most 3 full backups when using local fs repo
minio : # optional minio repo for pgbackrest
type : s3 # minio is s3-compatible, so s3 is used
s3_endpoint : sss.pigsty # minio endpoint domain name, `sss.pigsty` by default
s3_region : us-east-1 # minio region, us-east-1 by default, useless for minio
s3_bucket : pgsql # minio bucket name, `pgsql` by default
s3_key : pgbackrest # minio user access key for pgbackrest
s3_key_secret : S3User.Backup # minio user secret key for pgbackrest
s3_uri_style : path # use path style uri for minio rather than host style
path : /pgbackrest # minio backup path, default is `/pgbackrest`
storage_port : 9000 # minio port, 9000 by default
storage_ca_file : /etc/pki/ca.crt # minio ca file path, `/etc/pki/ca.crt` by default
block : y # Enable block incremental backup
bundle : y # bundle small files into a single file
bundle_limit : 20MiB # Limit for file bundles, 20MiB for object storage
bundle_size : 128MiB # Target size for file bundles, 128MiB for object storage
cipher_type : aes-256-cbc # enable AES encryption for remote backup repo
cipher_pass : pgBackRest # AES encryption password, default is 'pgBackRest'
retention_full_type : time # retention full backup by time on minio repo
retention_full : 14 # keep full backup for the the last 14 days
#-----------------------------------------------------------------
# PG_ACCESS
#-----------------------------------------------------------------
pgbouncer_enabled : true # if disabled, pgbouncer will not be launched on pgsql host
pgbouncer_port : 6432 # pgbouncer listen port, 6432 by default
pgbouncer_log_dir : /pg/log/pgbouncer # pgbouncer log dir, `/pg/log/pgbouncer` by default
pgbouncer_auth_query : false # query postgres to retrieve unlisted business users?
pgbouncer_poolmode: transaction # pooling mode : transaction,session,statement, transaction by default
pgbouncer_sslmode : disable # pgbouncer client ssl mode, disable by default
pgbouncer_ignore_param : [ extra_float_digits, application_name, TimeZone, DateStyle, IntervalStyle, search_path ]
pg_weight : 100 #INSTANCE # relative load balance weight in service, 100 by default, 0-255
pg_service_provider : '' # dedicate haproxy node group name, or empty string for local nodes by default
pg_default_service_dest : pgbouncer # default service destination if svc.dest='default'
pg_default_services : # postgres default service definitions
- { name: primary ,port: 5433 ,dest: default ,check: /primary ,selector : "[]" }
- { name: replica ,port: 5434 ,dest: default ,check: /read-only ,selector : "[]" , backup : "[? pg_role == `primary` || pg_role == `offline` ]" }
- { name: default ,port: 5436 ,dest: postgres ,check: /primary ,selector : "[]" }
- { name: offline ,port: 5438 ,dest: postgres ,check: /replica ,selector : "[? pg_role == `offline` || pg_offline_query ]" , backup : "[? pg_role == `replica` && !pg_offline_query]" }
pg_vip_enabled : false # enable a l2 vip for pgsql primary? false by default
pg_vip_address : 127.0.0.1 /24 # vip address in `<ipv4>/<mask>` format, require if vip is enabled
pg_vip_interface : eth0 # vip network interface to listen, eth0 by default
pg_dns_suffix : '' # pgsql dns suffix, '' by default
pg_dns_target : auto # auto, primary, vip, none, or ad hoc ip
#-----------------------------------------------------------------
# PG_MONITOR
#-----------------------------------------------------------------
pg_exporter_enabled : true # enable pg_exporter on pgsql hosts?
pg_exporter_config : pg_exporter.yml # pg_exporter configuration file name
pg_exporter_cache_ttls : '1,10,60,300' # pg_exporter collector ttl stage in seconds, '1,10,60,300' by default
pg_exporter_port : 9630 # pg_exporter listen port, 9630 by default
pg_exporter_params : 'sslmode=disable' # extra url parameters for pg_exporter dsn
pg_exporter_url : '' # overwrite auto-generate pg dsn if specified
pg_exporter_auto_discovery : true # enable auto database discovery? enabled by default
pg_exporter_exclude_database : 'template0,template1,postgres' # csv of database that WILL NOT be monitored during auto-discovery
pg_exporter_include_database : '' # csv of database that WILL BE monitored during auto-discovery
pg_exporter_connect_timeout : 200 # pg_exporter connect timeout in ms, 200 by default
pg_exporter_options : '' # overwrite extra options for pg_exporter
pgbouncer_exporter_enabled : true # enable pgbouncer_exporter on pgsql hosts?
pgbouncer_exporter_port : 9631 # pgbouncer_exporter listen port, 9631 by default
pgbouncer_exporter_url : '' # overwrite auto-generate pgbouncer dsn if specified
pgbouncer_exporter_options : '' # overwrite extra options for pgbouncer_exporter
pgbackrest_exporter_enabled : true # enable pgbackrest_exporter on pgsql hosts?
pgbackrest_exporter_port : 9854 # pgbackrest_exporter listen port, 9854 by default
pgbackrest_exporter_options : >
--collect.interval=120
--log.level=info
#-----------------------------------------------------------------
# PG_REMOVE
#-----------------------------------------------------------------
pg_safeguard : false # stop pg_remove running if pg_safeguard is enabled, false by default
pg_rm_data : true # remove postgres data during remove? true by default
pg_rm_backup : true # remove pgbackrest backup during primary remove? true by default
pg_rm_pkg : true # uninstall postgres packages during remove? true by default
...
配置解读 demo/debian 模板是针对 Debian 和 Ubuntu 发行版优化的配置。
支持的发行版 :
Debian 12 (Bookworm) Debian 13 (Trixie) Ubuntu 22.04 LTS (Jammy) Ubuntu 24.04 LTS (Noble) Ubuntu 26.04 LTS (Resolute) 关键特性 :
使用 PGDG APT 软件源 针对 APT 包管理器优化 支持 Debian/Ubuntu 特定的软件包名称 适用场景 :
云服务器(Ubuntu 广泛使用) 容器环境(Debian 常用作基础镜像) 开发测试环境 9.40 - demo/demo Pigsty 公开演示站点配置,展示如何配置 SSL 证书、暴露域名、安装全部扩展
demo/demo 配置模板是 Pigsty 公开演示站点使用的配置文件,展示了如何对外暴露网站、配置 SSL 证书、安装全部扩展插件。
如果您希望在云服务器上搭建自己的公开服务,可以参考此配置模板。
配置概览 配置名称: demo/demo 节点数量: 单节点 配置说明:Pigsty 公开演示站点配置 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64 相关配置:meta ,rich 启用方式:
./configure -c demo/demo [ -i <primary_ip>]
主要特性 此模板在 meta 基础上进行了以下增强:
配置 SSL 证书和自定义域名(如 pigsty.cc) 下载并安装 PostgreSQL 18 所有可用扩展 启用 Docker 并配置镜像加速 部署 MinIO 对象存储 预置多个业务数据库和用户 添加 Redis 主从实例示例 添加 FerretDB MongoDB 兼容集群 添加 Kafka 样例集群 配置内容 源文件地址:pigsty/conf/demo/demo.yml
---
#==============================================================#
# File : demo.yml
# Desc : Pigsty Public Demo Configuration
# Ctime : 2020-05-22
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/conf/demo
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
all :
children :
# infra cluster for proxy, monitor, alert, etc..
infra :
hosts : { 10.10.10.10 : { infra_seq : 1 } }
vars :
nodename : pigsty.cc # overwrite the default hostname
node_id_from_pg : false # do not use the pg identity as hostname
docker_enabled : true # enable docker on this node
docker_registry_mirrors : [ "https://mirror.ccs.tencentyun.com" , "https://docker.1ms.run" ]
# ./pgsql-monitor.yml -l infra # monitor 'external' PostgreSQL instance
pg_exporters : # treat local postgres as RDS for demonstration purpose
20001 : { pg_cluster: pg-foo, pg_seq: 1, pg_host : 10.10.10.10 }
#20002: { pg_cluster: pg-bar, pg_seq: 1, pg_host: 10.10.10.11 , pg_port: 5432 }
#20003: { pg_cluster: pg-bar, pg_seq: 2, pg_host: 10.10.10.12 , pg_exporter_url: 'postgres://dbuser_monitor:DBUser.Monitor@10.10.10.12:5432/postgres?sslmode=disable' }
#20004: { pg_cluster: pg-bar, pg_seq: 3, pg_host: 10.10.10.13 , pg_monitor_username: dbuser_monitor, pg_monitor_password: DBUser.Monitor }
# etcd cluster for ha postgres
etcd : { hosts : { 10.10.10.10 : { etcd_seq: 1 } }, vars : { etcd_cluster : etcd } }
# minio cluster, s3 compatible object storage
minio : { hosts : { 10.10.10.10 : { minio_seq: 1 } }, vars : { minio_cluster : minio } }
# postgres example cluster: pg-meta
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 : pigsty admin user }
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment : read-only viewer for meta database }
- {name: dbuser_grafana ,password: DBUser.Grafana ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for grafana database }
- {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for bytebase database }
- {name: dbuser_kong ,password: DBUser.Kong ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for kong api gateway }
- {name: dbuser_gitea ,password: DBUser.Gitea ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for gitea service }
- {name: dbuser_wiki ,password: DBUser.Wiki ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for wiki.js service }
- {name: dbuser_noco ,password: DBUser.Noco ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for nocodb service }
- {name: dbuser_odoo ,password: DBUser.Odoo ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for odoo service ,createdb: true } #,superuser : true }
- {name: dbuser_mattermost ,password: DBUser.MatterMost ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user for mattermost ,createdb : true }
pg_databases :
- {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions : [ {name : vector},{name: postgis},{name: timescaledb}]}
- {name: grafana ,owner: dbuser_grafana ,revokeconn: true ,comment : grafana primary database }
- {name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment : bytebase primary database }
- {name: kong ,owner: dbuser_kong ,revokeconn: true ,comment : kong api gateway database }
- {name: gitea ,owner: dbuser_gitea ,revokeconn: true ,comment : gitea meta database }
- {name: wiki ,owner: dbuser_wiki ,revokeconn: true ,comment : wiki meta database }
- {name: noco ,owner: dbuser_noco ,revokeconn: true ,comment : nocodb database }
#- {name: odoo ,owner: dbuser_odoo ,revokeconn: true ,comment: odoo main database }
- {name: mattermost ,owner: dbuser_mattermost ,revokeconn: true ,comment : mattermost main database }
pg_hba_rules :
- {user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title : 'allow grafana dashboard access cmdb from infra nodes' }
pg_libs : 'timescaledb,pg_stat_statements, auto_explain' # add timescaledb to shared_preload_libraries
pg_extensions : # extensions to be installed on this cluster
- timescaledb timescaledb_toolkit pg_timeseries periods temporal_tables emaj table_version pg_cron pg_task pg_later pg_background
- postgis pgrouting pointcloud pg_h3 q3c ogr_fdw geoip pg_polyline pg_geohash #mobilitydb
- pgvector vchord pgvectorscale pg_vectorize pg_similarity smlar pg_summarize pg_tiktoken pg4ml #pgml
- pg_search pgroonga pg_bigm zhparser pg_bestmatch vchord_bm25 hunspell
- citus hydra pg_analytics pg_duckdb pg_mooncake duckdb_fdw pg_parquet pg_fkpart pg_partman plproxy #pg_strom
- age hll rum pg_graphql pg_jsonschema jsquery pg_hint_plan hypopg index_advisor pg_plan_filter imgsmlr pg_ivm pg_incremental pgmq pgq pg_cardano omnigres #rdkit
- pg_tle plv8 pllua plprql pldebugger plpgsql_check plprofiler plsh pljava #plr #pgtap #faker #dbt2
- pg_prefix pg_semver pgunit pgpdf pglite_fusion md5hash asn1oid roaringbitmap pgfaceting pgsphere pg_country pg_xenophile pg_currency pg_collection pgmp numeral pg_rational pguint pg_uint128 hashtypes ip4r pg_uri pgemailaddr pg_acl timestamp9 chkpass #pg_duration #debversion #pg_rrule
- pg_gzip pg_bzip pg_zstd pg_http pg_net pg_curl pgjq pgjwt pg_smtp_client pg_html5_email_address url_encode pgsql_tweaks pg_extra_time pgpcre icu_ext pgqr pg_protobuf envvar floatfile pg_readme ddl_historization data_historization pg_schedoc pg_hashlib pg_xxhash shacrypt cryptint pg_ecdsa pgsparql
- pg_idkit pg_uuidv7 permuteseq pg_hashids sequential_uuids topn quantile lower_quantile count_distinct omnisketch ddsketch vasco pgxicor tdigest first_last_agg extra_window_functions floatvec aggs_for_vecs aggs_for_arrays pg_arraymath pg_math pg_random pg_base36 pg_base62 pg_base58 pg_financial
- pg_repack pg_squeeze pg_dirtyread pgfincore pg_cooldown pg_ddlx pg_prioritize pg_checksums pg_readonly pg_upless pg_permissions pgautofailover pg_catcheck preprepare pgcozy pg_orphaned pg_crash pg_cheat_funcs pg_fio pg_savior safeupdate pg_drop_events table_log #pgagent #pgpool
- pg_profile pg_tracing pg_show_plans pg_stat_kcache pg_stat_monitor pg_qualstats pg_store_plans pg_track_settings pg_wait_sampling system_stats pg_meta pgnodemx pg_sqlog bgw_replstatus pgmeminfo toastinfo pg_explain_ui pg_relusage pagevis powa
- passwordcheck supautils pgsodium pg_vault pg_session_jwt pg_anon pg_tde pgsmcrypto pgaudit pgauditlogtofile pg_auth_mon credcheck pgcryptokey pg_jobmon logerrors login_hook set_user pg_snakeoil pgextwlist pg_auditor sslutils pg_noset
- wrappers multicorn odbc_fdw jdbc_fdw mysql_fdw tds_fdw sqlite_fdw pgbouncer_fdw mongo_fdw redis_fdw pg_redis_pubsub kafka_fdw hdfs_fdw firebird_fdw aws_s3 log_fdw #oracle_fdw #db2_fdw
- documentdb orafce pgtt session_variable pg_statement_rollback pg_dbms_metadata pg_dbms_lock pgmemcache #pg_dbms_job
- pglogical pglogical_ticker pgl_ddl_deploy pg_failover_slots db_migrator wal2json wal2mongo decoderbufs decoder_raw mimeo pg_fact_loader pg_bulkload #repmgr
redis-ms : # redis classic primary & replica
hosts : { 10.10.10.10 : { redis_node: 1 , redis_instances : { 6379 : { }, 6380 : { replica_of: '10.10.10.10 6379' }, 6381 : { replica_of : '10.10.10.10 6379' } } } }
vars : { redis_cluster: redis-ms ,redis_password: 'redis.ms' ,redis_max_memory : 64MB }
# ./mongo.yml -l pg-mongo
pg-mongo :
hosts : { 10.10.10.10 : { mongo_seq : 1 } }
vars :
mongo_cluster : pg-mongo
mongo_pgurl : 'postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/grafana'
# Kafka is a pilot module, see: https://pigsty.io/docs/pilot/kafka
kf-main :
hosts : { 10.10.10.10 : { kafka_seq: 1, kafka_role : controller } }
vars :
kafka_cluster : kf-main
kafka_peer_port : 9093
vars : # global variables
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: china # upstream mirror region : default|china|europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
cc : { domain: pigsty.cc ,path : "/www/pigsty.cc" ,cert: /etc/cert/pigsty.cc.crt ,key : /etc/cert/pigsty.cc.key }
minio : { domain: m.pigsty.cc ,endpoint : "${admin_ip}:9001" ,scheme: https ,websocket : true }
postgrest : { domain: api.pigsty.cc ,endpoint : "127.0.0.1:8884" }
pgadmin : { domain: adm.pigsty.cc ,endpoint : "127.0.0.1:8885" }
pgweb : { domain: cli.pigsty.cc ,endpoint : "127.0.0.1:8886" }
bytebase : { domain: ddl.pigsty.cc ,endpoint : "127.0.0.1:8887" }
jupyter : { domain: lab.pigsty.cc ,endpoint : "127.0.0.1:8888" , websocket : true }
gitea : { domain: git.pigsty.cc ,endpoint : "127.0.0.1:8889" }
wiki : { domain: wiki.pigsty.cc ,endpoint : "127.0.0.1:9002" }
noco : { domain: noco.pigsty.cc ,endpoint : "127.0.0.1:9003" }
supa : { domain: supa.pigsty.cc ,endpoint : "10.10.10.10:8000" ,websocket : true }
dify : { domain: dify.pigsty.cc ,endpoint : "10.10.10.10:8001" ,websocket : true }
odoo : { domain: odoo.pigsty.cc ,endpoint : "127.0.0.1:8069" ,websocket : true }
mm : { domain: mm.pigsty.cc ,endpoint : "10.10.10.10:8065" ,websocket : true }
# scp -r ~/pgsty/cc/cert/* pj:/etc/cert/ # copy https certs
# scp -r ~/dev/pigsty.cc/public pj:/www/pigsty.cc # copy pigsty.cc website
node_etc_hosts : [ "${admin_ip} i.pigsty sss.pigsty" ]
node_timezone : Asia/Hong_Kong
node_ntp_servers :
- pool cn.pool.ntp.org iburst
- pool ${admin_ip} iburst # assume non-admin nodes does not have internet access
pgbackrest_enabled : false # do not take backups since this is disposable demo env
# keep 3GiB metrics data at most on demo env
vmetrics_options : >-
-retentionPeriod=15d
-retention.maxDiskSpaceUsageBytes=3GiB
# install all postgresql18 extensions
pg_version : 18 # default postgres version
repo_extra_packages : [ pg18-core ,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]
pg_extensions : [ pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl ] #,pg18-olap]
#----------------------------------------------#
# 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
...
配置解读 demo/demo 模板是 Pigsty 的 公开演示配置 ,展示了完整的生产级部署示例。
关键特性 :
配置 HTTPS 证书和自定义域名 安装所有可用的 PostgreSQL 扩展 集成 Redis、FerretDB、Kafka 等组件 配置 Docker 镜像加速 适用场景 :
搭建公开演示站点 需要完整功能展示的场景 学习 Pigsty 高级配置 注意事项 :
需要准备 SSL 证书文件 需要配置 DNS 解析 部分扩展在 ARM64 架构不可用 9.41 - demo/minio 四节点 x 四盘位的高可用多节点多盘 MinIO 集群演示
demo/minio 配置模板演示了如何部署一套四节点 x 四盘位、总计十六盘的高可用 MinIO 集群,提供 S3 兼容的对象存储服务。
更多教程,请参考 MINIO 模块文档。
配置概览 配置名称: demo/minio 节点数量: 四节点 配置说明:高可用多节点多盘 MinIO 集群演示 适用系统:el8, el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64, aarch64 相关配置:meta 启用方式:
./configure -c demo/minio
备注:这是一个四节点模版,您需要在生成配置后修改其他三个节点的 IP 地址
配置内容 源文件地址:pigsty/conf/demo/minio.yml
---
#==============================================================#
# File : minio.yml
# Desc : pigsty: 4 node x 4 disk MNMD minio clusters
# Ctime : 2023-01-07
# Mtime : 2025-12-12
# Docs : https://pigsty.io/docs/minio
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
# One pass installation with:
# ./deploy.yml
#==============================================================#
# 1. minio-1 @ 10.10.10.10:9000 - - (9002) svc <-x 10.10.10.9:9002
# 2. minio-2 @ 10.10.10.11:9000 -xx- (9002) svc <-x <----------------
# 3. minio-3 @ 10.10.10.12:9000 -xx- (9002) svc <-x sss.pigsty:9002
# 4. minio-4 @ 10.10.10.12:9000 - - (9002) svc <-x (intranet dns)
#==============================================================#
# use minio load balancer service (9002) instead of direct access (9000)
# mcli alias set sss https://sss.pigsty:9002 minioadmin S3User.MinIO
#==============================================================#
# https://min.io/docs/minio/linux/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.html
# MINIO_VOLUMES="https://minio-{1...4}.pigsty:9000/data{1...4}/minio"
all :
children :
# infra cluster for proxy, monitor, alert, etc..
infra : { hosts : { 10.10.10.10 : { infra_seq : 1 } } }
# minio cluster with 4 nodes and 4 drivers per node
minio :
hosts :
10.10.10.10 : { minio_seq: 1 , nodename : minio-1 }
10.10.10.11 : { minio_seq: 2 , nodename : minio-2 }
10.10.10.12 : { minio_seq: 3 , nodename : minio-3 }
10.10.10.13 : { minio_seq: 4 , nodename : minio-4 }
vars :
minio_cluster : minio
minio_data : '/data{1...4}'
minio_buckets : # list of minio bucket to be created
- { name : pgsql }
- { name: meta ,versioning : true }
- { name : data }
minio_users : # list of minio user to be created
- { access_key: pgbackrest ,secret_key: S3User.Backup ,policy : pgsql }
- { access_key: s3user_meta ,secret_key: S3User.Meta ,policy : meta }
- { access_key: s3user_data ,secret_key: S3User.Data ,policy : data }
# bind a node l2 vip (10.10.10.9) to minio cluster (optional)
node_cluster : minio
vip_enabled : true
vip_vrid : 128
vip_address : 10.10.10.9
vip_interface : eth1
# expose minio service with haproxy on all nodes
haproxy_services :
- name : minio # [REQUIRED] service name, unique
port : 9002 # [REQUIRED] service port, unique
balance : leastconn # [OPTIONAL] load balancer algorithm
options : # [OPTIONAL] minio health check
- option httpchk
- option http-keep-alive
- http-check send meth OPTIONS uri /minio/health/live
- http-check expect status 200
servers :
- { name: minio-1 ,ip: 10.10.10.10 ,port: 9000 ,options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
- { name: minio-2 ,ip: 10.10.10.11 ,port: 9000 ,options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
- { name: minio-3 ,ip: 10.10.10.12 ,port: 9000 ,options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
- { name: minio-4 ,ip: 10.10.10.13 ,port: 9000 ,options : 'check-ssl ca-file /etc/pki/ca.crt check port 9000' }
vars :
version : v4.3.0 # pigsty version string
admin_ip : 10.10.10.10 # admin node ip address
region: default # upstream mirror region : default|china|europe
infra_portal : # infra services exposed via portal
home : { domain : i.pigsty } # default domain name
# domain names to access minio web console via nginx web portal (optional)
minio : { domain: m.pigsty ,endpoint : "10.10.10.10:9001" ,scheme: https ,websocket : true }
minio10 : { domain: m10.pigsty ,endpoint : "10.10.10.10:9001" ,scheme: https ,websocket : true }
minio11 : { domain: m11.pigsty ,endpoint : "10.10.10.11:9001" ,scheme: https ,websocket : true }
minio12 : { domain: m12.pigsty ,endpoint : "10.10.10.12:9001" ,scheme: https ,websocket : true }
minio13 : { domain: m13.pigsty ,endpoint : "10.10.10.13:9001" ,scheme: https ,websocket : true }
minio_endpoint : https://sss.pigsty:9002 # explicit overwrite minio endpoint with haproxy port
node_etc_hosts : [ "10.10.10.9 sss.pigsty" ] # domain name to access minio from all nodes (required)
#----------------------------------------------#
# PASSWORD : https://pigsty.io/docs/setup/security/
#----------------------------------------------#
grafana_admin_password : pigsty
haproxy_admin_password : pigsty
minio_secret_key : S3User.MinIO
... 配置解读 demo/minio 模板是 MinIO 生产级部署的参考配置,展示了多节点多盘 (MNMD) 架构。
关键特性 :
多节点多盘架构 :4 节点 × 4 盘 = 16 盘纠删码组L2 VIP 高可用 :通过 Keepalived 绑定虚拟 IPHAProxy 负载均衡 :9002 端口统一访问入口细粒度权限 :为不同应用创建独立用户和存储桶访问方式 :
# 使用 mcli 配置 MinIO 别名(通过 HAProxy 负载均衡)
mcli alias set sss https://sss.pigsty:9002 minioadmin S3User.MinIO
# 列出存储桶
mcli ls sss/
# 使用控制台
# 访问 https://m.pigsty 或 https://m10-m13.pigsty
适用场景 :
需要 S3 兼容对象存储的环境 PostgreSQL 备份存储(pgBackRest 远程仓库) 大数据和 AI 工作负载的数据湖 需要高可用对象存储的生产环境 注意事项 :
每个节点需要准备 4 块独立磁盘挂载到 /data1 - /data4 生产环境建议至少 4 节点以实现纠删码冗余 VIP 需要正确配置网络接口(vip_interface) 9.42 - build/oss Pigsty 开源版离线软件包构建环境配置
build/oss 配置模板是 Pigsty 开源版离线软件包的构建环境配置,用于在多个操作系统上批量构建离线安装包。
此配置仅供开发者和贡献者使用。
配置概览 配置名称: build/oss 节点数量: 七节点(el9, el10, d12, d13, u22, u24, u26) 配置说明:Pigsty 开源版离线软件包构建环境 适用系统:el9, el10, d12, d13, u22, u24, u26 适用架构:x86_64 启用方式:
cp conf/build/oss.yml pigsty.yml
备注:这是一个固定 IP 地址的构建模板,仅供内部使用
配置内容 源文件地址:pigsty/conf/build/oss.yml
---
#==============================================================#
# File : oss.yml
# Desc : Pigsty 3-node building env (PG18)
# Ctime : 2024-10-22
# Mtime : 2026-05-01
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
all :
vars :
version : v4.3.0
admin_ip : 10.10.10.24
region : china
proxy_env :
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn,*.pigsty.cc"
# building spec
pg_version : 18
repo_modules : infra,node,pgsql
repo_packages : [ node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-utility, extra-modules ]
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]
# OSS
cache_pkg_dir : 'dist/${version}'
repo_extra_packages : [ pg18-core ,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]
# PRO
#cache_pkg_dir: 'dist/${version}/pro'
#repo_extra_packages: [
# pg18-main,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,
# pg17-main,pg17-time,pg17-gis,pg17-rag,pg17-fts,pg17-olap,pg17-feat,pg17-lang,pg17-type,pg17-util,pg17-func,pg17-admin,pg17-stat,pg17-sec,pg17-fdw,pg17-sim,pg17-etl,
# pg16-main,pg16-time,pg16-gis,pg16-rag,pg16-fts,pg16-olap,pg16-feat,pg16-lang,pg16-type,pg16-util,pg16-func,pg16-admin,pg16-stat,pg16-sec,pg16-fdw,pg16-sim,pg16-etl,
# pg15-main,pg15-time,pg15-gis,pg15-rag,pg15-fts,pg15-olap,pg15-feat,pg15-lang,pg15-type,pg15-util,pg15-func,pg15-admin,pg15-stat,pg15-sec,pg15-fdw,pg15-sim,pg15-etl,
# pg14-main,pg14-time,pg14-gis,pg14-rag,pg14-fts,pg14-olap,pg14-feat,pg14-lang,pg14-type,pg14-util,pg14-func,pg14-admin,pg14-stat,pg14-sec,pg14-fdw,pg14-sim,pg14-etl,
# infra-extra, kafka, java-runtime, sealos, tigerbeetle, polardb, ivorysql
#]
children :
el9 : { hosts : { 10.10.10.9 : { pg_cluster: el9 ,pg_seq: 1 ,pg_role : primary }}}
el10 : { hosts : { 10.10.10.10 : { pg_cluster: el10 ,pg_seq: 1 ,pg_role : primary }}}
d12 : { hosts : { 10.10.10.12 : { pg_cluster: d12 ,pg_seq: 1 ,pg_role : primary }}}
d13 : { hosts : { 10.10.10.13 : { pg_cluster: d13 ,pg_seq: 1 ,pg_role : primary }}}
u22 : { hosts : { 10.10.10.22 : { pg_cluster: u22 ,pg_seq: 1 ,pg_role : primary }}}
u24 : { hosts : { 10.10.10.24 : { pg_cluster: u24 ,pg_seq: 1 ,pg_role : primary }}}
u26 : { hosts : { 10.10.10.26 : { pg_cluster: u26 ,pg_seq: 1 ,pg_role : primary }}}
etcd : { hosts : { 10.10.10.24 : { etcd_seq: 1 }}, vars : { etcd_cluster : etcd }}
infra :
hosts :
10.10.10.9 : { infra_seq: 1, admin_ip: 10.10.10.9 ,ansible_host : el9 }
10.10.10.10 : { infra_seq: 2, admin_ip: 10.10.10.10 ,ansible_host : el10 }
10.10.10.12 : { infra_seq: 3, admin_ip: 10.10.10.12 ,ansible_host : d12 }
10.10.10.13 : { infra_seq: 4, admin_ip: 10.10.10.13 ,ansible_host : d13 }
10.10.10.22 : { infra_seq: 5, admin_ip: 10.10.10.22 ,ansible_host : u22 }
10.10.10.24 : { infra_seq: 6, admin_ip: 10.10.10.24 ,ansible_host : u24 }
10.10.10.26 : { infra_seq: 7, admin_ip: 10.10.10.26 ,ansible_host : u26 }
vars : { node_tune : oltp }
...
配置解读 build/oss 模板是 Pigsty 开源版离线软件包的构建配置。
构建内容 :
PostgreSQL 18 及所有分类扩展包 基础设施软件包(Prometheus、Grafana、Nginx 等) 节点软件包(监控代理、工具等) 额外模块(extra-modules) 支持的操作系统 :
EL9 (Rocky/Alma/RHEL 9) EL10 (Rocky 10 / RHEL 10) Debian 12 (Bookworm) Debian 13 (Trixie) Ubuntu 22.04 (Jammy) Ubuntu 24.04 (Noble) Ubuntu 26.04 (Resolute) 构建流程 :
# 1. 准备构建环境
cp conf/build/oss.yml pigsty.yml
# 2. 在各节点上下载软件包
./infra.yml -t repo_build
# 3. 打包离线安装包
make cache
适用场景 :
Pigsty 开发者构建新版本 贡献者测试新扩展 企业用户自定义离线包 9.43 - build/pro Pigsty 专业版离线软件包构建环境配置(多版本)
build/pro 配置模板是 Pigsty 专业版离线软件包的构建环境配置,包含 PostgreSQL 14-18 全版本及额外商业组件。
此配置仅供开发者和贡献者使用。
配置概览 配置名称: build/pro 节点数量: 六节点(el9, el10, d12, d13, u22, u24) 配置说明:Pigsty 专业版离线软件包构建环境(多版本) 适用系统:el9, el10, d12, d13, u22, u24 适用架构:x86_64 启用方式:
cp conf/build/pro.yml pigsty.yml
备注:这是一个固定 IP 地址的构建模板,仅供内部使用
配置内容 源文件地址:pigsty/conf/build/pro.yml
---
#==============================================================#
# File : pro.yml
# Desc : Pigsty 6-node pro building env (PG 14-18)
# Ctime : 2024-10-22
# Mtime : 2025-12-15
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#
all :
vars :
version : v4.3.0
admin_ip : 10.10.10.24
region : china
proxy_env :
no_proxy : "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn,*.pigsty.cc"
# building spec
pg_version : 18
cache_pkg_dir : 'dist/${version}/pro'
repo_modules : infra,node,pgsql
pg_extensions : []
repo_packages : [
node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-utility, extra-modules,
pg18-main,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,
pg17-main,pg17-time,pg17-gis,pg17-rag,pg17-fts,pg17-olap,pg17-feat,pg17-lang,pg17-type,pg17-util,pg17-func,pg17-admin,pg17-stat,pg17-sec,pg17-fdw,pg17-sim,pg17-etl,
pg16-main,pg16-time,pg16-gis,pg16-rag,pg16-fts,pg16-olap,pg16-feat,pg16-lang,pg16-type,pg16-util,pg16-func,pg16-admin,pg16-stat,pg16-sec,pg16-fdw,pg16-sim,pg16-etl,
pg15-main,pg15-time,pg15-gis,pg15-rag,pg15-fts,pg15-olap,pg15-feat,pg15-lang,pg15-type,pg15-util,pg15-func,pg15-admin,pg15-stat,pg15-sec,pg15-fdw,pg15-sim,pg15-etl,
pg14-main,pg14-time,pg14-gis,pg14-rag,pg14-fts,pg14-olap,pg14-feat,pg14-lang,pg14-type,pg14-util,pg14-func,pg14-admin,pg14-stat,pg14-sec,pg14-fdw,pg14-sim,pg14-etl,
infra-extra, kafka, java-runtime, sealos, tigerbeetle, polardb, ivorysql
]
children :
#el8: { hosts: { 10.10.10.8: { pg_cluster: el8 ,pg_seq: 1 ,pg_role: primary }}}
el9 : { hosts : { 10.10.10.9 : { pg_cluster: el9 ,pg_seq: 1 ,pg_role : primary }}}
el10 : { hosts : { 10.10.10.10 : { pg_cluster: el10 ,pg_seq: 1 ,pg_role : primary }}}
d12 : { hosts : { 10.10.10.12 : { pg_cluster: d12 ,pg_seq: 1 ,pg_role : primary }}}
d13 : { hosts : { 10.10.10.13 : { pg_cluster: d13 ,pg_seq: 1 ,pg_role : primary }}}
u22 : { hosts : { 10.10.10.22 : { pg_cluster: u22 ,pg_seq: 1 ,pg_role : primary }}}
u24 : { hosts : { 10.10.10.24 : { pg_cluster: u24 ,pg_seq: 1 ,pg_role : primary }}}
etcd : { hosts : { 10.10.10.24 : { etcd_seq: 1 }}, vars : { etcd_cluster : etcd }}
infra :
hosts :
#10.10.10.8: { infra_seq: 9, admin_ip: 10.10.10.8 ,ansible_host: el8 } #, ansible_python_interpreter: /usr/bin/python3.12 }
10.10.10.9 : { infra_seq: 1, admin_ip: 10.10.10.9 ,ansible_host : el9 }
10.10.10.10 : { infra_seq: 2, admin_ip: 10.10.10.10 ,ansible_host : el10 }
10.10.10.12 : { infra_seq: 3, admin_ip: 10.10.10.12 ,ansible_host : d12 }
10.10.10.13 : { infra_seq: 4, admin_ip: 10.10.10.13 ,ansible_host : d13 }
10.10.10.22 : { infra_seq: 5, admin_ip: 10.10.10.22 ,ansible_host : u22 }
10.10.10.24 : { infra_seq: 6, admin_ip: 10.10.10.24 ,ansible_host : u24 }
vars : { node_tune : oltp }
...
配置解读 build/pro 模板是 Pigsty 专业版离线软件包的构建配置,比开源版包含更多内容。
与 OSS 版的区别 :
包含 PostgreSQL 14-18 全部五个大版本 包含额外商业/企业组件:Kafka、PolarDB、IvorySQL 等 包含 Java 运行时和 Sealos 等工具 输出目录为 dist/${version}/pro/ 构建内容 :
PostgreSQL 14、15、16、17、18 全版本 每个版本的全部分类扩展包 Kafka 消息队列 PolarDB 和 IvorySQL 内核 TigerBeetle 分布式数据库 Sealos 容器平台 适用场景 :
企业客户需要多版本支持 需要 Oracle/MySQL 兼容内核 需要 Kafka 消息队列集成 需要长期支持版本(LTS) 构建流程 :
# 1. 准备构建环境
cp conf/build/pro.yml pigsty.yml
# 2. 在各节点上下载软件包
./infra.yml -t repo_build
# 3. 打包离线安装包
make cache-pro
10 - Linux 软件仓库 用于交付 PostgreSQL 扩展的基础设施和软件包仓库
Pigsty 为主流 Linux 发行版 提供了 PostgreSQL 扩展仓库,其中包含 340+ 额外的 PostgreSQL 扩展。
Pigsty 扩展仓库旨在与 PGDG 官方仓库配合使用,共同使用时可以安装多达 510 个 PostgreSQL 扩展 。
兼容性概览 系统 / 架构 代码 x86_64 aarch64 EL8 el8 18 17 16 15 14 18 17 16 15 14 EL9 el9 18 17 16 15 14 18 17 16 15 14 EL10 el10 18 17 16 15 14 18 17 16 15 14 Debian 12 d12 18 17 16 15 14 18 17 16 15 14 Debian 13 d13 18 17 16 15 14 18 17 16 15 14 Ubuntu 22.04 u22 18 17 16 15 14 18 17 16 15 14 Ubuntu 24.04 u24 18 17 16 15 14 18 17 16 15 14 Ubuntu 26.04 u26 18 17 16 15 14 18 17 16 15 14
快速上手 你可以使用 pig 命令行工具来方便地启用 infra 和 pgsql 仓库:
curl https://repo.pigsty.io/pig | bash # 下载安装最新版本的 pig 命令行工具
pig repo add all -u # 添加 Linux / PGDG / Pigsty 仓库并更新缓存
curl https://repo.pigsty.cc/pig | bash # 从中国镜像站下载安装最新版本的 pig 命令行工具
pig repo add -u # 添加 Linux / PGDG / Pigsty 仓库并更新缓存
手工添加 您也可以使用经典的 apt / dnf / yum 命令,将仓库手工添加到系统中。
# 将 Pigsty 的 GPG 公钥添加到系统密钥链中,以验证软件包签名
curl -fsSL https://repo.pigsty.io/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg
# 获取 Debian / Ubuntu 发行版的代号(bookworm, trixie, jammy, noble, resolute),并将相应的上游仓库地址写入 /etc/apt/sources.list.d/ 中
distro_codename = $( lsb_release -cs)
sudo tee /etc/apt/sources.list.d/pigsty-io.list > /dev/null <<EOF
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/infra generic main
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/pgsql/${distro_codename} ${distro_codename} main
EOF
# 刷新 APT 仓库缓存
sudo apt update
# 将 Pigsty 的 GPG 公钥添加到系统密钥链中,以验证软件包签名
curl -fsSL https://repo.pigsty.io/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
# 将 Pigsty 仓库的定义写入 /etc/yum.repos.d/ 目录中
sudo tee /etc/yum.repos.d/pigsty-io.repo > /dev/null <<-'EOF'
[pigsty-infra]
name=Pigsty Infra for $basearch
baseurl=https://repo.pigsty.io/yum/infra/$basearch
skip_if_unavailable = 1
enabled = 1
priority = 1
gpgcheck = 1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty
module_hotfixes=1
[pigsty-pgsql]
name=Pigsty PGSQL For el$releasever.$basearch
baseurl=https://repo.pigsty.io/yum/pgsql/el$releasever.$basearch
skip_if_unavailable = 1
enabled = 1
priority = 1
gpgcheck = 1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty
module_hotfixes=1
EOF
# 刷新 YUM 仓库缓存
sudo yum makecache;
所有的 RPM / DEB 软件包都使用指纹为 (B9BD8B20) 的 GPG 密钥 进行签名,以确保软件包的完整性。
仓库组成 Pigsty 仓库由两个主要部分组成:INFRA 和 PGSQL ,提供 x86_64 和 aarch64 架构下的 DEB / RPM 包。
INFRA 仓库中的软件包与 PostgreSQL / Linux 大版本无关,包括 Prometheus、Grafana、以及一些 PostgreSQL 管理工具,
通常由 Go 等语言编写的,只有芯片架构(x86_64 | aarch64)的区别。
Linux 软件包 x86_64 aarch64 EL rpm✓ ✓ Debian deb✓ ✓
PGSQL 仓库中的软件包通常特定于 Linux 大版本(例如 el9, d12),也通常与 PostgreSQL 大版本相关(例如 pg17,pg16)。
这个仓库中包含了 PostgreSQL 内核分支、扩展插件与工具,通常由类 C 语言编写。
兼容性详情 OS 系统代码 厂商 大版本 小版本 全名 PG 大版本 备注 el7.x86_64EL 7 7.9 CentOS 7 x86 15 14 13 EOL el8.x86_64EL 8 8.10 RockyLinux 8 x86 18 17 16 15 14 即将 EOL el8.aarch64EL 8 8.10 RockyLinux 8 ARM 18 17 16 15 14 即将 EOL el9.x86_64EL 9 9.7 RockyLinux 9 x86 18 17 16 15 14 OK el9.aarch64EL 9 9.7 RockyLinux 9 ARM 18 17 16 15 14 OK el10.x86_64EL 10 10.1 RockyLinux 10 x86 18 17 16 15 14 OK el10.aarch64EL 10 10.1 RockyLinux 10 ARM 18 17 16 15 14 OK d11.x86_64Debian 11 11.11 Debian 11 x86 17 16 15 14 13 EOL d11.aarch64Debian 11 11.11 Debian 11 ARM 17 16 15 14 13 EOL d12.x86_64Debian 12 12.13 Debian 12 x86 18 17 16 15 14 OK d12.aarch64Debian 12 12.13 Debian 12 ARM 18 17 16 15 14 OK d13.x86_64Debian 13 13.3 Debian 13 x86 18 17 16 15 14 OK d13.aarch64Debian 13 13.3 Debian 13 ARM 18 17 16 15 14 OK u22.x86_64Ubuntu 22 22.04.5 Ubuntu 22.04 x86 18 17 16 15 14 OK u22.aarch64Ubuntu 22 22.04.5 Ubuntu 22.04 ARM 18 17 16 15 14 OK u24.x86_64Ubuntu 24 24.04.4 Ubuntu 24.04 x86 18 17 16 15 14 OK u24.aarch64Ubuntu 24 24.04.4 Ubuntu 24.04 ARM 18 17 16 15 14 OK u26.x86_64Ubuntu 26 26.04.0 Ubuntu 26.04 x86 18 17 16 15 14 OK u26.aarch64Ubuntu 26 26.04.0 Ubuntu 26.04 ARM 18 17 16 15 14 OK
源代码 用于构建仓库内软件的源代码文件位于以下仓库中:
10.1 - PGDG 仓库 PostgreSQL 官方 APT/YUM 仓库
Pigsty PGSQL 仓库旨在与 PostgreSQL PGDG 官方仓库 配合使用。
Pigsty 依赖 PGDG 仓库中原生的 PostgreSQL 内核软件包,在此基础上提供了额外的 340+ 扩展插件。
PGDG Pigsty 镜像仓库最后同步于:2025-12-29 12:00:00
快速上手 您可以安装 pig CLI 工具,并使用它添加 pgdg / pigsty 仓库(推荐):
pig repo add pgdg # 添加 PGDG 仓库
pig repo add pgdg -u # 添加 PGDG 仓库,并更新本地缓存
pig repo add pgdg -u --region= default # 强制使用全球默认区域的仓库(postgresql.org)
pig repo add pgdg -u --region= china # 使用中国镜像仓库 (repo.pigsty.cc)
pig repo add pgsql -u # pgsql = pgdg + pigsty-pgsql (同时添加 Pigsty 与 PGDG 官方仓库)
pig repo add -u # all = node + pgsql (pgdg + pigsty) + infra,一次性添加所有仓库
镜像 2025年5月中旬,PGDG 关闭了 rsync/ftp 同步渠道,导致全球几乎所有 PGDG 镜像站失去同步。根据观察,目前只有 YANDEX,XTOM,PIGSTY 提供定期同步。
Pigsty 在中国区域提供了 PGDG 镜像的子集,更新频率约为一周一更新。对于 EL 7-10,Debian 11-13,Ubuntu 22.04 - 26.04 提供 x86_64 与 arm64 架构的镜像仓库。覆盖范围为所有生命周期内的 PG 大版本(PG14 - 19alpha)。
2025-11 更新通知:阿里云/清华TUNA 恢复更新
目前阿里云/清华 TUNA 镜像站已经恢复 PGDG 仓库的同步。
仓库配置 EL YUM/DNF 仓库 - { name: pgdg14 ,description: 'PostgreSQL 14' ,module: pgsql ,releases: [7,8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/14/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/14/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/14/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg15 ,description: 'PostgreSQL 15' ,module: pgsql ,releases: [7,8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/15/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/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,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/16/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/16/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg17 ,description: 'PostgreSQL 17' ,module: pgsql ,releases: [ 8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/17/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/17/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/17/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg18 ,description: 'PostgreSQL 18' ,module: pgsql ,releases: [ 8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/18/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/18/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg19-beta ,description: 'PostgreSQL 19 Beta' ,module: beta ,releases: [ 8,9,10] ,arch: [x86_64, aarch64] ,baseurl : { default: 'https://download.postgresql.org/pub/repos/yum/testing/19/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/testing/19/redhat/rhel-$releasever-$basearch' ,europe : 'https://mirrors.xtom.de/postgresql/repos/yum/testing/19/redhat/rhel-$releasever-$basearch' }}
Debian / Ubuntu APT 仓库 - { name: pgdg ,description: 'PGDG' ,module: pgsql ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://apt.postgresql.org/pub/repos/apt/ ${distro_codename}-pgdg main' ,china : 'https://repo.pigsty.cc/apt/pgdg/ ${distro_codename}-pgdg main' }}
- { name: pgdg-beta ,description: 'PGDG Beta' ,module: beta ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl : { default : 'http://apt.postgresql.org/pub/repos/apt/ ${distro_codename}-pgdg-testing main 19' ,china : 'https://repo.pigsty.cc/apt/pgdg/ ${distro_codename}-pgdg-testing main 19' }}
APT GPG 密钥 PGDG APT 仓库使用以下 GPG 密钥签名: B97B0AFCAA1A47F044F244A07FCC7D46ACCC4CF8 (ACCC4CF8)
MD5 校验和为 f54c5c1aa1329dc26e33b29762faaec4,详情参考 https://www.postgresql.org/download/linux/debian/
sudo curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
. /etc/os-release
sudo sh -c "echo 'deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $VERSION_CODENAME -pgdg main' > /etc/apt/sources.list.d/pgdg.list"
sudo curl -fsSL https://repo.pigsty.cc/apt/pgdg/ACCC4CF8.key -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
. /etc/os-release
sudo sh -c "echo 'deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://repo.pigsty.cc/apt/pgdg/ $VERSION_CODENAME -pgdg main' > /etc/apt/sources.list.d/pgdg.list"
YUM GPG 密钥 PGDG YUM 仓库使用 https://ftp.postgresql.org/pub/repos/yum/keys/ 中的一系列密钥进行签名。请自行按需选取使用。
兼容性 OS 系统代码 厂商 大版本 PG 大版本 备注 el7.x86_64 EL 7 18 17 16 15 14 EOL el8.x86_64 EL 8 18 17 16 15 14 即将 EOL el8.aarch64 EL 8 18 17 16 15 14 即将 EOL el9.x86_64 EL 9 18 17 16 15 14 OK el9.aarch64 EL 9 18 17 16 15 14 OK el10.x86_64 EL 10 18 17 16 15 14 OK el10.aarch64 EL 10 18 17 16 15 14 OK d11.x86_64 Debian 11 18 17 16 15 14 EOL d11.aarch64 Debian 11 18 17 16 15 14 EOL d12.x86_64 Debian 12 18 17 16 15 14 OK d12.aarch64 Debian 12 18 17 16 15 14 OK d13.x86_64 Debian 13 18 17 16 15 14 OK d13.aarch64 Debian 13 18 17 16 15 14 OK u22.x86_64 Ubuntu 22 18 17 16 15 14 OK u22.aarch64 Ubuntu 22 18 17 16 15 14 OK u24.x86_64 Ubuntu 24 18 17 16 15 14 OK u24.aarch64 Ubuntu 24 18 17 16 15 14 OK u26.x86_64 Ubuntu 26 18 17 16 15 14 OK u26.aarch64 Ubuntu 26 18 17 16 15 14 OK
10.2 - GPG 密钥 导入 Pigsty 仓库使用的 GPG 公钥以验证软件包签名完整性
你可以通过检查 GPG 签名来验证从 Pigsty 仓库下载的软件包的完整性,本文会介绍如何导入用于签名软件包的 GPG 密钥。
你也可以生成自己的 GPG 密钥,构建自己的仓库,并用它来签发你自己的软件包。
摘要 Pigsty 仓库中所有的 RPM / DEB 软件包都使用 GPG 密钥(指纹:B9BD8B20)进行签名,以确保软件包的完整性和来源的可信度。
完整摘要: 9592A7BC7A682E7333376E09E7935D8DB9BD8B20 Ruohang Feng (Pigsty) rh@vonng.com
pub rsa4096 2024-07-16 [SC]
9592A7BC7A682E7333376E09E7935D8DB9BD8B20
uid [ultimate] Ruohang Feng (Pigsty) <rh@vonng.com>
sub rsa4096 2024-07-16 [E]
你可以在这里找到 Pigsty 使用的 GPG 公钥:
默认地址:https://repo.pigsty.io/key 中国镜像:https://repo.pigsty.cc/key 导入 在 RHEL 兼容的 Linux 发行版上,你可以使用以下命令导入此密钥:
curl -fsSL https://repo.pigsty.io/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
curl -fsSL https://repo.pigsty.cc/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
在 Debian / Ubuntu 兼容的 Linux 发行版上,你可以使用以下命令导入此密钥:
curl -fsSL https://repo.pigsty.io/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg
curl -fsSL https://repo.pigsty.cc/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg
公钥 Pigsty 仓库使用的 GPG 公钥内容如下:
-----BEGIN PGP PUBLIC KEY BLOCK-----
mQINBGaV5PwBEACbErI+7yOrsXTT3mR83O6Fw9WyHJqozhyNPF3dA1gAtWpfWqd4
S9x6vBjVwUbIRn21jYgov0hDiaLABNQhRzifvVr0r1IjBW8lhA8zJGaO42Uz0aBW
YIkajOklsXgYMX+gSmy5WXzM31sDQVMnzptHh9dwW067hMM5pJKDslu2pLMwSb9K
QgIFcYsaR0taBkcDg4dNu1gncriD/GcdXIS0/V4R82DIYeIqj2S0lt0jDTACbUz3
C6esrTw2XerCeHKHb9c/V+KMhqvLJOOpy/aJWLrTGBoaH7xw6v0qg32OYiBxlUj9
VEzoQbDfbRkR+jlxiuYP3scUs/ziKrSh+0mshVbeuLRSNfuHLa7C4xTEnATcgD1J
MZeMaJXIcDt+DN+1aHVQjY5YNvr5wA3ykxW51uReZf7/odgqVW3+1rhW5pd8NQKQ
qoVUHOtIrC9KaiGfrczEtJTNUxcNZV9eBgcKHYDXB2hmR2pIf7WvydgXTs/qIsXg
SIzfKjisi795Dd5GrvdLYXVnu9YzylWlkJ5rjod1wnSxkI/CcCJaoPLnXZA9KV7A
cpMWWaUEXP/XBIwIU+vxDd1taBIaPIOv1KIdzvG7QqAQtf5Lphi5HfaGvBud/CVt
mvWhRPJMr1J0ER2xAgU2iZR7dN0vSF6zDqc0W09RAoC0nDS3tupDX2BrOwARAQAB
tCRSdW9oYW5nIEZlbmcgKFBpZ3N0eSkgPHJoQHZvbm5nLmNvbT6JAlEEEwEIADsW
IQSVkqe8emguczM3bgnnk12Nub2LIAUCZpXk/AIbAwULCQgHAgIiAgYVCgkICwIE
FgIDAQIeBwIXgAAKCRDnk12Nub2LIOMuEACBLVc09O4icFwc45R3KMvOMu14Egpn
UkpmBKhErjup0TIunzI0zZH6HG8LGuf6XEdH4ItCJeLg5349UE00BUHNmxk2coo2
u4Wtu28LPqmxb6sqpuRAaefedU6vqfs7YN6WWp52pVF1KdOHkIOcgAQ9z3ZHdosM
I/Y/UxO2t4pjdCAfJHOmGPrbgLcHSMpoLLxjuf3YIwS5NSfjNDd0Y8sKFUcMGLCF
5P0lv5feLLdZvh2Una34UmHKhZlXC5E3vlY9bf/LgsRzXRFQosD0RsCXbz3Tk+zF
+j/eP3WhUvJshqIDuY6eJYCzMjiA8sM5gety+htVJuD0mewp+qAhjxE0d4bIr4qO
BKQzBt9tT2ackCPdgW42VPS+IZymm1oMET0hgZfKiVpwsKO6qxeWn4RW2jJ0zkUJ
MsrrxOPFdZQAtuFcLwa5PUAHHs6XQT2vzxDpeE9lInQ14lshofU5ZKIeb9sbvb/w
P+xnDqvZ1pcotEIBvDK0S0jHbHHqtioIUdDFvdCBlBlYP1TQRNPlJ7TJDBBvhj8i
fmjQsYSV1u36aHOJVGYNHv+SyJpVd3nHCZn97ADM9qHnDm7xljyHXPzIx4FMmBGJ
UTiLH5yxa1xhWr42Iv3TykaQJVbpydmBuegFR8WbWitAvVqI3HvRG+FalLsjJruc
8YDAf7gHdj/937kCDQRmleT8ARAAmJxscC76NZzqFBiaeq2+aJxOt1HGPqKb4pbz
jLKRX9sFkeXuzhfZaNDljnr2yrnQ75rit9Aah/loEhbSHanNUDCNmvOeSEISr9yA
yfOnqlcVOtcwWQK57n6MvlCSM8Js3jdoSmCFHVtdFFwxejE5ok0dk1VFYDIg6DRk
ZBMuxGO7ZJW7TzCxhK4AL+NNYA2wX6b+IVMn6CA9kwNwCNrrnGHR1sblSxZp7lPo
+GsqzYY0LXGR2eEicgKd4lk38gaO8Q4d1mlpX95vgdhGKxR+CM26y9QU0qrO1hXP
Fw6lX9HfIUkVNrqAa1mzgneYXivnLvcj8gc7bFAdweX4MyBHsmiPm32WqjUJFAmw
kcKYaiyfDJ+1wusa/b+7RCnshWc8B9udYbXfvcpOGgphpUuvomKT8at3ToJfEWmR
BzToYYTsgAAX8diY/X53BHCE/+MhLccglEUYNZyBRkTwDLrS9QgNkhrADaTwxsv1
8PwnVKve/ZxwOU0QGf4ZOhA2YQOE5hkRDR5uY2OHsOS5vHsd9Y6kNNnO8EBy99d1
QiBJOW3AP0nr4Cj1/NhdigAujsYRKiCAuPT7dgqART58VU4bZ3PgonMlziLe7+ht
YYxV+wyP6LVqicDd0MLLvG7r/JOiWuABOUxsFFaRecehoPJjeAEQxnWJjedokXKL
HVOFaEkAEQEAAYkCNgQYAQgAIBYhBJWSp7x6aC5zMzduCeeTXY25vYsgBQJmleT8
AhsMAAoJEOeTXY25vYsgG8sP/3UdsWuiwTsf/x4BTW82K+Uk9YwZDnUNH+4dUMED
bKT1C6CbuSZ7Mnbi2rVsmGzOMs9MehIx6Ko8/iCR2OCeWi8Q+wM+iffAfWuT1GK6
7f/VIfoYBUWEa+kvDcPgEbd5Tu7ZdUO/jROVBSlXRSjzK9LpIj7GozBTJ8Vqy5x7
oqbWPPEYtGDVHime8o6f5/wfhNgL3mFnoq6srK7KhwACwfTXlNqAlGiXGa30Yj+b
Cj6IvmxoII49E67/ovMEmzDCb3RXiaL6OATy25P+HQJvWvAam7Qq5Xn+bZg65Mup
vXq3zoX0a7EKXc5vsJVNtTlXO1ATdYszKP5uNzkHrNAN52VRYaowq1vPy/MVMbSI
rL/hTFKr7ZNhmC7jmS3OuJyCYQsfEerubtBUuc/W6JDc2oTI3xOG1S2Zj8f4PxLl
H7vMG4E+p6eOrUGw6VQXjFsH9GtwhkPh/ZGMKENb2+JztJ02674Cok4s5c/lZFKz
mmRUcNjX2bm2K0GfGG5/hAog/CHCeUZvwIh4hZLkdeJ1QsIYpN8xbvY7QP6yh4VB
XrL18+2sontZ45MsGResrRibB35x7IrCrxZsVtRJZthHqshiORPatgy+AiWcAtEv
UWEnnC1xBSasNebw4fSE8AJg9JMCRw+3GAetlotOeW9q7PN6yrXD9rGuV/QquQNd
/c7w
=4rRi
-----END PGP PUBLIC KEY BLOCK-----
使用 如果你想要分发自己的仓库并使用自己的 GPG 密钥进行签名,以下是简单介绍:
安装 GPG 软件包 brew install gnupg pinentry-mac
sudo apt install gnupg2 pinentry-curses
sudo dnf install gnupg2 pinentry-curses
生成 GPG 密钥 你可以使用以下命令生成一个新的 GPG 密钥对:
导入 GPG 私钥 如果你有一个 GPG 私钥文件(例如 mykey.secret),你可以使用以下命令导入它:
gpg --import mykey.secret
列出 GPG 密钥 你可以列出已经导入的 GPG 公钥和私钥:
$ gpg --list-key
[ keyboxd]
---------
pub rsa4096 2024-07-16 [ SC]
9592A7BC7A682E7333376E09E7935D8DB9BD8B20
uid [ unknown] Ruohang Feng ( Pigsty) <rh@vonng.com>
sub rsa4096 2024-07-16 [ E]
$ gpg --list-secret-key
[ keyboxd]
---------
sec rsa4096 2024-07-16 [ SC]
9592A7BC7A682E7333376E09E7935D8DB9BD8B20
uid [ unknown] Ruohang Feng ( Pigsty) <rh@vonng.com>
ssb rsa4096 2024-07-16 [ E]
签名 RPM 包 如果你想要用 GPG 私钥签名你的 RPM 包,可以在 ~/.rpmmacros 文件中指定 GPG 密钥:
%_signature gpg
%_gpg_path ~/.gnupg
%_gpg_name B9BD8B20
%_gpg_digest_algo sha256
这里的 %_gpg_name 是你的 GPG 密钥的指纹,请将 Pigsty 密钥指纹 B9BD8B20 替换为你自己的密钥指纹。
rpm --addsign yourpackage.rpm
签名 DEB 包 如果你想要用 GPG 私钥签名你的 DEB 包,可以在 reprepro 配置文件中指定 GPG 密钥:
Origin : Pigsty
Label : Pigsty INFRA
Codename : generic
Architectures : amd64 arm64
Components : main
Description : pigsty apt repository for infra components
SignWith : 9592A7BC7A682E7333376E09E7935D8DB9BD8B20
同理,将这里的 SignWith 替换为你自己的 GPG 密钥指纹即可,reprepro 会自动使用它进行签名。
10.3 - INFRA 仓库 可观测性/PostgreSQL 工具软件仓库,Linux 发行版大版本无关的软件包
pigsty-infra 仓库包含与任何 PostgreSQL 版本和 Linux 主版本无关的通用软件包,
包括 Prometheus & Grafana 技术栈、PostgreSQL 管理工具,以及许多用 Go 编写的实用工具。
该仓库由 冯若航 (Vonng ) @ Pigsty 维护,
您可以在 https://github.com/pgsty/infra-pkg 找到所有构建源代码与命令。
为 RHEL / Debian / Ubuntu 发行版提供预构建的 RPM / DEB 包,支持 x86_64 和 aarch64 架构。
托管于 Cloudflare CDN,提供免费的全球访问。
Linux 包类型 x86_64 aarch64 EL rpm✓ ✓ Debian deb✓ ✓
Infra 仓库的更新记录可以参考 发布 - Infra 变更日志 。
快速上手 您可以使用 pig CLI 工具添加 pigsty-infra 仓库,它会自动从 apt/yum/dnf 中选择合适的包管理器。
curl https://repo.pigsty.io/pig | bash # 下载并安装 pig CLI 工具
pig repo add infra # 将 pigsty-infra 仓库文件添加到您的系统
pig repo update # 使用 apt / dnf 更新本地仓库缓存
# 在中国大陆或 Cloudflare 不可用时使用
curl https://repo.pigsty.cc/pig | bash # 从中国 CDN 镜像安装 pig
pig repo add infra # 将 pigsty-infra 仓库文件添加到您的系统
pig repo update # 使用 apt / dnf 更新本地仓库缓存
# 您可以使用以下命令管理 infra 仓库:
pig repo add infra -u # 添加仓库文件,并更新缓存
pig repo add infra -ru # 删除所有现有仓库,添加仓库并创建缓存
pig repo set infra # = pigsty repo add infra -ru
pig repo add all # 将 infra、node、pgsql 仓库添加到您的系统
pig repo set all # 删除现有仓库,添加上述仓库并更新缓存
手动设置 您也可以不使用 pig CLI 工具直接使用此仓库,手动将其添加到您的 Linux 操作系统仓库列表中:
APT 仓库 在 Debian / Ubuntu 兼容的 Linux 发行版上,您可以手动添加 GPG 密钥 和 APT 仓库文件:
# 将 Pigsty 的 GPG 公钥添加到您的系统密钥链以验证包签名,或者直接信任
curl -fsSL https://repo.pigsty.io/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg
# 获取 Debian / Ubuntu 发行版代号(bookworm, trixie, jammy, noble, resolute)
# 并将相应的上游仓库地址写入 APT List 文件
distro_codename = $( lsb_release -cs)
sudo tee /etc/apt/sources.list.d/pigsty-infra.list > /dev/null <<EOF
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/infra generic main
EOF
# 刷新 APT 仓库缓存
sudo apt update
# 在中国大陆或 Cloudflare 不可用时使用
# 将 Pigsty 的 GPG 公钥添加到您的系统密钥链以验证包签名,或者直接信任
curl -fsSL https://repo.pigsty.cc/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg
# 获取 Debian / Ubuntu 发行版代号(bookworm, trixie, jammy, noble, resolute)
# 并将相应的上游仓库地址写入 APT List 文件
distro_codename = $( lsb_release -cs)
sudo tee /etc/apt/sources.list.d/pigsty-infra.list > /dev/null <<EOF
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.cc/apt/infra generic main
EOF
# 刷新 APT 仓库缓存
sudo apt update
# 如果您不想信任任何 GPG 密钥,直接信任仓库
distro_codename = $( lsb_release -cs)
sudo tee /etc/apt/sources.list.d/pigsty-infra.list > /dev/null <<EOF
deb [trust=yes] https://repo.pigsty.io/apt/infra generic main
EOF
sudo apt update
YUM 仓库 在 RHEL 兼容的 Linux 发行版上,您可以手动添加 GPG 密钥 和 YUM 仓库文件:
# 将 Pigsty 的 GPG 公钥添加到您的系统密钥链以验证包签名
curl -fsSL https://repo.pigsty.io/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
# 将 Pigsty 仓库定义文件添加到 /etc/yum.repos.d/ 目录
sudo tee /etc/yum.repos.d/pigsty-infra.repo > /dev/null <<-'EOF'
[pigsty-infra]
name=Pigsty Infra for $basearch
baseurl=https://repo.pigsty.io/yum/infra/$basearch
skip_if_unavailable = 1
enabled = 1
priority = 1
gpgcheck = 1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty
module_hotfixes=1
EOF
# 刷新 YUM/DNF 仓库缓存
sudo yum makecache;
# 在中国大陆或 Cloudflare 不可用时使用
# 将 Pigsty 的 GPG 公钥添加到您的系统密钥链以验证包签名
curl -fsSL https://repo.pigsty.cc/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
# 将 Pigsty 仓库定义文件添加到 /etc/yum.repos.d/ 目录
sudo tee /etc/yum.repos.d/pigsty-infra.repo > /dev/null <<-'EOF'
[pigsty-infra]
name=Pigsty Infra for $basearch
baseurl=https://repo.pigsty.cc/yum/infra/$basearch
skip_if_unavailable = 1
enabled = 1
priority = 1
gpgcheck = 1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty
module_hotfixes=1
EOF
# 刷新 YUM/DNF 仓库缓存
sudo yum makecache;
# 如果您不想信任任何 GPG 密钥,直接信任仓库
sudo tee /etc/yum.repos.d/pigsty-infra.repo > /dev/null <<-'EOF'
[pigsty-infra]
name=Pigsty Infra for $basearch
baseurl=https://repo.pigsty.io/yum/infra/$basearch
skip_if_unavailable = 1
enabled = 1
priority = 1
gpgcheck = 0
module_hotfixes=1
EOF
sudo yum makecache;
10.3.1 - 软件清单 Infra 仓库中可用的软件清单
Grafana 技术栈 Victoria 技术栈 自行安装使用 victoria grafana 数据源插件时注意
Pigsty 将 victoria 数据源扩展拆分为特定架构的专用分包,因此如果您选择自行安装这些插件到您自己的 grafana 中使用时,
请在 /etc/grafana/grafana.ini 中配置以下参数,以允许使用未签名的插件。
allow_loading_unsigned_plugins = victoriametrics-logs-datasource,victoriametrics-metrics-datasource
Prometheus 技术栈 指标导出器 对象存储 数据库 PostgreSQL 相关工具、数据库管理系统和其他实用程序
工具 Pig 包管理器、PostgreSQL 工具和其他数据库相关实用程序
AI AI Agent,MCP 工具箱,编码 IDE,Python/Go/Node 工具……
10.3.2 - 发布日志 pigsty-infra 仓库变更日志和可观测性包发布说明
2026-05-01 名称 旧版本 新版本 备注 prometheus3.11.2 3.11.3 alertmanager0.32.0 0.32.1 victoria-metrics1.140.0 1.142.0 victoria-metrics-cluster1.140.0 1.142.0 VictoriaMetrics 配套组件 vmutils1.140.0 1.142.0 VictoriaMetrics 配套组件 victoria-traces0.8.1 0.8.2 tigerbeetle0.17.1 0.17.2 loki3.6.7 3.6.7 obsolete,保持冻结 promtail3.6.7 3.6.7 obsolete,保持冻结 logcli3.6.7 3.6.7 随 Loki obsolete,保持冻结 hugo0.160.1 0.161.1 seaweedfs4.21 4.22 rustfs1.0.0-alpha.94 1.0.0-b1 预发布版本线 sabiql1.11.0 1.11.1 timescaledb-tools0.18.2 0.19.0 重新构建 timescaledb-tune Linux 二进制 agentsview0.25.0 0.26.0 claude2.1.119 2.1.123 通过 8118 代理下载并核验 stalwart0.16.0 0.16.2 opencode1.14.24 1.14.30 uv0.11.7 0.11.8 vip-manager4.0.0 4.2.0 直链元数据更新 crush0.62.1 0.64.0 直链元数据更新 code1.115.0 1.118.1 直链元数据更新 pig1.4.0 1.4.1 仅更新元信息
2026-04-25 名称 旧版本 新版本 备注 grafana13.0.0 13.0.1 直链元数据更新 vector0.54.0 0.55.0 直链元数据更新 keepalived_exporter1.7.0 1.7.1 seaweedfs4.20 4.21 tigerbeetle0.17.0 0.17.1 agentsview0.22.2 0.25.0 claude2.1.114 2.1.119 通过 8118 代理下载并核验 codex0.121.0 0.125.0 stalwart0.15.5 0.16.0 opencode1.4.11 1.14.24 crush0.57.0 0.62.1 直链元数据更新 rclone1.73.4 1.73.5 直链元数据更新 code-server4.115.0 4.117.0 直链元数据更新
2026-04-19 名称 旧版本 新版本 备注 victoria-logs1.49.0 1.50.0 主包 vlagent1.49.0 1.50.0 VictoriaLogs 配套组件 vlogscli1.49.0 1.50.0 VictoriaLogs 配套组件 victoria-traces0.8.0 0.8.1 dblab0.37.1 0.38.0 grafana-victoriametrics-ds0.23.4 0.24.0 grafana-plugins12.3.0 13.0.0 noarch 插件包,手工归集 garage2.2.0 2.3.0 rustfs1.0.0-alpha.93 1.0.0-alpha.94 claude2.1.107 2.1.114 按版本化模板重构并收敛到最新 stable codex0.121.0-alpha.7 0.121.0 切换到稳定版并重新构建 genai-toolbox1.0.0 1.1.0 同步收录 genai-toolbox 项目构建产物 postgrest14.9 14.10 opencode1.4.3 1.4.11 改为版本化缓存并重新构建 uv0.11.6 0.11.7 nodejs24.14.1 24.15.0 保持在 24.x 策略线 minio20260325000000 20260417000000 直链元数据更新;pgsty fork 构建刷新 mcli20260321000000 20260417000000 直链元数据更新;pgsty fork 构建刷新 sabiql1.10.0 1.11.0 etcd3.6.8 3.6.10 统一软件包版本 pig1.3.4 1.4.0
2026-04-14 名称 旧版本 新版本 备注 prometheus3.10.0 3.11.2 alertmanager0.31.1 0.32.0 node_exporter1.10.2 1.11.1 mongodb_exporter0.49.0 0.50.0 victoria-metrics1.138.0 1.140.0 victoria-metrics-cluster1.138.0 1.140.0 VictoriaMetrics 配套组件 vmutils1.138.0 1.140.0 VictoriaMetrics 配套组件 victoria-logs1.48.0 1.49.0 vlagent1.48.0 1.49.0 VictoriaLogs 配套组件 vlogscli1.48.0 1.49.0 VictoriaLogs 配套组件 grafana12.4.1 13.0.0 主版本升级 duckdb1.5.0 1.5.2 dblab0.34.3 0.37.1 grafana-victoriametrics-ds0.23.1 0.23.4 grafana-infinity-ds3.7.4 3.8.0 seaweedfs4.17 4.20 rustfs1.0.0-alpha.89 1.0.0-alpha.93 改为使用带版本号的发布资产 v2ray5.47.0 5.48.0 xray26.2.6 26.3.27 agentsview0.15.0 0.22.2 claude2.1.81 2.1.107 重新构建;Makefile 改为从版本化 bucket 拉取 codex0.116.0 0.121.0-alpha.7 预发布链升级;重新构建 maddy0.8.2 0.9.3 genai-toolbox0.27.0 1.0.0 仅元数据更新;上游已更名为 mcp-toolbox npgsqlrest3.11.1 3.12.0 postgrest14.7 14.9 rainfrog0.3.17 0.3.18 sqlcmd1.9.0 1.10.0 opencode1.2.27 1.4.3 重新构建 uv0.10.12 0.11.6 golang1.26.1 1.26.2 nodejs24.14.0 24.14.1 保持在 24.x 策略线 pgschema1.7.4 1.9.0 crush0.51.2 0.57.0 rclone1.73.2 1.73.4 code1.112.0 1.115.0 code-server4.112.0 4.115.0 tigerbeetle0.16.77 0.17.0 tigerfs0.5.0 0.6.0 sabiql1.8.2 1.10.0 hugo0.158.0 0.160.1 etcd3.6.9 3.6.8 冻结在 3.6.8,并修正 README loki3.6.7 3.6.7 保持启用,暂不更新 promtail3.6.7 3.6.7 保持启用,暂不更新 pg_exporter1.2.1 1.2.2 直链元数据更新 pig1.3.2 1.3.4 直链元数据更新 pgflo0.0.15 - 已移除
2026-03-21 名称 旧版本 新版本 备注 grafana12.4.0 12.4.1 pgbackrest_exporter0.22.0 0.23.0 redis_exporter1.81.0 1.82.0 victoria-logs1.47.0 1.48.0 vlagent1.47.0 1.48.0 vlogscli1.47.0 1.48.0 victoria-traces0.7.1 0.8.0 duckdb1.4.4 1.5.0 pg_timetable6.2.0 6.3.0 pgschema1.4.2 1.7.4 pgstream- 1.0.1 新增 tigerbeetle0.16.75 0.16.77 grafana-victorialogs-ds0.26.2 0.26.3 grafana-infinity-ds3.7.3 3.7.4 caddy2.11.1 2.11.2 npgsqlrest3.10.0 3.11.1 postgrest14.5 14.7 opencode1.2.17 1.2.27 pev21.20.2 1.21.0 golang1.26.0 1.26.1 vector0.53.0 0.54.0 rclone1.73.1 1.73.2 code-server4.109.5 4.112.0 code1.109.4 1.112.0 seaweedfs4.15 4.17 uv0.10.8 0.10.12 codex0.110.0 0.116.0 v2ray5.44.1 5.47.0 sabiql1.6.2 1.8.2 sql-studio- 0.1.51 新增 rainfrog- 0.3.17 新增 agentsview0.10.0 0.15.0 crush- 0.51.2 新增 tigerfs- 0.5.0 新增 victoria-metrics1.137.0 1.138.0 victoria-metrics-cluster1.137.0 1.138.0 vmutils1.137.0 1.138.0 hugo0.157.0 0.158.0 rustfs1.0.0-alpha.85 1.0.0-alpha.89 mysqld_exporter0.18.0 0.19.0 pg_exporter1.2.0 1.2.1 pig1.3.1 1.3.2 minio20260214 20260325000000 mcli20260213 20260321000000 claude2.1.68 2.1.81 ivroysql5.1 5.3
2026-03-05 名称 旧版本 新版本 备注 asciinema3.1.0 3.2.0 grafana-infinity-ds3.7.2 3.7.3 victoria-metrics1.136.0 1.137.0 victoria-metrics-cluster1.136.0 1.137.0 vmutils1.136.0 1.137.0 hugo0.155.3 0.157.0 opencode1.2.15 1.2.17 rustfs1.0.0-alpha.83 1.0.0-alpha.85 seaweedfs4.13 4.15 tigerbeetle0.16.74 0.16.75 uv0.10.4 0.10.8 codex0.105.0 0.110.0 claude2.1.59 2.1.68 xray- 26.2.6 新增 gost- 2.12.0 新增 sabiql- 1.6.2 新增 agentsview- 0.10.0 新增
2026-02-26 名称 旧版本 新版本 备注 grafana12.3.3 12.4.0 prometheus3.9.1 3.10.0 mongodb_exporter0.47.2 0.49.0 victoria-logs1.45.0 1.47.0 vlagent1.45.0 1.47.0 vlogscli1.45.0 1.47.0 tigerbeetle0.16.73 0.16.74 loki3.6.6 3.6.7 promtail3.6.6 3.6.7 logcli3.6.6 3.6.7 grafana-victorialogs-ds0.25.0 0.26.2 grafana-victoriametrics-ds0.22.0 0.23.1 grafana-infinity-ds3.7.1 3.7.2 caddy2.10.2 2.11.1 npgsqlrest3.8.0 3.10.0 opencode1.2.10 1.2.15 nodejs24.13.1 24.14.0 pev21.20.1 1.20.2 claude2.1.45 2.1.59 codex0.104.0 0.105.0 pig1.2.0 1.3.0
2026-02-22 名称 旧版本 新版本 备注 victoria-metrics1.135.0 1.136.0 victoria-metrics-cluster1.135.0 1.136.0 vmutils1.135.0 1.136.0 loki3.6.5 3.6.6 promtail3.6.5 3.6.6 logcli3.6.5 3.6.6 opencode1.2.6 1.2.10 pig1.1.2 1.2.0 stalwart- 0.15.5 新增 maddy- 0.8.2 新增
2026-02-18 名称 旧版本 新版本 备注 grafana12.3.2 12.3.3 grafana-victorialogs-ds0.24.1 0.25.0 grafana-victoriametrics-ds0.21.0 0.22.0 grafana-infinity-ds3.7.0 3.7.1 redis_exporter1.80.2 1.81.0 etcd3.6.7 3.6.8 dblab0.34.2 0.34.3 tigerbeetle0.16.72 0.16.73 seaweedfs4.09 4.13 rustfs1.0.0-alpha.82 1.0.0-alpha.83 uv0.10.0 0.10.4 kafka4.1.1 4.2.0 npgsqlrest3.7.0 3.8.0 postgrest14.4 14.5 opencode1.1.59 1.2.6 genai-toolbox0.25.0 0.27.0 claude2.1.37 2.1.45 rclone1.73.0 1.73.1 code-server4.108.2 4.109.2 code1.109.2 1.109.4
2026-02-12 名称 旧版本 新版本 备注 alertmanager0.31.0 0.31.1 tigerbeetle0.16.70 0.16.72 grafana-infinity-ds3.7.0 3.7.1 nodejs24.13.0 24.13.1 opencode1.1.53 1.1.59 golang1.25.7 1.26.0 minio20251203120000 20260214120000 pgsty fork pig1.1.0 1.1.1
2026-02-08 名称 旧版本 新版本 备注 alertmanager0.30.1 0.31.0 victoria-metrics1.134.0 1.135.0 victoria-metrics-cluster1.134.0 1.135.0 vmutils1.134.0 1.135.0 victoria-logs1.43.1 1.45.0 vlagent1.43.1 1.45.0 vlogscli1.43.1 1.45.0 grafana-victorialogs-ds0.23.5 0.24.1 grafana-victoriametrics-ds0.20.1 0.21.0 tigerbeetle0.16.68 0.16.70 loki3.1.1 3.6.5 promtail3.0.0 3.6.5 logcli3.1.1 3.6.5 redis_exporter1.80.1 1.80.2 timescaledb-tools0.18.1 0.18.2 seaweedfs4.06 4.09 rustfs1.0.0-alpha.80 1.0.0-alpha.82 uv0.9.26 0.10.0 garage2.1.0 2.2.0 headscale0.27.1 0.28.0 hugo0.154.5 0.155.2 pev21.20.0 1.20.1 postgrest14.3 14.4 npgsqlrest3.4.7 3.7.0 opencode1.1.34 1.1.53 golang1.25.6 1.25.7 nodejs24.12.0 24.13.0 claude2.1.19 2.1.37 vector0.52.0 0.53.0 code1.108.0 1.109.0 code-server4.108.0 4.108.2 rclone1.72.1 1.73.0 pg_exporter1.1.2 1.2.0 grafana12.3.1 12.3.2 pig1.0.0 1.1.0 cloudflared2026.1.1 2026.2.0
2026-01-25 名称 旧版本 新版本 备注 alertmanager0.30.0 0.30.1 victoria-metrics1.133.0 1.134.0 victoria-traces0.5.1 0.7.1 grafana-victorialogs-ds0.23.3 0.23.5 grafana-victoriametrics-ds0.20.0 0.20.1 npgsqlrest3.4.3 3.4.7 claude2.1.9 2.1.19 opencode1.1.23 1.1.34 caddy- 2.10.2 新增 hugo- 0.154.5 新增 cloudflared- 2026.1.1 新增 headscale- 0.27.1 新增 pig0.9.0 1.0.0 duckdb1.4.3 1.4.4
2026-01-16 名称 旧版本 新版本 备注 prometheus3.8.1 3.9.1 victoria-metrics1.132.0 1.133.0 tigerbeetle0.16.65 0.16.68 kafka4.0.0 4.1.1 grafana-victoriametrics-ds0.19.7 0.20.0 grafana-victorialogs-ds0.23.2 0.23.3 grafana-infinity-ds3.6.0 3.7.0 uv0.9.18 0.9.26 seaweedfs4.01 4.06 rustfsalpha.71 alpha.80 v2ray5.28.0 5.44.1 sqlcmd1.8.0 1.9.0 opencode1.0.223 1.1.23 claude2.1.1 2.1.9 golang1.25.5 1.25.6 asciinema3.0.1 3.1.0 code1.107.0 1.108.0 code-server4.107.0 4.108.0 npgsqlrest3.3.0 3.4.3 genai-toolbox0.24.0 0.25.0 pg_exporter1.1.1 1.1.2 pig0.9.0 0.9.1
2026-01-08 名称 旧版本 新版本 备注 pg_exporter1.1.01.1.1新增 pg_timeline 采集器 npgsqlrest3.3.3新增 postgrest14.3新增 opencode1.0.223新增 code-server4.107.0新增 claude2.0.762.1.1更新 genai-toolbox0.23.00.24.0移除损坏的 oracle 驱动 golang1.25.5新增 nodejs24.12.0新增
2025-12-25 名称 旧版本 新版本 备注 pig0.8.00.9.0例行更新 etcd3.6.63.6.7例行更新 uv- 0.9.18新增 PY 包管理器 ccm- 2.0.76新增 claude code asciinema- 3.0.1新增命令行录屏工具 ivorysql5.05.1grafana12.3.012.3.1vector0.51.10.52.0prometheus3.8.03.8.1alertmanager0.29.00.30.0victoria-logs1.41.01.43.1pgbackrest_exporter0.21.00.22.0grafana-victorialogs-ds0.22.40.23.2
2025-12-16 名称 旧版本 新版本 备注 victoria-metrics1.131.01.132.0victoria-logs1.40.01.41.0blackbox_exporter0.27.00.28.0duckdb1.4.21.4.3rclone1.72.01.72.1pev21.17.01.19.0pg_exporter1.0.31.1.0pig0.7.40.8.0genai-toolbox0.22.00.23.0minio2025090716130920251203120000by pgsty
2025-12-04 名称 旧版本 新版本 备注 rustfs- 1.0.0-a71新增 seaweedfs- 4.1.0新增 garage- 2.1.0新增 rclone1.71.21.72.0vector0.51.00.51.1prometheus3.7.33.8.0victoria-metrics0.130.00.131.0victoria-logs0.38.00.40.0victoria-traces- 0.5.1新增 grafana-victorialogs-ds0.22.10.22.4redis_exporter1.80.01.80.1mongodb_exporter0.47.10.47.2genai-toolbox0.21.00.22.0
2025-11-23 名称 旧版本 新版本 备注 pgschema- 1.4.2新增 pgflo- 0.0.15新增 vector0.51.00.51.1问题修复 sealos5.0.15.1.1etcd3.6.53.6.6duckdb1.4.11.4.2pg_exporter1.0.21.0.3pig0.7.10.7.2grafana12.1.012.3.0pg_timetable6.1.06.2.0genai-toolbox0.16.00.21.0timescaledb-tools0.18.00.18.1从 PGSQL 移入 INFRA 仓库 timescaledb-event-streamer0.12.00.20.0tigerbeetle0.16.600.16.65victoria-metrics1.129.11.130.0victoria-logs1.37.21.38.0grafana-victorialogs-ds0.21.40.22.1grafana-victoriametrics-ds0.19.60.19.7grafana-plugins12.0.012.3.0
2025-11-11 名称 旧版本 新版本 备注 grafana12.1.012.2.1下载地址发生变化 prometheus3.6.03.7.3pushgateway1.11.11.11.2alertmanager0.28.10.29.0nginx_exporter1.5.01.5.1node_exporter1.9.11.10.2pgbackrest_exporter0.20.00.21.0redis_exporter1.77.01.80.0duckdb1.4.01.4.1dblab0.33.00.34.2pg_timetable5.13.06.1.0vector0.50.00.51.0rclone1.71.11.71.2victoria-metrics1.126.01.129.1victoria-logs1.35.01.37.2grafana-victorialogs-ds0.21.00.21.4grafana-victoriametrics-ds0.19.40.19.6grafana-infinity-ds3.5.03.6.0genai-toolbox0.16.00.18.0pev21.16.01.17.0pig0.6.20.7.1
2025-10-18 名称 旧版本 新版本 备注 prometheus3.5.03.6.0nginx_exporter1.4.21.5.0mysqld_exporter0.17.20.18.0redis_exporter1.75.01.77.0mongodb_exporter0.47.00.47.1victoria-metrics1.121.01.126.0victoria-logs1.25.11.35.0duckdb1.3.21.4.0etcd3.6.43.6.5restic0.18.00.18.1tigerbeetle0.16.540.16.60grafana-victorialogs-ds0.19.30.21.0grafana-victoriametrics-ds0.18.30.19.4grafana-infinity-ds3.3.03.5.0genai-toolbox0.9.00.16.0grafana12.1.012.2.0vector0.49.00.50.0rclone1.70.31.71.1minio2025072315540220250907161309mcli2025072105280820250813083541
2025-08-15 名称 旧版本 新版本 备注 grafana12.0.012.1.0pg_exporter1.0.11.0.2pig0.6.00.6.1vector0.48.00.49.0redis_exporter1.74.01.75.0mongodb_exporter0.46.00.47.0victoria-metrics1.121.01.123.0victoria-logs1.25.01.28.0grafana-victoriametrics-ds0.17.00.18.3grafana-victorialogs-ds0.18.30.19.3grafana-infinity-ds3.3.03.4.1etcd3.6.13.6.4ferretdb2.3.12.5.0tigerbeetle0.16.500.16.54genai-toolbox0.9.00.12.0
2025-07-24 名称 旧版本 新版本 备注 ferretdb- 2.4.0与 documentdb 1.105 配合 etcd- 3.6.3minio- 20250723155402mcli- 20250721052808ivorysql- 4.5-0ffca11-20250709修复 libxcrypt 依赖问题
2025-07-16 名称 旧版本 新版本 备注 genai-toolbox0.8.00.9.0各种 DBMS 的 MCP 工具箱 victoria-metrics1.120.01.121.0拆分为各种包 victoria-logs1.24.01.25.0拆分为各种包 prometheus3.4.23.5.0duckdb1.3.11.3.2etcd3.6.13.6.2tigerbeetle0.16.480.16.50grafana-victoriametrics-ds0.16.00.17.0rclone1.69.31.70.3pig0.5.00.6.0pev21.15.01.16.0pg_exporter1.0.01.0.1
2025-07-04 名称 旧版本 新版本 备注 prometheus3.4.13.4.2- grafana12.0.112.0.2- vector0.47.00.48.0- rclone1.69.01.70.2- vip-manager3.0.04.0.0- blackbox_exporter0.26.00.27.0- redis_exporter1.72.11.74.0- duckdb1.3.01.3.1- etcd3.6.03.6.1- ferretdb2.2.02.3.1- dblab0.32.00.33.0- tigerbeetle0.16.410.16.48- grafana-victorialogs-ds0.16.30.18.1- grafana-victoriametrics-ds0.15.10.16.0- grafana-infinity-ds3.2.13.3.0- victoria-logs1.22.21.24.0- victoria-metrics1.117.11.120.0-
2025-06-01 名称 旧版本 新版本 备注 grafana- 12.0.1- prometheus- 3.4.1- keepalived_exporter- 1.7.0- redis_exporter- 1.73.0- victoria-metrics- 1.118.0- victoria-logs- 1.23.1- tigerbeetle- 0.16.42- grafana-victorialogs-ds- 0.17.0- grafana-infinity-ds- 3.2.2-
2025-05-22 名称 旧版本 新版本 备注 dblab- 0.32.0- prometheus- 3.4.0- duckdb- 1.3.0- etcd- 3.6.0- pg_exporter- 1.0.0- ferretdb- 2.2.0- rclone- 1.69.3- minio- 20250422221226最后一个带管理 GUI 的版本 mcli- 20250416181326- nginx_exporter- 1.4.2- keepalived_exporter- 1.6.2- pgbackrest_exporter- 0.20.0- redis_exporter- 1.27.1- victoria-metrics- 1.117.1- victoria-logs- 1.22.2- pg_timetable- 5.13.0- tigerbeetle- 0.16.41- pev2- 1.15.0- grafana- 12.0.0- grafana-victorialogs-ds- 0.16.3- grafana-victoriametrics-ds- 0.15.1- grafana-infinity-ds- 3.2.1- grafana-plugins- 12.0.0-
2025-04-23 名称 旧版本 新版本 备注 mtail- 3.0.8新 pig- 0.4.0- pg_exporter- 0.9.0- prometheus- 3.3.0- pushgateway- 1.11.1- keepalived_exporter- 1.6.0- redis_exporter- 1.70.0- victoria-metrics- 1.115.0- victoria-logs- 1.20.0- duckdb- 1.2.2- pg_timetable- 5.12.0- vector- 0.46.1- minio- 20250422221226- mcli- 20250416181326-
2025-04-05 名称 旧版本 新版本 备注 pig- 0.3.4- etcd- 3.5.21- restic- 0.18.0- ferretdb- 2.1.0- tigerbeetle- 0.16.34- pg_exporter- 0.8.1- node_exporter- 1.9.1- grafana- 11.6.0- zfs_exporter- 3.8.1- mongodb_exporter- 0.44.0- victoria-metrics- 1.114.0- minio- 20250403145628- mcli- 20250403170756-
2025-03-23 名称 旧版本 新版本 备注 etcd- 3.5.20- pgbackrest_exporter- 0.19.0重新构建 victoria-logs- 1.17.0- victoria-logs-cli- 1.17.0-
2025-03-17 名称 旧版本 新版本 备注 kafka- 4.0.0- prometheus- 3.2.1- alertmanager- 0.28.1- blackbox_exporter- 0.26.0- node_exporter- 1.9.0- mysqld_exporter- 0.17.2- kafka_exporter- 1.9.0- redis_exporter- 1.69.0- duckdb- 1.2.1- etcd- 3.5.19- ferretdb- 2.0.0- tigerbeetle- 0.16.31- vector- 0.45.0- victoria-metrics- 1.114.0- victoria-logs- 1.16.0- rclone- 1.69.1- pev2- 1.14.0- grafana-victorialogs-ds- 0.16.0- grafana-victoriametrics-ds- 0.14.0- grafana-infinity-ds- 3.0.0- timescaledb-event-streamer- 0.12.0新 restic- 0.17.3新 juicefs- 1.2.3新
2025-02-12 名称 旧版本 新版本 备注 pushgateway1.10.01.11.0- alertmanager0.27.00.28.0- nginx_exporter1.4.01.4.1- pgbackrest_exporter0.18.00.19.0- redis_exporter1.66.01.67.0- mongodb_exporter0.43.00.43.1- victoria-metrics1.107.01.111.0- victoria-logs1.3.21.9.1- duckdb1.1.31.2.0- etcd3.5.173.5.18- pg_timetable5.10.05.11.0- ferretdb1.24.02.0.0- tigerbeetle0.16.130.16.27- grafana11.4.011.5.1- vector0.43.10.44.0- minio2024121813154420250207232109- mcli2024112117215420250208191421- rclone1.68.21.69.0-
2024-11-19 名称 旧版本 新版本 备注 prometheus2.54.03.0.0- victoria-metrics1.102.11.106.1- victoria-logs0.28.01.0.0- mysqld_exporter0.15.10.16.0- redis_exporter1.62.01.66.0- mongodb_exporter0.41.20.42.0- keepalived_exporter1.3.31.4.0- duckdb1.1.21.1.3- etcd3.5.163.5.17- tigerbeetle16.80.16.13- grafana- 11.3.0- vector- 0.42.0-
10.4 - PGSQL 仓库 PostgreSQL 扩展和内核分支仓库
pigsty-pgsql 仓库包含特定于 PostgreSQL 主版本的软件包(通常也特定于特定的 Linux 发行版主版本),包括扩展和一些内核分支。
当前活跃维护的 PostgreSQL 扩展构建范围为 14-18 ,PG 13 已退出当前维护窗口。
您可以参考 发布 - RPM 变更日志 / 发布 - DEB 变更日志 查阅最近的版本更新情况。
快速上手 PIG 您可以安装 pig CLI 工具,并使用它添加 pgdg / pigsty 仓库(推荐):
pig repo add pigsty # 添加 pigsty-pgsql 仓库
pig repo add pigsty -u # 添加 pigsty-pgsql 仓库,并更新本地缓存
pig repo add pigsty -u --region= default # 强制使用全球默认区域的仓库(pigsty.io)
pig repo add pigsty -u --region= china # 使用中国镜像仓库 (pigsty.cc)
pig repo add pgsql -u # pgsql = pgdg + pigsty-pgsql (同时添加 Pigsty 与 PGDG 官方仓库)
pig repo add -u # all = node + pgsql (pgdg + pigsty) + infra,一次性添加所有仓库
提示 :如果您在中国大陆区域,可以考虑使用中国 CDN 镜像(将 pigsty.io 替换为 pigsty.cc)
APT 您也可以直接在 Debian / Ubuntu 上使用 apt 启用此仓库:
# 将 Pigsty 的 GPG 公钥添加到您的系统密钥链以验证包签名
curl -fsSL https://repo.pigsty.io/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg
# 获取 Debian / Ubuntu 发行版代号(bookworm, trixie, jammy, noble, resolute),并将相应的上游仓库地址写入 APT List 文件
distro_codename = $( lsb_release -cs)
sudo tee /etc/apt/sources.list.d/pigsty-io.list > /dev/null <<EOF
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/pgsql/${distro_codename} ${distro_codename} main
EOF
# 刷新 APT 仓库缓存
sudo apt update
# 在中国大陆或 Cloudflare 不可用时使用
# 将 Pigsty 的 GPG 公钥添加到您的系统密钥链以验证包签名
curl -fsSL https://repo.pigsty.cc/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg
# 获取 Debian 发行版代号,并将相应的上游仓库地址写入 APT List 文件
distro_codename = $( lsb_release -cs)
sudo tee /etc/apt/sources.list.d/pigsty-io.list > /dev/null <<EOF
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.cc/apt/pgsql/${distro_codename} ${distro_codename} main
EOF
# 刷新 APT 仓库缓存
sudo apt update
DNF 您也可以直接在兼容 EL 的系统上使用 dnf/yum 启用此仓库:
# 将 Pigsty 的 GPG 公钥添加到您的系统密钥链以验证包签名
curl -fsSL https://repo.pigsty.io/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
# 将 Pigsty 仓库定义文件添加到 /etc/yum.repos.d/ 目录,包括两个仓库
sudo tee /etc/yum.repos.d/pigsty-pgsql.repo > /dev/null <<-'EOF'
[pigsty-pgsql]
name=Pigsty PGSQL For el$releasever.$basearch
baseurl=https://repo.pigsty.io/yum/pgsql/el$releasever.$basearch
skip_if_unavailable = 1
enabled = 1
priority = 1
gpgcheck = 1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty
module_hotfixes=1
EOF
# 刷新 YUM/DNF 仓库缓存
sudo yum makecache;
# 在中国大陆或 Cloudflare 不可用时使用
# 将 Pigsty 的 GPG 公钥添加到您的系统密钥链以验证包签名
curl -fsSL https://repo.pigsty.cc/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
# 将 Pigsty 仓库定义文件添加到 /etc/yum.repos.d/ 目录
sudo tee /etc/yum.repos.d/pigsty-pgsql.repo > /dev/null <<-'EOF'
[pigsty-pgsql]
name=Pigsty PGSQL For el$releasever.$basearch
baseurl=https://repo.pigsty.cc/yum/pgsql/el$releasever.$basearch
skip_if_unavailable = 1
enabled = 1
priority = 1
gpgcheck = 1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty
module_hotfixes=1
EOF
# 刷新 YUM/DNF 仓库缓存
sudo yum makecache;
源代码 此仓库的构建脚本与源代码在 GitHub 上开源:
如果平台不受支持,您也可以自行从源代码构建软件包。
pig build 提供了简便的扩展构建基础设施,您可以方便地在自己的系统上制作 RPM/DEB 包。
兼容性 系统 / 架构 代码 x86_64 aarch64 EL8 el8 18, 17, 16, 15, 1418, 17, 16, 15, 14EL9 el9 18, 17, 16, 15, 1418, 17, 16, 15, 14EL10 el10 18, 17, 16, 15, 1418, 17, 16, 15, 14Debian 12 d12 18, 17, 16, 15, 1418, 17, 16, 15, 14Debian 13 d13 18, 17, 16, 15, 1418, 17, 16, 15, 14Ubuntu 22.04 u22 18, 17, 16, 15, 1418, 17, 16, 15, 14Ubuntu 24.04 u24 18, 17, 16, 15, 1418, 17, 16, 15, 14Ubuntu 26.04 u26 18, 17, 16, 15, 1418, 17, 16, 15, 14
10.4.1 - DNF 变更日志 PostgreSQL 和扩展 RPM 包变更日志和发布说明
2026-05-01 包名 旧版本 新版本 备注 pg_pathcheck - 0.9.1 新增,PG 17-18,需通过 shared_preload_libraries 加载 pg_bikram_sambat - 0.1.0 新增,尼泊尔 Bikram Sambat 日期类型与 AD/BS 转换函数 timescaledb 2.26.3 2.26.4 TimescaleDB TSL 小版本更新 storage_engine 1.2.3 1.3.4 PGXN 更新,列式/行压缩 table access method pgproto 0.3.3 0.5.0 PGXN 更新,原生 Protobuf 支持 pg_savior 0.0.1 0.1.0 高风险 DDL/DML 防护 hook,需 preload 或 LOAD pg_textsearch 1.0.0 1.1.0 Timescale BM25 全文搜索扩展更新,PG 17-18,需 preload pg_trickle 0.31.0 0.40.0 Rust/pgrx 更新,仅支持 PG 18
2026-04-25 包名 旧版本 新版本 备注 documentdb 0.109 0.110 升级到上游版本,PG 15-18 pg_trickle 0.20.0 0.31.0 升级,仅 PG 18,pgrx 0.18.0 pg_search 0.23.0 0.23.1 升级,PG 15-18,pgrx 0.18.0 pg_ivm 1.13 1.14 升级,PG 14-18 prefix 1.2.10 1.2.11 升级,PG 14-18,PGDG credcheck 4.6 4.7 升级,PG 14-18,PGDG pg_dbms_job 1.5 2.0 升级,PG 14-18,PGDG storage_engine 1.0.7 1.2.3 升级,PG 14-18 pgmq 1.11.0 1.11.1 升级,PG 14-18 parray_gin 1.4.0 1.5.0 升级,PG 14-18 rdf_fdw 2.4.0 2.5.0 升级,PG 14-18 pg_accumulator - 1.1.3 新增,PG 14-18
2026-04-19 包名 旧版本 新版本 备注 cloudberry 2.0.0 2.1.0-2 升级到 2.1.0,release 2 修复 initdb errno 问题 cloudberry-backup - 2.1.0-2 新增 Cloudberry 备份工具包 cloudberry-pxf - 2.1.0-2 新增 Cloudberry PXF 包 re2 - 0.1.1 新增,PG 16-18 storage_engine - 1.0.7 新增,PG 14-18 ulak - 0.0.2 新增,PG 14-18 orioledb beta14 beta15 配套 OriolePG 17.18 oriolepg 17.16 17.18 内核补丁集更新 pg_clickhouse 0.1.10 0.2.0 pg_search 0.22.6 0.23.0 pg_stat_ch 0.3.4 0.3.6 仅支持 EL9+ pg_trickle 0.17.0 0.20.0 仅支持 PG 18 pgclone 3.6.0 4.0.0 pgproto 0.2.4 0.3.3 pgxicor 0.1.0 0.1.1 timescaledb 2.26.2 2.26.3
2026-04-14 包名 旧版本 新版本 备注 block_copy_command - 0.1.5 新增,PG 14-18,Rust/pgrx 0.17.0 pg_kazsearch - 2.0.0 新增,PG 16-18,Rust/pgrx 0.17.0 pg_rrf - 0.0.3 新增,PG 14-17,Rust/pgrx 0.16.1 -> 0.17.0 pgmqtt - 0.1.0 新增,PG 14-18,Rust/pgrx 0.16.1 -> 0.17.0 pg_when - 0.1.9 新增,PG 14-18,Rust/pgrx 0.17.0 provsql - 1.2.3 新增,PG 14-18 pg_isok - 1.4.1 新增,PG 14-18 pg_byteamagic - 0.2.4 新增,PG 14-18 logical_ddl - 0.1.0 新增,PG 14-18 datasketches - 1.7.0 新增,PG 14-18 pg_text_semver - 1.2.1 新增,PG 14-18 external_file - 1.2 新增,PG 14-18 pg_query_rewrite - 0.0.5 新增,PG 14-18 pghydro - 6.6 新增,PG 14-18 pg_datasentinel - 1.0 新增,PG 15-18 onesparse - 1.0.0 新增,仅 PG 18 rdkit - 202503.6 新增,PG 14-18 pg_dispatch - 0.1.5 新增,PG 14-18 pg_fsql - 1.1.0 新增,PG 14-18 pg_liquid - 0.1.7 新增,PG 14-18 pg_regresql - 2.0.0 新增,PG 14-18 pg_slug_gen - 1.0.0 新增,PG 15-18 pg_stat_ch - 0.3.4 新增,PG 16-18 pg_variables - 1.2.5 新增,PG 14-18 pgcalendar - 1.1.0 新增,PG 14-18 pgclone - 3.6.0 新增,PG 14-18 pgelog - 1.0.2 新增,PG 14-18 pglock - 1.0.0 新增,PG 14-18 pgproto - 0.2.4 新增,PG 14-18 postgresbson - 2.0.2 新增,PG 14-18 rdf_fdw - 2.4.0 新增,PG 14-18 parray_gin - 1.4.0 新增,PG 14-18 timescaledb 2.25.2 2.26.2 升级 pg_ivm 1.13 1.14 升级 system_stats 3.2 4.0 升级 nominatim_fdw 1.1.0 1.2 升级 pg_textsearch 0.5.0 1.0.0 升级 pg_clickhouse 0.1.5 0.1.10 升级 pg_search 0.22.2 0.22.6 升级 pg_store_plans 1.9 1.10 升级 pg_tzf 0.2.3 0.2.4 升级,Rust/pgrx 0.17.0 pg_anon 3.0.1 3.0.13 升级,Rust/pgrx 0.16.1 -> 0.17.0 pg_cardano 1.1.1 1.2.0 升级,Rust/pgrx 0.17.0 pg_strict 1.0.3 1.0.5 升级,Rust/pgrx 0.16.1 -> 0.17.0 pg_vectorize 0.26.0 0.26.1 升级,Rust/pgrx 0.16.1 -> 0.17.0 pglinter 1.1.1 1.1.2 升级,Rust/pgrx 0.16.1 -> 0.17.0 pgx_ulid 0.2.2 0.2.3 升级,Rust/pgrx 0.17.0 wrappers 0.5.7 0.6.0 升级,Rust/pgrx 0.16.1 -> 0.17.0 pg_trickle 0.16.0 0.17.0 升级,Rust/pgrx 0.17.0 supautils 3.1.0 3.2.1 升级 ddl_historization 0.0.7 0.2 升级 pg_incremental 1.4.1 1.5.0 升级 pg_failover_slots 1.2.0 1.2.1 升级 plv8 3.2.4 3.2.4-2 fix el10 build PolarDB 15.15 17.9.1.0 PG 15 -> 17
2026-03-21 包名 旧版本 新版本 备注 pg_search 0.21.12 0.22.2 pgsentinel 1.4.0 1.4.1 仅更新 rpm pg_track_optimizer 0.9.1 0.9.2 pgcollection 1.0.0 2.0.0 pg_ttl_index 2.0.0 3.0.0 pg_clickhouse 0.1.4 0.1.5 pdu 3.0.25.12 新增 pgdog 0.1.32 新增
2026-03-05 包名 旧版本 新版本 备注 timescaledb 2.25.1 2.25.2 vchord 1.1.0 1.1.1 新增 clang 构建依赖,修复错误 aggs_for_vecs 1.4.0 1.4.1 pg_search 0.21.9 0.21.12 pg_pinyin - 0.0.2 新增扩展 pg_eviltransform - 0.0.2 新增扩展 pg_qos - 1.0.0 新增扩展,QoS 资源治理
2026-02-27 包名 旧版本 新版本 备注 timescaledb 2.25.0 2.25.1 citus 14.0.0-3 14.0.0-4 使用最新官方版本重新构建 age 1.7.0 1.7.0 新增 PG 17 的 1.7.0 版本支持 pgmq 1.10.0 1.10.1 当前没有该扩展包 pg_search 0.21.7 0.21.9 直接下载使用 oriolepg 17.11 17.16 OriolePG 内核更新 orioledb beta12 beta14 配套 OriolePG 17.16 openhalo 14.10 1.0 更新并重命名,14.18 pgedge - 17.9 新增多主边缘分布式内核 spock - 5.0.5 新增,pgEdge 核心扩展 lolor - 1.2.2 新增,pgEdge 核心扩展 snowflake - 2.4 新增,pgEdge 核心扩展 cloudberry - 2.0.0 新增包 babelfishpg - 5.5.0 新增 BabelfishPG 包组 babelfish - 5.5.0 新增 Babelfish 兼容包 antlr4-runtime413 - 4.13 新增 Babelfish 依赖运行时
2026-02-12 名称 旧版本 新版本 备注 timescaledb 2.24.0 2.25.0 citus 14.0.0-2 14.0.0-3 官方正式 tag 发布 pg_incremental 1.2.0 1.4.1 pg_bigm 1.2-20240606 1.2-20250903 pg_net 0.20.0 0.20.2 el8/el9 libcurl 版本过低 pgmq 1.9.0 1.10.0 修复依赖关系 pg_textsearch 0.4.0 0.5.0 pljs 1.0.4 1.0.5 sslutils 1.4-1 1.4-2 el8.pg18 无法编译 table_version 1.11.0 1.11.1 supautils 3.0.2 3.1.0 pg_math 1.0 1.1.0 pgsentinel 1.3.1 1.4.0 pg_uri 1.20151224 1.20251029 pgcollection 1.1.0 1.1.1 补丁修复并发构建问题 pg_uint128 1.1.1 1.2.0 pg_roaringbitmap 0.5.5 1.1.0 交由 PGDG plprql 18.0.0 18.0.1 pglinter 1.0.1 1.1.0 pg_jsonschema 0.3.3 0.3.4 pg_anon 2.5.1 3.0.1 vchord 1.0.0 1.1.0 更新至 pgrx 0.17.0 pg_search 0.21.4 0.21.7 针对 el8 手工构建 pg_graphql 1.5.12-1 1.5.12-2 切换至官方版本 nominatim_fdw 1.1.0 新增,与 PGDG YUM 同步 pg_utl_smtp 1.0.0 新增,与 PGDG YUM 同步 pg_strict - 1.0.2 新增 Rust 扩展 pg_track_optimizer - 0.9.1 新增扩展 pgmb - 1.0.0 新增扩展
2026-01-25 名称 旧版本 新版本 备注 age 1.6.0 1.7.0 仅 PG 18 citus 14.0.0-1PIGSTY 14.0.0-2PIGSTY 官方分支正式发布 pg_clickhouse 0.1.2 0.1.3 pgmq 1.8.1 1.9.0 pg_search 0.21.2 0.21.4
2026-01-16 名称 旧版本 新版本 备注 etcd_fdw 0.0.0 新增 pg_ttl_index 0.1.0 新增 citus 13.2.0 14.0.0 +pg18,预发布 pg_search 0.20.5 0.21.2 +pg18 pg_clickhouse 0.1.0 0.1.2 pg_textsearch 0.1.0 0.4.0 pg_convert 0.0.5 0.1.0 pg_timeseries 0.1.8 0.2.0 biscuit 2.0.1 2.2.2 pgmq 1.8.0 1.8.1 documentdb 0.107 0.109 +pg18,使用微软版本 pg_bulkload 3.1.22 3.1.23 +pg18 age 1.5.0 1.6.0 pgsentinel 1.3.0 1.3.1 pljs - 1.0.4 新增 pg_partman 5.3.1 5.4.0 PGDG pgfincore - 1.3.1 +pg18 documentdb_extended_rum 0.109 新增 mobilitydb_datagen 1.3.0 新增 rum 1.3.15 +pg18,新增
2025-12-25 名称 旧版本 新版本 备注 pg_duckdb1.1.01.1.1pg_search0.20.40.20.5vchord_bm250.2.20.3.0pg_semver0.40.00.41.0pg_timeseries0.1.70.1.8
2025-12-16 名称 旧版本 新版本 备注 pg_textsearch- 0.1.0新增扩展 pg_clickhouse- 0.1.0新增扩展 pg_ai_query- 0.1.1新增扩展 timescaledb2.23.12.24.0pg_search0.20.00.20.4pg_duckdb1.1.0-11.1.0-2官方发布的版本 pg_biscuit1.02.0.1切换至新仓库 pg_convert0.0.40.0.5移除 pg13 支持 pgdd0.6.00.6.1移除 pg13 支持 pglinter1.0.01.0.1pg_session_jwt0.3.30.4.0pg_anon2.4.12.5.1pg_enigma0.4.00.5.0wrappers0.5.60.5.7pg_vectorize0.25.00.26.0synchdb- 1.3仅 EL9 可用
2025-11-20 名称 旧版本 新版本 备注 vchord0.5.31.0.0pg_later0.3.10.4.0pgvectorscale0.8.00.9.0-pg13, +pg18 pglite_fusion0.0.50.0.6pgx_ulid0.2.10.2.2pg_search0.19.50.19.7恢复由 PIGSTY 构建 citus13.2.013.2.0使用官方 tag 构建 timescaledb2.23.02.23.1pg_profile4.104.11pglinter1.0.0new pg_typeid0.3.0对齐 pg18 支持 pg_enigma0.4.0vonng patched pgrx version pg_retry1.0.0新增,pg17-18 pg_biscuit1.0新增,pg16-18 pg_weighted_statistics1.0.0新增,pg13-18 pg_stat_monitor2.2.02.3.0修复 PGDG pg18 缺失问题 documentdb0.1060.107ferretdb 分支 polardb15.1515.15.5.0-38948055
2025-11-10 为几乎所有扩展添加 PostgreSQL 18 支持
名称 旧版本 新版本 备注 omni_csv- 0.1.1新增扩展 omni_datasets- 0.1.0新增扩展 omni_shmem- 0.1.0新增扩展 pg_csv- 1.0.1新增扩展 pg_dbms_errlog- 2.2新增扩展 pg_rrule- 0.2.0新增扩展 plxslt- 0.20140221新增扩展 anon2.3.02.4.1+pg18 collection1.0.01.1.0+pg18 credcheck3.04.2+pg18 emaj4.7.04.7.1+pg18 explain_ui0.0.10.0.2+pg18 firebird_fdw1.4.01.4.1+pg18 logerrors2.1.32.1.5+pg18 multicorn3.03.2+pg18 omni0.2.90.2.14+pg18 omni_email00.1.0+pg18 omni_httpc0.1.50.1.10+pg18 omni_httpd0.4.60.4.11+pg18 omni_id0.4.20.4.3+pg18 omni_kube0.1.10.4.2+pg18 omni_ledger0.1.20.1.3+pg18 omni_sql0.5.10.5.3+pg18 omni_sqlite0.1.20.2.2+pg18 omni_types0.3.40.3.6+pg18 omni_vfs0.2.10.2.2+pg18 omni_worker0.1.00.2.1+pg18 periods1.2.21.2.3+pg18 pg_bestmatch0.0.10.0.2+pg18 pg_cardano1.0.51.1.1+pg18 pg_checksums1.11.3+pg18 pg_duckdb0.3.11.1.0+pg18 pg_failover_slots1.1.01.2.0+pg18 pg_graphql1.5.111.5.12+pg18 pg_idkit0.3.10.4.0+pg18 pg_later0.3.00.3.1+pg18 pg_mooncake0.1.20.2.0+pg18 pg_net0.9.20.20.0+pg18 pg_parquet0.4.30.5.1+pg18 pg_render0.1.20.1.3+pg18 pg_session_jwt0.3.10.3.3+pg18 pg_smtp_client0.2.00.2.1+pg18 pg_sphere1.5.11.5.2+pg18 pg_statement_rollback1.41.5+pg18 pg_store_plans1.81.9+pg18 pg_tle1.5.11.5.2+pg18 pg_tokenizer0.1.00.1.1+pg18 pg_uuidv71.6.01.7.0+pg18 pgactive2.1.62.1.7+pg18 pglogical2.4.52.4.6+pg18 pglogical_origin2.4.52.4.6+pg18 pgmq1.5.11.7.0+pg18 pgsmcrypto0.1.00.1.1+pg18 pgx_ulid0.2.00.2.1+pg18 pldbgapi1.81.9+pg18 pljava1.6.81.6.10+pg18 plprql1.0.018.0.0+pg18 roaringbitmap0.5.40.5.5+pg18 semver0.32.10.40.0+pg18 supautils2.10.03.0.2+pg18 tds_fdw2.0.42.0.5+pg18 timescaledb2.22.02.23.0+pg18 timescaledb_toolkit1.21.01.22.0+pg18 timeseries0.1.60.1.7+pg18 pg_tzf0.2.20.2.3+pg18 vchord0.5.10.5.3+pg18 vchord_bm250.2.10.2.2+pg18 vectorize0.22.20.25.0+pg18 wrappers0.5.40.5.6+pg18 gzip1.0.11.0.0+pg18 hypopg1.4.11.4.2+pg18 mobilitydb1.2.01.3.0+pg18 mongo_fdw5.5.15.5.3+pg18 orafce4.14.44.14.6+pg18 pg_hint_plan1.7.11.8.0+pg18 pg_ivm1.111.13+pg18 pg_partman5.2.45.3.1+pg18 pg_search0.18.10.19.2+pg18 pg_show_plans2.1.62.1.7+pg18 pgpcre10.20190509+pg18 pgroonga4.0.04.0.4+pg18 pgroonga_database4.0.04.0.4+pg18 plpgsql_check2.8.22.8.3+pg18 uint1.202312061.20250815+pg18 uint1281.1.01.1.1+pg18 omni_*2025052520251108+pg18 acl1.0.4+pg18 aggs_for_arrays1.3.3+pg18 aggs_for_vecs1.4.0+pg18 arraymath1.1+pg18 asn1oid1.6+pg18 aws_s30.0.1+pg18 base361.0.0+pg18 base620.0.1+pg18 bzip1.0.0+pg18 chkpass1.0+pg18 convert0.0.4+pg18 count_distinct3.0.2+pg18 country0.0.3+pg18 cryptint1.0.0+pg18 currency0.0.3+pg18 data_historization1.1.0+pg18 db_migrator1.0.0+pg18 dbt20.61.7+pg18 ddl_historization0.0.7+pg18 ddsketch1.0.1+pg18 decoder_raw1.0+pg18 decoderbufs3.2.0+pg18 emailaddr0+pg18 envvar1.0.1+pg18 faker0.5.3+pg18 financial1.0.1+pg18 fio1.0+pg18 first_last_agg0.1.4+pg18 floatfile1.3.1+pg18 floatvec1.1.1+pg18 geoip0.3.0+pg18 hashlib1.1+pg18 hashtypes0.1.5+pg18 hll2.18+pg18 hunspell_*1.0+pg18 imgsmlr1.0+pg18 index_advisor0.2.0+pg18 kafka_fdw0.0.3+pg18 login_hook1.7+pg18 oracle_fdw2.8.0+pg18 pg_auth_mon3.0+pg18 pg_background1.3+pg18 pg_bigm1.2+pg18 pg_cron1.6.7+pg18 pg_profile4.10+pg18 pg_stat_kcache2.3.0+pg18 pgdd0.6.0+pg18 pgjwt0.2.0+pg18 pgnodemx1.7+pg18 pgsodium3.1.9+pg18 pgtap1.3.3+pg18 plprofiler4.2.5+pg18 plproxy2.11.0+pg18 plr8.4.8+pg18 plv83.2.4+pg18 pointcloud1.2.5+pg18 powa5.0.1+pg18 prefix1.2.10+pg18 q3c2.0.1+pg18 redis_fdw1.0+pg18 session_variable3.4+pg18 set_user4.1.0+pg18 system_stats3.2+pg18 temporal_tables1.2.2+pg18 topn2.7.0+pg18 unit7.10+pg18 zhparser2.3+pg18 zstd1.1.2+pg18
2025-09-04 名称 旧版本 新版本 备注 timescaledb2.21.12.22.0citus13.1.013.2.0documentdb0.105.00.106.0work with ferretdb 2.5 ddlx0.290.30+ pg18 icu_ext1.9.01.10.0+ pg18 asn1oid1.51.6+ pg18 uint1281.0.01.1.0+ pg18 toastinfo1.51.6+ pg18 vchord0.4.30.5.1pgrx 0.16.0 pg_idkit0.3.00.3.1pgrx 0.15.0 pg_search0.17.30.18.0pgrx 0.15.0 pg_parquet0.4.00.4.3pgrx 0.16.0 wrappers0.5.30.5.4pgrx 0.14.3 pg_rewrite- 2.0.0+ Debian/Ubuntu (PGDG) pg_tracing- 0.1.3-2+ pg 14/18 pg_curl2.42.4.5new version epoch pg_rewrite- 2.0.0Import from PGDG pg_tracing- 1.3.0+ pg14 / pg18 pgactive2.1.52.1.6+ pg18 pgsentinel1.11.21.2 pg_tle1.5.1-11.5.1-2+ pg18 redis_fdw+ pg18 pgextwlist1.171.19+ pg18 wal2json1.6+ pg18 pgvector0.8.1+ pg18
2025-07-24 名称 旧版本 新版本 备注 orioledbbeta11 1.4beta12 1.5与 oriolepg 17.11 配合 oriolepg17.917.11与 orioledb 1.5 beta12 配合 documentdb0.104.00.105.0与 ferretdb 2.4 配合 timescaledb2.20.02.21.1supautils2.9.22.10.0.so 位置变更plv83.2.33.2.4postgresql_anonymizer3.1.12.3.0(pgrx 0.14.3) wrappers0.5.00.5.3(pgrx 0.14.3) pgrx 版本变更 pgvectorscale0.7.10.8.0(pgrx 0.12.9) pg_search0.15.80.17.0修复 el icu 依赖问题,直接下载
2025-06-24 名称 旧版本 新版本 备注 citus13.0.313.1.0timescaledb2.20.02.21.0vchord0.3.00.4.3pgactive- 2.1.5需要 pgfeutils documentdb0.103.00.104.0添加 arm 支持
2025-05-26 2025-05-22 2025-05-07 2025-03-20 名称 旧版本 新版本 备注 timescaledb- 2.19.0citus- 13.0.2documentdb- 1.102pg_analytics- 0.3.7pg_search- 0.15.8emaj- 4.6.0pgsql_tweaks- 0.11.0pgvectorscale- 0.6.0pg_session_jwt- 0.2.0wrappers- 0.4.5pg_parquet- 0.3.1vchord- 0.2.2pg_tle1.2.01.5.0supautils2.5.02.6.0sslutils1.31.4pg_profile4.74.8pg_jsonschema0.3.20.3.3pg_incremental1.1.11.2.0ddl_historization0.70.0.7pg_sqlog3.1.71.6pg_random- - pg_stat_monitor2.1.02.1.1pg_profile4.74.8
2024-10-16 名称 旧版本 新版本 备注 pg_timeseries- 0.1.6pgmq- 1.4.4pg_protobuf- 16 17pg_uuidv7- 1.6pg_readonly- latestpgddl- 0.28pg_safeupdate- latestpg_stat_monitor- 2.1pg_profile- 4.7system_stats- 3.2pg_auth_mon- 3.0login_hook- 1.6logerrors- 2.1.3pg_orphaned- latestpgnodemx- 1.7sslutils- 1.4+pg16, +pg17)
10.4.2 - APT 变更日志 PostgreSQL 和扩展 DEB 包变更日志和发布说明
2026-05-01 包名 旧版本 新版本 备注 pg_pathcheck - 0.9.1 新增 planner Path 诊断模块,PG 17-18,需 shared_preload_libraries pg_bikram_sambat - 0.1.0 新增 Bikram Sambat 日期类型与 AD/BS 转换函数 timescaledb 2.26.3 2.26.4 TSL 小版本更新 storage_engine 1.2.3 1.3.4 PGXN 更新,列式与行压缩 table access method pgproto 0.3.3 0.5.0 PGXN 更新,原生 Protobuf 支持,C/PGXS 构建 pg_savior 0.0.1 0.1.0 PGXN 更新,防误删/高风险 DDL/DML hook,需 preload 或 LOAD pg_textsearch 1.0.0 1.1.0 Timescale BM25 全文搜索更新,PG 17-18,需 shared_preload_libraries pg_trickle 0.31.0 0.40.0 Rust/pgrx 更新,仅 PG 18
已完成 Debian 12/13 与 Ubuntu 22.04/24.04/26.04 在 amd64 和 arm64 上的构建。
2026-04-25 包名 旧版本 新版本 备注 documentdb 0.109 0.110 升级到上游版本,PG 15-18 pg_trickle 0.20.0 0.31.0 升级,仅 PG 18,pgrx 0.18.0 pg_search 0.23.0 0.23.1 升级,PG 15-18,pgrx 0.18.0 pg_ivm 1.13 1.14 升级,PG 14-18 prefix 1.2.10 1.2.11 升级,PG 14-18,PGDG credcheck 4.6 4.7 升级,PG 14-18,PGDG pg_dbms_job 1.5 2.0 升级,PG 14-18,PGDG storage_engine 1.0.7 1.2.3 升级,PG 14-18 pgmq 1.11.0 1.11.1 升级,PG 14-18 parray_gin 1.4.0 1.5.0 升级,PG 14-18 rdf_fdw 2.4.0 2.5.0 升级,PG 14-18 pg_accumulator - 1.1.3 新增,PG 14-18
新增 Ubuntu 26.04 支持。
2026-04-19 包名 旧版本 新版本 备注 storage_engine - 1.0.7 新增,PG 14-18 re2 - 0.1.1 新增,PG 16-18 ulak - 0.0.2 新增,PG 14-18 cloudberry 2.0.0 2.1.0 升级,并拆分 backup / pxf 子包 cloudberry-backup - 2.1.0 新增配套子包 cloudberry-pxf - 2.1.0 新增配套子包 oriolepg 17.16 17.18 内核升级,适配 orioledb beta15/1.7 orioledb 1.6 1.7 升级,配套 oriolepg 17.18 postgis 3.6.2 3.6.3 升级 timescaledb 2.26.2 2.26.3 升级 pg_search 0.22.6 0.23.0 升级 pg_trickle 0.17.0 0.20.0 升级,仅 PG 18 pg_clickhouse 0.1.10 0.2.0 升级 pg_stat_ch 0.3.4 0.3.6 升级,PG 16-18 pgclone 3.6.0 4.0.0 升级 pgproto 0.2.4 0.3.3 升级 pgxicor 0.1.0 0.1.1 升级
2026-04-14 包名 旧版本 新版本 备注 block_copy_command - 0.1.5 新增,PG 14-18,Rust/pgrx 0.17.0 pg_kazsearch - 2.0.0 新增,PG 16-18,Rust/pgrx 0.17.0 pg_rrf - 0.0.3 新增,PG 14-17,Rust/pgrx 0.16.1 -> 0.17.0 pgmqtt - 0.1.0 新增,PG 14-18,Rust/pgrx 0.16.1 -> 0.17.0 pg_when - 0.1.9 新增,PG 14-18,Rust/pgrx 0.17.0 provsql - 1.2.3 新增,PG 14-18 pg_isok - 1.4.1 新增,PG 14-18 pg_byteamagic - 0.2.4 新增,PG 14-18 logical_ddl - 0.1.0 新增,PG 14-18 datasketches - 1.7.0 新增,PG 14-18 pg_text_semver - 1.2.1 新增,PG 14-18 external_file - 1.2 新增,PG 14-18 pg_query_rewrite - 0.0.5 新增,PG 14-18 pghydro - 6.6 新增,PG 14-18 pg_datasentinel - 1.0 新增,PG 15-18 onesparse - 1.0.0 新增,仅 PG 18 rdkit - 202503.6 新增,PG 14-18 pg_dispatch - 0.1.5 新增,PG 14-18 pg_fsql - 1.1.0 新增,PG 14-18 pg_liquid - 0.1.7 新增,PG 14-18 pg_regresql - 2.0.0 新增,PG 14-18 pg_slug_gen - 1.0.0 新增,PG 15-18 pg_stat_ch - 0.3.4 新增,PG 16-18 pg_variables - 1.2.5 新增,PG 14-18 pgcalendar - 1.1.0 新增,PG 14-18 pgclone - 3.6.0 新增,PG 14-18 pgelog - 1.0.2 新增,PG 14-18 pglock - 1.0.0 新增,PG 14-18 pgproto - 0.2.4 新增,PG 14-18 postgresbson - 2.0.2 新增,PG 14-18 rdf_fdw - 2.4.0 新增,PG 14-18 parray_gin - 1.4.0 新增,PG 14-18 timescaledb 2.25.2 2.26.2 升级 pg_background 1.8 1.9.2 升级 pg_ivm 1.13 1.14 升级 system_stats 3.2 4.0 升级 nominatim_fdw 1.1.0 1.2 升级 pg_textsearch 0.5.0 1.0.0 升级 pg_clickhouse 0.1.5 0.1.10 升级 pg_search 0.22.2 0.22.6 升级 pg_store_plans 1.9 1.10 升级 pg_tzf 0.2.3 0.2.4 升级,Rust/pgrx 0.17.0 pg_anon 3.0.1 3.0.13 升级,Rust/pgrx 0.16.1 -> 0.17.0 pg_cardano 1.1.1 1.2.0 升级,Rust/pgrx 0.17.0 pg_strict 1.0.3 1.0.5 升级,Rust/pgrx 0.16.1 -> 0.17.0 pg_vectorize 0.26.0 0.26.1 升级,Rust/pgrx 0.16.1 -> 0.17.0 pglinter 1.1.1 1.1.2 升级,Rust/pgrx 0.16.1 -> 0.17.0 pgx_ulid 0.2.2 0.2.3 升级,Rust/pgrx 0.17.0 wrappers 0.5.7 0.6.0 升级,Rust/pgrx 0.16.1 -> 0.17.0 pg_trickle 0.16.0 0.17.0 升级,Rust/pgrx 0.17.0 supautils 3.1.0 3.2.1 升级 ddl_historization 0.0.7 0.2 升级 pg_incremental 1.4.1 1.5.0 升级 pg_failover_slots 1.2.0 1.2.1 升级
2026-03-21 包名 旧版本 新版本 备注 pg_search 0.21.12 0.22.2 pg_track_optimizer 0.9.1 0.9.2 pgcollection 1.0.0 2.0.0 pg_ttl_index 2.0.0 3.0.0 pg_clickhouse 0.1.4 0.1.5 pdu 3.0.25.12 新增 pgdog 0.1.32 新增
2026-03-05 本次为 7 个扩展在 Debian 12/13 与 Ubuntu 22/24(amd64/arm64)构建了 264 个 DEB 包。
包名 旧版本 新版本 备注 aggs_for_vecs 1.4.0 1.4.1 上游版本升级,PG 14-18 timescaledb 2.25.1 2.25.2 上游版本升级,PG 15-18 vchord 1.1.0 1.1.1 上游版本升级,PG 14-18 vchord_bm25 0.3.0-1 0.3.0-2 打包修复,PG 14-18 pg_pinyin - 0.0.2 新增扩展包,PG 14-18 pg_eviltransform - 0.0.2 新增扩展包,并对齐版本号 qos - 1.0.0 新增扩展包,PG 15-18
2026-02-27 包名 旧版本 新版本 备注 timescaledb 2.25.0 2.25.1 citus 14.0.0-3 14.0.0-4 使用最新官方版本重新构建 age 1.7.0 1.7.0 新增 PG 17 的 1.7.0 版本支持 pg_background - 1.8 仅提供 DEB 包,没有 RPM pgmq 1.10.0 1.10.1 当前没有该扩展包 pg_search 0.21.6 0.21.9 直接下载使用 oriolepg 17.11 17.16 OriolePG 内核更新 orioledb beta12 beta14 配套 OriolePG 17.16 openhalo 14.10 1.0 更新并重命名,14.18 pgedge - 17.9 新增多主边缘分布式内核 spock - 5.0.5 新增,pgEdge 核心扩展 lolor - 1.2.2 新增,pgEdge 核心扩展 snowflake - 2.4 新增,pgEdge 核心扩展 babelfishpg - 5.5.0 新增 BabelfishPG 包组 babelfish - 5.5.0 新增 Babelfish 兼容包 antlr4-runtime413 - 4.13 新增 Babelfish 依赖运行时
2026-02-12 名称 旧版本 新版本 备注 timescaledb 2.24.0 2.25.0 pg_incremental 1.2.0 1.4.1 pg_bigm 1.2 1.2-20250903 pg_net 0.20.0 0.20.2 ubuntu22 libcurl 版本过低 pgmq 1.9.0 1.10.0 pg_textsearch 0.4.0 0.5.0 pljs 1.0.4 1.0.5 sslutils 1.4-1 1.4-2 supautils 3.0.2 3.1.0 pg_math 1.0 1.1.0 pgsentinel 1.3.1 1.4.0 pg_uri 1.20151224 1.20251029 pgcollection 1.1.0 1.1.1 pg_readonly 1.0.3 1.0.4 timestamp9 1.4.0-1 1.4.0-2 重新构建,修复依赖问题 plprql 18.0.0 18.0.1 pglinter 1.0.1 1.1.0 pg_jsonschema 0.3.3 0.3.4 pg_anon 2.5.1 3.0.1 pg_search 0.21.4 0.21.6 pg_graphql 1.5.12-1 1.5.12-2 切换至官方 release pg_summarize 0.0.1-2 0.0.1-3 重新构建,修复 pg18 问题 nominatim_fdw 1.1.0 新增,与 PGDG YUM 同步 pg_utl_smtp 1.0.0 新增,与 PGDG YUM 同步 pg_strict - 1.0.2 新增 Rust 扩展 pg_track_optimizer - 0.9.1 新增扩展 pgmb - 1.0.0 新增扩展
2026-01-25 名称 旧版本 新版本 备注 age 1.6.0 1.7.0 仅 PG 18 citus 14.0.0-1PIGSTY 14.0.0-2PIGSTY 官方分支正式发布 pg_clickhouse 0.1.2 0.1.3 pgmq 1.8.1 1.9.0 pg_search 0.21.2 0.21.4
2026-01-16 名称 旧版本 新版本 备注 etcd_fdw 0.0.0 新增 pg_ttl_index 0.1.0 新增 citus 13.2.0 14.0.0 +pg18,预发布 pg_search 0.20.5 0.21.2 +pg18 pg_clickhouse 0.1.0 0.1.2 pg_textsearch 0.1.0 0.4.0 pg_convert 0.0.5 0.1.0 pg_timeseries 0.1.8 0.2.0 biscuit 2.0.1 2.2.2 pgmq 1.8.0 1.8.1 documentdb 0.107 0.109 +pg18,使用微软版本 pg_bulkload 3.1.22 3.1.23 +pg18 age - 1.6.0 +pg18 PGDG pgsentinel 1.2.0 1.3.1 PGDG pljs - 1.0.4 PGDG pg_partman 5.3.0 5.4.0 PGDG pgfincore - 1.3.1 PGDG documentdb_extended_rum 0.109 新增 mobilitydb_datagen 1.3.0 新增
2025-12-25 名称 旧版本 新版本 备注 pg_duckdb1.1.01.1.1pg_search0.20.40.20.5vchord_bm250.2.20.3.0pg_semver0.40.00.41.0pg_timeseries0.1.70.1.8supautils3.0.2-13.0.2-2修复 pg18 pg_summarize0.0.1-10.0.1-2修复 pg18
2025-12-16 名称 旧版本 新版本 备注 pg_textsearch- 0.1.0新增 pg_clickhouse- 0.1.0新增 pg_ai_query- 0.1.1新增 timescaledb2.23.12.24.0pg_search0.20.00.20.4pg_duckdb1.1.0-11.1.0-2官方版本 pg_biscuit1.02.0.1新仓库 pg_convert0.0.40.0.5移除 pg13 支持 pgdd0.6.00.6.1移除 pg13 支持 pglinter1.0.01.0.1pg_session_jwt0.3.30.4.0pg_anon2.4.12.5.1pg_enigma0.4.00.5.0wrappers0.5.60.5.7pg_vectorize0.25.00.26.0修复 pg18 pg_tiktoken- - 修复 pg18 pg_tzf- - 修复 pg18 pglite_fusion- - 修复 pg18 pgsmcrypto- - 修复 pg18 pgx_ulid- - 修复 pg18 plprql- - 修复 pg18 synchdb- 1.3仅支持 Ubuntu 22/24
2025-11-20 名称 旧版本 新版本 备注 vchord0.5.31.0.0pg_later0.3.10.4.0pgvectorscale0.8.00.9.0-pg13, +pg18 pglite_fusion0.0.50.0.6pgx_ulid0.2.10.2.2pg_search0.19.50.19.7resume PIGSTY building citus13.2.013.2.0official tag timescaledb2.23.02.23.1pg_profile4.104.11pglinter1.0.0new pg_typeid0.3.0head with pg18 support pg_enigma0.4.0vonng patched pgrx version pg_retry1.0.0new, pg17-18 pg_biscuit1.0new, pg16-18 pg_weighted_statistics1.0.0new, pg13-18 documentdb0.1060.107ferretdb fork polardb15.1515.15.5.0-38948055
2025-11-10 为几乎所有扩展添加 PostgreSQL 18 支持
名称 旧版本 新版本 备注 omni_csv- 0.1.1new omni_datasets- 0.1.0new omni_shmem- 0.1.0new pg_csv- 1.0.1new pljs- 1.0.3new plxslt- 0.20140221new credcheck3.04.2+pg18 dbt20.45.00.61.7+pg18 h34.1.34.2.3+pg18 h3_postgis4.1.34.2.3+pg18 mongo_fdw1.15.5.3+pg18 multicorn3.03.2+pg18 orafce4.14.44.14.6+pg18 pg_hint_plan1.7.01.8.0+pg18 pg_search0.18.10.19.2+pg18 pg_show_plans2.1.62.1.7+pg18 pgactive2.1.62.1.7+pg18 pgpcre10.20190509+pg18 plpgsql_check2.8.22.8.3+pg18 roaringbitmap0.5.40.5.5+pg18 uint1.202312061.20250815+pg18 uint1281.1.01.1.1+pg18 anon2.3.02.4.1+pg18 collection1.0.01.1.0+pg18 emaj4.7.04.7.1+pg18 explain_ui0.0.10.0.2+pg18 firebird_fdw1.4.01.4.1+pg18 login_hook1.61.7+pg18 logerrors2.1.32.1.5+pg18 mobilitydb1.2.01.3.0+pg18 omni0.2.90.2.14+pg18 omni_httpc0.1.50.1.10+pg18 omni_httpd0.4.60.4.11+pg18 omni_kube0.1.10.4.2+pg18 omni_sql0.5.10.5.3+pg18 omni_sqlite0.1.20.2.2+pg18 omni_worker0.1.00.2.1+pg18 pg_cardano1.0.51.1.1+pg18 pg_checksums1.21.3+pg18 pg_cron1.6.51.6.7+pg18 pg_duckdb0.3.11.1.0+pg18 pg_failover_slots1.1.01.2.0+pg18 pg_graphql1.5.111.5.12+pg18 pg_idkit0.3.10.4.0+pg18 pg_mooncake0.1.20.2.0+pg18 pg_net0.9.20.20.0+pg18 pg_parquet0.4.30.5.1+pg18 pg_partman5.2.45.3.0+pg18 pg_session_jwt0.3.10.3.3+pg18 pg_sphere1.5.11.5.2+pg18 pg_stat_monitor2.2.02.3.0+pg18 pg_statement_rollback1.41.5+pg18 pg_store_plans1.81.9+pg18 pg_task1.0.02.1.12+pg18 pg_tle1.5.11.5.2+pg18 pg_uuidv71.6.01.7.0+pg18 pglogical2.4.52.4.6+pg18 pgmq1.5.11.7.0+pg18 pgroonga4.0.04.0.4+pg18 pgsql_tweaks0.11.31.0.2+pg18 pldbgapi1.81.9+pg18 plprql1.0.018.0.0+pg18 supautils2.10.03.0.2+pg18 timescaledb2.22.02.23.0+pg18 timescaledb_toolkit1.21.01.22.0+pg18 vchord0.5.10.5.3+pg18 vectorize0.22.20.25.0+pg18 wrappers0.5.40.5.6+pg18 acl1.0.4- +pg18 aggs_for_arrays1.3.3- +pg18 aggs_for_vecs1.4.0- +pg18 base361.0.0- +pg18 hashlib1.1- +pg18 hll2.18- +pg18 imgsmlr1.0- +pg18 index_advisor0.2.0- +pg18 kafka_fdw0.0.3- +pg18 pg_auth_mon3.0- +pg18 pg_background1.3- +pg18 pg_bigm1.2- +pg18 pg_profile4.10- +pg18 pg_stat_kcache2.3.0- +pg18 pgdd0.6.0- +pg18 pgjwt0.2.0- +pg18 pgmp1.0.5- +pg18 plprofiler4.2.5- +pg18 plv83.2.4- +pg18 redis_fdw1.0- +pg18 repmgr5.5.0- +pg18 system_stats3.2- +pg18 topn2.7.0- +pg18 zhparser2.3- +pg18
2025-09-06 名称 旧版本 新版本 备注 timescaledb2.21.12.22.0citus13.1.013.2.0documentdb0.105.00.106.0work with ferretdb 2.5 ddlx0.290.30+ pg18 uint1281.0.01.1.0+ pg18 vchord0.4.30.5.1pgrx 0.16.0 pg_idkit0.3.00.3.1pgrx 0.15.0 pg_search0.17.30.18.0pgrx 0.15.0 pg_parquet0.4.00.4.3pgrx 0.16.0 wrappers0.5.30.5.4pgrx 0.14.3 pg_rewrite- 2.0.0+ Debian/Ubuntu pg_tracing- 0.1.3-2+ pg 14/18 pg_curl2.42.4.5pg_ivm1.111.12+ pg18 pg_rewrite- 2.0.0new extension pg_tracing- 1.3.0+ pg14 / pg18 pgactive2.1.52.1.6+ pg18 pgsentinel1.11.21.2 pg_tle1.5.1-11.5.1-2+ pg18 redis_fdw+ pg18 emaj4.64.7table_version1.11.01.11.1
2025-07-24 名称 旧版本 新版本 备注 orioledbbeta11 1.4beta12 1.5与 oriolepg 17.11 配合 oriolepg17.917.11与 orioledb 1.5 beta12 配合 documentdb0.104.00.105.0与 ferretdb 2.4 配合 timescaledb2.20.02.21.1supautils2.9.22.10.0.so 位置变更plv83.2.33.2.4postgresql_anonymizer3.1.12.3.0 (pgrx 0.14.3)wrappers0.5.00.5.3 (pgrx 0.14.3)pgrx 版本变更 pgvectorscale0.7.10.8.0 (pgrx 0.12.9)pg_search0.15.80.17.0 (download)修复 el icu 依赖问题 pg_profile4.8.04.10.0
2025-07-04 名称 旧版本 新版本 备注 orioledb1.4 beta11重新构建 pgvectorscale0.7.10.7.1重新构建修复错误 pg_stat_monitor2.1.12.2.0pgsql_tweaks0.11.10.11.3pg_tle1.5.01.5.1pg_curl2.42.4.5
2025-06-24 名称 旧版本 新版本 备注 citus13.0.313.1.0timescaledb2.20.02.21.0vchord0.3.00.4.3pgactive- 2.1.5需要 pgfeutils documentdb0.103.00.104.0添加 arm 支持
2025-05-26 2025-05-22 2025-05-07 2025-03-20 名称 旧版本 新版本 备注 timescaledb- 2.19.0citus- 13.0.2documentdb- 1.102pg_analytics- 0.3.7pg_search- 0.15.8pg_ivm- 1.10emaj- 4.6.0pgsql_tweaks- 0.11.0pgvectorscale- 0.6.0pg_session_jwt- 0.2.0wrappers- 0.4.5pg_parquet- 0.3.1vchord- 0.2.2pg_tle1.2.01.5.0supautils2.5.02.6.0sslutils1.31.4pg_profile4.74.8pg_jsonschema0.3.20.3.3pg_incremental1.1.11.2.0ddl_historization0.70.0.7pg_sqlog3.1.71.6pg_random- - pg_stat_monitor2.1.02.1.1pg_profile4.74.8
2024-10-16 名称 旧版本 新版本 备注 pg_ivm- 1.9pg_timeseries- 0.1.6pgmq- 1.4.4pg_protobuf- 16 17pg_uuidv7- 1.6pg_readonly- latestpgddl- 0.28pg_safeupdate- latestpg_stat_monitor- 2.1pg_profile- 4.7system_stats- 3.2pg_auth_mon- 3.0login_hook- 1.6logerrors- 2.1.3pg_orphaned- latestpgnodemx- 1.7sslutils- 1.4 (+16,17)
11 - 功能模块 12 - 模块:PGSQL 如何使用 Pigsty 部署并管理世界上最先进的开源关系型数据库 —— PostgreSQL,按需定制,开箱即用!
世界上最先进的开源关系型数据库!
而 Pigsty 帮它进入全盛状态:开箱即用、可靠、可观测、可维护、可伸缩! 配置 | 管理 | 剧本 | 监控 | 参数
概览 了解关于 PostgreSQL 的重要主题与概念。
配置 描述 你想要的 PostgreSQL 集群
身份参数 :定义 PostgreSQL 集群的身份参数读写主库 :创建由单一主库构成的单实例“集群”只读从库 :创建一主一从的两节点基础高可用集群离线从库 :创建专用于 OLAP/ETL/交互式查询的特殊只读实例同步备库 :启用同步提交,以确保没有数据丢失法定人数 :使用法定人数同步提交以获得更高的一致性级别备份集群 :克隆现有集群,并保持同步(异地灾备集群)延迟集群 :克隆现有集群,并延迟重放,用于紧急数据恢复Citus集群 :定义并创建 Citus 水平分布式数据库集群大版本切换 :使用不同的 PostgreSQL 大版本部署集群管理 管理 您所创建的 PostgreSQL 集群。
剧本 使用幂等的 剧本 ,将您的描述变为现实。
监控 在 Grafana 仪表盘 中查阅 PostgreSQL 的详情状态。
在 Pigsty 中共有 26 个与 PostgreSQL 相关的监控面板:
参数 PGSQL 模块的配置参数列表
教程 一些使用/管理 Pigsty 中 PostgreSQL 数据库的教程。
克隆一套现有的 PostgreSQL 集群 创建一套现有 PostgreSQL 集群的在线备份集群。 创建一套现有 PostgreSQL 集群的延迟备份集群 监控一个已有的 postgres 实例? 使用逻辑复制从外部 PostgreSQL 迁移至 Pigsty 托管的 PostgreSQL 实例? 使用 MinIO 作为集中的 pgBackRest 备份仓库。 使用专门的 etcd 集群作为 PostgreSQL / Patroni 的 DCS? 使用专用的 haproxy 负载均衡器集群对外暴露 PostgreSQL 服务。 使用 pg-meta CMDB 替代 pigsty.yml 作为配置清单源。 使用 PostgreSQL 作为 Grafana 的后端存储数据库? 使用 PostgreSQL 作为 Prometheus 后端存储数据库?
12.1 - 配置指南 12.2 - 集群配置 根据需求场景选择合适的实例与集群类型,配置出满足需求的 PostgreSQL 数据库集群。
Pigsty 是一个“配置驱动”的 PostgreSQL 平台:所有行为都来自 ~/pigsty/conf/*.yml 清单与 PGSQL 参数 的组合。
只要写好配置,你就能在几分钟内复刻出一套包含实例、用户、数据库、访问控制、扩展与调优策略的定制集群。
配置入口 准备清单 :复制 pigsty/conf/*.yml 模板或从零开始编写 Ansible Inventory,将集群分组(all.children.<cls>.hosts)与全局变量(all.vars)写入同一个文件。定义参数 :在 vars 区块中覆盖需要的 PGSQL 参数 。全局 → 集群 → 主机的覆盖顺序决定了最终值。应用配置 :运行 ./configure -c <conf> 或 bin/pgsql-add <cls> 等剧本让配置落地。Pigsty 会根据参数生成 Patroni/pgbouncer/pgbackrest 等服务所需的配置文件。Pigsty 默认的 Demo 清单 conf/pgsql.yml 就是一份最小化示例:一个 pg-meta 集群、全局 pg_version: 18、少量业务用户与数据库定义。你可以在此基础上扩展更多集群。
关注点与文档索引 Pigsty 的 PostgreSQL 配置可以从以下几个维度组合,后续文档会逐一展开“如何配置”:
集群实例 :通过 pg_cluster / pg_role / pg_seq / pg_upstream 定义实例拓扑(单机、主从、备份集群、延迟集群、Citus 等)。内核版本 :使用 pg_version、pg_mode、pg_packages、pg_extensions、pg_conf 等参数挑选核心版本、风味和调优模板。用户/角色 :在 pg_default_roles 与 pg_users 中声明系统角色、业务账号、密码策略以及连接池属性。数据库对象 :借助 pg_databases、baseline、schemas、extensions、pool_* 字段按需创建数据库并自动接入 pgbouncer/Grafana。访问控制 (HBA) :利用 pg_default_hba_rules 与 pg_hba_rules 维护主机级认证策略,保证不同角色/网络的访问边界。权限模型 (ACL) :通过 pg_default_privileges、pg_default_roles、pg_revoke_public 等参数收敛对象权限,开箱即用地提供分层角色体系。理解这些参数之后,你就可以针对任意业务需求写出“配置即基础设施”的声明式清单,Pigsty 会负责执行并确保幂等。
一个典型示例 下面的片段展示了如何在同一个配置文件中同时控制实例拓扑、内核版本、扩展、用户以及数据库:
all :
children :
pg-analytics :
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary }
10.10.10.12 : { pg_seq: 2, pg_role: replica, pg_offline_query : true }
vars :
pg_cluster : pg-analytics
pg_conf : olap.yml
pg_extensions : [ postgis, timescaledb, pgvector ]
pg_databases :
- { name: bi, owner: dbuser_bi, schemas: [mart], extensions: [timescaledb], pool_mode : session }
pg_users :
- { name: dbuser_bi, password: DBUser.BI, roles: [dbrole_admin], pgbouncer : true }
vars :
pg_version : 18
pg_packages : [ pgsql-main pgsql-common ]
pg_hba_rules :
- { user: dbuser_bi, db: bi, addr: intra, auth: ssl, title : 'BI 只允许内网 SSL 访问' }
pg-analytics 集群包含一个主库和一个离线副本。全局指定 pg_version: 18 与一套扩展示例,并加载 olap.yml 调优。 在 pg_databases 与 pg_users 中声明业务对象,自动生成 schema/extension 与连接池条目。 附加的 pg_hba_rules 限制了访问来源与认证方式。 修改并应用这份清单即可得到一套定制化的 PostgreSQL 集群,而无需手工逐项配置。
12.2.1 - 集群实例 根据需求场景选择合适的实例与集群类型,配置出满足需求的 PostgreSQL 数据库集群。
根据需求场景选择合适的实例与集群类型,配置出满足需求的 PostgreSQL 数据库集群。
您可以定义不同类型的实例和集群,下面是 Pigsty 中常见的几种 PostgreSQL 实例/集群类型:
读写主库 我们从最简单的情况开始:由一个主库(Primary)组成的单实例集群:
pg-test :
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary }
vars :
pg_cluster : pg-test
这段配置言简意赅,自我描述,仅由 身份参数 构成,请注意 Ansible Group 分组名应当与 pg_cluster 保持一致。
使用以下命令创建该集群:
Demo 展示,开发测试,承载临时需求,进行无关紧要的计算分析任务时,使用单一数据库实例可能并没有太大问题。但这样的单机集群没有 高可用 ,当出现硬件故障时,您需要使用 PITR 或其他恢复手段来确保集群的 RTO / RPO。为此,您可以考虑为集群添加若干个 只读从库
只读从库 要添加一台只读从库(Replica)实例,您可以在 pg-test 中添加一个新节点,并将其 pg_role 设置为replica。
pg-test :
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary }
10.10.10.12 : { pg_seq: 2, pg_role : replica } # <--- 新添加的从库
vars :
pg_cluster : pg-test
如果整个集群不存在,您可以直接 创建 这个完整的集群。 如果集群主库已经初始化好了,那么您可以向现有集群 添加 一个从库:
bin/pgsql-add pg-test # 一次性初始化整个集群
bin/pgsql-add pg-test 10.10.10.12 # 添加从库到现有的集群
当集群主库出现故障时,只读实例(Replica)可以在高可用系统的帮助下接管主库的工作。除此之外,只读实例还可以用于执行只读查询:许多业务的读请求要比写请求多很多,而大部分只读查询负载都可以由从库实例承担。
离线从库 离线实例(Offline)是专门用于服务慢查询、ETL、OLAP 流量和交互式查询等的专用只读从库。慢查询/长事务对在线业务的性能与稳定性有不利影响,因此最好将它们与在线业务隔离开来。
要添加离线实例,请为其分配一个新实例,并将 pg_role 设置为offline。
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
专用离线实例的工作方式与常见的从库实例类似,但它在 pg-test-replica 服务中用作备份服务器。 也就是说,只有当所有replica实例都宕机时,离线和主实例才会提供此项只读服务。
许多情况下,数据库资源有限,单独使用一台服务器作为离线实例是不经济的做法。作为折中,您可以选择一台现有的从库实例,打上 pg_offline_query 标记,将其标记为一台可以承载"离线查询"的实例。在这种情况下,这台只读从库会同时承担在线只读请求与离线类查询。您可以使用 pg_default_hba_rules 和 pg_hba_rules 对离线实例进行额外的访问控制。
同步备库 当启用同步备库(Sync Standby)时,PostgreSQL 将选择一个从库作为同步备库 ,其他所有从库作为候选者 。 主数据库会等待备库实例刷新到磁盘,然后才确认提交,备库实例始终拥有最新的数据,没有复制延迟,主从切换至同步备库不会有数据丢失。
PostgreSQL 默认使用异步流复制,这可能会有小的复制延迟(10KB / 10ms 数量级)。当主库失败时,可能会有一个小的数据丢失窗口(可以使用 pg_rpo 来控制),但对于大多数场景来说,这是可以接受的。
但在某些关键场景中(例如,金融交易),数据丢失是完全不可接受的,或者,读取复制延迟是不可接受的。在这种情况下,您可以使用同步提交来解决这个问题。 要启用同步备库模式,您可以简单地使用 pg_conf 中的crit.yml模板。
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
pg_conf : crit.yml # <--- 使用 crit 模板
要在现有集群上启用同步备库,请 配置集群 并启用 synchronous_mode:
$ pg edit-config pg-test # 在管理员节点以管理员用户身份运行
+++
-synchronous_mode: false # <--- 旧值
+synchronous_mode: true # <--- 新值
synchronous_mode_strict: false
应用这些更改?[ y/N] : y
在这种情况下,PostgreSQL 配置项 synchronous_standby_names 由 Patroni 自动管理。
一台从库将被选拔为同步从库,它的 application_name 将被写入 PostgreSQL 主库配置文件中并应用生效。
法定人数提交 法定人数提交(Quorum Commit)提供了比同步备库更强大的控制能力:特别是当您有多个从库时,您可以设定提交成功的标准,实现更高/更低的一致性级别(以及可用性之间的权衡)。
如果想要最少两个从 库来确认提交,可以通过 Patroni 配置集群 ,调整参数 synchronous_node_count 并应用生效
synchronous_mode : true # 确保同步提交已经启用
synchronous_node_count : 2 # 指定“至少”有多少个从库提交成功,才算提交成功
如果你想要使用更多的同步从库,修改 synchronous_node_count 的取值即可。当集群的规模发生变化时,您应当确保这里的配置仍然是有效的,以避免服务不可用。
在这种情况下,PostgreSQL 配置项 synchronous_standby_names 由 Patroni 自动管理。
synchronous_standby_names = '2 ("pg-test-3","pg-test-2")'
示例:使用多个同步从库 $ pg edit-config pg-test
---
+synchronous_node_count: 2
Apply these changes? [ y/N] : y
应用配置后,出现两个同步备库。
+ Cluster: pg-test ( 7080814403632534854) +---------+----+-----------+-----------------+
| Member | Host | Role | State | TL | Lag in MB | Tags |
+-----------+-------------+--------------+---------+----+-----------+-----------------+
| pg-test-1 | 10.10.10.10 | Leader | running | 1 | | clonefrom: true |
| pg-test-2 | 10.10.10.11 | Sync Standby | running | 1 | 0 | clonefrom: true |
| pg-test-3 | 10.10.10.12 | Sync Standby | running | 1 | 0 | clonefrom: true |
+-----------+-------------+--------------+---------+----+-----------+-----------------+
另一种情景是,使用 任意 n 个 从库来确认提交。在这种情况下,配置的方式略有不同,例如,假设我们只需要任意一个从库确认提交:
synchronous_mode : quorum # 使用法定人数提交
postgresql :
parameters : # 修改 PostgreSQL 的配置参数 synchronous_standby_names ,使用 `ANY n ()` 语法
synchronous_standby_names : 'ANY 1 (*)' # 你可以指定具体的从库列表,或直接使用 * 通配所有从库。
示例:启用 ANY 法定人数提交 $ pg edit-config pg-test
+ synchronous_standby_names: 'ANY 1 (*)' # 在 ANY 模式下,需要使用此参数
- synchronous_node_count: 2 # 在 ANY 模式下, 不需要使用此参数
Apply these changes? [ y/N] : y
应用后,配置生效,所有备库在 Patroni 中变为普通的 replica。但是在 pg_stat_replication 中可以看到 sync_state 会变为 quorum。
备份集群 您可以克隆现有的集群,并创建一个备份集群(Standby Cluster),用于数据迁移、水平拆分、多区域部署,或灾难恢复。
在正常情况下,备份集群将追随上游集群并保持内容同步,您可以将备份集群提升,作为真正地独立集群。
备份集群的定义方式与正常集群的定义基本相同,除了在主库上额外定义了 pg_upstream 参数,备份集群的主库被称为 备份集群领导者 (Standby Leader)。
例如,下面定义了一个pg-test集群,以及其备份集群pg-test2,其配置清单可能如下所示:
# pg-test 是原始集群
pg-test :
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary }
vars : { pg_cluster : pg-test }
# pg-test2 是 pg-test 的备份集群
pg-test2 :
hosts :
10.10.10.12 : { pg_seq: 1, pg_role: primary , pg_upstream : 10.10.10.11 } # <--- pg_upstream 在这里定义
10.10.10.13 : { pg_seq: 2, pg_role : replica }
vars : { pg_cluster : pg-test2 }
而 pg-test2 集群的主节点 pg-test2-1 将是 pg-test 的下游从库,并在pg-test2集群中充当备份集群领导者(Standby Leader )。
只需确保备份集群的主节点上配置了 pg_upstream 参数,以便自动从原始上游拉取备份。
bin/pgsql-add pg-test # 创建原始集群
bin/pgsql-add pg-test2 # 创建备份集群
示例:更改复制上游 如有必要(例如,上游发生主从切换/故障转移),您可以通过 配置集群 更改备份集群的复制上游。
要这样做,只需将standby_cluster.host更改为新的上游 IP 地址并应用。
$ pg edit-config pg-test2
standby_cluster:
create_replica_methods:
- basebackup
- host: 10.10.10.13 # <--- 旧的上游
+ host: 10.10.10.12 # <--- 新的上游
port: 5432
Apply these changes? [ y/N] : y
示例:提升备份集群 你可以随时将备份集群提升为独立集群,这样该集群就可以独立承载写入请求,并与原集群分叉。
为此,你必须 配置 该集群并完全擦除standby_cluster部分,然后应用。
$ pg edit-config pg-test2
-standby_cluster:
- create_replica_methods:
- - basebackup
- host: 10.10.10.11
- port: 5432
Apply these changes? [ y/N] : y
示例:级联复制 如果您在一台从库上指定了 pg_upstream ,而不是主库。那么可以配置集群的 级联复制 (Cascade Replication)
在配置级联复制时,您必须使用集群中某一个实例的 IP 地址作为参数的值,否则初始化会报错。该从库从特定的实例进行流复制,而不是主库。
这台充当 WAL 中继器的实例被称为 桥接实例 (Bridge Instance)。使用桥接实例可以分担主库发送 WAL 的负担,当您有几十台从库时,使用桥接实例级联复制是一个不错的注意。
pg-test :
hosts : # pg-test-1 ---> pg-test-2 ---> pg-test-3
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, pg_upstream : 10.10.10.12 }
# ^--- 从 pg-test-2 (桥接)复制,而不是从 pg-test-1 (主节点)
vars : { pg_cluster : pg-test }
延迟集群 延迟集群(Delayed Cluster)是一种特殊类型的 备份集群 ,用于尽快恢复"意外删除"的数据。
例如,如果你希望有一个名为 pg-testdelay 的集群,其数据内容与一小时前的 pg-test 集群相同:
# pg-test 是原始集群
pg-test :
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary }
vars : { pg_cluster : pg-test }
# pg-testdelay 是 pg-test 的延迟集群
pg-testdelay :
hosts :
10.10.10.12 : { pg_seq: 1, pg_role: primary , pg_upstream: 10.10.10.11, pg_delay : 1d }
10.10.10.13 : { pg_seq: 2, pg_role : replica }
vars : { pg_cluster : pg-testdelay }
你还可以在现有的 备份集群 上 配置 一个"复制延迟"。
$ pg edit-config pg-testdelay
standby_cluster:
create_replica_methods:
- basebackup
host: 10.10.10.11
port: 5432
+ recovery_min_apply_delay: 1h # <--- 在此处添加延迟时长,例如1小时
Apply these changes? [ y/N] : y
当某些元组和表格被意外删除时,你可以通过修改此参数的方式,将此延迟集群推进到适当的时间点,并从中读取数据,快速修复原始集群。
延迟集群需要额外的资源,但比起 PITR 要快得多,并且对系统的影响也小得多,对于非常关键的集群,可以考虑搭建延迟集群。
Citus集群 Pigsty 原生支持 Citus。可以参考 files/pigsty/citus.yml 与 prod.yml 作为样例。
要定义一个 citus 集群,您需要指定以下参数:
此外,还需要额外的 hba 规则,允许从本地和其他数据节点进行 SSL 访问。如下所示:
all :
children :
pg-citus0 : # citus 0号分片
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus0 , pg_group : 0 }
pg-citus1 : # citus 1号分片
hosts : { 10.10.10.11 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus1 , pg_group : 1 }
pg-citus2 : # citus 2号分片
hosts : { 10.10.10.12 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus2 , pg_group : 2 }
pg-citus3 : # citus 3号分片
hosts :
10.10.10.13 : { pg_seq: 1, pg_role : primary }
10.10.10.14 : { pg_seq: 2, pg_role : replica }
vars : { pg_cluster: pg-citus3 , pg_group : 3 }
vars : # 所有 Citus 集群的全局参数
pg_mode : citus # pgsql 集群模式需要设置为: citus
pg_shard : pg-citus # citus 水平分片名称: pg-citus
pg_primary_db : meta # citus 数据库名称:meta
pg_dbsu_password : DBUser.Postgres # 如果使用 dbsu ,那么需要为其配置一个密码
pg_users : [ { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles : [ dbrole_admin ] } ]
pg_databases : [ { name: meta ,extensions : [ { name : citus }, { name: postgis }, { name: timescaledb } ] } ]
pg_hba_rules :
- { user: 'all' ,db: all ,addr: 127.0.0.1/32 ,auth: ssl ,title : 'all user ssl access from localhost' }
- { user: 'all' ,db: all ,addr: intra ,auth: ssl ,title : 'all user ssl access from intranet' }
在协调者节点上,您可以创建分布式表和引用表,并从任何数据节点查询它们。从 11.2 开始,任何 Citus 数据库节点都可以扮演协调者的角色了。
SELECT create_distributed_table( 'pgbench_accounts' , 'aid' ) ; SELECT truncate_local_data_after_distributing_table( $$ public.pgbench_accounts$$ ) ;
SELECT create_reference_table( 'pgbench_branches' ) ; SELECT truncate_local_data_after_distributing_table( $$ public.pgbench_branches$$ ) ;
SELECT create_reference_table( 'pgbench_history' ) ; SELECT truncate_local_data_after_distributing_table( $$ public.pgbench_history$$ ) ;
SELECT create_reference_table( 'pgbench_tellers' ) ; SELECT truncate_local_data_after_distributing_table( $$ public.pgbench_tellers$$ ) ;
12.2.2 - 内核版本 如何选择合适的 PostgreSQL 内核与大版本。
在 Pigsty 中选择"内核"意味着确定 PostgreSQL 大版本、模式/发行版、需要安装的包以及要加载的调优模板。
Pigsty v4.3 当前支持 PostgreSQL 14 - 18,默认使用 18。下方内容展示如何通过配置文件完成这些选择。
大版本与软件包 pg_version:指定 PostgreSQL 主版本(默认 18)。Pigsty 会根据版本自动映射到正确的包名前缀。pg_packages:定义需要安装的核心包集合,支持使用 包别名 (默认 pgsql-main pgsql-common,包含内核 + patroni/pgbouncer/pgbackrest 等常用工具)。pg_extensions:额外需要安装的扩展包列表,同样支持别名;缺省为空表示只装核心依赖。all :
vars :
pg_version : 18
pg_packages : [ pgsql-main pgsql-common ]
pg_extensions : [ postgis, timescaledb, pgvector, pgml ]
效果:Ansible 在安装阶段会拉取与 pg_version=18 对应的包,将扩展预装到系统中,随后数据库初始化脚本即可直接 CREATE EXTENSION。
Pigsty 的离线仓库中不同版本的扩展支持范围不同:14 可用扩展相对较少,17/18 覆盖最广。若某扩展未预打包,可通过 repo_packages_extra 追加。
内核模式(pg_mode) pg_mode 控制要部署的内核“风味”,默认 pgsql 表示标准 PostgreSQL。Pigsty 目前支持以下模式:
模式 场景 pgsql标准 PostgreSQL,高可用 + 复制 citusCitus 分布式集群,需要额外的 pg_shard / pg_group gpsqlCloudberry / Greenplum / MatrixDB mssqlBabelfish mysqlOpenGauss/HaloDB 兼容 MySQL 协议 polar阿里 PolarDB(基于 pg polar 发行) ivoryIvorySQL(Oracle 兼容语法) orioleOrioleDB 存储引擎 oraclePostgreSQL + ora 兼容(pg_mode: oracle)
选择模式后,Pigsty 会自动加载对应的模板、依赖包与 Patroni 配置。以部署 Citus 为例:
all :
children :
pg-citus0 :
hosts : { 10.10.10.11 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus0, pg_group : 0 }
pg-citus1 :
hosts : { 10.10.10.12 : { pg_seq: 1, pg_role : primary } }
vars : { pg_cluster: pg-citus1, pg_group : 1 }
vars :
pg_mode : citus
pg_shard : pg-citus
patroni_citus_db : meta
效果:所有成员会安装 Citus 相关包,Patroni 以分片模式写入 etcd,并自动在 meta 数据库内 CREATE EXTENSION citus。
扩展与预置对象 除了系统包,你还可以通过以下参数控制数据库启动后自动加载的组件:
pg_libs:写入 shared_preload_libraries 的列表。例如 pg_libs: 'timescaledb, pg_stat_statements, auto_explain'。pg_default_extensions / pg_default_schemas:控制初始化脚本对 template1 与 postgres 预创建的 schema、扩展。pg_parameters:为所有实例附加 ALTER SYSTEM SET(写入 postgresql.auto.conf)。示例:启用 TimescaleDB、pgvector 并自定义一些系统参数。
pg-analytics :
vars :
pg_cluster : pg-analytics
pg_libs : 'timescaledb, pg_stat_statements, pgml'
pg_default_extensions :
- { name : timescaledb }
- { name : pgvector }
pg_parameters :
timescaledb.max_background_workers : 8
shared_preload_libraries : "'timescaledb,pg_stat_statements,pgml'"
效果:初始化时 template1 会创建扩展、Patroni 的 postgresql.conf 注入对应参数,所有业务库继承这些设置。
调优模板 (pg_conf) pg_conf 指向 roles/pgsql/templates/*.yml 中的 Patroni 模板。Pigsty 内置四套通用模板:
模板 适用场景 oltp.yml默认模板,面向 4–128 核的 TP 负载 olap.yml针对分析场景优化 crit.yml强调同步提交/最小延迟,适合金融等零丢失场景 tiny.yml轻量机 / 边缘场景 / 资源受限环境
你可以直接替换模板或自定义一个 YAML 文件放在 templates/ 下,然后在集群 vars 里指定。
pg-ledger :
hosts : { 10.10.10.21 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-ledger
pg_conf : crit.yml
pg_parameters :
synchronous_commit : 'remote_apply'
max_wal_senders : 16
wal_keep_size : '2GB'
效果:拷贝 crit.yml 作为 Patroni 配置,叠加 pg_parameters 写入 postgresql.auto.conf,使实例立即以同步提交模式运行。
组合实例:一个完整示例 pg-rag :
hosts :
10.10.10.31 : { pg_seq: 1, pg_role : primary }
10.10.10.32 : { pg_seq: 2, pg_role : replica }
vars :
pg_cluster : pg-rag
pg_version : 18
pg_mode : pgsql
pg_conf : olap.yml
pg_packages : [ pgsql-main pgsql-common ]
pg_extensions : [ pgvector, pgml, postgis ]
pg_libs : 'pg_stat_statements, pgvector, pgml'
pg_parameters :
max_parallel_workers : 8
shared_buffers : '32GB'
第一台主库 + 一台 replica,使用 olap.yml 调优。 安装 PG18 + RAG 常用扩展,自动在系统级加载 pgvector/pgml。 Patroni/pgbouncer/pgbackrest 由 Pigsty 生成,无需手工干预。 根据业务需要替换上述参数即可完成内核层的全部定制。
12.2.3 - 别名翻译 Pigsty 提供软件包别名翻译机制,可以屏蔽底层操作系统的二进制包细节差异,让安装更简易。
PostgreSQL 在不同操作系统上的软件包命名规则存在显著差异:
EL 系统 (RHEL/Rocky/Alma/…)使用 pgvector_18,postgis36_18* 这样的格式Debian/Ubuntu 系统 使用 postgresql-18-pgvector,postgresql-18-postgis-3 这样的格式这种差异给用户带来了额外的认知负担:您需要记住不同系统的包名规则,还要处理 PostgreSQL 版本号嵌入的问题。
软件包别名 Pigsty 通过 软件包别名(Package Alias) 机制解决了这个问题:您只需使用统一的别名,Pigsty 会处理好所有细节:
# 使用别名 —— 简单、统一、跨平台
pg_extensions : [ postgis, pgvector, timescaledb ]
# 等效于 EL9 + PG18 上的实际包名
pg_extensions : [ postgis36_18*, pgvector_18*, timescaledb-tsl_18* ]
# 等效于 Ubuntu 24 + PG18 上的实际包名
pg_extensions : [ postgresql-18-postgis-3, postgresql-18-pgvector, postgresql-18-timescaledb-tsl ]
别名翻译 别名还可以将一组软件包归类为一个整体,例如 Pigsty 默认安装的软件包 —— pg_packages 的默认值是:
pg_packages : # pg packages to be installed, alias can be used
- pgsql-main pgsql-common
Pigsty 将查询当前的操作系统别名清单(假设为 el10.x86_64 ),将其翻译为 PGSQL 内核,扩展,以及工具包:
pgsql-main : "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl postgresql$v-llvmjit pg_repack_$v* wal2json_$v* pgvector_$v*"
pgsql-common : "patroni patroni-etcd pgbouncer pgbackrest pg_exporter pgbackrest_exporter vip-manager"
接下来,Pigsty 又进一步通过当前指定的 PG 大版本(假设 pg_version = 18),将 pgsql-main 翻译为:
pg18-main : "postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl postgresql18-llvmjit pg_repack_18* wal2json_18* pgvector_18*"
通过这种方式,Pigsty 屏蔽了软件包的复杂性,让用户可以简单的指定自己想要的功能组件。
哪些变量可以使用别名? 您可以在以下四个参数中使用包别名,别名会根据翻译流程自动转换为实际的软件包名称:
别名列表 你可以在 Pigsty 项目源代码的 roles/node_id/vars/ 目录下,找到各操作系统与架构对应的别名映射文件:
工作原理 别名翻译流程 用户配置别名 --> 检测操作系统 --> 查找别名映射表 ---> 替换$v占位符 ---> 安装实际软件包
↓ ↓ ↓ ↓
postgis el9.x86_64 postgis36_$v * postgis36_18*
postgis u24.x86_64 postgresql-$v -postgis-3 postgresql-18-postgis-3
版本占位符 Pigsty 的别名系统使用 $v 作为 PostgreSQL 版本号的占位符。当您使用 pg_version 指定了 PostgreSQL 版本后,所有别名中的 $v 都会被替换为实际版本号。
例如,当 pg_version: 18 时:
别名定义 (EL) 展开结果 postgresql$v*postgresql18*pgvector_$v*pgvector_18*timescaledb-tsl_$v*timescaledb-tsl_18*
别名定义 (Debian/Ubuntu) 展开结果 postgresql-$vpostgresql-18postgresql-$v-pgvectorpostgresql-18-pgvectorpostgresql-$v-timescaledb-tslpostgresql-18-timescaledb-tsl
通配符匹配 在 EL 系统上,许多别名使用 * 通配符来匹配相关的子包。例如:
postgis36_18* 会匹配 postgis36_18、postgis36_18-client、postgis36_18-utils 等postgresql18* 会匹配 postgresql18、postgresql18-server、postgresql18-libs、postgresql18-contrib 等这种设计确保您无需逐一列出每个子包,一个别名即可安装完整的扩展。
12.2.4 - 用户/角色 如何通过配置来定制所需 PostgreSQL 用户与角色?
在本文中,“用户”(User) 指的是使用 SQL 命令 CREATE USER/ROLE 创建的,数据库集簇内的逻辑对象。
在 PostgreSQL 中,用户直接隶属于数据库集簇而非某个具体的数据库。因此在创建业务数据库和业务用户时,应当遵循"先用户,后数据库"的原则。
Pigsty 通过两个配置参数定义数据库集群中的角色与用户:
前者用于定义整套环境中共用的角色与用户,后者定义单个集群中特有的业务角色与用户。二者形式相同,均为用户定义对象的数组。
用户/角色按数组顺序逐一创建,因此后定义的用户可以属于先定义的角色。
默认情况下,所有带有 pgbouncer: true 标记的用户都会被添加到 Pgbouncer 连接池用户列表中。
定义用户 下面是 Pigsty 演示环境中默认集群 pg-meta 中的业务用户定义:
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 : pigsty admin user }
- {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment : read-only viewer for meta database }
- {name: dbuser_grafana ,password: DBUser.Grafana ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for grafana database }
- {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for bytebase database }
- {name: dbuser_kong ,password: DBUser.Kong ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for kong api gateway }
- {name: dbuser_gitea ,password: DBUser.Gitea ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for gitea service }
- {name: dbuser_wiki ,password: DBUser.Wiki ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for wiki.js service }
- {name: dbuser_noco ,password: DBUser.Noco ,pgbouncer: true ,roles: [dbrole_admin] ,comment : admin user for nocodb service }
- {name: dbuser_remove ,state: absent } # 使用 state : absent 删除用户
每个用户/角色定义都是一个复杂对象,可能包括以下字段,除了 name 字段外,其他字段均为可选字段:
- name : dbuser_meta # 必选,`name` 是用户定义的唯一必选字段
state : create # 可选,用户状态:create(创建,默认)、absent(删除)
password : DBUser.Meta # 可选,密码,可以是 scram-sha-256 哈希字符串或明文
login : true # 可选,默认为 true,是否可以登录
superuser : false # 可选,默认为 false,是否是超级用户
createdb : false # 可选,默认为 false,是否可以创建数据库
createrole : false # 可选,默认为 false,是否可以创建角色
inherit : true # 可选,默认为 true,是否自动继承所属角色权限
replication : false # 可选,默认为 false,是否可以发起流复制连接
bypassrls : false # 可选,默认为 false,是否可以绕过行级安全
connlimit : -1 # 可选,用户连接数限制,默认 -1 不限制
expire_in : 3650 # 可选,从创建时起 N 天后过期(优先级比 expire_at 高)
expire_at : '2030-12-31' # 可选,过期日期,使用 YYYY-MM-DD 格式(优先级没 expire_in 高)
comment : pigsty admin user # 可选,用户备注信息
roles : [ dbrole_admin] # 可选,所属角色数组
parameters : # 可选,角色级配置参数
search_path : public
pgbouncer : true # 可选,是否加入连接池用户列表,默认 false
pool_mode : transaction # 可选,用户级别的池化模式,默认 transaction
pool_connlimit : -1 # 可选,用户级别的连接池最大连接数,默认 -1 不限制
用户级连接池限额字段统一使用 pool_connlimit(对应 Pgbouncer max_user_connections)。
参数总览 所有参数中唯一 必选 的字段是 name,它应该是当前 PostgreSQL 集群中有效且唯一的用户名,其他参数都有合理的默认值,均为可选项。
参数详情 name字符串,必选参数,表示用户的名称,在一个数据库集群内必须唯一。
用户名必须是有效的 PostgreSQL 标识符,必须匹配正则表达式 ^[a-z_][a-z0-9_]{0,62}$ :
以小写字母或下划线开头,只能包含小写字母、数字、下划线,最长 63 个字符。
- name : dbuser_app # 标准命名
- name : app_readonly # 下划线分隔
- name : _internal # 下划线开头(用于内部角色)
state枚举值,用于指定要对用户执行的操作,可以是 create 或 absent,默认值为 create。
状态 说明 create默认,创建用户,如果已存在则更新属性 absent删除用户,使用 DROP ROLE
- name : dbuser_app # state 默认为 create
- name : dbuser_old
state : absent # 删除用户
以下系统用户无法通过 state: absent 删除,这是为了防止误删关键系统用户导致集群故障:
password字符串,可变参数,用于设置用户密码,不指定则用户无法使用密码登录。
密码可以是以下格式之一:
格式 示例 说明 明文密码 DBUser.Meta不推荐,会被记录到配置文件和日志 SCRAM-SHA-256 SCRAM-SHA-256$4096:xxx$yyy:zzz推荐,PostgreSQL 10+ 默认认证方式 MD5 哈希 md5...兼容旧版本,不推荐新项目使用
# 明文密码(不推荐,会被记录到配置和日志中)
- name : dbuser_app
password : MySecretPassword
# SCRAM-SHA-256 哈希(推荐)
- name : dbuser_app
password : 'SCRAM-SHA-256$4096:xxx$yyy:zzz'
设置密码时,Pigsty 会临时屏蔽当前会话的日志记录以避免密码泄露:
SET log_statement TO 'none' ;
ALTER USER "dbuser_app" PASSWORD 'xxx' ;
SET log_statement TO DEFAULT ;
如果你不希望在配置文件中记录明文密码,可以使用 SCRAM-SHA-256 哈希字符串代替明文密码。生成 SCRAM-SHA-256 哈希的方法:
# 使用 PostgreSQL 生成(需要先连接到数据库,数据库有 pgcrypto 扩展)
psql -c "SELECT encode(digest('password' || 'username', 'sha256'), 'hex')"
字符串,可变参数,用于设置用户的备注信息,如果不指定,默认值为 business user {name}。
用户备注信息通过 COMMENT ON ROLE 语句设置,支持中文和特殊字符(Pigsty 会自动转义单引号)。
- name : dbuser_app
comment : '业务应用主账号'
COMMENT ON ROLE "dbuser_app" IS '业务应用主账号' ;
login布尔值,可变参数,用于控制用户是否可以登录,默认值为 true。
设置为 false 则创建的是无法登陆的 角色 (Role)而非用户(User),通常用于权限分组。
在 PostgreSQL 中,CREATE USER 等价于 CREATE ROLE ... LOGIN。
# 创建可登录用户
- name : dbuser_app
login : true
# 创建角色(不可登录,用于权限分组)
- name : dbrole_custom
login : false
comment : 自定义权限角色
CREATE USER "dbuser_app" LOGIN ;
CREATE USER "dbrole_custom" NOLOGIN ;
superuser布尔值,可变参数,用于指定用户是否为超级用户,默认值为 false。
超级用户拥有数据库的全部权限,可以绕过所有权限检查。
- name : dbuser_admin
superuser : true # 危险:拥有全部权限
ALTER USER "dbuser_admin" SUPERUSER ;
Pigsty 已经提供了默认的超级用户 pg_admin_username (dbuser_dba)
除非绝对必要,否则不应创建额外的超级用户。
createdb布尔值,可变参数,用于指定用户是否可以创建数据库,默认值为 false。
- name : dbuser_dev
createdb : true # 允许创建数据库
ALTER USER "dbuser_dev" CREATEDB ;
一些应用软件可能会要求自己创建数据库,例如 Gitea,Odoo 等,因此您可能需要为这些应用的管理员用户启用 CREATEDB 权限。
createrole布尔值,可变参数,用于指定用户是否可以创建其他角色,默认值为 false。
拥有 CREATEROLE 权限的用户可以创建、修改、删除其他非超级用户角色。
- name : dbuser_admin
createrole : true # 允许管理其他角色
ALTER USER "dbuser_admin" CREATEROLE ;
inherit布尔值,可变参数,用于控制用户是否自动继承所属角色的权限,默认值为 true。
设置为 false 时,用户需要通过 SET ROLE 显式切换角色才能使用所属角色的权限。
# 自动继承角色权限(默认)
- name : dbuser_app
inherit : true
roles : [ dbrole_readwrite]
# 需要显式切换角色
- name : dbuser_special
inherit : false
roles : [ dbrole_admin]
ALTER USER "dbuser_special" NOINHERIT ;
-- 用户需要执行 SET ROLE dbrole_admin 才能获得该角色权限(必要但不充分)
replication布尔值,可变参数,用于指定用户是否可以发起流复制连接,默认值为 false。
通常只有复制用户(如 replicator)需要此权限。普通业务用户不应该拥有此权限,除非这是一个逻辑解码订阅者。
- name : replicator
replication : true # 允许流复制连接
roles : [ pg_monitor, dbrole_readonly]
ALTER USER "replicator" REPLICATION ;
bypassrls布尔值,可变参数,用于指定用户是否可以绕过行级安全(RLS)策略,默认值为 false。
启用此权限后,用户可以访问所有行,即使表上定义了行级安全策略。此权限通常只授予管理员用户。
- name : dbuser_myappadmin
bypassrls : true # 绕过行级安全策略
ALTER USER "dbuser_myappadmin" BYPASSRLS ;
connlimit整数,可变参数,用于限制用户的最大并发连接数,默认值为 -1,表示不限制。
设置为正整数时,会限制该用户同时建立的最大数据库连接数。此限制不影响超级用户。
- name : dbuser_app
connlimit : 100 # 最多 100 个并发连接
- name : dbuser_batch
connlimit : 10 # 批处理用户限制连接数
ALTER USER "dbuser_app" CONNECTION LIMIT 100 ;
expire_in整数,可变参数,用于指定用户从当前日期起多少天后过期。
此参数优先级高于 expire_at ,如果同时指定两者,只有 expire_in 生效。
每次执行剧本时会根据当前日期重新计算过期时间,适合用于临时用户或需要定期续期的场景。
- name : temp_user
expire_in : 30 # 30 天后过期
- name : contractor_user
expire_in : 90 # 90 天后过期
执行时会计算实际过期日期并生成对应的 SQL:
-- expire_in: 30, 假设当前日期为 2025-01-01
ALTER USER "temp_user" VALID UNTIL '2025-01-31' ;
expire_at字符串,可变参数,用于指定用户的过期日期,格式为 YYYY-MM-DD 或特殊值 infinity。
此参数优先级低于 expire_in 。使用 infinity 表示用户永不过期。
- name : contractor_user
expire_at : '2024-12-31' # 指定日期过期
- name : permanent_user
expire_at : 'infinity' # 永不过期
ALTER USER "contractor_user" VALID UNTIL '2024-12-31' ;
ALTER USER "permanent_user" VALID UNTIL 'infinity' ;
roles数组,增量参数,用于定义用户所属的角色。数组元素可以是字符串或对象。
简单格式使用字符串直接指定角色名:
- name : dbuser_app
roles :
- dbrole_readwrite
- pg_read_all_data
GRANT "dbrole_readwrite" TO "dbuser_app" ;
GRANT "pg_read_all_data" TO "dbuser_app" ;
完整格式使用对象定义,支持更精细的角色成员关系控制:
- name : dbuser_app
roles :
- dbrole_readwrite # 简单字符串:GRANT 角色
- { name: dbrole_admin, admin : true } # 带 ADMIN OPTION
- { name: pg_monitor, set: false } # PG16+ : 不允许 SET ROLE
- { name: pg_signal_backend, inherit: false } # PG16+ : 不自动继承权限
- { name: old_role, state : absent } # 撤销角色成员关系
对象格式参数说明 :
参数 类型 说明 namestring 角色名称(必选) stateenum grant(默认)或 absent/revoke:控制授予或撤销adminbool true:WITH ADMIN OPTION,false:REVOKE ADMINsetbool PG16+:true:WITH SET TRUE,false:REVOKE SET inheritbool PG16+:true:WITH INHERIT TRUE,false:REVOKE INHERIT
PostgreSQL 16+ 新特性 :
PostgreSQL 16 引入了更细粒度的角色成员关系控制:
ADMIN OPTION :允许将角色授予其他用户SET OPTION :允许使用 SET ROLE 切换到该角色INHERIT OPTION :是否自动继承该角色的权限# PostgreSQL 16+ 完整示例
- name : dbuser_app
roles :
# 普通成员关系
- dbrole_readwrite
# 可以将 dbrole_admin 授予其他用户
- { name: dbrole_admin, admin : true }
# 不能 SET ROLE 到 pg_monitor(只能通过继承使用权限)
- { name: pg_monitor, set : false }
# 不自动继承 pg_execute_server_program 的权限(需要显式 SET ROLE)
- { name: pg_execute_server_program, inherit : false }
# 撤销 old_role 的成员关系
- { name: old_role, state : absent }
set 和 inherit 选项仅在 PostgreSQL 16+ 中有效,在早期版本会被忽略并在生成的 SQL 中添加警告注释。
parameters对象,可变参数,用于设置角色级别的配置参数。参数通过 ALTER ROLE ... SET 设置,会对该用户的所有会话生效。
- name : dbuser_analyst
parameters :
work_mem : '256MB'
statement_timeout : '5min'
search_path : 'analytics,public'
log_statement : 'all'
ALTER USER "dbuser_analyst" SET "work_mem" = '256MB' ;
ALTER USER "dbuser_analyst" SET "statement_timeout" = '5min' ;
ALTER USER "dbuser_analyst" SET "search_path" = 'analytics,public' ;
ALTER USER "dbuser_analyst" SET "log_statement" = 'all' ;
使用特殊值 DEFAULT(大小写不敏感)可以将参数重置为 PostgreSQL 默认值:
- name : dbuser_app
parameters :
work_mem : DEFAULT # 重置为默认值
statement_timeout : '30s' # 设置新值
ALTER USER "dbuser_app" SET "work_mem" = DEFAULT ;
ALTER USER "dbuser_app" SET "statement_timeout" = '30s' ;
常用角色级参数:
参数 说明 示例值 work_mem查询工作内存 '64MB'statement_timeout语句超时时间 '30s'lock_timeout锁等待超时 '10s'idle_in_transaction_session_timeout空闲事务超时 '10min'search_pathSchema 搜索路径 'app,public'log_statement日志记录级别 'ddl'temp_file_limit临时文件大小限制 '10GB'
您可以从数据库的 pg_db_role_setting 系统视图查询用户级别的参数设置。
pgbouncer布尔值,可变参数,用于控制是否将用户添加到 Pgbouncer 连接池用户列表,默认值为 false。
对于需要通过连接池访问数据库的生产用户,必须显式设置 pgbouncer: true。
默认为 false 是为了避免意外将内部用户暴露给连接池。
# 生产用户:需要连接池
- name : dbuser_app
password : DBUser.App
pgbouncer : true
# 内部用户:不需要连接池
- name : dbuser_internal
password : DBUser.Internal
pgbouncer : false # 默认值,可省略
设置 pgbouncer: true 的用户会被添加到 /etc/pgbouncer/userlist.txt 文件中。
pool_mode枚举值,可变参数,用于设置用户级别的池化模式,可选值为 transaction、session 或 statement,默认值为 transaction。
模式 说明 适用场景 transaction事务结束后归还连接 大多数 OLTP 应用,默认推荐 session会话结束后归还连接 需要会话状态的应用(如 SET 命令) statement每条语句后归还连接 简单无状态查询,极致复用
# DBA 用户使用 session 模式(可能需要 SET 命令等会话状态)
- name : dbuser_dba
pgbouncer : true
pool_mode : session
# 普通业务用户使用 transaction 模式
- name : dbuser_app
pgbouncer : true
pool_mode : transaction
用户级别的连接池参数通过 /etc/pgbouncer/useropts.txt 文件配置:
dbuser_dba = pool_mode=session max_user_connections=16
dbuser_monitor = pool_mode=session max_user_connections=8
pool_connlimit整数,可变参数,用于设置用户级别的连接池最大连接数,默认值为 -1,表示不限制。
- name : dbuser_app
pgbouncer : true
pool_connlimit : 50 # 此用户最多使用 50 个连接池连接
ACL 系统 Pigsty 提供了一套内置的、开箱即用的访问控制 / ACL 系统,您只需将以下四个默认角色分配给业务用户即可轻松使用:
角色 权限说明 典型使用场景 dbrole_readwrite全局读写访问 主属业务的生产账号 dbrole_readonly全局只读访问 其他业务的只读访问 dbrole_admin拥有 DDL 权限 业务管理员,需要建表的场景 dbrole_offline受限只读访问(仅离线实例) 个人用户,ETL/分析任务
# 典型业务用户配置
pg_users :
- name : dbuser_app
password : DBUser.App
pgbouncer : true
roles : [ dbrole_readwrite] # 生产账号,读写权限
- name : dbuser_readonly
password : DBUser.Readonly
pgbouncer : true
roles : [ dbrole_readonly] # 只读账号
- name : dbuser_admin
password : DBUser.Admin
pgbouncer : true
roles : [ dbrole_admin] # 管理员,可执行 DDL
- name : dbuser_etl
password : DBUser.ETL
roles : [ dbrole_offline] # 离线分析账号
如果您希望重新设计您自己的 ACL 系统,可以考虑定制以下参数和模板:
Pgbouncer 用户 默认情况下启用 Pgbouncer 作为连接池中间件。Pigsty 默认将 pg_users 中显式带有 pgbouncer: true 标志的所有用户添加到 Pgbouncer 用户列表中。
Pgbouncer 连接池中的用户在 /etc/pgbouncer/userlist.txt 中列出:
"postgres" ""
"dbuser_wiki" "SCRAM-SHA-256$4096:+77dyhrPeFDT/TptHs7/7Q = =$KeatuohpKIYzHPCt/tqBu85vI11o9mar/by0hHYM2W8=:X9gig4JtjoS8Y/o1vQsIX/gY1Fns8ynTXkbWOjUfbRQ="
"dbuser_view" "SCRAM-SHA-256$4096:DFoZHU/DXsHL8MJ8regdEw = =$gx9sUGgpVpdSM4o6A2R9PKAUkAsRPLhLoBDLBUYtKS0=:MujSgKe6rxcIUMv4GnyXJmV0YNbf39uFRZv724+X1FE="
"dbuser_monitor" "SCRAM-SHA-256$4096:fwU97ZMO/KR0ScHO5+UuBg = =$CrNsmGrx1DkIGrtrD1Wjexb/aygzqQdirTO1oBZROPY=:L8+dJ+fqlMQh7y4PmVR/gbAOvYWOr+KINjeMZ8LlFww="
"dbuser_meta" "SCRAM-SHA-256$4096:leB2RQPcw1OIiRnPnOMUEg = =$eyC+NIMKeoTxshJu314+BmbMFpCcspzI3UFZ1RYfNyU=:fJgXcykVPvOfro2MWNkl5q38oz21nSl1dTtM65uYR1Q="
用户级别的连接池参数使用另一个单独的文件 /etc/pgbouncer/useropts.txt 进行维护:
dbuser_dba = pool_mode=session max_user_connections=16
dbuser_monitor = pool_mode=session max_user_connections=8
当您 创建用户 时,Pgbouncer 的用户列表定义文件将会被刷新,并通过在线重载配置的方式生效,不会影响现有的连接。
Pgbouncer 使用和 PostgreSQL 相同的 dbsu 运行,默认为 postgres 操作系统用户。您可以使用 pgb 别名,使用 dbsu 访问 Pgbouncer 管理功能。
pgbouncer_auth_query 参数允许您使用动态查询来完成连接池用户认证,当您不想手动管理连接池中的用户时,这是一种便捷的方案。
相关资源 关于用户管理操作,请参考 用户管理 一节。
关于用户的访问权限,请参考 ACL:角色权限 一节。
12.2.5 - 数据库 如何通过配置来定制所需 PostgreSQL 数据库?
在本文中,“数据库”(Database) 指的是使用 SQL 命令 CREATE DATABASE 创建的,数据库集簇内的逻辑对象。
一组 PostgreSQL 服务器可以同时服务于多个 数据库 (Database)。在 Pigsty 中,你可以在集群配置中 定义 好所需的数据库。
Pigsty 会对默认模板数据库template1进行修改与定制,创建默认模式,安装默认扩展,配置默认权限,新创建的数据库默认会从template1继承这些设置。
您也可以通过 template 参数指定其他模板数据库,实现瞬间 数据库克隆 。
默认情况下,所有业务数据库都会被 1:1 添加到 Pgbouncer 连接池 中;pg_exporter 默认会通过 自动发现 机制查找所有业务数据库并进行库内对象监控。
所有数据库也会添加到所有 INFRA节点 上的 Grafana 中,
注册为 PostgreSQL 数据源供 PGCAT 监控面板使用。
定义数据库 业务数据库定义在数据库集群参数 pg_databases 中,这是一个数据库定义构成的对象数组。
在集群初始化时,数组内的数据库按照 定义顺序 依次创建,因此后面定义的数据库可以使用先前定义的数据库作为模板 。
下面是 Pigsty 演示环境中默认集群 pg-meta 中的数据库定义:
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta
pg_databases :
- { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions : [ {name: postgis, schema : public}, {name: timescaledb}]}
- { name: grafana ,owner: dbuser_grafana ,revokeconn: true ,comment : grafana primary database }
- { name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment : bytebase primary database }
- { name: kong ,owner: dbuser_kong ,revokeconn: true ,comment : kong the api gateway database }
- { name: gitea ,owner: dbuser_gitea ,revokeconn: true ,comment : gitea meta database }
- { name: wiki ,owner: dbuser_wiki ,revokeconn: true ,comment : wiki meta database }
- { name: noco ,owner: dbuser_noco ,revokeconn: true ,comment : nocodb database }
每个数据库定义都是一个复杂对象,可能包括以下字段,除了 name 字段外,其他字段均为可选字段:
- name : meta # 必选,`name` 是数据库定义的唯一必选字段
state : create # 可选,数据库状态:create(创建,默认)、absent(删除)、recreate(重建)
baseline : cmdb.sql # 可选,数据库 sql 的基线定义文件路径(ansible 搜索路径中的相对路径,如 files/)
pgbouncer : true # 可选,是否将此数据库添加到 pgbouncer 数据库列表?默认为 true
schemas : [ pigsty] # 可选,要创建的附加模式,由模式名称字符串组成的数组
extensions : # 可选,要安装的附加扩展: 扩展对象的数组
- { name: postgis , schema : public } # 可以指定将扩展安装到某个模式中,也可以不指定(不指定则安装到 search_path 首位模式中)
- { name : timescaledb } # 例如有的扩展会创建并使用固定的模式,就不需要指定模式。
comment : pigsty meta database # 可选,数据库的说明与备注信息
owner : postgres # 可选,数据库所有者,不指定则为当前用户
template : template1 # 可选,要使用的模板,默认为 template1,目标必须是一个模板数据库
strategy : FILE_COPY # 可选,克隆策略:FILE_COPY 或 WAL_LOG(PG15+),不指定使用 PG 默认
encoding : UTF8 # 可选,不指定则继承模板/集群配置(UTF8)
locale : C # 可选,不指定则继承模板/集群配置(C)
lc_collate : C # 可选,不指定则继承模板/集群配置(C)
lc_ctype : C # 可选,不指定则继承模板/集群配置(C)
locale_provider : libc # 可选,本地化提供者:libc、icu、builtin(PG15+)
icu_locale : en-US # 可选,ICU 本地化规则(PG15+)
icu_rules : '' # 可选,ICU 排序规则(PG16+)
builtin_locale : C.UTF-8 # 可选,内置本地化提供者规则(PG17+)
tablespace : pg_default # 可选,默认表空间,默认为 'pg_default'
is_template : false # 可选,是否标记为模板数据库,允许任何有 CREATEDB 权限的用户克隆
allowconn : true # 可选,是否允许连接,默认为 true。显式设置 false 将完全禁止连接到此数据库
revokeconn : false # 可选,撤销公共连接权限。默认为 false,设置为 true 时,属主和管理员之外用户的 CONNECT 权限会被回收
register_datasource : true # 可选,是否将此数据库注册到 grafana 数据源?默认为 true,显式设置为 false 会跳过注册
connlimit : -1 # 可选,数据库连接限制,默认为 -1 ,不限制,设置为正整数则会限制连接数。
parameters : # 可选,数据库级参数,通过 ALTER DATABASE SET 设置
work_mem : '64MB'
statement_timeout : '30s'
pool_auth_user : dbuser_meta # 可选,连接到此 pgbouncer 数据库的所有连接都将使用此用户进行验证(启用 pgbouncer_auth_query 才有用)
pool_mode : transaction # 可选,数据库级别的 pgbouncer 池化模式,默认为 transaction
pool_size : 64 # 可选,数据库级别的 pgbouncer 默认池子大小,默认为 64
pool_reserve : 32 # 可选,数据库级别的 pgbouncer 池子保留空间,默认为 32,当默认池子不够用时,最多再申请这么多条突发连接。
pool_size_min : 0 # 可选,数据库级别的 pgbouncer 池的最小大小,默认为 0
pool_connlimit : 100 # 可选,数据库级别的最大数据库连接数,默认为 100
自 Pigsty v4.1.0 起,数据库连接池参数统一使用 pool_reserve 与 pool_connlimit,旧别名 pool_size_reserve / pool_max_db_conn 已收敛。
参数总览 所有参数中唯一 必选 的字段是 name,它应该是当前 PostgreSQL 集群中有效且唯一的数据库名称,其他参数都有合理的默认值,均为可选项。
带有 “不可变 ” 标记的参数仅在数据库创建时生效,创建后无法修改,若需更改则必须删除并重建数据库。
参数详情 name字符串,必选参数,表示数据库的名称,在一个数据库集群内必须唯一。
数据库名称必须是有效的 PostgreSQL 标识符,长度不超过 63 个字符,不得使用 SQL 关键字,
形式上以字母或下划线开头,后续字符可以是字母、数字或下划线,不能包含空格或特殊字符。
形式应当满足正则表达式:^[A-Za-z_][A-Za-z0-9_$]{0,62}$
- name : myapp # 简单命名
- name : my_application # 下划线分隔
- name : app_v2 # 包含版本号
state枚举值,用于指定要对数据库执行的操作,可以是 create、absent 或 recreate,默认值为 create。
状态 说明 create默认,创建或修改数据库,如果已经存在,则将可变参数调整到描述的状态 absent删除数据库,使用 DROP DATABASE WITH (FORCE) recreate先删除再创建,用于重置数据库
- name : myapp # state 默认为 create
- name : olddb
state : absent # 删除数据库
- name : testdb
state : recreate # 重建数据库
owner字符串,指定数据库的属主用户,默认不指定,不指定则为数据库 pg_dbsu ,即 postgres 用户。
要指定数据库的 owner,被指定的用户必须已存在。修改 owner 会执行:旧 Owner 在数据库上的权限不会被撤回。
数据库属主具有对数据库的完全控制权限,包括创建模式、表、扩展等对象的权限,对于多租户场景尤为有用。
ALTER DATABASE "myapp" OWNER TO "new_owner" ;
GRANT ALL PRIVILEGES ON DATABASE "myapp" TO "new_owner" ;
字符串,用于设置数据库的备注信息,如果不指定,默认值为 business database {name}。
数据库备注信息通过 COMMENT ON DATABASE 语句设置,支持中文和特殊字符(Pigsty 会自动转义单引号)。
备注信息会存储在系统目录 pg_database.datacl 中,可以通过 \l+ 命令查看。
COMMENT ON DATABASE "myapp" IS '我的应用主数据库' ;
- name : myapp
comment : 我的应用主数据库
template字符串,不可变参数 ,用于指定创建数据库时使用的模板数据库,默认值为 template1。
PostgreSQL 的 CREATE DATABASE 本质上是对模板数据库进行复制,新数据库会继承模板中的所有对象、扩展、模式、权限设置等。
Pigsty 会在集群初始化阶段对 template1 进行定制配置,因此新建数据库默认会继承这些设置。
模板 说明 template1默认模板,包含 Pigsty 预配置的扩展、模式和权限设置 template0干净模板,使用不同于集群默认的本地化提供者时,必须使用此模板 自定义数据库 可以使用已有数据库作为模板进行克隆
使用 icu 或 builtin 本地化提供者时,必须指定 template: template0,因为 template1 已有本地化设置无法覆盖。
使用其他
- name : myapp_icu
template : template0 # 使用 ICU 时必须指定 template0
locale_provider : icu
icu_locale : zh-Hans
使用 template0 时,监控所需的扩展与 Schema,以及角色的默认权限都不再自动创建,这允许你从一个完全干净的模板开始定制数据库。
strategy枚举值,不可变参数,用于指定从模板克隆数据库的策略,可选值为 FILE_COPY 或 WAL_LOG,此参数在 PostgreSQL 15 及以上版本可用。
策略 说明 适用场景 FILE_COPY直接复制数据文件,PG15+ 默认 大模板,通用场景 WAL_LOG通过 WAL 日志记录复制 小模板,不阻塞模板上的连接
WAL_LOG 策略的优势是复制过程中不会阻塞模板数据库上的连接,但对于较大的模板效率不如 FILE_COPY。
在 PostgreSQL 14 及更早版本中,此参数会被忽略。
- name : cloned_db
template : source_db
strategy : WAL_LOG # 使用 WAL 日志方式克隆
encoding字符串,不可变参数,用于指定数据库的字符编码,如果不指定则继承模板数据库的编码设置,通常为 UTF8。
如果没有特殊原因,强烈建议使用 UTF8 编码。字符编码在数据库创建后无法修改,如需更改必须重建数据库。
- name : legacy_db
template : template0 # 指定非默认编码时使用 template0
encoding : LATIN1
locale字符串,不可变参数,用于指定数据库的本地化规则,相当于同时设置 lc_collate 和 lc_ctype,如果不指定则继承模板数据库的设置,通常为 C。
本地化规则决定了字符串的排序顺序和字符分类行为。使用 C 或 POSIX 可获得最佳性能和跨平台一致性,
使用特定语言的本地化规则(如 zh_CN.UTF-8)可以获得符合该语言习惯的排序结果。
- name : chinese_db
template : template0
locale : zh_CN.UTF-8 # 中文本地化
encoding : UTF8
lc_collate字符串,不可变参数,用于指定字符串的排序规则,如果不指定则继承模板数据库的设置,通常为 C。
排序规则决定了 ORDER BY 和比较操作的结果。常用值包括:C(字节序,最快)、C.UTF-8、en_US.UTF-8、zh_CN.UTF-8。
此参数在数据库创建后无法修改。
- name : myapp
template : template0
lc_collate : en_US.UTF-8 # 英文排序规则
lc_ctype : en_US.UTF-8
lc_ctype字符串,不可变参数,用于指定字符分类规则,决定字符的大小写、数字、字母等分类,如果不指定则继承模板数据库的设置,通常为 C。
字符分类规则影响 upper()、lower()、正则表达式中的 \w 等函数的行为。此参数在数据库创建后无法修改。
locale_provider枚举值,不可变参数,用于指定本地化的实现提供者,可选值为 libc、icu 或 builtin,此参数在 PostgreSQL 15 及以上版本可用,默认值为 libc。
提供者 版本 说明 libc- 使用操作系统 C 库,传统默认方式,行为因系统而异 icuPG15+ 使用 ICU 库,跨平台一致,支持更多语言 builtinPG17+ PostgreSQL 内置实现,最高效,仅支持 C/C.UTF-8
使用 icu 或 builtin 提供者时,必须指定 template: template0,并配合相应的 icu_locale 或 builtin_locale 参数。
- name : fast_db
template : template0
locale_provider : builtin # 使用内置提供者,最高效
builtin_locale : C.UTF-8
icu_locale字符串,不可变参数,用于指定 ICU 本地化规则标识符,此参数在 PostgreSQL 15 及以上版本、且 locale_provider 为 icu 时可用。
ICU 本地化标识符遵循 BCP 47 标准,常用值包括:
值 说明 en-US美式英语 en-GB英式英语 zh-Hans简体中文 zh-Hant繁体中文 ja-JP日语 ko-KR韩语
- name : chinese_app
template : template0
locale_provider : icu
icu_locale : zh-Hans # 简体中文 ICU 排序
encoding : UTF8
icu_rules字符串,不可变参数,用于自定义 ICU 排序规则,此参数在 PostgreSQL 16 及以上版本可用。
ICU 规则允许对默认排序行为进行微调,使用 ICU 排序规则语法 。
- name : custom_sort_db
template : template0
locale_provider : icu
icu_locale : en-US
icu_rules : '&V << w <<< W' # 自定义 V/W 排序顺序
builtin_locale字符串,不可变参数,用于指定内置本地化提供者的规则,此参数在 PostgreSQL 17 及以上版本、且 locale_provider 为 builtin 时可用,可选值为 C 或 C.UTF-8。
builtin 提供者是 PostgreSQL 17 新增的内置本地化实现,比 libc 更快,且行为跨平台完全一致。
适合只需要 C 或 C.UTF-8 排序规则的场景。
- name : fast_db
template : template0
locale_provider : builtin
builtin_locale : C.UTF-8 # 内置 UTF-8 支持
encoding : UTF8
tablespace字符串,可变参数,用于指定数据库的默认表空间,默认值为 pg_default。
修改现有数据库的表空间会触发数据物理迁移,PostgreSQL 会将数据库中的所有对象移动到新表空间,对于大数据库可能需要较长时间,慎用。
- name : archive_db
tablespace : slow_hdd # 归档数据使用慢速存储
ALTER DATABASE "archive_db" SET TABLESPACE "slow_hdd" ;
is_template布尔值,可变参数,用于指定是否将数据库标记为模板数据库,默认值为 false。
设置为 true 后,任何拥有 CREATEDB 权限的用户都可以使用此数据库作为模板克隆新数据库。
模板数据库通常用于预装标准模式、扩展和数据,方便快速创建具有相同配置的新数据库。
- name : app_template
is_template : true # 标记为模板,允许普通用户克隆
schemas : [ core, api]
extensions : [ postgis, pg_trgm]
删除标记为 is_template: true 的数据库时,Pigsty 会先执行 ALTER DATABASE ... IS_TEMPLATE false 取消模板标记,然后再删除。
allowconn布尔值,可变参数,用于控制是否允许连接到此数据库,默认值为 true。
设置为 false 会在数据库层面完全禁止连接,任何用户(包括超级用户)都无法连接到此数据库。
此参数通常用于维护或归档用途。
- name : archive_db
allowconn : false # 禁止任何连接
ALTER DATABASE "archive_db" ALLOW_CONNECTIONS false ;
revokeconn布尔值,可变参数,用于控制是否回收 PUBLIC 角色的 CONNECT 权限,默认值为 false。
设置为 true 时,Pigsty 会执行以下权限变更:
回收 PUBLIC 的 CONNECT 权限,普通用户将无法连接 授予复制用户(replicator)和监控用户(dbuser_monitor)连接权限 授予管理员用户(dbuser_dba)和数据库属主连接权限,并附带 WITH GRANT OPTION 设置为 false 时,会恢复 PUBLIC 的 CONNECT 权限。
- name : secure_db
owner : dbuser_secure
revokeconn : true # 回收公共连接权限,只有指定用户可连接
connlimit整数,可变参数,用于限制数据库的最大并发连接数,默认值为 -1,表示不限制。
设置为正整数时,会限制同时连接到此数据库的最大会话数。此限制不影响超级用户。
- name : limited_db
connlimit : 50 # 最多允许 50 个并发连接
ALTER DATABASE "limited_db" CONNECTION LIMIT 50 ;
baseline字符串,一次性参数,用于指定数据库创建后要执行的 SQL 基线文件路径。
基线文件通常包含表结构定义、初始数据、存储过程等,用于初始化新数据库。
路径是相对于 Ansible 搜索路径的相对路径,通常放在 files/ 目录下。
基线文件仅在首次创建数据库时执行;如果数据库已存在则跳过。使用 state: recreate 重建数据库时会重新执行基线文件。
- name : myapp
baseline : myapp_schema.sql # 会查找 files/myapp_schema.sql
schemas数组,可变参数(支持增删),用于定义要在数据库中创建或删除的模式。数组元素可以是字符串或对象。
简单格式使用字符串直接指定模式名,仅支持创建操作:
schemas :
- app
- api
- core
完整格式使用对象定义,支持指定模式属主和删除操作:
schemas :
- name : app # 模式名(必选)
owner : dbuser_app # 模式属主(可选),生成 AUTHORIZATION 子句
- name : deprecated
state : absent # 删除模式(使用 CASCADE)
创建模式时使用 IF NOT EXISTS,已存在则跳过;删除模式时使用 CASCADE,会同时删除模式内的所有对象。
CREATE SCHEMA IF NOT EXISTS "app" AUTHORIZATION "dbuser_app" ;
DROP SCHEMA IF EXISTS "deprecated" CASCADE ;
extensions数组,可变参数(支持增删),用于定义要在数据库中安装或卸载的扩展。数组元素可以是字符串或对象。
简单格式使用字符串直接指定扩展名,仅支持安装操作:
extensions :
- postgis
- pg_trgm
- vector
完整格式使用对象定义,支持指定安装模式、版本和卸载操作:
extensions :
- name : vector # 扩展名(必选)
schema : public # 安装到指定模式(可选)
version : '0.5.1' # 指定版本(可选)
- name : old_extension
state : absent # 卸载扩展(使用 CASCADE)
安装扩展时使用 CASCADE,如果已存在则会报错但跳过,同时自动安装依赖扩展;卸载扩展时使用 CASCADE,会同时删除依赖此扩展的对象。
CREATE EXTENSION IF NOT EXISTS "vector" WITH SCHEMA "public" VERSION '0.5.1' CASCADE ;
DROP EXTENSION IF EXISTS "old_extension" CASCADE ;
parameters对象,可变参数,用于设置数据库级别的配置参数。参数通过 ALTER DATABASE ... SET 设置,会对连接到此数据库的所有会话生效。
- name : analytics
parameters :
work_mem : '256MB'
maintenance_work_mem : '512MB'
statement_timeout : '5min'
search_path : 'analytics,public'
使用特殊值 DEFAULT(大小写不敏感)可以将参数重置为 PostgreSQL 默认值:
parameters :
work_mem : DEFAULT # 重置为默认值
statement_timeout : '30s' # 设置新值
ALTER DATABASE "myapp" SET "work_mem" = DEFAULT ;
ALTER DATABASE "myapp" SET "statement_timeout" = '30s' ;
pgbouncer布尔值,可变参数,用于控制是否将数据库添加到 Pgbouncer 连接池列表,默认值为 true。
设置为 false 时,数据库不会出现在 Pgbouncer 的数据库列表中,客户端无法通过连接池访问此数据库。
适用于内部管理数据库或需要直连的特殊场景。
- name : internal_db
pgbouncer : false # 不通过连接池访问
pool_mode枚举值,可变参数,用于设置此数据库在 Pgbouncer 中的池化模式,可选值为 transaction、session 或 statement,默认值为 transaction。
模式 说明 适用场景 transaction事务结束后归还连接 大多数 OLTP 应用,默认推荐 session会话结束后归还连接 需要会话级状态的应用 statement每条语句后归还连接 简单无状态查询,极致复用
- name : session_app
pool_mode : session # 使用会话级池化
pool_size整数,可变参数,用于设置此数据库在 Pgbouncer 中的默认连接池大小,默认值为 64。
连接池大小决定了 Pgbouncer 为此数据库预留的后端连接数量。根据应用负载调整此值。
- name : high_load_db
pool_size : 128 # 高负载应用使用更大的池
pool_size_min整数,可变参数,用于设置此数据库在 Pgbouncer 中的最小连接池大小,默认值为 0。
设置大于 0 的值会让 Pgbouncer 预先创建指定数量的后端连接,用于连接预热,减少首次请求的延迟。
- name : latency_sensitive
pool_size_min : 10 # 预热 10 个连接
pool_reserve整数,可变参数,用于设置此数据库在 Pgbouncer 中的保留连接数,默认值为 32。
当默认池不够用时,Pgbouncer 最多可以额外申请 pool_reserve 个连接来处理突发流量。
- name : bursty_db
pool_size : 64
pool_reserve : 64 # 允许突发到 128 个连接
pool_connlimit整数,可变参数,用于设置通过 Pgbouncer 连接池访问此数据库的最大连接数,默认值为 100。
此限制是 Pgbouncer 层面的限制,与数据库本身的 connlimit 参数独立。
- name : limited_pool_db
pool_connlimit : 50 # 连接池最多 50 个连接
pool_auth_user字符串,可变参数,用于指定 Pgbouncer 认证查询使用的用户。
此参数需要配合 pgbouncer_auth_query 参数启用才生效。
设置后,所有通过 Pgbouncer 连接到此数据库的请求都会使用指定用户执行认证查询来验证密码。
- name : myapp
pool_auth_user : dbuser_monitor # 使用监控用户执行认证查询
register_datasource布尔值,可变参数,用于控制是否将此数据库注册到 Grafana 作为 PostgreSQL 数据源,默认值为 true。
设置为 false 可以跳过 Grafana 数据源注册。适用于临时数据库、测试数据库,或不希望在监控系统中出现的内部数据库。
- name : temp_db
register_datasource : false # 不注册到 Grafana
模板继承 许多参数如果不显式指定,会从模板数据库继承。默认模板是 template1,其编码设置由集群初始化参数决定:
新创建的数据库默认会从 template1 数据库 Fork 出来,这个模版数据库会在 PG_PROVISION 阶段进行定制修改:
配置好扩展、模式以及默认权限,因此新创建的数据库也会继承这些配置,除非您显式使用一个其他的数据库作为模板。
深度定制 Pigsty 提供了丰富的定制参数与配置旋钮,如果你想定制模板数据库,请参考以下资源:
如果上面这些配置仍然无法满足您的需求,您可以使用 pg_init 指定自定义的集群初始化脚本进行定制:
本地化提供者 PostgreSQL 15+ 引入了 locale_provider 参数,支持不同的本地化实现。这些属性只能在数据库创建时指定,之后无法修改。
Pigsty 在 configure 配置向导中会根据 PG 与操作系统版本,优先使用 PG 内置的 C.UTF-8/C 本地化提供者。
数据库在默认情况下继承集群的本地化设置。如果您要为数据库指定一个不同于集群默认的本地化提供者,则必须使用 template0 作为模板数据库。
使用 ICU 提供者(PG15+) :
- name : myapp_icu
template : template0 # ICU 必须使用 template0
locale_provider : icu
icu_locale : en-US # ICU 本地化规则
encoding : UTF8
使用内置提供者(PG17+) :
- name : myapp_builtin
template : template0
locale_provider : builtin
builtin_locale : C.UTF-8 # 内置本地化规则
encoding : UTF8
提供者对比 :libc(传统方式,依赖操作系统)、icu(PG15+,跨平台一致,功能丰富)、builtin(PG17+,最高效的 C/C.UTF-8 排序)。
连接池 Pgbouncer 连接池可以优化短连接性能,降低并发征用,以避免过高的连接数冲垮数据库,并在数据库迁移时提供额外的灵活处理空间。
Pigsty 会默认为 PostgreSQL 实例 1:1 配置启用一个连接池,
使用和 PostgreSQL 同样的 pg_dbsu 运行,默认为 postgres 操作系统用户。
连接池与数据库使用 /var/run/postgresql Unix Socket 通信。
Pigsty 默认将 pg_databases 中的所有数据库都添加到 pgbouncer 的数据库列表中。
您可以通过在数据库定义中显式设置 pgbouncer: false 来禁用特定数据库的 pgbouncer 连接池支持。
pgbouncer 数据库列表与其配置参数在 /etc/pgbouncer/database.txt 中定义。
meta = host=/var/run/postgresql mode=session
grafana = host=/var/run/postgresql mode=transaction
bytebase = host=/var/run/postgresql auth_user=dbuser_meta
kong = host=/var/run/postgresql pool_size=32 reserve_pool=64
gitea = host=/var/run/postgresql min_pool_size=10
wiki = host=/var/run/postgresql
noco = host=/var/run/postgresql
mongo = host=/var/run/postgresql
当您 创建数据库 时,Pgbouncer 的数据库列表定义文件将会被刷新,并通过在线重载配置的方式生效,正常不会影响现有的连接。
12.2.6 - HBA 规则 Pigsty 中 PostgreSQL 与 Pgbouncer 的 HBA(Host-Based Authentication)规则配置详解。
概述 HBA(Host-Based Authentication)控制"谁可以从哪里、以什么方式连接到数据库"。
Pigsty 通过 pg_default_hba_rules 与 pg_hba_rules 让 HBA 规则也能以声明式配置形式管理。
Pigsty 在集群初始化或 HBA 刷新时渲染以下配置文件:
配置文件 路径 说明 PostgreSQL HBA /pg/data/pg_hba.confPostgreSQL 服务器的 HBA 规则 Pgbouncer HBA /etc/pgbouncer/pgb_hba.conf连接池 Pgbouncer 的 HBA 规则
HBA 规则由以下参数控制:
规则支持以下特性:
按角色过滤 :规则支持 role 字段,根据实例的 pg_role 自动筛选生效按顺序排序 :规则支持 order 字段,控制规则在最终配置文件中的位置两种写法 :支持别名形式(简化语法)和原始形式(直接 HBA 文本)刷新 HBA 修改配置后,需要重新渲染配置文件并让服务重载:
bin/pgsql-hba <cls> # 刷新整个集群的 HBA 规则(推荐)
bin/pgsql-hba <cls> <ip>... # 刷新集群中指定实例的 HBA 规则
脚本内部执行以下剧本命令:
./pgsql.yml -l <cls> -t pg_hba,pg_reload,pgbouncer_hba,pgbouncer_reload -e pg_reload = true
仅刷新 PostgreSQL :./pgsql.yml -l <cls> -t pg_hba,pg_reload -e pg_reload=true
仅刷新 Pgbouncer :./pgsql.yml -l <cls> -t pgbouncer_hba,pgbouncer_reload
不要直接编辑配置文件
不要直接编辑 /pg/data/pg_hba.conf 或 /etc/pgbouncer/pgb_hba.conf,下次执行 playbook 时会被覆盖。
所有变更应在 pigsty.yml 中进行,然后执行 bin/pgsql-hba 刷新。
参数详解 pg_default_hba_rulesPostgreSQL 全局默认 HBA 规则列表,通常定义在 all.vars 中,为所有 PostgreSQL 集群提供基础访问控制。
pg_default_hba_rules :
- {user : '${dbsu}' ,db: all ,addr: local ,auth: ident ,title: 'dbsu access via local os user ident' ,order : 100 }
- {user : '${dbsu}' ,db: replication ,addr: local ,auth: ident ,title: 'dbsu replication from local os ident' ,order : 150 }
- {user : '${repl}' ,db: replication ,addr: localhost ,auth: pwd ,title: 'replicator replication from localhost',order : 200 }
- {user : '${repl}' ,db: replication ,addr: intra ,auth: pwd ,title: 'replicator replication from intranet' ,order : 250 }
- {user : '${repl}' ,db: postgres ,addr: intra ,auth: pwd ,title: 'replicator postgres db from intranet' ,order : 300 }
- {user : '${monitor}' ,db: all ,addr: localhost ,auth: pwd ,title: 'monitor from localhost with password' ,order : 350 }
- {user : '${monitor}' ,db: all ,addr: infra ,auth: pwd ,title: 'monitor from infra host with password',order : 400 }
- {user : '${admin}' ,db: all ,addr: infra ,auth: ssl ,title: 'admin @ infra nodes with pwd & ssl' ,order : 450 }
- {user : '${admin}' ,db: all ,addr: world ,auth: ssl ,title: 'admin @ everywhere with ssl & pwd' ,order : 500 }
- {user: '+dbrole_readonly',db: all ,addr: localhost ,auth: pwd ,title: 'pgbouncer read/write via local socket',order : 550 }
- {user: '+dbrole_readonly',db: all ,addr: intra ,auth: pwd ,title: 'read/write biz user via password' ,order : 600 }
- {user: '+dbrole_offline' ,db: all ,addr: intra ,auth: pwd ,title: 'allow etl offline tasks from intranet',order : 650 }
pg_hba_rulesPostgreSQL 集群/实例级 HBA 追加规则,可在集群或实例级别覆盖,与默认规则合并后按 order 排序。
类型:rule[],层级:全局/集群/实例 (G/C/I),默认值:[] pg_hba_rules :
- {user: app_user, db: app_db, addr: intra, auth: pwd, title : 'app user access' }
pgb_default_hba_rulesPgbouncer 全局默认 HBA 规则列表,通常定义在 all.vars 中。
pgb_default_hba_rules :
- {user : '${dbsu}' ,db: pgbouncer ,addr: local ,auth: peer ,title: 'dbsu local admin access with os ident',order : 100 }
- {user: 'all' ,db: all ,addr: localhost ,auth: pwd ,title: 'allow all user local access with pwd' ,order : 150 }
- {user : '${monitor}' ,db: pgbouncer ,addr: intra ,auth: pwd ,title: 'monitor access via intranet with pwd' ,order : 200 }
- {user : '${monitor}' ,db: all ,addr: world ,auth: deny ,title: 'reject all other monitor access addr' ,order : 250 }
- {user : '${admin}' ,db: all ,addr: intra ,auth: pwd ,title: 'admin access via intranet with pwd' ,order : 300 }
- {user : '${admin}' ,db: all ,addr: world ,auth: deny ,title: 'reject all other admin access addr' ,order : 350 }
- {user: 'all' ,db: all ,addr: intra ,auth: pwd ,title: 'allow all user intra access with pwd' ,order : 400 }
pgb_hba_rulesPgbouncer 集群/实例级 HBA 追加规则。
类型:rule[],层级:全局/集群/实例 (G/C/I),默认值:[] 注意 :Pgbouncer HBA 不支持 db: replication。
规则字段 每条 HBA 规则是一个 YAML 字典,支持以下字段:
字段 类型 必需 默认值 说明 userstring 否 all用户名,支持 all、变量占位符、+rolename 等 dbstring 否 all数据库名,支持 all、replication、具体库名 addrstring 是* - 地址别名或 CIDR,见 地址别名 authstring 否 pwd认证方式别名,见 认证方式 titlestring 否 - 规则说明/注释,会渲染为配置文件中的注释 rolestring 否 common实例角色过滤,见 角色过滤 orderint 否 1000排序权重,数字小的排前面,见 排序机制 ruleslist 是* - 原始 HBA 文本行列表,与 addr 二选一
addr 和 rules 必须指定其一。使用 rules 时可以直接写原始 HBA 格式。
地址别名 Pigsty 提供地址别名,简化 HBA 规则编写:
别名 展开为 说明 localUnix socket 本地 Unix 套接字连接 localhostUnix socket + 127.0.0.1/32 + ::1/128 本地回环地址 admin${admin_ip}/32管理员 IP 地址 infra所有 infra 组节点 IP 基础设施节点列表 cluster当前集群所有成员 IP 同一集群内的所有实例 intra / intranet10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16内网 CIDR 网段 world / all0.0.0.0/0 + ::/0任意地址(IPv4 + IPv6) <CIDR>直接使用 如 192.168.1.0/24、10.1.1.100/32
内网 CIDR 可通过 node_firewall_intranet 参数自定义:
node_firewall_intranet :
- 10.0.0.0 /8
- 172.16.0.0 /12
- 192.168.0.0 /16
认证方式 Pigsty 提供认证方式别名,简化配置:
别名 实际方式 连接类型 说明 pwdscram-sha-256 或 md5host根据 pg_pwd_enc 自动选择 sslscram-sha-256 或 md5hostssl强制 SSL + 密码 ssl-shascram-sha-256hostssl强制 SSL + SCRAM-SHA-256 ssl-md5md5hostssl强制 SSL + MD5 certcerthostssl客户端证书认证 trusttrusthost无条件信任(危险) deny / rejectrejecthost拒绝连接 identidenthostOS 用户映射(PostgreSQL) peerpeerlocalOS 用户映射(Pgbouncer/本地)
pg_pwd_enc 默认为 scram-sha-256,可设为 md5 以兼容老客户端。
用户变量 HBA 规则支持以下用户占位符,渲染时自动替换为实际用户名:
占位符 默认值 对应参数 ${dbsu}postgrespg_dbsu${repl}replicatorpg_replication_username${monitor}dbuser_monitorpg_monitor_username${admin}dbuser_dbapg_admin_username
角色过滤 HBA 规则的 role 字段控制规则在哪些实例上生效:
角色 说明 common默认值,所有实例都生效 primary仅主库实例生效 replica仅从库实例生效 offline仅离线实例生效(pg_role: offline 或 pg_offline_query: true) standby备库实例 delayed延迟从库实例
角色过滤基于实例的 pg_role 变量进行匹配,不匹配的规则会被注释掉(以 # 开头)。
pg_hba_rules :
# 仅在主库生效:写入用户只能连主库
- {user: writer, db: all, addr: intra, auth: pwd, role: primary, title : 'writer only on primary' }
# 仅在离线实例生效:ETL 任务专用网络
- {user: '+dbrole_offline', db: all, addr: '172.20.0.0/16', auth: ssl, role: offline, title : 'offline dedicated' }
排序机制 PostgreSQL HBA 是 首条匹配生效 ,规则顺序至关重要。Pigsty 通过 order 字段控制规则渲染顺序。
Order 区间约定
区间 用途 0 - 99用户高优先规则(在所有默认规则之前) 100 - 650默认规则区(间隔 50,便于插入) 1000+用户规则默认值(不填 order 时追加到最后)
PostgreSQL 默认规则 Order 分配
Order 规则说明 100 dbsu local ident 150 dbsu replication local 200 replicator localhost 250 replicator intra replication 300 replicator intra postgres 350 monitor localhost 400 monitor infra 450 admin infra ssl 500 admin world ssl 550 dbrole_readonly localhost 600 dbrole_readonly intra 650 dbrole_offline intra
Pgbouncer 默认规则 Order 分配
Order 规则说明 100 dbsu local peer 150 all localhost pwd 200 monitor pgbouncer intra 250 monitor world deny 300 admin intra pwd 350 admin world deny 400 all intra pwd
写法示例 别名形式 :使用 Pigsty 提供的简化语法
pg_hba_rules :
- title : allow grafana view access
role : primary
user : dbuser_view
db : meta
addr : infra
auth : ssl
渲染结果:
# allow grafana view access [primary]
hostssl meta dbuser_view 10.10.10.10/32 scram-sha-256
原始形式 :直接使用 PostgreSQL HBA 语法
pg_hba_rules :
- title : allow intranet password access
role : common
rules :
- host all all 10.0.0.0/8 scram-sha-256
- host all all 172.16.0.0/12 scram-sha-256
- host all all 192.168.0.0/16 scram-sha-256
渲染结果:
# allow intranet password access [common]
host all all 10.0.0.0/8 scram-sha-256
host all all 172.16.0.0/12 scram-sha-256
host all all 192.168.0.0/16 scram-sha-256
常见配置场景 黑名单 IP :使用 order: 0 确保最先匹配
pg_hba_rules :
- {user: all, db: all, addr: '10.1.1.100/32', auth: deny, order: 0, title : 'block bad ip' }
白名单应用服务器 :高优先级允许特定 IP
pg_hba_rules :
- {user: app_user, db: app_db, addr: '192.168.1.10/32', auth: ssl, order: 50, title : 'app server' }
管理员强制证书 :覆盖默认的 SSL 密码认证
pg_hba_rules :
- {user : '${admin}' , db: all, addr: world, auth: cert, order: 10, title : 'admin cert only' }
离线实例专用网络 :仅在 offline 实例生效
pg_hba_rules :
- {user: '+dbrole_offline', db: all, addr: '172.20.0.0/16', auth: ssl-sha, role: offline, title : 'etl network' }
按数据库限制访问 :敏感库仅允许特定网段
pg_hba_rules :
- {user: fin_user, db: finance_db, addr: '10.20.0.0/16', auth: ssl, title : 'finance only' }
- {user: hr_user, db: hr_db, addr: '10.30.0.0/16', auth: ssl, title : 'hr only' }
Pgbouncer 专用规则 :注意不支持 db: replication
pgb_hba_rules :
- {user: '+dbrole_readwrite', db: all, addr: world, auth: ssl, title : 'app via pgbouncer' }
完整集群示例 pg-prod :
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-prod
pg_hba_rules :
# 黑名单:已知恶意 IP(最高优先级)
- {user: all, db: all, addr: '10.1.1.100/32', auth: deny, order: 0, title : 'blacklist' }
# 应用服务器白名单(高优先级)
- {user: app_user, db: app_db, addr: '192.168.1.0/24', auth: ssl, order: 50, title : 'app servers' }
# ETL 任务:仅离线实例
- {user: etl_user, db: all, addr: '172.20.0.0/16', auth: pwd, role: offline, title : 'etl tasks' }
# 集群内监控访问
- {user : '${monitor}' , db: all, addr: cluster, auth: pwd, order: 380, title : 'cluster monitor' }
pgb_hba_rules :
# 应用通过连接池
- {user: '+dbrole_readwrite', db: all, addr: '192.168.1.0/24', auth: ssl, title : 'app via pgbouncer' }
验证与排查 查看当前 HBA 规则
psql -c "TABLE pg_hba_file_rules" # 通过 SQL 查看(推荐)
cat /pg/data/pg_hba.conf # 查看 PostgreSQL HBA 文件
cat /etc/pgbouncer/pgb_hba.conf # 查看 Pgbouncer HBA 文件
grep '^#' /pg/data/pg_hba.conf | head -20 # 查看规则标题(验证 order)
测试连接认证
psql -h <host> -p 5432 -U <user> -d <db> -c "SELECT 1"
常见问题排查
错误信息 可能原因 解决方案 no pg_hba.conf entry for host...没有匹配的 HBA 规则 添加对应规则并刷新 password authentication failed密码错误或加密方式不兼容 检查密码和 pg_pwd_enc 规则不生效 未刷新或 order 被覆盖 执行 bin/pgsql-hba 并检查顺序
注意事项 顺序敏感 :PostgreSQL HBA 首条匹配生效,善用 order 字段角色匹配 :确保 role 字段与目标实例的 pg_role 一致地址格式 :CIDR 必须正确,如 10.0.0.0/8 而非 10.0.0.0/255.0.0.0Pgbouncer 限制 :不支持 db: replicationSSL 前提 :使用 ssl、cert 认证前确保 SSL 已正确配置测试优先 :修改 HBA 前建议先在测试环境验证扩缩容刷新 :使用 addr: cluster 的规则在集群成员变化后需要刷新相关文档 12.2.7 - 参数配置 如何配置集群、实例、用户和数据库级别的 PostgreSQL 参数
PostgreSQL 参数可以在多个层级进行配置,不同层级的参数设置具有不同的作用范围和优先级。
Pigsty 支持在四个层级配置 PostgreSQL 参数,从全局到局部依次为:
层级 作用范围 配置方式 存储位置 集群级 整个集群所有实例 Patroni DCS / 调优模板 etcd + postgresql.conf 实例级 单个 PostgreSQL 实例 pg_parameters / ALTER SYSTEMpostgresql.auto.conf数据库级 特定数据库的所有会话 pg_databases[].parameterspg_db_role_setting用户级 特定用户的所有会话 pg_users[].parameterspg_db_role_setting
参数优先级从低到高:集群级 < 实例级 < 数据库级 < 用户级 < 会话级 (SET 命令)。
高优先级的设置会覆盖低优先级的设置。
关于 PostgreSQL 参数的完整说明,请参阅 PostgreSQL 官方文档:服务器配置 。
集群级参数 集群级参数是整个 PostgreSQL 集群共享的配置,所有实例(主库和从库)都会使用相同的参数值。
在 Pigsty 中,集群级参数通过 Patroni 管理,存储在分布式配置存储(DCS,默认为 etcd)中。
Pigsty 提供了四种预置的 Patroni 参数优化模板 ,针对不同的使用场景进行了优化,通过 pg_conf 参数指定:
调优模板文件位于 Pigsty 安装目录的 roles/pgsql/templates/ 目录下,包含了根据硬件规格自动计算的参数值。
这些模板会在集群初始化时渲染为 Patroni 配置文件 /etc/patroni/patroni.yml。更多详情请参阅 场景模板 。
在集群创建前,您可以通过调整这些 Patroni 配置模板来修改集群的 初始化参数 。
一旦集群初始化完成,后续的参数修改应通过 Patroni 的 配置管理 机制进行。
Patroni DCS 配置 Patroni 将集群配置存储在 DCS(分布式配置存储,默认为 etcd)中,确保集群所有成员使用一致的配置。
配置存储结构 :
/pigsty/ # 命名空间(patroni_namespace)
└── pg-meta/ # 集群名称(pg_cluster)
├── config # 集群配置(所有成员共享)
├── leader # 当前主库信息
├── members/ # 成员注册信息
│ ├── pg-meta-1
│ └── pg-meta-2
└── ...
配置渲染流程 :
初始化阶段 :调优模板(如 oltp.yml)通过 Jinja2 渲染为 /etc/patroni/patroni.yml启动阶段 :Patroni 读取本地配置,将 PostgreSQL 参数写入 DCS运行阶段 :Patroni 定期从 DCS 同步配置到本地 PostgreSQL本地缓存机制 :
每个 Patroni 实例会在本地缓存 DCS 配置,位于 /pg/conf/<instance>.yml:
启动时:从 DCS 加载配置,缓存到本地 运行时:定期同步 DCS 配置到本地缓存 DCS 不可用时:使用本地缓存继续运行(但无法进行主从切换) 配置文件层次 Patroni 会将 DCS 中的配置渲染到本地 PostgreSQL 配置文件,形成以下层次结构:
/pg/data/
├── postgresql.conf # 主配置文件(由 Patroni 动态管理)
├── postgresql.base.conf # 基础配置(通过 include 指令加载)
├── postgresql.auto.conf # 实例级覆盖配置(ALTER SYSTEM 写入)
├── pg_hba.conf # 客户端认证配置
└── pg_ident.conf # 用户映射配置
配置加载顺序 (优先级从低到高):
postgresql.conf:Patroni 动态生成,包含 DCS 中的集群参数postgresql.base.conf:通过 include 指令加载,包含静态基础配置postgresql.auto.conf:PostgreSQL 自动加载,用于实例级参数覆盖由于 postgresql.auto.conf 最后加载 ,其中的参数会覆盖前面文件中的同名参数。
实例级参数 实例级参数仅对单个 PostgreSQL 实例生效,用于覆盖集群级配置或设置实例特定的参数。
实例级参数会写入 postgresql.auto.conf 文件,由于该文件最后加载,可以覆盖集群级的任何参数。
这是一项非常有用的技术:您可以为特定实例设置不同于集群的参数值,例如:
为从库设置 hot_standby_feedback = on 为特定实例调整 work_mem 或 maintenance_work_mem 为延迟从库设置 recovery_min_apply_delay 使用 pg_parameters 在 Pigsty 配置中,使用 pg_parameters 参数定义实例级配置:
pg-meta :
hosts :
10.10.10.10 :
pg_seq : 1
pg_role : primary
pg_parameters : # 实例级参数
log_statement : all # 仅此实例记录所有 SQL
vars :
pg_cluster : pg-meta
pg_parameters : # 集群默认的实例参数
log_timezone : Asia/Shanghai
log_min_duration_statement : 1000
使用 ./pgsql.yml -l <cls> -t pg_param 子任务,可以将参数配置应用生效,这些参数会被渲染到 postgresql.auto.conf 文件中。
参数覆盖层次 pg_parameters 可以在 Ansible 配置的不同层次定义,优先级从低到高:
all :
vars :
pg_parameters : # 全局默认
log_statement : none
children :
pg-meta :
vars :
pg_parameters : # 集群级覆盖
log_statement : ddl
hosts :
10.10.10.10 :
pg_parameters : # 实例级覆盖(最高优先级)
log_statement : all
使用 ALTER SYSTEM 除了通过配置文件,还可以在运行时使用 SQL 命令 ALTER SYSTEM 修改实例级参数:
-- 设置参数
ALTER SYSTEM SET work_mem = '256MB' ;
ALTER SYSTEM SET log_min_duration_statement = 1000 ;
-- 重置为默认值
ALTER SYSTEM RESET work_mem ;
ALTER SYSTEM RESET ALL ; -- 重置所有 ALTER SYSTEM 设置
-- 重新加载配置使其生效
SELECT pg_reload_conf ();
ALTER SYSTEM 会将参数写入 postgresql.auto.conf 文件。
注意 :在 Pigsty 管理的集群中,postgresql.auto.conf 由 Ansible 通过 pg_parameters 管理。
手动使用 ALTER SYSTEM 修改的参数可能会在下次执行 playbook 时被覆盖。
建议通过修改 pigsty.yml 中的 pg_parameters 来管理实例级参数。
列表类型参数 PostgreSQL 中有一类特殊的参数接受逗号分隔的列表值。在 YAML 配置文件中配置这类参数时,
整个值必须用引号包裹 ,否则 YAML 解析器会将其解释为数组而导致错误:
# ✓ 正确:用引号包裹整个值
pg_parameters :
shared_preload_libraries : 'timescaledb, pg_stat_statements'
search_path : '"$user", public, app'
# ✗ 错误:不加引号会导致 YAML 解析错误
pg_parameters :
shared_preload_libraries : timescaledb, pg_stat_statements # YAML 会解析为数组!
Pigsty 会自动识别以下列表类型参数,在渲染到配置文件时不添加外层引号 :
参数 说明 示例值 shared_preload_libraries预加载共享库 'timescaledb, pg_stat_statements'search_pathSchema 搜索路径 '"$user", public, app'local_preload_libraries本地预加载库 'auto_explain'session_preload_libraries会话预加载库 'pg_hint_plan'log_destination日志输出目标 'csvlog, stderr'unix_socket_directoriesUnix Socket 目录 '/var/run/postgresql, /tmp'temp_tablespaces临时表空间 'ssd_space, hdd_space'debug_io_direct直接 I/O 模式(PG16+) 'data, wal'
渲染示例 :
# pigsty.yml 配置(YAML 中需要引号)
pg_parameters :
shared_preload_libraries : 'timescaledb, pg_stat_statements'
search_path : '"$user", public, app'
work_mem : 64MB
# 渲染后的 postgresql.auto.conf(列表参数无外层引号)
shared_preload_libraries = timescaledb, pg_stat_statements
search_path = "$user", public, app
work_mem = '64MB'
数据库级参数 数据库级参数针对特定数据库生效,连接到该数据库的所有会话都会应用这些参数设置。
通过 ALTER DATABASE ... SET 实现,存储在系统表 pg_db_role_setting 中。
配置方式 在 pg_databases 中使用 parameters 字段定义:
pg_databases :
- name : analytics
owner : dbuser_analyst
parameters :
work_mem : 256MB # 分析库需要更多内存
maintenance_work_mem : 1GB # 大表维护操作
statement_timeout : 10min # 允许长查询
search_path : '"$user", public, mart' # 列表参数需要引号
与实例级参数相同,列表类型参数值在 YAML 中需要用引号包裹。
参数渲染规则 数据库级参数通过 ALTER DATABASE ... SET 语句设置。Pigsty 会根据参数类型自动选择正确的语法:
列表类型参数 (search_path、temp_tablespaces、local_preload_libraries、session_preload_libraries、log_destination)不加外层引号:
ALTER DATABASE "analytics" SET "search_path" = "$user" , public , mart ;
标量参数 使用引号包裹值:
ALTER DATABASE "analytics" SET "work_mem" = '256MB' ;
ALTER DATABASE "analytics" SET "statement_timeout" = '10min' ;
注意 :虽然 log_destination 在数据库级参数白名单中,但由于其 context 为 sighup,
实际上无法在数据库级别生效。此参数应在实例级(pg_parameters)配置。
查看数据库参数 -- 查看特定数据库的参数设置
SELECT datname , unnest ( setconfig ) AS setting
FROM pg_db_role_setting drs
JOIN pg_database d ON d . oid = drs . setdatabase
WHERE drs . setrole = 0 AND datname = 'analytics' ;
手动管理 -- 设置参数
ALTER DATABASE analytics SET work_mem = '256MB' ;
ALTER DATABASE analytics SET search_path = "$user" , public , myschema ;
-- 重置参数
ALTER DATABASE analytics RESET work_mem ;
ALTER DATABASE analytics RESET ALL ;
用户级参数 用户级参数针对特定数据库用户生效,该用户的所有会话都会应用这些参数设置。
通过 ALTER USER ... SET 实现,同样存储在系统表 pg_db_role_setting 中。
配置方式 在 pg_users 或 pg_default_roles 中使用 parameters 字段定义:
pg_users :
- name : dbuser_analyst
password : DBUser.Analyst
parameters :
work_mem : 256MB # 分析查询需要更多内存
statement_timeout : 5min # 允许较长的查询时间
search_path : '"$user", public, analytics' # 列表参数需要引号
log_statement : all # 记录所有 SQL
参数渲染规则 用户级参数的渲染规则与数据库级参数相同:
列表类型参数 (search_path、temp_tablespaces、local_preload_libraries、session_preload_libraries)不加外层引号:
ALTER USER "dbuser_analyst" SET "search_path" = "$user" , public , analytics ;
标量参数 使用引号包裹:
ALTER USER "dbuser_analyst" SET "work_mem" = '256MB' ;
ALTER USER "dbuser_analyst" SET "statement_timeout" = '5min' ;
特殊值 DEFAULT 使用 DEFAULT(大小写不敏感)可以将参数重置为 PostgreSQL 默认值:
parameters :
work_mem : DEFAULT # 重置为默认值
statement_timeout : 30s # 设置具体值
ALTER USER "dbuser_app" SET "work_mem" = DEFAULT ;
ALTER USER "dbuser_app" SET "statement_timeout" = '30s' ;
查看用户参数 -- 查看特定用户的参数设置
SELECT rolname , unnest ( setconfig ) AS setting
FROM pg_db_role_setting drs
JOIN pg_roles r ON r . oid = drs . setrole
WHERE rolname = 'dbuser_analyst' ;
手动管理 -- 设置参数
ALTER USER dbuser_app SET work_mem = '128MB' ;
ALTER USER dbuser_app SET search_path = "$user" , public , myschema ;
-- 重置参数
ALTER USER dbuser_app RESET work_mem ;
ALTER USER dbuser_app RESET ALL ;
参数优先级 当同一参数在多个层级设置时,PostgreSQL 按以下优先级应用(从低到高):
postgresql.conf ← 集群级参数(Patroni DCS)
↓
postgresql.auto.conf ← 实例级参数(pg_parameters / ALTER SYSTEM)
↓
数据库级 ← ALTER DATABASE SET
↓
用户级 ← ALTER USER SET
↓
会话级 ← SET 命令
关于数据库级与用户级的优先级 :
当用户连接到特定数据库时,如果同一参数在数据库级和用户级都有设置,
PostgreSQL 会使用 用户级参数 ,因为用户级优先级更高。
示例场景 :
# 数据库级:analytics 数据库 work_mem = 256MB
pg_databases :
- name : analytics
parameters :
work_mem : 256MB
# 用户级:analyst 用户 work_mem = 512MB
pg_users :
- name : analyst
parameters :
work_mem : 512MB
当 analyst 用户连接到 analytics 数据库时:work_mem = 512MB(用户级优先) 当其他用户连接到 analytics 数据库时:work_mem = 256MB(数据库级生效) 当 analyst 用户连接到其他数据库时:work_mem = 512MB(用户级生效) 12.2.8 - 访问控制 Pigsty 提供的默认角色系统与权限模型
访问控制由“角色体系 + 权限模板 + HBA”共同决定。本节聚焦于如何通过配置参数声明角色与对象权限。
Pigsty 预置了一套精简的 ACL 模型,全部通过以下参数描述:
pg_default_roles:系统角色与系统用户。pg_users:业务用户与角色。pg_default_privileges:管理员/属主新建对象时的默认权限。pg_revoke_public、pg_default_schemas、pg_default_extensions:控制 template1 的默认行为。理解这些参数后,你就可以写出完全可复现的权限配置。
默认角色体系(pg_default_roles) 默认包含 4 个业务角色 + 4 个系统用户:
名称 类型 说明 dbrole_readonlyNOLOGIN所有业务共用,拥有 SELECT/USAGE dbrole_readwriteNOLOGIN继承只读角色,并拥有 INSERT/UPDATE/DELETE dbrole_adminNOLOGIN继承 pg_monitor + 读写角色,可建对象和触发器 dbrole_offlineNOLOGIN受限只读角色,仅允许访问离线实例 postgres用户 系统超级用户,与 pg_dbsu 同名 replicator用户 用于流复制与备份,继承监控与只读权限 dbuser_dba用户 主要管理员账号,同时同步到 pgbouncer dbuser_monitor用户 监控账号,具备 pg_monitor 权限,默认记录慢 SQL
这些定义位于 pg_default_roles,理论上可以自定义,但若要替换名称,必须同步更新 HBA/ACL/脚本中的引用。
示例:为离线任务额外加一个 dbrole_etl:
pg_default_roles :
- { name: dbrole_etl, login: false, roles: [dbrole_offline], comment : 'etl read-only role' }
- { name: dbrole_admin, login: false, roles : [ pg_monitor, dbrole_readwrite, dbrole_etl] }
效果:所有继承 dbrole_admin 的用户自动拥有 dbrole_etl 权限,可访问 offline 实例并执行 ETL。
默认用户与凭据参数 系统用户的用户名/密码由以下参数控制:
参数 默认值 作用 pg_dbsupostgres数据库/系统超级用户 pg_dbsu_password空字符串 dbsu 密码(默认不启用) pg_replication_usernamereplicator复制用户名称 pg_replication_passwordDBUser.Replicator复制用户密码 pg_admin_usernamedbuser_dba管理员用户名 pg_admin_passwordDBUser.DBA管理员密码 pg_monitor_usernamedbuser_monitor监控用户 pg_monitor_passwordDBUser.Monitor监控用户密码
如果修改这些参数,请同步在 pg_default_roles 中更新对应用户的定义,以避免角色属性不一致。
业务角色与授权(pg_users) 业务用户通过 pg_users 声明(详细字段见 用户配置 ),其中 roles 字段控制授予的业务角色。
示例:创建只读/读写用户各一名:
pg_users :
- { name: app_reader, password: DBUser.Reader, roles: [dbrole_readonly], pgbouncer : true }
- { name: app_writer, password: DBUser.Writer, roles: [dbrole_readwrite], pgbouncer : true }
通过继承 dbrole_* 来控制访问权限,无需为每个库单独 GRANT。配合 pg_hba_rules 即可区分访问来源。
若需要更细粒度的 ACL,可在 baseline SQL 中或后续剧本里使用标准 GRANT/REVOKE。Pigsty 不会阻止你额外授予权限。
默认权限模板(pg_default_privileges) pg_default_privileges 会在 postgres、dbuser_dba、dbrole_admin(业务管理员 SET ROLE 后)上设置 DEFAULT PRIVILEGE。默认模板如下:
pg_default_privileges :
- GRANT USAGE ON SCHEMAS TO dbrole_readonly
- GRANT SELECT ON TABLES TO dbrole_readonly
- GRANT SELECT ON SEQUENCES TO dbrole_readonly
- GRANT EXECUTE ON FUNCTIONS TO dbrole_readonly
- GRANT USAGE ON SCHEMAS TO dbrole_offline
- GRANT SELECT ON TABLES TO dbrole_offline
- GRANT SELECT ON SEQUENCES TO dbrole_offline
- GRANT EXECUTE ON FUNCTIONS TO dbrole_offline
- GRANT INSERT ON TABLES TO dbrole_readwrite
- GRANT UPDATE ON TABLES TO dbrole_readwrite
- GRANT DELETE ON TABLES TO dbrole_readwrite
- GRANT USAGE ON SEQUENCES TO dbrole_readwrite
- GRANT UPDATE ON SEQUENCES TO dbrole_readwrite
- GRANT TRUNCATE ON TABLES TO dbrole_admin
- GRANT REFERENCES ON TABLES TO dbrole_admin
- GRANT TRIGGER ON TABLES TO dbrole_admin
- GRANT CREATE ON SCHEMAS TO dbrole_admin
只要对象由上述管理员创建,就会自动携带对应权限,无需人为执行 GRANT。若业务需要自定义模板,直接替换该数组即可。
额外提示:
pg_revoke_public 默认为 true,意味着自动撤销 PUBLIC 在数据库和 public schema 上的 CREATE 权限。pg_default_schemas 和 pg_default_extensions 控制在 template1/postgres 中预创建的 schema/扩展,通常用于监控对象(monitor schema、pg_stat_statements 等)。常见配置场景 为合作方提供只读账号 pg_users :
- name : partner_ro
password : Partner.Read
roles : [ dbrole_readonly]
pg_hba_rules :
- { user: partner_ro, db: analytics, addr: 203.0.113.0/24, auth : ssl }
效果:合作方账号登录后只具备默认只读权限,并且只能通过 TLS 从指定网段访问 analytics 库。
为业务管理员赋予 DDL 能力 pg_users :
- name : app_admin
password : DBUser.AppAdmin
roles : [ dbrole_admin]
业务管理员通过 SET ROLE dbrole_admin 或直接以 app_admin 登录,即可继承默认的 DDL 权限模板。
自定义默认权限 pg_default_privileges :
- GRANT INSERT,UPDATE,DELETE ON TABLES TO dbrole_admin
- GRANT SELECT,UPDATE ON SEQUENCES TO dbrole_admin
- GRANT SELECT ON TABLES TO reporting_group
替换默认模板后,所有由管理员创建的对象都会携带新的权限定义,避免逐对象授权。
与其他组件的协同 HBA 规则 :使用 pg_hba_rules 将角色与来源进行绑定(例如只让 dbrole_offline 访问离线实例)。Pgbouncer :pgbouncer: true 的用户会被写入 userlist.txt,pool_mode/pool_connlimit 可以控制连接池层面的配额。Grafana/监控 :dbuser_monitor 的权限来自 pg_default_roles,如果你新增监控用户,记得赋予 pg_monitor + monitor schema 的访问权。通过这些参数,可以让权限体系与代码一起版本化,真正做到“配置即策略”。
12.3 - 服务/接入 分离读写操作,正确路由流量,稳定可靠地交付 PostgreSQL 集群提供的能力。
分离读写操作,正确路由流量,稳定可靠地交付 PostgreSQL 集群提供的能力。
服务 是一种抽象:它是数据库集群对外提供能力的形式,并封装了底层集群的细节。
服务对于生产环境中的 稳定接入 至关重要,在 高可用 集群自动故障时方显其价值,单机用户 通常不需要操心这个概念。
单机用户 “服务” 的概念是给生产环境用的,个人用户/单机集群可以不折腾,直接拿实例名/IP 地址访问数据库。
例如,Pigsty 默认的单节点 pg-meta.meta 数据库,就可以直接用下面三个不同的用户连接上去。
psql postgres://dbuser_dba:DBUser.DBA@10.10.10.10/meta # 直接用 DBA 超级用户连上去
psql postgres://dbuser_meta:DBUser.Meta@10.10.10.10/meta # 用默认的业务管理员用户连上去
psql postgres://dbuser_view:DBUser.View@pg-meta/meta # 用默认的只读用户走实例域名连上去
服务概述 在真实世界生产环境中,我们会使用基于复制的主从数据库集群。集群中有且仅有一个实例作为领导者(主库 )可以接受写入。
而其他实例(从库 )则会从持续从集群领导者获取变更日志,与领导者保持一致。同时,从库还可以承载只读请求,在读多写少的场景下可以显著分担主库的负担,
因此对集群的写入请求与只读请求进行区分,是一种十分常见的实践。
此外对于高频短连接的生产环境,我们还会通过连接池中间件(Pgbouncer)对请求进行池化,减少连接与后端进程的创建开销。但对于 ETL 与变更执行等场景,我们又需要绕过连接池,直接访问数据库。
同时,高可用集群在故障时会出现故障切换(Failover),故障切换会导致集群的领导者出现变更。因此高可用的数据库方案要求写入流量可以自动适配集群的领导者变化。
这些不同的访问需求(读写分离,池化与直连,故障切换自动适配)最终抽象出 服务 (Service)的概念。
通常来说,数据库集群都必须提供这种最基础的服务:
对于生产数据库集群,至少应当提供这两种服务:
读写服务(primary) :写入数据:只能由主库所承载。只读服务(replica) :读取数据:可以由从库承载,没有从库时也可由主库承载此外,根据具体的业务场景,可能还会有其他的服务,例如:
默认直连服务(default) :允许(管理)用户,绕过连接池直接访问数据库的服务离线从库服务(offline) :不承接线上只读流量的专用从库,用于 ETL 与分析查询同步从库服务(standby) :没有复制延迟的只读服务,由 同步备库 /主库处理只读查询延迟从库服务(delayed) :访问同一个集群在一段时间之前的旧数据,由 延迟从库 来处理默认服务 Pigsty 默认为每个 PostgreSQL 数据库集群提供四种不同的服务,以下是默认服务及其定义:
以默认的 pg-meta 集群为例,它提供四种默认服务:
psql postgres://dbuser_meta:DBUser.Meta@pg-meta:5433/meta # pg-meta-primary : 通过主要的 pgbouncer(6432) 进行生产读写
psql postgres://dbuser_meta:DBUser.Meta@pg-meta:5434/meta # pg-meta-replica : 通过备份的 pgbouncer(6432) 进行生产只读
psql postgres://dbuser_dba:DBUser.DBA@pg-meta:5436/meta # pg-meta-default : 通过主要的 postgres(5432) 直接连接
psql postgres://dbuser_stats:DBUser.Stats@pg-meta:5438/meta # pg-meta-offline : 通过离线的 postgres(5432) 直接连接
从示例集群 架构图 上可以看出这四种服务的工作方式:
注意在这里pg-meta 域名指向了集群的 L2 VIP,进而指向集群主库上的 haproxy 负载均衡器,它负责将流量路由到不同的实例上,详见 服务接入
服务实现 在 Pigsty 中,服务使用 节点 上的 haproxy 来实现,通过主机节点上的不同端口进行区分。
Pigsty 所纳管的每个节点上都默认启用了 Haproxy 以对外暴露服务,而数据库节点也不例外。
集群中的节点尽管从数据库的视角来看有主从之分,但从服务的视角来看,每个节点都是相同的:
这意味着即使您访问的是从库节点,只要使用正确的服务端口,就依然可以使用到主库读写的服务。
这样的设计可以屏蔽复杂度:所以您只要可以访问 PostgreSQL 集群上的任意一个实例,就可以完整的访问到所有服务。
这样的设计类似于 Kubernetes 中的 NodePort 服务,同样在 Pigsty 中,每一个服务都包括以下两个核心要素:
通过 NodePort 暴露的访问端点(端口号,从哪访问?) 通过 Selectors 选择的目标实例(实例列表,谁来承载?) Pigsty 的服务交付边界止步于集群的 HAProxy,用户可以用各种手段访问这些负载均衡器,请参考 接入服务 。
所有的服务都通过配置文件进行声明,例如,PostgreSQL 默认服务就是由 pg_default_services 参数所定义的:
pg_default_services :
- { name: primary ,port: 5433 ,dest: default ,check: /primary ,selector : "[]" }
- { name: replica ,port: 5434 ,dest: default ,check: /read-only ,selector : "[]" , backup : "[? pg_role == `primary` || pg_role == `offline` ]" }
- { name: default ,port: 5436 ,dest: postgres ,check: /primary ,selector : "[]" }
- { name: offline ,port: 5438 ,dest: postgres ,check: /replica ,selector : "[? pg_role == `offline` || pg_offline_query ]" , backup : "[? pg_role == `replica` && !pg_offline_query]" }
您也可以在 pg_services 中定义额外的服务,参数 pg_default_services 与 pg_services 都是由 服务定义 对象组成的数组。
定义服务 Pigsty 允许您定义自己的服务:
对于 PostgreSQL 集群来说,通常只需要关注前两者即可。
每一条服务定义都会在所有相关 HAProxy 实例的配置目录下生成一个新的配置文件:/etc/haproxy/<svcname>.cfg
下面是一个自定义的服务样例 standby:当您想要对外提供没有复制延迟的只读服务时,就可以在 pg_services 新增这条记录:
- name : standby # 必选,服务名称,最终的 svc 名称会使用 `pg_cluster` 作为前缀,例如:pg-meta-standby
port : 5435 # 必选,暴露的服务端口(作为 kubernetes 服务节点端口模式)
ip : "*" # 可选,服务绑定的 IP 地址,默认情况下为所有 IP 地址
selector : "[]" # 必选,服务成员选择器,使用 JMESPath 来筛选配置清单
backup : "[? pg_role == `primary`]" # 可选,服务成员选择器(备份),也就是当默认选择器选中的实例都宕机后,服务才会由这里选中的实例成员来承载
dest : default # 可选,目标端口,default|postgres|pgbouncer|<port_number>,默认为 'default',Default的意思就是使用 pg_default_service_dest 的取值来最终决定
check : /sync # 可选,健康检查 URL 路径,默认为 /,这里使用 Patroni API:/sync ,只有同步备库和主库才会返回 200 健康状态码
maxconn : 5000 # 可选,允许的前端连接最大数,默认为5000
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'
而上面的服务定义,在样例的三节点 pg-test 上将会被转换为 haproxy 配置文件 /etc/haproxy/pg-test-standby.conf:
#---------------------------------------------------------------------
# service: pg-test-standby @ 10.10.10.11:5435
#---------------------------------------------------------------------
# service instances 10.10.10.11, 10.10.10.13, 10.10.10.12
# service backups 10.10.10.11
listen pg-test-standby
bind *:5435 # <--- 绑定了所有IP地址上的 5435 端口
mode tcp # <--- 负载均衡器工作在 TCP 协议上
maxconn 5000 # <--- 最大连接数为 5000,可按需调大
balance roundrobin # <--- 负载均衡算法为 rr 轮询,还可以使用 leastconn
option httpchk # <--- 启用 HTTP 健康检查
option http-keep-alive # <--- 保持HTTP连接
http-check send meth OPTIONS uri /sync # <---- 这里使用 /sync ,Patroni 健康检查 API ,只有同步备库和主库才会返回 200 健康状态码。
http-check expect status 200 # <---- 健康检查返回代码 200 代表正常
default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
# servers: # pg-test 集群全部三个实例都被 selector: "[]" 给圈中了,因为没有任何的筛选条件,所以都会作为 pg-test-replica 服务的后端服务器。但是因为还有 /sync 健康检查,所以只有主库和同步备库才能真正承载请求。
server pg-test-1 10.10.10.11:6432 check port 8008 weight 100 backup # <----- 唯独主库满足条件 pg_role == `primary`, 被 backup selector 选中。
server pg-test-3 10.10.10.13:6432 check port 8008 weight 100 # 因此作为服务的兜底实例:平时不承载请求,其他从库全部宕机后,才会承载只读请求,从而最大避免了读写服务受到只读服务的影响
server pg-test-2 10.10.10.12:6432 check port 8008 weight 100 #
在这里,pg-test 集群全部三个实例都被 selector: "[]" 给圈中了,渲染进入 pg-test-replica 服务的后端服务器列表中。但是因为还有 /sync 健康检查,Patroni Rest API 只有在主库和 同步备库 上才会返回代表健康的 HTTP 200 状态码,因此只有主库和同步备库才能真正承载请求。
此外,主库因为满足条件 pg_role == primary, 被 backup selector 选中,被标记为了备份服务器,只有当没有其他实例(也就是同步备库)可以满足需求时,才会顶上。
Primary服务 Primary 服务可能是生产环境中最关键的服务,它在 5433 端口提供对数据库集群的读写能力,服务定义如下:
- { name: primary ,port: 5433 ,dest: default ,check: /primary ,selector : "[]" }
选择器参数 selector: "[]" 意味着所有集群成员都将被包括在 Primary 服务中 但只有主库能够通过健康检查(check: /primary),实际承载 Primary 服务的流量。 目的地参数 dest: default 意味着 Primary 服务的目的地受到 pg_default_service_dest 参数的影响 dest 默认值 default 会被替换为 pg_default_service_dest 的值,默认为 pgbouncer。默认情况下 Primary 服务的目的地默认是主库上的连接池,也就是由 pgbouncer_port 指定的端口,默认为 6432 如果 pg_default_service_dest 的值为 postgres,那么 primary 服务的目的地就会绕过连接池,直接使用 PostgreSQL 数据库的端口(pg_port ,默认值 5432),对于一些不希望使用连接池的场景,这个参数非常实用。
示例:pg-test-primary 的 haproxy 配置 listen pg-test-primary
bind *:5433 # <--- primary 服务默认使用 5433 端口
mode tcp
maxconn 5000
balance roundrobin
option httpchk
option http-keep-alive
http-check send meth OPTIONS uri /primary # <--- primary 服务默认使用 Patroni RestAPI /primary 健康检查
http-check expect status 200
default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
# servers
server pg-test-1 10.10.10.11:6432 check port 8008 weight 100
server pg-test-3 10.10.10.13:6432 check port 8008 weight 100
server pg-test-2 10.10.10.12:6432 check port 8008 weight 100
Patroni 的 高可用 机制确保任何时候最多只会有一个实例的 /primary 健康检查为真,因此 Primary 服务将始终将流量路由到主实例。
使用 Primary 服务而不是直连数据库的一个好处是,如果集群因为某种情况出现了双主(比如在没有 watchdog 的情况下 kill -9杀死主库 Patroni),Haproxy 在这种情况下仍然可以避免脑裂,因为它只会在 Patroni 存活且返回主库状态时才会分发流量。
Replica服务 Replica 服务在生产环境中的重要性仅次于 Primary 服务,它在 5434 端口提供对数据库集群的只读能力,服务定义如下:
- { name: replica ,port: 5434 ,dest: default ,check: /read-only ,selector : "[]" , backup : "[? pg_role == `primary` || pg_role == `offline` ]" }
选择器参数 selector: "[]" 意味着所有集群成员都将被包括在 Replica 服务中 所有实例都能够通过健康检查(check: /read-only),承载 Replica 服务的流量。 备份选择器:[? pg_role == 'primary' || pg_role == 'offline' ] 将主库和 离线从库 标注为备份服务器。 只有当所有 普通从库 都宕机后,Replica 服务才会由主库或离线从库来承载。 目的地参数 dest: default 意味着 Replica 服务的目的地也受到 pg_default_service_dest 参数的影响 dest 默认值 default 会被替换为 pg_default_service_dest 的值,默认为 pgbouncer,这一点和 Primary服务 相同默认情况下 Replica 服务的目的地默认是从库上的连接池,也就是由 pgbouncer_port 指定的端口,默认为 6432 示例:pg-test-replica 的 haproxy 配置 listen pg-test-replica
bind *:5434
mode tcp
maxconn 5000
balance roundrobin
option httpchk
option http-keep-alive
http-check send meth OPTIONS uri /read-only
http-check expect status 200
default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
# servers
server pg-test-1 10.10.10.11:6432 check port 8008 weight 100 backup
server pg-test-3 10.10.10.13:6432 check port 8008 weight 100
server pg-test-2 10.10.10.12:6432 check port 8008 weight 100
Replica 服务非常灵活:如果有存活的专用 Replica 实例,那么它会优先使用这些实例来承载只读请求,只有当从库实例全部宕机后,才会由主库来兜底只读请求。对于常见的一主一从双节点集群就是:只要从库活着就用从库,从库挂了再用主库。
此外,除非专用只读实例全部宕机,Replica 服务也不会使用专用 Offline 实例,这样就避免了在线快查询与离线慢查询混在一起,相互影响。
Default服务 Default 服务在 5436 端口上提供服务,它是 Primary 服务的变体。
Default 服务总是绕过连接池直接连到主库上的 PostgreSQL,这对于管理连接、ETL 写入、CDC 数据变更捕获等都很有用。
- { name: primary ,port: 5433 ,dest: default ,check: /primary ,selector : "[]" }
如果 pg_default_service_dest 被修改为 postgres,那么可以说 Default 服务除了端口和名称内容之外,与 Primary 服务是完全等价的。在这种情况下,您可以考虑将 Default 从默认服务中剔除。
示例:pg-test-default 的 haproxy 配置 listen pg-test-default
bind *:5436 # <--- 除了监听端口/目标端口和服务名,其他配置和 primary 服务一模一样
mode tcp
maxconn 5000
balance roundrobin
option httpchk
option http-keep-alive
http-check send meth OPTIONS uri /primary
http-check expect status 200
default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
# servers
server pg-test-1 10.10.10.11:5432 check port 8008 weight 100
server pg-test-3 10.10.10.13:5432 check port 8008 weight 100
server pg-test-2 10.10.10.12:5432 check port 8008 weight 100
Offline服务 Default 服务在 5438 端口上提供服务,它也绕开连接池直接访问 PostgreSQL 数据库,通常用于慢查询/分析查询/ETL 读取/个人用户交互式查询,其服务定义如下:
- { name: offline ,port: 5438 ,dest: postgres ,check: /replica ,selector : "[? pg_role == `offline` || pg_offline_query ]" , backup : "[? pg_role == `replica` && !pg_offline_query]" }
Offline 服务将流量直接路由到专用的 离线从库 上,或者带有 pg_offline_query 标记的普通 只读实例 。
选择器参数从集群中筛选出了两种实例:pg_role = offline 的离线从库,或是带有 pg_offline_query = true 标记的普通 只读实例 专用离线从库和打标记的普通从库主要的区别在于:前者默认不承载 Replica服务 的请求,避免快慢请求混在一起,而后者默认会承载。 备份选择器参数从集群中筛选出了一种实例:不带 offline 标记的普通从库,这意味着如果离线实例或者带 Offline 标记的普通从库挂了之后,其他普通的从库可以用来承载 Offline 服务。 健康检查 /replica 只会针对从库返回 200, 主库会返回错误,因此 Offline 服务 永远不会将流量分发到主库实例上去,哪怕集群中只剩这一台主库。 同时,主库实例既不会被选择器圈中,也不会被备份选择器圈中,因此它永远不会承载 Offline 服务。因此 Offline 服务总是可以避免用户访问主库,从而避免对主库的影响。 示例:pg-test-offline 的 haproxy 配置 listen pg-test-offline
bind *:5438
mode tcp
maxconn 5000
balance roundrobin
option httpchk
option http-keep-alive
http-check send meth OPTIONS uri /replica
http-check expect status 200
default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
# servers
server pg-test-3 10.10.10.13:5432 check port 8008 weight 100
server pg-test-2 10.10.10.12:5432 check port 8008 weight 100 backup
Offline 服务提供受限的只读服务,通常用于两类查询:交互式查询(个人用户),慢查询长事务(分析/ETL)。
Offline 服务需要额外的维护照顾:当集群发生主从切换或故障自动切换时,集群的实例角色会发生变化,而 Haproxy 的配置却不会自动发生变化。对于有多个从库的集群来说,这通常并不是一个问题。
然而对于一主一从,从库跑 Offline 查询的精简小集群而言,主从切换意味着从库变成了主库(健康检查失效),原来的主库变成了从库(不在 Offline 后端列表中),于是没有实例可以承载 Offline 服务了,因此需要手动 重载服务 以使变更生效。
如果您的业务模型较为简单,您可以考虑剔除 Default 服务与 Offline 服务,使用 Primary 服务与 Replica 服务直连数据库。
重载服务 当集群成员发生变化,如添加/删除副本、主备切换或调整相对权重时, 你需要 重载服务 以使更改生效。
bin/pgsql-svc <cls> [ ip...] # 为 lb 集群或 lb 实例重载服务
# ./pgsql.yml -t pg_service # 重载服务的实际 ansible 任务
接入服务 Pigsty 的服务交付边界止步于集群的 HAProxy,用户可以用各种手段访问这些负载均衡器。
典型的做法是使用 DNS 或 VIP 接入,将其绑定在集群所有或任意数量的负载均衡器上。
你可以使用不同的 主机 & 端口 组合,它们以不同的方式提供 PostgreSQL 服务。
主机
类型 样例 描述 集群域名 pg-test通过集群域名访问(由 dnsmasq @ infra 节点解析) 集群 VIP 地址 10.10.10.3通过由 vip-manager 管理的 L2 VIP 地址访问,绑定到主节点 实例主机名 pg-test-1通过任何实例主机名访问(由 dnsmasq @ infra 节点解析) 实例 IP 地址 10.10.10.11访问任何实例的 IP 地址
端口
Pigsty 使用不同的 端口 来区分 pg services
端口 服务 类型 描述 5432 postgres 数据库 直接访问 postgres 服务器 6432 pgbouncer 中间件 访问 postgres 前先通过连接池中间件 5433 primary 服务 访问主 pgbouncer (或 postgres) 5434 replica 服务 访问备份 pgbouncer (或 postgres) 5436 default 服务 访问主 postgres 5438 offline 服务 访问离线 postgres
组合
# 通过集群域名访问
postgres://test@pg-test:5432/test # DNS -> L2 VIP -> 主直接连接
postgres://test@pg-test:6432/test # DNS -> L2 VIP -> 主连接池 -> 主
postgres://test@pg-test:5433/test # DNS -> L2 VIP -> HAProxy -> 主连接池 -> 主
postgres://test@pg-test:5434/test # DNS -> L2 VIP -> HAProxy -> 备份连接池 -> 备份
postgres://dbuser_dba@pg-test:5436/test # DNS -> L2 VIP -> HAProxy -> 主直接连接 (用于管理员)
postgres://dbuser_stats@pg-test:5438/test # DNS -> L2 VIP -> HAProxy -> 离线直接连接 (用于 ETL/个人查询)
# 通过集群 VIP 直接访问
postgres://test@10.10.10.3:5432/test # L2 VIP -> 主直接访问
postgres://test@10.10.10.3:6432/test # L2 VIP -> 主连接池 -> 主
postgres://test@10.10.10.3:5433/test # L2 VIP -> HAProxy -> 主连接池 -> 主
postgres://test@10.10.10.3:5434/test # L2 VIP -> HAProxy -> 备份连接池 -> 备份
postgres://dbuser_dba@10.10.10.3:5436/test # L2 VIP -> HAProxy -> 主直接连接 (用于管理员)
postgres://dbuser_stats@10.10.10.3::5438/test # L2 VIP -> HAProxy -> 离线直接连接 (用于 ETL/个人查询)
# 直接指定任何集群实例名
postgres://test@pg-test-1:5432/test # DNS -> 数据库实例直接连接 (单例访问)
postgres://test@pg-test-1:6432/test # DNS -> 连接池 -> 数据库
postgres://test@pg-test-1:5433/test # DNS -> HAProxy -> 连接池 -> 数据库读/写
postgres://test@pg-test-1:5434/test # DNS -> HAProxy -> 连接池 -> 数据库只读
postgres://dbuser_dba@pg-test-1:5436/test # DNS -> HAProxy -> 数据库直接连接
postgres://dbuser_stats@pg-test-1:5438/test # DNS -> HAProxy -> 数据库离线读/写
# 直接指定任何集群实例 IP 访问
postgres://test@10.10.10.11:5432/test # 数据库实例直接连接 (直接指定实例, 没有自动流量分配)
postgres://test@10.10.10.11:6432/test # 连接池 -> 数据库
postgres://test@10.10.10.11:5433/test # HAProxy -> 连接池 -> 数据库读/写
postgres://test@10.10.10.11:5434/test # HAProxy -> 连接池 -> 数据库只读
postgres://dbuser_dba@10.10.10.11:5436/test # HAProxy -> 数据库直接连接
postgres://dbuser_stats@10.10.10.11:5438/test # HAProxy -> 数据库离线读-写
# 智能客户端:自动进行读写分离
postgres://test@10.10.10.11:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs= primary
postgres://test@10.10.10.11:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs= prefer-standby
覆盖服务 你可以通过多种方式覆盖默认的服务配置,一种常见的需求是让 Primary服务 与 Replica服务 绕过 Pgbouncer 连接池,直接访问 PostgreSQL 数据库。
为了实现这一点,你可以将 pg_default_service_dest 更改为 postgres,这样所有服务定义中 svc.dest='default' 的服务都会使用 postgres 而不是默认的 pgbouncer 作为目标。
如果您已经将 Primary服务 指向了 PostgreSQL,那么 default服务 就会比较多余,可以考虑移除。
如果您不需要区分个人交互式查询,分析/ETL 慢查询,可以考虑从默认服务列表 pg_default_services 中移除 Offline服务 。
如果您不需要只读从库来分担在线只读流量,也可以从默认服务列表中移除 Replica服务 。
委托服务 Pigsty 通过节点上的 haproxy 暴露 PostgreSQL 服务。整个集群中的所有 haproxy 实例都使用相同的 服务定义 进行配置。
但是,你可以将 pg 服务委托给特定的节点分组(例如,专门的 haproxy 负载均衡器集群),而不是 PostgreSQL 集群成员上的 haproxy。
为此,你需要使用 pg_default_services 覆盖默认的服务定义,并将 pg_service_provider 设置为代理组名称。
例如,此配置将在端口 10013 的 proxy haproxy 节点组上公开 pg 集群的主服务。
pg_service_provider : proxy # 使用端口 10013 上的 `proxy` 组的负载均衡器
pg_default_services : [ { name: primary ,port: 10013 ,dest: postgres ,check: /primary ,selector : "[]" }]
用户需要确保每个委托服务的端口,在代理集群中都是唯一 的。
在 43 节点生产环境仿真 沙箱 中提供了一个使用专用负载均衡器集群的例子:prod.yml
12.4 - 访问控制 Pigsty 提供的默认角色系统与权限模型
Pigsty 提供了一套开箱即用的,基于 角色系统 和 权限系统 的访问控制模型。
权限控制很重要,但很多用户做不好。因此 Pigsty 提供了一套开箱即用的精简访问控制模型,为您的集群安全性提供一个兜底。
角色系统 Pigsty 默认的角色系统包含四个 默认角色 和四个 默认用户 :
角色名称 属性 所属 描述 dbrole_readonlyNOLOGIN角色:全局只读访问 dbrole_readwriteNOLOGINdbrole_readonly 角色:全局读写访问 dbrole_adminNOLOGINpg_monitor,dbrole_readwrite 角色:管理员/对象创建 dbrole_offlineNOLOGIN角色:受限的只读访问 postgresSUPERUSER系统超级用户 replicatorREPLICATIONpg_monitor,dbrole_readonly 系统复制用户 dbuser_dbaSUPERUSERdbrole_admin pgsql 管理用户 dbuser_monitorpg_monitor pgsql 监控用户
这些 角色与用户 的详细定义如下所示:
pg_default_roles : # 全局默认的角色与系统用户
- { name: dbrole_readonly ,login: false ,comment : role for global read-only access }
- { name: dbrole_offline ,login: false ,comment : role for restricted read-only access }
- { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly] ,comment : role for global read-write access }
- { name: dbrole_admin ,login: false ,roles: [pg_monitor, dbrole_readwrite] ,comment : role for object creation }
- { name: postgres ,superuser: true ,comment : system superuser }
- { name: replicator ,replication: true ,roles: [pg_monitor, dbrole_readonly] ,comment : system replicator }
- { name: dbuser_dba ,superuser: true ,roles: [dbrole_admin] ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 ,comment : pgsql admin user }
- { name: dbuser_monitor ,roles: [pg_monitor] ,pgbouncer: true ,parameters : {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment : pgsql monitor user }
默认角色 Pigsty 中有四个默认角色:
业务只读 (dbrole_readonly): 用于全局只读访问的角色。如果别的业务想要此库只读访问权限,可以使用此角色。 业务读写 (dbrole_readwrite): 用于全局读写访问的角色,主属业务使用的生产账号应当具有数据库读写权限 业务管理员 (dbrole_admin): 拥有 DDL 权限的角色,通常用于业务管理员,或者需要在应用中建表的场景(比如各种业务软件) 离线只读访问 (dbrole_offline): 受限的只读访问角色(只能访问 offline 实例,通常是个人用户,ETL 工具账号) 默认角色在 pg_default_roles 中定义,除非您确实知道自己在干什么,建议不要更改默认角色的名称。
- { name: dbrole_readonly , login: false , comment : role for global read-only access } # 生产环境的只读角色
- { name: dbrole_offline , login: false , comment : role for restricted read-only access (offline instance) } # 受限的只读角色
- { name: dbrole_readwrite , login: false , roles: [dbrole_readonly], comment : role for global read-write access } # 生产环境的读写角色
- { name: dbrole_admin , login: false , roles: [pg_monitor, dbrole_readwrite] , comment : role for object creation } # 生产环境的 DDL 更改角色
默认用户 Pigsty 也有四个默认用户(系统用户):
超级用户 (postgres),集群的所有者和创建者,与操作系统 dbsu 名称相同。 复制用户 (replicator),用于主-从复制的系统用户。 监控用户 (dbuser_monitor),用于监控数据库和连接池指标的用户。 管理用户 (dbuser_dba),执行日常操作和数据库更改的管理员用户。 这4个默认用户的用户名/密码通过4对专用参数进行定义,并在很多地方引用:
在生产部署中记得更改这些密码,不要使用默认值!
pg_dbsu : postgres # 数据库超级用户名,这个用户名建议不要修改。
pg_dbsu_password : '' # 数据库超级用户密码,这个密码建议留空!禁止dbsu密码登陆。
pg_replication_username : replicator # 系统复制用户名
pg_replication_password : DBUser.Replicator # 系统复制密码,请务必修改此密码!
pg_monitor_username : dbuser_monitor # 系统监控用户名
pg_monitor_password : DBUser.Monitor # 系统监控密码,请务必修改此密码!
pg_admin_username : dbuser_dba # 系统管理用户名
pg_admin_password : DBUser.DBA # 系统管理密码,请务必修改此密码!
如果您修改默认用户的参数,在 pg_default_roles 中修改相应的角色 定义 即可:
- { name: postgres ,superuser: true ,comment : system superuser }
- { name: replicator ,replication: true ,roles: [pg_monitor, dbrole_readonly] ,comment : system replicator }
- { name: dbuser_dba ,superuser: true ,roles: [dbrole_admin] ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 , comment : pgsql admin user }
- { name: dbuser_monitor ,roles: [pg_monitor, dbrole_readonly] ,pgbouncer: true ,parameters : {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment : pgsql monitor user }
权限系统 Pigsty 拥有一套开箱即用的权限模型,该模型与 默认角色 一起配合工作。
所有用户都可以访问所有模式。 只读用户(dbrole_readonly)可以从所有表中读取数据。(SELECT,EXECUTE) 读写用户(dbrole_readwrite)可以向所有表中写入数据并运行 DML。(INSERT,UPDATE,DELETE)。 管理员用户(dbrole_admin)可以创建对象并运行 DDL(CREATE,USAGE,TRUNCATE,REFERENCES,TRIGGER)。 离线用户(dbrole_offline)类似只读用户,但访问受到限制,只允许访问 离线实例 (pg_role = 'offline' 或 pg_offline_query = true) 由管理员用户创建的对象将具有正确的权限。 所有数据库上都配置了默认权限,包括模板数据库。 数据库连接权限由数据库 定义 管理。 默认撤销PUBLIC在数据库和public模式下的CREATE权限。 对象权限 数据库中新建对象的默认权限由参数 pg_default_privileges 所控制:
- GRANT USAGE ON SCHEMAS TO dbrole_readonly
- GRANT SELECT ON TABLES TO dbrole_readonly
- GRANT SELECT ON SEQUENCES TO dbrole_readonly
- GRANT EXECUTE ON FUNCTIONS TO dbrole_readonly
- GRANT USAGE ON SCHEMAS TO dbrole_offline
- GRANT SELECT ON TABLES TO dbrole_offline
- GRANT SELECT ON SEQUENCES TO dbrole_offline
- GRANT EXECUTE ON FUNCTIONS TO dbrole_offline
- GRANT INSERT ON TABLES TO dbrole_readwrite
- GRANT UPDATE ON TABLES TO dbrole_readwrite
- GRANT DELETE ON TABLES TO dbrole_readwrite
- GRANT USAGE ON SEQUENCES TO dbrole_readwrite
- GRANT UPDATE ON SEQUENCES TO dbrole_readwrite
- GRANT TRUNCATE ON TABLES TO dbrole_admin
- GRANT REFERENCES ON TABLES TO dbrole_admin
- GRANT TRIGGER ON TABLES TO dbrole_admin
- GRANT CREATE ON SCHEMAS TO dbrole_admin
由管理员新创建 的对象,默认将会上述权限。使用 \ddp+ 可以查看这些默认权限:
类型 访问权限 函数 =X dbrole_readonly=X dbrole_offline=X dbrole_admin=X 模式 dbrole_readonly=U dbrole_offline=U dbrole_admin=UC 序列号 dbrole_readonly=r dbrole_offline=r dbrole_readwrite=wU dbrole_admin=rwU 表 dbrole_readonly=r dbrole_offline=r dbrole_readwrite=awd dbrole_admin=arwdDxt
默认权限 ALTER DEFAULT PRIVILEGES 允许您设置将来创建的对象的权限。 它不会影响已经存在对象的权限,也不会影响非管理员用户创建的对象。
在 Pigsty 中,默认权限针对三个角色进行定义:
{ % for priv in pg_default_privileges % }
ALTER DEFAULT PRIVILEGES FOR ROLE {{ pg_dbsu }} {{ priv }} ;
{ % endfor % }
{ % for priv in pg_default_privileges % }
ALTER DEFAULT PRIVILEGES FOR ROLE {{ pg_admin_username }} {{ priv }} ;
{ % endfor % }
-- 对于其他业务管理员而言,它们应当在执行 DDL 前执行 SET ROLE dbrole_admin,从而使用对应的默认权限配置。
{ % for priv in pg_default_privileges % }
ALTER DEFAULT PRIVILEGES FOR ROLE "dbrole_admin" {{ priv }} ;
{ % endfor % }
这些内容将会被 PG 集群初始化模板 pg-init-template.sql 所使用,在集群初始化的过程中渲染并输出至 /pg/tmp/pg-init-template.sql。
该命令会在 template1 与 postgres 数据库中执行,新创建的数据库会通过模板 template1 继承这些默认权限配置。
也就是说,为了维持正确的对象权限,您必须用管理员用户 来执行 DDL,它们可以是:
{{ pg_dbsu }} ,默认为 postgres{{ pg_admin_username }} ,默认为 dbuser_dba授予了 dbrole_admin 角色的业务管理员用户(通过 SET ROLE 切换为 dbrole_admin 身份)。 使用 postgres 作为全局对象所有者是明智的。如果您希望以业务管理员用户身份创建对象,创建之前必须使用 SET ROLE dbrole_admin 来维护正确的权限。
当然,您也可以在数据库中通过 ALTER DEFAULT PRIVILEGE FOR ROLE <some_biz_admin> XXX 来显式对业务管理员授予默认权限。
数据库权限 在 Pigsty 中,数据库(Database)层面的权限在 数据库定义 中被涵盖。
数据库有三个级别的权限:CONNECT、CREATE、TEMP,以及一个特殊的’权限’:OWNERSHIP。
- name : meta # 必选,`name` 是数据库定义中唯一的必选字段
owner : postgres # 可选,数据库所有者,默认为 postgres
allowconn : true # 可选,是否允许连接,默认为 true。显式设置 false 将完全禁止连接到此数据库
revokeconn : false # 可选,撤销公共连接权限。默认为 false,设置为 true 时,属主和管理员之外用户的 CONNECT 权限会被回收
如果 owner 参数存在,它作为数据库属主,替代默认的 {{ pg_dbsu }} (通常也就是postgres) 如果 revokeconn 为 false,所有用户都有数据库的 CONNECT 权限,这是默认的行为。 如果显式设置了 revokeconn 为 true:数据库的 CONNECT 权限将从 PUBLIC 中撤销:普通用户无法连接上此数据库 CONNECT 权限将被显式授予 {{ pg_replication_username }}、{{ pg_monitor_username }} 和 {{ pg_admin_username }}CONNECT 权限将 GRANT OPTION 被授予数据库属主,数据库属主用户可以自行授权其他用户连接权限。 revokeconn 选项可用于在同一个集群间隔离跨数据库访问,您可以为每个数据库创建不同的业务用户作为属主,并为它们设置 revokeconn 选项。示例:数据库隔离 pg-infra :
hosts :
10.10.10.40 : { pg_seq: 1, pg_role : primary }
10.10.10.41 : { pg_seq: 2, pg_role: replica , pg_offline_query : true }
vars :
pg_cluster : pg-infra
pg_users :
- { name: dbuser_confluence, password: mc2iohos , pgbouncer: true, roles : [ dbrole_admin ] }
- { name: dbuser_gitlab, password: sdf23g22sfdd , pgbouncer: true, roles : [ dbrole_readwrite ] }
- { name: dbuser_jira, password: sdpijfsfdsfdfs , pgbouncer: true, roles : [ dbrole_admin ] }
pg_databases :
- { name: confluence , revokeconn: true, owner: dbuser_confluence , connlimit : 100 }
- { name: gitlab , revokeconn: true, owner: dbuser_gitlab, connlimit : 100 }
- { name: jira , revokeconn: true, owner: dbuser_jira , connlimit : 100 }
CREATE权限 出于安全考虑,Pigsty 默认从 PUBLIC 撤销数据库上的 CREATE 权限,从 PostgreSQL 15 开始这也是默认行为。
数据库属主总是可以根据实际需要,来自行调整 CREATE 权限。
12.6 - 日常管理 数据库日常管理任务标准操作指南(SOP)
12.6.1 - 管理 PostgreSQL 数据库集群 创建/销毁 PostgreSQL 集群,以及对现有集群进行扩容,缩容,克隆集群。
速查手册 操作 快捷命令 说明 创建集群 bin/pgsql-add <cls>创建新的 PostgreSQL 集群 扩容集群 bin/pgsql-add <cls> <ip...>为现有集群添加从库副本 缩容集群 bin/pgsql-rm <cls> <ip...>从集群中移除指定实例 销毁集群 bin/pgsql-rm <cls>销毁整个 PostgreSQL 集群 刷新服务 bin/pgsql-svc <cls> [ip...]重载集群的负载均衡配置 刷新HBA bin/pgsql-hba <cls> [ip...]重载集群的 HBA 访问规则 克隆集群 - 通过备份集群或 PITR 克隆
其他管理任务,请参考:高可用管理 ,管理用户 ,管理数据库 。
创建集群 要创建一个新的 PostgreSQL 集群,请首先在 配置清单 中 定义集群 ,然后 纳管节点 并进行初始化:
bin/node-add <cls> # 添加分组 <cls> 下的节点
./node.yml -l <cls> # 直接使用 Ansible 剧本添加分组 <cls> 下的节点
bin/pgsql-add pg-test # 例子,添加 pg-test 分组下的节点,实际执行 ./node.yml -l pg-test
在被纳管的节点上,可以使用以下命令创建集群:(针对 <cls> 分组执行 pgsql.yml 剧本)
bin/pgsql-add <cls> # 创建 PostgreSQL 集群 <cls>
./pgsql.yml -l <cls> # 直接使用 Ansible 剧本创建 PostgreSQL 集群 <cls>
bin/pgsql-add pg-test # 例子,创建 pg-test 集群
示例:创建三节点 PG 集群 pg-test
针对已经存在的集群重新执行创建存在风险
如果您在已经存在的集群上重新执行创建操作,Pigsty 不会移除已有的数据文件,但现有服务配置会被覆盖,集群会发生 重启 !
此外,如果你在 数据库定义 中指定了 baseline SQL,它也会重新执行,如果里面包含删除/覆盖逻辑,可能会导致 数据丢失 。
扩容集群 若要将新从库添加到 现有的 PostgreSQL 集群 中,您需要将 实例定义 添加到 配置清单 :all.children.<cls>.hosts 中。
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 }
扩容集群的操作与 创建集群 非常类似,首先需要将扩容的节点纳入 Pigsty 管理:添加节点 :
bin/node-add <ip> # 添加 IP 地址为 <ip> 的节点
./node.yml -l <ip> # 直接使用 Ansible 剧本添加 <ip> 对应的节点
bin/node-add 10.10.10.13 # 例子,添加 IP 为 10.10.10.13 的节点,实际执行 ./node.yml -l 10.10.10.13
然后在新节点上运行以下命令以扩容集群(针对新节点安装 PGSQL 模块 ,使用与现有集群相同的 pg_cluster )
bin/pgsql-add <cls> <ip> # 添加 IP 地址为 <ip> 的节点
./pgsql.yml -l <ip> # 核心逻辑:使用 Ansible 剧本在 <ip> 节点上安装 PGSQL 模块
bin/pgsql-add pg-test 10.10.10.13 # 示例,为 pg-test 集群扩容 IP 为 10.10.10.13 的节点
扩容完成后,您应当 刷新服务 以将新成员添加至负载均衡器中以实际承载流量。
示例:为两节点集群 pg-test 扩容一个新从库 10.10.10.13
缩容集群 若要从 现有的 PostgreSQL 集群 中移除副本,您需要从 配置清单 的 all.children.<cls>.hosts 中移除对应的 实例定义 。
缩容集群首先需要卸载目标节点上的 PGSQL 模块(针对 <ip> 执行 pgsql-rm.yml 剧本):
bin/pgsql-rm <cls> <ip> # 从集群 <cls> 中移除 <ip> 节点上的 PostgreSQL 实例
./pgsql-rm.yml -l <ip> # 直接使用 Ansible 剧本移除 <ip> 节点上的 PostgreSQL 实例
bin/pgsql-rm pg-test 10.10.10.13 # 例子,从 pg-test 集群移除 10.10.10.13 节点
移除 PGSQL 模块后,您可以选择将节点从 Pigsty 管理中移除:移除节点 (可选):
bin/node-rm <ip> # 从 Pigsty 管理中移除 <ip> 节点
./node-rm.yml -l <ip> # 直接使用 Ansible 剧本从 Pigsty 管理中移除 <ip> 节点
bin/node-rm 10.10.10.13 # 例子,从 Pigsty 管理中移除 10.10.10.13 节点
缩容完成后,您应当从 配置清单 中移除该实例的定义,然后 刷新服务 以将已它从负载均衡器中踢除。
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 }
示例:从三节点集群 pg-test 中缩容一个从库 10.10.10.13
销毁集群 销毁集群需要在集群的所有节点上卸载 PGSQL 模块(针对 <cls> 执行 pgsql-rm.yml 剧本):
bin/pgsql-rm <cls> # 销毁整个 PostgreSQL 集群 <cls>
./pgsql-rm.yml -l <cls> # 直接使用 Ansible 剧本销毁整个 PostgreSQL 集群 <cls>
bin/pgsql-rm pg-test # 例子,销毁 pg-test 集群
销毁 PGSQL 模块后,您可以选择将节点一并从 Pigsty 管理中移除:移除节点 (可选,如果还有其他服务可以保留):
bin/node-rm <cls> # 从 Pigsty 管理中移除 <cls> 分组下的所有节点
./node-rm.yml -l <cls> # 直接使用 Ansible 剧本从 Pigsty 管理中移除 <cls> 分组下的所有节点
bin/node-rm pg-test # 例子,从 Pigsty 管理中移除 pg-test 分组下的所有节点
销毁结束后,建议及时从 配置清单 中移除整个 集群定义 。
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 }
示例:销毁三节点 PG 集群 pg-test
注意:如果为这个集群配置了 pg_safeguard (或全局设置为 true),pgsql-rm.yml 将中止执行,以避免意外销毁集群。
您可以使用剧本命令行参数明确地覆盖它,以强制执行销毁。
此外默认情况下,集群的备份仓库将同集群一并删除。如果你希望保留备份(例如在使用集中式备份仓库时),可以设置 pg_rm_backup=false 参数:
./pgsql-rm.yml -l pg-meta -e pg_safeguard = false # 强制销毁受保护的 pg 集群 pg-meta
./pgsql-rm.yml -l pg-meta -e pg_rm_backup = false # 在销毁集群过程中保留其备份仓库
刷新服务 PostgreSQL 集群通过主机节点上的 HAProxy 对外提供 服务 。
当服务定义变化,实例权重变化,或者集群成员发生变化时(例如,集群 扩容 / 缩容 ,主从切换/故障转移),您需要择机刷新服务以更新负载均衡器的配置。
要在整个集群或特定实例上刷新服务配置(针对 <cls> 或 <ip> 执行 pgsql.yml 的 pg_service 子任务):
bin/pgsql-svc <cls> # 刷新整个集群 <cls> 的服务配置
bin/pgsql-svc <cls> <ip...> # 刷新集群 <cls> 中指定实例的服务配置
./pgsql.yml -l <cls> -t pg_service -e pg_reload = true # 刷新整个集群的服务配置
./pgsql.yml -l <ip> -t pg_service -e pg_reload = true # 刷新指定实例的服务配置
bin/pgsql-svc pg-test # 例子,刷新 pg-test 集群的服务配置
bin/pgsql-svc pg-test 10.10.10.13 # 例子,刷新 pg-test 集群中 10.10.10.13 实例的服务配置
备注:如果您使用集中式的专用负载均衡集群(pg_service_provider ),那么只有刷新集群主库时才会更新负载均衡配置。
示例:刷新集群 pg-test 的服务配置
示例:重载 PG 服务以踢除一个实例
刷新HBA 当您修改了 HBA 相关配置后,需要刷新 HBA 规则以应用更改。(pg_hba_rules / pgb_hba_rules )
如果您有任何特定于角色的 HBA 规则,或者在 IP 地址段中引用了集群成员的别名,那么当主从切换/集群扩缩容后也可能需要刷新 HBA。
要在整个集群或特定实例上刷新 PG 和 Pgbouncer 的 HBA 规则(针对 <cls> 或 <ip> 执行 pgsql.yml 的 HBA 相关子任务):
bin/pgsql-hba <cls> # 刷新整个集群 <cls> 的 HBA 规则
bin/pgsql-hba <cls> <ip...> # 刷新集群 <cls> 中指定实例的 HBA 规则
./pgsql.yml -l <cls> -t pg_hba,pg_reload,pgbouncer_hba,pgbouncer_reload -e pg_reload = true # 刷新整个集群
./pgsql.yml -l <ip> -t pg_hba,pg_reload,pgbouncer_hba,pgbouncer_reload -e pg_reload = true # 刷新指定实例
bin/pgsql-hba pg-test # 例子,刷新 pg-test 集群的 HBA 规则
bin/pgsql-hba pg-test 10.10.10.13 # 例子,刷新 pg-test 集群中 10.10.10.13 实例的 HBA 规则
示例:刷新集群 pg-test 的 HBA 规则
配置集群 PostgreSQL 的配置参数由 Patroni 管理,初始参数由 Patroni 配置模板 指定。
集群初始化之后,配置存储在 Etcd 中,并由 Patroni 进行动态管理,并在集群中同步与共享。
Patroni 本身的 配置参数 大部分可以通过 patronictl命令行工具修改。
其余参数(例如,etcd DCS 配置,日志/RestAPI 等配置)则可以通过下面的子任务进行更新。例如,当 etcd 集群成员发生变动时,你可以刷新 Patroni 配置:
./pgsql.yml -l pg-test -t pg_conf # 更新 Patroni 配置文件
ansible pg-test -b -a 'systemctl reload patroni' # 重载 Patroni 服务
您可以在不同层次上覆盖 Patroni 集中管理的默认,例如单独 为实例指定配置参数 ;
单独为 为用户指定配置参数 ,或者 为数据库指定配置参数 。
克隆集群 有两种克隆集群的方式:使用 备份集群 功能,或者使用 时间点恢复 功能。
前者配置简单,无需依赖,但只能克隆指定集群的最新状态;后者依赖集中式的 备份仓库 (例如 MinIO),但可以克隆到备份保留期内的任意时间点。
方式 优点 缺点 适用场景 备份集群 配置简单,无需依赖 只能克隆最新状态 灾备,读写分离,迁移 PITR 可恢复到任意时间点 依赖集中式备份仓库 误操作恢复,数据审计
使用备份集群克隆 备份集群(Standby Cluster)通过流复制从上游集群持续同步数据,是克隆集群最简单的方式。
只需在新集群主库上指定 pg_upstream 参数,即可自动从上游集群拉取数据。
# pg-test 是原始集群
pg-test :
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary }
vars : { pg_cluster : pg-test }
# pg-test2 是 pg-test 的备份集群(克隆)
pg-test2 :
hosts :
10.10.10.12 : { pg_seq: 1, pg_role: primary, pg_upstream : 10.10.10.11 } # 指定上游
10.10.10.13 : { pg_seq: 2, pg_role : replica }
vars : { pg_cluster : pg-test2 }
使用以下命令创建备份集群:
bin/pgsql-add pg-test2 # 创建备份集群,自动从上游 pg-test 克隆数据
./pgsql.yml -l pg-test2 # 直接使用 Ansible 剧本创建备份集群
备份集群会持续追随上游集群,保持数据同步。您可以随时将其 提升 为独立集群:
示例:提升备份集群为独立集群 通过 配置集群 擦除 standby_cluster 配置段,即可将备份集群提升为独立集群:
$ pg edit-config pg-test2
-standby_cluster:
- create_replica_methods:
- - basebackup
- host: 10.10.10.11
- port: 5432
Apply these changes? [ y/N] : y
提升后,pg-test2 将成为可以独立承载写入请求的独立集群,与原集群 pg-test 分叉。
示例:更改复制上游 如果上游集群发生主从切换,您可以通过 配置集群 更改备份集群的复制上游:
$ pg edit-config pg-test2
standby_cluster:
create_replica_methods:
- basebackup
- host: 10.10.10.11 # <--- 旧的上游
+ host: 10.10.10.14 # <--- 新的上游
port: 5432
Apply these changes? [ y/N] : y
使用 PITR 克隆 时间点恢复 (PITR)允许您将集群恢复到备份保留期内的任意时间点。
此方式依赖集中式的 备份仓库 (如 MinIO/S3),但功能更加强大。
要使用 PITR 克隆集群,在配置中添加 pg_pitr 参数指定恢复目标:
# 从 pg-meta 集群的备份克隆一个新集群 pg-meta2
pg-meta2 :
hosts : { 10.10.10.12 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta2
pg_pitr :
cluster : pg-meta # 从 pg-meta 的备份恢复
time : '2025-01-10 10:00:00+00' # 恢复到指定时间点
使用 pgsql-pitr.yml 剧本执行克隆:
./pgsql-pitr.yml -l pg-meta2 # 从 pg-meta 备份克隆 pg-meta2
# 也可以通过命令行参数指定 PITR 选项
./pgsql-pitr.yml -l pg-meta2 -e '{"pg_pitr": {"cluster": "pg-meta", "time": "2025-01-10 10:00:00+00"}}'
PITR 支持多种恢复目标类型:
目标类型 参数示例 说明 时间点 time: "2025-01-10 10:00:00+00"恢复到指定时间戳 事务 ID xid: "250000"恢复到指定事务之前/之后 恢复点 name: "before_migration"恢复到命名恢复点 LSN lsn: "0/4001C80"恢复到指定 WAL 位置 最新 type: "latest"恢复到 WAL 归档末尾
PITR 恢复后处理
恢复后的集群会禁用 archive_mode,以防止意外的 WAL 写入覆盖归档。
如果恢复后的数据库状态正常,您应当启用归档并执行新的全量备份:
psql -c 'ALTER SYSTEM RESET archive_mode; SELECT pg_reload_conf();'
pg-backup full # 执行新的全量备份
更多 PITR 的详细用法,请参考 恢复操作 文档。
12.6.2 - 管理 PostgreSQL 业务用户 用户管理:创建、修改、删除用户,管理角色成员关系,连接池用户配置
快速上手 Pigsty 使用声明式管理方式,首先在 配置清单 中 定义用户 ,然后使用 bin/pgsql-user <cls> <username> 创建或修改用户。
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta
pg_users : [ { name: dbuser_app, password: 'DBUser.App', pgbouncer : true }] # <--- 在这里定义用户列表!
bin/pgsql-user <cls> <username> # 在 <cls> 集群上创建/修改 <username> 用户
./pgsql-user.yml -l pg-meta -e username = dbuser_app # 直接使用剧本在 <cls> 集群上创建/修改 <username> 用户
bin/pgsql-user pg-meta dbuser_app # 在 pg-meta 集群上创建/修改 dbuser_app 用户
关于用户定义参数的完整参考,请查阅 用户配置 。关于用户的访问权限,请参考 ACL:角色权限 。
请注意,用户的 name 字段在创建后无法修改。如需更改用户名,请先删除原用户,再创建新用户。
操作 快捷命令 说明 创建用户 bin/pgsql-user <cls> <user>创建新的业务用户或角色 修改用户 bin/pgsql-user <cls> <user>修改已存在用户的属性 删除用户 bin/pgsql-user <cls> <user>安全删除用户(需设置 state: absent)
创建用户 定义在 pg_users 里面的用户会在 PostgreSQL 集群创建 的时候在 pg_user 任务中自动创建。
要在现有的 PostgreSQL 集群上创建新的业务用户,请将 用户定义 添加到 all.children.<cls>.pg_users,然后执行:
bin/pgsql-user <cls> <username> # 创建用户 <username>
./pgsql-user.yml -l <cls> -e username = <username> # 直接使用 Ansible 剧本创建用户
bin/pgsql-user pg-meta dbuser_app # 例子,在 pg-meta 集群中创建 dbuser_app 用户
示例配置:创建名为 dbuser_app 的业务用户
#all.children.pg-meta.vars.pg_users: # 省略上级缩进
- name : dbuser_app
password : DBUser.App
pgbouncer : true
roles : [ dbrole_readwrite]
comment : application user for myapp
执行效果 :在主库上创建用户 dbuser_app,设置密码,授予 dbrole_readwrite 角色权限,
将用户添加到 Pgbouncer 连接池,在每个实例上重载 Pgbouncer 配置使其立即生效。
建议使用剧本创建用户
如果您需要手工创建用户,那么需要自行确保 Pgbouncer 连接池用户列表同步。
修改用户 修改用户与创建用户使用相同的命令,剧本是幂等的。当目标用户已存在时,Pigsty 会修改目标用户的属性使其符合配置。
bin/pgsql-user <cls> <user> # 修改用户 <user> 的属性
./pgsql-user.yml -l <cls> -e username = <user> # 幂等操作,可重复执行
bin/pgsql-user pg-meta dbuser_app # 修改 dbuser_app 用户的属性使其符合配置
不可修改的属性 :用户的 name(名称)在创建后无法修改,需要先删除再创建。
其他属性均可修改,以下是一些常见的修改示例:
修改密码 :更新配置中的 password 字段后执行剧本。密码修改时会临时禁用日志记录,避免密码泄露到日志中。
- name : dbuser_app
password : NewSecretPassword # 修改密码
修改权限属性 :通过配置相应的布尔标志来修改用户权限。
- name : dbuser_app
superuser : false # 超级用户(谨慎使用!)
createdb : true # 允许创建数据库
createrole : false # 允许创建角色
inherit : true # 自动继承角色权限
replication : false # 允许流复制连接
bypassrls : false # 绕过行级安全策略
connlimit : 50 # 限制连接数,-1 不限制
修改用户有效期 :使用 expire_in 设置相对过期时间(N 天后过期),或 expire_at 设置绝对过期日期。expire_in 优先级更高,每次执行剧本时会重新计算,适合需要定期续期的临时用户。
- name : temp_user
expire_in : 30 # 30 天后过期(相对时间)
- name : contractor_user
expire_at : '2024-12-31' # 指定日期过期(绝对时间)
- name : permanent_user
expire_at : 'infinity' # 永不过期
修改角色成员关系 :通过 roles 数组配置角色成员关系,支持简单格式和扩展格式。角色成员关系是增量操作,不会移除未声明的现有角色。使用 state: absent 可以显式撤销角色。
- name : dbuser_app
roles :
- dbrole_readwrite # 简单形式:授予角色
- { name: dbrole_admin, admin : true } # 带 ADMIN OPTION(可以将此角色授予其他用户)
- { name: pg_monitor, set: false } # PG16+ : 不允许 SET ROLE
- { name: old_role, state : absent } # 撤销角色成员关系
管理用户参数 :通过 parameters 字典配置用户级参数,会生成 ALTER USER ... SET 语句。使用特殊值 DEFAULT 可将参数重置为 PostgreSQL 默认值。
- name : dbuser_analyst
parameters :
work_mem : '256MB'
statement_timeout : '5min'
search_path : 'analytics,public'
log_statement : DEFAULT # 重置为默认值
连接池配置 :设置 pgbouncer: true 将用户添加到连接池,可选配置 pool_mode(池化模式:transaction/session/statement)和 pool_connlimit(用户最大连接数)。
- name : dbuser_app
pgbouncer : true # 添加到连接池
pool_mode : transaction # 池化模式
pool_connlimit : 50 # 用户最大连接数
删除用户 要删除用户,将其 state 设置为 absent 并执行剧本:
bin/pgsql-user <cls> <user> # 删除用户 <user>(需在配置中设置 state: absent)
./pgsql-user.yml -l <cls> -e username = <user> # 直接使用 Ansible 剧本删除用户
bin/pgsql-user pg-meta dbuser_old # 删除 dbuser_old 用户(配置中已设置 state: absent)
配置示例 :
pg_users :
- name : dbuser_old
state : absent
删除操作会 :使用 pg-drop-role 脚本安全删除用户,自动禁用用户登录并终止活跃连接,自动转移数据库/表空间所有权到 postgres,自动处理所有数据库中的对象所有权和权限,撤销所有角色成员关系,创建审计日志,从 Pgbouncer 用户列表中移除并重载配置。
保护机制 :以下系统用户无法删除,会被自动跳过:postgres(超级用户)、replicator(或 pg_replication_username 配置的用户)、dbuser_dba(或 pg_admin_username 配置的用户)、dbuser_monitor(或 pg_monitor_username 配置的用户)。
安全删除
Pigsty 使用 pg-drop-role 脚本安全删除用户,该脚本会自动处理用户拥有的数据库、表空间、Schema、表等对象,自动终止用户的活跃连接,将对象所有权转移给 postgres 用户,并在 /tmp/pg_drop_role_<user>_<timestamp>.log 创建审计日志。无需手动处理依赖对象。
手工删除用户 如果需要手动删除用户,可以直接使用 pg-drop-role 脚本:
# 检查依赖关系(只读操作)
pg-drop-role dbuser_old --check
# 预览删除操作(不实际执行)
pg-drop-role dbuser_old --dry-run -v
# 删除用户,转移对象给 postgres
pg-drop-role dbuser_old
# 强制删除(终止活跃连接)
pg-drop-role dbuser_old --force
# 删除用户,转移对象给指定用户
pg-drop-role dbuser_old dbuser_new
常见用例 下面是一些常见的用户配置示例:
创建基本业务用户
- name : dbuser_app
password : DBUser.App
pgbouncer : true
roles : [ dbrole_readwrite]
comment : application user
创建只读用户
- name : dbuser_readonly
password : DBUser.Readonly
pgbouncer : true
roles : [ dbrole_readonly]
创建管理员用户(可执行 DDL)
- name : dbuser_admin
password : DBUser.Admin
pgbouncer : true
pool_mode : session
roles : [ dbrole_admin]
parameters :
log_statement : 'all'
创建临时用户(30天后过期)
- name : temp_contractor
password : TempPassword
expire_in : 30
roles : [ dbrole_readonly]
创建角色(不可登录,用于权限分组)
- name : custom_role
login : false
comment : custom role for special permissions
创建带高级角色选项的用户(PG16+)
- name : dbuser_special
password : DBUser.Special
pgbouncer : true
roles :
- dbrole_readwrite
- { name: dbrole_admin, admin : true }
- { name: pg_monitor, set : false }
- { name: pg_execute_server_program, inherit : false }
查询用户 以下是一些常用的 SQL 查询,用于查看用户信息:
查看所有用户
SELECT rolname , rolsuper , rolinherit , rolcreaterole , rolcreatedb ,
rolcanlogin , rolreplication , rolbypassrls , rolconnlimit , rolvaliduntil
FROM pg_roles WHERE rolname NOT LIKE 'pg_%' ORDER BY rolname ;
查看用户的角色成员关系
SELECT r . rolname AS member , g . rolname AS role , m . admin_option , m . set_option , m . inherit_option
FROM pg_auth_members m
JOIN pg_roles r ON r . oid = m . member
JOIN pg_roles g ON g . oid = m . roleid
WHERE r . rolname = 'dbuser_app' ;
查看用户级参数设置
SELECT rolname , setconfig FROM pg_db_role_setting s
JOIN pg_roles r ON r . oid = s . setrole WHERE s . setdatabase = 0 ;
查看即将过期的用户
SELECT rolname , rolvaliduntil , rolvaliduntil - CURRENT_TIMESTAMP AS time_remaining
FROM pg_roles WHERE rolvaliduntil IS NOT NULL
AND rolvaliduntil < CURRENT_TIMESTAMP + INTERVAL '30 days'
ORDER BY rolvaliduntil ;
连接池管理 在用户定义中配置的 连接池参数 会在创建/修改用户时应用到 Pgbouncer 连接池中。
设置 pgbouncer: true 的用户会被添加到 /etc/pgbouncer/userlist.txt 文件中。用户级别的连接池参数(pool_mode、pool_connlimit)通过 /etc/pgbouncer/useropts.txt 文件配置。
您可以使用 postgres 操作系统用户,使用 pgb 别名访问 Pgbouncer 管理数据库。更多连接池管理操作,请参考 Pgbouncer 管理 。
管理默认用户密码 要修改普通用户的密码, 按照上面 修改用户 的说明,更新配置中的 password 字段并执行剧本即可。
不过修改 默认用户 的密码会稍微复杂一些,因为它们的密码还在多个地方被其他服务引用。
要修改 pg_admin_password ,请执行以下命令:
# Step 1: 修改配置文件中的密码 pg_admin_password 后(重要!),通过剧本批量修改密码
./pgsql-user.yml -e username = dbuser_dba -e '{"pg_users":[{"name":"dbuser_dba","password":"NewPass123"}]}'
# Step 2: 更新所有 PG 节点的 patroni 配置文件与 .pgpass,然后重载 patroni 配置
./pgsql.yml -t pg_conf,pg_pass,patroni_reload -e pg_reload = true
# Step 3: 刷新 /infra/env/.pgpass 以及 /infra/conf/pg_service.conf 对管理员密码的引用
./infra.yml -t env_pgpass,env_pg_service
要修改 pg_monitor_password ,请执行以下命令:
# Step 1: 修改配置文件中的密码 pg_monitor_password 后(重要!),通过剧本批量修改密码
./pgsql-user.yml -e username = dbuser_monitor -e '{"pg_users":[{"name":"dbuser_monitor","password":"NewPass123"}]}'
# Step 2: 更新所有 PG 节点的 patroni 配置文件与 .pgpass,然后重载 patroni 配置
./pgsql.yml -t pg_conf,pg_pass,patroni_reload -e pg_reload = true
# Step 3: 刷新 pg_exporter 与 pgbouncer_exporter 配置里面使用的密码,更新 Grafana 监控面板中数据源使用的密码
./pgsql.yml -t pg_exporter,pgbouncer_exporter,add_ds
要修改 pg_replication_password ,请执行以下命令:
# Step 1: 修改配置文件中的密码 pg_replication_password 后(重要!),通过剧本批量修改密码
./pgsql-user.yml -e username = replicator -e '{"pg_users":[{"name":"replicator","password":"NewPass123"}]}'
# Step 2: 更新所有 PG 节点的 patorni 配置文件与 .pgpass,然后重载 patroni 配置
./pgsql.yml -t pg_conf,pg_pass,patroni_reload -e pg_reload = true
# Step 3: 更新 Infra 节点的 .pgpass
./infra.yml -t env_pgpass
此外,Patroni 本身 RestAPI 的密码 patroni_password 可以通过以下命令进行修改:
# Step 1: 刷新 patroni 配置文件里面配置的密码,并重载 patroni 配置应用生效
./pgsql.yml -t pg_conf,patroni_reload -e pg_reload = true
# Step 2: 刷新 /infra/conf/patronictl.yml 对 patroni 密码的引用
./infra.yml -t env_patroni
修改前三个密码前,需先用 SQL 修改对应 PostgreSQL 用户的密码:ALTER USER <username> PASSWORD '<new_password>';
12.6.3 - 管理 PostgreSQL 业务数据库 数据库管理:创建、修改、删除、重建数据库,使用模板克隆数据库
快速上手 Pigsty 使用声明式管理方式,首先在 配置清单 中 定义数据库 ,然后使用 bin/pgsql-db <cls> <dbname> 创建或修改数据库。
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta
pg_databases : [ { name : some_db }] # <--- 在这里定义数据库列表!
bin/pgsql-db <cls> <dbname> # 在 <cls> 集群上创建/修改 <dbname> 数据库
./pgsql-db.yml -l pg-meta -e dbname = some_db # 直接使用剧本在 <cls> 集群上创建/修改 <dbname> 数据库
bin/pgsql-db pg-meta some_db # 在 pg-meta 集群上创建/修改 some_db 数据库
关于数据库定义参数的完整参考,请查阅 数据库配置 。关于数据库的访问权限,请参考 ACL:数据库权限 。
请注意,部分数据库参数仅能在 创建时 指定。修改这些参数需要先删除再创建数据库(使用 state: recreate 重建数据库)。
操作 快捷命令 说明 创建数据库 bin/pgsql-db <cls> <db>创建新的业务数据库 修改数据库 bin/pgsql-db <cls> <db>修改已存在数据库的属性 删除数据库 bin/pgsql-db <cls> <db>删除数据库(需设置 state: absent) 重建数据库 bin/pgsql-db <cls> <db>先删再建(需设置 state: recreate) 克隆数据库 bin/pgsql-db <cls> <db>使用模板克隆数据库
创建数据库 定义在 pg_databases 里面的数据库会在 PostgreSQL 集群创建 的时候在 pg_db 任务中自动创建。
要在现有的 PostgreSQL 集群上创建新的业务数据库,请将 数据库定义 添加到 all.children.<cls>.pg_databases,然后执行:
bin/pgsql-db <cls> <dbname> # 创建数据库 <dbname>
./pgsql-db.yml -l <cls> -e dbname = <dbname> # 直接使用 Ansible 剧本创建数据库
bin/pgsql-db pg-meta myapp # 例子,在 pg-meta 集群中创建 myapp 数据库
示例配置:创建名为 myapp 的业务数据库
#all.children.pg-meta.vars.pg_databases: # 省略上级缩进
- name : myapp
owner : dbuser_myapp
schemas : [ app]
extensions :
- { name : pg_trgm }
- { name : btree_gin }
comment : my application database
执行效果 :在主库上创建数据库 myapp,设置数据库所有者为 dbuser_myapp,创建 schema app,
启用扩展 pg_trgm 和 btree_gin,数据库将默认添加到 Pgbouncer 连接池,并注册为 Grafana PG 数据源。
建议使用剧本创建数据库
如果您需要手工创建数据库,那么需要自行确保 pgbouncer 连接池 / grafana 数据源同步。
修改数据库 修改数据库与创建数据库使用相同的命令,在没有定义 baseline SQL 的情况下剧本是幂等的。
当目标数据库已存在时,Pigsty 会修改目标数据库的属性使其符合配置。然而,一些属性只能在数据库创建时设置。
bin/pgsql-db <cls> <db> # 修改数据库 <db> 的属性
./pgsql-db.yml -l <cls> -e dbname = <db> # 幂等操作,可重复执行
bin/pgsql-db pg-meta myapp # 修改 myapp 数据库的属性使其符合配置
不可修改的属性 :以下属性在数据库创建后无法修改,需要使用 state: recreate 重建数据库:
name(数据库名称)、template(模板数据库)、strategy(克隆策略)。encoding(字符编码)、locale/lc_collate/lc_ctype(本地化设置)、locale_provider/icu_locale/icu_rules/builtin_locale(本地化提供者设置)其他属性均可修改,以下是一些常见的修改示例:
修改属主 :更新配置中的 owner 字段后执行剧本,会执行 ALTER DATABASE ... OWNER TO 并授予相应权限。
- name : myapp
owner : dbuser_new_owner # 修改为新属主
修改连接限制 :通过 connlimit 限制数据库的最大连接数。
- name : myapp
connlimit : 100 # 限制最大 100 个连接
回收公共连接权限 :设置 revokeconn: true 会回收 PUBLIC 的 CONNECT 权限,仅允许属主、DBA、监控用户和复制用户连接。
- name : myapp
owner : dbuser_myapp
revokeconn : true # 回收 PUBLIC 的 CONNECT 权限
管理数据库参数 :通过 parameters 字典配置数据库级参数,会生成 ALTER DATABASE ... SET 语句。使用特殊值 DEFAULT 可将参数重置为默认值。
- name : myapp
parameters :
work_mem : '256MB'
maintenance_work_mem : '512MB'
statement_timeout : '30s'
search_path : DEFAULT # 重置为默认值
管理模式(Schema) :通过 schemas 数组配置模式,支持简单格式和指定属主的完整格式。使用 state: absent 删除模式(CASCADE)。
- name : myapp
schemas :
- app # 简单形式
- { name: core, owner : dbuser_myapp } # 指定属主
- { name: deprecated, state : absent } # 删除模式
管理扩展(Extension) :通过 extensions 数组配置扩展,支持简单格式和指定 schema/版本的完整格式。使用 state: absent 卸载扩展(CASCADE)。
- name : myapp
extensions :
- postgis # 简单形式
- { name: vector, schema : public } # 指定 schema
- { name: pg_trgm, state : absent } # 卸载扩展
CASCADE 警告
删除模式或卸载扩展使用 CASCADE 选项,会同时删除依赖该模式/扩展的所有对象。请确保理解影响范围后再执行删除操作。
连接池配置 :默认情况下所有业务数据库都会添加到 Pgbouncer 连接池。可配置 pgbouncer(是否加入连接池)、pool_mode(池化模式)、pool_size(默认池大小)、pool_reserve(保留连接数)、pool_size_min(最小池大小)、pool_connlimit(最大数据库连接)、pool_auth_user(认证查询用户)等参数。
- name : myapp
pgbouncer : true # 是否加入连接池(默认 true)
pool_mode : transaction # 池化模式:transaction/session/statement
pool_size : 64 # 默认池大小
pool_reserve : 32 # 保留池大小
pool_size_min : 0 # 最小池大小
pool_connlimit : 100 # 最大数据库连接
pool_auth_user : dbuser_meta # 认证查询使用用户(配合 pgbouncer_auth_query)
自 Pigsty v4.1.0 起,数据库连接池参数统一使用 pool_reserve 与 pool_connlimit,旧别名 pool_size_reserve / pool_max_db_conn 已收敛。
删除数据库 要删除数据库,将其 state 设置为 absent 并执行剧本:
bin/pgsql-db <cls> <db> # 删除数据库 <db>(需在配置中设置 state: absent)
./pgsql-db.yml -l <cls> -e dbname = <db> # 直接使用 Ansible 剧本删除数据库
bin/pgsql-db pg-meta olddb # 删除 olddb 数据库(配置中已设置 state: absent)
配置示例 :
pg_databases :
- name : olddb
state : absent
删除操作会 :如果数据库标记为 is_template: true,先执行 ALTER DATABASE ... IS_TEMPLATE false;使用 DROP DATABASE ... WITH (FORCE) 强制删除数据库(PG13+)并终止所有活动连接;从 Pgbouncer 连接池中移除该数据库;从 Grafana 数据源中取消注册。
保护机制 :系统数据库 postgres、template0、template1 无法删除。删除操作仅在主库上执行,流复制会自动同步到从库。
危险操作警告
删除数据库是不可逆 操作,会永久删除该数据库中的所有数据。执行前请确保:已有最新的数据库备份、已确认没有业务在使用该数据库、已通知相关干系人。
Pigsty 不对任何因删除数据库导致的数据丢失承担责任,使用需自担风险。
重建数据库 recreate 状态用于重建数据库,等效于先删除再创建:
bin/pgsql-db <cls> <db> # 重建数据库 <db>(需在配置中设置 state: recreate)
./pgsql-db.yml -l <cls> -e dbname = <db> # 直接使用 Ansible 剧本重建数据库
bin/pgsql-db pg-meta testdb # 重建 testdb 数据库(配置中已设置 state: recreate)
配置示例 :
pg_databases :
- name : testdb
state : recreate
owner : dbuser_test
baseline : test_init.sql # 重建后执行初始化
适用场景 :测试环境重置、清空开发数据库、修改不可变属性(编码、本地化等)、恢复数据库到初始状态。
与手动 DROP + CREATE 的区别 :单条命令完成,无需两次操作;自动保留 Pgbouncer 和 Grafana 配置;执行后自动加载 baseline 初始化脚本。
克隆数据库 你可以通过 PG 的 template 机制复制一个 PostgreSQL 数据库,在克隆期间,不允许有任何连接到模版数据库的活动连接。
bin/pgsql-db <cls> <db> # 克隆数据库 <db>(需在配置中指定 template)
./pgsql-db.yml -l <cls> -e dbname = <db> # 直接使用 Ansible 剧本克隆数据库
bin/pgsql-db pg-meta meta_dev # 克隆创建 meta_dev 数据库(配置中已指定 template: meta)
配置示例 :
pg_databases :
- name : meta # 源数据库
- name : meta_dev
template : meta # 以 meta 作为模板
strategy : FILE_COPY # PG15+ 克隆策略,PG18 瞬间生效
瞬间克隆(PG18+) :如果使用 PostgreSQL 18 以上版本,Pigsty 默认设置了 file_copy_method ,配合 strategy: FILE_COPY 可以在约 200ms 内完成数据库克隆,而不需要复制数据文件。例如克隆一个 30 GB 的数据库,普通克隆用时 18 秒,瞬间克隆仅需 200 毫秒。
手动克隆 :确保清理掉所有连接到模版数据库的连接后执行:
SELECT pg_terminate_backend ( pid ) FROM pg_stat_activity WHERE datname = 'meta' ;
CREATE DATABASE meta_dev TEMPLATE meta STRATEGY FILE_COPY ;
局限性与注意事项 :瞬间克隆仅在支持的文件系统上可用(xfs,brtfs,zfs,apfs);不要使用 postgres 数据库作为模版数据库进行克隆;在高并发环境中使用瞬间克隆需要谨慎,需在克隆窗口(200ms)内清理掉所有连接到模版数据库的连接。
连接池管理 在数据库定义中配置的 连接池参数 会在创建/修改数据库时应用到 Pgbouncer 连接池中。
默认情况下所有业务数据库都会添加到 Pgbouncer 连接池(pgbouncer: true)。数据库会被添加到 /etc/pgbouncer/database.txt 文件中,数据库级别的连接池参数(pool_auth_user、pool_mode、pool_size、pool_reserve、pool_size_min、pool_connlimit)通过此文件配置。
您可以使用 postgres 操作系统用户,使用 pgb 别名访问 Pgbouncer 管理数据库。更多连接池管理操作,请参考 Pgbouncer 管理 。
12.6.4 - 管理 Patroni 高可用 使用 Patroni 管理 PG 集群高可用,包括,修改参数,查看状态,主从切换,重启,重做从库等操作。
概览 Pigsty 使用 Patroni 管理 PostgreSQL 集群,它可以用来修改集群配置,查看集群状态,执行主从切换,重启集群,重做从库等操作。
要使用 Patroni 进行管理,您需要有以下两种身份之一:
Patroni 提供了 patronictl 命令行工具用于管理,Pigsty 提供了封装的快捷命令 pg 来简化其操作。
通过 pg 别名使用 patronictl pg ()
{
local patroni_conf = "/infra/conf/patronictl.yml" ;
if [ ! -r ${ patroni_conf } ] ; then
patroni_conf = "/etc/patroni/patroni.yml" ;
if [ ! -r ${ patroni_conf } ] ; then
echo "error: patronictl config not found" ;
return 1;
fi ;
fi ;
patronictl -c ${ patroni_conf } " $@ "
}
可用命令 修改配置 使用 edit-config 子命令可以交互式修改集群的 Patroni 与 PostgreSQL 配置。该命令会打开一个编辑器,让您修改存储在 DCS(分布式配置存储)中的集群配置,修改后会自动应用到所有集群成员。您可以更改 Patroni 本身的参数(如 ttl、loop_wait、synchronous_mode 等),以及 postgresql.parameters 中的 PostgreSQL 参数。
pg edit-config <cls> # 交互式编辑集群配置
pg edit-config <cls> --force # 跳过确认提示直接应用
pg edit-config <cls> -p <k>= <v> # 修改 PostgreSQL 参数(--pg 简写)
pg edit-config <cls> -s <k>= <v> # 修改 Patroni 参数(--set 简写)
以下是一些常见的配置修改示例:
# 修改 PostgreSQL 参数:慢查询阈值(会询问是否应用)
pg edit-config pg-test -p log_min_duration_statement = 1000
# 修改 PostgreSQL 参数并跳过确认
pg edit-config pg-test -p log_min_duration_statement = 1000 --force
# 修改多个 PostgreSQL 参数
pg edit-config pg-test -p work_mem = 256MB -p maintenance_work_mem = 1GB --force
# 修改 Patroni 参数:增大故障检测时间窗口(增大 RTO)
pg edit-config pg-test -s loop_wait = 15 -s ttl = 60 --force
# 修改 Patroni 参数:启用同步复制模式
pg edit-config pg-test -s synchronous_mode = true --force
# 修改 Patroni 参数:启用严格同步模式(至少一个同步从库才允许写入)
pg edit-config pg-test -s synchronous_mode_strict = true --force
# 修改需要重启的参数(修改后需执行 pg restart)
pg edit-config pg-test -p shared_buffers = 4GB --force
pg edit-config pg-test -p shared_preload_libraries = 'timescaledb, pg_stat_statements' --force
pg edit-config pg-test -p max_connections = 200 --force
部分参数修改后需要重启 PostgreSQL 才能生效,您可以使用 pg list 检查集群状态,带 * 标记的实例表示需要重启。然后使用 pg restart 命令重启集群使配置生效。
您也可以使用 curl 或编写程序直接调用 Patroni 提供的 REST API 来修改配置:
# 查看当前配置
curl -s 10.10.10.11:8008/config | jq .
# 通过 API 修改参数(需要认证)
curl -u 'postgres:Patroni.API' \
-d '{"postgresql":{"parameters": {"log_min_duration_statement":200}}}' \
-s -X PATCH http://10.10.10.11:8008/config | jq .
查看状态 使用 list 子命令可以查看集群成员及其状态。输出结果会显示每个实例的名称、主机地址、角色、运行状态、时间线和复制延迟等信息。这是日常运维中最常用的命令之一,用于快速了解集群的健康状况。
pg list <cls> # 查看指定集群的状态
pg list # 列出所有集群(需要在管理节点上执行)
pg list <cls> -e # 显示扩展信息(--extended)
pg list <cls> -t # 显示时间戳(--timestamp)
pg list <cls> -f json # 以 JSON 格式输出(--format)
pg list <cls> -W 5 # 每 5 秒刷新一次(--watch)
输出示例:
+ Cluster: pg-test (7322261897169354773) -----+----+--------------+
| Member | Host | Role | State | TL | Lag in MB |
+-----------+-------------+---------+---------+----+--------------+
| pg-test-1 | 10.10.10.11 | Leader | running | 1 | |
| pg-test-2 | 10.10.10.12 | Replica | running | 1 | 0 |
| pg-test-3 | 10.10.10.13 | Replica | running | 1 | 0 |
+-----------+-------------+---------+---------+----+--------------+
输出列说明:Member 是实例名称,由 pg_cluster-pg_seq 组成;Host 是实例所在主机的 IP 地址;Role 表示角色,包括 Leader(主库)、Replica(从库)、Sync Standby(同步从库)、Standby Leader(级联复制的级联主库)等;State 表示运行状态,常见值包括 running(正常运行)、streaming(流复制中)、in archive recovery(归档恢复中)、starting(启动中)、stopped(已停止)等;TL 是时间线编号(Timeline),每次主从切换后会递增;Lag in MB 是复制延迟,以 MB 为单位,主库不显示此值。
如果某个实例需要重启才能应用配置更改,实例名称后会显示 * 标记:
+ Cluster: pg-test (7322261897169354773) -------+----+--------------+
| Member | Host | Role | State | TL | Lag in MB |
+-------------+-------------+---------+---------+----+--------------+
| pg-test-1 * | 10.10.10.11 | Leader | running | 1 | |
| pg-test-2 * | 10.10.10.12 | Replica | running | 1 | 0 |
+-------------+-------------+---------+---------+----+--------------+
主动切换 使用 switchover 子命令可以执行计划内的主从切换。Switchover 是一种优雅的切换方式:Patroni 会先确保从库完全同步,然后让主库降级为从库,最后提升目标从库为新主库。这个过程通常只需要几秒钟,期间会有短暂的写入不可用。适用于主库所在主机需要维护、升级、或者需要将主库迁移到性能更好的节点等场景。
pg switchover <cls> # 交互式切换,会提示选择目标从库
pg switchover <cls> --leader <old> # 指定当前主库名称
pg switchover <cls> --candidate <new> # 指定目标从库名称
pg switchover <cls> --scheduled <time> # 定时切换,格式如 2024-12-01T03:00
pg switchover <cls> --force # 跳过确认提示
执行切换前请确保所有从库复制状态正常(状态为 running 或 streaming),复制延迟在可接受范围内,并已通知相关业务方。
# 交互式切换(推荐,会显示当前拓扑并提示选择)
$ pg switchover pg-test
Current cluster topology
+ Cluster: pg-test ( 7322261897169354773) -----+----+--------------+
| Member | Host | Role | State | TL | Lag in MB |
+-----------+-------------+---------+---------+----+--------------+
| pg-test-1 | 10.10.10.11 | Leader | running | 1 | |
| pg-test-2 | 10.10.10.12 | Replica | running | 1 | 0 |
| pg-test-3 | 10.10.10.13 | Replica | running | 1 | 0 |
+-----------+-------------+---------+---------+----+--------------+
Primary [ pg-test-1] :
Candidate [ 'pg-test-2' , 'pg-test-3' ] [] : pg-test-2
When should the switchover take place ( e.g. 2024-01-01T12:00) [ now] :
Are you sure you want to switchover cluster pg-test, demoting current leader pg-test-1? [ y/N] : y
# 非交互式切换(指定主库和候选从库)
pg switchover pg-test --leader pg-test-1 --candidate pg-test-2 --force
# 定时切换(在凌晨 3 点执行,适合维护窗口)
pg switchover pg-test --leader pg-test-1 --candidate pg-test-2 --scheduled "2024-12-01T03:00"
切换完成后,请使用 pg list 确认新的集群拓扑。
故障切换 使用 failover 子命令可以执行紧急故障切换。与 switchover 不同,failover 用于主库已经不可用的紧急情况。它会直接提升一个从库为新主库,而不等待原主库的确认。由于从库可能尚未完全同步所有数据,使用 failover 可能会导致少量数据丢失。因此,在非紧急情况下请优先使用 switchover。
pg failover <cls> # 交互式故障切换
pg failover <cls> --leader <old> # 指定原主库(用于验证,可选)
pg failover <cls> --candidate <new> # 指定要提升的从库
pg failover <cls> --force # 跳过确认提示
故障切换示例:
# 交互式故障切换
$ pg failover pg-test
Candidate [ 'pg-test-2' , 'pg-test-3' ] [] : pg-test-2
Are you sure you want to failover cluster pg-test? [ y/N] : y
Successfully failed over to "pg-test-2"
# 非交互式故障切换(紧急情况快速执行)
pg failover pg-test --candidate pg-test-2 --force
# 指定原主库进行验证(如果原主库名称不匹配会报错)
pg failover pg-test --leader pg-test-1 --candidate pg-test-2 --force
Switchover 与 Failover 的区别 :Switchover 用于计划内维护,要求原主库在线,执行前会确保数据完全同步,不会丢失数据;Failover 用于紧急故障恢复,原主库可以离线,会直接提升从库,可能丢失未同步的数据。日常维护、升级请使用 Switchover;只有在主库彻底故障无法恢复时才使用 Failover。
重启实例 使用 restart 子命令可以重启 PostgreSQL 实例,通常用于应用需要重启才能生效的参数更改。Patroni 会协调重启过程,对于整个集群的重启会采用滚动方式:先重启从库,最后重启主库,以最小化服务中断。
pg restart <cls> # 重启整个集群的所有实例
pg restart <cls> <member> # 重启指定实例
pg restart <cls> --role leader # 仅重启主库
pg restart <cls> --role replica # 仅重启所有从库
pg restart <cls> --pending # 仅重启标记为需要重启的实例
pg restart <cls> --scheduled <time> # 定时重启
pg restart <cls> --timeout <sec> # 设置重启超时时间(秒)
pg restart <cls> --force # 跳过确认提示
当您修改了需要重启才能生效的参数(如 shared_buffers、shared_preload_libraries、max_connections、max_worker_processes 等)后,需要使用此命令重启实例。
# 查看哪些实例需要重启(名称后带 * 标记)
$ pg list pg-test
+ Cluster: pg-test ( 7322261897169354773) -------+----+--------------+
| Member | Host | Role | State | TL | Lag in MB |
+-------------+-------------+---------+---------+----+--------------+
| pg-test-1 * | 10.10.10.11 | Leader | running | 1 | |
| pg-test-2 * | 10.10.10.12 | Replica | running | 1 | 0 |
+-------------+-------------+---------+---------+----+--------------+
# 重启单个从库实例
pg restart pg-test pg-test-2
# 重启整个集群(滚动重启,先从库后主库)
pg restart pg-test --force
# 仅重启需要重启的实例
pg restart pg-test --pending --force
# 仅重启所有从库
pg restart pg-test --role replica --force
# 定时重启(在维护窗口执行)
pg restart pg-test --scheduled "2024-12-01T03:00"
# 设置重启超时时间为 300 秒
pg restart pg-test --timeout 300 --force
重载配置 使用 reload 子命令可以重载 Patroni 配置,无需重启 PostgreSQL。该命令会让 Patroni 重新读取配置文件,并将不需要重启的参数变更应用到 PostgreSQL(通过 pg_reload_conf())。相比 restart,reload 更加轻量,不会中断数据库连接和正在执行的查询。
pg reload <cls> # 重载整个集群的配置
pg reload <cls> <member> # 重载指定实例的配置
pg reload <cls> --role leader # 仅重载主库
pg reload <cls> --role replica # 仅重载所有从库
pg reload <cls> --force # 跳过确认提示
大多数 PostgreSQL 参数可以通过 reload 生效,只有少数参数(位于 postmaster 上下文的参数,例如 shared_buffers、max_connections、shared_preload_libraries,archive_mode 等)需要重启 PostgreSQL 才能生效。
# 重载整个集群
pg reload pg-test
# 重载单个实例
pg reload pg-test pg-test-1
# 强制重载,跳过确认
pg reload pg-test --force
重做从库 使用 reinit 子命令可以重新初始化从库。该操作会删除从库上的所有数据,然后从主库重新执行 pg_basebackup 进行完整的数据复制。适用于从库数据损坏无法修复、从库落后太多导致 WAL 已被清理无法追赶、或从库配置错误需要重置等场景。
pg reinit <cls> <member> # 重新初始化指定从库
pg reinit <cls> <member> --force # 跳过确认提示
pg reinit <cls> <member> --wait # 等待重建完成后再返回
⚠️ 警告 :此操作会删除目标实例的所有数据!只能对从库执行,不能对主库执行。
# 重新初始化从库(会提示确认)
$ pg reinit pg-test pg-test-2
Are you sure you want to reinitialize members pg-test-2? [ y/N] : y
Success: reinitialize for member pg-test-2
# 强制重新初始化,跳过确认
pg reinit pg-test pg-test-2 --force
# 重新初始化并等待完成
pg reinit pg-test pg-test-2 --force --wait
重建过程中,可以使用 pg list 查看进度。从库状态会显示为 creating replica:
+ Cluster: pg-test (7322261897169354773) --------------+----+------+
| Member | Host | Role | State | TL | Lag |
+-----------+-------------+---------+------------------+----+------+
| pg-test-1 | 10.10.10.11 | Leader | running | 2 | |
| pg-test-2 | 10.10.10.12 | Replica | creating replica | | ? |
+-----------+-------------+---------+------------------+----+------+
暂停自动切换 使用 pause 子命令可以暂停 Patroni 的自动故障转移功能。暂停后,即使主库故障,Patroni 也不会自动提升从库为新主库。适用于计划内维护窗口(避免维护操作误触发切换)、调试问题时防止集群状态变化、或需要手动控制切换时机等场景。
pg pause <cls> # 暂停自动故障转移
pg pause <cls> --wait # 暂停并等待所有成员确认
⚠️ 警告 :暂停期间如果主库故障,集群将不会自动恢复!请确保在维护完成后及时使用 resume 恢复。
# 暂停自动切换
$ pg pause pg-test
Success: cluster management is paused
# 查看集群状态(底部会显示 Maintenance mode: on)
$ pg list pg-test
+ Cluster: pg-test ( 7322261897169354773) -----+----+--------------+
| Member | Host | Role | State | TL | Lag in MB |
+-----------+-------------+---------+---------+----+--------------+
| pg-test-1 | 10.10.10.11 | Leader | running | 1 | |
| pg-test-2 | 10.10.10.12 | Replica | running | 1 | 0 |
+-----------+-------------+---------+---------+----+--------------+
Maintenance mode: on
恢复自动切换 使用 resume 子命令可以恢复 Patroni 的自动故障转移功能。维护完成后应立即执行此命令,以确保集群在主库故障时能够自动恢复。
pg resume <cls> # 恢复自动故障转移
pg resume <cls> --wait # 恢复并等待所有成员确认
# 恢复自动切换
$ pg resume pg-test
Success: cluster management is resumed
# 确认已恢复(Maintenance mode 提示消失)
$ pg list pg-test
查看历史 使用 history 子命令可以查看集群的故障转移历史记录。每次主从切换(无论是自动故障转移还是手动切换)都会生成一条新的时间线记录。
pg history <cls> # 显示故障转移历史
pg history <cls> -f json # 以 JSON 格式输出
pg history <cls> -f yaml # 以 YAML 格式输出
$ pg history pg-test
+----+-----------+------------------------------+---------------------------+
| TL | LSN | Reason | Timestamp |
+----+-----------+------------------------------+---------------------------+
| 1 | 0/5000060 | no recovery target specified | 2024-01-15T10:30:00+08:00 |
| 2 | 0/6000000 | switchover to pg-test-2 | 2024-01-20T14:00:00+08:00 |
| 3 | 0/7000028 | failover to pg-test-1 | 2024-01-25T09:15:00+08:00 |
+----+-----------+------------------------------+---------------------------+
输出列说明:TL 是时间线编号(Timeline),每次切换后递增,用于区分不同的主库历史;LSN 是切换时的日志序列号(Log Sequence Number),标识切换发生时的 WAL 位置;Reason 是切换原因,可能是 switchover to xxx(手动切换)、failover to xxx(故障转移)或 no recovery target specified(初始化);Timestamp 是切换发生的时间戳。
显示配置 使用 show-config 子命令可以查看集群当前存储在 DCS 中的配置。这是一个只读操作,如需修改配置请使用 edit-config 命令。
pg show-config <cls> # 显示集群配置
$ pg show-config pg-test
loop_wait: 10
maximum_lag_on_failover: 1048576
postgresql:
parameters:
archive_command: pgbackrest --stanza= pg-test archive-push %p
max_connections: 100
shared_buffers: 256MB
log_min_duration_statement: 1000
use_pg_rewind: true
use_slots: true
retry_timeout: 10
ttl: 30
synchronous_mode: false
执行查询 使用 query 子命令可以在集群成员上快速执行 SQL 查询。这是一个方便的调试工具,适合快速检查集群状态或执行简单查询。生产环境中的复杂查询建议使用 psql 或应用程序连接。
pg query <cls> -c "<sql>" # 在主库上执行查询
pg query <cls> -c "<sql>" -m <member> # 在指定实例上执行(--member)
pg query <cls> -c "<sql>" -r leader # 在主库上执行(--role)
pg query <cls> -c "<sql>" -r replica # 在所有从库上执行
pg query <cls> -f <file> # 从文件读取 SQL 执行
pg query <cls> -c "<sql>" -U <user> # 指定用户名(--username)
pg query <cls> -c "<sql>" -d <db> # 指定数据库(--dbname)
pg query <cls> -c "<sql>" --format json # 以 JSON 格式输出
# 查看主库当前连接数
pg query pg-test -c "SELECT count(*) FROM pg_stat_activity"
# 查看 PostgreSQL 版本
pg query pg-test -c "SELECT version()"
# 在所有从库上查看复制状态
pg query pg-test -c "SELECT pg_is_in_recovery(), pg_last_wal_replay_lsn()" -r replica
# 在指定实例上执行
pg query pg-test -c "SELECT pg_is_in_recovery()" -m pg-test-2
# 使用指定用户和数据库
pg query pg-test -c "SELECT current_user, current_database()" -U postgres -d postgres
# 以 JSON 格式输出结果
pg query pg-test -c "SELECT * FROM pg_stat_replication" --format json
查看拓扑 使用 topology 子命令可以以树形结构查看集群的复制拓扑。与 list 相比,topology 更直观地展示了主从复制关系,特别适合级联复制(Cascading Replication)场景。
pg topology <cls> # 显示复制拓扑
$ pg topology pg-test
+ Cluster: pg-test ( 7322261897169354773) -------+----+--------------+
| Member | Host | Role | State | TL | Lag in MB |
+-------------+-------------+---------+---------+----+--------------+
| pg-test-1 | 10.10.10.11 | Leader | running | 1 | |
| + pg-test-2 | 10.10.10.12 | Replica | running | 1 | 0 |
| + pg-test-3 | 10.10.10.13 | Replica | running | 1 | 0 |
+-------------+-------------+---------+---------+----+--------------+
在级联复制场景中,拓扑图会清晰展示复制链路层级,例如 pg-test-3 从 pg-test-2 复制,而 pg-test-2 从主库 pg-test-1 复制。
查看版本 使用 version 子命令可以查看 patronictl 的版本信息。
pg version # 显示 patronictl 版本
$ pg version
patronictl version 4.1.0
移除成员 使用 remove 子命令可以从 DCS(分布式配置存储)中移除集群或成员的元数据。这是一个危险操作,仅移除 DCS 中的元数据,不会停止 PostgreSQL 服务或删除数据文件。错误使用可能导致集群状态不一致。
pg remove <cls> # 从 DCS 中移除整个集群的元数据
通常情况下您不需要使用此命令。如需正确移除集群或实例,请使用 Pigsty 提供的 bin/pgsql-rm 脚本或 pgsql-rm.yml 剧本。
只有在以下特殊情况下才考虑使用 remove:DCS 中存在孤立的元数据需要清理(例如节点已物理移除但元数据残留),或集群已通过其他方式销毁需要清理残留信息。
# 移除整个集群的元数据(需要多次确认)
$ pg remove pg-test
Please confirm the cluster name to remove: pg-test
You are about to remove all information in DCS for pg-test, please type: "Yes I am aware" : Yes I am aware
12.6.5 - Pgbouncer 连接池管理 使用 Pgbouncer 管理连接池,包括暂停、恢复、禁用、启用、重连、终止、重载等操作。
概览 Pigsty 使用 Pgbouncer 作为 PostgreSQL 的连接池中间件,默认监听 6432 端口,代理访问本机 5432 端口上的 PostgreSQL 实例。
这是一个 可选组件 ,如果您并没有海量链接,也不需要事务池化与查询监控指标,可以关闭连接池,直连数据库,或者保留但不使用。
用户与数据库管理 Pgbouncer 中的用户和数据库由 Pigsty 自动管理,并在 创建数据库 与 创建用户 时自动应用 数据库配置 与 用户配置 。
数据库管理 :在 pg_databases 中定义的数据库,默认会自动添加到 Pgbouncer。设置 pgbouncer: false 可以排除特定数据库。
pg_databases :
- name : mydb # 默认加入连接池
pool_auth_user : dbuser_meta # 可选,认证查询用户(配合 pgbouncer_auth_query)
pool_mode : transaction # 数据库级池化模式
pool_size : 64 # 默认池大小
pool_reserve : 32 # 保留池大小
pool_size_min : 0 # 最小池大小
pool_connlimit : 100 # 最大数据库连接数
- name : internal
pgbouncer : false # 不加入连接池
用户管理 :在 pg_users 中定义的用户,需要显式设置 pgbouncer: true 才会加入连接池用户列表。
pg_users :
- name : dbuser_app
password : DBUser.App
pgbouncer : true # 加入连接池用户列表
pool_mode : transaction # 用户级池化模式
pool_connlimit : 50 # 用户级最大连接数
自 Pigsty v4.1.0 起,数据库连接池参数统一使用 pool_reserve 与 pool_connlimit,旧别名 pool_size_reserve / pool_max_db_conn 已收敛。
服务管理 在 Pigsty 中,PostgreSQL 集群的 Primary 服务 与 Replica 服务默认指向 Pgbouncer 6432 端口,
如果您想要让这两个服务绕过连接池直接访问 PostgreSQL 实例,可以定制 pg_services ,或将将 pg_default_service_dest 设置为 postgres。
配置管理 Pgbouncer 的配置文件位于 /etc/pgbouncer/ 目录,由 Pigsty 统一生成与管理:
文件 说明 pgbouncer.ini主配置文件,连接池级别参数 database.txt数据库列表,数据库级别参数 userlist.txt用户密码列表 useropts.txt用户级别的连接池参数 pgb_hba.confHBA 访问控制规则
Pigsty 会自动管理 database.txt 和 userlist.txt,在 创建数据库 或 创建用户 时自动更新这些文件。
您也可以手动编辑配置文件后执行 RELOAD 使其生效:
# 编辑配置
$ vim /etc/pgbouncer/pgbouncer.ini
# 重载生效:通过 systemctl
$ sudo systemctl reload pgbouncer
# 重载生效,本身是 pg_dbsu / postgres 用户
$ pgb -c "RELOAD;"
连接池管理 Pgbouncer 使用和 PostgreSQL 相同的 dbsu 运行,默认为 postgres 操作系统用户。Pigsty 提供了快捷命令 pgb 来简化管理操作:
alias pgb = "psql -p 6432 -d pgbouncer -U postgres"
您可以在数据库节点上使用 pgb 命令连接到 Pgbouncer 管理控制台,执行管理命令和监控查询。
$ pgb
pgbouncer = # SHOW POOLS;
pgbouncer = # SHOW CLIENTS;
pgbouncer = # SHOW SERVERS;
PAUSE 使用 PAUSE 命令暂停数据库连接。Pgbouncer 会根据池化模式等待活动事务/会话完成后断开服务端连接。新的客户端请求会被阻塞直到执行 RESUME。
PAUSE [ db ]; -- 暂停指定数据库,不指定则暂停所有数据库
典型使用场景:
在线切换后端数据库(如主从切换后更新连接目标) 执行需要断开所有连接的维护操作 配合 SUSPEND 实现 Pgbouncer 在线重启 $ pgb -c "PAUSE mydb;" # 暂停 mydb 数据库
$ pgb -c "PAUSE;" # 暂停所有数据库
暂停后,SHOW DATABASES 会显示 paused 状态:
pgbouncer =# SHOW DATABASES ;
name | host | port | database | ... | paused | disabled
----------+-----------+------+----------+-----+--------+----------
mydb | / var / run | 5432 | mydb | ... | 1 | 0
RESUME 使用 RESUME 命令恢复被 PAUSE、KILL 或 SUSPEND 暂停的数据库,允许新的连接请求并恢复正常服务。
RESUME [ db ]; -- 恢复指定数据库,不指定则恢复所有数据库
$ pgb -c "RESUME mydb;" # 恢复 mydb 数据库
$ pgb -c "RESUME;" # 恢复所有数据库
DISABLE 使用 DISABLE 命令禁用指定数据库,拒绝所有新的客户端连接请求。已存在的连接不受影响。
DISABLE db ; -- 禁用指定数据库(必须指定数据库名)
典型使用场景:
临时下线某个数据库进行维护 阻止新连接以便安全地进行数据库迁移 逐步下线即将删除的数据库 $ pgb -c "DISABLE mydb;" # 禁用 mydb,新连接被拒绝
ENABLE 使用 ENABLE 命令启用之前被 DISABLE 禁用的数据库,重新接受新的客户端连接。
ENABLE db ; -- 启用指定数据库(必须指定数据库名)
$ pgb -c "ENABLE mydb;" # 启用 mydb,允许新连接
RECONNECT 使用 RECONNECT 命令优雅地重建服务端连接。Pgbouncer 会在连接释放回池后关闭它们,并在需要时建立新连接。
RECONNECT [ db ]; -- 重建指定数据库的服务端连接,不指定则重建所有
典型使用场景:
后端数据库 IP 地址变更后刷新连接 主从切换后重新路由流量 DNS 更新后重建连接 $ pgb -c "RECONNECT mydb;" # 重建 mydb 的服务端连接
$ pgb -c "RECONNECT;" # 重建所有服务端连接
执行 RECONNECT 后,可以使用 WAIT_CLOSE 等待旧连接完全释放。
KILL 使用 KILL 命令立即断开指定数据库的所有客户端和服务端连接。与 PAUSE 不同,KILL 不等待事务完成,直接强制断开。
KILL [ db ]; -- 终止指定数据库的所有连接,不指定则终止所有(admin 除外)
$ pgb -c "KILL mydb;" # 强制断开 mydb 的所有连接
$ pgb -c "KILL;" # 强制断开所有数据库的连接(admin 除外)
执行 KILL 后,新连接会被阻塞直到执行 RESUME。
KILL_CLIENT 使用 KILL_CLIENT 命令终止指定的客户端连接。客户端 ID 可以从 SHOW CLIENTS 输出中获取。
KILL_CLIENT id ; -- 终止指定 ID 的客户端连接
# 查看客户端连接
$ pgb -c "SHOW CLIENTS;"
# 终止特定客户端(假设 ptr 列显示的 ID 为 0x1234567890)
$ pgb -c "KILL_CLIENT 0x1234567890;"
SUSPEND 使用 SUSPEND 命令挂起 Pgbouncer。Pgbouncer 会刷新所有 socket 缓冲区并停止监听数据,直到执行 RESUME。
SUSPEND 主要用于实现 Pgbouncer 的在线重启(零停机升级):
# 1. 挂起当前 Pgbouncer
$ pgb -c "SUSPEND;"
# 2. 启动新的 Pgbouncer 进程(使用 -R 选项接管 socket)
$ pgbouncer -R /etc/pgbouncer/pgbouncer.ini
# 3. 新进程接管后,旧进程自动退出
SHUTDOWN 使用 SHUTDOWN 命令关闭 Pgbouncer 进程。支持多种关闭模式:
SHUTDOWN ; -- 立即关闭
SHUTDOWN WAIT_FOR_SERVERS ; -- 等待服务端连接释放后关闭
SHUTDOWN WAIT_FOR_CLIENTS ; -- 等待客户端断开后关闭(零停机滚动重启)
模式 说明 SHUTDOWN立即关闭 Pgbouncer 进程 WAIT_FOR_SERVERS停止接受新连接,等待服务端连接释放后退出 WAIT_FOR_CLIENTS停止接受新连接,等待所有客户端断开后退出,适用于滚动重启
$ pgb -c "SHUTDOWN WAIT_FOR_CLIENTS;" # 优雅关闭,等待客户端断开
RELOAD 使用 RELOAD 命令重新加载 Pgbouncer 配置文件。可以动态更新大部分配置参数,无需重启进程。
$ pgb -c "RELOAD;" # 通过管理控制台重载
$ systemctl reload pgbouncer # 通过 systemd 重载
$ kill -SIGHUP $( cat /var/run/pgbouncer/pgbouncer.pid) # 通过信号重载
Pigsty 提供了重载 Pgbouncer 配置的剧本任务:
./pgsql.yml -l <cls> -t pgbouncer_reload # 重载集群的 Pgbouncer 配置
WAIT_CLOSE 使用 WAIT_CLOSE 命令等待服务端连接完成关闭。通常在 RECONNECT 或 RELOAD 后使用,确保旧连接已全部释放。
WAIT_CLOSE [ db ]; -- 等待指定数据库的服务端连接关闭,不指定则等待所有
# 完整的连接重建流程
$ pgb -c "RECONNECT mydb;"
$ pgb -c "WAIT_CLOSE mydb;" # 等待旧连接释放
监控命令 Pgbouncer 提供了丰富的 SHOW 命令用于监控连接池状态:
命令 说明 SHOW HELP显示可用命令帮助 SHOW DATABASES显示数据库配置和状态 SHOW POOLS显示连接池统计信息 SHOW CLIENTS显示客户端连接列表 SHOW SERVERS显示服务端连接列表 SHOW USERS显示用户配置 SHOW STATS显示统计信息(请求数、字节数等) SHOW STATS_TOTALS显示累计统计信息 SHOW STATS_AVERAGES显示平均统计信息 SHOW CONFIG显示当前配置参数 SHOW MEM显示内存使用情况 SHOW DNS_HOSTS显示 DNS 缓存的主机名 SHOW DNS_ZONES显示 DNS 缓存的区域 SHOW SOCKETS显示打开的 socket 信息 SHOW ACTIVE_SOCKETS显示活动的 socket SHOW LISTS显示内部列表计数 SHOW FDS显示文件描述符使用情况 SHOW STATE显示 Pgbouncer 运行状态 SHOW VERSION显示 Pgbouncer 版本
常用监控示例:
# 查看连接池状态
$ pgb -c "SHOW POOLS;"
# 查看客户端连接
$ pgb -c "SHOW CLIENTS;"
# 查看服务端连接
$ pgb -c "SHOW SERVERS;"
# 查看统计信息
$ pgb -c "SHOW STATS;"
# 查看数据库状态
$ pgb -c "SHOW DATABASES;"
更多监控命令的详细说明,请参考 Pgbouncer 官方文档 。
Unix 信号 Pgbouncer 支持通过 Unix 信号进行控制,这在无法连接管理控制台时非常有用:
信号 等效命令 说明 SIGHUPRELOAD重载配置文件 SIGTERMSHUTDOWN WAIT_FOR_CLIENTS优雅关闭,等待客户端断开 SIGINTSHUTDOWN WAIT_FOR_SERVERS优雅关闭,等待服务端释放 SIGQUITSHUTDOWN立即关闭 SIGUSR1PAUSE暂停所有数据库 SIGUSR2RESUME恢复所有数据库
# 通过信号重载配置
$ kill -SIGHUP $( cat /var/run/pgbouncer/pgbouncer.pid)
# 通过信号优雅关闭
$ kill -SIGTERM $( cat /var/run/pgbouncer/pgbouncer.pid)
# 通过信号暂停
$ kill -SIGUSR1 $( cat /var/run/pgbouncer/pgbouncer.pid)
# 通过信号恢复
$ kill -SIGUSR2 $( cat /var/run/pgbouncer/pgbouncer.pid)
流量切换 Pigsty 提供了 pgb-route 实用函数,可以将 Pgbouncer 流量快速切换至其他节点,用于零停机迁移:
# 定义(已在 /etc/profile.d/pg-alias.sh 中)
function pgb-route(){
local ip = ${ 1 - '\/var\/run\/postgresql' }
sed -ie "s/host=[^[:space:]]\+/host= ${ ip } /g" /etc/pgbouncer/pgbouncer.ini
cat /etc/pgbouncer/pgbouncer.ini
}
# 使用:将流量路由到 10.10.10.12
$ pgb-route 10.10.10.12
$ pgb -c "RECONNECT; WAIT_CLOSE;"
完整的零停机切换流程:
# 1. 修改路由目标
$ pgb-route 10.10.10.12
# 2. 重载配置
$ pgb -c "RELOAD;"
# 3. 重建连接并等待旧连接释放
$ pgb -c "RECONNECT;"
$ pgb -c "WAIT_CLOSE;"
12.6.6 - 管理 PostgreSQL 组件服务 使用 systemctl 管理 PostgreSQL 集群中的各个组件服务:启动、停止、重启、重载与状态检查。
概述 Pigsty 的 PGSQL 模块由多个组件构成,每个组件都以 systemd 服务的形式运行在节点上。(pgbackrest 除外)
了解这些组件及其管理方式,对于维护生产环境中的 PostgreSQL 集群非常重要。
组件 端口 服务名 说明 Patroni 8008patroni高可用管理器,负责 PostgreSQL 的生命周期管理 PostgreSQL 5432postgres占位服务,默认不使用,应急使用 Pgbouncer 6432pgbouncer连接池中间件,业务流量入口 PgBackRest - - pgBackRest 没有守护服务 HAProxy 543xhaproxy负载均衡器,暴露数据库服务 pg_exporter 9630pg_exporterPostgreSQL 监控指标导出器 pgbouncer_exporter 9631pgbouncer_exporterPgbouncer 监控指标导出器 vip-manager - vip-manager可选,管理 L2 VIP 地址漂移
重要提示
不要直接使用 systemctl 管理 PostgreSQL 服务 。PostgreSQL 由 Patroni 托管,应通过 patronictl 命令进行管理。
直接操作 PostgreSQL 可能导致 Patroni 状态不一致,触发意外的故障转移。postgres 服务是 Patroni 服务失效时的应急逃生窗口。
命令速查 操作 命令 启动服务 systemctl start <service>停止服务 systemctl stop <service>重启服务 systemctl restart <service>重载配置 systemctl reload <service>查看状态 systemctl status <service>查看日志 journalctl -u <service> -f开机启动 systemctl enable <service>禁用启动 systemctl disable <service>
常用组件服务名:patroni、pgbouncer、haproxy、pg_exporter、pgbouncer_exporter、vip-manager
Patroni Patroni 是 PostgreSQL 的高可用管理器,负责 PostgreSQL 的启动、停止、故障检测与自动故障转移。
它是 PGSQL 模块的核心组件,PostgreSQL 进程由 Patroni 托管,不应直接通过 systemctl 管理 postgres 服务。
启动 Patroni
systemctl start patroni # 启动 Patroni(同时启动 PostgreSQL)
启动 Patroni 后,它会自动拉起 PostgreSQL 进程。首次启动时,Patroni 会根据角色决定行为:
主库:初始化或恢复数据目录 从库:从主库克隆数据并建立复制 停止 Patroni
systemctl stop patroni # 停止 Patroni(同时停止 PostgreSQL)
停止 Patroni 时,它会优雅地关闭 PostgreSQL 进程。注意:如果这是主库,且未暂停自动切换,可能触发故障转移。
重启 Patroni
systemctl restart patroni # 重启 Patroni(同时重启 PostgreSQL)
重启会导致短暂的服务中断。对于生产环境,建议使用 pg restart 命令进行滚动重启。
重载 Patroni
systemctl reload patroni # 重载 Patroni 配置
重载会让 Patroni 重新读取配置文件,并将可热加载的参数应用到 PostgreSQL。
查看状态与日志
systemctl status patroni # 查看 Patroni 服务状态
journalctl -u patroni -f # 实时查看 Patroni 日志
journalctl -u patroni -n 100 --no-pager # 查看最近 100 行日志
配置文件位置 :/etc/patroni/patroni.yml
最佳实践 :使用 patronictl 而非 systemctl 管理 PostgreSQL 集群。
Pgbouncer Pgbouncer 是轻量级的 PostgreSQL 连接池中间件。
业务流量通常通过 Pgbouncer(6432 端口)而非直接连接 PostgreSQL(5432 端口),以实现连接复用和保护数据库。
启动 Pgbouncer
systemctl start pgbouncer
停止 Pgbouncer
注意:停止 Pgbouncer 会中断所有通过连接池的业务连接。
重启 Pgbouncer
systemctl restart pgbouncer
重启会断开所有现有连接。如果只是配置变更,建议使用 reload。
重载 Pgbouncer
systemctl reload pgbouncer
重载会重新读取配置文件(用户列表、连接池参数等),不会断开现有连接。
查看状态与日志
systemctl status pgbouncer
journalctl -u pgbouncer -f
配置文件位置 :
主配置:/etc/pgbouncer/pgbouncer.ini HBA 规则:/etc/pgbouncer/pgb_hba.conf 用户列表:/etc/pgbouncer/userlist.txt 数据库列表:/etc/pgbouncer/database.txt 管理控制台
psql -p 6432 -U postgres -d pgbouncer # 连接到 Pgbouncer 管理控制台
常用管理命令:
SHOW POOLS ; -- 查看连接池状态
SHOW CLIENTS ; -- 查看客户端连接
SHOW SERVERS ; -- 查看后端服务器连接
SHOW STATS ; -- 查看统计信息
RELOAD ; -- 重载配置
PAUSE ; -- 暂停所有连接池
RESUME ; -- 恢复所有连接池
HAProxy HAProxy 是高性能的负载均衡器,负责将流量分发到正确的 PostgreSQL 实例。
Pigsty 使用 HAProxy 暴露 服务 ,根据角色(主库/从库)和健康状态进行流量调度。
启动 HAProxy
停止 HAProxy
注意:停止 HAProxy 会中断所有通过负载均衡器的连接。
重启 HAProxy
systemctl restart haproxy
重载 HAProxy
HAProxy 支持优雅重载,不会断开现有连接。配置变更后推荐使用 reload。
查看状态与日志
systemctl status haproxy
journalctl -u haproxy -f
配置文件位置 :/etc/haproxy/haproxy.cfg
管理界面
HAProxy 提供 Web 管理界面,默认监听在 9101 端口:
http://<node_ip>:9101/haproxy
默认认证:用户名 admin,密码由 haproxy_admin_password 配置。
pg_exporter pg_exporter 是 PostgreSQL 的 Prometheus 监控指标导出器,负责采集数据库性能指标。
启动 pg_exporter
systemctl start pg_exporter
停止 pg_exporter
systemctl stop pg_exporter
停止后,Prometheus 将无法采集该实例的 PostgreSQL 监控指标。
重启 pg_exporter
systemctl restart pg_exporter
查看状态与日志
systemctl status pg_exporter
journalctl -u pg_exporter -f
配置文件位置 :/etc/pg_exporter.yml
验证指标采集
curl -s localhost:9630/metrics | head -20
pgbouncer_exporter pgbouncer_exporter 是 Pgbouncer 的 Prometheus 监控指标导出器。
启动/停止/重启
systemctl start pgbouncer_exporter
systemctl stop pgbouncer_exporter
systemctl restart pgbouncer_exporter
查看状态与日志
systemctl status pgbouncer_exporter
journalctl -u pgbouncer_exporter -f
验证指标采集
curl -s localhost:9631/metrics | head -20
vip-manager vip-manager 是可选组件,用于管理 L2 VIP 地址漂移。
当启用 pg_vip_enabled 时,vip-manager 会将 VIP 绑定到当前主库节点。
启动 vip-manager
systemctl start vip-manager
停止 vip-manager
systemctl stop vip-manager
停止后,VIP 地址会从当前节点释放。
重启 vip-manager
systemctl restart vip-manager
查看状态与日志
systemctl status vip-manager
journalctl -u vip-manager -f
配置文件位置 :/etc/default/vip-manager
验证 VIP 绑定
ip addr show # 查看网络接口,检查 VIP 是否绑定
pg list <cls> # 确认主库位置
启动顺序与依赖 PGSQL 模块组件的推荐启动顺序:
1. patroni # 首先启动 Patroni(会自动启动 PostgreSQL)
2. pgbouncer # 然后启动连接池
3. haproxy # 启动负载均衡器
4. pg_exporter # 启动监控导出器
5. pgbouncer_exporter
6. vip-manager # 最后启动 VIP 管理器(如果启用)
停止顺序应相反。Pigsty 剧本会自动处理这些依赖关系。
批量启动所有服务
systemctl start patroni pgbouncer haproxy pg_exporter pgbouncer_exporter
批量停止所有服务
systemctl stop pgbouncer_exporter pg_exporter haproxy pgbouncer patroni
常见故障排查 服务启动失败
systemctl status <service> # 查看服务状态
journalctl -u <service> -n 50 # 查看最近日志
journalctl -u <service> --since "5 min ago" # 查看最近 5 分钟日志
Patroni 无法启动
现象 可能原因 解决方案 无法连接 etcd etcd 集群不可用 检查 etcd 服务状态 数据目录权限错误 文件所有权不是 postgres chown -R postgres:postgres /pg/data端口被占用 PostgreSQL 残留进程 pg_ctl stop -D /pg/data 或 kill
Pgbouncer 无法启动
现象 可能原因 解决方案 配置文件语法错误 INI 格式错误 检查 /etc/pgbouncer/pgbouncer.ini 端口被占用 6432 端口已被使用 lsof -i :6432userlist.txt 权限 文件权限不正确 chmod 600 /etc/pgbouncer/userlist.txt
HAProxy 无法启动
现象 可能原因 解决方案 配置文件语法错误 haproxy.cfg 格式错误 haproxy -c -f /etc/haproxy/haproxy.cfg端口被占用 服务端口冲突 lsof -i :5433
相关文档 12.6.7 - 管理 PostgreSQL 定时任务 配置 Crontab 定期调度 PostgreSQL 备份任务,执行备份 / Vacuum Freeze / Analyze 任务,以及处理表膨胀
Pigsty 使用 crontab 来管理定时任务,用于执行例行备份,冻结老化事务,重整膨胀表索引等维护工作。
速查手册 操作 快捷命令 说明 配置定时任务 ./pgsql.yml -t pg_crontab -l <cls>应用 pg_crontab 配置 查看定时任务 crontab -l以 postgres 用户查看 物理备份 pg-backup [full|diff|incr]使用 pgBackRest 执行备份 事务冻结 pg-vacuum [database...]冻结老化事务,预防 XID 回卷 膨胀治理 pg-repack [database...]在线重整膨胀的表与索引
其他管理任务,请参考:备份管理 ,监控系统 ,高可用管理 。
配置定时任务 使用 pg_crontab 参数配置 PostgreSQL 数据库超级用户(pg_dbsu ,默认 postgres)的定时任务。
下面 pg-meta 集群配置了每天凌晨1点进行全量备份的定时任务,pg-test 配置了每周一全量备份,其余日期增量备份的定时任务。
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta
pg_crontab :
- '00 01 * * * /pg/bin/pg-backup'
pg-test :
hosts :
10.10.10.11 : { pg_seq: 1, pg_role : primary }
10.10.10.12 : { pg_seq: 2, pg_role : replica }
vars :
pg_cluster : pg-test
pg_crontab :
- '00 01 * * 1 /pg/bin/pg-backup full'
- '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup'
推荐的维护计划
pg_crontab :
- '00 01 * * * /pg/bin/pg-backup full' # 每天凌晨1点全量备份
- '00 03 * * 0 /pg/bin/pg-vacuum' # 每周日凌晨3点执行 vacuum freeze
- '00 04 * * 1 /pg/bin/pg-repack' # 每周一凌晨4点执行 repack
任务 频率 时机 说明 pg-backup每天 凌晨 全量或增量备份,视业务需求而定 pg-vacuum每周一次 周日凌晨 冻结老化事务,预防 XID 回卷 pg-repack每周/每月 业务低峰期 重整膨胀表索引,回收空间
仅在主库执行
pg-backup、pg-vacuum、pg-repack 脚本会自动检测当前节点角色,只有主库才会实际执行,从库会直接退出。
因此可以安全地在所有节点配置相同的定时任务,故障切换后新主库会自动继续执行维护任务。
应用定时任务 定时任务会在 pgsql.yml 剧本执行时(pg_crontab 任务)自动写入对应操作系统发行版的默认位置:
EL(RHEL/Rocky/Alma):/var/spool/cron/postgres Debian/Ubuntu:/var/spool/cron/crontabs/postgres ./pgsql.yml -l pg-meta -t pg_crontab # 应用 pg_crontab 配置到指定集群
./pgsql.yml -l 10.10.10.10 -t pg_crontab # 仅针对特定主机
# 以 postgres 用户编辑定时任务
sudo -u postgres crontab -e
# 或直接编辑 crontab 文件
sudo vi /var/spool/cron/postgres # EL 系列
sudo vi /var/spool/cron/crontabs/postgres # Debian/Ubuntu
每次执行剧本都会 全量覆盖刷新 定时任务配置。
查看定时任务 使用 pg_dbsu 操作系统用户执行以下命令查看定时任务:
crontab -l
# Pigsty Managed Crontab for postgres
SHELL = /bin/bash
PATH = /usr/pgsql/bin:/pg/bin:/usr/local/bin:/usr/bin:/usr/sbin:/bin:/sbin
MAILTO = ""
00 01 * * * /pg/bin/pg-backup
如果您不熟悉 Crontab 的语法,可以参考 Crontab Guru 的解释。
pg-backup pg-backup 是 Pigsty 提供的物理备份脚本,基于 pgBackRest 实现,支持全量、差异、增量三种备份模式。
基本用法
pg-backup # 执行增量备份(默认),如果没有全量备份则自动执行全量备份
pg-backup full # 执行全量备份
pg-backup diff # 执行差异备份(基于最近的全量备份)
pg-backup incr # 执行增量备份(基于最近的任意备份)
备份类型说明
类型 参数 说明 全量备份 full完整备份所有数据,恢复时只需要该备份 差异备份 diff备份自上次全量备份以来的变更,恢复时需要全量+差异 增量备份 incr备份自上次任意备份以来的变更,恢复时需要完整链路
执行条件
脚本必须在 主库 上以 postgres 用户身份运行 脚本会自动检测当前节点角色,从库执行时会直接退出(exit 1) 从 /etc/pgbackrest/pgbackrest.conf 中自动获取 stanza 名称 常用定时任务配置
pg_crontab :
- '00 01 * * * /pg/bin/pg-backup full' # 每天凌晨1点全量备份
pg_crontab :
- '00 01 * * 1 /pg/bin/pg-backup full' # 周一全量备份
- '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup' # 其他日期增量备份
pg_crontab :
- '00 01 * * 1 /pg/bin/pg-backup full' # 周一全量备份
- '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup diff' # 其他日期差异备份
更多备份恢复操作,请参考 备份管理 章节。
pg-vacuum pg-vacuum 是 Pigsty 提供的事务冻结脚本,用于执行 VACUUM FREEZE 操作,防止事务 ID(XID)回卷导致数据库停机。
基本用法
pg-vacuum # 冻结所有数据库中的老化表
pg-vacuum mydb # 仅处理指定数据库
pg-vacuum -n mydb # 空跑模式,只显示不执行
pg-vacuum -a 80000000 mydb # 使用自定义年龄阈值(默认1亿)
pg-vacuum -r 50 mydb # 使用自定义老化比例阈值(默认40%)
-- 对整个数据库执行 VACUUM FREEZE
VACUUM FREEZE ;
-- 对特定表执行 VACUUM FREEZE
VACUUM FREEZE schema . table_name ;
命令选项
选项 说明 默认值 -h, --help显示帮助信息 - -n, --dry-run空跑模式,只显示不执行 false -a, --age年龄阈值,超过此值的表需要冻结 100000000 -r, --ratio老化比例阈值,超过则全库冻结(%) 40
工作逻辑
检查数据库的 datfrozenxid 年龄,如果低于阈值则跳过该库 计算老化页面比例(超过年龄阈值的表页面占总页面的百分比) 如果老化比例 > 40%,执行全库 VACUUM FREEZE ANALYZE 否则,仅对超过年龄阈值的表执行 VACUUM FREEZE ANALYZE 脚本会设置 vacuum_cost_limit = 10000 和 vacuum_cost_delay = 1ms 以控制 I/O 影响。
执行条件
脚本必须在 主库 上以 pg_dbsu postgres 用户身份运行 使用文件锁 /tmp/pg-vacuum.lock 防止并发执行 自动跳过 template0、template1、postgres 系统数据库 常用定时任务配置
建议将 vacuum 任务与备份/Repack 任务分开执行,避免冲突。
pg_crontab :
- '00 03 * * 0 /pg/bin/pg-vacuum' # 每周日凌晨3点执行
pg-repack pg-repack 是 Pigsty 提供的膨胀治理脚本,基于 pg_repack 扩展实现,用于在线重整膨胀的表与索引。
基本用法
pg-repack # 重整所有数据库中的膨胀表与索引
pg-repack mydb # 仅重整指定数据库
pg-repack mydb1 mydb2 # 重整多个数据库
pg-repack -n mydb # 空跑模式,只显示不执行
pg-repack -t mydb # 仅重整表
pg-repack -i mydb # 仅重整索引
pg-repack -T 30 -j 4 mydb # 自定义锁超时(秒)和并行度
# 直接使用 pg_repack 命令重整特定表
pg_repack dbname -t schema.table
# 直接使用 pg_repack 命令重整特定索引
pg_repack dbname -i schema.index
命令选项
选项 说明 默认值 -h, --help显示帮助信息 - -n, --dry-run空跑模式,只显示不执行 false -t, --table仅重整表 false -i, --index仅重整索引 false -T, --timeout锁等待超时时间(秒) 10 -j, --jobs并行作业数 2
自动选择阈值
脚本会根据表和索引的大小与膨胀率,自动选择需要重整的对象:
表膨胀阈值
大小范围 膨胀率阈值 最大数量 < 256MB > 40% 64 256MB - 2GB > 30% 16 2GB - 8GB > 20% 4 8GB - 64GB > 15% 1
索引膨胀阈值
大小范围 膨胀率阈值 最大数量 < 128MB > 40% 64 128MB - 1GB > 35% 16 1GB - 8GB > 30% 4 8GB - 64GB > 20% 1
超过 64GB 的巨型表/索引会被跳过并给出提示,需要手动处理。
执行条件
脚本必须在 主库 上以 postgres 用户身份运行 需要安装 pg_repack 扩展(Pigsty 默认安装) 需要 monitor schema 中的 pg_table_bloat 和 pg_index_bloat 视图 使用文件锁 /tmp/pg-repack.lock 防止并发执行 自动跳过 template0、template1、postgres 系统数据库 锁等待
重整期间不会影响正常读写,但重整完毕的 切换瞬间 需要获取表上的 AccessExclusive 锁阻塞一切访问。对于高吞吐量业务,建议在业务低峰期或维护窗口进行。
常用定时任务配置
pg_crontab :
- '00 04 * * 1 /pg/bin/pg-repack' # 每周一凌晨4点执行
您可以通过 Pigsty 的 PGCAT Database - Table Bloat 面板确认数据库中的膨胀情况,并选择膨胀率较高的表与索引进行重整。
更多细节请参考:关系膨胀的治理
移除定时任务 当使用 pgsql-rm.yml 剧本移除 PostgreSQL 集群时,会自动删除 postgres 用户的 crontab 文件。
./pgsql-rm.yml -l <cls> -t pg_crontab # 仅移除定时任务
./pgsql-rm.yml -l <cls> # 移除整个集群(包含定时任务)
相关文档 12.6.8 - 升级 PostgreSQL 大小版本 版本升级:小版本滚动升级、大版本迁移、扩展升级
快速上手 PostgreSQL 版本升级分为两种类型:小版本升级 和 大版本升级 ,两者的风险和复杂度差异很大。
类型 示例 停机时间 数据兼容性 风险等级 小版本升级 17.2 → 17.3 秒级(滚动重启) 完全兼容 低 大版本升级 17 → 18 分钟级 需要升级数据目录 中
# 滚动升级:先从库后主库
ansible <cls> -b -a 'yum upgrade -y postgresql17*'
pg restart --role replica --force <cls>
pg switchover <cls>
pg restart <cls> <old-primary> --force
# 推荐:逻辑复制迁移
bin/pgsql-add pg-new # 创建新版本集群
# 配置逻辑复制同步数据...
# 切换流量到新集群
ansible <cls> -b -a 'yum upgrade -y postgis36_17*'
psql -c 'ALTER EXTENSION postgis UPDATE;'
关于在线迁移的详细流程,请参考 在线迁移 文档。
小版本升级 小版本升级(如 17.2 → 17.3)是最常见的升级场景,通常用于应用安全补丁和 Bug 修复。数据目录完全兼容,通过滚动重启即可完成。
升级策略 :推荐采用 滚动升级 方式:先升级从库,再通过主从切换升级原主库,最小化服务中断。
1. 更新软件仓库 → 2. 升级从库软件包 → 3. 重启从库
4. 主从切换 → 5. 升级原主库软件包 → 6. 重启原主库
步骤一:准备软件包
确保本地软件仓库中有最新版本的 PostgreSQL 包,并刷新节点缓存:
cd ~/pigsty
./infra.yml -t repo_upstream # 添加上游仓库(需要互联网)
./infra.yml -t repo_build # 重建本地仓库
ansible <cls> -b -a 'yum clean all'
ansible <cls> -b -a 'yum makecache'
ansible <cls> -b -a 'apt clean'
ansible <cls> -b -a 'apt update'
步骤二:升级从库
在所有从库上升级软件包并验证版本:
ansible <cls> -b -a 'yum upgrade -y postgresql17*'
ansible <cls> -b -a '/usr/pgsql/bin/pg_ctl --version'
ansible <cls> -b -a 'apt install -y postgresql-17'
ansible <cls> -b -a '/usr/lib/postgresql/17/bin/pg_ctl --version'
重启所有从库以应用新版本:
pg restart --role replica --force <cls>
步骤三:切换主库
执行主从切换,将主库角色转移到已升级的从库:
pg switchover <cls>
# 或非交互式:
pg switchover --leader <old-primary> --candidate <new-primary> --scheduled= now --force <cls>
步骤四:升级原主库
原主库现在已降级为从库,升级软件包并重启:
ansible <old-primary-ip> -b -a 'yum upgrade -y postgresql17*'
ansible <old-primary-ip> -b -a 'apt install -y postgresql-17'
pg restart <cls> <old-primary-name> --force
步骤五:验证
确认所有实例版本一致:
pg list <cls>
pg query <cls> -c "SELECT version()"
小版本降级 在极少数情况下(如新版本引入 Bug),可能需要将 PostgreSQL 降级到之前的版本。
步骤一:获取旧版本包
cd ~/pigsty; ./infra.yml -t repo_upstream # 添加上游仓库
cd /www/pigsty; repotrack postgresql17-*-17.1 # 下载指定版本的包
cd ~/pigsty; ./infra.yml -t repo_create # 重建仓库元数据
ansible <cls> -b -a 'yum clean all'
ansible <cls> -b -a 'yum makecache'
步骤二:执行降级
ansible <cls> -b -a 'yum downgrade -y postgresql17*'
ansible <cls> -b -a 'apt install -y postgresql-17=17.1*'
步骤三:重启集群
大版本升级 大版本升级(如 17 → 18)涉及数据格式变更,需要使用专用工具进行数据迁移。
推荐方案
对于生产环境,推荐使用 逻辑复制迁移 方式:创建新版本集群,通过逻辑复制同步数据,然后进行蓝绿切换。这种方式停机时间最短,且可以随时回滚。详见 在线迁移 。
逻辑复制迁移 逻辑复制迁移是生产环境大版本升级的推荐方式,核心步骤:
1. 创建新版本目标集群 → 2. 配置逻辑复制同步数据 → 3. 验证数据一致性
4. 切换应用流量到新集群 → 5. 下线旧集群
步骤一:创建新版本集群
pg-meta-new :
hosts :
10.10.10.12 : { pg_seq: 1, pg_role : primary }
vars :
pg_cluster : pg-meta-new
pg_version : 18 # 新版本
bin/pgsql-add pg-meta-new
步骤二:配置逻辑复制
-- 源集群(旧版本)主库:创建发布
CREATE PUBLICATION upgrade_pub FOR ALL TABLES ;
-- 目标集群(新版本)主库:创建订阅
CREATE SUBSCRIPTION upgrade_sub
CONNECTION 'host=10.10.10.11 port=5432 dbname=mydb user=replicator password=xxx'
PUBLICATION upgrade_pub ;
步骤三:等待同步完成
-- 目标集群:检查订阅状态
SELECT * FROM pg_stat_subscription ;
-- 源集群:检查复制槽 LSN
SELECT slot_name , confirmed_flush_lsn FROM pg_replication_slots ;
步骤四:切换流量
确认数据同步完成后:停止应用写入源集群 → 等待最后的数据同步 → 切换应用连接到新集群 → 删除订阅,下线源集群。
-- 目标集群:删除订阅
DROP SUBSCRIPTION upgrade_sub ;
详细的迁移流程请参考 在线迁移 文档。
pg_upgrade 原地升级 pg_upgrade 是 PostgreSQL 官方提供的大版本升级工具,适用于测试环境或可接受较长停机时间的场景。
重要警告
原地升级会导致较长的停机时间,且回滚困难。生产环境请优先考虑逻辑复制迁移方式。
步骤一:安装新版本软件包
./pgsql.yml -l <cls> -t pg_pkg -e pg_version = 18
步骤二:停止 Patroni
pg pause <cls> # 暂停自动故障转移
systemctl stop patroni # 停止 Patroni(会停止 PostgreSQL)
步骤三:运行 pg_upgrade
sudo su - postgres
mkdir -p /data/postgres/pg-meta-18/data
# 预检(-c 参数只检查不执行)
/usr/pgsql-18/bin/pg_upgrade \
-b /usr/pgsql-17/bin -B /usr/pgsql-18/bin \
-d /data/postgres/pg-meta-17/data \
-D /data/postgres/pg-meta-18/data \
-v -c
# 执行升级
/usr/pgsql-18/bin/pg_upgrade \
-b /usr/pgsql-17/bin -B /usr/pgsql-18/bin \
-d /data/postgres/pg-meta-17/data \
-D /data/postgres/pg-meta-18/data \
--link -j 8 -v
步骤四:更新链接并启动
rm -rf /usr/pgsql && ln -s /usr/pgsql-18 /usr/pgsql
rm -rf /pg && ln -s /data/postgres/pg-meta-18 /pg
# 编辑 /etc/patroni/patroni.yml 更新路径
systemctl start patroni
pg resume <cls>
步骤五:后处理
/usr/pgsql-18/bin/vacuumdb --all --analyze-in-stages
./delete_old_cluster.sh # pg_upgrade 生成的清理脚本
扩展升级 升级 PostgreSQL 版本时,通常也需要升级相关扩展插件。
升级扩展软件包
ansible <cls> -b -a 'yum upgrade -y postgis36_17 timescaledb-2-postgresql-17* pgvector_17*'
ansible <cls> -b -a 'apt install -y postgresql-17-postgis-3 postgresql-17-pgvector'
升级扩展版本
软件包升级后,在数据库中执行扩展升级:
-- 查看可升级的扩展
SELECT name , installed_version , default_version FROM pg_available_extensions
WHERE installed_version IS NOT NULL AND installed_version <> default_version ;
-- 升级扩展
ALTER EXTENSION postgis UPDATE ;
ALTER EXTENSION timescaledb UPDATE ;
ALTER EXTENSION vector UPDATE ;
-- 检查扩展版本
SELECT extname , extversion FROM pg_extension ;
扩展兼容性
大版本升级前,请确认所有使用的扩展都支持目标 PostgreSQL 版本。某些扩展可能需要先卸载再重新安装,请查阅扩展文档。
注意事项 备份优先 :任何升级操作前都应进行完整备份测试验证 :先在测试环境验证升级流程扩展兼容 :确认所有扩展支持目标版本回滚预案 :准备好回滚方案,特别是大版本升级监控观察 :升级后密切监控数据库性能和错误日志文档记录 :记录升级过程中的所有操作和问题相关文档 12.6.9 - 管理 PostgreSQL 扩展插件 扩展管理:下载、安装、配置、启用、更新、卸载扩展
快速上手 Pigsty 提供 510 扩展 ,使用扩展涉及四个步骤:下载 、安装 、配置 、启用 。
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta
pg_extensions : [ postgis, timescaledb, pgvector ] # <--- 安装扩展软件包
pg_libs : 'timescaledb, pg_stat_statements, auto_explain' # <--- 配置预加载扩展
pg_databases :
- name : meta
extensions : [ postgis, timescaledb, vector ] # <--- 在数据库中启用
bin/pgsql-ext <cls> # 在 <cls> 集群上安装配置中定义的扩展
bin/pgsql-ext <cls> [ ext...] # 在 <cls> 集群上安装命令行参数给出的扩展
./pgsql.yml -l pg-meta -t pg_ext # 使用剧本安装扩展
bin/pgsql-ext pg-meta # 在 pg-meta 集群上安装定义的扩展
bin/pgsql-ext pg-meta pg_duckdb pg_mooncake # 安装指定扩展
关于扩展的完整参考,请查阅 扩展插件 章节。关于可用扩展列表,请参考 扩展目录 。
操作 快捷命令 说明 下载扩展 ./infra.yml -t repo_build将扩展下载到本地仓库 安装扩展 bin/pgsql-ext <cls>在集群节点上安装扩展软件包 配置扩展 pg edit-config <cls> -p将扩展添加到预加载库(需重启) 启用扩展 psql -c 'CREATE EXT ...'在数据库中创建扩展对象 更新扩展 ALTER EXTENSION UPDATE更新扩展软件包与扩展对象 移除扩展 DROP EXTENSION删除扩展对象,卸载软件包
安装扩展 定义在 pg_extensions 里面的扩展会在 PostgreSQL 集群创建 的时候在 pg_extension 任务中自动安装。
要在现有的 PostgreSQL 集群上安装扩展,请将扩展添加到 all.children.<cls>.pg_extensions,然后执行:
bin/pgsql-ext <cls> # 在 <cls> 集群上安装扩展
./pgsql.yml -l <cls> -t pg_extension # 直接使用 Ansible 剧本安装扩展
bin/pgsql-ext pg-meta # 在 pg-meta 集群上安装配置中定义的扩展
示例配置:在集群上安装 PostGIS、TimescaleDB 和 PGVector
#all.children.pg-meta.vars: # 省略上级缩进
pg_extensions : [ postgis, timescaledb, pgvector ]
执行效果 :在集群所有节点上安装扩展软件包。Pigsty 会自动将 包别名 翻译为对应操作系统和 PostgreSQL 版本的实际包名。
安装前,确保软件源可用
安装扩展前请确保节点已配置正确的软件源 —— 扩展已经在本地仓库中 下载好 ,或者已经 配置扩展仓库 。
手工安装 如果您不想使用 Pigsty 配置来管理 PostgreSQL 扩展,可以在命令行中直接传递要安装的扩展列表:
bin/pgsql-ext pg-meta pg_duckdb pg_mooncake # 在 pg-meta 集群上安装指定扩展
./pgsql.yml -l pg-meta -t pg_ext -e '{"pg_extensions": ["pg_duckdb", "pg_mooncake"]}'
您也可以使用 pig 包管理器命令行工具在单个节点上安装扩展,同样会自动进行 包别名 解析。
pig install postgis timescaledb # 安装多个扩展
pig install pgvector -v 18 # 针对特定 PG 大版本安装
ansible pg-test -b -a 'pig install pg_duckdb' # 使用 Ansible 在集群上批量安装
您也可以 直接使用操作系统包管理器 (apt/dnf) 进行安装,但您必须知道具体操作系统/PG 下的 RPM/DEB 包名:
# EL 系统(RHEL、Rocky、Alma、Oracle Linux)
sudo yum install -y pgvector_18*
# Debian / Ubuntu 系统
sudo apt install -y postgresql-18-pgvector
下载扩展 要想安装扩展,您需要确保节点上配置的 扩展仓库 包含待安装的扩展:
Pigsty 的默认配置在安装过程中会自动下载主流扩展到本地仓库。如需额外扩展,添加到 repo_extra_packages 后重建仓库:
repo_extra_packages : [ pgvector, postgis, timescaledb ]
make repo # 快捷方式 = repo-build + node-repo
make repo-build # 快捷方式,重建 Infra 上的软件仓库(下载软件包与依赖)
make node-repo # 快捷方式,刷新节点上的软件源缓存,更新对 Infra 软件仓库的引用
./deploy.yml -t repo_build,node_repo # 一次性执行两个任务
./infra.yml -t repo_build # 重新下载软件包到本地仓库
./node.yml -t node_repo # 刷新节点软件源缓存
配置仓库 您也可以选择直接让所有节点都使用上游仓库(生产环境不推荐),跳过下载步骤,直接从互联网 上游扩展仓库 安装
./node.yml -t node_repo -e node_repo_modules = node,pgsql # 添加 PGDG 与 Pigsty 上游仓库
配置扩展 部分扩展需要预加载到 shared_preload_libraries 才能使用,修改后需要 重启数据库 生效。
您可以用 pg_libs 参数作为它的默认值,在配置预加载的扩展,但是这个参数只在集群初始化时生效,后面修改就无效了。
pg-meta :
vars :
pg_cluster : pg-meta
pg_libs : 'timescaledb, pg_stat_statements, auto_explain' # 预加载扩展
pg_extensions : [ timescaledb, postgis, pgvector ] # 安装扩展包
对于已有集群,您可以参考 修改配置 的介绍,修改 shared_preload_libraries参数:
pg edit-config pg-meta --force -p shared_preload_libraries = 'timescaledb, pg_stat_statements, auto_explain'
pg restart pg-meta # 修改 pg-meta 集群的参数,并重启集群使配置生效
请确保扩展软件包已正确安装后再添加预加载配置,如果 shared_preload_libraries 中的扩展不存在或加载失败,PostgreSQL 将 无法启动 。
此外,请通过 Patroni 管理集群的配置变更,避免使用 ALTER SYSTEM 或者 pg_parameters 单独修改实例配置。
如果主库和从库配置不一致,可能导致启动失败或复制中断。
启用扩展 安装扩展软件包后,需要在数据库中执行 CREATE EXTENSION 才能使用扩展提供的功能。
集群初始化时启用
在 数据库定义 中通过 extensions 数组声明要启用的扩展:
pg_databases :
- name : meta
extensions :
- vector # 简单形式
- { name: postgis, schema : public } # 指定 Schema
手动启用
CREATE EXTENSION vector ; -- 创建扩展
CREATE EXTENSION postgis SCHEMA public ; -- 指定 Schema
CREATE EXTENSION IF NOT EXISTS vector ; -- 幂等创建
CREATE EXTENSION postgis_topology CASCADE ; -- 自动安装依赖
psql -d meta -c 'CREATE EXTENSION vector;' # 在 meta 数据库创建扩展
psql -d meta -c 'CREATE EXTENSION postgis SCHEMA public;' # 指定 Schema
# 修改数据库定义后使用剧本启用扩展
bin/pgsql-db pg-meta meta # 创建/修改数据库会自动启用定义的扩展
执行效果 :在数据库中创建扩展对象(函数、类型、操作符、索引方法等),之后即可使用扩展提供的功能。
更新扩展 扩展更新涉及两个层面:软件包更新 和 扩展对象更新 。
更新软件包
pig update pgvector # 使用 pig 更新扩展
sudo yum update pgvector_18 # EL
sudo apt upgrade postgresql-18-pgvector # Debian/Ubuntu
更新扩展对象
-- 查看可升级的扩展
SELECT name , installed_version , default_version FROM pg_available_extensions
WHERE installed_version IS NOT NULL AND installed_version <> default_version ;
-- 更新扩展到最新版本
ALTER EXTENSION vector UPDATE ;
-- 更新到指定版本
ALTER EXTENSION vector UPDATE TO '0.8.1' ;
更新注意事项
更新扩展前建议备份数据库。预加载扩展更新后可能需要重启 PostgreSQL。某些扩展版本升级可能不兼容,请查阅扩展文档。
移除扩展 移除扩展涉及两个层面:删除扩展对象 和 卸载软件包 。
删除扩展对象
DROP EXTENSION vector ; -- 删除扩展
DROP EXTENSION vector CASCADE ; -- 级联删除(删除依赖对象)
移除预加载
如果是预加载扩展,需从 shared_preload_libraries 中移除并重启:
pg edit-config pg-meta --force -p shared_preload_libraries = 'pg_stat_statements, auto_explain'
pg restart pg-meta # 重启使配置生效
卸载软件包(可选)
pig remove pgvector # 使用 pig 卸载
sudo yum remove pgvector_18* # EL 系统
sudo apt remove postgresql-18-pgvector # Debian/Ubuntu
CASCADE 警告
使用 CASCADE 删除扩展会同时删除所有依赖该扩展的对象(表、索引、视图等)。请先检查依赖关系再执行删除。
查询扩展 以下是一些常用的 SQL 查询,用于查看扩展信息:
查看已启用的扩展
SELECT extname , extversion , nspname AS schema
FROM pg_extension e JOIN pg_namespace n ON e . extnamespace = n . oid
ORDER BY extname ;
查看可用扩展
SELECT name , default_version , installed_version , comment
FROM pg_available_extensions
WHERE installed_version IS NOT NULL -- 仅显示已安装的
ORDER BY name ;
检查扩展是否可用
SELECT * FROM pg_available_extensions WHERE name = 'vector' ;
查看扩展依赖关系
SELECT e . extname , d . refobjid :: regclass AS depends_on
FROM pg_extension e
JOIN pg_depend d ON d . objid = e . oid
WHERE d . deptype = 'e' AND e . extname = 'postgis_topology' ;
查看扩展对象
SELECT classid :: regclass , objid , deptype
FROM pg_depend
WHERE refobjid = ( SELECT oid FROM pg_extension WHERE extname = 'vector' );
psql 快捷命令
\d x # 列出已启用的扩展
\d x+ vector # 显示扩展详情
添加仓库 如需直接从上游安装扩展,可手动添加软件仓库。
使用 Pigsty 剧本添加
./node.yml -t node_repo -e node_repo_modules = node,pgsql # 添加 PGDG 与 Pigsty 仓库
./node.yml -t node_repo -e node_repo_modules = node,pgsql,local # 包括本地仓库
YUM 仓库(EL 系统)
# Pigsty 仓库
curl -fsSL https://repo.pigsty.io/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
curl -fsSL https://repo.pigsty.io/yum/repo | sudo tee /etc/yum.repos.d/pigsty.repo >/dev/null
# 中国大陆镜像
curl -fsSL https://repo.pigsty.cc/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
curl -fsSL https://repo.pigsty.cc/yum/repo | sudo tee /etc/yum.repos.d/pigsty.repo >/dev/null
APT 仓库(Debian/Ubuntu)
curl -fsSL https://repo.pigsty.io/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg
sudo tee /etc/apt/sources.list.d/pigsty.list > /dev/null <<EOF
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/infra generic main
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/pgsql $(lsb_release -cs) main
EOF
sudo apt update
# 中国大陆镜像:将 repo.pigsty.io 替换为 repo.pigsty.cc
常见问题 扩展名与包名的区别
名称 说明 示例 扩展名 CREATE EXTENSION 使用的名称vector包别名 Pigsty 配置中使用的标准化名称 pgvector包名 操作系统实际的包名 pgvector_18* 或 postgresql-18-pgvector
预加载扩展无法启动
如果 shared_preload_libraries 中的扩展不存在或加载失败,PostgreSQL 将无法启动。解决方法:
确保扩展软件包已正确安装 或从 shared_preload_libraries 中移除该扩展(编辑 /pg/data/postgresql.conf) 扩展依赖问题
某些扩展依赖于其他扩展,需按顺序创建或使用 CASCADE:
CREATE EXTENSION postgis ; -- 先创建基础扩展
CREATE EXTENSION postgis_topology ; -- 再创建依赖扩展
-- 或
CREATE EXTENSION postgis_topology CASCADE ; -- 自动创建依赖
扩展版本不兼容
查看当前 PostgreSQL 版本支持的扩展版本:
SELECT * FROM pg_available_extension_versions WHERE name = 'vector' ;
相关资源 12.7 - 备份恢复 时间点恢复(PITR)备份与恢复
Pigsty 使用 pgBackRest 管理 PostgreSQL 备份,这可能是生态系统中最强大的开源备份工具。
它支持增量/并行备份与恢复、加密、MinIO /S3 等众多特性。Pigsty 默认为每个 PGSQL 集群预配置了备份功能。
章节 内容 机制 备份脚本、定时任务、pgbackrest、仓库与管理 策略 备份策略、磁盘规划、恢复窗口权衡 仓库 配置备份仓库:本地、MinIO、S3 管理 常用备份管理命令 恢复 使用剧本恢复到特定时间点 示例 沙箱示例:手工执行恢复操作
免责声明
Pigsty 尽最大努力提供可靠的 PITR 解决方案,但我们不对 PITR 操作导致的数据丢失承担任何责任,使用需自担风险。如需专业支持,请考虑我们的 专业服务 。
快速上手 备份策略 :使用 Crontab 调度基础备份WAL 归档 :持续记录写入活动恢复与还原 :从备份和 WAL 归档中恢复node_crontab : [ '00 01 * * * postgres /pg/bin/pg-backup full' ]
./pgsql-pitr.yml -e '{"pg_pitr": { "time": "2025-07-13 10:00:00+00" }}'
12.7.1 - 备份策略 根据您的需求设计备份策略
下图将“恢复窗口”与“存储空间占用”合并到同一时间轴(0~108h)中,便于一起观察。
在相同假设(数据库 100GB、日写入 10GB)下,下图展示“每 7 天全量 + 每日增量、全量保留 14 天”时,30 天内恢复窗口与存储占用变化。
何时备份 第一个问题是何时 备份您的数据库——这是备份频率和恢复时间之间的权衡。
由于您需要从上一次备份开始重放 WAL 日志到恢复目标点,备份越频繁,需要重放的 WAL 日志就越少,恢复速度就越快。
每日全量备份 对于生产数据库,建议从最简单的每日全量备份策略开始。
这也是 Pigsty 的默认备份策略,通过 crontab 实现。
pg_crontab : [ '00 01 * * * /pg/bin/pg-backup full' ]
pgbackrest_method : local # 选择备份仓库方法:`local`、`minio` 或其他自定义仓库
pgbackrest_repo: # pgbackrest 仓库配置 : https://pgbackrest.org/configuration.html#section-repository
local : # 使用本地 POSIX 文件系统的默认 pgbackrest 仓库
path : /pg/backup # 本地备份目录,默认为 `/pg/backup`
retention_full_type : count # 按数量保留全量备份
retention_full : 2 # 使用本地文件系统仓库时,保留2个,最多3个全量备份
假设您的数据库大小为 100GB,每天更新写入 10GB 数据,备份耗时1小时,那么在每日全量备份,使用本地仓库的策略下,恢复窗口与备份空间随时间的变化如下图所示:
恢复窗口会在 25-49 小时之间循环,备份消耗的存储空间约为全量基础备份的 2 倍加上 2 天的 WAL 日志。
在实践中,您可能需要准备至少 3~5 倍基础数据库大小的备份磁盘才能使用默认备份策略。
全量 + 增量备份 您可以通过调整这些参数来优化备份空间使用。
如果使用 MinIO / S3 作为集中式备份仓库,您可以使用超出本地磁盘限制的存储空间。
此时可以考虑使用全量 + 增量备份配合 2 周保留策略:
pg_crontab : # 周一凌晨1点全量备份,工作日增量备份
- '00 01 * * 1 /pg/bin/pg-backup full'
- '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup'
pgbackrest_method : minio
pgbackrest_repo: # pgbackrest 仓库配置 : https://pgbackrest.org/configuration.html#section-repository
minio : # 可选的 minio 仓库
type : s3 # minio 兼容 S3 协议
s3_endpoint : sss.pigsty # minio 端点域名,默认为 `sss.pigsty`
s3_region : us-east-1 # minio 区域,默认 us-east-1,对 minio 无实际意义
s3_bucket : pgsql # minio 桶名,默认为 `pgsql`
s3_key : pgbackrest # pgbackrest 的 minio 用户访问密钥
s3_key_secret : S3User.Backup # pgbackrest 的 minio 用户密钥
s3_uri_style : path # minio 使用路径风格 URI 而非主机风格
path : /pgbackrest # minio 备份路径,默认为 `/pgbackrest`
storage_port : 9000 # minio 端口,默认 9000
storage_ca_file : /etc/pki/ca.crt # minio CA 证书路径,默认 `/etc/pki/ca.crt`
block : y # 启用块级增量备份
bundle : y # 将小文件打包成单个文件
bundle_limit : 20MiB # 文件包大小限制,对象存储建议 20MiB
bundle_size : 128MiB # 文件包目标大小,对象存储建议 128MiB
cipher_type : aes-256-cbc # 为远程备份仓库启用 AES 加密
cipher_pass : pgBackRest # AES 加密密码,默认为 'pgBackRest'
retention_full_type : time # 按时间保留全量备份
retention_full : 14 # 保留最近 14 天的全量备份
配合内置的 minio 备份仓库使用时,可提供保证 1 周的 PITR 恢复窗口。
假设您的数据库大小为 100GB,每天写入 10GB 数据,则备份大小如下:
备份位置 默认情况下,Pigsty 提供两个默认备份仓库定义:local 和 minio 备份仓库。
local:默认选项 ,使用本地 /pg/backup 目录(软链接指向 pg_fs_backup :/data/backups)minio:使用 SNSD 单节点 MinIO 集群(Pigsty 支持,但默认不启用)pgbackrest_method : local # 选择备份仓库方法:`local`、`minio` 或其他自定义仓库
pgbackrest_repo: # pgbackrest 仓库配置 : https://pgbackrest.org/configuration.html#section-repository
local : # 使用本地 POSIX 文件系统的默认 pgbackrest 仓库
path : /pg/backup # 本地备份目录,默认为 `/pg/backup`
retention_full_type : count # 按数量保留全量备份
retention_full : 2 # 使用本地文件系统仓库时,保留2个,最多3个全量备份
minio : # 可选的 minio 仓库
type : s3 # minio 兼容 S3 协议
s3_endpoint : sss.pigsty # minio 端点域名,默认为 `sss.pigsty`
s3_region : us-east-1 # minio 区域,默认 us-east-1,对 minio 无实际意义
s3_bucket : pgsql # minio 桶名,默认为 `pgsql`
s3_key : pgbackrest # pgbackrest 的 minio 用户访问密钥
s3_key_secret : S3User.Backup # pgbackrest 的 minio 用户密钥
s3_uri_style : path # minio 使用路径风格 URI 而非主机风格
path : /pgbackrest # minio 备份路径,默认为 `/pgbackrest`
storage_port : 9000 # minio 端口,默认 9000
storage_ca_file : /etc/pki/ca.crt # minio CA 证书路径,默认 `/etc/pki/ca.crt`
block : y # 启用块级增量备份
bundle : y # 将小文件打包成单个文件
bundle_limit : 20MiB # 文件包大小限制,对象存储建议 20MiB
bundle_size : 128MiB # 文件包目标大小,对象存储建议 128MiB
cipher_type : aes-256-cbc # 为远程备份仓库启用 AES 加密
cipher_pass : pgBackRest # AES 加密密码,默认为 'pgBackRest'
retention_full_type : time # 按时间保留全量备份
retention_full : 14 # 保留最近 14 天的全量备份
12.7.2 - 备份机制 备份脚本、定时任务、备份仓库与基础设施
备份可以通过内置 脚本 调用,使用节点 crontab 定时执行,
由 pgbackrest 管理,存储在备份仓库中,
仓库可以是本地磁盘文件系统或 MinIO / S3,并支持不同的 保留 策略。
脚本 您可以使用 pg_dbsu 用户(默认为 postgres)执行 pgbackrest 命令创建备份:
备份命令
backup
full
diff
incr
info pgbackrest --stanza= pg-meta --type= full backup # 为集群 pg-meta 创建全量备份 $ pgbackrest --stanza= pg-meta --type= full backup
2025-07-15 01:36:57.007 P00 INFO: backup command begin 2.54.2: --annotation= pg_cluster = pg-meta ...
2025-07-15 01:36:57.030 P00 INFO: execute non-exclusive backup start: backup begins after the requested immediate checkpoint completes
2025-07-15 01:36:57.105 P00 INFO: backup start archive = 000000010000000000000006, lsn = 0/6000028
2025-07-15 01:36:58.540 P00 INFO: new backup label = 20250715-013657F
2025-07-15 01:36:58.588 P00 INFO: full backup size = 44.5MB, file total = 1437
2025-07-15 01:36:58.589 P00 INFO: backup command end: completed successfully ( 1584ms) $ pgbackrest --stanza= pg-meta --type= diff backup
2025-07-15 01:37:24.952 P00 INFO: backup command begin 2.54.2: ...
2025-07-15 01:37:24.985 P00 INFO: last backup label = 20250715-013657F, version = 2.54.2
2025-07-15 01:37:26.337 P00 INFO: new backup label = 20250715-013657F_20250715-013724D
2025-07-15 01:37:26.381 P00 INFO: diff backup size = 424.3KB, file total = 1437
2025-07-15 01:37:26.381 P00 INFO: backup command end: completed successfully ( 1431ms) $ pgbackrest --stanza= pg-meta --type= incr backup
2025-07-15 01:37:30.305 P00 INFO: backup command begin 2.54.2: ...
2025-07-15 01:37:30.337 P00 INFO: last backup label = 20250715-013657F_20250715-013724D, version = 2.54.2
2025-07-15 01:37:31.356 P00 INFO: new backup label = 20250715-013657F_20250715-013730I
2025-07-15 01:37:31.403 P00 INFO: incr backup size = 8.3KB, file total = 1437
2025-07-15 01:37:31.403 P00 INFO: backup command end: completed successfully ( 1099ms) $ pgbackrest --stanza= pg-meta info
stanza: pg-meta
status: ok
cipher: aes-256-cbc
db ( current)
wal archive min/max ( 17) : 000000010000000000000001/00000001000000000000000A
full backup: 20250715-013657F
timestamp start/stop: 2025-07-15 01:36:57+00 / 2025-07-15 01:36:58+00
wal start/stop: 000000010000000000000006 / 000000010000000000000006
database size: 44.5MB, database backup size: 44.5MB
repo1: backup size: 8.7MB
diff backup: 20250715-013657F_20250715-013724D
timestamp start/stop: 2025-07-15 01:37:24+00 / 2025-07-15 01:37:26+00
database size: 44.5MB, database backup size: 424.3KB
repo1: backup size: 94KB
backup reference total: 1 full
incr backup: 20250715-013657F_20250715-013730I
timestamp start/stop: 2025-07-15 01:37:30+00 / 2025-07-15 01:37:31+00
database size: 44.5MB, database backup size: 8.3KB
repo1: backup size: 504B
backup reference total: 1 full, 1 diff 这里的 stanza 是数据库集群名称:pg_cluster ,在默认配置中为 pg-meta。
Pigsty 提供了 pb 别名和 pg-backup 包装脚本,会自动填充当前集群名称作为 stanza:
function pb() {
local stanza = $( grep -o '\[[^][]*]' /etc/pgbackrest/pgbackrest.conf | head -n1 | sed 's/.*\[\([^]]*\)].*/\1/' )
pgbackrest --stanza= $stanza $@
}
pb ... # pgbackrest --stanza=pg-meta ...
pb info # pgbackrest --stanza=pg-meta info
pb backup # pgbackrest --stanza=pg-meta backup
pg-backup full # 执行全量备份 = pgbackrest --stanza=pg-meta --type=full backup
pg-backup incr # 执行增量备份 = pgbackrest --stanza=pg-meta --type=incr backup
pg-backup diff # 执行差异备份 = pgbackrest --stanza=pg-meta --type=diff backup
定时备份 Pigsty 利用 Linux crontab 来调度备份任务。您可以用它定义备份策略。
例如,大多数单节点配置模板都有以下用于备份的 node_crontab :
node_crontab : [ '00 01 * * * postgres /pg/bin/pg-backup full' ]
您可以使用 crontab 和 pg-backup 脚本设计更复杂的备份策略,例如:
node_crontab : # 周一凌晨1点全量备份,工作日增量备份
- '00 01 * * 1 postgres /pg/bin/pg-backup full'
- '00 01 * * 2,3,4,5,6,7 postgres /pg/bin/pg-backup'
要应用 crontab 变更,使用 node.yml 更新所有节点的 crontab:
./node.yml -t node_crontab -l pg-meta # 将 crontab 变更应用到 pg-meta 组
pgbackrest 以下是 Pigsty 对 pgbackrest 的配置细节:
文件层次结构 bin:/usr/bin/pgbackrest,来自 PGDG 的 pgbackrest 包,在组别名 pgsql-common 中。 conf:/etc/pgbackrest,主配置文件是 /etc/pgbackrest/pgbackrest.conf 。 logs:/pg/log/pgbackrest/*,由 pgbackrest_log_dir 控制 tmp:/pg/spool 用作 pgbackrest 的临时 spool 目录 data:/pg/backup 用于存储数据(当选择默认的 local 文件系统备份仓库时) 此外,在 PITR 恢复 过程中,Pigsty 会创建临时的 /pg/conf/pitr.conf pgbackrest 配置文件,
并将 postgres 恢复日志写入 /pg/tmp/recovery.log 文件。
监控 有一个 pgbackrest_exporter 服务运行在 pgbackrest_exporter_port (9854)端口上,用于导出 pgbackrest 指标。
您可以通过 pgbackrest_exporter_options 自定义它,
或将 pgbackrest_exporter_enabled 设置为 false 来禁用它。
初始备份 当创建 postgres 集群时,Pigsty 会自动创建初始备份。
由于新集群几乎为空,这是一个很小的备份。
它会留下一个 /etc/pgbackrest/initial.done 标记文件,以避免重复创建初始备份。
如果不需要初始备份,请将 pgbackrest_init_backup 设置为 false。
管理 启用备份 如果数据库集群创建时 pgbackrest_enabled 设置为 true,备份将自动启用。
如果创建时该值为 false,您可以使用以下命令启用 pgbackrest 组件:
./pgsql.yml -t pg_backup # 运行 pgbackrest 子任务
删除备份 当移除主实例(pg_role = primary)时,Pigsty 会删除 pgbackrest 备份 stanza。
./pgsql-rm.yml
./pgsql-rm.yml -e pg_rm_backup = false # 保留备份
./pgsql-rm.yml -t pg_backup # 仅删除备份
使用 pg_backup 子任务仅删除备份,使用 pg_rm_backup 参数(设为 false)保留备份。
如果您的备份仓库被锁定 (例如 S3 / MinIO 有锁定选项),此操作将失败。
备份删除
删除备份可能导致永久性数据丢失,这是一个危险操作,请务必谨慎。
列出备份 此命令将列出 pgbackrest 仓库中的所有备份(所有集群共享)
手动备份 Pigsty 提供了内置脚本 /pg/bin/pg-backup,封装了 pgbackrest 备份命令。
pg-backup # 执行增量备份
pg-backup full # 执行全量备份
pg-backup incr # 执行增量备份
pg-backup diff # 执行差异备份
基础备份 Pigsty 提供了一个替代备份脚本 /pg/bin/pg-basebackup,它不依赖 pgbackrest,直接提供数据库集群的物理副本。
默认备份目录为 /pg/backup。
pg-basebackup
help
backup NAME
pg-basebackup -- make base backup from PostgreSQL instance
SYNOPSIS
pg-basebackup -sdfeukr
pg-basebackup --src postgres:/// --dst . --file backup.tar.lz4
DESCRIPTION
-s, --src, --url 备份源 URL,可选,默认为 "postgres:///" ,如需密码应在 url、ENV 或 .pgpass 中提供
-d, --dst, --dir 备份文件存放位置,默认为 "/pg/backup"
-f, --file 覆盖默认备份文件名,"backup_ ${ tag } _ ${ date } .tar.lz4"
-r, --remove 删除 n 分钟前的 .lz4 文件,默认 1200(20小时)
-t, --tag 备份文件标签,未设置时使用目标集群名或本地 IP 地址,也用于默认文件名
-k, --key 指定 --encrypt 时的加密密钥,默认密钥为 ${ tag }
-u, --upload 上传备份文件到云存储(需自行实现)
-e, --encryption 使用 OpenSSL RC4 加密,未指定密钥时使用 tag 作为密钥
-h, --help 打印此帮助信息 postgres@pg-meta-1:~$ pg-basebackup
[ 2025-07-13 06:16:05][ INFO] ================================================================
[ 2025-07-13 06:16:05][ INFO] [ INIT] pg-basebackup begin, checking parameters
[ 2025-07-13 06:16:05][ DEBUG] [ INIT] filename ( -f) : backup_pg-meta_20250713.tar.lz4
[ 2025-07-13 06:16:05][ DEBUG] [ INIT] src ( -s) : postgres:///
[ 2025-07-13 06:16:05][ DEBUG] [ INIT] dst ( -d) : /pg/backup
[ 2025-07-13 06:16:05][ INFO] [ LOCK] lock acquired success on /tmp/backup.lock, pid = 107417
[ 2025-07-13 06:16:05][ INFO] [ BKUP] backup begin, from postgres:/// to /pg/backup/backup_pg-meta_20250713.tar.lz4
pg_basebackup: initiating base backup, waiting for checkpoint to complete
pg_basebackup: checkpoint completed
pg_basebackup: write-ahead log start point: 0/7000028 on timeline 1
pg_basebackup: write-ahead log end point: 0/7000FD8
pg_basebackup: syncing data to disk ...
pg_basebackup: base backup completed
[ 2025-07-13 06:16:06][ INFO] [ BKUP] backup complete!
[ 2025-07-13 06:16:06][ INFO] [ DONE] backup procedure complete!
[ 2025-07-13 06:16:06][ INFO] ================================================================ 备份使用 lz4 压缩。您可以使用以下命令解压并提取 tarball:
mkdir -p /tmp/data # 将备份提取到此目录
cat /pg/backup/backup_pg-meta_20250713.tar.lz4 | unlz4 -d -c | tar -xC /tmp/data
逻辑备份 您也可以使用 pg_dump 命令执行逻辑备份。
逻辑备份不能用于 PITR(时间点恢复),但对于在不同主版本之间迁移数据或实现灵活的数据导出逻辑非常有用。
从仓库引导 假设您有一个现有集群 pg-meta,想要将其克隆 为 pg-meta2:
您需要创建新的 pg-meta2 集群分支,然后在其上运行 pitr。
12.7.3 - 备份仓库 PostgreSQL 备份存储仓库配置
您可以通过指定 pgbackrest_repo 参数来配置备份存储位置 。
您可以在此定义多个仓库,Pigsty 会根据 pgbackrest_method 的值选择使用哪个。
默认仓库 默认情况下,Pigsty 提供两个默认备份仓库定义:local 和 minio 备份仓库。
local:默认选项 ,使用本地 /pg/backup 目录(软链接指向 pg_fs_backup :/data/backups)minio:使用 SNSD 单节点 MinIO 集群(Pigsty 支持,但默认不启用)pgbackrest_method : local # 选择备份仓库方法:`local`、`minio` 或其他自定义仓库
pgbackrest_repo: # pgbackrest 仓库配置 : https://pgbackrest.org/configuration.html#section-repository
local : # 使用本地 POSIX 文件系统的默认 pgbackrest 仓库
path : /pg/backup # 本地备份目录,默认为 `/pg/backup`
retention_full_type : count # 按数量保留全量备份
retention_full : 2 # 使用本地文件系统仓库时,保留2个,最多3个全量备份
minio : # 可选的 minio 仓库
type : s3 # minio 兼容 S3 协议
s3_endpoint : sss.pigsty # minio 端点域名,默认为 `sss.pigsty`
s3_region : us-east-1 # minio 区域,默认 us-east-1,对 minio 无实际意义
s3_bucket : pgsql # minio 桶名,默认为 `pgsql`
s3_key : pgbackrest # pgbackrest 的 minio 用户访问密钥
s3_key_secret : S3User.Backup # pgbackrest 的 minio 用户密钥
s3_uri_style : path # minio 使用路径风格 URI 而非主机风格
path : /pgbackrest # minio 备份路径,默认为 `/pgbackrest`
storage_port : 9000 # minio 端口,默认 9000
storage_ca_file : /etc/pki/ca.crt # minio CA 证书路径,默认 `/etc/pki/ca.crt`
block : y # 启用块级增量备份
bundle : y # 将小文件打包成单个文件
bundle_limit : 20MiB # 文件包大小限制,对象存储建议 20MiB
bundle_size : 128MiB # 文件包目标大小,对象存储建议 128MiB
cipher_type : aes-256-cbc # 为远程备份仓库启用 AES 加密
cipher_pass : pgBackRest # AES 加密密码,默认为 'pgBackRest'
retention_full_type : time # 按时间保留全量备份
retention_full : 14 # 保留最近 14 天的全量备份
仓库保留策略 如果每天备份但不删除旧备份,备份仓库会不断增长并耗尽磁盘空间。
您需要定义保留策略,只保留有限数量的备份。
默认备份策略定义在 pgbackrest_repo 参数中,可按需调整。
local:保留最近 2 个全量备份,备份期间最多允许 3 个minio:保留最近 14 天的所有全量备份空间规划 对象存储提供几乎无限的存储容量,因此无需担心磁盘空间。
您可以使用混合的全量 + 差异备份策略来优化空间使用。
对于本地磁盘备份仓库,Pigsty 建议使用保留最近 2 个全量备份的策略,
这意味着磁盘上保留两个最新的全量备份(运行新备份时可能存在第三个副本)。
这可保证至少 24 小时的恢复窗口。详情请参阅 备份策略 。
其他仓库选项 您也可以使用其他服务作为备份仓库,详情请参阅 pgbackrest 文档 :
仓库版本控制 您甚至可以指定 repo target time 来获取对象存储的快照。
您可以通过在 minio_buckets 中添加 versioning 标志来启用 MinIO 版本控制:
minio_buckets :
- { name: pgsql ,versioning : true }
- { name: meta ,versioning : true }
- { name : data }
仓库锁定 某些对象存储服务(S3、MinIO 等)支持锁定 功能,可以防止备份被删除,即使是 DBA 本人也无法删除。
您可以通过在 minio_buckets 中添加 lock 标志来启用 MinIO 锁定功能:
minio_buckets :
- { name: pgsql , lock : true }
- { name: meta ,versioning : true }
- { name : data }
使用对象存储 对象存储服务提供几乎无限的存储容量,并为您的系统提供远程容灾能力。
如果您没有对象存储服务,Pigsty 内置了 MinIO 支持。
MinIO 您可以通过取消注释以下设置来启用 MinIO 备份仓库。
请注意 pgbackrest 只支持 HTTPS / 域名,因此您必须使用域名和 HTTPS 端点运行 MinIO。
all :
vars :
pgbackrest_method : minio # 使用 minio 作为默认备份仓库
children : # 定义一个单节点 minio SNSD 集群
minio : { hosts : { 10.10.10.10 : { minio_seq: 1 }} ,vars : { minio_cluster : minio }}
S3 如果您只有一个 节点,有意义的备份策略可以是使用云厂商的对象存储服务,如 AWS S3、阿里云 OSS 或 Google Cloud 等。
为此,您可以定义一个新仓库:
pgbackrest_method : s3 # 使用 'pgbackrest_repo.s3' 作为备份仓库
pgbackrest_repo: # pgbackrest 仓库配置 : https://pgbackrest.org/configuration.html#section-repository
s3 : # 阿里云 OSS(S3 兼容)对象存储服务
type : s3 # oss 兼容 S3 协议
s3_endpoint : oss-cn-beijing-internal.aliyuncs.com
s3_region : oss-cn-beijing
s3_bucket : <your_bucket_name>
s3_key : <your_access_key>
s3_key_secret : <your_secret_key>
s3_uri_style : host
path : /pgbackrest
bundle : y # 将小文件打包成单个文件
bundle_limit : 20MiB # 文件包大小限制,对象存储建议 20MiB
bundle_size : 128MiB # 文件包目标大小,对象存储建议 128MiB
cipher_type : aes-256-cbc # 为远程备份仓库启用 AES 加密
cipher_pass : pgBackRest # AES 加密密码,默认为 'pgBackRest'
retention_full_type : time # 按时间保留全量备份
retention_full : 14 # 保留最近 14 天的全量备份
local : # 使用本地 POSIX 文件系统的默认 pgbackrest 仓库
path : /pg/backup # 本地备份目录,默认为 `/pg/backup`
retention_full_type : count # 按数量保留全量备份
retention_full : 2 # 使用本地文件系统仓库时,保留2个,最多3个全量备份
管理备份 启用备份 如果数据库集群创建时 pgbackrest_enabled 设置为 true,备份将自动启用。
如果创建时该值为 false,您可以使用以下命令启用 pgbackrest 组件:
./pgsql.yml -t pg_backup # 运行 pgbackrest 子任务
删除备份 当移除主实例(pg_role = primary)时,Pigsty 会删除 pgbackrest 备份 stanza。
./pgsql-rm.yml
./pgsql-rm.yml -e pg_rm_backup = false # 保留备份
./pgsql-rm.yml -t pg_backup # 仅删除备份
使用 pg_backup 子任务仅删除备份,使用 pg_rm_backup 参数(设为 false)保留备份。
如果您的备份仓库被锁定 (例如 S3 / MinIO 有锁定选项),此操作将失败。
备份删除
删除备份可能导致永久性数据丢失,这是一个危险操作,请务必谨慎。
列出备份 此命令将列出 pgbackrest 仓库中的所有备份(所有集群共享)
手动备份 Pigsty 提供了内置脚本 /pg/bin/pg-backup,封装了 pgbackrest 备份命令。
pg-backup # 执行增量备份
pg-backup full # 执行全量备份
pg-backup incr # 执行增量备份
pg-backup diff # 执行差异备份
基础备份 Pigsty 提供了一个替代备份脚本 /pg/bin/pg-basebackup,它不依赖 pgbackrest,直接提供数据库集群的物理副本。
默认备份目录为 /pg/backup。
pg-basebackup
help
backup NAME
pg-basebackup -- make base backup from PostgreSQL instance
SYNOPSIS
pg-basebackup -sdfeukr
pg-basebackup --src postgres:/// --dst . --file backup.tar.lz4
DESCRIPTION
-s, --src, --url 备份源 URL,可选,默认为 "postgres:///" ,如需密码应在 url、ENV 或 .pgpass 中提供
-d, --dst, --dir 备份文件存放位置,默认为 "/pg/backup"
-f, --file 覆盖默认备份文件名,"backup_ ${ tag } _ ${ date } .tar.lz4"
-r, --remove 删除 n 分钟前的 .lz4 文件,默认 1200(20小时)
-t, --tag 备份文件标签,未设置时使用目标集群名或本地 IP 地址,也用于默认文件名
-k, --key 指定 --encrypt 时的加密密钥,默认密钥为 ${ tag }
-u, --upload 上传备份文件到云存储(需自行实现)
-e, --encryption 使用 OpenSSL RC4 加密,未指定密钥时使用 tag 作为密钥
-h, --help 打印此帮助信息 postgres@pg-meta-1:~$ pg-basebackup
[ 2025-07-13 06:16:05][ INFO] ================================================================
[ 2025-07-13 06:16:05][ INFO] [ INIT] pg-basebackup begin, checking parameters
[ 2025-07-13 06:16:05][ DEBUG] [ INIT] filename ( -f) : backup_pg-meta_20250713.tar.lz4
[ 2025-07-13 06:16:05][ DEBUG] [ INIT] src ( -s) : postgres:///
[ 2025-07-13 06:16:05][ DEBUG] [ INIT] dst ( -d) : /pg/backup
[ 2025-07-13 06:16:05][ INFO] [ LOCK] lock acquired success on /tmp/backup.lock, pid = 107417
[ 2025-07-13 06:16:05][ INFO] [ BKUP] backup begin, from postgres:/// to /pg/backup/backup_pg-meta_20250713.tar.lz4
pg_basebackup: initiating base backup, waiting for checkpoint to complete
pg_basebackup: checkpoint completed
pg_basebackup: write-ahead log start point: 0/7000028 on timeline 1
pg_basebackup: write-ahead log end point: 0/7000FD8
pg_basebackup: syncing data to disk ...
pg_basebackup: base backup completed
[ 2025-07-13 06:16:06][ INFO] [ BKUP] backup complete!
[ 2025-07-13 06:16:06][ INFO] [ DONE] backup procedure complete!
[ 2025-07-13 06:16:06][ INFO] ================================================================ 备份使用 lz4 压缩。您可以使用以下命令解压并提取 tarball:
mkdir -p /tmp/data # 将备份提取到此目录
cat /pg/backup/backup_pg-meta_20250713.tar.lz4 | unlz4 -d -c | tar -xC /tmp/data
逻辑备份 您也可以使用 pg_dump 命令执行逻辑备份。
逻辑备份不能用于 PITR(时间点恢复),但对于在不同主版本之间迁移数据或实现灵活的数据导出逻辑非常有用。
从仓库引导 假设您有一个现有集群 pg-meta,想要将其克隆 为 pg-meta2:
您需要创建新的 pg-meta2 集群分支,然后在其上运行 pitr。
12.7.4 - 管理命令 管理备份仓库和备份
启用备份 如果数据库集群创建时 pgbackrest_enabled 设置为 true,备份将自动启用。
如果创建时该值为 false,您可以使用以下命令启用 pgbackrest 组件:
./pgsql.yml -t pg_backup # 运行 pgbackrest 子任务
删除备份 当移除主实例(pg_role = primary)时,Pigsty 会删除 pgbackrest 备份 stanza。
./pgsql-rm.yml
./pgsql-rm.yml -e pg_rm_backup = false # 保留备份
./pgsql-rm.yml -t pg_backup # 仅删除备份
使用 pg_backup 子任务仅删除备份,使用 pg_rm_backup 参数(设为 false)保留备份。
如果您的备份仓库被锁定 (例如 S3 / MinIO 有锁定选项),此操作将失败。
备份删除
删除备份可能导致永久性数据丢失,这是一个危险操作,请务必谨慎。
列出备份 此命令将列出 pgbackrest 仓库中的所有备份(所有集群共享)
手动备份 Pigsty 提供了内置脚本 /pg/bin/pg-backup,封装了 pgbackrest 备份命令。
pg-backup # 执行增量备份
pg-backup full # 执行全量备份
pg-backup incr # 执行增量备份
pg-backup diff # 执行差异备份
基础备份 Pigsty 提供了一个替代备份脚本 /pg/bin/pg-basebackup,它不依赖 pgbackrest,直接提供数据库集群的物理副本。
默认备份目录为 /pg/backup。
pg-basebackup
help
backup NAME
pg-basebackup -- make base backup from PostgreSQL instance
SYNOPSIS
pg-basebackup -sdfeukr
pg-basebackup --src postgres:/// --dst . --file backup.tar.lz4
DESCRIPTION
-s, --src, --url 备份源 URL,可选,默认为 "postgres:///" ,如需密码应在 url、ENV 或 .pgpass 中提供
-d, --dst, --dir 备份文件存放位置,默认为 "/pg/backup"
-f, --file 覆盖默认备份文件名,"backup_ ${ tag } _ ${ date } .tar.lz4"
-r, --remove 删除 n 分钟前的 .lz4 文件,默认 1200(20小时)
-t, --tag 备份文件标签,未设置时使用目标集群名或本地 IP 地址,也用于默认文件名
-k, --key 指定 --encrypt 时的加密密钥,默认密钥为 ${ tag }
-u, --upload 上传备份文件到云存储(需自行实现)
-e, --encryption 使用 OpenSSL RC4 加密,未指定密钥时使用 tag 作为密钥
-h, --help 打印此帮助信息 postgres@pg-meta-1:~$ pg-basebackup
[ 2025-07-13 06:16:05][ INFO] ================================================================
[ 2025-07-13 06:16:05][ INFO] [ INIT] pg-basebackup begin, checking parameters
[ 2025-07-13 06:16:05][ DEBUG] [ INIT] filename ( -f) : backup_pg-meta_20250713.tar.lz4
[ 2025-07-13 06:16:05][ DEBUG] [ INIT] src ( -s) : postgres:///
[ 2025-07-13 06:16:05][ DEBUG] [ INIT] dst ( -d) : /pg/backup
[ 2025-07-13 06:16:05][ INFO] [ LOCK] lock acquired success on /tmp/backup.lock, pid = 107417
[ 2025-07-13 06:16:05][ INFO] [ BKUP] backup begin, from postgres:/// to /pg/backup/backup_pg-meta_20250713.tar.lz4
pg_basebackup: initiating base backup, waiting for checkpoint to complete
pg_basebackup: checkpoint completed
pg_basebackup: write-ahead log start point: 0/7000028 on timeline 1
pg_basebackup: write-ahead log end point: 0/7000FD8
pg_basebackup: syncing data to disk ...
pg_basebackup: base backup completed
[ 2025-07-13 06:16:06][ INFO] [ BKUP] backup complete!
[ 2025-07-13 06:16:06][ INFO] [ DONE] backup procedure complete!
[ 2025-07-13 06:16:06][ INFO] ================================================================ 备份使用 lz4 压缩。您可以使用以下命令解压并提取 tarball:
mkdir -p /tmp/data # 将备份提取到此目录
cat /pg/backup/backup_pg-meta_20250713.tar.lz4 | unlz4 -d -c | tar -xC /tmp/data
逻辑备份 您也可以使用 pg_dump 命令执行逻辑备份。
逻辑备份不能用于 PITR(时间点恢复),但对于在不同主版本之间迁移数据或实现灵活的数据导出逻辑非常有用。
从仓库引导 假设您有一个现有集群 pg-meta,想要将其克隆 为 pg-meta2:
您需要创建新的 pg-meta2 集群分支,然后在其上运行 pitr。
12.7.5 - 恢复操作 从备份恢复 PostgreSQL
您可以使用预配置的 pgbackrest 在 Pigsty 中执行时间点恢复(PITR)。
剧本方式 :使用 pgsql-pitr.yml 剧本自动执行 PITR手动方式 :使用 pg-pitr 脚本手动执行 PITR快速上手 如果您想将 pg-meta 集群回滚到之前的时间点,添加 pg_pitr 参数:
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta2
pg_pitr : { time : '2025-07-13 10:00:00+00' } # 从最新备份恢复
然后运行 pgsql-pitr.yml 剧本,它将把 pg-meta 集群回滚到指定时间点。
./pgsql-pitr.yml -l pg-meta
恢复后处理 恢复后的集群会禁用 archive_mode,以防止意外的 WAL 写入。
如果恢复后的数据库状态正常,您可以启用 archive_mode 并执行全量备份。
psql -c 'ALTER SYSTEM RESET archive_mode; SELECT pg_reload_conf();'
pg-backup full # 执行新的全量备份
恢复目标 您可以在 pg_pitr 中指定不同类型的恢复目标,但它们是互斥的:
time :恢复到哪个时间点?name :恢复到命名的恢复点(由 pg_create_restore_point 创建)xid :恢复到特定的事务 ID(TXID/XID)lsn :恢复到特定的 LSN(日志序列号)点如果指定了上述任何参数,恢复 类型 会相应设置,
否则将设置为 latest(WAL 归档流的末尾)。
特殊的 immediate 类型可用于指示 pgbackrest 通过在第一个一致点停止来最小化恢复时间。
目标类型
恢复目标类型
latest
time
lsn
xid
name
immediate pg_pitr : { } # 恢复到最新状态(WAL 归档流末尾) pg_pitr : { time : "2025-07-13 10:00:00+00" }pg_pitr : { lsn : "0/4001C80" }pg_pitr : { xid : "250000" }pg_pitr : { name : "some_restore_point" }pg_pitr : { type : "immediate" }按时间恢复 最常用的目标是时间点;您可以指定要恢复到的时间点:
./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": { "time": "2025-12-27 15:50:00+00" }}'
时间应该是有效的 PostgreSQL TIMESTAMP 格式,建议使用 YYYY-MM-DD HH:MM:SS+TZ。
按名称恢复 您可以使用 pg_create_restore_point 创建命名恢复点:
SELECT pg_create_restore_point ( 'shit_incoming' );
然后在 PITR 中使用该命名恢复点:
./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": { "name": "shit_incoming" }}'
按 XID 恢复 如果您有一个事务意外删除了某些数据,最好的恢复方式是将数据库恢复到该事务之前的状态。
./pgsql-pitr.yml -e '{"pg_pitr": { "xid": "250000", exclusive: true }}'
您可以从监控仪表盘找到确切的事务 ID,或从 CSVLOG 中的 TXID 字段获取。
包含与排除
目标参数默认是"包含"的,这意味着恢复会包含目标点。
exclusive 标志会排除该确切目标,例如 xid 24999 将是最后一个被重放的事务。
这仅适用于 time、xid、lsn 恢复目标,详情请参阅 recovery_target_inclusive 。
按 LSN 恢复 PostgreSQL 使用 LSN (日志序列号)来标识 WAL 记录的位置。
您可以在很多地方找到它,比如 Pigsty 仪表盘的 PG LSN 面板。
./pgsql-pitr.yml -e '{"pg_pitr": { "lsn": "0/4001C80", timeline: "1" }}'
要恢复到 WAL 流中的确切位置,您还可以指定 timeline 参数(默认为 latest)
恢复来源 cluster:从哪个集群恢复?默认使用当前的 pg_cluster,您可以使用同一 pgbackrest 仓库中的任何其他集群repo:覆盖备份仓库,使用与 pgbackrest_repo 相同的格式set:默认使用 latest 备份集,但您可以通过标签指定特定的 pgbackrest 备份Pigsty 将从 pgbackrest 备份仓库恢复。如果您使用集中式备份仓库(如 MinIO/S3),
可以指定另一个 “stanza”(另一个集群的备份目录)作为恢复来源。
pg-meta2 :
hosts : { 10.10.10.11 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta2
pg_pitr : { cluster : pg-meta } # 从 pg-meta 集群备份恢复
上述配置将标记 PITR 过程使用 pg-meta stanza。
您也可以通过 CLI 参数传递 pg_pitr 参数:
./pgsql-pitr.yml -l pg-meta2 -e '{"pg_pitr": { "cluster": "pg-meta" }}'
从另一个集群 PITR 时也可以使用这些目标:
./pgsql-pitr.yml -l pg-meta2 -e '{"pg_pitr": { "cluster": "pg-meta", "time": "2025-07-14 08:00:00+00" }}'
分步执行 这种方式是半自动的,您将参与 PITR 过程以做出关键决策。
例如,此配置将把 pg-meta 集群本身恢复到指定时间点:
pg-meta :
hosts : { 10.10.10.10 : { pg_seq: 1, pg_role : primary } }
vars :
pg_cluster : pg-meta2
pg_pitr : { time : '2025-07-13 10:00:00+00' } # 从最新备份恢复
让我们逐步执行:
./pgsql-pitr.yml -l pg-meta -t down # 暂停 patroni 高可用
./pgsql-pitr.yml -l pg-meta -t pitr # 运行 pitr 过程
./pgsql-pitr.yml -l pg-meta -t up # 生成 pgbackrest 配置和恢复脚本
# down : # 停止高可用并关闭 patroni 和 postgres
# - pause : # 暂停 patroni 自动故障切换
# - stop : # 停止 patroni 和 postgres 服务
# - stop_patroni : # 停止 patroni 服务
# - stop_postgres : # 停止 postgres 服务
# pitr : # 执行 PITR 过程
# - config : # 生成 pgbackrest 配置和恢复脚本
# - restore : # 运行 pgbackrest 恢复命令
# - recovery : # 启动 postgres 并完成恢复
# - verify : # 验证恢复后的集群控制数据
# up: : # 启动 postgres / patroni 并恢复高可用
# - etcd : # 启动前清理 etcd 元数据
# - start : # 启动 patroni 和 postgres 服务
# - start_postgres : # 启动 postgres 服务
# - start_patroni : # 启动 patroni 服务
# - resume : # 恢复 patroni 自动故障切换
PITR 参数定义 pg_pitr 参数还有更多可用选项:
pg_pitr : # 定义 PITR 任务
cluster : "some_pg_cls_name" # 源集群名称
type : default # 恢复目标类型:time, xid, name, lsn, immediate, default
time : "2025-01-01 10:00:00+00" # 恢复目标:时间,与 xid, name, lsn 互斥
name : "some_restore_point" # 恢复目标:命名恢复点,与 time, xid, lsn 互斥
xid : "100000" # 恢复目标:事务 ID,与 time, name, lsn 互斥
lsn : "0/3000000" # 恢复目标:日志序列号,与 time, name, xid 互斥
timeline : latest # 目标时间线,可以是整数,默认为 latest
exclusive : false # 是否排除目标点,默认为 false
action : pause # 恢复后操作:pause, promote, shutdown
archive : false # 是否保留归档设置?默认为 false
db_exclude : [ template0, template1 ]
db_include : []
link_map :
pg_wal : '/data/wal'
pg_xact : '/data/pg_xact'
process : 4 # 并行恢复进程数
repo : {} # 恢复来源仓库
data : /pg/data # 数据恢复位置
port : 5432 # 恢复实例的监听端口
12.7.6 - 克隆数据库集群 如何利用 PITR 创建一个新的 PostgreSQL 集群,并恢复到指定时间点?
快速上手 利用 Standby Cluster 创建现有集群的在线副本 利用 PITR 创建现有集群的时间点快照 在 PITR 完成后进行善后,确保新集群的备份流程正常运行 您可以使用 PG PITR 机制克隆整个数据库集群。
重置一个集群的状态 您也可以考虑创建一个全新的空集群,然后利用 PITR,将其重置为 pg-meta 集群的特定状态。
利用这种技术,您可以将现有集群 pg-meta 的任意时间点(备份保留期内)状态克隆到一个新的集群中。
我们依然以 Pigsty 4 节点沙箱环境为例,使用以下命令将 pg-test 集群重置为 pg-meta 集群的最新状态:
./pgsql-pitr.yml -l pg-test -e '{"pg_pitr": { "cluster": "pg-meta" }}'
PITR 善后工作 当你使用 PITR 恢复一个集群后,这个新集群本身的 PITR 功能是被禁用的。
因为如果它也尝试去生成备份,归档 WAL,有可能会写脏数据之前集群的备份仓库。
因此,当你确认这个 PITR 恢复出来的新集群状态符合预期后,你需要执行以下善后工作。
升级备份仓库 Stanza,允许它接纳来自不同集群的新备份(仅当从别的集群恢复时)。 启用 archive_mode,允许新集群归档 WAL 日志(需要重启集群) 执行一个新的全量备份,确保新集群的数据被纳入(可选,也可以等 crontab 定时执行) pb stanza-upgrade
psql -c 'ALTER SYSTEM RESET archive_mode;'
pg-backup full
通过这些操作,你的新集群将从第一次全量备份开始时,拥有自己的备份历史。
如果你跳过这些步骤,新集群本身的备份将无法进行,WAL 归档也不会生效。
意味着你将无法对新集群执行任何备份或 PITR 操作。
不善后的后果 假设您在 pg-test 集群上执行了 PITR 恢复,使用了另外一个集群 pg-meta 的数据,但没有进行善后工作。
那么在下一次例行备份的时候,你会看到下面的错误:
postgres@pg-test-1:~$ pb backup
2025-12-27 10:20:29.336 P00 INFO: backup command begin 2.57.0: --annotation= pg_cluster = pg-test --compress-type= lz4 --delta --exec-id= 21034-171fb30b --expire-auto --log-level-console= info --log-level-file= info --log-path= /pg/log/pgbackrest --pg1-path= /pg/data --pg1-port= 5432 --repo1-block --repo1-bundle --repo1-bundle-limit= 20MiB --repo1-bundle-size= 128MiB --repo1-cipher-pass= <redacted> --repo1-cipher-type= aes-256-cbc --repo1-path= /pgbackrest --repo1-retention-full= 14 --repo1-retention-full-type= time --repo1-s3-bucket= pgsql --repo1-s3-endpoint= sss.pigsty --repo1-s3-key= <redacted> --repo1-s3-key-secret= <redacted> --repo1-s3-region= us-east-1 --repo1-s3-uri-style= path --repo1-storage-ca-file= /etc/pki/ca.crt --repo1-storage-port= 9000 --repo1-type= s3 --stanza= pg-test --start-fast
2025-12-27 10:20:29.357 P00 ERROR: [ 051] : PostgreSQL version 18, system-id 7588470953413201282 do not match stanza version 18, system-id 7588470974940466058
HINT: is this the correct stanza?
2025-12-27 10:20:29.357 P00 INFO: backup command end: aborted with exception [ 051]
postgres@pg-test-1:~$
WAL 日志归档被 pgBackrest 关闭了,因此也不会有 WAL 归档。
克隆一个新集群 例如,假设您有一个集群 pg-meta,现在你想要从 pg-meta 克隆一个 pg-meta2 的新集群。
您可以考虑使用 备份集群 的方式创建一个新的集群 pg-meta2。
pgBackrest 支持增量备份/还原,因此如果您已经通过物理复制拉取了 pg-meta 的数据,通常增量 PITR 还原会非常快。
pb stop --force
pb stanza-delete --force
pb start
pb stanza-create
./pgsql-rm.yml -t pg_backup -l pg-test -e pg_rm_backup = true
./pgsql.yml -t pg_backup -l pg-test
如果您想要将 pg-test 集群重置为 pg-meta 集群在 2025 年 12 月 26 日 15:30 的状态,可以使用以下命令:
./pgsql-pitr.yml -l pg-test -e '{"pg_pitr": { "cluster": "pg-meta", "time": "2025-12-27 17:50:00+08" ,archive: true }}'
当然,您也可以直接创建一个全新的集群,然后使用 pgsql-pitr.yml 剧本从 pg-meta 恢复数据到新集群 pg-meta2 并顶替新集群的数据目录。
使用这种技术,您不仅可以克隆 pg-meta 集群的最新状态,还可以克隆到任意时间点,例如:
12.8 - 数据迁移 如何将现有的 PostgreSQL 集群以最小的停机时间迁移至新的、由 Pigsty 管理的 PostgreSQL 集群?
Pigsty 内置了一个剧本 pgsql-migration.yml ,基于逻辑复制来实现在线数据库迁移。
通过预生成的自动化脚本,应用停机时间可以缩减到几秒内。但请注意,逻辑复制需要 PostgreSQL 10 以上的版本才能工作。
当然如果您有充足的停机时间预算,那么总是可以使用 pg_dump | psql 的方式进行停机迁移。
定义迁移任务 想要使用 Pigsty 提供的在线迁移剧本,您需要创建一个定义文件,来描述迁移任务的细节。
请查看任务定义文件示例作为参考: files/migration/pg-meta.yml 。
这个迁移任务要将 pg-meta.meta 在线迁移到 pg-test.test,前者称为 源集群(SRC) , 后者称为 宿集群(DST) 。
pg-meta-1 10.10.10.10 --> pg-test-1 10.10.10.11 (10.10.10.12,10.10.10.13)
基于逻辑复制的迁移以数据库为单位,您需要指定需要迁移的数据库名称,以及数据库源宿集群主节点的 IP 地址,以及超级用户的连接信息。
---
#-----------------------------------------------------------------
# PG_MIGRATION
#-----------------------------------------------------------------
context_dir : ~/migration # 迁移手册 & 脚本的放置目录
#-----------------------------------------------------------------
# SRC Cluster (旧集群)
#-----------------------------------------------------------------
src_cls : pg-meta # 源集群名称 <必填>
src_db : meta # 源数据库名称 <必填>
src_ip : 10.10.10.10 # 源集群主 IP <必填>
#src_pg: '' # 如果定义,使用此作为源 dbsu pgurl 代替:
# # postgres://{{ pg_admin_username }}@{{ src_ip }}/{{ src_db }}
# # 例如: 'postgres://dbuser_dba:DBUser.DBA@10.10.10.10:5432/meta'
#sub_conn: '' # 如果定义,使用此作为订阅连接字符串代替:
# # host={{ src_ip }} dbname={{ src_db }} user={{ pg_replication_username }}'
# # 例如: 'host=10.10.10.10 dbname=meta user=replicator password=DBUser.Replicator'
#-----------------------------------------------------------------
# DST Cluster (新集群)
#-----------------------------------------------------------------
dst_cls : pg-test # 宿集群名称 <必填>
dst_db : test # 宿数据库名称 <必填>
dst_ip : 10.10.10.11 # 宿集群主 IP <必填>
#dst_pg: '' # 如果定义,使用此作为目标 dbsu pgurl 代替:
# # postgres://{{ pg_admin_username }}@{{ dst_ip }}/{{ dst_db }}
# # 例如: 'postgres://dbuser_dba:DBUser.DBA@10.10.10.11:5432/test'
#-----------------------------------------------------------------
# PGSQL
#-----------------------------------------------------------------
pg_dbsu : postgres
pg_replication_username : replicator
pg_replication_password : DBUser.Replicator
pg_admin_username : dbuser_dba
pg_admin_password : DBUser.DBA
pg_monitor_username : dbuser_monitor
pg_monitor_password : DBUser.Monitor
#-----------------------------------------------------------------
...
默认情况下,源宿集群两侧的超级用户连接串会使用全局的管理员用户和各自主库的 IP 地址拼接而成,但您总是可以通过 src_pg 和 dst_pg 参数来覆盖这些默认值。
同理,您也可以通过 sub_conn 参数来覆盖订阅连接串的默认值。
生成迁移计划 此剧本不会主动完成集群的迁移工作,但它会生成迁移所需的操作手册与自动化脚本。
默认情况下,你会在 ~/migration/pg-meta.meta 下找到迁移上下文目录。
按照 README.md 的说明,依次执行这些脚本,你就可以完成数据库迁移了!
# 激活迁移上下文:启用相关环境变量
. ~/migration/pg-meta.meta/activate
# 这些脚本用于检查 src 集群状态,并帮助在 pigsty 中生成新的集群定义
./check-user # 检查 src 用户
./check-db # 检查 src 数据库
./check-hba # 检查 src hba 规则
./check-repl # 检查 src 复制身份
./check-misc # 检查 src 特殊对象
# 这些脚本用于在现有的 src 集群和由 pigsty 管理的 dst 集群之间建立逻辑复制,除序列外的数据将实时同步
./copy-schema # 将模式复制到目标
./create-pub # 在 src 上创建发布
./create-sub # 在 dst 上创建订阅
./copy-progress # 打印逻辑复制进度
./copy-diff # 通过计数表快速比较 src 和 dst 的差异
# 这些脚本将在线迁移中运行,该迁移将停止 src 集群,复制序列号(逻辑复制不复制序列号!)
./copy-seq [ n] # 同步序列号,如果给出了 n,则会应用额外的偏移
# 你必须根据你的访问方式(dns,vip,haproxy,pgbouncer等),将应用流量切换至新的集群!
#./disable-src # 将 src 集群访问限制为管理节点和新集群(你的实现)
#./re-routing # 从 SRC 到 DST 重新路由应用流量!(你的实现)
# 然后进行清理以删除订阅和发布
./drop-sub # 迁移后在 dst 上删除订阅
./drop-pub # 迁移后在 src 上删除发布
注意事项
如果担心拷贝序列号时出现主键冲突,您可以在拷贝时将所有序列号向前推进一段距离,例如 +1000,你可以使用 ./copy-seq 加一个参数 1000 来实现这一点。
你必须实现自己的 ./re-routing 脚本,以将你的应用流量从 src 路由到 dst。 因为我们不知道你的流量是如何路由的(例如 dns, VIP, haproxy 或 pgbouncer)。 当然,您也可以手动完成这项操作…
你可以实现一个 ./disable-src 脚本来限制应用对 src 集群的访问,这是可选的:如果你能确保所有应用流量都在 ./re-routing 中干净利落地切完,其实不用这一步。
但如果您有未知来源的各种访问无法梳理干净,那么最好使用更为彻底的方式:更改 HBA 规则并重新加载来实现(推荐),或者只是简单粗暴地关停源主库上的 postgres、pgbouncer 或 haproxy 进程。
12.9 - 任务教程 如何去完成单个任务。每个任务页面是一般通过给出若干步骤展示如何执行完成某事。
12.9.1 - 故障排查 常见故障与分析排查思路
本文档列举了 PostgreSQL 和 Pigsty 中可能出现的故障,以及定位、处理、分析问题的 SOP。
磁盘空间写满 磁盘空间写满是最常见的故障类型。
现象 当数据库所在磁盘空间耗尽时,PostgreSQL 将无法正常工作,可能出现以下现象:数据库日志反复报错"no space left on device"(磁盘空间不足),
新数据无法写入,甚至 PostgreSQL 可能触发 PANIC 强制关闭。
Pigsty 带有 NodeFsSpaceFull 告警规则,当文件系统可用空间不足 10% 时触发告警。
使用监控系统 NODE Instance 面板查阅 FS 指标面板定位问题。
诊断 您也可以登录数据库节点,使用 df -h 查看各挂载盘符使用率,确定哪个分区被写满。
对于数据库节点,重点检查以下目录及其大小,以判断是哪个类别的文件占满了空间:
数据目录 (/pg/data/base):存放表和索引的数据文件,大量写入与临时文件需要关注WAL 目录 (如 pg/data/pg_wal):存放 PG WAL,WAL 堆积/复制槽保留是常见的磁盘写满原因。数据库日志目录 (如 pg/log):如果 PG 日志未及时轮转写大量报错写入,也可能占用大量空间。本地备份目录 (如 data/backups):使用 pgBackRest 等在本机保存备份时,也有可能撑满磁盘。如果问题出在 Pigsty 管理节点或监控节点,还需考虑:
监控数据 :VictoriaMetrics 的时序指标和 VictoriaLogs 日志存储都会占用磁盘,可检查保留策略。对象存储数据 :Pigsty 集成的 MinIO 对象存储可能会被用于 PG 备份保存。明确占用空间最大的目录后,可进一步使用 du -sh <目录> 深入查找特定大型文件或子目录。
处理 磁盘写满属于紧急问题,需立即采取措施释放空间并保证数据库继续运行。
当数据盘并未与系统盘区分时,写满磁盘可能导致 Shell 命令无法执行。这种情况下,可以删除 /pg/dummy 占位文件,释放少量应急空间以便 shell 命令恢复正常。
如果数据库由于 pg_wal 写满已经宕机,清理空间后需要重启数据库服务并仔细检查数据完整性。
事务号回卷 PostgreSQL 循环使用 32 位事务 ID (XID),耗尽时会出现"事务号回卷"故障(XID Wraparound)。
现象 第一阶段的典型征兆是 PGSQL Persist - Age Usage 面板年龄饱和度进入警告区域。
数据库日志开始出现:WARNING: database "postgres" must be vacuumed within xxxxxxxx transactions 字样的信息。
若问题持续恶化,PostgreSQL 会进入保护模式:当剩余事务 ID 不到约100万时数据库切换为只读模式;达到上限约21亿(2^31)时则拒绝任何新事务并迫使服务器停机以避免数据错误。
诊断 PostgreSQL 与 Pigsty 默认启用自动垃圾回收(AutoVacuum),因此此类故障出现通常有更深层次的根因。
常见的原因包括:超长事务(SAGE),Autovacuum 配置失当,复制槽阻塞,资源不足,存储引擎/扩展 BUG,磁盘坏块。
首先定位年龄最大的数据库,然后可通过 Pigsty PGCAT Database - Tables 面板来确认表的年龄分布。
同时查阅数据库错误日志,通常可以找到定位根因的线索。
处理 立即冻结老事务 :如果数据库尚未进入只读保护状态,立刻对受影响的库执行一次手动 VACUUM FREEZE。可以从老化最严重的表开始逐个冻结,而不是整库一起做,以加快效果。使用超级用户连接数据库,针对识别出的 relfrozenxid 最大的表运行 VACUUM FREEZE 表名;,优先冻结那些 XID 年龄最大的表元组。这样可以迅速回收大量事务 ID 空间。单用户模式救援 :如果数据库已经拒绝写入或宕机保护,此时需要启动数据库到单用户模式执行冻结操作。在单用户模式下运行 VACUUM FREEZE database_name; 对整个数据库进行冻结清理。完成后再以多用户模式重启数据库。这样做可以解除回卷锁定,让数据库重新可写。需要注意在单用户模式下操作要非常谨慎,并确保有足够的事务 ID 余量完成冻结。备用节点接管 :在某些复杂场景(例如遭遇硬件问题导致 vacuum 无法完成),可考虑提升集群中的只读备节点为主,以获取一个相对干净的环境来处理冻结。例如主库因坏块导致无法 vacuum,此时可以手动 Failover 提升备库为新的主库,再对其进行紧急 vacuum freeze。确保新主库已冻结老事务后,再将负载切回来。连接耗尽 PostgreSQL 有一个最大连接数配置 (max_connections),当客户端连接数超过此上限时,新的连接请求将被拒绝。典型现象是在应用端看到数据库无法连接,并报出类似
FATAL: remaining connection slots are reserved for non-replication superuser connections 或 too many clients already 的错误。
这表示普通连接数已用完,仅剩下保留给超管或复制的槽位
诊断 连接耗尽通常由客户端大量并发请求引起。您可以通过 PGCAT Instance / PGCAT Database / PGCAT Locks 直接查阅数据库当前的活跃会话。
并判断是什么样的查询填满了系统,并进行进一步的处理。特别需要关注是否存在大量 Idle in Transaction 状态的连接以及长时间运行的事务(以及慢查询)。
处理 杀查询 :对于已经耗尽导致业务受阻的情况,通常立即使用 pg_terminate_backend(pid) 进行紧急降压。
对于使用连接池的情况,则可以调整连接池大小参数,并执行 reload 重载的方式减少数据库层面的连接数量。
您也可以修改 max_connections 参数为更大的值,但本参数需要重启数据库后才能生效。
etcd 配额写满 etcd 配额写满将导致 PG 高可用控制面失效,无法进行配置变更。
诊断 Pigsty 在实现高可用时使用 etcd 作为分布式配置存储(DCS),etcd 自身有一个存储配额(默认约为2GB)。
当 etcd 存储用量达到配额上限时,etcd 将拒绝写入操作,报错 “etcdserver: mvcc: database space exceeded "。在这种情况下,Patroni 无法向 etcd 写入心跳或更新配置,从而导致集群管理功能失效。
解决 在 Pigsty v2.0.0 - v2.5.1 之间的版本默认受此问题影响。Pigsty v2.6.0 为部署的 etcd 新增了自动压实的配置项,如果您仅将其用于 PG 高可用租约,则常规用例下不会再有此问题。
有缺陷的存储引擎 目前,TimescaleDB 的试验性存储引擎 Hypercore 被证实存在缺陷,已经出现 VACUUM 无法回收出现 XID 回卷故障的案例。
请使用该功能的用户及时迁移至 PostgreSQL 原生表或者 TimescaleDB 默认引擎
详细介绍:《PG新存储引擎故障案例 》
12.9.2 - 误删处理 处理误删数据,误删表,误删数据库
误删数据 如果是小批量 DELETE 误操作,可以考虑使用 pg_surgery 或者 pg_dirtyread 扩展进行原地手术恢复。
-- 立即关闭此表上的 Auto Vacuum 并中止 Auto Vacuum 本表的 worker 进程
ALTER TABLE public . some_table SET ( autovacuum_enabled = off , toast . autovacuum_enabled = off );
CREATE EXTENSION pg_dirtyread ;
SELECT * FROM pg_dirtyread ( 'tablename' ) AS t ( col1 type1 , col2 type2 , ...);
如果被删除的数据已经被 VACUUM 回收,那么使用通用的误删处理流程。
误删对象 当出现 DROP/DELETE 类误操作,通常按照以下流程决定恢复方案。
确认此数据是否可以通过业务系统或其他数据系统找回,如果可以,直接从业务侧修复。 确认是否有延迟从库,如果有,推进延迟从库至误删时间点,查询出来恢复。 如果数据已经确认删除,确认备份信息,恢复范围是否覆盖误删时间点,如果覆盖,开始 PITR 确认是整集群原地 PITR 回滚 ,还是新开服务器重放,还是用从库来重放,并执行恢复策略 误删集群 如果出现整个数据库集群通过 Pigsty 管理命令被误删的情况,例如错误的执行 pgsql-rm.yml 剧本或 bin/pgsql-rm 命令。
除非您指定了 pg_rm_backup 参数为 false,否则备份会与数据库集群一起被删除。
警告 :在这种情况,您的数据将无法找回!请务必三思而后行!
建议:对于生产环境,您可以在配置清单中全局配置此参数为 false,在移除集群时保留备份。
12.9.3 - 手工恢复 在沙箱环境中按照提示脚本手动执行 PITR
您可以使用 pgsql-pitr.yml 剧本执行 PITR,但在某些情况下,您可能希望手动执行 PITR,直接使用 pgbackrest 原语实现精细的控制。
我们将使用带有 MinIO 备份仓库的 四节点沙箱 集群来演示该过程。
初始化沙箱 使用 vagrant 或 terraform 准备四节点沙箱环境,然后:
curl https://repo.pigsty.io/get | bash; cd ~/pigsty/
./configure -c full
./install
现在以管理节点上的管理员用户(或 dbsu)身份操作。
检查备份 要检查备份状态,您需要切换到 postgres 用户并使用 pb 命令:
sudo su - postgres # 切换到 dbsu: postgres 用户
pb info # 打印 pgbackrest 备份信息
pb 是 pgbackrest 的别名,会自动从 pgbackrest 配置中获取 stanza 名称。
function pb() {
local stanza = $( grep -o '\[[^][]*]' /etc/pgbackrest/pgbackrest.conf | head -n1 | sed 's/.*\[\([^]]*\)].*/\1/' )
pgbackrest --stanza= $stanza $@
}
您可以看到初始备份信息,这是一个全量备份:
root@pg-meta-1:~# pb info
stanza: pg-meta
status: ok
cipher: aes-256-cbc
db (current)
wal archive min/max (17): 000000010000000000000001/000000010000000000000007
full backup: 20250713-022731F
timestamp start/stop: 2025-07-13 02:27:31+00 / 2025-07-13 02:27:33+00
wal start/stop: 000000010000000000000004 / 000000010000000000000004
database size: 44MB, database backup size: 44MB
repo1: backup size: 8.4MB
备份完成于 2025-07-13 02:27:33+00,这是您可以恢复到的最早时间。
由于 WAL 归档处于活动状态,您可以恢复到备份之后的任何时间点,直到 WAL 结束(即现在)。
生成心跳 您可以生成一些心跳来模拟工作负载。/pg-bin/pg-heartbeat 就是用于此目的的,
它每秒向 monitor.heartbeat 表写入一个心跳时间戳。
心跳生成
alias
pgbench
output make rh # 运行心跳:ssh 10.10.10.10 'sudo -iu postgres /pg/bin/pg-heartbeat' ssh 10.10.10.10 'sudo -iu postgres /pg/bin/pg-heartbeat' cls | ts | lsn | lsn_int | txid | status | now | elapse
---------+-------------------------------+------------+-----------+------+---------+-----------------+----------
pg-meta | 2025-07-13 03:01:20.318234+00 | 0/115BF5C0 | 291239360 | 4812 | leading | 03:01:20.318234 | 00:00:00 您甚至可以向集群添加更多工作负载,让我们使用 pgbench 生成一些随机写入:
pgbench 负载
alias
pgbench
output make ri # 初始化 pgbench
make rw # 运行 pgbench 读写工作负载 pgbench -is10 postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5433/meta
while true; do pgbench -nv -P1 -c4 --rate= 64 -T10 postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5433/meta; done while true; do pgbench -nv -P1 -c4 --rate= 64 -T10 postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5433/meta; done
pgbench ( 17.5 ( Homebrew) , server 17.4 ( Ubuntu 17.4-1.pgdg24.04+2))
progress: 1.0 s, 60.9 tps, lat 7.295 ms stddev 4.219, 0 failed, lag 1.818 ms
progress: 2.0 s, 69.1 tps, lat 6.296 ms stddev 1.983, 0 failed, lag 1.397 ms
... PITR 手册 现在让我们选择一个恢复时间点,比如 2025-07-13 03:03:03+00,这是初始备份(和心跳)之后的一个时间点。
要执行手动 PITR,使用 pg-pitr 工具:
$ pg-pitr -t "2025-07-13 03:03:00+00"
它会为您生成执行恢复的指令,通常需要四个步骤:
Perform time PITR on pg-meta
[ 1. Stop PostgreSQL] ===========================================
1.1 Pause Patroni ( if there are any replicas)
$ pg pause <cls> # 暂停 patroni 自动故障切换
1.2 Shutdown Patroni
$ pt-stop # sudo systemctl stop patroni
1.3 Shutdown Postgres
$ pg-stop # pg_ctl -D /pg/data stop -m fast
[ 2. Perform PITR] ===========================================
2.1 Restore Backup
$ pgbackrest --stanza= pg-meta --type= time --target= '2025-07-13 03:03:00+00' restore
2.2 Start PG to Replay WAL
$ pg-start # pg_ctl -D /pg/data start
2.3 Validate and Promote
- If database content is ok, promote it to finish recovery, otherwise goto 2.1
$ pg-promote # pg_ctl -D /pg/data promote
[ 3. Restore Primary] ===========================================
3.1 Enable Archive Mode ( Restart Required)
$ psql -c 'ALTER SYSTEM SET archive_mode = on;'
3.1 Restart Postgres to Apply Changes
$ pg-restart # pg_ctl -D /pg/data restart
3.3 Restart Patroni
$ pt-restart # sudo systemctl restart patroni
[ 4. Restore Cluster] ===========================================
4.1 Re-Init All [ **REPLICAS**] ( if any)
- 4.1.1 option 1: restore replicas with same pgbackrest cmd ( require central backup repo)
$ pgbackrest --stanza= pg-meta --type= time --target= '2025-07-13 03:03:00+00' restore
- 4.1.2 option 2: nuke the replica data dir and restart patroni ( may take long time to restore)
$ rm -rf /pg/data/*; pt-restart
- 4.1.3 option 3: reinit with patroni, which may fail if primary lsn < replica lsn
$ pg reinit pg-meta
4.2 Resume Patroni
$ pg resume pg-meta
4.3 Full Backup ( optional)
$ pg-backup full # 建议在 PITR 后执行新的全量备份
单节点示例 让我们从简单的单节点 pg-meta 集群开始,作为一个更简单的示例。
关闭数据库
关闭服务
shutdown patroni
shutdown postgres pt-stop # sudo systemctl stop patroni,关闭 patroni(和 postgres) # 可选,因为如果 patroni 未暂停,postgres 会被 patroni 关闭
$ pg_stop # pg_ctl -D /pg/data stop -m fast,关闭 postgres
pg_ctl: PID file "/pg/data/postmaster.pid" does not exist
Is server running?
$ pg-ps # 打印 postgres 相关进程
UID PID PPID C STIME TTY STAT TIME CMD
postgres 31048 1 0 02:27 ? Ssl 0:19 /usr/sbin/pgbouncer /etc/pgbouncer/pgbouncer.ini
postgres 32026 1 0 02:28 ? Ssl 0:03 /usr/bin/pg_exporter ...
postgres 35510 35480 0 03:01 pts/2 S+ 0:00 /bin/bash /pg/bin/pg-heartbeat 确保本地 postgres 没有运行,然后执行手册中给出的恢复命令:
恢复备份 pgbackrest --stanza= pg-meta --type= time --target= '2025-07-13 03:03:00+00' restore postgres@pg-meta-1:~$ pgbackrest --stanza= pg-meta --type= time --target= '2025-07-13 03:03:00+00' restore
2025-07-13 03:17:07.443 P00 INFO: restore command begin 2.54.2: ...
2025-07-13 03:17:07.470 P00 INFO: repo1: restore backup set 20250713-022731F, recovery will start at 2025-07-13 02:27:31
2025-07-13 03:17:07.471 P00 INFO: remove invalid files/links/paths from '/pg/data'
2025-07-13 03:17:08.523 P00 INFO: write updated /pg/data/postgresql.auto.conf
2025-07-13 03:17:08.527 P00 INFO: restore size = 44MB, file total = 1436
2025-07-13 03:17:08.527 P00 INFO: restore command end: completed successfully ( 1087ms) 验证数据 我们不希望 patroni HA 接管,直到确定数据正确,所以手动启动 postgres:
验证数据
start postgres
output waiting for server to start....2025-07-13 03:19:33.133 UTC [ 39294] LOG: redirecting log output to logging collector process
2025-07-13 03:19:33.133 UTC [ 39294] HINT: Future log output will appear in directory "/pg/log/postgres" .
done
server started 现在您可以检查数据,看看是否处于您想要的时间点。
您可以通过检查业务表中的最新时间戳来验证,或者在本例中通过心跳表检查。
postgres@pg-meta-1:~$ psql -c 'table monitor.heartbeat'
id | ts | lsn | txid
---------+-------------------------------+-----------+------
pg-meta | 2025-07-13 03:02:59.214104+00 | 302005504 | 4912
时间戳正好在我们指定的时间点之前!(2025-07-13 03:03:00+00)。
如果这不是您想要的时间点,可以使用不同的时间点重复恢复。
由于恢复是以增量和并行方式执行的,速度非常快。
可以重试直到找到正确的时间点。
提升主库 恢复后的 postgres 集群处于 recovery 模式,因此在提升为主库之前会拒绝任何写操作。
这些恢复参数是由 pgBackRest 在配置文件中生成的。
postgres@pg-meta-1:~$ cat /pg/data/postgresql.auto.conf
# Do not edit this file or use ALTER SYSTEM manually!
# It is managed by Pigsty & Ansible automatically!
# Recovery settings generated by pgBackRest restore on 2025-07-13 03:17:08
archive_mode = 'off'
restore_command = 'pgbackrest --stanza=pg-meta archive-get %f "%p"'
recovery_target_time = '2025-07-13 03:03:00+00'
如果数据正确,您可以提升 它为主库,将其标记为新的领导者并准备接受写入。
pg-promote
waiting for server to promote.... done
server promoted psql -c 'SELECT pg_is_in_recovery()' # 'f' 表示已提升为主库
pg_is_in_recovery
-------------------
f
( 1 row) 新时间线和脑裂
一旦提升,数据库集群将进入新的时间线(领导者纪元)。
如果有任何写流量,将写入新的时间线。
恢复集群 最后,不仅需要恢复数据,还需要恢复集群状态,例如:
Patroni 接管 您的 postgres 是直接启动的,要恢复 HA 接管,您需要启动 patroni 服务:
Patroni 接管
launch patroni
resume patroni pt-start # sudo systemctl start patroni pg resume pg-meta # 恢复 patroni 自动故障切换(如果之前暂停过) 归档模式 archive_mode 在恢复期间被 pgbackrest 禁用。
如果您希望新领导者的写入归档到备份仓库,还需要启用 archive_mode 配置。
归档模式
check archive_mode
reset archive_mode
edit directly psql -c 'show archive_mode'
archive_mode
--------------
off psql -c 'ALTER SYSTEM RESET archive_mode;'
psql -c 'SELECT pg_reload_conf();'
psql -c 'show archive_mode' # 您也可以直接编辑 postgresql.auto.conf 并使用 pg_ctl 重载
sed -i '/archive_mode/d' /pg/data/postgresql.auto.conf
pg_ctl -D /pg/data reload 备份集 通常建议在 PITR 后执行新的全量备份,但这是可选的。
从库 如果您的 postgres 集群有从库,您也需要在每个从库上执行 PITR。
或者,更简单的方法是删除从库数据目录并重启 patroni,这将从主库重新初始化从库。
我们将在下一个多节点集群示例中介绍这种情况。
多节点示例 现在让我们以三节点 pg-test 集群作为 PITR 示例。
12.9.4 - 利用 xfs 实现实例 Fork 在同一台机器上克隆实例并执行时间点恢复
Pigsty 提供了两个实用脚本,用于在同一台机器上快速克隆实例并执行时间点恢复:
这两个脚本可以配合使用:先用 pg-fork 克隆实例,再用 pg-pitr 将克隆实例恢复到指定时间点。
pg-fork pg-fork 可以在同一台机器上快速克隆一个新的 PostgreSQL 实例。
快速上手 使用 postgres 用户(dbsu)执行以下命令,即可创建一个新的实例:
pg-fork 1 # 从 /pg/data 克隆到 /pg/data1,端口 15432
pg-fork 2 -d /pg/data1 # 从 /pg/data1 克隆到 /pg/data2,端口 25432
pg-fork 3 -D /tmp/test -P 5555 # 克隆到自定义目录和端口
克隆完成后,可以启动并访问新实例:
pg_ctl -D /pg/data1 start # 启动克隆实例
psql -p 15432 # 连接克隆实例
命令语法 pg-fork <FORK_ID> [ options]
必填参数:
参数 说明 <FORK_ID>克隆实例编号(1-9),决定默认端口和数据目录
可选参数:
参数 说明 默认值 -d, --data <datadir>源实例数据目录 /pg/data 或 $PG_DATA-D, --dst <dst_dir>目标数据目录 /pg/data<FORK_ID>-p, --port <port>源实例端口 5432 或 $PG_PORT-P, --dst-port <port>目标实例端口 <FORK_ID>5432-s, --skip跳过备份 API,使用冷拷贝模式 - -y, --yes跳过确认提示 - -h, --help显示帮助信息 -
使用示例
pg-fork 示例
基础克隆
指定源端口
链式克隆
自定义位置
冷拷贝模式 # 从默认实例克隆到 /pg/data1,端口 15432
pg-fork 1
# 从默认实例克隆到 /pg/data2,端口 25432
pg-fork 2 # 从端口 5433 的实例克隆
pg-fork 1 -p 5433
# 使用环境变量指定源端口
PG_PORT = 5433 pg-fork 1 # 从 /pg/data1 克隆到 /pg/data2
pg-fork 2 -d /pg/data1
# 从 /pg/data2 克隆到 /pg/data3
pg-fork 3 -d /pg/data2 # 克隆到自定义目录和端口
pg-fork 1 -D /tmp/pgtest -P 5555
# 完全自定义
pg-fork 1 -d /pg/data -D /mnt/backup/pgclone -P 6543 # 源实例已停止时使用冷拷贝
pg-fork 1 -s
# 跳过确认直接执行
pg-fork 1 -s -y 工作原理 pg-fork 支持两种工作模式:
热备份模式 (默认,源实例运行中):
调用 pg_backup_start() 开始备份 使用 cp --reflink=auto 拷贝数据目录 调用 pg_backup_stop() 结束备份 修改配置文件,避免与源实例冲突 冷拷贝模式 (使用 -s 参数或源实例未运行):
直接使用 cp --reflink=auto 拷贝数据目录 修改配置文件 CoW 快速克隆
如果您使用 XFS(启用 reflink)、Btrfs 或 ZFS 文件系统,pg-fork 会利用 Copy-on-Write 特性,
数据目录拷贝在几百毫秒内完成,且几乎不占用额外存储空间。只有在数据被修改时才会分配新的存储块。
克隆后配置 pg-fork 会自动修改克隆实例的以下配置:
配置项 修改内容 port改为目标端口(避免冲突) archive_mode设为 off(避免污染 WAL 归档) log_directory设为 log(使用数据目录下的日志) primary_conninfo移除(创建独立实例) standby.signal移除(创建独立实例) pg_replslot/*清空(避免复制槽冲突)
典型工作流 # 1. 克隆实例用于测试
pg-fork 1 -y
# 2. 启动克隆实例
pg_ctl -D /pg/data1 start
# 3. 在克隆实例上测试(不影响生产)
psql -p 15432 -c "DROP TABLE important_data;" # 安全测试
# 4. 测试完成后清理
pg_ctl -D /pg/data1 stop
rm -rf /pg/data1
pg-pitr pg-pitr 是一个用于手动执行时间点恢复的脚本,基于 pgbackrest。
快速上手 pg-pitr -d # 恢复到最新状态
pg-pitr -i # 恢复到备份完成时间
pg-pitr -t "2025-01-01 12:00:00+08" # 恢复到指定时间点
pg-pitr -n my-savepoint # 恢复到命名恢复点
pg-pitr -l "0/7C82CB8" # 恢复到指定 LSN
pg-pitr -x 12345678 -X # 恢复到事务之前
pg-pitr -b 20251225-120000F # 恢复到指定备份集
命令语法 pg-pitr [ options] [ recovery_target]
恢复目标(选择一个):
参数 说明 -d, --default恢复到 WAL 归档流末尾(最新状态) -i, --immediate恢复到数据库一致性点(最快恢复) -t, --time <timestamp>恢复到指定时间点 -n, --name <restore_point>恢复到命名恢复点 -l, --lsn <lsn>恢复到指定 LSN -x, --xid <xid>恢复到指定事务 ID -b, --backup <label>恢复到指定备份集
可选参数:
参数 说明 默认值 -D, --data <path>恢复目标数据目录 /pg/data-s, --stanza <name>pgbackrest stanza 名称 自动检测 -X, --exclusive排除目标点(恢复到目标之前) - -P, --promote恢复后自动提升(默认暂停) - -c, --check干运行模式,仅打印命令 - -y, --yes跳过确认和倒计时 - -h, --help显示帮助信息 -
恢复目标类型
恢复目标
latest
immediate
time
name
lsn
xid
backup # 恢复到 WAL 归档流末尾(最新状态)
pg-pitr -d
# 这是默认行为,会重放所有可用的 WAL # 恢复到数据库一致性点
pg-pitr -i
# 最快的恢复方式,不重放额外的 WAL
# 适用于快速验证备份是否可用 # 恢复到指定时间点
pg-pitr -t "2025-01-01 12:00:00+08"
# 使用 UTC 时间
pg-pitr -t "2025-01-01 04:00:00+00"
# 时间格式:YYYY-MM-DD HH:MM:SS[.usec][+/-TZ] # 恢复到命名恢复点
pg-pitr -n my-savepoint
# 恢复点需要事先使用 pg_create_restore_point() 创建
# SELECT pg_create_restore_point('my-savepoint'); # 恢复到指定 LSN
pg-pitr -l "0/7C82CB8"
# LSN 可以从监控面板或 pg_current_wal_lsn() 获取 # 恢复到指定事务 ID
pg-pitr -x 12345678
# 恢复到事务之前(不包含该事务)
pg-pitr -x 12345678 -X # 恢复到指定备份集
pg-pitr -b 20251225-120000F
# 查看可用备份集
pgbackrest info 使用示例 恢复到指定时间点:
# 1. 停止 PostgreSQL
pg_ctl -D /pg/data stop -m fast
# 2. 执行 PITR
pg-pitr -t "2025-12-27 10:00:00+08"
# 3. 启动并验证
pg_ctl -D /pg/data start
psql -c "SELECT * FROM important_table;"
# 4. 确认无误后提升
pg_ctl -D /pg/data promote
# 5. 启用归档并执行新备份
psql -c "ALTER SYSTEM SET archive_mode = on;"
pg_ctl -D /pg/data restart
pg-backup full
恢复到克隆实例:
# 1. 克隆实例
pg-fork 1 -y
# 2. 在克隆实例上执行 PITR
pg-pitr -D /pg/data1 -t "2025-12-27 10:00:00+08"
# 3. 启动克隆实例验证
pg_ctl -D /pg/data1 start
psql -p 15432
干运行模式:
# 仅打印命令,不执行
pg-pitr -t "2025-12-27 10:00:00+08" -c
# 输出示例:
# Command:
# pgbackrest --stanza=pg-meta --delta --force --type=time --target="2025-12-27 10:00:00+08" restore
恢复后处理 恢复完成后,实例会处于恢复暂停 状态(除非使用 -P 参数)。您需要:
启动实例 :pg_ctl -D /pg/data start验证数据 :检查数据是否符合预期提升实例 :pg_ctl -D /pg/data promote启用归档 :psql -c "ALTER SYSTEM SET archive_mode = on;"重启实例 :pg_ctl -D /pg/data restart执行备份 :pg-backup full重要提示
恢复后的实例 archive_mode 被设为 off,以防止意外的 WAL 写入污染归档仓库。
确认数据正确后,务必重新启用归档并执行全量备份。
组合使用 pg-fork 和 pg-pitr 可以组合使用,实现安全的 PITR 验证流程:
# 1. 克隆当前实例
pg-fork 1 -y
# 2. 在克隆实例上执行 PITR(不影响生产)
pg-pitr -D /pg/data1 -t "2025-12-27 10:00:00+08"
# 3. 启动克隆实例
pg_ctl -D /pg/data1 start
# 4. 验证恢复结果
psql -p 15432 -c "SELECT count(*) FROM orders WHERE created_at < '2025-12-27 10:00:00';"
# 5. 确认无误后,可以选择:
# - 方案A:在生产实例上执行相同的 PITR
# - 方案B:将克隆实例提升为新的生产实例
# 6. 清理测试实例
pg_ctl -D /pg/data1 stop
rm -rf /pg/data1
注意事项 运行要求 必须以 postgres 用户(或 postgres 组成员)执行 pg-pitr 执行前必须停止目标实例的 PostgreSQLpg-fork 热备份模式需要源实例正在运行文件系统 推荐使用 XFS(启用 reflink)或 Btrfs 文件系统 CoW 文件系统上克隆几乎瞬间完成,且不占用额外空间 非 CoW 文件系统会执行完整拷贝,耗时较长 端口规划 FORK_ID 默认端口 默认数据目录 1 15432 /pg/data1 2 25432 /pg/data2 3 35432 /pg/data3 … … … 9 95432 /pg/data9
安全建议 克隆实例仅用于测试和验证,不应长期运行 验证完成后及时清理克隆实例 生产环境 PITR 建议使用 pgsql-pitr.yml 剧本 重要操作前先使用 -c 干运行模式确认命令 原理剖析 有时候,您想要用现有的 PostgreSQL 实例在 同一台机器 上创建一个新的实例 (用于测试,PITR 恢复),可以使用 postgres 用户执行下面的命令:
psql <<EOF
CHECKPOINT;
SELECT pg_backup_start('pgfork', true);
\! rm -rf /pg/data2 && cp -r --reflink=auto /pg/data /pg/data2 && ls -alhd /pg/data2
SELECT * FROM pg_backup_stop(false);
EOF
# 修改配置,避免与现有实例冲突:端口,日志,归档等
sed -i 's/^port.*/port = 5431/' /pg/data2/postgresql.conf;
sed -i 's/^log_destination.*/log_destination = stderr/' /pg/data2/postgresql.conf;
sed -i 's/^archive_mode.*/archive_mode = off/' /pg/data2/postgresql.conf;
rm -rf /pg/data2/postmaster.pid /pg/data2/postmaster.opts
pg_ctl -D /pg/data2 start -l /pg/log/pgfork.log
pg_ctl -D /pg/data2 stop
psql -p 5431 # 访问新实例
上面的命令会创建一个新的数据目录 /pg/data2,它是现有数据目录 /pg/data 的一个完整拷贝。
如果您使用的是 XFS (启用了 reflink COW 特性),那么同磁盘拷贝目录会非常快,通常几百毫秒的常数时间内即可完成。
您在原地拉起新实例前,务必 修改 postgresql.conf 里的 port / archive_mode / log_destination 参数,避免影响现有生产实例等运行。
您可以使用一个没有被占用的端口,例如 5431,并将日志输出到 /pg/log/xxxx.log 避免写脏现有实例的日志文件。
我们建议同时修改 shared_buffers Pigsty 默认情况通常分配 25% 的系统内存给 PostgreSQL 实例,
开启新实例时,会与现有实例争夺内存资源。您可以适当调小,以减小对现有生产实例的影响。
12.9.5 - 为 PostgreSQL 集群启用 HugePage 为 PostgreSQL 集群启用大页,减少大内存实例的页表开销并提高性能
使用 node_hugepage_count 和 node_hugepage_ratio 或 /pg/bin/pg-tune-hugepage
如果你计划启用大页(HugePage),请考虑使用 node_hugepage_count 和 node_hugepage_ratio ,并配合 ./node.yml -t node_tune 进行应用。
大页对于数据库来说有利有弊,利是内存是专门管理的,不用担心被挪用,降低数据库 OOM 风险。缺点是某些场景下可能对性能由负面影响。
在 PostgreSQL 启动前,您需要分配 足够多的 大页,浪费的部分可以使用 pg-tune-hugepage 脚本对其进行回收,不过此脚本仅 PostgreSQL 15+ 可用。
如果你的 PostgreSQL 已经在运行,你可以使用下面的办法启动大页(仅 PG15+ 可用):
sync; echo 3 > /proc/sys/vm/drop_caches # 刷盘,释放系统缓存(请做好数据库性能受到冲击的准备)
sudo /pg/bin/pg-tune-hugepage # 将 nr_hugepages 写入 /etc/sysctl.d/hugepage.conf
pg restart <cls> # 重启 postgres 以使用 hugepage
12.9.6 - 3坏2应急处理 高可用典型场景处理预案:三节点坏了两个节点,高可用不生效了,怎么从紧急状态中恢复?
如果经典3节点高可用部署同时出现两台(多数主体)故障,系统通常无法自动完成故障切换,需要人工介入:
首先判断另外两台服务器的情况,如果短时间内可以拉起,优先选择拉起另外两台服务。否则进入 紧急止血流程
紧急止血流程假设您的管理节点故障 ,只有单台普通数据库节点存活,在这种情况下,最快的恢复操作流程为:
调整 HAProxy 配置,将流量指向主库。 关闭 Patroni,手动提升 PostgreSQL 从库为主库。 调整HAProxy配置 如果你通过其他方式绕开 HAProxy 访问集群,那么可以跳过这一步。
如果你通过 HAProxy 方式访问数据库集群,那么你需要调整负载均衡配置,将读写流量手工指向主库。
编辑 /etc/haproxy/<pg_cluster>-primary.cfg 配置文件,其中 <pg_cluster> 为你的 PostgreSQL 集群名称,例如 pg-meta。 将健康检查配置选项注释,停止进行健康鉴擦好 将服务器列表中,其他两台故障的机器注释掉,只保留当前主库服务器。 listen pg-meta-primary
bind *:5433
mode tcp
maxconn 5000
balance roundrobin
# 注释掉以下四行健康检查配置
#option httpchk # <---- remove this
#option http-keep-alive # <---- remove this
#http-check send meth OPTIONS uri /primary # <---- remove this
#http-check expect status 200 # <---- remove this
default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
server pg-meta-1 10.10.10.10:6432 check port 8008 weight 100
# 注释掉其他两台故障的机器
#server pg-meta-2 10.10.10.11:6432 check port 8008 weight 100 <---- comment this
#server pg-meta-3 10.10.10.12:6432 check port 8008 weight 100 <---- comment this
配置调整完成后,先不着急执行 systemctl reload haproxy 重载生效,等待后续主库提升后一起执行。
以上配置的效果是,HAProxy 将不再进行主库健康检查(默认使用 Patroni),而是直接将写入流量指向当前主库
手工提升备库 登陆目标服务器,切换至 dbsu 用户,执行 CHECKPOINT 刷盘后,关闭 Patroni,重启 PostgreSQL 并执行 Promote。
sudo su - postgres # 切换到数据库 dbsu 用户
psql -c 'checkpoint; checkpoint;' # 两次 Checkpoint 刷脏页,避免PG后重启耗时过久
sudo systemctl stop patroni # 关闭 Patroni
pg-restart # 重新拉起 PostgreSQL
pg-promote # 将 PostgreSQL 从库提升为主库
psql -c 'SELECT pg_is_in_recovery();' # 如果结果为 f,表示已经提升为主库
如果你上面调整了 HAProxy 配置,那么现在可以执行 systemctl reload haproxy 重载 HAProxy 配置,将流量指向新的主库。
systemctl reload haproxy # 重载 HAProxy 配置,将写入流量指向当前实例
避免脑裂 紧急止血后,第二优先级问题为:避免脑裂 。用户应当防止另外两台服务器重新上线后,与当前主库形成脑裂,导致数据不一致。
简单的做法是:
将另外两台服务器直接 断电/断网 ,确保它们不会在不受控的情况下再次上线。 调整应用使用的数据库连接串,将其 HOST 直接指向唯一幸存服务器上的主库。 然后应当根据具体情况,决定下一步的操作:
A:这两台服务器是临时故障(比如断网断电),可以原地修复后继续服务 B:这两台故障服务器是永久故障(比如硬件损坏),将移除并下线。 临时故障后的复原 如果另外两台服务器是临时故障,可以修复后继续服务,那么可以按照以下步骤进行修复与重建:
每次处理一台故障服务器,优先处理 管理节点 / INFRA 管理节点 启动故障服务器,并在启动后关停 Patroni ETCD 集群在法定人数恢复后,将恢复工作,此时可以启动幸存服务器(当前主库)上的 Patroni,接管现有 PostgreSQL,并重新获取集群领导者身份。
Patroni 启动后进入维护模式。
systemctl restart patroni
pg pause <pg_cluster>
在另外两台实例上以 postgres 用户身份创建 touch /pg/data/standby.signal 标记文件将其标记为从库,然后拉起 Patroni:
systemctl restart patroni
确认 Patroni 集群身份/角色正常后,退出维护模式:
永久故障后的复原 出现永久故障后,首先需要恢复管理节点上的 ~/pigsty 目录,主要是需要 pigsty.yml 与 files/pki/ca/ca.key 两个核心文件。
如果您无法取回或没有备份这两个文件,您可以选择部署一套新的 Pigsty,并通过 备份集群 的方式将现有集群迁移至新部署中。
请定期备份 pigsty 目录(例如使用 Git 进行版本管理)。建议吸取教训,下次不要犯这样的错误。
配置修复 您可以将幸存的节点作为新的管理节点,将 ~/pigsty 目录拷贝到新的管理节点上,然后开始调整配置。
例如,将原本默认的管理节点 10.10.10.10 替换为幸存节点 10.10.10.12
all :
vars :
admin_ip : 10.10.10.12 # 使用新的管理节点地址
node_etc_hosts : [ 10.10.10.12 h.pigsty a.pigsty p.pigsty g.pigsty sss.pigsty]
infra_portal : {} # 一并修改其他引用旧管理节点 IP (10.10.10.10) 的配置
children :
infra : # 调整 Infra 集群
hosts :
# 10.10.10.10: { infra_seq: 1 } # 老的 Infra 节点
10.10.10.12 : { infra_seq : 3 } # 新增 Infra 节点
etcd : # 调整 ETCD 集群
hosts :
#10.10.10.10: { etcd_seq: 1 } # 注释掉此故障节点
#10.10.10.11: { etcd_seq: 2 } # 注释掉此故障节点
10.10.10.12 : { etcd_seq : 3 } # 保留幸存节点
vars :
etcd_cluster : etcd
pg-meta : # 调整 PGSQL 集群配置
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 , pg_offline_query: true }
10.10.10.12 : { pg_seq: 3, pg_role: primary , pg_offline_query : true }
vars :
pg_cluster : pg-meta
ETCD修复 然后执行以下命令,将 ETCD 重置为单节点集群:
./etcd.yml -e etcd_safeguard = false -e etcd_clean = true
根据 ETCD重载配置 的说明,调整对 ETCD Endpoint 的引用。
INFRA修复 如果幸存节点上没有 INFRA 模块,请在当前节点上配置新的 INFRA 模块并安装。执行以下命令,将 INFRA 模块部署到幸存节点上:
./infra.yml -l 10.10.10.12
修复当前节点的监控
./node.yml -t node_monitor
PGSQL修复 ./pgsql.yml -t pg_conf # 重新生成 PG 配置文件
systemctl reload patroni # 在幸存节点上重载 Patroni 配置
各模块修复后,您可以参考标准扩容流程,将新的节点加入集群,恢复集群的高可用性。
12.9.7 - 使用 VIP-Manager 为 PostgreSQL 集群配置二层 VIP 您可以在 PostgreSQL 集群上绑定一个可选的 L2 VIP —— 前提条件是:集群中的所有节点都在一个二层网络中。
这个 L2 VIP 强制使用 Master - Backup 模式,Master 始终指向在数据库集群主库实例所在的节点。
这个 VIP 由 VIP-Manager 组件管理,它会从 DCS (etcd) 中直接读取由 Patroni 写入的 Leader Key,从而判断自己是否是 Master。
启用VIP 在 PostgreSQL 集群上定义 pg_vip_enabled 参数为 true,即可在集群上启用 VIP 组件。当然您也可以在全局配置中启用此配置项。
# pgsql 3 node ha cluster: pg-test
pg-test:
hosts:
10.10.10.11: { pg_seq: 1, pg_role: primary } # primary instance, leader of cluster
10.10.10.12: { pg_seq: 2, pg_role: replica } # replica instance, follower of leader
10.10.10.13: { pg_seq: 3, pg_role: replica, pg_offline_query: true } # replica with offline access
vars:
pg_cluster: pg-test # define pgsql cluster name
pg_users: [{ name: test , password: test , pgbouncer: true , roles: [ dbrole_admin ] }]
pg_databases: [{ name: test }]
# 启用 L2 VIP
pg_vip_enabled: true
pg_vip_address: 10.10.10.3/24
pg_vip_interface: eth1
请注意,pg_vip_address 必须是一个合法的 IP 地址,带有网段,且在当前二层网络中可用。
请注意,pg_vip_interface 必须是一个合法的网络接口名,并且应当是与 inventory 中使用 IPv4 地址一致的网卡。
如果集群成员的网卡名不一样,用户应当为每个实例显式指定 pg_vip_interface 参数,例如:
pg-test :
hosts :
10.10.10.11 : { pg_seq: 1, pg_role: primary , pg_vip_interface : eth0 }
10.10.10.12 : { pg_seq: 2, pg_role: replica , pg_vip_interface : eth1 }
10.10.10.13 : { pg_seq: 3, pg_role: replica , pg_vip_interface : ens33 }
vars :
pg_cluster : pg-test # define pgsql cluster name
pg_users : [ { name: test , password: test , pgbouncer: true , roles : [ dbrole_admin ] }]
pg_databases : [ { name : test }]
# 启用 L2 VIP
pg_vip_enabled : true
pg_vip_address : 10.10.10.3 /24
#pg_vip_interface: eth1
使用以下命令,刷新 PG 的 vip-manager 配置并重启生效:
12.9.8 - Citus 集群部署 如何部署 Citus 高可用分布式集群?
Citus 是一个 PostgreSQL 扩展,可以将 PostgreSQL 原地转换为一个分布式数据库,并实现在多个节点上水平扩展,以处理大量数据和大量查询。
Patroni 在 v3.0 后,提供了对 Citus 原生高可用的支持,简化了 Citus 集群的搭建,Pigsty 也对此提供了原生支持。
注意:Citus 13.x 支持 PostgreSQL 18、17、16、15、14 五个大版本。Pigsty 扩展仓库提供了 Citus ARM64 软件包。
Citus集群 Pigsty 原生支持 Citus。可以参考 conf/citus.yml
这里使用 Pigsty 四节点沙箱,定义了一个 Citus 集群 pg-citus,其中包括一个两节点的协调者集群 pg-citus0,
以及两个 Worker 集群 pg-citus1,pg-citus2。
pg-citus :
hosts :
10.10.10.10 : { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.2/24 ,pg_seq: 1, pg_role : primary }
10.10.10.11 : { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.2/24 ,pg_seq: 2, pg_role : replica }
10.10.10.12 : { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.3/24 ,pg_seq: 1, pg_role : primary }
10.10.10.13 : { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.4/24 ,pg_seq: 1, pg_role : primary }
vars :
pg_mode: citus # pgsql cluster mode : citus
pg_version : 18 # citus 13.x supports PG 14-18
pg_shard: pg-citus # citus shard name : pg-citus
pg_primary_db : citus # primary database used by citus
pg_vip_enabled : true # enable vip for citus cluster
pg_vip_interface : eth1 # vip interface for all members
pg_dbsu_password : DBUser.Postgres # all dbsu password access for citus cluster
pg_extensions : [ citus, postgis, pgvector, topn, pg_cron, hll ] # install these extensions
pg_libs : 'citus, pg_cron, pg_stat_statements' # citus will be added by patroni automatically
pg_users : [ { name: dbuser_citus ,password: DBUser.Citus ,pgbouncer: true ,roles : [ dbrole_admin ] }]
pg_databases : [ { name: citus ,owner: dbuser_citus ,extensions : [ citus, vector, topn, pg_cron, hll ] }]
pg_parameters :
cron.database_name : citus
citus.node_conninfo : 'sslmode=require sslrootcert=/pg/cert/ca.crt sslmode=verify-full'
pg_hba_rules :
- { user: 'all' ,db: all ,addr: 127.0.0.1/32 ,auth: ssl ,title : 'all user ssl access from localhost' }
- { user: 'all' ,db: all ,addr: intra ,auth: ssl ,title : 'all user ssl access from intranet' }
相比标准 PostgreSQL 集群,Citus 集群的配置有一些特殊之处,首先,你需要确保 Citus 扩展被下载,安装,加载并启用,这涉及到以下四个参数
其次,你需要确保 Citus 集群的配置正确:
配置完成后,您可以像创建普通 PostgreSQL 集群一样,使用 pgsql.yml 部署 Citus 集群。
管理Citus集群 定义好 Citus 集群后,部署 Citus 集群同样使用的剧本 pgsql.yml:
./pgsql.yml -l pg-citus # 部署 Citus 集群 pg-citus
使用任意成员的 DBSU(postgres)用户,都能通过 patronictl (alias: pg) 列出 Citus 集群的状态:
$ pg list
+ Citus cluster: pg-citus ----------+---------+-----------+----+-----------+--------------------+
| Group | Member | Host | Role | State | TL | Lag in MB | Tags |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+
| 0 | pg-citus0-1 | 10.10.10.10 | Leader | running | 1 | | clonefrom: true |
| | | | | | | | conf: tiny.yml |
| | | | | | | | spec: 20C.40G.125G |
| | | | | | | | version: '16' |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+
| 1 | pg-citus1-1 | 10.10.10.11 | Leader | running | 1 | | clonefrom: true |
| | | | | | | | conf: tiny.yml |
| | | | | | | | spec: 10C.20G.125G |
| | | | | | | | version: '16' |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+
| 2 | pg-citus2-1 | 10.10.10.12 | Leader | running | 1 | | clonefrom: true |
| | | | | | | | conf: tiny.yml |
| | | | | | | | spec: 10C.20G.125G |
| | | | | | | | version: '16' |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+
| 2 | pg-citus2-2 | 10.10.10.13 | Replica | streaming | 1 | 0 | clonefrom: true |
| | | | | | | | conf: tiny.yml |
| | | | | | | | spec: 10C.20G.125G |
| | | | | | | | version: '16' |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+
您可以将每个水平分片集群视为一个独立的 PGSQL 集群,使用 pg (patronictl) 命令管理它们。
但是务必注意,当你使用 pg 命令管理 Citus 集群时,需要额外使用 --group 参数指定集群分片号
pg list pg-citus --group 0 # 需要使用 --group 0 指定集群分片号
Citus 中有一个名为 pg_dist_node 的系统表,用于记录 Citus 集群的节点信息,Patroni 会自动维护该表。
PGURL = postgres://postgres:DBUser.Postgres@10.10.10.10/citus
psql $PGURL -c 'SELECT * FROM pg_dist_node;' # 查看节点信息
nodeid | groupid | nodename | nodeport | noderack | hasmetadata | isactive | noderole | nodecluster | metadatasynced | shouldhaveshards
--------+---------+-------------+----------+----------+-------------+----------+-----------+-------------+----------------+------------------
1 | 0 | 10.10.10.10 | 5432 | default | t | t | primary | default | t | f
4 | 1 | 10.10.10.12 | 5432 | default | t | t | primary | default | t | t
5 | 2 | 10.10.10.13 | 5432 | default | t | t | primary | default | t | t
6 | 0 | 10.10.10.11 | 5432 | default | t | t | secondary | default | t | f
此外,你还可以查看用户认证信息(仅限超级用户访问):
$ psql $PGURL -c 'SELECT * FROM pg_dist_authinfo;' # 查看节点认证信息(仅限超级用户访问)
然后,你可以使用普通业务用户(例如,具有 DDL 权限的 dbuser_citus)来访问 Citus 集群:
psql postgres://dbuser_citus:DBUser.Citus@10.10.10.10/citus -c 'SELECT * FROM pg_dist_node;'
使用Citus集群 在使用 Citus 集群时,我们强烈建议您先阅读 Citus 官方文档 ,了解其架构设计与核心概念。
其中核心是了解 Citus 中的五种表,以及其特点与应用场景:
分布式表(Distributed Table) 参考表(Reference Table) 本地表(Local Table) 本地管理表(Local Management Table) 架构表(Schema Table) 在协调者节点上,您可以创建分布式表和引用表,并从任何数据节点查询它们。从 11.2 开始,任何 Citus 数据库节点都可以扮演协调者的角色了。
我们可以使用 pgbench 来创建一些表,并将其中的主表(pgbench_accounts)分布到各个节点上,然后将其他小表作为引用表:
PGURL = postgres://dbuser_citus:DBUser.Citus@10.10.10.10/citus
pgbench -i $PGURL
psql $PGURL <<-EOF
SELECT create_distributed_table('pgbench_accounts', 'aid'); SELECT truncate_local_data_after_distributing_table('public.pgbench_accounts');
SELECT create_reference_table('pgbench_branches') ; SELECT truncate_local_data_after_distributing_table('public.pgbench_branches');
SELECT create_reference_table('pgbench_history') ; SELECT truncate_local_data_after_distributing_table('public.pgbench_history');
SELECT create_reference_table('pgbench_tellers') ; SELECT truncate_local_data_after_distributing_table('public.pgbench_tellers');
EOF
执行读写测试:
pgbench -nv -P1 -c10 -T500 postgres://dbuser_citus:DBUser.Citus@10.10.10.10/citus # 直连协调者 5432 端口
pgbench -nv -P1 -c10 -T500 postgres://dbuser_citus:DBUser.Citus@10.10.10.10:6432/citus # 通过连接池,减少客户端连接数压力,可以有效提高整体吞吐。
pgbench -nv -P1 -c10 -T500 postgres://dbuser_citus:DBUser.Citus@10.10.10.13/citus # 任意 primary 节点都可以作为 coordinator
pgbench --select-only -nv -P1 -c10 -T500 postgres://dbuser_citus:DBUser.Citus@10.10.10.11/citus # 可以发起只读查询
更严肃的生产部署 要将 Citus 用于生产环境,您通常需要为 Coordinator 和每个 Worker 集群设置流复制物理副本。
例如,在 simu.yml 中定义了一个 10 节点的 Citus 集群。
pg-citus : # citus group
hosts :
10.10.10.50 : { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.60/24 ,pg_seq: 0, pg_role : primary }
10.10.10.51 : { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.60/24 ,pg_seq: 1, pg_role : replica }
10.10.10.52 : { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.61/24 ,pg_seq: 0, pg_role : primary }
10.10.10.53 : { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.61/24 ,pg_seq: 1, pg_role : replica }
10.10.10.54 : { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.62/24 ,pg_seq: 0, pg_role : primary }
10.10.10.55 : { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.62/24 ,pg_seq: 1, pg_role : replica }
10.10.10.56 : { pg_group: 3, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.63/24 ,pg_seq: 0, pg_role : primary }
10.10.10.57 : { pg_group: 3, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.63/24 ,pg_seq: 1, pg_role : replica }
10.10.10.58 : { pg_group: 4, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.64/24 ,pg_seq: 0, pg_role : primary }
10.10.10.59 : { pg_group: 4, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.64/24 ,pg_seq: 1, pg_role : replica }
vars :
pg_mode: citus # pgsql cluster mode : citus
pg_version : 18 # citus 13.x supports PG 14-18
pg_shard: pg-citus # citus shard name : pg-citus
pg_primary_db : citus # primary database used by citus
pg_vip_enabled : true # enable vip for citus cluster
pg_vip_interface : eth1 # vip interface for all members
pg_dbsu_password : DBUser.Postgres # enable dbsu password access for citus
pg_extensions : [ citus, postgis, pgvector, topn, pg_cron, hll ] # install these extensions
pg_libs : 'citus, pg_cron, pg_stat_statements' # citus will be added by patroni automatically
pg_users : [ { name: dbuser_citus ,password: DBUser.Citus ,pgbouncer: true ,roles : [ dbrole_admin ] }]
pg_databases : [ { name: citus ,owner: dbuser_citus ,extensions : [ citus, vector, topn, pg_cron, hll ] }]
pg_parameters :
cron.database_name : citus
citus.node_conninfo : 'sslrootcert=/pg/cert/ca.crt sslmode=verify-full'
pg_hba_rules :
- { user: 'all' ,db: all ,addr: 127.0.0.1/32 ,auth: ssl ,title : 'all user ssl access from localhost' }
- { user: 'all' ,db: all ,addr: intra ,auth: ssl ,title : 'all user ssl access from intranet' }
我们将在后续教程中覆盖一系列关于 Citus 的高级主题
读写分离 故障处理 一致性备份与恢复 高级监控与问题诊断 连接池 12.11 - 监控系统 Pigsty 监控系统架构概览,以及如何监控现存的 PostgreSQL 实例?
本文介绍了 Pigsty 的监控系统架构,包括监控指标,日志,与目标管理的方式。以及如何 监控现有PG集群 与远程 RDS服务 。
监控概览 Pigsty 使用现代的可观测技术栈对 PostgreSQL 进行监控:
使用 Grafana 进行指标可视化和 PostgreSQL 数据源。 使用 VictoriaMetrics 来采集 PostgreSQL / Pgbouncer / Patroni / HAProxy / Node 的指标 使用 VictoriaLogs 来记录 PostgreSQL / Pgbouncer / Patroni / pgBackRest 以及主机组件的日志 Pigsty 提供了开箱即用的 Grafana 仪表盘,展示与 PostgreSQL 有关的方方面面。 监控指标
PostgreSQL 本身的监控指标完全由 pg_exporter 配置文件所定义:pg_exporter.yml
它将进一步被 Prometheus 记录规则和告警规则进行加工处理:files/prometheus/rules/pgsql.yml 。
Pigsty 使用三个身份标签:cls、ins、ip,它们将附加到所有指标和日志上。此外,Pgbouncer 的监控指标,主机节点 NODE,与负载均衡器的监控指标也会被 Pigsty 所使用,并尽可能地使用相同的标签以便于关联分析。
{ cls: pg-meta, ins: pg-meta-1, ip : 10.10.10.10 }
{ cls: pg-meta, ins: pg-test-1, ip : 10.10.10.11 }
{ cls: pg-meta, ins: pg-test-2, ip : 10.10.10.12 }
{ cls: pg-meta, ins: pg-test-3, ip : 10.10.10.13 }
日志
与 PostgreSQL 有关的日志由 vector 负责收集,并发送至 infra 节点上的 VictoriaLogs 日志存储/查询服务。
目标管理
Prometheus 的监控目标在 /etc/prometheus/targets/pgsql/ 下的静态文件中定义,每个实例都有一个相应的文件。以 pg-meta-1 为例:
# pg-meta-1 [primary] @ 10.10.10.10
- labels : { cls: pg-meta, ins: pg-meta-1, ip : 10.10.10.10 }
targets :
- 10.10.10.10 : 9630 # <--- pg_exporter 用于PostgreSQL指标
- 10.10.10.10 : 9631 # <--- pg_exporter 用于pgbouncer指标
- 10.10.10.10 : 8008 # <--- patroni指标(未启用 API SSL 时)
当全局标志 patroni_ssl_enabled 被设置时,patroni 目标将被移动到单独的文件 /etc/prometheus/targets/patroni/<ins>.yml。 因为此时使用的是 https 抓取端点。当您 监控RDS 实例时,监控目标会被单独放置于: /etc/prometheus/targets/pgrds/ 目录下,并以集群 为单位进行管理。
当使用 bin/pgsql-rm 或 pgsql-rm.yml 移除集群时,Prometheus 监控目标将被移除。您也可以手动移除它,或使用剧本里的子任务:
bin/pgmon-rm <cls| ins> # 从所有infra节点中移除 prometheus 监控目标
远程 RDS 监控目标会被放置于 /etc/prometheus/targets/pgrds/<cls>.yml,它们是由 pgsql-monitor.yml 剧本或 bin/pgmon-add 脚本所创建的。
监控模式 Pigsty 提供三种监控模式,以适应不同的监控需求。
事项\等级 L1 L2 L3 名称 基础部署 托管部署 标准部署 英文 RDS MANAGED FULL 场景 只有连接串,例如 RDS DB 已存在,节点可管理 实例由 Pigsty 创建 PGCAT 功能 ✅ 完整可用 ✅ 完整可用 ✅ 完整可用 PGSQL 功能 ✅ 限 PG 指标 ✅ 限 PG 与节点指标 ✅ 完整功能 连接池指标 ❌ 不可用 ⚠️ 选装 ✅ 预装项 负载均衡器指标 ❌ 不可用 ⚠️ 选装 ✅ 预装项 PGLOG 功能 ❌ 不可用 ⚠️ 选装 ✅ 预装项 PG Exporter ⚠️ 部署于 Infra 节点 ✅ 部署于 DB 节点 ✅ 部署于 DB 节点 Node Exporter ❌ 不部署 ✅ 部署于 DB 节点 ✅ 部署于 DB 节点 侵入 DB 节点 ✅ 无侵入 ⚠️ 安装 Exporter ⚠️ 完全由 Pigsty 管理 监控现有实例 ✅ 可支持 ✅ 可支持 ❌ 仅用于 Pigsty 托管实例 监控用户与视图 人工创建 人工创建 Pigsty 自动创建 部署使用剧本 bin/pgmon-add <cls>部分执行 pgsql.ym/node.yml pgsql.yml所需权限 Infra 节点可达的 PGURL DB 节点 ssh 与 sudo 权限 DB 节点 ssh 与 sudo 权限 功能概述 PGCAT + PGRDS 大部分功能 完整功能
由 Pigsty 完全管理的数据库会自动纳入监控,并拥有最好的监控支持,通常不需要任何配置。对于现有的 PostgreSQL 集群或者 RDS 服务,如果目标 DB 节点可以被 Pigsty 所管理 (ssh 可达,sudo 可用),那么您可以考虑 托管部署 ,实现与 Pigsty 基本类似的监控管理体验。如果您只能通过 PGURL (数据库连接串)的方式访问目标数据库,例如远程的 RDS 服务,则可以考虑使用 精简模式 监控目标数据库。
监控现有集群 如果目标 DB 节点可以被 Pigsty 所管理 (ssh可达且sudo可用),那么您可以使用 pgsql.yml 剧本中的pg_exporter任务,
使用与标准部署相同的方式,在目标节点上部署监控组件:PG Exporter。您也可以使用该剧本的 pgbouncer,pgbouncer_exporter 任务在已有实例节点上部署连接池及其监控。此外,您也可以使用 node.yml 中的 node_exporter, haproxy, vector 部署主机监控,负载均衡,日志收集组件。从而获得与原生 Pigsty 数据库实例完全一致的使用体验。
现有集群的定义方式与 Pigsty 所管理的集群定义方式完全相同,您只是选择性执行 pgsql.yml 剧本中的部分任务,而不是执行整个剧本。
./node.yml -l <cls> -t node_repo,node_pkg # 在主机节点上添加 INFRA节点的 YUM 源并安装软件包。
./node.yml -l <cls> -t node_exporter,node_register # 配置主机监控,并加入 VictoriaMetrics
./node.yml -l <cls> -t vector # 配置主机日志采集,并发送至 victoria-logs
./pgsql.yml -l <cls> -t pg_exporter,pg_register # 配置 PostgreSQL 监控,并注册至 Victoria/Grafana
因为目标数据库集群已存在,所以您需要手工在目标数据库集群上 创建监控用户、模式与扩展 。
监控RDS 如果您只能通过 PGURL (数据库连接串)的方式访问目标数据库,那么可以参照这里的说明进行配置。在这种模式下,Pigsty 在 INFRA节点 上部署对应的 PG Exporter,抓取远端数据库指标信息。如下图所示:
------ infra ------
| |
| prometheus | v---- pg-foo-1 ----v
| ^ | metrics | ^ |
| pg_exporter <-|------------|---- postgres |
| (port: 20001) | | 10.10.10.10:5432 |
| ^ | ^------------------^
| ^ | ^
| ^ | v---- pg-foo-2 ----v
| ^ | metrics | ^ |
| pg_exporter <-|------------|---- postgres |
| (port: 20002) | | 10.10.10.11:5433 |
------------------- ^------------------^
在这种模式下,监控系统不会有主机,连接池,负载均衡器,高可用组件的相关指标,但数据库本身,以及数据目录(Catalog)中的实时状态信息仍然可用。Pigsty 提供了两个专用的监控面板,专注于 PostgreSQL 本身的监控指标: PGRDS Cluster 与 PGRDS Instance ,总览与数据库内监控则复用现有监控面板。因为 Pigsty 不能管理您的 RDS,所以用户需要在目标数据库上提前 配置好监控对象 。
监控外部 Postgres 实例时的局限性
pgBoucner 连接池指标不可用 Patroni 高可用组件指标不可用 主机节点监控指标不可用,以及节点 HAProxy,Keepalived 指标亦不可用。 日志收集与日志衍生指标不可用 下面我们使用沙箱环境作为示例:现在我们假设 pg-meta 集群是一个有待监控的 RDS 实例 pg-foo-1,而 pg-test 集群则是一个有待监控的 RDS 集群 pg-bar:
在目标上创建监控模式、用户和权限。详情请参考 监控对象配置
在配置清单中声明集群。例如,假设我们想要监控“远端”的 pg-meta & pg-test 集群:
infra : # 代理、监控、警报等的infra集群..
hosts : { 10.10.10.10 : { infra_seq : 1 } }
vars : # 在组'infra'上为远程postgres RDS安装pg_exporter
pg_exporters : # 在此列出所有远程实例,为k分配一个唯一的未使用的本地端口
20001 : { pg_cluster: pg-foo, pg_seq: 1, pg_host: 10.10.10.10 , pg_databases : [ { name : meta }] } # 注册 meta 数据库为 Grafana 数据源
20002 : { pg_cluster: pg-bar, pg_seq: 1, pg_host: 10.10.10.11 , pg_port : 5432 } # 几种不同的连接串拼接方法
20003 : { pg_cluster: pg-bar, pg_seq: 2, pg_host: 10.10.10.12 , pg_exporter_url : 'postgres://dbuser_monitor:DBUser.Monitor@10.10.10.12:5432/postgres?sslmode=disable' }
20004 : { pg_cluster: pg-bar, pg_seq: 3, pg_host: 10.10.10.13 , pg_monitor_username: dbuser_monitor, pg_monitor_password : DBUser.Monitor }
其中, pg_databases 字段中所列出的数据库,将会被注册至 Grafana 中,成为一个 PostgreSQL 数据源,为 PGCAT 监控面板提供数据支持。如果您不想使用 PGCAT,将注册数据库到 Grafana 中,只需要将 pg_databases 设置为空数组或直接留空即可。
执行添加监控命令:bin/pgmon-add <clsname>
bin/pgmon-add pg-foo # 将 pg-foo 集群纳入监控
bin/pgmon-add pg-bar # 将 pg-bar 集群纳入监控
要删除远程集群的监控目标,可以使用 bin/pgmon-rm <clsname>
bin/pgmon-rm pg-foo # 将 pg-foo 从 Pigsty 监控中移除
bin/pgmon-rm pg-bar # 将 pg-bar 从 Pigsty 监控中移除
您可以使用更多的参数来覆盖默认 pg_exporter 的选项,下面是一个使用 Pigsty 监控阿里云 RDS 与 PolarDB 的配置样例:
示例:监控阿里云 RDS for PostgreSQL 与 PolarDB 详情请参考:remote.yml
infra : # 代理、监控、警报等的infra集群..
hosts : { 10.10.10.10 : { infra_seq : 1 } }
vars :
pg_exporters : # 在此列出所有待监控的远程 RDS PG 实例
20001 : # 分配一个唯一的未使用的本地端口,供本地监控 Agent 使用,这里是一个 PolarDB 的主库
pg_cluster : pg-polar # RDS 集群名 (身份参数,手工指定分配监控系统内名称)
pg_seq : 1 # RDS 实例号 (身份参数,手工指定分配监控系统内名称)
pg_host : pc-2ze379wb1d4irc18x.polardbpg.rds.aliyuncs.com # RDS 主机地址
pg_port : 1921 # RDS 端口(从控制台连接信息获取)
pg_exporter_auto_discovery : true # 禁用新数据库自动发现功能
pg_exporter_include_database : 'test' # 仅监控这个列表中的数据库(多个数据库用逗号分隔)
pg_monitor_username : dbuser_monitor # 监控用的用户名,覆盖全局配置
pg_monitor_password : DBUser_Monitor # 监控用的密码,覆盖全局配置
pg_databases : [ { name : test }] # 希望启用PGCAT的数据库列表,只要name字段即可,register_datasource设置为false则不注册。
20002 : # 这是一个 PolarDB 从库
pg_cluster : pg-polar # RDS 集群名 (身份参数,手工指定分配监控系统内名称)
pg_seq : 2 # RDS 实例号 (身份参数,手工指定分配监控系统内名称)
pg_host : pe-2ze7tg620e317ufj4.polarpgmxs.rds.aliyuncs.com # RDS 主机地址
pg_port : 1521 # RDS 端口(从控制台连接信息获取)
pg_exporter_auto_discovery : true # 禁用新数据库自动发现功能
pg_exporter_include_database : 'test,postgres' # 仅监控这个列表中的数据库(多个数据库用逗号分隔)
pg_monitor_username : dbuser_monitor # 监控用的用户名
pg_monitor_password : DBUser_Monitor # 监控用的密码
pg_databases : [ { name : test } ] # 希望启用PGCAT的数据库列表,只要name字段即可,register_datasource设置为false则不注册。
20004 : # 这是一个基础版的单节点 RDS for PostgreSQL 实例
pg_cluster : pg-rds # RDS 集群名 (身份参数,手工指定分配监控系统内名称)
pg_seq : 1 # RDS 实例号 (身份参数,手工指定分配监控系统内名称)
pg_host : pgm-2zern3d323fe9ewk.pg.rds.aliyuncs.com # RDS 主机地址
pg_port : 5432 # RDS 端口(从控制台连接信息获取)
pg_exporter_auto_discovery : true # 禁用新数据库自动发现功能
pg_exporter_include_database : 'rds' # 仅监控这个列表中的数据库(多个数据库用逗号分隔)
pg_monitor_username : dbuser_monitor # 监控用的用户名
pg_monitor_password : DBUser_Monitor # 监控用的密码
pg_databases : [ { name : rds } ] # 希望启用PGCAT的数据库列表,只要name字段即可,register_datasource设置为false则不注册。
20005 : # 这是一个高可用版的 RDS for PostgreSQL 集群主库
pg_cluster : pg-rdsha # RDS 集群名 (身份参数,手工指定分配监控系统内名称)
pg_seq : 1 # RDS 实例号 (身份参数,手工指定分配监控系统内名称)
pg_host : pgm-2ze3d35d27bq08wu.pg.rds.aliyuncs.com # RDS 主机地址
pg_port : 5432 # RDS 端口(从控制台连接信息获取)
pg_exporter_include_database : 'rds' # 仅监控这个列表中的数据库(多个数据库用逗号分隔)
pg_databases : [ { name : rds }, {name : test} ] # 将这两个数据库纳入 PGCAT 管理,注册为 Grafana 数据源
20006 : # 这是一个高可用版的 RDS for PostgreSQL 集群只读实例(从库)
pg_cluster : pg-rdsha # RDS 集群名 (身份参数,手工指定分配监控系统内名称)
pg_seq : 2 # RDS 实例号 (身份参数,手工指定分配监控系统内名称)
pg_host : pgr-2zexqxalk7d37edt.pg.rds.aliyuncs.com # RDS 主机地址
pg_port : 5432 # RDS 端口(从控制台连接信息获取)
pg_exporter_include_database : 'rds' # 仅监控这个列表中的数据库(多个数据库用逗号分隔)
pg_databases : [ { name : rds }, {name : test} ] # 将这两个数据库纳入 PGCAT 管理,注册为 Grafana 数据源
监控对象配置 当您想要监控现有实例时,不论是 RDS,还是自建的 PostgreSQL 实例,您都需要在目标数据库上进行一些配置,以便 Pigsty 可以访问它们。
为了将外部现存 PostgreSQL 实例纳入监控,您需要有一个可用于访问该实例/集群的连接串。任何可达连接串(业务用户,超级用户)均可使用,但我们建议使用一个专用监控用户以避免权限泄漏。
监控用户 以 Pigsty 默认使用的监控用户dbuser_monitor为例,在目标数据库集群创建以下用户。
CREATE USER dbuser_monitor ; -- 创建监控用户
COMMENT ON ROLE dbuser_monitor IS 'system monitor user' ; -- 监控用户备注
GRANT pg_monitor TO dbuser_monitor ; -- 授予监控用户 pg_monitor 权限,否则一些指标将无法采集
ALTER USER dbuser_monitor PASSWORD 'DBUser.Monitor' ; -- 按需修改监控用户密码(强烈建议修改!但请与Pigsty配置一致)
ALTER USER dbuser_monitor SET log_min_duration_statement = 1000 ; -- 建议设置此参数,避免日志塞满监控慢查询
ALTER USER dbuser_monitor SET search_path = monitor , public ; -- 建议设置此参数,避免 pg_stat_statements 扩展无法生效
请注意,这里创建的监控用户与密码需要与 pg_monitor_username 与 pg_monitor_password 保持一致。
监控认证 配置数据库 pg_hba.conf 文件,添加以下规则以允许监控用户从本地,以及管理机使用密码访问所有数据库。
# allow local role monitor with password
local all dbuser_monitor md5
host all dbuser_monitor 127.0.0.1/32 md5
host all dbuser_monitor <管理机器IP地址>/32 md5
如果您的 RDS 不支持定义 HBA,那么把安装 Pigsty 机器的内网 IP 地址开白即可。
监控模式 监控模式可选项 ,即使没有,Pigsty 监控系统的主体也可以正常工作,但我们强烈建议设置此模式。
CREATE SCHEMA IF NOT EXISTS monitor ; -- 创建监控专用模式
GRANT USAGE ON SCHEMA monitor TO dbuser_monitor ; -- 允许监控用户使用
监控扩展 监控扩展是可选项,但我们强烈建议启用 pg_stat_statements 扩展该扩展提供了关于查询性能的重要数据。
注意:该扩展必须列入数据库参数 shared_preload_libraries 中方可生效,而修改该参数需要重启数据库。
CREATE EXTENSION IF NOT EXISTS "pg_stat_statements" WITH SCHEMA "monitor" ;
请注意,您应当在默认的管理数据库 postgres 中安装此扩展。有些时候,RDS 不允许您在 postgres 数据库中创建监控模式,
在这种情况下,您可以将 pg_stat_statements 插件安装到默认的 public 下,只要确保监控用户的 search_path 按照上面的配置,能够找到 pg_stat_statements 视图即可。
CREATE EXTENSION IF NOT EXISTS "pg_stat_statements" ;
ALTER USER dbuser_monitor SET search_path = monitor , public ; -- 建议设置此参数,避免 pg_stat_statements 扩展无法生效
监控视图 监控视图提供了若干常用的预处理结果,并对某些需要高权限的监控指标进行权限封装(例如共享内存分配),便于查询与使用。强烈建议在所有需要监控的数据库中创建
监控模式与监控视图定义 ----------------------------------------------------------------------
-- Table bloat estimate : monitor.pg_table_bloat
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor . pg_table_bloat CASCADE ;
CREATE OR REPLACE VIEW monitor . pg_table_bloat AS
SELECT CURRENT_CATALOG AS datname , nspname , relname , tblid , bs * tblpages AS size ,
CASE WHEN tblpages - est_tblpages_ff > 0 THEN ( tblpages - est_tblpages_ff ) / tblpages :: FLOAT ELSE 0 END AS ratio
FROM (
SELECT ceil ( reltuples / ( ( bs - page_hdr ) * fillfactor / ( tpl_size * 100 ) ) ) + ceil ( toasttuples / 4 ) AS est_tblpages_ff ,
tblpages , fillfactor , bs , tblid , nspname , relname , is_na
FROM (
SELECT
( 4 + tpl_hdr_size + tpl_data_size + ( 2 * ma )
- CASE WHEN tpl_hdr_size % ma = 0 THEN ma ELSE tpl_hdr_size % ma END
- CASE WHEN ceil ( tpl_data_size ):: INT % ma = 0 THEN ma ELSE ceil ( tpl_data_size ):: INT % ma END
) AS tpl_size , ( heappages + toastpages ) AS tblpages , heappages ,
toastpages , reltuples , toasttuples , bs , page_hdr , tblid , nspname , relname , fillfactor , is_na
FROM (
SELECT
tbl . oid AS tblid , ns . nspname , tbl . relname , tbl . reltuples ,
tbl . relpages AS heappages , coalesce ( toast . relpages , 0 ) AS toastpages ,
coalesce ( toast . reltuples , 0 ) AS toasttuples ,
coalesce ( substring ( array_to_string ( tbl . reloptions , ' ' ) FROM 'fillfactor=([0-9]+)' ):: smallint , 100 ) AS fillfactor ,
current_setting ( 'block_size' ):: numeric AS bs ,
CASE WHEN version () ~ 'mingw32' OR version () ~ '64-bit|x86_64|ppc64|ia64|amd64' THEN 8 ELSE 4 END AS ma ,
24 AS page_hdr ,
23 + CASE WHEN MAX ( coalesce ( s . null_frac , 0 )) > 0 THEN ( 7 + count ( s . attname ) ) / 8 ELSE 0 :: int END
+ CASE WHEN bool_or ( att . attname = 'oid' and att . attnum < 0 ) THEN 4 ELSE 0 END AS tpl_hdr_size ,
sum ( ( 1 - coalesce ( s . null_frac , 0 )) * coalesce ( s . avg_width , 0 ) ) AS tpl_data_size ,
bool_or ( att . atttypid = 'pg_catalog.name' :: regtype )
OR sum ( CASE WHEN att . attnum > 0 THEN 1 ELSE 0 END ) <> count ( s . attname ) AS is_na
FROM pg_attribute AS att
JOIN pg_class AS tbl ON att . attrelid = tbl . oid
JOIN pg_namespace AS ns ON ns . oid = tbl . relnamespace
LEFT JOIN pg_stats AS s ON s . schemaname = ns . nspname AND s . tablename = tbl . relname AND s . inherited = false AND s . attname = att . attname
LEFT JOIN pg_class AS toast ON tbl . reltoastrelid = toast . oid
WHERE NOT att . attisdropped AND tbl . relkind = 'r' AND nspname NOT IN ( 'pg_catalog' , 'information_schema' )
GROUP BY 1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , 10
) AS s
) AS s2
) AS s3
WHERE NOT is_na ;
COMMENT ON VIEW monitor . pg_table_bloat IS 'postgres table bloat estimate' ;
GRANT SELECT ON monitor . pg_table_bloat TO pg_monitor ;
----------------------------------------------------------------------
-- Index bloat estimate : monitor.pg_index_bloat
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor . pg_index_bloat CASCADE ;
CREATE OR REPLACE VIEW monitor . pg_index_bloat AS
SELECT CURRENT_CATALOG AS datname , nspname , idxname AS relname , tblid , idxid , relpages :: BIGINT * bs AS size ,
COALESCE (( relpages - ( reltuples * ( 6 + ma - ( CASE WHEN index_tuple_hdr % ma = 0 THEN ma ELSE index_tuple_hdr % ma END )
+ nulldatawidth + ma - ( CASE WHEN nulldatawidth % ma = 0 THEN ma ELSE nulldatawidth % ma END ))
/ ( bs - pagehdr ):: FLOAT + 1 )), 0 ) / relpages :: FLOAT AS ratio
FROM (
SELECT nspname , idxname , indrelid AS tblid , indexrelid AS idxid ,
reltuples , relpages ,
current_setting ( 'block_size' ):: INTEGER AS bs ,
( CASE WHEN version () ~ 'mingw32' OR version () ~ '64-bit|x86_64|ppc64|ia64|amd64' THEN 8 ELSE 4 END ) AS ma ,
24 AS pagehdr ,
( CASE WHEN max ( COALESCE ( pg_stats . null_frac , 0 )) = 0 THEN 2 ELSE 6 END ) AS index_tuple_hdr ,
sum (( 1 . 0 - COALESCE ( pg_stats . null_frac , 0 . 0 )) *
COALESCE ( pg_stats . avg_width , 1024 )):: INTEGER AS nulldatawidth
FROM pg_attribute
JOIN (
SELECT pg_namespace . nspname ,
ic . relname AS idxname ,
ic . reltuples ,
ic . relpages ,
pg_index . indrelid ,
pg_index . indexrelid ,
tc . relname AS tablename ,
regexp_split_to_table ( pg_index . indkey :: TEXT , ' ' ) :: INTEGER AS attnum ,
pg_index . indexrelid AS index_oid
FROM pg_index
JOIN pg_class ic ON pg_index . indexrelid = ic . oid
JOIN pg_class tc ON pg_index . indrelid = tc . oid
JOIN pg_namespace ON pg_namespace . oid = ic . relnamespace
JOIN pg_am ON ic . relam = pg_am . oid
WHERE pg_am . amname = 'btree' AND ic . relpages > 0 AND nspname NOT IN ( 'pg_catalog' , 'information_schema' )
) ind_atts ON pg_attribute . attrelid = ind_atts . indexrelid AND pg_attribute . attnum = ind_atts . attnum
JOIN pg_stats ON pg_stats . schemaname = ind_atts . nspname
AND (( pg_stats . tablename = ind_atts . tablename AND pg_stats . attname = pg_get_indexdef ( pg_attribute . attrelid , pg_attribute . attnum , TRUE ))
OR ( pg_stats . tablename = ind_atts . idxname AND pg_stats . attname = pg_attribute . attname ))
WHERE pg_attribute . attnum > 0
GROUP BY 1 , 2 , 3 , 4 , 5 , 6
) est ;
COMMENT ON VIEW monitor . pg_index_bloat IS 'postgres index bloat estimate (btree-only)' ;
GRANT SELECT ON monitor . pg_index_bloat TO pg_monitor ;
----------------------------------------------------------------------
-- Relation Bloat : monitor.pg_bloat
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor . pg_bloat CASCADE ;
CREATE OR REPLACE VIEW monitor . pg_bloat AS
SELECT coalesce ( ib . datname , tb . datname ) AS datname ,
coalesce ( ib . nspname , tb . nspname ) AS nspname ,
coalesce ( ib . tblid , tb . tblid ) AS tblid ,
coalesce ( tb . nspname || '.' || tb . relname , ib . nspname || '.' || ib . tblid :: RegClass ) AS tblname ,
tb . size AS tbl_size ,
CASE WHEN tb . ratio < 0 THEN 0 ELSE round ( tb . ratio :: NUMERIC , 6 ) END AS tbl_ratio ,
( tb . size * ( CASE WHEN tb . ratio < 0 THEN 0 ELSE tb . ratio :: NUMERIC END )) :: BIGINT AS tbl_wasted ,
ib . idxid ,
ib . nspname || '.' || ib . relname AS idxname ,
ib . size AS idx_size ,
CASE WHEN ib . ratio < 0 THEN 0 ELSE round ( ib . ratio :: NUMERIC , 5 ) END AS idx_ratio ,
( ib . size * ( CASE WHEN ib . ratio < 0 THEN 0 ELSE ib . ratio :: NUMERIC END )) :: BIGINT AS idx_wasted
FROM monitor . pg_index_bloat ib
FULL OUTER JOIN monitor . pg_table_bloat tb ON ib . tblid = tb . tblid ;
COMMENT ON VIEW monitor . pg_bloat IS 'postgres relation bloat detail' ;
GRANT SELECT ON monitor . pg_bloat TO pg_monitor ;
----------------------------------------------------------------------
-- monitor.pg_index_bloat_human
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor . pg_index_bloat_human CASCADE ;
CREATE OR REPLACE VIEW monitor . pg_index_bloat_human AS
SELECT idxname AS name ,
tblname ,
idx_wasted AS wasted ,
pg_size_pretty ( idx_size ) AS idx_size ,
round ( 100 * idx_ratio :: NUMERIC , 2 ) AS idx_ratio ,
pg_size_pretty ( idx_wasted ) AS idx_wasted ,
pg_size_pretty ( tbl_size ) AS tbl_size ,
round ( 100 * tbl_ratio :: NUMERIC , 2 ) AS tbl_ratio ,
pg_size_pretty ( tbl_wasted ) AS tbl_wasted
FROM monitor . pg_bloat
WHERE idxname IS NOT NULL ;
COMMENT ON VIEW monitor . pg_index_bloat_human IS 'postgres index bloat info in human-readable format' ;
GRANT SELECT ON monitor . pg_index_bloat_human TO pg_monitor ;
----------------------------------------------------------------------
-- monitor.pg_table_bloat_human
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor . pg_table_bloat_human CASCADE ;
CREATE OR REPLACE VIEW monitor . pg_table_bloat_human AS
SELECT tblname AS name ,
idx_wasted + tbl_wasted AS wasted ,
pg_size_pretty ( idx_wasted + tbl_wasted ) AS all_wasted ,
pg_size_pretty ( tbl_wasted ) AS tbl_wasted ,
pg_size_pretty ( tbl_size ) AS tbl_size ,
tbl_ratio ,
pg_size_pretty ( idx_wasted ) AS idx_wasted ,
pg_size_pretty ( idx_size ) AS idx_size ,
round ( idx_wasted :: NUMERIC * 100 . 0 / idx_size , 2 ) AS idx_ratio
FROM ( SELECT datname ,
nspname ,
tblname ,
coalesce ( max ( tbl_wasted ), 0 ) AS tbl_wasted ,
coalesce ( max ( tbl_size ), 1 ) AS tbl_size ,
round ( 100 * coalesce ( max ( tbl_ratio ), 0 ):: NUMERIC , 2 ) AS tbl_ratio ,
coalesce ( sum ( idx_wasted ), 0 ) AS idx_wasted ,
coalesce ( sum ( idx_size ), 1 ) AS idx_size
FROM monitor . pg_bloat
WHERE tblname IS NOT NULL
GROUP BY 1 , 2 , 3
) d ;
COMMENT ON VIEW monitor . pg_table_bloat_human IS 'postgres table bloat info in human-readable format' ;
GRANT SELECT ON monitor . pg_table_bloat_human TO pg_monitor ;
----------------------------------------------------------------------
-- Activity Overview: monitor.pg_session
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor . pg_session CASCADE ;
CREATE OR REPLACE VIEW monitor . pg_session AS
SELECT coalesce ( datname , 'all' ) AS datname , numbackends , active , idle , ixact , max_duration , max_tx_duration , max_conn_duration
FROM (
SELECT datname ,
count ( * ) AS numbackends ,
count ( * ) FILTER ( WHERE state = 'active' ) AS active ,
count ( * ) FILTER ( WHERE state = 'idle' ) AS idle ,
count ( * ) FILTER ( WHERE state = 'idle in transaction'
OR state = 'idle in transaction (aborted)' ) AS ixact ,
max ( extract ( epoch from now () - state_change ))
FILTER ( WHERE state = 'active' ) AS max_duration ,
max ( extract ( epoch from now () - xact_start )) AS max_tx_duration ,
max ( extract ( epoch from now () - backend_start )) AS max_conn_duration
FROM pg_stat_activity
WHERE backend_type = 'client backend'
AND pid <> pg_backend_pid ()
GROUP BY ROLLUP ( 1 )
ORDER BY 1 NULLS FIRST
) t ;
COMMENT ON VIEW monitor . pg_session IS 'postgres activity group by session' ;
GRANT SELECT ON monitor . pg_session TO pg_monitor ;
----------------------------------------------------------------------
-- Sequential Scan: monitor.pg_seq_scan
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor . pg_seq_scan CASCADE ;
CREATE OR REPLACE VIEW monitor . pg_seq_scan AS
SELECT schemaname AS nspname ,
relname ,
seq_scan ,
seq_tup_read ,
seq_tup_read / seq_scan AS seq_tup_avg ,
idx_scan ,
n_live_tup + n_dead_tup AS tuples ,
round ( n_live_tup * 100 . 0 :: NUMERIC / ( n_live_tup + n_dead_tup ), 2 ) AS live_ratio
FROM pg_stat_user_tables
WHERE seq_scan > 0
and ( n_live_tup + n_dead_tup ) > 0
ORDER BY seq_scan DESC ;
COMMENT ON VIEW monitor . pg_seq_scan IS 'table that have seq scan' ;
GRANT SELECT ON monitor . pg_seq_scan TO pg_monitor ;
查看共享内存分配的函数(PG13 以上可用) DROP FUNCTION IF EXISTS monitor . pg_shmem () CASCADE ;
CREATE OR REPLACE FUNCTION monitor . pg_shmem () RETURNS SETOF
pg_shmem_allocations AS $$ SELECT * FROM pg_shmem_allocations ; $$ LANGUAGE SQL SECURITY DEFINER ;
COMMENT ON FUNCTION monitor . pg_shmem () IS 'security wrapper for system view pg_shmem' ;
REVOKE ALL ON FUNCTION monitor . pg_shmem () FROM PUBLIC ;
GRANT EXECUTE ON FUNCTION monitor . pg_shmem () TO pg_monitor ;
12.12 - 监控面板 Pigsty 为 PostgreSQL 提供了诸多开箱即用的 Grafana 监控仪表盘
Pigsty 为 PostgreSQL 提供了诸多开箱即用的 Grafana 监控仪表盘: Demo & Gallery 。
在 Pigsty 中共有 26 个与 PostgreSQL 相关的监控面板,按照层次分为 总览,集群,实例,数据库四大类,按照数据来源又分为 PGSQL ,PGCAT ,PGLOG 三大类。
总览 概览
集群
实例
数据库
总览 PGSQL Overview :PGSQL 模块的主仪表板
PGSQL Overview
PGSQL Alert :PGSQL 全局核心指标总览与告警事件一览
PGSQL Alert
PGSQL Shard :展示一个 PGSQL 水平分片集群内的横向指标对比:例如 CITUS / GPSQL 集群。
PGSQL Shard
集群 PGSQL Cluster :一个 PGSQL 集群的主仪表板
PGSQL Cluster
PGRDS Cluster :PGSQL Cluster 的 RDS 版本,专注于所有 PostgreSQL 本身的指标
PGRDS Cluster
PGSQL Service :关注 PGSQL 集群服务、代理、路由和负载均衡。
PGSQL Service
PGSQL Activity :关注 PGSQL 集群的会话/负载/QPS/TPS/锁定情况
PGSQL Activity
PGSQL Replication :关注 PGSQL 集群复制、插槽和发布/订阅。
PGSQL Replication
PGSQL Databases :关注所有实例的数据库 CRUD、慢查询和表统计信息。
PGSQL Databases
PGSQL Patroni :关注集群高可用状态,Patroni 组件状态
PGSQL Patroni
PGSQL PITR :关注集群 PITR 过程的上下文,用于辅助时间点恢复
PGSQL PITR
实例 PGSQL Instance :单个 PGSQL 实例的主仪表板
PGSQL Instance
PGRDS Instance :PGSQL Instance 的 RDS 版本,专注于所有 PostgreSQL 本身的指标
PGRDS Instance
PGSQL Proxy :单个 haproxy 负载均衡器的详细指标
PGSQL Proxy
PGSQL Pgbouncer :单个 Pgbouncer 连接池实例中的指标总览
PGSQL Pgbouncer
PGSQL Persist :持久性指标:WAL、XID、检查点、存档、IO
PGSQL Persist
PGSQL Xacts :关于事务、锁、TPS/QPS 相关的指标
PGSQL Xacts
PGSQL Session :单个实例中的会话和活动/空闲时间的指标
PGSQL Session
PGSQL Exporter :Postgres/Pgbouncer 监控组件自我监控指标
PGSQL Exporter
数据库 PGSQL Database :单个 PGSQL 数据库的主仪表板
PGSQL Database
PGSQL Tables :单个数据库内的表/索引访问指标
PGSQL Tables
PGSQL Table :单个表的详细信息(QPS/RT/索引/序列…)
PGSQL Table
PGSQL Query :单类查询的详细信息(QPS/RT)
PGSQL Query
PGCAT PGCAT Instance :直接从数据库目录获取的实例信息
PGCAT Instance
PGCAT Database :直接从数据库目录获取的数据库信息
PGCAT Database
PGCAT Schema :直接从数据库目录获取关于模式的信息(表/索引/序列…)
PGCAT Schema
PGCAT Table :直接从数据库目录获取的单个表的详细信息(统计/膨胀…)
PGCAT Table
PGCAT Query :直接从数据库目录获取的单类查询的详细信息(SQL/统计)
PGCAT Query
PGCAT Locks :直接从数据库目录获取的关于活动与锁等待的信息
PGCAT Locks
PGLOG PGLOG Overview :总览 Pigsty CMDB 中的 CSV 日志样本
PGLOG Overview
PGLOG Overview :Pigsty CMDB 中的 CSV 日志样本中某一条会话的日志详情
PGLOG Session
画廊 详情请参考 pigsty/wiki/gallery 。
PGSQL Overview
PGSQL Shard
PGSQL Cluster
PGSQL Service
PGSQL Activity
PGSQL Replication
PGSQL Databases
PGSQL Instance
PGSQL Proxy
PGSQL Pgbouncer
PGSQL Session
PGSQL Xacts
PGSQL Persist
PGSQL Database
PGSQL Tables
PGSQL Table
PGSQL Query
PGCAT Instance
PGCAT Database
PGCAT Schema
PGCAT Table
PGCAT Lock
PGCAT Query
PGLOG Overview
PGLOG Session
12.12.1 - 总览面板 PostgreSQL 模块全局总览类监控面板
PostgreSQL 模块全局总览类监控面板,包括:
12.12.1.1 - PGSQL Overview PGSQL 模块的主仪表板
PGSQL 模块的主仪表板:Demo
PGSQL Overview 是 PostgreSQL 模块的主仪表板,提供整个 PGSQL 模块的全局概览视图。
12.12.1.2 - PGSQL Alert PGSQL 的全局关键指标和警报事件
PGSQL 的全局关键指标和警报事件:Demo
PGSQL Alert 仪表板展示 PGSQL 全局核心指标总览与告警事件一览。
12.12.1.3 - PGSQL Shard 关于水平分片的 PGSQL 集群的概览
关于水平分片的 PGSQL 集群的概览:Demo
PGSQL Shard 仪表板展示一个 PGSQL 水平分片集群内的横向指标对比,例如 Citus / GPSQL 集群。
12.12.2 - 集群面板 PostgreSQL 集群级别监控面板
PostgreSQL 集群级别监控面板,包括:
12.12.2.1 - PGSQL Cluster 一个 PGSQL 集群的主仪表板
一个 PGSQL 集群的主仪表板:Demo
PGSQL Cluster 是单个 PostgreSQL 集群的主仪表板,提供集群级别的核心指标概览。
12.12.2.2 - PGRDS Cluster PGSQL Cluster 的 RDS 版本,专注于 PostgreSQL 本身的指标
PGSQL Cluster 的 RDS 版本:Demo
PGRDS Cluster 是 PGSQL Cluster 的 RDS 版本,专注于所有 PostgreSQL 本身的指标,适用于云数据库 RDS 监控场景。
12.12.2.3 - PGSQL Activity 关注 PGSQL 集群的会话/负载/QPS/TPS/锁定情况
关注 PGSQL 集群的会话/负载/QPS/TPS/锁定情况:Demo
PGSQL Activity 仪表板关注 PGSQL 集群的会话、负载、QPS、TPS 以及锁定情况。
12.12.2.4 - PGSQL Replication 关注 PGSQL 集群复制、插槽和发布/订阅
关注 PGSQL 集群复制、插槽和发布/订阅:Demo
PGSQL Replication 仪表板关注 PGSQL 集群的复制状态、复制插槽和发布/订阅信息。
12.12.2.5 - PGSQL Service 关