PATRONI

警告 在 内存受限且使用 Python 3.11+ 的系统 上运行 Patroni 如果系统设置了严格的内存限制，例如启用 PostgreSQL 推荐的 vm.overcommit_memory=2，并使用 Python 3.11 或更高版本，可能出现以下异常： Patroni 表面上保持健康； PostgreSQL 继续运行； Patroni REST API 失去响应； 操作系统仍显示 Patroni 正在监听 REST API 端口； Patroni 日志看似正常，但以下消息可能只出现一 …

在线交流 如有疑问、需要互动式故障排查帮助，或希望与其他 Patroni 用户交流，欢迎加入 PostgreSQL Slack 的 #patroni 频道。 报告缺陷 提交缺陷报告前，请务必 在最新版 Patroni 上复现该问题！同时请仔细核对 问题跟踪器 中是否已存在相同问题。 运行测试 运行 behave 测试的前置条件： 需要安装包含 contrib 模块的 PostgreSQL 软件包。 PostgreSQL 二进制文件必须在 PATH 中可访问。你可能需要通过类似 …

版本 4.1.5 发布于 2026-08-12 兼容性改进 兼容 PostgreSQL 14.24、15.19、16.15、17.11 与 18.6（Alexander Kukushkin） 添加用于限制逻辑解码输出插件的新 GUC output_plugin_libraries。 改进 将 REST API 连接重置的日志级别从 WARNING 调整为 DEBUG（Kyle McLaren） 屏蔽常见的“客户端在写入中途离开”类日志，同时不影响真正的非连接类错误处理。 错误修复 修正 …

本节收录了关于 Patroni 最常见问题的解答，各子节聚焦于不同类别的问题。 希望这些内容能帮你解答大多数疑问。如果仍有疑问或遇到意外问题，请参阅 交流 和 报告问题，了解如何获取帮助或提交问题报告。 与其他高可用方案的比较 为什么 Patroni 需要独立的 DCS 节点集群，而 repmgr 等其他方案不需要？ 实现高可用方案有多种不同方式，各有优缺点。 repmgr 等软件通过节点间通信来决定何时采取行动。 而 Patroni 则依赖存储在 DCS 中的状态，DCS 是 Patroni …

部署在多个数据中心的 PostgreSQL 集群，其高可用基于复制实现，复制可以是同步的，也可以是异步的（参见 复制模式）。 无论哪种模式，明确以下概念都很重要： PostgreSQL 仅在持有领导者键且能够更新领导者键时，才能以主库或备用领导者身份运行。 etcd、ZooKeeper 或 Consul 节点的数量应为奇数：3 个或 5 个！ 同步复制 要构建能够自动容忍单区域故障的多数据中心集群，至少需要 3 个数据中心。 架构图如下： 必须跨不同数据中心部署一个 …

Patroni 集群有两个需要防范未授权访问的接口：分布式配置存储（DCS）和 Patroni REST API。 保护 DCS Patroni 和 patronictl 都会向 DCS 读写数据。 即使 DCS 中未存储敏感信息，它仍允许修改部分 Patroni/PostgreSQL 配置，因此首要保护对象就是 DCS 本身。 具体的保护方式取决于所使用的 DCS 类型。所支持的各类 DCS 的认证和加密参数（令牌/基本认证/客户端证书）详见 配置说明。 通用建议是为所有 DCS 通信启用 …

Patroni 能够与技术栈中的其他工具集成。本节列举了一些示例，虽非详尽清单，但或许能为你提供 Patroni 与其他工具集成的思路。 Barman Patroni 提供了一个名为 patroni_barman 的应用程序，内含与 pg-backup-api 通信的逻辑，可用于远程执行 Barman 操作。 该应用程序目前包含两个子命令：recover 和 config-switch。 patroni_barman recover recover 子命令可用作自定义引导方法或自定义从库创建方 …

本节介绍将独立 PostgreSQL 实例转换为 Patroni 集群的操作流程。 如需从零开始部署 Patroni 集群（不使用已有 PostgreSQL 实例），请参阅 运行与配置。 操作步骤 以下是将现有 PostgreSQL 集群转换为 Patroni 托管集群的步骤概览。本步骤假设现有集群的所有节点当前均在运行，并且你 不打算 在迁移过程中修改 PostgreSQL 配置。具体步骤如下： 按照 Patroni 配置中 认证 章节的说明创建 PostgreSQL 用户。下方代码块中提供 …

