pgBackRest 2.60.0 配置参数详解

目标：把 pgBackRest 2.60.0 的 pgbackrest.conf 配置体系讲透——配置文件放哪、段怎么组织、核心参数默认值是什么、每个关键参数改了之后行为如何变化，并给出可直接套用的生产配置模板。本文所有默认值取自 2.60.0 二进制 pgbackrest help 回显，所有行为结论均在 Ubuntu 22.04 + PostgreSQL 16.15 环境实测（实测日期 2026-10-19~20）；安装见 《Ubuntu 22.04 安装 pgBackRest 2.60.0 指南》，stanza 创建、备份/恢复命令的完整实战见 《pgBackRest 2.60.0 常用 CLI 命令与工具详解》。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）。
• 数据库：PostgreSQL 16.15（PGDG 源），数据目录 /var/lib/postgresql/16/main，端口 5432，服务单元 postgresql@16-main。
• pgBackRest：2.60.0（官方发行包 meson 编译，安装于 /usr/local/bin/pgbackrest）。
• 主配置：/etc/pgbackrest/pgbackrest.conf；仓库：/var/lib/pgbackrest（repo1，明文 zst 压缩）与 /var/lib/pgbackrest2（repo2，AES-256-CBC 加密 + bundle/block）；日志：/var/log/pgbackrest。
• 实验载荷：demo 表 10 万行（约 30MB 数据目录），用于压缩率与备份/恢复实测。

二、前置条件

• 已按《Ubuntu 22.04 安装 pgBackRest 2.60.0 指南》完成 pgBackRest 与 PostgreSQL 16 安装。
• PostgreSQL 实例可重启（本文多处需要 systemctl restart postgresql@16-main 使归档配置生效）。
• 具备 root/sudo 与 postgres 用户操作权限。

三、配置体系：文件位置、优先级与生效方式

3.1 配置文件搜索顺序与优先级

pgBackRest 启动时按固定顺序搜索主配置文件：--config 显式指定的文件 → /etc/pgbackrest/pgbackrest.conf → /etc/pgbackrest.conf（来源：官方配置参考 Configuration File Location 一节；与 pgbackrest help 回显的 --config [default=/etc/pgbackrest/pgbackrest.conf] 一致）。Debian/Ubuntu 的 apt 包自带的是后者骨架文件，因此同一台机器上两处可能同时存在。实测做法（避免"改了没生效"）：统一使用 /etc/pgbackrest/pgbackrest.conf，把包骨架改成注释占位：

sudo mkdir -p /etc/pgbackrest
echo '# 主配置迁移至 /etc/pgbackrest/pgbackrest.conf' | sudo tee /etc/pgbackrest.conf

3.2 [global] 与 [stanza] 段结构

配置分两类 section：[global] 放仓库级与全局参数；[db]（段名即 stanza 名，可自定义）放该 PG 集群的连接参数。本文实测配置全文（repo1 基础版）：

[global]
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
repo1-retention-diff=2
process-max=4
compress-type=zst
compress-level=3
log-level-console=info
log-level-file=detail
log-path=/var/log/pgbackrest
start-fast=y
archive-timeout=60

[db]
pg1-path=/var/lib/postgresql/16/main
pg1-port=5432
pg1-user=postgres

规则要点：参数名大小写不敏感、布尔值用 y/n；时间值可带单位（60 默认按秒，1m 按分）；同名参数在 [global] 是全局默认，放到 [db] 段则只对该 stanza 生效。

3.3 优先级与 include 目录

同一参数的取值优先级为：命令行选项 > stanza 段 > global 段 > 默认值。此外还有目录级 include：--config-include-path [default=/etc/pgbackrest/conf.d]，该目录下的 .conf 文件会并入主配置，适合放机密参数（如 cipher-pass）做权限隔离。所有参数也都可以在命令行临时覆盖，例如本文实测的异步归档：

pgbackrest --stanza=db --archive-async --spool-path=/var/spool/pgbackrest archive-push %p

3.4 查看实际生效值：help 回显里的 [current=] 与 [default=]

