PostgreSQL 18 两台服务器主备搭建:从零到可切换
单机数据库最大的问题是它只有一份。磁盘坏了、机器宕了、机房断网了,业务就停在原地。本文记录用两台服务器、两个 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不是streamingreplay_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 connection | pg_hba.conf 用了 all 而不是 replication,或备库 IP 不在网段内 | 修正规则后 pg_reload_conf() |
备库日志报 password authentication failed | primary_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 999 | chown -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 主备复制配置说明。