pg_auto_failover 2.2 常用 CLI 命令详解

目标：逐条详解 pg_auto_failover 2.2 的核心命令行工具 pg_autoctl，覆盖 create、show、set/get、perform、config、enable/disable、run/stop/reload/status、drop 等子命令，每条命令给出语法、参数说明与实测回显。所有命令均在 1 monitor + 2 数据节点集群上实测通过（Ubuntu 22.04 + PostgreSQL 17.11 + pg_auto_failover 2.2）。

一、环境信息

项目	取值
pg_autoctl 版本	2.2-4.pgdg22.04+1
扩展版本	2.2
PostgreSQL	17.11
集群形态	1 monitor（主机名 monitor）+ 2 数据节点（node1 主 / node2 备）

二、工具概览

pg_autoctl 是 pg_auto_failover 的统一命令行工具，既是管理 CLI，也是 monitor/keeper 的运行进程。命令树如下：

pg_autoctl
├── create     创建 monitor / 数据节点 / formation
├── drop       删除 monitor / 数据节点 / formation
├── config     管理本地配置（check/get/set）
├── show       查看集群信息（uri/events/state/settings/standby-names/file/systemd）
├── enable     启用特性（secondary/maintenance/ssl/monitor）
├── disable    禁用特性
├── get        获取节点/formation 配置
├── set        设置节点/formation 配置
├── perform    执行故障转移动作（failover/switchover/promotion）
├── run        启动 pg_autoctl 服务（monitor 或 keeper）
├── watch      实时监控集群状态与事件
├── stop       停止 pg_autoctl 服务
├── reload     重载 pg_autoctl 配置
├── status     查看 pg_autoctl 服务状态
└── version    查看版本

全局选项：

pg_autoctl [ --verbose --quiet ] <command>

--verbose：输出详细日志；
--quiet：静默模式，仅输出结果。

三、版本与帮助

3.1 pg_autoctl --version

查看版本信息：

pg_autoctl --version

实测回显：

