Patroni 4.1.5 介绍与选型指南

目标：全面认知 Patroni——PostgreSQL 生态中最主流的开源高可用（HA）编排方案，讲清它的定位、架构、功能、适用场景，并与 repmgr、pg_auto_failover、Stolon 等同类方案做量化对比，帮助你在自建 PostgreSQL 高可用时做出正确的选型决策。本文为认知篇，全部事实均来自官方源联网溯源并标注来源与查询日期（2026-10-20）；配套的部署实测内容见本专栏《Patroni 4.1.5 3 节点高可用集群部署指南》。

一、环境信息

本文是软件认知与选型篇，不依赖本地实验环境，全部信息通过官方渠道联网溯源取得，关键取证的来源与查询日期如下（查询日期统一为 2026-10-20）：

💡 说明：本章所有结论均可通过上表来源在 2026-10-20 当日复核。版本查询命令可在部署环境执行 patroni --version 确认（本文配套部署篇实测回显为 patroni 4.1.5）。

二、软件概述

2.1 项目定位

Patroni 官方对它的定义是「A template for PostgreSQL High Availability」（PostgreSQL 高可用模板，仓库描述原文）。它不是一个数据库，而是一个部署在 PostgreSQL 旁边的高可用编排器：每一台数据库服务器上运行一个 Patroni 进程，多个 Patroni 进程借助一个外部分布式配置存储（Distributed Configuration Store，DCS）完成选主、故障转移、流复制管理和集群状态仲裁，让「一主多从 + 自动故障转移」的 PostgreSQL 集群可以无人值守地运行。

项目沿革（README 原文溯源）：Patroni 前身是 Zalando 的 Patroni（"formerly known as Zalando's Patroni"），最初是 Compose 公司 Governor 项目的一个分支（"started as a fork of Governor"），由 Zalando 于 2016 年开源并持续主导至今；2025 年起项目仓库迁移至独立的 patroni 组织（LICENSE 版权行同时保留 Compose、Zalando SE 与 Patroni Contributors，实查于 2026-10-20）。

2.2 版本与发布节奏

GitHub Releases 实查（2026-10-20）显示 Patroni 维持三条并行维护线：

关键差异：4.0 是一次大版本演进（含 API 语义调整，如 patronictl 对 --master 等旧旗标更名、移除 bootstrap.users 自动建用户能力），从 3.x 升级前务必阅读 4.0 Release Notes。新部署建议直接采用 v4.1.5。

2.3 生态位

• 数据层：搭配 PostgreSQL 9.3–18（README 明示），本文配套实测使用 PostgreSQL 17.11。
• 共识层：搭配 etcd/Consul/ZooKeeper/Kubernetes 等任一 DCS（本文配套实测使用 etcd 3.5.21）。
• 接入层：官方 README 提供 HAProxy 单端点接入配置（"Patroni includes an HAProxy configuration for a single application endpoint"），也常与 keepalived VIP、PgBouncer 连接池组合。
• 安装方式：PyPI 包 pip install patroni[etcd3]；Kubernetes 场景另有 Spilo 镜像与 zalando-postgres-operator。

三、核心架构

3.1 三层架构

一个最小可用的 Patroni 集群由三层角色组成：

                 ┌────────────────────────────┐
                 │        接入层（可选）        │
                 │  HAProxy / VIP / PgBouncer  │
                 └──────┬───────────┬─────────┘
                        │           │
   ┌────────────────────▼───┐   ┌───▼────────────────────┐
   │ node1: patroni + PG(主) │   │ node2: patroni + PG(从) │──┐
   └───────────┬────────────┘   └────────────────────────┘  │
               │  REST API(8008)         REST API(8008)      │
               │        ┌───────────────┐                     │
               └────────►  DCS（etcd 等） ◄─────────────────────┘
                        │  领导者租约/集群配置  │
                 ┌──────▼──────────────────────┐
                 │ node3: patroni + PG(从)      │
                 └─────────────────────────────┘

• DCS 共识层：存储领导者租约（leader key）、集群动态配置、故障转移历史与各节点心跳。哪台机器能续期持有 leader key，哪台就是主库——选主本质上变成一次分布式锁竞争。
• Patroni 代理层：每节点一个守护进程（Python 实现），向下调用 pg_ctl/pg_rewind/pg_basebackup 管理 PostgreSQL 实例，向 DCS 维护租约与心跳，向本地暴露 REST API（默认 8008 端口）供节点间通信与负载均衡健康检查。
• PostgreSQL 数据层：真正的数据引擎，主从之间用 PostgreSQL 原生流复制（streaming replication）同步 WAL；从库落后过多时（超过 maximum_lag_on_failover）不会被提升为主。

3.2 一次故障转移是如何发生的

以三节点集群、DCS 为 etcd 为例（机制描述依据官方文档原理与本文配套部署篇实测行为综合）：

