跳到主要内容

PostgreSQL 18 两台服务器主备搭建:从零到可切换

· 阅读需 14 分钟

单机数据库最大的问题是它只有一份。磁盘坏了、机器宕了、机房断网了,业务就停在原地。本文记录用两台服务器、两个 Docker Compose 实例,从零搭出一套 PostgreSQL 18 异步流复制主备的完整过程,包括参数选择、备库初始化、验证、手动切换和故障处理。

背景与目标​

需求很明确:

  • 主库故障时,备库可以接管,数据最多丢失一个很小的窗口
  • 备库平时可以提供只读查询,分担报表和统计压力
  • 整个方案只依赖两台服务器和 Docker,不引入额外的中间件

最终形态:

角色地址说明
主库10.0.0.11接受读写,向备库发送 WAL
备库10.0.0.12持续接收并回放 WAL,只读

方案选择​

物理流复制而不是逻辑复制​

PostgreSQL 的复制分两类:

  • 物理流复制:按 WAL 字节流复制整个集群,备库和主库完全一致,适合容灾和只读分流
  • 逻辑复制:按表复制数据变更,可以选择性复制、跨版本复制,但配置复杂,DDL 不会自动同步

这里的目标是“整机接管”,选物理流复制。它不需要为每张表建 publication,也不会漏掉 DDL。

异步复制而不是同步复制​

异步复制下,主库提交事务不等待备库确认,因此主库故障时,尚未传到备库的 WAL 会丢失。同步复制可以消除这个窗口,但代价是:

  • 每次提交都多一次网络往返,写入延迟上升
  • 备库故障或网络抖动会直接阻塞主库写入

对大多数业务来说,异步复制 + 监控延迟是更稳妥的起点。等业务明确要求“零丢失”时,再按 配置说明 里的 synchronous_commit 和 synchronous_standby_names 开启同步复制。

使用物理复制槽​

如果不使用复制槽,主库会按 checkpoint 回收旧 WAL。备库只要断开时间稍长,就可能因为 WAL 已被删除而无法追平,只能重做基础备份。

复制槽会让主库保留备库还没确认的 WAL。代价是备库长期离线时,WAL 会一直堆积。因此必须同时设置 max_slot_wal_keep_size 给槽的保留量封顶:宁可槽失效后重建备库,也不能让主库磁盘被写满。

为什么用 PostgreSQL 18​

两台服务器都是全新实例,没有“必须跟随现网 17”的约束,所以直接用 18:它是当前最新稳定版,支持到 2030-11。18 还有一个和本方案相关的好处:initdb 默认开启数据校验和,后面如果要用 pg_rewind 把旧主库接回来,不需要额外开启 wal_log_hints。

需要提前知道 18 的镜像布局变化:

  • PGDATA 是 /var/lib/postgresql/18/docker
  • 挂载卷是 /var/lib/postgresql,不是旧版的 /var/lib/postgresql/data

准备两台服务器​

两台机器都需要:

  • 安装 Docker 和 Docker Compose
  • 时间同步正常(chrony 或 systemd-timesyncd),避免切换后时间线判断异常
  • 创建 /app/postgres 目录

网络和防火墙只做最小放行:

  • 备库 10.0.0.12 可以访问主库 10.0.0.11 的 5432
  • 运维机可以访问两台机器的 5432(按需)

不要把 5432 直接暴露到公网。

第一步:部署主库​

主库的 /app/postgres/docker-compose.yml:

services:
postgres:
image: postgres:18
container_name: postgres
restart: unless-stopped
environment:
POSTGRES_DB: appdb
POSTGRES_USER: appuser
POSTGRES_PASSWORD: change_me
TZ: Asia/Shanghai
PGTZ: Asia/Shanghai
ports:
- "5432:5432"
volumes:
- ./data:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
interval: 30s
timeout: 10s
retries: 5
start_period: 30s

启动:

cd /app/postgres
docker compose up -d
docker compose ps
docker logs -f postgres

确认数据目录结构:

/app/postgres/data/
└─ 18/
└─ docker/ # 实际 PGDATA

进入数据库确认状态:

docker exec -it postgres psql -U appuser -d appdb
SELECT version();
SHOW data_checksums;
SHOW password_encryption;

18 的预期结果是 data_checksums = on、password_encryption = scram-sha-256。

第二步:主库开启复制​

1. 创建复制账号​

