PGBACKREST

简介 pgBackRest 是一款可靠的 PostgreSQL 备份与恢复解决方案，可无缝扩展以应对超大规模数据库和各类工作负载。 本站文档对应 pgBackRest v2.60.0。发布说明请查阅 发布历史 页面。 2.60.0 新增了可配置的页面校验和错误处理、对象存储读取预取和 GCS 工作负载身份联合。restore 和 expire 现在默认在页面校验和无效时停止；详见 2.60.0 版本说明。 2.59.3 修复了可能生成弱加密子密钥和盐值的问题。升级不会替换 stanza 已有的 …

显示已安装的 pgBackRest 版本。 命令选项 输出格式选项（--output） 输出类型。 支持以下输出类型： text — 以文本形式显示已安装的 pgBackRest 版本。 num — 以整数形式显示已安装的 pgBackRest 版本。 default: text example: --output=num

verify 用于验证仓库中的备份和归档是否有效。 命令选项 输出格式选项（--output） 输出类型。 支持以下输出类型： none — 不输出验证信息。 text — 将验证信息输出到标准输出。 default: none example: --output=text 备份集选项（--set） 要验证的备份集。 验证与指定备份集关联的所有数据库文件和归档文件。 example: --set=20150131-153358F_20150131-153401I 详细输出选项 …

禁止任何新的 pgBackRest 进程运行。默认情况下，正在运行的进程将被允许正常完成。使用 --force 选项可强制终止正在运行的进程。 stop 命令执行完成后，此后尝试运行的 pgBackRest 进程将返回错误。详情与示例请参见 启动与停止。 命令选项 强制选项（--force） 强制停止所有 pgBackRest 进程。 此选项会向所有正在运行的 pgBackRest 进程发送 TERM 信号，实现立即的优雅关闭。注意，这也会关闭由其他系统发起、但在当前系统上运行的远程进程。例如， …

如果 pgBackRest 进程之前已通过 stop 命令停止，可使用 start 命令重新允许它们运行。注意，此命令不会立即启动任何 pgBackRest 进程，只是解除运行限制。详情与示例请参见 启动与停止。 通用选项 允许以 root 用户运行选项（--allow-root） 允许命令以 root 用户运行。 默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件 …

将 PostgreSQL 升级到新的主版本后，必须立即将所有 pgBackRest 配置中的 pg-path 更新为新的数据库位置，然后运行 stanza-upgrade 命令。若主机上配置了多个仓库，每个仓库都会执行 stanza 升级。若数据库处于离线状态，请使用 --no-online 选项。 命令选项 在线选项（--online） 在线更新集群。 指定 --no-online 可阻止 pgBackRest 在升级 stanza 时连接 PostgreSQL。 default: y …

stanza-delete 命令用于删除仓库中与指定 stanza 关联的所有数据。stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称。 警告： 此命令会永久删除指定 stanza 在 pgBackRest 仓库中的所有备份和归档数据，请谨慎使用。 删除 stanza 的步骤如下： 停止与该 stanza 关联的 PostgreSQL 集群（或使用 --force 选项强制删除）。 在执行 stanza-delete 命令的主机上先运行 stop …

stanza-create 命令须在 pgbackrest.conf 中完成 stanza 配置后再执行（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）。若配置了多个仓库，stanza-create 会在每个仓库上分别建立 stanza。已创建的 stanza 会被跳过，因此即便新增了仓库，也可以随时安全地重复执行 stanza-create。 更多信息和示例，请参见 创建 Stanza。 命令选项 在线选项（--online） 在在线集群 …

向 pgBackRest TLS 服务器发送 ping，确认其正在接受连接。此命令仅作为存活性检查，不进行身份验证。 若命令行中未指定主机，则使用 tls-server-host 选项的值。 命令选项 TLS 服务器地址选项（--tls-server-address） TLS 服务器地址。 服务器监听客户端请求的 IP 地址。 default: localhost example: --tls-server-address=* TLS 服务器端口选项（--tls-server-port） TLS …

pgBackRest 服务器允许在不使用 SSH 协议的情况下访问远程主机。 命令选项 TLS 服务器地址选项（--tls-server-address） TLS 服务器地址。 服务器监听客户端请求的 IP 地址。 default: localhost example: --tls-server-address=* TLS 服务器授权客户端选项（--tls-server-auth） TLS 服务器授权客户端。 服务器通过验证客户端证书，并将其证书 CN（Common Name，通用名称）与 …

restore 命令默认从第一个存有备份的仓库中自动选取最新备份（参见 快速开始 - 恢复备份）。仓库的检查顺序由 pgbackrest.conf 决定（例如先检查 repo1，再检查 repo2）。若要从特定仓库恢复，可使用 --repo 选项（例如 --repo=1）。若需恢复非最新的备份，可传入 --set 选项。 指定 --type=time 或 --type=lsn 进行 PITR 时，必须通过 --target 选项提供目标时间或 LSN。若未指定 --set，pgBackRest …