1. 正常态：主节点的 Patroni 每 ttl 秒周期内持续向 etcd 续期 leader key；两个从节点的 Patroni 各自汇报心跳与复制位点。
2. 主库宕机：leader key 在 ttl 秒内无法续期而过期；两个从节点的 Patroni 在下一个 loop_wait 周期发现空缺，发起选主。
3. 竞选条件：候选节点必须是健康、复制延迟在 maximum_lag_on_failover 以内的节点；DCS 保证同一时刻只有一个节点能获得锁（与 etcd 的 Raft 共识共同保证不会双主）。
4. 提升：胜出节点执行 pg_ctl promote 将自己提升为主，时间线（timeline）加一，并把事件写入集群历史（patronictl history 可查）。
5. 旧主回归：旧主重新上线后发现集群已有新主，自动调用 pg_rewind 把自己回退/追赶成新主的从库，重新加入流复制（本文配套部署篇实测：旧主停机 16 秒内新主完成提升，旧主回归后以 streaming 状态重新入列）。

💡 技术拓展：PostgreSQL 的「主从高可用」不止 Patroni 一种实现路线，常见方案的核心差异在于「谁来做仲裁」——

方案	仲裁机制	外部依赖	特点
Patroni	外部 DCS（etcd/Consul/ZK/K8s）租约选主	需要 DCS（奇数节点）	功能最全、自动化程度最高
repmgr	无独立仲裁，repmgrd 守护进程 + 元数据库	不需要 DCS	偏工具箱，自动切换策略保守
pg_auto_failover	独立 monitor 节点仲裁	不需要 DCS（需 monitor）	部署轻，但 monitor 是关键节点
Stolon	keeper + sentinel + proxy，状态存 DCS	需要 DCS	三角色分离，活跃度已停滞
手工 failover	DBA 人工决策	无	可控性最高，MTTR 最长

Patroni 用「外部 DCS + 本地代理」换取了最强的自动化与可观测性，代价是集群必须额外维护一套奇数节点的 DCS；本文及配套部署篇实际采用 Patroni + etcd 组合，理由是 etcd 部署轻、与 Patroni 的租约模型契合度最高、社区案例最丰富。

3.3 应用如何接入集群

主库地址会随故障转移漂移，因此应用不应直连某台服务器 IP，而是接入一个「跟随角色」的稳定端点，常见三种：

1. HAProxy：Patroni 官方提供 haproxy.cfg 模板，对 8008 REST API 的 /primary、/replica 端点做 HTTP 健康检查，把 5000 端口的连接导到当前主库（README 明示该用法，示例命令 psql --host 127.0.0.1 --port 5000 postgres）。
2. keepalived VIP：在持有主库的节点上绑定虚拟 IP，故障转移后 VIP 随角色漂移。
3. 客户端侧服务发现：直接轮询各节点 REST API 的 /patroni 端点读取 role 字段自行路由。

四、功能特性

以下特性均有官方来源支撑（README 原文或官方文档站章节，查询日期 2026-10-20）：

💡 说明：内置 Raft DCS（pysyncobj）仅建议测试环境使用，生产环境官方推荐独立 etcd/Consul/ZooKeeper 集群；Kubernetes 环境下也可直接用 K8s API 做后端（kubernetes extras），配合 Spilo 镜像即为 Zalando 生产同款形态。

4.1 值得注意的官方告警：Python 3.11+ 内存问题

README「Memory issue on Python 3.11+」章节明确提示：在 vm.overcommit_memory=2（PostgreSQL 官方推荐设置）等严格内存限制下，Patroni 跑在 Python 3.11+ 可能出现「REST API 无响应但进程健康」的异常（CPython issue #140746）。官方建议：使用 4.1.1+/4.0.8+ 版本（已缓解），并以 MALLOC_ARENA_MAX=1 环境变量启动 Patroni，必要时调低 thread_stack_size（默认 512kB）与 thread_pool_size（默认 5）。这直接指导生产环境两个决策：选 Python 3.10 或确保 Patroni ≥ 4.1.1、systemd 单元里显式设置 MALLOC_ARENA_MAX（本文配套部署篇实测环境为 Python 3.10 + Patroni 4.1.5，未触发该问题）。

五、快速开始（最小可用示例）

以下流程直接溯源官方 README「Running and Configuring」节（查询日期 2026-10-20），是最小化的本地体验路径（两个 patroni 节点 + 单 etcd），用于理解工作方式；生产化三节点部署请直接跳转本专栏《Patroni 4.1.5 3 节点高可用集群部署指南》。

1. 安装 Patroni 及 etcd 驱动（README 原文示例命令，依赖 extras 机制）：

pip install patroni[etcd3]

README 依赖 extras 清单原文（节选）：etcd/etcd3 对应 python-etcd、consul 对应 py-consul、zookeeper/exhibitor 对应 kazoo、kubernetes 对应 kubernetes、raft 对应 pysyncobj、psycopg3/psycopg2/psycopg2-binary 对应 PostgreSQL 驱动三选一。

2. 按 README 快速开始，在三个终端分别执行（官方原文命令）：

etcd --data-dir=data/etcd --enable-v2=true   # 终端 1：启动 etcd
./patroni.py postgres0.yml                   # 终端 2：节点 0
./patroni.py postgres1.yml                   # 终端 3：节点 1