pgbackrest help <命令> 会把"实际生效值"与"默认值"一起打印，是排查配置问题最快的工具。实测（restore 命令，节选——可看到本文配置中的 process-max=4、log-level-*=、log-path 均已生效）：

  --process-max                       max processes to use for
                                      compress/transfer [current=4, default=1]
  --log-level-console                 level for console logging [current=info,
                                      default=warn]
  --log-level-file                    level for file logging [current=detail,
                                      default=info]
  --log-path                          path where log files are stored
                                      [current=/var/log/pgbackrest, default=/var/log/pgbackrest]

任何 pgBackRest 命令启动日志的首行也会回显解析后的参数串，实测：

2026-10-19 16:55:38.846 P00   INFO: restore command begin 2.60.0: --exec-id=9268-e4e3487a --log-level-console=info --log-level-file=detail --log-path=/var/log/pgbackrest --process-max=4 --repo1-path=/var/lib/pgbackrest

💡 技术拓展：pgBackRest 的参数是按命令作用域校验的——不是所有参数都能配在所有命令上。实测反例：check 命令不认识 --archive-async，直接报 ERROR: [031]: option 'archive-async' not valid for command 'check'。写配置文件时若把某命令不支持的全局参数放进 [global]，一样会触发 [031] 报错，报错信息会明确指出命令名，据此排查即可。

四、参数总览（默认值速查表）

以下默认值全部实测自 2.60.0 pgbackrest help 回显，挑生产最常用的 16 项：

五、核心参数分类详解

5.1 仓库与保留策略：repo1-path、repo-retention-*

• repo1-path：仓库根目录，备份与 WAL 归档都在其下（backup/ 与 archive/ 子目录）。多仓库时编号递增（repo2-path、repo3-path…），编号即 --repo 取值与处理顺序（restore 按 repo1→repo2 顺序找备份，来源：restore 命令帮助）。实测目录布局：/var/lib/pgbackrest/{backup,archive}/db/…。
• repo-retention-full [default=1 / 实测=2]：全量保留个数。超出后由 expire 在备份后自动清理最老全量及其依赖链。实测证据：设 repo1-retention-full=2 连做 3 个全量后，日志出现 expire full backup set: 20261019-164520F, 20261019-164520F_20261019-164613D，info 中旧全量消失。
• repo-retention-diff [实测=2]：差异保留个数。注意"保留 2 个差异"是相对每个全量而言，受全量保留约束（全量被清，其差异链随之清理，实测已验证）。
• repo-retention-archive [default=2] / repo-retention-archive-type [default=full]：为多少个（何种类型的）备份保留连续 WAL，保证 PITR 可用窗口。这条必须在保留策略里一起规划：PITR 能回到的最早时间点由"最老保留备份 + 其 WAL"决定。
• expire-auto [default=y]：备份后自动执行 expire；关掉则需手动跑 pgbackrest expire（可用 cron 单独调度）。

5.2 备份行为：start-fast、compress-*、archive-check/copy、checksum-page

• start-fast [实测=y]：备份开始立即发 checkpoint，避免等下次自动 checkpoint（默认要等 checkpoint_timeout，大库可达数分钟——10 万行小库差异不明显，生产建议开启）。
• compress-type [default=gz / 实测=zst] + compress-level [default=3 / 实测=3]：压缩算法与级别。实测压缩率：10 万行 demo 库全量备份 full backup size = 30.8MB → 仓库侧 backup set size = 5.5MB or 17.8%（zst level 3）。算法选择建议：追求速度 lz4、均衡 zst、极限压缩 gz（来源：官方特性说明，实测数据见上）。
• archive-check [default=y]：备份完成前校验"使备份一致所需的 WAL 是否都已入仓"，这是 pgBackRest 完整性模型的关键一环（官网 Features："a backup is not complete until the WAL required to make it consistent is in the repository"）。除非离线备份，不要关。
• archive-copy [default=n]：把所需 WAL 再额外拷进备份集本身，牺牲空间换取"该备份集自包含"。生产可对全量开启、增量关闭。
• checksum-page [default=y]：利用 PG 页校验和逐页校验；2.60.0 配套新行为：restore 时遇到无效页校验和默认直接报错停止（checksum-page-error [default=y]，release notes IMPORTANT NOTE），可用 checksum-page-error=n 降级为告警——这是 2.60.0 相对旧版的显著行为变化。前置条件：PG 实例开启 data_checksums（initdb 时 --data-checksums）。
• online [default=y] / resume [default=y]：在线备份与断点续传，一般保持默认。

