pgBackRest 基础教程

官方文档：

pgBackRest: https://pgbackrest.org/
GitHub: https://github.com/pgbackrest/pgbackrest.git

下面是一份最完整、最清晰、最实战化的 pgBackRest 知识体系，一次性把核心概念、架构、配置、备份策略、恢复流程、最佳实践全部讲清楚，适合生产环境直接使用。

pgBackRest — PostgreSQL 企业级备份恢复工具

pgBackRest 是 PostgreSQL 最强的备份与恢复工具之一，替代 pg_basebackup、技术成熟、企业大量使用，支持全量/差量/增量备份、高效压缩、WAL 归档、PITR 恢复、对象存储等功能。

其核心目标：

可靠（Reliable）
高性能（Performance）
易管理（Manageable）

一、pgBackRest 核心特性

1. 全量 / 差量 / 增量备份

full：全量备份，完整数据目录
diff：差量备份，基于上次 full 备份后的所有变化
incr：增量备份，基于最近一次 full 或 diff 备份后的变化

2. 支持本地、远程、对象存储

Local FS
Remote Host（ssh）
S3 / MinIO / aliyun OSS / Google / Azure

3. WAL 存档与完整性检查

自动 push/pull WAL（替代 archive_command）
保障可恢复性（WAL 完整性检查）

4. 支持压缩、多线程、并行传输

节省存储
高速备份还原

5. 支持 PITR（Point In Time Recovery）

精确恢复到任意时刻

6. 强大的配置体系

支持多个 stanza
同时管理多个 PostgreSQL 实例

二、pgBackRest 架构与术语

stanza

pgBackRest 的“备份集”、逻辑单位，类似：

一组 PostgreSQL 集群（一个 PGDATA）
一个备份目录（repo）

通常一个 PostgreSQL 集群创建一个 stanza。

repo（仓库）

备份数据存放位置，例如：

/data/pgbackrest/repo1

主机角色

Database Host (DB Host)：运行 PostgreSQL 的主机
Repository Host：存储备份数据的主机（可以与 DB 共存）

二者可分离或同机。

三、典型部署方式

1) 单机本地备份（最简单、常用）

PostgreSQL + pgBackRest

备份 -> 本地 /data/pgbackrest/

2) 远程 repo + SSH

PostgreSQL —ssh—> Backup Server

3) S3 / MinIO 远程备份

PostgreSQL —https—> S3

非常适合云环境。

四、配置示例（最常用版）

以本地备份为例。

1. 安装

# RHEL/CentOS/AlmaLinux
yum install -y pgbackrest

# Debian/Ubuntu
sudo apt install -y pgbackrest

2. 创建 repo 目录

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

3. 配置文件

/etc/pgbackrest.conf
/etc/pgbackrest/pgbackrest.conf

[global]
repo1-path=/data/pgbackrest/repo1
repo1-retention-full=7
start-fast=y
log-level-console=info

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

4. 初始化 stanza

pgbackrest --stanza=main stanza-create
pgbackrest --stanza=main check

五、备份命令大全（最常用）

全量备份

pgbackrest --stanza=main --type=full backup

差量备份

pgbackrest --stanza=main --type=diff backup

增量备份

pgbackrest --stanza=main --type=incr backup

查看备份信息

pgbackrest info

删除旧备份（自动根据 retention）

无需手动删除，pgBackRest 会自动清理。

六、WAL 归档配置（最关键）

编辑 postgresql.conf：

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

验证 WAL 推送

pgbackrest --stanza=main check

七、恢复（最关键的部分）

1. 选择最新 backup 的恢复

pgbackrest --stanza=main restore

恢复目录会被自动覆盖为 PGDATA。

2. 指定恢复时间点（PITR）

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

3. 恢复到特定备份

pgbackrest --stanza=main --set=20250118-100000F restore

4. 恢复到最近一致点（无 PITR）

pgbackrest restore --stanza=mydb --type=default

恢复后启动 PostgreSQL：

pg_ctl -D /var/lib/pgsql/16/data start

八、生产最佳实践（重点）

1. 一定要有 WAL 归档

否则无法进行 PITR，也无法保证数据安全。

2. 建议备份策略（最佳实践）

每天一份 full + 每小时 diff/incr：

每天 02:00   full
每小时       incr

PGBackRest 自带 retention，自动清理旧备份。

3. 多线程加速

process-max=8

4. 开启压缩

compress-type=zstd
compress-level=3

5. 备份专用服务器（推荐）

减少 DB 服务器 IO 压力。

6. S3 存储（企业必备）

MinIO / 阿里云 OSS / AWS S3

7. 定期验证备份可恢复性

pgbackrest --stanza=main check

或定期做一次恢复演练。

九、pgBackRest vs pg_basebackup

特性	pgBackRest	pg_basebackup
差量备份	✅	❌
增量备份	✅	❌
自动 WAL 归档	✅	❌
并行备份	✅	✅
多 repo	✅	❌
S3 / 远程	✅	❌
主从模式	✅	✅

pgBackRest 是 pg_basebackup 的超集，强太多。

