PostgreSQL / 系统课时
使用 pg_basebackup 创建基础备份
使用 pg_basebackup 创建基础备份
pg_basebackup 能从运行中的 PostgreSQL 实例生成物理基础备份,并取得恢复所需的 WAL。本文从复制权限、检查点、WAL 策略到完整性校验走一遍,得到可用于物理恢复或 PITR 的可靠起点。
学习目标
- 能准备
pg_basebackup所需的复制连接与权限。 - 能解释
spread/fast检查点和stream/fetchWAL 策略的差异。 - 会创建并校验一份完整的 plain-format 基础备份。
确认复制权限与连接容量
pg_basebackup 通过 replication protocol 连接源库,执行账号需要 LOGIN 与 REPLICATION 属性,pg_hba.conf 还必须允许该账号从备份机发起 replication 连接。使用 --wal-method=stream 时,会额外启动 WAL receiver,因此基础备份连接和 WAL 流一共需要两个 replication 连接。
psql -d postgres -Atc "SELECT rolname || ':' || rolreplication FROM pg_roles WHERE rolname='backup_user';"
psql -d postgres -Atc "SHOW max_wal_senders;"预期输出
backup_user:true
<VALUE><VALUE> 是实例配置值;还要结合当前已有的复制连接判断是否至少有两个可用 sender 槽位。若角色尚未创建,应由具备角色管理权限的管理员建立专用备份账号,并避免使用超级用户长期执行备份。
备份机对应的 pg_hba.conf 规则可以采用如下形式,地址应收窄为实际备份主机或网段。
host replication backup_user <IP>/32 scram-sha-256修改后需要重新加载配置,并通过一次真实 pg_basebackup 连接验证规则是否命中。密码建议放入权限为 0600 的 .pgpass,不要直接写在命令行历史中。
创建 plain-format 基础备份
下面把备份写入独立目录,使用 plain format、流式获取 WAL,并让检查点以较平缓的 spread 方式完成。<IP>、<PORT>、<PATH> 与 <TIME> 都应替换为实际环境值;目标目录应不存在或保持为空。
SOURCE_HOST='<IP>'
SOURCE_PORT='<PORT>'
BACKUP_DIR='<PATH>/base-<TIME>'
pg_basebackup \
--host="$SOURCE_HOST" \
--port="$SOURCE_PORT" \
--username=backup_user \
--pgdata="$BACKUP_DIR" \
--format=plain \
--wal-method=stream \
--checkpoint=spread \
--progress \
--verbose预期输出
pg_basebackup: initiating base backup, waiting for checkpoint to complete
pg_basebackup: checkpoint completed
pg_basebackup: write-ahead log start point: <LSN> on timeline <ID>
pg_basebackup: write-ahead log end point: <LSN>
pg_basebackup: base backup completed不同 PostgreSQL 版本的详细提示行和进度输出可能略有差异,但成功时进程应以 0 退出,并在 $BACKUP_DIR 中形成完整数据目录、backup_label 与默认生成的 backup_manifest。
理解检查点与 WAL 如何配合
基础备份开始时,服务器先建立一致的备份边界;随后数据文件持续传输,而备份期间发生的新写入由 WAL 记录补齐。使用 stream 时,pg_basebackup 会在数据复制之外再开一条 WAL 流,直到覆盖基础备份的结束位置。stream 也是当前 pg_basebackup 的默认 WAL 获取方式。

--checkpoint=spread 是默认方式,让检查点 I/O 分散执行;--checkpoint=fast 会尽快完成检查点,适合恢复演练或备份窗口很紧的场景,但可能制造更明显的 I/O 峰值。
WAL 策略决定基础备份怎样取得恢复所需日志。stream 边复制数据边接收 WAL;fetch 在数据文件复制结束后再取所需 WAL,因此必须保证这些 WAL 在此期间没有被回收;none 不把 WAL 放进备份,只有在你已经有可靠 WAL 来源并能保证恢复链完整时才适合使用。
校验备份完整性
备份命令退出 0 之后,还应使用与备份源主要版本匹配的 pg_verifybackup,根据 manifest 检查文件、校验和以及恢复所需 WAL。它能尽早发现复制后文件损坏或缺失,但仍不能替代定期的隔离恢复演练。
BACKUP_DIR='<PATH>/base-<TIME>'
pg_verifybackup "$BACKUP_DIR"预期输出
backup successfully verified还可以确认关键元数据确实存在,避免把一个中途失败留下的目录误登记为成功备份。
BACKUP_DIR='<PATH>/base-<TIME>'
test -f "$BACKUP_DIR/backup_label" \
&& test -f "$BACKUP_DIR/backup_manifest" \
&& echo "backup metadata ok"预期输出
backup metadata ok如果 pg_basebackup 因网络中断、磁盘写满或复制连接被终止而非零退出,默认会尽量清理它创建的目录;若仍存在人工准备或调试选项留下的残留目录,也不要把它继续加入备份链,应修复根因后重新执行。
识别最常见的失败点
连接阶段报 replication 权限或 pg_hba.conf 错误时,先检查角色属性、来源地址和 HBA 匹配顺序。启动 WAL receiver 失败时,再检查 max_wal_senders 是否还有可用槽位,以及是否被现有流复制、归档工具或其他基础备份占满。
如果选择 fetch 后提示所需 WAL 已不存在,说明备份持续时间超过了源库对旧 WAL 的保留能力;可以改用 stream,或先完善 WAL 归档与保留策略。若 pg_verifybackup 失败,则该批次不能作为可信恢复起点,应保留错误证据并重新生成基础备份。
一份可用的基础备份必须同时满足三点:数据文件完整、覆盖备份边界的 WAL 可获得、校验结果可信。把这三项作为固定验收条件,后续无论做物理恢复、搭建副本还是建立 PITR 链,都有可靠的起点。