5.3 仓库加密：repo-cipher-type 与 repo-cipher-pass

实测配置（repo2，AES-256-CBC）：

repo2-path=/var/lib/pgbackrest2
repo2-cipher-type=aes-256-cbc
repo2-cipher-pass=h3F8xOc9fbrQO/nAWxWf3wJSJoOFGp1D
repo2-bundle=y
repo2-block=y

实测验证：pgbackrest info 显示 stanza 状态 cipher: mixed / repo1: none / repo2: aes-256-cbc；加密仓库首备份时 pgBackRest 会生成加密校验指纹存入备份清单。敏感值保护实测：命令回显中 cipher-pass 自动脱敏为 --repo2-cipher-pass=<redacted>；文件层面建议把 repo*-cipher-pass 放进 /etc/pgbackrest/conf.d/ 并 chmod 600。注意：密码丢失即数据不可解密，务必离线保存。

5.4 bundle 与 block：打包存储与块级增量

• repo-bundle [default=n / 实测 repo2=y]：把小文件打包成 bundle 文件存储，减少小文件数量（对 TB 级库、对象存储后端尤其友好）。实测 repo2 备份目录布局：backup/db/<label>/bundle/ 下是编号 bundle 文件 + backup.manifest，与 repo1 的逐文件布局明显不同。
• repo-block [default=n / 实测 repo2=y]：块级增量，增量备份只记录"文件内变化的块"，需与 bundle 同开。实测：repo2 上对 2000 行数据做增量后，仓库侧按块追加而非整文件重拷（bundle 内以 .b2 块索引呈现）。大库频繁小变更场景收益最大。
• repo-hardlink [default=n]：硬链接共享相同文件（压缩关闭时配合快照直接拉起）。默认关闭。
• bundle/block 一经启用，仅影响其后的备份；旧备份仍按旧布局读取，混用安全（实测 repo1 保持逐文件、repo2 全程 bundle，两仓库并行备份互不影响）。

5.5 日志：log-level-*、log-path、log-timestamp

• log-level-console [default=warn / 实测=info]：人看终端时用 info（能看到每个阶段与耗时）。
• log-level-file [default=info / 实测=detail]：写文件的日志更细，排障用；配合 log-path（实测 /var/log/pgbackrest，apt 包自带 logrotate 规则 /etc/logrotate.d/pgbackrest 按 weekly/rotate 10 轮转）。
• log-level-stderr [default=off]：stderr 输出级别；被 systemd/cron 捕获时按需调低避免重复。
• log-timestamp [default=y]：日志带时间戳，默认保持。
• 日志首行格式实测：2026-10-19 16:55:38.846 P00 INFO: …——P00 是主进程编号，P01-Pnn 为并行子进程（与 process-max 对应），exec-id=9268-e4e3487a 可用于跨日志关联同一次执行。

5.6 并行与超时：process-max、*timeout、lock-path

• process-max [default=1 / 实测=4]：压缩/传输并行进程数。备份与恢复共用该并行度；经验值 4~8 或接近 CPU 核数，配合 NVMe 与 zst/lz4 提速明显（官方定位：并行处理正是 pgBackRest 解决压缩瓶颈的核心手段）。
• archive-timeout [default=1m / 实测=60（秒，等价）]：备份/检查等待 WAL 归档完成的超时。慢盘/高写入量库可调大；本文实测 60 秒内小库绰绰有余。
• db-timeout [default=30m] / protocol-timeout [default=31m]：数据库操作与进程协议超时，protocol 必须大于 db-timeout（帮助文档明确要求），不要单独调乱。
• io-timeout [default=1m]：单次 I/O 超时；对象存储偶发抖动场景可适当放大。
• lock-path [default=/tmp/pgbackrest]：锁文件目录，防止并发备份/恢复。生产建议移到持久目录如 /var/spool/pgbackrest/lock 并纳入备份计划文档。

