Patroni作为PostgreSQL高可用管理工具，在集群中承担自动故障转移和配置管理的核心角色。除了通过patronictl命令行工具操作，Patroni还内嵌了一个轻量级HTTP API服务，允许外部系统以RESTful方式读取集群状态、触发管理动作。掌握这套API，能够帮助运维团队将数据库高可用能力无缝集成到监控、告警、发布系统甚至自定义Controller中。本文将系统梳理Patroni REST API的端点用法、典型操作示例以及生产环境安全实践。
Patroni REST API基础与端点概览
Patroni的REST API默认绑定在8008端口，可以通过配置项restapi.listen和restapi.connect_address调整监听地址与对外宣告地址。API根路径为/patroni，返回当前节点的角色、状态、集群时间线以及是否为Leader等关键信息。这是排查集群脑裂或确认主备关系的首选入口。
健康检查类端点设计得更加细分，/health返回HTTP 200仅表示Patroni进程存活，/liveness类似，而/readiness则进一步检查节点是否准备接受读写请求。对于Leader角色，readiness返回200意味着可以提供服务；对于Replica，readiness可能返回503，表示不适合转发读请求（除非配置允许）。这些端点常被负载均衡器或服务发现系统用于动态挑选可用节点。
监控类端点/metrics输出Prometheus格式的指标数据，涵盖集群状态、复制延迟、WAL位置等。使用这些指标可以构建精细的告警规则，例如当复制延迟超过阈值或节点角色异常变化时触发通知。下表列出常用端点及其用途。
| 端点 | 方法 | 说明 |
|---|---|---|
/patroni | GET | 返回节点详细状态、角色、时间线等 |
/health | GET | 进程存活检查，返回200或503 |
/readiness | GET | 就绪检查，常用于负载均衡健康探测 |
/metrics | GET | Prometheus监控指标 |
/config | GET/PATCH | 读取或更新动态配置 |
/switchover | POST | 计划内主备切换 |
/failover | POST | 故障切换，跳过健康检查 |
/restart | POST | 重启当前节点PostgreSQL |
/reload | POST | 重新加载PostgreSQL配置 |
使用REST API执行常见管理操作
切换主备是运维中最敏感的操作之一。POST /switchover用于计划内切换，Patroni会检查目标节点是否健康、是否存在复制延迟，然后按步骤将Leader角色转移。请求体可以指定leader和candidate字段。例如下面的curl命令将集群切换到名为postgresql1的候选节点，并要求在30秒内完成。
curl -s -X POST http://127.0.0.1:8008/switchover \
-H 'Content-Type: application/json' \
-d '{"leader":"postgresql0","candidate":"postgresql1","scheduled_at":null,"timeout":30}'
与switchover不同，POST /failover用于紧急故障场景。它允许在Leader无法正常响应的情况下强制提升Replica，但可能造成数据丢失，因此请求中必须显式设置force字段为true，以表明操作者理解风险。该接口常用于自动故障恢复脚本或当Patroni自身自动切换失败时的人工干预。
curl -s -X POST http://127.0.0.1:8008/failover \
-H 'Content-Type: application/json' \
-d '{"candidate":"postgresql1","force":true}'
动态配置修改可以让集群在不停机的情况下调整DCS参数。使用GET /config读取当前生效的配置，返回的JSON包含ttl、loop_wait、retry_timeout等参数。通过PATCH /config可以更新这些值，Patroni会把变更写入DCS并通知所有节点。下面示例将loop_wait从默认10秒改为5秒，以加快故障检测速度。
curl -s -X PATCH http://127.0.0.1:8008/config \
-H 'Content-Type: application/json' \
-d '{"loop_wait":5}'
重启和重载操作同样通过API暴露。POST /restart可以重启当前节点的PostgreSQL实例，支持restart_pending等参数控制是否仅在有待生效配置时重启。POST /reload则向PostgreSQL发送SIGHUP信号，使配置文件变更生效。这些操作为自动化变更发布提供了统一入口，避免了直接登录服务器的风险。
安全加固与自动化集成实践
Patroni REST API默认没有任何认证机制，任何能访问8008端口的客户端都可以读取集群状态甚至触发切换。生产环境必须通过反向代理添加访问控制，常见的做法是使用Nginx作为TLS终结点并启用Basic Auth。下面是一个Nginx配置片段，它将外部HTTPS请求代理到本机Patroni API，并要求用户名密码。
server {
listen 443 ssl;
server_name patroni-api.ippipp.com;
ssl_certificate /etc/nginx/ssl/patroni.crt;
ssl_certificate_key /etc/nginx/ssl/patroni.key;
location / {
auth_basic "Patroni API";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8008;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
除了网络层防护，还应遵循最小权限原则。为自动化系统创建专用账号，仅授予必要端点权限。例如监控系统只需要访问/metrics和/health，发布系统只需要POST /switchover和PATCH /config。如果使用Nginx，可以基于location和HTTP方法做细粒度限制，减少误操作面。
自动化集成方面，Python是调用REST API的主流选择。下面示例使用requests库查询集群状态，并在Leader不可达时输出告警。该脚本可集成到现有监控平台或定时任务中。
import requests
api_base = "http://127.0.0.1:8008"
try:
resp = requests.get(f"{api_base}/patroni", timeout=5)
data = resp.json()
if data.get("role") != "leader":
print(f"Current node is {data.get('role')}, not leader")
else:
print(f"Leader is healthy, timeline={data.get('timeline')}")
except requests.RequestException as e:
print(f"API request failed: {e}")
在企业级场景中，Patroni REST API经常被Kubernetes Operator或自研DBaaS平台调用，用于编排数据库实例的生命周期。通过将API操作封装为带审计和重试逻辑的服务，可以实现安全、可追踪的集群管理。结合Prometheus监控与告警，可以构建完整的数据库高可用闭环。
掌握Patroni REST API，意味着你拥有了一种对PostgreSQL集群进行程序化控制的标准方式。从基础状态查询到复杂的主备切换，再到安全加固和自动化集成，每一步都需要理解接口语义并防范误操作风险。建议在测试环境充分演练各类API调用，再逐步应用到生产环境。
Patroni REST APIPostgreSQL集群高可用管理修改时间：2026-08-28 19:59:48