下面是一份 pgBackRest 超清晰、全面、实战向的教程，适合 PostgreSQL 生产环境备份、恢复、增量备份、WAL 管理、高可用架构。

📘 什么是 pgBackRest？

pgBackRest 是 PostgreSQL 目前最强、最可靠的企业级备份与恢复工具之一。

它的目标是：

高性能（多线程、压缩、并行传输）
高可靠性（严格校验、自动恢复 WAL）
极简恢复（基于时间点 PITR）
支持非常大的数据库（TB~PB）

相比传统 pg_basebackup：

功能	pg_basebackup	pgBackRest
全量备份	✅	✅
增量备份	❌	✅
差异备份	❌	✅
并行备份	❌	✅
验证校验和	❌	✅
自动管理 WAL	❌	✅
加密备份	❌	✅
S3 / MinIO 备份	❌	✅
自动清理旧备份	❌	✅

pgBackRest = PostgreSQL 备份界的天花板

🪄 pgBackRest 核心功能总结

全量、增量、差异备份
支持本地、远程、S3、MinIO、多存储
自动归档 WAL
自动合并旧备份
PITR（按时间点恢复）
多线程备份/恢复
校验数据完整性
加密、压缩
适用于单机 & 集群（Patroni/PGPool/HA）

🔧 pgBackRest 安装（Debian 12 + PostgreSQL 17 示例）

sudo apt install -y pgbackrest

安装后目录：

配置文件：/etc/pgbackrest.conf
日志：/var/log/pgbackrest/
命令：pgbackrest

📁 最小可运行配置（本地备份版本）

/etc/pgbackrest.conf：

默认配置：

[global]
repo1-path=/var/lib/pgbackrest
#repo1-retention-full=2
#repo1-cipher-pass=...
#repo1-cipher-type=aes-256-cbc

#[main]
#pg1-path=/var/lib/postgresql/13/main

修改配置：

sudo tee /etc/pgbackrest.conf <<'EOF'
[global]
repo1-path=/var/lib/pgbackrest
repo1-retention-full=5
start-fast=y

[main]
pg1-path=/var/lib/postgresql/data
EOF

创建备份目录：

sudo mkdir -p /var/lib/pgbackrest
sudo chown -R postgres:postgres /var/lib/pgbackrest

🟦 立即进行第一次全量备份

# 本地运行
sudo -u postgres pgbackrest --stanza=main --type=full backup

# 容器运行
sudo podman exec -it postgres bash
su - postgres -c 'pgbackrest --stanza=main --type=full backup'

检查状态：

# 本地运行
sudo -u postgres pgbackrest --stanza=main info

# 容器运行
sudo podman exec -it postgres bash
su - postgres -c 'pgbackrest --stanza=main info'

<<COMMENT
stanza: main
    status: ok
    cipher: none

    db (current)
        wal archive min/max (17): 000000010000000D0000001E/000000010000000D00000023

        full backup: 20251210-190712F
            timestamp start/stop: 2025-12-10 11:07:12+00 / 2025-12-10 11:11:18+00
            wal start/stop: 000000010000000D00000023 / 000000010000000D00000023
            database size: 2.9GB, database backup size: 2.9GB
            repo1: backup set size: 645.5MB, backup size: 645.5MB
COMMENT

输出中你可以看到：

全量备份时间
WAL 信息
存储占用

🟧 增量备份

# 本地运行
sudo -u postgres pgbackrest --stanza=main --type=incr backup

# 容器运行
sudo podman exec -it postgres bash
su - postgres -c 'pgbackrest --stanza=main --type=incr backup'

🟧 差异备份

# 本地运行
sudo -u postgres pgbackrest --stanza=main --type=diff backup

# 容器运行
sudo podman exec -it postgres bash
su - postgres -c 'pgbackrest --stanza=main --type=diff backup'

🟨 启用 WAL 归档（必须）

在 postgresql.conf 中：

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

重启 PostgreSQL。

验证：

sudo -u postgres pgbackrest --stanza=main check

♻ 备份保留策略（Retention Policy）

repo1-retention-full=5
repo1-retention-diff=10
repo1-retention-archive=7

pgBackRest 会自动清理旧备份。

🛠 恢复 PostgreSQL（最关键部分）

停止 PostgreSQL
```
sudo systemctl stop postgresql
```

清空数据库目录