5.7 PostgreSQL 连接与 [db] 段：pg1-*

• pg1-path：PG 数据目录（必填，pgBackRest 直接读写它做备份/恢复）。
• pg1-port [default=5432]、pg1-user [default=postgres]、pg1-socket-path [default=/var/run/postgresql]、pg1-database [default=postgres]：连接参数；本机场景只需 path/port。
• pg1-host / pg1-host-user：远程 PG 主机参数（pgBackRest 从仓库机反向连数据库主机），本文单机场景未启用，配置语义见官方 Configuration 参考的 "Stanza Section - Host Options"。
• stanza 段名：[db] 中的 db 就是 stanza 名，任意合法字符串；一个配置文件可放多个 stanza 段管理多个实例。

5.8 异步归档：archive-async 与 spool-path（实测）

PG 的 archive_command 每次归档一段 WAL 都会同步等 pgBackRest 完成；archive-async=y 让 pgBackRest 把 WAL 放入 spool 队列后立即返回，由后台进程异步入仓，避免归档拖慢主库提交。实测验证链：

1. 归档命令切到异步模式：archive_command = 'pgbackrest --stanza=db --archive-async --spool-path=/var/spool/pgbackrest archive-push %p'，select pg_reload_conf(); 立即生效（无需重启）。
2. select pg_switch_wal(); 触发归档后，spool 出现应答文件（实测）：

/var/spool/pgbackrest/archive/db/out/00000003000000000000001C.ok

.ok 文件表示该段已成功入仓——异步模式下"队列目录 + .ok 确认"即状态机，排障时看 archive/db/in（待处理）与 out（已完成）即可。

3. 作用域实测：--archive-async 只对 archive-push/archive-get 有效，配到 check 命令报 [031] not valid for command 'check'（见 3.4 拓展块）。
4. 相关参数：archive-push-queue-max [default=128MiB]——spool 队列上限，超出后 archive-push 开始丢弃并报错（保护 spool 磁盘），高写入量库要按 WAL 生成速率设置；官方文档注明异步归档对 S3 等高延迟存储收益最大。
5. 实测后已还原同步归档：archive_command = 'pgbackrest --stanza=db archive-push %p'。

5.9 对象存储参数组：repo-type 与 s3/azure/gcs（官方引述，未实测展开）

仓库后端可切对象存储：repo1-type [default=posix，可选 s3/azure/gcs/sftp/cifs]，S3 组参数实测自 pgbackrest help 回显包括 repo-s3-bucket / repo-s3-endpoint / repo-s3-region / repo-s3-key / repo-s3-key-secret / repo-s3-key-type [default=shared] / repo-s3-uri-style [default=host]（2.59.0 起另支持 S3 Outposts 与 repo-s3-process-cmd 进程式认证，2.60.0 增加 GCS Workload Identity Federation），Azure 组 repo-azure-*，GCS 组 repo-gcs-*，SFTP 组 repo-sftp-*；自签证书场景用 repo-storage-ca-file/ca-path。指向 MinIO 类 S3 兼容端点时典型组合是 repo1-type=s3 + repo1-s3-endpoint=<minio>:9000 + repo1-s3-uri-style=path（参数名与语义来源：官方 Configuration 参考，2026-10-20 查阅；本文实测环境未搭建对象存储，此组参数未逐项验证，上生产前请以官方配置参考核对）。

5.10 恢复（PITR）参数组：type/target/target-action/…

恢复参数多在命令行传入，但同样可写进配置。实测 PITR 完整命令（目标时间点恢复并提升）：

sudo -u postgres pgbackrest --stanza=db restore \
  --type=time --target="2026-10-19 16:47:25+00" --target-action=promote

实测回显（节选）：

