PostgreSQL Patroni 配置与管理

Patroni 简介

Patroni 是一个用于 PostgreSQL 高可用集群管理的开源工具，它提供了自动故障切换、集群配置管理和监控功能。Patroni 可以与多种分布式一致性存储系统集成，如 ZooKeeper、etcd、Consul 和 Kubernetes。

Patroni 核心功能

自动故障切换：监控主库状态，当主库故障时自动将从库提升为主库
集群配置管理：集中管理 PostgreSQL 集群配置，确保所有节点配置一致
节点加入与退出：支持动态添加和移除集群节点
监控与告警：提供集群状态监控和告警功能
多种一致性存储支持：支持 ZooKeeper、etcd、Consul 和 Kubernetes

Patroni 架构

Patroni 架构由以下组件组成：

Patroni 代理：运行在每个 PostgreSQL 节点上，负责监控节点状态和执行故障切换
分布式一致性存储：存储集群配置和状态信息
PostgreSQL 实例：实际的数据库实例
可选的负载均衡器：如 HAProxy 或 pgpool-II，用于分发客户端连接

Patroni 安装与部署

1. 环境准备

系统要求

Linux 操作系统（推荐使用 CentOS 7/8、Ubuntu 18.04+）
Python 3.6+
PostgreSQL 10+
分布式一致性存储（如 etcd、ZooKeeper 或 Consul）

节点规划

节点角色	主机名	IP 地址	端口
主库	node1	192.168.1.1	5432
从库1	node2	192.168.1.2	5432
从库2	node3	192.168.1.3	5432
etcd1	etcd1	192.168.1.4	2379
etcd2	etcd2	192.168.1.5	2379
etcd3	etcd3	192.168.1.6	2379

2. 安装 Patroni

使用 pip 安装

bash

# 安装 Patroni 和依赖
sudo pip3 install patroni[etcd]

# 或安装特定版本
sudo pip3 install patroni[etcd]==2.1.4

安装 PostgreSQL

在每个节点上安装 PostgreSQL：

bash

# CentOS/RHEL
sudo yum install -y postgresql-server postgresql-contrib

# Ubuntu/Debian
sudo apt-get install -y postgresql postgresql-contrib

3. 配置分布式一致性存储

以 etcd 为例，配置一个三节点的 etcd 集群：

bash

# 在每个 etcd 节点上安装 etcd
sudo yum install -y etcd

# 配置 etcd（etcd1 节点）
sudo cat > /etc/etcd/etcd.conf << EOF
ETCD_NAME=etcd1
ETCD_DATA_DIR="/var/lib/etcd/default.etcd"
ETCD_LISTEN_PEER_URLS="http://192.168.1.4:2380"
ETCD_LISTEN_CLIENT_URLS="http://192.168.1.4:2379,http://127.0.0.1:2379"
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://192.168.1.4:2380"
ETCD_ADVERTISE_CLIENT_URLS="http://192.168.1.4:2379"
ETCD_INITIAL_CLUSTER="etcd1=http://192.168.1.4:2380,etcd2=http://192.168.1.5:2380,etcd3=http://192.168.1.6:2380"
ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-1"
ETCD_INITIAL_CLUSTER_STATE="new"
EOF

# 启动 etcd 服务
sudo systemctl enable etcd
sudo systemctl start etcd

Patroni 配置文件详解

1. 基本配置结构

Patroni 配置文件采用 YAML 格式，主要包含以下部分：

scope：集群名称
namespace：命名空间（用于区分多个集群）
name：节点名称
restapi：Patroni REST API 配置
etcd：etcd 配置（或其他一致性存储配置）
bootstrap：集群初始化配置
postgresql：PostgreSQL 配置
tags：节点标签

2. 示例配置文件

yaml

scope: postgres-cluster
namespace: /db/
name: node1

restapi:
  listen: 192.168.1.1:8008
  connect_address: 192.168.1.1:8008

etcd:
  hosts: 192.168.1.4:2379,192.168.1.5:2379,192.168.1.6:2379

bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    maximum_lag_on_failover: 1048576
    postgresql:
      use_pg_rewind: true
      use_slots: true
      parameters:
        wal_level: replica
        hot_standby: on
        logging_collector: on
        log_directory: pg_log
        log_filename: postgresql-%Y-%m-%d_%H%M%S.log
        log_truncate_on_rotation: on
        log_rotation_age: 1d
        log_rotation_size: 100MB
        max_wal_senders: 10
        max_replication_slots: 10
        hot_standby_feedback: on
  initdb:
  - encoding: UTF8
  - data-checksums
  pg_hba:
  - host replication replicator 127.0.0.1/32 trust
  - host replication replicator 192.168.1.0/24 trust
  - host all all 0.0.0.0/0 md5

postgresql:
  listen: 0.0.0.0:5432
  connect_address: 192.168.1.1:5432
  data_dir: /var/lib/pgsql/13/data
  bin_dir: /usr/pgsql-13/bin
  pgpass: /tmp/pgpass0
  authentication:
    replication:
      username: replicator
      password: secret
    superuser:
      username: postgres
      password: secret
  parameters:
    unix_socket_directories: /var/run/postgresql

tags:
  nofailover: false
  noloadbalance: false
  clonefrom: false
  nosync: false

3. 关键配置参数

分布式一致性存储配置

ttl：集群状态的生存时间，默认 30 秒
loop_wait：Patroni 循环检查的间隔时间，默认 10 秒
retry_timeout：操作重试的超时时间，默认 10 秒
maximum_lag_on_failover：故障切换时允许的最大 WAL 延迟，默认 1MB

PostgreSQL 配置

use_pg_rewind：是否使用 pg_rewind 来同步节点，默认 false
use_slots：是否使用复制槽，默认 false
wal_level：WAL 日志级别，建议设置为 replica 或 logical
max_wal_senders：最大 WAL 发送者数量，建议设置为从库数量 + 2
max_replication_slots：最大复制槽数量，建议设置为从库数量 + 2

Patroni 集群管理

1. 启动 Patroni 服务

使用 systemd 启动

bash

# 创建 systemd 服务文件
sudo cat > /etc/systemd/system/patroni.service << EOF
[Unit]
Description=Patroni PostgreSQL Cluster Manager
After=syslog.target network.target

[Service]
Type=simple
User=postgres
Group=postgres
ExecStart=/usr/local/bin/patroni /etc/patroni.yml
ExecReload=/bin/kill -s HUP $MAINPID
KillMode=process
TimeoutSec=30
Restart=no

[Install]
WantedBy=multi-user.target
EOF

# 启动 Patroni 服务
sudo systemctl enable patroni
sudo systemctl start patroni

手动启动

bash

patroni /etc/patroni.yml

2. 查看集群状态

使用 Patroni REST API

bash

# 查看集群状态
curl -s http://192.168.1.1:8008/cluster | jq .

# 查看特定节点状态
curl -s http://192.168.1.1:8008/ | jq .

使用 patronictl 命令行工具

bash

# 查看集群状态
patronictl -c /etc/patroni.yml list

# 查看集群配置
patronictl -c /etc/patroni.yml show-config

3. 集群操作

切换主库

bash

# 手动将 node2 切换为主库
patronictl -c /etc/patroni.yml switchover postgres-cluster

重启主库

bash

# 重启主库（会自动切换到其他节点）
patronictl -c /etc/patroni.yml restart postgres-cluster

暂停自动故障切换

bash

# 暂停自动故障切换
patronictl -c /etc/patroni.yml pause postgres-cluster

# 恢复自动故障切换
patronictl -c /etc/patroni.yml resume postgres-cluster

4. 节点管理

添加新节点

在新节点上安装 Patroni 和 PostgreSQL
配置 Patroni 配置文件，确保 scope 和 namespace 与现有集群一致
启动 Patroni 服务，新节点会自动加入集群并同步数据

移除节点