复制账号只需要 REPLICATION 和 LOGIN,不要给它业务库权限:

docker exec -i postgres psql -U appuser -d postgres <<'SQL'
CREATE ROLE replicator WITH REPLICATION LOGIN PASSWORD 'repl_change_me';
SQL

密码会按 scram-sha-256 存储。

2. 调整主库参数​

docker exec -i postgres psql -U appuser -d postgres <<'SQL'
ALTER SYSTEM SET wal_level = 'replica';
ALTER SYSTEM SET max_wal_senders = 10;
ALTER SYSTEM SET max_replication_slots = 10;
ALTER SYSTEM SET wal_keep_size = '1GB';
ALTER SYSTEM SET max_slot_wal_keep_size = '10GB';
SQL

wal_level、max_wal_senders、max_replication_slots 都是 postmaster 级参数,必须重启:

docker restart postgres

重启后确认:

SHOW wal_level;
SHOW max_wal_senders;
SHOW max_replication_slots;
SHOW max_slot_wal_keep_size;

各参数的含义和配错的后果,单独整理在 配置说明 里。

3. 允许备库的复制连接​

物理复制连接在 pg_hba.conf 中使用的是 replication 这个特殊数据库关键字,不是 all:

docker exec -i postgres bash -c '
grep -q "^host replication replicator 10.0.0.12/32" "$PGDATA/pg_hba.conf" \
|| echo "host replication replicator 10.0.0.12/32 scram-sha-256" >> "$PGDATA/pg_hba.conf"
'

pg_hba.conf 修改后 reload 即可,不需要重启:

docker exec -i postgres psql -U appuser -d postgres -c "SELECT pg_reload_conf();"

可以用下面的查询确认规则已经生效:

SELECT line_number, type, database, user_name, address, auth_method
FROM pg_hba_file_rules
WHERE database::text LIKE '%replication%';

4. 创建物理复制槽​

docker exec -i postgres psql -U appuser -d postgres \
-c "SELECT pg_create_physical_replication_slot('standby1');"

确认槽存在:

SELECT slot_name, slot_type, active FROM pg_replication_slots;

此时 active 应该是 false,因为备库还没连上来。

第三步:初始化备库​

备库现在还是一台空机器。先用 pg_basebackup 从主库拉一份基础备份,同时让工具自动写好流复制配置。

1. 准备数据目录​

官方镜像里的 postgres 用户 UID 通常是 999,目录属主要对上。如果镜像版本不同,可以先执行 docker run --rm postgres:18 id postgres 确认实际 UID:

sudo mkdir -p /app/postgres/data
sudo chown -R 999:999 /app/postgres/data

2. 拉取基础备份​

docker run --rm --user postgres \
-e PGPASSWORD='repl_change_me' \
-v /app/postgres/data:/var/lib/postgresql \
postgres:18 \
bash -c 'pg_basebackup -h 10.0.0.11 -p 5432 -U replicator -D "$PGDATA" -Fp -Xs -P -R -S standby1'

参数说明:

参数作用
-h 10.0.0.11主库地址
-U replicator复制账号
-D "$PGDATA"写入容器内的 /var/lib/postgresql/18/docker
-Fp明文目录格式,便于直接启动
-Xs备份期间流式传输 WAL
-P显示进度
-R自动创建 standby.signal,并把连接信息写入 postgresql.auto.conf
-S standby1使用主库上已经创建好的物理槽

注意两点:

  • -D 指定的目录必须为空或不存在,重复执行前要先清理
  • 命令里的单引号不要改成双引号,$PGDATA 需要在容器内展开

3. 确认自动生成的配置​

ls -l /app/postgres/data/18/docker/standby.signal
grep -E 'primary_conninfo|primary_slot_name' \
/app/postgres/data/18/docker/postgresql.auto.conf

预期能看到类似内容:

primary_conninfo = 'user=replicator password=repl_change_me host=10.0.0.11 port=5432 ...'
primary_slot_name = 'standby1'

standby.signal 的存在告诉 PostgreSQL:这次启动要以备库身份进入恢复模式。

第四步:启动备库​

备库的 compose 文件和主库基本一样,但不需要 POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD:

services:
postgres:
image: postgres:18
container_name: postgres
restart: unless-stopped
environment:
TZ: Asia/Shanghai
PGTZ: Asia/Shanghai
ports:
- "5432:5432"
volumes:
- ./data:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
interval: 30s
timeout: 10s
retries: 5
start_period: 30s