2026-10-19 16:47:39.128 P00   INFO: selected backup 20261019-164626F
  ... P01   INFO: selected backup ...
2026-10-19 16:47:39.908 P00   INFO: wrote /var/lib/postgresql/16/main/recovery.signal
2026-10-19 16:47:39.908 P00   INFO: wrote updated postgresql.auto.conf
  restore size = 32.5MB, file total = 969
2026-10-19 16:47:39.914 P00   INFO: restore command end: completed successfully (786ms)

恢复后实测 /var/lib/postgresql/16/main/postgresql.auto.conf 内容（pgBackRest 生成的恢复参数）：

# Recovery settings added by pgBackRest
restore_command = 'pgbackrest --stanza=db archive-get %f "%p"'
recovery_target_time = '2026-10-19 16:47:25+00'
recovery_target_action = 'promote'

参数逐项：

• --type [default=default]：default 重放全部可用归档 WAL；time 按时间戳、xid 按事务号、lsn 按 LSN、name 按恢复点命名、immediate 到一致点即停、standby 进入只读热备模式。time/lsn 必须配 --target（来源：restore 帮助）。
• --target-action：到达目标后的动作（pause/promote/shutdown），PITR 场景最常用 promote。
• --target-exclusive [default=n]：是否停在目标之前。
• --target-timeline：沿哪条时间线恢复；配合历史分叉场景使用。
• --set [default=latest]：指定恢复哪个备份集（restore 默认取第一个有备份的仓库的最新集；来源：restore 帮助原文）。
• --delta [default=n]：增量恢复——按 manifest 校验和比对，跳过未变化文件、删除无效文件。实测对 PITR 后的数据目录再恢复，回显含 remove invalid files/links/paths (1), backup ... exists and matches size 等行，耗时远低于全量重拷。
• --db-include / --db-exclude：部分数据库恢复（选择性还原），多库大实例可显著省时。
• --archive-mode [default=preserve]：恢复出的集群是否保留归档配置；重建恢复测试环境时常用 --archive-mode=off 避免恢复实例把测试 WAL 推进生产仓库。
• --recovery-option：直接向 postgresql.auto.conf 注入额外恢复参数。

六、生产配置模板（逐项注释，可直接改值使用）

以下模板整合本文实测参数与生产常规项（8GB 内存 / NVMe / 单机本地仓库 + S3 异地仓库的场景假设）：

[global]
# —— 仓库 1：本地 NVMe，快速恢复 ——
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2                # 全量保留 2 个（配合每周全量 ≈ PITR 窗口 2 周）
repo1-retention-diff=2                # 每个全量下保留 2 个差异
repo1-retention-archive-type=full     # WAL 保留锚点：全量
repo1-retention-archive=2             # 为 2 个全量保留连续 WAL（PITR 窗口与上面对齐）
repo1-cipher-type=aes-256-cbc         # 仓库加密（cipher-pass 建议 conf.d + chmod 600）
repo1-bundle=y                        # 打包存储：省 inode、对象存储友好
repo1-block=y                         # 块级增量：小改动增量收益大
# —— 仓库 2：对象存储异地（以 MinIO/S3 为例，官方 Configuration 参考）——
#repo2-type=s3
#repo2-path=/pgbackrest
#repo2-s3-endpoint=minio.internal:9000
#repo2-s3-bucket=pgbackrest
#repo2-s3-region=us-east-1
#repo2-s3-key-type=shared
#repo2-s3-uri-style=path
# —— 行为 ——
process-max=4                         # 并行进程数 ≈ CPU 核数
compress-type=zst                     # zstd：速度/压缩率均衡
compress-level=3
start-fast=y                          # 立即 checkpoint
archive-check=y                       # 校验 WAL 一致性（默认开）
archive-copy=n                        # WAL 不重复入备份集（省空间）
# —— 异步归档 ——
archive-async=y                       # spool 队列异步入仓（archive_command 需同步修改）
spool-path=/var/spool/pgbackrest
archive-push-queue-max=1GiB           # 队列上限按 WAL 速率调
# —— 日志与锁 ——
log-level-console=info
log-level-file=detail
log-path=/var/log/pgbackrest
log-level-stderr=off
lock-path=/var/spool/pgbackrest/lock
# —— 超时 ——
archive-timeout=60
db-timeout=30m
protocol-timeout=31m

