积木式架构

• 1: 节点
• 2: INFRA 架构
• 3: PGSQL 架构

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'

1 - 节点

节点（node） 是对硬件资源/操作系统的抽象，可以是物理机，裸金属、虚拟机、或者容器与 pods。

只要装着 Linux 操作系统（以及 systemd 守护进程），能使用 CPU/内存/磁盘/网络 等标准资源，即可视作节点。

节点上可以安装 模块，Pigsty 中存在几种不同类型节点，主要区别就在于安装了不同的模块。

在 单机部署 Pigsty 时，多者合而为一，当前节点将同时作为普通节点，管理节点、基础设施节点、ETCD 节点，以及数据库节点。

普通节点

使用 Pigsty 管理节点，可在其上安装模块。node.yml 剧本将调整节点至所需状态。 普通节点上可能会运行以下服务：

这里，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 模块，包含下列组件：

其中，Nginx 作为当前模块的入口，提供 Web 图形界面和本地软件仓库服务。 如果你部署多个 INFRA 节点，每个 Infra 节点上的服务是相互独立的。 但你确实可以从任意一个 Infra 节点上的 Grafana 访问所有的监控数据源。

请注意，INFRA 模块受到 Grafana 传染，使用 AGPLv3 许可证开源。 但作为例外，如果你只使用 Nginx / Victoria 全家桶等组件，而不使用 Grafana，实际上使用的是 Apache-2.0 许可证。

ETCD节点

ETCD 模块为 PostgreSQL 高可用提供分布式共识服务（DCS）。

配置清单 中的 etcd 分组指定哪些节点是 ETCD 节点，ETCD 节点上运行着 etcd 服务器，监听以下两个端口：

MINIO节点

MINIOn 模块为 PostgreSQL 提供了一个可选的 备份存储仓库。

配置清单中的 minio 分组指定哪些节点是 MinIO 节点，这些节点上会运行 MinIO 服务器，监听以下端口：

PGSQL节点

安装了 PGSQL 模块的节点被称为 PGSQL 节点。节点与 PostgreSQL 实例为 1:1 部署，也就是每个节点上只运行一个 PG 实例。

PGSQL 节点可从相应 PostgreSQL 实例借用 身份 —— 由 node_id_from_pg 控制，默认为 true，即节点名会被设置为 PG 实例名。

PGSQL节点在 普通节点 的基础上，还会额外运行以下组件：

其中，vip-manager 只有当用户配置了 PG VIP 时才会启用。 在 pg_services 中可以定义更多的 自定义服务，这些服务会被 haproxy 对外暴露，并使用更多的服务端口。

2 - INFRA 架构

运行生产级别高可用 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 地址。

• dns_records : 写入 INFRA 节点的默认解析记录
• node_dns_servers ：为节点配置 DNS 服务器，默认通过 admin_ip 指向 INFRA 节点。（也可以 不配置）

更多信息请参阅：配置：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 剧本中， 采用了一种 “交织部署” 的技术：

• 首先初始化所有 普通节点 上的 NODE模块，但是不配置监控，因为基础设施服务尚未部署完成。
• 然后初始化 INFRA节点 上的 INFRA模块，此时监控已经可用
• 然后回过头来，重新配置所有 普通节点 上的监控功能，连接到已经部署完成的监控平台

如果您不追求 “一次性” 部署所有节点，也可以采用 分阶段部署 的方式，先初始化 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.0.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 - PGSQL 架构

PGSQL 模块在生产环境中以 集群 的形式组织，这些 集群 是由一组通过 主-备 关联的数据库 实例 组成的 逻辑实体。

概览

PGSQL 模块 包含下列组件，协同提供生产级 PostgreSQL 高可用集群服务：

其中 vip-manager 为按需启用的组件。此外，PGSQL 还会使用到其他模块中的组件：

如果用类比来形容，PostgreSQL 数据库内核就是 CPU，而整个 PGSQL 模块将其封装为一台完整的计算机。 Patroni 与 Etcd 组成 高可用子系统，pgBackRest 与 MinIO 组成 备份恢复子系统。 HAProxy 与 Pgbouncer、vip-manager 组成 接入子系统。 各种 Exporter 与 Vector 构成 可观测性子系统； 最后还可以替换不同的 内核 CPU 与 扩展卡。

组件交互

• 集群 DNS 由 infra 节点上的 DNSMASQ 负责解析
• 集群 VIP 由 vip-manager 组件管理，它负责将 pg_vip_address 绑定到集群主库节点上。
  • vip-manager 从 etcd 集群获取由 patroni 写入的集群领导者信息
