PostgreSQL 复制与高可用系列（六）：Patroni生产级高可用集群部署——自动容灾与 K8s 集成

前五期完成了从物理流复制到逻辑复制、从 WAL 内核到 PITR 备份恢复的全链路学习。每一期都在夯实一个核心理念：高可用不仅仅是一句口号，而是由一套环环相扣的技术体系保障的运行韧性。 但前五期的所有知识还存在一个缺口：故障切换需要人工介入。当主库在凌晨三点宕机时，依赖值班工程师执行pg_ctl promote的方式既慢又不安全。第六期将填补这个缺口——全面系统地介绍 Patroni，这款 PostgreSQL 生态中最流行的高可用自动化管理工具。

一、为什么需要 Patroni

1.1 传统方案的痛点

前五期中，我们已经掌握了手动搭建流复制集群的全部技能，包括配置同步/异步模式、修复pg_rewind回切等。然而，仅靠手工运维，会持续面临三个令人头疼的问题：

• 主库故障时，切换需要人工介入：DBA 需要登录备库执行pg_ctl promote、确认新主库并重新配置其他备库的primary_conninfo。RTO 取决于人的响应速度，通常在数分钟到数十分钟之间，且在凌晨故障时会被拉得更长。 最令人担忧的是：如果故障发生在深夜，RTO 可能被拉长到小时级，甚至需要等工程师醒来。
• 脑裂风险难以消除：流复制本身没有选主机制。当网络分区发生时，旧主库继续接收写入，新提升的备库也在接收写入，两套数据同时在线且产生分歧——后期很难恢复。
• 配置变更需要逐节点手动操作：修改流复制参数或集群规模时，需要在每个节点上分别编辑配置文件并重启，极易出现人为疏漏。

Patroni 的核心价值：将这些令人头疼的操作——故障检测、选主、切换、配置同步、备库重建——全部自动化，让 DBA 从”应急抢险”转向”架构设计”。

流复制解决的是数据同步问题（技术能力），Patroni 解决的是故障切换的自动化问题（运维闭环）。二者的关系是：流复制是 Patroni 赖以工作的数据同步底座，Patroni 则是流复制的自动化管理中枢。

1.2 Patroni 是什么

Patroni 是一个用 Python 编写的 PostgreSQL 高可用管理工具，起源于 Compose 公司的 Governor 项目，经过社区持续开发后成为业界事实标准。它在每个数据库节点上运行一个 Patroni 进程，控制本地的 PostgreSQL 实例，同时通过一个分布式配置存储（DCS，Distributed Configuration Store）来协调集群状态和领导选举。

核心设计理念：数据库的自治化运维——数据库的健康检查、角色切换、配置更新等由控制器自动完成。

DCS 在 Patroni 架构中的作用，可以理解为以下三个维度：

二、Patroni 架构全景

2.1 核心组件

2.2 故障切换的时间线

当主库宕机时，Patroni 的自动故障转移过程如下：

T+0s:  主库（PostgreSQL进程或所在主机）崩溃
T+10s: Patroni 通过健康检查检测到主库无响应（取决于 loop_wait 配置）
T+30s: Leader key 在 DCS 中的 TTL 租约超时，Leader 锁自动释放
T+31s: 各备库的 Patroni 竞争 Leader 锁
T+32s: 某一备库赢得锁，执行 pg_promote 将自己提升为新主库
T+33s: 其他备库重新配置，将新主库设为上游，继续流复制
T+35s: HAProxy 通过 Patroni REST API 感知到主库变化，开始将写流量路由到新主库

故障转移可在约 35 秒内完成。如果业务对 RTO 要求更严，可调低ttl和loop_wait，但需要谨慎权衡网络波动带来的误切换风险。

2.3 Watchdog 如何防止脑裂

脑裂（Split-Brain）是最危险的高可用故障场景：旧主库因网络分区与集群隔离，但仍以为自己持有 Leader 锁，继续对外提供写服务，同时 DCS 侧选出了一个新主库也在写——两边数据分道扬镳，事后无法合并。

Patroni 的解决方案是 DCS TTL + 本地的 Watchdog 双线保护：

