pgBackRest 配置文件详解

下面是一份最完整、最清晰、最可直接用于生产的 pgbackrest.conf 配置文件详解。

涵盖：全局参数、Stanza 参数、S3/远程 repo、高级参数、性能参数、保留策略、防踩坑说明。

pgbackrest.conf 总体结构

pgBackRest 的配置文件采用 INI 格式：

[global]         # 全局设置（所有 stanza 共享）
[stanza-name]    # 针对某个 PostgreSQL 实例的配置

示例：

[global]
repo1-path=/data/pgbackrest/repo1

[main]
pg1-path=/var/lib/pgsql/16/data

一、[global] 全局段（最常用参数）

1. repo 相关（最关键）

repo1-path

备份仓库路径：

repo1-path=/data/pgbackrest/repo1

repo1-host（远程备份主机）

repo1-host=backup-server
repo1-host-user=postgres

📌 用于 DB -> repo 远程存储。

repo 多仓库支持

repo2-path=/data/repo2
repo3-type=s3

2. 压缩（节省空间）

compress-type=zstd
compress-level=3

推荐使用 zstd，速度快、压缩比高。

3. 日志

log-level-console=info
log-level-file=detail
log-path=/var/log/pgbackrest

可选级别：error, warn, info, detail, debug

4. 性能参数（强烈推荐）

多线程

process-max=8

可以按 CPU 核心数调整，提升备份、恢复速度。

5. 保留策略（非常重要）

保留 full 备份数量

repo1-retention-full=7

仅保留最新 7 个全量备份（差量和增量自动以 full 为基准删除）。

保留时间模式（按天）

repo1-retention-full-type=time
repo1-retention-full=30    # 保留 30 天

WAL 保留策略

通常不单独指定，pgBackRest 自动管理。

6. 安全参数

repo1-cipher-type=aes-256-cbc
repo1-cipher-pass="StrongPassword123!"

用于备份加密（可选）。

7. S3 / MinIO 参数（如果使用 S3 repo）

repo1-type=s3
repo1-s3-endpoint=s3.amazonaws.com
repo1-s3-bucket=pg-backup
repo1-s3-region=us-east-1
repo1-s3-key=<your-key>
repo1-s3-key-secret=<your-secret>
repo1-s3-verify-tls=n

MinIO 示例：

repo1-type=s3
repo1-s3-endpoint=minio.local:9000
repo1-s3-region=us-east-1
repo1-s3-bucket=pg
repo1-s3-key=minio
repo1-s3-key-secret=minio123
repo1-s3-uri-style=path
repo1-s3-verify-tls=n

二、[stanza] 段（每个 PostgreSQL 集群一份）

1. PG 数据目录

pg1-path=/var/lib/pgsql/16/data

如果是远程备份（DB host != repo host），使用：

pg1-host=db-server
pg1-host-user=postgres
pg1-path=/var/lib/pgsql/16/data

2. WAL 归档（天空级重要）

WAL archive_command 会调用 archive-push：

postgresql.conf 需配置：

archive_mode=on
archive_command='pgbackrest --stanza=main archive-push %p'

pgbackrest.conf 不需要额外配置归档参数，除非：

限制 WAL 归档并发

archive-async=y
archive-push-queue-max=8

3. 恢复相关参数

指定恢复目标

recovery-option=target-action=promote
recovery-option=target-time=2025-01-18 10:12:00

但通常不会写在配置文件中，而是恢复时运行命令：

pgbackrest --stanza=main --type=time --target='2025-01-18 10:12:00' restore

三、完整本地备份配置示例（生产可用）

[global]
repo1-path=/data/pgbackrest/repo1
repo1-retention-full=7

compress-type=zstd
compress-level=3

log-level-console=info
log-level-file=detail
log-path=/var/log/pgbackrest

process-max=8
start-fast=y

[main]
pg1-path=/var/lib/pgsql/16/data

四、完整远程备份（DB->备份服务器）配置示例

⭐ repo 服务器 /etc/pgbackrest/pgbackrest.conf

[global]
repo1-path=/data/pgbackrest/repo1

[main]
pg1-host=db01
pg1-host-user=postgres
pg1-path=/var/lib/pgsql/16/data

⭐ 数据库服务器 /etc/pgbackrest/pgbackrest.conf

[global]
repo1-host=backup01
repo1-host-user=postgres

五、完整 S3/MinIO 配置示例（企业常用）

[global]
repo1-type=s3
repo1-s3-endpoint=minio.local:9000
repo1-s3-bucket=pg
repo1-s3-region=us-east-1
repo1-s3-uri-style=path
repo1-s3-key=minio
repo1-s3-key-secret=minio123
repo1-s3-verify-tls=n
repo1-path=/pgbackrest
repo1-retention-full=14

compress-type=zstd
compress-level=3

process-max=4
log-level-console=info

[main]
pg1-path=/var/lib/pgsql/16/data

六、常见高级参数

📌 禁用 fsync（不安全，但用于测试）

repo1-fsync=n

📌 禁用备份文件校验（不建议）

checksum-page=n

📌 并行校验

repo1-checksum=y

📌 限制流量

用于带宽敏感环境：

bandwidth-limit=50MB/s

七、配置文件常见踩坑

❌ 1. repo1-path 目录权限不对（最常见）

必须是 postgres 用户读写：

chown -R postgres:postgres /data/pgbackrest
chmod 750 /data/pgbackrest

❌ 2. 两台机之间 SSH 未免密

需要：

ssh-copy-id postgres@repo-server

❌ 3. archive_command 写错或没执行

应为：

pgbackrest --stanza=main archive-push %p

不能加引号、不能缺参数。

❌ 4. 使用 S3 忘记关闭 TLS

MinIO 的自签名证书会报错：

repo1-s3-verify-tls=n