这些环境变量只在初始化空数据目录时使用。备库的数据目录已经由 pg_basebackup 初始化过,镜像会打印 “Skipping initialization” 并直接启动。

启动并观察日志:

cd /app/postgres
docker compose up -d
docker logs -f postgres

日志里应该出现:

LOG: entering standby mode
LOG: started streaming WAL from primary at ...
LOG: consistent recovery state reached
LOG: database system is ready to accept read-only connections

第五步:验证复制​

主库视角​

SELECT client_addr,
application_name,
state,
sync_state,
sent_lsn,
replay_lsn,
replay_lag,
pg_size_pretty(pg_wal_lsn_diff(sent_lsn, replay_lsn)) AS replay_lag_bytes
FROM pg_stat_replication;

预期:有一行记录,state = streaming,sync_state = async,replay_lag_bytes 很小或为 0。

备库视角​

SELECT status,
sender_host,
slot_name,
latest_end_lsn,
last_msg_receipt_time
FROM pg_stat_wal_receiver;

SELECT pg_is_in_recovery() AS is_standby,
pg_last_wal_receive_lsn() AS received_lsn,
pg_last_wal_replay_lsn() AS replayed_lsn,
now() - pg_last_xact_replay_timestamp() AS replay_delay;

预期:status = streaming,is_standby = true,replay_delay 很小。

写入验证​

在主库建表并写入:

docker exec -i postgres psql -U appuser -d appdb <<'SQL'
CREATE TABLE repl_check (id int PRIMARY KEY, note text);
INSERT INTO repl_check VALUES (1, 'hello from primary');
SQL

在备库查询:

docker exec -i postgres psql -U appuser -d appdb \
-c "SELECT * FROM repl_check;"

能查到数据,说明 WAL 已经完成传输和回放。再在备库尝试写入,应该收到只读错误:

ERROR: cannot execute INSERT in a read-only transaction

这是预期行为,备库在恢复期间就是只读的。

日常监控​

复制搭起来只是开始,真正需要盯的是延迟和 WAL 堆积。

延迟​

在主库执行:

SELECT application_name,
client_addr,
replay_lag,
pg_size_pretty(pg_wal_lsn_diff(sent_lsn, replay_lsn)) AS lag_bytes
FROM pg_stat_replication;

建议至少对以下情况告警:

  • pg_stat_replication 没有记录,或 state 不是 streaming
  • replay_lag 持续超过 30 秒
  • lag_bytes 持续增长

WAL 堆积​

SELECT slot_name,
active,
wal_status,
restart_lsn,
pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained_wal
FROM pg_replication_slots;

关注点:

  • active = false 说明备库没在用这个槽,WAL 会继续保留
  • wal_status 变成 lost 说明槽已经失效,备库必须重建
  • retained_wal 接近磁盘可用空间时,必须先处理,否则主库会写满

手动主备切换​

下面是一次计划内切换的完整流程。故障切换的原理相同,只是没有时间等延迟归零。

1. 停止写入并确认延迟归零​

先停掉应用写入或摘掉流量,然后在主库确认备库已经追平:

SELECT application_name,
pg_wal_lsn_diff(sent_lsn, replay_lsn) AS lag_bytes
FROM pg_stat_replication;

lag_bytes = 0 时再继续。

2. 提升备库​

在备库执行:

docker exec -it postgres psql -U appuser -d postgres -c "SELECT pg_promote();"

确认已经退出恢复模式:

SELECT pg_is_in_recovery() AS is_standby,
(SELECT timeline_id FROM pg_control_checkpoint()) AS timeline;

is_standby 应该变成 false,时间线会加 1。

3. 切换应用连接​

把应用的数据库地址改到新的主库 10.0.0.12,确认读写正常。此时旧主库必须先停掉,避免两边同时接受写入造成双主。

4. 把旧主库接回来​

旧主库的时间线已经和新主库分叉,不能直接启动继续当主库。接回来之前,先在新主库上放行旧主库的复制连接:

docker exec -i postgres bash -c '
grep -q "^host replication replicator 10.0.0.11/32" "$PGDATA/pg_hba.conf" \
|| echo "host replication replicator 10.0.0.11/32 scram-sha-256" >> "$PGDATA/pg_hba.conf"
'
docker exec -i postgres psql -U appuser -d postgres -c "SELECT pg_reload_conf();"

