PostgreSQL / 系统课时
配置 archive_mode 与归档命令
配置 archive_mode 与归档命令
本课把 PostgreSQL 从“只在本机生成 WAL”改造成“持续把已完成 WAL 安全交给归档存储”的链路。重点不只是复制文件,而是让失败可见、重试幂等、既有归档不可被静默覆盖,并能用统计视图与日志确认归档持续前进。
学习目标
- 正确启用
archive_mode,并理解archive_command与archive_library的生效关系。 - 编写不会覆盖既有 WAL、重复执行仍安全的归档逻辑。
- 通过切换 WAL、
pg_stat_archiver与日志验证归档是否真正成功。
先把归档链路拆清楚
开启归档后,WAL 仍先写入 pg_wal。只有已经完成的 WAL 段才会交给 archiver;归档命令返回成功,或归档模块返回成功后,该段才会被记为已归档。失败会触发后续重试,因此成功返回值必须等价于“WAL 已经安全持久化”。

最小配置至少包含:wal_level 不能为 minimal,并启用 archive_mode = on。archive_mode 只能在服务器启动时生效,因此修改后需要重启;archive_command 与 archive_library 可以在保持归档模式开启的情况下调整。若 archive_library 非空,归档由该模块处理,archive_command 不再承担归档工作。
使用 archive_command 安全发布 WAL
不要把复杂的复制、校验和对象存储逻辑直接塞进 postgresql.conf。更稳妥的做法是让 archive_command 只调用受版本控制的脚本,并给 %p 与 %f 加引号:前者是待归档 WAL 的路径,后者是 WAL 文件名。
archive_mode = on
archive_command = '/usr/local/sbin/archive-wal.sh "%p" "%f"'
archive_timeout = '5min'这段配置的生效结果是:完成的 WAL 段会传给脚本;低写入量场景下,archive_timeout 可以促使服务器切换 WAL 段,但它不替代归档成功判断,也不保证每隔 5 分钟一定产生新的归档文件。
下面的脚本以 GNU/Linux 上的独立本地归档目录为例。它先在目标目录写临时文件,再用硬链接原子地“只发布一次”;目标已存在时,仅在内容完全一致的情况下返回成功。
#!/bin/sh
set -eu
src=$1
name=$2
dst_dir=/srv/postgresql/wal-archive
dst="$dst_dir/$name"
tmp=$(mktemp "$dst_dir/.$name.XXXXXX")
umask 077
trap 'rm -f "$tmp"' EXIT HUP INT TERM
cp -- "$src" "$tmp"
sync "$tmp"
# 同一文件系统内创建硬链接不会覆盖已存在的最终文件。
if ln -- "$tmp" "$dst" 2>/dev/null; then
sync "$dst_dir"
exit 0
fi
# PostgreSQL 可能重试同一 WAL;只有内容相同才允许幂等成功。
if cmp -s -- "$src" "$dst"; then
exit 0
fi
exit 1预期结果:首次归档时创建目标文件并返回退出码 0;同一 WAL 被再次归档时,若既有文件内容相同仍返回 0;若同名文件内容不同或目标不可读,则返回非零退出码,PostgreSQL 不会把错误文件当成成功归档。
本例要求临时文件与最终文件位于同一文件系统,并假设归档目录不会被不受信任的进程修改。若目标是对象存储,应改用“仅当对象不存在时创建”或等价的条件写入能力;对象已存在时还要校验内容或可靠校验和,不能依赖默认覆盖语义。
需要时改用 archive_library
PostgreSQL 15 及以上可以通过 archive_library 把归档逻辑放进归档模块,避免每个 WAL 段都启动外部 shell。内置的 basic_archive 模块可用于本地文件归档和机制演示,但跨主机持久性、对象存储、复制与保留策略仍需要额外设计。
archive_mode = on
archive_command = ''
archive_library = 'basic_archive'
basic_archive.archive_directory = '/srv/postgresql/wal-archive'生效行为是:archiver 调用 basic_archive 写入指定目录,不再通过 archive_command 执行 shell。PostgreSQL 14 及更早版本没有 archive_library,应继续使用 archive_command。
验证归档确实持续推进
重启使 archive_mode 生效后,先记录 pg_stat_archiver 的计数,再主动切换一次 WAL。归档完成后再次查询,核心判断是 archived_count 相比基线至少增加 1,并结合 last_archived_wal、failed_count 和 PostgreSQL 日志确认没有异常。
SHOW archive_mode;
SHOW archive_command;
SELECT archived_count, failed_count, last_archived_wal
FROM pg_stat_archiver;
SELECT pg_switch_wal();预期输出中的 LSN、计数和 WAL 文件名取决于实例状态,实际值会不同:
archive_mode
--------------
on
archive_command
-----------------------------------------------------------
/usr/local/sbin/archive-wal.sh "%p" "%f"
archived_count | failed_count | last_archived_wal
----------------+--------------+----------------------------
<VALUE> | <VALUE> | <WAL_FILE>
pg_switch_wal
---------------
<LSN>等待归档完成后再次执行查询:
SELECT archived_count, failed_count, last_archived_wal
FROM pg_stat_archiver;预期结果:archived_count 相比切换前增加至少 1,last_archived_wal 更新为新的 WAL 文件名;failed_count 不应因本次测试异常增长。统计视图不是唯一证据,归档失败时还应同时检查 PostgreSQL 日志与目标存储中的实际文件。
识别会破坏恢复链的失败方式
最危险的问题通常不是“命令报错”,而是命令失败却返回成功。例如用 || true 吞掉错误、只根据文件名存在就成功、上传失败后仍返回 0,都会让 PostgreSQL 过早认为 WAL 已安全归档。
归档目录也不应位于 PGDATA,或与数据库共用同一故障域的易失磁盘上,否则一次主机或磁盘故障可能同时带走在线 WAL 和归档副本。配置完成后,应把“归档成功”定义为可验证、可重复读取的持久化结果;这是后续 PITR 能连续取得 WAL 的前提。