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 从生成到归档成功或重试的状态链路

最小配置至少包含: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 文件名。

text
archive_mode = on
archive_command = '/usr/local/sbin/archive-wal.sh "%p" "%f"'
archive_timeout = '5min'

这段配置的生效结果是:完成的 WAL 段会传给脚本;低写入量场景下,archive_timeout 可以促使服务器切换 WAL 段,但它不替代归档成功判断,也不保证每隔 5 分钟一定产生新的归档文件。

下面的脚本以 GNU/Linux 上的独立本地归档目录为例。它先在目标目录写临时文件,再用硬链接原子地“只发布一次”;目标已存在时,仅在内容完全一致的情况下返回成功。

bash
#!/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 模块可用于本地文件归档和机制演示,但跨主机持久性、对象存储、复制与保留策略仍需要额外设计。

text
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 日志确认没有异常。

sql
SHOW archive_mode;
SHOW archive_command;

SELECT archived_count, failed_count, last_archived_wal
FROM pg_stat_archiver;

SELECT pg_switch_wal();

预期输出中的 LSN、计数和 WAL 文件名取决于实例状态,实际值会不同:

text
 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>

等待归档完成后再次执行查询:

sql
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 的前提。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 archive_mode 与归档命令

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通