PostgreSQL 流式复制设置分步指南

流式复制是在 PostgreSQL 环境中实现高可用性和读取可扩展性的基础机制。通过配置主服务器持续将预写日志记录流式传输到一个或多个备用服务器，您可以确保数据同步且延迟最小。

本指南将引导您使用 pg_basebackup、pg_hba.conf 和备用信号文件完成异步流式复制的设置。最终您将获得一个正常工作的主-备对，以及验证其是否真正进行流式复制所需的检查。

先决条件和环境设置

在开始之前，请确保满足以下先决条件。本指南假设有两台服务器，主服务器和备用服务器，运行相同主要版本的 PostgreSQL（建议使用 12 或更高版本）。

服务器	角色	IP 地址（示例）
主服务器	数据源	192.168.1.10
备用服务器	副本	192.168.1.11

用户： 您必须对两台服务器具有管理访问权限（例如，sudo 或 postgres 系统用户）。
网络： 备用服务器必须能够通过 PostgreSQL 端口（默认 5432）连接到主服务器。

步骤 1：配置主服务器

必须配置主服务器以生成并提供用于复制的 WAL 文件。

1.1 修改 `postgresql.conf`

编辑主配置文件。在 Debian 和 Ubuntu 软件包中，该文件通常位于 /etc/postgresql/<version>/main/postgresql.conf；在许多源代码或容器安装中，它位于数据目录中。设置以下参数：

# 允许来自其他主机的连接
listen_addresses = '*'

# 将 WAL 级别设置为 'replica' 或更高
wal_level = replica

# 来自备用服务器的最大并发连接数
max_wal_senders = 5 

# 控制可以同时激活的备用连接数
max_replication_slots = 5

# 允许在备用服务器上执行只读查询
hot_standby = on

1.2 创建专用复制用户

为了安全起见，创建一个具有 REPLICATION 属性的特定用户。该用户将仅由备用服务器用于拉取 WAL 记录。

# 连接到 PostgreSQL
sudo -u postgres psql -c "CREATE ROLE replica_user WITH REPLICATION LOGIN PASSWORD 'use-a-real-secret-here';"

1.3 更新客户端认证 (`pg_hba.conf`)

允许来自备用服务器 IP 地址的复制用户连接到特殊的 replication 伪数据库。

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    replication     replica_user    192.168.1.11/32         md5

1.4 重启主服务器

应用配置更改。更改 listen_addresses 后，重启是简单的选项；如果只更改了 pg_hba.conf，则重新加载即可。

sudo systemctl restart postgresql

步骤 2：准备备用服务器

在克隆数据之前，请确保备用服务器的 PostgreSQL 服务已停止，并且其现有数据目录已清空。

2.1 停止备用 PostgreSQL 服务

sudo systemctl stop postgresql

2.2 清空数据目录

警告： 此步骤将永久删除备用服务器数据目录中的所有现有数据。执行前请确认路径。

# PG 14 的示例路径
PG_DATA=/var/lib/postgresql/14/main

sudo rm -rf $PG_DATA/*

2.3 使用 `pg_basebackup` 克隆数据

使用 pg_basebackup 创建主服务器数据目录的精确副本。-R 标志至关重要，因为它会自动生成流式复制所需的配置文件（standby.signal 和 primary_conninfo）（PostgreSQL 12+）。

在备用服务器上运行此命令：

PG_DATA=/var/lib/postgresql/14/main

sudo -u postgres pg_basebackup -h 192.168.1.10 -D $PG_DATA -U replica_user -P -v -R

选项	描述
`-h`	主服务器主机名/IP 地址。
`-D`	本地数据目录路径。
`-U`	复制用户名（`replica_user`）。
`-P`	显示进度。
`-v`	详细输出。
`-R`	自动创建复制配置文件。

步骤 3：配置并启动备用服务器

3.1 验证备用服务器配置

如果您在步骤 2.3 中使用了 -R 标志，pg_basebackup 会创建一个 standby.signal 文件，并填充 primary_conninfo 设置，通常位于数据目录内生成的配置文件 postgresql.auto.conf 中。

验证 primary_conninfo 字符串的内容。它应该类似于以下内容（检查 $PG_DATA/postgresql.auto.conf 内部）：

primary_conninfo = 'host=192.168.1.10 user=replica_user password=SuperSecurePassword123 application_name=standby_node'

提示： 确保密码包含在 primary_conninfo 中，或者您正在使用基于证书的认证。如果使用 pg_hba.conf 的 trust 或 cert 方法，则可以省略密码。

3.2 启动备用服务

由于数据目录中存在所需的信号文件（standby.signal），服务将以只读备用模式启动，并立即尝试连接到主服务器。

sudo systemctl start postgresql

步骤 4：验证流式复制

启动备用服务器后，您必须确认连接处于活动状态并且数据同步正在进行。

4.1 在主服务器上验证

连接到主服务器并查询 pg_stat_replication 视图。您应该看到一行代表来自备用服务器的连接。

psql -c "SELECT client_addr, state, sync_state, sent_lsn, write_lsn, flush_lsn FROM pg_stat_replication;"

预期输出（关键字段）：

client_addr：应与备用服务器的 IP 匹配（例如，192.168.1.11）。
state：应为 streaming。如果显示 startup 或 catching up，请稍等片刻。如果显示 walsender 正在启动，则已接近完成。
sync_state：应为 async（对于标准异步复制）。

4.2 测试数据同步

为了确认数据流，在主服务器上执行更改，并立即检查备用服务器上是否存在该更改。

在主服务器上：

CREATE TABLE replication_test (id serial primary key, message text);
INSERT INTO replication_test (message) VALUES ('Data synchronized successfully');

在备用服务器上（只读）：

-- 此操作必须成功且无错误
psql -c "SELECT * FROM replication_test;"

如果数据在备用服务器上可见，则流式复制已成功配置并处于活动状态。

最佳实践和故障排除

持久连接：复制槽

虽然可选，但强烈建议使用复制槽。复制槽确保主服务器不会过早丢弃备用服务器所需的 WAL 段，即使备用服务器暂时断开连接。