Patroni 4.1.5 常用 CLI 命令与工具详解

patronictl 全部 19 个子命令逐个实测：list/topology/history/dsn/query、switchover 与 failover 差异、restart/reload/reinit、pause/resume 维护模式，附 REST API 端点、etcdctl 巡检与 5 条 FAQ。

PatroniPatroni2026/10/20

Patroni 4.1.5 常用 CLI 命令与工具详解

目标：给日常运维一套趁手的 Patroni 工具箱手册——patronictl 全部 19 个子命令的用法、实测回显与适用场景，REST API 管理端点，以及 etcdctl / psql 两个外围巡检工具的配合用法。全部命令与输出均来自 3 节点 etcd + Patroni 4.1.5 + PostgreSQL 17.11 集群实测（部署载体见《Patroni 4.1.5 3 节点高可用集群部署指南》，实测日期 2026-10-20，集群名 pgdemo）。

一、环境信息

项目值
集群pgdemo：pgnode1（10.89.60.11）/ pgnode2（10.89.60.12）/ pgnode3（10.89.60.13）
Patroni4.1.5（patronictl version 实测，见 4.2 节）
配置文件每节点 /etc/patroni/patroni.yml（systemd 环境变量 PATRONICTL_CONFIG_FILE 已指向该文件）
DCSetcd v3.5.21 三节点（2379 端口）
PostgreSQL17.11，超级用户 postgres / 密码 q1w2e3r4（演示口令）
巡检账号线su postgres -c "psql ..."（本机 peer 认证）或 PGPASSWORD=q1w2e3r4 psql -h <节点IP> -U postgres（TCP scram）

二、工具体系概览

工具形态主要用途本文章节
patronictlCLI（逐节点或任一节点执行）集群查看、切换、重启、配置、维护模式四
REST API（8008 端口）HTTP健康检查、角色探测、配置与拓扑读取、脚本化运维五
etcdctlCLIDCS 健康巡检、key 空间检查六.1
psqlCLI数据层巡检：流复制状态、恢复态、业务数据验证六.2

三、前置条件

  1. 集群健康：patronictl list 显示 1 Leader + 2 Replica streaming。
  2. patronictl 需要知道配置文件位置，两种方式二选一：
    • 每条命令显式带 -c /etc/patroni/patroni.yml（本文所有实测均带此参数，最稳妥）；
    • 导出环境变量 export PATRONICTL_CONFIG_FILE=/etc/patroni/patroni.yml（与部署篇 systemd 单元一致）。
  3. 在任意一个节点上执行均可（Patroni 会经 REST API/DCS 汇聚全集群视图），本篇统一在 pgnode1 执行（特殊注明除外）。

四、patronictl 全套命令详解

4.1 全局参数与命令清单

patronictl --help 实测回显：

Usage: patronictl [OPTIONS] COMMAND [ARGS]...

  Command-line interface for interacting with Patroni.

Options:
  -c, --config-file TEXT     Configuration file
  -d, --dcs-url, --dcs TEXT  The DCS connect url
  -k, --insecure             Allow connections to SSL sites without certs
  --help                     Show this message and exit.

Commands:
  demote-cluster   Demote cluster to a standby cluster
  dsn              Generate a dsn for the leader of the cluster
  edit-config      Edit cluster configuration
  failover         Failover only when unscheduled leader failure detected
  flush            Discard scheduled events (restarts or switchover)
  history          Print cluster history
  list             List the Patroni nodes for a given Patroni cluster
  pause            Disable auto failover
  query            Query a Patroni PostgreSQL node
  reinit           Reinitialize cluster member
  reload           Reload cluster member configuration
  remove           Remove cluster from DCS
  restart          Restart cluster member
  resume           Enable auto failover
  show-config      Show cluster configuration
  switchover       Perform a manual leader switchover
  topology         Prints topology of the cluster
  version          Print version of patronictl

清单之外的 promote-cluster（把 standby 集群转正为独立集群）在不带参数时同样存在。版本确认（patronictl version）实测回显：

patronictl version 4.1.5

4.2 查看类命令：list / topology / history / dsn

（1）list——最常用的一行集群总览（实测回显）：

+ Cluster: pgdemo (7698419935852473711) ------+----+-------------+-----+------------+-----+
| Member  | Host        | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
| pgnode1 | 10.89.60.11 | Replica | streaming |  4 |   0/60038A8 |   0 |  0/60038A8 |   0 |
| pgnode2 | 10.89.60.12 | Replica | streaming |  4 |   0/60038A8 |   0 |  0/60038A8 |   0 |
| pgnode3 | 10.89.60.13 | Leader  | running   |  4 |             |     |            |     |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+

