这是本节的多页打印视图。点击此处打印.

Patroni 配置

Patroni 配置模型、优先级规则与验证工具。

1: 动态配置
2: YAML 配置参数
3: 环境变量

原始页面： https://patroni.readthedocs.io/en/latest/patroni_configuration.html

Patroni 的配置分为 3 种类型：

全局 动态配置。这些选项存储在 DCS（分布式配置存储）中，并应用于集群的所有节点。动态配置可以随时通过 patronictl edit-config 工具或 Patroni REST API 进行设置。如果更改的选项不属于启动配置，它们将异步地（在下一个唤醒周期时）应用到每个节点，随后触发重载。如果节点需要重启才能应用配置（对于上下文为 postmaster 且值已更改的 PostgreSQL 参数），则会在成员数据 JSON 中设置一个特殊标志 pending_restart，同时节点状态也会通过 "restart_pending": true 来体现这一情况。
本地 YAML 配置文件（patroni.yml）。这些选项定义在配置文件中，优先级高于动态配置。patroni.yml 可以在运行时通过向 Patroni 进程发送 SIGHUP 信号、执行 POST /reload REST API 请求或运行 patronictl reload 来更改和重载（无需重启 Patroni）。本地配置可以是单个 YAML 文件，也可以是一个目录。当配置为目录时，该目录下的所有 YAML 文件会按排序顺序逐个加载。如果某个键在多个文件中定义，以最后一个文件中的值为准。
环境变量配置。可以通过环境变量设置/覆盖部分"本地"配置参数。环境配置在动态环境中非常有用——当某些参数事先无法确定时（例如在 docker 容器内运行时无法预知外部 IP 地址）。

重要规则

由 Patroni 控制的 PostgreSQL 参数

某些 PostgreSQL 参数必须在主库和从库上保持相同的值。对于这些参数，在本地 Patroni 配置文件或通过环境变量设置的值不会生效。要修改或设置这些参数的值，必须通过 DCS 修改共享配置。以下是这类参数的列表，包含默认值和最小值：

max_connections：默认值 100，最小值 25
max_locks_per_transaction：默认值 64，最小值 32
max_worker_processes：默认值 8，最小值 2
max_prepared_transactions：默认值 0，最小值 0
wal_level：默认值 hot_standby，可接受值：hot_standby、replica、logical
track_commit_timestamp：默认值 off

对于下列参数，PostgreSQL 不要求主库和所有从库的值相同。但考虑到从库随时可能成为主库，将它们设置为不同值实际上没有意义；因此，Patroni 限制只能通过 动态配置 来设置这些参数的值。

max_wal_senders：默认值 10，最小值 3
max_replication_slots：默认值 10，最小值 4
wal_keep_segments：默认值 8，最小值 1
wal_keep_size：默认值 128MB，最小值 16MB
wal_log_hints：on

这些参数会经过校验，以确保其合理性或满足最小值要求。

还有一些其他由 Patroni 控制的 Postgres 参数：

listen_addresses - 从 postgresql.listen 或 PATRONI_POSTGRESQL_LISTEN 环境变量中设置
port - 从 postgresql.listen 或 PATRONI_POSTGRESQL_LISTEN 环境变量中设置
cluster_name - 从 scope 或 PATRONI_SCOPE 环境变量中设置
hot_standby: on

为安全起见，上述列表中的参数会被写入 postgresql.conf，并作为参数列表传递给 postgres，赋予其最高优先级（wal_keep_segments 和 wal_keep_size 除外），甚至高于 ALTER SYSTEM。

还有一些参数如 postgresql.listen、postgresql.data_dir，只能在本地设置，即在 Patroni YAML 配置文件 中或通过 环境变量配置 环境变量设置。在大多数情况下，本地配置会覆盖动态配置。

应用本地或动态配置选项时，会执行以下操作：

节点首先检查是否存在 postgresql.base.conf 文件，或是否设置了 custom_conf 参数。
如果设置了 custom_conf 参数，则使用其指定的文件作为基础配置，忽略 postgresql.base.conf 和 postgresql.conf。
如果未设置 custom_conf 且存在 postgresql.base.conf，则它包含重命名后的"原始"配置，并作为基础配置使用。
如果既无 custom_conf 也无 postgresql.base.conf，原始的 postgresql.conf 会被重命名为 postgresql.base.conf 并作为基础配置使用。
动态选项（除上述例外）会被写入 postgresql.conf，并在 postgresql.conf 中设置 include 指向基础配置（postgresql.base.conf 或 custom_conf 指定的文件）。这样就能在不重新读取配置文件来检查 include 是否存在的情况下，直接应用新选项。
对于 Patroni 管理集群所必需的某些参数，会通过命令行进行覆盖。
如果某个需要重启的选项被更改（需查看 pg_settings 中的上下文以及这些选项的实际值），则会在该节点上设置 pending_restart 标志。该标志在任何重启时都会被清除。

参数按以下顺序应用（运行时参数优先级最高）：

从 postgresql.base.conf 文件（或 custom_conf 文件，如已设置）中加载参数
从 postgresql.conf 文件中加载参数
从 postgresql.auto.conf 文件中加载参数
使用 -o --name=value 传入运行时参数

这种设计允许为所有节点统一配置（2），通过 ALTER SYSTEM 为特定节点配置（3），确保 Patroni 运行所必需的参数得到执行（4），同时为直接管理 postgresql.conf 而不涉及 Patroni 的配置工具预留空间（1）。

影响共享内存的 PostgreSQL 参数

PostgreSQL 有一些参数决定了其使用的共享内存大小：

max_connections
max_prepared_transactions
max_locks_per_transaction
max_wal_senders
max_worker_processes

更改这些参数需要重启 PostgreSQL 才能生效，且从库上的共享内存结构不能小于主库上的对应结构。

如前所述，Patroni 限制只能通过 动态配置 修改这些参数的值，通常操作流程为：

通过 patronictl edit-config（或通过 REST API 的 /config 端点）应用更改
通过 patronictl restart（或通过 REST API 的 /restart 端点）重启节点

注意： 请记住，应通过 patronictl restart 命令或 REST API 的 /restart 端点来重启 PostgreSQL 节点。尝试通过重启 Patroni 守护进程来重启 PostgreSQL（例如执行 systemctl restart patroni），如果重启的是主库，可能会导致集群发生故障转移。

由于这些设置管理共享内存，重启节点时需要格外注意：

若要增大上述任一设置的值：
1. 先重启所有从库
2. 之后再重启主库
若要减小上述任一设置的值：
1. 先重启主库
2. 之后再重启所有从库

注意： 如果在减小上述任一设置值后尝试一次性重启所有节点，Patroni 将忽略该变更并用原始设置值重启从库，从而需要之后再次重启从库。Patroni 这样处理是为了防止从库进入无限崩溃循环，因为如果尝试将上述任一参数设置为低于从库的 pg_controldata 中可见值的值，PostgreSQL 会以 FATAL 消息退出。换句话说，只有当从库的 pg_controldata 与主库关于这些更改保持一致后，才能在从库上减小该设置。

