pglookout 介绍与选型指南

目标：讲清 pglookout 的软件定位、核心架构、故障转移判定机制与同类方案对比，为「PostgreSQL 流复制集群要不要配 pglookout」给出选型依据。本篇为纯联网溯源的认知篇，全部信息溯源官方渠道（GitHub 仓库、PyPI、官方文档）并标注来源与查询日期（2026-11-01），不含本地实测环节；部署与功能实测见本专栏后续各篇。

一、环境信息

本篇不涉及本地实验，先交代本篇全部事实性信息的溯源清单，便于读者复核口径。所有外部信息均为 2026-11-01 查询所得：

💡 说明：pglookout 在 GitHub 上不发布 Release/Tag（Releases 页查询结果为「There aren't any releases here」，shields.io 的 tag 端点亦无返回），版本号由构建脚本从 git describe --always 动态生成；PyPI 上的最新发行版为 1.4.0（2017-06-08 发布）。因此本文以「pglookout 1.4.0（PyPI 最新稳定版）」作为版本锚点，同时注明 GitHub master 分支源码持续演进（最近提交 2025-01）。

二、软件概述

pglookout 是一个 PostgreSQL 复制监控与自动故障转移守护进程（replication monitoring and failover daemon）。它持续监控 PG 数据库节点及其复制状态，并根据状态采取行动——例如在主库失联时调用预定义的故障转移命令，把一个从库提升为新主库（来源：aiven/pglookout README，2026-11-01 查询）。

💡 技术拓展：PostgreSQL 官方只提供流复制机制本身，主库宕机后「谁来发现、谁来切换」需要额外的 HA 组件。业界主流方案分四类——

方案类别	代表组件	原理与特点	适用场景
复制监控/故障转移守护进程	pglookout、repmgr	轻量，监控复制状态并触发脚本级切换，不依赖外部协调服务	中小规模流复制集群、已有运维脚本体系
DCS 集群管理器	Patroni	依赖 etcd/Consul/ZooKeeper 等分布式协调服务做 Leader 选举与配置管理，功能完整	对自动切换一致性要求高、规模较大的生产集群
共享存储/热备	STONITH + Pacemaker	底层集群栈，通过 fencing 保证不脑裂	已有 Pacemaker 体系的企业
云托管 HA	云厂商托管 PG	切换由云平台完成	不想自运维的场景

pglookout 属于第一类中的「监控 + 自动 failover 守护进程」，且独特地引入了独立观察节点提供第三方视点（详见第三章）。本文选型对比即围绕第一、二类的代表组件展开。

pglookout 由 Hannu Valtonen 与 Ohmu 团队为安全公司 F-Secure 创建，现由 Aiven（云数据平台公司）的开发者维护，采用 Apache License 2.0 许可证。它用 Python 实现，要求 CPython 3.9 或更新版本，仅依赖 requests 与 psycopg2 两个第三方库；可监控 PostgreSQL 10 及以上版本的集群（来源：aiven/pglookout README，2026-11-01 查询）。

关键元数据一览：

从表格可以看出 pglookout 的两个鲜明特点：依赖极薄（Python 环境加两个库即可运行，无需 etcd/Consul 等外部服务），以及发布节奏与社区规模都偏小（PyPI 上 8 年未发新版，代码以 master 源码形态演进，社区主要使用者是 Aiven 自家云平台与 F-Secure 类规模的存量用户）。选型时需要同时正视这两点，后文第七章给出与 repmgr/Patroni 的量化对比。

三、核心架构

3.1 两类节点与部署拓扑

pglookout 支持两类节点（来源：aiven/pglookout README，2026-11-01 查询）：

• db 节点上的 pglookout：安装在 PostgreSQL 主/从库所在主机上，监控集群复制状态并「按状态行动」——包括在需要时执行故障转移命令把本机从库提升为主库；
• 观察节点（observer）：可以安装在任意位置，职能受限——只观察集群状态、提供第三方视点，自身不做任何动作。

一个观察节点可以同时观察任意多个 PostgreSQL 复制集群，因此可以在多个集群间共享一个 observer。官方建议：至少部署一个外部观察节点，为集群健康提供「另一双眼睛」。