[db]
pg1-path=/var/lib/postgresql/16/main
pg1-port=5432
pg1-user=postgres

配套的 PostgreSQL 侧配置（postgresql.conf）：

archive_mode = on
archive_command = 'pgbackrest --stanza=db --archive-async --spool-path=/var/spool/pgbackrest archive-push %p'
archive_timeout = 600        # 低写入量库强制切 WAL，保证 PITR 粒度
wal_level = replica

模板未展开项：repo-host-*（远端仓库机）、pg1-host-*（远端数据库机）、*-tls-*（TLS 证书路径）——需要主机间部署时按官方 Configuration 参考 "Repository Host / Host Options" 补齐。

七、常见问题（FAQ，含排障实录）

Q1：改了配置怎么确认生效？ 最快办法：pgbackrest help <命令> 看 [current=] 值（3.4 实测样式），或看命令日志首行的参数解析串。

Q2：报 [031]: option 'xxx' not valid for command 'yyy'？ 参数与命令作用域不匹配（实测：archive-async 配到 check 即触发）。把该参数移到正确的命令行参数或从 [global] 移除；官方 Command 参考可查每个命令支持的参数集。

Q3：多仓库时 info 显示 status: mixed？ 正常的多仓库状态语义：repo1 ok、repo2 尚未建 stanza 时实测显示 status: mixed / repo1: ok / repo2: error (missing stanza path)，cipher 也会逐仓显示（mixed / none / aes-256-cbc）。对每个仓库完成 stanza-create 后即恢复 ok。注意：stanza-create 不支持 --repo 参数（实测报 [031] option 'repo' not valid for command 'stanza-create'），直接不带 --repo 执行一次即可对全部仓库生效（对已有仓库幂等）。

Q4：cipher-pass 写在配置里安全吗？ 命令日志与回显自动脱敏（实测 --repo2-cipher-pass=<redacted>）；建议将敏感参数挪到 /etc/pgbackrest/conf.d/（config-include-path 默认包含）并 chmod 600，主配置只留非敏感项。密码丢失则仓库不可解密，请离线双份保存。

Q5：expire 没有清理旧备份？ 先确认 repo-retention-full 的口径：它按"全量个数"计数（repo-retention-full-type [default=count]），只有当新全量完成后 expire-auto 才触发清理（实测第 3 个全量完成后立即清理最老全量及其差异链）。也可手动 pgbackrest --stanza=db expire 立即执行并观察回显。

Q6：异步归档后 spool 里的 .ok/.partial 文件是什么？ 异步模式的状态机文件：archive/db/in 是待处理队列、archive/db/out/*.ok 是已完成确认（实测见 5.8）。排障时 in 长期堆积说明后台入仓跟不上（看 archive-push-queue-max 与网络/对象存储延迟）。

Q7：restore 后启动报 WAL 相关错误？ 确认三点：restore 写入的 postgresql.auto.conf 中 restore_command 的 stanza 名与当前配置一致；归档在仓库中确实存在（pgbackrest info 看 wal archive min/max）；--archive-mode=preserve 时原 archive_command 仍指向同一仓库。

八、参考链接

• 官方配置参考（本篇参数语义的权威出处）：https://pgbackrest.org/configuration.html
• 官方命令参考（各命令参数作用域）：https://pgbackrest.org/command.html
• 官方用户指南：https://pgbackrest.org/user-guide.html
• 2.60.0 发行说明（checksum-page-error 等行为变更）：https://github.com/pgbackrest/pgbackrest/releases/tag/release/2.60.0
• 站内相关：《pgBackRest 2.60.0 介绍与选型指南》、《Ubuntu 22.04 安装 pgBackRest 2.60.0 指南》、《PostgreSQL 18 常用 CLI 命令与工具详解》