模块化架构

• 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 - VICTORIA

VictoriaLogs

VictoriaLogs 是 Pigsty 的日志平台，集中存储来自所有节点的结构化日志。在线演示

默认监听 9428 端口，挂载于 Nginx /vlogs 路径上：

所有纳管节点默认运行 Vector Agent，负责收集系统日志、PostgreSQL 日志、Patroni 日志、Pgbouncer 日志等，结构化处理后推送至 VictoriaLogs。 内置 Web UI 支持日志检索与过滤，也可配合 Grafana 的 victorialogs-datasource 插件进行可视化分析。

更多信息请参阅：配置：INFRA - VICTORIA

VictoriaTraces

VictoriaTraces 用于收集链路追踪数据与慢 SQL 记录。在线演示

默认监听 10428 端口，挂载于 Nginx /vtraces 路径上：

VictoriaTraces 提供 Jaeger 兼容接口，可用于分析服务调用链路与数据库慢查询。 结合 Grafana 面板，能够快速定位性能瓶颈，追溯问题根因。

更多信息请参阅：配置：INFRA - VICTORIA

VMAlert

VMAlert 是告警规则计算引擎，负责评估告警规则并将触发的事件推送至 Alertmanager。在线演示

默认监听 8880 端口，挂载于 Nginx /vmalert 路径上：

VMAlert 从 VictoriaMetrics 读取指标数据，周期性执行告警规则评估。 Pigsty 预置了 PGSQL、NODE、REDIS 等模块的告警规则，覆盖常见故障场景，开箱即用。

更多信息请参阅：配置：INFRA - PROMETHEUS

AlertManager

AlertManager 负责告警事件的聚合、去重、分组与分发。在线演示

默认监听 9059 端口，挂载于 Nginx /alertmgr 路径上，亦可通过 a.pigsty 域名直接访问：

AlertManager 支持多种通知渠道：邮件、Webhook、Slack、PagerDuty、企业微信等。 通过配置告警路由规则，可实现按严重程度、模块类型进行差异化分发，支持静默、抑制等高级功能。

更多信息请参阅：配置：INFRA - PROMETHEUS

BlackboxExporter

Blackbox Exporter 用于主动探测目标的可达性，实现黑盒监控。

默认监听 9115 端口，挂载于 Nginx /blackbox 路径上：

支持 ICMP Ping、TCP 端口、HTTP/HTTPS 端点等多种探测方式。 可用于监控 VIP 可达性、服务端口存活、外部依赖健康状态等场景，是判断故障影响范围的重要手段。

更多信息请参阅：配置：INFRA - PROMETHEUS

Ansible

Ansible 是 Pigsty 的核心编排工具，所有部署、配置、管理操作均通过 Ansible Playbook 完成。

Pigsty 在安装时会自动在管理节点（Infra 节点）上安装 Ansible。 它采用声明式配置风格与幂等剧本设计：同一剧本可重复执行，系统会自动收敛至期望状态，无需担心副作用。

Ansible 的核心优势：

• 无 Agent：通过 SSH 远程执行，无需在目标节点安装额外软件。
• 声明式：描述期望状态，而非执行步骤，配置即文档。
• 幂等性：多次执行结果一致，支持部分失败后重试。

更多信息请参阅：剧本：Pigsty Playbook

DNSMASQ

DNSMASQ 提供环境内的 DNS 解析服务，将 Pigsty 内部使用的域名解析到对应 IP 地址。

请注意，DNS 是完全可选的模块，Pigsty 本身不依赖 DNS 即可正常运行。

默认监听 53 端口（UDP/TCP），为环境内所有节点提供 DNS 解析：

其他模块在部署时会自动将域名注册到 INFRA 节点的 DNSMASQ 服务中，例如：

客户端节点可将 INFRA 节点配置为 DNS 服务器，即可通过域名访问各服务，无需记忆 IP 地址。

更多信息请参阅：配置：INFRA - DNS 与 教程：DNS：配置域名解析

Chronyd

Chronyd 提供 NTP 时间同步服务，确保环境内所有节点时钟一致。

默认监听 123 端口（UDP），作为环境内的时间源：

时间同步对分布式系统至关重要：日志排查需要时间戳对齐，证书校验依赖时钟准确，PostgreSQL 流复制也对时钟偏移敏感。 在隔离网络环境中，INFRA 节点可作为内部 NTP 服务器，其他节点同步至此。

更多信息请参阅：配置：NODE - NTP

节点与Infra的关系

节点关系

普通的节点，会通过 admin_ip 参数来引用某个 INFRA节点 作为它们的基础设施提供者。

例如，当你配置了全局的 admin_ip = 10.10.10.10，那么通常意味着所有节点都会使用这个 IP 上的基础设施服务。

以下是引用 ${admin_ip} 的配置参数列表

这是一种弱依赖关系

通常管理节点与基础设施节点（INFRA 节点）重合。若有多个 INFRA 节点，管理节点通常是其中第一个，其他作为备份。

在大规模生产环境部署的时候，您可能会出于各种原因，将安装 Ansible 管理节点与运行 Infra 模块的节点分离开来。 例如，使用 1-2 台迷你的专用主机，归属于 DBA 组，作为整个环境的控制中枢，ADMIN 节点。 使用 2-3 台高配置的物理机，作为整个环境的监控基础设施 INFRA 节点。

下表展示了不同规模部署中各类节点的典型数量：

3 - PGSQL 架构

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

每个集群都是一个 自治 的业务单元，由至少一个 主库实例 组成，并通过服务向外暴露能力。

