Patroni 技术文档:配置与高可用机制 #HaishanDB

1. 概述

Patroni 是用于 PostgreSQL 的高可用集群管理器，通过分布式配置存储（DCS）实现自动化故障转移、主节点选举和集群全生命周期管理。它由 Zalando 开源，采用 Python 开发，被公认为当前生产环境最主流的 PostgreSQL 高可用方案。

核心能力：自动故障转移、脑裂防护、节点自愈、跨数据中心灾备。

2. 架构简述

Patroni 集群由三层组成：

·PostgreSQL 节点：实际提供数据库服务，包含一主多备。

·Patroni 守护进程：运行在每个数据库节点上，负责监控、决策和配置同步。

·DCS（分布式配置存储）：如 etcd / Consul / ZooKeeper，存储集群状态和元数据，提供领导选举所需的分布式锁。

3. Patroni 配置文件详解

每个节点都需要一份 patroni.yml，以下对核心配置块进行逐段解释。

3.1 基础标识与 DCS 连接

scope: pg_cluster # 集群名称，同一集群所有节点必须一致namespace: /service/ # DCS 中存储路径前缀name: pg1 # 节点名，必须唯一

restapi:listen: 0.0.0.0:8008 # REST API 监听地址connect_address: 192.168.17.20:8008 # 其他节点可访问的地址

etcd:hosts: 192.168.17.20:2379,192.168.17.21:2379,192.168.17.22:2379

·scope用于隔离不同集群，同一套 etcd 中可以有多个 scope。

·name用于唯一标识当前节点，一旦运行不建议更改。

3.2 集群初始化与动态配置 (bootstrap)

bootstrap定义集群首次初始化时的参数，以及之后可动态修改的配置。

bootstrap:dcs:ttl: 30 # Leader 锁超时时间（秒）loop_wait: 10 # 主循环间隔（秒）retry_timeout: 10 # DCS 操作重试超时（秒）maximum_lag_on_failover: 1048576 # 允许故障转移的最大复制延迟（字节），超过则备节点不参与选主postgresql:use_pg_rewind: true # 启用 pg_rewind 快速回切旧主use_slots: true # 启用复制槽，防止 WAL 被过早清理parameters:# PostgreSQL 初始化参数（initdb）initdb:– encoding: UTF8– data-checksums# pg_hba 条目pg_hba:– host replication replicator 192.168.17.0/24 md5– host all all 0.0.0.0/0 md5

关键参数说明：

参数	作用
ttl	主节点需在 ttl 秒内刷新领导令牌，超时则令牌失效触发选举
loop_wait	Patroni 检查状态、尝试获取/刷新令牌的间隔
maximum_lag_on_failover	防止数据差异过大的备节点被提升为新主
use_pg_rewind	让旧主可以快速追齐新主时间线，重新加入集群
use_slots	物理复制槽可防止备节点所需 WAL 被清理，避免出现 requested WAL segment has already been removed

3.3 PostgreSQL本地配置

postgresql:listen: 192.168.17.20:5432connect_address: 192.168.17.20:5432 # 其他节点连接本机数据库的地址data_dir: /opt/pgdatabin_dir: /opt/pgsql/binpgpass: /tmp/pgpass # 存储密码文件路径authentication:replication:username: replicatorpassword: replicatorsuperuser:username: postgrespassword: postgresparameters:# 可在 bootstrap 中定义，也可在此覆盖某些 PostgreSQL 参数max_connections: 200shared_buffers: 256MB

·connect_address必须正确，其他节点通过此地址建立流复制。

·复制用户和超级用户的认证信息用于 Patroni 管理PostgreSQL实例。

3.4 Watchdog 配置

watchdog:

mode: required

# required | off | automatic

device: /dev/watchdog

safety_margin: 5

# 安全余量，必须小于 ttl

当 Patroni 无法续约领导令牌（如进程卡死、网络隔离）时，Watchdog 会触发系统重启当前节点，避免出现“双主”脑裂。这是防范脑裂的最后一道硬件级防线。

3.5 标签（Tags）

tags:

nofailover: false

# true 则该节点不参与自动故障转移的主节点选举

clonefrom: true

# 允许其他节点从此节点克隆

# 可以自定义标签，用于调度

