管理命令

备份管理命令应以数据库超级用户（pg_dbsu，默认 postgres）身份在数据库节点上执行。 您可以按习惯选择三种等价的入口：

• pig pb：pig 命令行工具 的封装 —— 自动检测 stanza、自动切换 DBSU 身份、带安全检查，推荐使用
• pb：登录 shell 的别名函数，自动填充 --stanza 后转发给 pgbackrest
• pgbackrest：原生命令，完整选项参阅 pgBackRest 命令参考

命令一览

启用备份

如果集群创建时 pgbackrest_enabled 为 true（默认），备份已自动启用。 若创建时禁用了备份，或修改了仓库配置，可用 pg_backup 子任务补充配置：

./pgsql.yml -t pg_backup -l pg-meta   # 配置 pgbackrest，创建 stanza

集群初始化后 Pigsty 会自动尝试执行一次初始全量备份；只有备份命令成功后才写入 /etc/pgbackrest/initial.done，失败会被剧本忽略且不会留下标记。该文件只防止初始化任务重复执行，最终仍应使用 pig pb info（或 pgbackrest info）核对仓库中的实际备份状态。 定时备份计划通过 pg_crontab 声明，详见 备份策略。

移除备份

pig pb delete 是只删除备份 stanza 的首选入口。它会在实际执行前交互确认；多 stanza 配置还要求显式给出目标。核对目标后执行：

pig pb info -s pg-meta           # 核对当前备份链与恢复窗口
pig pb delete -s pg-meta         # 输入精确 stanza 名确认后才执行

移除主实例（pg_role = primary）时，pgsql-rm.yml 默认也会尝试删除该集群的备份 stanza。以下命令会直接修改或删除状态：

./pgsql-rm.yml -l pg-meta                          # 移除集群及其备份
./pgsql-rm.yml -l pg-meta -e pg_rm_backup=false    # 移除集群但保留备份
./pgsql-rm.yml -l pg-meta -t pg_backup             # 仅删除备份相关状态

执行前应确认近期备份可用、记录恢复需求，并由操作者再次输入精确的集群/stanza 名。使用 pg_rm_backup（设为 false）可以在移除集群时保留备份。

pgsql-rm.yml -t pg_backup 会在主库上强制执行 pgbackrest stanza-delete，删除本地仓库目录（仅 local 模式），并移除 pgBackRest 配置与初始备份标记；该任务会忽略部分删除错误。因此执行后必须再次检查仓库，不能把剧本“成功”当成备份已物理清空的证明。只需要删除 stanza 时，优先使用上面的 pig pb delete，它提供计划与确认保护。

如果备份仓库为对象版本配置了 对象锁定保留期， 删除可能只写入 Delete Marker，被锁定的历史版本会继续占用空间，直到保留期结束。

手动备份

crontab 之外，随时可以手动触发备份。pg-backup 脚本与 pig pb backup 都带主库角色检查，在从库上执行会直接退出，不会产生错误的备份：

pg-backup            # 增量备份（仓库中无全量备份时自动升级为全量）
pg-backup full       # 全量备份
pg-backup diff       # 差异备份（相对最近一次全量）
pg-backup incr       # 增量备份（相对最近一次任意备份）

pig pb backup full   # 等价：pig 封装，自动检测 stanza 与 DBSU

备份期间会显著占用磁盘 I/O 与网络带宽（并行度已限制在 2～4 进程），建议安排在业务低峰执行。

查看备份

pb info 列出仓库中当前 stanza 的备份与 WAL 归档状态：

pb info          # = pgbackrest --stanza=pg-meta info
pig pb info      # 等价
pig pb list      # 列出仓库中所有 stanza

输出解读的关键是 备份标签： 20250715-013657F 为全量备份（F），..._20250715-013724D 为差异备份（D），..._20250715-013730I 为增量备份（I）—— 下划线前的部分标识备份链所依附的全量备份。wal archive min/max 显示 WAL 归档范围， 它与最早的全量备份共同描述 恢复窗口。

监控系统同样提供备份状态的持续观测：pgbackrest_exporter（端口 9854）导出的 指标 覆盖最近备份时间、类型、大小与错误状态，可直接用于告警。

清理过期备份

保留策略默认在每次备份后自动执行（expire-auto）。手动触发或预览清理计划：

pig pb expire --plan    # 预览将被清理的备份（dry-run，不实际删除）
pig pb expire           # 按保留策略执行清理

Stanza 管理

Stanza 记录集群的备份身份（system-id 与主版本）， 以下场景需要手动管理：

pig pb create             # 创建 stanza：新仓库初始化（Pigsty 集群初始化时自动执行）
pig pb upgrade            # 升级 stanza：PostgreSQL 大版本升级后，或克隆恢复出新集群后
pig pb delete -s pg-meta  # 交互确认后删除全部备份与归档，危险操作！

最常见的手动场景是 克隆集群的善后： 从其他集群的备份恢复出新集群后，stanza 中记录的 system-id 与新集群不符， 必须执行 stanza-upgrade 之后，新集群的备份才能写入仓库。

检查与启停

pig pb check     # 端到端校验：配置、归档推送、仓库可达性
pig pb stop      # 暂停 pgbackrest 操作（维护窗口，阻止新备份/归档启动）
pig pb start     # 恢复 pgbackrest 操作

check 命令会实际推送一个 WAL 段并确认其到达仓库，是排查"归档不工作"问题的第一步。

查看日志

pig pb log           # 列出日志文件
pig pb log tail      # 跟踪最新日志
ls /pg/log/pgbackrest/   # 日志目录：备份、归档、恢复各有独立日志文件

使用 pgsql-pitr.yml 时，PostgreSQL 的恢复日志位于 /pg/tmp/recovery.log。

替代备份工具

pg-basebackup

Pigsty 另备有不依赖 pgbackrest 的独立备份脚本 /pg/bin/pg-basebackup， 它使用原生 pg_basebackup 生成单文件物理备份（lz4 压缩 tarball），默认写入 /pg/backup。 适合在不便使用备份仓库时快速留存一份物理副本：

pg-basebackup                        # 生成 /pg/backup/backup_<tag>_<date>.tar.lz4
pg-basebackup --dst /tmp --file backup.tar.lz4   # 指定输出位置与文件名

mkdir -p /tmp/data                   # 解压提取
cat /pg/backup/backup_pg-meta_20250713.tar.lz4 | unlz4 -d -c | tar -xC /tmp/data

逻辑备份

pg_dump 生成的逻辑备份 不能 用于 PITR，但它是跨大版本迁移、导出部分数据、长期归档快照的正确工具。 物理备份与逻辑备份互为补充，严肃的生产环境通常两者兼备。这是 PostgreSQL 自带的工具，请参阅 官方文档