健康判据：恰好 1 个 Leader、其余 Replica 且 State=streaming、TL 一致、两个 Lag 均为 0。需要机读时加 -f json（实测节选，含 pending restart 原因列）：

[{"Cluster": "pgdemo", "Member": "pgnode1", "Host": "10.89.60.11", "Role": "Replica", "State": "streaming", "TL": 4, "Receive LSN": "0/60038A8", "Receive Lag": 0, "Replay LSN": "0/60038A8", "Replay Lag": 0, "Pending restart": "*", "Pending restart reason": "max_wal_senders: 12->10"}, {"Cluster": "pgdemo", "Member": "pgnode2", ...}, {"Cluster": "pgdemo", "Member": "pgnode3", "Host": "10.89.60.13", "Role": "Leader", "State": "running", "TL": 4, "Pending restart": "*", "Pending restart reason": "max_wal_senders: 12->10"}]

💡 Pending restart reason 是 4.x 的新增字段：直接告诉你哪个参数在等待重启生效（上例为 DCS 配置从 12 回调 10），比 3.x 只有一个星号友好得多。

（2）topology——树状主从层级（实测回显）：

+ Cluster: pgdemo (7698419935852473711) -------+-----+------------+-----+-------------------+
| Host        | Role    | State   | TL | Lag       | Replay LSN | TL Lag | Pending restart |
+-------------+---------+---------+----+-----------+------------+--------+-----------------+
| pgnode3     | Leader  | running |  4 |           |            |        | *               |
| + pgnode1   | Replica | running |  4 |   0 bytes |   0/60038A8 |    0s | *               |
| + pgnode2   | Replica | running |  4 |   0 bytes |   0/60038A8 |    0s | *               |
+-------------+---------+---------+----+-----------+------------+--------+-----------------+

（3）history——故障转移与切换审计（实测回显）：

+----+----------+------------------------------+----------------------------------+------------+
| TL |      LSN | Reason                       | Timestamp                        | New Leader |
+----+----------+------------------------------+----------------------------------+------------+
|  1 | 67665336 | no recovery target specified | 2026-10-19T16:43:07.010262+00:00 | pgnode2    |
|  2 | 67695048 | no recovery target specified | 2026-10-19T16:43:29.556843+00:00 | pgnode1    |
|  3 | 67696624 | no recovery target specified | 2026-10-19T16:59:36.610036+00:00 | pgnode3    |
+----+----------+------------------------------+----------------------------------+------------+

（4）dsn——生成连接串，供应用/脚本取当前角色的 DSN（实测回显）：

patronictl -c /etc/patroni/patroni.yml dsn pgdemo
# patronictl -c /etc/patroni/patroni.yml dsn pgdemo 输出：
host=10.89.60.13 port=5432

patronictl -c /etc/patroni/patroni.yml dsn pgdemo -r replica
# 输出（从库组）：
host=10.89.60.11,10.89.60.12 port=5432

-r 可选 leader/replica/primary（默认 leader）；多从库时 replica 的 host 列表即负载均衡目标池。

4.3 配置类命令：show-config / edit-config

  • show-config：输出全集群生效的 DCS 动态配置全文（完整回显见《Patroni 4.1.5 配置参数详解》3.1 节）。
  • edit-config：修改 DCS 动态配置，支持 -s key=value（任意键）、-p key=value（postgresql.parameters）、-r key（删除）、-f 文件（整文件覆盖）与 --force/-y（免确认）。实测（-p max_wal_senders=12 自动生成 diff，节选）：
---
+++
@@ -4,7 +4,7 @@
   parameters:
     hot_standby: 'on'
     max_replication_slots: 10
-    max_wal_senders: 10
+    max_wal_senders: 12
     wal_level: replica
     wal_log_hints: 'on'
   pg_hba:
Configuration changed

4.4 切换类命令：switchover（计划内）与 failover（应急）

两者的定位差异是面试与实操双重高频考点：

对比项switchoverfailover
使用场景计划内维护（升级、迁移、演练）现任主库疑似不可用时的应急接管
对在线主库先降级旧主再提升候选，严格保护数据不检查旧主状态，直接强制切换
典型参数--leader <现任主> --candidate <候选>--leader <原主> --candidate <候选> --force
交互确认缺省交互询问，--force 免确认缺省交互询问，--force 免确认