更多信息请参阅 PostgreSQL 管理员概述。

Patroni 配置参数

以下 Patroni 配置选项只能通过动态配置方式修改：

ttl：30
loop_wait：10
retry_timeouts：10
maximum_lag_on_failover：1048576
max_timelines_history：0
check_timeline：false
postgresql.use_slots：true

修改这些选项后，Patroni 会读取存储在 DCS 中的配置相关部分，并更新其运行时值。

Patroni 节点会在每次配置变更时，将 DCS 选项的状态以文件形式写入 Postgres 数据目录中名为 patroni.dynamic.json 的文件。只有主库才被允许在 DCS 中这些选项完全缺失或无效时，从磁盘上的文件恢复这些选项。

配置生成与验证

Patroni 提供了用于生成和验证 Patroni 本地配置文件 的命令行工具。使用 patroni 可执行文件，你可以：

生成示例本地 Patroni 配置；
为本地运行的 PostgreSQL 实例生成 Patroni 配置文件（例如作为 Patroni 集成 的准备步骤）；
验证给定的 Patroni 配置文件。

示例 Patroni 配置

patroni --generate-sample-config [configfile]

说明

以 yaml 格式生成示例 Patroni 配置文件。参数值通过 环境变量配置 定义，如果未设置，则使用 Patroni 的默认值，或对用户需要自行定义的值使用 #FIXME 字符串。

部分默认值根据本地环境确定：

postgresql.listen：当前机器主机名通过 gethostname 调用返回的 IP 地址，以及标准的 5432 端口。
postgresql.connect_address：当前机器主机名通过 gethostname 调用返回的 IP 地址，以及标准的 5432 端口。
postgresql.authentication.rewind：仅当能够从二进制文件中确定 PostgreSQL 版本且版本为 11 或更高时才定义。
restapi.listen：当前机器主机名通过 gethostname 调用返回的 IP 地址，以及标准的 8008 端口。
restapi.connect_address：当前机器主机名通过 gethostname 调用返回的 IP 地址，以及标准的 8008 端口。

参数

configfile - 用于存储结果的配置文件完整路径。如果不提供，结果将输出到 stdout。

为运行中实例生成 Patroni 配置

patroni --generate-config [--dsn DSN] [configfile]

说明

为本地运行的 PostgreSQL 实例以 yaml 格式生成 Patroni 配置。将使用提供的 DSN（优先）或 PostgreSQL 环境变量建立 PostgreSQL 连接。如果未提供密码，则通过提示符输入。

源 Postgres 实例中定义的所有非内部 GUC，无论是通过配置文件、postmaster 命令行还是环境变量设置，都将作为以下 Patroni 配置参数的来源：

scope：cluster_name GUC 的值；
postgresql.listen：listen_addresses 和 port GUC 的值；
postgresql.datadir：data_directory GUC 的值；
postgresql.parameters：archive_command、restore_command、archive_cleanup_command、recovery_end_command、ssl_passphrase_command、hba_file、ident_file、config_file GUC 的值；
bootstrap.dcs：所有其他收集到的 PostgreSQL GUC。

如果 scope、postgresql.listen 或 postgresql.datadir 未能从 Postgres GUC 中设置，则使用相应的 环境变量配置 值。

其他值定义规则：

name：若设置了 PATRONI_NAME 环境变量则使用该值，否则使用当前机器的主机名。
postgresql.bin_dir：从运行中实例收集到的 Postgres 二进制文件路径。
postgresql.connect_address：当前机器主机名通过 gethostname 调用返回的 IP 地址，以及用于实例连接的端口或 port GUC 的值。
postgresql.authentication.superuser：用于实例连接的配置；
postgresql.pg_hba：从源实例的 hba_file 收集的内容。
postgresql.pg_ident：从源实例的 ident_file 收集的内容。
restapi.listen：当前机器主机名通过 gethostname 调用返回的 IP 地址，以及标准的 8008 端口。
restapi.connect_address：当前机器主机名通过 gethostname 调用返回的 IP 地址，以及标准的 8008 端口。

通过 环境变量配置 定义的其他参数也会包含在配置中。

参数

configfile 用于存储结果的配置文件完整路径。如果不提供，结果将输出到 stdout。

dsn 用于从本地 PostgreSQL 实例获取 GUC 值的可选 DSN 字符串。

验证 Patroni 配置

patroni --validate-config [configfile] [--ignore-listen-port | -i]

说明

验证给定的 Patroni 配置，并打印失败检查项的相关信息。

参数

configfile 待检查配置文件的完整路径。如果未提供或文件不存在，将尝试从 PATRONI_CONFIG_VARIABLE 环境变量中读取，如果也未设置，则从 Patroni 环境变量 中读取。

--ignore-listen-port | -i 可选标志，在验证 configfile 时忽略已在使用中的 listen 端口的绑定失败。

--print | -p 可选标志，在成功验证后打印本地配置（包含环境配置覆盖项）。

1 - 动态配置

存储在 DCS 中并应用于整个集群的动态配置参数。

原始页面： https://patroni.readthedocs.io/en/latest/dynamic_configuration.html

动态配置存储在 DCS（分布式配置存储）中，并应用于集群的所有节点。

如需修改动态配置，可使用 patronictl edit-config 工具或 Patroni REST API。

loop_wait：主循环每轮的休眠秒数。默认值：10，最小值：1。
ttl：获取领导者锁的 TTL（秒）。可以理解为触发自动故障转移前的等待时长。默认值：30，最小值：20。
retry_timeout：DCS 和 PostgreSQL 操作的重试超时时间（秒）。若 DCS 或网络故障时长短于此值，Patroni 不会对主库执行降级。默认值：10，最小值：3。

警告

修改 loop_wait、retry_timeout 或 ttl 时，必须遵守以下约束：

loop_wait + 2 * retry_timeout <= ttl