一个典型的三节点部署拓扑（两台 db 服务器 + 一台观察节点）：

+----------------+       +----------------+       +----------------------+
|   db 服务器 1   |       |   db 服务器 2   |       |      观察节点         |
|  PG 主库        |  流复制 |  PG 从库        |       |   pglookout observer |
|  pglookout     | -----> |  pglookout     |       |  （own_db 留空，      |
|  (own_db=p1)   |       |  (own_db=s1)   |       |   只观察不动作）      |
+-------+--------+       +-------+--------+       +----------+-----------+
        |                        |                           |
        +----------- HTTP 状态互查（含 observer 视点）----------+

db 节点与观察节点之间通过 pglookout 内置的 HTTP 状态服务（默认端口 15000，由 http_port 配置）互查状态快照，这一「多视点互查」正是 pglookout 防止网络分区误切换的核心设计（见 3.3 节）。

3.2 监控数据流与复制状态判定

pglookout 内部由两条主线协作（依据 master 分支源码 pglookout/cluster_monitor.py、pglookout/pglookout.py，2026-11-01 拉取）：

1. cluster_monitor 线程：按 db_poll_interval（默认 5 秒）轮询 remote_conns 中配置的每个 PG 节点，执行内置函数查询（如 pg_is_in_recovery()、pg_last_xact_replay_timestamp() 等），得到「本节点视角」的 cluster_state；同时按需轮询 observers 配置的观察节点 HTTP 端点，得到 observer_state。若配置了 poll_observers_on_warning_only，观察节点只在复制延迟超过告警阈值时才被轮询。
2. 主线程（failover 决策）：按 replication_state_check_interval（默认 10 秒）执行 check_cluster_state()，调用 create_node_map(cluster_state, observer_state) 把自身视角与观察节点视角合并成一张集群节点角色图（谁是主、谁是从、谁失联），再决定是否进入故障转移流程。

每个 pglookout 还会把整个集群状态写成人类可读的 JSON 状态文件（json_state_file_path，默认 /tmp/pglookout_state.json），并通过 HTTP 端点对外提供同一份状态；配置了 statsd 时还会向 statsd/Telegraf 兼容的守护进程发送指标（来源：README「General notes」「Configuration keys」章节）。

3.3 故障转移决策流程（防误切与观察节点视点）

故障转移决策是 pglookout 的灵魂，源码级流程如下（依据 master 分支 pglookout.py 中 check_cluster_state → consider_failover 的实现，2026-11-01 拉取）：

1. 确认主库缺失或失联：合并视点后若集群中不存在「可连接的主库」，进入决策分支；若配置 failover_on_disconnect 为 true（默认），自身与主库断连也会纳入考量。
2. 等待与二次确认：主库消失后，pglookout 先主动触发一次即时状态复查（"Master is missing, ask for immediate state check"），并在 missing_master_from_config_timeout（默认 15 秒）内等待决策队列，复查后若主库又出现了就放弃切换——避免瞬时抖动引发误切。
3. 已知下线节点立即切换：若主库在 known_gone_nodes 名单中（计划内摘除），跳过等待立即切换。
4. 复制延迟超时切换：若主库存在但复制延迟超过 max_failover_replication_time_lag（默认 120 秒），执行 failover_command。
5. 挑选提升候选：按复制位置一致性 + failover_priorities 优先级（未配置时按 remote_conns 的键序）选定要提升的从库，never_promote_these_nodes 名单中的节点永远不会被提升；自身处于维护模式文件存在状态时也不会被选中。
6. 执行切换：以 pglookout 进程用户权限执行 failover_command 外部脚本，并生成 failover_has_happened 告警文件。

观察节点在其中的价值是抗网络分区的第三方证据：create_node_map 合并了 observer 上报的「它看到的主库状态」。当网络发生分区（net split）时，观察节点的视角可以帮助避免「仅仅是 db 节点自己看不到主库就贸然提升自己」的脑裂事故——官方 README 明确说明观察节点「Useful especially during net splits」；配置 poll_observers_on_warning_only 后，延迟超限时还会校验「主库对应的观察者数据是否足够新鲜」（is_master_observer_new_enough），数据不足时跳过本轮检查。

