数据库高可用集群管理运维后端【免费下载链接】patroniA template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes项目地址https://gitcode.com/gh_mirrors/pa/patroni点击查看免费下载导读本文以当前仓库 docs/releases.rst 官方发布说明为骨架系统梳理 PostgreSQL 高可用方案 Patroni 从 2016 年 0.80 版到 2026 年 4.1.5 版的核心能力演进涵盖 DCS 故障安全模式、quorum 同步复制、Citus 集成、Kubernetes 原生支持、patronictl命令行与 REST API 生态并结合仓库源码如 patroni/ha.py、patroni/global_config.py、patroni/validator.py逐项印证发布说明背后的实现细节。读完本文你将掌握 Patroni 每个重要版本的升级要点、关键配置参数的行为语义以及迁移到 4.x 时必须注意的破坏性变更。一、发布说明文档在仓库中的定位docs/releases.rst是 Patroni 官方文档体系的变更日志中枢全文约 4000 行按版本号倒序组织4.1.5 → 0.80每个版本条目下按New features新特性 / Improvements改进 / Bugfixes缺陷修复 / Stability improvements稳定性改进 / Breaking changes破坏性变更等类别展开。它与其他文档页面相互引用动态配置、同步复制等机制见 docs/dynamic_configuration.rstDCS 故障安全模式专章见 docs/dcs_failsafe_mode.rstCitus 集成专章见 docs/citus.rstKubernetes 部署与角色标签迁移见 docs/kubernetes.rst标签体系tags见 docs/patroni_configuration.rst 中相关章节运维命令见 docs/patronictl.rst。当前仓库实际版本号由 patroni/version.py 中的__version__ 4.1.5定义与发布说明最新条目一致。二、4.x 时代主从术语统一与架构性新能力2.1 4.0.0 —— master 时代的终结2024-08-294.0.0 是发布说明中标注了.. warning::的重大版本完成了去除 master 术语、全面改用 primary 的工作并明确提示升级到 Patroni 4 仅在运行 3.1.0 及以上版本时可靠若主节点故障时其余节点仍运行旧版本直接从更老版本升级到 4 可能产生意外行为。破坏性变更清单发布说明原文要点运维迁移前必读Kubernetes 上默认将role标签设为primary如需保留旧行为可配置kubernetes.leader_label_value与kubernetes.standby_leader_label_value为masterPatroni 角色写入 DCS 时由master改为primaryREST API 返回的角色、/switchover、/failover、/restart请求参数同步调整rolemaster不再被接受/metrics端点不再上报patroni_master指标patronictl所有命令不再接受--master选项改用--leader或--primary自定义复制方法声明式配置中的no_master改为no_leaderpatroni_wale_restore不再接受--no_masterpatroni_barman不再接受--rolemaster所有回调脚本统一以roleprimary参数执行patronictl failover移除自 3.2.0 起废弃的--leader选项自 3.2.0 起废弃的bootstrap.users用户创建功能被彻底移除需改用bootstrap.post_bootstrap钩子。同版本引入的新特性中最具架构意义的是Quorum-based failover基于 quorum 的同步复制。它利用 PostgreSQL 10 的原生 quorum 提交能力通过多个同步备机互相补偿延迟来降低最坏情况延迟同时 Patroni 基于最近收到的事务选择故障转移候选节点防止用户可见的数据丢失。该能力在源码中的映射点包括patroni/global_config.pyis_quorum_commit_mode判断synchronous_mode quorumis_synchronous_mode综合布尔值与 quorum 两种形态patroni/config.pyDCS 配置默认写入synchronous_mode: quorumpatroni/postgresql/sync.py同步备机选择时按sync_priority、sync_state、LSN 排序优先选择sync_priority更高的副本。4.0.0 还新增了Citus 第二节点注册Patroni 维护pg_dist_node中rolereplica、staterunning且无noloadbalance标签的节点列表member_slots_ttl控制成员复制槽在成员 key 缺失后保留多久可配置日志文件权限默认按umaskPostgreSQL 17 beta3 兼容扩展 GUC 校验规则在primary_conninfo中设置dbname逻辑复制槽同步所需patroni --validate-config --ignore-listen-port校验配置时可忽略已被占用的端口wal_log_hints变为可配置当use_pg_rewindoff时可关闭以避免开销。2.2 4.1.x —— 系统化通知、线程池与配置校验完善4.1.x 系列集中在稳定性、systemd 集成与校验工具链的打磨4.1.52026-08-12兼容 PostgreSQL 14.24/15.19/16.15/17.11/18.6新增限制逻辑解码输出插件的output_plugin_librariesGUC将 REST API 连接重置日志降级为DEBUG修复thread_stack_size校验对齐问题aligned值由 65535 修正为 65536此前连守护进程默认的 524288 都会被patroni --validate-config拒绝并允许synchronous_mode接受quorum与 PostgreSQL 风格布尔字符串。这两处修复在源码中均有直接对应patroni/validator.py 的validate_synchronous_mode接受quorum或parse_bool可解析的值patroni/validator.py 的thread_stack_size校验为IntValidator(min65536, base_unitB, aligned65536)守护进程侧 patroni/daemon.py 默认thread_stack_size 524288并执行max(65536, value)兜底。4.1.42026-07-07仅在NOTIFY_SOCKET环境变量存在时才导入并使用 systemd 包避免FileNotFoundError统一pg_replication_slots查询以修复failover/synced值处理引发的KeyError--generate-config依据 PostgreSQL 连接获取的版本剔除不适用的认证参数主节点作为备机启动期间回退使用pg_controldata信息处理pg_rewindpatroni_postgres_timeline指标类型由counter改为gauge其值可能回落如实例未运行时归 0保证客户端后端完全停止后再关闭 watchdog监控查询超时后使用缓存角色避免误降级并强制pg_stat_statements.tracknone以避免昂贵的 GC 调用自动丢弃wal_statuslost的复制槽并重建。4.1.32026-05-05覆盖 Etcd 误标错误码leader 丢失时Unknown→UnavailablePG_VERSION文件缺失如自定义 bootstrap时改从二进制获取版本提前创建PatroniLogger以捕获早期日志systemd 257 要求RELOADING1通知必须携带MONOTONIC_USEC。4.1.22026-04-21支持notify-reloadsystemd 单元类型systemctl reload会等待 Patroni 实际完成配置重载关闭时发送STOPPING1通知从示例 systemd 单元移除NotifyAccessall并在启动 PostgreSQL 时过滤NOTIFY_SOCKET防止 Postgres 向 systemd 发送READY1/STOPPING1干扰状态机。4.1.12026-04-08兼容 Python 3.11 的线程变更——引入全局与 REST API 线程池新增thread_pool_size与restapi.thread_pool_size配置。实现见 patroni/thread_pool.pyPatroniThreadPoolExecutor与全局执行器、patroni/main.py全局池默认 5max(5, ...)兜底与 patroni/api.pyREST API 池为thread_pool_size 1个 worker同时兼容 Python 3.14 与 Etcd v3.6.9/v3.5.28/v3.4.42 的安全修复拓扑读取与 lease keepalive 需认证Patroni 在成员发现与租约续期路径认证并自动重试。4.1.02025-09-23新特性密集——systemd notify 单元类型、REST API/cluster与patronictl list提供 receive/replay LSN 与延迟信息、patronictl demote-cluster/promote-cluster命令、sync_priority标签控制同步备机选举优先级见 patroni/config.py 对nosync/sync_priority的联动校验以及 patroni/postgresql/sync.py 的排序逻辑、patroni --validate-config --print校验通过后打印含环境变量的本地配置、kubernetes.bootstrap_labels初始化/自定义 bootstrap/创建副本等状态下给 Pod 打标签见 patroni/dcs/kubernetes.py 与 patroni/dcs/kubernetes.py、抑制重复心跳日志的配置项、永久复制槽可选cluster_type属性、可配置 HTTPServer头的restapi.server_tokens以及备机就绪探针PostgreSQL 复制且落后主节点不多时才算 ready。2.3 4.0.x —— 同步状态机与复制槽细节修复4.0.72025-09-22为 PostgreSQL 18 RC1 扩展 GUC 校验规则修复 Windows 上localhost解析为 IPv6::1导致监听受限的问题改用127.0.0.1、/configkey 缺失时 REST API 空配置问题、Etcd 不可用时 failsafe 未触发问题、容器PID1下SIGCHLD信号重入死锁、不预留 WAL 的物理槽报 replication slot cannot be advanced 时自动重建、etcd3取消通知导致 stale 数据等。4.0.62025-06-06修复了高优先级前主节点在报告相同 LSN 时仍参与 failover 竞争、PGDATA外postgresql.conf权限遵循 umask、synchronous_modequorum下指定候选节点时仍检查 quorum、Etcd stale 节点比较 raft_term、SIGHUP时无条件更新 PostgreSQL 配置文件、etcd3Unavailable异常应切换节点而非重试同一节点、每次 HA loop 至少刷新一次 etcd3 lease、409 时重查注解、按replay_lsn推进槽、promote 后确保CHECKPOINT完成、避免并发 offline 降级、初始化失败重命名前规范化data_dir防尾部斜杠等。4.0.52025-02-20兼容python-json-logger3.1、Python 3.13、pyinstaller4.4修复 PostgreSQL 9.5 下pg_rewind输出格式与synchronous_standby_names无 num 规格的处理、urlparse多主机变化改用 libpq 的PQconninfoParse()原生封装。patronictl restart --pending只列出真正待重启的成员Patroni 停止时取消长时间任务并清理失败的副本 bootstrap 数据目录patronictl edit-config对含/的集群名以下划线替换。4.0.42024-11-22转向官方维护的py-consul模块保留 python-consul 向后兼容、兼容prettytable3.12.0与ydiff1.4.2修复失败的主节点恢复后on_role_change回调未执行、patronictl list -W线程泄漏、连接串写入新版本参数导致连接错误等问题。4.0.32024-10-18禁用pgaudit下创建用户时的密码日志泄露兼容主节点为 v4 之前版本的混合部署从/memberskey 取xlog_location无 Patroni validator 的合法 GUC 仍通过postgres --describe-config校验K8s 409 状态时重查注解支持 PostgreSQL 17 的sslnegotiation。4.0.22024-09-17修复复制槽推进引入的xmin保留问题不活跃物理槽持NOT NULLxmin 时重建、启动阶段未处理的DCSError先确保 DCS 连通再检查节点名唯一性、恢复被pg_ctl传入的CMDLINE_OPTIONSGUC、synchronous_standby_names的ANY/FIRST双引号规则、keepalive 值越界等。4.0.12024-08-30修复name含大写或特殊字符时为自身创建多余复制槽的问题。三、3.x 时代Citus、failsafe 与生态补齐3.1 3.0.0 —— DCS failsafe 与 Citus 集成2023-01-303.0.0 发布说明开篇即点明两大主题Citus 集成与在主节点不降级的前提下挺过临时 DCS 故障。同时声明这是最后一个支持 Python 2.7 的版本RAFT 支持进入尽力维护的废弃状态。DCS failsafe 模式启用后集群可在 DCS 短暂不可用期间继续存活而不降级主节点详细机制见 docs/dcs_failsafe_mode.rst。相关行为在 patroni/ha.py 的 HA 状态机与 patroni/global_config.py 的check_mode(failsafe_mode)中体现。Citus 支持Patroni 可方便地部署与管理带 HA 的 Citus 集群详见 docs/citus.rst 与 patroni/postgresql/mpp/citus.py。移除patronictl scaffold它只是运行 standby cluster 的 hacky 方式。3.2 3.1.x 与 3.2.x —— 动态配置与标签语义3.1.02023-08-03变更restapi.keyfile/certfile语义不再作为客户端证书回退若restapi.verify_clientrequired则必须在ctl段提供有效客户端证书新增可配置 Pod 角色标签kubernetes.leader_label_value/follower_label_value/standby_leader_label_value为 4.0 的 primary 迁移铺路patroni --validate-config对 DCS、bootstrap.dcs、ctl、restapi、watchdog各段校验大幅增强启动 Postgres 时若其在恢复期间崩溃则以非恢复模式启动缩短恢复时间、避免无谓的 timeline 递增避免max_connections等参数校验失败时静默使用默认值改为显式告警PGDATA内文件权限遵循目录权限。3.1.12023-09-20修复 promote 后 failsafe 状态未重置导致新主自降级、同步模式无副本流时未真正激活、kubernetes.standby_leader_label_value从未生效等问题。3.2.02023-10-25发布说明明确loop_wait 2*retry_timeout ttl强制规则与最小值loop_wait2、retry_timeout3、ttl20违反时自动调整并告警——这是 Patroni 心跳拓扑的核心约束。新增tags.failover_priorityleader 竞争中的偏好度、patroni --generate-config [--dsn DSN]与--generate-sample-config、REST API 专用连接避免压力下阻塞心跳主循环、永久物理复制槽与逻辑槽行为对齐pg_replication_slot_advance()推进restart_lsn、patronictl --dcs指定命名空间、自定义 bootstrap 参数映射支持并预告bootstrap.users将在 4.0.0 移除。3.2.22024-01-17修复 Consul 同步读、pending_restart参数复位后未重载、patronictlfailover 确认提示逻辑反转、leader 被列入 failover 候选、Citus 幂等创建、PyInstaller 冻结问题等。3.3 3.3.x —— 工具链兼容与可观测性3.3.02024-04-04新增 Zookeeperauth_data认证、patroni_barman集成脚本可作自定义 bootstrap/复制方法或on_role_change回调见 docs/tools_integration.rst、json日志格式需python-json-logger2.0.2见 patroni/log.py 相关实现、pending_restart_reason信息patronictl list与/patroni端点展示触发pending_restart的参数名与 diff、nostream标签不通过复制协议流式传输 WAL依赖restore_command归档恢复并禁用本节点及其级联副本的永久逻辑槽复制。同时警告所有旧版 Patroni 与ydiff1.3不兼容可升级、安装ydiff1.3或安装cdiff模块解决。3.3.22024-07-11修复synchronous_mode关闭时未按用户配置设置synchronous_standby_names的问题明文 Postgres 同步复制回归、PG16 备机上逻辑槽因 horizon 失效时强制重建copy、逻辑槽推进与复制间的竞态。四、2.x 时代Kubernetes DCS、Etcd v3 与复制槽体系2.0.02020-09-02兼容 PostgreSQL 13、支持多同步备机synchronous_node_count默认 1synchronous_modeoff时无效、Etcd v3gPRC-gateway需显式创建etcd3段、纯 RAFT DCS无需 Etcd/Consul/Zookeeper需 3 节点或 21 的patroni_raft_controller、pre_promotefencing脚本同步执行非零退出则释放 leader lock、配置目录YAML 按字母序加载、GUC 高级校验不支持的参数移除或修正、Consulservice_tags、Zookeeper SSL、自定义 bootstrapno_params、pg_rewind --restore-target-wal、基于时间线差异的智能 rewind 判断、K8s 绕过 service 直连 API、HA loop 同步、/readiness与/liveness端点、DELETE /switchover、patronictlASCII 拓扑图等。2.1.x2.1.0 实现逻辑复制槽跨 failover/switchover 存续、REST API allowlist、unix socket 复制连接、Prometheus/metrics端点patroni/api.py 中/metrics相关实现、日志降噪每 HA loop 一行2.1.2 兼容 psycopg3、新增dcs_last_seen字段、释放 leader lock 时机优化、Zookeeperset_acls2.1.5 声明 Etcd v3 生产就绪、patronictl history、PATRONICTL_CONFIG_FILE、postgresql.proxy_address、HEAD 请求支持2.1.7 修复 Debian buster/Ubuntu bionic 构建问题。五、1.x 时代基础能力成形同步复制、自定义 bootstrap、暂停模式1.02016-07-05引入全局动态配置/configREST API 端点 DCS 存储pending_restart标志这是后续所有运维自动化的基石升级 v0.90 及以下时必须先升级全部副本再升级主节点凭证不再存入 DCS。1.22016-12-13新增synchronous_mode管理synchronous_standby_names主故障时只 failover 到同步中的备机保证无用户可见事务丢失master_start_timeout与starting状态post_init钩子PostgreSQL 9.6 支持。1.32017-07-27自定义 bootstrap替代initdb支持 PITR 与备份恢复见 docs/replica_bootstrap.rst、智能pg_rewind决策比较 WAL 位置而非固定规则集、synchronous_mode_strict无备机时也不停用同步复制写入要么双节点持久化要么根本不发生、patronictl配置编辑、Linux watchdog 支持见 docs/watchdog.rst、PostgreSQL 10 兼容。1.42018-01-10Kubernetes 作为 DCSEndpoints 元数据存配置与 leader keyPod metadata 存成员数据支持 ConfigMappip 安装不再自动携带 DCS 依赖需显式pip install patroni[etcd,kubernetes]等。1.5.xstandby cluster跨数据中心级联复制见 docs/standby_cluster.rst、Consul 服务注册、永久复制槽、pgBackRest 支持、Windows 实验支持、日志系统灵活化。1.6.xPostgreSQL 12 兼容recovery.conf消失恢复参数转为 GUCPatroni 解析postgresql.auto.conf移除 standby/recovery 参数、pg_rewind免 superuserpostgresql.authentication.rewind段、IPv6、Kerberos、/health//read-only//read-write端点、--wait选项、patroni --version。六、0.x 时代多 DCS 与级联复制的起点0.802016-03-14replicatefrom/clonefrom标签实现级联复制no_master: true支持无复制连接时初始化副本S3/FTP 快照场景计划性 failover。0.902016-04-27Consul 支持与 Etcd、Zookeeper 并列noloadbalance标签clonefrom改为布尔标签多候选时随机选择系统脚本改进避免停止 Patroni 时误杀 PostgreSQL环境变量配置读取。七、贯穿所有版本的关键机制源码印证发布说明中的高频关键词在源码中均有实体支撑以下梳理最值得关注的几组7.1 心跳与超时拓扑3.2.0 强制的loop_wait 2*retry_timeout ttl规则定义了 HA loop 的节律loop_wait是每次主循环的间隔retry_timeout是 DCS 操作的重试窗口ttl是 leader key 的租约有效期。这组参数直接决定故障检测速度与误判概率配置低于最小值时 Patroni 会自动调整并告警。相关的 DCS 实现分散在 patroni/dcs/ 各文件etcd/etcd3/consul/zookeeper/kubernetes/raft。7.2 同步复制状态机is_synchronous_modepatroni/global_config.py综合布尔与 quorum 两种形态且 standby cluster 中自动忽略_maybe_enable_synchronous_modepatroni/ha.py 附近负责在同步模式开启/关闭时同步更新synchronous_standby_names。备机选举排序sync_priority→sync_state→ LSN在 patroni/postgresql/sync.py 实现。7.3 配置校验体系patroni --validate-config从 1.6.5 的首版草案演进为覆盖全部配置段的 schema 校验patroni/validator.py。4.1.5 的两处修复正说明了该校验器的严谨程度thread_stack_size要求min65536且按 65536 对齐patroni/validator.pysynchronous_mode显式接受quorum与布尔字符串patroni/validator.py。7.4 复制槽管理永久复制槽1.5.1 引入在 failover/switchover 后保留pg_replication_slot_advance()推进restart_lsn3.2.0member_slots_ttl控制成员槽保留时长4.0.0wal_statuslost的槽被丢弃重建4.1.4。这些逻辑集中在 patroni/postgresql/slots.py 与 HA 状态机配合。7.5 运维工具链patronictlpatroni/ctl.py与 REST APIpatroni/api.py是发布说明反复提及的两大入口覆盖list、switchover、failover、restart、reload、pause/resume、edit-config、flush、history、demote-cluster/promote-cluster等操作监控侧/metricsPrometheus、/health、/readiness、/liveness、/replica?lag等端点构成完整的健康检查矩阵。八、升级路线与注意事项总结综合发布说明社区推荐的升级路径与关注点如下跨大版本迁移进入 4.x 前先确保集群运行 3.1.0若仍在使用master相关术语的脚本、监控与 K8s 标签务必提前对照 4.0.0 的破坏性变更清单逐一适配。Python 版本要求3.0.0 是最后支持 Python 2.7 的版本3.0.2 起要求 Python 3.6后续版本依次验证 Python 3.11/3.12/3.13/3.14 兼容性。依赖锁定注意ydiff1.3对旧版的不兼容警告、py-consul取代python-consul、psycopg2/psycopg3二选一安装方式1.6.0 起从 requirements 移除见 requirements.txt 与 docs/installation.rst。心跳参数loop_wait/retry_timeout/ttl满足loop_wait 2*retry_timeout ttl低于最小值会被强制上调。每次升级前以发布说明为准核对该版本的新特性、稳定性改进与缺陷修复清单尤其关注涉及同步复制、复制槽、watchdog 与 systemd 通知的条目——这些模块的行为细节密集且相互耦合。九、结语从 0.80 的 Etcd/Zookeeper 双 DCS 起步到 4.1.5 的 Python 3.14、PostgreSQL 18 兼容与 quorum 提交成熟落地docs/releases.rst完整记录了 Patroni 十年来的每一次能力跃迁级联复制、同步复制与严格模式、自定义 bootstrap、暂停模式、Kubernetes 原生 DCS、Etcd v3 与纯 RAFT、逻辑复制槽跨故障转移、DCS failsafe、Citus 集成、多同步备机与 quorum 提交以及 master→primary 的术语统一。对运维与开发而言这份文档既是升级手册也是理解 HA 状态机设计取舍的第一手资料配合仓库源码尤其 patroni/ha.py、patroni/global_config.py、patroni/validator.py、patroni/postgresql/sync.py阅读可以清晰地看到每一条 release note 背后对应的代码路径与设计意图。赞分享数据库高可用集群管理运维后端【免费下载链接】patroniA template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes项目地址https://gitcode.com/gh_mirrors/pa/patroni点击查看免费下载相关推荐FiftyOne 版本发布说明深度解析从 0.2.0 到 1.22.0 的功能演进与多模态数据平台之路FiftyOne 版本发布说明深度解析从 0.2.0 到 1.22.0 的功能演进与多模态数据平台之路 本文以 FiftyOne 官方 release not人工智能计算机视觉数据集数据可视化数据标注模型评测Karmada v1.11 版本发布说明深度解读从 1.11.0 到 1.11.9 的完整演进与源码佐证Karmada v1.11 版本发布说明深度解读从 1.11.0 到 1.11.9 的完整演进与源码佐证 本篇基于仓库中的 CHANGELOG 1.11.md云原生多集群集群管理微服务FoundationDB 1.0 系列发布说明全解析从 Alpha 5 到 1.0.0 商用版的演进之路FoundationDB 1.0 系列发布说明全解析从 Alpha 5 到 1.0.0 商用版的演进之路 本文基于 release notes 100.rst分布式数据库KV存储数据库后端上一篇CppCMS 项目推荐下一篇Button2Arduino/ESP按钮库项目推荐创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