maximum_lag_on_failover：从库参与主库竞选所允许的最大落后字节数。
maximum_lag_on_syncnode：同步从库在被健康的异步从库替代之前，允许落后的最大字节数。若存在多个从库，Patroni 取所有从库中最大的 LSN 作为参考；若只有一个从库，则使用主库当前的 WAL LSN。默认值为 -1；当该值为 0 或更低时，Patroni 不主动替换不健康的同步从库。请将此值设置得足够高，避免在高事务量期间 Patroni 频繁替换同步从库。
max_timelines_history：DCS 中保留的时间线历史条目最大数量。默认值：0。设置为 0 时，保留完整历史记录。
primary_start_timeout：主库在触发故障转移之前，允许从故障中恢复的时间（秒）。默认值为 300 秒。设置为 0 时，一旦检测到崩溃就立即执行故障转移（如果可能）。使用异步复制时，故障转移可能导致事务丢失。主库故障时的最长故障转移时间为 loop_wait + primary_start_timeout + loop_wait；若 primary_start_timeout 为零，则仅为 loop_wait。请根据持久性与可用性的取舍来设置该值。
primary_stop_timeout：Patroni 停止 PostgreSQL 时允许等待的秒数，仅在启用 synchronous_mode 时生效。当该值大于 0 且启用了同步模式时，若停止操作运行时间超过 primary_stop_timeout 所设定的值，Patroni 会向 postmaster 发送 SIGKILL 信号。请根据持久性与可用性的取舍来设置该值。若该参数未设置或设置为 <= 0，则不生效。
synchronous_mode：启用同步复制模式。可选值：off、on、quorum。在此模式下，主库负责管理 synchronous_standby_names，且只有最后已知的领导者或同步从库之一才被允许参与主库竞选。同步模式确保已成功提交的事务在故障转移时不会丢失，代价是当 Patroni 无法保证事务持久性时，写入操作将不可用。详见 复制模式文档。
synchronous_mode_strict：当没有可用的同步从库时，禁止关闭同步复制，阻塞所有客户端对主库的写入。详见 复制模式文档。
synchronous_node_count：启用 synchronous_mode 时，Patroni 使用此参数精确控制同步备库实例的数量，并随成员的加入和离开动态调整 DCS 中的状态及 PostgreSQL 的 synchronous_standby_names 参数。若设置值高于符合条件的节点数，将被自动调低。默认值为 1。
failsafe_mode：启用 DCS 故障安全模式。默认值为 false。
postgresql：
- use_pg_rewind：是否使用 pg_rewind。默认值为 false。注意：集群必须以数据页校验和（initdb 的 --data-checksums 选项）初始化，且/或将 wal_log_hints 设置为 on，否则 pg_rewind 将无法工作。
- use_slots：是否使用复制槽。在 PostgreSQL 9.4+ 上默认值为 true。
- recovery_conf：配置从库时写入 recovery.conf 的附加配置项。PostgreSQL 12 已不再使用 recovery.conf，但仍可继续使用此节，Patroni 会透明地处理。
- parameters：PostgreSQL 配置参数（GUC），格式为 {max_connections: 100, wal_level: "replica", max_wal_senders: 10, wal_log_hints: "on"}。其中许多参数是复制正常工作的必要条件。
- pg_hba：Patroni 用于生成 pg_hba.conf 的规则列表。若 PostgreSQL 参数 hba_file 被设置为非默认值，Patroni 将忽略此参数。
  - - host all all 0.0.0.0/0 md5
  - - host replication replicator 127.0.0.1/32 md5：复制所必需的一行配置。
- pg_ident：Patroni 用于生成 pg_ident.conf 的规则列表。若 PostgreSQL 参数 ident_file 被设置为非默认值，Patroni 将忽略此参数。
  - - mapname1 systemname1 pguser1
  - - mapname1 systemname2 pguser2
standby_cluster：若定义了此节，表示要引导一个备用集群。
- host：远端节点的地址。
- port：远端节点的端口。
- primary_slot_name：用于复制的远端节点槽名。此参数可选，默认值由实例名称派生（参见函数 slot_name_from_member_name）。
- create_replica_methods：从远端主库引导备用领导者所用方法的有序列表，可与 postgresql_settings 中定义的列表不同。
- restore_command：将 WAL 记录从远端主库恢复到备用集群节点的命令，可与 postgresql_settings 中定义的不同。
- archive_cleanup_command：备用领导者的归档清理命令。
- recovery_min_apply_delay：备用领导者实际应用 WAL 记录前的等待时长。
member_slots_ttl：从库关闭后，其物理复制槽的保留时间。默认值：30min。若希望保留旧行为（成员键从 DCS 过期后立即删除槽），可将其设置为 0。此功能仅在 PostgreSQL 11 及以上版本中有效。
slots：定义永久复制槽。这些复制槽在主从切换/故障转移期间会被保留，不存在的永久槽由 Patroni 负责创建。从 PostgreSQL 11 起，永久物理槽在所有节点上创建，其位置每 loop_wait 秒推进一次。对于 PostgreSQL 11 以下版本，永久物理复制槽仅在当前主库上维护。逻辑槽通过重启从主库复制到从库，此后其位置每 loop_wait 秒推进一次（如有必要）。逻辑槽文件的复制通过 libpq 连接完成，使用 rewind 或超级用户凭据（参见 postgresql.authentication 节）。从库上的逻辑槽位置可能略落后于原主库，因此应用程序应做好在故障转移后接收到重复消息的准备，最简便的处理方式是追踪 confirmed_flush_lsn。启用永久复制槽需要将 postgresql.use_slots 设置为 true。若定义了永久逻辑复制槽，Patroni 将自动启用 hot_standby_feedback。由于逻辑复制槽的故障转移在 PostgreSQL 9.6 及更低版本上不安全，且 PostgreSQL 10 缺少一些重要函数，该功能仅支持 PostgreSQL 11+。
- my_slot_name：永久复制槽的名称。若槽名称与当前节点名称相同，该槽不会在此节点上创建。若添加的永久物理复制槽名称与某个 Patroni 成员名称相同，Patroni 将确保该槽不被删除，即使对应成员变得无响应（正常情况下这会导致 Patroni 删除该槽）。这在某些场景下很有用，例如希望成员所用的复制槽在临时故障期间持续存在，或将现有成员导入新的 Patroni 集群（详见 将独立实例转换为 Patroni 集群）。但运维人员应注意，当该槽不再需要时，须及时清除 DCS 中的名称冲突配置，否则会影响 Patroni 的正常运行。
  - type：槽类型，可为 physical 或 logical。逻辑槽需额外定义 database 和 plugin；物理槽可选择定义 cluster_type。
  - database：逻辑槽应创建所在的数据库名称。
  - plugin：逻辑槽使用的插件名称。
  - cluster_type：槽仅应创建于其上的集群类型（primary 或 standby），否则该槽不会被创建，或已存在的槽将被删除。
ignore_slots：需要 Patroni 忽略的复制槽属性集合列表。当某些复制槽由 Patroni 以外的工具管理时，此配置非常有用。任何属性子集匹配都会导致该槽被忽略。
- name：复制槽的名称。
- type：槽类型，可为 physical 或 logical。逻辑槽可额外定义 database 和/或 plugin。
- database：数据库名称（匹配 logical 槽时使用）。
- plugin：逻辑解码插件（匹配 logical 槽时使用）。

注意：slots 是哈希映射，而 ignore_slots 是数组。示例如下：

slots:
  permanent_logical_slot_name:
    type: logical
    database: my_db
    plugin: test_decoding
  permanent_physical_slot_name:
    type: physical
  ...
ignore_slots:
  - name: ignored_logical_slot_name
    type: logical
    database: my_db
    plugin: test_decoding
  - name: ignored_physical_slot_name
    type: physical
  ...