这一步很容易漏:新主库的 pg_hba.conf 是从原主库复制过来的,里面只有原备库 10.0.0.12 的规则,不会自动放行 10.0.0.11。

方式一:重新做基础备份(推荐,最稳)

先在新主库上为旧主库创建复制槽:

SELECT pg_create_physical_replication_slot('oldprimary');

然后在旧主库上清空并重新拉取:

cd /app/postgres
docker compose down
sudo rm -rf data
sudo mkdir -p data
sudo chown -R 999:999 data

docker run --rm --user postgres \
-e PGPASSWORD='repl_change_me' \
-v /app/postgres/data:/var/lib/postgresql \
postgres:18 \
bash -c 'pg_basebackup -h 10.0.0.12 -p 5432 -U replicator -D "$PGDATA" -Fp -Xs -P -R -S oldprimary'

docker compose up -d

数据量不大时,这个方式最简单,也最容易确认结果。

方式二:pg_rewind(数据量大时更快)

pg_rewind 只同步分叉后变化的块,不需要全量拷贝。前提是旧主库被干净关闭,并且集群开启了数据校验和或 wal_log_hints。18 默认开启校验和,这个条件通常已经满足。

pg_rewind 需要读取源端的文件系统信息,普通复制账号默认没有这些权限。先在新主库上给 replicator 补上函数权限:

docker exec -i postgres psql -U appuser -d postgres <<'SQL'
GRANT EXECUTE ON FUNCTION pg_catalog.pg_ls_dir(text, boolean, boolean) TO replicator;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_stat_file(text, boolean) TO replicator;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_read_binary_file(text) TO replicator;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO replicator;
SQL

然后在旧主库上执行 rewind:

cd /app/postgres
docker compose down

docker run --rm --user postgres \
-e PGPASSWORD='repl_change_me' \
-v /app/postgres/data:/var/lib/postgresql \
postgres:18 \
bash -c 'pg_rewind -D "$PGDATA" --source-server="host=10.0.0.12 port=5432 user=replicator dbname=postgres" -R -P'

docker compose up -d

-R 会生成 standby.signal,并把连接信息写进 postgresql.auto.conf。连接信息里的用户就是刚才执行 rewind 的 replicator,所以前面的复制规则和函数权限必须都对上。如果 pg_rewind 提示找不到分叉点之后的 WAL,就需要配置归档恢复,或者退回方式一。

常见故障​

现象原因处理
备库日志报 no pg_hba.conf entry for replication connectionpg_hba.conf 用了 all 而不是 replication,或备库 IP 不在网段内修正规则后 pg_reload_conf()
备库日志报 password authentication failedprimary_conninfo 里的账号密码不对重新生成或手工修正 postgresql.auto.conf 后重启备库
备库日志报 replication slot "standby1" does not exist主库槽没创建,或名字拼错在主库创建同名物理槽
主库 pg_stat_replication 为空备库没启动、防火墙拦截、max_wal_senders = 0依次检查备库进程、网络、主库参数
备库追不上,主库 WAL 已被删除没有复制槽,或 wal_keep_size 太小创建槽并合理设置 wal_keep_size
主库磁盘被 WAL 写满有长期 inactive 的槽检查 pg_replication_slots,必要时删槽或重建备库
备库报 requested timeline ... is not in the history主备时间线分叉pg_rewind 或重新 pg_basebackup
备库启动报权限错误数据目录属主不是 UID 999chown -R 999:999 /app/postgres/data

上线前检查清单​

  • 主备 SELECT version() 的大版本一致
  • 主库 wal_level = replica
  • 主库 max_wal_senders 大于备库数量
  • pg_hba.conf 有 host replication <user> <standby-ip>/32 scram-sha-256
  • 物理复制槽已创建,且备库 primary_slot_name 与之一致
  • max_slot_wal_keep_size 已设置,不会写满主库磁盘
  • 监控覆盖复制状态、延迟和 WAL 堆积
  • 至少演练过一次手动切换和旧主库回归
  • 基础备份和 WAL 归档策略单独确认,主备不等于备份

主备解决的是“机器或实例故障时业务能继续”,不解决误删数据、错误更新这类逻辑故障。真正的备份仍然需要独立的 pg_basebackup、WAL 归档或逻辑导出,并且要定期做恢复演练。

字段级别的详细说明,包括每个参数的默认值、推荐值和配错的后果,见 PostgreSQL 主备复制配置说明。