PostgreSQL / 系统课时
验证备份清单与文件完整性
验证备份清单与文件完整性
本课不再重复“怎样运行一次完整性校验”,而是解决更靠近生产的问题:怎样把校验结果变成可审计的备份验收状态。最终形成一条门禁:复制完成不等于可恢复,只有指定备份、必要 WAL、工具版本与完整校验全部通过后,才登记为可用。
学习目标
- 将
pg_verifybackup的退出状态接入备份验收门禁 - 正确处理外置 WAL、工具主版本与不可变备份标识
- 用独立且原子更新的状态文件区分“复制完成”“验收中”“已通过”和“已拒绝”
把校验结果变成状态迁移
备份流水线至少要区分复制和验收两个阶段。复制程序返回成功,只能说明数据已经落到目标位置;验收程序返回成功后,备份才可以进入恢复候选集。这样做的重点不是再解释 backup_manifest 的校验细节,而是避免调度器、保留策略或恢复脚本误用尚未验收的制品。
建议把状态放在备份目录之外,并使用稳定的备份 ID,而不是把 latest 这类可移动别名当作验收对象。一次验收开始时写入 VERIFYING,完整通过后原子替换为 VERIFIED;任一步失败则写入 REJECTED。状态文件与备份制品分离,也不会向待检目录额外写入文件。

固定验收输入
完整验收开始前先固定四个输入:不可变的备份目录、该目录中的 backup_manifest、存放所需 WAL 的目录,以及与该备份主版本一致的 pg_verifybackup。WAL 解析具有版本相关性,因此不能随意拿另一主版本的工具完成“全量通过”登记。
如果 WAL 不在备份目录的 pg_wal 中,可用 -w <PATH> 指向外置 WAL 目录。这里的路径应是本次验收明确绑定的归档位置;不要因为某个共享目录“通常都有 WAL”就直接登记通过,否则后续清理或并发归档可能改变验收输入。
用脚本完成原子登记
下面的主示例把状态登记、版本检查、外置 WAL 和退出码合并到一个流程。示例要求 BACKUP_ID 对应不可变目录;状态文件先写临时文件,再用 mv 原子替换,避免消费者读到半写入内容。
#!/usr/bin/env bash
set -euo pipefail
BACKUP_ID="${BACKUP_ID:-base-20260830-001}"
BACKUP_ROOT="${BACKUP_ROOT:-/backup/base}"
WAL_DIR="${WAL_DIR:-/backup/wal}"
STATE_DIR="${STATE_DIR:-/backup/state}"
BACKUP_DIR="$BACKUP_ROOT/$BACKUP_ID"
STATUS_FILE="$STATE_DIR/$BACKUP_ID.status"
reject() {
echo "reject: $*" >&2
exit 1
}
write_status() {
local status="$1"
local tmp
tmp="$(mktemp "${STATUS_FILE}.tmp.XXXXXX")"
printf 'status=%s\nbackup_id=%s\nupdated_at=%s\nbackup_path=%s\nwal_path=%s\n' \
"$status" "$BACKUP_ID" "$(date -u +%FT%TZ)" "$BACKUP_DIR" "$WAL_DIR" > "$tmp"
chmod 600 "$tmp"
mv -f "$tmp" "$STATUS_FILE"
}
install -d -m 700 "$STATE_DIR"
# 失败退出时把本次验收登记为 REJECTED。
on_exit() {
local rc=$?
trap - EXIT
if [ "$rc" -ne 0 ]; then
write_status "REJECTED" || true
fi
exit "$rc"
}
trap on_exit EXIT
write_status "VERIFYING"
# 完整验收要求清单、版本文件和外置 WAL 目录都已就绪。
test -f "$BACKUP_DIR/backup_manifest" || reject "missing backup_manifest"
test -f "$BACKUP_DIR/PG_VERSION" || reject "missing PG_VERSION"
test -d "$WAL_DIR" || reject "missing WAL directory"
BACKUP_MAJOR="$(tr -d '[:space:]' < "$BACKUP_DIR/PG_VERSION")"
TOOL_MAJOR="$(
pg_verifybackup --version |
awk '{for (i=1;i<=NF;i++) if ($i ~ /^[0-9]+([.][0-9]+)+/) {split($i,v,"."); print v[1]; exit}}'
)"
test -n "$TOOL_MAJOR" || reject "cannot detect pg_verifybackup version"
test "$BACKUP_MAJOR" = "$TOOL_MAJOR" || reject "pg_verifybackup major version mismatch"
# 只有该命令状态码为 0,才允许把备份升级为 VERIFIED。
pg_verifybackup --quiet -w "$WAL_DIR" "$BACKUP_DIR"
write_status "VERIFIED"
trap - EXIT
echo "backup accepted: $BACKUP_ID"
cat "$STATUS_FILE"预期输出
backup accepted: base-20260830-001
status=VERIFIED
backup_id=base-20260830-001
updated_at=<TIME>
backup_path=/backup/base/base-20260830-001
wal_path=/backup/wal<TIME> 为实际 UTC 时间。若清单缺失、WAL 目录不存在、工具主版本不匹配或 pg_verifybackup 返回非 0,脚本都会以非 0 状态结束,并把该备份登记为 REJECTED,不会留下 VERIFIED 状态。
区分完整验收与降级检查
--skip-checksums 会跳过文件内容校验和比较,--no-parse-wal 会跳过所需 WAL 的解析检查。它们可以用于受控诊断或明确的降级流程,但不应与完整验收共用 VERIFIED。如果业务确实需要这类快速检查,应登记成单独状态,例如 PARTIAL,并让恢复候选选择器默认排除它。
这个课时的验收边界到“备份制品与必要 WAL 达到自动化门禁条件”为止。真实恢复启动、数据库对象检查以及 PITR 目标是否可达,仍应由恢复演练负责;门禁的价值在于让未验收或降级验收的备份无法被误当成正式恢复源。