注意：当运行 PostgreSQL v11 或更新版本时，Patroni 在所有可能成为领导者的节点上维护物理复制槽，以便从库在其他节点可能需要时保留 WAL 段。若节点缺席且其在 DCS 中的成员键过期，对应的复制槽将在 member_slots_ttl（默认值为 30min）后被删除。可按需调整保留时间。另外，若集群拓扑固定（节点数量和名称不变），可为每个节点配置与节点名对应的永久物理复制槽，避免从库临时下线时槽被删除、WAL 文件被回收：

slots:
  node_name1:
    type: physical
  node_name2:
    type: physical
  node_name3:
    type: physical
  ...

警告

永久复制槽仅从 primary/standby_leader 同步到从库，因此应用程序应仅在领导者节点上使用它们。在从库上使用永久复制槽会导致集群中所有其他节点的 pg_wal 无限增长。例外情况是与 Patroni 成员名称匹配的物理槽（由 Patroni 创建和维护），这些槽会在所有节点间同步，因为它们用于节点间的复制。

警告

在备库上设置 nostream 标签会禁用该节点自身及其所有级联从库上永久逻辑复制槽的复制和同步。

2 - YAML 配置参数

Patroni YAML 配置选项与各配置节的完整参考。

原始页面： https://patroni.readthedocs.io/en/latest/yaml_configuration.html

全局/通用

name：主机名称，在集群中必须唯一。
namespace：Patroni 在配置存储中保存集群信息的路径，默认值为 /service。
scope：集群名称。

日志

type：设置日志格式，可选 plain 或 json。使用 json 格式时，必须安装 jsonlogger。默认值为 plain。
level：设置通用日志级别，默认值为 INFO（参见 Python logging 文档）。
traceback_level：设置显示调用栈跟踪的日志级别，默认值为 ERROR。若希望仅在 log.level=DEBUG 时才输出调用栈，可将其设为 DEBUG。
format：设置日志格式化字符串。若日志类型为 plain，格式应为字符串，可用属性参见 LogRecord 属性。若日志类型为 json，格式可以是字符串，也可以是列表——列表中每项对应一个 LogRecord 属性名，只需填写字段名，无需加 %( 和 )。若希望以不同键名输出某个日志字段，可使用字典：键为日志字段名，值为期望在日志中显示的名称。默认值为 %(asctime)s %(levelname)s: %(message)s。
dateformat：设置日期时间格式化字符串（参见 formatTime() 文档）。
static_fields：向日志中添加额外字段，仅在日志类型设为 json 时可用。
max_queue_size：Patroni 采用两阶段日志记录——日志记录先写入内存队列，由独立线程从队列取出后写入 stderr 或文件。内部队列默认最多保存 1000 条记录，足以覆盖过去约 1 小时 20 分钟的日志。
dir：应用日志的写入目录，该目录必须存在且对运行 Patroni 的用户可写。设置此值后，默认保留 4 个 25MB 的日志文件，可通过 file_num 和 file_size（见下文）调整保留策略。
mode：日志文件的权限（例如 0644）。若未指定，权限将根据当前 umask 值设置。
file_num：保留的应用日志文件数量。
file_size：触发日志滚动的 patroni.log 文件大小（单位：字节）。
loggers：本节允许按 Python 模块重新定义日志级别：
- patroni.postmaster: WARNING
- urllib3: DEBUG
deduplicate_heartbeat_logs：若设为 true，连续相同的心跳日志将不再重复输出，默认值为 false。

警告

HA 循环的执行时间是诊断因资源耗尽等问题导致故障转移的重要信息。当 deduplicate_heartbeat_logs 设为 true 时，HA 循环的执行日志将不再生成（除非主库发生变更），因此这部分潜在有用的信息将无法从日志中获取。

以下是将 Patroni 配置为 JSON 格式日志的配置示例：

log:
   type: json
   format:
      - message
      - module
      - asctime: '@timestamp'
      - levelname: level
   static_fields:
      app: patroni

引导配置

说明

一旦 Patroni 完成集群的首次初始化并将配置写入 DCS，此后对 YAML 配置文件中 bootstrap.dcs 节所做的任何修改将不再生效！如需更改，请使用 patronictl edit-config 或 Patroni REST API。

bootstrap：
- dcs：本节内容将在新集群初始化完成后写入配置存储的 /<namespace>/<scope>/config，作为集群的全局动态配置。可将 动态配置参数 中描述的任意参数放在 bootstrap.dcs 下，Patroni 完成集群引导后会将本节写入该路径。
- method：用于引导本集群的自定义脚本。
  详见 自定义引导方法文档。指定 initdb 时将回退到默认的 initdb 命令；配置文件中不存在 method 参数时同样触发 initdb。
- initdb：（可选）传递给 initdb 的选项列表。
  - - data-checksums：在 PostgreSQL 9.3 上使用 pg_rewind 时必须启用。
  - - encoding: UTF8：新数据库的默认编码。
  - - locale: UTF8：新数据库的默认区域设置。
- post_bootstrap 或 post_init：集群初始化完成后执行的附加脚本。脚本接收一个以集群超级用户为用户名的连接字符串 URL，pgpass 文件路径通过 PGPASSFILE 环境变量传入。

Citus

启用 Patroni 与 Citus 的集成。配置后，Patroni 将负责在协调节点上注册 Citus 工作节点。关于 Citus 支持的更多信息，参见此处。

group：Citus 组 ID，整数类型。协调节点使用 0，工作节点使用 1、2 等。
database：应创建 citus 扩展的数据库，协调节点和所有工作节点必须相同，目前仅支持一个数据库。

Consul

大多数参数为可选，但必须指定 host 或 url 之一。

host：Consul 本地代理的 host:port。
url：Consul 本地代理的 URL，格式为 http(s)://host:port。
port：（可选）Consul 端口。
scheme：（可选）http 或 https，默认为 http。
token：（可选）ACL 令牌。
verify：（可选）是否验证 HTTPS 请求的 SSL 证书。
cacert：（可选）CA 证书文件，设置后将启用验证。
cert：（可选）客户端证书文件。
key：（可选）客户端密钥文件，若密钥已包含在 cert 中则可为空。
dc：（可选）通信的数据中心，默认使用当前主机所在的数据中心。
consistency：（可选）选择 Consul 一致性模式，可选值为 default、consistent 或 stale（详见 Consul API 参考）。
checks：（可选）用于会话的 Consul 健康检查列表，默认为空列表。
register_service：（可选）是否注册以 scope 参数命名的服务，并根据节点角色标记为 master、primary、replica 或 standby-leader，默认为 false。
service_tags：（可选）除角色标签（primary/replica/standby-leader）外，要添加到 Consul 服务的额外静态标签，默认为空列表。
service_check_interval：（可选）对已注册 URL 执行健康检查的频率，默认为 5s。
service_check_tls_server_name：（可选）通过 TLS 连接时覆盖 SNI 主机名，参见 Consul agent check API 参考。