• DCS 层防护：Leader 锁带有 TTL 租约，旧主库若无法续租，Leader 锁自动释放，集群将选出一个新主库。但如果旧主库处于单机网络分区，它看不到锁已释放，仍可能自认为还持有锁——这是风险依然存在的地方。
• Watchdog 层（最后一道防线）：在每个数据库节点上运行，Patroni 会周期性向 Watchdog 发送心跳信号。当 Patroni 因故障或无法续租而无法发送心跳时，Watchdog 会强制执行系统重启（硬重启物理机），彻底将旧主库踢出服务，以此物理抹除任何对外服务的可能性。

Watchdog 的配置方式因 Linux 发行版和环境而异（如/dev/watchdog、SoftDog、IPMI 等）。虽然部署 Watchdog 会增加运维复杂性，但在要求零数据分歧的生产场景中是至关重要的防线。

三、DCS 选型与部署

3.1 etcd vs Consul vs ZooKeeper

Patroni 支持多种分布式配置存储后端，统一的抽象接口确保了 DCS 切换时不需要更改 Patroni 的核心高可用逻辑。

部署建议：DCS 集群必须使用 3 个节点（最小高可用配置）或 5 个节点（更高容错），以保证多数派选主能力。单个 DCS 集群可通过不同的 namespace/scope 服务于成百上千个 Patroni 集群，无需为每个 PostgreSQL 集群单独部署一套 DCS。

3.2 etcd 集群部署要点

以 3 节点的 etcd 集群为例，配置核心参数：

# /etc/etcd/etcd.conf
name: 'etcd1'
data-dir: /var/lib/etcd
initial-advertise-peer-urls: http://192.168.1.11:2380
listen-peer-urls: http://0.0.0.0:2380
advertise-client-urls: http://192.168.1.11:2379
listen-client-urls: http://0.0.0.0:2379
initial-cluster: 'etcd1=http://192.168.1.11:2380,etcd2=http://192.168.1.12:2380,etcd3=http://192.168.1.13:2380'
initial-cluster-token: 'etcd-cluster-1'
initial-cluster-state: 'new'

三个节点启动后，使用以下命令验证集群健康状态：

etcdctl --endpoints=http://192.168.1.11:2379 endpoint health

重要建议：生产环境中，PostgreSQL 节点和 DCS 节点应分布在不同的物理服务器上，以免单一硬件故障同时导致数据库和协调层失效。

四、Patroni 配置详解

4.1 基础配置文件（patroni.yml）

以下是完整的 Patroni 配置文件示例，包含生产环境所需的核心参数：

# /etc/patroni/patroni.yml

scope: prod-cluster               # 集群唯一标识
name: pg-node-1                   # 节点名，全局唯一

restapi:
  listen: 0.0.0.0:8008            # REST API 监听地址
  connect_address: 192.168.1.10:8008

# etcd 集群连接配置
etcd3:
  hosts:
    - 192.168.1.11:2379
    - 192.168.1.12:2379
    - 192.168.1.13:2379

bootstrap:
  dcs:
    ttl: 30                       # Leader 租约 TTL（秒）
    loop_wait: 10                 # 健康检查循环间隔（秒）
    retry_timeout: 10             # 操作重试超时（秒）
    maximum_lag_on_failover: 1048576  # 故障转移时允许的最大 WAL 延迟（字节），默认 1MB
    synchronous_mode: false       # 同步模式开关
    synchronous_node_count: 1     # 同步节点数量
    postgresql:
      use_pg_rewind: true         # 启用 pg_rewind 加速节点重建
      use_slots: true             # 启用复制槽，防止 WAL 被提前回收
      parameters:
        max_connections: 200
        shared_buffers: 4GB
        wal_level: replica
        max_wal_senders: 10
        max_replication_slots: 10
        hot_standby: on
        wal_keep_size: 4GB        # 主库保留的 WAL 总量限制（PG 13+）
        synchronous_commit: off   # 异步复制模式

  pg_hba:
    - host all all 0.0.0.0/0 md5
    - host replication replicator 0.0.0.0/0 md5

  # 初始化时创建的用户
  users:
    admin:
      password: admin_secure_password
      options:
        - createrole
        - createdb

postgresql:
  listen: 0.0.0.0:5432
  connect_address: 192.168.1.10:5432
  data_dir: /var/lib/postgresql/data
  bin_dir: /usr/lib/postgresql/bin
  pgpass: /tmp/pgpass
  authentication:
    replication:
      username: replicator
      password: replicator_secure_password
    superuser:
      username: postgres
      password: postgres_super_secure

4.2 关键配置参数详解

