pg_auto_failover 2.2 配置参数详解

目标：系统梳理 pg_auto_failover 2.2 的全部可配置项，分为 monitor 配置、keeper 配置、复制相关参数、超时参数、SSL 参数五大类，每项给出含义、默认值、修改方式与实测回显。所有命令均在 1 monitor + 2 数据节点集群上实测通过（Ubuntu 22.04 + PostgreSQL 17.11 + pg_auto_failover 2.2）。

一、环境信息

项目	取值
操作系统	Ubuntu 22.04 LTS
PostgreSQL	17.11
pg_auto_failover	2.2
集群形态	1 monitor + 2 数据节点
配置文件路径	~/.config/pg_autoctl/<pgdata路径>/pg_autoctl.cfg
monitor 数据目录	/var/lib/pgaf/data
数据节点数据目录	/var/lib/pgaf/data

二、配置查看与修改方式

2.1 查看当前配置

pg_auto_failover 的配置分为两层：

本地配置文件（pg_autoctl.cfg）：每个节点自身的配置，如 pgdata、monitor 连接串、SSL 等；
monitor 集中配置：存放在 monitor 数据库中的集群级配置，如 candidate-priority、replication-quorum、number-sync-standbys。

查看本地配置：

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

实测回显（数据节点）：

[pg_autoctl]
role = keeper
monitor = postgres://autoctl_node@monitor:5432/pg_auto_failover
formation = default
group = 0
name = node_1
hostname = node1
nodekind = standalone

[postgresql]
pgdata = /var/lib/pgaf/data
pg_ctl = /usr/lib/postgresql/17/bin/pg_ctl
username = postgres
dbname = postgres
host = localhost
port = 5432
proxyport = 0
listen_addresses = 0.0.0.0
auth_method = trust
hba_level = app

[ssl]
active = 1
sslmode = require
cert_file = /var/lib/pgaf/data/server.crt
key_file = /var/lib/pgaf/data/server.key

[replication]
maximum_backup_rate = 100M
backup_directory = /var/lib/pgaf/backup/node_1

[timeout]
network_partition_timeout = 20
prepare_promotion_catchup = 30
prepare_promotion_walreceiver = 5
postgresql_restart_failure_timeout = 20
postgresql_restart_failure_max_retries = 3

查看 monitor 集中配置：

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

2.2 修改本地配置

本地配置通过 pg_autoctl config set 修改：

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

修改后需 pg_autoctl reload 生效。

2.3 修改 monitor 集中配置

monitor 集中配置通过 pg_autoctl set node / pg_autoctl set formation 修改（部分参数也可直接调用 monitor 数据库中的 SQL 函数）。

三、核心参数分类详解

3.1 节点属性参数

candidate-priority（候选优先级）

含义：节点被提升为主库的优先级，取值 0–100，数值越高越优先被提升。
默认值：50
修改方式：pg_autoctl set node candidate-priority --name <节点名> <值>
实测：

# 查询当前优先级
pg_autoctl get node candidate-priority --pgdata /var/lib/pgaf/data --name node_1

回显：

⚠️ 注意：pg_auto_failover 2.2 的 pg_autoctl set node candidate-priority CLI 存在参数解析缺陷，传入任意整数值均报 "value X is not valid"。可绕过此问题，直接在 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)

设置后查看：

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

回显（节选）：

     node |  node_1 |        candidate priority | 80

replication-quorum（复制仲裁）

含义：该节点是否参与写入仲裁。设为 true 时，主库的每次提交需等待该备库确认收到 WAL；设为 false 时，该备库仅异步复制，不阻塞主库写入。
默认值：true
修改方式：pg_autoctl set node replication-quorum --name <节点名> <true|false>
实测：

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

回显：

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.
false

设置后查看：

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

回显（节选）：

     node |  node_2 |        replication quorum | false

💡 技术拓展：复制仲裁（replication quorum）决定备库是否参与同步复制的写入确认。常见策略对比——

策略特点适用场景
全部备库参与仲裁 RPO=0，但任一备库故障都会阻塞主库写入对数据一致性要求极高
部分备库参与仲裁平衡性能与一致性，故障备库不阻塞写入大多数生产场景
无备库参与仲裁纯异步复制，性能最好但可能丢数据对性能要求极高、可容忍少量数据丢失