pg_autoctl version 2.2-4.pgdg22.04+1
pg_autoctl extension version 2.2
compiled with PostgreSQL 18.4 (Ubuntu 18.4-1.pgdg22.04+1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0, 64-bit
compatible with Postgres 13, 14, 15, 16 and 17

3.2 pg_autoctl --help

查看命令总览：

pg_autoctl --help

实测回显：

pg_autoctl: pg_auto_failover control tools and service
usage: pg_autoctl [ --verbose --quiet ]

Available commands:
  pg_autoctl
  + create    Create a pg_auto_failover node, or formation
  + drop      Drop a pg_auto_failover node, or formation
  + config    Manages the pg_autoctl configuration
  + show      Show pg_auto_failover information
  + enable    Enable a feature on a formation
  + disable   Disable a feature on a formation
  + get       Get a pg_auto_failover node, or formation setting
  + set       Set a pg_auto_failover node, or formation setting
  + perform   Perform an action orchestrated by the monitor
    activate  Activate a Citus worker from the Citus coordinator
    run       Run the pg_autoctl service (monitor or keeper)
    watch     Display a dashboard to watch monitor's events and state
    stop      signal the pg_autoctl service for it to stop
    reload    signal the pg_autoctl for it to reload its configuration
    status    Display the current status of the pg_autoctl service
    help      print help message
    version   print pg_autoctl version

四、create 命令

4.1 pg_autoctl create monitor

初始化 monitor 节点。

语法：

pg_autoctl create monitor [ --pgdata --pgport --pgctl --hostname ]

主要参数：

参数	含义	默认值
`--pgdata`	数据目录	无（必填）
`--pgport`	PostgreSQL 端口	5432
`--hostname`	monitor 对外主机名	自动检测
`--auth`	数据节点连接的认证方式	无
`--run`	创建后立即启动	false
`--ssl-self-signed`	使用自签名证书	false
`--no-ssl`	不启用 SSL	false

实测：

pg_autoctl create monitor \
  --pgdata /var/lib/pgaf/data \
  --hostname monitor \
  --pgport 5432 \
  --auth trust \
  --ssl-self-signed \
  --run

回显（节选）：

INFO  Initialising a PostgreSQL cluster at "/var/lib/pgaf/data"
INFO  Your pg_auto_failover monitor instance is now ready on port 5432.
INFO  Monitor has been successfully initialized.

4.2 pg_autoctl create postgres

初始化一个数据节点（keeper）并注册到 monitor。

语法：

pg_autoctl create postgres [ --pgdata --pghost --pgport --hostname --monitor ... ]

主要参数：

参数	含义	默认值
`--pgdata`	数据目录	无（必填）
`--pghost`	PostgreSQL 本地连接主机	localhost
`--pgport`	PostgreSQL 端口	5432
`--listen`	监听地址	*
`--hostname`	对外主机名	自动检测
`--monitor`	monitor 连接串	无（必填）
`--auth`	认证方式	无
`--pg-hba-lan`	自动放通局域网	false
`--candidate-priority`	候选优先级	50
`--replication-quorum`	是否参与仲裁	true
`--ssl-self-signed`	自签名证书	false
`--run`	创建后立即启动	false

实测：

pg_autoctl create postgres \
  --pgdata /var/lib/pgaf/data \
  --pghost localhost \
  --hostname node1 \
  --pgport 5432 \
  --listen 0.0.0.0 \
  --monitor postgres://autoctl_node@monitor:5432/pg_auto_failover \
  --auth trust \
  --pg-hba-lan \
  --ssl-self-signed \
  --run

回显（节选）：

INFO  Registering node 1 "node_1" (node1:5432) to formation "default"
INFO  Setting goal state of node 1 "node_1" (node1:5432) to single as there is no other node.
INFO  FSM transition from "init" to "single": Start as a single node

五、show 命令

5.1 pg_autoctl show state

查看集群节点状态（最常用命令）。

pg_autoctl show state --pgdata /var/lib/pgaf/data

实测回显：

  Name |  Node |  Host:Port |       TLI: LSN |   Connection |      Reported State |      Assigned State
-------+-------+------------+----------------+--------------+---------------------+--------------------
node_1 |     1 | node1:5432 |   1: 0/3000130 |   read-write |             primary |             primary
node_2 |     2 | node2:5432 |   1: 0/3000130 |    read-only |           secondary |           secondary

字段说明：

Name：节点在 monitor 中的名称；
Node：节点 ID；
Host:Port：节点连接地址；
TLI: LSN：时间线与日志序列号，主备一致表示同步正常；
Connection：连接类型（read-write=主库，read-only=备库，none=不可达）；
Reported State：节点实际报告的状态；
Assigned State：monitor 要求的目标状态。

5.2 pg_autoctl show uri

查看连接 URI：

pg_autoctl show uri --pgdata /var/lib/pgaf/data

实测回显：

        Type |    Name | Connection String
-------------+---------+-------------------------------
     monitor | monitor | postgres://autoctl_node@monitor:5432/pg_auto_failover?sslmode=require
   formation | default | postgres://node1:5432,node2:5432/postgres?target_session_attrs=read-write&sslmode=require

formation 行的连接串可直接用于应用连接，target_session_attrs=read-write 确保应用只连主库。

5.3 pg_autoctl show settings

查看复制相关配置：

pg_autoctl show settings --pgdata /var/lib/pgaf/data

实测回显：

  Context |    Name |                   Setting | Value
----------+---------+---------------------------+-----------------------------------
formation | default |      number_sync_standbys | 0
  primary |  node_1 | synchronous_standby_names | 'ANY 1 (pgautofailover_standby_2)'
     node |  node_1 |        candidate priority | 50
     node |  node_2 |        candidate priority | 50
     node |  node_1 |        replication quorum | true
     node |  node_2 |        replication quorum | true

5.4 pg_autoctl show events

查看集群状态变更事件历史：

pg_autoctl show events --pgdata /var/lib/pgaf/data

实测回显（节选）：

                    Event Time |   Node |       Current State |      Assigned State | Comment
-------------------------------+--------+---------------------+---------------------+-----------
 2026-10-25 12:06:39.003676+00 |    0/1 |              single |        wait_primary | Setting goal state of node 1 to wait_primary after node 2 joined.
 2026-10-25 12:06:47.521927+00 |    0/2 |          catchingup |           secondary | Setting goal state of node 2 to secondary after it caught up.
 2026-10-25 12:06:47.584359+00 |    0/1 |        wait_primary |             primary | Setting goal state of node 1 to primary now that we have 1 healthy secondary.

5.5 pg_autoctl show standby-names

查看当前 synchronous_standby_names 配置：

pg_autoctl show standby-names --pgdata /var/lib/pgaf/data

实测回显：

'ANY 1 (pgautofailover_standby_2)'

5.6 pg_autoctl show file

查看 pg_autoctl 内部文件路径：

pg_autoctl show file --pgdata /var/lib/pgaf/data

实测回显：

   File | Path
--------+----------------
 Config | /var/lib/postgresql/.config/pg_autoctl/var/lib/pgaf/data/pg_autoctl.cfg
    Pid | /tmp/pg_autoctl/var/lib/pgaf/data/pg_autoctl.pid

5.7 pg_autoctl show systemd

输出 systemd 单元文件，用于生产托管：

pg_autoctl show systemd --pgdata /var/lib/pgaf/data

实测回显：

[Unit]
Description = pg_auto_failover

[Service]
WorkingDirectory = /var/lib/postgresql
Environment = 'PGDATA=/var/lib/pgaf/data'
User = postgres
ExecStart = /usr/bin/pg_autoctl run
Restart = always
StartLimitBurst = 0
ExecReload = /usr/bin/pg_autoctl reload

[Install]
WantedBy = multi-user.target

六、set / get 命令

6.1 pg_autoctl set node replication-quorum

设置节点是否参与复制仲裁：

pg_autoctl set node replication-quorum --pgdata /var/lib/pgaf/data --name node_2 true

实测回显：

INFO  Waiting for the settings to have been applied to the monitor and primary node
INFO  New state is reported by node 2 "node_2" (node2:5432): "apply_settings"
INFO  Setting goal state of node 2 "node_2" (node2:5432) to primary after it applied replication properties change.
true

6.2 pg_autoctl get node replication-quorum

查询节点复制仲裁设置：

pg_autoctl get node replication-quorum --pgdata /var/lib/pgaf/data --name node_2

回显：

true

6.3 pg_autoctl set node candidate-priority

设置节点候选优先级。

⚠️ 注意：pg_auto_failover 2.2 的该 CLI 子命令存在参数解析缺陷，直接调用会报错。需通过 monitor 数据库的 SQL 函数设置：

psql -h monitor -p 5432 -d pg_auto_failover -U autoctl_node \
  -c "SELECT pgautofailover.set_node_candidate_priority('default', 'node_1', 80);"

回显：

 set_node_candidate_priority
-----------------------------
 t
(1 row)

6.4 pg_autoctl get node candidate-priority

查询候选优先级：

pg_autoctl get node candidate-priority --pgdata /var/lib/pgaf/data --name node_1

回显：

6.5 pg_autoctl set formation number-sync-standbys

设置集群同步备库数量：

pg_autoctl set formation number-sync-standbys --pgdata /var/lib/pgaf/data --formation default 0

注意：设为 N 时需要至少 N+1 个参与仲裁的备库。

七、perform 命令（故障转移）

7.1 pg_autoctl perform failover

主动执行故障转移（模拟主库故障，提升备库）。

语法：

pg_autoctl perform failover [ --pgdata --formation --group ]

实测（切换前 node_1 为主库，node_2 为备库）：

pg_autoctl perform failover --pgdata /var/lib/pgaf/data --formation default --group 0

回显（状态转换过程）：

INFO  Waiting 60 secs for a notification with state "primary"
    Time |   Name |  Node |  Host:Port |       Current State |      Assigned State
---------+--------+-------+------------+---------------------+--------------------
12:08:01 | node_1 |   0/1 | node1:5432 |             primary |            draining
12:08:01 | node_2 |   0/2 | node2:5432 |           secondary |   prepare_promotion
12:08:02 | node_2 |   0/2 | node2:5432 |    stop_replication |        wait_primary
12:08:02 | node_1 |   0/1 | node1:5432 |      demote_timeout |             demoted
12:08:03 | node_1 |   0/1 | node1:5432 |          catchingup |           secondary
12:08:03 | node_2 |   0/2 | node2:5432 |        wait_primary |             primary

切换后状态：

  Name |  Node |  Host:Port |       TLI: LSN |   Connection |      Reported State |      Assigned State
-------+-------+------------+----------------+--------------+---------------------+--------------------
node_1 |     1 | node1:5432 |   2: 0/3091720 |    read-only |           secondary |           secondary
node_2 |     2 | node2:5432 |   2: 0/3091720 |   read-write |             primary |             primary

实测耗时：real 0m2.857s（约 2.9 秒）。

7.2 pg_autoctl perform switchover

计划性主备切换（主库正常时主动切换角色）。

pg_autoctl perform switchover --pgdata /var/lib/pgaf/data --formation default --group 0

与 failover 的区别：switchover 是计划内操作，主库先排空连接再降级；failover 是故障后操作，直接降级主库。

7.3 pg_autoctl perform promotion

提升指定节点为新主库：

pg_autoctl perform promotion [ --pgdata --formation --group --name ]

--name 指定要提升的节点名。

八、config 命令

8.1 pg_autoctl config check

检查本地配置与运行状态：

pg_autoctl config check --pgdata /var/lib/pgaf/data

实测回显：

INFO  Postgres setup for PGDATA "/var/lib/pgaf/data" is ok
INFO  Connection to local Postgres ok
INFO  Postgres configuration settings required for pg_auto_failover are ok
pgdata:                /var/lib/pgaf/data
pg_ctl:                /usr/lib/postgresql/17/bin/pg_ctl
pg_version:            "17.11" (1711)
pghost:                localhost
pgport:                5432
is in recovery:        yes
INFO  Connection to monitor ok
INFO  Monitor is running version "2.2", as expected

8.2 pg_autoctl config get

查看本地配置文件内容：

pg_autoctl config get --pgdata /var/lib/pgaf/data

输出为完整的 pg_autoctl.cfg 内容（详见《配置参数详解》第二章）。

8.3 pg_autoctl config set

修改本地配置项：

pg_autoctl config set --pgdata /var/lib/pgaf/data <section>.<key> <value>

修改后需 pg_autoctl reload 生效。

九、服务管理命令

9.1 pg_autoctl run

启动 pg_autoctl 服务（monitor 或 keeper）。create 命令加 --run 时会自动调用。

pg_autoctl run --pgdata /var/lib/pgaf/data

9.2 pg_autoctl stop

停止 pg_autoctl 服务：

pg_autoctl stop --pgdata /var/lib/pgaf/data

9.3 pg_autoctl reload

重载配置（不重启进程）：

pg_autoctl reload --pgdata /var/lib/pgaf/data

9.4 pg_autoctl status

查看服务运行状态：

pg_autoctl status --pgdata /var/lib/pgaf/data

实测回显：

INFO  pg_autoctl is running with pid 9
INFO  Postgres is serving PGDATA "/var/lib/pgaf/data" on port 5432 with pid 330

9.5 pg_autoctl watch

实时监控集群状态与事件（仪表盘模式）：

pg_autoctl watch --pgdata /var/lib/pgaf/data

参数：

--formation：指定 formation（默认 default）；
--group：指定 group（默认全部）；
--json：JSON 格式输出。

十、enable / disable 命令

10.1 pg_autoctl enable secondary

允许 formation 中存在备库节点（默认已启用）：

pg_autoctl enable secondary --pgdata /var/lib/pgaf/data --formation default

10.2 pg_autoctl disable secondary

禁止添加新的备库节点（已有备库不受影响）：

pg_autoctl disable secondary --pgdata /var/lib/pgaf/data --formation default

10.3 pg_autoctl enable maintenance

将节点置为维护模式（不参与故障转移）：

pg_autoctl enable maintenance --pgdata /var/lib/pgaf/data

10.4 pg_autoctl disable maintenance

取消维护模式：

pg_autoctl disable maintenance --pgdata /var/lib/pgaf/data

十一、drop 命令

11.1 pg_autoctl drop node

从 monitor 中移除一个数据节点：

pg_autoctl drop node --pgdata /var/lib/pgaf/data --name node_2

⚠️ 注意：drop node 会从 monitor 中注销节点，但不会删除节点上的数据。如需完全清理，需手动删除数据目录。

11.2 pg_autoctl drop monitor

删除 monitor（需先移除所有数据节点）：

pg_autoctl drop monitor --pgdata /var/lib/pgaf/data

11.3 pg_autoctl drop formation

删除一个 formation：

pg_autoctl drop formation --pgdata /var/lib/pgaf/data --formation default

十二、注意事项

--pgdata 参数：几乎所有命令都需要 --pgdata 指定数据目录，pg_autoctl 通过它定位配置文件。
monitor 命令 vs keeper 命令：show state、show settings、perform 等命令需在 monitor 节点执行（或通过 --pgdata 指向 monitor 的数据目录）；config、status、run 等命令在对应节点执行。
故障转移的安全性：perform failover 要求至少有一个健康的备库，否则 monitor 会拒绝执行，防止数据丢失。
SSL 强制要求：create 命令必须显式指定 SSL 选项（--ssl-self-signed、--no-ssl 或自定义证书）。

十三、参考链接

官方命令参考：https://pg-auto-failover.readthedocs.io/en/main/reference.html
故障转移设计：https://pg-auto-failover.readthedocs.io/en/main/failover-design.html