（1）DCS 参数（影响切换速度和容错机制）

maximum_lag_on_failover并不是一个严格绝限的参数，而是 Patroni 在该节点与其他节点竞争 Leader 锁时，会检查该节点落后 Leader 的 WAL 字节数是否超过了此值。如果超过，它将在本次选主过程中ineligible（不合格），避免一个严重落后的备库被选为新主库导致大量数据丢失。

（2）PostgreSQL 复制参数

前几期讲解的所有流复制参数都可以在postgresql.parameters下面配置。优势在于：集群配置统一存储在 DCS 中，通过patronictl edit-config修改一次后，所有节点自动生效。

4.3 三种同步复制模式配置

Patroni 支持三种同步复制模式，可在bootstrap.dcs层级进行配置：

推荐选型：在金融、支付等零数据丢失的核心系统，推荐使用多数派仲裁模式，以在保证 RPO=0 的前提下实现最高的业务可用性。

4.4 bootstrap.dcs 与运行时 edit-config 的区别

bootstrap.dcs是 Patroni 在初始化新集群时一次性写入 DCS 的配置，包括 PostgreSQL 初始参数、用户、pg_hba 等。一旦集群运行起来，应该使用 patronictl edit-config 来修改 DCS 中存储的动态配置，而不是手工编辑各节点patroni.yml并重启。

edit-config的优势在于：

• 一次修改、全体生效：所有节点实时读取 DCS 中更新后的配置
• 无需手动重启 Patroni 或 PG（除需要重启的参数外）
• 配置历史可追溯：Patroni 会将所有集群级配置变更记录在 DCS 中

如果需要修改 Patroni 自身的参数（如ttl、loop_wait、synchronous_mode），也需要通过edit-config完成，然后通过patronictl reload在集群范围内统一生效。

五、生产级 Patroni 集群部署实战

5.1 节点规划

生产环境中，PostgreSQL 节点和 DCS 节点建议分开部署，以保证单一故障范围可控。

5.2 安装步骤

步骤 1：在所有节点安装 PostgreSQL、etcd 和 Patroni

# 安装 PostgreSQL 17（以 Ubuntu 24.04 为例）
sudo apt install -y postgresql-17 postgresql-client-17

# 安装 etcd
wget https://github.com/etcd-io/etcd/releases/download/v3.6.4/etcd-v3.6.4-linux-amd64.tar.gz
sudo tar -xvf etcd-v3.6.4-linux-amd64.tar.gz --strip-components=1 -C /usr/local/bin/

# 安装 Patroni 及其 etcd 支持
sudo apt install -y python3-pip
sudo pip3 install 'patroni[etcd3]' psycopg2-binary

步骤 2：配置 etcd 集群（选择一个节点作为初始引导）

在三个节点上分别配置 etcd（以 node1 为例）：

# /etc/etcd/etcd.conf 及 systemd 单元设置完成后，启动服务
sudo systemctl start etcd
sudo systemctl enable etcd

步骤 3：配置 Patroni

在每个节点创建/etc/patroni/patroni.yml，注意各节点的name和connect_address必须唯一。确认配置无误后：

sudo systemctl start patroni
sudo systemctl enable patroni

步骤 4：验证集群状态

patronictl -c /etc/patroni/patroni.yml list

期望看到类似以下输出：

+--------+--------+---------+---------+----+-----------+
| Member |  Host  |  Role   |  State  | TL | Lag in MB |
+--------+--------+---------+---------+----+-----------+
| node1  | 10.0.1 | Leader  | running | 5  |           |
| node2  | 10.0.2 | Replica | running | 5  | 0         |
| node3  | 10.0.3 | Replica | running | 5  | 0         |
+--------+--------+---------+---------+----+-----------+

• Leader：当前主库
• Replica：从库，Lag in MB 为 0 或很小
• TL（Timeline）：时间线 ID，所有成员应保持一致

TL 是指 PostgreSQL 的时间线 ID。当出现时间线分裂（如手动pg_ctl promote后）且某些节点落后于当前 TL 时，Patroni 会自动协调回切过程，避免手工干预。

六、HAProxy 与客户端接入

6.1 让应用无感知地访问

Patroni 集群部署完成后，客户端仍需连接到某个特定的数据库节点，这引出了一个新问题：如果主库发生切换，客户端需要重新配置连接。

