Patroni 4.1.5 中文文档 on PIG.CENTER

简介

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 是一个基于 Python 构建的高可用 PostgreSQL 解决方案模板框架。它最初 fork 自 Compose 公司的 Governor 项目，并在此基础上引入了大量新特性。

更多背景资料，请参阅：

PostgreSQL HA with Kubernetes and Patroni ——Josh Berkus 在 KubeCon 2016 上的演讲（视频）
2016 年 2 月 Zalando 技术博客文章

开发状态

Patroni 正处于活跃开发阶段，欢迎社区贡献。详情请参阅下方的 贡献指南 章节。

安装

Mon, 01 Jan 0001 00:00:00 +0000

Mac OS 前置依赖

在 Mac 上安装依赖，执行以下命令：

brew install postgresql etcd haproxy libyaml python

Psycopg

从 psycopg2-2.8 开始，psycopg2 的二进制版本不再默认安装。从源码编译安装需要 C 编译器以及 postgres 和 python 的开发包。由于 Python 生态中无法将依赖声明为 psycopg2 OR psycopg2-binary，您需要自行选择安装方式。

Patroni REST API

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 提供了丰富的 REST API，供 Patroni 自身在主库竞选期间调用，也供 patronictl 工具执行故障转移、主从切换、重新初始化、重启和重载等操作，还可供 HAProxy 或其他负载均衡器执行 HTTP 健康检查，以及用于监控目的。以下是 Patroni REST API 端点的完整列表。

patronictl 命令行

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 提供了 patronictl 命令行工具，用于与 Patroni 的 REST API 和 DCS 交互，旨在简化集群操作，适合人工操作或脚本调用。

配置

patronictl 使用以下 3 个配置节：

从库镜像与引导

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 支持自定义新从库的创建方式，也支持定义全新空集群在引导时的行为。两者有明确区别：只有当 DCS 中存在 initialize 键时，Patroni 才会创建从库。若不存在该键，Patroni 将在第一个抢到初始化锁的节点上独占执行引导流程。

复制模式

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 使用 PostgreSQL 流复制。关于流复制的更多信息，请参阅 Postgres 文档。默认情况下，Patroni 将 PostgreSQL 配置为异步复制。选择哪种复制方案取决于你的业务需求。建议同时研究异步和同步复制，以及其他高可用方案，以确定最适合自己的解决方案。

备用集群

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 还支持通过"备用集群"功能向远程数据中心（Region）运行级联复制。这类集群具有以下特点：

备用领导者（standby leader）：行为与普通集群领导者基本相同，区别在于它从远程节点进行复制。
级联从库：从备用领导者进行复制。

备用领导者在 DCS 中持有并更新领导者锁。若领导者锁过期，级联从库将通过选举从备用节点中选出新的领导者。

Watchdog 支持

Mon, 01 Jan 0001 00:00:00 +0000

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

集群的暂停/恢复模式

Mon, 01 Jan 0001 00:00:00 +0000

目标

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

DCS 故障安全模式

Mon, 01 Jan 0001 00:00:00 +0000

问题背景

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

在 Kubernetes 中使用 Patroni

Mon, 01 Jan 0001 00:00:00 +0000

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

Citus 支持

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 使部署多节点 Citus 集群变得极为简单。

TL;DR

只需遵循以下几条简单规则：

所有节点上必须安装 Citus 数据库扩展。最低支持的 Citus 版本为 10.0，但为了充分利用工作节点透明主从切换和重启的特性，建议使用至少 Citus 11.2。
集群名称（scope）在所有 Citus 节点上必须相同！
超级用户凭据在协调节点和所有工作节点上必须相同，且 pg_hba.conf 应允许所有节点之间的超级用户访问。
工作节点到协调节点的 REST API 访问必须被允许。例如，凭据应相同，如果配置了客户端证书，工作节点的客户端证书必须被协调节点接受。
在 patroni.yaml 中添加以下配置节：

citus:
 group: X  # 0 表示协调节点，工作节点使用 1、2、3 等
 database: citus  # 所有节点上必须相同

之后只需启动 Patroni，它会处理其余的一切：

将独立实例转换为 Patroni 集群

Mon, 01 Jan 0001 00:00:00 +0000

本节介绍将独立 PostgreSQL 实例转换为 Patroni 集群的操作流程。

如需从零开始部署 Patroni 集群（不使用已有 PostgreSQL 实例），请参阅 运行与配置 。

操作步骤

以下是将现有 PostgreSQL 集群转换为 Patroni 托管集群的步骤概览。本步骤假设现有集群的所有节点当前均在运行，并且您 不打算 在迁移过程中修改 PostgreSQL 配置。具体步骤如下：

与其他工具的集成

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 能够与技术栈中的其他工具集成。本节列举了一些集成示例，并不详尽，但希望能为您提供参考和启发。

Barman

Patroni 提供了一个名为 patroni_barman 的应用程序，内含与 pg-backup-api 通信的逻辑，可用于远程执行 Barman 操作。

安全注意事项

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 集群有两个需要防范未授权访问的接口：分布式配置存储（DCS）和 Patroni REST API。

保护 DCS

Patroni 和 patronictl 都会向 DCS 读写数据。

尽管 DCS 本身不包含任何敏感信息，但它允许修改部分 Patroni/PostgreSQL 配置，因此首要保护对象就是 DCS 本身。

多数据中心高可用

Mon, 01 Jan 0001 00:00:00 +0000

部署在多个数据中心的 PostgreSQL 集群，其高可用基于复制实现，复制可以是同步的，也可以是异步的（参见 复制模式 ）。

无论哪种模式，都需要明确以下概念：

PostgreSQL 仅在持有领导者键且能够更新领导者键时，才能以主库或备用领导者身份运行。
etcd、ZooKeeper 或 Consul 节点的数量应为奇数：3 个或 5 个！

同步复制

要构建能够自动容忍单区域故障的多数据中心集群，至少需要 3 个数据中心。

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

本节收录了关于 Patroni 最常见问题的解答，各子节聚焦于不同类别的问题。

希望这些内容能帮你解答大多数疑问。如果仍有疑问或遇到意外问题，请参阅 chatting 和 reporting_bugs ，了解如何获取帮助或提交问题报告。

版本历史

Mon, 01 Jan 0001 00:00:00 +0000

Version 4.1.5

发布于 2026-08-12

兼容性改进

兼容 PostgreSQL 14.24、15.19、16.15、17.11 与 18.6（Alexander Kukushkin）

贡献指南

Mon, 01 Jan 0001 00:00:00 +0000

在线交流

如有疑问、需要互动式故障排查帮助，或希望与其他 Patroni 用户交流，欢迎加入 PostgreSQL Slack 的 #patroni 频道。

报告缺陷

提交缺陷报告前，请务必 在最新版 Patroni 上复现该问题！同时请检查 Issues Tracker 中是否已存在相同问题。