repo-ls 类似于 Unix 的 ls 命令，但支持所有 pgBackRest 仓库类型。该命令接受一个路径参数，可以是绝对路径，也可以是相对于 --repo-path 所定义的仓库根路径的相对路径。此命令主要用于管理、排查和测试场景，并非常规部署的必要命令。 默认以文本格式输出，每行一个文件名。指定 --output=json 可切换为 JSON 格式。 若配置了多个仓库，默认操作优先级最高的仓库（如 repo1），如需指定特定仓库，请使用 --repo 选项。 命令选项 过滤输出选项 …

repo-get 命令类似于 Unix 的 cat 命令，但支持所有仓库类型。使用此命令需要提供完整的文件名，主要用于管理、排查和测试目的，不是常规 pgBackRest 使用流程中的必需命令。 若仓库已加密，repo-get 将自动解密文件。文件不会自动解压，但可将输出通过管道传递给相应的解压命令，例如 gzip -d。 若配置了多个仓库，命令默认使用优先级最高的仓库（如 repo1），除非通过 --repo 选项指定了具体仓库。 命令选项 忽略缺失文件选项（--ignore-missing） …

代码覆盖率 pgBackRest 致力于对 /src 目录下的核心 C 代码实现完整的函数、分支和行覆盖。 函数覆盖率和行覆盖率均已达到 100%，无任何例外。 分支覆盖率排除了宏内部的分支和 assert() 调用。宏有专属的单元测试，因此无需在每处调用时都进行测试。assert 断言不要求完整的分支覆盖，因为它们测试的是应当始终为真的条件。 目录 函数 分支 行 command 17/17 (100.00%) 104/104 (100.00%) 210/210 (100.00%) …

info 命令可作用于单个 stanza 或所有 stanza。默认输出为文本格式，以人类可读的摘要展示所请求 stanza 的备份信息。该格式可能随版本更新而变化。 如需机器可读输出，请使用 --output=json。JSON 输出包含的信息远多于文本格式，且除非发现缺陷，其格式保持稳定。 若只需快速查看进度信息，可指定 --detail-level=progress。注意此模式会跳过 stanza 可用性检查以外的所有检查。 每个 stanza 占独立的输出区块，可使用 --stanza …

简介 常见问题解答旨在针对一些具体问题提供详细说明，这些问题可能未在用户指南、配置参考或命令参考中涵盖。如果在此处找不到您的问题，pgBackRest 在 GitHub 上的 问题列表 也是一个宝贵的资源。 遇到"could not find WAL segment"错误该怎么办？ 此错误可能有多种原因，包括但不限于： archive_command 配置错误 pgBackRest 配置文件配置错误 网络或权限问题 第三方产品（如 S3、Swift 或 MinIO）配置问题 大量 WAL 积压 …

help 命令提供三个层级的帮助信息：未指定命令时显示通用帮助；指定命令（例如 pgbackrest help backup）时显示该命令的完整说明及有效选项列表；在命令之外还指定了某个选项（例如 pgbackrest help backup type）时显示该选项在此命令下的完整说明。 命令选项 显示帮助选项（--help） 显示帮助信息。 即使未指定 help 命令也会显示帮助信息，且优先于 --version 选项。 default: n example: --help 显示版本选项 …

简介 pgBackRest 版本号由主版本、次版本和补丁版本三部分组成。主版本 可能 与上一主版本不兼容，但 v2 与 v1 仓库完全兼容，并接受所有 v1 选项。次版本可以包含缺陷修复和新功能，但不改变仓库格式，并尽量避免修改选项和命名。补丁版本包含针对最新次版本的缺陷修复。 功能版本计划在一月、四月、七月和十月的第三个星期一发布。补丁版本则根据需要，在其余月份的第三个星期一发布。 v1 版本的文档可在 此处 查阅。 版本说明还可能包含“附加说明”，但该部分仅涉及文档或测试套件的变更，不会直 …

pgBackRest 基于保留策略对全量备份进行轮换，策略可按数量或时间段定义。按数量保留时，过期操作只关注需要保留的备份数量，不考虑备份的创建时间。差异备份按数量进行保留，但当其依赖的全量备份过期时，差异备份也会随之过期。增量备份没有独立的保留策略——它们始终随关联的全量备份或差异备份一同过期。详情及示例请参见 全量备份保留策略 和 差异备份保留策略 章节。 默认情况下，未过期备份对应的已归档 WAL 会被保留。如有需要（不推荐），可通过归档保留选项按仓库单独调整此策略。详情及示例请参见 归档 …

简介 pgBackRest 可以完全通过命令行参数使用，但当配置较为复杂或需要设置大量选项时，使用配置文件更为实用。配置文件的默认路径为 /etc/pgbackrest/pgbackrest.conf。若该路径下不存在配置文件，则会检查旧的默认路径 /etc/pgbackrest.conf。 以下是支持的选项类型： String（字符串）：文本字符串，常见用途包括标识符、密码等。 命令行示例：--stanza=demo配置文件示例 …

