模块: PGBACKREST

pgBackRest 2.59 文档快照： https://pgbackrest.org/ 简介 pgBackRest 是一款可靠的 PostgreSQL 备份与恢复解决方案，可无缝扩展以应对超大规模数据库和各类工作负载。 pgBackRest v2.59.0 是当前稳定版本。发布说明请查阅 发布历史 页面。 如果您喜欢 pgBackRest，欢迎在 GitHub 上给我们点星！ 新闻 2026 年 7 月 20 日 - 新的发行版 tarball 2026 年 7 月 20 日 - …

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

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

原始页面： pgBackRest Command Docs: stop 禁止任何新的 pgBackRest 进程运行。默认情况下，正在运行的进程将被允许正常完成。使用 --force 选项可强制终止正在运行的进程。 stop 命令执行完成后，此后尝试运行的 pgBackRest 进程将返回错误。详情与示例请参见 启动与停止。 命令选项 强制停止选项（--force） 强制停止所有 pgBackRest 进程。 此选项会向所有正在运行的 pgBackRest 进程发送 TERM 信号，实现立即的 …

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

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

原始页面： pgBackRest Command Docs: stanza-delete stanza-delete 命令用于删除仓库中与指定 stanza 关联的所有数据。stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称。 警告： 此命令会永久删除指定 stanza 在 pgBackRest 仓库中的所有备份和归档数据，请谨慎使用。 删除 stanza 的步骤如下： 停止与该 stanza 关联的 PostgreSQL 集群（或使用 …

原始页面： pgBackRest Command Docs: stanza-create stanza-create 命令须在 pgbackrest.conf 中完成 stanza 配置后再执行（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）。若配置了多个仓库，stanza-create 会在每个仓库上分别建立 stanza。已创建的 stanza 会被跳过，因此即便新增了仓库，也可以随时安全地重复执行 stanza-create。 更多 …

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

原始页面： pgBackRest Command Docs: server pgBackRest 服务器允许在不使用 SSH 协议的情况下访问远程主机。 命令选项 TLS 服务器地址选项（--tls-server-address） TLS 服务器地址。 服务器监听客户端请求的 IP 地址。 default: localhost example: --tls-server-address=* TLS 服务器授权客户端选项（--tls-server-auth） TLS 服务器授权客户端。 服务器通 …

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

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

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

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

原始页面： pgBackRest Command Docs: info info 命令可查询单个 stanza（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）或所有 stanza 的信息。默认输出为文本格式，以人类可读的摘要展示所请求 stanza 的备份信息。该格式可能随版本更新而变化。 如需机器可读输出，请使用 --output=json。JSON 输出包含的信息远多于文本格式，且除非发现缺陷，其格式保持稳定。 若只需快速查看进度信息 …

原始页面： https://pgbackrest.org/faq.html 简介 常见问题解答旨在针对一些具体问题提供详细说明，这些问题可能未在用户指南、配置参考或命令参考中涵盖。如果在此处找不到您的问题，pgBackRest 在 GitHub 上的 Issues List 也是一个宝贵的资源。 遇到"could not find WAL segment"错误该怎么办？ 此错误可能有多种原因，包括但不限于： archive_command 配置错误 pgBackRest 配置文件配置错误 网络 …

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

原始页面： https://pgbackrest.org/release.html 简介 pgBackRest 的版本号由主版本号和次版本号两部分组成。主版本升级 可能 破坏与上一主版本的兼容性，但 v2 版本与 v1 仓库完全兼容，且接受所有 v1 选项。次版本可包含漏洞修复和新功能，但不会更改仓库格式，并尽量避免修改选项和命名约定。v1 版本的文档可在 此处 查阅。版本说明中还可能包含"附加说明"，此部分变更仅涉及文档或测试套件，不直接影响 pgBackRest 代码库。 当前稳定版本 …

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

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

原始页面： pgBackRest Command Docs: check check 命令用于验证 pgBackRest 及 archive_command 的配置是否正确，确保指定 stanza（stanza 是 pgBackRest 中用于标识 PostgreSQL 集群备份配置的逻辑名称）的归档与备份能够正常运作。该命令会对当前主机上为该 stanza 配置的所有仓库和数据库逐一检查，可检测出配置错误——尤其是归档配置问题，此类问题会导致所需的 WAL 段无法进入归档，从而造成备份不完整 …

原始页面： https://pgbackrest.org/command.html 简介 pgBackRest 通过命令来执行各项功能。本文档对每个命令的选项进行了详尽列举——即每个适用于某命令的选项都会随该命令一并列出，即便该选项同样适用于其他命令。所有可在 pgbackrest.conf 中配置的选项均包含在内。 在 pgbackrest.conf 中配置的非布尔型选项，可在命令行上使用 reset- 前缀将其重置为默认值。这一功能在直接于仓库主机上执行恢复时很有用。通常情况下 …

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

原始页面： https://pgbackrest.org/user-guide-rhel.html 简介 本用户指南设计为从头到尾顺序阅读——每个章节都依赖前一章节的内容。例如， 恢复 章节依赖 快速开始 章节中完成的配置。熟悉 pgBackRest 之后可以跳章查阅，但初次阅读建议按顺序跟随。 本指南的示例基于 RHEL 和 PostgreSQL 14，但迁移到其他 Unix 发行版或 PostgreSQL 版本并不困难。与操作系统相关的命令仅限于创建、启动、停止和删除 PostgreSQL …

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

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

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

原始页面： https://pgbackrest.org/news.html 新的发行版 tarball 2026 年 7 月 20 日 从 pgBackRest 2.59.0 开始，每个版本都会提供一个发行版 tarball，让从源码构建变得更加简单。与 Git 仓库检出版本不同，该 tarball 已经包含生成后的源码和预先渲染的文档，因此构建和安装 pgBackRest 时不再需要仓库检出所要求的代码生成工具或文档工具。 tarball 包含 pgBackRest 源码及预生成代码、命令 …

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