token 需要具备以下 ACL 权限：

service_prefix "${scope}" {
    policy = "write"
}
key_prefix "${namespace}/${scope}" {
    policy = "write"
}
session_prefix "" {
    policy = "write"
}

Etcd

大多数参数为可选，但必须指定 host、hosts、url、proxy 或 srv 之一。

host：etcd 端点的 host:port。
hosts：etcd 端点列表，格式为 host1:port1,host2:port2 等，可以是逗号分隔的字符串，也可以是 YAML 列表。
use_proxies：若设为 true，Patroni 将把 hosts 视为代理列表，不再对 etcd 集群进行拓扑发现。
url：etcd 的 URL。
proxy：etcd 的代理 URL，若通过代理连接 etcd，请使用此参数而非 url。
srv：用于集群自动发现的 SRV 记录搜索域。Patroni 将按以下顺序查询指定域的 SRV 服务名，找到第一个有效结果即止：_etcd-client-ssl、_etcd-client、_etcd-ssl、_etcd、_etcd-server-ssl、_etcd-server。若查到 _etcd-server-ssl 或 _etcd-server 的 SRV 记录，将通过 ETCD peer 协议查询可用成员；否则直接使用 SRV 记录中的主机。
srv_suffix：配置用于自动发现时 SRV 查询名称的后缀，可在同一域下区分多个 etcd 集群，仅与 srv 联用。例如，设置 srv_suffix: foo 且 srv: example.org 时，将发起 _etcd-client-ssl-foo._tcp.example.com 等 DNS SRV 查询（所有可能的 ETCD SRV 服务名均以相同方式处理）。
protocol：（可选）http 或 https，未指定时默认使用 http。若已指定 url 或 proxy，则从中获取协议。
username：（可选）etcd 认证的用户名。
password：（可选）etcd 认证的密码。
cacert：（可选）CA 证书文件，设置后将启用验证。
cert：（可选）客户端证书文件。
key：（可选）客户端密钥文件，若密钥已包含在 cert 中则可为空。

Etcdv3

若要让 Patroni 通过协议版本 3 与 Etcd 集群通信，在 Patroni 配置文件中使用 etcd3 节即可，所有配置参数与 etcd 相同。

警告

使用协议版本 2 创建的键在版本 3 中不可见，反之亦然，因此不能仅通过更新 Patroni 配置文件来从 etcd 切换到 etcd3。此外，Patroni 使用 Etcd 的 gRPC-gateway（代理）与 V3 API 通信，这意味着不支持 TLS 通用名称认证。

ZooKeeper

hosts：ZooKeeper 集群成员列表，格式为 \['host1:port1', 'host2:port2', 'etc...'\]。
use_ssl：（可选）是否使用 SSL，默认为 false。若为 false，所有 SSL 相关参数将被忽略。
cacert：（可选）CA 证书文件，设置后将启用验证。
cert：（可选）客户端证书文件。
key：（可选）客户端密钥文件。
key_password：（可选）客户端密钥密码。
verify：（可选）是否验证证书，默认为 true。
set_acls：（可选）若设置，Kazoo 将对其创建的每个 ZNode 应用默认 ACL。ACL 以字典形式指定，键为完整主体（可选带模式前缀），值为权限列表。支持 x509 模式（默认）或其他 ZooKeeper 支持的模式（如 digest）。权限可以是 CREATE、READ、WRITE、DELETE、ADMIN 或 ALL 之一或多个。示例：set_acls: {CN=principal1: [CREATE, READ], digest:principal2:+pjROuBuuwNNSujKyH8dGcEnFPQ=: [ALL]}。
auth_data：（可选）连接使用的认证凭据，应以字典形式指定，键为 scheme，值为 credential，默认为空字典。

说明

需要安装 kazoo>=2.6.0 以支持 SSL。

Exhibitor

hosts：Exhibitor（ZooKeeper）节点的初始列表，格式为 ‘host1,host2,etc…’，当 Exhibitor（ZooKeeper）集群拓扑变化时自动更新。
poll_interval：从 Exhibitor 更新 ZooKeeper 和 Exhibitor 节点列表的频率。
port：Exhibitor 端口。

Kubernetes

bypass_api_service：（可选）与 Kubernetes API 通信时，Patroni 通常依赖 kubernetes 服务——该服务地址通过 KUBERNETES_SERVICE_HOST 环境变量暴露给 Pod。若将 bypass_api_service 设为 true，Patroni 将解析该服务背后的 API 节点列表并直接连接。
namespace：（可选）Patroni Pod 运行所在的 Kubernetes namespace，默认值为 default。
labels：格式为 {label1: value1, label2: value2} 的标签，用于查找与当前集群关联的已有对象（Pod 及 Endpoints 或 ConfigMaps），Patroni 也会将这些标签设置到其创建的每个对象（Endpoint 或 ConfigMap）上。
scope_label：（可选）包含集群名称的标签名，默认值为 cluster-name。
bootstrap_labels：（可选）格式为 {label1: value1, label2: value2} 的标签，当 Patroni Pod 处于 initializing new cluster、running custom bootstrap script、starting after custom bootstrap 或 creating replica 状态时，这些标签将被分配给该 Pod。
role_label：（可选）包含角色（primary、replica 或其他自定义值）的标签名，Patroni 会在其运行的 Pod 上设置此标签，默认值为 role。
leader_label_value：（可选）Postgres 角色为 primary 时 Pod 标签的值，默认值为 primary。
follower_label_value：（可选）Postgres 角色为 replica 时 Pod 标签的值，默认值为 replica。
standby_leader_label_value：（可选）Postgres 角色为 standby_leader 时 Pod 标签的值，默认值为 primary。
tmp_role_label：（可选）包含临时角色（primary 或 replica）的标签名，此标签的值始终使用对应角色的默认值，仅在必要时设置。
use_endpoints：（可选）若设为 true，Patroni 将使用 Endpoints 而非 ConfigMaps 进行主库选举和集群状态保存。
pod_ip：（可选）运行 Patroni 的 Pod 的 IP 地址。启用 use_endpoints 时必须提供，用于在该 Pod 上的 PostgreSQL 被提升时填充领导者 Endpoint 的子集。
ports：（可选）若 Service 对象为端口指定了名称，Endpoint 对象中也必须出现相同名称，否则服务将无法工作。例如，若服务定义为 {Kind: Service, spec: {ports: [{name: postgresql, port: 5432, targetPort: 5432}]}}，则须设置 kubernetes.ports: [{"name": "postgresql", "port": 5432}]，Patroni 将用它更新领导者 Endpoint 的子集。此参数仅在 kubernetes.use_endpoints 已设置时生效。
cacert：（可选）用于验证 Kubernetes API SSL 证书的受信任 CA 证书包文件，若未提供，Patroni 将使用 ServiceAccount secret 中的值。
retriable_http_codes：（可选）需要重试的 K8s API HTTP 状态码列表。默认情况下，Patroni 在收到 500、503、504 响应，或 K8s API 响应包含 retry-after HTTP 头时自动重试。

