pg_basebackup 是 PostgreSQL 自带的物理备份工具，适用于快速搭建从库、灾难恢复及高一致性全量备份场景，但需数据库启用归档模式并允许复制连接。

pg_basebackup 是什么，它适合哪种备份场景

pg_basebackup 是 PostgreSQL 自带的物理备份工具，直接拷贝数据目录下的所有文件（包括 WAL 归档前的预写日志），生成一个一致的、可启动的数据库快照。它不依赖 SQL 导出，也不解析表结构或数据内容，因此速度快、恢复可靠——但要求数据库处于归档模式（archive_mode = on）且主库允许复制连接。

• 适用于：需要快速搭建从库、灾难恢复、或对一致性要求极高的生产环境全量备份
• 不适用于：只想备份某几张表、或数据库停机不可接受且未配置流复制的场景
• 注意：pg_basebackup 默认不自动归档 WAL，若要支持时间点恢复（PITR），必须配合 archive_command 和归档路径使用

执行 pg_basebackup 前必须确认的 4 个配置项

PostgreSQL 不会主动告诉你哪些配置没开，直到报错才暴露问题。以下四项缺一不可：

• listen_addresses 必须包含备份发起方能访问的 IP（如 'localhost,192.168.1.10'），不能是 'localhost' 就完事
• max_wal_senders 要 ≥ 1（建议设为 5–10），否则并发备份或流复制会失败
• archive_mode = on 且 archive_command 已测试成功（可用 pg_archivecleanup 验证归档是否写入）
• pg_hba.conf 中需有明确允许 replication 数据库 + trust 或 md5 的条目，例如：

  host    replication     all             192.168.1.0/24        md5

常见 pg_basebackup 报错及对应修复动作

报错不是随机发生的，基本都卡在这几个环节：

• could not connect to server: Connection refused → 检查 postgresql.conf 的 listen_addresses 和 port，再 telnet 确认端口通不通
• FATAL: no pg_hba.conf entry for replication connection → 不是权限不够，而是 pg_hba.conf 缺少 replication 类型的规则，重启服务后 reload 不生效，必须 pg_ctl reload 或重启
• ERROR: requested starting point is ahead of the WAL flush position → 备份时主库 WAL 写得太快，加 -X stream 参数强制同步流式传输 WAL，避免断点不一致
• WARNING: skipping special file → 正常现象，pg_basebackup 会跳过 pg_stat_tmp、pg_dynshmem 这类运行时临时目录，不用干预

一次稳妥的 pg_basebackup 命令怎么写

不要直接抄文档默认命令，生产环境至少加这四个参数：

• -D /backup/pg_20240520：指定绝对路径目标目录，必须为空或不存在，不能是已有数据目录
• -Ft -z -Z9：用 tar 格式打包 + gzip 压缩（-Z9 最高压缩比，适合网络慢但磁盘足的场景）
• -X stream：关键！确保备份过程中产生的 WAL 被实时接收并写入备份目录的 pg_wal/ 子目录
• --checkpoint=fast：减少 checkpoint 对主库 I/O 的冲击（默认是 spread，会拉长备份窗口）

示例命令：

pg_basebackup -h 192.168.1.5 -U repuser -D /backup/pg_20240520 -Ft -z -Z9 -X stream --checkpoint=fast -P

注意：repuser 必须在 pg_hba.conf 中被授予 replication 权限，且密码正确；-P 显示进度，别省略，否则不知道卡在哪。

物理备份真正麻烦的从来不是命令本身，而是归档路径是否持续可写、WAL 是否完整保留、以及恢复时 recovery.signal 文件有没有放对位置——这些细节不检查，备份等于白做。