模块: PATRONI

原始页面： https://patroni.readthedocs.io/en/latest/index.html Patroni 是一个基于 Python 的 PostgreSQL 高可用（HA）解决方案模板。为了最大程度地兼容各种环境，Patroni 支持多种分布式配置存储后端，包括 ZooKeeper、etcd、Consul 和 Kubernetes。希望在数据中心或任何其他环境中快速部署 PostgreSQL 高可用的数据库工程师、DBA、DevOps 工程师和 SRE 们，都能从中受 …

原始页面： https://patroni.readthedocs.io/en/latest/contributing_guidelines.html 在线交流 如有疑问、需要互动式故障排查帮助，或希望与其他 Patroni 用户交流，欢迎加入 PostgreSQL Slack 的 #patroni 频道。 报告缺陷 提交缺陷报告前，请务必 在最新版 Patroni 上复现该问题！同时请检查 Issues Tracker 中是否已存在相同问题。 运行测试 运行 behave 测试的前置条件： …

原始页面：https://patroni.readthedocs.io/en/latest/releases.html Version 4.1.4 发布于 2026-07-07 错误修复 使用 systemd 软件包前检查 NOTIFY_SOCKET 环境变量（Polina Bungina） 仅当 NOTIFY_SOCKET 环境变量已设置时，才尝试导入并使用该软件包，以免触发 FileNotFoundError: [Errno 2] No such file or directory 异常。 …

原始页面： https://patroni.readthedocs.io/en/latest/faq.html 本节收录了关于 Patroni 最常见问题的解答，各子节聚焦于不同类别的问题。 希望这些内容能帮你解答大多数疑问。如果仍有疑问或遇到意外问题，请参阅 chatting 和 reporting_bugs，了解如何获取帮助或提交问题报告。 与其他高可用方案的比较 为什么 Patroni 需要独立的 DCS 节点集群，而 repmgr 等其他方案不需要？ 实现高可用方案有多种不同方式，各有 …

原始页面： https://patroni.readthedocs.io/en/latest/ha_multi_dc.html 部署在多个数据中心的 PostgreSQL 集群，其高可用基于复制实现，复制可以是同步的，也可以是异步的（参见 复制模式）。 无论哪种模式，都需要明确以下概念： PostgreSQL 仅在持有领导者键且能够更新领导者键时，才能以主库或备用领导者身份运行。 etcd、ZooKeeper 或 Consul 节点的数量应为奇数：3 个或 5 个！ 同步复制 要构建能够自动容 …

原始页面： https://patroni.readthedocs.io/en/latest/security.html Patroni 集群有两个需要防范未授权访问的接口：分布式配置存储（DCS）和 Patroni REST API。 保护 DCS Patroni 和 patronictl 都会向 DCS 读写数据。 尽管 DCS 本身不包含任何敏感信息，但它允许修改部分 Patroni/PostgreSQL 配置，因此首要保护对象就是 DCS 本身。 具体的保护方式取决于所使用的 DCS …

原始页面： https://patroni.readthedocs.io/en/latest/tools_integration.html Patroni 能够与技术栈中的其他工具集成。本节列举了一些集成示例，并不详尽，但希望能为您提供参考和启发。 Barman Patroni 提供了一个名为 patroni_barman 的应用程序，内含与 pg-backup-api 通信的逻辑，可用于远程执行 Barman 操作。 该应用程序目前包含两个子命令：recover 和 …

原始页面： https://patroni.readthedocs.io/en/latest/existing_data.html 本节介绍将独立 PostgreSQL 实例转换为 Patroni 集群的操作流程。 如需从零开始部署 Patroni 集群（不使用已有 PostgreSQL 实例），请参阅 运行与配置。 操作步骤 以下是将现有 PostgreSQL 集群转换为 Patroni 托管集群的步骤概览。本步骤假设现有集群的所有节点当前均在运行，并且您 不打算 在迁移过程中修改 …

原始页面： https://patroni.readthedocs.io/en/latest/citus.html Patroni 使部署 多节点 Citus 集群变得极为简单。 TL;DR 只需遵循以下几条简单规则： 所有节点上必须安装 Citus 数据库扩展。最低支持的 Citus 版本为 10.0，但为了充分利用工作节点透明主从切换和重启的特性，建议使用至少 Citus 11.2。 集群名称（scope）在所有 Citus 节点上必须相同！ 超级用户凭据在协调节点和所有工作节点上必须相同 …

原始页面： https://patroni.readthedocs.io/en/latest/kubernetes.html Patroni 可以利用 Kubernetes 对象来存储集群状态并管理领导者键，从而无需任何额外的一致性存储即可在 Kubernetes 环境中运行 PostgreSQL——也就是说，不需要单独部署 Etcd。Patroni 支持两种不同类型的 Kubernetes 对象来存储领导者键和配置键，通过 kubernetes.use_endpoints 配置项或 …

原始页面： https://patroni.readthedocs.io/en/latest/dcs_failsafe_mode.html 问题背景 Patroni 高度依赖分布式配置存储（DCS）来完成领导者选举和检测网络分区。具体而言，节点只有在能够成功更新 DCS 中的领导者锁时，才被允许以主库身份运行 PostgreSQL。一旦领导者锁更新失败，PostgreSQL 将立即被降级并以只读模式启动。触发该"问题"的概率因所使用的 DCS 而异——例如，当 Etcd 专用于 Patroni …

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

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