在 Pigsty 的 PGSQL 模块中有四种核心实体：

• 集群（Cluster）：自治的 PostgreSQL 业务单元，用作其他实体的顶级命名空间。
• 服务（Service）：对外暴露能力的命名抽象，路由流量，并使用节点端口暴露服务。
• 实例（Instance）：由在单个节点上的运行进程和数据库文件组成的单一 PostgreSQL 服务器。
• 节点（Node）：运行 Linux + Systemd 环境的硬件资源抽象，可以是裸机、VM、容器或 Pod。

辅以"数据库"“角色"两个业务实体，共同组成完整的逻辑视图。如下图所示：

命名约定

• 集群名应为有效的 DNS 域名，不包含任何点号，正则表达式为：[a-zA-Z0-9-]+
• 服务名应以集群名为前缀，并以特定单词作为后缀：primary、replica、offline、delayed，中间用 - 连接。
• 实例名以集群名为前缀，以正整数实例号为后缀，用 - 连接，例如 ${cluster}-${seq}。
• 节点由其首要内网 IP 地址标识，因为 PGSQL 模块中数据库与主机 1:1 部署，所以主机名通常与实例名相同。

概览

下图是 PGSQL 模块的架构示意图，展示了各组件之间的交互关系：

PostgreSQL

PostgreSQL 是 PGSQL 模块的核心，默认监听 5432 端口提供关系型数据库服务。

在多个节点上以相同 pg_cluster 安装 PGSQL 模块，将自动基于流式复制组成高可用集群。 实例角色由 pg_role 定义：primary（主库）、replica（从库）、offline（离线从库）。

PostgreSQL 进程默认由 Patroni 托管，可根据 pg_conf 模板切换 OLTP/OLAP/CRIT/TINY 配置， 并通过 pg_parameters 覆盖任意参数。

更多信息请参阅：配置：PGSQL - PG_BOOTSTRAP

Patroni

Patroni 是 PostgreSQL 高可用控制器，默认监听 8008 端口提供 REST API。

Patroni 接管 PostgreSQL 的启动、停止、配置与健康状态，将领导者、成员信息写入 etcd。 它负责自动故障转移、保持复制因子、协调参数变更，并提供 REST API 供 HAProxy、监控与管理员查询。

HAProxy 通过 Patroni 健康检查端点判断实例角色，将流量路由至正确的主库或从库。 vip-manager 监视 etcd 中的领导者键，在主库切换时自动漂移 VIP。

更多信息请参阅：配置：PGSQL - PG_BOOTSTRAP

Pgbouncer

Pgbouncer 是轻量级连接池中间件，默认监听 6432 端口。

Pgbouncer 以无状态方式运行在每个实例上，通过本地 Unix Socket 连接 PostgreSQL， 用于吸收瞬时连接、稳定会话并提供额外指标。

Pigsty 默认让生产流量（读写服务 5433 / 只读服务 5434）经由 Pgbouncer， 仅默认服务（5436）与离线服务（5438）绕过连接池直连 PostgreSQL。

连接池模式由 pgbouncer_poolmode 控制，默认为 transaction（事务级复用）。 可通过 pgbouncer_enabled 关闭连接池。

更多信息请参阅：配置：PGSQL - PG_ACCESS

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 绑定到当前主库节点，实现透明漂移。

vip-manager 在每个 PG 节点上运行，监视 etcd 中由 Patroni 写入的领导者键， 将 pg_vip_address 绑定到当前主库节点的网络接口上。

当发生故障转移时，vip-manager 会立即释放旧主机上的 VIP，并在新主机上重新绑定， 保障旧主机不会继续响应请求，避免脑裂。

该组件可选，通过 pg_vip_enabled 启用。 启用后需确保所有节点处于同一 VLAN，否则 VIP 无法正确漂移。

更多信息请参阅：教程：VIP 配置 与 配置：PGSQL - PG_ACCESS

pgBackRest

pgBackRest 是专业的 PostgreSQL 备份恢复工具，支持全量/增量/差异备份与 WAL 归档。

pgBackRest 与 PostgreSQL 配合，在主库上创建备份仓库，执行备份与归档任务。 默认使用本地备份仓库（pgbackrest_method = local）， 也可配置为 MinIO 等对象存储，实现集中化备份管理。

初始化完成后可通过 pgbackrest_init_backup 自动发起首次全量备份。 恢复过程与 Patroni 集成，支持将副本引导为新的主库或备库。

更多信息请参阅：备份恢复 与 配置：PGSQL - PG_BACKUP

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 读取 Pgbouncer 的统计视图，提供连接池利用率、等待队列与命中率指标。 若禁用 Pgbouncer，本组件也应同时关闭。

更多信息请参阅：配置：PGSQL - PG_MONITOR

pgbackrest_exporter

pgbackrest_exporter 导出备份状态指标，默认监听 9854 端口。

pgbackrest_exporter 解析 pgBackRest 状态，生成最近备份时间、大小、类型等指标。 结合告警策略可快速发现备份过期或失败，保障数据安全。

更多信息请参阅：配置：PGSQL - PG_MONITOR

总结

PGSQL 模块为 Pigsty 提供生产级 PostgreSQL 高可用集群，是整个系统的核心。

典型的访问路径：客户端 → DNS/VIP → HAProxy（服务端口） → Pgbouncer → PostgreSQL。

Patroni 与 etcd 协同实现自动故障转移，pgBackRest 保障数据可恢复， 三个 Exporter 配合 VictoriaMetrics 提供完整的可观测性。

更多信息请参阅：PGSQL 模块 与 组件与交互