sudo rm -rf /var/lib/postgresql/17/main/*

恢复

sudo -u postgres pgbackrest --stanza=main restore

启动 PostgreSQL
```
sudo systemctl start postgresql
```

🔄 PITR（按时间点恢复）

例如恢复到 2025-01-01 10:20:00：

sudo -u postgres pgbackrest --stanza=main \
    --type=time \
    --target="2025-01-01 10:20:00" \
    --target-action=promote \
    restore

☁ 云对象存储（S3 / MinIO）

配置：

[global]
repo1-type=s3
repo1-path=/pgbackrest
repo1-s3-bucket=pgbackup
repo1-s3-endpoint=minio.example.com
repo1-s3-key=admin
repo1-s3-key-secret=12345678
repo1-s3-verify-ssl=n

🏗 与 Patroni 集群配合（生产常用）

由 Patroni 管理 PostgreSQL
pgBackRest 管理备份与 WAL
使用 S3/MiniO 储存备份
能够在节点损坏时自动从备份恢复并重新加入集群

此架构是目前最推荐的高可用 + 高可靠备份方案。

📊 命令总结（最常用）

操作	命令
创建全量备份	pgbackrest –stanza=main –type=full backup
增量备份	pgbackrest –type=incr backup
差异备份	pgbackrest –type=diff backup
查看备份	pgbackrest info
恢复	pgbackrest restore
WAL 推送	pgbackrest archive-push
WAL 获取	pgbackrest archive-get
校验配置	pgbackrest check

🔥 什么时候你必须使用 pgBackRest？

你的数据库大于 50GB
你需要自动增量备份
你需要 PITR（按时间点恢复）
你需要 S3 远程备份
你需要企业级备份
你想避免 WAL 撑爆磁盘
你有多节点（Patroni, Repmgr）

su - postgres -c 'pgbackrest --stanza=main --type=full backup'
<< COMMENT
2025-12-10 10:54:37.052 P00  ERROR: [055]: unable to load info file '/var/lib/pgbackrest/backup/main/backup.info' or '/var/lib/pgbackrest/backup/main/backup.info.copy':
                                    FileMissingError: unable to open missing file '/var/lib/pgbackrest/backup/main/backup.info' for read
                                    FileMissingError: unable to open missing file '/var/lib/pgbackrest/backup/main/backup.info.copy' for read
                                    HINT: backup.info cannot be opened and is required to perform a backup.
                                    HINT: has a stanza-create been performed?
COMMENT

下面我给你解释这个报错的真正原因、为什么会发生、如何修复、以及如何避免再次出现。内容非常实用，适合生产环境直接用。

✅ pgBackRest 报错解析

ERROR: [055]: unable to load info file '/var/lib/pgbackrest/backup/main/backup.info'
HINT: backup.info cannot be opened and is required to perform a backup.
HINT: has a stanza-create been performed?

🔍 问题本质：backup.info 文件不存在

pgBackRest 必须依赖每个 stanza 的 backup.info 文件，它包含：

PostgreSQL 的版本
系统标识符 (system-id)
备份历史
WAL 归档信息

如果 backup.info 不存在，pgBackRest 无法判断当前集簇是否正确、是否能继续备份。

为什么文件不存在？

可能原因如下：

1）你还没有创建这个 stanza（最常见）

即：

pgbackrest --stanza=main stanza-create

还没执行过。

2）之前创建过，但 /var/lib/pgbackrest 目录被清理或权限不对

例如：

删除了 pgBackRest 的数据目录
使用 Docker/K8s 时没有持久化 volume
更换服务器后忘记迁移该目录
用户权限错误（比如 root 创建，postgres 运行）

3）你改动过 pgBackRest 配置文件，导致目录路径变更

🛠️ 解决方案（按步骤走，必成功）

第一步：确认目录是否存在

ls -l /var/lib/pgbackrest/backup/main/

如果目录为空或不存在 -> 必定缺失 backup.info

第二步：检查权限

pgBackRest 必须以 postgres 用户运行：

chown -R postgres:postgres /var/lib/pgbackrest
chmod -R 750 /var/lib/pgbackrest

第三步：重新创建 stanza

必须在 PostgreSQL 正常运行情况下执行：

pgbackrest --stanza=main stanza-create

如果成功，你会看到：

stanza-create command end: completed successfully

目录中会生成：

backup.info
backup.info.copy

🧪 第四步：测试归档

# 确保 postgresql.conf 文件有以下配置
# archive_mode = on
# archive_command = 'pgbackrest --stanza=main archive-push %p'
pgbackrest --stanza=main check

如果正常，会显示：

check command end: completed successfully

🔐 如果你原来有旧备份想恢复怎么办？

如果你误删了 backup.info，但 /var/lib/pgbackrest/backup/main 下仍有备份内容，可用以下方式恢复：

从旧备份目录重建 backup.info

pgbackrest --stanza=main info

它会自动从备份结构重建 backup.info。

如果还原失败，你可以手动：

pgbackrest --stanza=main --force stanza-create

⚠️ 只有当你确定备份一致性损坏或不需要时才使用 –force

🚫 最危险的行为（请避免）

以下会导致你再也恢复不了原来的备份：

❌ 删除 /var/lib/pgbackrest/backup/main/backup.info
❌ 修改 PostgreSQL 的 system-id（重建集簇）
❌ pgBackRest 服务使用 root 而不是 postgres
❌ Docker/K8s 没有持久化 /var/lib/pgbackrest

🎯 最佳实践（生产环境必做）

1）确保 pgBackRest 数据目录持久化（尤其是容器环境）

/var/lib/pgbackrest
/var/log/pgbackrest

必须使用持久卷，否则容器重启后 backup.info 会消失。

2）定期验证 stanza

pgbackrest --stanza=main check

3）保持 WAL 归档正常

PostgreSQL 配置必须包括：

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