Patroni 使部署 多节点 Citus 集群变得极为简单。 要点 只需遵循以下几条简单规则： PostgreSQL 的 Citus 数据库扩展必须在所有节点上可用。最低支持的 Citus 版本为 10.0，但为了充分利用工作节点透明主从切换和重启的特性，建议使用至少 Citus 11.2。 集群名称（scope）在所有 Citus 节点上必须相同！ 超级用户凭据在协调节点和所有工作节点上必须相同，且 pg_hba.conf 应允许所有节点之间的超级用户访问。 应允许从工作节点访问协调节点的 …

Patroni 可以利用 Kubernetes 对象来存储集群状态并管理领导者键，从而无需任何额外的一致性存储即可在 Kubernetes 环境中运行 PostgreSQL——也就是说，不需要单独部署 etcd。Patroni 支持两种不同类型的 Kubernetes 对象来存储领导者键和配置键，通过 kubernetes.use_endpoints 配置项或 PATRONI_KUBERNETES_USE_ENDPOINTS 环境变量进行选择。 使用 Endpoints 尽管这是推荐模式，但出 …

问题背景 Patroni 高度依赖分布式配置存储（DCS）来完成领导者选举和检测网络分区。具体而言，节点只有在能够成功更新 DCS 中的领导者锁时，才被允许以主库身份运行 PostgreSQL。一旦领导者锁更新失败，PostgreSQL 将立即被降级并以只读模式启动。触发该"问题"的概率因所使用的 DCS 而异——例如，当 etcd 专用于 Patroni 时，发生概率接近于零；而当使用以 etcd 为后端的 Kubernetes API 时，则可能更为频繁。 现有实现的设计原因 领导者锁更新 …

目标 在某些情况下，Patroni 需要临时退出对集群的管理，同时仍在 DCS 中保留集群状态。可能的使用场景是对集群执行的一些不常见操作，例如大版本升级或数据损坏恢复。在此类操作期间，节点往往会因 Patroni 未知的原因频繁启停，某些节点甚至可能被临时提升为主库，从而打破"同一时间只能有一个主库"的假设。为此，Patroni 需要具备从运行中的集群"脱离"的能力，实现类似 Pacemaker 维护模式的效果。 实现机制 当 Patroni 处于暂停模式时，它不会更改 PostgreSQL …

同时存在多个以主库身份运行的 PostgreSQL 实例，可能因时间线分叉而导致事务丢失，这种情况也称为脑裂（split-brain）问题。为了避免脑裂，Patroni 需要确保在 DCS 中的领导者键过期后，PostgreSQL 不再接受任何事务提交。正常情况下，无论因何种原因导致领导者锁更新失败，Patroni 都会尝试通过停止 PostgreSQL 来实现这一目标。然而，以下各种原因可能导致该机制失效： Patroni 因程序缺陷、内存不足或被系统管理员意外终止而崩溃。 …

Patroni 还支持通过"备用集群"功能向远程数据中心（Region）运行级联复制。这类集群具有以下特点： 备用领导者（standby leader）：行为与普通集群领导者基本相同，区别在于它从远程节点进行复制。 级联从库：从备用领导者进行复制。 备用领导者在 DCS 中持有并更新领导者锁。若领导者锁过期，级联从库将通过选举从备用节点中选出新的领导者。 备用集群与其所复制的主集群之间没有其他关联。特别是，若双方使用同一个 DCS，则不能共享相同的 DCS 作用域（scope）。双方除复制信息 …

Patroni 使用 PostgreSQL 流复制。关于流复制的更多信息，请参阅 Postgres 文档。默认情况下，Patroni 将 PostgreSQL 配置为异步复制。选择哪种复制方案取决于你的业务需求。请同时研究异步和同步复制，以及其他高可用方案，以确定最适合自己的解决方案。 异步模式的持久性 在异步模式下，集群允许丢失部分已提交的事务以保证可用性。当主库故障或因任何其他原因变得不可用时，Patroni 会自动将一个足够健康的备库提升为主库。尚未复制到该备库的事务将残留在主库的"分叉 …

Patroni 支持自定义新从库的创建方式，也支持定义全新空集群在引导时的行为。两者有明确区别：只有当 DCS 中存在 initialize 键时，Patroni 才会创建从库。若不存在该键，Patroni 将在第一个抢到初始化锁的节点上独占执行引导流程。 引导（Bootstrap） PostgreSQL 提供了 initdb 命令来初始化新集群，Patroni 默认即调用此命令。在某些场景下——尤其是将现有集群复制一份来创建新集群时——有必要用自定义操作替换内置方式。Patroni 支持执行 …