switchover 实测（把主库从 pgnode1 平移到 pgnode2）：

patronictl -c /etc/patroni/patroni.yml switchover pgdemo --leader pgnode1 --candidate pgnode2 --force

实测回显：

Current cluster topology
+ Cluster: pgdemo (7698419935852473711) ------+----+-------------+-----+------------+-----+
| Member  | Host        | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
| pgnode1 | 10.89.60.11 | Leader  | running   |  1 |             |     |            |     |
| pgnode2 | 10.89.60.12 | Replica | streaming |  1 |   0/4087C70 |   0 |  0/4087C70 |   0 |
| pgnode3 | 10.89.60.13 | Replica | streaming |  1 |   0/4087C70 |   0 |  0/4087C70 |   0 |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
2026-10-19 16:43:07.55887 Successfully switched over to "pgnode2"

failover 实测（对健康集群执行 failover pgdemo --candidate pgnode3 --force——注意：即使现任主库在线，--force 也会直接触发切换，实测 pgnode3 被提升、时间线升到 4）：

Current cluster topology
+ Cluster: pgdemo (...) ------+----+-------------+-----+------------+-----+
| Member  | Host        | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
| pgnode1 | 10.89.60.11 | Leader  | running   |  3 |             |     |            |     |
| pgnode2 | 10.89.60.12 | Replica | streaming |  3 |   0/60112C0 |   0 |  0/60112C0 |   0 |
| pgnode3 | 10.89.60.13 | Replica | streaming |  3 |   0/60112C0 |   0 |  0/60112C0 |   0 |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
2026-10-19 16:59:36.32266 Successfully switched over to "pgnode3"

⚠️ 强烈建议：failover 是为「主库失联但 Patroni 未自动切换」设计的应急通道，禁止在健康集群上随手使用；日常演练与维护一律用 switchover。不带 --candidate 时两者都会交互式列出可候选节点。

4.5 实例管理命令：restart / reload / reinit

（1）restart——重启指定成员的 Patroni 管理域（消 pending restart、重载进程）（实测回显）：

patronictl -c /etc/patroni/patroni.yml restart pgdemo pgnode3 --force

+ Cluster: pgdemo (7698419935852473711) ------+----+-------------+-----+------------+-----+
| Member  | Host        | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
| pgnode1 | 10.89.60.11 | Replica | streaming |  3 |   0/40886C8 |   0 |  0/40886C8 |   0 |
| pgnode2 | 10.89.60.12 | Leader  | running   |  3 |             |     |            |     |
| pgnode3 | 10.89.60.13 | Replica | streaming |  3 |   0/40886C8 |   0 |  0/40886C8 |   0 |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
Success: Restart on member pgnode3

支持 --pg-version 17.11（滚动大版本）、--role leader（按角色批量）、--any（任一成员）。多节点重启顺序：先从库后主库。

（2）reload——仅重载配置不重启进程（实测回显）：

patronictl -c /etc/patroni/patroni.yml reload pgdemo pgnode3 --force

+ Cluster: pgdemo (...) ------+----+-------------+-----+------------+-----+
| Member  | Host        | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
| pgnode3 | 10.89.60.13 | Replica | streaming |  3 |   0/40C2930 |   0 |  0/40C2930 |   0 |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
Success: reload on member pgnode3

（3）reinit——从主库整库重建指定从库（pg_basebackup 全量覆盖）（实测回显）：

patronictl -c /etc/patroni/patroni.yml reinit pgdemo pgnode2 --force

+ Cluster: pgdemo (...) ------+----+-------------+-----+------------+-----+
| Member  | Host        | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
| pgnode1 | 10.89.60.11 | Leader  | running   |  3 |             |     |            |     |
| pgnode2 | 10.89.60.12 | Replica | streaming |  3 |   0/40C2930 |   0 |  0/40C2930 |   0 |
| pgnode3 | 10.89.60.13 | Replica | streaming |  3 |   0/40C2930 |   0 |  0/40C2930 |   0 |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+
Success: reinitialize for member pgnode2

💡 技术拓展：reinit 是「重锤」——数据目录被 pg_basebackup 全量覆盖，数据量大时耗时数小时且占用主库 IO/网络；旧主回归场景应优先信任 pg_rewind（增量回卷，秒级），只有 rewind 失败（如 wal_log_hints 未开）才动用 reinit。

4.6 维护模式命令：pause / resume

