数据库高可用集群管理运维后端【免费下载链接】patroniA template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes项目地址https://gitcode.com/gh_mirrors/pa/patroni点击查看免费下载导读Patroni 将集群级配置如 TTL、超时、同步复制模式、PostgreSQL 参数与访问控制等存储在分布式配置存储DCSDistributed Configuration Store中并自动应用到所有集群节点这套机制被称为动态配置Dynamic Configuration。本文以 docs/dynamic_configuration.rst 为主体结合 patroni/config.py、patroni/ctl.py、patroni/api.py 等源码完整讲解动态配置的存储机制、全部参数语义与默认值、两种修改方式patronictl与 REST API以及生产环境的配置建议。读完本文你将掌握如何安全地在线调整 Patroni 集群的容错与同步行为而无需逐个节点手工修改 YAML。一、什么是动态配置为什么集群参数要放进 DCS传统的高可用方案中每个节点的配置文件各自独立修改一个参数必须逐台主机同步极易造成配置漂移。Patroni 的设计与之不同凡是需要集群范围内一致的配置统一写入 DCSEtcd、Consul、ZooKeeper 或 Kubernetes由每个 Patroni 实例读取后计算生效配置effective configuration。从 patroni/config.py 的Config类实现可以看出生效配置由三层合并而来__DEFAULT_CONFIG—— 内置的合理默认值dynamic_configuration—— 存储在 DCS 中的动态配置本篇文章的主角local_configuration—— 节点本地patroni.yaml或环境变量中的配置。合并逻辑在_build_effective_configurationpatroni/config.py中完成。动态配置的每次变更会被节点感知并热加载通常无需重启 Patroni 即可生效这正是它被广泛用于在线调整集群行为的原因。本地缓存与容灾恢复动态配置还会以 JSON 形式缓存到 PostgreSQL 数据目录下的patroni.dynamic.json文件中见 patroni/config.py 与save_cache方法patroni/config.py。这样即使 DCS 被误清空Patroni 也能从本地缓存恢复动态配置避免集群因丢失全局配置而行为错乱。二、修改动态配置的两种方式原文档明确指出修改动态配置有两种途径patronictl edit-config命令行工具以及 Patroni 的 REST API。方式一patronictl edit-configpatronictl是 Patroni 官方命令行工具其中edit-config与show-config两个子命令专门负责动态配置的查看与修改实现见 patroni/ctl.py 与 patroni/ctl.py。常用用法# 查看当前集群存储在 DCS 中的动态配置 patronictl -c patroni.yml show-config cluster_name # 交互式编辑不加任何参数时调用 $EDITOR 编辑整个配置 patronictl -c patroni.yml edit-config cluster_name # 用 --set 设置单个通用参数可多次指定 patronictl -c patroni.yml edit-config cluster_name \ --set loop_wait5 --set ttl30 # 用 --pg 设置 PostgreSQL 参数等价于 -s postgresql.parameters.xxx patronictl -c patroni.yml edit-config cluster_name \ --pg max_connections200 --pg max_worker_processes16 # 从 YAML 文件增量应用配置--replace 则整体替换- 表示从 stdin 读取 patronictl -c patroni.yml edit-config cluster_name --apply - changes.yaml patronictl -c patroni.yml edit-config cluster_name --replace new_full_config.yaml # 非交互无人值守脚本场景使用 --force 跳过确认 patronictl -c patroni.yml edit-config cluster_name --set ttl40 --force需要特别注意的是并发安全edit-config在提交前会校验 DCS 中配置的版本号若检测到其他会话并发修改会抛出 Config modification aborted due to concurrent changes 错误见 patroni/ctl.py避免覆盖他人变更。方式二REST APIPatroni 的 REST API 也提供了三个与动态配置相关的端点实现见 patroni/api.py方法路径语义GET /config读取当前 DCS 中的动态配置 JSON见 patroni/api.pyPATCH /config增量合并请求体中的配置项见 patroni/api.pyPUT /config用请求体整体覆盖动态配置见 patroni/api.py示例需携带restapi配置的认证信息# 增量修改 curl -X PATCH -H Content-Type: application/json \ -d {loop_wait: 5, ttl: 30} \ http://127.0.0.1:8008/config # 整体覆盖 curl -X PUT -H Content-Type: application/json \ -d {ttl: 40, loop_wait: 10, retry_timeout: 10} \ http://127.0.0.1:8008/config无论哪种方式最终都会调用 DCS 的set_config_value见 patroni/dcs/init.py写入配置键并携带版本号用于乐观锁并发控制。三、全局时序参数loop_wait、ttl、retry_timeout 及其约束规则这三个参数共同决定了 Patroni 主循环的节奏与故障切换的时效是动态配置里最核心的心跳参数。loop_wait主循环两次迭代之间的休眠秒数。默认值10最小值1。它决定了 Patroni 感知 DCS 状态变化、执行健康检查的频率下限。ttl获取 leader 锁的 TTL秒。可以理解为自动触发故障切换之前允许的时长。默认值30最小值20。leader 通过周期性续约锁来维持身份若锁过期且无人续约其他节点即可发起选举。retry_timeoutDCS 与 PostgreSQL 操作的重试超时秒。默认值10最小值3。凡是短于该时长的 DCS 或网络问题不会导致 leader 被降级——这是 Patroni 抵御瞬时抖动、避免无谓切换的第一道防线。必须遵守的不等式loop_wait 2 * retry_timeout ttl原文档给出了一个必须遵循的硬性规则loop_wait 2 * retry_timeout ttl这条规则的意义在于一次完整的发现问题并可能触发切换的周期最坏需要loop_wait 2 * retry_timeout的时间如等待主循环 两次带重试的 DCS 操作它必须小于锁的 TTL否则锁可能在操作完成前就已过期导致脑裂或频繁切换。值得注意的是Patroni 并不会拒绝违反规则的配置而是在提交时自动修正。_validate_and_adjust_timeoutspatroni/config.py的实现细节如下优先把loop_wait降到最小值1仍不满足时再压缩retry_timeout例如ttl30时若retry_timeout10则loop_wait会被调整到30 - 2*10 10若ttl太小导致1 2*retry_timeout ttl则retry_timeout会被压到(ttl - 1) // 2。因此在实际配置时建议手动保持该不等式成立以免触发隐式修正后得到与预期不符的时序。四、故障切换与同步复制相关参数primary_race_backoffprimary_race_backoff当从 primary 传来的 WAL 复制仍在推进时将 standby 的 leader 竞选推迟该秒数。默认值0禁用。它用来最小化因 Patroni 短暂无响应例如 GC 停顿、瞬时网络抖动而引发的非必要 failover——给原 primary 一个复活窗口避免 standby 急于抢锁。从 patroni/global_config.py 可确认其默认读取值为0。maximum_lag_on_failover 与 maximum_lag_on_syncnodemaximum_lag_on_failover允许参与 leader 选举的 follower 的最大 WAL 滞后字节数。超过该值的节点在 failover 时没有资格成为新 leader。其默认值在源码中为1048576即 1 MiB见 patroni/global_config.py。maximum_lag_on_syncnode同步 follower 被视为不健康并被异步 follower 替换前允许的最大滞后字节数。默认值-1即 Patroni 不主动替换不健康的同步 follower。需要注意当存在多个 follower 时Patroni 使用所有 follower 中的最大 replica LSN 作为参照只有单个 follower 时才以 leader 当前 WAL LSN 为参照。在写事务量高的场景下请把该值设得足够大避免同步 follower 被频繁换出换入。max_timelines_historymax_timelines_history在 DCS 中保留的 timeline 历史条目的最大数量。默认值0表示保留全部历史。该历史用于patronictl history查询以及切换时的时间线管理见 patroni/ctl.py 对 history 输出的实现。primary_start_timeout 与 primary_stop_timeoutprimary_start_timeoutprimary 从故障中恢复所允许的时间秒超时即触发 failover。默认300秒设为0时一旦检测到崩溃且条件允许立即 failover。 由于异步复制下 failover 可能丢失已提交事务需要在持久性与可用性之间权衡。最坏情况下的故障切换时间为loop_wait primary_start_timeout loop_wait若primary_start_timeout为 0则仅需loop_wait。primary_stop_timeout仅在启用了synchronous_mode时生效是停止 Postgres 时允许等待的秒数。当设为 0且同步模式开启时若停止操作运行超过该时长Patroni 会对 postmaster 发送SIGKILL。未设置或 0时该参数不生效。同样需要按持久性/可用性权衡取舍。五、同步复制模式synchronous_mode 家族synchronous_mode开启同步复制模式。可选值为off、on、quorum。开启后leader 负责管理synchronous_standby_names且只有最近已知的 leader或同步副本之一允许参与 leader 竞选。同步模式保证 failover 时不丢失已提交事务代价是当 Patroni 无法确保事务持久性时如无可用同步副本写入可用性会下降。完整语义见 docs/replication_modes.rst。synchronous_mode_strict当没有可用的同步副本时阻止关闭同步复制即阻塞所有发往 primary 的客户端写入。此时 Patroni 会让synchronous_standby_names继续指向/syncDCS 键中记录的上一次已知同步节点若从未有过同步状态则使用内部占位符__patroni_strict_sync_replica_placeholder__。注意节点在patroni.yaml中的name绝不能设为__patroni_strict_sync_replica_placeholder__。synchronous_node_count启用同步模式后Patroni 用它精确管理同步副本的数量并在成员加入/离开时同步更新 DCS 状态与 PostgreSQL 的synchronous_standby_names。若该值高于实际可用节点数会被自动下调。默认值1见 patroni/global_config.py实际生效值取max(配置值, min_synchronous_nodes)。failsafe_modefailsafe_mode启用 DCS Failsafe Mode默认false。当 DCS 不可达时该模式让 Patroni 进入一种保守自我保护状态防止 DCS 失联期间发生错误的决策如误降级或误切换。其设计动机与行为细节见 docs/dcs_failsafe_mode.rst。六、postgresql 子配置参数、角色差异化与访问控制动态配置中的postgresql小节用于承载跨节点的 PostgreSQL 配置但它不能包含所有本地项。哪些本地项不允许放入动态配置从_safe_copy_dynamic_configurationpatroni/config.py的实现可以看到以下键若出现在动态配置的postgresql小节中会被直接丢弃connect_address、proxy_address、listen、config_dir、data_dir、pgpass、authentication。它们是纯节点本地配置必须留在patroni.yaml中。parameters 与角色差异化覆盖parametersPostgreSQL 参数GUC字典格式如{max_connections: 100, wal_level: replica, max_wal_senders: 10, wal_log_hints: on}。其中相当一部分是复制功能所必需的。通过动态配置设置这些参数时会经过_process_postgresql_parameterspatroni/config.py的校验命中CMDLINE_OPTIONS的启动参数会按对应 validator 验证校验失败则回退默认值并记录 warninglisten_addresses、port、cluster_name、hot_standby这类由本地配置推导的参数不可在动态配置中设置。parameters_primary/parameters_replica/parameters_standby_leader均可选分别针对 primary、replica、standby_leader 角色的参数覆盖。它们与基础parameters合并并优先于基础值。这一机制让同一套参数 角色差异化微调成为可能——例如只在 primary 上加大max_connections。pg_hba / pg_ident / pg_hosts 及角色差异化版本pg_hba用于生成pg_hba.conf的行列表。注意若 PostgreSQL 参数hba_file被设置为非默认值Patroni 会忽略本参数。原文档给出的典型示例pg_hba: - host all all 0.0.0.0/0 md5 - host replication replicator 127.0.0.1/32 md5 # 复制所必需pg_hba_primary/pg_hba_replica/pg_hba_standby_leader可选角色差异化的 pg_hba 条目。与parameters_*的合并语义不同它们完全替换pg_hba不做合并未定义时回退使用pg_hba。pg_ident用于生成pg_ident.conf的行列表若ident_file被设置为非默认值则忽略。示例pg_ident: - mapname1 systemname1 pguser1 - mapname1 systemname2 pguser2同样提供pg_ident_primary/pg_ident_replica/pg_ident_standby_leader三个完全替换式角色版本。pg_hosts仅 PostgreSQL 19用于生成pg_hosts.conf的行列表若hosts_file被设置为非默认值则忽略。同样提供pg_hosts_primary/pg_hosts_replica/pg_hosts_standby_leader三个完全替换式角色版本。复制与恢复相关use_pg_rewind是否使用pg_rewind。默认false。注意前提条件集群初始化时必须开启data page checksumsinitdb --data-checksums和/或wal_log_hints设为on否则pg_rewind无法工作。use_slots是否使用复制槽。PostgreSQL 9.4 默认true。复制槽可防止 WAL 在 follower 尚未消费前被回收是复制稳定性的关键。recovery_conf配置 follower 时额外写入recovery.conf的设置。PostgreSQL 12 已取消recovery.conf文件但本小节仍可继续使用因为 Patroni 会透明地将这些设置迁移到postgresql.conf的primary_conninfo等价项见 patroni/postgresql/config.py 对primary_slot_name的处理逻辑。七、standby_cluster级联/备集群配置若定义了standby_cluster小节则该节点作为 standby 集群启动从远端 primary 拉取数据。原文档列出的子参数如下host远端节点地址。port远端节点端口。primary_slot_name在远端节点上使用的复制槽名。可选默认值由实例名推导对应slot_name_from_member_name函数。create_replica_methods从远端 primary 引导 standby leader 的有序方法列表可与 patroni_configuration.rst 中定义的列表不同。restore_command从远端 primary 向 standby 集群节点恢复 WAL 的命令同样可不同于基础配置。archive_cleanup_commandstandby leader 的归档清理命令。recovery_min_apply_delaystandby leader 延迟应用 WAL 的时长用于延迟复制/灾备演练。更完整的 standby 集群搭建流程见 docs/standby_cluster.rst。八、复制槽管理slots、member_slots_ttl 与 ignore_slots复制槽管理是 Patroni 动态配置中机制最复杂、也最需要谨慎的部分。member_slots_ttl下线副本的槽保留时间member_slots_ttl副本节点关闭时其物理复制槽的保留时长。默认值30min。设为0则恢复旧行为成员键从 DCS 过期后槽被立即删除。该特性仅对 PostgreSQL 11 生效默认值 1800 秒的读取逻辑见 patroni/global_config.py。PostgreSQL 11 下Patroni 会在所有可能成为 leader 的节点上维护物理复制槽确保节点离线时 WAL 仍被保留。若节点缺席且其 DCS 成员键过期对应槽会在member_slots_ttl后被删除。对于节点数量固定、名称不变的自定义拓扑原文档建议用名称与节点名一一对应的永久物理槽来避免槽被回收、WAL 被过早清理slots: node_name1: type: physical node_name2: type: physical node_name3: type: physicalslots永久复制槽slots定义永久复制槽它们在 switchover/failover 期间被保留不存在的永久槽会由 Patroni 自动创建。行为因 PostgreSQL 版本而异PostgreSQL 11永久物理槽在所有节点上创建其位置每loop_wait秒推进一次PostgreSQL 11 之前永久物理槽只在当前 primary 上维护逻辑槽从 primary 复制到 standby 时随重启进行之后每loop_wait秒如有必要推进位置。逻辑槽文件通过libpq连接复制使用 rewind 或 superuser 凭据见postgresql.authentication小节。复制后逻辑槽位置可能略落后于原 primary因此应用应做好 failover 后重复接收部分消息的准备——最稳妥的办法是追踪confirmed_flush_lsn。启用永久复制槽要求postgresql.use_slots为true一旦定义了永久逻辑槽Patroni 会自动开启hot_standby_feedback。由于 PostgreSQL 9.6 及更早版本的逻辑槽 failover 不安全、PostgreSQL 10 又缺少关键函数该特性仅对 PostgreSQL 11 生效。每个槽可配置的属性type槽类型physical或logical。逻辑槽必须额外定义database和plugin物理槽可选用cluster_type。database创建逻辑槽的数据库名。plugin逻辑槽的解码插件名。cluster_type槽应创建在的集群类型primary或standby。不匹配时槽不会被创建已存在的也会被删除。特殊规则若永久槽名称与当前节点名相同则不会在该节点上创建该槽。若永久物理槽名称恰好与某个 Patroni 成员名一致即使该成员失联该槽也不会被删除正常情况下失联成员对应的槽会被移除。这在成员临时故障期间保留槽或将独立实例导入 Patroni 集群见 docs/existing_data.rst等场景下很有用但运维人员需注意这类重名不应长期保留在 DCS 中以免影响 Patroni 的正常行为。原文档给出的 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注意slots是哈希表hashmap而ignore_slots是数组array两者结构不同不可混用。ignore_slots放行外部管理的槽ignore_slots列出需要 Patroni 忽略的复制槽属性集合。当部分复制槽由 Patroni 之外的工具管理时例如逻辑复制工具自建的槽用此配置避免 Patroni 误删。只要属性匹配子集即可忽略即匹配的属性越多越精确但任意子集匹配都会生效。匹配属性包括name槽名称。typephysical或logical逻辑槽可额外定义database和/或plugin。database匹配逻辑槽时的数据库名。plugin匹配逻辑槽时的解码插件名。永久槽的两条重要警告原文档明确给出两条警告务必遵守永久复制槽只从 primary/standby_leader 向副本节点同步。应用应只在 leader 节点上使用它们若在副本上使用会导致集群所有其他节点的pg_wal无限增长。唯一例外是与 Patroni 成员名匹配的物理槽它们本就用于节点间复制会被同步到所有节点。给 standby 设置nostream标签会禁用该节点及其所有级联副本上的永久逻辑槽的复制与同步。九、manage_synchronized_standby_slotsPostgreSQL 17manage_synchronized_standby_slots仅 PostgreSQL 17。启用后Patroni 自动维护synchronized_standby_slots参数使其与synchronous_standby_names保持一致从而保证failovertrue的逻辑复制槽同步到与同步复制相同的物理 standby 上。默认false需要显式开启。启用前提与行为细节要求synchronous_mode: true或synchronous_mode: quorum已开启因为该功能依赖当前的同步复制拓扑来决定哪些 standby 接收同步逻辑槽。quorum 模式下Patroni 会把所有同步 standby 列入synchronized_standby_slots。由于 PostgreSQL 会等待每一个列出的物理槽追平后才推进逻辑槽逻辑复制的等待时间可能比提交语义所需的更长提交只需synchronous_node_count个 standby 确认。这是保证逻辑复制零丢失的保守默认行为但一个长期滞后的 standby 会永久阻塞逻辑槽推进。功能关闭时Patroni 将synchronized_standby_slots恢复为用户在postgresql.parameters中配置的值若未配置则移除该参数。当synchronous_mode_strict开启且当前无可用同步 standby 时Patroni 将synchronized_standby_slots设为与synchronous_standby_names相同的内部占位符__patroni_strict_sync_replica_placeholder__。由于不存在该名称的复制槽PostgreSQL 会反复记录如下日志——这是预期行为用于阻止逻辑槽在同步 standby 可用前推进从而保证逻辑订阅者不会先于物理复制确认收到变更standby 恢复连接后告警即消失WARNING: replication slot __patroni_strict_sync_replica_placeholder__ specified in parameter synchronized_standby_slots does not exist DETAIL: Logical replication is waiting on the standby associated with replication slot __patroni_strict_sync_replica_placeholder__. HINT: Create the replication slot __patroni_strict_sync_replica_placeholder__ or amend parameter synchronized_standby_slots.原文档给出的最小启用示例synchronous_mode: true manage_synchronized_standby_slots: true十、一份可落地的完整动态配置示例综合以上全部参数下面是一份可直接用于生产评估的完整动态配置 YAML结合了原文档示例与源码中的默认值语义# 全局时序务必满足 loop_wait 2 * retry_timeout ttl loop_wait: 10 # 默认 10最小值 1 ttl: 30 # 默认 30最小值 20 retry_timeout: 10 # 默认 10最小值 3 # 故障切换与同步 primary_race_backoff: 0 # 默认 0禁用 maximum_lag_on_failover: 1048576 # 默认 1MiB maximum_lag_on_syncnode: -1 # 默认 -1不主动替换 max_timelines_history: 0 # 0 保留全部历史 primary_start_timeout: 300 # 默认 300 秒 primary_stop_timeout: 0 # 仅同步模式下 0 时生效 # 同步复制 synchronous_mode: on # off | on | quorum synchronous_mode_strict: false synchronous_node_count: 1 # 默认 1 failsafe_mode: false # 默认 false postgresql: use_pg_rewind: false use_slots: true parameters: max_connections: 100 wal_level: replica max_wal_senders: 10 wal_log_hints: on pg_hba: - host all all 0.0.0.0/0 md5 - host replication replicator 127.0.0.1/32 md5 pg_ident: - mapname1 systemname1 pguser1 standby_cluster: host: remote-primary.example.com port: 5432 primary_slot_name: standby_cluster_slot recovery_min_apply_delay: 0 member_slots_ttl: 30min # 默认 30min0 恢复旧行为 slots: permanent_logical_slot_name: type: logical database: my_db plugin: test_decoding permanent_physical_slot_name: type: physical ignore_slots: - name: externally_managed_slot type: logical database: my_db plugin: test_decoding manage_synchronized_standby_slots: false # PostgreSQL 17默认 false十一、修改后的验证与常见问题修改动态配置后建议按以下顺序验证查看生效配置执行patronictl show-config cluster或GET /config确认写入 DCS 的内容符合预期观察节点日志各节点应能在下一个主循环周期内应用新配置若配置了 Postgres 参数Patroni 会触发相应的 reload 或重启流程核对不等式若设置了loop_wait、retry_timeout、ttl确认loop_wait 2 * retry_timeout ttl否则留意 Patroni 日志中的 Violated the rule ... Adjusting 修正信息见 patroni/config.py并发修改保护多人同时edit-config时版本号校验会拒绝后提交者提交失败方需重新拉取最新配置后再改DCS 被清空的恢复只要 Postgres 数据目录中的patroni.dynamic.json缓存存在Patroni 会尝试从缓存恢复动态配置见 patroni/config.py。常见误区提醒slots是哈希表、ignore_slots是数组写反会导致配置解析失败不要把listen、data_dir、connect_address、authentication等本地项放进动态配置它们会被静默丢弃见 patroni/config.py永久逻辑槽只应被 leader 上的应用使用副本节点使用会引发pg_wal膨胀节点name严禁使用__patroni_strict_sync_replica_placeholder__否则会与严格同步模式的内部占位符冲突。十二、延伸阅读docs/patroni_configuration.rst完整静态配置本地 YAML参考理解动态配置与本地配置的分工边界docs/replication_modes.rst同步/异步/quorum 复制模式的原理与选择docs/dcs_failsafe_mode.rstDCS 失联时的自我保护机制docs/standby_cluster.rststandby_cluster 小节的完整搭建指南docs/existing_data.rst将独立实例导入 Patroni 集群涉及永久槽重名用法patroni/config.py动态配置合并、校验、缓存的核心实现patroni/ctl.pypatronictl edit-config/show-config的完整实现patroni/api.pyREST API 中GET/PATCH/PUT /config的实现patroni/global_config.py各全局参数的默认值与读取逻辑。赞分享数据库高可用集群管理运维后端【免费下载链接】patroniA template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes项目地址https://gitcode.com/gh_mirrors/pa/patroni点击查看免费下载相关推荐OpenAPI Generator 配置详解全局参数最佳实践OpenAPI Generator 配置详解全局参数最佳实践 你是否还在为API文档生成效率低而烦恼是否希望通过简单配置实现代码生成的精准控制本文将系统讲开发工具代码生成API设计CLI浏览器端AI抠图革命无需服务器3行代码实现专业级背景移除浏览器端AI抠图革命无需服务器3行代码实现专业级背景移除 在当今数字内容创作时代图像背景移除已成为电商、设计和社交媒体应用中不可或缺的功能。然而传统方案计算机视觉图像处理AI 应用ImagePicker完全配置指南9大核心参数详解与最佳实践ImagePicker完全配置指南9大核心参数详解与最佳实践 ImagePicker是一款完全仿微信的图片选择库提供了多种图片加载接口支持图片旋转、裁剪上一篇彻底解决HTMLBars开发痛点从编译原理到性能优化全指南下一篇Cordova Google Maps插件常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Patroni 动态配置（Dynamic Configuration）完全指南：DCS 全局配置的存储、参数详解与最佳实践
数据库高可用集群管理运维后端【免费下载链接】patroniA template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes项目地址https://gitcode.com/gh_mirrors/pa/patroni点击查看免费下载导读Patroni 将集群级配置如 TTL、超时、同步复制模式、PostgreSQL 参数与访问控制等存储在分布式配置存储DCSDistributed Configuration Store中并自动应用到所有集群节点这套机制被称为动态配置Dynamic Configuration。本文以 docs/dynamic_configuration.rst 为主体结合 patroni/config.py、patroni/ctl.py、patroni/api.py 等源码完整讲解动态配置的存储机制、全部参数语义与默认值、两种修改方式patronictl与 REST API以及生产环境的配置建议。读完本文你将掌握如何安全地在线调整 Patroni 集群的容错与同步行为而无需逐个节点手工修改 YAML。一、什么是动态配置为什么集群参数要放进 DCS传统的高可用方案中每个节点的配置文件各自独立修改一个参数必须逐台主机同步极易造成配置漂移。Patroni 的设计与之不同凡是需要集群范围内一致的配置统一写入 DCSEtcd、Consul、ZooKeeper 或 Kubernetes由每个 Patroni 实例读取后计算生效配置effective configuration。从 patroni/config.py 的Config类实现可以看出生效配置由三层合并而来__DEFAULT_CONFIG—— 内置的合理默认值dynamic_configuration—— 存储在 DCS 中的动态配置本篇文章的主角local_configuration—— 节点本地patroni.yaml或环境变量中的配置。合并逻辑在_build_effective_configurationpatroni/config.py中完成。动态配置的每次变更会被节点感知并热加载通常无需重启 Patroni 即可生效这正是它被广泛用于在线调整集群行为的原因。本地缓存与容灾恢复动态配置还会以 JSON 形式缓存到 PostgreSQL 数据目录下的patroni.dynamic.json文件中见 patroni/config.py 与save_cache方法patroni/config.py。这样即使 DCS 被误清空Patroni 也能从本地缓存恢复动态配置避免集群因丢失全局配置而行为错乱。二、修改动态配置的两种方式原文档明确指出修改动态配置有两种途径patronictl edit-config命令行工具以及 Patroni 的 REST API。方式一patronictl edit-configpatronictl是 Patroni 官方命令行工具其中edit-config与show-config两个子命令专门负责动态配置的查看与修改实现见 patroni/ctl.py 与 patroni/ctl.py。常用用法# 查看当前集群存储在 DCS 中的动态配置 patronictl -c patroni.yml show-config cluster_name # 交互式编辑不加任何参数时调用 $EDITOR 编辑整个配置 patronictl -c patroni.yml edit-config cluster_name # 用 --set 设置单个通用参数可多次指定 patronictl -c patroni.yml edit-config cluster_name \ --set loop_wait5 --set ttl30 # 用 --pg 设置 PostgreSQL 参数等价于 -s postgresql.parameters.xxx patronictl -c patroni.yml edit-config cluster_name \ --pg max_connections200 --pg max_worker_processes16 # 从 YAML 文件增量应用配置--replace 则整体替换- 表示从 stdin 读取 patronictl -c patroni.yml edit-config cluster_name --apply - changes.yaml patronictl -c patroni.yml edit-config cluster_name --replace new_full_config.yaml # 非交互无人值守脚本场景使用 --force 跳过确认 patronictl -c patroni.yml edit-config cluster_name --set ttl40 --force需要特别注意的是并发安全edit-config在提交前会校验 DCS 中配置的版本号若检测到其他会话并发修改会抛出 Config modification aborted due to concurrent changes 错误见 patroni/ctl.py避免覆盖他人变更。方式二REST APIPatroni 的 REST API 也提供了三个与动态配置相关的端点实现见 patroni/api.py方法路径语义GET /config读取当前 DCS 中的动态配置 JSON见 patroni/api.pyPATCH /config增量合并请求体中的配置项见 patroni/api.pyPUT /config用请求体整体覆盖动态配置见 patroni/api.py示例需携带restapi配置的认证信息# 增量修改 curl -X PATCH -H Content-Type: application/json \ -d {loop_wait: 5, ttl: 30} \ http://127.0.0.1:8008/config # 整体覆盖 curl -X PUT -H Content-Type: application/json \ -d {ttl: 40, loop_wait: 10, retry_timeout: 10} \ http://127.0.0.1:8008/config无论哪种方式最终都会调用 DCS 的set_config_value见 patroni/dcs/init.py写入配置键并携带版本号用于乐观锁并发控制。三、全局时序参数loop_wait、ttl、retry_timeout 及其约束规则这三个参数共同决定了 Patroni 主循环的节奏与故障切换的时效是动态配置里最核心的心跳参数。loop_wait主循环两次迭代之间的休眠秒数。默认值10最小值1。它决定了 Patroni 感知 DCS 状态变化、执行健康检查的频率下限。ttl获取 leader 锁的 TTL秒。可以理解为自动触发故障切换之前允许的时长。默认值30最小值20。leader 通过周期性续约锁来维持身份若锁过期且无人续约其他节点即可发起选举。retry_timeoutDCS 与 PostgreSQL 操作的重试超时秒。默认值10最小值3。凡是短于该时长的 DCS 或网络问题不会导致 leader 被降级——这是 Patroni 抵御瞬时抖动、避免无谓切换的第一道防线。必须遵守的不等式loop_wait 2 * retry_timeout ttl原文档给出了一个必须遵循的硬性规则loop_wait 2 * retry_timeout ttl这条规则的意义在于一次完整的发现问题并可能触发切换的周期最坏需要loop_wait 2 * retry_timeout的时间如等待主循环 两次带重试的 DCS 操作它必须小于锁的 TTL否则锁可能在操作完成前就已过期导致脑裂或频繁切换。值得注意的是Patroni 并不会拒绝违反规则的配置而是在提交时自动修正。_validate_and_adjust_timeoutspatroni/config.py的实现细节如下优先把loop_wait降到最小值1仍不满足时再压缩retry_timeout例如ttl30时若retry_timeout10则loop_wait会被调整到30 - 2*10 10若ttl太小导致1 2*retry_timeout ttl则retry_timeout会被压到(ttl - 1) // 2。因此在实际配置时建议手动保持该不等式成立以免触发隐式修正后得到与预期不符的时序。四、故障切换与同步复制相关参数primary_race_backoffprimary_race_backoff当从 primary 传来的 WAL 复制仍在推进时将 standby 的 leader 竞选推迟该秒数。默认值0禁用。它用来最小化因 Patroni 短暂无响应例如 GC 停顿、瞬时网络抖动而引发的非必要 failover——给原 primary 一个复活窗口避免 standby 急于抢锁。从 patroni/global_config.py 可确认其默认读取值为0。maximum_lag_on_failover 与 maximum_lag_on_syncnodemaximum_lag_on_failover允许参与 leader 选举的 follower 的最大 WAL 滞后字节数。超过该值的节点在 failover 时没有资格成为新 leader。其默认值在源码中为1048576即 1 MiB见 patroni/global_config.py。maximum_lag_on_syncnode同步 follower 被视为不健康并被异步 follower 替换前允许的最大滞后字节数。默认值-1即 Patroni 不主动替换不健康的同步 follower。需要注意当存在多个 follower 时Patroni 使用所有 follower 中的最大 replica LSN 作为参照只有单个 follower 时才以 leader 当前 WAL LSN 为参照。在写事务量高的场景下请把该值设得足够大避免同步 follower 被频繁换出换入。max_timelines_historymax_timelines_history在 DCS 中保留的 timeline 历史条目的最大数量。默认值0表示保留全部历史。该历史用于patronictl history查询以及切换时的时间线管理见 patroni/ctl.py 对 history 输出的实现。primary_start_timeout 与 primary_stop_timeoutprimary_start_timeoutprimary 从故障中恢复所允许的时间秒超时即触发 failover。默认300秒设为0时一旦检测到崩溃且条件允许立即 failover。 由于异步复制下 failover 可能丢失已提交事务需要在持久性与可用性之间权衡。最坏情况下的故障切换时间为loop_wait primary_start_timeout loop_wait若primary_start_timeout为 0则仅需loop_wait。primary_stop_timeout仅在启用了synchronous_mode时生效是停止 Postgres 时允许等待的秒数。当设为 0且同步模式开启时若停止操作运行超过该时长Patroni 会对 postmaster 发送SIGKILL。未设置或 0时该参数不生效。同样需要按持久性/可用性权衡取舍。五、同步复制模式synchronous_mode 家族synchronous_mode开启同步复制模式。可选值为off、on、quorum。开启后leader 负责管理synchronous_standby_names且只有最近已知的 leader或同步副本之一允许参与 leader 竞选。同步模式保证 failover 时不丢失已提交事务代价是当 Patroni 无法确保事务持久性时如无可用同步副本写入可用性会下降。完整语义见 docs/replication_modes.rst。synchronous_mode_strict当没有可用的同步副本时阻止关闭同步复制即阻塞所有发往 primary 的客户端写入。此时 Patroni 会让synchronous_standby_names继续指向/syncDCS 键中记录的上一次已知同步节点若从未有过同步状态则使用内部占位符__patroni_strict_sync_replica_placeholder__。注意节点在patroni.yaml中的name绝不能设为__patroni_strict_sync_replica_placeholder__。synchronous_node_count启用同步模式后Patroni 用它精确管理同步副本的数量并在成员加入/离开时同步更新 DCS 状态与 PostgreSQL 的synchronous_standby_names。若该值高于实际可用节点数会被自动下调。默认值1见 patroni/global_config.py实际生效值取max(配置值, min_synchronous_nodes)。failsafe_modefailsafe_mode启用 DCS Failsafe Mode默认false。当 DCS 不可达时该模式让 Patroni 进入一种保守自我保护状态防止 DCS 失联期间发生错误的决策如误降级或误切换。其设计动机与行为细节见 docs/dcs_failsafe_mode.rst。六、postgresql 子配置参数、角色差异化与访问控制动态配置中的postgresql小节用于承载跨节点的 PostgreSQL 配置但它不能包含所有本地项。哪些本地项不允许放入动态配置从_safe_copy_dynamic_configurationpatroni/config.py的实现可以看到以下键若出现在动态配置的postgresql小节中会被直接丢弃connect_address、proxy_address、listen、config_dir、data_dir、pgpass、authentication。它们是纯节点本地配置必须留在patroni.yaml中。parameters 与角色差异化覆盖parametersPostgreSQL 参数GUC字典格式如{max_connections: 100, wal_level: replica, max_wal_senders: 10, wal_log_hints: on}。其中相当一部分是复制功能所必需的。通过动态配置设置这些参数时会经过_process_postgresql_parameterspatroni/config.py的校验命中CMDLINE_OPTIONS的启动参数会按对应 validator 验证校验失败则回退默认值并记录 warninglisten_addresses、port、cluster_name、hot_standby这类由本地配置推导的参数不可在动态配置中设置。parameters_primary/parameters_replica/parameters_standby_leader均可选分别针对 primary、replica、standby_leader 角色的参数覆盖。它们与基础parameters合并并优先于基础值。这一机制让同一套参数 角色差异化微调成为可能——例如只在 primary 上加大max_connections。pg_hba / pg_ident / pg_hosts 及角色差异化版本pg_hba用于生成pg_hba.conf的行列表。注意若 PostgreSQL 参数hba_file被设置为非默认值Patroni 会忽略本参数。原文档给出的典型示例pg_hba: - host all all 0.0.0.0/0 md5 - host replication replicator 127.0.0.1/32 md5 # 复制所必需pg_hba_primary/pg_hba_replica/pg_hba_standby_leader可选角色差异化的 pg_hba 条目。与parameters_*的合并语义不同它们完全替换pg_hba不做合并未定义时回退使用pg_hba。pg_ident用于生成pg_ident.conf的行列表若ident_file被设置为非默认值则忽略。示例pg_ident: - mapname1 systemname1 pguser1 - mapname1 systemname2 pguser2同样提供pg_ident_primary/pg_ident_replica/pg_ident_standby_leader三个完全替换式角色版本。pg_hosts仅 PostgreSQL 19用于生成pg_hosts.conf的行列表若hosts_file被设置为非默认值则忽略。同样提供pg_hosts_primary/pg_hosts_replica/pg_hosts_standby_leader三个完全替换式角色版本。复制与恢复相关use_pg_rewind是否使用pg_rewind。默认false。注意前提条件集群初始化时必须开启data page checksumsinitdb --data-checksums和/或wal_log_hints设为on否则pg_rewind无法工作。use_slots是否使用复制槽。PostgreSQL 9.4 默认true。复制槽可防止 WAL 在 follower 尚未消费前被回收是复制稳定性的关键。recovery_conf配置 follower 时额外写入recovery.conf的设置。PostgreSQL 12 已取消recovery.conf文件但本小节仍可继续使用因为 Patroni 会透明地将这些设置迁移到postgresql.conf的primary_conninfo等价项见 patroni/postgresql/config.py 对primary_slot_name的处理逻辑。七、standby_cluster级联/备集群配置若定义了standby_cluster小节则该节点作为 standby 集群启动从远端 primary 拉取数据。原文档列出的子参数如下host远端节点地址。port远端节点端口。primary_slot_name在远端节点上使用的复制槽名。可选默认值由实例名推导对应slot_name_from_member_name函数。create_replica_methods从远端 primary 引导 standby leader 的有序方法列表可与 patroni_configuration.rst 中定义的列表不同。restore_command从远端 primary 向 standby 集群节点恢复 WAL 的命令同样可不同于基础配置。archive_cleanup_commandstandby leader 的归档清理命令。recovery_min_apply_delaystandby leader 延迟应用 WAL 的时长用于延迟复制/灾备演练。更完整的 standby 集群搭建流程见 docs/standby_cluster.rst。八、复制槽管理slots、member_slots_ttl 与 ignore_slots复制槽管理是 Patroni 动态配置中机制最复杂、也最需要谨慎的部分。member_slots_ttl下线副本的槽保留时间member_slots_ttl副本节点关闭时其物理复制槽的保留时长。默认值30min。设为0则恢复旧行为成员键从 DCS 过期后槽被立即删除。该特性仅对 PostgreSQL 11 生效默认值 1800 秒的读取逻辑见 patroni/global_config.py。PostgreSQL 11 下Patroni 会在所有可能成为 leader 的节点上维护物理复制槽确保节点离线时 WAL 仍被保留。若节点缺席且其 DCS 成员键过期对应槽会在member_slots_ttl后被删除。对于节点数量固定、名称不变的自定义拓扑原文档建议用名称与节点名一一对应的永久物理槽来避免槽被回收、WAL 被过早清理slots: node_name1: type: physical node_name2: type: physical node_name3: type: physicalslots永久复制槽slots定义永久复制槽它们在 switchover/failover 期间被保留不存在的永久槽会由 Patroni 自动创建。行为因 PostgreSQL 版本而异PostgreSQL 11永久物理槽在所有节点上创建其位置每loop_wait秒推进一次PostgreSQL 11 之前永久物理槽只在当前 primary 上维护逻辑槽从 primary 复制到 standby 时随重启进行之后每loop_wait秒如有必要推进位置。逻辑槽文件通过libpq连接复制使用 rewind 或 superuser 凭据见postgresql.authentication小节。复制后逻辑槽位置可能略落后于原 primary因此应用应做好 failover 后重复接收部分消息的准备——最稳妥的办法是追踪confirmed_flush_lsn。启用永久复制槽要求postgresql.use_slots为true一旦定义了永久逻辑槽Patroni 会自动开启hot_standby_feedback。由于 PostgreSQL 9.6 及更早版本的逻辑槽 failover 不安全、PostgreSQL 10 又缺少关键函数该特性仅对 PostgreSQL 11 生效。每个槽可配置的属性type槽类型physical或logical。逻辑槽必须额外定义database和plugin物理槽可选用cluster_type。database创建逻辑槽的数据库名。plugin逻辑槽的解码插件名。cluster_type槽应创建在的集群类型primary或standby。不匹配时槽不会被创建已存在的也会被删除。特殊规则若永久槽名称与当前节点名相同则不会在该节点上创建该槽。若永久物理槽名称恰好与某个 Patroni 成员名一致即使该成员失联该槽也不会被删除正常情况下失联成员对应的槽会被移除。这在成员临时故障期间保留槽或将独立实例导入 Patroni 集群见 docs/existing_data.rst等场景下很有用但运维人员需注意这类重名不应长期保留在 DCS 中以免影响 Patroni 的正常行为。原文档给出的 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注意slots是哈希表hashmap而ignore_slots是数组array两者结构不同不可混用。ignore_slots放行外部管理的槽ignore_slots列出需要 Patroni 忽略的复制槽属性集合。当部分复制槽由 Patroni 之外的工具管理时例如逻辑复制工具自建的槽用此配置避免 Patroni 误删。只要属性匹配子集即可忽略即匹配的属性越多越精确但任意子集匹配都会生效。匹配属性包括name槽名称。typephysical或logical逻辑槽可额外定义database和/或plugin。database匹配逻辑槽时的数据库名。plugin匹配逻辑槽时的解码插件名。永久槽的两条重要警告原文档明确给出两条警告务必遵守永久复制槽只从 primary/standby_leader 向副本节点同步。应用应只在 leader 节点上使用它们若在副本上使用会导致集群所有其他节点的pg_wal无限增长。唯一例外是与 Patroni 成员名匹配的物理槽它们本就用于节点间复制会被同步到所有节点。给 standby 设置nostream标签会禁用该节点及其所有级联副本上的永久逻辑槽的复制与同步。九、manage_synchronized_standby_slotsPostgreSQL 17manage_synchronized_standby_slots仅 PostgreSQL 17。启用后Patroni 自动维护synchronized_standby_slots参数使其与synchronous_standby_names保持一致从而保证failovertrue的逻辑复制槽同步到与同步复制相同的物理 standby 上。默认false需要显式开启。启用前提与行为细节要求synchronous_mode: true或synchronous_mode: quorum已开启因为该功能依赖当前的同步复制拓扑来决定哪些 standby 接收同步逻辑槽。quorum 模式下Patroni 会把所有同步 standby 列入synchronized_standby_slots。由于 PostgreSQL 会等待每一个列出的物理槽追平后才推进逻辑槽逻辑复制的等待时间可能比提交语义所需的更长提交只需synchronous_node_count个 standby 确认。这是保证逻辑复制零丢失的保守默认行为但一个长期滞后的 standby 会永久阻塞逻辑槽推进。功能关闭时Patroni 将synchronized_standby_slots恢复为用户在postgresql.parameters中配置的值若未配置则移除该参数。当synchronous_mode_strict开启且当前无可用同步 standby 时Patroni 将synchronized_standby_slots设为与synchronous_standby_names相同的内部占位符__patroni_strict_sync_replica_placeholder__。由于不存在该名称的复制槽PostgreSQL 会反复记录如下日志——这是预期行为用于阻止逻辑槽在同步 standby 可用前推进从而保证逻辑订阅者不会先于物理复制确认收到变更standby 恢复连接后告警即消失WARNING: replication slot __patroni_strict_sync_replica_placeholder__ specified in parameter synchronized_standby_slots does not exist DETAIL: Logical replication is waiting on the standby associated with replication slot __patroni_strict_sync_replica_placeholder__. HINT: Create the replication slot __patroni_strict_sync_replica_placeholder__ or amend parameter synchronized_standby_slots.原文档给出的最小启用示例synchronous_mode: true manage_synchronized_standby_slots: true十、一份可落地的完整动态配置示例综合以上全部参数下面是一份可直接用于生产评估的完整动态配置 YAML结合了原文档示例与源码中的默认值语义# 全局时序务必满足 loop_wait 2 * retry_timeout ttl loop_wait: 10 # 默认 10最小值 1 ttl: 30 # 默认 30最小值 20 retry_timeout: 10 # 默认 10最小值 3 # 故障切换与同步 primary_race_backoff: 0 # 默认 0禁用 maximum_lag_on_failover: 1048576 # 默认 1MiB maximum_lag_on_syncnode: -1 # 默认 -1不主动替换 max_timelines_history: 0 # 0 保留全部历史 primary_start_timeout: 300 # 默认 300 秒 primary_stop_timeout: 0 # 仅同步模式下 0 时生效 # 同步复制 synchronous_mode: on # off | on | quorum synchronous_mode_strict: false synchronous_node_count: 1 # 默认 1 failsafe_mode: false # 默认 false postgresql: use_pg_rewind: false use_slots: true parameters: max_connections: 100 wal_level: replica max_wal_senders: 10 wal_log_hints: on pg_hba: - host all all 0.0.0.0/0 md5 - host replication replicator 127.0.0.1/32 md5 pg_ident: - mapname1 systemname1 pguser1 standby_cluster: host: remote-primary.example.com port: 5432 primary_slot_name: standby_cluster_slot recovery_min_apply_delay: 0 member_slots_ttl: 30min # 默认 30min0 恢复旧行为 slots: permanent_logical_slot_name: type: logical database: my_db plugin: test_decoding permanent_physical_slot_name: type: physical ignore_slots: - name: externally_managed_slot type: logical database: my_db plugin: test_decoding manage_synchronized_standby_slots: false # PostgreSQL 17默认 false十一、修改后的验证与常见问题修改动态配置后建议按以下顺序验证查看生效配置执行patronictl show-config cluster或GET /config确认写入 DCS 的内容符合预期观察节点日志各节点应能在下一个主循环周期内应用新配置若配置了 Postgres 参数Patroni 会触发相应的 reload 或重启流程核对不等式若设置了loop_wait、retry_timeout、ttl确认loop_wait 2 * retry_timeout ttl否则留意 Patroni 日志中的 Violated the rule ... Adjusting 修正信息见 patroni/config.py并发修改保护多人同时edit-config时版本号校验会拒绝后提交者提交失败方需重新拉取最新配置后再改DCS 被清空的恢复只要 Postgres 数据目录中的patroni.dynamic.json缓存存在Patroni 会尝试从缓存恢复动态配置见 patroni/config.py。常见误区提醒slots是哈希表、ignore_slots是数组写反会导致配置解析失败不要把listen、data_dir、connect_address、authentication等本地项放进动态配置它们会被静默丢弃见 patroni/config.py永久逻辑槽只应被 leader 上的应用使用副本节点使用会引发pg_wal膨胀节点name严禁使用__patroni_strict_sync_replica_placeholder__否则会与严格同步模式的内部占位符冲突。十二、延伸阅读docs/patroni_configuration.rst完整静态配置本地 YAML参考理解动态配置与本地配置的分工边界docs/replication_modes.rst同步/异步/quorum 复制模式的原理与选择docs/dcs_failsafe_mode.rstDCS 失联时的自我保护机制docs/standby_cluster.rststandby_cluster 小节的完整搭建指南docs/existing_data.rst将独立实例导入 Patroni 集群涉及永久槽重名用法patroni/config.py动态配置合并、校验、缓存的核心实现patroni/ctl.pypatronictl edit-config/show-config的完整实现patroni/api.pyREST API 中GET/PATCH/PUT /config的实现patroni/global_config.py各全局参数的默认值与读取逻辑。赞分享数据库高可用集群管理运维后端【免费下载链接】patroniA template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes项目地址https://gitcode.com/gh_mirrors/pa/patroni点击查看免费下载相关推荐OpenAPI Generator 配置详解全局参数最佳实践OpenAPI Generator 配置详解全局参数最佳实践 你是否还在为API文档生成效率低而烦恼是否希望通过简单配置实现代码生成的精准控制本文将系统讲开发工具代码生成API设计CLI浏览器端AI抠图革命无需服务器3行代码实现专业级背景移除浏览器端AI抠图革命无需服务器3行代码实现专业级背景移除 在当今数字内容创作时代图像背景移除已成为电商、设计和社交媒体应用中不可或缺的功能。然而传统方案计算机视觉图像处理AI 应用ImagePicker完全配置指南9大核心参数详解与最佳实践ImagePicker完全配置指南9大核心参数详解与最佳实践 ImagePicker是一款完全仿微信的图片选择库提供了多种图片加载接口支持图片旋转、裁剪上一篇彻底解决HTMLBars开发痛点从编译原理到性能优化全指南下一篇Cordova Google Maps插件常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考