4. 高可用与故障转移机制

4.1 领导令牌与选举

Patroni 的高可用基于DCS提供的 Leader Key（领导令牌）实现：

·每个节点在主循环中检查是否持有令牌。

·若自己是 Leader，则刷新令牌 TTL；同时确保 PostgreSQL 运行在主模式。

·若未持有令牌但发现集群无主（令牌过期），则尝试通过 DCS 的 CAS 操作获取令牌。成功者提升为主，失败者继续以备节点运行。

·若集群已有主，则本节点自动配置流复制指向当前主节点。

由于DCS保证令牌的唯一性，任意时刻最多只有一个节点能成为主，从机制上杜绝了脑裂。

4.2 自动故障转移流程

当主节点发生故障（如宕机、网络不通、PostgreSQL 崩溃）时：

1 心跳超时：主节点在 ttl秒内未刷新令牌，令牌过期。

2选举触发：各备节点检测到令牌过期，开始竞选。竞选规则：

·节点本身必须健康，且标记nofailover不为true。

·复制延迟需小于maximum_lag_on_failover。

·优先选择LSN（日志序列号）更大（即数据更新）的节点。

3提升新主：获胜节点在 DCS 中创建新令牌，执行pg_ctl promote将自己提升为主。

4拓扑重配：Patroni更新DCS中的members信息，其他备节点检测到新主后重新建立流复制。

5原主恢复：当故障节点恢复时，Patroni 检测到它曾为主且已不是最新时间线，会自动使用pg_rewind（若启用）将其快速同步并加入集群为备节点。若 pg_rewind失败，则执行全量pg_basebackup重建。

4.3 手动切换 (Switchover)

计划内维护可通过patronictl switchover平滑切换主备，流程与自动故障转移类似，但更可控：

·Patroni会先确认候选节点健康且延迟在允许范围内。

·先将旧主降级为备，再提升候选节点为主。

·整个过程对应用影响极小。

4.4 脑裂防护三层机制

层次	机制	作用
应用层（Patroni）	失去 Leader 令牌立即降级，不会继续接收写请求	防止双主在应用层共存
协调层（DCS）	强一致性分布式锁，同一时刻仅一个节点持有令牌	保证全局视角唯一主
系统层（Watchdog）	卡死或进程异常时强制重启当前机器	物理确保旧主无法继续服务

4.5 节点自愈与复制管理

·自动重启：PostgreSQL 异常退出后，Patroni自动重启实例。

·自动重建副本：备节点若因 WAL 缺失、时间线分叉等原因无法继续复制，Patroni 会自动从主节点（或 clonefrom标记的节点）全量重建。

·复制槽维护：启用use_slots后，Patroni 会在主节点创建并管理复制槽，防止备节点所需的WAL被清理；故障转移时会自动在新主上创建缺失的槽。

4.6 Standby Cluster（异地灾备集群）

Standby Cluster是一种级联复制方案，用于跨数据中心灾备：

·该集群内部也有一个“Standby Leader”（对主集群而言它只是一个备节点）。

·所有 Standby Cluster内的其他节点从该 Standby Leader复制。

·当主集群整体不可用时，可以将 Standby Cluster提升为独立的新主集群。

适用场景：地理冗余、云迁移、读写分离异地访问、灾备演练。

5. 最佳实践配置建议

·同步复制：通过设置synchronous_mode: true和synchronous_node_count保证至少指定数量的备节点写入成功后才返回提交确认，实现零数据丢失故障转移，但会略微增加写延迟。

·合理设置TTL：ttl不宜过小（避免网络抖动导致误判）也不宜过大（增大故障转移时间）。通常网络稳定环境设为 30 秒，loop_wait设为 10 秒。

·启用 pg_rewind：建议开启 use_pg_rewind: true，并确保 PostgreSQL 编译时有该功能，这样旧主恢复时无需全量重建。

·监控 REST API：通过 /health、/primary、/replica等端点集成到监控和负载均衡器中。 #HaishanDB #He3DB #Patroni

感谢阅读，如果这篇文章对你有帮助，欢迎点赞、在看、转发支持。

更多数据库硬核干货、实战避坑指南，请持续关注「什么都要学点」，一起在数据的世界里精进。