check 命令用于验证 pgBackRest 及 archive_command 的配置是否正确，确保指定 stanza 的归档与备份能够正常运作。该命令会对当前主机上为该 stanza 配置的所有仓库和数据库逐一检查，可检测出配置错误——尤其是归档配置问题，此类问题会导致所需的 WAL 段无法进入归档，从而造成备份不完整。此命令可在 PostgreSQL 主机或仓库主机上运行；也可在备库主机上运行，但由于备库无法执行 pg_switch_xlog()/pg_switch_wal()，命令仅会 …

简介 pgBackRest 通过命令来执行各项功能。本文档对每个命令的选项进行了详尽列举——即每个适用于某命令的选项都会随该命令一并列出，即便该选项同样适用于其他命令。所有可在 pgbackrest.conf 中配置的选项均包含在内。 在 pgbackrest.conf 中配置的非布尔型选项，可在命令行上使用 reset- 前缀将其重置为默认值。这一功能可用于在仓库主机上直接恢复备份。通常情况下，pgBackRest 检测到数据库主机是远程主机后会报错，因为恢复操作无法远程执行。在命令行添加 …

配置多个仓库时，pgBackRest 默认备份到优先级最高的仓库（如 repo1），除非通过 --repo 选项明确指定目标仓库。 pgBackRest 本身不内置调度器，建议通过 cron 或其他调度机制触发备份。 详情与示例请参见 执行备份。 命令选项 备份注解选项（--annotation） 为备份附加用户自定义的键值对注解。 可为备份附加任意键值对信息，此选项可多次使用以添加多个注解。 通过 --set 指定备份时，info 命令的文本输出会显示注解；JSON 输出则始终包含注解信息。 …

简介 本用户指南设计为从头到尾顺序阅读——每个章节都依赖前一章节的内容。例如， 恢复 章节依赖 快速开始 章节中完成的配置。pgBackRest 运行起来之后可以跳章查阅，但初次阅读建议按顺序跟随。 本指南的示例基于 RHEL 和 PostgreSQL 14，但迁移到其他 Unix 发行版或 PostgreSQL 版本并不困难。与操作系统相关的命令仅限于创建、启动、停止和删除 PostgreSQL 集群的部分；pgBackRest 命令在所有 Unix 系统上均相同，只是可执行文件路径可能有所 …

接收来自 PostgreSQL 的 WAL 段，并将其归档到各个仓库中（仓库路径由带索引的 repo-path 选项定义，详见 仓库选项 章节）。WAL 段可以立即推送到归档，也可以根据 archive-async 的值先暂存在本地。配置了多个仓库时，archive-push 会尽量向所有仓库推送。 archive-push 由 PostgreSQL 负责配置和调用。相关示例请参见 配置归档。 命令选项 异步归档选项（--archive-async） 异步推送/获取 WAL 段。 为 …

简介 本用户指南适合从头到尾顺序阅读——每章内容均依赖前一章的配置基础。例如， 恢复 章节依赖 快速开始 章节中已完成的配置。pgBackRest 运行起来之后，跳章阅读也无妨，但建议初次阅读时按顺序跟随本指南。 本指南的示例基于 Debian/Ubuntu 和 PostgreSQL 17，但移植到其他 Unix 发行版和 PostgreSQL 版本并不困难。与操作系统相关的命令仅限于创建、启动、停止和删除 PostgreSQL 集群的部分；pgBackRest 命令在各 Unix 系统上完全 …

PostgreSQL 通过此命令执行备份恢复、PITR，或将其作为流复制的替代方式来维持副本同步。WAL 段是 PostgreSQL 执行恢复或维护副本的必要条件。 配置多个仓库时，pgBackRest 按优先级顺序（如 repo1、repo2 等）依次从各仓库获取 WAL。速度更快或成本更低的存储应配置更高的优先级。若通过 --repo 选项指定了某个仓库，则仅从该仓库中查找。 archive-get 命令由 pgBackRest 在恢复过程中自动配置并生成，供 PostgreSQL 使用。相 …

pgBackRest 2.60.0 正式发布 2026 年 10 月 18 日 pgBackRest 社区很高兴地宣布 pgBackRest 2.60.0 正式发布。pgBackRest 是一款可靠、易用的备份与恢复解决方案，可无缝扩展以应对超大规模数据库和工作负载。 pgBackRest 为管理备份与恢复基础设施提供了丰富而强大的功能，包括：并行备份与恢复、全量/差异/增量备份、块级增量备份、多仓库、delta 恢复、并行异步归档、恶意软件/勒索软件防护、逐文件校验和、备份期间验证页面校验和 …

backup 命令执行时附加的注解，可在事后通过 annotate 命令进行添加、修改或删除。 命令选项 备份注解选项（--annotation） 为备份添加用户自定义键值对注解。 可为备份附加具有描述性的键值对。此选项可多次使用，以添加多条注解。 使用 --set 指定备份后，注解将显示在 info 命令的文本输出中，并始终出现在 JSON 输出中。 example: --annotation=source="Sunday backup for website database" 备份集选项 …