pause 冻结自动故障转移与角色自动调整（打补丁、全量备份等需要"让集群安静"的场景）；resume 恢复。实测（pause → 查看 → resume）：

Success: cluster management is paused

+ Cluster: pgdemo (7698419935852473711) ------+----+-------------+-----+------------+-----+--------+
| Member  | Host        | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag | Pending restart |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+-----------------+
| pgnode1 | 10.89.60.11 | Leader  | running   |  3 |             |     |            |     | *               |
| pgnode2 | 10.89.60.12 | Replica | streaming |  3 |   0/40C2930 |   0 |  0/40C2930 |   0 | *               |
| pgnode3 | 10.89.60.13 | Replica | running   |  3 |   0/40C2930 |   0 |  0/40C2930 |   0 | *               |
+---------+-------------+---------+-----------+----+-------------+-----+------------+-----+-----------------+
Maintenance mode

Success: cluster management is resumed

resume 后的 list 输出顶部 Maintenance mode 标记消失。⚠️ pause 期间主库宕机不会自动选主，务必在维护窗口内完成操作并 resume。

4.7 查询命令：query

不直连某台机器、跟随角色跑 SQL/取 DSN（实测回显）：

PGPASSWORD=q1w2e3r4 patronictl -c /etc/patroni/patroni.yml query pgdemo -U postgres -c "SELECT count(*) FROM ha_demo;"

 count
-------
     3
(1 row)

常用参数：-r leader|replica（按角色路由）、--file（执行 SQL 文件）、不带 -c 时仅输出 DSN（等价 dsn）。

4.8 危险命令与低频命令

命令用途风险与实测说明
remove从 DCS 抹掉整个集群注册信息（etcd 中 /service/pgdemo/ 全部 key）不可逆。--help 实测需交互确认集群名（输入集群名 + Yes I am aware）；仅用于彻底废弃集群。执行前务必 show-config > 备份文件
flush pgdemo取消已排程的 switchover/restart 计划任务flush pgdemo restart --force 实测格式可用；排程任务用 restart --scheduled / switchover --scheduled 创建
demote-cluster把普通集群降级为跟随上游的 standby cluster（跨机房容灾用）需提供上游 --host/--port/--restore-command/--primary-slot-name；本次未实测（涉及第二套集群）
promote-cluster把 standby 集群转正为独立集群standby 场景专用，本次未实测

五、REST API 管理端点（8008 端口）

REST API 既是 HAProxy 的健康检查来源，也是脚本化运维通道。核心 GET 端点实测（全部在节点上 curl 验证）：

端点行为实测结果
/服务探活返回 403（非 root 路径无授权时），进程存活即可探测
/health存活检查{"state": "running", "role": "primary"}，HTTP 200
/patroni本节点完整状态 JSON含 role/timeline/replication 数组/patroni.version 等（全文见部署篇 4.7 节）
/primary（别名 /master）仅主库返回 200主库实测返回完整 JSON；从库上调用返回 503
/replica仅从库返回 200从库实测：{"state": "running", "role": "replica", ...}
/read-only可读节点（主+从）返回 200从库实测 role=replica JSON
/config读取 DCS 动态配置返回与 show-config 一致的 JSON
/history故障转移历史JSON 数组：[[1, 67665336, "no recovery target specified", "2026-10-19T16:43:07...", "pgnode2"], ...]
/cluster全集群拓扑 JSON含 members 数组（各节点 name/host/role/state/timeline/lag）

实测示例（在 pgnode2 上 curl 主库与自身）：

curl -s http://10.89.60.11:8008/primary
curl -s http://10.89.60.12:8008/replica

{"state": "running", "postmaster_start_time": "2026-10-19 16:46:57.805386+00:00", "role": "primary", "server_version": 170011, "xlog": {"location": 100677800}, "timeline": 4, ...}

{"state": "running", "postmaster_start_time": "2026-10-19 16:46:57.805386+00:00", "role": "replica", "server_version": 170011, "xlog": {"received_location": 100677800, "replayed_location": 100677800}, ...}

写通道：PATCH /config 提交与 edit-config 等价的 DCS 配置变更（报文即 /config 返回的 JSON 子集），适合自动化平台对接；生产建议开启 restapi authentication 或 ssl 段后再对外暴露。

六、外围巡检工具

6.1 etcdctl：DCS 层健康检查

三节点 etcd 成员与 leader 分布（实测回显，见部署篇 4.4 节全文）：