Patroni 提供了 patronictl 命令行工具，用于与 Patroni 的 REST API 和 DCS 交互，旨在简化集群操作，适合人工操作或脚本调用。 配置 patronictl 使用以下 3 个配置节： ctl：用于对 Patroni REST API 进行认证以及验证服务器身份，详见 ctl 配置参数； restapi：同样用于认证和验证服务器身份，仅在 ctl 配置不足时作为补充。patronictl 主要使用 restapi.authentication 节（当 …

Patroni 提供了丰富的 REST API，供 Patroni 自身在主库竞选期间调用，也供 patronictl 工具执行故障转移、主从切换、重新初始化、重启和重载等操作，还可供 HAProxy 或其他负载均衡器执行 HTTP 健康检查，以及用于监控目的。以下是 Patroni REST API 端点的完整列表。 健康检查端点 对于所有健康检查 GET 请求，Patroni 返回描述节点状态的 JSON 文档，并附带相应的 HTTP 状态码。若不需要 JSON 响应体，可使用 HEAD …

可以使用系统环境变量覆盖 Patroni 配置文件中定义的部分配置参数。本文档列出了 Patroni 处理的所有环境变量。通过环境变量设置的值始终优先于配置文件中的值。 全局/通用 PATRONI_CONFIGURATION：可通过 PATRONI_CONFIGURATION 环境变量为 Patroni 提供完整配置。设置此变量后，其他所有环境变量将被忽略！ PATRONI_THREAD_POOL_SIZE：Patroni 用于执行异步任务，以及在领导者竞选或 failsafe 检查期间通过 …

Patroni 的配置分为 3 种类型： 全局 动态配置。 这些选项存储在 DCS（分布式配置存储）中，并应用于集群的所有节点。动态配置可以随时通过 patronictl edit-config 工具或 Patroni REST API 进行设置。如果更改的选项不属于启动配置，它们将异步地（在下一个唤醒周期时）应用到每个节点，随后触发重载。如果节点需要重启才能应用配置（对于上下文为 postmaster 且值已更改的 PostgreSQL 参数），则会在 members.data JSON 中 …

Mac OS 前置依赖 在 Mac 上安装依赖，执行以下命令： brew install postgresql etcd haproxy libyaml python Psycopg 从 psycopg2-2.8 开始，psycopg2 的二进制版本不再默认安装。从源码编译安装需要 C 编译器以及 postgres 和 python 的开发包。由于 Python 生态中无法将依赖声明为 psycopg2 OR psycopg2-binary，必须自行决定安装方式。 可选方案如下： 使用发行版自 …

全局/通用 thread_pool_size：Patroni 用于执行异步任务，以及在主库竞选或 failsafe 检查期间通过 REST API 与其他成员通信的线程池大小。最小值为 5，默认值为 5。 thread_stack_size：指定 Patroni 启动的线程所使用的栈大小，取值必须按 64kB 对齐。最小值为 64kB，默认值（由 Patroni 设置）为 512kB。 name：主机名称，在集群中必须唯一。 namespace：Patroni 在配置存储中保存集群信息的路径， …

Patroni 是一个基于 Python 的高可用 PostgreSQL 解决方案模板。它最初 fork 自 Compose 公司的 Governor 项目，并包含大量新特性。 更多背景资料，请参阅： 使用 Kubernetes 和 Patroni 实现 PostgreSQL 高可用——Josh Berkus 在 KubeCon 2016 上的演讲（视频） 2016 年 2 月 Zalando 技术博客文章 开发状态 Patroni 正处于活跃开发阶段，欢迎社区贡献。详情请参阅下方的 贡献指南 …

动态配置存储在 DCS（分布式配置存储）中，并应用于集群的所有节点。 如需修改动态配置，可使用 patronictl edit-config 工具或 Patroni REST API。 loop_wait：主循环每轮的休眠秒数。默认值：10，最小值：1。 ttl：获取领导者锁的 TTL（秒）。可以理解为触发自动故障转移前的等待时长。默认值：30，最小值：20。 retry_timeout：DCS 和 PostgreSQL 操作的重试超时时间（秒）。若 DCS 或网络故障时长短于此值 …