18.5 Pigsty 作为参考实现

本书选择 Pigsty，不是为了把 PostgreSQL 原理隐藏在自动化后面，而是为了让读者看到一套完整参考实现如何把原理变成可交付环境。

阅读方法始终是双向的：

平台职责 -> Pigsty 参数/组件/动作
Pigsty 现象 -> PostgreSQL/catalog/log/backup/route 证据

18.5.1 把 PostgreSQL、HA、备份、接入和观察组合起来

声明期望状态

Pigsty 4.4 的 Architecture 说明，它用 config inventory 与参数描述部署环境，再由 Ansible playbook 实现。

最小 cluster 声明大致包含：

pg-shop:
  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 }
    10.10.10.14: { pg_seq: 4, pg_role: offline }
  vars:
    pg_cluster: pg-shop
    pg_version: 18

声明有两个重要作用：

让拓扑、身份、版本与参数进入版本化评审；
让重复执行与漂移修复有一个共同期望。

它没有证明：

四个地址真的跨故障域；
存储与网络满足容量；
package repository 完整；
secret 已正确交付；
RPO/RTO 已演练；
业务应用兼容。

inventory 是控制平面输入，不是验收报告。

模块与职责映射

Pigsty 官方架构列出多个模块。本书关注：

模块/组件	本书中的职责
NODE	主机基线、监控、日志、HAProxy 等节点能力
ETCD	HA 的分布式配置与 leader 协调
PGSQL	PostgreSQL、Patroni、PgBouncer、pgBackRest、exporter
INFRA	软件仓库、DNS/NTP、指标/日志/告警/可视化
MINIO（可选）	S3-compatible 对象/备份仓库候选
REDIS（可选）	缓存候选，但 authority 仍由合同决定

模块安装并不改变业务边界。例如部署 REDIS 不会自动让它成为商品权威；部署 MINIO 也不会自动完成 media 两阶段状态机。

PostgreSQL 仍是数据面核心

自动化完成后，仍要从 PostgreSQL 验证：

SELECT current_setting('server_version');
SELECT pg_is_in_recovery();
TABLE pg_extension;
TABLE pg_roles;
SELECT * FROM pg_stat_replication;
SELECT * FROM pg_stat_wal_receiver;

以及：

database/schema/object owner
ACL
business checksum
extension versions
replication position
archive status
backup restore result

Pigsty 提供实现路径，不改变这些原生事实的语义。

Patroni 与 etcd 形成 HA 控制

Pigsty 的 High Availability 描述了参考链：

PostgreSQL physical streaming replication
  -> Patroni manages member role/process
  -> etcd provides DCS/leader election
  -> Patroni health API exposes current role
  -> HAProxy routes by health/role

理解边界：

PostgreSQL replication 决定数据复制位置；
Patroni 决定/执行 promotion 与成员管理；
etcd 参与 leader 共识，不存业务表；
HAProxy 决定新连接去哪，不复制数据；
client 必须处理切换期间连接/事务失败。

“自动切换”不是“请求无感成功”。切换中的连接会中断，未决事务需要应用依据幂等身份判断和重试。

复制不是备份

HA 复制会忠实传播：

DROP TABLE
wrong UPDATE
application bug
malicious committed change
logical corruption

Pigsty 官方 HA 文档也明确区分流复制故障覆盖与人为/软件错误恢复，后者需要延迟副本或 PITR。

因此平台组合同时需要：

HA: current service continuity
backup/WAL: historical recovery
PITR: select target time/LSN/transaction
forensics: preserve evidence before repair

第 20、21、32、35 章分别承担这些证据。

pgBackRest 形成恢复链，但恢复仍需演练

参考实现可生成 pgBackRest 配置、执行 base/differential/incremental backup、归档 WAL 并管理 repository。

验收不能止于：

backup command exit 0

还要证明：

repository manifest and retention
WAL continuity
encryption/key recovery
independent failure domain
empty isolated target restore
extension packages
business checksum
RTO under representative size
operator runbook

第 21 章会在隔离目标恢复；第 32 章选择随机 recovery target。

HAProxy 把拓扑封装为服务

Pigsty 官方 Service/Access 说明 service 由访问端点与 selector 组成，并提供默认 primary、replica、 default、offline 等服务。

概念映射：

primary endpoint  -> current writable primary
replica endpoint  -> eligible read-only members with fallback policy
offline endpoint  -> offline/analytical candidates
default endpoint  -> default PostgreSQL/PgBouncer path

要进一步验收：

health check 与实际 role 是否一致；
failover 后多久摘除旧 primary；
fallback 是否会把只读流量压回 primary；
client DNS/VIP/port 怎样接入；
TLS 在哪终止；
health endpoint 是否越权； -连接失败与重试风暴怎样受控。

PgBouncer 把连接变成有限资源池