💡 技术拓展：自动故障转移方案最怕的是脑裂（两个节点都认为自己是主库、同时接收写入）。业界防脑裂手段对比——

手段	原理	代表
第三方视点仲裁	引入独立观察者交叉验证主库存活	pglookout observer
分布式锁/租约	只有多数派同意才能当选 Leader	Patroni + etcd
Fencing/STONITH	提升前强制「击毙」旧主	Pacemaker、pglookout 官方建议 failover 脚本内实现

pglookout 采用「观察节点视点 + 建议在 failover_command 中实现 STONITH」的组合，而非多数派选举，这也是它与 Patroni 的本质差异点之一。本方案（pglookout）实际采用前者，理由是部署轻、不引入额外协调服务。

3.4 告警文件机制

pglookout 在出现需要人工介入的异常时，会在 alert_file_dir（默认进程工作目录）下创建告警文件，官方建议把「这些文件是否存在」纳入外部告警系统（来源：README「Alert files」章节）：

这套机制设计得很朴素：文件即信号，任何能看文件系统的监控（cron 脚本、Zabbix agent、Nagios check_file_exists 等）都能零成本接入。

四、功能特性

综合 README 与源码，pglookout 1.4.0 / master（2026-11-01 查询）的功能清单如下：

功能定位上的「不做清单」同样重要：pglookout 不负责初始搭建复制（clone/backup）、不提供 switchover 计划内切换命令、不管理 PG 配置文件、不做代理流量切换（它只执行你给的脚本）。这些都留给运维脚本或外部工具——这是它比 repmgr/Patroni「小」的地方，也是它「轻」的原因。

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

⚠️ 本节流程转述自官方 README（2026-11-01 查询），为官方推荐的最小可用路径，本篇未做本地实测；逐命令实测与回显见本专栏部署篇。

官方给出的最小可用配置共五步（命令与配置取自 README「Setup」章节，账号密码按本文演示约定落值）：

1. 创建 pglookout 专用数据库账号（在主库执行，监控用户无需超级权限）：

CREATE USER pglookout PASSWORD 'q1w2e3r4';

2. 编辑主库 pg_hba.conf，放行该账号从主库、从库与观察节点连入 postgres 库（或为 pglookout 单独建一个空库），然后 SELECT pg_reload_conf(); 重载配置。

3. 编写 pglookout.json，填入账号与主/从/观察节点地址（remote_conns 的键为节点名，值为合法的 PostgreSQL 连接串）：

{
    "remote_conns": {
        "p1": "dbname=postgres host=10.89.60.11 password=q1w2e3r4 user=pglookout",
        "s1": "dbname=postgres host=10.89.60.12 password=q1w2e3r4 user=pglookout"
    },
    "own_db": "p1",
    "observers": {"obs1": "http://10.89.60.13:13000"},
    "http_port": 13000,
    "warning_replication_time_lag": 30.0,
    "max_failover_replication_time_lag": 120.0,
    "failover_command": "/opt/pglookout/failover.sh"
}

将同一份配置复制到从库与观察节点，仅把 own_db 改为对应节点名；观察节点的 own_db 留空字符串（它没有自己的数据库）。

4. 编写 failover 脚本并把路径填入 failover_command。官方在 examples 目录提供了一个基于 IP 别名（IP aliasing）漂移的示例脚本，并建议脚本内实现 STONITH 能力；其他常见切换手段还包括切换 PgBouncer 等连接池的指向、修改 PL/Proxy 配置。官方特别提醒：先用 pglookout 的运行用户手动执行一遍脚本验证可用。

5. 启动进程并验证。Linux 上官方推荐用 systemd 托管：systemctl enable pglookout.service 后 systemctl start pglookout.service；无 systemd 的系统建议用 Supervisor 等进程管理器。装好后随包提供两个可执行文件：pglookout（主守护进程）与 pglookout_current_master（解析状态文件、输出当前主库）。

验证手段：查看 json_state_file_path 指向的 JSON 状态文件（默认 /tmp/pglookout_state.json），内容即当前集群全量状态；或直接请求 HTTP 状态端点（http_port 配置的端口）。

六、适用场景与限制

6.1 适用场景

基于上述架构与功能，pglookout 最能发挥价值的场景：

