设置 PostgreSQL 流复制的分步指南

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

本综合指南将指导您完成建立稳定、异步流复制所需的关键步骤。我们涵盖了主服务器和备用服务器上必要的配置更改，并利用了现代 PostgreSQL 功能（例如 pg_basebackup 和信号文件）来简化设置。遵循本教程将为您稳健的 PostgreSQL 操作奠定可靠的基础。

先决条件和环境设置

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

服务器	角色	IP 地址 (示例)
Primary (主)	事实来源	192.168.1.10
Standby (备用)	副本	192.168.1.11

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

步骤 1：配置主服务器

必须配置主服务器，以便它能够生成并提供 WAL 文件用于复制。

1.1 修改 `postgresql.conf`

编辑主配置文件，该文件通常位于数据目录中（例如 /etc/postgresql/14/main/postgresql.conf），并设置以下参数：

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

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

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

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

# 备用服务器上进行只读查询所需 (热备用 Hot Standby)
hot_standby = on

1.2 创建专用的复制用户

出于安全考虑，创建一个具有 REPLICATION 属性的特定用户。该用户将仅供备用服务器用于拉取 WAL 记录。

# 连接到 PostgreSQL
psql -c "CREATE USER replica_user REPLICATION ENCRYPTED PASSWORD 'SuperSecurePassword123';"

1.3 更新客户端身份验证 (`pg_hba.conf`)

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

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

1.4 重启主服务器

通过重启 PostgreSQL 服务来应用更改：

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 段，即使备用服务器暂时断开连接。