池化可减少 backend 数、平滑短连接，但会引入语义：

session / transaction / statement pooling
prepared statements
temporary tables
session GUC
LISTEN/NOTIFY
advisory locks
server reset
cancel routing
authentication

应用是否兼容，取决于 pool mode 与使用的 session feature。第 22 章会用实际请求验证，不能只看 PgBouncer 端口可连。

offline replica 实现分析隔离候选

Pigsty 的 Offline Instance 把 pg_role: offline 用于慢查询、ETL、OLAP 与交互查询。

蓝图提出：

primary + 2 replicas + 1 offline

offline 服务合同：

read-only；
不保证 read-your-writes；
显示 replay lag；
分析连接池独立；
查询 timeout/temp 配额独立；
不默认承接 online replica 流量；
长查询与 WAL replay 冲突有明确处理。

节点存在不证明这些条件，仍需第 22、26、27 章。

观察栈连接组件信号

Pigsty 4.4 Monitoring 描述了 Grafana、VictoriaMetrics、VictoriaLogs 与 PostgreSQL/PgBouncer/ Patroni/HAProxy/Node 等 exporter/日志源。

平台至少需要关联：

client/service probe
HAProxy backend
PgBouncer queue/pool
PostgreSQL session/query/wait
Patroni role/timeline
replication lag
WAL/archive/backup
host CPU/memory/I/O/network
extension-specific state
business freshness

仪表盘只是表现层。alert owner、阈值依据、抑制、升级与 runbook 仍由团队定义。

18.5.2 哪些能力开箱可用，哪些仍需组织流程

三层“可用”

讨论开箱能力时应分：

L0 mechanism
  配置/组件/命令存在，能在受控环境执行

L1 environment validation
  目标环境完成身份、版本、行为和复位/恢复证据

L2 service acceptance
  目标、容量、安全、值班、变更、演练和业务签字成立

本章：

direct PostgreSQL fixture L1 = passed for chapter-specific mechanisms
Pigsty mapping = documented
Pigsty L1 = not-run
production L2 = pending chapters 19-36

不要把不同对象的 L1 混在一起：本地 PostgreSQL 18.4 实验通过，不等于目标 Linux/Pigsty cluster 通过。

参考实现可直接提供的机制

按官方能力，Pigsty 可以自动化：

host desired state
software repository/package deployment
PostgreSQL instance/cluster creation
Patroni/etcd HA wiring
HAProxy service definitions
PgBouncer deployment/configuration
pgBackRest configuration and scheduled backup
monitoring/log collection/dashboard/alerts baseline
roles/databases/extensions declarations
offline replica role

“提供机制”的准确含义：

有对应 module/parameter/playbook；
可以在支持环境中声明和部署；
有默认配置和可观察入口。

它不是针对 pg36_shop 的完成证明。

组织必须补齐的工作

工作	为什么不能由工具自动决定
数据 authority	业务语义与冲突裁决
SLO/error budget	业务损失、成本与风险取舍
RPO/RTO scope	故障模型与恢复价值
tenant trust	法规、组织与威胁模型
extension admission	功能收益、生命周期、支持
capacity headroom	真实 workload 与增长
on-call/RACI	人与组织责任
change approval	风险、窗口与可逆性
incident judgment	不完整证据下的取舍
postmortem actions	系统性改进优先级

自动化可以检查字段非空，不能替业务 owner 承诺。

默认值是起点，不是证据

生产环境常见错误：

default topology -> default failure guarantee
default HA timeout -> our RTO
default backup schedule -> our RPO
default dashboard -> complete observability
default password -> acceptable security
default pool size -> safe connection budget
default shared_buffers/work_mem -> tuned

正确流程：

document default
  -> explain why it may fit
  -> measure target
  -> accept/override
  -> validate
  -> monitor drift

secret 永远不属于示例 inventory

本章 pigsty-declaration.example.yml 只放不可用 sentinel：

password: "REPLACE_VIA_APPROVED_SECRET_SOURCE"

正式环境要决定：

secret authority
render/injection path
file permissions
rotation
revocation
backup/log redaction
break-glass
audit

示例中的明文不是“方便”，而是泄露路径。

配置成功后还要独立验收

部署命令成功后，验收从外到内：

inventory identity
host/OS/time/storage/network
package/version
PostgreSQL role and settings
replication/timeline
service selectors and endpoints
pool behavior
backup archive + isolated restore
monitoring and alert path
business golden
failure drill

每项证据要保存 target、时间、版本和执行者。截图可以辅助，不应是唯一机器证据。

环境与组织漂移

技术漂移：

manual ALTER SYSTEM
package patch mismatch
extension extversion mismatch
inventory not applied
certificate expiry
backup schedule disabled
alert rule changed

组织漂移：