• 已有流复制集群、需要「最后一公里」自动切换：PG 自带流复制只解决数据同步，主库宕机后的发现与提升需要 pglookout 这类守护进程兜底；
• 不希望引入 etcd/Consul 等额外协调服务：pglookout 零外部依赖（仅需 Python + 两个库），两台 db 服务器加一个观察节点即可组成完整监控拓扑，运维面极小；
• 多集群共享监控视点：一个 observer 可同时观察任意多个复制集群，托管多套中小集群的平台型场景（Aiven 自身即如此使用）非常契合；
• 切换策略高度定制：故障转移的全部动作收敛在一个 failover_command 脚本里，可以用 IP 漂移、连接池切换、DNS 切换、STONITH 等任何团队熟悉的方式完成流量切换。

6.2 已知限制

选型时必须正视的限制（均来自官方信息与源码行为，2026-11-01 查询）：

• 版本发布停滞：PyPI 最新发行版 1.4.0 发布于 2017-06-08，此后 8 年未再打版本号；master 分支虽持续维护（最近提交 2025-01）且明确支持 CPython 3.9+/PG 10+，但生产使用需要接受「源码形态部署、跟随 master 演进」的现实；
• 社区规模小：stars 193 / forks 28（shields.io，2026-11-01），遇到问题主要依赖读源码与 Aiven 维护者的响应，第三方教程与生态集成远少于 Patroni；
• 切换强依赖外部脚本：不含克隆备份（重搭从库）、不含计划内 switchover 命令、不含代理流量切换，这些能力都要自行编写脚本或引入其他工具；
• 防脑裂依赖观察节点与脚本纪律：没有多数派选举的强一致保证，观察节点被绕过（如全部失联）时退化为单视点判定，官方因此建议 failover 脚本内实现 STONITH；
• 监控用户权限要规划好：pglookout 只需运行少量内置函数，但复制槽等信息的可见性受 PG 权限体系影响，authentication_error 类告警多源于 pg_hba.conf 配置不当（README 明示）。

七、同类选型对比

本章把 pglookout 与两个最常被拿来做对比的方案——repmgr 与 Patroni——放在同一张表里量化对比。三个方案的版本、许可证、社区数据均为 2026-11-01 实查（来源见第一章溯源清单）。

7.1 候选方案概览

7.2 能力细节对比

7.3 选型建议

结合两张表，给出「如果……则……」式的建议：

• 如果已有流复制集群、只想补一个轻量的「发现主库挂了并提升从库」的守护进程，团队愿意维护少量自定义脚本 → pglookout 最省事，零外部组件、配置不到二十个键；
• 如果希望「克隆从库 + 计划内切换 + 自动 failover」一个工具全包、且接受 GPL-3.0 与 EDB 生态 → 选 repmgr；
• 如果集群规模大、要求强一致的自动选主（多数派）、愿意多运维一套 etcd/Consul，或跑在 Kubernetes 上 → 选 Patroni，其社区活跃度（8.8k stars、2026 年仍在发版）也显著领先；
• 如果同时管理大量中小 PG 集群并希望共享监控视点 → pglookout 的「一个 observer 观察任意多集群」设计是三者中独有的。

一句话总结：pglookout 是「最小可用自动 failover」的极致形态——它用最少的依赖解决了「主库挂了怎么办」，代价是把克隆、切换、流量等周边能力留给脚本；是否选它，取决于你想要一套全托管 HA 平台，还是一枚嵌入现有运维体系的「监控 + 切换」插件。

八、参考链接

• pglookout GitHub 仓库（README/源码）：https://github.com/aiven/pglookout
• pglookout PyPI 项目页（版本 1.4.0）：https://pypi.org/project/pglookout/
• pglookout Apache-2.0 许可证全文：https://www.apache.org/licenses/LICENSE-2.0.txt
• repmgr 官方站点与文档（版本对照表）：https://www.repmgr.org/ 、 https://www.repmgr.org/docs/current/repmgr.html
• Patroni 官方文档 Release notes：https://patroni.readthedocs.io/en/latest/releases.html
• shields.io 社区徽章数据（stars/forks/last-commit）：https://img.shields.io/
• PostgreSQL 官方文档·流复制：https://www.postgresql.org/docs/current/warm-standby.html