原始页面： https://patroni.readthedocs.io/en/latest/standby_cluster.html Patroni 还支持通过"备用集群"功能向远程数据中心（Region）运行级联复制。这类集群具有以下特点： 备用领导者（standby leader）：行为与普通集群领导者基本相同，区别在于它从远程节点进行复制。 级联从库：从备用领导者进行复制。 备用领导者在 DCS 中持有并更新领导者锁。若领导者锁过期，级联从库将通过选举从备用节点中选出新的领导者。 备用 …

原始页面： https://patroni.readthedocs.io/en/latest/replication_modes.html Patroni 使用 PostgreSQL 流复制。关于流复制的更多信息，请参阅 Postgres 文档。默认情况下，Patroni 将 PostgreSQL 配置为异步复制。选择哪种复制方案取决于你的业务需求。建议同时研究异步和同步复制，以及其他高可用方案，以确定最适合自己的解决方案。 异步模式的持久性 在异步模式下，集群允许丢失部分已提交的事务以保证可 …

原始页面： https://patroni.readthedocs.io/en/latest/replica_bootstrap.html Patroni 支持自定义新从库的创建方式，也支持定义全新空集群在引导时的行为。两者有明确区别：只有当 DCS 中存在 initialize 键时，Patroni 才会创建从库。若不存在该键，Patroni 将在第一个抢到初始化锁的节点上独占执行引导流程。 引导（Bootstrap） PostgreSQL 提供了 initdb 命令来初始化新集群 …

原始页面： https://patroni.readthedocs.io/en/latest/patronictl.html Patroni 提供了 patronictl 命令行工具，用于与 Patroni 的 REST API 和 DCS 交互，旨在简化集群操作，适合人工操作或脚本调用。 配置 patronictl 使用以下 3 个配置节： ctl：用于对 Patroni REST API 进行认证以及验证服务器身份，详见 ctl 配置参数； restapi：同样用于认证和验证服务器身份，仅 …

原始页面： https://patroni.readthedocs.io/en/latest/rest_api.html Patroni 提供了丰富的 REST API，供 Patroni 自身在主库竞选期间调用，也供 patronictl 工具执行故障转移、主从切换、重新初始化、重启和重载等操作，还可供 HAProxy 或其他负载均衡器执行 HTTP 健康检查，以及用于监控目的。以下是 Patroni REST API 端点的完整列表。 健康检查端点 对于所有健康检查 GET 请求 …

原始页面： https://patroni.readthedocs.io/en/latest/ENVIRONMENT.html 可以使用系统环境变量覆盖 Patroni 配置文件中定义的部分配置参数。本文档列出了 Patroni 处理的所有环境变量。通过环境变量设置的值始终优先于配置文件中的值。 全局/通用 PATRONI_CONFIGURATION：可通过 PATRONI_CONFIGURATION 环境变量为 Patroni 提供完整配置。设置此变量后，其他所有环境变量将被忽略！ …

原始页面： https://patroni.readthedocs.io/en/latest/patroni_configuration.html Patroni 的配置分为 3 种类型： 全局 动态配置。 这些选项存储在 DCS（分布式配置存储）中，并应用于集群的所有节点。动态配置可以随时通过 patronictl edit-config 工具或 Patroni REST API 进行设置。如果更改的选项不属于启动配置，它们将异步地（在下一个唤醒周期时）应用到每个节点，随后触发重载。如果节点 …

原始页面： https://patroni.readthedocs.io/en/latest/installation.html Mac OS 前置依赖 在 Mac 上安装依赖，执行以下命令： brew install postgresql etcd haproxy libyaml python Psycopg 从 psycopg2-2.8 开始，psycopg2 的二进制版本不再默认安装。从源码编译安装需要 C 编译器以及 postgres 和 python 的开发包。由于 Python 生 …

原始页面： https://patroni.readthedocs.io/en/latest/yaml_configuration.html 全局/通用 name：主机名称，在集群中必须唯一。 namespace：Patroni 在配置存储中保存集群信息的路径，默认值为 /service。 scope：集群名称。 日志 type：设置日志格式，可选 plain 或 json。使用 json 格式时，必须安装 jsonlogger。默认值为 plain。 level：设置通用日志级别，默认值为 …

原始页面： https://patroni.readthedocs.io/en/latest/README.html Patroni 是一个基于 Python 构建的高可用 PostgreSQL 解决方案模板框架。它最初 fork 自 Compose 公司的 Governor 项目，并在此基础上引入了大量新特性。 更多背景资料，请参阅： PostgreSQL HA with Kubernetes and Patroni——Josh Berkus 在 KubeCon 2016 上的演讲（视频） …

原始页面： https://patroni.readthedocs.io/en/latest/dynamic_configuration.html 动态配置存储在 DCS（分布式配置存储）中，并应用于集群的所有节点。 如需修改动态配置，可使用 patronictl edit-config 工具或 Patroni REST API。 loop_wait：主循环每轮的休眠秒数。默认值：10，最小值：1。 ttl：获取领导者锁的 TTL（秒）。可以理解为触发自动故障转移前的等待时长。默认值：30，最 …