Patroni 是 Zalando 开源、Python 开发的 PostgreSQL 高可用编排工具业界 PostgreSQL 高可用事实标准。底层基于 PostgreSQL 原生物理流复制不修改数据库内核依靠外部 DCS 分布式一致性存储完成选主、故障转移、脑裂防护。读音pa‑tro‑ni读作「帕特罗尼」对比 repmgrrepmgr集群元数据存储在 PG 内部表节点之间互相投票需要 witness 见证节点防脑裂。Patroni集群状态全部保存在外部 DCS(etcd/consul/zookeeper)依靠分布式协议选主天然防脑裂。一、整体架构Patroni 集群由 4 类组件构成patroni agent每个PG节点部署Python 常驻进程管理本机 PostgreSQL 实例启停PG、主备提升、降级、配置下发、上报节点状态。⚠️ 禁止直接使用 systemd 管理 postgresqlPG 生命周期交给 patroni否则存在脑裂风险。自带 REST API默认端口8008用于状态查询、触发切换、监控检测。DCS 分布式配置存储Distributed Configuration Store集群唯一真相源保存 leader 锁、所有成员状态、集群动态配置、复制信息、timeline。支持后端etcd生产最常用ConsulZooKeeperKubernetes APIDCS 自身必须高可用一般部署 3/5 节点保证 quorum 多数派。PostgreSQL 实例primary主库、replica备库使用 PG 原生物理流复制支持复制槽、pg_rewind。连接代理层可选HAProxy / VIP / PgBouncerPatroni本身不提供连接转发、不提供虚拟IP。主备切换完成后应用需要感知新主地址。常见三种方案HAProxy patroni REST API 健康检查自动路由读写流量keepalived / vip‑managerpatroni 回调脚本浮动 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模式含义使用场景switchover计划内手动优雅切换版本升级、硬件维护业务低峰尽量零数据丢失failover自动故障转移主库异常宕机自动触发短暂业务中断可能少量 WAL 丢失3. pg_rewind 自动回退故障恢复后的旧主时间线已经分裂Patroni 会自动调用pg_rewind把旧主回退为备库无需人工全量重建数据库。repmgr 需要手动执行 pg_rewind。4. 集群动态配置集群配置保存在 DCS全局统一对所有节点生效。使用patronictl edit‑config修改配置自动下发全部节点reload 即可生效参数需要数据库重启生效参数部分 PG 核心参数wal_level、max_connections全局强制统一本地 yaml 会被 DCS 配置覆盖。三、命令行工具patroniagent 守护进程每个数据库节点运行读取patroni.yml。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生产建议ttlloop_wait * 2常用ttl30loop_wait10。五、failover 自动故障转移完整流程Primary 宕机patroni agent 停止不再刷新 DCS leader 锁DCS 中 leader key TTL 到期锁释放所有 replica 观察锁消失发起选举DCS 通过 Raft 协议选举授予某个节点 leader 锁获取锁的节点执行 pg_promote提升为新 primary其余备库修改复制源指向新主库老主故障恢复启动patroni 发现自己不再是 leader调用 pg_rewind 回退时间线自动转为备库重新加入集群HAProxy 调用 patroni REST API/primary健康检查业务流量切到新主。六、Patroni vs repmgr 对比七、Patroni 的短板与坑点需要额外维护 DCSetcd 3 节点增加运维负担DCS 整体不可用时patroni 进入 failsafe 模式需要人工介入DCS 不能单点不自带 VIP、代理组件必须搭配 HAProxy /keepalivedPostgreSQL 实例管理权完全交给 patroni禁止 systemd 启停 pg两节点 PG 集群可以运行但 DCS 仍然至少 3 节点DCS quorum 丢失则无法选举只管理物理流复制不管理逻辑复制读写分离依赖外部代理。八、生产最佳实践etcd 部署在独立机器尽量不和 PG 混部做好 etcd 备份使用 HAProxy利用 patroni/primary、/replica接口做健康检查开启use_pg_rewind: true故障节点自动修复设置合理maximum_lag_on_failover避免延迟过高副本升主重大维护前执行patronictl pause关闭自动故障转移维护完成 resume监控项DCS 集群健康、patroni REST API、PG 复制延迟、timeline 变更、failover 切换历史。