企业官网建设流程全解析

Patroni 是 Zalando 开源、Python 开发的 PostgreSQL 高可用编排工具，业界 PostgreSQL 高可用事实标准。底层基于 PostgreSQL 原生物理流复制，不修改数据库内核；依靠外部 DCS 分布式一致性存储完成选主、故障转移、脑裂防护。

读音：pa‑tro‑ni，读作「帕特罗尼」
对比 repmgr：

• repmgr：集群元数据存储在 PG 内部表，节点之间互相投票；需要 witness 见证节点防脑裂。
• Patroni：集群状态全部保存在外部 DCS(etcd/consul/zookeeper)，依靠分布式协议选主，天然防脑裂。

一、整体架构

Patroni 集群由 4 类组件构成：

1. patroni agent（每个PG节点部署）
   Python 常驻进程，管理本机 PostgreSQL 实例：启停PG、主备提升、降级、配置下发、上报节点状态。

⚠️ 禁止直接使用 systemd 管理 postgresql，PG 生命周期交给 patroni，否则存在脑裂风险。
自带 REST API，默认端口8008，用于状态查询、触发切换、监控检测。

2. DCS 分布式配置存储（Distributed Configuration Store）
   集群唯一真相源，保存 leader 锁、所有成员状态、集群动态配置、复制信息、timeline。
   支持后端：

• etcd（生产最常用）
• Consul
• ZooKeeper
• Kubernetes API

DCS 自身必须高可用，一般部署 3/5 节点保证 quorum 多数派。

3. PostgreSQL 实例
   primary（主库）、replica（备库），使用 PG 原生物理流复制，支持复制槽、pg_rewind。

4. 连接代理层（可选，HAProxy / VIP / PgBouncer）
   Patroni本身不提供连接转发、不提供虚拟IP。主备切换完成后应用需要感知新主地址。
   常见三种方案：

• HAProxy + patroni REST API 健康检查，自动路由读写流量
• keepalived / vip‑manager，patroni 回调脚本浮动 VIP
• 应用端配置多地址列表

典型生产架构：Patroni(PG×3) + etcd(3节点) + HAProxy + Keepalived(VIP)

二、核心概念

1. Leader 锁 TTL 租约机制

主节点在 DCS 持有带 TTL 超时的 leader 锁：

• 主节点每loop_wait周期向 DCS 刷新锁；
• 主库宕机 / 网络隔离，锁超时自动释放；
• 备节点检测 leader 锁消失，发起选举竞争锁；
• 抢到 DCS leader 锁的节点才有资格提升为主库。

网络分区场景：老主无法连接 DCS，锁过期，patroni 主动将本地 PG 降级为备库，从根源避免脑裂。

2. switchover vs failover

3. pg_rewind 自动回退

故障恢复后的旧主时间线已经分裂，Patroni 会自动调用pg_rewind，把旧主回退为备库，无需人工全量重建数据库。

repmgr 需要手动执行 pg_rewind。

4. 集群动态配置

集群配置保存在 DCS，全局统一对所有节点生效。
使用patronictl edit‑config修改配置，自动下发全部节点：

• reload 即可生效参数
• 需要数据库重启生效参数

部分 PG 核心参数（wal_level、max_connections）全局强制统一，本地 yaml 会被 DCS 配置覆盖。

三、命令行工具

1. patroni：agent 守护进程，每个数据库节点运行，读取patroni.yml。
2. patronictl：集群运维客户端工具。

# 查看集群状态patronictl-c/etc/patroni.yml list# 计划内主备切换patronictl-c/etc/patroni.yml switchover# 手动强制故障转移patronictl-c/etc/patroni.yml failover# 编辑集群全局动态配置patronictl-c/etc/patroni.yml edit‑config# 重新初始化异常副本patronictl-c/etc/patroni.yml reinit node‑2# 暂停自动故障转移（维护窗口）patronictl-c/etc/patroni.yml pause# 恢复自动故障转移patronictl-c/etc/patroni.yml resume# 查看切换历史记录patronictl-c/etc/patroni.ymlhistory

四、patroni.yml 关键配置参数

dcs: ttl:30# leader锁TTL超时时间，超时锁失效loop_wait:10# patroni主循环间隔，刷新锁、状态检查retry_timeout:10# DCS/PG操作超时时间maximum_lag_on_failover:1048576# 故障转移允许备库最大延迟(字节)，延迟过大不升主postgresql: use_slots:true# 开启复制槽use_pg_rewind:true# 故障节点恢复自动pg_rewindparameters: wal_level: replica max_connections:200

生产建议：ttl>loop_wait * 2；常用ttl=30，loop_wait=10。

五、failover 自动故障转移完整流程

1. Primary 宕机，patroni agent 停止，不再刷新 DCS leader 锁；
2. DCS 中 leader key TTL 到期，锁释放；
3. 所有 replica 观察锁消失，发起选举；
4. DCS 通过 Raft 协议选举，授予某个节点 leader 锁；
5. 获取锁的节点执行 pg_promote，提升为新 primary；
6. 其余备库修改复制源，指向新主库；
7. 老主故障恢复启动：patroni 发现自己不再是 leader，调用 pg_rewind 回退时间线，自动转为备库重新加入集群；
8. HAProxy 调用 patroni REST API/primary健康检查，业务流量切到新主。

六、Patroni vs repmgr 对比

七、Patroni 的短板与坑点

1. 需要额外维护 DCS（etcd 3 节点），增加运维负担；
2. DCS 整体不可用时，patroni 进入 failsafe 模式，需要人工介入；DCS 不能单点；
3. 不自带 VIP、代理组件，必须搭配 HAProxy /keepalived；
4. PostgreSQL 实例管理权完全交给 patroni，禁止 systemd 启停 pg；
5. 两节点 PG 集群可以运行，但 DCS 仍然至少 3 节点；DCS quorum 丢失则无法选举；
6. 只管理物理流复制，不管理逻辑复制；读写分离依赖外部代理。

八、生产最佳实践

1. etcd 部署在独立机器，尽量不和 PG 混部，做好 etcd 备份；
2. 使用 HAProxy，利用 patroni/primary、/replica接口做健康检查；
3. 开启use_pg_rewind: true，故障节点自动修复；
4. 设置合理maximum_lag_on_failover，避免延迟过高副本升主；
5. 重大维护前执行patronictl pause，关闭自动故障转移，维护完成 resume；
6. 监控项：DCS 集群健康、patroni REST API、PG 复制延迟、timeline 变更、failover 切换历史。