owner 离职
on-call 无人
runbook 过期
SLO 与业务不匹配
例外无到期
恢复密钥不可得

平台治理必须同时检测两类。第二类不会出现在 pg_settings。

何时可以说“生产就绪”

至少满足：

offering approved
target L1 evidence retained
business acceptance golden passes
RPO/RTO drills pass
security threat model and tests pass
capacity has headroom
SLI/SLO/error budget approved
alerts reach accountable responder
change/rollback/upgrade tested
incident and recovery runbooks exercised
open exceptions bounded and expiring

因此本章不会使用“部署完成，所以生产就绪”的句式。

18.5.3 不把参考实现冒充唯一架构

稳定的是合同，变化的是实现

应尽量稳定：

service endpoint semantics
data authority
consistency/freshness
identity/privilege boundary
RPO/RTO definition
backup/recovery evidence
extension lifecycle
observability requirements
exit path

可以替换：

automation engine
HA controller/DCS
proxy/pooler
backup tool/repository
metrics/log stack
cloud/on-prem substrate

替换实现时，合同成为验收基线。

不要绕过组件理解

Pigsty 把复杂组件组合起来，但值班者仍需知道故障落在哪一层：

症状	可能层
endpoint 不通	DNS/VIP/HAProxy/network
pool queue 高	PgBouncer/connection budget
primary 不明确	Patroni/etcd/network partition
replica lag	PostgreSQL/WAL/I/O/long query
backup missing	archive/pgBackRest/repository/secret
dashboard blank	exporter/collection/storage/query
SQL wrong result	schema/data/extension/business semantics

“重跑 playbook”不是通用诊断，更可能覆盖证据或扩大变更。

不要把云托管与自托管简化成好坏

托管服务可能减少：

hardware lifecycle
base engine patching
some HA/backup implementation
control-plane construction

但团队仍负责：

data model
SQL/application behavior
roles/security configuration
SLO and capacity/cost
restore acceptance
extension compatibility
migration/exit
incident collaboration

自托管给予更多控制和透明度，也带来更多直接责任。选择应基于组织能力、法规、故障模型、成本与退出，而非身份认同。

保持原生证据层

无论实现是什么，都尽量保留：

SQL business golden
catalog inventory
configuration snapshot
backup manifest
restore checksum
service probe
fault timeline
versioned ADR

这些证据比某个 UI 路径更可迁移。

用接口封装平台差异

消费者看到：

service name
endpoint class
database
runtime identity
TLS/auth method
pool/session contract
SLO/freshness
quota
support/escalation

不应依赖：

当前 primary IP
Patroni member name
HAProxy 内部 selector
backup repository layout
Ansible role internals
monitoring storage schema

这样平台升级或替换时，业务应用变更最小。

参考实现也必须有退出路线

从 Pigsty 迁出并不是“一条 pg_dump”：

冻结 PostgreSQL/extension/locale/role 依赖；
选择 physical 或 logical 路径；
重建 service endpoint 与 pooling 语义；
重建 backup/PITR；
重建 monitoring/alerts；
验证 HA 与 failover；
验证业务 golden；
切换并保留回退；
退役旧控制面与 secret。

反向迁入同样需要这些合同。

一个合格的参考映射

本章示例 YAML 明确注释：

not Pigsty L1 validated
example IPs
no real secrets
backup policy pending
synchronous mode not selected
ports/selectors/pool pending chapter 22
extension lifecycle governed outside package list

有意保留 unknown，比填入未经证实的“最佳实践”更专业。

何时偏离 Pigsty 参考

可以偏离，只要有证据：

existing organizational platform already satisfies contracts
managed service is required
unsupported OS/network/security boundary
different HA/recovery model
specialized kernel/distribution
team skills and support model
regulatory requirement
cost/capacity evidence

偏离应写 ADR，包含等价职责、差异、风险与退出，而不是静默拼装。

本书为什么仍然以 Pigsty 实战

因为读者要从 SQL 走到生产，必须面对：

host
package
topology
service endpoint
pool
HA
backup
monitoring
change
incident

Pigsty 给出一个可以落地、查看、运行与破坏性演练的完整对象；PostgreSQL 原生证据则防止读者只会操作一个封装。两条线并行，才能真正迁移知识。

这一章的最终边界

我们接受：

Pigsty 4.4 是 pg36_shop 下卷的参考实现。

我们尚未接受：

示例 inventory 已经可以部署生产，或提案中的 SLO 已经实现。

后一项只有在下卷 evidence 完成后才可能成立。

上一节：平台服务目录与多租户 · 返回本章目录 · 下一节：实战：设计 pg36_shop 生产蓝图 · 查看全书目录 · 查看索引中心

最后更新于 2026-07-30

18.4 平台服务目录与多租户 18.6 实战：设计 `pg36_shop` 生产蓝图