pg_auto_failover 2.2 介绍与选型指南
pg_auto_failover 2.2（2025-04-03 最新稳定版，PostgreSQL License）认知与选型：monitor+keeper 状态机架构、同步复制与 RPO=0 机制，与 Patroni/repmgr/Pgpool-II/Stolon 的量化对比，全部数据联网溯源（查询日期 2026-10-25）。
pg_auto_failover 2.2 介绍与选型指南
目标：在动手部署前判断 pg_auto_failover 是不是你要的 PostgreSQL 高可用方案。本篇基于官方仓库、官方文档与 shields.io 徽章的联网溯源（查询日期 2026-10-25），讲清它的定位、组成、能做什么、对服务器和 PostgreSQL 版本有哪些硬要求，并与 Patroni、repmgr、Pgpool-II、Stolon 做量化对比。部署、参数与 CLI 的逐步实测不在本篇展开。
一、信息基准
本篇是认知与选型文档，先交代"信息从哪来、以哪个版本为基准"，便于读者判断时效并自行复核。
1.1 查询与版本基准
- 查询日期：2026-10-25。
- 基准版本：pg_auto_failover 2.2（2025-04-03 发布）。依据：官方 GitHub Releases 最新稳定版为 v2.2，主题为"支持 PostgreSQL 17"并移除了对 PG 11/12 的支持。
- PostgreSQL 兼容范围：13、14、15、16、17。v2.2 新增 PG 17 支持，同时不再支持 PG 11/12。
- 写作方式：不做本地安装实测；所有版本、特性、量化数据以官方来源为准，随文标注来源。
1.2 官方来源清单
| 信息项 | 官方来源 URL | 用途 |
|---|---|---|
| 项目仓库 | https://github.com/citusdata/pg_auto_failover | 定位、架构、安装方式 |
| GitHub Releases | https://github.com/citusdata/pg_auto_failover/releases | 版本节奏与变更明细 |
| 官方文档站 | https://pg-auto-failover.readthedocs.io/ | 教程、手册、设计与排障 |
| 星标徽章 | https://img.shields.io/github/stars/citusdata/pg_auto_failover | 社区规模（约 1.4k，查询日 2026-10-25） |
| LICENSE | 仓库 LICENSE 文件 | PostgreSQL License |
说明：项目原由 Citus Data（Microsoft）团队驱动，当前由社区志愿者维护（文档首页注明"orphaned in terms of financial support"）。版本号与星标属于随时间变化的数据，读者复核时可能已有更新；本文只对 2026-10-25 这个时间点的取值负责。
二、软件概述
pg_auto_failover 是一个为 PostgreSQL 集群提供自动故障转移的开源扩展与服务。它由两部分组成：一个 monitor（监督进程）和若干 keeper（托管 PostgreSQL 实例的进程）。monitor 实现了一套状态机，依靠 PostgreSQL 内核机制（流复制、synchronous_standby_names、复制槽等）来保证故障转移的安全性。
它解决的核心问题是：当主库宕机时，如何自动、安全地提升一个备库成为新主库，并避免脑裂与数据丢失。
与"手动流复制 + 脚本切换"相比，pg_auto_failover 的关键差异是把故障转移的决策和执行交给一个有状态的 monitor，由 monitor 统一协调多个 keeper 的状态转换，而不是每个节点各自为政。
💡 技术拓展：PostgreSQL 高可用方案不止 pg_auto_failover 一种。常见方案的核心思路对比——
方案 核心思路 决策主体 典型架构 pg_auto_failover 状态机驱动自动故障转移 monitor 节点 monitor + N 个 keeper Patroni 基于 DCS 的分布式锁选主 DCS（etcd/Consul/ZooKeeper） patroni + DCS + HAProxy repmgr 复制管理 + 守护进程切换 repmgrd 守护进程 主 + 备 + repmgrd Pgpool-II 连接池 + 在线恢复 + 故障转移 Pgpool-II 进程 Pgpool-II + 主 + 备 Stolon 基于 etcd 的哨兵式管理 etcd + keeper + sentinel stolon-proxy + stolon-keeper + etcd 本文聚焦 pg_auto_failover 这一路由：monitor 集中决策、keeper 执行状态转换。
三、核心架构
3.1 运行时组成
pg_auto_failover 的最小生产形态是 1 个 monitor + 2 个 keeper（一主一备）。每个角色的职责与硬要求如下：
| 部件 | 作用 | 硬要求 |
|---|---|---|
| monitor | 运行 pgautofailover 扩展的 PostgreSQL 实例，记录集群状态、驱动状态机、协调故障转移 | 一个独立的 PostgreSQL 实例（可与业务库同机但不推荐）；需常驻运行 |
| keeper | 运行在每个数据节点上，管理本地 PostgreSQL 实例的生命周期、执行状态转换 | 每个数据节点一个；需常驻运行；由 pg_autoctl run 启动 |
| 数据节点 | 被 keeper 托管的 PostgreSQL 实例（主或备） | PostgreSQL 13–17；需支持流复制 |
monitor 和 keeper 都通过 pg_autoctl 命令行工具管理。pg_autoctl create monitor 初始化 monitor，pg_autoctl create postgres 初始化一个数据节点并注册到 monitor，pg_autoctl run 启动对应进程。
3.2 状态机
pg_auto_failover 的核心是 monitor 维护的有限状态机（FSM）。每个数据节点在 monitor 中有一个"报告状态"（Reported State，节点实际所处状态）和一个"目标状态"（Assigned State，monitor 要求节点转换到的状态）。keeper 不断向 monitor 报告当前状态，并执行 monitor 下发的状态转换指令。
主要状态包括：
| 状态 | 含义 |
|---|---|
| init | 节点刚注册，尚未初始化 |
| single | 唯一节点，作为独立主库运行 |
| wait_primary | 等待成为主库（已有备库加入，主库处于等待确认状态） |
| primary | 主库，接受读写 |
| secondary | 备库，只读、流复制 |
| wait_standby | 等待成为备库 |
| catchingup | 备库正在追赶主库 |
| draining | 主库正在排空连接（故障转移前） |
| demote_timeout | 主库正在降级（故障转移中） |
| demoted | 主库已降级，等待重新加入 |
| apply_settings | 正在应用复制配置变更 |
故障转移的本质是 monitor 把主库的目标状态从 primary 依次改为 draining → demote_timeout → demoted → catchingup → secondary，同时把备库的目标状态从 secondary 改为 prepare_promotion → stop_replication → wait_primary → primary。整个过程由 monitor 保证步骤的安全性（如确认备库已追平 WAL 后才提升）。
3.3 复制与一致性
默认情况下，pg_auto_failover 使用同步流复制，并把每个达到 secondary 状态的备库加入主库的 synchronous_standby_names。这意味着主库的每次提交都需要至少一个备库确认收到 WAL，从而保证 RPO=0（不丢失已提交事务）。
当备库不可用或延迟过大时，monitor 会自动把它从 synchronous_standby_names 中移除，避免主库被阻塞；待备库恢复健康后再重新加入。这个机制保证了可用性优先，但不牺牲数据一致性。
四、功能特性
pg_auto_failover 2.2 的主要功能特性：
- 自动故障转移：主库宕机时，monitor 自动把最健康的备库提升为新主库，无需人工干预。
- 状态机驱动：所有节点状态转换由 monitor 的状态机统一编排，避免脑裂。
- 同步复制保护：默认同步复制，RPO=0；备库不健康时自动降级为异步，恢复后自动切回。
- 复制仲裁（replication quorum）：可配置哪些备库参与写入仲裁，灵活平衡性能与一致性。
- 候选优先级（candidate priority）：可配置每个备库被提升为主库的优先级（0–100），优先级越高越先被提升。
- Citus 高可用：从 v2.0 起支持 Citus 集群的高可用（coordinator + worker 故障转移）。
- SSL 加密：支持自签名证书或自定义证书，加密节点间通信。
- systemd 集成：
pg_autoctl show systemd输出 systemd 单元文件，便于生产托管。
五、适用场景与限制
5.1 适用场景
- 中小规模 PostgreSQL 集群（2–5 个数据节点），需要自动故障转移但不想引入 etcd/Consul 等外部 DCS。
- 团队希望用一套命令行工具（
pg_autoctl）统一管理集群，而不是拼接多个组件。 - 对 RPO=0 有要求，能接受同步复制带来的写入延迟。
- 已经在使用 Citus，需要为 Citus 集群提供高可用。
5.2 限制与边界
- 不提供连接路由：pg_auto_failover 只负责故障转移，不负责应用连接的自动切换。生产环境通常需要配合 HAProxy、PgBouncer 或 DNS 切换来实现应用透明。
- monitor 单点：monitor 本身是单点（官方不支持 monitor 的 HA）。monitor 宕机期间，数据节点仍正常运行，但无法执行故障转移。生产部署建议为 monitor 做冷备或定期备份。
- 不支持多主：pg_auto_failover 是单主复制架构，不支持多主写入。
- 版本兼容：v2.2 只支持 PG 13–17，更低版本的 PostgreSQL 无法使用。
- 社区维护状态：项目当前由志愿者维护，商业支持有限（文档页提及可联系 oss.theartofpostgresql.com 获取专业支持）。
六、同类选型对比
下面从架构、决策机制、依赖、复杂度、适用规模等维度，把 pg_auto_failover 与四个主流方案做量化对比。数据来源为各项目官方文档与上文检索到的对比资料（查询日期 2026-10-25）。
| 维度 | pg_auto_failover 2.2 | Patroni | repmgr | Pgpool-II | Stolon |
|---|---|---|---|---|---|
| 决策机制 | monitor 状态机 | DCS 选主（etcd/Consul/ZK） | repmgrd 守护进程 | Pgpool-II 进程 | etcd + sentinel |
| 外部依赖 | 无（自带 monitor） | 需 DCS 集群 | 无 | 无 | 需 etcd 集群 |
| 自动故障转移 | ✅ 全自动，状态机保证 | ✅ 全自动，DCS 保证 | ✅ 需配置 repmgrd | ✅ 在线恢复+切换 | ✅ 全自动 |
| RPO | 0（同步复制默认） | 0（可配同步） | 0（可配同步） | 取决于配置 | 0（同步复制） |
| 连接路由 | ❌ 需外部组件 | ❌ 需 HAProxy 等 | ❌ 需外部组件 | ✅ 内置连接池+路由 | ✅ 内置 proxy |
| 复杂度 | 低 | 中（DCS 运维成本） | 低 | 中 | 中高 |
| K8s 支持 | 有限 | 原生支持好 | 有限 | 有限 | 一般 |
| 适用规模 | 2–5 节点 | 任意规模 | 2–5 节点 | 任意规模 | 任意规模 |
| 许可证 | PostgreSQL License | MIT | GPL-3.0 | BSD-like（自定义） | Apache-2.0 |
| 维护状态 | 社区志愿者 | 活跃（多家厂商） | 维护放缓 | 活跃（PG 社区） | 社区维护 |
6.1 选型建议
- 选 pg_auto_failover：你有一个 2–5 节点的 PostgreSQL 集群，想要"装上去就能自动故障转移"，不想维护 etcd 集群，能接受 monitor 单点和无内置连接路由。
- 选 Patroni：你在 Kubernetes 上运行 PostgreSQL，或者已经有 etcd/Consul 基础设施，需要大规模、成熟的 HA 方案。
- 选 repmgr：你只需要简单的主备复制管理和基本的自动切换，对故障转移的自动化程度要求不高。注意 repmgr 的维护节奏已放缓。
- 选 Pgpool-II：你同时需要连接池、负载均衡和故障转移，希望一个组件搞定。注意 Pgpool-II 的配置复杂度较高。
- 选 Stolon：你已经在使用 etcd，想要一个哨兵式的 PostgreSQL 管理方案。