按这篇做完,你能从零搭出一套三节点 PostgreSQL 高可用集群:主库宕机后由 Patroni 自动选主切换,旧主库回来自动以从库身份重新接入,业务侧只需要连一个固定入口。
下面以三台 CentOS/Rocky 9 机器为例,角色划分是:三个节点同时跑 etcd(用来存放集群状态),三个节点同时跑 PostgreSQL + Patroni。IP 分别记为 192.168.1.11 / .12 / .13。
第一步:基础环境准备
三台机器都做这几件事:
hostnamectl set-hostname pg1 # 另两台对应 pg2 / pg3
cat >> /etc/hosts <<'EOF'
192.168.1.11 pg1
192.168.1.12 pg2
192.168.1.13 pg3
EOF
systemctl enable --now chronyd # 时间必须同步,否则选主会出怪问题
useradd postgres 2>/dev/null
mkdir -p /data/pgdata && chown -R postgres:postgres /data
开放端口:2379/2380(etcd)、5432(PG)、8008(Patroni REST API)。
注意:/data/pgdata 必须是空目录。Patroni 自己会执行 initdb,你手动初始化过反而会启动失败。
第二步:安装 PostgreSQL 与 Patroni
装官方源和软件包(这里以 PG16 为例):
dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
dnf -qy module disable postgresql
dnf install -y postgresql16-server postgresql16-contrib python3 python3-pip
pip3 install patroni[etcd3] psycopg2-binary
三台都装。
注意:不要执行 systemctl enable --now postgresql-16。数据库实例的启停完全交给 Patroni 管理,系统服务起来会和 Patroni 抢数据目录。
第三步:搭 etcd 集群
三台都装 dnf install -y etcd,然后编辑 /etc/etcd/etcd.conf,pg1 上内容如下(另两台只改名字和 IP):
ETCD_NAME=etcd1
ETCD_DATA_DIR=/var/lib/etcd/data
ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
ETCD_ADVERTISE_CLIENT_URLS=http://192.168.1.11:2379
ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
ETCD_INITIAL_ADVERTISE_PEER_URLS=http://192.168.1.11:2380
ETCD_INITIAL_CLUSTER=etcd1=http://192.168.1.11:2380,etcd2=http://192.168.1.12:2380,etcd3=http://192.168.1.13:2380
ETCD_INITIAL_CLUSTER_STATE=new
ETCD_INITIAL_CLUSTER_TOKEN=pg-etcd-cluster
三台依次启动后验证:
systemctl enable --now etcd
etcdctl endpoint health --cluster
etcdctl member list
三个节点都输出 healthy 才算过。
注意:etcd 必须是奇数节点(3/5)。两节点集群在网络抖动时可能直接失去法定票数,整个集群只读不写。
第四步:写 Patroni 配置
在 pg1 上创建 /etc/patroni.yml:
scope: pgcluster
namespace: /service/
name: pg1
restapi:
listen: 0.0.0.0:8008
connect_address: 192.168.1.11:8008
auth:
username: patroni
password: patronipass
etcd3:
hosts: 192.168.1.11:2379,192.168.1.12:2379,192.168.1.13:2379
bootstrap:
dcs:
ttl: 30
loop_wait: 10
retry_timeout: 10
maximum_lag_on_failover: 1048576
synchronous_mode: false
postgresql:
use_pg_rewind: true
use_slots: true
parameters:
wal_level: replica
hot_standby: "on"
max_wal_senders: 10
max_replication_slots: 10
wal_keep_size: 1GB
max_connections: 300
initdb:
- encoding: UTF8
- data-checksums
pg_hba:
- host replication replicator 192.168.1.0/24 scram-sha-256
- host all all 192.168.1.0/24 scram-sha-256
users:
admin:
password: adminpass
options: [createrole, createdb]
postgresql:
listen: 0.0.0.0:5432
connect_address: 192.168.1.11:5432
data_dir: /data/pgdata
bin_dir: /usr/pgsql-16/bin
authentication:
replication:
username: replicator
password: replpass
superuser:
username: postgres
password: postgrespass
parameters:
unix_socket_directories: /var/run/postgresql
复制到 pg2 / pg3,只改 name 和两处 connect_address 里的 IP。
注意:bootstrap 段只在集群第一次初始化时生效,后续改参数要用 patronictl edit-config,改完记得重启对应实例。
第五步:启动与验证
三台都执行:
chown postgres:postgres /etc/patroni.yml
systemctl enable --now patroni
然后在任意一台看集群状态:
patronictl -c /etc/patroni.yml list
正常输出是一个 Leader 加两个 replica,且 Lag in MB 应为 0。
再做一次主动切换验证:
patronictl -c /etc/patroni.yml switchover --master pg1 --candidate pg2 --force
观察 list 输出,pg2 变 Leader、pg1 变 replica,客户端连接不中断(连接池会有一次重连)。
顺便验证一下自动故障转移:直接 systemctl stop patroni 停掉 current leader,约 30 秒内剩余节点会自动选出新主。再把停掉的节点启动,它会用 pg_rewind 自动追平数据后作为从库加入。
注意:switchover 前先确认两件事——候选节点 lag 为 0、集群不处于 pause 状态(patronictl list 顶部会显示)。
第六步:给客户端一个固定入口
应用不能写死 IP。两种常见做法:
- HAProxy:在三台(或额外两台)上装 HAProxy,后端按
192.168.1.11:5432 等列全,健康检查用 Patroni REST API:
- 主库检查
GET /master,期望 200
- 从库检查
GET /replica,期望 200
这样读写分离也顺手做了。
- VIP:keepalived 配合
chk_patroni 脚本(脚本里 curl /master 判断),漂移比 HAProxy 快,但只解决主库入口。
注意:Patroni REST API 一定要在配置里设置 auth 用户名密码,否则 8008 端口裸奔,任何人都能触发切换。
小结
- 三节点:etcd 存状态(必须奇数),Patroni 管进程,PG 流复制传数据。
- 数据目录必须空、权限归 postgres,且绝不能再用系统 postgresql 服务启动实例。
use_pg_rewind: true 是旧主库能自动归队的关键,maximum_lag_on_failover 决定多大延迟的从库可以被选为主。
- 参数改动走
patronictl edit-config,运维动作走 patronictl list / switchover / failover。
- 生产上先做一次
switchover + 一次 stop leader 演练,再谈上线。