Raft（已弃用）

self_addr：用于 Raft 连接监听的 ip:port，self_addr 必须可从集群其他节点访问。若未设置，该节点将不参与共识。
bind_addr：（可选）用于 Raft 连接监听的 ip:port，若未指定则使用 self_addr。
partner_addrs：集群中其他 Patroni 节点的列表，格式为
\['ip1:port', 'ip2:port', 'etc...'\]
。
data_dir：存储 Raft 日志和快照的目录，若未指定则使用当前工作目录。
password：（可选）使用指定密码加密 Raft 流量，需要 cryptography Python 模块。
关于 Raft 实现的简短 FAQ：
- 问：如何列出所有参与共识的节点？
  答：syncobj_admin -conn host:port -status，其中 host:port 为集群某个节点的地址。
- 问：某个参与共识的节点已下线，且我无法为其他节点复用相同 IP，如何将其从共识中移除？
  答：syncobj_admin -conn host:port -remove host2:port2，其中 host2:port2 为要移除的节点地址。
- 问：从哪里获取 syncobj_admin 工具？
  答：它随 pysyncobj 模块（Python RAFT 实现，Patroni 的依赖项）一同安装。
- 问：是否可以在不加入共识的情况下运行 Patroni 节点？
  答：可以，只需在 Patroni 配置中注释掉或删除 raft.self_addr。
- 问：是否可以只在两个节点上运行 Patroni 和 PostgreSQL？
  答：可以，在第三个节点上运行 patroni_raft_controller（不含 Patroni 和 PostgreSQL）。这种部署方式下，临时失去一个节点不会影响主库。

PostgreSQL

postgresql：
- authentication：
  - superuser：
    - username：超级用户名，在初始化（initdb）时设置，后续由 Patroni 用于连接 PostgreSQL。
    - password：超级用户密码，在初始化（initdb）时设置。
    - sslmode：（可选）映射到 sslmode 连接参数，允许客户端指定与服务器的 TLS 协商模式，默认模式为 prefer。
    - sslkey：（可选）映射到 sslkey 连接参数，指定与客户端证书配套的私钥位置。
    - sslpassword：（可选）映射到 sslpassword 连接参数，指定 sslkey 中私钥的密码。
    - sslcert：（可选）映射到 sslcert 连接参数，指定客户端证书的位置。
    - sslrootcert：（可选）映射到 sslrootcert 连接参数，指定包含一个或多个受信任 CA 证书的文件位置，客户端将用其验证服务器证书。
    - sslcrl：（可选）映射到 sslcrl 连接参数，指定证书吊销列表文件的位置，客户端将拒绝连接证书出现在该列表中的服务器。
    - sslcrldir：（可选）映射到 sslcrldir 连接参数，指定包含证书吊销列表文件的目录位置，客户端将拒绝连接证书出现在该列表中的服务器。
    - sslnegotiation：（可选）映射到 sslnegotiation 连接参数，控制在使用 SSL 时与服务器协商 SSL 加密的方式。
    - gssencmode：（可选）映射到 gssencmode 连接参数，决定是否以及以何种优先级与服务器建立安全的 GSS TCP/IP 连接。
    - channel_binding：（可选）映射到 channel_binding 连接参数，控制客户端对通道绑定的使用。
  - replication：
    - username：复制用户名，在初始化时创建，从库通过流复制连接复制源时使用该用户。
    - password：复制用户密码，在初始化时创建。
    - sslmode：（可选）映射到 sslmode 连接参数，默认模式为 prefer。
    - sslkey：（可选）映射到 sslkey 连接参数，指定与客户端证书配套的私钥位置。
    - sslpassword：（可选）映射到 sslpassword 连接参数，指定 sslkey 中私钥的密码。
    - sslcert：（可选）映射到 sslcert 连接参数，指定客户端证书的位置。
    - sslrootcert：（可选）映射到 sslrootcert 连接参数，指定包含一个或多个受信任 CA 证书的文件位置。
    - sslcrl：（可选）映射到 sslcrl 连接参数，指定证书吊销列表文件的位置。
    - sslcrldir：（可选）映射到 sslcrldir 连接参数，指定包含证书吊销列表文件的目录位置。
    - sslnegotiation：（可选）映射到 sslnegotiation 连接参数，控制在使用 SSL 时协商 SSL 加密的方式。
    - gssencmode：（可选）映射到 gssencmode 连接参数，决定是否以及以何种优先级建立安全的 GSS TCP/IP 连接。
    - channel_binding：（可选）映射到 channel_binding 连接参数，控制客户端对通道绑定的使用。
  - rewind：
    - username：（可选）用于 pg_rewind 的用户名，在初始化 PostgreSQL 11+ 时创建，并授予所有必要的权限。
    - password：（可选）用于 pg_rewind 的用户密码，在初始化时创建。
    - sslmode：（可选）映射到 sslmode 连接参数，默认模式为 prefer。
    - sslkey：（可选）映射到 sslkey 连接参数，指定与客户端证书配套的私钥位置。
    - sslpassword：（可选）映射到 sslpassword 连接参数，指定 sslkey 中私钥的密码。
    - sslcert：（可选）映射到 sslcert 连接参数，指定客户端证书的位置。
    - sslrootcert：（可选）映射到 sslrootcert 连接参数，指定包含一个或多个受信任 CA 证书的文件位置。
    - sslcrl：（可选）映射到 sslcrl 连接参数，指定证书吊销列表文件的位置。
    - sslcrldir：（可选）映射到 sslcrldir 连接参数，指定包含证书吊销列表文件的目录位置。
    - sslnegotiation：（可选）映射到 sslnegotiation 连接参数，控制在使用 SSL 时协商 SSL 加密的方式。
    - gssencmode：（可选）映射到 gssencmode 连接参数，决定是否以及以何种优先级建立安全的 GSS TCP/IP 连接。
    - channel_binding：（可选）映射到 channel_binding 连接参数，控制客户端对通道绑定的使用。
- callbacks：在特定操作时运行的回调脚本，Patroni 会将操作名称、角色和集群名称作为参数传入（可参考 scripts/aws.py 作为示例）。
  - on_reload：触发配置重载时运行此脚本。
  - on_restart：Postgres 重启时（不改变角色）运行此脚本。
  - on_role_change：Postgres 被提升或降级时运行此脚本。
  - on_start：Postgres 启动时运行此脚本。
  - on_stop：Postgres 停止时运行此脚本。