pg_auto_failover 默认所有备库参与仲裁（replication-quorum=true），并在备库不健康时自动将其移出 synchronous_standby_names，兼顾一致性与可用性。

策略	特点	适用场景
全部备库参与仲裁	RPO=0，但任一备库故障都会阻塞主库写入	对数据一致性要求极高
部分备库参与仲裁	平衡性能与一致性，故障备库不阻塞写入	大多数生产场景
无备库参与仲裁	纯异步复制，性能最好但可能丢数据	对性能要求极高、可容忍少量数据丢失

3.2 集群级复制参数

number-sync-standbys（同步备库数量）

含义：要求多少个同步备库确认 WAL 后，主库的提交才返回。设为 0 时使用 ANY 1 语义（任意一个备库确认即可）。
默认值：0
修改方式：pg_autoctl set formation number-sync-standbys --formation default <值>
约束：必须有足够多参与仲裁的备库。例如设为 1 时，至少需要 2 个参与仲裁的备库（1 个同步 + 1 个冗余）。
实测：当仅有 1 个参与仲裁的备库时，设为 1 会报错：

ERROR:  invalid value for number_sync_standbys: "1"
DETAIL:  At least 2 standby nodes are required, and only 1 are currently participating in the replication quorum

💡 技术拓展：PostgreSQL 的同步复制有两种语义——FIRST N（前 N 个备库确认）和 ANY N（任意 N 个备库确认）。pg_auto_failover 默认使用 ANY 1（number_sync_standbys=0 时），即只要有一个备库确认就提交，性能与一致性的平衡点。

synchronous_standby_names（同步备库名称）

含义：PostgreSQL 内核参数，由 pg_auto_failover 自动维护，列出当前同步复制的备库名称。
默认值：由 monitor 根据节点状态自动生成，格式如 'ANY 1 (pgautofailover_standby_2)'
修改方式：不建议手动修改，由 monitor 自动管理。
查看方式：pg_autoctl show standby-names --pgdata /var/lib/pgaf/data
实测回显：

'ANY 1 (pgautofailover_standby_2)'

3.3 本地 PostgreSQL 配置

参数	含义	默认值	修改方式
pgdata	PostgreSQL 数据目录	无（必填）	`pg_autoctl create` 时 `--pgdata`
pg_ctl	pg_ctl 路径	自动检测	配置文件 `[postgresql]` 段
pghost / host	本地连接主机名	localhost	`--pghost`
pgport / port	PostgreSQL 端口	5432	`--pgport`
listen_addresses	监听地址	*	`--listen`
username	数据库用户名	postgres	`--username`
dbname	数据库名	postgres	`--dbname`
auth_method	认证方式	trust	`--auth`

3.4 超时参数

超时参数位于配置文件的 [timeout] 段，控制故障转移各阶段的等待时间：

参数	含义	默认值
network_partition_timeout	网络分区超时（秒），超过后 monitor 认为节点失联	20
prepare_promotion_catchup	备库提升前追赶 WAL 的超时（秒）	30
prepare_promotion_walreceiver	备库提升前等待 WAL 接收进程停止的超时（秒）	5
postgresql_restart_failure_timeout	PostgreSQL 重启失败的超时（秒）	20
postgresql_restart_failure_max_retries	PostgreSQL 重启失败的最大重试次数	3

💡 说明：network_partition_timeout 是最关键的超时参数——它决定了主库失联后多久开始故障转移。值越小故障转移越快，但可能因短暂网络抖动触发不必要的切换；值越大越稳定，但故障恢复时间越长。生产环境建议根据网络稳定性在 20–60 秒之间调整。

3.5 复制参数

参数	含义	默认值
maximum_backup_rate	初始同步（pg_basebackup）的最大传输速率	100M
backup_directory	备份目录	/var/lib/pgaf/backup/<节点名>

3.6 SSL 参数

参数	含义	默认值
active	是否启用 SSL	1（启用）
sslmode	SSL 模式	require
cert_file	服务器证书路径	<pgdata>/server.crt
key_file	服务器私钥路径	<pgdata>/server.key

pg_auto_failover 支持三种 SSL 配置方式：

自签名证书（--ssl-self-signed）：pg_autoctl 自动生成，适合测试与内网；
自定义证书（--server-key / --server-cert / --ssl-ca-file）：使用 CA 签发的证书，适合生产；
不加密（--no-ssl）：明文传输，不推荐。

