1.5 Pigsty 的资源模型

上一节把数据库平台拆成一组通用职责。本节只做一件事：把这些职责映射到 Pigsty v4.4 的实体、组件和证据源。记住映射比背命令重要，因为端口、界面和组件版本会变化，而“谁负责数据、谁负责角色判断、谁负责路由”必须始终说得清。

1.5.1 节点、集群、实例与服务

Pigsty 的 PGSQL 模块使用四个核心实体组织 PostgreSQL：

Pigsty 默认采用节点与 PostgreSQL 实例 1:1 的独占部署模型，因此节点名经常借用实例名；这是 Pigsty 的部署约定，不是 PostgreSQL 限制。pg_cluster、pg_seq 和 pg_role 三个身份参数构成最小声明：

pg-meta:
  hosts:
    10.10.10.10: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-meta

由此可以推导：

节点：10.10.10.10（默认命名可为 pg-meta-1）
实例：pg-meta-1
集群：pg-meta
服务：pg-meta-primary / pg-meta-replica / pg-meta-default / pg-meta-offline

配置中的 pg_role: primary 表示初始化或编排意图，不是永远不变的运行角色。多节点集群发生切换后，主库可以从 pg-meta-1 变成其他实例，而实例编号不变。服务名表达访问意图，也不应跟着当前主实例改名。

在 Pigsty 管理节点的安装目录中，用只读命令观察解析后的配置范围：

cd ~/pigsty

# 只显示分组与主机关系，不输出包含密码的完整变量
ansible-inventory --graph

# 只从源文件定位非敏感身份字段；动态清单环境应改查相应 CMDB
grep -nE 'pg-meta:|pg_cluster:|pg_seq:|pg_role:' pigsty.yml

不要把完整 ansible-inventory --list 直接贴进工单或书稿，它可能包含密码、令牌和内部地址。证据包只采集解决当前问题所需的字段。

单节点 L1 会让四种服务最终落到同一台节点甚至同一个 PostgreSQL 实例，但实体仍然不同。就像一位工程师可以兼任开发、值班和发布审批，职责名称相同不意味着角色边界消失。

1.5.2 PostgreSQL、Patroni、PgBouncer 与 HAProxy 的职责

一条默认生产读写连接的路径是：

客户端
  → HAProxy :5433
  → 当前主实例上的 PgBouncer :6432
  → PostgreSQL :5432

组件之间不是相互替代，而是逐层收窄职责：

在高可用集群中，Patroni 通常使用 etcd 之类的分布式配置存储（DCS）协调领导者信息。HAProxy 请求 Patroni 健康接口判断实例角色，再把 5433 流量送往主库的 PgBouncer。PgBouncer 最后通过本地连接进入 PostgreSQL。

Pigsty v4.4 的默认入口如下，均可配置：

“默认目标”必须结合配置阅读。例如 pg_default_service_dest 可以让 primary/replica 服务绕过 PgBouncer。不要仅凭端口号推断实际路径。

在管理节点上查看控制面状态：

# R0：列出集群成员、角色和复制状态
pg list pg-meta

在数据库中从另一侧复核：

SELECT
    pg_is_in_recovery() AS in_recovery,
    current_setting('port') AS postgres_port,
    inet_server_addr() AS server_addr,
    inet_server_port() AS accepted_port;

若 pg list 报告 Leader，而 SQL 的 pg_is_in_recovery() 为 true，不要挑一个自己喜欢的结果继续操作。先停止角色相关变更，确认两条命令是否观察了同一集群、同一实例和同一时刻，再检查 Patroni 与 PostgreSQL 日志。配置标签、控制面判断和内核运行状态不一致，本身就是需要处理的事件。

本节暂不演练切换、连接池模式或代理重载；它们分别属于 ch20《高可用拓扑与容灾目标》和 ch22《服务接入、连接池与路由》。

1.5.3 配置清单、运行状态与监控事实分别来自哪里

Pigsty 环境至少存在三类事实源：

配置清单：系统应当是什么

默认静态清单是 ~/pigsty/pigsty.yml，也可以使用动态 inventory 或 CMDB。它声明节点、集群、初始角色、数据库、用户、服务和参数。清单适合回答“期望如何配置”，不能单独证明变更已经执行并生效。

运行状态：系统现在是什么

运行状态分散在各组件中：

• PostgreSQL：SQL、系统目录、统计视图和日志；
• Patroni：成员与角色状态、DCS 信息、健康接口和日志；
• PgBouncer：连接池状态、管理控制台和日志；
• HAProxy：服务后端、健康检查、运行配置和日志；
• systemd 与主机：进程、端口、文件、资源和服务状态。

例如，“当前谁是主库”首先要看 PostgreSQL 与 Patroni 的实时状态，而不是初始化清单中的 pg_role 标签。

监控事实：系统在一段时间内发生了什么

Pigsty 的采集系统把 PostgreSQL、主机、组件和日志事实转换成带标签的时间序列与日志流。常见身份标签包括：

• cls：集群；
• ins：实例；
• ip：节点地址；
• job：采集任务或日志来源；
• datname、relname、idxname：数据库内部对象。

监控适合回答趋势、持续时间和事件先后，但它仍可能受采集间隔、标签错误、查询权限和数据保留影响。面板显示“主库”时，应能追到指标标签与原生 SQL；SQL 显示瞬时正常时，也不能据此否认五分钟前的告警。

建立一张证据优先级表：

实战：生成 L1 资源快照

在管理节点执行：

cd ~/pigsty

{
  printf 'captured_at=%s\n' "$(date -Is)"
  printf 'host=%s\n' "$(hostname -f 2>/dev/null || hostname)"
  printf 'pigsty_source=%s\n' "$(git describe --tags --always 2>/dev/null || printf unknown)"
  printf '%s\n' '--- inventory graph ---'
  ansible-inventory --graph
  printf '%s\n' '--- cluster runtime ---'
  pg list pg-meta
} > pg36-l1-platform.txt

这段脚本只采集身份与拓扑，不输出完整变量。若环境不是 Git 安装，pigsty_source=unknown 是有效结果，随后应从发行包或发布记录补充版本，而不是编造标签。

在数据库端另存原生快照：

psql -X "$PG36_BOOTSTRAP_URL" -A -t -c "
SELECT jsonb_build_object(
  'captured_at', clock_timestamp(),
  'database', current_database(),
  'user', current_user,
  'server_addr', inet_server_addr(),
  'server_port', inet_server_port(),
  'version', current_setting('server_version'),
  'in_recovery', pg_is_in_recovery()
);" > pg36-l1-postgres.json

两份文件共同构成证据：一份描述平台，一份描述 PostgreSQL。提交或分享前检查是否含有内部地址、用户名或其他不应公开的信息；密码和令牌在任何情况下都不应进入证据包。

本节验收

你应当能够从 L1 环境指出：

• 哪个名字是节点、实例、集群和服务；
• 5432、6432、5433 各由哪个组件接收；
• 配置清单、pg list、SQL 与监控分别回答什么问题；
• 当这些证据冲突时，为什么“重新运行自动化让它一致”不是安全的第一动作。

参考资料

• Pigsty v4.4：PGSQL 集群模型
• Pigsty v4.4：PGSQL 架构
• Pigsty v4.4：服务与接入
• Pigsty v4.4：发布注记

上一节：从数据库实例到数据库服务 · 返回本章目录 · 下一节：最小 psql 生存卡 · 查看全书目录 · 查看索引中心