PostgreSQL 主从复制（Streaming Replication）完整指南

PostgreSQL 主从复制是一种 实时同步数据 的机制，可以实现 高可用性 (HA)、读写分离 和 负载均衡。其核心是 WAL (Write-Ahead Logging) 日志与 流复制机制。

一、核心概念回顾

• Primary (主库)：负责处理读写请求，所有数据修改都在这里进行。
• Standby (备库/从库)：实时复制主库的 WAL 日志，并回放，保证数据一致性（通常是只读）。
• WAL：预写日志，任何修改必须先写 WAL 才能写数据文件。
• 流复制：备库通过 TCP 流式接收 WAL 日志并应用，保持与主库同步。
• 复制模式
• 异步复制（默认）：主库提交事务后立即返回，不等待备库确认，性能高但可能丢失极少数据。
• 同步复制：主库必须等待备库确认 WAL 写入后才提交，保证强一致性但增加延迟。

二、环境准备

• 服务器：
• 主库 (Primary)：192.168.1.10
• 从库 (Standby)：192.168.1.20
• PostgreSQL 版本：推荐 12+，例如 v15
• 网络要求：主从之间 TCP 5432 端口畅通

三、主库配置

1. 创建复制用户

CREATE ROLE repl_user WITH REPLICATION LOGIN PASSWORD 'your_strong_password';

2. 修改 postgresql.conf

通常路径
/var/lib/pgsql/15/data/postgresql.conf

listen_addresses = '*'           # 监听所有地址
wal_level = replica              # 开启复制所需的 WAL 级别
max_wal_senders = 10             # 允许的最大复制连接数
wal_keep_size = 1024             # WAL 保留大小，避免备库长时间断开
archive_mode = on
archive_command = 'test ! -f /pg_archive/%f && cp %p /pg_archive/%f'

重启数据库：

systemctl restart postgresql-15

3. 配置 pg_hba.conf

host    replication     repl_user    192.168.1.20/32    md5

重新加载配置：

pg_ctl reload

四、备库配置

1. 停止数据库

systemctl stop postgresql-15

2. 清空数据目录

rm -rf /var/lib/pgsql/15/data/*

3. 使用 pg_basebackup 拉取主库数据

pg_basebackup -h 192.168.1.10 -U repl_user -D /var/lib/pgsql/15/data/ -Fp -Xs -P -R

说明：-R 会自动创建 standby.signal 并配置 primary_conninfo，非常推荐。

如果没用 -R，需要手动配置：

# standby.signal 文件
touch /var/lib/pgsql/15/data/standby.signal

# postgresql.auto.conf 添加：
primary_conninfo = 'host=192.168.1.10 port=5432 user=repl_user password=your_strong_password'

4. 启动备库

systemctl start postgresql-15

五、验证复制

主库查看复制状态

SELECT application_name, client_addr, state, sync_state
FROM pg_stat_replication;

• state=streaming 表示复制正常。
• sync_state=async/sync 表示复制模式。

备库验证

SELECT pg_is_in_recovery();

返回 t 表示备库处于恢复模式（只读）。

六、故障转移 (Failover)

主库宕机时，可以将备库提升为主库：

pg_ctl promote -D /var/lib/pgsql/15/data/
# 或
touch /var/lib/pgsql/15/data/promote

应用端需切换连接到新的主库。其余备库需重新指向新主库。

七、生产环境建议

• 手动模式适合学习或测试，但不适合大规模生产。
• 推荐工具：
• Patroni：支持自动故障转移，高可用首选方案。
• Pgpool-II：支持连接池、负载均衡、故障转移。
• repmgr：方便的复制和 failover 管理工具。

八、总结

最佳实践：

• 异步复制作为默认方案，适合大多数场景。
• 关键数据场景使用同步复制，结合 Patroni/pgpool-II 实现自动化高可用。