• 集群服务由节点上的 HAProxy 对外暴露，不同服务通过节点的不同端口（543x）区分。
  • HAProxy 端口 9101：监控指标 & 统计 & 管理页面
  • HAProxy 端口 5433：默认路由至主 pgbouncer：读写服务
  • HAProxy 端口 5434：默认路由至从库 pgbouncer：只读服务
  • HAProxy 端口 5436：默认路由至主 postgres：默认服务
  • HAProxy 端口 5438：默认路由至离线 postgres：离线服务
  • HAProxy 将根据 patroni 提供的健康检查信息路由流量。
• Pgbouncer 是连接池中间件，默认监听 6432 端口，可以缓冲连接、暴露额外的指标，并提供额外的灵活性。
  • Pgbouncer 是无状态的，并通过本地 Unix 套接字以 1:1 的方式与 Postgres 服务器部署。
  • 生产流量（主/从）将默认通过 pgbouncer（可以通过 pg_default_service_dest 指定跳过）
  • 默认/离线服务将始终绕过 pgbouncer，并直接连接到目标 Postgres。
• PostgreSQL 监听 5432 端口，提供关系型数据库服务
  • 在多个节点上安装 PGSQL 模块，并使用同一集群名，将自动基于流式复制组成高可用集群
  • PostgreSQL 进程默认由 patroni 管理。
• Patroni 默认监听端口 8008，监管着 PostgreSQL 服务器进程
  • Patroni 将 Postgres 服务器作为子进程启动
  • Patroni 使用 etcd 作为 DCS：存储配置、故障检测和领导者选举。
  • Patroni 通过健康检查提供 Postgres 信息（比如主/从），HAProxy 通过健康检查使用该信息分发服务流量
• pg_exporter 在 9630 端口对外暴露 postgres 监控指标
• pgbouncer_exporter 在端口 9631 暴露 pgbouncer 指标
• pgBackRest 默认使用本地备份仓库 （pgbackrest_method = local）
  • 如果使用 local（默认）作为备份仓库，pgBackRest 将在主库节点的 pg_fs_bkup 下创建本地仓库
  • 如果使用 minio 作为备份仓库，pgBackRest 将在专用的 MinIO 集群上创建备份仓库
• Vector 负责收集 Postgres 相关日志（postgres, pgbouncer, patroni, pgbackrest）
  • vector 监听 9598 端口，也对 infra 节点上的 VictoriaMetrics 暴露自身的监控指标
  • vector 将日志发送至 infra 节点上的 VictoriaLogs

高可用子系统

高可用 子系统由 Patroni 与 etcd 组成，负责 PostgreSQL 集群的故障检测、自动切换与配置管理。

工作原理：Patroni 在每个节点上运行，托管本地 PostgreSQL 进程，并将集群状态（领导者、成员、配置）写入 etcd。 当主库故障时，Patroni 通过 etcd 协调选举，选出最健康的从库提升为新主库，整个过程自动完成，RTO 通常在 45 秒内。

关键交互：

• PostgreSQL：作为父进程启动、停止、重载 PG，控制其生命周期
• etcd：外部依赖，写入/监视领导者键，实现分布式共识与故障检测
• HAProxy：通过 REST API（:8008）提供健康检查，告知实例角色
• vip-manager：监视 etcd 中的领导者键，自动漂移 VIP

更多信息请参阅：高可用 与 配置：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/分析）

关键特性：

• HAProxy 通过 Patroni REST API 判断实例角色，自动路由流量
• Pgbouncer 采用事务级池化，吸收连接峰值，降低 PG 连接开销
• vip-manager 监视 etcd 领导者键，故障切换时自动漂移 VIP

更多信息请参阅：服务接入 与 配置：PGSQL - PG_ACCESS

备份恢复子系统

备份恢复子系统由 pgBackRest 组成（可选配 MinIO 作为远程仓库），负责数据备份与时间点恢复（PITR）。

备份类型：

• 全量备份：完整的数据库副本
• 增量/差异备份：仅备份变更的数据块
• WAL 归档：持续归档事务日志，支持任意时间点恢复

存储后端：

• local（默认）：本地磁盘，备份存储在 pg_fs_bkup 挂载点
• minio：S3 兼容对象存储，支持集中化备份管理与异地容灾

关键交互：

• pgBackRest → PostgreSQL：执行备份命令，管理 WAL 归档
• pgBackRest → Patroni：恢复时可将副本引导为新的主库或备库
• pgbackrest_exporter → Prometheus：导出备份状态指标，监控备份健康

更多信息请参阅：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 内核上加装多达 440 个扩展插件。

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 是服务入口与负载均衡器，对外暴露多个数据库服务端口。

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 模块