bash

# 移除节点
patronictl -c /etc/patroni.yml remove postgres-cluster node3

自动故障切换机制

1. 故障检测

Patroni 通过以下方式检测主库故障：

定期心跳检查：主库定期向一致性存储发送心跳信息
PostgreSQL 状态检查：Patroni 代理定期检查本地 PostgreSQL 实例状态
TCP 连接检查：尝试建立 TCP 连接到主库

2. 故障切换流程

当 Patroni 检测到主库故障时，会触发故障切换流程
首先，Patroni 会检查集群中所有从库的状态
选择一个合适的从库（通常是 WAL 延迟最小的从库）
将选中的从库提升为主库
更新集群配置，将其他从库指向新的主库
通知所有节点更新配置

3. 故障切换配置

可以通过以下配置参数调整故障切换行为：

maximum_lag_on_failover：故障切换时允许的最大 WAL 延迟
failover_check_timeout：故障检查的超时时间
synchronous_mode：是否启用同步复制模式

Patroni 监控与告警

1. 内置监控指标

Patroni 提供了丰富的监控指标，可以通过 REST API 获取：

集群状态：主库、从库状态和数量
节点状态：每个节点的 PostgreSQL 状态、复制延迟等
配置版本：集群配置的版本信息
故障切换历史：历史故障切换记录

2. 与 Prometheus 集成

Patroni 可以与 Prometheus 集成，提供更强大的监控功能：

yaml

# 在 Patroni 配置文件中添加 Prometheus 配置
restapi:
  listen: 192.168.1.1:8008
  connect_address: 192.168.1.1:8008
  prometheus_metrics: true
  prometheus_endpoint: /metrics

3. 告警配置

可以使用 Prometheus Alertmanager 或其他监控工具配置告警规则，例如：

主库故障
从库延迟超过阈值
Patroni 服务停止
分布式一致性存储连接失败

生产环境最佳实践

1. 硬件配置

CPU：建议使用 4 核以上 CPU
内存：建议使用 8GB 以上内存
磁盘：使用 SSD 磁盘，提高 I/O 性能
网络：使用千兆以上网络，确保节点间通信流畅

2. 分布式一致性存储选择

etcd：推荐用于中小型集群，部署简单
ZooKeeper：推荐用于大型集群，可靠性高
Consul：推荐用于已使用 Consul 的环境
Kubernetes：推荐用于 Kubernetes 环境

3. 安全配置

防火墙：限制 Patroni REST API 的访问
认证：为 Patroni REST API 配置认证
加密：为节点间通信配置 TLS 加密
权限：使用最小权限原则配置 Patroni 运行用户

4. 备份策略

定期全量备份：使用 pg_basebackup 或第三方工具进行定期全量备份
WAL 归档：配置 WAL 归档，确保可以进行时间点恢复
备份验证：定期验证备份的完整性和可恢复性

5. 测试与演练

故障切换测试：定期进行故障切换测试，确保自动故障切换正常工作
恢复测试：定期进行数据库恢复测试，确保备份可用
性能测试：定期进行性能测试，确保集群性能满足需求

不同版本的 Patroni 差异

Patroni 1.6.x

引入了对 PostgreSQL 12 的支持
增强了 pg_rewind 集成
改进了故障切换逻辑

Patroni 2.0.x

引入了对 PostgreSQL 13 的支持
增强了 Kubernetes 集成
改进了监控指标
支持更多的一致性存储选项

Patroni 2.1.x

引入了对 PostgreSQL 14 的支持
增强了配置管理功能
改进了故障切换性能
支持更多的 PostgreSQL 配置参数

常见问题（FAQ）

Q1: Patroni 支持哪些 PostgreSQL 版本？

A1: Patroni 支持 PostgreSQL 10 及以上版本，建议使用最新的 LTS 版本以获得最佳性能和安全性。

Q2: 如何选择合适的分布式一致性存储？

A2: 选择分布式一致性存储应考虑以下因素：