- connect_address：其他节点和应用程序访问 Postgres 所用的 IP 地址和端口。
- proxy_address：与 PostgreSQL 并行运行的连接池（如 pgbouncer）的可访问 IP 地址和端口，该值以 proxy_url 的形式写入 DCS 成员键，可用于服务发现。
- create_replica_methods：创建新从库所用方法的有序列表，basebackup 为默认方法，其余方法视为脚本，每个脚本需作为独立配置节进行配置。详见 自定义从库创建方法文档。
- data_dir：Postgres 数据目录的位置，可以是 已有目录 或由 Patroni 初始化的目录。
- config_dir：Postgres 配置目录的位置，默认为数据目录，必须对 Patroni 可写。
- bin_dir：（可选）PostgreSQL 可执行文件（pg_ctl、initdb、pg_controldata、pg_basebackup、postgres、pg_isready、pg_rewind）的路径。若未提供或为空字符串，将使用 PATH 环境变量查找可执行文件。
- bin_name：（可选）若使用自定义 Postgres 发行版，可用此选项覆盖 Postgres 二进制文件名：
  - pg_ctl：（可选）pg_ctl 的自定义名称。
  - initdb：（可选）initdb 的自定义名称。
  - pgcontroldata：（可选）pg_controldata 的自定义名称。
  - pg_basebackup：（可选）pg_basebackup 的自定义名称。
  - postgres：（可选）postgres 的自定义名称。
  - pg_isready：（可选）pg_isready 的自定义名称。
  - pg_rewind：（可选）pg_rewind 的自定义名称。
- listen：PostgreSQL 监听的 IP 地址和端口，使用流复制时必须可从集群其他节点访问。支持多个逗号分隔的地址，端口附加在最后一个地址之后，例如 listen: 127.0.0.1,127.0.0.2:5432。Patroni 将使用列表中的第一个地址建立到 PostgreSQL 节点的本地连接。
- use_unix_socket：指定 Patroni 优先使用 Unix 套接字连接 PostgreSQL，默认值为 false。若已定义 unix_socket_directories，Patroni 将从中选取第一个合适的路径用于连接，无合适值时回退到 TCP。若 postgresql.parameters 中未指定 unix_socket_directories，Patroni 将假设使用默认值并在连接参数中省略 host。
- use_unix_socket_repl：指定 Patroni 优先使用 Unix 套接字建立复制用户连接，默认值为 false，行为与 use_unix_socket 相同。
- pgpass：.pgpass 密码文件的路径。Patroni 在执行 pg_basebackup、post_init 脚本及其他某些情况下会创建此文件，该路径必须对 Patroni 可写。
- recovery_conf：配置从库时写入 recovery.conf 的附加配置项。
- custom_conf：可选的自定义 postgresql.conf 文件路径，将代替 postgresql.base.conf 使用。该文件必须存在于所有集群节点上且对 PostgreSQL 可读，实际的 postgresql.conf 将从其所在位置包含该文件。注意 Patroni 不会监控此文件的变更，也不会备份它，但其中的设置仍可被 Patroni 自身的配置机制覆盖，详见 动态配置。
- parameters：Postgres 的配置参数（GUC），格式为 {ssl: "on", ssl_cert_file: "cert_file"}。
- pg_hba：Patroni 用于生成 pg_hba.conf 的行列表。若 PostgreSQL 的 hba_file 参数设为非默认值，Patroni 将忽略此参数。与 动态配置 配合使用，可简化 pg_hba.conf 的管理。
  - - host all all 0.0.0.0/0 md5
  - - host replication replicator 127.0.0.1/32 md5：复制所需的规则行。
- pg_ident：Patroni 用于生成 pg_ident.conf 的行列表。若 PostgreSQL 的 ident_file 参数设为非默认值，Patroni 将忽略此参数。与 动态配置 配合使用，可简化 pg_ident.conf 的管理。
  - - mapname1 systemname1 pguser1
  - - mapname1 systemname2 pguser2
- pg_ctl_timeout：pg_ctl 执行 start、stop 或 restart 时的等待时长，默认值为 60 秒。
- use_pg_rewind：当旧主库以从库身份重新加入集群时，尝试对其执行 pg_rewind。需要集群在初始化时启用了 data page checksums（initdb 的 --data-checksums 选项）或将 wal_log_hints 设为 on，否则 pg_rewind 无法正常工作。
- rewind：（可选）传递给 pg_rewind 的自定义选项，可以是字符串列表和/或单键值字典。以下选项不允许使用：target-pgdata、source-pgdata、source-server、write-recovery-conf、dry-run、restore-target-wal、config-file、no-ensure-shutdown、version 和 help。使用示例：
```
postgresql:
  rewind:
    - debug
    - progress
    - sync-method: fsync
```
- remove_data_directory_on_rewind_failure：启用后，若 pg_rewind 失败，Patroni 将删除 PostgreSQL 数据目录并重新创建从库；否则将尝试跟随新主库，默认值为 false。
- remove_data_directory_on_diverged_timelines：若 Patroni 检测到时间线出现分歧，且旧主库无法从新主库开始流复制，则删除 PostgreSQL 数据目录并重新创建从库。此选项在无法使用 pg_rewind 时很有用。在 PostgreSQL v10 及更早版本上进行时间线分歧检查时，Patroni 将尝试使用复制凭据连接 “postgres” 数据库，因此 pg_hba.conf 中必须允许此类访问。默认值为 false。
- replica_method：对于 create_replica_methods 中除 basebackup 外的每种方法，需添加同名配置节。该节至少须包含 command 字段，指向实际执行脚本的完整路径，其余配置参数将以 parameter=value 的形式传递给脚本。
- pre_promote：故障转移期间在获取领导者锁之后、提升从库之前执行的隔离脚本。若脚本以非零退出码退出，Patroni 将放弃提升并从 DCS 中移除领导者键。
- before_stop：在停止 PostgreSQL 之前立即执行的脚本。与回调不同，此脚本同步运行，会阻塞关闭流程直到脚本完成。脚本的返回码不影响后续关闭操作的执行。

REST API

restapi：
- connect_address：访问 Patroni REST API 所用的 IP 地址（或主机名）和端口。集群中所有成员必须能够访问此地址，因此除非 Patroni 仅用于本地演示，否则不能使用回环地址（如 “localhost” 或 “127.0.0.1”）。该地址可作为 HTTP 健康检查端点（详见下文 REST API 的 “listen” 参数），也用于用户查询（直接访问或通过 REST API）以及集群成员在主库选举期间的健康检查（例如，判断当前主库是否仍在运行，或是否存在 WAL 位置超前于查询节点的节点）。connect_address 写入 DCS 的成员键，从而可通过成员名称解析出其 REST API 连接地址。
- listen：Patroni 监听 REST API 请求的 IP 地址（或主机名）和端口，同样提供上述健康检查与集群节点间通信功能，也可为 HAProxy 等支持 HTTP OPTIONS 或 GET 检查的负载均衡器提供健康检查端点。
- authentication：（可选）
  - username：用于保护不安全 REST API 端点的 Basic-auth 用户名。
  - password：用于保护不安全 REST API 端点的 Basic-auth 密码。
