PostgreSQL 主从复制（流复制）实战配置指南：Windows 环境详细步骤

PostgreSQL 16 主从复制配置实战

[PostgreSQL 16 主从复制（流复制）实战配置指南](#PostgreSQL 16 主从复制（流复制）实战配置指南)
- 概述
- 环境准备
- - 服务器信息
  - 前置条件
- 一、网络与防火墙配置
- - [1.1 防火墙规则配置（两台服务器都需要执行）](#1.1 防火墙规则配置（两台服务器都需要执行）)
  - [1.2 网络连通性测试](#1.2 网络连通性测试)
- 二、主库配置（10.15.0.96）
- - [2.1 修改 postgresql.conf 配置文件](#2.1 修改 postgresql.conf 配置文件)
  - [2.2 修改 pg_hba.conf 配置文件](#2.2 修改 pg_hba.conf 配置文件)
  - [2.3 创建复制专用用户](#2.3 创建复制专用用户)
  - [2.4 重启主库 PostgreSQL 服务](#2.4 重启主库 PostgreSQL 服务)
- 三、备库配置（10.15.0.98）
- - [3.1 停止备库服务](#3.1 停止备库服务)
  - [3.2 清空备库数据目录（⚠️ 危险操作，请谨慎）](#3.2 清空备库数据目录（⚠️ 危险操作，请谨慎）)
  - [3.3 使用 pg_basebackup 从主库拉取数据](#3.3 使用 pg_basebackup 从主库拉取数据)
  - [3.4 检查生成的连接信息](#3.4 检查生成的连接信息)
  - [3.5 启动备库服务](#3.5 启动备库服务)
- 四、验证复制状态
- - [4.1 在主库查看复制状态](#4.1 在主库查看复制状态)
  - [4.2 在备库验证恢复模式](#4.2 在备库验证恢复模式)
  - [4.3 测试数据同步](#4.3 测试数据同步)
- 五、故障切换（备库提升为主库）
- - [5.1 方法一：使用 pg_ctl promote 命令](#5.1 方法一：使用 pg_ctl promote 命令)
  - [5.2 方法二：在 psql 中执行 promote 函数](#5.2 方法二：在 psql 中执行 promote 函数)
  - [5.3 验证提升结果](#5.3 验证提升结果)
  - [5.4 原主库恢复后的重新配置](#5.4 原主库恢复后的重新配置)
- 六、常见问题与故障排除
- - [6.1 连接失败问题](#6.1 连接失败问题)
  - [6.2 认证失败问题](#6.2 认证失败问题)
  - [6.3 复制延迟问题](#6.3 复制延迟问题)
  - [6.4 复制槽相关问题](#6.4 复制槽相关问题)
- 七、性能优化建议
- - [7.1 网络优化](#7.1 网络优化)
  - [7.2 PostgreSQL 参数优化](#7.2 PostgreSQL 参数优化)
  - [7.3 监控配置](#7.3 监控配置)
- 总结
- 附录：常用命令参考
- - 查看复制状态
  - 管理复制槽
  - 停止/启动复制
  - [查看 WAL 文件信息](#查看 WAL 文件信息)

PostgreSQL 16 主从复制（流复制）实战配置指南

概述

PostgreSQL 流复制（Streaming Replication）是 PostgreSQL 数据库高可用架构的核心技术之一，它通过 WAL（Write-Ahead Logging）日志的实时传输，实现主库到备库的数据同步。本文将基于 Windows Server 环境，详细演示 PostgreSQL 16 主从复制的完整配置流程，涵盖网络配置、主库配置、备库初始化、同步验证及故障切换等关键环节。

环境准备

服务器信息

角色	IP 地址	安装目录	数据目录
主库 (Primary)	10.15.0.96	`D:\Program Files\PostgreSQL\16`	`D:\Program Files\PostgreSQL\16\data`
备库 (Standby)	10.15.0.98	`C:\Program Files\PostgreSQL\16`	`C:\Program Files\PostgreSQL\16\data`

前置条件

PostgreSQL 16 已在两台服务器上安装完成
确保主库和备库的 PostgreSQL 版本一致
主库已有业务数据或为空数据库均可

一、网络与防火墙配置

1.1 防火墙规则配置（两台服务器都需要执行）

在 Windows PowerShell（管理员权限）中执行以下命令，开放 PostgreSQL 默认端口 5432：

powershell 复制代码

# 创建入站规则，允许 TCP 5432 端口
New-NetFirewallRule -DisplayName "PostgreSQL 5432" -Direction Inbound -Protocol TCP -LocalPort 5432 -Action Allow

1.2 网络连通性测试

确保两台服务器之间网络互通：

powershell 复制代码

# 测试网络连通性
ping 10.15.0.98  # 从主库 ping 备库
ping 10.15.0.96  # 从备库 ping 主库

# 测试端口连通性（使用 Test-NetConnection）
Test-NetConnection -ComputerName 10.15.0.98 -Port 5432  # 从主库测试备库端口
Test-NetConnection -ComputerName 10.15.0.96 -Port 5432  # 从备库测试主库端口

如果 Test-NetConnection 不可用，可以使用传统的 telnet 命令：

cmd 复制代码

telnet 10.15.0.98 5432
telnet 10.15.0.96 5432

二、主库配置（10.15.0.96）

2.1 修改 postgresql.conf 配置文件

编辑主库的配置文件 D:\Program Files\PostgreSQL\16\data\postgresql.conf，找到或添加以下参数：

ini 复制代码

# 监听所有 IP 地址
listen_addresses = '*'

# WAL 日志级别设置为 replica（流复制必需）
wal_level = replica

# 最大 WAL 发送进程数
max_wal_senders = 10

# 保留的 WAL 日志大小
wal_keep_size = 1024MB

# 启用热备模式（备库可读）
hot_standby = on

参数说明：

listen_addresses = '*'：允许从任何 IP 连接
wal_level = replica：WAL 日志级别，流复制必需
max_wal_senders = 10：最大并发复制连接数
wal_keep_size = 1024MB：保留的 WAL 日志大小，防止备库落后时 WAL 被清理
hot_standby = on：允许备库在恢复期间执行只读查询

2.2 修改 pg_hba.conf 配置文件

编辑 D:\Program Files\PostgreSQL\16\data\pg_hba.conf，在文件末尾添加以下行：

conf 复制代码

# 允许备库使用 repl_user 用户进行复制连接
host    replication     repl_user       10.15.0.98/32        md5

配置说明：

host：连接类型
replication：数据库名（特殊数据库，用于复制）
repl_user：复制专用用户
10.15.0.98/32：备库 IP 地址，/32 表示单个主机
md5：密码认证方式

2.3 创建复制专用用户

使用 psql 连接到主库并创建复制用户：

sql 复制代码

-- 以管理员身份运行 PowerShell 或命令提示符
"D:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -p 5432

-- 创建复制用户
CREATE ROLE repl_user WITH REPLICATION LOGIN PASSWORD 'c123456';

-- 查看用户是否创建成功
\du

-- 退出 psql
\q

2.4 重启主库 PostgreSQL 服务

cmd 复制代码

# 停止 PostgreSQL 服务
net stop postgresql-x64-16

# 启动 PostgreSQL 服务
net start postgresql-x64-16

三、备库配置（10.15.0.98）

3.1 停止备库服务

cmd 复制代码

net stop postgresql-x64-16

3.2 清空备库数据目录（⚠️ 危险操作，请谨慎）

如果备库是全新安装且无数据，可跳过此步骤。如果备库已有数据，需要先清空：

cmd 复制代码

# 切换到备库数据目录
cd /d "C:\Program Files\PostgreSQL\16\data"

# 删除目录内所有文件（需要管理员权限）
del /f /s /q "C:\Program Files\PostgreSQL\16\data\*.*" > nul

# 删除所有子目录
for /d %%i in ("C:\Program Files\PostgreSQL\16\data\*") do rd /s /q "%%i"

重要提醒：

此操作不可逆，请确保已备份重要数据
如果数据目录不是默认路径，请相应修改命令中的路径

3.3 使用 pg_basebackup 从主库拉取数据

在备库服务器上执行以下命令，从主库获取基础备份：

cmd 复制代码

"C:\Program Files\PostgreSQL\16\bin\pg_basebackup.exe" -h 10.15.0.96 -D "C:\Program Files\PostgreSQL\16\data" -U repl_user -P -R -X stream -C -S standby_slot

参数详解：

-h 10.15.0.96：主库 IP 地址
-D "C:\Program Files\PostgreSQL\16\data"：备库数据目录
-U repl_user：复制用户名
-P：显示进度
-R：自动创建 standby.signal 文件和 postgresql.auto.conf
-X stream：使用流式传输 WAL 日志
-C：创建复制槽
-S standby_slot：复制槽名称

执行过程中会提示输入密码，输入之前设置的 c123456。

3.4 检查生成的连接信息

备份完成后，检查 C:\Program Files\PostgreSQL\16\data\postgresql.auto.conf 文件，确认包含以下内容：

ini 复制代码

primary_conninfo = 'user=repl_user password=c123456 host=10.15.0.96 port=5432 sslmode=prefer sslcompression=0 gssencmode=prefer krbsrvname=postgres target_session_attrs=any'
primary_slot_name = 'standby_slot'

3.5 启动备库服务

cmd 复制代码

net start postgresql-x64-16

四、验证复制状态

4.1 在主库查看复制状态

连接到主库执行查询：

sql 复制代码

"D:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -p 5432

-- 查看复制状态
SELECT 
    client_addr, 
    state, 
    sync_state, 
    write_lag, 
    flush_lag, 
    replay_lag,
    sent_lsn,
    write_lsn,
    flush_lsn,
    replay_lsn
FROM pg_stat_replication;

预期结果：

client_addr 应为 10.15.0.98（备库 IP）
state 应为 streaming
sync_state 显示同步状态（async 或 sync）

4.2 在备库验证恢复模式

连接到备库执行查询：

sql 复制代码

"C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -p 5432

-- 检查是否处于恢复模式
SELECT pg_is_in_recovery();

-- 查看备库的 WAL 接收和应用情况
SELECT 
    pg_last_wal_receive_lsn(),
    pg_last_wal_replay_lsn(),
    pg_last_xact_replay_timestamp();

预期结果：

pg_is_in_recovery() 返回 t（true），表示备库处于恢复模式
WAL 接收和重放位置应不断更新

4.3 测试数据同步

在主库创建测试数据：

sql 复制代码

-- 在主库执行
CREATE DATABASE test_replication;
\c test_replication
CREATE TABLE test_table (id SERIAL PRIMARY KEY, name VARCHAR(50), created_at TIMESTAMP DEFAULT NOW());
INSERT INTO test_table (name) VALUES ('test_data_1'), ('test_data_2'), ('test_data_3');

在备库验证数据：

sql 复制代码

-- 在备库执行（备库为只读模式）
\c test_replication
SELECT * FROM test_table;

五、故障切换（备库提升为主库）

当主库发生故障且无法恢复时，需要将备库提升为主库。

5.1 方法一：使用 pg_ctl promote 命令

在备库服务器上执行：

cmd 复制代码

"C:\Program Files\PostgreSQL\16\bin\pg_ctl.exe" promote -D "C:\Program Files\PostgreSQL\16\data"

5.2 方法二：在 psql 中执行 promote 函数

sql 复制代码

-- 在备库的 psql 中执行
SELECT pg_promote();

5.3 验证提升结果

sql 复制代码

-- 在提升后的新主库执行
SELECT pg_is_in_recovery();  -- 应返回 f（false）

-- 检查是否可读写
CREATE TABLE promote_test (id INT);
INSERT INTO promote_test VALUES (1);
SELECT * FROM promote_test;

5.4 原主库恢复后的重新配置

当原主库（10.15.0.96）恢复后，需要重新配置为备库：

清空原主库数据目录
使用 pg_basebackup 从新主库（10.15.0.98）拉取数据
修改连接信息指向新主库
启动服务

六、常见问题与故障排除

6.1 连接失败问题

问题： pg_basebackup: error: could not connect to server

解决方案：

检查防火墙规则是否生效
确认主库 postgresql.conf 中 listen_addresses = '*'
确认 pg_hba.conf 中配置正确
使用 telnet 或 Test-NetConnection 测试端口连通性

6.2 认证失败问题

问题： FATAL: password authentication failed for user "repl_user"

解决方案：

确认主库已创建 repl_user 用户
确认密码正确
确认 pg_hba.conf 中配置了正确的 IP 和认证方式

6.3 复制延迟问题

问题： 备库数据同步延迟较大

解决方案：

增加 wal_keep_size 参数值
检查网络带宽和延迟
考虑使用同步复制（设置 synchronous_standby_names）

6.4 复制槽相关问题

问题： ERROR: replication slot "standby_slot" already exists

解决方案：

sql 复制代码

-- 在主库删除已存在的复制槽
SELECT pg_drop_replication_slot('standby_slot');

七、性能优化建议

7.1 网络优化

确保主备库之间网络延迟低、带宽充足
考虑使用专用网络或 VLAN 隔离复制流量

7.2 PostgreSQL 参数优化

ini 复制代码

# 增加 WAL 相关缓冲区
wal_buffers = 16MB
max_wal_size = 2GB
min_wal_size = 1GB

# 调整检查点参数
checkpoint_timeout = 15min
checkpoint_completion_target = 0.9

7.3 监控配置

建议配置以下监控项：

复制延迟（replay_lag）
WAL 发送和接收位置
复制连接状态
磁盘空间使用情况

总结

本文详细介绍了在 Windows Server 环境下配置 PostgreSQL 16 主从复制（流复制）的完整流程。通过合理的配置和监控，可以构建稳定可靠的数据库高可用架构。在实际生产环境中，建议：

定期测试故障切换，确保灾难恢复流程有效
监控复制延迟，及时发现并解决问题
备份策略，即使有备库也需要定期全量备份
文档化，记录所有配置变更和故障处理过程

通过本文的步骤，您应该能够成功搭建 PostgreSQL 主从复制环境，为业务系统提供更高的可用性和数据安全性。

附录：常用命令参考

查看复制状态

sql 复制代码

-- 主库查看
SELECT * FROM pg_stat_replication;

-- 备库查看
SELECT pg_is_in_recovery();
SELECT pg_last_wal_receive_lsn(), pg_last_wal_replay_lsn();

管理复制槽

sql 复制代码

-- 查看复制槽
SELECT * FROM pg_replication_slots;

-- 创建复制槽
SELECT * FROM pg_create_physical_replication_slot('slot_name');

-- 删除复制槽
SELECT pg_drop_replication_slot('slot_name');

停止/启动复制

sql 复制代码

-- 在备库暂停复制
SELECT pg_wal_replay_pause();

-- 在备库恢复复制
SELECT pg_wal_replay_resume();

查看 WAL 文件信息

sql 复制代码

SELECT pg_walfile_name(pg_current_wal_lsn());