集群规模：中小型集群建议使用 etcd，大型集群建议使用 ZooKeeper
现有技术栈：如果已使用 Consul 或 Kubernetes，建议使用相应的一致性存储
运维经验：选择团队熟悉的技术

Q3: 如何手动触发故障切换？

A3: 可以使用 patronictl 命令行工具手动触发故障切换：

bash

patronictl -c /etc/patroni.yml switchover postgres-cluster

Q4: 如何处理 Patroni 无法自动故障切换的情况？

A4: 如果 Patroni 无法自动故障切换，可以尝试以下方法：

检查分布式一致性存储是否正常运行
检查 Patroni 服务是否正常运行
检查主库是否真的故障
手动触发故障切换

Q5: 如何升级 Patroni 集群？

A5: 升级 Patroni 集群的步骤如下：

备份集群配置和数据
逐个节点升级 Patroni 软件
重启 Patroni 服务
验证集群状态
如果需要，升级 PostgreSQL 版本

PostgreSQL Patroni 配置与管理 ​

Patroni 简介 ​

Patroni 核心功能 ​

Patroni 架构 ​

Patroni 安装与部署 ​

1. 环境准备 ​

系统要求 ​

节点规划 ​

2. 安装 Patroni ​

使用 pip 安装 ​

安装 PostgreSQL ​

3. 配置分布式一致性存储 ​

Patroni 配置文件详解 ​

1. 基本配置结构 ​

2. 示例配置文件 ​

3. 关键配置参数 ​

分布式一致性存储配置 ​

PostgreSQL 配置 ​

Patroni 集群管理 ​

1. 启动 Patroni 服务 ​

使用 systemd 启动 ​

手动启动 ​

2. 查看集群状态 ​

使用 Patroni REST API ​

使用 patronictl 命令行工具 ​

3. 集群操作 ​

切换主库 ​

重启主库 ​

暂停自动故障切换 ​

4. 节点管理 ​

添加新节点 ​

移除节点 ​

自动故障切换机制 ​

1. 故障检测 ​

2. 故障切换流程 ​

3. 故障切换配置 ​

Patroni 监控与告警 ​

1. 内置监控指标 ​

2. 与 Prometheus 集成 ​

3. 告警配置 ​

生产环境最佳实践 ​

1. 硬件配置 ​

2. 分布式一致性存储选择 ​

3. 安全配置 ​

4. 备份策略 ​

5. 测试与演练 ​

不同版本的 Patroni 差异 ​

Patroni 1.6.x ​

Patroni 2.0.x ​

Patroni 2.1.x ​

常见问题（FAQ） ​

Q1: Patroni 支持哪些 PostgreSQL 版本？ ​

PostgreSQL Patroni 配置与管理

Patroni 简介

Patroni 核心功能

Patroni 架构

Patroni 安装与部署

1. 环境准备

系统要求

节点规划

2. 安装 Patroni

使用 pip 安装

安装 PostgreSQL

3. 配置分布式一致性存储

Patroni 配置文件详解

1. 基本配置结构

2. 示例配置文件

3. 关键配置参数

分布式一致性存储配置

PostgreSQL 配置

Patroni 集群管理

1. 启动 Patroni 服务

使用 systemd 启动

手动启动

2. 查看集群状态

使用 Patroni REST API

使用 patronictl 命令行工具

3. 集群操作

切换主库

重启主库

暂停自动故障切换

4. 节点管理

添加新节点

移除节点

自动故障切换机制

1. 故障检测

2. 故障切换流程

3. 故障切换配置

Patroni 监控与告警

1. 内置监控指标

2. 与 Prometheus 集成

3. 告警配置

生产环境最佳实践

1. 硬件配置

2. 分布式一致性存储选择

3. 安全配置

4. 备份策略

5. 测试与演练

不同版本的 Patroni 差异

Patroni 1.6.x

Patroni 2.0.x

Patroni 2.1.x

常见问题（FAQ）

Q1: Patroni 支持哪些 PostgreSQL 版本？