- certfile：（可选）PEM 格式的证书文件，若未指定或留空，API 服务器将在无 SSL 的情况下工作。
- keyfile：（可选）PEM 格式的私钥文件。
- keyfile_password：（可选）用于解密 keyfile 的密码。
- cafile：（可选）包含受信任 CA 证书的 CA_BUNDLE 文件，用于验证客户端证书。
- ciphers：（可选）允许的密码套件（例如 “ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:!SSLv1:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1”）。
- verify_client：（可选）none（默认）、optional 或 required。none 时不检查客户端证书；required 时所有 REST API 调用均需提供客户端证书；optional 时仅对不安全的 REST API 端点要求客户端证书。使用 required 时，证书签名验证通过即视为认证成功；使用 optional 时，仅对 PUT、POST、PATCH 和 DELETE 请求检查客户端证书。
- allowlist：（可选）允许调用不安全 REST API 端点的主机列表，每个元素可以是主机名、IP 地址或 CIDR 格式的网络地址，默认允许所有来源。一旦设置了 allowlist 或 allowlist_include_members，不在列表中的请求将被拒绝。
- allowlist_include_members：（可选）若设为 true，DCS 中已注册的其他集群成员（IP 地址或主机名取自成员的 api_url）也被允许访问不安全 REST API 端点。注意操作系统可能为出站连接使用不同的 IP 地址。
- http_extra_headers：（可选）允许 REST API 服务器在 HTTP 响应中传递额外信息的 HTTP 头。
- https_extra_headers：（可选）启用 TLS 时，允许 REST API 服务器在 HTTP 响应中传递额外信息的 HTTPS 头，同时也会传递 http_extra_headers 中设置的额外信息。
- request_queue_size：（可选）Patroni REST API 使用的 TCP 套接字请求队列大小，队列满后新请求将收到 “Connection denied” 错误，默认值为 5。
- server_tokens：（可选）配置 Server HTTP 头的值：
  - Minimal：头部仅包含 Patroni 版本，例如 Patroni/4.0.0。
  - ProductOnly：头部仅包含产品名称，例如 Patroni。
  - Original（默认）：头部显示原始行为，包含 BaseHTTP 和 Python 版本，例如 BaseHTTP/0.6 Python/3.12.3。

以下是 http_extra_headers 和 https_extra_headers 的配置示例：

restapi:
  listen: <listen>
  connect_address: <connect_address>
  authentication:
    username: <username>
    password: <password>
  http_extra_headers:
    'X-Frame-Options': 'SAMEORIGIN'
    'X-XSS-Protection': '1; mode=block'
    'X-Content-Type-Options': 'nosniff'
  cafile: <ca file>
  certfile: <cert>
  keyfile: <key>
  https_extra_headers:
    'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'

Warning

restapi.connect_address 必须可从该 Patroni 集群的所有节点访问。Patroni 在主库竞选期间会在内部使用它来查找复制延迟最小的节点。
若启用了客户端证书验证（restapi.verify_client 设为 required），还必须在 ctl.certfile、ctl.keyfile、ctl.keyfile_password 中提供有效的客户端证书，否则 Patroni 将无法正常工作。

CTL

ctl：（可选）
- authentication：
  - username：访问受保护 REST API 端点的 Basic-auth 用户名。若未提供，patronictl 将使用 REST API 的 “username” 参数值。
  - password：访问受保护 REST API 端点的 Basic-auth 密码。若未提供，patronictl 将使用 REST API 的 “password” 参数值。
- insecure：允许在不验证 SSL 证书的情况下连接 REST API。
- cacert：用于验证 REST API SSL 证书的 CA_BUNDLE 文件或受信任 CA 证书目录，若未提供，patronictl 将使用 REST API 的 “cafile” 参数值。
- certfile：PEM 格式的客户端证书文件。
- keyfile：PEM 格式的客户端私钥文件。
- keyfile_password：用于解密客户端 keyfile 的密码。

Watchdog

mode：off、automatic 或 required。off 时禁用 watchdog；automatic 时如有可用的 watchdog 则启用，否则忽略；required 时节点必须在 watchdog 成功启用后才能成为主库。
device：watchdog 设备路径，默认为 /dev/watchdog。
safety_margin：watchdog 触发与领导者键过期之间的安全边距（秒）。

标签（Tags）

clonefrom：true 或 false。若设为 true，其他节点在引导时可能优先从此节点克隆（pg_basebackup）。若多个节点的 clonefrom 均为 true，将随机选择引导源节点，默认值为 false。
noloadbalance：true 或 false。若设为 true，该节点在 GET /replica REST API 健康检查时将返回 HTTP 503，从而被排除在负载均衡之外，默认为 false。
replicatefrom：另一个从库的名称，用于支持级联复制。
nosync：true 或 false。若设为 true，该节点永远不会被选为同步从库。
sync_priority：整数，控制 synchronous_mode 设为 on 时此节点在同步从库选择中的优先级，数值越高越优先。若 sync_priority 为 0 或负数，该节点不会被写入 synchronous_standby_names 参数（效果类似于 nosync: true）。注意此参数的含义与 pg_stat_replication 视图中报告的 sync_priority 值相反。
nofailover：true 或 false，控制此节点是否允许参与主库竞选，默认为 false，即此节点可以参与主库竞选。
failover_priority：整数，控制此节点在故障转移时的优先级。在接收/回放相同 WAL 量的前提下，优先级高的节点优先被选为新主库；但无论优先级高低，接收/回放 LSN 更大的节点始终优先。若 failover_priority 为 0 或负数，该节点不允许参与主库竞选（效果类似于 nofailover: true）。已知限制：failover_priority 目前不支持 基于法定人数的同步复制。
nostream：true 或 false。若设为 true，该节点将不使用复制协议流式传输 WAL，而依赖归档恢复（需配置 restore_command）和 pg_wal/pg_xlog 轮询。同时将禁用该节点本身及其所有级联从库上永久逻辑复制槽的复制与同步，在主库上设置此标签无效。

警告

nofailover 和 failover_priority 只能提供其中一个。nofailover: true 等同于 failover_priority: 0，而 nofailover: false 将给予节点优先级 1。

除这些预定义标签外，还可以添加自定义标签：

key1：true
key2：false
key3：1.4
key4："RandomString"

标签在 REST API 和 patronictl list 中均可查看。也可通过这些标签检查实例的健康状态——若某个实例未定义该标签，或对应值与查询值不匹配，将返回 HTTP 503。

3 - 环境变量

用于覆盖 Patroni 配置文件参数的环境变量。

原始页面： https://patroni.readthedocs.io/en/latest/ENVIRONMENT.html

可以使用系统环境变量覆盖 Patroni 配置文件中定义的部分配置参数。本文档列出了 Patroni 处理的所有环境变量。通过环境变量设置的值始终优先于配置文件中的值。