etcdctl --endpoints=10.89.60.11:2379 member list -w table
etcdctl --endpoints=10.89.60.11:2379 endpoint status --cluster -w table
etcdctl --endpoints=10.89.60.11:2379 endpoint health --cluster

Patroni 在 etcd 中的 key 空间实测（etcdctl --endpoints=10.89.60.11:2379 get /service/pgdemo/ --prefix --keys-only）：

/service/pgdemo/config
/service/pgdemo/failover
/service/pgdemo/history
/service/pgdemo/initialize
/service/pgdemo/leader
/service/pgdemo/members/pgnode1
/service/pgdemo/members/pgnode2
/service/pgdemo/members/pgnode3
/service/pgdemo/status

巡检要点：leader key 的 TTL 是否在被持续续约、members/* 是否齐全、config 与 patronictl show-config 是否一致。etcd 集群出现 member 不可用时，Patroni 只要还能连上法定人数就不受影响。

6.2 psql：数据层巡检 SQL

# 主库视角：流复制通道状态（实测回显：两行 streaming/async，client_addr 为两个从库）
su postgres -c "psql -c \"SELECT application_name, state, sync_state, client_addr FROM pg_stat_replication;\""

# 任意节点视角：是否处于恢复态（主库 f，从库 t）
PGPASSWORD=q1w2e3r4 psql -h 10.89.60.12 -U postgres -c "SELECT pg_is_in_recovery();"

复制槽检查（use_slots: true 时每个从库对应一个槽）：

su postgres -c "psql -c \"SELECT slot_name, slot_type, active FROM pg_replication_slots;\""

巡检口径：pg_stat_replication 在主库上应有 N-1 行 streaming；pg_replication_slots 的 active 必须为 t，出现 inactive 槽需排查（否则 WAL 无限堆积）。

七、注意事项

  1. 集群名别打错：除 version/--help 外，所有子命令都要带集群名（pgdemo）；跑错集群名会报 Cluster is not initialized 或查询到错误集群。
  2. --force 是双刃剑：所有交互式命令的确认环节都会被跳过，排程演练可用，生产变更建议保留确认（或用 -y 前三思）。
  3. 在哪台节点执行都行，但 reinit/restart 的目标节点写成员名（pgnodeN）而非 IP。
  4. pause 状态下不要离开人：维护窗口结束必须 resume，否则主库宕机无人接管。
  5. query/dsn 跟随的是"当前"角色：故障转移发生后输出会随之变化，不要把 dsn 输出写死进配置文件。
  6. patronictl 版本与服务端同版本：本篇全部实测基于 4.1.5 客户端 + 4.1.5 服务端；跨大版本混用可能存在旗标语义差异（4.0 起 --master 等旧旗标已更名）。

八、常见问题（FAQ）

Q1：patronictl list 报 Cluster is not initialized？

三种可能：① 集群名写错（本篇实测集群名为 pgdemo）；② -c 指向的配置文件里 scope/namespace 与实际集群不一致；③ DCS 连不上（用 etcdctl endpoint health --cluster 先排 DCS）。

Q2：query 连接报口令错误？

query 走 libpq 认证，口令需经 PGPASSWORD 环境变量或 ~/.pgpass 提供（本篇实测前缀 PGPASSWORD=q1w2e3r4）；生产建议配置 .pgpass（600 权限）避免口令进 shell 历史。

Q3：list 里 Pending restart 星号怎么消除，-f json 能看到原因吗？

能——4.x 的 json 输出含 Pending restart reason（实测样例："max_wal_senders: 12->10"，表示 DCS 期望值 10 但进程仍运行 12）。按《Patroni 4.1.5 配置参数详解》3.3 节，在维护窗口对受影响节点执行 patronictl restart pgdemo <节点> --force（先从后主）即可清除。

Q4：switchover 后旧主长时间 stopped 不回来？

先看旧主上 patroni 服务是否在运行（systemctl status patroni）；若服务被手动停止过需先拉起。服务正常但仍 stopped 时查 journalctl -u patroni：常见原因是旧主上存在未复制事务且未开 pg_rewind 前提（wal_log_hints/data-checksums），需手工决策后 reinit（4.5 节）。

Q5：能不能用 remove 重建集群？

可以但极其危险：remove 只清 DCS 注册信息与动态配置，不动数据目录；用于「保留数据目录、重置集群身份」的救援场景时，务必先 show-config 备份配置、确认三个节点的 patroni 服务全部停止后再操作，否则残留 Patroni 进程可能重新写入旧 key。

九、参考链接