3. 官方 README 同一节提供参考配置文件 postgres0.yml（仓库根目录），其中定义了 scope/name/restapi/etcd/postgresql 五个核心段；修改 YAML 即可观察集群行为变化（README 原话："Test different settings in the YAML files to see how the cluster's behavior changes. Kill some of the components to see how the system behaves."）。

⚠️ 注意：README 快速开始使用单实例 etcd 仅供体验；生产集群必须部署奇数节点（3 或 5）的 etcd 集群，否则 DCS 自身即是单点。

六、适用场景与限制

6.1 适用场景

1. 自管 PostgreSQL 高可用：裸金属/虚机上的主从集群自动化（自动故障转移、自动克隆、自动回卷），是 Patroni 的主战场。
2. 私有化交付：需要把带自动 failover 的 PG 集群打包进客户环境（etcd 可随集群一同交付）。
3. Kubernetes 上的 PostgreSQL：经 Spilo 镜像 + zalando-postgres-operator（或直接用 K8s DCS 后端）在容器平台交付。
4. Citus 分布式集群的协调器：为 Citus coordinator/worker 提供同样的高可用语义（3.0+ 官方支持）。
5. 跨机房容灾：利用 standby cluster 级联复制搭建异地灾备从集群。

6.2 限制与边界

• 不是备份方案：Patroni 只管高可用，不替代 pgBackRest/Barman 等物理备份（逻辑误删会被复制到从库，回滚靠备份 + 归档）。
• 不提供分片：水平拆分需另行组合 Citus 等扩展。
• 依赖 DCS 可用性：DCS 失去法定人数时集群进入只读/维持现状的保护态；DCS 自身必须奇数节点部署。
• 异步复制下的 RPO > 0：默认异步复制故障转移可能丢最后若干事务，零数据丢失需开启 synchronous_mode（README 明示支持）并接受写入延迟。
• 不是连接池：应用侧仍需 PgBouncer 等池化组件（本系列另有 PgBouncer 专栏覆盖）。
• Python 3.11+ 严格内存限制场景：见 4.1 节官方告警。

七、同类选型对比（量化）

7.1 量化对比表

以下数据取证于 2026-10-20（星数与最近提交来自 shields.io 徽章，版本/仓库状态来自 GitHub 仓库页与 Releases 页）：

关键差异解读：Patroni 在星数、提交频率、发布节奏三个活跃度维度全面领先，且是唯一把「初始化克隆 + pg_rewind 回卷 + 动态配置 + REST API + 多 DCS」做成闭环的方案；Stolon 星数虽高（4.8k），但已有约三年无提交，属于「历史名声大、当前不可选」；repmgr 与 pg_auto_failover 各胜在「无需外部 DCS」，适合不想维护 etcd 的团队。

7.2 关于「PGSolution」

任务语境中提到的「PGSolution」：经在 GitHub 仓库检索与 PostgreSQL 官方 Software Catalogue（Clustering/replication 分类页）核对，截至 2026-10-20 并不存在名为 PGSolution 的独立开源 PostgreSQL HA 软件（官方目录中收录的是 pg_auto_failover、Patroni、repmgr 等条目）。该名称更可能指向某厂商的商业发行版或解决方案集；若确有所指，应按具体厂商的许可与支持文档另行评估，本篇对比以官方目录收录且可量化取证的开源方案为准。

7.3 选型建议（如果…则…）

• 如果你的团队能维护一套 3 节点 etcd，追求最完整的自动化（克隆、回卷、切换、动态配置、REST、watchdog、standby cluster 全都要）→ Patroni，无明显短板。
• 如果你在 Kubernetes 上运行 → 优先评估 CloudNativePG / PGO / zalando-postgres-operator（Spilo，基于 Patroni），让 K8s 承担 DCS 与生命周期。
• 如果坚决不想引入外部 DCS，且能接受 monitor 节点仲裁模型 → pg_auto_failover（记得给 monitor 本身做高可用评估）。
• 如果只需要主从搭建与半自动切换的工具箱，DBA 团队有精力手工兜底 → repmgr。
• 如果存量环境是 Stolon → 制定迁移计划；新项目不要选 Stolon。
• 如果需要零数据丢失（RPO=0）→ Patroni + synchronous_mode 是开源方案里工程化最成熟的组合。

八、参考链接

• 官方仓库（含 README/LICENSE）：https://github.com/patroni/patroni
• 官方文档站：https://patroni.readthedocs.io
• Releases（版本实查）：https://github.com/patroni/patroni/releases
• 动态配置文档：https://github.com/patroni/patroni/blob/master/docs/dynamic_configuration.rst
• 复制模式文档：https://github.com/patroni/patroni/blob/master/docs/replication_modes.rst
• PostgreSQL 官方 Software Catalogue（Clustering/replication）：https://www.postgresql.org/download/products/3-clusteringreplication/
• 竞品仓库：https://github.com/EnterpriseDB/repmgr 、https://github.com/hapostgres/pg_auto_failover 、https://github.com/sorintlab/stolon
• 本专栏配套实测篇：《Patroni 4.1.5 3 节点高可用集群部署指南》《Patroni 4.1.5 配置参数详解》《Patroni 4.1.5 常用 CLI 命令与工具详解》