Patroni 提供了 REST API（默认端口 8008）来暴露集群状态。第三方负载均衡器可以通过查询 /replica 或 /primary 端点动态获取当前主库和从库的节点，然后将对应的请求代理到该节点。

在实际生产部署中，通常采用 HAProxy 作为接入层，结合 Patroni REST API 实现动态路由：

架构：客户端 → HAProxy（VIP）→ 根据 Patroni 状态代理至主从节点

6.2 HAProxy 核心配置

# /etc/haproxy/haproxy.cfg

# 写池：指向当前 Leader
backend postgres_write
    option httpchk OPTIONS /primary
    http-check expect status 200
    server node1 192.168.1.10:5432 check port 8008 inter 3s fall 3 rise 2
    server node2 192.168.1.11:5432 check port 8008 inter 3s fall 3 rise 2
    server node3 192.168.1.12:5432 check port 8008 inter 3s fall 3 rise 2

# 读池：指向所有 Replica
backend postgres_read
    option httpchk OPTIONS /replica
    http-check expect status 200
    server node1 192.168.1.10:5432 check port 8008 inter 3s fall 3 rise 2
    server node2 192.168.1.11:5432 check port 8008 inter 3s fall 3 rise 2
    server node3 192.168.1.12:5432 check port 8008 inter 3s fall 3 rise 2

HAProxy 对 Patroni /primary 端点的健康检查工作方式如下：HAProxy 每隔数秒（由inter决定）向每个节点的:8008/primary发送 HTTP 请求，只有当前持有 Leader 锁的节点才会返回 HTTP 200。HAProxy 据此将后端写流量只发往响应 200 的节点，其他节点即使 PostgreSQL 服务在运行，只要不是 Leader 就响应非 200，HAProxy 会从写池中将其临时摘除。

在这一机制下，当 Patroni 完成 Leader 故障切换（或触发switchover）后，新 Leader 节点的 /primary 端点立即开始返回 200，同时旧 Leader 的响应变为非 200。HAProxy 在下一个检查周期（例如inter 3s）就会感知到这一变化并瞬间调整写流量的目标——实现真正的客户端无感知主从路由。

HAProxy 后端可配置 Keepalived 来提供虚拟 VIP，消除负载均衡器层的单点故障。

七、日常运维命令

7.1 patronictl 核心命令

计划内切换（switchover） 与故障切换（failover）的区别：switchover 是在主库健康的情况下，将主库角色明确切换到指定的备库，切换过程中零数据丢失且所有备库保持复制关系；failover 则是在主库已经无法响应时强制提升一个备库，这时可能丢失尚未同步的数据，日志中会明确记录哪些事务没有被恢复。

7.2 配置修改范例

patronictl -c /etc/patroni.yml edit-config prod-cluster

# 交互式编辑器打开后，修改参数如下：
ttl: 20
synchronous_mode: "quorum"
synchronous_node_count: 2
postgresql:
  parameters:
    max_connections: 500        # 修改 PostgreSQL 参数
    shared_buffers: 8GB

# 保存后 Patroni 会自动分发配置并触发 reload，无需手动重启 PG

Patroni 会自动检测哪些参数修改需要重启 PostgreSQL 实例（如shared_buffers），哪些只需 reload 即可生效（如max_connections）。对需要重启的参数，可以后续执行patronictl restart来应用变更，并且 Patroni 会按照主从拓扑串行进行重启，整个过程中不会出现主从同时重启的停机窗口。这一串行重启机制确保了高可用集群在维护窗口期间的持续服务。

八、与 Kubernetes 生态的集成

8.1 云原生的部署模式

Patroni 支持在 Kubernetes 上直接运行，与之配合的常见方案有：

• Kubernetes 原生 DCS：利用 Kubernetes Endpoints 或 ConfigMap 作为配置存储，无需部署单独的 etcd 集群
• Zalando Postgres Operator：基于 Patroni 和 Spilo 对 K8s 原生支持的数据库 Operator，通过 CRD 以声明式管理 PostgreSQL 集群的生命周期

8.2 Spilo 镜像简介

Zalando 开源的 Spilo 将 PostgreSQL 和 Patroni 打包为一个容器镜像，专为 Kubernetes 环境设计。与常规部署相比，在 Kubernetes 上运行时，Patroni 使用 Kubernetes Endpoints 作为 DCS，Pod 通过 StatefulSet 管理，数据库状态通过 PVC 持久化。Patroni 完全自主协调高可用切换，Operator 主要负责资源的声明式管理，而非接管 PostgreSQL 的运行时逻辑。