四、配置检查

使用 pg_autoctl config check 检查当前节点配置是否正确：

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

实测回显：

INFO  Postgres setup for PGDATA "/var/lib/pgaf/data" is ok, running with PID 5432 and port 330
INFO  Connection to local Postgres ok, using "port=5432 dbname=postgres host=localhost user=postgres"
INFO  Postgres configuration settings required for pg_auto_failover are ok
INFO  Postgres version "17.11" allows using replication slots on the standby nodes
pgdata:                /var/lib/pgaf/data
pg_ctl:                /usr/lib/postgresql/17/bin/pg_ctl
pg_version:            "17.11" (1711)
pghost:                localhost
pgport:                5432
pid:                   330
is in recovery:        yes
Control cluster state: in archive recovery
INFO  Connection to monitor ok, using "postgres://autoctl_node@monitor:5432/pg_auto_failover"
INFO  Monitor is running version "2.2", as expected

检查项包括：本地 PostgreSQL 是否运行、配置是否符合 pg_auto_failover 要求、PostgreSQL 版本是否支持复制槽、与 monitor 的连接是否正常、monitor 版本是否匹配。

五、生产配置模板

以下为一个 2 节点（1 主 1 备）生产集群的推荐配置：

5.1 monitor 节点

[pg_autoctl]
role = monitor
hostname = monitor

[postgresql]
pgdata = /var/lib/pgaf/data
pg_ctl = /usr/lib/postgresql/17/bin/pg_ctl
username = autoctl_node
dbname = pg_auto_failover
host = /var/run/postgresql
port = 5432
listen_addresses = *
auth_method = scram-sha-256

[ssl]
active = 1
sslmode = verify-ca
cert_file = /etc/ssl/certs/pgaf-monitor.crt
key_file = /etc/ssl/private/pgaf-monitor.key

5.2 数据节点

[pg_autoctl]
role = keeper
monitor = postgres://autoctl_node@monitor:5432/pg_auto_failover
formation = default
group = 0
hostname = node1
nodekind = standalone

[postgresql]
pgdata = /var/lib/pgaf/data
pg_ctl = /usr/lib/postgresql/17/bin/pg_ctl
username = postgres
dbname = postgres
host = localhost
port = 5432
listen_addresses = 0.0.0.0
auth_method = scram-sha-256

[ssl]
active = 1
sslmode = verify-ca
cert_file = /etc/ssl/certs/pgaf-node1.crt
key_file = /etc/ssl/private/pgaf-node1.key

[timeout]
network_partition_timeout = 30

5.3 monitor 集中配置

# 主备优先级：主库优先级设高，避免故障恢复后主备频繁切换
SELECT pgautofailover.set_node_candidate_priority('default', 'node_1', 90);
SELECT pgautofailover.set_node_candidate_priority('default', 'node_2', 50);

# 两个备库都参与仲裁（3 节点集群时）
pg_autoctl set node replication-quorum --name node_2 true

六、常见问题

6.1 set node candidate-priority 报 "value X is not valid"

现象：pg_autoctl set node candidate-priority --name node_1 80 报 candidate-priority value 80 is not valid. Valid values are integers from 0 to 100.

原因：pg_auto_failover 2.2 的 CLI 参数解析缺陷。

解决：直接调用 monitor 数据库的 SQL 函数：

SELECT pgautofailover.set_node_candidate_priority('default', 'node_1', 80);

6.2 set formation number-sync-standbys 报 "At least N standby nodes are required"

现象：设置 number-sync-standbys 时报备库数量不足。

原因：参与仲裁的备库数量不够。设为 N 时，至少需要 N+1 个参与仲裁的备库。

解决：增加参与仲裁的备库数量，或降低 number-sync-standbys 的值。

6.3 修改配置后不生效

现象：修改了 pg_autoctl.cfg 但行为未变。

解决：执行 pg_autoctl reload --pgdata /var/lib/pgaf/data 重载配置，或重启 pg_autoctl 进程。

七、参考链接

官方配置文档：https://pg-auto-failover.readthedocs.io/en/main/reference.html
故障转移设计：https://pg-auto-failover.readthedocs.io/en/main/failover-design.html
PostgreSQL 同步复制：https://www.postgresql.org/docs/current/warm-standby.html#SYNCHRONOUS-REPLICATION