数据库高可用集群管理运维后端【免费下载链接】patroniA template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes项目地址https://gitcode.com/gh_mirrors/pa/patroni点击查看免费下载本文以 Patroni 官方 YAML 配置文档 为骨架系统梳理 Patroni 配置文件中的全部核心参数全局与日志、bootstrap 初始化、各 DCSConsul/Etcd/Etcdv3/ZooKeeper/Exhibitor/Kubernetes/Raft、PostgreSQL 运行参数、REST API、CTL、Watchdog 与 Tags。读者读完本文后将能够独立编写一份可运行的多节点 Patroni 配置文件并理解每个参数在源码层面的实际作用与约束。Patroni 使用单个 YAML 文件描述节点的完整运行状态配置文件既包含节点自身的身份与网络信息也包含集群级动态配置的种子值。本文中所有参数均以当前仓库gh_mirrors/pa/patroni实际支持的配置为准并配套给出仓库根目录下 postgres0.yml、postgres1.yml、postgres2.yml 三份可运行示例作为参照。一、Global/Universal每个 Patroni 节点必备的全局参数无论使用哪种 DCS以下全局参数都直接决定节点如何参与集群thread_pool_sizePatroni 用于执行异步任务、以及在 leader race 或 failsafe 检查时通过 REST API 与其他成员通信的线程池大小。最小值为5默认值为5。thread_stack_size指定 Patroni 启动线程所使用的栈大小。取值必须按64kB对齐最小值为64kBPatroni 默认设置为512kB。name当前节点host的名称在集群内必须唯一。__patroni_strict_sync_replica_placeholder__被 Patroni 保留用于内部实现同步复制占位不能用作节点名。该名称会写入 DCS 的成员键中是集群区分各节点的标识。namespace配置存储DCS中 Patroni 保存集群信息的路径前缀。默认值为/service。集群的实际数据存放在/namespace/scope/config等路径下。scope集群名称。所有属于同一集群的节点必须使用相同的scopePatroni 据此将不同集群的数据在 DCS 中隔离。site可选字符串表示该节点所在的物理位置如数据中心、可用区或地域。配置后 Patroni 会将其记录到成员元数据中用于自动故障转移时优先将主节点切换到与最近已知 leader 同site的本地节点副本 bootstrap 与patronictl reinit时优先选择本地克隆源。从源码看全局参数同样支持通过环境变量覆盖详见 patroni/config.py 中对name、namespace、scope、site、thread_pool_size、thread_stack_size的环境变量读取逻辑。对应的环境变量为PATRONI_NAME、PATRONI_NAMESPACE、PATRONI_SCOPE、PATRONI_SITE、PATRONI_THREAD_POOL_SIZE、PATRONI_THREAD_STACK_SIZE相关完整清单参见 docs/ENVIRONMENT.rst。一个最小化的全局配置片段如下取自 postgres0.ymlscope: batman #namespace: /service/ name: postgresql0二、Log日志格式、滚动与去重Patroni 的日志配置集中在log一节支持两段式异步日志先写入内存队列再由独立线程刷到 stderr 或文件type日志格式可选plain或json。使用json需要安装jsonlogger见仓库 extras/README.md 中的依赖说明。默认值为plain。level总体日志级别默认INFO遵循 Python logging 标准级别。traceback_leveltraceback 可见的最低级别默认ERROR。若希望仅在log.levelDEBUG时才输出 traceback可将其设为DEBUG。format日志格式串。plain类型下为字符串可引用的属性参见 PythonLogRecord attributes。json类型下既可以是字符串也可以是列表——列表每个元素对应一个 LogRecord 属性只需写字段名省略%(与)若希望以不同的 key 名输出字段则使用字典字典的 key 为日志字段、值为希望输出到日志中的名称。默认值为%(asctime)s %(levelname)s: %(message)s。dateformat日期时间格式串对应logging.Formatter.formatTime()。static_fields为日志追加静态字段仅type: json时可用。max_queue_size内部日志队列最大记录数。默认1000条官方说明足以保留过去约 1 小时 20 分钟的日志。源码中默认值定义见 patroni/log.py。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后HA 循环除非 leader 发生变化将不再产生日志这部分信息会从日志中消失。该特性的实现位于 patroni/log.py当记录为心跳消息且与上一条相同时直接将本条记录置空。官方给出的 JSON 日志配置示例log: type: json format: - message - module - asctime: timestamp - levelname: level static_fields: app: patroni对应的环境变量前缀为PATRONI_LOG_*如PATRONI_LOG_TYPE、PATRONI_LOG_LEVEL、PATRONI_LOG_FORMAT、PATRONI_LOG_STATIC_FIELDS、PATRONI_LOG_MAX_QUEUE_SIZE、PATRONI_LOG_FILE_NUM、PATRONI_LOG_FILE_SIZE、PATRONI_LOG_LOGGERS、PATRONI_LOG_DEDUPLICATE_HEARTBEAT_LOGS见 docs/ENVIRONMENT.rst。其中static_fields与loggers属于需要解析为字典的配置解析逻辑见 patroni/config.py。三、Bootstrap集群初始化配置与动态配置的种子bootstrap一节只在集群尚未初始化时生效用于定义“第一个节点如何把集群拉起来”。重要提示一旦 Patroni 完成首次集群初始化并将配置写入 DCS之后对 YAML 中bootstrap.dcs的任何修改都不会再生效如需修改必须使用patronictl edit-config或 Patroni REST API见 docs/dynamic_configuration.rst 与 docs/patronictl.rst。bootstrap下的关键子项bootstrap.dcs新集群初始化后本节内容会被写入配置存储的/namespace/scope/config成为集群的全局动态配置。可放入 docs/dynamic_configuration.rst 中描述的任何参数例如ttl、loop_wait、retry_timeout、maximum_lag_on_failover、synchronous_mode、postgresql含use_pg_rewind、pg_hba、parameters、recovery_conf等。bootstrap.method自定义 bootstrap 脚本。详见 docs/replica_bootstrap.rst 中的自定义 bootstrap 方法说明。指定initdb时回退为默认的initdb命令配置文件没有method参数时同样触发默认initdb。bootstrap.initdb可选传给 initdb 的选项列表注意需要写成 YAML 列表->bootstrap: dcs: ttl: 30 loop_wait: 10 retry_timeout: 10 maximum_lag_on_failover: 1048576 postgresql: use_pg_rewind: true pg_hba: - host replication replicator 127.0.0.1/32 md5 - host all all 0.0.0.0/0 md5 initdb: - encoding: UTF8 ->authentication: replication: username: replicator password: rep-pass superuser: username: postgres password: patroni rewind: # Has no effect on postgres 10 and lower username: rewind_user password: rewind_password对应的环境变量为PATRONI_SUPERUSER_USERNAME、PATRONI_SUPERUSER_PASSWORD、PATRONI_REPLICATION_USERNAME、PATRONI_REPLICATION_PASSWORD、PATRONI_REWIND_USERNAME、PATRONI_REWIND_PASSWORD及各自的*_SSLMODE等 SSL 系列变量。10.2 回调与地址callbacks在特定动作时执行的脚本Patroni 会传入 action、role 与 cluster name可参考 patroni/scripts/aws.py 了解回调脚本的编写方式on_reload触发配置重载时执行on_restartPostgres 重启角色不变时执行on_role_changePostgres 被提升或降级时执行on_startPostgres 启动时执行on_stopPostgres 停止时执行。connect_address其他节点和应用访问 Postgres 的 IP 地址 端口。proxy_address与 Postgres 相邻运行的连接池如 pgbouncer的访问地址其值以proxy_url写入 DCS 的成员键用于服务发现。10.3 复制方法、数据目录与二进制create_replica_methods将节点变成新副本的创建方法有序列表。basebackup是默认方法其他方法视为脚本每个脚本需要各自的配置小节。详见自定义副本创建方法文档docs/replica_bootstrap.rst。data_dirPostgres 数据目录位置既可以是已存在的数据目录也可以由 Patroni 初始化。config_dirPostgres 配置目录位置默认等于数据目录必须对 Patroni 可写。bin_dir可选PostgreSQL 二进制pg_ctl、initdb、pg_controldata、pg_basebackup、postgres、pg_isready、pg_rewind所在路径。未提供或为空字符串时使用 PATH 查找可执行文件。bin_name可选若使用自定义 Postgres 发行版可覆盖各二进制名pg_ctl、initdb、pg_controldata、pg_basebackup、postgres、pg_isready、pg_rewind。10.4 监听与连接listenPostgres 监听的 IP 地址 端口若使用流复制必须能被集群其他节点访问。支持多个逗号分隔的地址端口只需在最后一个地址后以冒号追加例如listen: 127.0.0.1,127.0.0.2:5432。Patroni 使用该列表中的第一个地址建立到本地 PostgreSQL 节点的连接。use_unix_socket指定 Patroni 是否优先用 Unix socket 连接集群默认false。若定义了unix_socket_directoriesPatroni 使用其中第一个合适的值连接集群无可用的再回退 TCP若postgresql.parameters中未指定unix_socket_directoriesPatroni 假定使用默认值并从连接参数中省略host。仓库示例 postgres0.yml 通过parameters.unix_socket_directories: ..data_dir 的父目录配合使用。use_unix_socket_repl指定复制用户集群连接是否优先使用 Unix socket默认false。行为同上。pgpass.pgpass口令文件路径。Patroni 在执行 pg_basebackup、post_init 脚本等场景前创建此文件位置必须对 Patroni 可写。recovery_conf配置 follower 时写入 recovery.conf 的附加配置。custom_conf可选的自定义postgresql.conf路径将替代postgresql.base.conf被使用。文件必须在所有集群节点存在、对 PostgreSQL 可读并从其所在位置被真实的postgresql.confinclude。Patroni 不会监视该文件变化也不会备份它其设置仍可被 Patroni 自身的配置机制覆盖见 docs/patroni_configuration.rst。10.5 参数与角色化覆盖parametersPostgres 的 GUC 配置参数格式{ssl: on, ssl_cert_file: cert_file}。parameters_primary可选primary 角色专用参数覆盖与基础parameters合并并覆盖之。parameters_replica可选replica 角色专用参数覆盖合并并覆盖基础参数。parameters_standby_leader可选standby_leader 角色专用参数覆盖合并并覆盖基础参数。10.6 pg_hba / pg_ident / pg_hosts 管理pg_hbaPatroni 用于生成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_hba_primary / pg_hba_replica / pg_hba_standby_leader可选角色化 pg_hba 条目完全替换不合并pg_hba未定义时使用pg_hba。pg_ident用于生成pg_ident.conf的行列表ident_file被设置为非默认值时忽略- mapname1 systemname1 pguser1- mapname1 systemname2 pguser2pg_ident_primary / pg_ident_replica / pg_ident_standby_leader可选角色化替换版本规则同 pg_hba。pg_hosts仅 PostgreSQL 19用于生成pg_hosts.conf的行列表hosts_file被设置为非默认值时忽略。pg_hosts_primary / pg_hosts_replica / pg_hosts_standby_leader可选角色化替换版本。10.7 启动控制与 pg_rewindpg_ctl_timeoutpg_ctl 执行start、stop、restart的等待时间默认 60 秒。use_pg_rewind前 leader 以副本身份重新加入集群时尝试使用 pg_rewind。集群必须用data page checksumsinitdb 的--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。使用progress选项时pg_rewind输出会实时流式写入 Patroni 日志。示例postgresql: rewind: - debug - progress - sync-method: fsyncremove_data_directory_on_rewind_failure启用后pg_rewind 失败时 Patroni 会删除 PostgreSQL 数据目录并重建副本否则尝试跟随新 leader。默认false。remove_data_directory_on_diverged_timelines当 Patroni 发现时间线分叉且原主库无法从新主库开始流复制时删除数据目录并重建副本适用于无法使用 pg_rewind 的场景。对 PostgreSQL v10 及更早版本做时间线分叉检查时Patroni 会使用复制凭据连接postgres数据库因此 pg_hba.conf 中需要允许此类访问。默认false。replica_method为create_replica_methods中 basebackup 之外的每个方法添加同名配置小节至少包含command脚本完整路径。其余配置参数以parametervalue形式传给脚本。仓库示例 postgres1.yml 展示了basebackup小节的额外选项写法- verbose、- max-rate: 100M。pre_promote故障转移期间获取 leader 锁之后、提升副本之前的 fencing 脚本。脚本以非零码退出时Patroni 不提升该副本并从 DCS 移除 leader key。before_stop停止 Postgres 之前立即执行的脚本。与回调不同此脚本同步执行会阻塞关闭流程直到完成。脚本返回码不影响后续是否继续关闭。十一、REST API健康检查与集群通信端点restapi.thread_pool_size处理 REST API 请求的线程池大小最小5默认5。restapi.connect_address访问 Patroni REST API 的 IP或主机名 端口。集群所有成员必须能连接到该地址因此除非是 localhost 演示环境否则不能使用localhost或127.0.0.1这类回环地址。它可作为 HTTP 健康检查端点、用户查询端点也是 leader 选举期间成员间健康检查的目标如判断 leader 是否存活、是否有节点的 WAL 位置领先等。该地址写入 DCS 的成员键从而可以将成员名解析为其 REST API 地址。restapi.listenPatroni 监听 REST API 的 IP或主机名 端口用于 HAProxy或其他支持 HTTP OPTION/GET 检查的负载均衡器的健康检查与成员间通信。restapi.authentication可选username保护不安全 REST API 端点的 Basic-auth 用户名password对应密码。restapi.certfile可选PEM 格式证书文件。未指定或留空时 API 服务器不带 SSL。restapi.keyfile可选PEM 格式私钥文件。restapi.keyfile_password可选解密 keyfile 的口令。restapi.cafile可选校验客户端证书时使用的 CA_BUNDLE 文件。restapi.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。restapi.verify_client可选none默认、optional或requirednone不检查客户端证书required所有 REST API 调用都需要客户端证书optional所有不安全的 REST API 端点需要客户端证书。required时证书签名校验通过即视为客户端认证成功optional时仅对PUT、POST、PATCH、DELETE请求检查客户端证书。restapi.allowlist可选允许调用不安全 REST API 端点的主机集合元素可以是主机名、IP 地址或 CIDR 网段。默认allow all。一旦设置了allowlist或allowlist_include_members未包含在内的请求一律拒绝。restapi.allowlist_include_members可选设为true时允许 DCS 中注册的其他集群成员IP/主机名取自成员api_url访问不安全端点。注意操作系统可能对出站连接使用不同 IP。restapi.http_extra_headers / https_extra_headers可选让 REST API 服务器在 HTTP/HTTPS 响应中附加额外头。HTTPS 场景会同时附加http_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; modeblock X-Content-Type-Options: nosniff cafile: ca file certfile: cert keyfile: key https_extra_headers: Strict-Transport-Security: max-age31536000; includeSubDomainsrestapi.request_queue_size可选REST API TCP socket 的请求队列大小队列满后后续请求返回 Connection denied 错误。默认值 5。restapi.handshake_timeout可选单个客户端完成 TLS 握手的最长时间秒超时连接被关闭仅当设置certfile时生效。默认 2。restapi.request_timeout可选单个客户端发送请求与读取响应的最长时间秒静默超时的连接被关闭。默认 5。restapi.server_tokens可选配置ServerHTTP 头的值Minimal仅包含 Patroni 版本如Patroni/4.0.0ProductOnly仅包含产品名PatroniOriginal默认暴露原始行为显示 BaseHTTP 与 Python 版本如BaseHTTP/0.6 Python/3.12.3。警告restapi.connect_address必须能被给定 Patroni 集群的所有节点访问leader race 期间 Patroni 内部用它寻找复制延迟最小的节点。另外若启用客户端证书校验restapi.verify_client: required必须同时在ctl.certfile、ctl.keyfile、ctl.keyfile_password提供有效的客户端证书否则 Patroni 无法正常工作。十二、CTLpatronictl 客户端连接配置ctl节可选配置patronictl访问 REST API 的方式authentication.username / authentication.password访问受保护 REST API 端点的 Basic-auth 凭据未提供时使用 REST API 的username/password参数值。insecure允许不校验 SSL 证书连接 REST API。cacert校验 REST API SSL 证书时使用的 CA_BUNDLE 文件或目录未提供时使用 REST API 的cafile值。certfilePEM 格式客户端证书。keyfilePEM 格式客户端私钥。keyfile_password解密客户端 keyfile 的口令。对应环境变量为PATRONICTL_CONFIG_FILE配置文件位置与PATRONI_CTL_USERNAME、PATRONI_CTL_PASSWORD、PATRONI_CTL_INSECURE、PATRONI_CTL_CACERT、PATRONI_CTL_CERTFILE、PATRONI_CTL_KEYFILE、PATRONI_CTL_KEYFILE_PASSWORD。十三、Watchdog硬件看门狗保护modeoff、automatic或requiredoff禁用 watchdogautomatic可用则使用不可用则忽略required除非成功启用 watchdog否则节点不能成为 leader。devicewatchdog 设备路径默认/dev/watchdog。safety_marginwatchdog 触发与 leader key 过期之间的安全余量秒。仓库示例 postgres0.yml 的注释给出了典型配置#watchdog: # mode: automatic # Allowed values: off, automatic, required # device: /dev/watchdog # safety_margin: 5十四、Tags节点行为标签与自定义元数据clonefromtrue或false。为true时其他节点可能优先选择从该节点 bootstrap执行pg_basebackup。存在多个clonefrom: true节点时随机选择。默认false。noloadbalancetrue或false。为true时节点对GET /replicaREST API 健康检查返回 HTTP 503从而被排除在负载均衡之外。默认false。replicatefrom另一个副本的名称用于支持级联复制。nosynctrue或false。为true时该节点永远不会被选为同步副本。sync_priority整数synchronous_mode为on时控制同步副本选择优先级值越高越优先。为 0 或负数时节点不允许被写入 PostgreSQL 的synchronous_standby_names等价于nosync: true。注意该参数与pg_stat_replication视图报告的sync_priority含义相反。nofailovertrue或false控制节点是否允许参与 leader race 并成为 leader。默认false即可以参与。failover_priority整数控制故障转移优先级。在收到/重放了相同 WAL 量时值越高越优先但 receive/replay LSN 更高的节点无论如何都优先。为 0 或负数时节点不允许参与 leader race等价于nofailover: true。已知限制failover_priority目前不适用于基于 quorum 的同步复制见 docs/replication_modes.rst。nostreamtrue或false。为true时节点不使用复制协议流式拉取 WAL而依赖归档恢复需配置restore_command与pg_wal/pg_xlog轮询。同时会禁用该节点及其所有级联副本上永久逻辑复制槽的复制与同步。设置在主节点上无效。警告nofailover与failover_priority只提供其一。nofailover: true等价于failover_priority: 0nofailover: false等价于优先级 1。除预定义标签外还可以添加自定义标签tags: key1: true key2: false key3: 1.4 key4: RandomString标签在 REST API 与patronictl list中可见也可用于检查实例健康若某实例未定义该标签或标签值与查询值不匹配健康检查将返回 HTTP 503。仓库示例 postgres0.yml 展示了noloadbalance、clonefrom、nostream的默认写法。十五、配置文件的典型结构总结综合上述所有小节一份完整的多节点 Patroni YAML 配置文件通常按以下顺序组织参考 postgres0.ymlscope: cluster-name name: unique-node-name restapi: listen: ip:port connect_address: ip:port etcd: # 或 consul / zookeeper / kubernetes / raft 之一 host: host:port bootstrap: dcs: # 集群动态配置种子初始化后写入 DCS ttl: 30 loop_wait: 10 retry_timeout: 10 maximum_lag_on_failover: 1048576 postgresql: use_pg_rewind: true pg_hba: - host replication replicator 127.0.0.1/32 md5 - host all all 0.0.0.0/0 md5 initdb: - encoding: UTF8 ->赞分享数据库高可用集群管理运维后端【免费下载链接】patroniA template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes项目地址https://gitcode.com/gh_mirrors/pa/patroni点击查看免费下载相关推荐Patroni动态配置详解高可用PostgreSQL集群管理指南Patroni动态配置详解高可用PostgreSQL集群管理指南 动态配置概述 Patroni作为PostgreSQL高可用解决方案其核心特性之一就是支持动数据库高可用集群管理运维后端Patroni配置文档生成自动化PostgreSQL高可用集群配置的完整指南Patroni配置文档生成自动化PostgreSQL高可用集群配置的完整指南 Patroni是一款强大的PostgreSQL高可用性解决方案能够自动化管理P数据库高可用集群管理运维后端Patroni环境变量配置详解全方位掌握高可用PostgreSQL集群管理Patroni环境变量配置详解全方位掌握高可用PostgreSQL集群管理 概述 Patroni作为PostgreSQL高可用解决方案的核心组件提供了丰富的数据库高可用集群管理运维后端上一篇解锁NixOS与Flakes生态从模块到社区高级实践下一篇从理论到实践Awesome Typography中的字体设计完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考