8.3 PostgreSQL + Patroni 在 Kubernetes 上的关键差异

在需要利用 Kubernetes 的弹性基础设施、简化运维且没有专职 DBA 团队时，建议使用 Kubernetes 原生部署；在需要极致确定性、最低延迟并允许 DBA 全权控制每条故障切换路径细节的场景中，建议使用带 etcd 的传统虚拟机/物理机部署。

九、高可用架构的多层部署

在生产环境中，完整的高可用架构通常采用分层部署以满足不同的容灾需求：

• 数据库节点层（Data Layer） ：3 或 5 台 PostgreSQL + Patroni，构成数据库集群核心；
• DCS 节点层（Coordination Layer） ：3 台或 5 台 etcd 提供分布式协调和选举；
• 负载均衡层（Routing Layer） ：2 台 HAProxy + Keepalived，将读写流量路由到正确的数据库节点。

这种分层架构的优势在于：

• 各层独立扩展：可以根据负载分别调整数据库节点数、DCS 节点规模等。
• 各层独立故障：单一 HAProxy 故障不影响数据库本身，单一 etcd 故障不影响数据库可用性。
• 运维职责清晰：网络团队维护负载均衡层，DBA 维护数据库层，分工明确。

9.1 规模选型建议

重要原则：DCS 节点和 HAProxy 节点数量必须保持奇数且至少 3 个以保证多数派共识。etcd 节点数量不应超过数据库节点，但至少为 3 或 5。

9.2 容灾域隔离策略

根据业务需求，在不同容灾策略下选择不同的组件分布：

十、常见问题排查

Q1：Patroni 启动时提示“could not acquire lock”

原因：可能是之前的主库残留的 Leader 锁未正常释放。解决方案：检查 DCS 中是否存在 Legacy 锁或异常节点，通过etcdctl清除对应 key 后重启 Patroni。

Q2：故障切换后，旧主库无法以 Replica 身份重新加入集群

原因：旧主库与新的主库之间时间线已经出现分歧。解决方案：Patroni 配置中包含use_pg_rewind: true即可自动调用pg_rewind将旧主库回滚到一致的时间线。但需确保 PostgreSQL 在编译时启用了--with-checksums，或者在配置文件中启用了wal_log_hints=on。

Q3：HAProxy 无法动态识别 Leader

步骤一：检查 Patroni REST API 是否可访问：curl <a href="http://node1:8008/primary">http://node1:8008/primary</a>；步骤二：检查 HAProxy 的配置文件是否指向正确的端口和健康检查配置。

Q4：复制槽与 WAL 无限膨胀

监控 DCS 配置，确保use_slots: true并且所有的复制槽都被正确回收。同时设置wal_keep_size和max_slot_wal_keep_size来控制主库保留的 WAL 总量，防止备库出现长期离线导致 WAL 堆积。

写在最后

第六期构建了完整的 Patroni 高可用生产实践体系——从 DCS 选型、Patroni 配置，到 HAProxy 接入与 K8s 上的云原生部署。而贯穿始终的核心理念是：用代码和配置来治理基础设施，而非依赖人工干预。

这也是本系列对高可用集群的最后一块拼图——架构设计层面的完整闭环。第七期将作为系列的收官之作，全面汇总前六期所呈现的各类技术组件，并横向对比常见的 PostgreSQL 高可用方案，给出业务导向的选型决策模型与前瞻性的架构演进思考。

📋 当前系列进度回顾与预告：

• ✅ 第一期：宏观框架与技术演进 —— 从单点走向集群
• ✅ 第二期：物理流复制实战 —— 主从搭建与配置
• ✅ 第三期：同步与异步工程实践 —— RPO/RTO 量化与性能权衡
• ✅ 第四期：逻辑复制深度实战 —— 跨版本迁移与数据分发
• ✅ 第五期：WAL 内核与 PITR 备份恢复 —— 数据安全的最后防线
• ✅ 第六期：Patroni 高可用集群部署 —— 自动容灾与 K8s 集成
• 🏁 第七期：水平扩展与架构全景 —— 选型决策、级联复制与展望

本系列为付费专栏，所有内容均由作者独立整理与撰写。如您转载或参考本系列内容，请注明出处并保留完整说明。