这是本节的多页打印视图。 .

返回本页常规视图.

pgBackRest 2.59 中文文档

可靠的 PostgreSQL 备份与恢复工具 —— pgBackRest 文档与参考手册。

pgBackRest 2.59 文档快照： https://pgbackrest.org/

简介

pgBackRest 是一款可靠的 PostgreSQL 备份与恢复解决方案，可无缝扩展以应对超大规模数据库和各类工作负载。

pgBackRest v2.59.0 是当前稳定版本。发布说明请查阅 发布历史 页面。

如果您喜欢 pgBackRest，欢迎在 GitHub 上给我们点星！

新闻

2026 年 7 月 20 日 - 新的发行版 tarball

2026 年 7 月 20 日 - pgBackRest 2.59.0 正式发布

2026 年 5 月 18 日 - pgBackRest 将继续维护！

赞助商

没有赞助就不会有 pgBackRest。开发新功能、修复缺陷、审核贡献、回答社区问题以及日常维护都需要投入大量时间。如果您在企业中使用 pgBackRest，请考虑 赞助 项目。

我们的赞助商：AWS、Supabase、pgEdge、Tiger Data、Percona、Eon、Xata、Dalibo 和 Data Egret。

感谢赞助商投资于惠及整个 PostgreSQL 社区的开源基础设施。

曾经的赞助商：Crunchy Data、Resonate。

功能特性

并行备份与恢复

压缩通常是备份操作的性能瓶颈，pgBackRest 通过并行处理以及 lz4、zstd 等高效压缩算法解决了这一问题。

本地或远程操作

pgBackRest 采用自定义协议，仅需极少配置即可通过 TLS/SSH 在本地或远程执行备份、恢复和归档操作。协议层还提供了查询 PostgreSQL 的接口，因此无需直接远程访问 PostgreSQL，从而增强了安全性。

多仓库支持

多仓库支持让用户可以灵活组合，例如：用一个保留周期较短的本地仓库快速恢复，同时用一个保留周期较长的远程仓库实现冗余备份和企业级访问。

全量、差异与增量备份（文件级或块级）

pgBackRest 支持全量备份（full backup）、差异备份（differential backup）和增量备份（incremental backup）。pgBackRest 不受 rsync 时间精度问题的影响，因此无需对每个文件都做校验和计算，差异备份和增量备份同样安全可靠。块级备份通过仅复制文件中发生变化的部分来节省存储空间。

备份轮换与归档过期

可为全量备份和差异备份分别设置保留策略，覆盖任意时间范围。WAL 归档可以针对所有备份维护，也可以只针对最近的备份维护；后一种情况下，旧备份保持一致性所必需的 WAL 会继续保留在归档中。

备份完整性

pgBackRest 为备份中的每个文件计算校验和，并在恢复或验证时重新校验。备份完成文件复制后，会等待所有维持备份一致性所需的 WAL 段到达仓库。

仓库中的备份可以与标准 PostgreSQL 集群相同的格式存储（含表空间）。若禁用压缩并启用硬链接，可对仓库中的备份创建快照，并直接在快照上启动 PostgreSQL 集群。这对于以传统方式恢复耗时较长的 TB 级数据库尤为有利。

所有操作均使用文件和目录级 fsync 以确保持久性。

页面校验和

若启用了页面校验和，pgBackRest 在备份时会对每个复制的文件进行校验和验证。全量备份时验证所有页面的校验和，差异备份和增量备份时仅验证已变更文件的校验和。

校验和验证失败不会中止备份进程，而是将包含具体失败页面详情的警告信息输出到控制台和日志文件。

此功能可在包含有效数据副本的备份过期之前，提前发现页面级损坏。

备份续传

中断的备份可从中断位置续传。已复制的文件会与清单文件（manifest）中的校验和进行比对以确保完整性。由于该操作可完全在仓库主机上执行，因此减轻了数据库主机的负载，并因校验和计算比重新压缩和重传数据更快而节省了时间。

流式压缩与校验和

无论仓库位于本地还是远程，压缩和校验和计算均在文件复制到仓库的过程中以流式方式同步进行。

若仓库位于仓库主机上，压缩在数据库主机上执行，文件以压缩格式传输并直接存储到仓库主机。若禁用压缩，则采用较低级别的压缩，在最大程度降低 CPU 开销的同时有效利用可用带宽。

Delta 恢复

清单文件（manifest）包含备份中每个文件的校验和，恢复时可利用这些校验和大幅加速处理过程。执行 delta restore 时，先删除备份中不存在的文件，再对剩余文件计算校验和；与备份匹配的文件原地保留，其余文件按常规方式恢复。并行处理可显著缩短恢复时间。

并行异步 WAL 推送与获取

pgBackRest 提供了专用命令，用于将 WAL 推送到归档以及从归档获取 WAL。两个命令均支持并行处理以加速操作，并以异步方式运行，尽可能快速地响应 PostgreSQL 的请求。

WAL 推送会自动检测被重复推送的 WAL 段：内容相同则去重，内容不同则报错。异步 WAL 推送可将传输任务卸载到后台进程，该进程并行压缩 WAL 段以实现最大吞吐量。对于写入量极大的数据库，这是一项关键功能。

异步 WAL 获取会在本地维护一个已解压、可供回放的 WAL 段队列，从而减少向 PostgreSQL 提供 WAL 所需的延迟，最大化回放速度。高延迟连接和存储（如 S3）受益最为明显。

推送和获取命令均通过比对 PostgreSQL 版本和系统标识符来确保数据库与仓库匹配，从而几乎消除了 WAL 归档位置配置错误的风险。

表空间与链接支持

pgBackRest 完全支持表空间，恢复时可将表空间重新映射到任意位置。也可通过单条命令将所有表空间映射到同一位置，在开发环境恢复时非常实用。

pgBackRest 支持 PostgreSQL 集群中任意文件或目录的文件链接和目录链接。恢复时，可将所有链接还原到原始位置、重新映射部分或全部链接，也可将部分或全部链接以普通文件或目录的形式恢复到集群目录中。

兼容 S3、Azure 和 GCS 对象存储

pgBackRest 仓库可存储在兼容 S3、Azure 和 GCS 的对象存储中，从而实现近乎无限的存储容量和保留期限。

加密

pgBackRest 支持对仓库加密，无论备份存储在何处，均能保障数据安全。

勒索软件与恶意软件防护

当仓库存储在启用了版本控制的对象存储中时，pgBackRest 可以按指定时间点读取仓库。如果备份因误操作、恶意软件或勒索软件而被删除或损坏，可以设置目标时间，恢复受损前的数据。

兼容 S3、Azure 和 GCS 的对象存储均支持版本控制。S3 的对象锁定以及 GCS 或 Azure 的软删除可以提供额外的防篡改保护。

兼容十个 PostgreSQL 版本

pgBackRest 支持十个 PostgreSQL 版本，包括五个仍在官方支持期内的版本和最近五个已终止支持（EOL）的版本，为用户升级到受支持版本留出了充足时间。

快速入门

pgBackRest 致力于提供简便的配置和操作体验：

贡献

我们随时欢迎对 pgBackRest 的贡献！请参阅 贡献指南 了解如何贡献功能、改进或提交问题反馈。

支持

pgBackRest 基于 MIT 许可证完全免费开源，可用于个人或商业用途，不受任何限制。我们非常重视 Bug 报告，并将尽快处理。请在 此处 提交 Bug。

制定完善的容灾方案（包含合理的复制和备份策略）可能是一项复杂而艰巨的任务。在架构设计阶段和持续运营中，您可能需要专业支持以确保企业业务平稳运行。

我们的 赞助商 所提供的产品和服务包含 pgBackRest 支持，可协助您满足容灾需求。

1 - 新闻

pgBackRest 项目新闻、版本发布公告与维护动态。

原始页面： https://pgbackrest.org/news.html

新的发行版 tarball

2026 年 7 月 20 日

从 pgBackRest 2.59.0 开始，每个版本都会提供一个发行版 tarball，让从源码构建变得更加简单。与 Git 仓库检出版本不同，该 tarball 已经包含生成后的源码和预先渲染的文档，因此构建和安装 pgBackRest 时不再需要仓库检出所要求的代码生成工具或文档工具。

tarball 包含 pgBackRest 源码及预生成代码、命令参考手册页、HTML 文档，以及用于验证构建的冒烟测试。仅需 pgBackRest 通常依赖的库，即可使用 meson 和 ninja 进行构建。

该 tarball 会以 pgbackrest-{version}.tar.gz 的名称作为附件随每个版本发布，并同时提供对应的 .sha256sum 校验和文件。请从 GitHub 的 版本发布 页面下载，然后参阅 tarball 中的 README.md 了解构建与测试说明。

建议打包者使用发行版 tarball 进行构建，以避免未来版本因生成代码和文档而需要额外的构建工具。

pgBackRest 2.59.0 正式发布

2026 年 7 月 20 日

pgBackRest 社区很高兴地宣布 pgBackRest 2.59.0 正式发布。pgBackRest 是一款可靠、易用的备份与恢复解决方案，可无缝扩展以应对超大规模数据库和工作负载。

pgBackRest 为管理备份与恢复基础设施提供了丰富而强大的功能，包括：并行备份与恢复、全量/差异/增量备份、块级增量备份、多仓库、delta 恢复、并行异步归档、恶意软件/勒索软件防护、逐文件校验和、备份期间验证页面校验和（启用时）、多种压缩类型、加密、部分备份/失败备份续传、从备库执行备份、表空间与链接支持、S3/Azure/GCS/SFTP 支持、备份过期、本地或通过 SSH/TLS 进行远程操作、灵活配置，以及更多功能。

pgBackRest 可从 PostgreSQL Yum 仓库 或 PostgreSQL APT 仓库 安装，许多其他发行版也提供相应软件包。源码可从 版本发布 页面下载。

重要新功能与改进

  • 支持 PostgreSQL 19（David Steele）
  • 新增 archive-expire-before 选项，用于清理 WAL 归档（Stefan Fercot）
  • 添加对 S3 Outposts 的支持（Shiva Kumar Ambigi）
  • 添加 S3 进程认证支持（David Steele）
  • 添加用户/组缓存，加快清单构建速度（Gunnar Lindholm）
  • 服务器断开空闲连接后，重新建立 SFTP 存储连接（David Steele）
  • 在 info 命令输出中添加各仓库的备份进度（Will Morland）
  • 为 Azure 存储添加批量删除功能（David Steele）
  • 为 verify 命令添加 backup.info 检查（Denis Garsh）
  • 允许配置 S3 STS 端点（Simon Gratton）
  • 添加 systemd 通知集成（Andrew Jackson）
  • 未启用 allow-root 时，由 root 用户运行命令将报错（David Steele）
  • 异步 archive-push 遇到第一个错误时退出（David Steele）

其他功能和改进请参阅 2.59.0 版本说明。

重要提示

  • 默认情况下，只有 restore 命令允许由 root 用户运行。若要由 root 用户运行其他命令，请使用 allow-root（但不建议这样做）。
  • 每个版本现在都会附带一个新的发行版 tarball，其中包含预生成的文档、手册页和代码，从而简化打包流程。详情请参阅 新的发行版 tarball。
  • 新增了对 libsystemd 的可选依赖。

赞助

感谢 AWS、Supabase、pgEdge、Tiger Data、Percona、Eon、Xata、Dalibo 和 Data Egret 的慷慨赞助，使本次发布成为可能。

pgBackRest 将继续维护！

2026 年 5 月 18 日

我很高兴地宣布，pgBackRest 将继续维护！在过去几周里，多家赞助商组成联盟，为项目的持续开发提供资金。他们的支持意味着项目不再依赖单一赞助商，为 pgBackRest 提供了长期发展所需的稳定性。

我要感谢每一位赞助商：

Amazon Web Services 为个人、企业和政府提供按需云计算资源。用户可以按实际用量付费，使用计算、存储、数据库、机器学习以及 200 多项服务。AWS 与用户共同成长，并持续投资于我们共有的社区。

Supabase 是一个基于 PostgreSQL 构建的完整后端平台，使开发者无需管理基础设施即可快速构建和扩展应用。它提供 Postgres 数据库、用户认证、实时订阅、文件存储、边缘函数和无服务器函数，并由活跃的开源社区提供支持。

pgEdge 是面向 AI、高可用等场景的企业级开源 Postgres 平台，提供 Agentic AI 原生工具、DBA 工作台、监控与事件响应、灵活部署以及零停机维护。它可以从单节点扩展到双活多主集群，并可部署在云端、本地或网络隔离环境中。

Tiger Data 是 TimescaleDB 的创建者，负责开发基于 PostgreSQL 构建的开源时序数据库，并运营面向时序、分析和 AI 工作负载的托管平台 Tiger Cloud。无论自主管理还是使用云服务，组织都可以大规模采集、存储和分析时序数据，覆盖从边缘到集中式云端的部署场景。

Percona 是一家开源数据库软件、支持与服务公司，致力于帮助组织完全掌控自己的数据基础设施。他们通过免费提供的开源软件、全天候专家支持和实际数据库经验，帮助企业安全高效地运行 MySQL、PostgreSQL、MongoDB、Valkey 和 Redis。

Eon.io 提供面向备份、恢复和数据管理的智能云基础设施，帮助团队更高效地存储和访问备份，并使数据可用于分析和 AI 工作流。它为各类云环境中的 Postgres 和数据密集型工作负载提供快速、细粒度的恢复能力并显著降低存储成本，也能应对误删数据和 AI 智能体回归问题。

这些组织依赖 pgBackRest 为其产品和客户提供可靠的容灾能力。他们的投资体现了 pgBackRest 在 PostgreSQL 生态系统中的关键作用，而共同赞助则确保了项目的长期可持续发展。

我期待着重新投入工作。项目已经规划了一些令人振奋的功能和优化，我很高兴能在后续版本中与大家分享。感谢赞助商让这一切成为可能，也感谢社区在此次过渡期间的耐心与支持。

维护动态

2026 年 5 月 4 日

在我宣布不再维护 pgBackRest 后，收件箱瞬间被塞爆了。我花了一些时间梳理这些邮件，其中很多都是对我多年工作的祝福与感谢。

但很快便出现了一种明显的共识。许多 pgBackRest 用户，尤其是那些还需要为自己的 pgBackRest 用户提供支持的人，更希望项目继续由我担任主要维护者。我当然也希望如此，但经过数月筹款后，我刚刚认定这件事不会实现。

现在情况已经改变，我几乎可以确定能够获得足够的资金让项目继续下去。这一次，pgBackRest 将由赞助商联盟提供资金，这样单次收购事件就不会再影响我继续维护项目的能力。我们应该还能引入另一位维护者来分担工作，并为项目未来提供连续性保障。

我知道这件事令人震惊，也带来了许多不确定性。请保持耐心——当前版本的 pgBackRest 可以正常工作，也没有尚未解决的关键缺陷或安全问题，因此不必立即 fork 项目。

我预计将在本周结束前发布更明确的公告。在此之前，请耐心等待；我们正积极努力让 pgBackRest 恢复活力。

pgBackRest 已不再维护

2026 年 4 月 27 日

简而言之：pgBackRest 已不再维护。如果您要 fork pgBackRest，请为自己的项目选择一个新名称。

经过深思熟虑，我决定停止 pgBackRest 的开发工作。这个决定并非轻率做出。过去十三年间，pgBackRest 一直是我倾注热情的项目；在其中很长一段时间里，我很幸运地获得了企业赞助，但也曾在许多个深夜和周末持续工作，并在众多贡献者的帮助下将 pgBackRest 打造成今天的项目。每一位开源开发者都清楚我的意思，也知道一个特别的项目会占据生命中的多少时间。

Crunchy Data 被收购后，我一边继续维护 pgBackRest，一边寻找能让我继续这项工作的职位，但截至目前并未成功。同样，我为项目争取赞助的努力，也远未达到维持项目所需的水平。

和所有人一样，我也需要维持生计，但与 pgBackRest 相关的职位选择非常有限。现在我可以考虑更广泛的机会，但这些工作不会给我留下维护 pgBackRest 的时间，而日常维护、修复缺陷、审核 PR、回复问题等都需要投入相当多的精力。这甚至还不包括开发新功能的时间，而那恰恰是我最喜欢的工作。与其质量低下或断断续续地继续，我认为彻底停止更为合理。

我想 pgBackRest 终有一天会被 fork，但那将是一个由新维护者负责的新项目，他们也需要像我们当初一样逐步建立信任。

再次衷心感谢这些年来所有 pgBackRest 的贡献者。与大家合作是我的荣幸！

2 - 用户指南（Debian/Ubuntu）

面向 Debian 和 Ubuntu 系统的 pgBackRest 安装配置与使用指南，按步骤逐一讲解。

原始页面： https://pgbackrest.org/user-guide.html

简介

本用户指南适合从头到尾顺序阅读——每章内容均依赖前一章的配置基础。例如， 恢复 章节依赖 快速开始 章节中已完成的配置。pgBackRest 运行起来之后，跳章阅读也无妨，但建议初次阅读时按顺序跟随本指南。

本指南的示例基于 Debian/Ubuntu 和 PostgreSQL 17，但移植到其他 Unix 发行版和 PostgreSQL 版本并不困难。与操作系统相关的命令仅限于创建、启动、停止和删除 PostgreSQL 集群的部分；pgBackRest 命令在各 Unix 系统上完全相同，只是可执行文件路径可能有所不同。pgBackRest 致力于在各 PostgreSQL 版本间保持一致的行为，但不同版本在路径、文件名和配置项等细节上存在细微差异，这些差异可能在本指南的某些示例中有所体现。

有关 PostgreSQL 的配置信息和文档，请参阅 PostgreSQL 手册。

本用户指南在文档方式上颇具特色：每条命令在从 XML 源构建文档时都会在虚拟机上实际执行。因此，你可以充分相信这些命令按照呈现的顺序能够正确运行。命令执行后如有相关输出，将显示在命令下方；若未附输出，则说明该输出与叙述无关或有所干扰。

所有命令均以具有 root 和 postgres 用户 sudo 权限的非特权用户身份运行。也可以直接以对应用户身份运行，无需任何修改，此时去掉 sudo 即可。

核心概念

以下概念的定义与 pgBackRest、PostgreSQL 及本用户指南密切相关。

备份

备份是数据库集群的一致性副本，可用于从硬件故障中恢复、执行时间点恢复（PITR）或启动新的备库。

全量备份（full backup）：将数据库集群的全部内容复制到备份中。第一次备份始终是全量备份。全量备份可直接恢复，其一致性不依赖于任何外部文件。

差异备份（differential backup）：仅复制自上次全量备份以来发生变化的文件。恢复时，pgBackRest 将差异备份中的所有文件与上一次全量备份中未变化的文件合并。差异备份占用的磁盘空间少于全量备份，但恢复时差异备份和对应的全量备份必须同时有效。

增量备份（incremental backup）：仅复制自上次备份（可以是增量备份、差异备份或全量备份）以来发生变化的文件，因此通常比全量备份或差异备份小得多。与差异备份类似，增量备份的恢复依赖于其他备份的有效性。具体而言，恢复增量备份需要：该增量备份之前同一差异备份周期内的所有增量备份、上一次差异备份，以及上一次全量备份，全部有效。若不存在差异备份，则需要追溯至上一次全量备份的全部增量备份及全量备份本身。

恢复

恢复是将备份复制到目标系统并将其作为活跃数据库集群启动的过程。恢复需要备份文件以及一个或多个 WAL 段。

预写日志（WAL）

WAL 是 PostgreSQL 用于确保已提交事务不丢失的机制。事务按顺序写入 WAL，写入刷盘后该事务即视为已提交。此后，后台进程再将变更写入主数据库集群文件（即堆文件）。发生崩溃时，PostgreSQL 会重放 WAL 以恢复数据库一致性。

WAL 在概念上是无限的，但实际中会被切分为每个 16MB 的独立文件，称为 WAL 段。WAL 段遵循 0000000100000A1E000000FE 这样的命名约定，其中前 8 个十六进制数字表示时间线，后 16 位是逻辑序列号（LSN）。

加密

加密是将数据转换为不可识别格式的过程，只有提供正确的密码（口令）才能还原。

pgBackRest 根据用户提供的密码对仓库进行加密，防止未经授权的访问。

升级 pgBackRest

从 v2.x 升级到 v2.y

从 v2.x 升级到 v2.y 非常简单。仓库格式没有变化，大多数情况下只需安装新版本的二进制文件即可。如果未使用旧版本不支持的新功能，也可以回滚降级。

重要提示：

本地与远程的 pgBackRest 版本必须完全一致，因此应同步升级。版本不一致时，WAL 归档和备份将无法正常工作，并报告如下错误：[ProtocolError] expected value '2.x' for greeting key 'version' but got '2.y'。

编译构建

推荐通过软件包安装 pgBackRest，而非从源码构建。有关软件包的更多信息，请参阅 安装 章节。

如需从源码构建，建议在专用构建主机上进行，而非生产环境——构建所需的许多工具不应出现在生产系统上。pgBackRest 由单个可执行文件构成，构建完成后可方便地复制到目标主机。

build ⇒ 将 pgBackRest 版本 2.59.0 下载到 /build 路径

BASH
mkdir -p /build
curl -fsSL \
       https://github.com/pgbackrest/pgbackrest/releases/download/release%2F2.59.0/pgbackrest-2.59.0.tar.gz | \
       tar zx -C /build

build ⇒ 安装构建依赖

BASH
sudo apt-get install python3-distutils meson gcc libpq-dev libssl-dev libxml2-dev \
       pkg-config liblz4-dev libzstd-dev libbz2-dev libz-dev libssh2-1-dev libsystemd-dev

build ⇒ 配置并编译 pgBackRest

BASH
meson setup /build/pgbackrest /build/pgbackrest-2.59.0
ninja -C /build/pgbackrest

build ⇒ 可选：运行冒烟测试，确认 pgBackRest 已正确构建

BASH
meson test -C /build/pgbackrest --suite smoke
ninja: Entering directory `/build/pgbackrest'
ninja: no work to do.
TEXT
1/1 smoke OK               14.97s
       [filtered 7 lines of output]

安装

创建一台名为 pg-primary 的新主机，用于承载演示集群并运行 pgBackRest 示例。

推荐通过软件包安装 pgBackRest。使用软件包时，本节后续步骤通常不必手动执行，但个别软件包可能遗漏某个目录的创建或权限设置有误，此时需要手动创建目录或修正权限。

Debian/Ubuntu 的 pgBackRest 软件包可在 apt.postgresql.org 获取。

如果当前发行版没有提供软件包，可以 从源码构建 后手动安装，步骤如下。

pg-primary ⇒ 安装依赖项

BASH
sudo apt-get install postgresql-client libxml2 libssh2-1

pg-primary ⇒ 从构建主机复制 pgBackRest 二进制文件

BASH
sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin
sudo chmod 755 /usr/bin/pgbackrest

pgBackRest 运行需要日志目录、配置目录和配置文件。

pg-primary ⇒ 创建 pgBackRest 配置文件和目录

BASH
sudo mkdir -p -m 770 /var/log/pgbackrest
sudo chown postgres:postgres /var/log/pgbackrest
sudo mkdir -p /etc/pgbackrest
sudo mkdir -p /etc/pgbackrest/conf.d
sudo touch /etc/pgbackrest/pgbackrest.conf
sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf

pgBackRest 此时应已正确安装，建议进行验证。若有依赖项缺失，命令行运行 pgBackRest 时会报错。

pg-primary ⇒ 确认安装成功

BASH
sudo -u postgres pgbackrest

pgBackRest 2.59.0 - General help

Usage:
    pgbackrest [options] [command]

Commands:
    annotate        add or modify backup annotation
    archive-get     get a WAL segment from the archive
    archive-push    push a WAL segment to the archive
    backup          backup a database cluster
    check           check the configuration
    expire          expire backups that exceed retention
    help            get help
    info            retrieve information about backups
    repo-get        get a file from a repository
    repo-ls         list files in a repository
    restore         restore a database cluster
    server          pgBackRest server
    server-ping     ping pgBackRest server
    stanza-create   create the required stanza data
    stanza-delete   delete a stanza
    stanza-upgrade  upgrade a stanza
    start           allow pgBackRest processes to run
    stop            stop pgBackRest processes from running
    verify          verify contents of a repository
    version         get version

Use 'pgbackrest help [command]' for more information.

快速开始

本章介绍 pgBackRest 和 PostgreSQL 的基本配置，并演示 backup、restore 和 info 命令的基本用法。

创建演示集群

创建演示集群是可选步骤，但强烈推荐，尤其是对新用户而言——用户指南中的示例命令均引用该演示集群，且假设其运行在默认端口（5432）上。由于还有一些配置工作需要完成，集群将在后续章节中启动。

pg-primary ⇒ 创建演示集群

BASH
sudo -u postgres /usr/lib/postgresql/17/bin/initdb \
       -D /var/lib/postgresql/17/demo -k -A peer

sudo pg_createcluster 17 demo
TEXT
Configuring already existing cluster (configuration: /etc/postgresql/17/demo, data: /var/lib/postgresql/17/demo, owner: 102:103)
Ver Cluster Port Status Owner    Data directory              Log file
17  demo    5432 down   postgres /var/lib/postgresql/17/demo /var/log/postgresql/postgresql-17-demo.log

配置集群 Stanza

stanza 是 pgBackRest 中标识一个 PostgreSQL 集群备份配置的逻辑名称，定义了数据库集群的位置、备份方式和归档选项等配置。大多数数据库服务器只有一个 PostgreSQL 集群，因此只有一个 stanza；备份服务器则为每个需要备份的集群各配置一个 stanza。

为 stanza 命名时，容易直接使用主集群名，但更好的做法是用能描述集群所承载业务的名称。由于 stanza 名称同时用于主库和所有副本，选择能反映集群实际用途的名称（如 app 或 dw）比使用本地集群名（如 main 或 prod）更为合适。

demo 准确描述了该集群的用途，因此也是一个合适的 stanza 名称。

pgBackRest 需要知道 PostgreSQL 集群数据目录的位置。该路径通常可从 PostgreSQL 直接获取，但在恢复场景中 PostgreSQL 进程不可用。备份过程中，pgBackRest 会将配置的路径与 PostgreSQL 实际运行的路径进行比对，两者必须完全一致，否则备份会报错。请确保 pg-path 与 PostgreSQL 报告的 data_directory 完全匹配。

Debian/Ubuntu 默认将集群存储在 /var/lib/postgresql/[version]/[cluster]，数据目录路径易于确定。

/etc/pgbackrest/pgbackrest.conf 文件必须对数据库所有者（通常为 postgres）授予读取权限。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 PostgreSQL 集群数据目录

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo

pgBackRest 配置文件采用类 Windows INI 的格式。节（section）以方括号内的文本标识，键/值对包含在各节中。以 # 开头的行为注释，会被忽略，但不支持在值后的同一行添加行尾注释。不支持引号，键和值会自动去除首尾空白。若同一节出现多次，内容将被合并。

pgBackRest 配置文件支持多种加载方式：

  • config 和 config-include-path 均使用默认值：若存在则加载默认配置文件，若存在则追加默认配置包含路径中的 *.conf 文件。
  • 指定了 config 选项：仅加载指定的配置文件，且该文件必须存在。
  • 指定了 config-include-path：加载该路径中的所有 *.conf 文件（路径必须存在），同时加载默认配置文件（若存在）。若只想加载指定路径中的文件，可额外传入 --no-config 选项。
  • 同时指定了 config 和 config-include-path：使用用户指定的值，加载配置文件并追加包含路径中的 *.conf 文件，这些文件必须存在。
  • 指定了 config-path：此设置将覆盖配置文件默认位置的基路径和/或 config-include-path 的默认基路径，除非已显式设置 config 或 config-include-path。

所有配置文件会被拼接为一个整体，每个文件须各自有效。这意味着每个文件中需要为相应的键/值对声明所属节。节的顺序不影响最终结果，但存在基于节的优先级。优先级从高到低为：

  • [stanza:command]
  • [stanza]
  • [global:command]
  • [global]

注意：

--config、--config-include-path 和 --config-path 仅为命令行选项。

pgBackRest 也支持通过环境变量进行配置（见下方示例）；环境变量适用于 backup、restore 和 archive-push 等命令。

pg-primary ⇒ 使用环境变量配置 log-path

BASH
sudo -u postgres bash -c ' \
       export PGBACKREST_LOG_PATH=/path/set/by/env && \
       pgbackrest --log-level-console=error help backup log-path'

pgBackRest 2.59.0 - 'backup' command - 'log-path' option help

Path where log files are stored.

The log path provides a location for pgBackRest to store log files. Note that
if log-level-file=off then no log path is required.
TEXT
current: /path/set/by/env

default: /var/log/pgbackrest

创建仓库

仓库是 pgBackRest 存储备份和归档 WAL 段的位置。

提前准确估算所需空间并不容易。最好的做法是先执行几次备份，记录各类备份（full/incr/diff）的大小，并测量每天产生的 WAL 量，从而得出大致的空间需求——随着数据库的增长，这一需求也会随时间变化。

本演示中，仓库与 PostgreSQL 服务器存放在同一台主机上。这是最简单的配置，适合已用传统备份软件备份数据库主机的场景。

pg-primary ⇒ 创建 pgBackRest 仓库

BASH
sudo mkdir -p /var/lib/pgbackrest
sudo chmod 750 /var/lib/pgbackrest
sudo chown postgres:postgres /var/lib/pgbackrest

必须配置仓库路径，pgBackRest 才能找到它。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pgBackRest 仓库路径

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-path=/var/lib/pgbackrest

pgBackRest 也支持配置多个仓库，详见 多仓库 章节。

配置归档

备份正在运行的 PostgreSQL 集群需要启用 WAL 归档。其中 %p 是 PostgreSQL 传递待归档 WAL 段路径的方式。请注意，即使没有对集群进行显式写入，备份过程中也至少会生成一个 WAL 段。

pg-primary:/etc/postgresql/17/demo/postgresql.conf ⇒ 配置归档设置

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

完成上述配置修改后，必须重启 PostgreSQL 集群方可执行备份。

pg-primary ⇒ 重启演示集群

BASH
sudo pg_ctlcluster 17 demo restart

如果归档单个 WAL 段预计耗时超过 60 秒（默认超时），应适当增大 pgBackRest 的 archive-timeout 选项。注意，该选项与 PostgreSQL 的 archive_timeout 不同，后者用于强制切换 WAL 段，适合长时间处于非活跃状态的数据库。关于 PostgreSQL archive_timeout 的详细说明，请参阅 PostgreSQL 预写日志 文档。

archive-push 命令支持单独配置选项。例如，可以为其设置较低的压缩级别以加速归档，而不影响备份使用的压缩配置。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 archive-push 使用较低的压缩级别

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-path=/var/lib/pgbackrest
[global:archive-push]
compress-level=3

这种配置方式适用于任何命令，也可以针对特定 stanza，例如 demo:archive-push。

配置保留策略

pgBackRest 根据保留策略选项对备份执行到期清理操作。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置保留 2 个全量备份

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
[global:archive-push]
compress-level=3

有关保留策略的更多信息，请参阅 保留策略 章节。

配置仓库加密

本节将为仓库配置加密类型和密钥以演示加密功能。无论仓库类型（如 S3 或其他对象存储）本身是否支持加密，pgBackRest 的加密始终在客户端执行。

建议为密钥使用足够长的随机口令，可通过以下命令生成：openssl rand -base64 48。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pgBackRest 仓库加密

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
[global:archive-push]
compress-level=3

注意：

上面的加密设置放在 [global] 配置节中，以便 info 命令读取所有 stanza。未指定 stanza 选项时，info 只从 [global] 配置节读取加密设置；因此，按 stanza 配置加密时，必须为 info 指定 stanza 才能读取加密 stanza。

仓库配置完成、stanza 创建并检查通过后，仓库加密设置将无法再更改。

创建 Stanza

需要运行 stanza-create 命令来初始化 stanza。建议在 stanza-create 之后运行 check 命令，验证归档和备份配置是否正确。

pg-primary ⇒ 创建 stanza 并检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create
TEXT
P00   INFO: stanza-create command begin 2.59.0: --exec-id=415-78abd183 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo
P00   INFO: stanza-create for stanza 'demo' on repo1

P00   INFO: stanza-create command end: completed successfully

检查配置

check 命令用于验证 pgBackRest 和 archive_command 是否为指定 stanza 的归档和备份正确配置。它会检查运行该命令的主机上所有已配置的仓库和数据库，可发现配置错误——尤其是因所需 WAL 段未能到达归档而导致备份不完整的问题。该命令可在 PostgreSQL 主机或仓库主机上运行，也可在备库主机上运行，但由于备库无法执行 pg_switch_xlog()/pg_switch_wal()，在备库上仅能测试仓库配置。

注意：执行该命令时，pgBackRest 会调用 pg_create_restore_point('pgBackRest Archive Check') 和 pg_switch_xlog()/pg_switch_wal() 来强制 PostgreSQL 归档一个 WAL 段。

pg-primary ⇒ 检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=424-13bdd96c --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo
P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 000000010000000000000001 successfully archived to '/var/lib/pgbackrest/archive/demo/17-1/0000000100000000/000000010000000000000001-da969c4afd42c88e82d82b8072c86786941339bf.gz' on repo1

P00   INFO: check command end: completed successfully

性能调优

pgBackRest 提供了许多性能选项，为保持仓库的向后兼容性，这些选项默认未启用。但对于新建仓库，推荐开启以下选项。这些选项也可用于现有仓库，但请注意，开启后旧版本 pgBackRest 将无法读取该仓库，具体的兼容性边界取决于各功能的引入版本，详见下方列表。

  • compress-type — 控制 backup 和 archive-push 命令使用的压缩算法。默认为 gz（Gzip），推荐改用 zst（Zstandard），速度更快且压缩率与 gz 相当。zst 自 v2.27 起支持。详情请参阅 压缩类型。
  • repo-bundle — 备份时将小文件合并打包，节省空间并提升 backup 和 restore 速度，在 S3 等对象存储上效果尤为明显。repo-bundle 选项在 v2.39 中引入。详情请参阅 文件打包。
  • repo-block — 执行 diff/incr 备份时，仅存储文件中发生变化的数据块，而非整个文件，从而节省空间并提升备份速度。repo-block 选项在 v2.46 中引入，建议至少使用 v2.52.1。详情请参阅 块级增量备份。

还有一些性能选项因需要额外配置或默认值已足够安全（但未必最优）而默认未启用，这些选项在所有 v2 版本中均可用：

  • process-max — 控制命令使用的进程数，默认为 1，几乎在任何场景下都不是最优值。各命令对 process-max 的使用方式不同，请参阅对应命令的文档。
  • archive-async — 批量将 WAL 文件归档到仓库，大幅提升归档速度，默认未启用（需要创建缓冲区路径）。详情请参阅 异步归档。
  • backup-standby — 在备库而非主库上执行备份，降低主库负载，默认未启用（需要额外配置且依赖备库的存在）。详情请参阅 从备库备份。

执行备份

默认情况下，pgBackRest 会等待下一个定期检查点完成后再开始备份。根据 PostgreSQL 的 checkpoint_timeout 和 checkpoint_segments 设置，检查点可能需要较长时间，从而延迟备份启动。通常建议设置 start-fast=y，使备份立即开始——这会强制触发一次检查点，但由于备份通常每天只运行一次，额外的检查点对性能影响可以忽略不计。对于极其繁忙的集群，可以根据需要在命令行临时传入 --start-fast。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置备份快速启动

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

使用 backup 命令对 PostgreSQL 集群执行备份。

pg-primary ⇒ 备份演示集群

BASH
sudo -u postgres pgbackrest --stanza=demo \
       --log-level-console=info backup
TEXT
P00   INFO: backup command begin 2.59.0: --exec-id=451-8c17d67f --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-full=2 --stanza=demo --start-fast

P00   WARN: no prior backup exists, incr backup has been changed to full

P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 000000010000000000000002, lsn = 0/2000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 000000010000000000000002:000000010000000000000003
P00   INFO: new backup label = 20260720-005040F

P00   INFO: full backup size = 22MB, file total = 963

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=451-8c17d67f --log-level-console=info --no-log-timestamp --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-full=2 --stanza=demo

默认情况下，pgBackRest 会尝试执行增量备份。由于增量备份必须基于全量备份，而此时不存在全量备份，pgBackRest 自动改为执行全量备份。

可通过 type 选项指定备份类型为全量备份或差异备份。

pg-primary ⇒ 对演示集群执行差异备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=diff \
       --log-level-console=info backup
TEXT
       [filtered 7 lines of output]
P00   INFO: check archive for segment(s) 000000010000000000000004:000000010000000000000005
P00   INFO: new backup label = 20260720-005040F_20260720-005043D

P00   INFO: diff backup size = 8.3KB, file total = 963

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=478-06c17053 --log-level-console=info --no-log-timestamp --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-full=2 --stanza=demo

这次未出现警告，因为全量备份已存在。增量备份可以基于全量备份 或 差异备份，而差异备份只能基于全量备份。可通过 --type=full 选项执行全量备份。

在线备份期间，pgBackRest 会等待备份一致性所需的 WAL 段完成归档。等待超时由 archive-timeout 选项控制，默认为 60 秒。若已知归档单个 WAL 段需要更长时间，应适当增大该选项的值。

制定备份计划

可以使用 cron 等工具调度备份任务。

下面的示例配置了两个 cron 任务：每周日早上 6:30 执行全量备份，周一至周六早上 6:30 执行差异备份。若该 crontab 在周中首次安装，pgBackRest 会在差异任务首次执行时自动改为执行全量备份，次日再执行差异备份。

BASH
#m h   dom mon dow   command
30 06  *   *   0     pgbackrest --type=full --stanza=demo backup
30 06  *   *   1-6   pgbackrest --type=diff --stanza=demo backup

确定备份计划后，务必配置保留策略，以便定期清理过期备份，详见 保留策略。

备份信息

使用 info 命令获取备份信息。

pg-primary ⇒ 获取演示集群的信息

BASH
sudo -u postgres pgbackrest info
TEXT
stanza: demo
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (17): 000000010000000000000001/000000010000000000000005

        full backup: 20260720-005040F

            timestamp start/stop: 2026-07-20 00:50:40+00 / 2026-07-20 00:50:42+00
            wal start/stop: 000000010000000000000002 / 000000010000000000000003
            database size: 22MB, database backup size: 22MB
            repo1: backup set size: 2.9MB, backup size: 2.9MB

        diff backup: 20260720-005040F_20260720-005043D

            timestamp start/stop: 2026-07-20 00:50:43+00 / 2026-07-20 00:50:44+00
            wal start/stop: 000000010000000000000004 / 000000010000000000000005
            database size: 22MB, database backup size: 8.3KB
            repo1: backup set size: 2.9MB, backup size: 464B
            backup reference total: 1 full

info 命令可操作单个 stanza 或所有 stanza。默认为文本格式，以人类可读的摘要展示所请求 stanza 的备份信息，此格式可能随版本变化。

如需机器可读的输出，请使用 --output=json。JSON 输出比文本格式包含更多信息，在无 bug 的情况下格式保持稳定。

如需加快执行速度，可指定 --detail-level=progress，将输出限制为仅进度信息，但注意这会跳过除 stanza 可用性以外的所有检查。

输出中每个 stanza 对应一个独立区块，可通过 --stanza 选项限制仅显示指定 stanza。status 字段简要描述 stanza 的健康状态：ok 表示正常；若有多个仓库，mixed 表示 stanza 在一个或多个仓库上存在问题，此时会按仓库逐一列出详细状态；对于不属于已知错误码的仓库错误，将使用 other 错误码并附上完整错误信息。wal archive min/max 显示归档中当前存储的最小和最大 WAL，有多个仓库时跨所有仓库汇总报告（可通过 --repo 选项限制到特定仓库）。注意，由于归档保留策略或其他原因，WAL 序列中可能存在间隙。

若当前主机上有备份/过期或恢复操作正在运行，status 信息旁会出现 backup/expire running 和/或 restore running 提示。文本输出还会报告各仓库的进度，JSON 输出中则会包含 repo 数组。

备份按从旧到新的顺序排列。最旧的备份 始终 是全量备份（标签末尾带 F），最新的备份可以是全量备份、差异备份（末尾带 D）或增量备份（末尾带 I）。

timestamp start/stop 定义了备份的运行时间范围，timestamp stop 可用于确定时间点恢复所选用的备份。详见 时间点恢复 章节。

wal start/stop 定义了恢复时使数据库达到一致状态所需的 WAL 范围，backup 命令会确保该范围内的 WAL 在备份完成前已归档。

database size 是数据库的完整未压缩大小，database backup size 是本次实际备份的数据量（全量备份时两者相同）。

repo 标识此备份所在的仓库。backup set size 包含恢复该备份所需的本备份及所有引用备份的全部文件，backup size 则仅包含本次备份的文件（全量备份时两者相同）。若启用了压缩，仓库大小反映的是压缩后的文件大小。

backup reference total 汇总了恢复此备份所依赖的其他备份。使用 --set 选项可显示完整的引用列表。

恢复备份

备份可以防范多种灾难场景，最常见的是硬件故障和数据损坏。模拟数据损坏最简单的方法是删除一个关键的 PostgreSQL 集群文件。

pg-primary ⇒ 停止演示集群并删除 pg_control 文件

BASH
sudo pg_ctlcluster 17 demo stop
sudo -u postgres rm /var/lib/postgresql/17/demo/global/pg_control

缺少该关键文件时，启动集群将报错。

pg-primary ⇒ 尝试启动已损坏的演示集群

BASH
sudo pg_ctlcluster 17 demo start
TEXT
Error: /usr/lib/postgresql/17/bin/pg_ctl /usr/lib/postgresql/17/bin/pg_ctl start -D /var/lib/postgresql/17/demo -l /var/log/postgresql/postgresql-17-demo.log -s -o  -c config_file="/etc/postgresql/17/demo/postgresql.conf"  exited with status 1:

postgres: could not find the database system

Expected to find it in the directory "/var/lib/postgresql/17/demo",
but could not open file "/var/lib/postgresql/17/demo/global/pg_control": No such file or directory
Examine the log output.

使用 restore 命令恢复 PostgreSQL 集群备份。执行前集群必须处于停止状态（本例中已停止），并且需要清空 PostgreSQL 数据目录中的所有文件。

pg-primary ⇒ 从演示集群中删除旧文件

BASH
sudo -u postgres find /var/lib/postgresql/17/demo -mindepth 1 -delete

pg-primary ⇒ 恢复演示集群并启动 PostgreSQL

BASH
sudo -u postgres pgbackrest --stanza=demo restore
sudo pg_ctlcluster 17 demo start

这次集群成功启动，因为恢复操作已补全缺失的 pg_control 文件。

有关 restore 命令的更多信息，请参阅 恢复 章节。

监控

监控是任何生产系统不可或缺的组成部分。市面上有许多可用的监控工具，稍加处理即可将 pgBackRest 纳入其中。

pgBackRest 支持以 JSON 格式输出仓库信息，包含每个 stanza 的完整备份列表和 WAL 归档信息。

在 PostgreSQL 中

PostgreSQL 的 COPY 命令可将 pgBackRest 信息加载到表中。以下示例将该逻辑封装为一个函数，供实时查询使用。

pg-primary ⇒ 为 PostgreSQL 加载 pgBackRest info 函数

BASH
sudo -u postgres cat \
       /var/lib/postgresql/pgbackrest/doc/example/pgsql-pgbackrest-info.sql
SQL
-- 在 PostgreSQL 内部监控 pgBackRest 的示例
--
-- 使用 copy 命令将 pgBackRest info 命令的输出导出为 jsonb 类型，
-- 以便 PostgreSQL 直接查询。

-- 创建 monitor schema
create schema monitor;

-- 以 JSON 格式获取 pgBackRest info
create function monitor.pgbackrest_info()
    returns jsonb AS $$
declare
    data jsonb;
begin
    -- 创建临时表以存储 JSON 数据
    create temp table temp_pgbackrest_data (data text);

    -- 直接从 pgBackRest info 命令将数据写入临时表
    copy temp_pgbackrest_data (data)
        from program
            'pgbackrest --output=json info' (format text);

    select replace(temp_pgbackrest_data.data, E'\n', '\n')::jsonb
      into data
      from temp_pgbackrest_data;

    drop table temp_pgbackrest_data;

    return data;
end $$ language plpgsql;
BASH
sudo -u postgres psql -f \
       /var/lib/postgresql/pgbackrest/doc/example/pgsql-pgbackrest-info.sql

现在可以使用 monitor.pgbackrest_info() 函数查询指定 stanza 的上次成功备份时间和已归档的 WAL。

pg-primary ⇒ 查询上次成功备份时间和归档的 WAL

BASH
sudo -u postgres cat \
       /var/lib/postgresql/pgbackrest/doc/example/pgsql-pgbackrest-query.sql
SQL
-- 获取每个 stanza 的最近一次成功备份时间
--
-- 依赖 monitor.pgbackrest_info 函数。
with stanza as
(
    select data->'name' as name,
           data->'backup'->(
               jsonb_array_length(data->'backup') - 1) as last_backup,
           data->'archive'->(
               jsonb_array_length(data->'archive') - 1) as current_archive
      from jsonb_array_elements(monitor.pgbackrest_info()) as data
)
select name,
       to_timestamp(
           (last_backup->'timestamp'->>'stop')::numeric) as last_successful_backup,
       current_archive->>'max' as last_archived_wal
  from stanza;
BASH
sudo -u postgres psql -f \
       /var/lib/postgresql/pgbackrest/doc/example/pgsql-pgbackrest-query.sql
TEXT
  name  | last_successful_backup |    last_archived_wal
--------+------------------------+--------------------------
 "demo" | 2026-07-20 00:50:44+00 | 000000010000000000000005
(1 row)

使用 jq

jq 是一款命令行工具，可方便地从 JSON 中提取数据。

pg-primary ⇒ 安装 jq 工具

BASH
sudo apt-get install jq

现在可以使用 jq 查询指定 stanza 的上次成功备份时间。

pg-primary ⇒ 查询上次成功备份时间

BASH
sudo -u postgres pgbackrest --output=json --stanza=demo info | \
       jq '.[0] | .backup[-1] | .timestamp.stop'
TEXT
1784508644

或查询最后归档的 WAL。

pg-primary ⇒ 查询最后归档的 WAL

BASH
sudo -u postgres pgbackrest --output=json --stanza=demo info | \
       jq '.[0] | .archive[-1] | .max'
TEXT
"000000010000000000000005"

注意：

此语法需要 jq v1.5 及以上版本。

注意：

jq 可能会对系统标识符等大整数进行四舍五入，请仔细测试你的查询。

备份

配置了多个仓库时，pgBackRest 默认备份到最高优先级的仓库（如 repo1），可通过 --repo 选项指定目标仓库。

pgBackRest 没有内置调度器，建议通过 cron 或其他调度机制运行备份任务。

详情与示例请参阅 执行备份。

文件打包

将仓库中的文件打包在一起可以节省备份时间和仓库空间，在对象存储（如 S3）或大块大小的文件系统上尤为明显。对象存储的每个文件创建开销较高，非常小的文件与较大文件的存储成本相差无几。

文件打包功能通过 repo-bundle 选项启用。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-bundle

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

不使用文件打包时，全量备份路径下通常有 1000 多个文件；启用打包后文件总数大幅减少。另一个好处是，零长度文件不再单独存储（仅记录在清单文件（manifest）中），而普通备份中每个零长度文件都会占用独立存储条目。

pg-primary ⇒ 执行全量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=full backup

pg-primary ⇒ 检查文件总数

BASH
sudo -u postgres find /var/lib/pgbackrest/backup/demo/latest/ -type f | wc -l
TEXT
5

repo-bundle-size 和 repo-bundle-limit 选项可用于调优，大多数情况下默认值即为最优。

文件打包虽然通常更高效，但也有一些不足：手动从仓库检索文件变得更加困难；对于去重存储，由于每次全量备份中文件在包内的排列方式不同，去重效果可能不理想；此外，文件包不支持断点续传，因此不应将 repo-bundle-limit 设置过高。

块级增量备份

块级增量备份仅存储文件中自上次备份以来发生变化的数据块，而非整个文件，从而节省存储空间。

块级增量备份通过 repo-block 选项启用，对所有备份类型均启用时效果最佳，且必须同时启用文件打包功能。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-block

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

备份注解

用户可以为备份附加键/值形式的注解信息，该选项可多次使用以添加多个注解。

pg-primary ⇒ 执行带注解的全量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --annotation=source="demo backup" \
       --annotation=key=value --type=full backup

通过 --set 指定备份时，info 命令的文本输出会显示注解；JSON 格式输出中始终包含注解信息。

pg-primary ⇒ 获取演示集群的信息

BASH
sudo -u postgres pgbackrest --stanza=demo --set=20260720-005100F info
TEXT
stanza: demo
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (17): 000000020000000000000007/000000020000000000000009

        full backup: 20260720-005100F
            timestamp start/stop: 2026-07-20 00:51:00+00 / 2026-07-20 00:51:02+00
            wal start/stop: 000000020000000000000008 / 000000020000000000000009
            lsn start/stop: 0/8000028 / 0/9000050
            database size: 22MB, database backup size: 22MB
            repo1: backup size: 2.9MB
            database list: postgres (5)

            annotation(s)

                key: value
                source: demo backup

备份时通过 backup 命令添加的注解，可在事后使用 annotate 命令进行添加、修改或删除。

pg-primary ⇒ 修改备份注解

BASH
sudo -u postgres pgbackrest --stanza=demo --set=20260720-005100F \
       --annotation=key= --annotation=new_key=new_value annotate

sudo -u postgres pgbackrest --stanza=demo --set=20260720-005100F info
TEXT
stanza: demo
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (17): 000000020000000000000007/000000020000000000000009

        full backup: 20260720-005100F
            timestamp start/stop: 2026-07-20 00:51:00+00 / 2026-07-20 00:51:02+00
            wal start/stop: 000000020000000000000008 / 000000020000000000000009
            lsn start/stop: 0/8000028 / 0/9000050
            database size: 22MB, database backup size: 22MB
            repo1: backup size: 2.9MB
            database list: postgres (5)

            annotation(s)

                new_key: new_value
                source: demo backup

保留策略

一般来说，保留尽可能多的备份可以扩大 时间点恢复 窗口，但也必须兼顾磁盘空间等实际限制。保留策略选项负责在旧备份不再需要时将其删除。

pgBackRest 根据保留策略类型（数量或时间段）对全量备份进行轮转。按数量时，过期逻辑只关注应保留多少个，而不关心备份的创建时间。差异备份按数量管理，但当依赖的全量备份过期时，差异备份也随之过期。增量备份不会被保留策略单独过期——始终随其关联的全量备份或差异备份一起过期。详情与示例请参见 全量备份保留策略 和 差异备份保留策略 章节。

归档的 WAL 默认随未过期的备份一起保留；如有特殊需求，可通过各仓库的 retention-archive 选项调整（不推荐）。详情与示例请参见 归档保留策略 章节。

expire 命令在每次备份成功后自动运行，也可手动触发。手动运行时，过期操作按各已配置仓库的保留策略执行；若指定了 --repo 选项，则仅对该仓库执行。还可通过 --set 选项将过期操作限定在特定备份集上——若未同时指定 --repo，则会搜索所有仓库并对匹配的备份集执行过期。注意，每次运行 expire 命令都会检查并执行归档保留计划。

全量备份保留策略

repo1-retention-full-type 决定 repo1-retention-full 的解释方式：可以是保留的全量备份数量，也可以是保留全量备份的天数。过期操作只在新备份完成后触发——若 repo1-retention-full-type=count 且 repo1-retention-full=2，则需要存储第三个全量备份时才会过期最旧的一个；若 repo1-retention-full-type=time 且 repo1-retention-full=20，则至少要有一个全量备份已经超过 20 天才会触发过期。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-retention-full

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

目前已配置 repo1-retention-full=2，但当前只有一个全量备份，因此下次执行全量备份时不会触发任何过期操作。

pg-primary ⇒ 执行全量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=full \
       --log-level-console=detail backup
TEXT
       [filtered 975 lines of output]
P00   INFO: repo1: remove expired backup 20260720-005057F
P00 DETAIL: repo1: 17-1 archive retention on backup 20260720-005100F, start = 000000020000000000000008

P00   INFO: repo1: 17-1 remove archive, start = 000000020000000000000007, stop = 000000020000000000000007

P00   INFO: expire command end: completed successfully

归档 确实 被过期了，因为这些 WAL 段是在最旧备份之前生成的，对恢复没有意义——只有备份开始之后生成的 WAL 段才能用于该备份的恢复。

pg-primary ⇒ 执行全量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=full \
       --log-level-console=info backup
TEXT
       [filtered 11 lines of output]
P00   INFO: repo1: expire full backup 20260720-005100F
P00   INFO: repo1: remove expired backup 20260720-005100F

P00   INFO: repo1: 17-1 remove archive, start = 000000020000000000000008, stop = 00000002000000000000000A

P00   INFO: expire command end: completed successfully

全量备份 20260720-005040F 已被过期，归档保留策略现在以 20260720-005103F 为基准——该备份是当前最旧的全量备份。

差异备份保留策略

将 repo1-retention-diff 设置为需要保留的差异备份数量。由于差异备份只依赖于前一次全量备份，可以维护一个最近数天的"滚动"差异备份集合，既能快速恢复到近期某个时间点，又能降低整体空间占用。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-retention-diff

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=1
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

已配置 repo1-retention-diff=1，因此需要执行第二次差异备份时才会过期第一个。下面再添加一个增量备份，以演示增量备份的过期逻辑——本例中，增量备份的过期依赖于所属差异备份的过期。

pg-primary ⇒ 执行差异备份和增量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=diff backup
sudo -u postgres pgbackrest --stanza=demo --type=incr backup

现在执行一次差异备份，将过期之前的差异备份和增量备份，只保留最新的一个差异备份。

pg-primary ⇒ 执行差异备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=diff \
       --log-level-console=info backup
TEXT
       [filtered 10 lines of output]
P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=952-88e66707 --log-level-console=info --no-log-timestamp --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-diff=1 --repo1-retention-full=2 --stanza=demo

P00   INFO: repo1: expire diff backup set 20260720-005106F_20260720-005108D, 20260720-005106F_20260720-005109I

P00   INFO: repo1: remove expired backup 20260720-005106F_20260720-005109I
P00   INFO: repo1: remove expired backup 20260720-005106F_20260720-005108D
P00   INFO: expire command end: completed successfully

归档保留策略

pgBackRest 在过期备份时会自动删除对应的归档 WAL 段（默认根据 repo1-retention-full 过期全量备份对应的 WAL），但有时可能需要更激进地清理归档以节省磁盘空间。注意，在差异归档保留策略中，全量备份被视为差异备份处理。

过期归档时，维持备份一致性所必需的 WAL 段永远不会被删除。但由于 PITR 只能在连续的 WAL 流上进行，在正常备份过期流程之外激进地清理归档时需格外谨慎。若要在不实际执行过期操作的情况下预览将被清理的内容，可在 expire 命令中传入 --dry-run 选项。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-retention-diff

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

pg-primary ⇒ 执行差异备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=diff \
       --log-level-console=info backup
TEXT
       [filtered 6 lines of output]
P00   INFO: backup stop archive = 000000020000000000000017, lsn = 0/17000050
P00   INFO: check archive for segment(s) 000000020000000000000016:000000020000000000000017

P00   INFO: new backup label = 20260720-005106F_20260720-005112D

P00   INFO: diff backup size = 8.3KB, file total = 963
P00   INFO: backup command end: completed successfully
       [filtered 2 lines of output]

pg-primary ⇒ 过期归档

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=detail \
       --repo1-retention-archive-type=diff --repo1-retention-archive=1 expire
TEXT
P00   INFO: expire command begin 2.59.0: --exec-id=1034-c8a8377e --log-level-console=detail --no-log-timestamp --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-archive=1 --repo1-retention-archive-type=diff --repo1-retention-diff=2 --repo1-retention-full=2 --stanza=demo
P00 DETAIL: repo1: 17-1 archive retention on backup 20260720-005103F, start = 00000002000000000000000B, stop = 00000002000000000000000B
P00 DETAIL: repo1: 17-1 archive retention on backup 20260720-005106F, start = 00000002000000000000000C, stop = 00000002000000000000000D

P00 DETAIL: repo1: 17-1 archive retention on backup 20260720-005106F_20260720-005110D, start = 000000020000000000000012, stop = 000000020000000000000013

P00 DETAIL: repo1: 17-1 archive retention on backup 20260720-005106F_20260720-005112D, start = 000000020000000000000016

P00   INFO: repo1: 17-1 remove archive, start = 00000002000000000000000E, stop = 000000020000000000000011
P00   INFO: repo1: 17-1 remove archive, start = 000000020000000000000014, stop = 000000020000000000000015

P00   INFO: expire command end: completed successfully

差异备份 20260720-005106F_20260720-005110D 保留了部分 WAL 段，即使这些 WAL 段无法用于更早备份的 PITR 向前回放，也必须保留以确保旧备份的一致性。20260720-005106F_20260720-005110D 之后、20260720-005106F_20260720-005112D 之前生成的 WAL 段已被删除。最新备份 20260720-005106F_20260720-005112D 之后生成的 WAL 段仍然保留，可用于 PITR。

由于差异归档保留策略中全量备份被视为差异备份，若以相同设置执行一次全量备份，则只保留该全量备份对应的归档用于 PITR。

恢复

restore 命令默认从第一个存在备份的仓库中自动选取最新备份（参见 快速开始 - 恢复备份）。检查仓库的顺序由 pgbackrest.conf 决定（如 repo1 先于 repo2 被检查）。若要从特定仓库选取备份，可传入 --repo 选项（如 --repo=1）；若需选取非最新的备份，可传入 --set 选项。

当 PITR 类型为 --type=time 或 --type=lsn 时，必须通过 --target 选项指定目标时间或 lsn。若未通过 --set 指定备份，pgBackRest 会按顺序检查各已配置仓库，寻找包含所请求时间或 lsn 的备份。若未找到匹配备份，--type=time 会使用第一个有备份的仓库中的最新备份，而 --type=lsn 则不会选取任何备份。对于其他 PITR 类型（如 xid），若目标在最新备份之前，则必须提供 --set 选项。详情与示例请参见 时间点恢复。

按照 PostgreSQL 的建议，复制槽不包含在备份中。详情请参阅 PostgreSQL 文档的 备份数据目录 章节。

以下各节介绍 restore 命令的更多功能。

文件所有权

以非 root 用户运行 restore（典型场景）时，所有恢复的文件都将归执行 pgBackRest 的用户/组所有。若现有文件不属于该用户/组，且无法更新所有权，则会报错——此时需要由特权用户先修正文件所有权，再重试恢复。

以 root 用户运行 restore 时，pgBackRest 会尝试按照备份清单文件（manifest）中记录的所有权来恢复文件归属。清单中只存储用户/组的 名称，因此恢复主机上必须存在同名的用户/组。若本地找不到对应名称，则使用 PostgreSQL 数据目录的用户/组；若数据目录的用户/组也无法映射到名称，则最终回退为 root。

Delta 选项

快速开始 中的 恢复备份 章节要求在执行 restore 前先清空数据库集群目录。delta 选项允许 pgBackRest 自动判断哪些文件可以保留、哪些需要从备份中恢复——同时 删除 不在备份清单中的文件，从而清除差异变更。该功能通过计算集群目录中每个文件的 SHA-1 哈希来实现，若哈希与备份中存储的不匹配，则恢复该文件。与 process-max 选项结合使用时效率极高。恢复期间 PostgreSQL 服务器已关闭，因此可以使用比备份时更多的并行进程。

pg-primary ⇒ 停止 demo 集群，执行 delta 恢复

BASH
sudo pg_ctlcluster 17 demo stop
sudo -u postgres pgbackrest --stanza=demo --delta \
       --log-level-console=detail restore
TEXT
       [filtered 2 lines of output]
P00 DETAIL: check '/var/lib/postgresql/17/demo' exists
P00 DETAIL: remove 'global/pg_control' so cluster will not start if restore does not complete

P00   INFO: remove invalid files/links/paths from '/var/lib/postgresql/17/demo'

P00 DETAIL: remove invalid file '/var/lib/postgresql/17/demo/backup_label.old'
P00 DETAIL: remove invalid file '/var/lib/postgresql/17/demo/base/1/pg_internal.init'
       [filtered 129 lines of output]
P01 DETAIL: restore file /var/lib/postgresql/17/demo/base/1/113 - exists and matches backup (bundle 20260720-005106F/1/58072, 8KB, 5.76%) checksum 1cd643347b87a472ff001ae124e4b532ce998d2f
P01 DETAIL: restore file /var/lib/postgresql/17/demo/base/1/112 - exists and matches backup (bundle 20260720-005106F/1/58160, 8KB, 5.79%) checksum 2cbd5cf8fb22ef627eb539776c5ec7457bdb2890

P01 DETAIL: restore file /var/lib/postgresql/17/demo/PG_VERSION - exists and matches backup (bundle 20260720-005106F/1/58248, 3B, 5.79%) checksum ad48103e4fc71796e9708cafc43adeed0d1076b7

P01 DETAIL: restore file /var/lib/postgresql/17/demo/global/6303 - exists and matches backup (bundle 20260720-005106F/1/58272, 16KB, 5.86%) checksum f5bab995185b4b5cc2a02777c157dff2937879bf
P01 DETAIL: restore file /var/lib/postgresql/17/demo/global/6302 - exists and matches backup (bundle 20260720-005106F/1/58480, 16KB, 5.94%) checksum eb54339bce7ce3a899043e950ba88034d2450218
       [filtered 873 lines of output]

pg-primary ⇒ 重启 PostgreSQL

BASH
sudo pg_ctlcluster 17 demo start

选择性数据库恢复

某些情况下，可能只需要从集群备份中恢复特定数据库——出于性能考虑，或是将选定数据库迁移到磁盘空间不足以恢复整个集群的机器上。

为演示此功能，先创建两个数据库：test1 和 test2。

pg-primary ⇒ 创建两个测试数据库

BASH
sudo -u postgres psql -c "create database test1;"
SQL
CREATE DATABASE
BASH
sudo -u postgres psql -c "create database test2;"
SQL
CREATE DATABASE

向每个测试数据库填充表和数据，以便演示选择性恢复的效果。

pg-primary ⇒ 在每个数据库中创建测试表

BASH
sudo -u postgres psql -c "create table test1_table (id int); \
       insert into test1_table (id) values (1);" test1
SQL
CREATE TABLE
INSERT 0 1
BASH
sudo -u postgres psql -c "create table test2_table (id int); \
       insert into test2_table (id) values (2);" test2
SQL
CREATE TABLE
INSERT 0 1

执行一次新备份，让 pgBackRest 感知到新建的数据库。

pg-primary ⇒ 执行备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=incr backup

使用选择性恢复的主要原因之一是节省空间。先记录 test1 数据库当前的磁盘占用，以便与选择性恢复后进行对比。

pg-primary ⇒ 查看 test1 数据库占用的空间

BASH
sudo -u postgres du -sh /var/lib/postgresql/17/demo/base/32768
TEXT
7.4M	/var/lib/postgresql/17/demo/base/32768

若不清楚要恢复的数据库名称，可使用 info 命令的 --set 选项查看该备份集包含的数据库列表。

pg-primary ⇒ 查看备份的数据库列表

BASH
sudo -u postgres pgbackrest --stanza=demo \
       --set=20260720-005106F_20260720-005120I info
TEXT
       [filtered 12 lines of output]
            repo1: backup size: 1.9MB
            backup reference list: 20260720-005106F, 20260720-005106F_20260720-005112D

            database list: postgres (5), test1 (32768), test2 (32769)

停止集群，仅恢复 test2 数据库。内置数据库（template0、template1 和 postgres）始终会被恢复。

警告：

除非指定 --type=immediate，否则恢复可能会报错。原因是在达到一致性点之后，PostgreSQL 会将清零页标记为错误，即使是完整页写入也不例外。对于 PostgreSQL 13 及以上版本，可通过 ignore_invalid_pages 参数忽略无效页面。此时恢复完成后务必检查日志，确认所选数据库中没有无效页面的报告。

pg-primary ⇒ 从最新备份恢复，仅包含 test2 数据库

BASH
sudo pg_ctlcluster 17 demo stop
sudo -u postgres pgbackrest --stanza=demo --delta \
       --db-include=test2 --type=immediate --target-action=promote restore

sudo pg_ctlcluster 17 demo start

恢复完成后，test2 数据库将包含之前创建的所有表和数据，可正常访问。

pg-primary ⇒ 验证 test2 数据库已成功恢复

BASH
sudo -u postgres psql -c "select * from test2_table;" test2
TEXT
 id
----
  2
(1 row)

test1 数据库虽然恢复成功，但无法访问。这是因为该数据库以稀疏清零文件的形式恢复——PostgreSQL 可以在清零文件上成功应用 WAL，但整个数据库并不有效，关键文件中不含任何实际数据。这是有意为之的设计，目的是防止在数据库可能包含 WAL 回放期间写入的部分数据时被意外访问。

pg-primary ⇒ 尝试连接 test1 数据库将产生错误

BASH
sudo -u postgres psql -c "select * from test1_table;" test1
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL:  relation mapping file "base/32768/pg_filenode.map" contains invalid data

由于 test1 以稀疏清零文件恢复，其占用空间仅相当于恢复期间写入的 WAL 量。备份期间生成并在恢复期间应用的 WAL 可能相当可观，但通常只是数据库总大小的一小部分——对于大型数据库而言尤为明显，这正是选择性恢复最有价值的场景。

可以看到，选择性恢复后 test1 的磁盘占用远小于完整恢复时的大小。

pg-primary ⇒ 查看恢复后 test1 数据库占用的空间

BASH
sudo -u postgres du -sh /var/lib/postgresql/17/demo/base/32768
TEXT
8.0K	/var/lib/postgresql/17/demo/base/32768

此时对无效的 test1 数据库唯一可执行的操作是 drop database。pgBackRest 不会自动删除该数据库，因为这一操作必须在恢复完成、集群可访问之后才能进行。

pg-primary ⇒ 删除 test1 数据库

BASH
sudo -u postgres psql -c "drop database test1;"
SQL
DROP DATABASE

删除无效的 test1 后，只剩下 test2 和内置数据库。

pg-primary ⇒ 列出剩余数据库

BASH
sudo -u postgres psql -c "select oid, datname from pg_database order by oid;"
TEXT
  oid  |  datname
-------+-----------
     1 | template1
     4 | template0
     5 | postgres

 32769 | test2

(4 rows)

时间点恢复

快速开始 中的 恢复备份 执行的是默认恢复，即将 WAL 一路回放至末尾。对于硬件故障，这通常是最佳选择；但对于数据损坏场景（无论是机器原因还是人为误操作），PITR 往往更为合适。

PITR 允许将 WAL 回放至指定的 lsn、时间戳、事务 ID 或恢复点。在常见恢复场景中，基于时间的恢复最为实用。典型场景是恢复意外删除的表或数据——下面以恢复被删除的表为例进行演示，被删除的数据可以用完全相同的方式恢复。

pg-primary ⇒ 创建一张存有重要数据的表

BASH
sudo -u postgres psql -c "begin; \
       create table important_table (message text); \
       insert into important_table values ('Important Data'); \
       commit; \
       select * from important_table;"
TEXT
       [filtered 4 lines of output]
    message
----------------

 Important Data

(1 row)

记录时间时应以 PostgreSQL 返回的时间为准，且必须包含时区偏移量。这样可以避免时区转换导致意外的恢复结果。

pg-primary ⇒ 从 PostgreSQL 获取当前时间

BASH
sudo -u postgres psql -Atc "select current_timestamp"
TEXT
2026-07-20 00:51:32.323409+00

记录时间后，删除该表。实际场景中，找到表被删除的确切时间远比此示例困难——可能无法精确定位，但通过一些排查工作通常能接近实际时间。

pg-primary ⇒ 删除重要表

BASH
sudo -u postgres psql -c "begin; \
       drop table important_table; \
       commit; \
       select * from important_table;"
SQL
BEGIN
DROP TABLE
TEXT
COMMITERROR:  relation "important_table" does not exist

LINE 1: ...le important_table;     commit;     select * from important_...
                                                             ^

若选择了错误的备份进行恢复，则无法恢复到所需的时间目标。为演示这一点，在 important_table 不存在的情况下执行一次新的增量备份。

pg-primary ⇒ 执行增量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=incr backup
sudo -u postgres pgbackrest info
TEXT
       [filtered 38 lines of output]
            backup reference total: 1 full, 1 diff

        incr backup: 20260720-005106F_20260720-005133I

            timestamp start/stop: 2026-07-20 00:51:33+00 / 2026-07-20 00:51:35+00
            wal start/stop: 00000004000000000000001A / 00000004000000000000001A
       [filtered 2 lines of output]

由于 PostgreSQL 只能向前回放 WAL，无法向后回放，因此无法从这个备份中恢复已删除的表。

pg-primary ⇒ 尝试从错误的备份中恢复

BASH
sudo pg_ctlcluster 17 demo stop
sudo -u postgres pgbackrest --stanza=demo --delta \
       --set=20260720-005106F_20260720-005133I --target-timeline=current \
       --type=time "--target=2026-07-20 00:51:32.323409+00" --target-action=promote restore

sudo pg_ctlcluster 17 demo start
TEXT
       [filtered 13 lines of output]
LOG:  database system is ready to accept read-only connections
LOG:  redo done at 0/1A000120 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.03 s

FATAL:  recovery ended before configured recovery target was reached

LOG:  startup process (PID 1434) exited with exit code 1
LOG:  terminating any other active server processes
       [filtered 3 lines of output]

一种可靠的方法是让 pgBackRest 自动选择能够恢复到目标时间的备份，即在指定时间之前完成的备份。

注意：

当恢复类型为 xid 或 name 时，pgBackRest 无法自动选择备份，必须手动指定。

pg-primary ⇒ 将 demo 集群恢复至 2026-07-20 00:51:32.323409+00

BASH
sudo -u postgres pgbackrest --stanza=demo --delta \
       --type=time "--target=2026-07-20 00:51:32.323409+00" \
       --target-action=promote restore

sudo -u postgres cat /var/lib/postgresql/17/demo/postgresql.auto.conf
TEXT
       [filtered 9 lines of output]
# Recovery settings generated by pgBackRest restore on 2026-07-20 00:51:38
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'
INI
recovery_target_time = '2026-07-20 00:51:32.323409+00'
recovery_target_action = 'promote'

pgBackRest 已将恢复配置写入 postgresql.auto.conf，PostgreSQL 可以直接启动恢复。其中 %f 是 PostgreSQL 传递所需 WAL 段名称的方式，%p 是该段的目标路径。恢复完成后，被删除的表将重新存在，可以正常查询。

pg-primary ⇒ 启动 PostgreSQL 并验证重要表是否存在

BASH
sudo pg_ctlcluster 17 demo start
sudo -u postgres psql -c "select * from important_table"
TEXT
    message
----------------

 Important Data

(1 row)

PostgreSQL 日志中也包含有价值的信息，记录了恢复停止的时间和事务，以及最后一个被应用事务的时间。

pg-primary ⇒ 查看 PostgreSQL 日志输出

BASH
sudo -u postgres cat /var/log/postgresql/postgresql-17-demo.log
TEXT
       [filtered 7 lines of output]
LOG:  restored log file "00000004.history" from archive
LOG:  restored log file "000000040000000000000019" from archive
LOG:  starting point-in-time recovery to 2026-07-20 00:51:32.323409+00
LOG:  restored log file "00000003.history" from archive
LOG:  redo starts at 0/19000028
       [filtered 2 lines of output]
LOG:  database system is ready to accept read-only connections
LOG:  restored log file "00000004000000000000001A" from archive
LOG:  recovery stopping before commit of transaction 748, time 2026-07-20 00:51:33.723321+00
LOG:  redo done at 0/1901CC00 system usage: CPU: user: 0.00 s, system: 0.02 s, elapsed: 0.10 s
LOG:  last completed transaction was at log time 2026-07-20 00:51:30.931579+00
LOG:  restored log file "000000040000000000000019" from archive
LOG:  selected new timeline ID: 5
       [filtered 5 lines of output]

删除 Stanza

stanza-delete 命令用于删除仓库中与某个 stanza 关联的所有数据。

警告：

请谨慎使用此命令——它将永久删除 pgBackRest 仓库中指定 stanza 的所有备份和归档。

删除 stanza 的步骤如下：

  • 关闭与该 stanza 关联的 PostgreSQL 集群（或使用 --force 强制跳过此检查）。
  • 在将要执行 stanza-delete 的主机上先运行 stop 命令。
  • 运行 stanza-delete 命令。

命令成功完成后，用户需自行从所有 pgBackRest 配置文件和/或环境变量中删除该 stanza 的相关配置。

每次只能从一个仓库中删除 stanza。若要从多个仓库中删除，需指定 --repo 选项，对每个仓库分别执行 stanza-delete。

pg-primary ⇒ 停止待删除的 PostgreSQL 集群

BASH
sudo pg_ctlcluster 17 demo stop

pg-primary ⇒ 停止该 stanza 的 pgBackRest

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stop
TEXT
P00   INFO: stop command begin 2.59.0: --exec-id=1563-7c6f409e --log-level-console=info --no-log-timestamp --stanza=demo

P00   INFO: stop command end: completed successfully

pg-primary ⇒ 从一个仓库中删除 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=1 \
       --log-level-console=info stanza-delete
TEXT
P00   INFO: stanza-delete command begin 2.59.0: --exec-id=1571-372cc4e9 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo=1 --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo

P00   INFO: stanza-delete command end: completed successfully

多仓库

如 S3 兼容对象存储支持 所示，pgBackRest 支持配置多个仓库。这样做的潜在优势在于：可以同时拥有一个用于快速恢复的本地仓库和一个用于冗余的远程仓库。

某些命令（如 stanza-create 和 stanza-upgrade）会自动作用于所有已配置的仓库，而另一些命令（如 stanza-delete）则需要通过 --repo 选项指定仓库。

注意，当仅配置了 repo1 时，--repo 选项不是必需的——这是为了保持向后兼容。但若单个仓库被配置为 repo2 等非默认索引，则必须指定 --repo，以防后续新增仓库时命令行为发生变化。

archive-push 命令始终将 WAL 推送到所有已配置仓库的归档。当某个仓库不可达时，WAL 仍会被推送到其他可达的仓库。但要使此功能有效运作，必须启用 archive-async=y；否则，其他仓库相比不可达的仓库也只能多归档一个 WAL 段。此外，若 WAL 无法推送到任何仓库，PostgreSQL 不会将其从 pg_wal 目录中删除，可能导致该卷空间耗尽。

备份需要为每个仓库单独调度，这在很多情况下是合理的，因为不同仓库可能采用不同的备份类型和保留策略。同样，恢复时也必须指定仓库。通常建议优先选择延迟低/成本低的仓库进行恢复，即使这意味着恢复时间较长——具体哪个仓库效率最高，只有通过实际恢复测试才能确定。

Azure 兼容对象存储支持

pgBackRest 支持将仓库存放在 Azure 兼容的对象存储中。存储仓库的容器必须提前创建——pgBackRest 不会自动创建。仓库可以放置在容器根目录（/），但通常建议放在子路径下，以便对象存储日志或其他数据也能存储在同一容器中而不产生冲突。

警告：

请勿启用"分层命名空间"，否则执行 expire 时会报错。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 Azure

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
repo2-azure-account=pgbackrest
repo2-azure-container=demo-container
repo2-azure-key=YXpLZXk=
repo2-path=/demo-repo
repo2-retention-full=4
repo2-type=azure
start-fast=y
[global:archive-push]
compress-level=3

将 repo2-azure-key-type 设置为 sas、将 repo2-azure-key 设置为共享访问签名令牌，即可使用共享访问签名（SAS）认证。

命令的运行方式与仓库存储在本地磁盘上完全相同。

pg-primary ⇒ 创建 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create
TEXT
P00   INFO: stanza-create command begin 2.59.0: --exec-id=1652-548991ed --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo2-type=azure --stanza=demo
P00   INFO: stanza-create for stanza 'demo' on repo1
P00   INFO: stanza-create for stanza 'demo' on repo2

P00   INFO: stanza-create command end: completed successfully

由于在 Azure 中创建文件相对较慢，启用 文件打包 可以提升 backup/restore 的性能。

pg-primary ⇒ 备份 demo 集群

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=2 \
       --log-level-console=info backup
TEXT
P00   INFO: backup command begin 2.59.0: --exec-id=1661-ae2af622 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo=2 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-block --repo1-bundle --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo2-type=azure --stanza=demo --start-fast

P00   WARN: no prior backup exists, incr backup has been changed to full

P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000005000000000000001B, lsn = 0/1B000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 00000005000000000000001B:00000005000000000000001B
P00   INFO: new backup label = 20260720-005151F

P00   INFO: full backup size = 29.2MB, file total = 1265

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=1661-ae2af622 --log-level-console=info --no-log-timestamp --repo=2 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo2-type=azure --stanza=demo

S3 兼容对象存储支持

pgBackRest 支持将仓库存放在 S3 兼容的对象存储中。存储仓库的存储桶必须提前创建——pgBackRest 不会自动创建。仓库可以放置在存储桶根目录（/），但通常建议放在子路径下，以便对象存储日志或其他数据也能存储在同一存储桶中而不产生冲突。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 S3

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
repo2-azure-account=pgbackrest
repo2-azure-container=demo-container
repo2-azure-key=YXpLZXk=
repo2-path=/demo-repo
repo2-retention-full=4
repo2-type=azure
repo3-path=/demo-repo
repo3-retention-full=4
repo3-s3-bucket=demo-bucket
repo3-s3-endpoint=s3.us-east-1.amazonaws.com
repo3-s3-key=accessKey1
repo3-s3-key-secret=verySecretKey1
repo3-s3-region=us-east-1
repo3-type=s3
start-fast=y
[global:archive-push]
compress-level=3

注意：

region 和 endpoint 需配置为存储桶所在的位置，此处给出的值适用于 us-east-1 区域。

建议创建专用角色来运行 pgBackRest，并尽可能收紧存储桶权限。若该角色与 AWS 实例关联，设置 repo3-s3-key-type=auto 后 pgBackRest 将自动获取临时凭证，无需在 /etc/pgbackrest/pgbackrest.conf 中显式配置密钥。

以下 Amazon S3 策略示例将存储桶和仓库路径的读写权限限制在最小范围。

TEXT
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::demo-bucket"
            ],
            "Condition": {
                "StringEquals": {
                    "s3:prefix": [
                        "",
                        "demo-repo"
                    ],
                    "s3:delimiter": [
                        "/"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::demo-bucket"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "demo-repo/*"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:PutObjectTagging",
                "s3:GetObject",
                "s3:GetObjectVersion",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::demo-bucket/demo-repo/*"
            ]
        }
    ]
}

命令的运行方式与仓库存储在本地磁盘上完全相同。

pg-primary ⇒ 创建 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create
TEXT
       [filtered 4 lines of output]
P00   INFO: stanza 'demo' already exists on repo2 and is valid
P00   INFO: stanza-create for stanza 'demo' on repo3

P00   INFO: stanza-create command end: completed successfully

由于在 S3 中创建文件相对较慢，启用 文件打包 可以提升 backup/restore 的性能。

pg-primary ⇒ 备份 demo 集群

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=3 \
       --log-level-console=info backup
TEXT
P00   INFO: backup command begin 2.59.0: --exec-id=1763-f64148cd --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo=3 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-block --repo1-bundle --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo2-type=azure --repo3-type=s3 --stanza=demo --start-fast

P00   WARN: no prior backup exists, incr backup has been changed to full

P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000005000000000000001D, lsn = 0/1D000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 00000005000000000000001D:00000005000000000000001D
P00   INFO: new backup label = 20260720-005210F

P00   INFO: full backup size = 29.2MB, file total = 1265

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=1763-f64148cd --log-level-console=info --no-log-timestamp --repo=3 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo2-type=azure --repo3-type=s3 --stanza=demo

SFTP 支持

pgBackRest 支持将仓库存储在 SFTP 主机上。SFTP 文件传输相对较慢，建议增大 process-max 以并行化文件传输，从而提升命令性能。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 SFTP

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
process-max=4
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
repo2-azure-account=pgbackrest
repo2-azure-container=demo-container
repo2-azure-key=YXpLZXk=
repo2-path=/demo-repo
repo2-retention-full=4
repo2-type=azure
repo3-path=/demo-repo
repo3-retention-full=4
repo3-s3-bucket=demo-bucket
repo3-s3-endpoint=s3.us-east-1.amazonaws.com
repo3-s3-key=accessKey1
repo3-s3-key-secret=verySecretKey1
repo3-s3-region=us-east-1
repo3-type=s3
repo4-bundle=y
repo4-path=/demo-repo
repo4-sftp-host=sftp-server
repo4-sftp-host-key-hash-type=sha1
repo4-sftp-host-user=pgbackrest
repo4-sftp-private-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp
repo4-sftp-public-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp.pub
repo4-type=sftp
start-fast=y
[global:archive-push]
compress-level=3

使用 SFTP 时，若 libssh2 基于 OpenSSH 编译，则 repo4-sftp-public-key-file 为可选项。

pg-primary ⇒ 为 SFTP 备份生成 SSH 密钥对

BASH
sudo -u postgres mkdir -m 750 -p /var/lib/postgresql/.ssh
sudo -u postgres ssh-keygen -f /var/lib/postgresql/.ssh/id_rsa_sftp \
       -t rsa -b 4096 -N "" -m PEM

sftp-server ⇒ 将 pg-primary 的 SFTP 备份公钥复制到 sftp-server

BASH
sudo -u pgbackrest mkdir -m 750 -p /home/pgbackrest/.ssh

(sudo ssh root@pg-primary cat /var/lib/postgresql/.ssh/id_rsa_sftp.pub) | \
       sudo -u pgbackrest tee -a /home/pgbackrest/.ssh/authorized_keys

命令的运行方式与仓库存储在本地磁盘上时完全相同。

pg-primary ⇒ 将 sftp-server 的指纹添加到 known_hosts 文件（repo4-sftp-host-key-check-type 默认为 “strict”）

BASH
ssh-keyscan -H sftp-server >> /var/lib/postgresql/.ssh/known_hosts 2>/dev/null

pg-primary ⇒ 创建 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create
TEXT
       [filtered 6 lines of output]
P00   INFO: stanza 'demo' already exists on repo3 and is valid
P00   INFO: stanza-create for stanza 'demo' on repo4

P00   INFO: stanza-create command end: completed successfully

pg-primary ⇒ 备份 demo 集群

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=4 \
       --log-level-console=info backup
TEXT
P00   INFO: backup command begin 2.59.0: --exec-id=1854-09375597 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --process-max=4 --repo=4 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-block --repo1-bundle --repo4-bundle --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo4-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo4-sftp-host=sftp-server --repo4-sftp-host-key-hash-type=sha1 --repo4-sftp-host-user=pgbackrest --repo4-sftp-private-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp --repo4-sftp-public-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp.pub --repo2-type=azure --repo3-type=s3 --repo4-type=sftp --stanza=demo --start-fast
P00   WARN: option 'repo4-retention-full' is not set for 'repo4-retention-full-type=count', the repository may run out of space
            HINT: to retain full backups indefinitely (without warning), set option 'repo4-retention-full' to the maximum.

P00   WARN: no prior backup exists, incr backup has been changed to full

P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000005000000000000001F, lsn = 0/1F000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 00000005000000000000001F:00000005000000000000001F
P00   INFO: new backup label = 20260720-005234F

P00   INFO: full backup size = 29.2MB, file total = 1265

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=1854-09375597 --log-level-console=info --no-log-timestamp --repo=4 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo4-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo4-sftp-host=sftp-server --repo4-sftp-host-key-hash-type=sha1 --repo4-sftp-host-user=pgbackrest --repo4-sftp-private-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp --repo4-sftp-public-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp.pub --repo2-type=azure --repo3-type=s3 --repo4-type=sftp --stanza=demo
P00   INFO: expire command end: completed successfully

GCS 兼容对象存储支持

pgBackRest 支持将仓库存储在 GCS 兼容的对象存储中。存储仓库的存储桶必须提前创建——pgBackRest 不会自动创建。仓库可以存放在存储桶根目录（/），但通常建议放在子路径下，以便对象存储日志或其他数据也能存储在同一存储桶中而不产生冲突。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 GCS

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
process-max=4
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
repo2-azure-account=pgbackrest
repo2-azure-container=demo-container
repo2-azure-key=YXpLZXk=
repo2-path=/demo-repo
repo2-retention-full=4
repo2-type=azure
repo3-path=/demo-repo
repo3-retention-full=4
repo3-s3-bucket=demo-bucket
repo3-s3-endpoint=s3.us-east-1.amazonaws.com
repo3-s3-key=accessKey1
repo3-s3-key-secret=verySecretKey1
repo3-s3-region=us-east-1
repo3-type=s3
repo4-bundle=y
repo4-path=/demo-repo
repo4-sftp-host=sftp-server
repo4-sftp-host-key-hash-type=sha1
repo4-sftp-host-user=pgbackrest
repo4-sftp-private-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp
repo4-sftp-public-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp.pub
repo4-type=sftp
repo5-gcs-bucket=demo-bucket
repo5-gcs-key=/etc/pgbackrest/gcs-key.json
repo5-path=/demo-repo
repo5-type=gcs
start-fast=y
[global:archive-push]
compress-level=3

在 GCE 中运行时，设置 repo5-gcs-key-type=auto 可使用实例服务账号自动完成身份验证，无需手动配置密钥文件。

命令的运行方式与仓库存储在本地磁盘上时完全相同。

GCS 中文件创建速度相对较慢，启用 文件打包 可以提升 backup/restore 的性能。

仓库目标时间

目标时间定义了命令读取版本化存储上仓库时所使用的时间点，允许以历史某一时刻的状态读取仓库，以便恢复因用户误操作或恶意软件而被删除或损坏的数据。

版本化存储受 S3、GCS 和 Azure 支持，但通常默认未启用。除了启用版本控制之外，还可以考虑为 S3 启用对象锁定（object locking），为 GCS 或 Azure 启用软删除（soft delete）。

指定 --repo-target-time 选项时，必须同时提供 --repo 选项。由于并非所有仓库类型都支持版本控制，针对单个仓库进行恢复是合理的做法。

注意，时间戳的比较采用 <= 关系，且所提供时间戳中的毫秒部分会被截断。

为演示此功能，先删除 S3 仓库中 demo stanza 的数据。

pg-primary ⇒ 删除 S3 仓库中的 stanza

BASH
sudo pg_ctlcluster 17 demo stop
sudo -u postgres pgbackrest --stanza=demo stop
sudo -u postgres pgbackrest --stanza=demo --repo=3 stanza-delete

stanza 删除后，info 命令会显示仓库处于错误状态。

pg-primary ⇒ info 命令报错

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=3 info
TEXT
stanza: demo

    status: error (missing stanza path)

由于存储是版本化的，可以查看 stanza 被删除之前某个时间点的仓库状态。确定合适的目标时间可能并不容易，但在本例中，可以通过检查 backup.info 被删除的时间来确定。

pg-primary ⇒ 列出存储桶中 backup.info 的版本信息

BASH
key=demo-repo/backup/demo/backup.info; \
       aws s3api list-object-versions --bucket demo-bucket \
       --prefix $key --output table \
       --query "sort_by([Versions[?Key=='$key'].{Action:'PUT', \
       Modified:LastModified,Object:Key}, \
       DeleteMarkers[?Key=='$key'].{Action:'DELETE', \
       Modified:LastModified,Object:Key}][],&Modified)"
TEXT
-----------------------------------------------------------------------------
|                            ListObjectVersions                             |
+--------+----------------------------+-------------------------------------+
| Action |         Modified           |               Object                |
+--------+----------------------------+-------------------------------------+
|  PUT   |  2026-07-20T00:52:10.222Z  |  demo-repo/backup/demo/backup.info  |
|  PUT   |  2026-07-20T00:52:29.141Z  |  demo-repo/backup/demo/backup.info  |
|  DELETE|  2026-07-20T00:52:41.328Z  |  demo-repo/backup/demo/backup.info  |
+--------+----------------------------+-------------------------------------+

现在可以使用目标时间运行 info 命令，查看仓库被删除之前的状态。

pg-primary ⇒ 带目标时间的 info 命令

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=3 \
       --repo-target-time="2026-07-20 00:52:29+00" info
TEXT
       [filtered 5 lines of output]
        wal archive min/max (17): 00000005000000000000001C/00000005000000000000001D

        full backup: 20260720-005210F

            timestamp start/stop: 2026-07-20 00:52:10+00 / 2026-07-20 00:52:28+00
            wal start/stop: 00000005000000000000001D / 00000005000000000000001D
            repo3: backup set size: 3.8MB, backup size: 3.8MB

若 info 命令显示了所需的备份，即可使用相同的目标时间进行恢复。

pg-primary ⇒ 带目标时间的 restore 命令

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=3 --delta \
       --repo-target-time="2026-07-20 00:52:29+00" --log-level-console=info restore
TEXT
P00   INFO: restore command begin 2.59.0: --delta --exec-id=1948-6793703a --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --process-max=4 --repo=3 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo5-gcs-bucket=demo-bucket --repo5-gcs-key= --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo4-path=/demo-repo --repo5-path=/demo-repo --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo4-sftp-host=sftp-server --repo4-sftp-host-key-hash-type=sha1 --repo4-sftp-host-user=pgbackrest --repo4-sftp-private-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp --repo4-sftp-public-key-file=/var/lib/postgresql/.ssh/id_rsa_sftp.pub --repo-target-time="2026-07-20 00:52:29+00" --repo2-type=azure --repo3-type=s3 --repo4-type=sftp --repo5-type=gcs --stanza=demo

P00   INFO: repo3: restore backup set 20260720-005210F, recovery will start at 2026-07-20 00:52:10

P00   INFO: remove invalid files/links/paths from '/var/lib/postgresql/17/demo'
P00   INFO: write updated /var/lib/postgresql/17/demo/postgresql.auto.conf
       [filtered 2 lines of output]
BASH
sudo pg_ctlcluster 17 demo start

专用仓库主机

快速开始 中描述的配置适合简单安装场景，但对于企业级配置，更典型的做法是使用专用仓库主机来存储备份和 WAL 归档。这样可以将备份与数据库服务器解耦，降低数据库主机故障的影响。仍然建议使用传统备份软件对仓库主机本身进行备份。

在 PostgreSQL 主机上，pg1-path 必须设置为本地 PostgreSQL 集群的路径，且不应配置 pg1-host。在仓库主机的配置中，pgBackRest 配置文件必须通过 pg-host 选项连接主库和备库（如有）。仓库主机是唯一需要感知多个 PostgreSQL 主机的配置节点。顺序无关紧要，pg1-path/pg1-host、pg2-path/pg2-host 可以分别对应主库或备库。

安装

创建一台名为 repository 的新主机，用于存储集群备份。

注意：

仓库主机上安装的 pgBackRest 版本必须与 PostgreSQL 主机上安装的版本完全一致。

创建 pgbackrest 用户来管理 pgBackRest 仓库。仓库可以由任何用户管理，但建议不要使用 postgres（若存在），以避免混淆。

注意：

从软件包安装 pgBackRest 时，可能会提供类似 /etc/logrotate.d/pgbackrest 的 logrotate 配置，通过 su 指令以特定用户轮转日志（例如 su postgres postgres）。由于 /var/log/pgbackrest 中的文件归运行 pgBackRest 的用户所有（此处为 pgbackrest），必须将 su 指令更新为该用户，否则 logrotate 会因权限错误而失败。

repository ⇒ 创建 pgbackrest 用户

BASH
sudo adduser --disabled-password --gecos "" pgbackrest

推荐通过软件包安装 pgBackRest，而非从源码编译。使用软件包时，本节后续步骤通常不必手动执行，但个别软件包可能遗漏某个目录的创建或权限设置有误，此时需要手动创建目录或修正权限。

Debian/Ubuntu 的 pgBackRest 软件包可在 apt.postgresql.org 获取。

如果当前发行版没有提供软件包，可以 从源码构建 后手动安装，步骤如下。

repository ⇒ 安装依赖

BASH
sudo apt-get install postgresql-client libxml2 libssh2-1

repository ⇒ 从构建主机复制 pgBackRest 二进制文件

BASH
sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin
sudo chmod 755 /usr/bin/pgbackrest

pgBackRest 运行需要日志目录、配置目录以及配置文件。

repository ⇒ 创建 pgBackRest 配置文件和目录

BASH
sudo mkdir -p -m 770 /var/log/pgbackrest
sudo chown pgbackrest:pgbackrest /var/log/pgbackrest
sudo mkdir -p /etc/pgbackrest
sudo mkdir -p /etc/pgbackrest/conf.d
sudo touch /etc/pgbackrest/pgbackrest.conf
sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
sudo chown pgbackrest:pgbackrest /etc/pgbackrest/pgbackrest.conf

repository ⇒ 创建 pgBackRest 仓库

BASH
sudo mkdir -p /var/lib/pgbackrest
sudo chmod 750 /var/lib/pgbackrest
sudo chown pgbackrest:pgbackrest /var/lib/pgbackrest

配置免密 SSH

pgBackRest 支持使用免密 SSH 实现主机间通信。也可以使用 TLS，请参见 配置 TLS。

repository ⇒ 创建仓库主机密钥对

BASH
sudo -u pgbackrest mkdir -m 750 /home/pgbackrest/.ssh
sudo -u pgbackrest ssh-keygen -f /home/pgbackrest/.ssh/id_rsa \
       -t rsa -b 4096 -N ""

pg-primary ⇒ 创建 pg-primary 主机密钥对

BASH
sudo -u postgres mkdir -m 750 -p /var/lib/postgresql/.ssh
sudo -u postgres ssh-keygen -f /var/lib/postgresql/.ssh/id_rsa \
       -t rsa -b 4096 -N ""

在 repository 和 pg-primary 之间互换公钥。

repository ⇒ 将 pg-primary 公钥复制到 repository

BASH
(echo -n 'no-agent-forwarding,no-X11-forwarding,no-port-forwarding,' && \
       echo -n 'command="/usr/bin/pgbackrest ${SSH_ORIGINAL_COMMAND#* }" ' && \
       sudo ssh root@pg-primary cat /var/lib/postgresql/.ssh/id_rsa.pub) | \
       sudo -u pgbackrest tee -a /home/pgbackrest/.ssh/authorized_keys

pg-primary ⇒ 将 repository 公钥复制到 pg-primary

BASH
(echo -n 'no-agent-forwarding,no-X11-forwarding,no-port-forwarding,' && \
       echo -n 'command="/usr/bin/pgbackrest ${SSH_ORIGINAL_COMMAND#* }" ' && \
       sudo ssh root@repository cat /home/pgbackrest/.ssh/id_rsa.pub) | \
       sudo -u postgres tee -a /var/lib/postgresql/.ssh/authorized_keys

验证 repository 到 pg-primary 以及反向的 SSH 连接是否正常。

repository ⇒ 测试从 repository 到 pg-primary 的连接

BASH
sudo -u pgbackrest ssh postgres@pg-primary

pg-primary ⇒ 测试从 pg-primary 到 repository 的连接

BASH
sudo -u postgres ssh pgbackrest@repository

注意：

SSH 已配置为仅允许通过免密 SSH 运行 pgBackRest，这可以在服务账号被劫持时增强安全性。

配置

仓库主机必须配置 pg-primary 的主机/用户及数据库路径。主库配置为 pg1，以便后续添加备库。

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pg1-host/pg1-host-user 和 pg1-path

INI
[demo]
pg1-host=pg-primary
pg1-path=/var/lib/postgresql/17/demo
[global]
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y

数据库主机必须配置仓库主机/用户。repo1-host-user 选项的默认值为 pgbackrest。若 postgres 用户需要在仓库主机上执行恢复操作，最好不要同时允许其执行备份。不过，若 postgres 用户与 pgbackrest 用户属于同一用户组，则可以直接读取仓库。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-host/repo1-host-user

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
log-level-file=detail
repo1-host=repository

PostgreSQL 的配置可以参见 配置归档 章节。

命令的运行方式与单主机配置相同，但 backup 和 expire 等命令需要在仓库主机上运行，而非数据库主机。

创建并检查 Stanza

在新仓库中创建 stanza。

repository ⇒ 创建 stanza

BASH
sudo -u pgbackrest pgbackrest --stanza=demo stanza-create

在数据库主机和仓库主机上分别验证配置是否正确。关于 check 命令的更多信息，请参见 检查配置。

pg-primary ⇒ 检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo check

repository ⇒ 检查配置

BASH
sudo -u pgbackrest pgbackrest --stanza=demo check

执行备份

在仓库主机上使用 backup 命令对 PostgreSQL 集群执行备份。

repository ⇒ 备份 demo 集群

BASH
sudo -u pgbackrest pgbackrest --stanza=demo backup
TEXT
P00   WARN: no prior backup exists, incr backup has been changed to full

由于仓库主机上的仓库是新建的，因此出现增量备份自动转为全量备份的警告。

恢复备份

在数据库主机上使用 restore 命令恢复 PostgreSQL 集群。

pg-primary ⇒ 停止 demo 集群、执行恢复并重启 PostgreSQL

BASH
sudo pg_ctlcluster 17 demo stop
sudo -u postgres pgbackrest --stanza=demo --delta restore
sudo pg_ctlcluster 17 demo start

并行备份与恢复

pgBackRest 提供并行处理功能，可以提升压缩和传输性能。通过 --process-max 选项设置并行进程数。

对于 backup 命令，通常建议不超过可用 CPU 数量的 25%。只要定期执行备份，速度并不需要太快，且备份过程应尽量不影响数据库性能。

对于 restore 命令，可以也应该使用全部可用 CPU，因为恢复期间 PostgreSQL 集群处于关闭状态，主机上通常没有其他关键任务在运行。若主机上有多个集群，设置恢复并行度时需相应考虑。

repository ⇒ 使用单进程执行备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo --type=full backup

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pgBackRest 使用多个 backup 进程

INI
[demo]
pg1-host=pg-primary
pg1-path=/var/lib/postgresql/17/demo
[global]
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y

repository ⇒ 使用多进程执行备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo --type=full backup

repository ⇒ 获取 demo 集群的备份信息

BASH
sudo -u pgbackrest pgbackrest info
TEXT
stanza: demo
    status: ok
    cipher: none

    db (current)
        wal archive min/max (17): 000000070000000000000023/000000070000000000000025

        full backup: 20260720-005325F

            timestamp start/stop: 2026-07-20 00:53:25+00 / 2026-07-20 00:53:29+00

            wal start/stop: 000000070000000000000023 / 000000070000000000000023
            database size: 29.2MB, database backup size: 29.2MB
            repo1: backup set size: 3.8MB, backup size: 3.8MB

        full backup: 20260720-005331F

            timestamp start/stop: 2026-07-20 00:53:31+00 / 2026-07-20 00:53:36+00

            wal start/stop: 000000070000000000000024 / 000000070000000000000025
            database size: 29.2MB, database backup size: 29.2MB
            repo1: backup set size: 3.8MB, backup size: 3.8MB

与单进程备份相比，多进程备份应有明显的性能提升。对于非常小的备份，差异可能不明显，但随着数据库规模增大，节省的时间也会相应增加。

启动与停止

若备库被提升用于测试，或测试集群从生产备份中恢复，应阻止这些集群向 pgBackRest 仓库写入数据，这可以通过 stop 命令实现。

会向仓库写入数据且会被 stop 阻止的命令有：archive-push、backup、expire、stanza-create 和 stanza-upgrade。注意，stanza-delete 是例外（详情参见 删除 Stanza）。

pg-primary ⇒ 停止 pgBackRest 写入命令

BASH
sudo -u postgres pgbackrest stop

此后新的 pgBackRest 写入命令将不再被执行。

repository ⇒ 尝试执行备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo backup
TEXT
P00   WARN: unable to check pg1: [StopError] raised from remote-0 ssh protocol on 'pg-primary': stop file exists for all stanzas

P00  ERROR: [056]: unable to find primary cluster - cannot proceed
            HINT: are all available clusters in recovery?

指定 --force 选项可以终止当前正在运行的 pgBackRest 写入命令，包括异步 archive-get（如果 PostgreSQL 需要，它会再次启动）。若 pgBackRest 已处于停止状态，再次执行 stop 将产生警告。

pg-primary ⇒ 再次停止 pgBackRest 服务

BASH
sudo -u postgres pgbackrest stop
TEXT
P00   WARN: stop file already exists for all stanzas

使用 start 命令重新允许 pgBackRest 写入命令运行。停止之前正在进行的写入命令不会自动重启，但现在可以重新运行。

pg-primary ⇒ 启动 pgBackRest 写入命令

BASH
sudo -u postgres pgbackrest start

也可以仅停止特定 stanza 的 pgBackRest 写入命令。

pg-primary ⇒ 停止 demo stanza 的 pgBackRest 写入命令

BASH
sudo -u postgres pgbackrest --stanza=demo stop

指定 stanza 的新写入命令将不再被执行。

repository ⇒ 尝试执行备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo backup
TEXT
P00   WARN: unable to check pg1: [StopError] raised from remote-0 ssh protocol on 'pg-primary': stop file exists for stanza demo

P00  ERROR: [056]: unable to find primary cluster - cannot proceed
            HINT: are all available clusters in recovery?

针对单个 stanza 重新启动写入命令时，也必须指定该 stanza。

pg-primary ⇒ 启动 demo stanza 的 pgBackRest 写入命令

BASH
sudo -u postgres pgbackrest --stanza=demo start

复制

复制允许从单个主库创建多个 PostgreSQL 集群副本（即备库）。备库可用于分担读取负载，并在主库主机发生故障时提供冗余。

安装

创建一台名为 pg-standby 的新主机来运行备库。

推荐通过软件包安装 pgBackRest，而非从源码编译。使用软件包时，本节后续步骤通常不必手动执行，但个别软件包可能遗漏目录创建或权限设置有误，此时需要手动处理。

Debian/Ubuntu 的 pgBackRest 软件包可在 apt.postgresql.org 获取。

如果当前发行版没有提供软件包，可以 从源码构建 后手动安装。

pg-standby ⇒ 安装依赖

BASH
sudo apt-get install postgresql-client libxml2 libssh2-1

pg-standby ⇒ 从构建主机复制 pgBackRest 二进制文件

BASH
sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin
sudo chmod 755 /usr/bin/pgbackrest

pgBackRest 需要日志目录、配置目录以及配置文件。

pg-standby ⇒ 创建 pgBackRest 配置文件和目录

BASH
sudo mkdir -p -m 770 /var/log/pgbackrest
sudo chown postgres:postgres /var/log/pgbackrest
sudo mkdir -p /etc/pgbackrest
sudo mkdir -p /etc/pgbackrest/conf.d
sudo touch /etc/pgbackrest/pgbackrest.conf
sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf

配置免密 SSH

pgBackRest 支持使用免密 SSH 实现主机间通信。也可以使用 TLS，请参见 配置 TLS。

pg-standby ⇒ 创建 pg-standby 主机密钥对

BASH
sudo -u postgres mkdir -m 750 -p /var/lib/postgresql/.ssh
sudo -u postgres ssh-keygen -f /var/lib/postgresql/.ssh/id_rsa \
       -t rsa -b 4096 -N ""

在 repository 和 pg-standby 之间互换公钥。

repository ⇒ 将 pg-standby 公钥复制到 repository

BASH
(echo -n 'no-agent-forwarding,no-X11-forwarding,no-port-forwarding,' && \
       echo -n 'command="/usr/bin/pgbackrest ${SSH_ORIGINAL_COMMAND#* }" ' && \
       sudo ssh root@pg-standby cat /var/lib/postgresql/.ssh/id_rsa.pub) | \
       sudo -u pgbackrest tee -a /home/pgbackrest/.ssh/authorized_keys

pg-standby ⇒ 将 repository 公钥复制到 pg-standby

BASH
(echo -n 'no-agent-forwarding,no-X11-forwarding,no-port-forwarding,' && \
       echo -n 'command="/usr/bin/pgbackrest ${SSH_ORIGINAL_COMMAND#* }" ' && \
       sudo ssh root@repository cat /home/pgbackrest/.ssh/id_rsa.pub) | \
       sudo -u postgres tee -a /var/lib/postgresql/.ssh/authorized_keys

验证 repository 到 pg-standby 以及反向的 SSH 连接是否正常。

repository ⇒ 测试从 repository 到 pg-standby 的连接

BASH
sudo -u pgbackrest ssh postgres@pg-standby

pg-standby ⇒ 测试从 pg-standby 到 repository 的连接

BASH
sudo -u postgres ssh pgbackrest@repository

热备库

热备库通过 WAL 归档进行复制，并允许只读查询。

pgBackRest 的配置与 pg-primary 非常相似，区别在于使用 standby 恢复类型，使集群在到达 WAL 流末尾时保持在恢复模式而不退出。

pg-standby:/etc/pgbackrest/pgbackrest.conf ⇒ 在备库上配置 pgBackRest

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
log-level-file=detail
repo1-host=repository

必须先创建 demo 集群（即使恢复时会被覆盖），以便生成 PostgreSQL 配置文件。

pg-standby ⇒ 创建 demo 集群

BASH
sudo pg_createcluster 17 demo

现在可以使用 restore 命令创建备库。

重要提示：

若集群要在不成为新主库的情况下被提升（例如用于报表或测试），请使用 --archive-mode=off 或在 postgresql.conf 中设置 archive_mode=off 来禁用归档。若不禁用归档，仓库中可能会被大量 WAL 污染，使后续恢复更加困难。

pg-standby ⇒ 恢复 demo 备库集群

BASH
sudo -u postgres pgbackrest --stanza=demo --delta --type=standby restore
sudo -u postgres cat /var/lib/postgresql/17/demo/postgresql.auto.conf

# Do not edit this file manually!
# It will be overwritten by the ALTER SYSTEM command.

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:50:46
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:51:14
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:51:38
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'
# Removed by pgBackRest restore on 2026-07-20 00:52:47 # recovery_target_time = '2026-07-20 00:51:32.323409+00'
# Removed by pgBackRest restore on 2026-07-20 00:52:47 # recovery_target_action = 'promote'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:52:47
restore_command = 'pgbackrest --repo=3 --repo-target-time="2026-07-20 00:52:29+00" --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:53:18
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:53:55
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

启动 PostgreSQL 之前，必须启用 hot_standby 设置以允许 pg-standby 接受只读连接，否则连接请求将被拒绝。其余配置是为备库被提升为主库做准备。

pg-standby:/etc/postgresql/17/demo/postgresql.conf ⇒ 配置 PostgreSQL

INI
archive_command = 'pgbackrest --stanza=demo archive-push %p'
archive_mode = on
hot_standby = on

pg-standby ⇒ 启动 PostgreSQL

BASH
sudo pg_ctlcluster 17 demo start

PostgreSQL 日志提供了恢复过程的重要信息，请注意确认集群已进入备库模式并准备好接受只读连接。

pg-standby ⇒ 检查 PostgreSQL 日志中表示成功的日志消息

BASH
sudo -u postgres cat /var/log/postgresql/postgresql-17-demo.log
TEXT
       [filtered 6 lines of output]
LOG:  restored log file "00000007.history" from archive
LOG:  restored log file "000000070000000000000024" from archive

LOG:  entering standby mode

LOG:  redo starts at 0/24000028
LOG:  restored log file "000000070000000000000025" from archive
       [filtered 3 lines of output]

验证复制是否正确配置的简单方法是在 pg-primary 上创建一张表。

pg-primary ⇒ 在主库上创建新表

BASH
sudo -u postgres psql -c " \
       begin; \
       create table replicated_table (message text); \
       insert into replicated_table values ('Important Data'); \
       commit; \
       select * from replicated_table";
TEXT
       [filtered 4 lines of output]
    message
----------------

 Important Data

(1 row)

然后在 pg-standby 上查询同一张表，验证数据是否已同步。

pg-standby ⇒ 在备库上查询新表

BASH
sudo -u postgres psql -c "select * from replicated_table;"
TEXT
ERROR:  relation "replicated_table" does not exist

LINE 1: select * from replicated_table;
                      ^

为什么没有数据？因为 PostgreSQL 从归档中拉取 WAL 段来执行复制，包含这些更改的 WAL 段尚未从 pg-primary 推送到归档，所以备库还看不到这些更改。

可以手动调用 pg_switch_wal() 解决这一问题——该函数会将当前 WAL 段推送到归档（并创建新的 WAL 段来存放后续更改）。

pg-primary ⇒ 调用 pg_switch_wal()

BASH
sudo -u postgres psql -c "select *, current_timestamp from pg_switch_wal()";
TEXT
 pg_switch_wal |       current_timestamp
---------------+-------------------------------
 0/26019600    | 2026-07-20 00:54:03.825464+00
(1 row)

稍等片刻后，表将出现在 pg-standby 上（可能需要等待 WAL 段完成归档和应用）。

pg-standby ⇒ 新表现在已出现在备库上（可能需要重试几次）

BASH
sudo -u postgres psql -c " \
       select *, current_timestamp from replicated_table"
TEXT
    message     |       current_timestamp
----------------+-------------------------------

 Important Data | 2026-07-20 00:54:05.488701+00

(1 row)

验证备库配置对仓库的访问是否正常。

pg-standby ⇒ 检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=487-8da2e26b --log-level-console=info --log-level-file=detail --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo1-host=repository --stanza=demo
P00   INFO: check repo1 (standby)

P00   INFO: switch wal not performed because this is a standby

P00   INFO: check command end: completed successfully

流复制

流复制不仅依赖 WAL 归档，而是直接连接到主库，在主库发生更改时立即应用，从而大幅降低主备延迟。

流复制需要一个具有复制权限的用户。

pg-primary ⇒ 创建复制用户

BASH
sudo -u postgres psql -c " \
       create user replicator password 'jw8s0F4' replication";
SQL
CREATE ROLE

需要更新 pg_hba.conf 文件以允许备库以复制用户身份连接。请将下面的 IP 地址替换为实际的 pg-standby IP 地址。修改 pg_hba.conf 后需重新加载配置。

pg-primary ⇒ 为复制用户创建 pg_hba.conf 条目

BASH
sudo -u postgres sh -c 'echo \
       "host    replication     replicator      172.17.0.8/32           md5" \
       >> /etc/postgresql/17/demo/pg_hba.conf'

sudo pg_ctlcluster 17 demo reload

备库需要知道如何连接到主库，因此在 pgBackRest 配置中设置 primary_conninfo。

pg-standby:/etc/pgbackrest/pgbackrest.conf ⇒ 设置 primary_conninfo

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
recovery-option=primary_conninfo=host=172.17.0.6 port=5432 user=replicator
[global]
log-level-file=detail
repo1-host=repository

密码可以直接写入 primary_conninfo，但使用 .pgpass 文件更灵活、更安全。

pg-standby ⇒ 在 .pgpass 文件中配置复制密码

BASH
sudo -u postgres sh -c 'echo \
       "172.17.0.6:*:replication:replicator:jw8s0F4" \
       >> /var/lib/postgresql/.pgpass'

sudo -u postgres chmod 600 /var/lib/postgresql/.pgpass

现在可以使用 restore 命令创建备库。

pg-standby ⇒ 停止 PostgreSQL，恢复 demo 备库集群

BASH
sudo pg_ctlcluster 17 demo stop
sudo -u postgres pgbackrest --stanza=demo --delta --type=standby restore
sudo -u postgres cat /var/lib/postgresql/17/demo/postgresql.auto.conf

# Do not edit this file manually!
# It will be overwritten by the ALTER SYSTEM command.

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:50:46
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:51:14
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:51:38
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'
# Removed by pgBackRest restore on 2026-07-20 00:52:47 # recovery_target_time = '2026-07-20 00:51:32.323409+00'
# Removed by pgBackRest restore on 2026-07-20 00:52:47 # recovery_target_action = 'promote'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:52:47
restore_command = 'pgbackrest --repo=3 --repo-target-time="2026-07-20 00:52:29+00" --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:53:18
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:54:08
primary_conninfo = 'host=172.17.0.6 port=5432 user=replicator'
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

注意：

primary_conninfo 设置已写入 postgresql.auto.conf，因为它在 pgbackrest.conf 中通过 recovery-option 方式配置。若希望保留现有的 postgresql.auto.conf 文件，可在 restore 时使用 --type=preserve 选项。

pg-standby ⇒ 启动 PostgreSQL

BASH
sudo pg_ctlcluster 17 demo start

PostgreSQL 日志将确认流复制已成功启动。

pg-standby ⇒ 检查 PostgreSQL 日志中表示成功的日志消息

BASH
sudo -u postgres cat /var/log/postgresql/postgresql-17-demo.log
TEXT
       [filtered 13 lines of output]
LOG:  consistent recovery state reached at 0/25000088
LOG:  database system is ready to accept read-only connections

LOG:  started streaming WAL from primary at 0/27000000 on timeline 7

现在在 pg-primary 上创建表后，无需调用 pg_switch_wal()，数据将很快出现在 pg-standby 上。

pg-primary ⇒ 在主库上创建新表

BASH
sudo -u postgres psql -c " \
       begin; \
       create table stream_table (message text); \
       insert into stream_table values ('Important Data'); \
       commit; \
       select *, current_timestamp from stream_table";
TEXT
       [filtered 4 lines of output]
    message     |       current_timestamp
----------------+-------------------------------

 Important Data | 2026-07-20 00:54:16.127931+00

(1 row)

pg-standby ⇒ 在备库上查询表

BASH
sudo -u postgres psql -c " \
       select *, current_timestamp from stream_table"
TEXT
    message     |      current_timestamp
----------------+------------------------------

 Important Data | 2026-07-20 00:54:16.56118+00

(1 row)

多 Stanza 配置

pgBackRest 支持多个 stanza，最常见的用法是多个 stanza 共享同一台仓库主机。

安装

创建一台名为 pg-alt 的新主机，用于运行新的主库。

推荐优先从软件包安装 pgBackRest，而非从源码构建。使用软件包安装时，本节中的其余步骤通常可以跳过，但某些软件包可能会遗漏目录创建或权限设置，届时需要手动补全。

Debian/Ubuntu 平台的 pgBackRest 软件包可在 apt.postgresql.org 获取。

如果当前发行版没有提供适用的软件包，可以参考 编译构建 一节从源码构建，并按如下方式手动安装。

pg-alt ⇒ 安装依赖

BASH
sudo apt-get install postgresql-client libxml2 libssh2-1

pg-alt ⇒ 从编译主机复制 pgBackRest 二进制文件

BASH
sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin
sudo chmod 755 /usr/bin/pgbackrest

pgBackRest 需要创建日志目录、配置目录和配置文件。

pg-alt ⇒ 创建 pgBackRest 配置文件和目录

BASH
sudo mkdir -p -m 770 /var/log/pgbackrest
sudo chown postgres:postgres /var/log/pgbackrest
sudo mkdir -p /etc/pgbackrest
sudo mkdir -p /etc/pgbackrest/conf.d
sudo touch /etc/pgbackrest/pgbackrest.conf
sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf

配置免密 SSH

pgBackRest 支持使用免密 SSH 实现主机间通信，也可以改用 TLS，详见 配置 TLS。

pg-alt ⇒ 创建 pg-alt 主机密钥对

BASH
sudo -u postgres mkdir -m 750 -p /var/lib/postgresql/.ssh
sudo -u postgres ssh-keygen -f /var/lib/postgresql/.ssh/id_rsa \
       -t rsa -b 4096 -N ""

交换仓库主机与 pg-alt 之间的 SSH 公钥。

repository ⇒ 将 pg-alt 公钥复制到仓库主机

BASH
(echo -n 'no-agent-forwarding,no-X11-forwarding,no-port-forwarding,' && \
       echo -n 'command="/usr/bin/pgbackrest ${SSH_ORIGINAL_COMMAND#* }" ' && \
       sudo ssh root@pg-alt cat /var/lib/postgresql/.ssh/id_rsa.pub) | \
       sudo -u pgbackrest tee -a /home/pgbackrest/.ssh/authorized_keys

pg-alt ⇒ 将仓库主机公钥复制到 pg-alt

BASH
(echo -n 'no-agent-forwarding,no-X11-forwarding,no-port-forwarding,' && \
       echo -n 'command="/usr/bin/pgbackrest ${SSH_ORIGINAL_COMMAND#* }" ' && \
       sudo ssh root@repository cat /home/pgbackrest/.ssh/id_rsa.pub) | \
       sudo -u postgres tee -a /var/lib/postgresql/.ssh/authorized_keys

验证仓库主机到 pg-alt 及 pg-alt 到仓库主机的双向 SSH 连接。

repository ⇒ 测试从仓库主机到 pg-alt 的连接

BASH
sudo -u pgbackrest ssh postgres@pg-alt

pg-alt ⇒ 测试从 pg-alt 到仓库主机的连接

BASH
sudo -u postgres ssh pgbackrest@repository

配置

pg-alt 上的 pgBackRest 配置与 pg-primary 基本相同，区别在于使用 demo-alt stanza，从而将备份和归档存储在独立的位置。

pg-alt:/etc/pgbackrest/pgbackrest.conf ⇒ 在新主库上配置 pgBackRest

INI
[demo-alt]
pg1-path=/var/lib/postgresql/17/demo
[global]
log-level-file=detail
repo1-host=repository

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pg1-host/pg1-host-user 和 pg1-path

INI
[demo]
pg1-host=pg-primary
pg1-path=/var/lib/postgresql/17/demo
[demo-alt]
pg1-host=pg-alt
pg1-path=/var/lib/postgresql/17/demo
[global]
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y

初始化演示集群

pg-alt ⇒ 创建演示集群

BASH
sudo -u postgres /usr/lib/postgresql/17/bin/initdb \
       -D /var/lib/postgresql/17/demo -k -A peer

sudo pg_createcluster 17 demo
TEXT
Configuring already existing cluster (configuration: /etc/postgresql/17/demo, data: /var/lib/postgresql/17/demo, owner: 102:103)
Ver Cluster Port Status Owner    Data directory              Log file
17  demo    5432 down   postgres /var/lib/postgresql/17/demo /var/log/postgresql/postgresql-17-demo.log

pg-alt:/etc/postgresql/17/demo/postgresql.conf ⇒ 配置 PostgreSQL 设置

INI
archive_command = 'pgbackrest --stanza=demo-alt archive-push %p'
archive_mode = on

pg-alt ⇒ 启动演示集群

BASH
sudo pg_ctlcluster 17 demo restart

创建 Stanza 并检查配置

必须运行 stanza-create 命令初始化 stanza。建议随后运行 check 命令，确认归档与备份配置均正确无误。

pg-alt ⇒ 创建 stanza 并检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo-alt --log-level-console=info stanza-create
TEXT
P00   INFO: stanza-create command begin 2.59.0: --exec-id=382-e3df02cb --log-level-console=info --log-level-file=detail --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo1-host=repository --stanza=demo-alt
P00   INFO: stanza-create for stanza 'demo-alt' on repo1

P00   INFO: stanza-create command end: completed successfully
BASH
sudo -u postgres pgbackrest --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=392-66f94f82 --log-level-console=info --log-level-file=detail --no-log-timestamp --repo1-host=repository

P00   INFO: check stanza 'demo-alt'

P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 000000010000000000000001 successfully archived to '/var/lib/pgbackrest/archive/demo-alt/17-1/0000000100000000/000000010000000000000001-203efafdd9df967f3a930969cc53b0303472f932.gz' on repo1

P00   INFO: check command end: completed successfully

在仓库主机上运行 check 命令时，会同时检查所有 stanza。

repository ⇒ 检查所有 stanza 的配置

BASH
sudo -u pgbackrest pgbackrest --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=1257-861abd63 --log-level-console=info --no-log-timestamp --repo1-path=/var/lib/pgbackrest

P00   INFO: check stanza 'demo'

P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 000000070000000000000027 successfully archived to '/var/lib/pgbackrest/archive/demo/17-1/0000000700000000/000000070000000000000027-221bbbda8246b36621dd12ef128e8906b5b1f9ea.gz' on repo1
P00   INFO: check stanza 'demo-alt'

P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 000000010000000000000002 successfully archived to '/var/lib/pgbackrest/archive/demo-alt/17-1/0000000100000000/000000010000000000000002-e9f6eb2b48ad5cb3b1a169259690bbff3d7a2805.gz' on repo1

P00   INFO: check command end: completed successfully

异步归档

通过 archive-async 选项可启用异步归档，该选项对 archive-push 和 archive-get 命令均生效。

异步归档需要配置缓冲区路径（spool path）。两个命令都会在此路径下存储临时数据，但工作方式各有不同，具体用法将在各小节中分别说明。

pg-primary ⇒ 创建缓冲区目录

BASH
sudo mkdir -p -m 750 /var/spool/pgbackrest
sudo chown postgres:postgres /var/spool/pgbackrest

pg-standby ⇒ 创建缓冲区目录

BASH
sudo mkdir -p -m 750 /var/spool/pgbackrest
sudo chown postgres:postgres /var/spool/pgbackrest

配置缓冲区路径并启用异步归档后，pgBackRest 会通过减少远程存储的连接次数自动获得一定的性能提升。进一步配置 process-max 可通过并行化操作大幅提升性能，但不宜设置过高，以免影响正常的数据库运行。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置缓冲区路径和异步归档

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
[global]
archive-async=y
log-level-file=detail
repo1-host=repository
spool-path=/var/spool/pgbackrest
[global:archive-get]
process-max=2
[global:archive-push]
process-max=2

pg-standby:/etc/pgbackrest/pgbackrest.conf ⇒ 配置缓冲区路径和异步归档

INI
[demo]
pg1-path=/var/lib/postgresql/17/demo
recovery-option=primary_conninfo=host=172.17.0.6 port=5432 user=replicator
[global]
archive-async=y
log-level-file=detail
repo1-host=repository
spool-path=/var/spool/pgbackrest
[global:archive-get]
process-max=2
[global:archive-push]
process-max=2

注意：

process-max 通过命令专属配置节（command sections）来设置，使其不会被备份和恢复操作所继承，同时也允许为 archive-push 和 archive-get 分别指定不同的值。

为便于演示，这里通过中断流复制，强制 PostgreSQL 使用 restore_command 从归档获取 WAL。

pg-primary ⇒ 通过更改复制密码来中断流复制

BASH
sudo -u postgres psql -c "alter user replicator password 'bogus'"
SQL
ALTER ROLE

pg-standby ⇒ 重启备库以中断连接

BASH
sudo pg_ctlcluster 17 demo restart

归档推送（Archive Push）

异步 archive-push 命令将 WAL 归档工作转交给独立进程（或多进程）处理，以提升吞吐量。其工作原理是"向前预读"——扫描除 PostgreSQL 当前通过 archive_command 请求的文件外，还有哪些 WAL 段已就绪可归档。WAL 段直接从 pg_xlog/pg_wal 目录传输到归档存储，只有确认 WAL 段已安全入库后，archive_command 才返回成功。

缓冲区路径用于记录当前 WAL 归档的状态。写入其中的状态文件通常为零字节，整体占用空间极少（最多几 MB），IO 开销也很小。目录中的所有信息均可重建，因此将集群迁移到新硬件时无需保留缓冲区目录。

重要提示：

早期实现中，WAL 段会先复制到缓冲区目录再进行压缩和传输；新实现则直接从 pg_xlog 目录读取 WAL。如果曾在 v1.12 或更早版本中使用异步归档，请在升级前仔细阅读 v1.13 的发版说明。

可通过 [stanza]-archive-push-async.log 文件监控异步进程的活动。快速连续推送多个 WAL 段是验证并行归档的好方法。

pg-primary ⇒ 测试并行异步归档

BASH
sudo -u postgres psql -c " \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal();"

sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=2581-64d295fa --log-level-console=info --log-level-file=detail --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --repo1-host=repository --stanza=demo
P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 00000007000000000000002D successfully archived to '/var/lib/pgbackrest/archive/demo/17-1/0000000700000000/00000007000000000000002D-d2d2b7910f776f59b73a176513de8e15846608b8.gz' on repo1

P00   INFO: check command end: completed successfully

此时日志文件中将包含并行异步归档的详细记录。

pg-primary ⇒ 查看日志中的结果

BASH
sudo -u postgres cat /var/log/pgbackrest/demo-archive-push-async.log
TEXT
-------------------PROCESS START-------------------
P00   INFO: archive-push:async command begin 2.59.0: [/var/lib/postgresql/17/demo/pg_wal] --archive-async --exec-id=2567-fdf7e175 --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --process-max=2 --repo1-host=repository --spool-path=/var/spool/pgbackrest --stanza=demo

P00   INFO: push 1 WAL file(s) to archive: 000000070000000000000028
P01 DETAIL: pushed WAL file '000000070000000000000028' to the archive

P00   INFO: archive-push:async command end: completed successfully

-------------------PROCESS START-------------------
P00   INFO: archive-push:async command begin 2.59.0: [/var/lib/postgresql/17/demo/pg_wal] --archive-async --exec-id=2585-277ad4a9 --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --process-max=2 --repo1-host=repository --spool-path=/var/spool/pgbackrest --stanza=demo

P00   INFO: push 5 WAL file(s) to archive: 000000070000000000000029...00000007000000000000002D
P02 DETAIL: pushed WAL file '00000007000000000000002A' to the archive
P01 DETAIL: pushed WAL file '000000070000000000000029' to the archive
P02 DETAIL: pushed WAL file '00000007000000000000002B' to the archive
P01 DETAIL: pushed WAL file '00000007000000000000002C' to the archive
P02 DETAIL: pushed WAL file '00000007000000000000002D' to the archive

P00   INFO: archive-push:async command end: completed successfully

归档获取（Archive Get）

异步 archive-get 命令通过维护本地 WAL 队列来提升吞吐量。若队列中找不到所需的 WAL 段，则会从仓库获取该段及足够多的后续 WAL 来填满队列。队列的最大容量由 archive-get-queue-max 定义，当队列剩余容量不足一半时，会自动补充获取。

在 WAL 生成量较大、或与仓库存储（如 S3 等对象存储）连接延迟较高的环境中，异步模式的收益最为显著。高延迟场景下，适当调大 process-max 通常有助于进一步提升性能。

可通过 [stanza]-archive-get-async.log 文件监控异步进程的活动。

pg-standby ⇒ 查看日志中的结果

BASH
sudo -u postgres cat /var/log/pgbackrest/demo-archive-get-async.log
TEXT
-------------------PROCESS START-------------------
P00   INFO: archive-get:async command begin 2.59.0: [000000070000000000000024, 000000070000000000000025, 000000070000000000000026, 000000070000000000000027, 000000070000000000000028, 000000070000000000000029, 00000007000000000000002A, 00000007000000000000002B] --archive-async --exec-id=707-b9ced134 --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --process-max=2 --repo1-host=repository --spool-path=/var/spool/pgbackrest --stanza=demo
P00   INFO: get 8 WAL file(s) from archive: 000000070000000000000024...00000007000000000000002B

P01 DETAIL: found 000000070000000000000024 in the repo1: 17-1 archive
P02 DETAIL: found 000000070000000000000025 in the repo1: 17-1 archive
P01 DETAIL: found 000000070000000000000026 in the repo1: 17-1 archive
P02 DETAIL: found 000000070000000000000027 in the repo1: 17-1 archive

P00 DETAIL: unable to find 000000070000000000000028 in the archive
P00   INFO: archive-get:async command end: completed successfully
       [filtered 14 lines of output]
P00   INFO: archive-get:async command begin 2.59.0: [000000070000000000000028, 000000070000000000000029, 00000007000000000000002A, 00000007000000000000002B, 00000007000000000000002C, 00000007000000000000002D, 00000007000000000000002E, 00000007000000000000002F] --archive-async --exec-id=752-5e97a136 --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --process-max=2 --repo1-host=repository --spool-path=/var/spool/pgbackrest --stanza=demo
P00   INFO: get 8 WAL file(s) from archive: 000000070000000000000028...00000007000000000000002F

P01 DETAIL: found 000000070000000000000028 in the repo1: 17-1 archive
P02 DETAIL: found 000000070000000000000029 in the repo1: 17-1 archive
P01 DETAIL: found 00000007000000000000002A in the repo1: 17-1 archive

P00 DETAIL: unable to find 00000007000000000000002B in the archive
P00   INFO: archive-get:async command end: completed successfully
       [filtered 2 lines of output]
P00   INFO: archive-get:async command begin 2.59.0: [00000007000000000000002B, 00000007000000000000002C, 00000007000000000000002D, 00000007000000000000002E, 00000007000000000000002F, 000000070000000000000030, 000000070000000000000031] --archive-async --exec-id=761-af866388 --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/postgresql/17/demo --process-max=2 --repo1-host=repository --spool-path=/var/spool/pgbackrest --stanza=demo
P00   INFO: get 7 WAL file(s) from archive: 00000007000000000000002B...000000070000000000000031

P02 DETAIL: found 00000007000000000000002C in the repo1: 17-1 archive
P01 DETAIL: found 00000007000000000000002B in the repo1: 17-1 archive
P02 DETAIL: found 00000007000000000000002D in the repo1: 17-1 archive

P00 DETAIL: unable to find 00000007000000000000002E in the archive
P00   INFO: archive-get:async command end: completed successfully
       [filtered 17 lines of output]

pg-primary ⇒ 通过更改复制密码恢复流复制

BASH
sudo -u postgres psql -c "alter user replicator password 'jw8s0F4'"
SQL
ALTER ROLE

从备库备份

pgBackRest 支持从备库而非主库执行备份。从备库备份需要配置 pg-standby 主机并启用 backup-standby 选项。若配置了多个备库，则使用第一个处于运行状态的备库进行备份。

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pg2-host/pg2-host-user 和 pg2-path

INI
[demo]
pg1-host=pg-primary
pg1-path=/var/lib/postgresql/17/demo
pg2-host=pg-standby
pg2-path=/var/lib/postgresql/17/demo
[demo-alt]
pg1-host=pg-alt
pg1-path=/var/lib/postgresql/17/demo
[global]
backup-standby=y
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y

执行备份时，主库和备库均须在线，但绝大多数文件将从备库复制，以减轻主库的 I/O 压力。数据库主机可按任意顺序配置，pgBackRest 会自动识别主库和备库的角色。

repository ⇒ 从 pg2 备份演示集群

BASH
sudo -u pgbackrest pgbackrest --stanza=demo --log-level-console=detail backup
TEXT
       [filtered 2 lines of output]
P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000007000000000000002F, lsn = 0/2F000028

P00   INFO: wait for replay on the standby to reach 0/2F000028
P00   INFO: replay on the standby reached 0/2F000028

P00   INFO: check archive for prior segment 00000007000000000000002E

P01 DETAIL: backup file pg-primary:/var/lib/postgresql/17/demo/global/pg_control (8KB, 0.53%) checksum 2fef26e26ab8ddbe9e264353b23ff2e2dc12d814

P01 DETAIL: match file from prior backup pg-primary:/var/lib/postgresql/17/demo/pg_logical/replorigin_checkpoint (8B, 0.53%) checksum 347fc8f2df71bd4436e38bd1516ccd7ea0d46532
P02 DETAIL: backup file pg-standby:/var/lib/postgresql/17/demo/base/5/1249 (448KB, 30.16%) checksum 317023e2773903a20f6633ef1ae9066fccbf9192
       [filtered 1278 lines of output]

从该增量备份的输出可以看出，绝大多数文件从 pg-standby 主机复制，只有极少数文件来自 pg-primary。

pgBackRest 从备库创建的备份与在主库上创建的备份完全等效。其实现方式为：在 pg-primary 上执行备份的启动和停止操作，从 pg-standby 复制已复制的文件，再从 pg-primary 补充少量剩余文件。因此，主库的日志和统计信息也会完整纳入备份。

升级 PostgreSQL

将 PostgreSQL 升级到新的主版本后，必须立即将所有 pgBackRest 配置中的 pg-path 更新为新的数据目录路径，并运行 stanza-upgrade 命令。若主机上配置了多个仓库，则每个仓库上的 stanza 都会一并升级。若数据库处于离线状态，请加上 --no-online 选项。

以下步骤并非 PostgreSQL 升级的完整指南，而是概要介绍了升级主库和备库的一般流程，重点展示重新配置 pgBackRest 所需的操作。建议在升级前先执行一次全量备份。

pg-primary ⇒ 停止旧集群

BASH
sudo pg_ctlcluster 17 demo stop

由于备库将从升级后的新集群恢复，因此备库上的旧集群也需要一并停止。

pg-standby ⇒ 停止旧集群

BASH
sudo pg_ctlcluster 17 demo stop

初始化新版本的集群并执行升级。

pg-primary ⇒ 创建新集群并执行升级

BASH
sudo -u postgres /usr/lib/postgresql/18/bin/initdb \
       -D /var/lib/postgresql/18/demo -k -A peer

sudo pg_createcluster 18 demo
sudo -u postgres sh -c 'cd /var/lib/postgresql && \
       /usr/lib/postgresql/18/bin/pg_upgrade \
       --old-bindir=/usr/lib/postgresql/17/bin \
       --new-bindir=/usr/lib/postgresql/18/bin \
       --old-datadir=/var/lib/postgresql/17/demo \
       --new-datadir=/var/lib/postgresql/18/demo \
       --old-options=" -c config_file=/etc/postgresql/17/demo/postgresql.conf" \
       --new-options=" -c config_file=/etc/postgresql/18/demo/postgresql.conf"'
TEXT
       [filtered 44 lines of output]
Checking for extension updates                                ok

Upgrade Complete

----------------
Some statistics are not transferred by pg_upgrade.
       [filtered 4 lines of output]

配置新集群的参数。

pg-primary:/etc/postgresql/18/demo/postgresql.conf ⇒ 配置 PostgreSQL

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

更新所有主机上的 pgBackRest 配置，将 pg-path 指向新集群的数据目录。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 升级 pg1-path

INI
[demo]
pg1-path=/var/lib/postgresql/18/demo
[global]
archive-async=y
log-level-file=detail
repo1-host=repository
spool-path=/var/spool/pgbackrest
[global:archive-get]
process-max=2
[global:archive-push]
process-max=2

pg-standby:/etc/pgbackrest/pgbackrest.conf ⇒ 升级 pg-path

INI
[demo]
pg1-path=/var/lib/postgresql/18/demo
recovery-option=primary_conninfo=host=172.17.0.6 port=5432 user=replicator
[global]
archive-async=y
log-level-file=detail
repo1-host=repository
spool-path=/var/spool/pgbackrest
[global:archive-get]
process-max=2
[global:archive-push]
process-max=2

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 升级 pg1-path 和 pg2-path，禁用从备库备份

INI
[demo]
pg1-host=pg-primary
pg1-path=/var/lib/postgresql/18/demo
pg2-host=pg-standby
pg2-path=/var/lib/postgresql/18/demo
[demo-alt]
pg1-host=pg-alt
pg1-path=/var/lib/postgresql/17/demo
[global]
backup-standby=n
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y

pg-primary ⇒ 复制 hba 配置文件

BASH
sudo cp /etc/postgresql/17/demo/pg_hba.conf \
       /etc/postgresql/18/demo/pg_hba.conf

启动新集群前，必须先运行 stanza-upgrade 命令完成 stanza 升级。

pg-primary ⇒ 升级 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --no-online \
       --log-level-console=info stanza-upgrade
TEXT
P00   INFO: stanza-upgrade command begin 2.59.0: --exec-id=3008-04f6b03b --log-level-console=info --log-level-file=detail --no-log-timestamp --no-online --pg1-path=/var/lib/postgresql/18/demo --repo1-host=repository --stanza=demo
P00   INFO: stanza-upgrade for stanza 'demo' on repo1

P00   INFO: stanza-upgrade command end: completed successfully

启动新集群并验证配置。

pg-primary ⇒ 启动新集群

BASH
sudo pg_ctlcluster 18 demo start

使用 check 命令验证配置。

pg-primary ⇒ 检查配置

BASH
sudo pg_lsclusters
sudo -u postgres pgbackrest --stanza=demo check

确认无误后，删除旧版本集群。

pg-primary ⇒ 删除旧集群

BASH
sudo pg_dropcluster 17 demo

在备库上安装新版本的 PostgreSQL 并创建集群。

pg-standby ⇒ 删除旧集群并创建新集群

BASH
sudo pg_dropcluster 17 demo
sudo pg_createcluster 18 demo

在仓库主机上运行 check 命令。由于备库集群尚未启动，出现备库不可用的警告属于预期行为。执行此命令是为了确认仓库主机已感知到备库的存在，且主库端配置正确。

repository ⇒ 检查配置

BASH
sudo -u pgbackrest pgbackrest --stanza=demo check
TEXT
P00   WARN: unable to check pg2: [DbConnectError] raised from remote-0 ssh protocol on 'pg-standby': unable to connect to 'dbname='postgres' port=5432': connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: No such file or directory
            	Is the server running locally and accepting connections on that socket?

对新集群执行全量备份，再从备份中恢复备库。若指定 incr 或 diff 类型，pgBackRest 会自动将其升级为 full。

repository ⇒ 运行全量备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo --type=full backup

pg-standby ⇒ 恢复演示备库集群

BASH
sudo -u postgres pgbackrest --stanza=demo --delta --type=standby restore

pg-standby:/etc/postgresql/18/demo/postgresql.conf ⇒ 配置 PostgreSQL

INI
hot_standby = on

pg-standby ⇒ 启动 PostgreSQL 并检查 pgBackRest 配置

BASH
sudo pg_ctlcluster 18 demo start
sudo -u postgres pgbackrest --stanza=demo check

备库恢复并正常运行后，即可重新启用从备库备份功能。

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 重新启用从备库备份

INI
[demo]
pg1-host=pg-primary
pg1-path=/var/lib/postgresql/18/demo
pg2-host=pg-standby
pg2-path=/var/lib/postgresql/18/demo
[demo-alt]
pg1-host=pg-alt
pg1-path=/var/lib/postgresql/17/demo
[global]
backup-standby=y
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y

3 - 用户指南（RHEL/Rocky/CentOS）

面向 RHEL、Rocky Linux 和 AlmaLinux 系统的 pgBackRest 安装配置与使用指南，按步骤逐一讲解。

原始页面： https://pgbackrest.org/user-guide-rhel.html

简介

本用户指南设计为从头到尾顺序阅读——每个章节都依赖前一章节的内容。例如， 恢复 章节依赖 快速开始 章节中完成的配置。熟悉 pgBackRest 之后可以跳章查阅，但初次阅读建议按顺序跟随。

本指南的示例基于 RHEL 和 PostgreSQL 14，但迁移到其他 Unix 发行版或 PostgreSQL 版本并不困难。与操作系统相关的命令仅限于创建、启动、停止和删除 PostgreSQL 集群的部分；pgBackRest 命令在所有 Unix 系统上均相同，只是可执行文件路径可能有所不同。pgBackRest 致力于在各 PostgreSQL 版本间保持一致的行为，但不同版本间存在细微差异，这些差异可能体现在本指南的部分示例中，例如 PostgreSQL 路径、文件名和配置项。

有关 PostgreSQL 的配置信息，请参阅 PostgreSQL 手册。

本指南在文档方面采用了一种较为新颖的方式：每条命令在从 XML 源构建文档时都会在虚拟机上实际执行，因此可以确信这些命令按照所呈现的顺序正确运行。相关命令的输出会显示在命令下方；若未包含输出，则是因为其与说明无关或会干扰行文。

所有命令均预期以具有 root 和 postgres 用户 sudo 权限的非特权用户身份运行。也可以直接以对应用户身份运行，去掉 sudo 即可。

核心概念

以下概念与 pgBackRest、PostgreSQL 以及本用户指南密切相关。

备份

备份是数据库集群的一致性副本，可用于从硬件故障中恢复、执行时间点恢复（PITR），或启动新的备库。

全量备份（full backup）：pgBackRest 将数据库集群的全部内容复制到备份中。数据库集群的第一次备份始终是全量备份。pgBackRest 始终能够直接恢复全量备份。全量备份的一致性不依赖于备份外部的任何文件。

差异备份（differential backup）：pgBackRest 仅复制自上次全量备份以来发生变化的数据库集群文件。pgBackRest 通过复制所选差异备份中的所有文件以及上一次全量备份中相应的未变化文件来恢复差异备份。差异备份的优点是比全量备份占用更少的磁盘空间，但差异备份和全量备份必须都有效才能恢复差异备份。

增量备份（incremental backup）：pgBackRest 仅复制自上次备份（可以是另一次增量备份、差异备份或全量备份）以来发生变化的文件，因此通常比全量备份或差异备份小得多。与差异备份一样，增量备份依赖于其他备份的有效性才能恢复。恢复增量备份需要：所有在上一次差异备份之前的增量备份、上一次差异备份以及上一次全量备份都有效。若不存在差异备份，则需要追溯到上一次全量备份的所有增量备份以及全量备份本身都有效。

恢复

恢复是将备份复制到某个系统并作为活跃数据库集群启动的过程，需要备份文件和一个或多个 WAL 段才能正确完成。

预写日志（WAL）

WAL 是 PostgreSQL 确保已提交更改不会丢失的机制。事务按顺序写入 WAL，待这些写入刷盘后，事务即视为已提交。随后，后台进程将变更写入主数据库集群文件（即堆）。发生崩溃时，PostgreSQL 会重放 WAL 以恢复数据库一致性。

WAL 在概念上是连续无限的，但在实践中被切分为每个 16MB 的独立文件，称为 WAL 段。WAL 段遵循 0000000100000A1E000000FE 这样的命名约定，其中前 8 个十六进制数字表示时间线，后 16 位是逻辑序列号（LSN）。

加密

加密是将数据转换为无法识别格式的过程，只有提供正确的密码（口令）才能还原。

pgBackRest 使用用户提供的密码对仓库进行加密，防止未经授权的访问。

升级 pgBackRest

从 v2.x 升级到 v2.y

从 v2.x 升级到 v2.y 非常简单。仓库格式没有改变，大多数安装只需替换新版本的二进制文件即可。若没有用到旧版本不支持的新功能，也可以降级。

重要提示：

本地和远程 pgBackRest 版本必须完全匹配，因此应一起升级。若版本不匹配，WAL 归档和备份将无法正常工作，直到版本一致为止，此时会报告以下错误：[ProtocolError] expected value '2.x' for greeting key 'version' but got '2.y'。

编译构建

推荐通过软件包安装 pgBackRest，而非从源码构建。有关软件包的更多信息，请参阅 安装 章节。

如需从源码构建，建议在专用构建主机上进行，而非生产环境——构建所需的许多工具不应出现在生产系统上。pgBackRest 由单个可执行文件构成，构建完成后可方便地复制到目标主机。

build ⇒ 将 pgBackRest 版本 2.59.0 下载到 /build 路径

BASH
mkdir -p /build
curl -fsSL \
       https://github.com/pgbackrest/pgbackrest/releases/download/release%2F2.59.0/pgbackrest-2.59.0.tar.gz | \
       tar zx -C /build

build ⇒ 安装构建依赖

BASH
sudo yum install meson gcc postgresql14-devel openssl-devel libxml2-devel \
       lz4-devel libzstd-devel bzip2-devel libssh2-devel systemd-devel

build ⇒ 配置并编译 pgBackRest

BASH
meson setup /build/pgbackrest /build/pgbackrest-2.59.0
ninja -C /build/pgbackrest

build ⇒ 可选：运行冒烟测试，确认 pgBackRest 已正确构建

BASH
meson test -C /build/pgbackrest --suite smoke
ninja: Entering directory `/build/pgbackrest'
ninja: no work to do.
TEXT
1/1 smoke OK               12.24s
Ok:                 1
       [filtered 6 lines of output]

安装

创建一台名为 pg-primary 的新主机，用于承载演示集群并运行 pgBackRest 示例。

推荐通过包安装 pgBackRest，而非从源码构建。通过包安装时，本节后续步骤通常不需要手动执行，但某些包可能会跳过创建目录或权限设置有误。遇到这种情况时，手动创建目录或更新权限即可。

RHEL 平台的 pgBackRest 包可在 yum.postgresql.org 获取。

如果所用发行版/版本没有提供包，可以 从源码构建 后手动安装，步骤如下。

pg-primary ⇒ 安装依赖项

BASH
sudo yum install postgresql-libs libssh2

pg-primary ⇒ 从构建主机复制 pgBackRest 二进制文件

BASH
sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin
sudo chmod 755 /usr/bin/pgbackrest

pgBackRest 需要日志目录、配置目录和配置文件。

pg-primary ⇒ 创建 pgBackRest 配置文件和目录

BASH
sudo mkdir -p -m 770 /var/log/pgbackrest
sudo chown postgres:postgres /var/log/pgbackrest
sudo mkdir -p /etc/pgbackrest
sudo mkdir -p /etc/pgbackrest/conf.d
sudo touch /etc/pgbackrest/pgbackrest.conf
sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf

pgBackRest 现在应已正确安装，建议验证一下。若有依赖项缺失，命令行运行 pgBackRest 时会出现相应错误。

pg-primary ⇒ 确认安装成功

BASH
sudo -u postgres pgbackrest

pgBackRest 2.59.0 - General help

Usage:
    pgbackrest [options] [command]

Commands:
    annotate        add or modify backup annotation
    archive-get     get a WAL segment from the archive
    archive-push    push a WAL segment to the archive
    backup          backup a database cluster
    check           check the configuration
    expire          expire backups that exceed retention
    help            get help
    info            retrieve information about backups
    repo-get        get a file from a repository
    repo-ls         list files in a repository
    restore         restore a database cluster
    server          pgBackRest server
    server-ping     ping pgBackRest server
    stanza-create   create the required stanza data
    stanza-delete   delete a stanza
    stanza-upgrade  upgrade a stanza
    start           allow pgBackRest processes to run
    stop            stop pgBackRest processes from running
    verify          verify contents of a repository
    version         get version

Use 'pgbackrest help [command]' for more information.

快速开始

本章介绍 pgBackRest 和 PostgreSQL 的基本配置，并演示 backup、restore 和 info 命令的用法。

创建演示集群

创建演示集群是可选的，但强烈推荐——尤其对新用户而言，因为本指南的所有示例命令都引用该演示集群，且假设它运行在默认端口（5432）上。由于还有一些配置工作要完成，集群将在后续章节中才会启动。

pg-primary ⇒ 创建演示集群

BASH
sudo -u postgres /usr/pgsql-14/bin/initdb \
       -D /var/lib/pgsql/14/data -k -A peer

RHEL 默认在日志文件名中包含星期几，这会使用户指南的示例变得复杂，因此将 log_filename 设置为固定值。

pg-primary:/var/lib/pgsql/14/data/postgresql.conf ⇒ 设置 log_filename

INI
log_filename = 'postgresql.log'

配置集群 Stanza

stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称，定义了集群的位置、备份方式、归档选项等。大多数数据库服务器只有一个 PostgreSQL 集群，因此只有一个 stanza；备份服务器则为每个需要备份的数据库集群各配置一个 stanza。

命名 stanza 时，以主集群名称命名是常见做法，但更好的方式是描述集群所承载的业务数据。由于 stanza 名称会同时用于主库和所有副本，选择描述集群功能的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

demo 准确描述了该集群的用途，因此也是一个恰当的 stanza 名称。

pgBackRest 需要知道 PostgreSQL 集群数据目录的位置。该路径可以直接从 PostgreSQL 获取，但在恢复场景中 PostgreSQL 进程不可用。备份过程中，pgBackRest 会将配置中的路径与 PostgreSQL 实际运行的路径进行比较，两者必须完全一致，否则备份会报错。请确保 pg-path 与 PostgreSQL 报告的 data_directory 完全匹配。

RHEL 默认将集群数据存储在 /var/lib/pgsql/[version]/data，因此数据目录路径很容易确定。

创建 /etc/pgbackrest/pgbackrest.conf 时，必须赋予数据库所有者（通常是 postgres）读取权限。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 PostgreSQL 集群数据目录

INI
[demo]
pg1-path=/var/lib/pgsql/14/data

pgBackRest 配置文件采用类 Windows INI 的格式。节（section）以方括号中的文本表示，键/值对包含在各节中。以 # 开头的行被视为注释而忽略，但不支持在值后的同一行添加行尾注释。不支持引号，键和值会自动去除首尾空白。同一节若出现多次，将被合并处理。

pgBackRest 配置文件有多种加载方式：

  • config 和 config-include-path 均为默认值：若默认配置文件存在则加载，若默认配置包含路径存在则追加其中的 *.conf 文件。
  • 指定了 config 选项：仅加载指定的配置文件，该文件必须存在。
  • 指定了 config-include-path：加载该路径下的 *.conf 文件，路径必须存在；同时若默认配置文件存在也会加载。如只希望加载指定路径中的文件，可同时传递 --no-config 选项。
  • 同时指定了 config 和 config-include-path：使用用户指定的值，加载配置文件并追加指定包含路径中的 *.conf 文件，这些文件均预期存在。
  • 指定了 config-path：此设置会覆盖配置文件默认基路径和/或默认 config-include-path 的基路径，除非显式设置了 config 和/或 config-include-path 选项。

所有配置文件会被拼接，相当于一个大文件，每个文件必须各自有效。这意味着需要在每个文件中为所需的键/值对指定对应的节。顺序不影响结果，但节有基于类型的优先级。优先级从高到低为：

  • [stanza:command]
  • [stanza]
  • [global:command]
  • [global]

注意：

--config、--config-include-path 和 --config-path 仅是命令行选项。

pgBackRest 也可以通过环境变量进行配置（如下示例所示），适用于 backup、restore 和 archive-push 等命令。

pg-primary ⇒ 使用环境变量配置 log-path

BASH
sudo -u postgres bash -c ' \
       export PGBACKREST_LOG_PATH=/path/set/by/env && \
       pgbackrest --log-level-console=error help backup log-path'

pgBackRest 2.59.0 - 'backup' command - 'log-path' option help

Path where log files are stored.

The log path provides a location for pgBackRest to store log files. Note that
if log-level-file=off then no log path is required.
TEXT
current: /path/set/by/env

default: /var/log/pgbackrest

创建仓库

仓库是 pgBackRest 存储备份和归档 WAL 段的位置。

提前精确估算所需空间并不容易。较好的做法是先执行几次备份，记录不同类型备份（full/incr/diff）的大小，并统计每日产生的 WAL 量，由此对空间需求形成大致判断——尽管随着数据库的演变，需求会随时间变化。

本演示将仓库存储在与 PostgreSQL 服务器相同的主机上，这是最简单的配置，适用于通过传统备份软件对数据库主机进行整机备份的场景。

pg-primary ⇒ 创建 pgBackRest 仓库

BASH
sudo mkdir -p /var/lib/pgbackrest
sudo chmod 750 /var/lib/pgbackrest
sudo chown postgres:postgres /var/lib/pgbackrest

需要配置仓库路径，以便 pgBackRest 知道仓库的位置。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pgBackRest 仓库路径

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-path=/var/lib/pgbackrest

也可以配置多个仓库，详见 多仓库 章节。

配置归档

备份正在运行的 PostgreSQL 集群需要启用 WAL 归档。%p 是 PostgreSQL 传递待归档 WAL 段路径的占位符。注意，即使没有对集群进行显式写入，备份过程中也会生成 至少 一个 WAL 段。

pg-primary:/var/lib/pgsql/14/data/postgresql.conf ⇒ 配置归档设置

INI
archive_command = 'pgbackrest --stanza=demo archive-push %p'
archive_mode = on
log_filename = 'postgresql.log'

完成以上更改后，必须重启 PostgreSQL 集群使配置生效。

pg-primary ⇒ 重启演示集群

BASH
sudo systemctl restart postgresql-14.service

若归档单个 WAL 段预计超过 60 秒（默认值）才能到达仓库，应适当增大 pgBackRest 的 archive-timeout 选项。注意，此选项与 PostgreSQL 的 archive_timeout 不同——后者用于强制切换 WAL 段，适用于长时间没有写入的数据库。有关 PostgreSQL archive_timeout 的更多信息，请参阅 PostgreSQL 预写日志 文档。

archive-push 命令可以单独配置选项。例如，可以为归档设置较低的压缩级别以提升速度，而不影响备份的压缩设置。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 archive-push 使用较低的压缩级别

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-path=/var/lib/pgbackrest
[global:archive-push]
compress-level=3

这种配置方式适用于任何命令，也可以针对特定 stanza 进一步细化，例如 demo:archive-push。

配置保留策略

pgBackRest 根据保留策略选项对备份执行过期（轮转）操作。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置保留 2 个全量备份

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
[global:archive-push]
compress-level=3

有关保留策略的更多信息，请参阅 保留策略 章节。

配置仓库加密

本节为仓库配置加密类型和密钥，演示加密功能。无论仓库类型（如 S3 或其他对象存储）是否自带加密，pgBackRest 的加密始终在客户端执行。

密钥应使用长随机口令，推荐通过 openssl rand -base64 48 生成。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pgBackRest 仓库加密

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
[global:archive-push]
compress-level=3

注意：

上面的加密设置放在 [global] 配置节中，以便 info 命令读取所有 stanza。未指定 stanza 选项时，info 只从 [global] 配置节读取加密设置；因此，按 stanza 配置加密时，必须为 info 指定 stanza 才能读取加密 stanza。

仓库完成配置、stanza 创建并检查完毕后，加密设置不可更改。

创建 Stanza

需要运行 stanza-create 命令来初始化 stanza。建议在 stanza-create 之后运行 check 命令，验证归档和备份配置是否正确。

pg-primary ⇒ 创建 stanza 并检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create
TEXT
P00   INFO: stanza-create command begin 2.59.0: --exec-id=1199-1f088435 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo
P00   INFO: stanza-create for stanza 'demo' on repo1

P00   INFO: stanza-create command end: completed successfully

检查配置

check 命令验证 pgBackRest 和 archive_command 是否为指定 stanza 正确配置了归档和备份。它会检查运行该命令的主机上配置的所有仓库和数据库，并能发现配置错误——尤其是因所需 WAL 段未能到达归档而导致备份不完整的问题。该命令可在 PostgreSQL 主机或仓库主机上运行。也可以在备库主机上运行，但由于备库无法执行 pg_switch_xlog()/pg_switch_wal()，此时只会测试仓库配置。

注意：check 命令会调用 pg_create_restore_point('pgBackRest Archive Check') 和 pg_switch_xlog()/pg_switch_wal()，以强制 PostgreSQL 归档一个 WAL 段。

pg-primary ⇒ 检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=1232-98ddd13f --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo
P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 000000010000000000000001 successfully archived to '/var/lib/pgbackrest/archive/demo/14-1/0000000100000000/000000010000000000000001-95e05e4799302297b1d3e23fa830dd5e2c853776.gz' on repo1

P00   INFO: check command end: completed successfully

性能调优

pgBackRest 有许多性能选项，为保持仓库的向后兼容性，这些选项默认未启用。创建新仓库时，建议启用以下选项。这些选项也可用于现有仓库，但需注意较旧版本的 pgBackRest 将无法读取该仓库——具体兼容性取决于各功能的引入版本，详见下列说明。

  • compress-type — 决定 backup 和 archive-push 命令使用的压缩算法。默认为 gz（Gzip），但推荐使用 zst（Zstandard），后者速度更快，压缩率与 gz 相近。zst 自 v2.27 起受 compress-type 支持。详见 压缩类型。
  • repo-bundle — 备份时将小文件合并打包，节省空间并提升 backup 和 restore 的速度，在 S3 等对象存储上效果尤为明显。该选项在 v2.39 中引入。详见 文件打包。
  • repo-block — 执行 diff/incr 备份时，仅存储文件中发生变化的部分，而非整个文件，从而节省空间并提升备份速度。该选项在 v2.46 中引入，但建议至少使用 v2.52.1。详见 块级增量备份。

还有一些性能选项默认未启用，原因是需要额外配置，或默认值虽安全但并非最优。这些选项在所有 v2 版本中均可用。

  • process-max — 控制命令使用的进程数，默认值为 1，几乎在任何场景下都不是合适的值。各命令对 process-max 的使用方式不同，详见各命令的文档。
  • archive-async — 批量将 WAL 文件归档到仓库，大幅提升归档吞吐量。默认未启用，因为需要额外创建缓冲区目录。详见 异步归档。
  • backup-standby — 在备库而非主库上执行备份，以减轻主库负载。默认未启用，因为需要额外配置，并且要求存在一个或多个备库。详见 从备库备份。

执行备份

默认情况下，pgBackRest 会等待下一个定期检查点完成后才开始备份。根据 PostgreSQL 的 checkpoint_timeout 和 checkpoint_segments 设置，等待时间可能较长。通常建议设置 start-fast=y，让备份立即启动——这会强制执行一次检查点，但由于备份一般每天只运行一次，额外的检查点对性能几乎没有影响。对于负载极高的集群，建议按需在命令行传递 --start-fast。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置备份快速启动

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

运行 pgBackRest 的 backup 命令即可对 PostgreSQL 集群执行备份。

pg-primary ⇒ 备份演示集群

BASH
sudo -u postgres pgbackrest --stanza=demo \
       --log-level-console=info backup
TEXT
P00   INFO: backup command begin 2.59.0: --exec-id=1326-1ed45d74 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-full=2 --stanza=demo --start-fast

P00   WARN: no prior backup exists, incr backup has been changed to full

P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 000000010000000000000002, lsn = 0/2000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 000000010000000000000002:000000010000000000000003
P00   INFO: new backup label = 20260720-004140F

P00   INFO: full backup size = 25.2MB, file total = 951

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=1326-1ed45d74 --log-level-console=info --no-log-timestamp --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-full=2 --stanza=demo

默认情况下，pgBackRest 尝试执行增量备份。增量备份必须基于全量备份，由于尚无全量备份，pgBackRest 自动改为执行全量备份。

type 选项用于指定备份类型（全量或差异）。

pg-primary ⇒ 对演示集群执行差异备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=diff \
       --log-level-console=info backup
TEXT
       [filtered 7 lines of output]
P00   INFO: check archive for segment(s) 000000010000000000000004:000000010000000000000005
P00   INFO: new backup label = 20260720-004140F_20260720-004143D

P00   INFO: diff backup size = 9.2KB, file total = 951

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=1396-28b52cd4 --log-level-console=info --no-log-timestamp --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-full=2 --stanza=demo

这次没有出现警告，因为全量备份已经存在。增量备份可以基于全量备份 或 差异备份，而差异备份只能基于全量备份。若要执行全量备份，加上 --type=full 选项即可。

在线备份期间，pgBackRest 会等待备份一致性所需的 WAL 段完成归档。等待时间由 archive-timeout 选项控制，默认为 60 秒。若已知单个 WAL 段的归档需要更长时间，应适当增大此值。

制定备份计划

可以使用 cron 等工具调度备份。

以下示例配置了两个 cron 任务：每周日早上 6:30 运行全量备份，周一至周六早上 6:30 运行差异备份。若此 crontab 在周中首次安装，pgBackRest 会在差异任务首次执行时自动改为运行全量备份，第二天再运行差异备份。

BASH
#m h   dom mon dow   command
30 06  *   *   0     pgbackrest --type=full --stanza=demo backup
30 06  *   *   1-6   pgbackrest --type=diff --stanza=demo backup

确定备份计划后，务必配置保留策略以定期清理旧备份，详见 保留策略。

备份信息

使用 info 命令获取备份信息。

pg-primary ⇒ 获取演示集群的信息

BASH
sudo -u postgres pgbackrest info
TEXT
stanza: demo
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (14): 000000010000000000000001/000000010000000000000005

        full backup: 20260720-004140F

            timestamp start/stop: 2026-07-20 00:41:40+00 / 2026-07-20 00:41:42+00
            wal start/stop: 000000010000000000000002 / 000000010000000000000003
            database size: 25.2MB, database backup size: 25.2MB
            repo1: backup set size: 3.2MB, backup size: 3.2MB

        diff backup: 20260720-004140F_20260720-004143D

            timestamp start/stop: 2026-07-20 00:41:43+00 / 2026-07-20 00:41:44+00
            wal start/stop: 000000010000000000000004 / 000000010000000000000005
            database size: 25.2MB, database backup size: 9.2KB
            repo1: backup set size: 3.2MB, backup size: 880B
            backup reference total: 1 full

info 命令可查询单个 stanza 或所有 stanza。默认输出为文本格式，以人类可读的方式显示备份摘要，该格式可能随版本发布而变化。

如需机器可读输出，请使用 --output=json。JSON 输出包含比文本格式更多的信息，且在未发现 bug 的情况下保持稳定。

若要加快执行速度，可指定 --detail-level=progress 将输出限制为仅进度信息，但这会跳过除 stanza 可用性之外的所有检查。

输出中每个 stanza 对应一个独立的节，可使用 --stanza 选项将输出限制为单个 stanza。status 字段简要说明 stanza 的健康状况：ok 表示运行正常；存在多个仓库时，mixed 表示 stanza 在一个或多个仓库上存在异常，此时会按仓库逐一列出状态；若仓库出现未知错误码的错误，将使用 other 并附上完整错误详情。wal archive min/max 显示归档中当前存储的最小和最大 WAL，若有多个仓库则跨所有仓库汇总报告（除非指定了 --repo）。注意，由于归档保留策略或其他原因，WAL 序列中可能存在间隙。

若有上述命令正在主机上运行，status 信息旁会出现 backup/expire running 和/或 restore running 提示。文本输出还会报告各仓库的进度，JSON 输出中则会包含 repo 数组。

备份按从旧到新的顺序显示。最旧的备份 始终 是全量备份（标签末尾为 F），最新的备份则可能是全量备份、差异备份（末尾为 D）或增量备份（末尾为 I）。

timestamp start/stop 定义了备份的执行时间段。timestamp stop 可用于判断时间点恢复时应选择哪个备份。有关时间点恢复的更多信息，请参阅 时间点恢复 章节。

wal start/stop 定义了恢复时使数据库达到一致性所需的 WAL 范围，backup 命令在完成前会确保此范围内的 WAL 已全部归档。

database size 是数据库的完整未压缩大小，database backup size 是实际需要备份的数据量（全量备份时两者相同）。

repo 标识备份所在的仓库。backup set size 包含该备份及恢复所需的所有引用备份中的文件总量，backup size 仅包含该备份自身的文件（全量备份时两者相同）。若启用了压缩，仓库大小反映压缩后的大小。

backup reference total 汇总了恢复该备份所需的其他备份。使用 --set 选项可显示完整的引用列表。

恢复备份

备份可以防范多种灾难场景，最常见的是硬件故障和数据损坏。模拟数据损坏最简单的方法是删除某个关键的 PostgreSQL 集群文件。

pg-primary ⇒ 停止演示集群并删除 pg_control 文件

BASH
sudo systemctl stop postgresql-14.service
sudo -u postgres rm /var/lib/pgsql/14/data/global/pg_control

缺少这个关键文件时，集群将无法启动。

pg-primary ⇒ 尝试启动已损坏的演示集群

BASH
sudo systemctl start postgresql-14.service
sudo systemctl status postgresql-14.service
TEXT
postgresql-14.service - PostgreSQL 14 database server
    Loaded: loaded (/usr/lib/systemd/system/postgresql-14.service, disabled)

    Active: failed (failed)

恢复 PostgreSQL 集群的备份，使用 pgBackRest 的 restore 命令即可。集群必须处于停止状态（本例已停止），且需先清空 PostgreSQL 数据目录中的所有文件。

pg-primary ⇒ 从演示集群中删除旧文件

BASH
sudo -u postgres find /var/lib/pgsql/14/data -mindepth 1 -delete

pg-primary ⇒ 恢复演示集群并启动 PostgreSQL

BASH
sudo -u postgres pgbackrest --stanza=demo restore
sudo systemctl start postgresql-14.service

这次集群成功启动，因为恢复操作已补回了缺失的 pg_control 文件。

有关 restore 命令的更多信息，请参阅 恢复 章节。

监控

监控是任何生产系统的重要组成部分。市面上有众多监控工具，稍加处理即可将 pgBackRest 集成进去。

pgBackRest 可以 JSON 格式输出仓库信息，包含每个 stanza 的所有备份列表和 WAL 归档信息。

在 PostgreSQL 中

PostgreSQL 的 COPY 命令可将 pgBackRest 信息加载到表中。以下示例将该逻辑封装成函数，便于执行实时查询。

pg-primary ⇒ 为 PostgreSQL 加载 pgBackRest info 函数

BASH
sudo -u postgres cat \
       /var/lib/pgsql/pgbackrest/doc/example/pgsql-pgbackrest-info.sql
SQL
-- An example of monitoring pgBackRest from within PostgreSQL
--
-- Use copy to export data from the pgBackRest info command into the jsonb
-- type so it can be queried directly by PostgreSQL.

-- Create monitor schema
create schema monitor;

-- Get pgBackRest info in JSON format
create function monitor.pgbackrest_info()
    returns jsonb AS $$
declare
    data jsonb;
begin
    -- Create a temp table to hold the JSON data
    create temp table temp_pgbackrest_data (data text);

    -- Copy data into the table directly from the pgBackRest info command
    copy temp_pgbackrest_data (data)
        from program
            'pgbackrest --output=json info' (format text);

    select replace(temp_pgbackrest_data.data, E'\n', '\n')::jsonb
      into data
      from temp_pgbackrest_data;

    drop table temp_pgbackrest_data;

    return data;
end $$ language plpgsql;
BASH
sudo -u postgres psql -f \
       /var/lib/pgsql/pgbackrest/doc/example/pgsql-pgbackrest-info.sql

现在可以使用 monitor.pgbackrest_info() 函数查询某个 stanza 的上次成功备份时间和最新归档 WAL。

pg-primary ⇒ 查询上次成功备份时间和归档的 WAL

BASH
sudo -u postgres cat \
       /var/lib/pgsql/pgbackrest/doc/example/pgsql-pgbackrest-query.sql
SQL
-- Get last successful backup for each stanza
--
-- Requires the monitor.pgbackrest_info function.
with stanza as
(
    select data->'name' as name,
           data->'backup'->(
               jsonb_array_length(data->'backup') - 1) as last_backup,
           data->'archive'->(
               jsonb_array_length(data->'archive') - 1) as current_archive
      from jsonb_array_elements(monitor.pgbackrest_info()) as data
)
select name,
       to_timestamp(
           (last_backup->'timestamp'->>'stop')::numeric) as last_successful_backup,
       current_archive->>'max' as last_archived_wal
  from stanza;
BASH
sudo -u postgres psql -f \
       /var/lib/pgsql/pgbackrest/doc/example/pgsql-pgbackrest-query.sql
TEXT
  name  | last_successful_backup |    last_archived_wal
--------+------------------------+--------------------------
 "demo" | 2026-07-20 00:41:44+00 | 000000010000000000000005
(1 row)

备份

配置了多个仓库时，pgBackRest 默认备份到优先级最高的仓库（如 repo1），除非指定了 --repo 选项。

pgBackRest 没有内置调度器，建议通过 cron 或其他调度机制运行备份。

详情和示例请参阅 执行备份。

文件打包

将仓库中的文件打包在一起可以节省备份时间和仓库空间，在对象存储（如 S3）或块大小较大的文件系统上效果尤为明显。对象存储上每个文件的创建开销较高，极小文件的存储成本可能与大文件相当。

文件打包功能通过 repo-bundle 选项启用。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-bundle

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

不使用文件打包时，全量备份路径中会有 1000 多个文件；启用打包后文件总数大幅减少。另一个好处是，零长度文件不再单独存储（仅记录在清单（manifest）中），而普通备份中每个零长度文件都会独立占用一个文件。

pg-primary ⇒ 执行全量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=full backup

pg-primary ⇒ 检查文件总数

BASH
sudo -u postgres find /var/lib/pgbackrest/backup/demo/latest/ -type f | wc -l
TEXT
5

repo-bundle-size 和 repo-bundle-limit 选项可用于调优，但大多数情况下默认值已是最优。

文件打包虽然通常更高效，但也有一些缺点：从仓库手动检索文件变得更困难；对去重存储可能并不理想，因为每次全量备份的文件在包中排列方式都不同；文件包不支持断点续传，因此不宜将 repo-bundle-limit 设置过高。

块级增量备份

块级增量备份只存储文件中自上次备份以来发生变化的部分，而非整个文件，从而节省存储空间。

通过 repo-block 选项启用块级增量备份，对所有备份类型都启用时效果最佳，且必须同时启用文件打包功能。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-block

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

备份注解

用户可以为备份附加键/值对形式的注解，此选项可多次使用以添加多条注解。

pg-primary ⇒ 执行带注解的全量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --annotation=source="demo backup" \
       --annotation=key=value --type=full backup

通过 --set 指定备份时，info 命令的文本输出会显示注解；JSON 输出中则始终包含注解。

pg-primary ⇒ 获取演示集群的信息

BASH
sudo -u postgres pgbackrest --stanza=demo --set=20260720-004200F info
TEXT
stanza: demo
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (14): 000000020000000000000007/000000020000000000000009

        full backup: 20260720-004200F
            timestamp start/stop: 2026-07-20 00:42:00+00 / 2026-07-20 00:42:02+00
            wal start/stop: 000000020000000000000008 / 000000020000000000000009
            lsn start/stop: 0/8000028 / 0/9000050
            database size: 25.2MB, database backup size: 25.2MB
            repo1: backup size: 3.2MB
            database list: postgres (13755)

            annotation(s)

                key: value
                source: demo backup

备份时附加的注解，之后可使用 annotate 命令添加、修改或删除。

pg-primary ⇒ 修改备份注解

BASH
sudo -u postgres pgbackrest --stanza=demo --set=20260720-004200F \
       --annotation=key= --annotation=new_key=new_value annotate

sudo -u postgres pgbackrest --stanza=demo --set=20260720-004200F info
TEXT
stanza: demo
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (14): 000000020000000000000007/000000020000000000000009

        full backup: 20260720-004200F
            timestamp start/stop: 2026-07-20 00:42:00+00 / 2026-07-20 00:42:02+00
            wal start/stop: 000000020000000000000008 / 000000020000000000000009
            lsn start/stop: 0/8000028 / 0/9000050
            database size: 25.2MB, database backup size: 25.2MB
            repo1: backup size: 3.2MB
            database list: postgres (13755)

            annotation(s)

                new_key: new_value
                source: demo backup

保留策略

通常，保留尽可能多的备份有助于提供更大的 时间点恢复 窗口，但也必须兼顾磁盘空间等实际限制。保留策略选项负责在旧备份不再需要时将其删除。

pgBackRest 根据保留策略类型（数量或时间段）对全量备份进行轮转。指定数量时，过期逻辑只关注需保留多少个备份，与创建时间无关。差异备份也按数量管理，当其依赖的全量备份过期时，差异备份随之过期。增量备份不会被保留策略单独过期，始终随关联的全量备份或差异备份一起过期。详情与示例请参见 全量备份保留策略 和 差异备份保留策略 章节。

归档 WAL 默认与未过期备份一起保留；如有特殊需求，可通过各仓库的 retention-archive 选项调整此策略（不推荐）。详情与示例请参见 归档保留策略 章节。

expire 命令会在每次备份成功后自动运行，也可手动执行。手动运行时，会按各已配置仓库的保留策略执行过期操作。若指定了 --repo 选项，则仅对该仓库执行。还可以通过 --set 选项将过期操作限定到特定备份集；若未同时指定 --repo，则会搜索所有仓库并对符合条件的备份集执行过期。每次运行 expire 命令时都会检查并执行归档保留计划。

全量备份保留策略

repo1-retention-full-type 决定 repo1-retention-full 的解释方式：可以是保留的全量备份数量，也可以是保留天数。过期操作仅在新备份完成后触发。例如，若 repo1-retention-full-type=count 且 repo1-retention-full=2，则需要存储了三个全量备份之后才会过期最旧的那个；若 repo1-retention-full-type=time 且 repo1-retention-full=20，则只有当至少一个全量备份的存储时间超过 20 天时，才会触发过期操作。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-retention-full

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

目前已配置 repo1-retention-full=2，但当前只有一个全量备份，因此下次执行全量备份时不会过期任何旧备份。

pg-primary ⇒ 执行全量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=full \
       --log-level-console=detail backup
TEXT
       [filtered 963 lines of output]
P00   INFO: repo1: remove expired backup 20260720-004157F
P00 DETAIL: repo1: 14-1 archive retention on backup 20260720-004200F, start = 000000020000000000000008

P00   INFO: repo1: 14-1 remove archive, start = 000000020000000000000007, stop = 000000020000000000000007

P00   INFO: expire command end: completed successfully

归档 确实 被过期了，因为这些 WAL 段生成于最旧备份之前，对恢复没有意义——只有备份之后生成的 WAL 段才能用于恢复该备份。

pg-primary ⇒ 执行全量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=full \
       --log-level-console=info backup
TEXT
       [filtered 11 lines of output]
P00   INFO: repo1: expire full backup 20260720-004200F
P00   INFO: repo1: remove expired backup 20260720-004200F

P00   INFO: repo1: 14-1 remove archive, start = 000000020000000000000008, stop = 000000020000000000000009

P00   INFO: expire command end: completed successfully

全量备份 20260720-004140F 已被过期，归档保留策略现在以 20260720-004204F（当前最旧的全量备份）为基准。

差异备份保留策略

repo1-retention-diff 设置为需要保留的差异备份数量。差异备份只依赖于之前的全量备份，因此可以维护最近一天或更长时间内的"滚动"差异备份集合，既支持快速恢复到近期时间点，又能控制整体空间占用。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-retention-diff

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=1
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

已配置 repo1-retention-diff=1，因此需要执行两次差异备份才会过期其中一个。这里额外创建一个增量备份，用于演示增量备份的过期逻辑——本例中，增量备份随差异备份一起被过期。

pg-primary ⇒ 执行差异备份和增量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=diff backup
sudo -u postgres pgbackrest --stanza=demo --type=incr backup

再执行一次差异备份，之前的差异备份和增量备份将被过期，只保留最新的差异备份。

pg-primary ⇒ 执行差异备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=diff \
       --log-level-console=info backup
TEXT
       [filtered 10 lines of output]
P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=2635-96bf1097 --log-level-console=info --no-log-timestamp --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-diff=1 --repo1-retention-full=2 --stanza=demo

P00   INFO: repo1: expire diff backup set 20260720-004206F_20260720-004209D, 20260720-004206F_20260720-004210I

P00   INFO: repo1: remove expired backup 20260720-004206F_20260720-004210I
P00   INFO: repo1: remove expired backup 20260720-004206F_20260720-004209D
P00   INFO: expire command end: completed successfully

归档保留策略

pgBackRest 在过期备份时会自动删除对应的归档 WAL（默认按 repo1-retention-full 过期全量备份的 WAL），但有时可能需要更激进地过期归档以节省磁盘空间。需要注意，在差异归档保留策略中，全量备份被视为差异备份处理。

过期归档时，pgBackRest 永远不会删除维持备份一致性所必需的 WAL 段。但由于时间点恢复（PITR）只能在连续的 WAL 流上进行，在正常备份过期流程之外激进地过期归档时需格外谨慎。若要在不实际执行过期的情况下预览哪些内容将被删除，可在执行 expire 命令时添加 dry-run 选项。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-retention-diff

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
start-fast=y
[global:archive-push]
compress-level=3

pg-primary ⇒ 执行差异备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=diff \
       --log-level-console=info backup
TEXT
       [filtered 6 lines of output]
P00   INFO: backup stop archive = 000000020000000000000017, lsn = 0/17000050
P00   INFO: check archive for segment(s) 000000020000000000000016:000000020000000000000017

P00   INFO: new backup label = 20260720-004206F_20260720-004214D

P00   INFO: diff backup size = 11.5KB, file total = 951
P00   INFO: backup command end: completed successfully
       [filtered 2 lines of output]

pg-primary ⇒ 过期归档

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=detail \
       --repo1-retention-archive-type=diff --repo1-retention-archive=1 expire
TEXT
P00   INFO: expire command begin 2.59.0: --exec-id=2871-c1e7faec --log-level-console=detail --no-log-timestamp --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-archive=1 --repo1-retention-archive-type=diff --repo1-retention-diff=2 --repo1-retention-full=2 --stanza=demo
P00 DETAIL: repo1: 14-1 archive retention on backup 20260720-004204F, start = 00000002000000000000000A, stop = 00000002000000000000000B
P00 DETAIL: repo1: 14-1 archive retention on backup 20260720-004206F, start = 00000002000000000000000D, stop = 00000002000000000000000D

P00 DETAIL: repo1: 14-1 archive retention on backup 20260720-004206F_20260720-004212D, start = 000000020000000000000012, stop = 000000020000000000000013

P00 DETAIL: repo1: 14-1 archive retention on backup 20260720-004206F_20260720-004214D, start = 000000020000000000000016

P00   INFO: repo1: 14-1 remove archive, start = 00000002000000000000000C, stop = 00000002000000000000000C
P00   INFO: repo1: 14-1 remove archive, start = 00000002000000000000000E, stop = 000000020000000000000011
P00   INFO: repo1: 14-1 remove archive, start = 000000020000000000000014, stop = 000000020000000000000015

P00   INFO: expire command end: completed successfully

差异备份 20260720-004206F_20260720-004212D 中保留了一些 WAL 段——尽管这些段无法用于更早备份的 PITR 向前回放，但必须保留以确保旧备份的一致性。20260720-004206F_20260720-004212D 之后、20260720-004206F_20260720-004214D 之前生成的 WAL 段已被删除。20260720-004206F_20260720-004214D 之后生成的 WAL 段仍然保留，可用于 PITR。

在差异归档保留策略中，全量备份被视为差异备份，因此若以相同设置执行全量备份，则只会保留该全量备份之后的归档用于 PITR。

恢复

restore 命令默认从第一个存在备份的仓库中自动选取最新备份（参见 快速开始 - 恢复备份）。仓库的检查顺序由 pgbackrest.conf 决定（如 repo1 先于 repo2）。若要从特定仓库恢复，可传入 --repo 选项（如 --repo=1）；若要恢复非最新的备份，可传入 --set 选项。

指定 PITR 类型为 --type=time 或 --type=lsn 时，必须通过 --target 选项指定目标时间或 LSN。若未通过 --set 指定备份，pgBackRest 会按顺序检查各仓库，寻找包含所请求时间或 LSN 的备份。若未找到匹配备份：--type=time 时会使用第一个含备份仓库中的最新备份；--type=lsn 时则不选取任何备份。对于其他 PITR 类型（如 xid），若目标早于最新备份，则必须提供 --set 选项。详情与示例请参见 时间点恢复。

根据 PostgreSQL 的建议，复制槽不包含在备份中，更多信息请参阅 PostgreSQL 文档中的 备份数据目录 章节。

以下各节介绍 restore 命令的更多功能。

文件所有权

若 restore 以非 root 用户运行（典型场景），所有恢复的文件都将归执行 pgBackRest 的用户/组所有。若现有文件不属于该用户/组且无法更新所有权，则会报错。此时需由特权用户先更新文件所有权，再重新尝试恢复。

若 restore 以 root 用户运行，pgBackRest 会尝试按照备份时清单（manifest）中记录的所有权信息重建文件归属。清单中只存储用户/组的 名称，恢复主机上必须存在相同的名称才能正常映射。若找不到对应的用户/组名称，则使用 PostgreSQL 数据目录的用户/组；若仍无法映射，则最终回退到 root。

Delta 选项

快速开始 中的 恢复备份 章节要求在执行 restore 前先清空数据库集群目录。delta 选项让 pgBackRest 自动判断集群目录中哪些文件可以保留、哪些需要从备份恢复——同时还会 删除 不在备份清单中的文件，从而清除无关变更。该功能通过计算集群目录中每个文件的 SHA-1 加密哈希来实现，若哈希值与备份中存储的不匹配，则恢复该文件。配合 process-max 使用时效率极高。由于恢复期间 PostgreSQL 已关闭，可以使用比备份时更多的进程数。

pg-primary ⇒ 停止 demo 集群，执行 delta 恢复

BASH
sudo systemctl stop postgresql-14.service
sudo -u postgres pgbackrest --stanza=demo --delta \
       --log-level-console=detail restore
TEXT
       [filtered 2 lines of output]
P00 DETAIL: check '/var/lib/pgsql/14/data' exists
P00 DETAIL: remove 'global/pg_control' so cluster will not start if restore does not complete

P00   INFO: remove invalid files/links/paths from '/var/lib/pgsql/14/data'

P00 DETAIL: remove invalid file '/var/lib/pgsql/14/data/backup_label.old'
P00 DETAIL: remove invalid file '/var/lib/pgsql/14/data/base/13755/pg_internal.init'
       [filtered 996 lines of output]

pg-primary ⇒ 重启 PostgreSQL

BASH
sudo systemctl start postgresql-14.service

选择性数据库恢复

某些场景下，可能需要从集群备份中有选择地恢复特定数据库——原因可能是性能考量，也可能是目标机器空间不足以恢复整个集群，只需迁移部分数据库。

为演示此功能，创建两个数据库：test1 和 test2。

pg-primary ⇒ 创建两个测试数据库

BASH
sudo -u postgres psql -c "create database test1;"
SQL
CREATE DATABASE
BASH
sudo -u postgres psql -c "create database test2;"
SQL
CREATE DATABASE

在每个测试数据库中创建表并填充数据，用于演示选择性恢复。

pg-primary ⇒ 在每个数据库中创建测试表

BASH
sudo -u postgres psql -c "create table test1_table (id int); \
       insert into test1_table (id) values (1);" test1
SQL
CREATE TABLE
INSERT 0 1
BASH
sudo -u postgres psql -c "create table test2_table (id int); \
       insert into test2_table (id) values (2);" test2
SQL
CREATE TABLE
INSERT 0 1

执行一次新备份，让 pgBackRest 感知到新建的数据库。

pg-primary ⇒ 执行备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=incr backup

选择性恢复的主要用途之一是节省空间。先记录 test1 当前占用的空间，以便与选择性恢复后进行对比。

pg-primary ⇒ 查看 test1 数据库占用的空间

BASH
sudo -u postgres du -sh /var/lib/pgsql/14/data/base/32768
TEXT
8.4M	/var/lib/pgsql/14/data/base/32768

若不清楚需要恢复的数据库名称，可使用 info 命令配合 --set 选项，查看该备份集中包含的数据库列表。

pg-primary ⇒ 查看备份的数据库列表

BASH
sudo -u postgres pgbackrest --stanza=demo \
       --set=20260720-004206F_20260720-004225I info
TEXT
       [filtered 12 lines of output]
            repo1: backup size: 2.1MB
            backup reference list: 20260720-004206F, 20260720-004206F_20260720-004214D

            database list: postgres (13755), test1 (32768), test2 (32769)

停止集群，仅恢复 test2 数据库。内置数据库（template0、template1、postgres）始终会被恢复。

警告：

除非指定 --type=immediate，否则恢复可能会报错。原因是：达到一致性点之后，PostgreSQL 会将清零页标记为错误，即使是完整页写入也不例外。对于 PostgreSQL 14 及以上版本，可使用 ignore_invalid_pages 参数忽略无效页面。采用此方案时，恢复完成后务必检查日志，确认所选数据库中没有无效页面的报告。

pg-primary ⇒ 从最新备份恢复，仅包含 test2 数据库

BASH
sudo systemctl stop postgresql-14.service
sudo -u postgres pgbackrest --stanza=demo --delta \
       --db-include=test2 --type=immediate --target-action=promote restore

sudo systemctl start postgresql-14.service

恢复完成后，test2 数据库中将包含之前创建的表和数据。

pg-primary ⇒ 验证 test2 数据库已成功恢复

BASH
sudo -u postgres psql -c "select * from test2_table;" test2
TEXT
 id
----
  2
(1 row)

test1 数据库虽然恢复成功，但无法访问。这是因为整个数据库以稀疏清零文件的形式恢复，关键文件中不含任何实际数据。PostgreSQL 可以在清零文件上应用 WAL，但数据库本身并不有效。这是有意为之——目的是防止该数据库在可能包含 WAL 回放期间写入的部分数据时被意外访问。

pg-primary ⇒ 尝试连接 test1 数据库将产生错误

BASH
sudo -u postgres psql -c "select * from test1_table;" test1
psql: error: connection to server on socket "/run/postgresql/.s.PGSQL.5432" failed: FATAL:  relation mapping file "base/32768/pg_filenode.map" contains invalid data

由于 test1 数据库以稀疏清零文件恢复，其占用空间仅相当于恢复期间写入的 WAL 量。备份期间生成、恢复期间应用的 WAL 量虽可能不少，但通常只是数据库总大小的一小部分——大型数据库中尤为如此，这正是此功能最有价值的场景。

因此，选择性恢复后 test1 数据库占用的磁盘空间远少于完整恢复时的用量。

pg-primary ⇒ 查看恢复后 test1 数据库占用的空间

BASH
sudo -u postgres du -sh /var/lib/pgsql/14/data/base/32768
TEXT
8.0K	/var/lib/pgsql/14/data/base/32768

此时对无效的 test1 数据库唯一可执行的操作是 drop database。pgBackRest 不会自动删除它，删除操作必须在恢复完成且集群可访问后手动执行。

pg-primary ⇒ 删除 test1 数据库

BASH
sudo -u postgres psql -c "drop database test1;"
SQL
DROP DATABASE

删除无效的 test1 数据库后，只剩下 test2 和内置系统数据库。

pg-primary ⇒ 列出剩余数据库

BASH
sudo -u postgres psql -c "select oid, datname from pg_database order by oid;"
TEXT
  oid  |  datname
-------+-----------
     1 | template1
 13754 | template0
 13755 | postgres

 32769 | test2

(4 rows)

时间点恢复

快速开始 中的 恢复备份 执行的是默认恢复，即将 WAL 一路回放至末尾。对于硬件故障，这通常是最佳选择；但对于数据损坏场景（无论是程序错误还是人为误操作），时间点恢复（PITR）往往更为合适。

PITR 允许将 WAL 从备份回放至指定的 LSN、时间、事务 ID 或恢复点。常见恢复场景中，基于时间的恢复最为实用。典型场景是恢复意外删除的表或数据——以下以恢复误删表为例，误删数据的恢复方式完全相同。

pg-primary ⇒ 创建一张存有重要数据的表

BASH
sudo -u postgres psql -c "begin; \
       create table important_table (message text); \
       insert into important_table values ('Important Data'); \
       commit; \
       select * from important_table;"
TEXT
       [filtered 4 lines of output]
    message
----------------

 Important Data

(1 row)

记录时间时务必以 PostgreSQL 的时间为准，并包含时区偏移量，以免时区转换错误导致恢复结果与预期不符。

pg-primary ⇒ 从 PostgreSQL 获取当前时间

BASH
sudo -u postgres psql -Atc "select current_timestamp"
TEXT
2026-07-20 00:42:38.14485+00

记录时间后删除该表。实际操作中，找到表被删除的确切时间远比示例困难，可能无法获得精确时间，但通过一些取证工作通常能大致确定。

pg-primary ⇒ 删除重要表

BASH
sudo -u postgres psql -c "begin; \
       drop table important_table; \
       commit; \
       select * from important_table;"
TEXT
BEGIN
DROP TABLE
COMMITERROR:  relation "important_table" does not exist

LINE 1: ...le important_table;     commit;     select * from important_...
                                                             ^

若选择了错误的备份，恢复到所需时间目标将会失败。为演示这一点，在 important_table 不存在的情况下执行一次增量备份。

pg-primary ⇒ 执行增量备份

BASH
sudo -u postgres pgbackrest --stanza=demo --type=incr backup
sudo -u postgres pgbackrest info
TEXT
       [filtered 38 lines of output]
            backup reference total: 1 full, 1 diff

        incr backup: 20260720-004206F_20260720-004240I

            timestamp start/stop: 2026-07-20 00:42:40+00 / 2026-07-20 00:42:41+00
            wal start/stop: 00000004000000000000001A / 00000004000000000000001A
       [filtered 2 lines of output]

由于 PostgreSQL 只能向前回放 WAL，无法向后回放，因此无法从该备份中恢复丢失的表。

pg-primary ⇒ 尝试从错误的备份中恢复

BASH
sudo systemctl stop postgresql-14.service
sudo -u postgres pgbackrest --stanza=demo --delta \
       --set=20260720-004206F_20260720-004240I --target-timeline=current \
       --type=time "--target=2026-07-20 00:42:38.14485+00" --target-action=promote restore

sudo systemctl start postgresql-14.service
sudo -u postgres cat /var/lib/pgsql/14/data/log/postgresql.log
TEXT
       [filtered 11 lines of output]
LOG:  database system is ready to accept read-only connections
LOG:  redo done at 0/1A000100 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.01 s

FATAL:  recovery ended before configured recovery target was reached

LOG:  startup process (PID 4035) exited with exit code 1
LOG:  terminating any other active server processes
LOG:  database system is shut down

更可靠的方法是让 pgBackRest 自动选择能够恢复到时间目标的备份，即在指定时间之前完成的那个备份。

注意：

当恢复类型为 xid 或 name 时，pgBackRest 无法自动选择备份，必须手动指定 --set。

pg-primary ⇒ 将 demo 集群恢复至 2026-07-20 00:42:38.14485+00

BASH
sudo -u postgres pgbackrest --stanza=demo --delta \
       --type=time "--target=2026-07-20 00:42:38.14485+00" \
       --target-action=promote restore

sudo -u postgres cat /var/lib/pgsql/14/data/postgresql.auto.conf
TEXT
       [filtered 9 lines of output]
# Recovery settings generated by pgBackRest restore on 2026-07-20 00:42:47
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'
INI
recovery_target_time = '2026-07-20 00:42:38.14485+00'
recovery_target_action = 'promote'

pgBackRest 已将恢复设置写入 postgresql.auto.conf，PostgreSQL 可以直接启动。其中 %f 是 PostgreSQL 指定所需 WAL 段名称的占位符，%p 是该段的目标路径。PostgreSQL 完成恢复后，该表将重新存在，可正常查询。

pg-primary ⇒ 启动 PostgreSQL 并验证重要表是否存在

BASH
sudo systemctl start postgresql-14.service
sudo -u postgres psql -c "select * from important_table"
TEXT
    message
----------------

 Important Data

(1 row)

PostgreSQL 日志中也包含有价值的信息，记录了恢复停止的时间和事务，以及最后应用的事务时间。

pg-primary ⇒ 查看 PostgreSQL 日志输出

BASH
sudo -u postgres cat /var/lib/pgsql/14/data/log/postgresql.log
TEXT
       [filtered 5 lines of output]
LOG:  database system was interrupted; last known up at 2026-07-20 00:42:25 UTC
LOG:  restored log file "00000004.history" from archive

LOG:  starting point-in-time recovery to 2026-07-20 00:42:38.14485+00

LOG:  restored log file "00000004.history" from archive
LOG:  restored log file "000000040000000000000019" from archive
       [filtered 2 lines of output]
LOG:  consistent recovery state reached at 0/19000100
LOG:  database system is ready to accept read-only connections

LOG:  recovery stopping before commit of transaction 743, time 2026-07-20 00:42:39.777503+00

LOG:  redo done at 0/1901E6C0 system usage: CPU: user: 0.00 s, system: 0.01 s, elapsed: 0.02 s

LOG:  last completed transaction was at log time 2026-07-20 00:42:36.512696+00

LOG:  selected new timeline ID: 5
LOG:  archive recovery complete
LOG:  database system is ready to accept connections

删除 Stanza

stanza-delete 命令用于删除仓库中与某个 stanza 关联的全部数据。

警告：

请谨慎使用此命令——它将 永久删除 pgBackRest 仓库中指定 stanza 的所有备份和归档，且无法恢复。

删除 stanza 的步骤如下：

  1. 关闭与该 stanza 关联的 PostgreSQL 集群（或使用 --force 强制覆盖）。
  2. 在将要运行 stanza-delete 命令的主机上执行 stop 命令。
  3. 运行 stanza-delete 命令。

命令成功完成后，需手动从所有 pgBackRest 配置文件和/或环境变量中删除该 stanza 的配置。

每次只能从一个仓库中删除 stanza。若要从多个仓库中删除，需指定 --repo 选项，并对每个仓库分别执行一次 stanza-delete。

pg-primary ⇒ 停止待删除的 PostgreSQL 集群

BASH
sudo systemctl stop postgresql-14.service

pg-primary ⇒ 停止该 stanza 的 pgBackRest

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stop
TEXT
P00   INFO: stop command begin 2.59.0: --exec-id=4385-f7983994 --log-level-console=info --no-log-timestamp --stanza=demo

P00   INFO: stop command end: completed successfully

pg-primary ⇒ 从一个仓库中删除 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=1 \
       --log-level-console=info stanza-delete
TEXT
P00   INFO: stanza-delete command begin 2.59.0: --exec-id=4417-d1112030 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo=1 --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo

P00   INFO: stanza-delete command end: completed successfully

多仓库

如 S3 兼容对象存储支持 所示，可以配置多个仓库。主要优势在于可以同时拥有一个用于快速恢复的本地仓库和一个用于冗余的远程仓库。

某些命令（如 stanza-create 和 stanza-upgrade）会自动作用于所有已配置的仓库，而另一些命令（如 stanza-delete）则需要通过 --repo 选项指定仓库。

注意：仅配置了 repo1 时，--repo 选项不是必需的，这是为了保持向后兼容。但若单个仓库配置为 repo2，则必须指定 --repo，以防止后续添加新仓库时改变命令行为。

archive-push 命令始终将 WAL 推送到所有已配置仓库的归档。某个仓库不可达时，WAL 仍会被推送到其他仓库。但要使此功能有效，必须启用 archive-async=y；否则其他仓库只能比不可达的仓库多存一个 WAL 段。另需注意，若 WAL 无法推送到任何仓库，PostgreSQL 将不会从 pg_wal 目录中删除它，可能导致磁盘空间耗尽。

各仓库的备份需要单独调度，这在多数情况下是合理的，因为不同仓库的备份类型和保留策略可能不同。恢复时同样必须指定仓库，通常建议优先选择延迟较低或成本较低的仓库，哪怕恢复时间更长。只有通过实际恢复测试才能确定哪个仓库效率最高。

Azure 兼容对象存储支持

pgBackRest 支持将仓库存放在 Azure 兼容的对象存储中。容器必须提前创建，pgBackRest 不会自动创建。仓库可以放在容器根目录（/），但通常建议放在子路径下，以便对象存储日志或其他数据也能存放在同一容器中而不产生冲突。

警告：

请勿启用"分层命名空间"，否则执行 expire 时会报错。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 Azure

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
repo2-azure-account=pgbackrest
repo2-azure-container=demo-container
repo2-azure-key=YXpLZXk=
repo2-path=/demo-repo
repo2-retention-full=4
repo2-type=azure
start-fast=y
[global:archive-push]
compress-level=3

若要使用共享访问签名（SAS），将 repo2-azure-key-type 设置为 sas，并将 repo2-azure-key 设置为对应的共享访问签名令牌即可。

命令的运行方式与本地磁盘仓库完全相同。

pg-primary ⇒ 创建 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create
TEXT
P00   INFO: stanza-create command begin 2.59.0: --exec-id=4624-6c22f9b1 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo2-type=azure --stanza=demo
P00   INFO: stanza-create for stanza 'demo' on repo1
P00   INFO: stanza-create for stanza 'demo' on repo2

P00   INFO: stanza-create command end: completed successfully

由于在 Azure 中创建文件相对较慢，建议启用 文件打包 以提升 backup/restore 的性能。

pg-primary ⇒ 备份 demo 集群

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=2 \
       --log-level-console=info backup
TEXT
P00   INFO: backup command begin 2.59.0: --exec-id=4656-51499292 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo=2 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-block --repo1-bundle --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo2-type=azure --stanza=demo --start-fast

P00   WARN: no prior backup exists, incr backup has been changed to full

P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000005000000000000001B, lsn = 0/1B000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 00000005000000000000001B:00000005000000000000001B
P00   INFO: new backup label = 20260720-004303F

P00   INFO: full backup size = 33.5MB, file total = 1249

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=4656-51499292 --log-level-console=info --no-log-timestamp --repo=2 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo2-type=azure --stanza=demo

S3 兼容对象存储支持

pgBackRest 支持将仓库存放在 S3 兼容的对象存储中。存储桶必须提前创建，pgBackRest 不会自动创建。仓库可以放在存储桶根目录（/），但通常建议放在子路径下，以便对象存储日志或其他数据也能存放在同一存储桶中而不产生冲突。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 S3

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
repo2-azure-account=pgbackrest
repo2-azure-container=demo-container
repo2-azure-key=YXpLZXk=
repo2-path=/demo-repo
repo2-retention-full=4
repo2-type=azure
repo3-path=/demo-repo
repo3-retention-full=4
repo3-s3-bucket=demo-bucket
repo3-s3-endpoint=s3.us-east-1.amazonaws.com
repo3-s3-key=accessKey1
repo3-s3-key-secret=verySecretKey1
repo3-s3-region=us-east-1
repo3-type=s3
start-fast=y
[global:archive-push]
compress-level=3

注意：

需要将 region 和 endpoint 配置为存储桶所在的区域。此处给出的值适用于 us-east-1 区域。

建议创建专用角色来运行 pgBackRest，并尽可能严格地限制存储桶权限。若该角色与 AWS 实例关联，设置 repo3-s3-key-type=auto 后 pgBackRest 将自动获取临时凭证，无需在 /etc/pgbackrest/pgbackrest.conf 中显式配置密钥。

以下 Amazon S3 策略示例将存储桶和仓库路径的读写权限限制在最小必要范围内。

TEXT
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::demo-bucket"
            ],
            "Condition": {
                "StringEquals": {
                    "s3:prefix": [
                        "",
                        "demo-repo"
                    ],
                    "s3:delimiter": [
                        "/"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::demo-bucket"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "demo-repo/*"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:PutObjectTagging",
                "s3:GetObject",
                "s3:GetObjectVersion",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::demo-bucket/demo-repo/*"
            ]
        }
    ]
}

命令的运行方式与本地磁盘仓库完全相同。

pg-primary ⇒ 创建 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create
TEXT
       [filtered 4 lines of output]
P00   INFO: stanza 'demo' already exists on repo2 and is valid
P00   INFO: stanza-create for stanza 'demo' on repo3

P00   INFO: stanza-create command end: completed successfully

由于在 S3 中创建文件相对较慢，建议启用 文件打包 以提升 backup/restore 的性能。

pg-primary ⇒ 备份 demo 集群

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=3 \
       --log-level-console=info backup
TEXT
P00   INFO: backup command begin 2.59.0: --exec-id=5049-047bfb40 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo=3 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-block --repo1-bundle --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo2-type=azure --repo3-type=s3 --stanza=demo --start-fast

P00   WARN: no prior backup exists, incr backup has been changed to full

P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000005000000000000001C, lsn = 0/1C000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 00000005000000000000001C:00000005000000000000001D
P00   INFO: new backup label = 20260720-004325F

P00   INFO: full backup size = 33.5MB, file total = 1249

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=5049-047bfb40 --log-level-console=info --no-log-timestamp --repo=3 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo2-type=azure --repo3-type=s3 --stanza=demo

SFTP 支持

pgBackRest 支持将仓库存储在 SFTP 主机上。SFTP 文件传输相对较慢，因此建议通过增大 process-max 来并行化文件传输，以提升命令性能。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 SFTP

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
process-max=4
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
repo2-azure-account=pgbackrest
repo2-azure-container=demo-container
repo2-azure-key=YXpLZXk=
repo2-path=/demo-repo
repo2-retention-full=4
repo2-type=azure
repo3-path=/demo-repo
repo3-retention-full=4
repo3-s3-bucket=demo-bucket
repo3-s3-endpoint=s3.us-east-1.amazonaws.com
repo3-s3-key=accessKey1
repo3-s3-key-secret=verySecretKey1
repo3-s3-region=us-east-1
repo3-type=s3
repo4-bundle=y
repo4-path=/demo-repo
repo4-sftp-host=sftp-server
repo4-sftp-host-key-hash-type=sha1
repo4-sftp-host-user=pgbackrest
repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp
repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub
repo4-type=sftp
start-fast=y
[global:archive-push]
compress-level=3

使用 SFTP 时，若 libssh2 基于 OpenSSH 编译，则 repo4-sftp-public-key-file 为可选项。

pg-primary ⇒ 为 SFTP 备份生成 SSH 密钥对

BASH
sudo -u postgres mkdir -m 750 -p /var/lib/pgsql/.ssh
sudo -u postgres ssh-keygen -f /var/lib/pgsql/.ssh/id_rsa_sftp \
       -t rsa -b 4096 -N "" -m PEM

sftp-server ⇒ 将 pg-primary 的 SFTP 备份公钥复制到 sftp-server

BASH
sudo -u pgbackrest mkdir -m 750 -p /home/pgbackrest/.ssh

(sudo ssh root@pg-primary cat /var/lib/pgsql/.ssh/id_rsa_sftp.pub) | \
       sudo -u pgbackrest tee -a /home/pgbackrest/.ssh/authorized_keys

命令的运行方式与本地磁盘仓库完全相同。

pg-primary ⇒ 将 sftp-server 的指纹添加到 known_hosts（repo4-sftp-host-key-check-type 默认为 strict）

BASH
ssh-keyscan -H sftp-server >> /var/lib/pgsql/.ssh/known_hosts 2>/dev/null

pg-primary ⇒ 创建 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create
TEXT
       [filtered 6 lines of output]
P00   INFO: stanza 'demo' already exists on repo3 and is valid
P00   INFO: stanza-create for stanza 'demo' on repo4

P00   INFO: stanza-create command end: completed successfully

pg-primary ⇒ 备份 demo 集群

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=4 \
       --log-level-console=info backup
TEXT
P00   INFO: backup command begin 2.59.0: --exec-id=5351-7b0bda1e --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --process-max=4 --repo=4 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-block --repo1-bundle --repo4-bundle --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo4-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo4-sftp-host=sftp-server --repo4-sftp-host-key-hash-type=sha1 --repo4-sftp-host-user=pgbackrest --repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp --repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub --repo2-type=azure --repo3-type=s3 --repo4-type=sftp --stanza=demo --start-fast
P00   WARN: option 'repo4-retention-full' is not set for 'repo4-retention-full-type=count', the repository may run out of space
            HINT: to retain full backups indefinitely (without warning), set option 'repo4-retention-full' to the maximum.

P00   WARN: no prior backup exists, incr backup has been changed to full

P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000005000000000000001F, lsn = 0/1F000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 00000005000000000000001F:00000005000000000000001F
P00   INFO: new backup label = 20260720-004346F

P00   INFO: full backup size = 33.5MB, file total = 1249

P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.59.0: --exec-id=5351-7b0bda1e --log-level-console=info --no-log-timestamp --repo=4 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo4-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo4-sftp-host=sftp-server --repo4-sftp-host-key-hash-type=sha1 --repo4-sftp-host-user=pgbackrest --repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp --repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub --repo2-type=azure --repo3-type=s3 --repo4-type=sftp --stanza=demo
P00   INFO: expire command end: completed successfully

GCS 兼容对象存储支持

pgBackRest 支持将仓库存储在 GCS 兼容的对象存储中。存储桶必须提前创建，pgBackRest 不会自动创建。仓库可以放在存储桶根目录（/），但通常建议放在子路径下，以便对象存储日志或其他数据也能存放在同一存储桶中而不产生冲突。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 GCS

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
process-max=4
repo1-block=y
repo1-bundle=y
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO
repo1-cipher-type=aes-256-cbc
repo1-path=/var/lib/pgbackrest
repo1-retention-diff=2
repo1-retention-full=2
repo2-azure-account=pgbackrest
repo2-azure-container=demo-container
repo2-azure-key=YXpLZXk=
repo2-path=/demo-repo
repo2-retention-full=4
repo2-type=azure
repo3-path=/demo-repo
repo3-retention-full=4
repo3-s3-bucket=demo-bucket
repo3-s3-endpoint=s3.us-east-1.amazonaws.com
repo3-s3-key=accessKey1
repo3-s3-key-secret=verySecretKey1
repo3-s3-region=us-east-1
repo3-type=s3
repo4-bundle=y
repo4-path=/demo-repo
repo4-sftp-host=sftp-server
repo4-sftp-host-key-hash-type=sha1
repo4-sftp-host-user=pgbackrest
repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp
repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub
repo4-type=sftp
repo5-gcs-bucket=demo-bucket
repo5-gcs-key=/etc/pgbackrest/gcs-key.json
repo5-path=/demo-repo
repo5-type=gcs
start-fast=y
[global:archive-push]
compress-level=3

在 GCE 中运行时，设置 repo5-gcs-key-type=auto 可利用实例服务账号自动完成身份验证。

命令的运行方式与本地磁盘仓库完全相同。

GCS 中的文件创建速度相对较慢，建议启用 文件打包 以提升 backup/restore 的性能。

仓库目标时间

目标时间（repo target time）定义了命令读取版本化存储上仓库时所用的历史时间点。通过指定目标时间，命令可以查看仓库在某个历史时刻的状态，从而恢复因用户误操作或恶意软件导致被删除或损坏的数据。

版本化存储受 S3、GCS 和 Azure 支持，但通常默认未启用。除了启用版本控制之外，还可以考虑为 S3 启用对象锁定（object locking），为 GCS 或 Azure 启用软删除（soft delete）。

指定 repo-target-time 时，必须同时提供 --repo 选项。由于并非所有仓库类型都支持版本控制，针对单个仓库进行恢复是合理的做法。

注意：时间戳比较使用 <= 逻辑（即小于等于所提供的时间戳），且所提供时间戳的毫秒部分会被截断。

为演示此功能，将删除 S3 仓库中 demo stanza 的数据。

pg-primary ⇒ 删除 S3 仓库中的 stanza

BASH
sudo systemctl stop postgresql-14.service
sudo -u postgres pgbackrest --stanza=demo stop
sudo -u postgres pgbackrest --stanza=demo --repo=3 stanza-delete

stanza 删除后，info 命令将显示仓库处于错误状态。

pg-primary ⇒ info 命令报错

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=3 info
TEXT
stanza: demo

    status: error (missing stanza path)

由于存储是版本化的，仍可查看 stanza 被删除之前某个时间点的仓库状态。确定合适的目标时间可能有些棘手，本例中可通过查找 backup.info 被删除的时间来确定。

pg-primary ⇒ 列出存储桶中 backup.info 的版本信息

BASH
key=demo-repo/backup/demo/backup.info; \
       aws s3api list-object-versions --bucket demo-bucket \
       --prefix $key --output table \
       --query "sort_by([Versions[?Key=='$key'].{Action:'PUT', \
       Modified:LastModified,Object:Key}, \
       DeleteMarkers[?Key=='$key'].{Action:'DELETE', \
       Modified:LastModified,Object:Key}][],&Modified)"
TEXT
-------------------------------------------------------------------------------------
|                                ListObjectVersions                                 |
+--------+------------------------------------+-------------------------------------+
| Action |             Modified               |               Object                |
+--------+------------------------------------+-------------------------------------+
|  PUT   |  2026-07-20T00:43:25.103000+00:00  |  demo-repo/backup/demo/backup.info  |
|  PUT   |  2026-07-20T00:43:41.347000+00:00  |  demo-repo/backup/demo/backup.info  |
|  DELETE|  2026-07-20T00:43:55.062000+00:00  |  demo-repo/backup/demo/backup.info  |
+--------+------------------------------------+-------------------------------------+

现在可以使用目标时间运行 info 命令，查看 stanza 被删除之前的仓库状态。

pg-primary ⇒ 带目标时间的 info 命令

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=3 \
       --repo-target-time="2026-07-20 00:43:41+00" info
TEXT
       [filtered 5 lines of output]
        wal archive min/max (14): 00000005000000000000001C/00000005000000000000001D

        full backup: 20260720-004325F

            timestamp start/stop: 2026-07-20 00:43:25+00 / 2026-07-20 00:43:40+00
            wal start/stop: 00000005000000000000001C / 00000005000000000000001D
            repo3: backup set size: 4.2MB, backup size: 4.2MB

若 info 命令显示了所需的备份，便可使用相同的目标时间进行恢复。

pg-primary ⇒ 带目标时间的 restore 命令

BASH
sudo -u postgres pgbackrest --stanza=demo --repo=3 --delta \
       --repo-target-time="2026-07-20 00:43:41+00" --log-level-console=info restore
TEXT
P00   INFO: restore command begin 2.59.0: --delta --exec-id=5676-62516a6c --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --process-max=4 --repo=3 --repo2-azure-account= --repo2-azure-container=demo-container --repo2-azure-key= --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo5-gcs-bucket=demo-bucket --repo5-gcs-key= --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo4-path=/demo-repo --repo5-path=/demo-repo --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key= --repo3-s3-key-secret= --repo3-s3-region=us-east-1 --repo4-sftp-host=sftp-server --repo4-sftp-host-key-hash-type=sha1 --repo4-sftp-host-user=pgbackrest --repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp --repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub --repo-target-time="2026-07-20 00:43:41+00" --repo2-type=azure --repo3-type=s3 --repo4-type=sftp --repo5-type=gcs --stanza=demo

P00   INFO: repo3: restore backup set 20260720-004325F, recovery will start at 2026-07-20 00:43:25

P00   INFO: remove invalid files/links/paths from '/var/lib/pgsql/14/data'
P00   INFO: write updated /var/lib/pgsql/14/data/postgresql.auto.conf
       [filtered 2 lines of output]
BASH
sudo systemctl start postgresql-14.service

专用仓库主机

快速开始 中描述的配置适用于简单安装场景，但在企业级部署中，更常见的做法是使用专用仓库主机存储备份和 WAL 归档。这样可以将备份与数据库服务器分离，降低数据库主机故障的影响。建议仍使用传统备份软件对仓库主机本身进行备份。

在 PostgreSQL 主机上，pg1-path 必须是本地集群的数据目录路径，且不应配置 pg1-host。在仓库主机上配置 pgBackRest 时，必须通过 pg-host 选项指定主库和备库（如有）的连接信息。仓库主机是唯一需要感知多个 PostgreSQL 主机的节点。配置顺序无关紧要，pg1-path/pg1-host、pg2-path/pg2-host 可以分别对应主库或备库。

安装

创建一台名为 repository 的新主机，用于存储集群备份。

注意：

仓库主机上安装的 pgBackRest 版本必须与 PostgreSQL 主机上安装的版本完全一致。

创建专用的 pgbackrest 用户来管理仓库。仓库可以由任何用户管理，但建议不要使用 postgres（若存在），以避免混淆。

注意：

从软件包安装 pgBackRest 时，可能会提供类似 /etc/logrotate.d/pgbackrest 的 logrotate 配置，通过 su 指令以特定用户轮转日志（例如 su postgres postgres）。由于 /var/log/pgbackrest 中的文件归运行 pgBackRest 的用户所有（此处为 pgbackrest），必须将 su 指令更新为该用户，否则 logrotate 会因权限错误而失败。

repository ⇒ 创建 pgbackrest 用户

BASH
sudo groupadd pgbackrest
sudo adduser -gpgbackrest -n pgbackrest

推荐通过软件包安装 pgBackRest，而非从源码编译。通过软件包安装时，本节后续步骤通常不需要手动执行，但某些软件包可能会跳过创建目录或权限设置有误。遇到这种情况，手动创建目录或更新权限即可。

RHEL 平台的 pgBackRest 软件包可在 yum.postgresql.org 获取。

如果所用发行版/版本没有提供软件包，可以 编译构建 后手动安装，步骤如下。

repository ⇒ 安装依赖

BASH
sudo yum install postgresql-libs libssh2

repository ⇒ 从构建主机复制 pgBackRest 二进制文件

BASH
sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin
sudo chmod 755 /usr/bin/pgbackrest

pgBackRest 需要日志目录、配置目录以及配置文件。

repository ⇒ 创建 pgBackRest 配置文件和目录

BASH
sudo mkdir -p -m 770 /var/log/pgbackrest
sudo chown pgbackrest:pgbackrest /var/log/pgbackrest
sudo mkdir -p /etc/pgbackrest
sudo mkdir -p /etc/pgbackrest/conf.d
sudo touch /etc/pgbackrest/pgbackrest.conf
sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
sudo chown pgbackrest:pgbackrest /etc/pgbackrest/pgbackrest.conf

repository ⇒ 创建 pgBackRest 仓库

BASH
sudo mkdir -p /var/lib/pgbackrest
sudo chmod 750 /var/lib/pgbackrest
sudo chown pgbackrest:pgbackrest /var/lib/pgbackrest

配置

pgBackRest 可以使用 TLS 客户端证书实现主机间通信，也可以使用 SSH，请参见 配置免密 SSH。

pgBackRest 期望客户端/服务器证书的生成方式与 PostgreSQL 相同。有关证书生成的详细说明，请参见 PostgreSQL 文档中的 使用 TLS 的安全 TCP/IP 连接。

仓库主机必须配置 pg-primary 的主机/用户和数据库路径。主库将配置为 pg1，以便后续可以添加备库。

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pg1-host/pg1-host-user 和 pg1-path

INI
[demo]
pg1-host=pg-primary
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/14/data
[global]
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
tls-server-address=*
tls-server-auth=pgbackrest-client=*
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

数据库主机需要配置仓库主机/用户信息。repo1-host-user 选项的默认值为 pgbackrest。若 postgres 用户需要在仓库主机上执行恢复，最好不要同时允许其执行备份。不过，若 postgres 用户与 pgbackrest 用户属于同一用户组，则可以直接读取仓库。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 repo1-host/repo1-host-user

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
log-level-file=detail
repo1-host=repository
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt
repo1-host-key-file=/etc/pgbackrest/cert/client.key
repo1-host-type=tls
tls-server-address=*
tls-server-auth=pgbackrest-client=demo
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

PostgreSQL 的归档配置请参见 配置归档 章节。

命令的运行方式与单主机配置相同，但 backup 和 expire 等命令需要在仓库主机上运行，而非数据库主机上。

配置 TLS 服务器

pgBackRest TLS 服务器必须在每台主机上进行配置并启动。

repository ⇒ 配置 pgBackRest 服务器

BASH
sudo cat /etc/systemd/system/pgbackrest.service
INI
[Unit]
Description=pgBackRest Server
After=network.target
StartLimitIntervalSec=0
[Service]
Type=notify
Restart=always
RestartSec=1
User=pgbackrest
ExecStart=/usr/bin/pgbackrest server
ExecStartPost=/bin/sleep 3
ExecStartPost=/bin/bash -c "[ ! -z $MAINPID ]"
ExecReload=/bin/kill -HUP $MAINPID
[Install]
WantedBy=multi-user.target
BASH
sudo systemctl enable pgbackrest
sudo systemctl start pgbackrest

pg-primary ⇒ 配置 pgBackRest 服务器

BASH
sudo cat /etc/systemd/system/pgbackrest.service
INI
[Unit]
Description=pgBackRest Server
After=network.target
StartLimitIntervalSec=0
[Service]
Type=notify
Restart=always
RestartSec=1
User=postgres
ExecStart=/usr/bin/pgbackrest server
ExecStartPost=/bin/sleep 3
ExecStartPost=/bin/bash -c "[ ! -z $MAINPID ]"
ExecReload=/bin/kill -HUP $MAINPID
[Install]
WantedBy=multi-user.target
BASH
sudo systemctl enable pgbackrest
sudo systemctl start pgbackrest

创建并检查 Stanza

在新仓库中创建 stanza。

repository ⇒ 创建 stanza

BASH
sudo -u pgbackrest pgbackrest --stanza=demo stanza-create

在数据库主机和仓库主机上分别验证配置是否正确。关于 check 命令的更多信息，请参见 检查配置。

pg-primary ⇒ 检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo check

repository ⇒ 检查配置

BASH
sudo -u pgbackrest pgbackrest --stanza=demo check

执行备份

在仓库主机上运行 pgBackRest 的 backup 命令，对 PostgreSQL 集群执行备份。

repository ⇒ 备份 demo 集群

BASH
sudo -u pgbackrest pgbackrest --stanza=demo backup
TEXT
P00   WARN: no prior backup exists, incr backup has been changed to full

由于仓库主机上为新仓库，因此出现增量备份自动变更为全量备份的警告。

恢复备份

在数据库主机上运行 restore 命令，对 PostgreSQL 集群执行恢复。

pg-primary ⇒ 停止 demo 集群、执行恢复并重启 PostgreSQL

BASH
sudo systemctl stop postgresql-14.service
sudo -u postgres pgbackrest --stanza=demo --delta restore
sudo systemctl start postgresql-14.service

并行备份与恢复

pgBackRest 提供并行处理功能，可提升压缩和传输的性能。通过 --process-max 选项设置并发进程数。

对于 backup 命令，通常建议不超过可用 CPU 数量的 25%。备份只要定期执行即可，速度不需要很快，且备份过程应尽量不影响数据库性能。

restore 命令可以也应该使用所有可用的 CPU——恢复期间 PostgreSQL 已关闭，主机上通常没有其他重要工作在运行。若主机上有多个集群，设置恢复并行度时需相应考虑。

repository ⇒ 使用单进程执行备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo --type=full backup

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pgBackRest 使用多个 backup 进程

INI
[demo]
pg1-host=pg-primary
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/14/data
[global]
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
tls-server-address=*
tls-server-auth=pgbackrest-client=*
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

repository ⇒ 使用多进程执行备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo --type=full backup

repository ⇒ 获取 demo 集群的备份信息

BASH
sudo -u pgbackrest pgbackrest info
TEXT
stanza: demo
    status: ok
    cipher: none

    db (current)
        wal archive min/max (14): 000000070000000000000023/000000070000000000000025

        full backup: 20260720-004457F

            timestamp start/stop: 2026-07-20 00:44:57+00 / 2026-07-20 00:45:01+00

            wal start/stop: 000000070000000000000023 / 000000070000000000000023
            database size: 33.5MB, database backup size: 33.5MB
            repo1: backup set size: 4.2MB, backup size: 4.2MB

        full backup: 20260720-004502F

            timestamp start/stop: 2026-07-20 00:45:02+00 / 2026-07-20 00:45:06+00

            wal start/stop: 000000070000000000000024 / 000000070000000000000025
            database size: 33.5MB, database backup size: 33.5MB
            repo1: backup set size: 4.2MB, backup size: 4.2MB

与单进程备份相比，多进程应能提升最后一次备份的速度。对于极小的备份，差距可能不明显，但随着数据库规模增大，节省的时间也会相应增加。

启动与停止

若备库被提升用于测试，或测试集群从生产备份恢复，最好阻止这些集群向 pgBackRest 仓库写入数据，stop 命令可以实现这一点。

会写入数据且受 stop 约束的命令包括：archive-push、backup、expire、stanza-create 和 stanza-upgrade。stanza-delete 是例外，详见 删除 Stanza 章节。

pg-primary ⇒ 停止 pgBackRest 写入命令

BASH
sudo -u postgres pgbackrest stop

新的 pgBackRest 写入命令将不再运行。

repository ⇒ 尝试执行备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo backup
TEXT
P00   WARN: unable to check pg1: [StopError] raised from remote-0 tls protocol on 'pg-primary': stop file exists for all stanzas

P00  ERROR: [056]: unable to find primary cluster - cannot proceed
            HINT: are all available clusters in recovery?

指定 --force 选项可以终止当前正在运行的 pgBackRest 写入命令，包括异步 archive-get（但若 PostgreSQL 需要，它会再次启动）。若 pgBackRest 已处于停止状态，再次执行 stop 会产生警告。

pg-primary ⇒ 再次停止 pgBackRest 服务

BASH
sudo -u postgres pgbackrest stop
TEXT
P00   WARN: stop file already exists for all stanzas

使用 start 命令恢复 pgBackRest 写入命令。停止前正在进行的写入命令不会自动重新启动，但之后允许重新运行。

pg-primary ⇒ 启动 pgBackRest 写入命令

BASH
sudo -u postgres pgbackrest start

也可以仅停止某个特定 stanza 的 pgBackRest 写入命令。

pg-primary ⇒ 停止 demo stanza 的 pgBackRest 写入命令

BASH
sudo -u postgres pgbackrest --stanza=demo stop

指定 stanza 的新 pgBackRest 写入命令将不再运行。

repository ⇒ 尝试执行备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo backup
TEXT
P00   WARN: unable to check pg1: [StopError] raised from remote-0 tls protocol on 'pg-primary': stop file exists for stanza demo

P00  ERROR: [056]: unable to find primary cluster - cannot proceed
            HINT: are all available clusters in recovery?

针对单个 stanza 启动时，同样必须指定该 stanza。

pg-primary ⇒ 启动 demo stanza 的 pgBackRest 写入命令

BASH
sudo -u postgres pgbackrest --stanza=demo start

复制

复制允许从单个主库派生出多个 PostgreSQL 集群副本（备库），用于分担读取负载，并在主库故障时提供冗余。

安装

创建一台名为 pg-standby 的新主机来运行备库。

推荐通过软件包安装 pgBackRest，而非从源码编译。通过软件包安装时，本节后续步骤通常不需要手动执行，但某些软件包可能会跳过创建目录或权限设置有误。遇到这种情况，手动创建目录或更新权限即可。

RHEL 平台的 pgBackRest 软件包可在 yum.postgresql.org 获取。

如果所用发行版/版本没有提供软件包，可以 编译构建 后手动安装。

pg-standby ⇒ 安装依赖

BASH
sudo yum install postgresql-libs libssh2

pg-standby ⇒ 从构建主机复制 pgBackRest 二进制文件

BASH
sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin
sudo chmod 755 /usr/bin/pgbackrest

pgBackRest 需要日志目录、配置目录以及配置文件。

pg-standby ⇒ 创建 pgBackRest 配置文件和目录

BASH
sudo mkdir -p -m 770 /var/log/pgbackrest
sudo chown postgres:postgres /var/log/pgbackrest
sudo mkdir -p /etc/pgbackrest
sudo mkdir -p /etc/pgbackrest/conf.d
sudo touch /etc/pgbackrest/pgbackrest.conf
sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf

热备库

热备库通过 WAL 归档进行复制，并允许只读查询。

备库上的 pgBackRest 配置与 pg-primary 非常相似，区别在于使用 standby 恢复类型，使集群在到达 WAL 流末尾时保持在恢复模式而不切换为主库。

pg-standby:/etc/pgbackrest/pgbackrest.conf ⇒ 在备库上配置 pgBackRest

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
log-level-file=detail
repo1-host=repository
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt
repo1-host-key-file=/etc/pgbackrest/cert/client.key
repo1-host-type=tls
tls-server-address=*
tls-server-auth=pgbackrest-client=demo
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

pg-standby ⇒ 配置 pgBackRest 服务器

BASH
sudo cat /etc/systemd/system/pgbackrest.service
INI
[Unit]
Description=pgBackRest Server
After=network.target
StartLimitIntervalSec=0
[Service]
Type=notify
Restart=always
RestartSec=1
User=postgres
ExecStart=/usr/bin/pgbackrest server
ExecStartPost=/bin/sleep 3
ExecStartPost=/bin/bash -c "[ ! -z $MAINPID ]"
ExecReload=/bin/kill -HUP $MAINPID
[Install]
WantedBy=multi-user.target
BASH
sudo systemctl enable pgbackrest
sudo systemctl start pgbackrest

创建 PostgreSQL 将要恢复到的路径。

pg-standby ⇒ 创建 PostgreSQL 路径

BASH
sudo -u postgres mkdir -p -m 700 /var/lib/pgsql/14/data

现在可以使用 restore 命令创建备库。

重要提示：

如果集群被提升后不会成为新主库（例如用于报表或测试），请使用 --archive-mode=off 或在 postgresql.conf 中设置 archive_mode=off 来禁用归档。若不禁用归档，仓库中可能积累大量无用 WAL，使后续恢复更加困难。

pg-standby ⇒ 恢复 demo 备库集群

BASH
sudo -u postgres pgbackrest --stanza=demo --type=standby restore
sudo -u postgres cat /var/lib/pgsql/14/data/postgresql.auto.conf

# Do not edit this file manually!
# It will be overwritten by the ALTER SYSTEM command.

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:41:50
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:42:19
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:42:47
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'
# Removed by pgBackRest restore on 2026-07-20 00:44:06 # recovery_target_time = '2026-07-20 00:42:38.14485+00'
# Removed by pgBackRest restore on 2026-07-20 00:44:06 # recovery_target_action = 'promote'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:44:06
restore_command = 'pgbackrest --repo=3 --repo-target-time="2026-07-20 00:43:41+00" --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:44:52
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:45:31
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

启动 PostgreSQL 之前，必须启用 hot_standby 设置，以允许在 pg-standby 上建立只读连接，否则连接请求将被拒绝。其余配置是为备库日后晋升为主库做准备。

pg-standby:/var/lib/pgsql/14/data/postgresql.conf ⇒ 配置 PostgreSQL

INI
archive_command = 'pgbackrest --stanza=demo archive-push %p'
archive_mode = on
hot_standby = on
log_filename = 'postgresql.log'

pg-standby ⇒ 启动 PostgreSQL

BASH
sudo systemctl start postgresql-14.service

PostgreSQL 日志提供了关于恢复的重要信息。特别注意集群已进入备库模式并准备好接受只读连接。

pg-standby ⇒ 检查 PostgreSQL 日志中表示成功的日志消息

BASH
sudo -u postgres cat /var/lib/pgsql/14/data/log/postgresql.log
TEXT
       [filtered 4 lines of output]
LOG:  listening on Unix socket "/tmp/.s.PGSQL.5432"
LOG:  database system was interrupted; last known up at 2026-07-20 00:45:02 UTC

LOG:  entering standby mode

LOG:  restored log file "00000007.history" from archive
LOG:  restored log file "000000070000000000000024" from archive
       [filtered 3 lines of output]

验证复制是否配置正确，最简单的方法是在 pg-primary 上创建一张表。

pg-primary ⇒ 在主库上创建新表

BASH
sudo -u postgres psql -c " \
       begin; \
       create table replicated_table (message text); \
       insert into replicated_table values ('Important Data'); \
       commit; \
       select * from replicated_table";
TEXT
       [filtered 4 lines of output]
    message
----------------

 Important Data

(1 row)

然后在 pg-standby 上查询同一张表。

pg-standby ⇒ 在备库上查询新表

BASH
sudo -u postgres psql -c "select * from replicated_table;"
TEXT
ERROR:  relation "replicated_table" does not exist

LINE 1: select * from replicated_table;
                      ^

这是为什么？由于 PostgreSQL 通过从归档拉取 WAL 段来执行复制，包含这些变更的 WAL 段还未从 pg-primary 推送过来，备库自然看不到这些变更。

手动调用 pg_switch_wal() 可以解决这个问题，该函数会将当前 WAL 段推送到归档（并创建新 WAL 段以存放后续变更）。

pg-primary ⇒ 调用 pg_switch_wal()

BASH
sudo -u postgres psql -c "select *, current_timestamp from pg_switch_wal()";
TEXT
 pg_switch_wal |       current_timestamp
---------------+-------------------------------
 0/2601E7C0    | 2026-07-20 00:45:38.037413+00
(1 row)

稍等片刻，该表就会出现在 pg-standby 上。

pg-standby ⇒ 新表现在已出现在备库上（可能需要重试几次）

BASH
sudo -u postgres psql -c " \
       select *, current_timestamp from replicated_table"
TEXT
    message     |       current_timestamp
----------------+-------------------------------

 Important Data | 2026-07-20 00:45:39.220085+00

(1 row)

检查备库配置对仓库的访问权限。

pg-standby ⇒ 检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=1181-02efd7d6 --log-level-console=info --log-level-file=detail --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --stanza=demo
P00   INFO: check repo1 (standby)

P00   INFO: switch wal not performed because this is a standby

P00   INFO: check command end: completed successfully

流复制

流复制不依赖 WAL 归档，而是直接连接到主库，变更发生后即刻应用，主备延迟因此大幅降低。

流复制需要一个具有复制权限的数据库用户。

pg-primary ⇒ 创建复制用户

BASH
sudo -u postgres psql -c " \
       create user replicator password 'jw8s0F4' replication";
SQL
CREATE ROLE

需要更新 pg_hba.conf 文件，允许备库以复制用户身份连接。请将下面的 IP 地址替换为 pg-standby 的实际地址，修改后需重新加载配置。

pg-primary ⇒ 为复制用户创建 pg_hba.conf 条目

BASH
sudo -u postgres sh -c 'echo \
       "host    replication     replicator      172.17.0.8/32           md5" \
       >> /var/lib/pgsql/14/data/pg_hba.conf'

sudo systemctl reload postgresql-14.service

备库需要知道如何连接主库，因此在 pgBackRest 中配置 primary_conninfo 设置。

pg-standby:/etc/pgbackrest/pgbackrest.conf ⇒ 设置 primary_conninfo

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
recovery-option=primary_conninfo=host=172.17.0.6 port=5432 user=replicator
[global]
log-level-file=detail
repo1-host=repository
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt
repo1-host-key-file=/etc/pgbackrest/cert/client.key
repo1-host-type=tls
tls-server-address=*
tls-server-auth=pgbackrest-client=demo
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

密码可以写在 primary_conninfo 中，但使用 .pgpass 文件更灵活、更安全。

pg-standby ⇒ 在 .pgpass 文件中配置复制密码

BASH
sudo -u postgres sh -c 'echo \
       "172.17.0.6:*:replication:replicator:jw8s0F4" \
       >> /var/lib/pgsql/.pgpass'

sudo -u postgres chmod 600 /var/lib/pgsql/.pgpass

现在可以使用 restore 命令创建备库。

pg-standby ⇒ 停止 PostgreSQL 并恢复 demo 备库集群

BASH
sudo systemctl stop postgresql-14.service
sudo -u postgres pgbackrest --stanza=demo --delta --type=standby restore
sudo -u postgres cat /var/lib/pgsql/14/data/postgresql.auto.conf

# Do not edit this file manually!
# It will be overwritten by the ALTER SYSTEM command.

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:41:50
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:42:19
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:42:47
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'
# Removed by pgBackRest restore on 2026-07-20 00:44:06 # recovery_target_time = '2026-07-20 00:42:38.14485+00'
# Removed by pgBackRest restore on 2026-07-20 00:44:06 # recovery_target_action = 'promote'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:44:06
restore_command = 'pgbackrest --repo=3 --repo-target-time="2026-07-20 00:43:41+00" --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:44:52
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2026-07-20 00:45:45
primary_conninfo = 'host=172.17.0.6 port=5432 user=replicator'
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

注意：

primary_conninfo 之所以写入了 postgresql.auto.conf，是因为它在 pgbackrest.conf 中被配置为 recovery-option。若希望保留现有的 postgresql.auto.conf，可在 restore 时使用 --type=preserve 选项。

RHEL 默认将 postgresql.conf 存放在数据目录中，因此每次恢复都会覆盖其中的更改，hot_standby 设置也需要重新启用。解决办法是：将 postgresql.conf 存放到其他位置，或在 pg-primary 上启用 hot_standby（主库上该设置会被忽略）。

pg-standby:/var/lib/pgsql/14/data/postgresql.conf ⇒ 启用 hot_standby

INI
archive_command = 'pgbackrest --stanza=demo archive-push %p'
archive_mode = on
hot_standby = on
log_filename = 'postgresql.log'

pg-standby ⇒ 启动 PostgreSQL

BASH
sudo systemctl start postgresql-14.service

PostgreSQL 日志将确认流复制已启动。

pg-standby ⇒ 检查 PostgreSQL 日志中表示成功的日志消息

BASH
sudo -u postgres cat /var/lib/pgsql/14/data/log/postgresql.log
TEXT
       [filtered 12 lines of output]
LOG:  database system is ready to accept read-only connections
LOG:  restored log file "000000070000000000000026" from archive

LOG:  started streaming WAL from primary at 0/27000000 on timeline 7

现在在 pg-primary 上创建表后，无需调用 pg_switch_wal()，它会很快出现在 pg-standby 上。

pg-primary ⇒ 在主库上创建新表

BASH
sudo -u postgres psql -c " \
       begin; \
       create table stream_table (message text); \
       insert into stream_table values ('Important Data'); \
       commit; \
       select *, current_timestamp from stream_table";
TEXT
       [filtered 4 lines of output]
    message     |       current_timestamp
----------------+-------------------------------

 Important Data | 2026-07-20 00:45:51.481518+00

(1 row)

pg-standby ⇒ 在备库上查询表

BASH
sudo -u postgres psql -c " \
       select *, current_timestamp from stream_table"
TEXT
    message     |       current_timestamp
----------------+-------------------------------

 Important Data | 2026-07-20 00:45:51.896045+00

(1 row)

多 Stanza 配置

pgBackRest 支持多个 stanza，最常见的用法是多个 stanza 共用同一台仓库主机。

安装

创建一台名为 pg-alt 的新主机，用于运行新的主库。

推荐通过软件包安装 pgBackRest，而非从源码编译。软件包安装时，本节后续步骤通常无需手动执行，但个别软件包可能漏建某些目录或权限设置有误，此时需手动创建目录或修正权限。

RHEL 平台的 pgBackRest 软件包可在 yum.postgresql.org 获取。

若您的发行版没有提供现成软件包，可参考 编译构建 手动安装。

pg-alt ⇒ 安装依赖

BASH
sudo yum install postgresql-libs libssh2

pg-alt ⇒ 从构建主机复制 pgBackRest 二进制文件

BASH
sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin
sudo chmod 755 /usr/bin/pgbackrest

pgBackRest 需要日志目录、配置目录以及配置文件。

pg-alt ⇒ 创建 pgBackRest 配置文件和目录

BASH
sudo mkdir -p -m 770 /var/log/pgbackrest
sudo chown postgres:postgres /var/log/pgbackrest
sudo mkdir -p /etc/pgbackrest
sudo mkdir -p /etc/pgbackrest/conf.d
sudo touch /etc/pgbackrest/pgbackrest.conf
sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf

配置

pg-alt 的 pgBackRest 配置与 pg-primary 基本相同，区别在于使用 demo-alt stanza，备份和归档因此存储在独立的位置。

pg-alt:/etc/pgbackrest/pgbackrest.conf ⇒ 在新主库上配置 pgBackRest

INI
[demo-alt]
pg1-path=/var/lib/pgsql/14/data
[global]
log-level-file=detail
repo1-host=repository
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt
repo1-host-key-file=/etc/pgbackrest/cert/client.key
repo1-host-type=tls
tls-server-address=*
tls-server-auth=pgbackrest-client=demo-alt
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pg1-host/pg1-host-user 和 pg1-path

INI
[demo]
pg1-host=pg-primary
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/14/data
[demo-alt]
pg1-host=pg-alt
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/14/data
[global]
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
tls-server-address=*
tls-server-auth=pgbackrest-client=*
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

pg-alt ⇒ 配置 pgBackRest 服务器

BASH
sudo cat /etc/systemd/system/pgbackrest.service
INI
[Unit]
Description=pgBackRest Server
After=network.target
StartLimitIntervalSec=0
[Service]
Type=notify
Restart=always
RestartSec=1
User=postgres
ExecStart=/usr/bin/pgbackrest server
ExecStartPost=/bin/sleep 3
ExecStartPost=/bin/bash -c "[ ! -z $MAINPID ]"
ExecReload=/bin/kill -HUP $MAINPID
[Install]
WantedBy=multi-user.target
BASH
sudo systemctl enable pgbackrest
sudo systemctl start pgbackrest

初始化演示集群

pg-alt ⇒ 创建演示集群

BASH
sudo -u postgres /usr/pgsql-14/bin/initdb \
       -D /var/lib/pgsql/14/data -k -A peer

pg-alt:/var/lib/pgsql/14/data/postgresql.conf ⇒ 配置 PostgreSQL 设置

INI
archive_command = 'pgbackrest --stanza=demo-alt archive-push %p'
archive_mode = on
log_filename = 'postgresql.log'

pg-alt ⇒ 启动演示集群

BASH
sudo systemctl restart postgresql-14.service

创建 Stanza 并检查配置

需运行 stanza-create 命令初始化 stanza，之后建议运行 check 命令，确认归档和备份配置正确。

pg-alt ⇒ 创建 stanza 并检查配置

BASH
sudo -u postgres pgbackrest --stanza=demo-alt --log-level-console=info stanza-create
TEXT
P00   INFO: stanza-create command begin 2.59.0: --exec-id=928-613b418d --log-level-console=info --log-level-file=detail --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --stanza=demo-alt
P00   INFO: stanza-create for stanza 'demo-alt' on repo1

P00   INFO: stanza-create command end: completed successfully
BASH
sudo -u postgres pgbackrest --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=961-0c86a782 --log-level-console=info --log-level-file=detail --no-log-timestamp --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls

P00   INFO: check stanza 'demo-alt'

P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 000000010000000000000001 successfully archived to '/var/lib/pgbackrest/archive/demo-alt/14-1/0000000100000000/000000010000000000000001-3148a34e7fa88aa437af38678ddbab2590adb628.gz' on repo1

P00   INFO: check command end: completed successfully

在仓库主机上运行 check 命令时，会检查所有 stanza。

repository ⇒ 检查所有 stanza 的配置

BASH
sudo -u pgbackrest pgbackrest --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=1379-a0628038 --log-level-console=info --no-log-timestamp --repo1-path=/var/lib/pgbackrest

P00   INFO: check stanza 'demo'

P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 000000070000000000000027 successfully archived to '/var/lib/pgbackrest/archive/demo/14-1/0000000700000000/000000070000000000000027-2137d43223a1bec901a46c8eb8feea0d77addf33.gz' on repo1
P00   INFO: check stanza 'demo-alt'

P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 000000010000000000000002 successfully archived to '/var/lib/pgbackrest/archive/demo-alt/14-1/0000000100000000/000000010000000000000002-0103254ce8b2225563e6b0ae03e3e580335f0a05.gz' on repo1

P00   INFO: check command end: completed successfully

异步归档

通过 archive-async 选项可启用异步归档，该选项同时适用于 archive-push 和 archive-get 命令。

异步归档需要配置缓冲区路径（spool path）。两个命令都会在此存储临时数据，但工作方式各有不同，具体用法将在各节中详细说明。

pg-primary ⇒ 创建缓冲区目录

BASH
sudo mkdir -p -m 750 /var/spool/pgbackrest
sudo chown postgres:postgres /var/spool/pgbackrest

pg-standby ⇒ 创建缓冲区目录

BASH
sudo mkdir -p -m 750 /var/spool/pgbackrest
sudo chown postgres:postgres /var/spool/pgbackrest

需配置缓冲区路径并启用异步归档。异步归档通过减少远程存储的连接次数自动带来一定的性能提升，配置 process-max 还可通过并行化操作大幅提升吞吐量。注意不要将 process-max 设置过高，以免影响正常数据库操作。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 配置缓冲区路径和异步归档

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
[global]
archive-async=y
log-level-file=detail
repo1-host=repository
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt
repo1-host-key-file=/etc/pgbackrest/cert/client.key
repo1-host-type=tls
spool-path=/var/spool/pgbackrest
tls-server-address=*
tls-server-auth=pgbackrest-client=demo
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key
[global:archive-get]
process-max=2
[global:archive-push]
process-max=2

pg-standby:/etc/pgbackrest/pgbackrest.conf ⇒ 配置缓冲区路径和异步归档

INI
[demo]
pg1-path=/var/lib/pgsql/14/data
recovery-option=primary_conninfo=host=172.17.0.6 port=5432 user=replicator
[global]
archive-async=y
log-level-file=detail
repo1-host=repository
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt
repo1-host-key-file=/etc/pgbackrest/cert/client.key
repo1-host-type=tls
spool-path=/var/spool/pgbackrest
tls-server-address=*
tls-server-auth=pgbackrest-client=demo
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key
[global:archive-get]
process-max=2
[global:archive-push]
process-max=2

注意：

process-max 通过命令专属配置节（command sections）设置，这样备份和恢复操作就不会受其影响，同时也允许为 archive-push 和 archive-get 分别设置不同的值。

为演示效果，下面通过中断流复制，强制 PostgreSQL 使用 restore_command 获取 WAL。

pg-primary ⇒ 通过更改复制密码来中断流复制

BASH
sudo -u postgres psql -c "alter user replicator password 'bogus'"
SQL
ALTER ROLE

pg-standby ⇒ 重启备库以中断连接

BASH
sudo systemctl restart postgresql-14.service

归档推送（Archive Push）

异步 archive-push 命令将 WAL 归档工作交给独立进程（或多个进程）处理，以提升吞吐量。其工作原理是"向前预读"——在 PostgreSQL 当前通过 archive_command 请求的 WAL 段之外，预先查找并归档其他已就绪的 WAL 段。WAL 段直接从 pg_xlog/pg_wal 目录传输到归档存储，只有 WAL 段安全入库后，archive_command 才返回成功。

缓冲区路径保存当前 WAL 归档的状态。写入其中的状态文件通常长度为零，占用空间极少（最多几 MB），IO 开销也很小。目录中的所有信息均可重建，因此将集群迁移到新硬件时无需保留缓冲区目录。

重要提示：

早期实现中，WAL 段在压缩和传输之前会先复制到缓冲区目录；新实现直接从 pg_xlog 目录复制 WAL。如果曾在 v1.12 或更早版本中使用过异步归档，请在升级前仔细阅读 v1.13 的发版说明。

可通过 [stanza]-archive-push-async.log 文件监控异步进程的活动。一个简单的测试方法是连续快速推送多个 WAL 段。

pg-primary ⇒ 测试并行异步归档

BASH
sudo -u postgres psql -c " \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal();"

sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check
TEXT
P00   INFO: check command begin 2.59.0: --exec-id=6853-b3bcef41 --log-level-console=info --log-level-file=detail --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --stanza=demo
P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)

P00   INFO: WAL segment 00000007000000000000002D successfully archived to '/var/lib/pgbackrest/archive/demo/14-1/0000000700000000/00000007000000000000002D-7234f698378e4ca6cdfc7270f97a766cfda99fbd.gz' on repo1

P00   INFO: check command end: completed successfully

现在日志文件中将包含并行异步活动的记录。

pg-primary ⇒ 查看日志中的结果

BASH
sudo -u postgres cat /var/log/pgbackrest/demo-archive-push-async.log
TEXT
-------------------PROCESS START-------------------
P00   INFO: archive-push:async command begin 2.59.0: [/var/lib/pgsql/14/data/pg_wal] --archive-async --exec-id=6817-01bf97bf --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --process-max=2 --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --spool-path=/var/spool/pgbackrest --stanza=demo

P00   INFO: push 1 WAL file(s) to archive: 000000070000000000000028
P01 DETAIL: pushed WAL file '000000070000000000000028' to the archive

P00 DETAIL: statistics: {"socket.client":{"total":1},"socket.session":{"total":1},"tls.client":{"total":1},"tls.session":{"total":1}}
P00   INFO: archive-push:async command end: completed successfully

-------------------PROCESS START-------------------
P00   INFO: archive-push:async command begin 2.59.0: [/var/lib/pgsql/14/data/pg_wal] --archive-async --exec-id=6855-8e4b8e04 --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --process-max=2 --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --spool-path=/var/spool/pgbackrest --stanza=demo

P00   INFO: push 5 WAL file(s) to archive: 000000070000000000000029...00000007000000000000002D
P02 DETAIL: pushed WAL file '00000007000000000000002A' to the archive
P01 DETAIL: pushed WAL file '000000070000000000000029' to the archive
P02 DETAIL: pushed WAL file '00000007000000000000002B' to the archive
P01 DETAIL: pushed WAL file '00000007000000000000002C' to the archive
P02 DETAIL: pushed WAL file '00000007000000000000002D' to the archive

P00 DETAIL: statistics: {"socket.client":{"total":1},"socket.session":{"total":1},"tls.client":{"total":1},"tls.session":{"total":1}}
P00   INFO: archive-push:async command end: completed successfully

归档获取（Archive Get）

异步 archive-get 命令通过维护本地 WAL 队列来提升吞吐量。若队列中找不到某个 WAL 段，会从仓库获取该段及足够多的连续 WAL 段填满队列，队列最大容量由 archive-get-queue-max 定义。当队列容量低于一半时，会自动获取更多 WAL 进行填充。

在 WAL 生成量较大、或与仓库存储（如 S3 等对象存储）连接延迟较高的环境中，异步操作最为有益。延迟较高时，适当增大 process-max 也有帮助。

可通过 [stanza]-archive-get-async.log 文件监控异步进程的活动。

pg-standby ⇒ 查看日志中的结果

BASH
sudo -u postgres cat /var/log/pgbackrest/demo-archive-get-async.log
TEXT
-------------------PROCESS START-------------------
P00   INFO: archive-get:async command begin 2.59.0: [000000070000000000000024, 000000070000000000000025, 000000070000000000000026, 000000070000000000000027, 000000070000000000000028, 000000070000000000000029, 00000007000000000000002A, 00000007000000000000002B] --archive-async --exec-id=1847-b6ebf0f1 --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --process-max=2 --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --spool-path=/var/spool/pgbackrest --stanza=demo
P00   INFO: get 8 WAL file(s) from archive: 000000070000000000000024...00000007000000000000002B

P02 DETAIL: found 000000070000000000000025 in the repo1: 14-1 archive
P01 DETAIL: found 000000070000000000000024 in the repo1: 14-1 archive
P02 DETAIL: found 000000070000000000000026 in the repo1: 14-1 archive
P01 DETAIL: found 000000070000000000000027 in the repo1: 14-1 archive

P00 DETAIL: unable to find 000000070000000000000028 in the archive
P00 DETAIL: statistics: {"socket.client":{"total":1},"socket.session":{"total":1},"tls.client":{"total":1},"tls.session":{"total":1}}
       [filtered 24 lines of output]
P00   INFO: archive-get:async command begin 2.59.0: [000000070000000000000028, 000000070000000000000029, 00000007000000000000002A, 00000007000000000000002B, 00000007000000000000002C, 00000007000000000000002D, 00000007000000000000002E, 00000007000000000000002F] --archive-async --exec-id=1902-6e53470d --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/pgsql/14/data --process-max=2 --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --spool-path=/var/spool/pgbackrest --stanza=demo
P00   INFO: get 8 WAL file(s) from archive: 000000070000000000000028...00000007000000000000002F

P02 DETAIL: found 000000070000000000000029 in the repo1: 14-1 archive
P01 DETAIL: found 000000070000000000000028 in the repo1: 14-1 archive
P02 DETAIL: found 00000007000000000000002A in the repo1: 14-1 archive
P01 DETAIL: found 00000007000000000000002B in the repo1: 14-1 archive
P01 DETAIL: found 00000007000000000000002C in the repo1: 14-1 archive
P02 DETAIL: found 00000007000000000000002D in the repo1: 14-1 archive

P00 DETAIL: unable to find 00000007000000000000002E in the archive
P00 DETAIL: statistics: {"socket.client":{"total":1},"socket.session":{"total":1},"tls.client":{"total":1},"tls.session":{"total":1}}
       [filtered 7 lines of output]

pg-primary ⇒ 通过更改复制密码恢复流复制

BASH
sudo -u postgres psql -c "alter user replicator password 'jw8s0F4'"
SQL
ALTER ROLE

从备库备份

pgBackRest 支持在备库而非主库上执行备份。从备库备份需要配置 pg-standby 主机并启用 backup-standby 选项。若配置了多个备库，将使用第一个处于运行状态的备库。

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 配置 pg2-host/pg2-host-user 和 pg2-path

INI
[demo]
pg1-host=pg-primary
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/14/data
pg2-host=pg-standby
pg2-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg2-host-cert-file=/etc/pgbackrest/cert/client.crt
pg2-host-key-file=/etc/pgbackrest/cert/client.key
pg2-host-type=tls
pg2-path=/var/lib/pgsql/14/data
[demo-alt]
pg1-host=pg-alt
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/14/data
[global]
backup-standby=y
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
tls-server-address=*
tls-server-auth=pgbackrest-client=*
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

备份时主库和备库都必须在线，但绝大多数文件从备库复制，从而减轻主库的负载。数据库主机可以按任意顺序配置，pgBackRest 会自动识别主备角色。

repository ⇒ 从 pg2 备份演示集群

BASH
sudo -u pgbackrest pgbackrest --stanza=demo --log-level-console=detail backup
TEXT
       [filtered 2 lines of output]
P00   INFO: execute backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000007000000000000002F, lsn = 0/2F000028

P00   INFO: wait for replay on the standby to reach 0/2F000028
P00   INFO: replay on the standby reached 0/2F000028

P00   INFO: check archive for prior segment 00000007000000000000002E

P01 DETAIL: backup file pg-primary:/var/lib/pgsql/14/data/log/postgresql.log (11.1KB, 0.43%) checksum ec93a5e8f2619b8c7d8b8d42b2b30b4e175784da
P01 DETAIL: backup file pg-primary:/var/lib/pgsql/14/data/global/pg_control (8KB, 0.74%) checksum 9e61a174e615df1f2f754dfff187f4661733973f
P01 DETAIL: backup file pg-primary:/var/lib/pgsql/14/data/pg_hba.conf (4.5KB, 0.91%) checksum cfa97af1dab1b130f0a921fa2d10d76fe0c5f630

P01 DETAIL: match file from prior backup pg-primary:/var/lib/pgsql/14/data/current_logfiles (26B, 0.91%) checksum 78a9f5c10960f0d91fcd313937469824861795a2
P01 DETAIL: match file from prior backup pg-primary:/var/lib/pgsql/14/data/pg_logical/replorigin_checkpoint (8B, 0.91%) checksum 347fc8f2df71bd4436e38bd1516ccd7ea0d46532
       [filtered 1263 lines of output]

从此增量备份可以看出，大部分文件从 pg-standby 复制，只有少数文件来自 pg-primary。

pgBackRest 从备库创建的备份与在主库上执行的备份完全等价。其实现方式是：在 pg-primary 上启动/停止备份，从 pg-standby 复制已完成复制的文件，再从 pg-primary 补充少量剩余文件。因此主库的日志和统计信息也会包含在备份中。

升级 PostgreSQL

将 PostgreSQL 升级到新主版本后，必须立即将所有 pgBackRest 配置中的 pg-path 更新为新路径，并运行 stanza-upgrade 命令。若主机上配置了多个仓库，每个仓库上的 stanza 都会被升级。若数据库处于离线状态，请使用 --no-online 选项。

以下说明并非 PostgreSQL 升级的完整指南，而是概述升级主库和备库的一般流程，重点演示重新配置 pgBackRest 所需的步骤。建议升级前先执行一次备份。

pg-primary ⇒ 停止旧集群

BASH
sudo systemctl stop postgresql-14.service

备库将从新升级的集群恢复，因此也需要停止旧集群。

pg-standby ⇒ 停止旧集群

BASH
sudo systemctl stop postgresql-14.service

初始化新集群并执行升级。

pg-primary ⇒ 创建新集群并执行升级

BASH
sudo -u postgres /usr/pgsql-15/bin/initdb \
       -D /var/lib/pgsql/15/data -k -A peer

sudo -u postgres sh -c 'cd /var/lib/pgsql && \
       /usr/pgsql-15/bin/pg_upgrade \
       --old-bindir=/usr/pgsql-14/bin \
       --new-bindir=/usr/pgsql-15/bin \
       --old-datadir=/var/lib/pgsql/14/data \
       --new-datadir=/var/lib/pgsql/15/data \
       --old-options=" -c config_file=/var/lib/pgsql/14/data/postgresql.conf" \
       --new-options=" -c config_file=/var/lib/pgsql/15/data/postgresql.conf"'
TEXT
       [filtered 41 lines of output]
Checking for extension updates                              ok

Upgrade Complete

----------------
Optimizer statistics are not transferred by pg_upgrade.
       [filtered 4 lines of output]

配置新集群的相关参数。

pg-primary:/var/lib/pgsql/15/data/postgresql.conf ⇒ 配置 PostgreSQL

INI
archive_command = 'pgbackrest --stanza=demo archive-push %p'
archive_mode = on
log_filename = 'postgresql.log'

更新所有主机上的 pgBackRest 配置，使其指向新集群。

pg-primary:/etc/pgbackrest/pgbackrest.conf ⇒ 升级 pg1-path

INI
[demo]
pg1-path=/var/lib/pgsql/15/data
[global]
archive-async=y
log-level-file=detail
repo1-host=repository
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt
repo1-host-key-file=/etc/pgbackrest/cert/client.key
repo1-host-type=tls
spool-path=/var/spool/pgbackrest
tls-server-address=*
tls-server-auth=pgbackrest-client=demo
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key
[global:archive-get]
process-max=2
[global:archive-push]
process-max=2

pg-standby:/etc/pgbackrest/pgbackrest.conf ⇒ 升级 pg-path

INI
[demo]
pg1-path=/var/lib/pgsql/15/data
recovery-option=primary_conninfo=host=172.17.0.6 port=5432 user=replicator
[global]
archive-async=y
log-level-file=detail
repo1-host=repository
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt
repo1-host-key-file=/etc/pgbackrest/cert/client.key
repo1-host-type=tls
spool-path=/var/spool/pgbackrest
tls-server-address=*
tls-server-auth=pgbackrest-client=demo
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key
[global:archive-get]
process-max=2
[global:archive-push]
process-max=2

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 升级 pg1-path 和 pg2-path，禁用从备库备份

INI
[demo]
pg1-host=pg-primary
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/15/data
pg2-host=pg-standby
pg2-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg2-host-cert-file=/etc/pgbackrest/cert/client.crt
pg2-host-key-file=/etc/pgbackrest/cert/client.key
pg2-host-type=tls
pg2-path=/var/lib/pgsql/15/data
[demo-alt]
pg1-host=pg-alt
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/14/data
[global]
backup-standby=n
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
tls-server-address=*
tls-server-auth=pgbackrest-client=*
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

pg-primary ⇒ 复制 hba 配置文件

BASH
sudo cp /var/lib/pgsql/14/data/pg_hba.conf \
       /var/lib/pgsql/15/data/pg_hba.conf

启动新集群前，必须先运行 stanza-upgrade 命令。

pg-primary ⇒ 升级 stanza

BASH
sudo -u postgres pgbackrest --stanza=demo --no-online \
       --log-level-console=info stanza-upgrade
TEXT
P00   INFO: stanza-upgrade command begin 2.59.0: --exec-id=7440-cc015b23 --log-level-console=info --log-level-file=detail --no-log-timestamp --no-online --pg1-path=/var/lib/pgsql/15/data --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --stanza=demo
P00   INFO: stanza-upgrade for stanza 'demo' on repo1

P00   INFO: stanza-upgrade command end: completed successfully

启动新集群并验证安装成功。

pg-primary ⇒ 启动新集群

BASH
sudo systemctl start postgresql-15.service

用 check 命令测试配置。

pg-primary ⇒ 检查配置

BASH
sudo systemctl status postgresql-15.service
sudo -u postgres pgbackrest --stanza=demo check

清理旧集群。

pg-primary ⇒ 删除旧集群

BASH
sudo rm -rf /var/lib/pgsql/14/data

在备库上安装新版 PostgreSQL 并准备集群目录。

pg-standby ⇒ 删除旧集群并创建新集群

BASH
sudo rm -rf /var/lib/pgsql/14/data
sudo -u postgres mkdir -p -m 700 /usr/pgsql-15/bin

在仓库主机上运行 check 命令。由于备库集群已停止，出现备库不可用的警告是正常现象。此命令说明仓库服务器已感知到备库的存在，且已为主库服务器正确配置。

repository ⇒ 检查配置

BASH
sudo -u pgbackrest pgbackrest --stanza=demo check
TEXT
P00   WARN: unable to check pg2: [DbConnectError] raised from remote-0 tls protocol on 'pg-standby': unable to connect to 'dbname='postgres' port=5432': connection to server on socket "/run/postgresql/.s.PGSQL.5432" failed: No such file or directory
                Is the server running locally and accepting connections on that socket?

对新集群执行全量备份，然后从备份恢复备库。若请求 incr 或 diff 类型，备份类型将自动升级为 full。

repository ⇒ 运行全量备份

BASH
sudo -u pgbackrest pgbackrest --stanza=demo --type=full backup

pg-standby ⇒ 恢复演示备库集群

BASH
sudo -u postgres pgbackrest --stanza=demo --type=standby restore

pg-standby:/var/lib/pgsql/15/data/postgresql.conf ⇒ 配置 PostgreSQL

INI
hot_standby = on

pg-standby ⇒ 启动 PostgreSQL 并检查 pgBackRest 配置

BASH
sudo systemctl start postgresql-15.service
sudo -u postgres pgbackrest --stanza=demo check

备库恢复完成后，即可重新启用从备库备份。

repository:/etc/pgbackrest/pgbackrest.conf ⇒ 重新启用从备库备份

INI
[demo]
pg1-host=pg-primary
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/15/data
pg2-host=pg-standby
pg2-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg2-host-cert-file=/etc/pgbackrest/cert/client.crt
pg2-host-key-file=/etc/pgbackrest/cert/client.key
pg2-host-type=tls
pg2-path=/var/lib/pgsql/15/data
[demo-alt]
pg1-host=pg-alt
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt
pg1-host-key-file=/etc/pgbackrest/cert/client.key
pg1-host-type=tls
pg1-path=/var/lib/pgsql/14/data
[global]
backup-standby=y
process-max=3
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y
tls-server-address=*
tls-server-auth=pgbackrest-client=*
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt
tls-server-cert-file=/etc/pgbackrest/cert/server.crt
tls-server-key-file=/etc/pgbackrest/cert/server.key

4 - 命令参考

pgBackRest 命令参考手册，包含备份、恢复、归档及管理操作的全部选项。

原始页面： https://pgbackrest.org/command.html

简介

pgBackRest 通过命令来执行各项功能。本文档对每个命令的选项进行了详尽列举——即每个适用于某命令的选项都会随该命令一并列出，即便该选项同样适用于其他命令。所有可在 pgbackrest.conf 中配置的选项均包含在内。

在 pgbackrest.conf 中配置的非布尔型选项，可在命令行上使用 reset- 前缀将其重置为默认值。这一功能在直接于仓库主机上执行恢复时很有用。通常情况下，pgBackRest 检测到数据库主机是远程主机后会报错，因为恢复操作无法远程执行。在命令行添加 --reset-pg1-host 后，pgBackRest 将忽略远程数据库主机并在本地执行恢复。此时可能还需要传入新的 --pg1-path，将恢复操作强制指向特定路径，而非使用数据库主机上的原有路径。

在命令行上，可使用 no- 前缀将布尔型选项设置为 false。

任何选项均可通过环境变量设置，方法是加上 PGBACKREST_ 前缀，将选项名称全部大写，并将 - 替换为 _，例如 pg1-path 对应 PGBACKREST_PG1_PATH，stanza 对应 PGBACKREST_STANZA。布尔型选项的表示方式与配置文件中相同，例如 PGBACKREST_COMPRESS="n"，且不支持 reset-* 变体。可在命令行或配置文件中多次指定的选项，可通过冒号分隔多个值来设置，例如 PGBACKREST_DB_INCLUDE="db1:db2"。

命令行选项优先于环境变量选项，环境变量选项优先于配置文件选项。

关于选项类型的说明，请参阅 配置简介。

命令列表

命令简介
annotate在备份创建后，添加、修改或删除备份注解。
archive-get获取已归档的 WAL 段，用于恢复、PITR 或副本恢复。
archive-push接收来自 PostgreSQL 的 WAL 段并推送到已配置的仓库。
backup将备份创建到目标仓库（默认为优先级最高的仓库）。
check验证 stanza 备份/归档配置及 WAL 归档健康状态。
expire根据已配置的保留策略，过期备份和已归档的 WAL。
help在通用、命令或选项级别显示帮助信息。
info以文本或 JSON 格式显示 stanza 和备份的状态/元数据。
repo-get读取仓库文件（类似 cat），用于管理、排查和测试。
repo-ls列出仓库文件/路径（类似 ls），用于管理、排查和测试。
restore从备份恢复（默认为最新备份），支持可选的时间点恢复。
server运行 pgBackRest TLS 服务器，实现无需 SSH 的远程主机访问。
server-ping向 pgBackRest TLS 服务器发送 ping，验证其是否正在接受连接。
stanza-create在所有已配置的仓库中创建 stanza 元数据。
stanza-delete永久删除某个 stanza 的所有备份和归档。
stanza-upgrade在 PostgreSQL 主版本升级后，升级 stanza 元数据。
start在执行过 stop 命令后，重新允许 pgBackRest 进程运行。
stop阻止新的 pgBackRest 进程启动，并可选择强制停止正在运行的进程。
verify验证仓库中的备份和归档数据是否有效。
version显示已安装的 pgBackRest 版本。

4.1 - 注解命令（annotate）

pgBackRest annotate 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: annotate

backup 命令执行时附加的注解，可在事后通过 annotate 命令进行添加、修改或删除。

命令选项

备份注解选项（--annotation）

为备份添加用户自定义键值对注解。

可为备份附加具有描述性的键值对。此选项可多次使用，以添加多条注解。

使用 --set 指定备份后，注解将显示在 info 命令的文本输出中，并始终出现在 JSON 输出中。

YAML
example: --annotation=source="Sunday backup for website database"

备份集选项（--set）

要添加注解的目标备份集。

指定需要添加注解的备份集名称。

YAML
example: --set=20150131-153358F_20150131-153401I

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

复制、压缩、加密等操作均使用此缓冲区。实际使用的缓冲区数量取决于各选项配置，每个操作可能还会额外占用内存，例如 gz 压缩可能额外使用 256KiB 内存。

允许的值为：16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

若需使用特定的 SSH 客户端，或 ssh 命令不在 $PATH 中，可通过此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，此选项设置网络压缩级别，以减少网络流量。若 compress-type 不等于 none，则忽略 compress-level-network，改用 compress-level，从而避免文件被压缩两次。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项可指定非默认路径的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

该路径下所有扩展名为 .conf 的文件将与 pgBackRest 主配置文件合并，共同构成完整配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置可覆盖 --config 和 --config-include-path 的默认基础路径，但仅在这两个选项未在命令行中明确指定时生效。

例如，若只传入 --config-path=/conf/pgbackrest，则 --config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读写操作的超时时间，单位为秒。

注意：整个读写操作无需在此时间内全部完成，但 必须 持续有进展，哪怕只传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 在此路径下创建锁文件，防止相互冲突的操作并发执行。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器赋予该进程的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。普通进程通常无权提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时时间。

本地或远程进程在协议层等待接收新消息的超时时间，单位为秒。此设置可防止进程无限期等待消息。

注意： protocol-timeout 的值必须大于 db-timeout。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用保活。

在 socket 连接上启用保活消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza。

stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称，包含集群的位置、备份方式、归档选项等信息。大多数数据库主机只有一个 PostgreSQL 集群，因此只需配置一个 stanza；备份服务器则需为每个待备份的集群各配置一个 stanza。

命名 stanza 时，用主库名称固然直观，但用描述数据库实际用途的名称（如 app 或 dw）更为合适，因为该名称对主库和所有副本均适用，而非仅用于本地集群（如 main 或 prod）。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

保活计数。

连接被判定为断开之前，允许丢失的 TCP 保活消息数量。

此选项仅在支持 TCP_KEEPCNT socket 选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

保活空闲时间。

无网络活动持续多少秒后，操作系统开始发送 TCP 保活消息。

此选项仅在支持 TCP_KEEPIDLE socket 选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

保活间隔时间。

未被确认的 TCP 保活消息在多少秒后重新发送。

此选项仅在支持 TCP_KEEPINTVL socket 选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均经过加密，连接对象存储（如 S3）时默认也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。示例中的配置在没有特殊安全要求的情况下是合理的选择。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均经过加密，连接对象存储（如 S3）时默认也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录追踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录追踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别输出到 stderr 而非 stdout（由 log-level-console 指定）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录追踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件存储在此路径下。注意，若 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

在子进程中启用日志记录。

为此进程创建的所有子进程启用文件日志，日志级别由 log-level-file 指定。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中启用时间戳。某些特殊场景（如生成文档时）会禁用此选项。

YAML
default: y
example: --no-log-timestamp

仓库选项

指定仓库选项（--repo）

设置仓库。

指定命令操作的目标仓库。

例如，可使用此选项从指定仓库执行恢复，而不是由 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

设置 repo-path=/ 可将 pgBackRest 仓库存储在容器根目录下，但通常建议指定一个前缀（如 /repo），以便日志及其他 Azure 生成的内容也能存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管身份自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加账户前缀。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

仓库加密所使用的加密算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

注意，即使仓库类型（如 S3）本身支持加密，pgBackRest 也始终在客户端执行加密。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录下，但通常建议指定一个前缀（如 /repo），以便日志及其他 GCS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

连接存储服务所使用的端点，可更新为本地 GCS 服务器或备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账户进行授权。
  • service - 使用本地存储的服务账户密钥。
  • token - 用于本地测试（如 fakegcs）。

当 repo-gcs-key-type=service 时，认证令牌续期时将重新加载凭证。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费归属的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

若备份和归档写入本地挂载的文件系统，则无需此设置。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令。

仅当本地主机与仓库主机上的 pgBackRest 命令路径不同时才需要配置。若未定义，仓库主机命令将与本地命令保持一致。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的位置。仅当仓库主机上的配置文件路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

设置了 repo-host 时的仓库主机端口。

使用此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口取决于 cmd-ssh 所指定命令的配置。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（Secure Shell）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

设置了 repo-host 时的仓库主机用户。

定义在仓库主机上执行操作所使用的用户。建议使用专用用户（如 pgbackrest），而非 postgres 用户。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其具有仓库的读取权限，同时防止意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的位置。

预估所需空间可能较为困难。建议先执行几次备份，记录不同备份类型（全量/增量/差异）的大小，并测量每日产生的 WAL 量，从而大致估算所需空间；当然，随着数据库规模增长，实际需求也会随之变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录下，但通常建议指定一个前缀（如 /repo），以便日志及其他 AWS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义或测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 等选项可能会有所帮助。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭证的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加存储桶前缀。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

包含仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

SFTP 仓库主机指纹的生成方式应与 repo-sftp-host-key-hash-type 匹配。可通过以下命令生成指纹：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录中。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下 SFTP 主机密钥检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts 文件，且拒绝连接到主机密钥已更改或在已知主机文件中找不到的主机。此选项要求用户手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到用户的已知主机文件，但不允许连接到主机密钥已更改的主机。
  • fingerprint - pgBackRest 会将主机密钥与 repo-sftp-host-fingerprint 选项指定的指纹进行比对。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明在 SSH 启动时用于计算远程系统主机密钥摘要的哈希算法。较新版本的 libssh2 除 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

SFTP 仓库主机端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

用于存储仓库的主机上的用户。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

认证时用于搜索 SFTP 主机匹配项的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将只在这些文件中搜索匹配项。文件路径必须为完整路径或以波浪号开头的路径。可多次传入 repo-sftp-known-host 以指定多个已知主机文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参阅 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件。若编译时链接了 OpenSSL，此项为可选；若链接了其他库，则为必填项。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接存储（如 S3、Azure）时使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接存储（如 S3、Azure）时使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的其他主机，通常用于测试场景。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接到存储（如 S3、Azure）端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库为对象存储（如 S3）时，指定要添加到对象上的标签。可重复使用此选项以添加多个标签。

pgBackRest 目前不支持修改这些标签，因此请在运行 stanza-create 之前正确设置，以确保整个仓库的标签一致。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

当文件过大无法全部加载到内存时，S3 等对象存储支持分块上传。即便文件可以全部加载到内存，限制上传时的内存用量也更为高效。

较大的分块大小通常能带来更好的性能，因为它减少了上传请求次数，允许更多文件在单次请求中完成上传而无需分块。其缺点是内存占用更高，且由于分块缓冲区按进程分配，较大的 process-max 值会导致整体内存消耗增加。

注意，有效的分块大小因存储类型和平台而异。例如，AWS S3 的最小分块大小为 5MiB。分块大小的术语也因存储类型而异：AWS S3 称之为"part size"，GCS 称之为"chunk size"，Azure 称之为"block size"。

如果文件大于 1GiB（PostgreSQL 默认创建的最大文件大小），分块大小将逐步增大至允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用存储（如 S3、Azure）服务端 TLS 证书的验证。仅在测试或使用自签名证书等特定场景下才应禁用验证。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud 存储
  • posix - 符合 POSIX 规范的文件系统
  • s3 - AWS 简单存储服务
  • sftp - 安全文件传输协议

当使用 NFS 挂载作为 posix 仓库时，适用于 pgBackRest 的规则与 PostgreSQL 文档中的描述相同，参见 创建数据库集群 - 文件系统。

YAML
default: posix
example: --repo1-type=cifs

4.2 - 归档获取命令（archive-get）

pgBackRest archive-get 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: archive-get

PostgreSQL 通过此命令执行备份恢复、PITR，或将其作为流复制的替代方式来维持副本同步。WAL 段是 PostgreSQL 执行恢复或维护副本的必要条件。

配置多个仓库时，pgBackRest 按优先级顺序（如 repo1、repo2 等）依次从各仓库获取 WAL。速度更快或成本更低的存储应配置更高的优先级。若通过 --repo 选项指定了某个仓库，则仅从该仓库中查找。

archive-get 命令由 pgBackRest 在恢复过程中自动配置并生成，供 PostgreSQL 使用。相关示例请参见 时间点恢复。

命令选项

异步归档选项（--archive-async）

异步推送/获取 WAL 段。

启用 archive-push 和 archive-get 命令的异步操作模式。

异步模式效率更高，可复用连接并充分利用并行处理。更多信息请参见 spool-path、archive-get-queue-max 和 archive-push-queue-max 选项。

YAML
default: n
example: --archive-async

归档获取最大队列大小选项（--archive-get-queue-max）

archive-get 队列的最大容量。

指定启用 archive-async 时 archive-get 队列的最大容量。队列存储在 spool-path 中，用于加速向 PostgreSQL 提供 WAL。

YAML
default: 128MiB
allowed: [0B, 4PiB]
example: --archive-get-queue-max=1GiB

重试缺失 WAL 段选项（--archive-missing-retry）

重试缺失的 WAL 段。

在异步模式下，对之前被 archive-get 命令标记为缺失的 WAL 段进行重试。此选项可防止使用缓冲区路径中来自先前恢复的通知，避免在尚未达到一致性状态时导致恢复失败。

禁用此选项后，PostgreSQL 可以更可靠地识别归档中 WAL 的结束位置，从而切换到从主库进行流复制。若启用重试，持续的 WAL 归档流会使 PostgreSQL 继续从归档获取 WAL，而不切换到流复制。

禁用此选项时，务必确保 stanza 的缓冲区路径为空。若恢复时已配置缓冲区路径，restore 命令会自动清空；否则需要手动清空。

YAML
default: y
example: --no-archive-missing-retry

归档超时选项（--archive-timeout）

归档超时时间。

设置等待每个 WAL 段到达 pgBackRest 归档仓库的最长时间（秒）。此超时适用于 check 和 backup 命令在等待备份一致性所需的 WAL 段完成归档时。

YAML
default: 1m
allowed: [100ms, 1d]
example: --archive-timeout=30

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际占用的缓冲区数量取决于具体选项，每个操作可能额外消耗内存，例如 gz 压缩可能额外占用 256KiB 内存。

允许的值为：16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

pgBackRest 命令选项（--cmd）

pgBackRest 命令路径。

pgBackRest 在某些场景下需要生成命令字符串，例如 restore 命令生成 restore_command 配置时。若未提供 cmd 选项，则使用当前运行的 pgBackRest 进程路径。

注意：

对 pgBackRest 命令进行包装可能导致不可预期的行为，不建议使用。

YAML
default: [path of executed pgbackrest binary]
example: --cmd=/var/lib/pgsql/bin/pgbackrest_wrapper.sh

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

当需要使用特定的 SSH 客户端，或 ssh 命令不在 $PATH 中时，使用此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，通过此选项设置网络传输的压缩级别，以减少网络流量。若 compress-type 不等于 none，则忽略 compress-level-network，改用 compress-level，避免对文件进行二次压缩。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件路径。

使用此选项指定非默认路径的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的目录路径。

该路径下扩展名为 .conf 的配置文件将与主配置文件合并，形成一份完整的配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

用于覆盖 --config 和 --config-include-path 选项的默认基础路径，除非这两个选项已在命令行中显式指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

I/O 超时选项（--io-timeout）

I/O 超时时间。

用于连接及读/写操作的超时时间（秒）。

注意：整个读/写操作不必在此超时内全部完成，但 必须 持续有进展，哪怕每次只传输一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 在此路径下创建锁文件，以防止冲突操作并发运行。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器赋予该进程的优先级（即 niceness 值）。正值降低优先级，负值提升优先级。普通进程在大多数情况下没有权限提升自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

最大进程数选项（--process-max）

用于压缩/传输的最大进程数。

每个进程负责压缩和传输，可加快命令执行速度。但不应将 process-max 设置过高，以免影响数据库性能。

YAML
default: 1
allowed: [1, 999]
example: --process-max=4

协议超时选项（--protocol-timeout）

协议超时时间。

设置本地或远端进程在协议层等待新消息的最长时间（秒），防止进程无限期阻塞等待。

注意： protocol-timeout 选项的值必须大于 db-timeout 选项的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用 keep-alive。

在 socket 连接上启用 keep-alive 消息。

YAML
default: y
example: --no-sck-keep-alive

缓冲区路径选项（--spool-path）

临时数据的存储路径。

该路径用于存储异步 archive-push 和 archive-get 命令的数据。

异步 archive-push 命令在成功将 WAL 存入归档后，向缓冲区路径写入确认文件（失败时写入错误信息），以便前台进程快速通知 PostgreSQL。确认文件非常小——成功时为零字节，失败时仅几百字节。

异步 archive-get 命令会将 WAL 预取至缓冲区路径，以便在 PostgreSQL 请求时快速响应。缓冲区路径与 pg_xlog/pg_wal 位于同一文件系统时，文件移动效率最高。但不建议将缓冲区路径设置在 pg_xlog/pg_wal 目录内部，否则可能导致 pg_rewind 等 PostgreSQL 工具出现问题。

缓冲区路径中存储的数据并非严格意义上的临时数据，重启后应当保留。不过，即使数据丢失也不成问题——pgBackRest 会重新检查每个 WAL 段以确认 archive-push 的归档安全性，并为 archive-get 重建队列。

缓冲区路径应位于本地 Posix 兼容文件系统上，而非 NFS 或 CIFS 等远程文件系统。

YAML
default: /var/spool/pgbackrest
example: --spool-path=/backup/db/spool

Stanza 选项（--stanza）

定义 stanza。

stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称，定义了集群的位置、备份方式、归档选项等。大多数数据库服务器只有一个 PostgreSQL 集群，因此只有一个 stanza；备份服务器则为每个需要备份的集群各配置一个 stanza。

命名 stanza 时，以主集群名称命名虽然直观，但更好的做法是描述集群所承载的业务内容。由于 stanza 名称同时用于主库和所有副本，选用描述集群实际功能的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

Keep-Alive 探测包数量。

指定连接被判定为断开之前，允许丢失的 TCP keep-alive 消息数量。

此选项仅在支持 TCP_KEEPCNT socket 选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

Keep-Alive 空闲时间。

指定在无网络活动多少秒后，操作系统应发送 TCP keep-alive 消息。

此选项仅在支持 TCP_KEEPIDLE socket 选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

Keep-Alive 重传间隔。

指定未收到确认的 TCP keep-alive 消息在多少秒后进行重传。

此选项仅在支持 TCP_KEEPINTVL socket 选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密，默认情况下与对象存储（如 S3）的连接也使用加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。示例中的配置是合理选择，除非有特定安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密，默认情况下与对象存储（如 S3）的连接也使用加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅输出错误
  • warn - 输出警告和错误
  • info - 输出信息、警告和错误
  • detail - 输出详情、信息、警告和错误
  • debug - 输出调试、详情、信息、警告和错误
  • trace - 输出追踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅输出错误
  • warn - 输出警告和错误
  • info - 输出信息、警告和错误
  • detail - 输出详情、信息、警告和错误
  • debug - 输出调试、详情、信息、警告和错误
  • trace - 输出追踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志输出级别。

指定哪些日志级别输出到 stderr（而非 stdout，后者由 log-level-console 控制）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅输出错误
  • warn - 输出警告和错误
  • info - 输出信息、警告和错误
  • detail - 输出详情、信息、警告和错误
  • debug - 输出调试、详情、信息、警告和错误
  • trace - 输出追踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件存储在此路径下。注意：若设置了 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为当前进程创建的子进程启用文件日志，使用 log-level-file 指定的日志级别。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

启用日志时间戳。

在控制台和文件日志中启用时间戳。此选项在生成文档等特殊场景下会被禁用。

YAML
default: y
example: --no-log-timestamp

维护者选项

强制指定 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用指定的 PostgreSQL 版本，而非通过读取 pg_control 或 WAL 头部自动检测到的版本。此选项主要用于 PostgreSQL 分支版本或开发版本——这些版本中的相关值可能与正式发行版不同。PostgreSQL 通过 server_version_num 报告的版本必须与强制指定的版本一致。

警告：

使用此选项需谨慎。pg_control 和 WAL 头部仍会按指定版本的预期格式（即 PostgreSQL 官方开源版本的格式）进行读取。若分支或开发版本修改了 pgBackRest 所依赖字段的格式，将导致不可预期的行为。通常只有当分支在标准 PostgreSQL 成员 之后 添加自定义结构体成员时，此选项才能正常工作。

YAML
example: --pg-version-force=15

仓库选项

指定仓库选项（--repo）

指定操作的目标仓库。

指定命令所操作的仓库。例如，可使用此选项从特定仓库执行恢复，而不是由 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器名称。

用于存储仓库的 Azure 容器。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在容器根目录，但通常建议指定前缀（如 /repo），以便日志及其他 Azure 生成的内容也能存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机并在 URI 前添加账户名。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

仓库加密所用的密码算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

注意：即使仓库类型（如 S3）本身支持加密，pgBackRest 的加密也始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶名称。

用于存储仓库的 GCS 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定前缀（如 /repo），以便日志及其他 GCS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点地址。

用于连接存储服务的端点，可更新为本地 GCS 服务器或备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号授权。
  • service - 使用本地存储的服务账号密钥。
  • token - 用于本地测试，例如 fakegcs。

设置 repo-gcs-key-type=service 时，认证令牌续期时会重新加载凭证。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费归属的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机地址。

若备份和归档目标为本地挂载的文件系统，则无需配置此选项。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

向仓库主机发送，用于证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令路径。

仅当本地主机与仓库主机上的 pgBackRest 命令路径不同时才需要配置。若未定义，仓库主机命令将与本地命令保持一致。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件路径。

设置仓库主机上的配置文件位置。仅当仓库主机上的配置文件路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

设置了 repo-host 时使用的仓库主机端口。

使用此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（SSH）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

设置了 repo-host 时使用的仓库主机用户。

定义在仓库主机上执行操作的用户。建议使用非 postgres 的专用用户（如 pgbackrest）。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其具有仓库读取权限，同时避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

pgBackRest 在此仓库中存储备份并归档 WAL 段。

预估所需空间并不容易。建议先执行几次备份，记录不同类型备份（全量/增量/差异）的大小，并统计每天产生的 WAL 量，从而大致估算所需空间。随着数据库规模增长，需求也会随之变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶名称。

用于存储仓库的 S3 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定前缀（如 /repo），以便日志及其他 AWS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点地址。

AWS 端点应与所选区域匹配。

对于自定义或测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 选项可能有所帮助。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭证的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机并在 URI 前添加存储桶名。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机地址。

包含仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

SFTP 仓库主机指纹的生成方式应与 repo-sftp-host-key-hash-type 匹配。可通过以下命令生成指纹：

TEXT
awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b

SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts 文件，且拒绝连接主机密钥已更改或未在已知主机文件中找到的主机。此选项要求用户手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到用户的已知主机文件，但不允许连接主机密钥已更改的主机。
  • fingerprint - pgBackRest 将根据 repo-sftp-host-fingerprint 选项指定的指纹检查主机密钥。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明在 SSH 启动时计算远端系统主机密钥摘要所使用的哈希类型。较新版本的 libssh2 除支持 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

SFTP 仓库主机的连接端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

用于存储仓库的主机上的用户。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

身份验证时用于查找 SFTP 主机匹配项的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将仅在这些路径中查找匹配项。文件路径必须为完整路径或以波浪号开头的路径。可多次传入 repo-sftp-known-host 以指定多个已知主机文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参见 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于身份验证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于身份验证的 SFTP 公钥文件。若编译时使用 OpenSSL 则为可选，若使用其他库则为必填。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接存储（如 S3、Azure）时使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file, repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接存储（如 S3、Azure）时使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path, repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机，通常用于测试。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host, repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储（如 S3、Azure）端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port, repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库为对象存储（如 S3）时，为对象添加指定标签。此选项可重复使用以添加多个标签。

pgBackRest 不提供修改标签的功能，因此请在运行 stanza-create 之前确保标签设置正确，以保证整个仓库标签的一致性。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

当文件过大无法全部存入内存时，S3 等对象存储支持分块上传。即使文件能够存入内存，限制上传内存用量也更为高效。

较大的分块大小通常可提升性能，因为它能减少上传请求次数，让更多文件在单次请求中完成上传，而非分块传输。缺点是内存占用更高——由于分块缓冲区需按进程分配，process-max 值越大，总体内存消耗越多。

注意，有效的分块大小因存储类型和平台而异。例如，AWS S3 的最小分块大小为 5MiB。各存储类型对分块大小的术语也不同：AWS S3 称为"part size"，GCS 称为"chunk size"，Azure 称为"block size"。

若文件大于 1GiB（PostgreSQL 默认创建文件的最大大小），则分块大小将递增至允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用对存储（如 S3、Azure）服务器 TLS 证书的验证。仅在测试或使用自签名证书的场景下才应禁用验证。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls, repo-s3-verify-ssl, repo-s3-verify-tls

仓库目标时间选项（--repo-target-time）

仓库目标时间。

目标时间定义了命令读取版本化存储上仓库时所参照的时间点。通过此选项，命令可以读取某一历史时间点的仓库状态，从而恢复因用户误操作或恶意软件导致删除或损坏的数据。

S3、GCS 和 Azure 均支持版本化存储，但通常默认未启用。除了启用版本化，还可以考虑为 S3 启用对象锁定，为 GCS 或 Azure 启用软删除功能。

指定 repo-target-time 时，还必须同时提供 repo 选项。通常并非所有仓库类型都支持版本化功能，因此建议针对单个仓库进行恢复。

注意：与存储时间戳的比较采用小于等于（<=）的方式，且时间戳中的毫秒部分在比较时会被截断。

YAML
example: --repo-target-time=2024-08-08 12:12:12+00

仓库类型选项（--repo-type）

仓库所使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud Storage
  • posix - 符合 Posix 标准的文件系统
  • s3 - AWS Simple Storage Service
  • sftp - 安全文件传输协议

将 NFS 挂载用作 posix 仓库时，适用于 pgBackRest 的规则与 PostgreSQL 文档中描述的规则相同，请参见 Creating a Database Cluster - File Systems。

YAML
default: posix
example: --repo1-type=cifs

Stanza 选项

PostgreSQL 路径选项（--pg-path）

PostgreSQL 数据目录。

应与 PostgreSQL 报告的 data_directory 一致。尽管此值可从多处读取，但建议明确配置，以防在恢复或离线备份场景中相关资源不可用。

pg-path 选项在每次在线备份时都会与 PostgreSQL 报告的值进行校验，因此应始终保持最新。

YAML
example: --pg1-path=/data/db

已弃用名称：db-path

4.3 - 归档推送命令（archive-push）

pgBackRest archive-push 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: archive-push

接收来自 PostgreSQL 的 WAL 段，并将其归档到各个仓库中（仓库路径由带索引的 repo-path 选项定义，详见 仓库选项 章节）。WAL 段可以立即推送到归档，也可以根据 archive-async 的值先暂存在本地。配置了多个仓库时，archive-push 会尽量向所有仓库推送。

archive-push 由 PostgreSQL 负责配置和调用。相关示例请参见 配置归档。

命令选项

异步归档选项（--archive-async）

异步推送/获取 WAL 段。

为 archive-push 和 archive-get 命令启用异步操作模式。

异步模式效率更高，因为它能复用连接并充分利用并行处理能力。详情请参见 spool-path、archive-get-queue-max 和 archive-push-queue-max 选项。

YAML
default: n
example: --archive-async

归档检查选项（--archive-check）

在备份完成前检查 WAL 段是否已存入归档。

检查使备份达到一致性所需的全部 WAL 段是否已存在于 WAL 归档中。除非采用了其他归档方式，否则建议保留默认值。

若启用了 archive-copy，则必须同时启用此选项。

YAML
default: y
example: --no-archive-check

归档模式检查选项（--archive-mode-check）

检查 PostgreSQL 的 archive_mode 设置。

此选项默认启用，用于禁止 PostgreSQL 使用 archive_mode=always。

从备库推送的 WAL 段，其内容在逻辑上可能与从主库推送的相同，但校验和不同。为避免冲突，建议禁止从多个来源归档。

注意：

若禁用此选项，必须确保只有一个归档进程通过 archive-push 命令向仓库写入数据。

YAML
default: y
example: --no-archive-mode-check

归档推送批量大小选项（--archive-push-batch-size）

每轮异步执行可推送的最大 WAL 量。

在异步模式下，archive-push 进程会在单轮执行中推送所有已就绪的 WAL 段。由于 archive-push-queue-max 只在每轮开始时检查，若单轮处理的 WAL 段数量非常多，队列可能在再次检查前增长到远超限制。

此选项限制每轮处理的 WAL 量，使进程退出，并由下一次 archive-push 再次启动，从而重新检查队列。较小的值会更频繁地检查队列，但代价是更频繁地启动异步进程。该值会向下取整为 WAL 段大小的整数倍，但每轮至少会处理一个 WAL 段。

YAML
default: 16GiB
allowed: [1MiB, 4PiB]
example: --archive-push-batch-size=1GiB

最大 archive-push 队列大小选项（--archive-push-queue-max）

PostgreSQL 归档队列的最大大小。

达到限制后，将发生以下情况：

  • pgBackRest 会通知 PostgreSQL WAL 已成功归档，然后将其 丢弃。
  • 会在 PostgreSQL 日志中输出一条警告。

若发生此情况，归档日志流将被中断，此后将无法执行 PITR。需要执行新的备份才能恢复完整的恢复能力。

在异步模式下会丢弃整个队列，以防队列再次超过上限前仍有零星 WAL 段进入归档。

在异步模式下，此限制仅在每轮 archive-push 开始时检查，因此单轮执行期间队列可能增长到超过此限制。可减小 archive-push-batch-size，以更频繁地检查队列。

此功能的目的是防止日志卷被写满——日志卷写满会导致 PostgreSQL 完全停止。宁可丢失备份，也好过让 PostgreSQL 宕机。

YAML
allowed: [0B, 4PiB]
example: --archive-push-queue-max=1TiB

已弃用名称：archive-queue-max

归档超时选项（--archive-timeout）

归档超时时间。

等待每个 WAL 段到达 pgBackRest 归档仓库的最长时间（秒）。此超时适用于 check 和 backup 命令等待备份一致性所需 WAL 段完成归档的场景。

YAML
default: 1m
allowed: [100ms, 1d]
example: --archive-timeout=30

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于具体选项，每种操作可能额外占用内存，例如 gz 压缩可能额外占用 256KiB。

允许的值：16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB、16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

pgBackRest 命令选项（--cmd）

pgBackRest 命令路径。

pgBackRest 有时需要生成命令字符串，例如 restore 命令生成 restore_command 配置时。若未提供 cmd 选项，则使用当前运行的 pgBackRest 进程路径。

注意：

对 pgBackRest 命令进行包装可能导致不可预期的行为，不建议使用。

YAML
default: [path of executed pgbackrest binary]
example: --cmd=/var/lib/pgsql/bin/pgbackrest_wrapper.sh

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

如需使用特定的 SSH 客户端，或 ssh 命令不在 $PATH 中，可通过此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

压缩选项（--compress）

启用文件压缩。

备份文件与命令行压缩工具兼容。

此选项已弃用，请改用 compress-type 选项。

YAML
default: y
example: --no-compress

压缩级别选项（--compress-level）

文件压缩级别。

当 compress-type 不等于 none，或使用已弃用的 compress=y 时，此选项指定文件压缩级别。

YAML
default (depending on compress-type):
   bz2 - 9
   gz - 6
   lz4 - 1
   zst - 3

allow range (depending on compress-type):
   bz2 - [1, 9]
   gz - [-1, 9]
   lz4 - [-5, 12]
   zst - [-7, 22]

example: --compress-level=9

网络压缩级别选项（--compress-level-network）

网络传输压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，通过此选项设置网络传输的压缩级别以减少网络流量。若 compress-type 不等于 none，则忽略 compress-level-network，改用 compress-level，从而避免对文件进行二次压缩。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

压缩类型选项（--compress-type）

文件压缩类型。

支持以下压缩类型：

  • none - 不压缩
  • bz2 - bzip2 压缩格式
  • gz - gzip 压缩格式
  • lz4 - lz4 压缩格式（并非所有平台均支持）
  • zst - Zstandard 压缩格式（并非所有平台均支持）
YAML
default: gz
example: --compress-type=none

配置文件选项（--config）

pgBackRest 配置文件路径。

指定非默认路径的配置文件时使用此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的目录路径。

该路径下扩展名为 .conf 的配置文件将与主配置文件合并，共同构成完整配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

用于覆盖 --config 和 --config-include-path 选项的默认基础路径，前提是这两个选项未在命令行中显式指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读/写操作的超时时间（秒）。

注意：整个读/写操作无需在此超时内全部完成，但 必须 有进展，哪怕只传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 在此路径下创建锁文件，以防止冲突操作并发运行。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器赋予该进程的优先级（即 niceness 值）。正值降低优先级，负值提升优先级。普通进程通常没有权限自行提升优先级。

YAML
allowed: [-20, 19]
example: --priority=19

最大进程数选项（--process-max）

用于压缩/传输的最大进程数。

每个进程负责压缩和传输，可加快命令执行速度。但 process-max 不宜设置过高，否则可能影响数据库性能。

YAML
default: 1
allowed: [1, 999]
example: --process-max=4

协议超时选项（--protocol-timeout）

协议超时时间。

本地或远端进程在协议层等待新消息的最长时间（秒），防止进程无限期阻塞。

注意： protocol-timeout 选项的值必须大于 db-timeout 选项的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用 keep-alive。

在 socket 连接上启用 keep-alive 消息。

YAML
default: y
example: --no-sck-keep-alive

缓冲区路径选项（--spool-path）

临时数据的存储路径。

用于存储异步 archive-push 和 archive-get 命令数据的路径。

异步 archive-push 命令在成功将 WAL 存入归档后，会在缓冲区路径写入确认文件（失败时写入错误信息），供前台进程快速通知 PostgreSQL。确认文件非常小——成功时为零字节，失败时仅几百字节。

异步 archive-get 命令会将 WAL 缓冲至此路径，以便在 PostgreSQL 请求时快速提供。若缓冲区路径与 pg_xlog/pg_wal 位于同一文件系统，文件移动效率最高。但不建议将缓冲区路径设置在 pg_xlog/pg_wal 目录内部，否则可能导致 pg_rewind 等 PostgreSQL 工具出现问题。

缓冲区路径中的数据并非严格意义上的临时数据，重启后应当保留。不过，即使数据丢失也不成问题——pgBackRest 会重新检查每个 WAL 段以确认 archive-push 的归档安全性，并为 archive-get 重建队列。

缓冲区路径应位于本地 Posix 兼容文件系统上，而非 NFS 或 CIFS 等远程文件系统。

YAML
default: /var/spool/pgbackrest
example: --spool-path=/backup/db/spool

Stanza 选项（--stanza）

定义 stanza。

stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称，定义了集群的位置、备份方式、归档选项等。大多数数据库服务器只有一个 PostgreSQL 集群，因此只有一个 stanza；备份服务器则为每个需要备份的数据库集群各配置一个 stanza。

命名 stanza 时，以主集群名称命名虽然直观，但更好的做法是描述集群中所承载的数据库内容。由于 stanza 名称同时适用于主库和所有副本，选用描述集群实际功能的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

Keep-Alive 探测包数量。

连接被判定为断开之前，允许丢失的 TCP keep-alive 消息数量。

此选项仅在支持 TCP_KEEPCNT socket 选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

Keep-Alive 空闲时间。

无网络活动超过指定秒数后，操作系统发送 TCP keep-alive 消息的等待时长。

此选项仅在支持 TCP_KEEPIDLE socket 选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

Keep-Alive 重传间隔。

未收到确认的 TCP keep-alive 消息经过指定秒数后进行重传。

此选项仅在支持 TCP_KEEPINTVL socket 选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接同样使用加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。示例中的配置是合理的选择，除非有特定安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接同样使用加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅输出错误
  • warn - 输出警告和错误
  • info - 输出信息、警告和错误
  • detail - 输出详情、信息、警告和错误
  • debug - 输出调试、详情、信息、警告和错误
  • trace - 输出追踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅输出错误
  • warn - 输出警告和错误
  • info - 输出信息、警告和错误
  • detail - 输出详情、信息、警告和错误
  • debug - 输出调试、详情、信息、警告和错误
  • trace - 输出追踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志输出级别。

指定哪些日志级别输出到 stderr（而非 stdout，后者由 log-level-console 控制）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅输出错误
  • warn - 输出警告和错误
  • info - 输出信息、警告和错误
  • detail - 输出详情、信息、警告和错误
  • debug - 输出调试、详情、信息、警告和错误
  • trace - 输出追踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件存储在此路径下。注意：若设置了 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为当前进程派生的子进程启用文件日志，日志级别由 log-level-file 指定。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

启用日志时间戳。

在控制台和文件日志中添加时间戳。此选项在生成文档等特殊场景下会被禁用。

YAML
default: y
example: --no-log-timestamp

维护者选项

WAL 头部检查选项（--archive-header-check）

检查 WAL 头部中的 PostgreSQL 版本/ID。

此选项默认启用，通过对照 PostgreSQL 版本和系统标识符检查 WAL 头部，确保 WAL 被复制到正确的 stanza。这是在核验 pg_control 与 stanza 匹配性、以及验证 WAL 是否来自 pg_control 所在 PostgreSQL 数据目录的基础上进行的额外校验。

因此，禁用此检查相对安全，但仅应在必要时使用，例如 WAL 已加密的场景。

YAML
default: y
example: --no-archive-header-check

强制指定 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用指定的 PostgreSQL 版本，而非通过读取 pg_control 或 WAL 头部自动检测到的版本。此选项主要用于 PostgreSQL 的分支版本或开发版本——这些版本中相关值可能与正式发行版不同。PostgreSQL 通过 server_version_num 报告的版本必须与强制指定的版本一致。

警告：

使用此选项时需谨慎。pg_control 和 WAL 头部仍会按指定版本的预期格式（即 PostgreSQL 官方开源版本的格式）进行解析。若分支或开发版本修改了 pgBackRest 所依赖字段的格式，将导致不可预期的行为。通常只有当分支在标准 PostgreSQL 成员 之后 添加自定义结构体成员时，此选项才能正常工作。

YAML
example: --pg-version-force=15

仓库选项

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器名称。

用于存储仓库的 Azure 容器。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在容器根目录，但通常建议指定前缀（如 /repo），以便日志及其他 Azure 生成的内容也能存入同一容器。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机并在 URI 前添加账户名。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

仓库加密所用的密码算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

注意：即使仓库类型（如 S3）本身支持加密，pgBackRest 的加密始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶名称。

用于存储仓库的 GCS 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定前缀（如 /repo），以便日志及其他 GCS 生成的内容也能存入同一存储桶。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点地址。

用于连接存储服务的端点，可更新为本地 GCS 服务器或备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号授权。
  • service - 使用本地存储的服务账号密钥。
  • token - 用于本地测试，例如 fakegcs。

设置 repo-gcs-key-type=service 时，认证令牌续期时会重新加载凭证。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费归属的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机地址。

若备份和归档目标为本地挂载的文件系统，则无需配置此选项。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机，用于证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令路径。

仅当本地主机与仓库主机上的 pgBackRest 命令路径不同时才需配置。若未定义，仓库主机命令将与本地命令保持一致。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件路径。

设置仓库主机上的配置文件位置。仅当仓库主机上的配置文件路径与本地不同时才需配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地不同时才需配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地不同时才需配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

设置了 repo-host 时使用的仓库主机端口。

为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（SSH）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

设置了 repo-host 时使用的仓库主机用户。

定义在仓库主机上执行操作的用户。建议使用非 postgres 的专用用户（如 pgbackrest）。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其具有仓库读取权限，同时避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

pgBackRest 在此仓库中存储备份并归档 WAL 段。

预估所需空间并不容易。建议先执行几次备份，记录不同类型（全量/增量/差异）的备份大小及每天产生的 WAL 量，从而大致估算所需空间。当然，随着数据库规模增长，需求也会相应变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶名称。

用于存储仓库的 S3 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定前缀（如 /repo），以便日志及其他 AWS 生成的内容也能存入同一存储桶。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点地址。

AWS 端点应与所选区域匹配。

对于自定义或测试配置，可参考 repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 选项。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

存储桶所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭证的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机并在 URI 前添加存储桶名。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机地址。

包含仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

指纹的生成方式应与 repo-sftp-host-key-hash-type 匹配。可通过以下命令生成：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下 SFTP 主机密钥检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts 文件，且拒绝连接主机密钥已更改或不在已知主机文件中的主机。此选项要求用户手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到用户的已知主机文件，但不允许连接主机密钥已更改的主机。
  • fingerprint - pgBackRest 将根据 repo-sftp-host-fingerprint 选项指定的指纹验证主机密钥。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明 SSH 启动时计算远端系统主机密钥摘要所使用的哈希类型。较新版本的 libssh2 除 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

SFTP 仓库主机的连接端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

用于存储仓库的主机上的用户。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

身份验证时用于查找 SFTP 主机匹配项的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将在这些路径中查找匹配项。文件路径必须为完整路径或以波浪号开头的路径。可多次传入 repo-sftp-known-host 以指定多个已知主机文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参见 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于身份验证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于身份验证的 SFTP 公钥文件。若编译时使用 OpenSSL 则为可选，若使用其他库则为必填。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接存储（如 S3、Azure）时使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file, repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接存储（如 S3、Azure）时使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path, repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机，通常用于测试。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host, repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储（如 S3、Azure）端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port, repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库为对象存储（如 S3）时，为对象添加指定标签。此选项可重复使用以添加多个标签。

pgBackRest 不提供修改标签的功能，因此请在运行 stanza-create 之前确保标签设置正确，以保证整个仓库标签的一致性。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

当文件过大无法全部存入内存时，S3 等对象存储支持分块上传。即使文件能够存入内存，限制上传内存用量也更为高效。

较大的分块通常可提升性能，因为它能减少上传请求次数，让更多文件在单次请求中完成上传，而非分块传输。但缺点是内存占用更高——由于分块缓冲区需按进程分配，process-max 值越大，总体内存消耗越多。

注意，有效的分块大小因存储类型和平台而异。例如，AWS S3 的最小分块大小为 5MiB。各存储类型对分块大小的术语也不同：AWS S3 称为"part size"，GCS 称为"chunk size"，Azure 称为"block size"。

若文件大于 1GiB（PostgreSQL 默认创建文件的最大大小），分块大小将递增至允许的最大值以完成上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用对存储（如 S3、Azure）服务器 TLS 证书的验证。仅在测试或使用自签名证书的场景下才应禁用。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls, repo-s3-verify-ssl, repo-s3-verify-tls

仓库类型选项（--repo-type）

仓库所使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud Storage
  • posix - 符合 Posix 标准的文件系统
  • s3 - AWS Simple Storage Service
  • sftp - 安全文件传输协议

将 NFS 挂载用作 posix 仓库时，适用的规则与 PostgreSQL 文档中描述的规则相同，详见 Creating a Database Cluster - File Systems。

YAML
default: posix
example: --repo1-type=cifs

Stanza 选项

PostgreSQL 路径选项（--pg-path）

PostgreSQL 数据目录。

应与 PostgreSQL 报告的 data_directory 一致。尽管此值可从多处读取，但建议明确配置，以防在恢复或离线备份场景中相关资源不可用。

pg-path 选项在每次在线备份时都会与 PostgreSQL 报告的值进行核验，因此应始终保持最新。

YAML
example: --pg1-path=/data/db

已弃用名称：db-path

4.4 - 备份命令（backup）

pgBackRest backup 命令的选项与行为参考。

Source: pgBackRest Command Docs: backup

配置多个仓库时，pgBackRest 默认备份到优先级最高的仓库（如 repo1），除非通过 --repo 选项明确指定目标仓库。

pgBackRest 本身不内置调度器，建议通过 cron 或其他调度机制触发备份。

详情与示例请参见 执行备份。

命令选项

备份注解选项（--annotation）

为备份附加用户自定义的键值对注解。

可为备份附加任意键值对信息，此选项可多次使用以添加多个注解。

通过 --set 指定备份时，info 命令的文本输出会显示注解；JSON 输出则始终包含注解信息。

YAML
example: --annotation=source="Sunday backup for website database"

归档检查选项（--archive-check）

备份完成前检查 WAL 段是否已写入归档。

此选项验证备份一致性所需的全部 WAL 段都已存在于 WAL 归档中。除非使用了其他归档方法，否则建议保留默认值。

若启用了 archive-copy，则必须同时启用此选项。

YAML
default: y
example: --no-archive-check

归档复制选项（--archive-copy）

将一致性所需的 WAL 段直接复制到备份中。

这是一个相对保守的选项，通过将一致性所需的 WAL 段直接存入备份，防范 WAL 归档损坏。WAL 段仍会写入归档，因此此选项会额外占用存储空间。

使用此选项时，建议 archive-push 和 backup 命令采用相同的压缩类型（如 lz4）。否则，WAL 段需要按备份所用的压缩类型重新压缩，这取决于备份期间产生的 WAL 量，代价可能较高。

恢复时，WAL 段位于 pg_xlog/pg_wal 目录中，PostgreSQL 会优先使用这些文件，而不调用 restore_command。

若启用 archive-copy，则必须同时启用 archive-check 选项。

YAML
default: n
example: --archive-copy

归档模式检查选项（--archive-mode-check）

检查 PostgreSQL 的 archive_mode 设置。

此选项默认启用，会禁止使用 PostgreSQL 的 archive_mode=always 配置。

从备库推送的 WAL 段与从主库推送的 WAL 段在逻辑上可能相同，但校验和不同。建议禁用多源归档以避免冲突。

注意：

禁用此选项时，务必确保只有一个归档进程通过 archive-push 命令向仓库写入数据。

YAML
default: y
example: --no-archive-mode-check

归档超时选项（--archive-timeout）

归档超时时间。

设置等待每个 WAL 段到达 pgBackRest 归档仓库的最长时间（秒）。check 和 backup 命令等待备份一致性所需的 WAL 段完成归档时，此超时时间生效。

YAML
default: 1m
allowed: [100ms, 1d]
example: --archive-timeout=30

从备库备份选项（--backup-standby）

从备库集群执行备份。

从备库备份可降低主库负载。使用此选项时，主库和备库主机都必须已完成配置。

支持以下模式：

  • y — 必须从备库执行备份。
  • prefer — 优先从备库备份，备库不可用时转为从主库备份。
  • n — 仅从主库备份。
YAML
default: n
example: --backup-standby=y

页面校验和选项（--checksum-page）

验证数据页面校验和。

指示 pgBackRest 在备份集群时验证所有数据页面的校验和。当集群启用了数据页面校验和时，此选项自动开启。

校验和验证失败不会中止备份，而是在日志中（默认也在控制台）输出警告，并将无效页面列表记录到备份的清单文件（manifest）中。

YAML
example: --no-checksum-page

路径/文件排除选项（--exclude）

从备份中排除指定的路径或文件。

所有排除规则均相对于 $PGDATA。若排除规则以 / 结尾，则仅排除该目录下的文件，例如 --exclude=junk/ 会排除 $PGDATA/junk 目录中的所有文件，但目录本身会保留。若不以 / 结尾，则精确匹配该文件名或追加 / 后匹配，例如 --exclude=junk 会排除 $PGDATA/junk 目录及其所有文件。

请谨慎使用此功能——极易误排除关键文件，导致备份不一致。务必测试恢复！

所有被排除的文件都会以 info 级别写入日志，并注明排除规则。请仔细审查被排除的文件列表，确认没有意外排除重要内容。

注意： delta 恢复不遵循排除规则。备份时被排除的文件/目录，在 delta 恢复时会被 删除。

不应使用此选项排除 PostgreSQL 日志。可通过 PostgreSQL 的 log_directory 参数将日志目录移到 PGDATA 之外，这样还能在恢复后保留日志。

可在命令行或配置文件中指定多个排除规则。

YAML
example: --exclude=junk/

自动过期选项（--expire-auto）

在成功备份后自动执行 expire 命令。

此设置默认启用。禁用时请谨慎，因为这将导致所有备份和归档被无限期保留，可能耗尽仓库空间。禁用后需定期手动执行 expire 命令以防止此情况发生。

成功备份后自动执行 expire 时，会使用 backup 命令的配置，因此仅设置在 expire 命令配置节（例如 [global:expire]）中的选项不会生效。若要应用 expire 专用配置，请禁用此选项并单独运行 expire 命令。

YAML
default: y
example: --expire-auto

强制选项（--force）

强制执行离线备份。

与 --no-start-stop 配合使用时，即使 pgBackRest 判断 PostgreSQL 正在运行，也会强制执行备份。此选项风险极高，极可能产生损坏的备份，请极度谨慎使用。

某些特殊场景下，此类条件下的备份可能仍有价值。例如，服务器崩溃后数据库集群卷只能以只读方式挂载时，即使存在 postmaster.pid 文件，也值得做一次备份。此时更好的做法是回退到上一个备份并重放 WAL，但如果某个未完成归档的 WAL 段中包含非常重要的事务，强制备份也是一种选择。

YAML
default: n
example: --force

清单保存阈值选项（--manifest-save-threshold）

备份过程中清单文件（manifest）的保存阈值。

定义备份期间保存清单文件的频率。保存清单文件非常重要，因为它存储了校验和并使续传功能高效工作。实际使用的阈值取备份大小的 1% 与 manifest-save-threshold 中的较大值。

YAML
default: 1GiB
allowed: [1B, 1TiB]
example: --manifest-save-threshold=8GiB

在线选项（--online）

执行在线备份。

指定 --no-online 会阻止 pgBackRest 在数据库集群上执行备份启动/停止函数。要使此选项生效，PostgreSQL 必须已关闭，否则 pgBackRest 会报错。

此选项的用途是支持离线备份。pg_xlog/pg_wal 目录会原样复制，且 archive-check 会为该次备份自动禁用。

YAML
default: y
example: --no-online

续传选项（--resume）

允许续传失败的备份。

定义是否启用续传功能。续传功能可大幅减少同类型备份在上次失败后重新运行所需的时间。在不需要此功能的环境中，可以考虑禁用以降低复杂性。

YAML
default: y
example: --no-resume

快速启动选项（--start-fast）

强制执行检查点以快速启动备份。

通过向备份启动函数的 fast 参数传入 y 来强制执行检查点，使备份立即开始。否则备份将等到下一个常规检查点后才开始。

YAML
default: n
example: --start-fast

类型选项（--type）

备份类型。

支持以下备份类型：

  • full — 全量备份（full backup），复制所有数据库集群文件，不依赖之前的任何备份。
  • incr — 增量备份（incremental backup），基于最近一次成功的备份。
  • diff — 差异备份（differential backup），类似增量备份，但始终基于最近一次全量备份。
YAML
default: incr
example: --type=full

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于具体选项，每个操作可能会占用额外内存，例如 gz 压缩可能额外使用 256KiB 内存。

允许值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

pgBackRest 命令选项（--cmd）

pgBackRest 命令路径。

pgBackRest 有时需要生成命令字符串，例如 restore 命令生成 restore_command 配置时。若未提供 cmd 选项，则使用当前运行 pgBackRest 进程的命令路径。

注意：

包装 pgBackRest 命令可能导致不可预期的行为，不建议这样做。

YAML
default: [path of executed pgbackrest binary]
example: --cmd=/var/lib/pgsql/bin/pgbackrest_wrapper.sh

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

当需要使用特定 SSH 客户端，或 ssh 命令不在 $PATH 中时，可通过此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

压缩选项（--compress）

启用文件压缩。

备份文件与命令行压缩工具兼容。

此选项现已弃用，请改用 compress-type 选项。

YAML
default: y
example: --no-compress

压缩级别选项（--compress-level）

文件压缩级别。

当 compress-type 不等于 none 或使用已弃用的 compress=y 时，指定文件压缩级别。

YAML
default (depending on compress-type):
   bz2 - 9
   gz - 6
   lz4 - 1
   zst - 3

allow range (depending on compress-type):
   bz2 - [1, 9]
   gz - [-1, 9]
   lz4 - [-5, 12]
   zst - [-7, 22]

example: --compress-level=9

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，指定网络压缩级别，用于减少网络流量。当 compress-type 不等于 none 时，此选项会被忽略，转而使用 compress-level，以避免文件被压缩两次。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

压缩类型选项（--compress-type）

文件压缩类型。

支持以下压缩类型：

  • none — 不压缩
  • bz2 — bzip2 压缩格式
  • gz — gzip 压缩格式
  • lz4 — lz4 压缩格式（并非所有平台都支持）
  • zst — Zstandard 压缩格式（并非所有平台都支持）
YAML
default: gz
example: --compress-type=none

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项指定非默认位置的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

指定路径下扩展名为 .conf 的配置文件将与主配置文件拼接，合并为一个完整的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

用于覆盖 --config 和 --config-include-path 选项的默认基础路径，前提是这两个选项未在命令行中显式指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

数据库超时选项（--db-timeout）

数据库查询超时时间。

设置对数据库执行查询的超时时间（秒）。这包括备份的启动/停止函数，这些函数各自可能耗时较长。因此，除非可以确定这些函数会很快返回（例如设置了 start-fast=y 且备份期间集群不会产生大量 WAL 段），否则应将此超时时间设置得较大。

注意： db-timeout 的值必须小于 protocol-timeout 的值。

YAML
default: 30m
allowed: [100ms, 7d]
example: --db-timeout=600

Delta 选项（--delta）

使用校验和进行恢复或备份。

恢复时，默认情况下 PostgreSQL 数据目录和表空间目录应已存在但为空。此选项启用基于校验和的 delta 恢复。

备份时，此选项使用校验和而非时间戳来判断哪些文件需要复制。

YAML
default: n
example: --delta

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读写操作的超时时间（秒）。

注意，整个读写操作不必在此超时时间内完成，但必须有 一定 进展，哪怕只是传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 使用锁文件防止并发执行相互冲突的操作。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器分配给该进程的优先级（即 niceness 值）。正值降低优先级，负值提升优先级。大多数情况下，进程没有权限提升自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

最大进程数选项（--process-max）

压缩/传输使用的最大进程数。

每个进程负责压缩和传输，进程数越多命令运行越快，但不要将 process-max 设置得过高，以免影响数据库性能。

YAML
default: 1
allowed: [1, 999]
example: --process-max=4

协议超时选项（--protocol-timeout）

协议超时时间。

设置本地或远程进程在协议层等待新消息的最长时间（秒），以防止进程无限期地等待。

注意： protocol-timeout 的值必须大于 db-timeout 的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用保活机制。

在 socket 连接上启用保活消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）。

一个 stanza 包含某个 PostgreSQL 数据库集群的完整配置，定义了集群的位置、备份方式、归档选项等。大多数数据库主机只有一个 PostgreSQL 集群，因此只有一个 stanza；而备份服务器通常为每个需要备份的数据库集群单独配置一个 stanza。

命名 stanza 时，常见做法是以主集群名称命名，但更好的方式是以集群中承载的业务来命名。由于 stanza 名称同时适用于主库和所有副本，选择能反映集群实际功能的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

保活计数。

指定连接被判定为断开之前，允许丢失的 TCP 保活消息数量。

此选项仅在系统支持 TCP_KEEPCNT socket 选项时可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

保活空闲时间。

指定操作系统在多少秒无网络活动后，应发送 TCP 保活消息。

此选项仅在系统支持 TCP_KEEPIDLE socket 选项时可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

保活重传间隔时间。

指定未收到确认的 TCP 保活消息多少秒后进行重传。

此选项仅在系统支持 TCP_KEEPINTVL socket 选项时可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许的 TLSv1.2 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均已加密。默认情况下，到对象存储（如 S3）的连接也经过加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整可接受的加密套件。示例值是合理的选择，除非有特定安全需求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许的 TLSv1.3 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均已加密。默认情况下，到对象存储（如 S3）的连接也经过加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整可接受的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off — 不记录任何日志（不推荐）
  • error — 仅记录错误
  • warn — 记录警告和错误
  • info — 记录信息、警告和错误
  • detail — 记录详细信息、信息、警告和错误
  • debug — 记录调试信息、详细信息、信息、警告和错误
  • trace — 记录跟踪信息（极详细的调试输出）、调试信息、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off — 不记录任何日志（不推荐）
  • error — 仅记录错误
  • warn — 记录警告和错误
  • info — 记录信息、警告和错误
  • detail — 记录详细信息、信息、警告和错误
  • debug — 记录调试信息、详细信息、信息、警告和错误
  • trace — 记录跟踪信息（极详细的调试输出）、调试信息、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别的内容输出到 stderr 而非 stdout（stdout 由 log-level-console 控制）。输出到 stderr 的内容不含时间戳和进程信息。

支持以下日志级别：

  • off — 不记录任何日志（不推荐）
  • error — 仅记录错误
  • warn — 记录警告和错误
  • info — 记录信息、警告和错误
  • detail — 记录详细信息、信息、警告和错误
  • debug — 记录调试信息、详细信息、信息、警告和错误
  • trace — 记录跟踪信息（极详细的调试输出）、调试信息、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件存储在此路径下。注意，若 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

在子进程中启用日志记录。

对该进程创建的所有子进程启用文件日志，日志级别使用 log-level-file 指定的级别。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中启用时间戳。此选项在某些特殊场景（如生成文档）中会被禁用。

YAML
default: y
example: --no-log-timestamp

维护者选项

页面头检查选项（--page-header-check）

检查 PostgreSQL 页面头。

此选项默认启用，会添加页面头检查。

除非必要（例如页面已加密），否则不建议禁用此选项。

YAML
default: y
example: --no-page-header-check

强制指定 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用指定的 PostgreSQL 版本，而非通过读取 pg_control 或 WAL 头自动检测的版本。此选项主要适用于 PostgreSQL 的分支版本或开发版本，因为这些版本的版本号可能与发行版本不同。PostgreSQL 通过 server_version_num 报告的版本号必须与强制指定的版本号一致。

警告：

使用此选项时请谨慎，因为 pg_control 和 WAL 头仍会按指定版本的预期格式读取，即官方开源 PostgreSQL 版本的格式。如果分支版本或开发版本修改了 pgBackRest 所依赖字段的格式，将导致不可预期的行为。通常，只有当分支版本将所有自定义结构成员添加在标准 PostgreSQL 成员 之后 时，此选项才能按预期工作。

YAML
example: --pg-version-force=15

仓库选项

指定仓库选项（--repo）

指定操作仓库。

指定命令操作的目标仓库。

例如，可用此选项从特定仓库执行恢复，而不是由 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在容器根目录，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 Azure 生成的内容也能存放在该容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared — 共享密钥
  • sas — 共享访问签名
  • auto — 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host — 连接到 account.endpoint 主机。
  • path — 连接到 endpoint 主机并在 URI 前添加账户名。
YAML
default: host
example: --repo1-azure-uri-style=path

块级增量备份选项（--repo-block）

启用块级增量备份（block incremental backup）。

块级备份将文件拆分为可独立备份的块，实现更细粒度的备份。这不仅节省仓库空间，还能提升 delta 恢复性能，因为可以直接获取单个块，而无需从仓库读取整个文件。

注意： 必须先启用 repo-bundle 选项，才能启用 repo-block。

文件的块大小根据文件大小和使用时间确定。通常，越旧/越大的文件使用越大的块。若文件足够旧，则不会使用块级增量备份。

块级备份在对所有备份类型（包括全量备份）启用时最为高效。这会使全量备份稍大，但后续的差异备份和增量备份可以利用全量备份生成的块映射来节省空间。

YAML
default: n
example: --repo1-block

仓库包（bundle）选项（--repo-bundle）

在仓库中将文件打包（bundle）存储。

将小文件合并打包存储，以减少写入仓库的文件总数。写入文件数量更少通常效率更高，尤其是在 S3 等对象存储上。此外，零长度文件不会存储（清单文件除外），可节省时间和空间。

YAML
default: n
example: --repo1-bundle

仓库包大小限制选项（--repo-bundle-limit）

文件包的大小限制。

指定纳入包中的文件大小上限，超过此大小的文件将单独存储。

打包的文件在备份续传时无法复用，因此此选项控制了可续传的文件范围——值越大，可续传的文件越少。

YAML
default: 2MiB
allowed: [8KiB, 1PiB]
example: --repo1-bundle-limit=10MiB

仓库包目标大小选项（--repo-bundle-size）

文件包的目标大小。

定义单个包所容纳文件的目标总大小。未压缩的包大小最大可能达到 repo-bundle-size + repo-bundle-limit，因此不要将此选项设置为文件系统允许的最大值。

通常不建议将此选项设置得过高，因为重试时需要重新执行整个包的操作。

YAML
default: 20MiB
allowed: [1MiB, 1PiB]
example: --repo1-bundle-size=10MiB

仓库加密类型选项（--repo-cipher-type）

用于加密仓库的加密算法。

支持以下加密类型：

  • none — 仓库不加密
  • aes-256-cbc — 使用 256 位密钥的高级加密标准

注意，即使仓库类型（如 S3）本身支持加密，加密也始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 GCS 生成的内容也能存放在该存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点，可修改为使用本地 GCS 服务器或备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto — 使用实例服务账号自动授权。
  • service — 使用本地存储的服务账号密钥文件。
  • token — 用于本地测试，例如 fakegcs。

当 repo-gcs-key-type=service 时，认证令牌续期时会重新加载凭证。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库硬链接选项（--repo-hardlink）

在仓库中对备份文件创建硬链接。

为差异备份和增量备份中的文件创建指向其对应全量备份的硬链接，使每个备份在文件系统层面看起来都像一个完整的全量备份。但请注意，修改硬链接文件会影响同一备份集中的所有备份。

YAML
default: n
example: --repo1-hardlink

已弃用名称：hardlink

仓库主机选项（--repo-host）

远程操作时的仓库主机。

若备份和归档使用本地挂载的文件系统，则无需配置此选项。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机的证书颁发机构文件。

连接仓库主机时使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机的证书颁发机构路径。

连接仓库主机时使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机的证书文件。

发送给仓库主机以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令路径。

仅当本地主机与仓库主机上的 pgBackRest 命令路径不同时才需要配置。若未定义，仓库主机命令将与本地命令相同。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的位置。仅当仓库主机的配置文件位置与本地配置文件位置不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机的配置包含路径与本地配置包含路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机的配置路径与本地配置路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机的密钥文件。

证明客户端证书由其所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

设置 repo-host 时使用的仓库主机端口。

使用此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，实际使用的端口由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh — 安全外壳协议（Secure Shell）。
  • tls — pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

设置 repo-host 时使用的仓库主机用户。

定义在仓库主机上执行操作所使用的用户。建议不使用 postgres 用户，而改用专用用户（如 pgbackrest）。若 PostgreSQL 也运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其拥有仓库的读权限，同时避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的位置。

预先估算所需空间可能比较困难。建议先执行若干次备份，记录不同类型备份（全量/增量/差异）的大小，并测量每天产生的 WAL 量，以此对所需空间有一个大致判断。随着数据库的演进，需求也会随时间变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

归档保留选项（--repo-retention-archive）

连续 WAL 保留的备份数量。

注意： 无论此选项如何配置，确保备份一致性所需的 WAL 段始终会保留到备份过期为止。

若未设置此值且 repo-retention-full-type 为 count（默认值），则归档过期默认值为 repo-retention-full（或 repo-retention-diff）对应 repo-retention-archive-type（设置为 full 或 diff）的值，确保 WAL 仅在对应备份过期后才会过期。若 repo-retention-full-type 为 time，则此值默认为移除早于满足 repo-retention-full 设置后保留的最旧全量备份的归档。

若 repo-retention-archive-type 设置为 incr，则必须设置此选项。在磁盘空间极为紧张时，可结合 repo-retention-archive-type 使用此选项激进地清理 WAL 段。但这样做会导致无法从已清理 WAL 的备份执行 PITR，因此 不推荐。

YAML
allowed: [1, 9999999]
example: --repo1-retention-archive=2

已弃用名称：retention-archive

归档保留类型选项（--repo-retention-archive-type）

WAL 保留的备份类型。

若设置为 full，pgBackRest 将按 repo-retention-archive 定义的全量备份数量保留归档日志。若设置为 diff（差异备份），则按 repo-retention-archive 定义的全量备份和差异备份数量保留归档日志，如果最后一次备份是全量备份，它将被视为差异备份计入 repo-retention-archive。若设置为 incr（增量备份），则按 repo-retention-archive 定义的全量、差异和增量备份数量保留归档日志。建议不要修改此选项的默认值，即仅在过期全量备份的同时过期对应的 WAL。

YAML
default: full
example: --repo1-retention-archive-type=diff

已弃用名称：retention-archive-type

差异备份保留选项（--repo-retention-diff）

保留的差异备份数量。

差异备份过期时，与之关联的所有增量备份也会一同过期。若未定义，所有差异备份将保留到其所依赖的全量备份过期为止。

注意，计算过期时，全量备份会被纳入差异备份数量的统计，这在大多数情况下会略微减少需要保留的差异备份数量。

YAML
allowed: [1, 9999999]
example: --repo1-retention-diff=3

已弃用名称：retention-diff

全量备份保留选项（--repo-retention-full）

全量备份的保留数量/时间。

全量备份过期时，与之关联的所有差异备份和增量备份也会一同过期。若未定义此选项，将会发出警告。如果希望无限期保留，可将此选项设置为最大值。

YAML
allowed: [1, 9999999]
example: --repo1-retention-full=2

已弃用名称：retention-full

全量备份保留类型选项（--repo-retention-full-type）

全量备份的保留类型。

决定 repo-retention-full 表示时间周期（天数）还是保留的全量备份数量。

若设置为 time，则超过 repo-retention-full 天的全量备份将被删除，前提是至少存在一个不早于 repo-retention-full 天的备份。例如，若 repo-retention-full 为 30（天），且有 2 个全量备份，分别为 25 天前和 35 天前创建，则两个备份均不会过期——因为删除 35 天前的备份将只剩 25 天前的备份，不满足"至少保留一个 30 天以内的备份"的策略要求。早于保留的最旧全量备份的归档 WAL 将自动过期，除非显式设置了 repo-retention-archive-type 和 repo-retention-archive。

若设置为 count，则超过 repo-retention-full 数量的全量备份将过期。例如，若 repo-retention-full 为 4 且第五个全量备份完成，则最旧的全量备份将过期以保持数量为 4。

注意，备份必须成功完成后才会被纳入保留策略的考量。例如，若 repo-retention-full-type 为 count 且 repo-retention-full 为 2，则必须有 3 个完整的全量备份，最旧的才会过期。

YAML
default: count
example: --repo1-retention-full-type=time

备份历史保留选项（--repo-retention-history）

备份历史清单文件的保留天数。

备份完成时，清单文件（manifest）的副本会存储在 backup.history 路径下。默认情况下这些文件永不过期，因为它们对数据挖掘（如统计备份和 WAL 增长趋势）很有价值。

通过设置 repo-retention-history，可以定义保留备份历史清单文件的天数。未过期的备份始终保留在备份历史中。设置 repo-retention-history=0 可仅为未过期的备份保留备份历史。

全量备份历史清单文件过期时，与之关联的所有差异备份和增量备份历史清单文件也会一同过期。

YAML
allowed: [0, 9999999]
example: --repo1-retention-history=365

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 AWS 生成的内容也能存放在该存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义或测试配置，可使用 repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 等选项。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭证的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host — 连接到 bucket.endpoint 主机。
  • path — 连接到 endpoint 主机并在 URI 前添加存储桶名称。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

存放仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

SFTP 仓库主机指纹的生成方式应与 repo-sftp-host-key-hash-type 匹配。通过以下命令生成指纹：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下 SFTP 主机密钥检查类型：

  • strict — pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts 文件，并拒绝连接到主机密钥已更改或未在已知主机文件中找到的主机。此选项要求用户手动添加所有新主机。
  • accept-new — pgBackRest 会自动将新主机密钥添加到用户的已知主机文件，但不允许连接到主机密钥已更改的主机。
  • fingerprint — pgBackRest 将根据 repo-sftp-host-fingerprint 选项指定的指纹验证主机密钥。
  • none — 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明在 SSH 启动时用于计算远程系统主机密钥摘要的哈希类型。较新版本的 libssh2 除 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

SFTP 仓库主机的端口号。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

存储仓库的主机上的用户名。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

身份验证时用于查找 SFTP 主机匹配的已知主机文件。若未指定，pgBackRest 默认依次搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将在这些文件中搜索匹配项。文件路径必须为完整路径或以波浪号（~）开头的路径。可多次传入 repo-sftp-known-host 选项以指定多个已知主机文件。使用已知主机文件检查时，不能指定 repo-sftp-host-fingerprint。另请参见 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于身份验证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于身份验证的 SFTP 公钥文件。若使用 OpenSSL 编译则为可选，若使用其他库编译则为必需。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

为存储（如 S3、Azure）证书使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

为存储（如 S3、Azure）证书使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机，通常用于测试。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储（如 S3、Azure）端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库为对象存储（如 S3）时，指定要添加到对象上的标签。此选项可重复使用以添加多个标签。

pgBackRest 不提供修改这些标签的功能，因此请在运行 stanza-create 之前正确设置，以确保整个仓库的标签一致。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

当文件过大无法完整存入内存时，S3 等对象存储支持分块上传。即使文件可以存入内存，限制上传所用的内存量也更为高效。

分块大小越大，通常性能越好，因为可以减少上传请求数量，允许在单次请求中上传更多数据。缺点是内存占用更高；process-max 值较大时，每个进程都需要分配分块缓冲区，整体内存消耗更多。

请注意，有效的分块大小因存储类型和平台而异。例如，AWS S3 的最小分块大小为 5MiB。不同存储类型对分块大小的术语也不同：AWS S3 称之为"part size"（分片大小），GCS 称之为"chunk size"（分块大小），Azure 称之为"block size"（块大小）。

若文件大于 1GiB（PostgreSQL 默认最大创建文件大小），则分块大小会逐步增大至允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

提供启用/禁用存储（如 S3、Azure）服务器 TLS 证书验证的能力。仅在测试或使用自签名证书等特殊场景下才应禁用验证。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库符号链接选项（--repo-symlink）

在仓库中创建符号链接。

启用 latest 和表空间符号链接的创建。这些符号链接在使用快照对仓库进行原地恢复时最为有用，但这是较少见的使用场景。

尽管此功能对大多数用户可能没有实际用处，但为了兼容性默认保持启用。对于不支持符号链接的 POSIX 类存储，禁用符号链接可能是有益的。

YAML
default: y
example: --no-repo1-symlink

仓库类型选项（--repo-type）

仓库所使用的存储类型。

支持以下仓库类型：

  • azure — Azure Blob 存储服务
  • cifs — 类似 posix，但禁用链接和目录 fsync
  • gcs — Google Cloud 存储
  • posix — 符合 POSIX 标准的文件系统
  • s3 — AWS 简单存储服务
  • sftp — 安全文件传输协议

当 NFS 挂载作为 posix 类型仓库使用时，适用 PostgreSQL 文档中描述的相同规则： 创建数据库集群 - 文件系统。

YAML
default: posix
example: --repo1-type=cifs

Stanza 选项

PostgreSQL 数据库选项（--pg-database）

PostgreSQL 数据库名。

连接 PostgreSQL 时使用的数据库名称。默认值通常即可，但某些安装可能不包含此数据库。

注意，出于历史兼容原因，PGDATABASE 环境变量的设置会被忽略。

YAML
default: postgres
example: --pg1-database=backupdb

PostgreSQL 主机选项（--pg-host）

远程操作时的 PostgreSQL 主机。

用于 PostgreSQL 主机与仓库主机不在同一台机器上的备份场景。

YAML
example: --pg1-host=db.domain.com

已弃用名称：db-host

PostgreSQL 主机证书颁发机构文件选项（--pg-host-ca-file）

PostgreSQL 主机的证书颁发机构文件。

连接 PostgreSQL 主机时使用非系统默认的 CA 文件。

YAML
example: --pg1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

PostgreSQL 主机证书颁发机构路径选项（--pg-host-ca-path）

PostgreSQL 主机的证书颁发机构路径。

连接 PostgreSQL 主机时使用非系统默认的 CA 路径。

YAML
example: --pg1-host-ca-path=/etc/pki/tls/certs

PostgreSQL 主机证书文件选项（--pg-host-cert-file）

PostgreSQL 主机的证书文件。

发送给 PostgreSQL 主机以证明客户端身份。

YAML
example: --pg1-host-cert-file=/path/to/client.crt

PostgreSQL 主机命令选项（--pg-host-cmd）

PostgreSQL 主机上的 pgBackRest 命令路径。

仅当本地主机与 PostgreSQL 主机上的 pgBackRest 命令路径不同时才需要配置。若未定义，PostgreSQL 主机命令将与本地命令相同。

YAML
default: [path of executed pgbackrest binary]
example: --pg1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：db-cmd

PostgreSQL 主机配置文件选项（--pg-host-config）

pgBackRest 数据库主机配置文件。

设置 PostgreSQL 主机上配置文件的位置。仅当 PostgreSQL 主机的配置文件位置与本地配置文件位置不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --pg1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：db-config

PostgreSQL 主机配置包含路径选项（--pg-host-config-include-path）

pgBackRest 数据库主机配置包含路径。

设置 PostgreSQL 主机上配置包含路径的位置。仅当 PostgreSQL 主机的配置包含路径与本地配置包含路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --pg1-host-config-include-path=/conf/pgbackrest/conf.d

PostgreSQL 主机配置路径选项（--pg-host-config-path）

pgBackRest 数据库主机配置路径。

设置 PostgreSQL 主机上配置路径的位置。仅当 PostgreSQL 主机的配置路径与本地配置路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --pg1-host-config-path=/conf/pgbackrest

PostgreSQL 主机密钥文件选项（--pg-host-key-file）

PostgreSQL 主机的密钥文件。

证明客户端证书由其所有者发送。

YAML
example: --pg1-host-key-file=/path/to/client.key

PostgreSQL 主机端口选项（--pg-host-port）

设置 pg-host 时使用的 PostgreSQL 主机端口。

使用此选项为 PostgreSQL 主机协议指定非默认端口。

注意： 当 pg-host-type=ssh 时，pg-host-port 没有默认值，实际使用的端口由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on pg-host-type):
   tls - 8432

allowed: [0, 65535]
example: --pg1-host-port=25

已弃用名称：db-ssh-port

PostgreSQL 主机协议类型选项（--pg-host-type）

PostgreSQL 主机协议类型。

支持以下协议类型：

  • ssh — 安全外壳协议（Secure Shell）。
  • tls — pgBackRest TLS 服务器。
YAML
default: ssh
example: --pg1-host-type=tls

PostgreSQL 主机用户选项（--pg-host-user）

设置 pg-host 时使用的 PostgreSQL 主机登录用户。

该用户同时拥有远程 pgBackRest 进程，并负责发起与 PostgreSQL 的连接。为使其正常工作，此用户应为 PostgreSQL 数据库集群的所有者，通常为默认值 postgres。

YAML
default: postgres
example: --pg1-host-user=db_owner

已弃用名称：db-user

PostgreSQL 路径选项（--pg-path）

PostgreSQL 数据目录。

应与 PostgreSQL 报告的 data_directory 一致。尽管可以从多处读取此值，但建议在配置文件中显式设置，以防在恢复或离线备份场景中这些来源不可用。

每次在线备份时，pg-path 选项都会与 PostgreSQL 报告的值进行核对，因此应始终保持最新。

YAML
example: --pg1-path=/data/db

已弃用名称：db-path

PostgreSQL 端口选项（--pg-port）

PostgreSQL 端口。

PostgreSQL 运行的端口。大多数 PostgreSQL 集群使用默认端口，通常无需指定此选项。

YAML
default: 5432
allowed: [0, 65535]
example: --pg1-port=6543

已弃用名称：db-port

PostgreSQL Socket 路径选项（--pg-socket-path）

PostgreSQL Unix socket 路径。

启动 PostgreSQL 时指定的 Unix socket 目录。pgBackRest 会自动查找操作系统的标准位置，通常无需配置此选项，除非通过 postgresql.conf 中的 unix_socket_directories 参数显式修改了 socket 目录。

YAML
example: --pg1-socket-path=/var/run/postgresql

已弃用名称：db-socket-path

PostgreSQL 数据库用户选项（--pg-user）

PostgreSQL 数据库用户。

连接 PostgreSQL 时使用的数据库用户名。若未指定，pgBackRest 将使用本地操作系统用户或 PGUSER 环境变量。

YAML
example: --pg1-user=backupuser

4.5 - 检查命令（check）

pgBackRest check 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: check

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

请注意，该命令会调用 pg_create_restore_point('pgBackRest Archive Check') 和 pg_switch_xlog()/pg_switch_wal() 来强制 PostgreSQL 归档一个 WAL 段。

命令选项

归档检查选项（--archive-check）

在备份完成前检查 WAL 段是否已进入归档。

此选项会验证使备份达到一致状态所需的全部 WAL 段是否均已存在于归档中。建议保持默认值，除非你通过其他方式管理归档。

若启用了 archive-copy，则必须同时启用此选项。

YAML
default: y
example: --no-archive-check

归档模式检查选项（--archive-mode-check）

检查 PostgreSQL 的 archive_mode 设置。

此选项默认启用，作用是禁止 PostgreSQL 使用 archive_mode=always。

从备库推送的 WAL 段与从主库推送的 WAL 段在逻辑上可能相同，但校验和不同。禁止多源归档可以避免潜在冲突。

注意：

若禁用此选项，必须确保只有一个归档进程通过 archive-push 命令向仓库写入数据。

YAML
default: y
example: --no-archive-mode-check

归档超时选项（--archive-timeout）

归档超时时间。

设置等待每个 WAL 段进入 pgBackRest 归档仓库的最长时间（秒）。此超时适用于 check 和 backup 命令等待备份一致性所需 WAL 段完成归档的场景。

YAML
default: 1m
allowed: [100ms, 1d]
example: --archive-timeout=30

从备库备份选项（--backup-standby）

从备库集群进行备份。

从备库备份可降低主库的负载。此选项要求同时配置主库和备库主机。

支持以下模式：

  • y - 必须使用备库进行备份。
  • prefer - 优先从备库备份，备库不可用时自动切换到主库。
  • n - 仅从主库备份。
YAML
default: n
example: --backup-standby=y

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于具体选项，每个操作可能会额外占用内存，例如 gz 压缩可能额外使用 256KiB 内存。

允许的值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

当需要使用特定 SSH 客户端，或 ssh 命令不在 $PATH 中时，使用此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，此选项设置网络传输的压缩级别。压缩可减少网络流量。当 compress-type 不为 none 时，compress-level-network 将被忽略，转而使用 compress-level，以避免对文件进行二次压缩。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项指定非默认路径的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

指定路径下扩展名为 .conf 的配置文件将与主配置文件合并，构成完整的配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置用于覆盖 --config 和 --config-include-path 的默认基础路径，前提是这两个选项未在命令行中显式指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

数据库超时选项（--db-timeout）

数据库查询超时时间。

设置对数据库执行查询的超时时间（秒）。涉及备份启动/停止函数的查询各自可能耗时较长，因此除非你确定这些函数会快速返回（例如已设置 start-fast=y，且数据库集群在备份期间不会产生大量 WAL 段），否则应将此超时设为较大值。

注意： db-timeout 选项的值必须小于 protocol-timeout 选项的值。

YAML
default: 30m
allowed: [100ms, 7d]
example: --db-timeout=600

I/O 超时选项（--io-timeout）

I/O 超时时间。

用于连接和读写操作的超时时间（秒）。

请注意，整个读写操作无需在此时间内完成，但 必须 持续有所进展，哪怕每次只传输一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器赋予该进程的优先级（即 nice 值）。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时时间。

设置本地或远程进程在协议层等待新消息的超时时间（秒），防止进程无限期阻塞。

注意： protocol-timeout 选项的值必须大于 db-timeout 选项的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用保活机制。

在 socket 连接上启用保活消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza。

stanza 是 PostgreSQL 数据库集群的配置，定义了集群的位置、备份方式、归档选项等。大多数数据库服务器只有一个 PostgreSQL 集群，因此只有一个 stanza；而备份服务器则需要为每个待备份的数据库集群分别配置一个 stanza。

命名 stanza 时，很容易直接使用主集群的名称，但更好的做法是根据集群承载的数据库功能来命名。由于 stanza 名称同时用于主库和所有副本，建议选择能描述集群实际用途的名称（如 app 或 dw），而非本地集群名称（如 main 或 prod）。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

保活数据包计数。

指定连接被判定为断开前，可丢失的 TCP 保活消息数量。

此选项仅在支持 TCP_KEEPCNT socket 选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

保活空闲时间。

指定无网络活动持续多少秒后，操作系统开始发送 TCP 保活消息。

此选项仅在支持 TCP_KEEPIDLE socket 选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

保活消息重传间隔。

指定未收到确认的 TCP 保活消息在多少秒后重新发送。

此选项仅在支持 TCP_KEEPINTVL socket 选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许的 TLSv1.2 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整可接受的加密套件列表。示例为合理选择，除非有特定安全需求。若未设置（默认），则使用底层 OpenSSL 库的默认配置。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许的 TLSv1.3 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整可接受的加密套件列表。若未设置（默认），则使用底层 OpenSSL 库的默认配置。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别输出到 stderr 而非 stdout（由 log-level-console 控制）。输出到 stderr 的内容不包含时间戳和进程信息。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件存储路径。

指定 pgBackRest 日志文件的存储位置。若 log-level-file=off，则无需配置此路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为当前进程创建的子进程启用文件日志记录，日志级别由 log-level-file 指定。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

启用日志时间戳。

在控制台和文件日志中附加时间戳。生成文档等特殊场景下此选项会被禁用。

YAML
default: y
example: --no-log-timestamp

维护者选项

强制指定 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用此选项指定的 PostgreSQL 版本，而不依赖从 pg_control 或 WAL 头部自动检测的版本。此选项主要用于 PostgreSQL 分支版本或开发版本——在这些版本中，自动检测值可能与正式发行版本不同。PostgreSQL 通过 server_version_num 报告的版本必须与强制指定的版本一致。

警告：

使用此选项须格外谨慎。pg_control 和 WAL 头部仍会按指定版本的预期格式读取，即官方开源 PostgreSQL 的格式。若分支版本或开发版本修改了 pgBackRest 所依赖的字段格式，将导致不可预期的行为。通常只有在分支版本于标准 PostgreSQL 结构成员 之后 追加自定义成员时，此选项才能正常工作。

YAML
example: --pg-version-force=15

仓库选项

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在容器根目录，但通常建议指定前缀（如 /repo），以便日志和其他 Azure 生成的内容也能存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加账户前缀。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

用于加密仓库的加密算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

请注意，即使仓库类型（如 S3）本身支持加密，pgBackRest 的加密也始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定前缀（如 /repo），以便日志和其他 GCS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点。可更新为本地 GCS 服务器或备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号授权。
  • service - 使用本地存储的服务账号密钥。
  • token - 用于本地测试，如 fakegcs。

当 repo-gcs-key-type=service 时，认证令牌续期时会重新加载凭据。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

若备份和归档使用本地挂载的文件系统，则无需此设置。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时，使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时，使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令。

仅当 pgBackRest 在本地主机与仓库主机上的路径不同时才需要此选项。若未定义，仓库主机命令将与本地命令相同。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的位置。仅当仓库主机上的配置文件路径与本地不同时才需要此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地不同时才需要此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地不同时才需要此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

证明客户端证书由其所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

repo-host 已设置时的仓库主机端口。

使用此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 无默认值，端口由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（Secure Shell）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

repo-host 已设置时的仓库主机用户。

定义在仓库主机上执行操作所用的用户。建议不要使用 postgres 用户，而是使用专用用户（如 pgbackrest）。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其对仓库拥有读取权限，但无法意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的地方。

预先估算所需空间可能比较困难。建议先执行若干次备份，记录不同备份类型（全量/增量/差异）的大小，并衡量每天产生的 WAL 量，从而得出大致的空间需求。随着数据库持续增长，需求也会相应变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定前缀（如 /repo），以便日志和其他 AWS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义或测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 选项可能有用。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭据的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加存储桶前缀。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

存储仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

主机指纹的生成方式应与 repo-sftp-host-key-hash-type 一致，通过 awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b 命令生成。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下 SFTP 主机密钥检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts 文件，并拒绝连接到主机密钥已更改或不在已知主机文件中的主机。此模式强制用户手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到用户的已知主机文件，但不允许连接到主机密钥已更改的主机。
  • fingerprint - pgBackRest 将主机密钥与 repo-sftp-host-fingerprint 选项指定的指纹进行比对。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明在 SSH 启动时用于计算远程系统主机密钥摘要的哈希类型。较新版本的 libssh2 除 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

SFTP 仓库主机的端口号。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

用于存储仓库的主机上的用户。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

认证过程中用于搜索 SFTP 主机匹配的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将只在这些文件中搜索匹配项。文件路径必须为完整路径或以波浪号开头的路径。此选项可多次传入以指定多个已知主机文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参阅 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件。使用 OpenSSL 编译时为可选；使用其他库编译时为必需。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接存储（如 S3、Azure）时，使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接存储（如 S3、Azure）时，使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机，通常用于测试。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储（如 S3、Azure）端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

指定在仓库为对象存储（如 S3）时添加到对象上的标签。可多次使用此选项以添加多个标签。

pgBackRest 不提供修改这些标签的功能，因此请在运行 stanza-create 之前确保标签设置正确，以保证整个仓库标签的一致性。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

S3 等对象存储支持在文件过大无法全部载入内存时分块上传。即使文件能全部载入内存，限制上传所用内存量也更为高效。

较大的块大小通常能提升性能，因为它可以减少上传请求数量，使更多文件在单次请求中完成上传而无需分块处理。其代价是内存占用更高，且由于块缓冲区需按进程分配，process-max 值越大，整体内存消耗越多。

请注意，有效的块大小因存储类型和平台而异。例如，AWS S3 的最小块大小为 5MiB。各存储类型对块大小的叫法不同，查找最小/最大值时请参考：AWS S3 用"part size"，GCS 用"chunk size"，Azure 用"block size"。

若文件大小超过 1GiB（PostgreSQL 默认创建文件的上限），块大小将逐步增大至允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用对存储（如 S3、Azure）服务端 TLS 证书的验证。禁用验证仅应用于测试或使用自签名证书的场景。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud 存储
  • posix - 符合 POSIX 标准的文件系统
  • s3 - AWS 简单存储服务
  • sftp - 安全文件传输协议

将 NFS 挂载用作 posix 仓库时，适用于 pgBackRest 的规则与 PostgreSQL 文档中描述的相同，详见 创建数据库集群 - 文件系统。

YAML
default: posix
example: --repo1-type=cifs

Stanza 选项

PostgreSQL 数据库选项（--pg-database）

PostgreSQL 数据库。

连接 PostgreSQL 时使用的数据库名称。默认值通常是最佳选择，但某些安装可能不包含此数据库。

请注意，出于历史原因，PGDATABASE 环境变量的设置将被忽略。

YAML
default: postgres
example: --pg1-database=backupdb

PostgreSQL 主机选项（--pg-host）

远程操作时的 PostgreSQL 主机。

用于 PostgreSQL 主机与仓库主机分离的备份场景。

YAML
example: --pg1-host=db.domain.com

已弃用名称：db-host

PostgreSQL 主机证书颁发机构文件选项（--pg-host-ca-file）

PostgreSQL 主机证书颁发机构文件。

连接 PostgreSQL 主机时，使用非系统默认的 CA 文件。

YAML
example: --pg1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

PostgreSQL 主机证书颁发机构路径选项（--pg-host-ca-path）

PostgreSQL 主机证书颁发机构路径。

连接 PostgreSQL 主机时，使用非系统默认的 CA 路径。

YAML
example: --pg1-host-ca-path=/etc/pki/tls/certs

PostgreSQL 主机证书文件选项（--pg-host-cert-file）

PostgreSQL 主机证书文件。

发送给 PostgreSQL 主机以证明客户端身份。

YAML
example: --pg1-host-cert-file=/path/to/client.crt

PostgreSQL 主机命令选项（--pg-host-cmd）

PostgreSQL 主机上的 pgBackRest 命令。

仅当 pgBackRest 在本地主机与 PostgreSQL 主机上的路径不同时才需要此选项。若未定义，PostgreSQL 主机命令将与本地命令相同。

YAML
default: [path of executed pgbackrest binary]
example: --pg1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：db-cmd

PostgreSQL 主机配置文件选项（--pg-host-config）

pgBackRest 数据库主机配置文件。

设置 PostgreSQL 主机上配置文件的位置。仅当 PostgreSQL 主机上的配置文件路径与本地不同时才需要此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --pg1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：db-config

PostgreSQL 主机配置包含路径选项（--pg-host-config-include-path）

pgBackRest 数据库主机配置包含路径。

设置 PostgreSQL 主机上配置包含路径的位置。仅当 PostgreSQL 主机上的配置包含路径与本地不同时才需要此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --pg1-host-config-include-path=/conf/pgbackrest/conf.d

PostgreSQL 主机配置路径选项（--pg-host-config-path）

pgBackRest 数据库主机配置路径。

设置 PostgreSQL 主机上配置路径的位置。仅当 PostgreSQL 主机上的配置路径与本地不同时才需要此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --pg1-host-config-path=/conf/pgbackrest

PostgreSQL 主机密钥文件选项（--pg-host-key-file）

PostgreSQL 主机密钥文件。

证明客户端证书由其所有者发送。

YAML
example: --pg1-host-key-file=/path/to/client.key

PostgreSQL 主机端口选项（--pg-host-port）

pg-host 已设置时的 PostgreSQL 主机端口。

使用此选项为 PostgreSQL 主机协议指定非默认端口。

注意： 当 pg-host-type=ssh 时，pg-host-port 无默认值，端口由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on pg-host-type):
   tls - 8432

allowed: [0, 65535]
example: --pg1-host-port=25

已弃用名称：db-ssh-port

PostgreSQL 主机协议类型选项（--pg-host-type）

PostgreSQL 主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（Secure Shell）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --pg1-host-type=tls

PostgreSQL 主机用户选项（--pg-host-user）

pg-host 已设置时的 PostgreSQL 主机登录用户。

此用户还将作为远程 pgBackRest 进程的所有者，并负责发起到 PostgreSQL 的连接。为使其正常工作，该用户应为 PostgreSQL 数据库集群的所有者，通常即默认值 postgres。

YAML
default: postgres
example: --pg1-host-user=db_owner

已弃用名称：db-user

PostgreSQL 路径选项（--pg-path）

PostgreSQL 数据目录。

此路径应与 PostgreSQL 报告的 data_directory 一致。尽管该值可从多处读取，但在恢复或离线备份场景下这些资源可能不可用，因此建议显式设置。

每次在线备份时，pg-path 选项都会与 PostgreSQL 报告的值进行核对，因此应始终保持最新。

YAML
example: --pg1-path=/data/db

已弃用名称：db-path

PostgreSQL 端口选项（--pg-port）

PostgreSQL 端口。

PostgreSQL 运行的端口号。大多数 PostgreSQL 集群使用默认端口，通常无需指定此选项。

YAML
default: 5432
allowed: [0, 65535]
example: --pg1-port=6543

已弃用名称：db-port

PostgreSQL Socket 路径选项（--pg-socket-path）

PostgreSQL Unix socket 路径。

启动 PostgreSQL 时指定的 Unix socket 目录。pgBackRest 会自动查找当前操作系统的标准位置，通常无需指定此选项，除非在 postgresql.conf 中通过 unix_socket_directories 显式修改了 socket 目录。

YAML
example: --pg1-socket-path=/var/run/postgresql

已弃用名称：db-socket-path

PostgreSQL 数据库用户选项（--pg-user）

PostgreSQL 数据库用户。

连接 PostgreSQL 时使用的数据库用户名。若未指定，pgBackRest 将使用本地操作系统用户或 PGUSER。

YAML
example: --pg1-user=backupuser

4.6 - 过期命令（expire）

pgBackRest expire 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: expire

pgBackRest 基于保留策略对全量备份进行轮换，策略可按数量或时间段定义。按数量保留时，过期操作只关注需要保留的备份数量，不考虑备份的创建时间。差异备份按数量进行保留，但当其依赖的全量备份过期时，差异备份也会随之过期。增量备份没有独立的保留策略——它们始终随关联的全量备份或差异备份一同过期。详情及示例请参见 全量备份保留策略 和 差异备份保留策略 章节。

默认情况下，未过期备份对应的已归档 WAL 会被保留。如有需要（不推荐），可通过归档保留选项按仓库单独调整此策略。详情及示例请参见 归档保留策略 章节。

expire 命令在每次备份成功后自动运行，也可由用户手动执行。手动执行时，将按每个已配置仓库的保留策略处理过期备份。若指定了 --repo 选项，则仅对指定仓库执行过期操作。还可通过 --set 选项将过期操作限定到特定备份集；若未指定 --repo，则会搜索所有仓库，对所有匹配该备份集条件的仓库执行过期。需要注意的是，每次运行 expire 命令时都会检查并执行归档保留策略。

命令选项

归档过期截止点选项（--archive-expire-before）

删除指定 WAL 段之前的 WAL 归档。

删除指定段之前、且保留备份不再需要的 WAL 段，即早于要保留的最早备份集的 WAL 段；若仓库中没有备份，则可删除任意更早的 WAL 段。指定段及其后的所有内容都会保留。这与 PostgreSQL 传给 archive_cleanup_command 的 %r 值含义一致。

此选项主要用于不存储备份、仅存放归档的仓库。尚未满足全量备份保留条件、因而无法触发归档过期时，也可用它回收首个备份之前的 WAL 归档空间。

YAML
example: --archive-expire-before=000000010000000000000010

最旧备份选项（--oldest）

过期最旧的可删除备份集。

过期可以删除的最旧全量备份集（即至少保留一个比它更新的全量备份）。这等价于将保留数量临时减一，但由系统自动计算。与该过期全量备份集关联的所有备份（差异备份和增量备份）也会一同过期。

使用此选项时，归档保留策略也会相应调整，以便在同一次运行中删除已过期备份的 WAL。

若配置了基于时间的全量保留策略（--repo-retention-full-type=time），则本次执行中 --oldest 将改用基于数量的过期方式。

警告：

此选项不能与 --set 同时使用。

YAML
default: n
example: --oldest

备份集选项（--set）

指定要过期的备份集。

无论保留规则如何，指定的备份集（即所提供的备份标签及其所有依赖备份）都将被过期，但仓库中至少必须保留一个全量备份。

警告：

请极其谨慎地使用此选项——它将从 pgBackRest 仓库中永久删除指定备份集中的所有备份，以及使该备份保持一致所不需要的所有归档文件。此操作可能导致相关备份无法执行 PITR。若已配置 --repo-retention-full 和/或 --repo-retention-archive，建议在执行临时过期操作时将这些选项设为最大值，以防意外删除归档文件。

YAML
example: --set=20150131-153358F_20150131-153401I

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于具体选项，每个操作可能会额外占用内存，例如 gz 压缩可能额外使用 256KiB 内存。

允许的值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

当需要使用特定 SSH 客户端，或 ssh 命令不在 $PATH 中时，使用此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，此选项设置网络传输的压缩级别。压缩可减少网络流量。当 compress-type 不为 none 时，compress-level-network 将被忽略，转而使用 compress-level，以避免对文件进行二次压缩。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项指定非默认路径的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

指定路径下扩展名为 .conf 的配置文件将与主配置文件合并，构成完整的配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置用于覆盖 --config 和 --config-include-path 的默认基础路径，前提是这两个选项未在命令行中显式指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

试运行选项（--dry-run）

以试运行模式执行命令。

--dry-run 仅可在命令行使用，适用于需要预判命令将进行哪些修改而不实际执行的场景。

YAML
default: n
example: --dry-run

I/O 超时选项（--io-timeout）

I/O 超时时间。

用于连接和读写操作的超时时间（秒）。

请注意，整个读写操作无需在此时间内完成，但 必须 持续有所进展，哪怕每次只传输一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件存储路径。

指定 pgBackRest 创建锁文件的位置，用于防止相互冲突的操作并发运行。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器赋予该进程的优先级（即 nice 值）。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时时间。

设置本地或远程进程在协议层等待新消息的超时时间（秒），防止进程无限期阻塞。

注意： protocol-timeout 选项的值必须大于 db-timeout 选项的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用保活机制。

在 socket 连接上启用保活消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza。

stanza 是 PostgreSQL 数据库集群的配置，定义了集群的位置、备份方式、归档选项等。大多数数据库服务器只有一个 PostgreSQL 集群，因此只有一个 stanza；而备份服务器则需要为每个待备份的数据库集群分别配置一个 stanza。

命名 stanza 时，很容易直接使用主集群的名称，但更好的做法是根据集群承载的数据库功能来命名。由于 stanza 名称同时用于主库和所有副本，建议选择能描述集群实际用途的名称（如 app 或 dw），而非本地集群名称（如 main 或 prod）。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

保活数据包计数。

指定连接被判定为断开前，可丢失的 TCP 保活消息数量。

此选项仅在支持 TCP_KEEPCNT socket 选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

保活空闲时间。

指定无网络活动持续多少秒后，操作系统开始发送 TCP 保活消息。

此选项仅在支持 TCP_KEEPIDLE socket 选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

保活消息重传间隔。

指定未收到确认的 TCP 保活消息在多少秒后重新发送。

此选项仅在支持 TCP_KEEPINTVL socket 选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许的 TLSv1.2 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整可接受的加密套件列表。示例为合理选择，除非有特定安全需求。若未设置（默认），则使用底层 OpenSSL 库的默认配置。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许的 TLSv1.3 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整可接受的加密套件列表。若未设置（默认），则使用底层 OpenSSL 库的默认配置。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别输出到 stderr 而非 stdout（由 log-level-console 控制）。输出到 stderr 的内容不包含时间戳和进程信息。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件存储路径。

指定 pgBackRest 日志文件的存储位置。若 log-level-file=off，则无需配置此路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为当前进程创建的子进程启用文件日志记录，日志级别由 log-level-file 指定。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

启用日志时间戳。

在控制台和文件日志中附加时间戳。生成文档等特殊场景下此选项会被禁用。

YAML
default: y
example: --no-log-timestamp

仓库选项

指定仓库选项（--repo）

指定操作仓库。

指定命令操作的目标仓库。

例如，可使用此选项从特定仓库执行恢复，而不是让 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在容器根目录，但通常建议指定前缀（如 /repo），以便日志和其他 Azure 生成的内容也能存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加账户前缀。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

用于加密仓库的加密算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

请注意，即使仓库类型（如 S3）本身支持加密，pgBackRest 的加密也始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定前缀（如 /repo），以便日志和其他 GCS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点。可更新为本地 GCS 服务器或备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号授权。
  • service - 使用本地存储的服务账号密钥。
  • token - 用于本地测试，如 fakegcs。

当 repo-gcs-key-type=service 时，认证令牌续期时会重新加载凭据。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

若备份和归档使用本地挂载的文件系统，则无需此设置。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时，使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时，使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令。

仅当 pgBackRest 在本地主机与仓库主机上的路径不同时才需要此选项。若未定义，仓库主机命令将与本地命令相同。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的位置。仅当仓库主机上的配置文件路径与本地不同时才需要此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地不同时才需要此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地不同时才需要此选项。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

证明客户端证书由其所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

repo-host 已设置时的仓库主机端口。

使用此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 无默认值，端口由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（Secure Shell）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

repo-host 已设置时的仓库主机用户。

定义在仓库主机上执行操作所用的用户。建议不要使用 postgres 用户，而是使用专用用户（如 pgbackrest）。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其对仓库拥有读取权限，但无法意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的地方。

预先估算所需空间可能比较困难。建议先执行若干次备份，记录不同备份类型（全量/增量/差异）的大小，并衡量每天产生的 WAL 量，从而得出大致的空间需求。随着数据库持续增长，需求也会相应变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

归档保留选项（--repo-retention-archive）

连续 WAL 保留的备份数量。

注意： 使备份保持一致所需的 WAL 段将始终保留，直到该备份过期，与此选项的配置无关。

若未设置此值且 repo-retention-full-type 为 count（默认值），则归档过期策略默认与 repo-retention-archive-type 对应的 repo-retention-full（或 repo-retention-diff）值一致——前提是 repo-retention-archive-type 设为 full（或 diff）。这确保了 WAL 仅在对应备份过期时才同步过期。若 repo-retention-full-type 为 time，则此值默认删除比满足 repo-retention-full 设置后所保留的最旧全量备份更早的归档。

若 repo-retention-archive-type 设为 incr，则必须设置此选项。在磁盘空间紧张时，此选项与 repo-retention-archive-type 配合可更激进地过期 WAL 段，但代价是相关备份将无法执行 PITR，因此 不推荐。

YAML
allowed: [1, 9999999]
example: --repo1-retention-archive=2

已弃用名称：retention-archive

归档保留类型选项（--repo-retention-archive-type）

WAL 保留的备份类型。

  • 设为 full 时，pgBackRest 将为 repo-retention-archive 指定数量的全量备份保留归档日志。
  • 设为 diff（差异）时，pgBackRest 将为 repo-retention-archive 指定数量的全量和差异备份保留归档日志；若最后一次备份是全量备份，它也会被计入差异备份数量。
  • 设为 incr（增量）时，pgBackRest 将为 repo-retention-archive 指定数量的全量、差异和增量备份保留归档日志。

建议保持默认值，即仅在全量备份过期时才过期 WAL。

YAML
default: full
example: --repo1-retention-archive-type=diff

已弃用名称：retention-archive-type

差异备份保留选项（--repo-retention-diff）

保留的差异备份数量。

差异备份过期时，与之关联的所有增量备份也会一同过期。若未定义，所有差异备份将保留，直到其依赖的全量备份过期。

请注意，在过期计算中，全量备份也会被计入差异备份数量，这在大多数情况下会略微减少实际保留的差异备份数量。

YAML
allowed: [1, 9999999]
example: --repo1-retention-diff=3

已弃用名称：retention-diff

全量备份保留选项（--repo-retention-full）

全量备份的保留数量/时间。

全量备份过期时，与之关联的所有差异和增量备份也会一同过期。若未定义此选项，将发出警告。若希望无限期保留，请将此选项设为最大值。

YAML
allowed: [1, 9999999]
example: --repo1-retention-full=2

已弃用名称：retention-full

全量备份保留类型选项（--repo-retention-full-type）

全量备份的保留类型。

决定 repo-retention-full 表示的是天数（时间段）还是全量备份数量。

  • 设为 time 时，创建时间早于 repo-retention-full 天的全量备份将被删除，但前提是仓库中至少有一个不早于该天数的备份。例如，若 repo-retention-full 为 30，且存在两个全量备份（一个 25 天前，一个 35 天前），则不会过期任何备份——因为删除 35 天前的备份后只剩 25 天前的备份，而 25 天未满足"至少有一个 30 天以内备份"的条件，因此不允许过期更旧的备份。比最旧保留全量备份更早的归档 WAL 将自动过期，除非显式设置了 repo-retention-archive-type 和 repo-retention-archive。
  • 设为 count 时，超出 repo-retention-full 数量的全量备份将被过期。例如，若 repo-retention-full 为 4，完成第五个全量备份后，最旧的全量备份将被过期以保持数量为 4。

请注意，只有成功完成的备份才会纳入保留计算。例如，若 repo-retention-full-type 为 count 且 repo-retention-full 为 2，则必须存在 3 个完整的全量备份，最旧的才会被过期。

YAML
default: count
example: --repo1-retention-full-type=time

备份历史保留选项（--repo-retention-history）

备份历史清单文件的保留天数。

备份完成时，清单文件（manifest）的副本会存储在 backup.history 路径下。默认情况下这些文件永不过期，因为它们对分析历史数据很有价值，例如用于统计备份和 WAL 随时间的增长趋势。

设置 repo-retention-history 可指定保留备份历史清单的天数。未过期的备份始终保留在备份历史中。指定 repo-retention-history=0 可仅为未过期备份保留备份历史。

当全量备份的历史清单过期时，与该全量备份关联的所有差异和增量备份历史清单也会一同过期。

YAML
allowed: [0, 9999999]
example: --repo1-retention-history=365

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定前缀（如 /repo），以便日志和其他 AWS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义或测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 选项可能有用。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭据的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加存储桶前缀。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

存储仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

主机指纹的生成方式应与 repo-sftp-host-key-hash-type 一致，通过 awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b 命令生成。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下 SFTP 主机密钥检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts 文件，并拒绝连接到主机密钥已更改或不在已知主机文件中的主机。此模式强制用户手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到用户的已知主机文件，但不允许连接到主机密钥已更改的主机。
  • fingerprint - pgBackRest 将主机密钥与 repo-sftp-host-fingerprint 选项指定的指纹进行比对。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明在 SSH 启动时用于计算远程系统主机密钥摘要的哈希类型。较新版本的 libssh2 除 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

SFTP 仓库主机的端口号。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

用于存储仓库的主机上的用户。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

认证过程中用于搜索 SFTP 主机匹配的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将只在这些文件中搜索匹配项。文件路径必须为完整路径或以波浪号开头的路径。此选项可多次传入以指定多个已知主机文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参阅 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件。使用 OpenSSL 编译时为可选；使用其他库编译时为必需。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接存储（如 S3、Azure）时，使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接存储（如 S3、Azure）时，使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机，通常用于测试。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储（如 S3、Azure）端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

指定在仓库为对象存储（如 S3）时添加到对象上的标签。可多次使用此选项以添加多个标签。

pgBackRest 不提供修改这些标签的功能，因此请在运行 stanza-create 之前确保标签设置正确，以保证整个仓库标签的一致性。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

S3 等对象存储支持在文件过大无法全部载入内存时分块上传。即使文件能全部载入内存，限制上传所用内存量也更为高效。

较大的块大小通常能提升性能，因为它可以减少上传请求数量，使更多文件在单次请求中完成上传而无需分块处理。其代价是内存占用更高，且由于块缓冲区需按进程分配，process-max 值越大，整体内存消耗越多。

请注意，有效的块大小因存储类型和平台而异。例如，AWS S3 的最小块大小为 5MiB。各存储类型对块大小的叫法不同，查找最小/最大值时请参考：AWS S3 用"part size"，GCS 用"chunk size"，Azure 用"block size"。

若文件大小超过 1GiB（PostgreSQL 默认创建文件的上限），块大小将逐步增大至允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用对存储（如 S3、Azure）服务端 TLS 证书的验证。禁用验证仅应用于测试或使用自签名证书的场景。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库符号链接选项（--repo-symlink）

在仓库中创建符号链接。

启用 latest 符号链接和表空间符号链接的创建。这些符号链接在使用快照进行仓库内原地恢复时最为有用，而这是一个不常见的使用场景。

虽然此功能对绝大多数用户可能没有实际价值，但出于历史原因默认保持开启。对于不支持符号链接的类 POSIX 存储，禁用此选项可能更为合适。

YAML
default: y
example: --no-repo1-symlink

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud 存储
  • posix - 符合 POSIX 标准的文件系统
  • s3 - AWS 简单存储服务
  • sftp - 安全文件传输协议

将 NFS 挂载用作 posix 仓库时，适用于 pgBackRest 的规则与 PostgreSQL 文档中描述的相同，详见 创建数据库集群 - 文件系统。

YAML
default: posix
example: --repo1-type=cifs

4.7 - 帮助命令（help）

pgBackRest help 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: help

help 命令提供三个层级的帮助信息：未指定命令时显示通用帮助；指定命令（例如 pgbackrest help backup）时显示该命令的完整说明及有效选项列表；在命令之外还指定了某个选项（例如 pgbackrest help backup type）时显示该选项在此命令下的完整说明。

命令选项

显示帮助选项（--help）

显示帮助信息。

即使未指定 help 命令也会显示帮助信息，且优先于 --version 选项。

YAML
default: n
example: --help

显示版本选项（--version）

显示版本信息。

即使未指定 version 或 help 命令也会显示版本信息。

YAML
default: n
example: --version

4.8 - Info 命令（info）

pgBackRest info 命令选项与行为参考。

原始页面： pgBackRest Command Docs: info

info 命令可查询单个 stanza（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）或所有 stanza 的信息。默认输出为文本格式，以人类可读的摘要展示所请求 stanza 的备份信息。该格式可能随版本更新而变化。

如需机器可读输出，请使用 --output=json。JSON 输出包含的信息远多于文本格式，且除非发现缺陷，其格式保持稳定。

若只需快速查看进度信息，可指定 --detail-level=progress。注意此模式会跳过 stanza 可用性检查以外的所有检查。

每个 stanza 占独立的输出区块，可使用 --stanza 选项将输出限定到单个 stanza。stanza 的 status 字段简要反映其健康状态：ok 表示 pgBackRest 运行正常。若配置了多个仓库，mixed 状态表示该 stanza 在一个或多个仓库上存在异常，此时会按仓库分别显示详细状态。若某仓库发生了未知错误代码的错误，将使用 other 作为错误码，并附上完整的错误详情。wal archive min/max 显示当前归档中最小和最大 WAL 段；配置多个仓库时，除非指定了 --repo 选项，否则将跨所有仓库汇总报告。注意，由于归档保留策略或其他原因，归档中可能存在间隙。

若主机上正在运行 backup/expire 或 restore 命令，status 信息旁边将分别显示 backup/expire running 和/或 restore running。文本输出还会报告每个仓库的进度，JSON 输出中则会包含 repo 数组。

备份按从旧到新的顺序列出。最旧的备份 始终 是全量备份（标签末尾以 F 标识），最新的备份可以是全量备份、差异备份（末尾以 D 标识）或增量备份（末尾以 I 标识）。

timestamp start/stop 定义了备份运行的时间段。timestamp stop 可用于确定时间点恢复（PITR）所需的目标备份。更多关于时间点恢复的信息，请参见 时间点恢复 章节。

wal start/stop 定义了恢复时将数据库恢复到一致状态所需的 WAL 范围。backup 命令完成前会确保该 WAL 范围已存在于归档中。

database size 是数据库未压缩的完整大小，database backup size 是本次备份实际需要备份的数据量（全量备份时两者相同）。

repo 表示该备份所在的仓库。backup set size 包含该备份及仓库中恢复数据库所需引用的所有备份文件，backup size 仅包含本次备份中的文件（全量备份时两者相同）。若 pgBackRest 启用了压缩，仓库大小反映压缩后的文件大小。

backup reference total 汇总了恢复该备份时所需引用的其他备份数量。使用 --set 选项可显示完整的引用列表。

命令选项

详细级别选项（--detail-level）

输出详细级别。

支持以下级别：

  • progress - 仅输出当前备份/expire 的进度信息。此级别不能与 --set 选项同时使用。
  • full - 输出完整信息。
YAML
default: full
example: --detail-level=progress

输出格式选项（--output）

输出格式。

支持以下输出类型：

  • text - 备份信息的人类可读摘要。
  • json - JSON 格式的完整机器可读备份信息。
YAML
default: text
example: --output=json

备份集选项（--set）

要查看详情的备份集。

详情包括：恢复该备份所需引用的其他备份完整列表、备份集中的数据库列表（含 OID，不含模板数据库）、表空间（含 OID）及其默认恢复目标路径，以及指定 --link-all 时符号链接的恢复目标路径。

YAML
example: --set=20150131-153358F_20150131-153401I

类型选项（--type）

按备份类型过滤。

使用以下备份类型之一过滤输出：

  • full - 仅输出全量备份。
  • diff - 仅输出差异备份。
  • incr - 仅输出增量备份。
YAML
example: --type=full

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于具体选项，每个操作可能还会使用额外内存，例如 gz 压缩可能额外使用 256KiB 内存。

允许的值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

如需使用其他 SSH 客户端，或 ssh 命令不在 $PATH 中，可通过此选项指定具体路径。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，设置网络传输的压缩级别。压缩用于减少网络流量。当 compress-type 不等于 none 时，将忽略 compress-level-network，转而使用 compress-level，以避免文件被压缩两次。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项指定非默认的配置文件路径。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

额外 pgBackRest 配置文件的路径。

该路径下扩展名为 .conf 的配置文件将与 pgBackRest 主配置文件合并，形成完整的配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

用于覆盖 --config 和 --config-include-path 选项的默认基础路径，除非这两个选项已在命令行中显式设置。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读/写操作的超时时间（秒）。

注意，整个读/写操作无需在此超时时间内完成，但 必须 有所进展，哪怕只传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 使用此路径下的锁文件防止冲突操作并发执行。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器为进程分配的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时时间。

本地或远程进程在协议层等待新消息的超时时间（秒），防止进程无限期等待。

注意： protocol-timeout 选项的值必须大于 db-timeout 选项的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用保活（keep-alive）。

在套接字连接上启用保活消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza。

stanza 是 PostgreSQL 数据库集群的配置单元，定义了集群的位置、备份方式、归档选项等。大多数数据库主机只有一个 PostgreSQL 集群，因此只有一个 stanza；备份服务器则为每个需要备份的数据库集群各配置一个 stanza。

命名 stanza 时，虽然容易以主集群名称命名，但更好的做法是以集群所承载数据库的功能来命名。由于 stanza 名称同时适用于主库和所有副本，选择能描述集群实际用途的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

保活（keep-alive）计数。

在判定连接已断开之前，允许丢失的 TCP 保活消息数量。

此选项仅在支持 TCP_KEEPCNT 套接字选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

保活（keep-alive）空闲时间。

无网络活动持续多少秒后，操作系统开始发送 TCP 保活消息。

此选项仅在支持 TCP_KEEPIDLE 套接字选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

保活（keep-alive）间隔时间。

未收到确认的 TCP 保活消息在多少秒后重新发送。

此选项仅在支持 TCP_KEEPINTVL 套接字选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均已加密。默认情况下，到对象存储（如 S3）的连接也经过加密。

注意： 所有传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。示例中的配置是合理的选择，除非有特殊安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均已加密。默认情况下，到对象存储（如 S3）的连接也经过加密。

注意： 所有传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪信息（非常详细的调试）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪信息（非常详细的调试）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别输出到 stderr 而非 stdout（由 log-level-console 控制）。输出到 stderr 的日志不含时间戳和进程信息。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪信息（非常详细的调试）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件存储在此路径下。注意，若 log-level-file=off，则无需设置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为该进程创建的所有子进程启用文件日志记录，日志级别由 log-level-file 指定。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中启用时间戳。在生成文档等特殊情况下，此选项会被禁用。

YAML
default: y
example: --no-log-timestamp

仓库选项

指定仓库选项（--repo）

设置仓库。

指定命令操作的目标仓库。

例如，可使用此选项从特定仓库执行恢复，而不是让 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

pgBackRest 仓库可通过设置 repo-path=/ 存储在容器根目录下，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 Azure 生成的内容也能存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管身份自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 前添加账户前缀。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

用于加密仓库的加密算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

注意，即使仓库类型（如 S3）支持服务端加密，pgBackRest 也始终在客户端执行加密。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

pgBackRest 仓库可通过设置 repo-path=/ 存储在存储桶根目录下，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 GCS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点。可更新为使用本地 GCS 服务器或其他端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号授权。
  • service - 使用本地存储的服务账号密钥。
  • token - 用于本地测试，例如 fakegcs。

当 repo-gcs-key-type=service 时，认证令牌续期时将重新加载凭证。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

当备份和归档到本地挂载的文件系统时，无需设置此选项。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令路径。

仅当仓库主机上的 pgBackRest 命令路径与本地不同时才需要设置。若未定义，仓库主机命令将与本地命令保持一致。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的位置。仅当仓库主机上的配置文件路径与本地不同时才需要设置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地不同时才需要设置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地不同时才需要设置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由其所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

设置了 repo-host 时仓库主机使用的端口。

使用此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - Secure Shell。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

设置了 repo-host 时仓库主机使用的用户。

定义在仓库主机上执行操作的用户。建议使用非 postgres 用户，例如 pgbackrest。如果 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其对仓库拥有只读权限，避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的地方。

事先估算所需空间可能比较困难。最佳做法是先执行几次备份，记录不同备份类型（全量/增量/差异）的大小，并测量每天生成的 WAL 量，以此作为空间规划的参考。随着数据库的演进，需求也会随时间变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

pgBackRest 仓库可通过设置 repo-path=/ 存储在存储桶根目录下，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 AWS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义/测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 选项可能会有用。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶时所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费模式。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭证的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 前添加存储桶前缀。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

包含仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

指纹的生成方式应与 repo-sftp-host-key-hash-type 一致。可通过以下命令生成：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts，并拒绝连接到主机密钥已更改或未在已知主机文件中找到的主机。此选项要求用户手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到用户的已知主机文件中，但不允许连接到主机密钥已更改的主机。
  • fingerprint - pgBackRest 将根据 repo-sftp-host-fingerprint 选项指定的指纹验证主机密钥。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明 SSH 启动时用于计算远程系统主机密钥摘要的哈希类型。较新版本的 libssh2 除支持 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

SFTP 仓库主机端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

用于存储仓库的主机上的用户。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

认证期间用于搜索 SFTP 主机匹配项的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将在这些路径中搜索匹配项。文件路径必须是完整路径或以波浪号（~）开头的路径。该选项可多次传入以指定多个已知主机文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参见 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件。编译时使用 OpenSSL 则为可选，使用其他库则为必填。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接存储（如 S3、Azure）时使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接存储（如 S3、Azure）时使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机。通常用于测试。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储（如 S3、Azure）端点（或指定的主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库为对象存储（如 S3）时，指定添加到对象上的标签。可重复使用此选项以添加多个标签。

pgBackRest 不提供修改这些标签的功能，因此请在运行 stanza-create 之前正确设置，以确保整个仓库的标签一致。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

当文件过大而无法完整存入内存时，S3 等对象存储支持分块上传。即使文件能够存入内存，限制上传所用内存量也更为高效。

较大的分块大小通常能提升性能，因为可以减少上传请求次数，并允许在单次请求中上传更多数据而无需分块。缺点是内存占用更高，且由于分块缓冲区必须按进程分配，较大的 process-max 值会导致整体内存消耗增加。

注意，有效的分块大小因存储类型和平台而异。例如，AWS S3 的最小分块大小为 5MiB。各存储类型对分块大小的术语不同：AWS S3 使用 “part size”，GCS 使用 “chunk size”，Azure 使用 “block size”。

若文件大于 1GiB（PostgreSQL 默认创建的最大文件大小），分块大小将逐步增大至允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用对存储（如 S3、Azure）服务器 TLS 证书的验证。仅在测试场景或使用自签名证书时才应禁用验证。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库目标时间选项（--repo-target-time）

仓库的目标时间。

目标时间定义了命令读取版本化存储上的仓库所使用的时间点。通过此选项，命令可以读取某一历史时刻的仓库状态，从而恢复因用户误操作或恶意软件导致被删除或损坏的数据。

S3、GCS 和 Azure 均支持版本化存储，但通常默认不启用。除了启用版本控制外，还可考虑为 S3 启用对象锁定，为 GCS 或 Azure 启用软删除。

使用 repo-target-time 选项时，还必须同时指定 repo 选项。并非所有仓库类型都支持版本控制，通常针对单个仓库进行恢复更为合理。

注意，与存储时间戳的比较为 <=（小于等于）所提供的时间戳，且提供的时间戳中的毫秒部分将被截断。

YAML
example: --repo-target-time=2024-08-08 12:12:12+00

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud 存储
  • posix - 符合 POSIX 标准的文件系统
  • s3 - AWS 简单存储服务
  • sftp - 安全文件传输协议

将 NFS 挂载用作 posix 仓库时，pgBackRest 遵循的规则与 PostgreSQL 文档中描述的相同，详见 Creating a Database Cluster - File Systems。

YAML
default: posix
example: --repo1-type=cifs

4.9 - 仓库获取命令（repo-get）

pgBackRest repo-get 命令选项与行为参考。

原始页面： pgBackRest Command Docs: repo-get

repo-get 命令类似于 Unix 的 cat 命令，但支持所有仓库类型。使用此命令需要提供完整的文件名，主要用于管理、排查和测试目的，不是常规 pgBackRest 使用流程中的必需命令。

若仓库已加密，repo-get 将自动解密文件。文件不会自动解压，但可将输出通过管道传递给相应的解压命令，例如 gzip -d。

若配置了多个仓库，命令默认使用优先级最高的仓库（如 repo1），除非通过 --repo 选项指定了具体仓库。

命令选项

忽略缺失文件选项（--ignore-missing）

忽略缺失的源文件。

若源文件不存在，则以退出码 1 退出，而不抛出错误。

YAML
default: n
example: --ignore-missing

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于具体选项，每个操作可能还会使用额外内存，例如 gz 压缩可能额外使用 256KiB 内存。

允许的值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

如需使用其他 SSH 客户端，或 ssh 命令不在 $PATH 中，可通过此选项指定具体路径。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，设置网络传输的压缩级别。压缩用于减少网络流量。当 compress-type 不等于 none 时，将忽略 compress-level-network，转而使用 compress-level，以避免文件被压缩两次。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项指定非默认的配置文件路径。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

额外 pgBackRest 配置文件的路径。

该路径下扩展名为 .conf 的配置文件将与 pgBackRest 主配置文件合并，形成完整的配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

用于覆盖 --config 和 --config-include-path 选项的默认基础路径，除非这两个选项已在命令行中显式设置。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读/写操作的超时时间（秒）。

注意，整个读/写操作无需在此超时时间内完成，但 必须 有所进展，哪怕只传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器为进程分配的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时时间。

本地或远程进程在协议层等待新消息的超时时间（秒），防止进程无限期等待。

注意： protocol-timeout 选项的值必须大于 db-timeout 选项的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

原始数据选项（--raw）

不对数据进行转换。

执行当前命令时跳过所有数据转换操作（如加密、解压等）。

YAML
default: n
example: --raw

保活选项（--sck-keep-alive）

启用保活（keep-alive）。

在套接字连接上启用保活消息。

YAML
default: y
example: --no-sck-keep-alive

TCP 保活计数选项（--tcp-keep-alive-count）

保活（keep-alive）计数。

在判定连接已断开之前，允许丢失的 TCP 保活消息数量。

此选项仅在支持 TCP_KEEPCNT 套接字选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

保活（keep-alive）空闲时间。

无网络活动持续多少秒后，操作系统开始发送 TCP 保活消息。

此选项仅在支持 TCP_KEEPIDLE 套接字选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

保活（keep-alive）间隔时间。

未收到确认的 TCP 保活消息在多少秒后重新发送。

此选项仅在支持 TCP_KEEPINTVL 套接字选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均已加密。默认情况下，到对象存储（如 S3）的连接也经过加密。

注意： 所有传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。示例中的配置是合理的选择，除非有特殊安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均已加密。默认情况下，到对象存储（如 S3）的连接也经过加密。

注意： 所有传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪信息（非常详细的调试）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪信息（非常详细的调试）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别输出到 stderr 而非 stdout（由 log-level-console 控制）。输出到 stderr 的日志不含时间戳和进程信息。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪信息（非常详细的调试）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件存储在此路径下。注意，若 log-level-file=off，则无需设置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为该进程创建的所有子进程启用文件日志记录，日志级别由 log-level-file 指定。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中启用时间戳。在生成文档等特殊情况下，此选项会被禁用。

YAML
default: y
example: --no-log-timestamp

仓库选项

指定仓库选项（--repo）

设置仓库。

指定命令操作的目标仓库。

例如，可使用此选项从特定仓库执行恢复，而不是让 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

pgBackRest 仓库可通过设置 repo-path=/ 存储在容器根目录下，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 Azure 生成的内容也能存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管身份自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 前添加账户前缀。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

用于加密仓库的加密算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

注意，即使仓库类型（如 S3）支持服务端加密，pgBackRest 也始终在客户端执行加密。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

pgBackRest 仓库可通过设置 repo-path=/ 存储在存储桶根目录下，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 GCS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点。可更新为使用本地 GCS 服务器或其他端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号授权。
  • service - 使用本地存储的服务账号密钥。
  • token - 用于本地测试，例如 fakegcs。

当 repo-gcs-key-type=service 时，认证令牌续期时将重新加载凭证。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

当备份和归档到本地挂载的文件系统时，无需设置此选项。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令路径。

仅当仓库主机上的 pgBackRest 命令路径与本地不同时才需要设置。若未定义，仓库主机命令将与本地命令保持一致。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的位置。仅当仓库主机上的配置文件路径与本地不同时才需要设置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地不同时才需要设置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地不同时才需要设置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由其所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

设置了 repo-host 时仓库主机使用的端口。

使用此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - Secure Shell。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

设置了 repo-host 时仓库主机使用的用户。

定义在仓库主机上执行操作的用户。建议使用非 postgres 用户，例如 pgbackrest。如果 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其对仓库拥有只读权限，避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的地方。

事先估算所需空间可能比较困难。最佳做法是先执行几次备份，记录不同备份类型（全量/增量/差异）的大小，并测量每天生成的 WAL 量，以此作为空间规划的参考。随着数据库的演进，需求也会随时间变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

pgBackRest 仓库可通过设置 repo-path=/ 存储在存储桶根目录下，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 AWS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义/测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 选项可能会有用。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶时所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费模式。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭证的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 前添加存储桶前缀。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

包含仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

指纹的生成方式应与 repo-sftp-host-key-hash-type 一致。可通过以下命令生成：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts，并拒绝连接到主机密钥已更改或未在已知主机文件中找到的主机。此选项要求用户手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到用户的已知主机文件中，但不允许连接到主机密钥已更改的主机。
  • fingerprint - pgBackRest 将根据 repo-sftp-host-fingerprint 选项指定的指纹验证主机密钥。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明 SSH 启动时用于计算远程系统主机密钥摘要的哈希类型。较新版本的 libssh2 除支持 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

SFTP 仓库主机端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

用于存储仓库的主机上的用户。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

认证期间用于搜索 SFTP 主机匹配项的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将在这些路径中搜索匹配项。文件路径必须是完整路径或以波浪号（~）开头的路径。该选项可多次传入以指定多个已知主机文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参见 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件。编译时使用 OpenSSL 则为可选，使用其他库则为必填。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接存储（如 S3、Azure）时使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接存储（如 S3、Azure）时使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机。通常用于测试。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储（如 S3、Azure）端点（或指定的主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库为对象存储（如 S3）时，指定添加到对象上的标签。可重复使用此选项以添加多个标签。

pgBackRest 不提供修改这些标签的功能，因此请在运行 stanza-create 之前正确设置，以确保整个仓库的标签一致。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

当文件过大而无法完整存入内存时，S3 等对象存储支持分块上传。即使文件能够存入内存，限制上传所用内存量也更为高效。

较大的分块大小通常能提升性能，因为可以减少上传请求次数，并允许在单次请求中上传更多数据而无需分块。缺点是内存占用更高，且由于分块缓冲区必须按进程分配，较大的 process-max 值会导致整体内存消耗增加。

注意，有效的分块大小因存储类型和平台而异。例如，AWS S3 的最小分块大小为 5MiB。各存储类型对分块大小的术语不同：AWS S3 使用 “part size”，GCS 使用 “chunk size”，Azure 使用 “block size”。

若文件大于 1GiB（PostgreSQL 默认创建的最大文件大小），分块大小将逐步增大至允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用对存储（如 S3、Azure）服务器 TLS 证书的验证。仅在测试场景或使用自签名证书时才应禁用验证。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库目标时间选项（--repo-target-time）

仓库的目标时间。

目标时间定义了命令读取版本化存储上的仓库所使用的时间点。通过此选项，命令可以读取某一历史时刻的仓库状态，从而恢复因用户误操作或恶意软件导致被删除或损坏的数据。

S3、GCS 和 Azure 均支持版本化存储，但通常默认不启用。除了启用版本控制外，还可考虑为 S3 启用对象锁定，为 GCS 或 Azure 启用软删除。

使用 repo-target-time 选项时，还必须同时指定 repo 选项。并非所有仓库类型都支持版本控制，通常针对单个仓库进行恢复更为合理。

注意，与存储时间戳的比较为 <=（小于等于）所提供的时间戳，且提供的时间戳中的毫秒部分将被截断。

YAML
example: --repo-target-time=2024-08-08 12:12:12+00

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud 存储
  • posix - 符合 POSIX 标准的文件系统
  • s3 - AWS 简单存储服务
  • sftp - 安全文件传输协议

将 NFS 挂载用作 posix 仓库时，pgBackRest 遵循的规则与 PostgreSQL 文档中描述的相同，详见 Creating a Database Cluster - File Systems。

YAML
default: posix
example: --repo1-type=cifs

4.10 - 仓库列表命令（repo-ls）

pgBackRest repo-ls 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: repo-ls

repo-ls 类似于 Unix 的 ls 命令，但支持所有 pgBackRest 仓库类型。该命令接受一个路径参数，可以是绝对路径，也可以是相对于 --repo-path 所定义的仓库根路径的相对路径。此命令主要用于管理、排查和测试场景，并非常规部署的必要命令。

默认以文本格式输出，每行一个文件名。指定 --output=json 可切换为 JSON 格式。

若配置了多个仓库，默认操作优先级最高的仓库（如 repo1），如需指定特定仓库，请使用 --repo 选项。

命令选项

过滤输出选项（--filter）

使用正则表达式过滤输出。

过滤器在输出文件名或路径名之前生效。

YAML
example: --filter="(F|D|I)$"

输出格式选项（--output）

输出格式。

支持以下输出类型：

  • text — 简单列表，每行一个文件、链接或路径名。
  • json — 以 JSON 格式输出文件、链接或路径的详细信息。

JSON 格式包含以下字段：

  • name — 文件、链接或路径名（递归时包含部分路径）。
  • type — file（文件）、path（路径）或 link（链接）。
  • size — 字节大小（仅限文件）。
  • time — 最后修改时间（仅限文件）。
  • destination — 链接目标（仅限链接）。
YAML
default: text
example: --output=json

递归子路径选项（--recurse）

在输出中包含所有子路径。

输出将递归包含所有子路径及其下的文件。

YAML
default: n
example: --recurse

排序输出选项（--sort）

按升序、降序或不排序输出。

支持以下排序类型：

  • asc — 升序。
  • desc — 降序。
  • none — 不排序。
YAML
default: asc
example: --sort=desc

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

该缓冲区用于复制、压缩、加密等操作。实际使用的缓冲区数量取决于具体选项，每种操作可能额外占用内存，例如 gz 压缩最多可额外使用 256KiB 内存。

允许的值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

如需使用特定的 SSH 客户端，或 ssh 命令不在 $PATH 中，可通过此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上执行时，此选项设置网络传输的压缩级别，以减少网络流量。若 compress-type 不等于 none，则忽略此设置，改用 compress-level，避免对文件进行二次压缩。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

通过此选项可指定非默认路径的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加配置文件的目录路径。

该目录下扩展名为 .conf 的文件将与 pgBackRest 主配置文件合并，共同构成最终的配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置覆盖 --config 和 --config-include-path 的默认基础路径，前提是这两个选项未在命令行中显式指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

I/O 超时选项（--io-timeout）

I/O 超时。

连接、读写操作的超时时间（秒）。

注意，整个读写操作不必在此超时内完成，但必须持续有进展，哪怕每次只传输一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

指定内核调度器为该进程分配的 niceness 值。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限自行提升优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时。

设置本地或远程进程在协议层等待新消息的超时时间（秒），防止进程无限期挂起。

注意： protocol-timeout 的值必须大于 db-timeout。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用 keep-alive。

在套接字连接上启用 keep-alive 消息。

YAML
default: y
example: --no-sck-keep-alive

TCP 保活计数选项（--tcp-keep-alive-count）

Keep-alive 计数。

指定在判定连接断开之前，允许丢失的 TCP keep-alive 消息数量。

此选项仅在系统支持 TCP_KEEPCNT 套接字选项时有效。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

Keep-alive 空闲时间。

指定在无网络活动达到多少秒后，操作系统开始发送 TCP keep-alive 消息。

此选项仅在系统支持 TCP_KEEPIDLE 套接字选项时有效。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

Keep-alive 间隔时间。

指定未收到确认的 TCP keep-alive 消息重新发送前的等待秒数。

此选项仅在系统支持 TCP_KEEPINTVL 套接字选项时有效。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许的 TLSv1.2 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密，默认情况下与对象存储（如 S3）的连接也会加密。

注意： 所有传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许的加密套件。示例中的配置是合理的选择，除非有特定安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许的 TLSv1.3 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密，默认情况下与对象存储（如 S3）的连接也会加密。

注意： 所有传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off — 不记录任何日志（不推荐）
  • error — 仅记录错误
  • warn — 记录警告和错误
  • info — 记录信息、警告和错误
  • detail — 记录详情、信息、警告和错误
  • debug — 记录调试、详情、信息、警告和错误
  • trace — 记录跟踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off — 不记录任何日志（不推荐）
  • error — 仅记录错误
  • warn — 记录警告和错误
  • info — 记录信息、警告和错误
  • detail — 记录详情、信息、警告和错误
  • debug — 记录调试、详情、信息、警告和错误
  • trace — 记录跟踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些级别的日志输出到 stderr 而非 stdout（由 log-level-console 控制）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off — 不记录任何日志（不推荐）
  • error — 仅记录错误
  • warn — 记录警告和错误
  • info — 记录信息、警告和错误
  • detail — 记录详情、信息、警告和错误
  • debug — 记录调试、详情、信息、警告和错误
  • trace — 记录跟踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件存储路径。

pgBackRest 将日志文件保存到此路径。注意，若 log-level-file=off，则无需配置此项。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为该进程创建的所有子进程启用文件日志记录，使用 log-level-file 指定的日志级别。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中输出时间戳。某些特殊场景（如生成文档）下会禁用此选项。

YAML
default: y
example: --no-log-timestamp

仓库选项

指定仓库选项（--repo）

指定仓库。

指定命令操作的目标仓库。

例如，可通过此选项指定从特定仓库执行恢复，而非由 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

pgBackRest 仓库可通过设置 repo-path=/ 存储在容器根目录，但通常建议指定一个前缀（如 /repo），这样日志及其他 Azure 生成的内容也可存放在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared — 共享密钥
  • sas — 共享访问签名
  • auto — 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host — 连接到 account.endpoint 主机。
  • path — 连接到 endpoint 主机，并在 URI 中添加账户前缀。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

仓库加密算法。

支持以下加密类型：

  • none — 不加密
  • aes-256-cbc — 256 位密钥的 AES 加密标准

注意，即使仓库存储类型（如 S3）本身支持加密，pgBackRest 的加密始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

pgBackRest 仓库可通过设置 repo-path=/ 存储在存储桶根目录，但通常建议指定一个前缀（如 /repo），这样日志及其他 GCS 生成的内容也可存放在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点地址，可替换为本地 GCS 服务器或其他备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto — 使用实例服务账号授权。
  • service — 使用本地存储的服务账号密钥。
  • token — 用于本地测试，如 fakegcs。

当 repo-gcs-key-type=service 时，认证令牌续期时会重新加载身份凭据。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费归属的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

若备份和归档存储在本地挂载的文件系统中，则无需此设置。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时，使用指定的 CA 文件替代系统默认值。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时，使用指定的 CA 路径替代系统默认值。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

向仓库主机发送此证书以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令。

仅当仓库主机上的 pgBackRest 命令路径与本地不同时才需要配置。若未定义，将沿用本地命令路径。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的路径。仅当仓库主机的配置文件路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机的配置包含路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机的配置路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由其所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

repo-host 已设置时的仓库主机端口。

通过此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口由 cmd-ssh 所指定命令的配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh — 安全外壳协议。
  • tls — pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

repo-host 已设置时的仓库主机用户。

定义在仓库主机上执行操作所使用的用户。建议使用专用用户（如 pgbackrest）而非 postgres。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其对仓库拥有读取权限，同时避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的位置。

预先估算所需空间可能比较困难。建议先执行几次备份，分别记录全量、增量、差异备份的大小，并统计每天的 WAL 生成量，从而大致估算所需空间。随着数据库的演进，空间需求也会持续变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

pgBackRest 仓库可通过设置 repo-path=/ 存储在存储桶根目录，但通常建议指定一个前缀（如 /repo），这样日志及其他 AWS 生成的内容也可存放在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与存储桶所在区域匹配。

自定义或测试配置时，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 等选项可能有所帮助。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS KMS 密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

存储桶所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭据的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host — 连接到 bucket.endpoint 主机。
  • path — 连接到 endpoint 主机，并在 URI 中添加存储桶前缀。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

存放仓库的 SFTP 主机地址。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

指纹的生成方式须与 repo-sftp-host-key-hash-type 保持一致。可通过以下命令生成：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下检查类型：

  • strict — pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts，并拒绝连接密钥已变更或不在已知主机文件中的主机。此选项要求手动添加所有新主机。
  • accept-new — pgBackRest 自动将新主机密钥添加到已知主机文件，但不允许连接密钥已变更的主机。
  • fingerprint — 根据 repo-sftp-host-fingerprint 指定的指纹验证主机密钥。
  • none — 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明 SSH 握手时计算远程主机密钥摘要所用的哈希算法。较新版本的 libssh2 在 md5 和 sha1 之外还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

存储仓库的主机上对应的用户名。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

认证时用于匹配 SFTP 主机的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若指定了一个或多个文件路径，pgBackRest 将仅在这些文件中查找匹配项。路径必须为完整路径或以波浪号（~）开头的路径。此选项可多次传入以指定多个文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参阅 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件路径。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件路径。若编译时链接的是 OpenSSL，则此项可选；若链接的是其他库，则为必填。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接对象存储（如 S3、Azure）时，使用指定的 CA 文件替代系统默认值。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接对象存储（如 S3、Azure）时，使用指定的 CA 路径替代系统默认值。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到非标准存储端点（如 S3、Azure）的主机地址，通常用于测试。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接对象存储端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库使用对象存储（如 S3）时，为对象添加的标签。此选项可多次指定以添加多个标签。

pgBackRest 不提供修改已有标签的功能，因此请在执行 stanza-create 之前确认标签设置正确，以保证整个仓库的标签一致性。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

S3 等对象存储在文件过大无法整体载入内存时，支持分块上传。即使文件能放入内存，限制单次上传的内存用量也更为高效。

较大的块大小通常有助于提升性能，因为它能减少上传请求次数，在单个请求中传输更多数据。但代价是内存占用更高，且块缓冲区按进程分配，process-max 越大，总内存消耗越多。

不同存储类型和平台对块大小的有效范围要求不同。例如，AWS S3 的最小块大小为 5MiB。各存储类型对此的术语也有差异：AWS S3 称为 “part size”，GCS 称为 “chunk size”，Azure 称为 “block size”。

若文件超过 1GiB（PostgreSQL 默认的单文件上限），块大小将自动逐步增大直至允许的最大值，以确保文件能够上传完成。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

控制是否验证对象存储（如 S3、Azure）服务器的 TLS 证书。仅在测试或使用自签名证书等特殊场景下才应禁用验证。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库目标时间选项（--repo-target-time）

仓库目标时间。

指定读取版本化存储上仓库时所参照的时间点，从而访问某一历史时刻的仓库状态，用于恢复因误操作或恶意软件导致删除或损坏的数据。

S3、GCS 和 Azure 均支持版本化存储，但通常默认未启用。除启用版本控制外，还可以考虑为 S3 启用对象锁定，为 GCS 或 Azure 启用软删除。

使用 repo-target-time 时，必须同时指定 repo 选项。并非所有仓库类型都支持版本控制，通常针对单个仓库进行恢复最为合理。

注意，时间戳比较使用 <= 关系，且提供的时间戳中的毫秒部分会被截断。

YAML
example: --repo-target-time=2024-08-08 12:12:12+00

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure — Azure Blob 存储服务
  • cifs — 类似 posix，但禁用链接和目录 fsync
  • gcs — Google Cloud 存储
  • posix — 符合 POSIX 规范的文件系统
  • s3 — AWS 简单存储服务
  • sftp — 安全文件传输协议

将 NFS 挂载用作 posix 类型仓库时，适用于 pgBackRest 的规则与 PostgreSQL 文档中的描述相同，详见 Creating a Database Cluster - File Systems。

YAML
default: posix
example: --repo1-type=cifs

4.11 - 恢复命令（restore）

pgBackRest restore 命令的选项与行为参考。

Source: pgBackRest Command Docs: restore

restore 命令默认从第一个存有备份的仓库中自动选取最新备份（参见 快速开始 - 恢复备份）。仓库的检查顺序由 pgbackrest.conf 决定（例如先检查 repo1，再检查 repo2）。若要从特定仓库恢复，可使用 --repo 选项（例如 --repo=1）。若需恢复非最新的备份，可传入 --set 选项。

使用 --type=time 或 --type=lsn 进行 PITR（时间点恢复）时，必须通过 --target 选项指定目标时间或目标 LSN。若未通过 --set 选项指定备份集，系统将依次检查各仓库，查找包含所请求时间或 LSN 的备份。若未找到匹配备份，--type=time 将使用第一个存有备份的仓库中的最新备份，而 --type=lsn 则不会选择任何备份。对于其他类型的 PITR（如 xid），若目标早于最新备份，则必须通过 --set 选项明确指定备份集。详情及示例请参见 时间点恢复。

按照 PostgreSQL 的建议，复制槽不包含在恢复中。更多信息请参阅 PostgreSQL 文档中的 Backing Up The Data Directory。

命令选项

归档模式选项（--archive-mode）

恢复后集群的归档模式设置。

此选项用于在恢复后的集群上保留或禁用归档功能。当集群必须被提升（promote）以执行某些操作，但并非打算成为新主库时，此选项非常有用——在这种情况下，将 WAL 从该集群推送到仓库并不合适。

支持以下模式：

  • off - 通过设置 archive_mode=off 禁用归档。
  • preserve - 保留当前的 archive_mode 设置。

注意： 此选项不适用于 PostgreSQL < 12。

YAML
default: preserve
example: --archive-mode=off

排除数据库选项（--db-exclude）

恢复时排除指定的数据库。

被排除的数据库将以稀疏清零文件的形式恢复，以节省空间，但仍允许 PostgreSQL 完成恢复过程。恢复完成后，这些数据库将无法访问，但可以用 drop database 命令将其删除。可多次传入 --db-exclude 选项以排除多个数据库。

与 --db-include 选项组合使用时，--db-exclude 仅适用于标准系统数据库（template0、template1 和 postgres）。

YAML
example: --db-exclude=db_main

包含数据库选项（--db-include）

仅恢复指定的数据库。

此功能允许只恢复选定的数据库。未明确包含的数据库将以稀疏清零文件的形式恢复，以节省空间，但仍允许 PostgreSQL 完成恢复过程。恢复完成后，未包含的数据库将无法访问，但可以用 drop database 命令将其删除。

注意： 内置数据库（template0、template1 和 postgres）始终会被恢复，除非被明确排除。

可多次传入 --db-include 选项以包含多个数据库。

更多信息及注意事项请参见 选择性数据库恢复。

YAML
example: --db-include=db_main

强制选项（--force）

强制执行恢复。

单独使用时，此选项将强制完全覆盖 PostgreSQL 数据目录及表空间路径。与 --delta 组合使用时，将基于时间戳/大小执行差量比对，而非使用校验和。

YAML
default: n
example: --force

恢复全部链接选项（--link-all）

恢复所有符号链接。

默认情况下，链接的目录和文件将作为普通目录和文件恢复到 $PGDATA 中。这是因为在与原始备份环境不同的系统上，将符号链接恢复到其原始目标可能并不安全。启用此选项后，所有符号链接将按原始备份系统的方式完整恢复。

YAML
default: n
example: --link-all

链接映射选项（--link-map）

修改符号链接的目标路径。

恢复时允许修改符号链接所指向的文件或路径。当恢复目标系统的存储布局与原始备份系统不同时，此选项非常有用。

YAML
example: --link-map=pg_xlog=/data/xlog

恢复选项（--recovery-option）

在 postgresql.auto.conf 或 recovery.conf 中设置选项。

各选项的详细说明请参阅 PostgreSQL 的 服务器配置 文档（请确保选择对应的 PostgreSQL 版本）。此选项可多次使用。

对于 PostgreSQL >= 12，选项将写入 postgresql.auto.conf；对于旧版本，选项将写入 recovery.conf。

注意： restore_command 选项由 pgBackRest 自动生成，但可通过此选项覆盖。请谨慎手动指定 restore_command，因为 pgBackRest 本身就是为处理该事项而设计的。目标恢复选项（recovery_target_name、recovery_target_time 等）由 pgBackRest 自动生成，不应通过此选项手动设置。

由于 pgBackRest 写入 postgresql.auto.conf 或 recovery.conf 文件后不会自动启动 PostgreSQL，在手动重启之前始终可以编辑或检查这些文件。

YAML
example: --recovery-option=primary_conninfo=db.mydomain.com

备份集选项（--set）

要恢复的备份集。

指定要恢复的备份集。latest 表示恢复最新备份，否则请提供具体的备份名称。

YAML
default: latest
example: --set=20150131-153358F_20150131-153401I

表空间映射选项（--tablespace-map）

将表空间恢复到指定目录。

恢复时将表空间移动到新位置。当备库或已升级系统上的表空间路径与原始系统不同时，此选项非常有用。

表空间位置不存储在 pg_tablespace 中，因此可以随意移动。但不建议将表空间移动到 data_directory，这可能会引发问题。关于移动表空间的更多信息，可参考 http://www.databasesoup.com/2013/11/moving-tablespaces.html。

YAML
example: --tablespace-map=ts_01=/db/ts_01

映射全部表空间选项（--tablespace-map-all）

将所有表空间恢复到指定目录。

默认情况下，表空间将恢复到其原始位置。可通过 --tablespace-map 选项为每个表空间单独修改，但有时将所有表空间一次性重新映射到同一个新目录更为方便，在存储布局与原始备份系统不同的开发或测试环境中尤为如此。

指定的路径将作为父路径，备份中所有表空间的子目录都将在其下创建。

注意：

备份启动后创建的表空间不会被映射。如有表空间映射需求，请在创建表空间后重新进行一次备份。

YAML
example: --tablespace-map-all=/data/tablespace

目标选项（--target）

恢复目标。

当 --type 为 lsn、name、xid 或 time 时，用于定义恢复目标。若目标早于最新备份且 --type 不是 time 或 lsn，则需使用 --set 选项指定备份集。

YAML
example: --target=2015-01-30 14:15:11 EST

目标动作选项（--target-action）

到达恢复目标时的动作。

当 hot_standby=on（PostgreSQL 10 起的默认值）时，此选项统一控制集群在到达目标或归档中没有更多 WAL 时的行为。

当 PostgreSQL >= 12 且 hot_standby=off 时，pause 的行为等同于 shutdown。当 PostgreSQL < 12 且 hot_standby=off 时，pause 的行为等同于 promote。

支持以下动作：

  • pause - 到达恢复目标时暂停。
  • promote - 到达恢复目标时提升并切换时间线。
  • shutdown - 到达恢复目标时关闭服务器（PostgreSQL >= 9.5）。
YAML
default: pause
example: --target-action=promote

目标排他选项（--target-exclusive）

在到达恢复目标之前停止。

定义是否以排他方式恢复到目标（默认为包含目标），仅在 --type 为 lsn、time 或 xid 时有效。例如，当 --type=xid 且 --target=1007 时，指定 --target-exclusive 将排除事务 1007 的内容。更多信息请参阅 PostgreSQL 文档中的 recovery_target_inclusive 选项。

YAML
default: n
example: --no-target-exclusive

目标时间线选项（--target-timeline）

沿指定时间线进行恢复。

更多信息请参阅 PostgreSQL 文档中的 recovery_target_timeline。

YAML
example: --target-timeline=3

类型选项（--type）

恢复类型。

支持以下恢复类型：

  • default - 恢复到归档流的末尾。
  • immediate - 仅恢复到数据库达到一致性状态为止。
  • lsn - 恢复到 --target 中指定的 LSN（日志序列号），仅支持 PostgreSQL >= 10。
  • name - 恢复到 --target 中指定的恢复点名称。
  • xid - 恢复到 --target 中指定的事务 ID。
  • time - 恢复到 --target 中指定的时间。
  • preserve - 保留现有的 postgresql.auto.conf 或 recovery.conf 文件。
  • standby - 向 postgresql.auto.conf 或 recovery.conf 文件中添加 standby_mode=on，使集群以备库模式启动。
  • none - 不写入 postgresql.auto.conf 或 recovery.conf 文件，PostgreSQL 将尝试使用 pg_xlog/pg_wal 中已有的 WAL 段达到一致性。请预先提供所需的 WAL 段，或通过 archive-copy 设置将其包含在备份中。

警告：

应避免使用 type=none，因为恢复结束时时间线不会递增。这可能导致 PostgreSQL 尝试归档重复的 WAL 段（会被拒绝），进而耗尽磁盘空间并引发 PostgreSQL panic。此外，pg_rewind 等工具可能无法正常工作，甚至可能造成数据损坏。

请注意，离线备份的默认恢复 type 为 none，因为当 wal_level=minimal 时无法进行时间点恢复。若明确设置了 type，则以该设置为准，因为只要 wal_level > minimal，即可从离线备份执行时间点恢复。

YAML
default: default
example: --type=xid

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: y
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于选项配置，每个操作可能占用额外内存，例如 gz 压缩可能额外使用 256KiB 内存。

允许值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

pgBackRest 命令选项（--cmd）

pgBackRest 命令。

pgBackRest 在某些情况下需要生成命令字符串，例如 restore 命令生成 restore_command 设置时。此时将使用运行当前 pgBackRest 进程的命令，除非通过 --cmd 选项另行指定。

注意：

对 pgBackRest 命令进行封装可能导致不可预期的行为，不建议这样做。

YAML
default: [path of executed pgbackrest binary]
example: --cmd=/var/lib/pgsql/bin/pgbackrest_wrapper.sh

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

当需要使用其他 SSH 客户端，或 ssh 命令不在 $PATH 中时，使用此选项指定特定的 SSH 客户端命令。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，设置网络传输的压缩级别。压缩用于减少网络流量。当 compress-type 不等于 none 时，compress-level-network 设置将被忽略，改用 compress-level，以避免文件被压缩两次。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项指定与默认路径不同的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

该路径下扩展名为 .conf 的配置文件将与 pgBackRest 主配置文件合并，形成完整的配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置用于覆盖 --config 和 --config-include-path 选项的默认基础路径，前提是这两个选项未在命令行中被显式指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

Delta 选项（--delta）

使用校验和进行恢复或备份。

恢复时，默认要求 PostgreSQL 数据目录和表空间目录已存在且为空。启用此选项后，将使用校验和执行差量恢复。

备份时，启用此选项将使用校验和而非时间戳来判断是否需要复制文件。

YAML
default: n
example: --delta

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读/写操作的超时时间（秒）。

请注意，整个读/写操作不必在此超时时间内完成，但必须有 一定 进展，哪怕只传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件存储路径。

pgBackRest 将锁文件存储在此路径下，以防止并发运行相互冲突的操作。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器分配给该进程的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。在大多数情况下，进程没有权限提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

最大进程数选项（--process-max）

压缩/传输使用的最大进程数。

每个进程将执行压缩和传输以加快命令运行速度，但不要将 process-max 设置过高，以免影响数据库性能。

YAML
default: 1
allowed: [1, 999]
example: --process-max=4

协议超时选项（--protocol-timeout）

协议超时时间。

本地或远程进程在协议层等待接收新消息的超时时间（秒）。此设置可防止进程无限期等待消息。

注意： --protocol-timeout 选项的值必须大于 --db-timeout 选项的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用保活（keep-alive）。

在套接字连接上启用保活消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza。

stanza（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）是对一个 PostgreSQL 数据库集群的配置，定义了集群所在位置、备份方式、归档选项等。大多数数据库服务器只有一个 PostgreSQL 集群，因此只有一个 stanza；备份服务器则为每个需要备份的集群各配置一个 stanza。

stanza 命名时容易直接使用主集群名称，但更好的做法是使用描述该集群中数据库用途的名称。由于 stanza 名称同时用于主库和所有副本，选择一个描述集群实际功能的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

保活计数。

指定在连接被判定为失效之前，可以丢失的 TCP 保活消息数量。

此选项在支持 TCP_KEEPCNT 套接字选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

保活空闲时间。

指定在无网络活动持续多少秒后，操作系统应发送 TCP 保活消息。

此选项在支持 TCP_KEEPIDLE 套接字选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

保活间隔时间。

指定未收到确认的 TCP 保活消息在多少秒后应重新发送。

此选项在支持 TCP_KEEPINTVL 套接字选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许的 TLSv1.2 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整接受的加密套件。示例中的配置是合理的选择，除非有特定安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许的 TLSv1.3 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整接受的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试信息、详情、信息、警告和错误
  • trace - 记录跟踪信息（非常详细的调试信息）、调试信息、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试信息、详情、信息、警告和错误
  • trace - 记录跟踪信息（非常详细的调试信息）、调试信息、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

标准错误输出日志级别。

指定哪些日志级别输出到 stderr 而非 stdout（由 --log-level-console 指定）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试信息、详情、信息、警告和错误
  • trace - 记录跟踪信息（非常详细的调试信息）、调试信息、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件存储路径。

pgBackRest 将日志文件存储在此路径下。请注意，若 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为当前进程创建的所有子进程启用文件日志记录，日志级别使用 --log-level-file 指定的值。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

启用日志时间戳。

在控制台和文件日志中启用时间戳。此选项在生成文档等特殊场景下会被禁用。

YAML
default: y
example: --no-log-timestamp

维护者选项

强制指定 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用指定的 PostgreSQL 版本，而非通过读取 pg_control 或 WAL 头部自动检测到的版本。此选项主要用于 PostgreSQL 分支版本或开发版本，因为这些版本中上述值可能与正式发布版本不同。PostgreSQL 通过 server_version_num 报告的版本必须与强制指定的版本一致。

警告：

使用此选项时需谨慎，因为 pg_control 和 WAL 头部仍将按指定版本的预期格式读取，即来自官方开源 PostgreSQL 版本的格式。若分支版本或开发版本更改了 pgBackRest 所依赖字段的格式，将导致不可预期的行为。一般而言，只有当分支在标准 PostgreSQL 成员 之后 添加所有自定义结构成员时，此选项才能按预期工作。

YAML
example: --pg-version-force=15

仓库选项

指定仓库选项（--repo）

设置仓库。

指定命令操作的目标仓库。

例如，可使用此选项从特定仓库执行恢复，而非让 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在容器根目录，但通常建议指定一个前缀（如 /repo），以便日志和其他 Azure 生成的内容也可以存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机并在 URI 中添加账户前缀。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

用于加密仓库的加密算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

请注意，即使仓库类型（如 S3）本身支持加密，加密也始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定一个前缀（如 /repo），以便日志和其他 GCS 生成的内容也可以存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点。可更新为使用本地 GCS 服务器或备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号自动授权。
  • service - 使用本地存储的密钥文件中的服务账号。
  • token - 用于本地测试，如 fakegcs。

当 repo-gcs-key-type=service 时，凭据将在身份验证令牌续期时重新加载。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费归属的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

备份和归档到本地挂载的文件系统时，无需此设置。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机 pgBackRest 命令。

仅当本地主机与仓库主机上的 pgBackRest 命令路径不同时才需要设置。若未定义，仓库主机命令将与本地命令相同。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的位置。仅当仓库主机上的配置文件与本地配置文件位于不同路径时才需要此设置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地配置包含路径不同时才需要此设置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地配置路径不同时才需要此设置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

与客户端证书配合使用，证明证书由所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

设置了 --repo-host 时的仓库主机端口。

使用此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，--repo-host-port 没有默认值，端口将使用 --cmd-ssh 指定命令所配置的端口。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

设置了 --repo-host 时的仓库主机用户。

定义在仓库主机上执行操作所使用的用户。建议不要使用 postgres 用户，而改用 pgbackrest 等专用用户。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其对仓库具有读权限，同时避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的位置。

提前估算所需空间可能比较困难。建议先进行几次备份，记录不同类型备份（全量/增量/差异）的大小，并测量每天产生的 WAL 量。这将给出大致的空间需求，但实际需求会随数据库的演变而变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定一个前缀（如 /repo），以便日志和其他 AWS 生成的内容也可以存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义或测试配置，可使用 --repo-storage-ca-file、--repo-storage-ca-path、--repo-storage-host、--repo-storage-port 和 --repo-storage-verify-tls 选项。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务器端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶时所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭据的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机并在 URI 中添加存储桶前缀。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

包含仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

SFTP 仓库主机指纹的生成方式应与 --repo-sftp-host-key-hash-type 匹配。通过以下命令生成指纹：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录中。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下 SFTP 主机密钥检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts 文件，且拒绝连接主机密钥已更改或不在已知主机文件中的主机。此选项强制用户手动添加所有新主机。
  • accept-new - pgBackRest 将自动将新主机密钥添加到用户的已知主机文件，但不允许连接主机密钥已更改的主机。
  • fingerprint - pgBackRest 将根据 --repo-sftp-host-fingerprint 选项指定的指纹来验证主机密钥。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明在 SSH 启动时用于计算远程系统主机密钥摘要的哈希类型。较新版本的 libssh2 除支持 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

用于存储仓库的主机上的用户名。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

身份验证期间用于搜索 SFTP 主机匹配项的已知主机文件。若未指定，pgBackRest 将默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将在这些路径中搜索匹配项。文件路径必须是完整路径或以波浪号开头的路径。可多次传入 --repo-sftp-known-host 选项以指定多个已知主机文件。使用已知主机文件检查时，不得同时指定 --repo-sftp-host-fingerprint。另请参阅 --repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于身份验证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于身份验证的 SFTP 公钥文件。针对 OpenSSL 编译时为可选，针对其他库编译时为必填。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

为存储（如 S3、Azure）证书使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file, repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

为存储（如 S3、Azure）证书使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path, repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机，通常用于测试目的。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host, repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接到存储（如 S3、Azure）端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port, repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库为对象存储（如 S3）时，指定添加到对象上的标签。可重复使用此选项添加多个标签。

pgBackRest 不提供修改这些标签的功能，因此请在运行 stanza-create 之前确保标签已正确设置，以保证整个仓库的标签统一。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

对象存储（如 S3）允许在文件过大无法存入内存时分块上传。即使文件可以存入内存，限制单次上传占用的内存量也更为高效。

较大的块大小通常可以带来更好的性能，因为它减少了上传请求数量，允许在单个请求中上传更多数据而非分块处理。其缺点是内存占用更高——由于块缓冲区必须按进程分配，--process-max 值越大，整体内存消耗越多。

请注意，有效的块大小因存储类型和平台而异。例如，AWS S3 的最小块大小为 5MiB。各存储类型对块大小的术语也不同，因此搜索最小/最大值时，AWS S3 请使用"part size"，GCS 请使用"chunk size"，Azure 请使用"block size"。

如果文件大于 1GiB（PostgreSQL 默认创建的最大文件大小），块大小将逐步增加到允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用存储（如 S3、Azure）服务器的 TLS 证书验证。仅在测试场景或使用自签名证书时才应禁用验证。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls, repo-s3-verify-ssl, repo-s3-verify-tls

仓库目标时间选项（--repo-target-time）

仓库目标时间。

定义命令读取版本化存储上的仓库所使用的时间点。这允许命令读取某个历史时间点的仓库状态，以便恢复因用户误操作或恶意软件而被删除或损坏的数据。

S3、GCS 和 Azure 均支持版本化存储，但通常默认不启用。除启用版本控制外，还可以考虑为 S3 启用对象锁定，为 GCS 或 Azure 启用软删除。

指定 --repo-target-time 时，还必须提供 --repo 选项。并非所有仓库类型都支持版本控制，通常针对单个仓库进行恢复更为合理。

请注意，与存储时间戳的比较使用 <= 关系，且提供的时间戳中的毫秒部分将被截断。

YAML
example: --repo-target-time=2024-08-08 12:12:12+00

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud Storage
  • posix - 符合 POSIX 标准的文件系统
  • s3 - AWS 简单存储服务
  • sftp - 安全文件传输协议

使用 NFS 挂载作为 posix 仓库时，适用规则与 PostgreSQL 文档中描述的相同：创建数据库集群 - 文件系统。

YAML
default: posix
example: --repo1-type=cifs

Stanza 选项

PostgreSQL 路径选项（--pg-path）

PostgreSQL 数据目录。

此路径应与 PostgreSQL 报告的 data_directory 一致。尽管可以从多处读取此值，但在恢复或离线备份场景中这些来源可能不可用，因此建议在配置文件中明确设置。

--pg-path 选项在每次在线备份时都会与 PostgreSQL 报告的值进行验证，因此应始终保持最新。

YAML
example: --pg1-path=/data/db

已弃用名称：db-path

4.12 - 服务器命令（server）

pgBackRest server 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: server

pgBackRest 服务器允许在不使用 SSH 协议的情况下访问远程主机。

命令选项

TLS 服务器地址选项（--tls-server-address）

TLS 服务器地址。

服务器监听客户端请求的 IP 地址。

YAML
default: localhost
example: --tls-server-address=*

TLS 服务器授权客户端选项（--tls-server-auth）

TLS 服务器授权客户端。

服务器通过验证客户端证书，并将其证书 CN（Common Name，通用名称）与 tls-server-auth 选项所配置的列表进行比对，来完成对客户端的授权。

可通过向 tls-server-auth 选项传入逗号分隔的列表，授权某个客户端 CN 访问多个 stanza（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）；也可通过指定 tls-server-auth=client-cn=* 授权其访问所有 stanza。客户端 CN 不支持通配符。

YAML
example: --tls-server-auth=client-cn=stanza1,stanza2

TLS 服务器证书颁发机构选项（--tls-server-ca-file）

TLS 服务器证书颁发机构。

用于验证客户端证书是否由受信任的证书颁发机构签发。

YAML
example: --tls-server-ca-file=/path/to/server.ca

TLS 服务器证书选项（--tls-server-cert-file）

TLS 服务器证书文件。

发送给客户端以证明服务器身份的证书。

YAML
example: --tls-server-cert-file=/path/to/server.crt

TLS 服务器密钥选项（--tls-server-key-file）

TLS 服务器密钥文件。

用于证明服务器证书归属的私钥。

YAML
example: --tls-server-key-file=/path/to/server.key

TLS 服务器端口选项（--tls-server-port）

TLS 服务器端口。

服务器监听客户端请求的端口。

YAML
default: 8432
allowed: [1, 65535]
example: --tls-server-port=8000

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于各选项配置，每个操作可能还会额外占用内存，例如 gz 压缩可能额外使用 256KiB 内存。

允许的值为：16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

配置文件选项（--config）

pgBackRest 配置文件。

指定与默认值不同的配置文件路径。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

该路径下扩展名为 .conf 的配置文件将与 pgBackRest 主配置文件合并，最终形成一个完整的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此选项覆盖 --config 和 --config-include-path 的默认基础路径，但仅在这两个选项未在命令行中明确指定时生效。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读写操作的超时时间，单位为秒。

注意：整个读写操作不必在此超时时间内完成，但 必须 有所进展，哪怕只传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器赋予该进程的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。普通进程在大多数情况下无权提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时时间。

本地或远程进程在协议层等待新消息的超时时间，单位为秒。此设置可防止进程无限期阻塞等待消息。

注意： protocol-timeout 选项的值必须大于 db-timeout 选项的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用保活。

在 socket 连接上启用保活消息。

YAML
default: y
example: --no-sck-keep-alive

TCP 保活计数选项（--tcp-keep-alive-count）

保活计数。

连接被判定为断开之前，允许丢失的 TCP 保活消息数量。

此选项仅在支持 TCP_KEEPCNT socket 选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

保活空闲时间。

无网络活动持续多少秒后，操作系统开始发送 TCP 保活消息。

此选项仅在支持 TCP_KEEPIDLE socket 选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

保活间隔时间。

未被确认的 TCP 保活消息重新发送前的等待秒数。

此选项仅在支持 TCP_KEEPINTVL socket 选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密，连接到对象存储（如 S3）时默认也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。示例中的配置是合理的选择，除非有特殊安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密，连接到对象存储（如 S3）时默认也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录追踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录追踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别输出到 stderr 而非 stdout（由 log-level-console 控制）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录追踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件写入此路径。若 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中启用时间戳。在某些特殊情况下（如生成文档时），此选项会被禁用。

YAML
default: y
example: --no-log-timestamp

4.13 - 服务器心跳命令（server-ping）

pgBackRest server-ping 命令选项与行为参考。

原始页面： pgBackRest Command Docs: server-ping

向 pgBackRest TLS 服务器发送 ping，确认其正在接受连接。此命令仅作为存活性检查，不进行身份验证。

若命令行中未指定主机，则使用 tls-server-host 选项的值。

命令选项

TLS 服务器地址选项（--tls-server-address）

TLS 服务器地址。

服务器监听客户端请求的 IP 地址。

YAML
default: localhost
example: --tls-server-address=*

TLS 服务器端口选项（--tls-server-port）

TLS 服务器端口。

服务器监听客户端请求的端口号。

YAML
default: 8432
allowed: [1, 65535]
example: --tls-server-port=8000

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于具体选项，每个操作可能会额外消耗内存，例如 gz 压缩可能额外占用 256KiB 内存。

允许的值为：16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项可以指定非默认的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

该路径下扩展名为 .conf 的配置文件将与主配置文件合并，形成统一的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置用于覆盖 --config 和 --config-include-path 选项的默认基础路径，但若这两个选项已在命令行中显式指定，则此设置不生效。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读写操作的超时时间（单位：秒）。

注意，整个读写操作无需在超时时间内全部完成，但必须有 一定 进展，哪怕只传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器为进程分配的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

保活选项（--sck-keep-alive）

启用 keep-alive。

在 socket 连接上启用 keep-alive 消息。

YAML
default: y
example: --no-sck-keep-alive

TCP 保活计数选项（--tcp-keep-alive-count）

keep-alive 探测次数。

指定在判定连接已断开之前，允许丢失的 TCP keep-alive 消息数量。

此选项仅在支持 TCP_KEEPCNT socket 选项的系统上可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

keep-alive 空闲时间。

指定在多长时间无网络活动后（单位：秒），操作系统开始发送 TCP keep-alive 消息。

此选项仅在支持 TCP_KEEPIDLE socket 选项的系统上可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

keep-alive 重传间隔时间。

指定未收到确认的 TCP keep-alive 消息在多长时间后重传（单位：秒）。

此选项仅在支持 TCP_KEEPINTVL socket 选项的系统上可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许的加密套件。除非有特定的安全要求，否则示例值是一个合理的选择。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志的输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志的输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 的日志输出级别。

指定哪些日志级别将输出到 stderr 而非 stdout（后者由 log-level-console 控制）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件写入此路径。注意，若 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中启用时间戳输出。某些特殊场景（如生成文档时）会禁用此选项。

YAML
default: y
example: --no-log-timestamp

4.14 - Stanza 创建命令（stanza-create）

pgBackRest stanza-create 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: stanza-create

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

更多信息和示例，请参见 创建 Stanza。

命令选项

在线选项（--online）

在在线集群上创建 stanza。

指定 --no-online 可阻止 pgBackRest 在创建 stanza 时连接 PostgreSQL。

YAML
default: y
example: --no-online

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

该缓冲区用于复制、压缩、加密等操作。实际使用的缓冲区数量取决于所启用的选项，每个操作还可能额外占用内存，例如 gz 压缩可能额外使用约 256KiB 内存。

允许值为：16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

需要使用特定 SSH 客户端，或 ssh 命令不在 $PATH 中时，可通过此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，通过此选项设置网络传输的压缩级别，以降低网络流量。若 compress-type 不等于 none，则忽略 compress-level-network，转而使用 compress-level，避免对文件进行二次压缩。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

指定与默认值不同的配置文件路径。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

该路径下以 .conf 为扩展名的配置文件将与主配置文件合并，形成完整配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

用于覆盖 --config 和 --config-include-path 的默认基础路径；若这两个选项已在命令行中显式指定，则此设置不生效。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

数据库超时选项（--db-timeout）

数据库查询超时时间。

设置对数据库执行查询的超时时长（单位：秒）。这包括备份启动和停止函数——两者各自可能需要较长时间。因此，除非明确知道这些函数会很快返回（例如已设置 start-fast=y，且备份期间数据库集群不会产生大量 WAL 段），否则应将此超时值设置得较高。

注意： db-timeout 的值必须小于 protocol-timeout。

YAML
default: 30m
allowed: [100ms, 7d]
example: --db-timeout=600

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读/写操作的超时时长（单位：秒）。

注意，整个读/写操作无需在此超时时间内全部完成，但必须持续有进展，哪怕每次仅传输一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 将锁文件存放于此路径，用于防止相互冲突的操作并发执行。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器为该进程分配的优先级（即 niceness 值）。正值降低优先级，负值提升优先级。普通进程通常没有权限提升自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时时间。

设置本地或远程进程在协议层等待新消息的超时时长（单位：秒），防止进程无限期等待。

注意： protocol-timeout 的值必须大于 db-timeout。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用 keep-alive。

在套接字连接上启用 keep-alive 消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza。

stanza 是对一个 PostgreSQL 数据库集群的备份配置，定义了集群的位置、备份方式及归档选项等内容。大多数数据库服务器只有一个 PostgreSQL 集群，因此只需配置一个 stanza；备份服务器则需要为每个待备份的数据库集群各配置一个 stanza。

命名 stanza 时，用主集群名称命名看似直观，但更好的做法是用名称描述集群中存储的数据库。由于 stanza 名称同时用于主库和所有副本，选用描述集群实际用途的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

TCP 保活计数。

指定在连接被判定为断开之前，允许丢失的 TCP 保活消息数量。

此选项仅在系统支持 TCP_KEEPCNT 套接字选项时可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

TCP 保活空闲时间。

指定网络空闲多少秒后，操作系统应开始发送 TCP 保活消息。

此选项仅在系统支持 TCP_KEEPIDLE 套接字选项时可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

TCP 保活间隔时间。

指定在未收到确认的情况下，TCP 保活消息的重传间隔（单位：秒）。

此选项仅在系统支持 TCP_KEEPINTVL 套接字选项时可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密，与对象存储（如 S3）的连接默认也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。示例值是合理的选择，除非有特殊安全需求。未设置时（默认行为），使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密，与对象存储（如 S3）的连接默认也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。未设置时（默认行为），使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志的输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详细信息、信息、警告和错误
  • debug - 记录调试、详细信息、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志的输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详细信息、信息、警告和错误
  • debug - 记录调试、详细信息、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 的日志输出级别。

指定哪些日志级别输出到 stderr 而非 stdout（由 log-level-console 控制）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详细信息、信息、警告和错误
  • debug - 记录调试、详细信息、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件存放于此路径。注意，若 log-level-file=off，则无需配置此选项。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为当前进程创建的子进程启用文件日志，使用 log-level-file 指定的日志级别。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

启用日志时间戳。

在控制台和文件日志中启用时间戳。该选项在生成文档等特殊场景下会被禁用。

YAML
default: y
example: --no-log-timestamp

维护者选项

强制指定 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用指定的 PostgreSQL 版本，而非通过读取 pg_control 或 WAL 头部自动检测到的版本。此选项主要用于 PostgreSQL 分支版本或开发版本——这些版本中的相关值可能与发行版本不同。PostgreSQL 通过 server_version_num 报告的版本必须与强制指定的版本一致。

警告：

使用此选项须谨慎，因为 pg_control 和 WAL 头部仍将按照所指定版本对应的官方 PostgreSQL 格式读取。若分支版本或开发版本修改了 pgBackRest 所依赖字段的格式，将导致不可预期的行为。通常，只有当分支在标准 PostgreSQL 结构成员 之后 追加自定义成员时，此选项才能正常工作。

YAML
example: --pg-version-force=15

仓库选项

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

设置 repo-path=/ 可将 pgBackRest 仓库存储在容器根目录下，但通常建议指定一个前缀路径（如 /repo），以便日志等 Azure 生成的内容也能存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中前置账户名。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

仓库加密算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥的高级加密标准

注意，即使仓库类型（如 S3）本身支持加密，pgBackRest 的加密操作始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录下，但通常建议指定一个前缀路径（如 /repo），以便日志等 GCS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

连接存储服务的端点，可修改为本地 GCS 服务器地址或其他备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号自动授权。
  • service - 使用本地存储的服务账号密钥文件。
  • token - 用于本地测试，例如 fakegcs。

当 repo-gcs-key-type=service 时，认证令牌续期时将重新加载凭据。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费归属的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时使用的仓库主机。

若备份和归档存储在本地挂载的文件系统上，则无需配置此选项。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时，使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时，使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机，用于验证客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令路径。

仅当本地主机与仓库主机上的 pgBackRest 命令路径不同时才需要配置。若未定义，仓库主机命令与本地命令相同。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的位置。仅当仓库主机上的配置文件路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由其所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

仓库主机端口。

设置 repo-host 时，通过此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口以 cmd-ssh 所指定命令的配置为准。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（SSH）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

仓库主机用户。

设置 repo-host 时，定义在仓库主机上执行操作所使用的用户。建议使用专用用户（如 pgbackrest）而非 postgres。若 PostgreSQL 也运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其对仓库具有读取权限，同时避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存放备份文件和归档 WAL 段的位置。

提前估算所需空间可能较为困难。建议先执行几次备份，记录不同备份类型（全量/增量/差异）的大小，并测量每日产生的 WAL 量，以此大致了解所需空间。随着数据库的增长，需求也会随时间变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录下，但通常建议指定一个前缀路径（如 /repo），以便日志等 AWS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域对应。

对于自定义或测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 选项可能会有所帮助。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶时所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭据的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中前置存储桶名。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

存储仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

主机指纹的生成方式应与 repo-sftp-host-key-hash-type 一致。可通过以下命令生成：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥文件通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts，并拒绝连接主机密钥已变更或在已知主机文件中不存在的主机。此选项要求用户手动添加所有新主机。
  • accept-new - pgBackRest 将自动将新主机密钥添加到已知主机文件，但不允许连接主机密钥已变更的主机。
  • fingerprint - pgBackRest 将对照 repo-sftp-host-fingerprint 选项指定的指纹验证主机密钥。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明 SSH 启动时用于计算远程系统主机密钥摘要的哈希类型。较新版本的 libssh2 除支持 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

存储仓库的主机上所使用的用户。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

用于在认证过程中查找 SFTP 主机匹配条目的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将在这些路径中查找匹配项；文件路径必须是绝对路径或以波浪号开头的路径。此选项可多次传入，以指定多个已知主机文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参见 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件。编译时链接了 OpenSSL 时为可选项；链接了其他库时为必填项。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接存储服务（如 S3、Azure）时，使用非系统默认的 CA 文件验证证书。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接存储服务（如 S3、Azure）时，使用非系统默认的 CA 路径验证证书。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储服务（如 S3、Azure）端点以外的主机，通常用于测试场景。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储服务（如 S3、Azure）端点或指定主机时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

指定当仓库为对象存储（如 S3）时，附加到对象上的标签。可重复使用此选项以添加多个标签。

pgBackRest 没有提供修改这些标签的机制，因此请在运行 stanza-create 之前确认标签设置正确，以保证整个仓库的标签一致。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

当文件过大无法全部载入内存时，对象存储（如 S3）支持以分块方式上传。即使文件可以全部载入内存，限制上传所用内存也更为高效。

较大的分块大小通常能提升性能，因为它可减少上传请求次数，并允许在单次请求中传输更多数据。代价是内存占用更高——分块缓冲区按进程分配，process-max 值越大，总体内存消耗也越多。

注意，有效的分块大小因存储类型和平台而异。例如，AWS S3 的最小分块大小为 5MiB。各存储类型对分块大小的术语不同：AWS S3 称之为"part size"，GCS 称之为"chunk size"，Azure 称之为"block size"。

若文件大于 1GiB（PostgreSQL 默认创建的最大文件大小），分块大小将逐步增加至允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用对存储服务（如 S3、Azure）服务器 TLS 证书的验证。禁用验证仅应用于测试环境或使用自签名证书的场景。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob Storage 服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud Storage
  • posix - 符合 POSIX 规范的文件系统
  • s3 - AWS Simple Storage Service
  • sftp - 安全文件传输协议

以 NFS 挂载作为 posix 类型仓库时，适用于 pgBackRest 的规则与 PostgreSQL 文档中描述的规则相同，详见 Creating a Database Cluster - File Systems。

YAML
default: posix
example: --repo1-type=cifs

Stanza 选项

PostgreSQL 数据库选项（--pg-database）

PostgreSQL 数据库名称。

连接 PostgreSQL 时使用的数据库名称。默认值通常可正常使用，但某些安装环境中可能不包含此数据库。

注意，出于历史原因，PGDATABASE 环境变量的设置将被忽略。

YAML
default: postgres
example: --pg1-database=backupdb

PostgreSQL 主机选项（--pg-host）

远程操作时使用的 PostgreSQL 主机。

用于 PostgreSQL 主机与仓库主机分离的备份场景。

YAML
example: --pg1-host=db.domain.com

已弃用名称：db-host

PostgreSQL 主机证书颁发机构文件选项（--pg-host-ca-file）

PostgreSQL 主机证书颁发机构文件。

连接 PostgreSQL 主机时，使用非系统默认的 CA 文件。

YAML
example: --pg1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

PostgreSQL 主机证书颁发机构路径选项（--pg-host-ca-path）

PostgreSQL 主机证书颁发机构路径。

连接 PostgreSQL 主机时，使用非系统默认的 CA 路径。

YAML
example: --pg1-host-ca-path=/etc/pki/tls/certs

PostgreSQL 主机证书文件选项（--pg-host-cert-file）

PostgreSQL 主机证书文件。

发送给 PostgreSQL 主机，用于验证客户端身份。

YAML
example: --pg1-host-cert-file=/path/to/client.crt

PostgreSQL 主机命令选项（--pg-host-cmd）

PostgreSQL 主机上的 pgBackRest 命令路径。

仅当本地主机与 PostgreSQL 主机上的 pgBackRest 命令路径不同时才需要配置。若未定义，PostgreSQL 主机命令与本地命令相同。

YAML
default: [path of executed pgbackrest binary]
example: --pg1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：db-cmd

PostgreSQL 主机配置文件选项（--pg-host-config）

pgBackRest 数据库主机配置文件。

设置 PostgreSQL 主机上配置文件的位置。仅当 PostgreSQL 主机上的配置文件路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --pg1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：db-config

PostgreSQL 主机配置包含路径选项（--pg-host-config-include-path）

pgBackRest 数据库主机配置包含路径。

设置 PostgreSQL 主机上配置包含路径的位置。仅当 PostgreSQL 主机上的配置包含路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --pg1-host-config-include-path=/conf/pgbackrest/conf.d

PostgreSQL 主机配置路径选项（--pg-host-config-path）

pgBackRest 数据库主机配置路径。

设置 PostgreSQL 主机上配置路径的位置。仅当 PostgreSQL 主机上的配置路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --pg1-host-config-path=/conf/pgbackrest

PostgreSQL 主机密钥文件选项（--pg-host-key-file）

PostgreSQL 主机密钥文件。

用于证明客户端证书由其所有者发送。

YAML
example: --pg1-host-key-file=/path/to/client.key

PostgreSQL 主机端口选项（--pg-host-port）

PostgreSQL 主机端口。

设置 pg-host 时，通过此选项为 PostgreSQL 主机协议指定非默认端口。

注意： 当 pg-host-type=ssh 时，pg-host-port 没有默认值，端口以 cmd-ssh 所指定命令的配置为准。

YAML
default (depending on pg-host-type):
   tls - 8432

allowed: [0, 65535]
example: --pg1-host-port=25

已弃用名称：db-ssh-port

PostgreSQL 主机协议类型选项（--pg-host-type）

PostgreSQL 主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（SSH）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --pg1-host-type=tls

PostgreSQL 主机用户选项（--pg-host-user）

PostgreSQL 主机登录用户。

设置 pg-host 时，该用户同时拥有远程 pgBackRest 进程，并负责发起与 PostgreSQL 的连接。为确保其正常工作，该用户通常应为 PostgreSQL 数据库集群的所有者，默认为 postgres。

YAML
default: postgres
example: --pg1-host-user=db_owner

已弃用名称：db-user

PostgreSQL 路径选项（--pg-path）

PostgreSQL 数据目录。

此路径应与 PostgreSQL 报告的 data_directory 一致。尽管该值可从多处获取，但为了在恢复或离线备份场景下这些资源不可用时仍能正常工作，建议明确配置此项。

pg-path 在每次在线备份时都会与 PostgreSQL 报告的值进行核对，应始终保持最新。

YAML
example: --pg1-path=/data/db

已弃用名称：db-path

PostgreSQL 端口选项（--pg-port）

PostgreSQL 端口。

PostgreSQL 运行的端口。大多数 PostgreSQL 集群使用默认端口，通常无需指定此选项。

YAML
default: 5432
allowed: [0, 65535]
example: --pg1-port=6543

已弃用名称：db-port

PostgreSQL Socket 路径选项（--pg-socket-path）

PostgreSQL Unix 套接字路径。

PostgreSQL 启动时指定的 Unix 套接字目录。pgBackRest 会自动查找操作系统标准位置，通常无需配置此选项，除非通过 postgresql.conf 中的 unix_socket_directories 显式修改了套接字目录。

YAML
example: --pg1-socket-path=/var/run/postgresql

已弃用名称：db-socket-path

PostgreSQL 数据库用户选项（--pg-user）

PostgreSQL 数据库用户。

连接 PostgreSQL 时使用的数据库用户名。若未指定，pgBackRest 将使用本地操作系统用户或 PGUSER 环境变量。

YAML
example: --pg1-user=backupuser

4.15 - Stanza 删除命令（stanza-delete）

pgBackRest stanza-delete 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: stanza-delete

stanza-delete 命令用于删除仓库中与指定 stanza 关联的所有数据。stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称。

警告：

此命令会永久删除指定 stanza 在 pgBackRest 仓库中的所有备份和归档数据，请谨慎使用。

删除 stanza 的步骤如下：

  • 停止与该 stanza 关联的 PostgreSQL 集群（或使用 --force 选项强制删除）。
  • 在执行 stanza-delete 命令的主机上先运行 stop 命令。
  • 运行 stanza-delete 命令。

命令执行成功后，需自行从所有 pgBackRest 配置文件和/或环境变量中移除该 stanza 的相关配置。

每次只能从一个仓库中删除 stanza。若需从多个仓库中删除，请使用 --repo 选项逐一指定每个仓库，分别执行 stanza-delete 命令。

命令选项

强制删除选项（--force）

强制删除 stanza。

若该 stanza 对应的 PostgreSQL 实例仍在运行，可使用此选项强制从仓库中删除该 stanza。

YAML
default: n
example: --no-force

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

此选项设置用于复制、压缩、加密及其他操作的缓冲区大小。实际使用的缓冲区数量取决于具体操作，部分操作可能额外占用内存，例如 gz 压缩可能额外占用 256KiB。

允许的值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

如需使用特定 SSH 客户端，或 ssh 命令不在 $PATH 中，可通过此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，此选项控制网络传输的压缩级别，用于减少网络流量。若 compress-type 不为 none，则忽略 compress-level-network，转而使用 compress-level，确保文件只被压缩一次。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

指定与默认路径不同的配置文件路径。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

该路径下扩展名为 .conf 的配置文件将与 pgBackRest 主配置文件合并，最终形成完整配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置用于覆盖 --config 和 --config-include-path 的默认基础路径，前提是这两个选项未在命令行中明确指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

数据库超时选项（--db-timeout）

数据库查询超时时间。

设置针对数据库查询的超时时间（秒），包括备份启动/停止函数。由于这些函数可能耗时较长，建议将此值设置得宽裕一些——除非确认已设置 start-fast=y，且数据库集群在备份期间不会产生大量 WAL 段。

注意： db-timeout 的值必须小于 protocol-timeout 的值。

YAML
default: 30m
allowed: [100ms, 7d]
example: --db-timeout=600

I/O 超时选项（--io-timeout）

I/O 超时时间。

用于连接及读/写操作的超时时间（秒）。

注意，整个读/写操作无需在此超时时间内完成，但必须有 一定 进展，哪怕只传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 将锁文件写入此路径，以防止并发执行相互冲突的操作。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器赋予该进程的 nice 值。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提升自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时时间。

设置本地或远程进程在协议层等待新消息的超时时间（秒），防止进程无限期挂起。

注意： protocol-timeout 的值必须大于 db-timeout 的值。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用 keep-alive。

在套接字连接上启用 keep-alive 消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza。

stanza 是对一个 PostgreSQL 数据库集群的备份配置，定义了集群位置、备份方式、归档选项等。大多数数据库主机只有一个 PostgreSQL 集群，因此只有一个 stanza；备份主机则会为每个需要备份的数据库集群各配置一个 stanza。

命名建议：相比使用本地集群名称（如 main 或 prod），更好的做法是根据集群中实际存放的数据来命名 stanza（如 app 或 dw），因为 stanza 名称同时用于主库和所有副本。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

Keep-alive 计数。

指定在判定连接已断开之前，允许丢失的 TCP keep-alive 消息数量。

此选项仅在系统支持 TCP_KEEPCNT 套接字选项时可用。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

Keep-alive 空闲时间。

指定在没有网络活动多少秒后，操作系统应发送 TCP keep-alive 消息。

此选项仅在系统支持 TCP_KEEPIDLE 套接字选项时可用。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

Keep-alive 间隔时间。

指定未收到确认的 TCP keep-alive 消息在多少秒后重新发送。

此选项仅在系统支持 TCP_KEEPINTVL 套接字选项时可用。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密，默认情况下与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。示例值是一个合理的选择，除非有特定安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密，默认情况下与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试信息、详情、信息、警告和错误
  • trace - 记录追踪信息（非常详细的调试）、调试信息、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试信息、详情、信息、警告和错误
  • trace - 记录追踪信息（非常详细的调试）、调试信息、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别输出到 stderr 而非 stdout（由 log-level-console 控制）。输出到 stderr 的日志不含时间戳和进程信息。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试信息、详情、信息、警告和错误
  • trace - 记录追踪信息（非常详细的调试）、调试信息、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件写入此路径。注意，若 log-level-file=off，则无需配置此选项。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为当前进程创建的所有子进程启用文件日志，日志级别由 log-level-file 控制。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

启用日志时间戳。

在控制台和文件日志中启用时间戳。此选项在特殊情况下（如生成文档时）会被禁用。

YAML
default: y
example: --no-log-timestamp

维护者选项

强制指定 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用此选项指定的版本，替代从 pg_control 或 WAL 头部自动检测的版本。此选项主要用于 PostgreSQL 分支版本或开发版本——这些版本中的相关值可能与发布版本不同。PostgreSQL 通过 server_version_num 上报的版本号必须与强制指定的版本一致。

警告：

使用此选项需谨慎。pg_control 和 WAL 头部仍会按照指定版本的预期格式（即官方开源 PostgreSQL 的格式）读取。若分支版本或开发版本更改了 pgBackRest 所依赖字段的格式，将导致不可预期的行为。通常，只有当分支将所有自定义结构成员添加在标准 PostgreSQL 成员 之后 时，此选项才能按预期工作。

YAML
example: --pg-version-force=15

仓库选项

指定仓库选项（--repo）

设置仓库。

指定命令操作的目标仓库。例如，可使用此选项从特定仓库执行恢复，而非由 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在容器根目录，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 Azure 生成的内容也可存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管身份自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机并在 URI 前添加账户名。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

仓库加密算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

注意，即使仓库类型（如 S3）本身支持加密，pgBackRest 的加密也始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 GCS 生成的内容也可存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点，可更改为本地 GCS 服务器或其他备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号自动授权。
  • service - 使用本地存储的密钥文件中的服务账号。
  • token - 用于本地测试，例如使用 fakegcs。

当 repo-gcs-key-type=service 时，凭据将在认证令牌续期时重新加载。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费归属的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

备份和归档到本地挂载的文件系统时，无需此设置。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时，使用非系统默认的 CA 文件。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时，使用非系统默认的 CA 路径。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令路径。

仅当本地主机与仓库主机上的 pgBackRest 路径不同时才需要配置。若未定义，则与本地命令路径保持一致。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的位置。仅当仓库主机上的配置文件路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

设置了 repo-host 时仓库主机的端口。

使用此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口由 cmd-ssh 指定命令中的配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（SSH）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

设置了 repo-host 时仓库主机的用户。

定义用于仓库主机操作的用户。建议使用非 postgres 的专用用户（如 pgbackrest）。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其对仓库具有读取权限，同时避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份并归档 WAL 段的位置。

预估所需空间并不容易。建议先执行几次备份，记录不同类型备份（全量/增量/差异）的大小，并测量每天产生的 WAL 量，从而得出大致估算。随着数据库的增长，空间需求也会随时间变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

通过设置 repo-path=/ 可将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定一个前缀路径（如 /repo），以便日志和其他 AWS 生成的内容也可存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义或测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 等选项可能会有所帮助。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶时所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费模式。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭证的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机并在 URI 前添加存储桶名。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

存储仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

SFTP 仓库主机指纹的生成方式应与 repo-sftp-host-key-hash-type 匹配。可通过以下命令生成指纹：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下 SFTP 主机密钥检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts，并拒绝连接主机密钥已更改或不在已知主机文件中的主机。此选项要求手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到已知主机文件，但不允许连接主机密钥已更改的主机。
  • fingerprint - pgBackRest 将根据 repo-sftp-host-fingerprint 选项指定的指纹验证主机密钥。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明在 SSH 启动时用于计算远程系统主机密钥摘要的哈希算法。较新版本的 libssh2 在支持 md5 和 sha1 的基础上，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

存储仓库的主机上使用的用户名。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

认证过程中用于匹配 SFTP 主机的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将仅在这些文件中搜索匹配项。文件路径必须为绝对路径或以波浪号开头。此选项可多次传入以指定多个文件。若要使用已知主机文件检查，不得同时指定 repo-sftp-host-fingerprint。另请参见 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件。若基于 OpenSSL 编译，此项可选；若基于其他库编译，则为必填项。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

为存储（如 S3、Azure）证书使用非系统默认的 CA 文件。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

为存储（如 S3、Azure）证书使用非系统默认的 CA 路径。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机，通常用于测试场景。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储（如 S3、Azure）端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库为对象存储（如 S3）时，指定添加到对象上的标签。可多次传入此选项以添加多个标签。

pgBackRest 不提供修改这些标签的功能，因此请在运行 stanza-create 之前确认标签设置正确，确保整个仓库的标签统一。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

当文件过大无法全部载入内存时，对象存储（如 S3）允许分块上传。即使文件可以载入内存，限制上传所用内存量也更高效。

较大的分块大小通常有助于提升性能：减少上传请求数，并允许更多文件在单次请求中完成上传而无需分块。缺点是内存占用更高——由于分块缓冲区必须按进程分配，较大的 process-max 值将导致整体内存消耗更多。

注意，不同存储类型和平台对有效分块大小有所不同。例如，AWS S3 的最小分块大小为 5MiB。各存储类型对分块大小的术语不同，查询最小/最大值时请注意：AWS S3 使用"part size"，GCS 使用"chunk size"，Azure 使用"block size"。

若文件大于 1GiB（PostgreSQL 默认创建的最大文件大小），分块大小将逐步增大至允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用对存储（如 S3、Azure）服务器 TLS 证书的验证。仅在测试或使用自签名证书时才应禁用此功能。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud 存储
  • posix - POSIX 兼容文件系统
  • s3 - AWS 简单存储服务
  • sftp - 安全文件传输协议

使用 NFS 挂载作为 posix 仓库时，适用于 pgBackRest 的规则与 PostgreSQL 文档中的描述相同，参见 Creating a Database Cluster - File Systems。

YAML
default: posix
example: --repo1-type=cifs

Stanza 选项

PostgreSQL 数据库选项（--pg-database）

PostgreSQL 数据库。

连接 PostgreSQL 时使用的数据库名称。默认值通常最为合适，但某些安装环境中可能不存在此数据库。

注意，由于历史原因，PGDATABASE 环境变量的设置将被忽略。

YAML
default: postgres
example: --pg1-database=backupdb

PostgreSQL 主机选项（--pg-host）

远程操作时的 PostgreSQL 主机。

用于 PostgreSQL 主机与仓库主机分离时的备份场景。

YAML
example: --pg1-host=db.domain.com

已弃用名称：db-host

PostgreSQL 主机证书颁发机构文件选项（--pg-host-ca-file）

PostgreSQL 主机证书颁发机构文件。

连接 PostgreSQL 主机时，使用非系统默认的 CA 文件。

YAML
example: --pg1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

PostgreSQL 主机证书颁发机构路径选项（--pg-host-ca-path）

PostgreSQL 主机证书颁发机构路径。

连接 PostgreSQL 主机时，使用非系统默认的 CA 路径。

YAML
example: --pg1-host-ca-path=/etc/pki/tls/certs

PostgreSQL 主机证书文件选项（--pg-host-cert-file）

PostgreSQL 主机证书文件。

发送给 PostgreSQL 主机以证明客户端身份。

YAML
example: --pg1-host-cert-file=/path/to/client.crt

PostgreSQL 主机命令选项（--pg-host-cmd）

PostgreSQL 主机上的 pgBackRest 命令路径。

仅当本地主机与 PostgreSQL 主机上的 pgBackRest 路径不同时才需要配置。若未定义，则与本地命令路径保持一致。

YAML
default: [path of executed pgbackrest binary]
example: --pg1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：db-cmd

PostgreSQL 主机配置文件选项（--pg-host-config）

pgBackRest 数据库主机配置文件。

设置 PostgreSQL 主机上配置文件的位置。仅当 PostgreSQL 主机上的配置文件路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --pg1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：db-config

PostgreSQL 主机配置包含路径选项（--pg-host-config-include-path）

pgBackRest 数据库主机配置包含路径。

设置 PostgreSQL 主机上配置包含路径的位置。仅当 PostgreSQL 主机上的配置包含路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --pg1-host-config-include-path=/conf/pgbackrest/conf.d

PostgreSQL 主机配置路径选项（--pg-host-config-path）

pgBackRest 数据库主机配置路径。

设置 PostgreSQL 主机上配置路径的位置。仅当 PostgreSQL 主机上的配置路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --pg1-host-config-path=/conf/pgbackrest

PostgreSQL 主机密钥文件选项（--pg-host-key-file）

PostgreSQL 主机密钥文件。

用于证明客户端证书由所有者发送。

YAML
example: --pg1-host-key-file=/path/to/client.key

PostgreSQL 主机端口选项（--pg-host-port）

设置了 pg-host 时 PostgreSQL 主机的端口。

使用此选项为 PostgreSQL 主机协议指定非默认端口。

注意： 当 pg-host-type=ssh 时，pg-host-port 没有默认值，端口由 cmd-ssh 指定命令中的配置决定。

YAML
default (depending on pg-host-type):
   tls - 8432

allowed: [0, 65535]
example: --pg1-host-port=25

已弃用名称：db-ssh-port

PostgreSQL 主机协议类型选项（--pg-host-type）

PostgreSQL 主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（SSH）。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --pg1-host-type=tls

PostgreSQL 主机用户选项（--pg-host-user）

设置了 pg-host 时 PostgreSQL 主机的登录用户。

此用户同时作为远程 pgBackRest 进程的所有者，并负责发起与 PostgreSQL 的连接。为使其正常工作，该用户通常应为 PostgreSQL 数据库集群的所有者，默认为 postgres。

YAML
default: postgres
example: --pg1-host-user=db_owner

已弃用名称：db-user

PostgreSQL 路径选项（--pg-path）

PostgreSQL 数据目录。

此路径应与 PostgreSQL 上报的 data_directory 一致。虽然可以从多处读取此值，但建议在配置文件中明确设置，以确保在恢复或离线备份等这些资源不可用的场景下仍能正常使用。

pg-path 在每次在线备份时都会与 PostgreSQL 上报的值进行校验，因此应始终保持最新。

YAML
example: --pg1-path=/data/db

已弃用名称：db-path

PostgreSQL 端口选项（--pg-port）

PostgreSQL 端口。

PostgreSQL 监听的端口。大多数集群使用默认端口，通常无需指定此选项。

YAML
default: 5432
allowed: [0, 65535]
example: --pg1-port=6543

已弃用名称：db-port

PostgreSQL Socket 路径选项（--pg-socket-path）

PostgreSQL Unix Socket 路径。

PostgreSQL 启动时指定的 Unix Socket 目录。pgBackRest 会自动在操作系统的标准位置查找，通常无需指定此选项——除非在 postgresql.conf 中通过 unix_socket_directories 修改了 Socket 目录。

YAML
example: --pg1-socket-path=/var/run/postgresql

已弃用名称：db-socket-path

PostgreSQL 数据库用户选项（--pg-user）

PostgreSQL 数据库用户。

连接 PostgreSQL 时使用的数据库用户名。若未指定，pgBackRest 将使用当前操作系统用户或 PGUSER 环境变量中的用户。

YAML
example: --pg1-user=backupuser

4.16 - Stanza 升级命令（stanza-upgrade）

pgBackRest stanza-upgrade 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: stanza-upgrade

将 PostgreSQL 升级到新的主版本后，必须立即将所有 pgBackRest 配置中的 pg-path 更新为新的数据库位置，然后运行 stanza-upgrade 命令。若主机上配置了多个仓库，每个仓库都会执行 stanza 升级。若数据库处于离线状态，请使用 --no-online 选项。

命令选项

在线选项（--online）

在线更新集群。

指定 --no-online 可阻止 pgBackRest 在升级 stanza 时连接 PostgreSQL。

YAML
default: y
example: --no-online

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

缓冲区大小用于复制、压缩、加密及其他操作。实际使用的缓冲区数量取决于各项选项，且每个操作可能会占用额外的内存，例如 gz 压缩最多可额外消耗 256KiB 内存。

允许的值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

若需要使用特定的 SSH 客户端，或 ssh 命令不在 $PATH 中，可通过此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上运行时，设置网络传输的压缩级别。压缩用于降低网络流量。若 compress-type 不等于 none，则忽略 compress-level-network 设置，改用 compress-level，从而避免对文件进行二次压缩。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

通过此选项可指定与默认值不同的配置文件路径。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

pgBackRest 附加配置文件路径。

指定路径下扩展名为 .conf 的配置文件将与 pgBackRest 主配置文件合并，形成一个统一的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置用于覆盖 --config 和 --config-include-path 选项的默认基础路径，除非这两个选项已在命令行中显式指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将被设为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将被设为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

数据库超时选项（--db-timeout）

数据库查询超时时间。

设置对数据库执行查询操作的超时时间（单位：秒）。这包括备份启动/停止函数，这些函数各自可能耗时较长。因此，除非确认这些函数能快速返回（例如已设置 start-fast=y，且数据库集群在备份期间不会产生大量 WAL 段），否则应将超时时间设置得足够长。

注意： db-timeout 的值必须小于 protocol-timeout。

YAML
default: 30m
allowed: [100ms, 7d]
example: --db-timeout=600

I/O 超时选项（--io-timeout）

I/O 超时时间。

连接及读写操作的超时时间（单位：秒）。

注意，整个读写操作无需在此时间内完成，但必须持续有所进展，哪怕仅传输了一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 将锁文件存储在此路径下，以防止冲突操作并发运行。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

进程优先级。

定义内核调度器赋予该进程的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

协议超时选项（--protocol-timeout）

协议超时时间。

设置本地或远程进程在协议层等待接收新消息的超时时间（单位：秒）。此设置可防止进程无限期等待。

注意： protocol-timeout 的值必须大于 db-timeout。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用保活机制。

在套接字连接上启用保活消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza。

stanza 是 PostgreSQL 数据库集群的配置单元，定义了集群的位置、备份方式、归档选项等信息。大多数数据库服务器只有一个 PostgreSQL 数据库集群，因此只有一个 stanza；而备份服务器通常会为每个需要备份的数据库集群分别配置一个 stanza。

命名 stanza 时，人们往往倾向于使用主集群名称，但更好的做法是根据集群所承载的数据库功能来命名。由于 stanza 名称会同时用于主库和所有副本，选择能描述集群实际功能的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

保活计数。

指定在判定连接已断开之前，允许丢失的 TCP 保活消息数量。

此选项仅适用于支持 TCP_KEEPCNT 套接字选项的系统。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

保活空闲时间。

指定网络无活动后，操作系统发送 TCP 保活消息前的等待时间（单位：秒）。

此选项仅适用于支持 TCP_KEEPIDLE 套接字选项的系统。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

保活间隔时间。

指定未收到确认的 TCP 保活消息在重传前的等待时间（单位：秒）。

此选项仅适用于支持 TCP_KEEPINTVL 套接字选项的系统。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别要求为 TLSv1.2。

可根据需要调整所接受的加密套件。示例值是合理的选择，除非有特定的安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，与对象存储（如 S3）的连接也会加密。

注意： 任何传输连接的最低安全级别要求为 TLSv1.2。

可根据需要调整所接受的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详细信息、普通信息、警告和错误
  • debug - 记录调试信息、详细信息、普通信息、警告和错误
  • trace - 记录追踪信息（非常详细的调试输出）、调试信息、普通信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详细信息、普通信息、警告和错误
  • debug - 记录调试信息、详细信息、普通信息、警告和错误
  • trace - 记录追踪信息（非常详细的调试输出）、调试信息、普通信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别的输出将写入 stderr 而非 stdout（由 log-level-console 指定）。写入 stderr 的日志不包含时间戳和进程信息。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详细信息、普通信息、警告和错误
  • debug - 记录调试信息、详细信息、普通信息、警告和错误
  • trace - 记录追踪信息（非常详细的调试输出）、调试信息、普通信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件存储在此路径下。注意，若 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为当前进程创建的所有子进程启用文件日志，日志级别由 log-level-file 指定。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

启用日志时间戳。

在控制台和文件日志中启用时间戳。在某些特殊场景（如生成文档）下，此选项会被禁用。

YAML
default: y
example: --no-log-timestamp

维护者选项

强制指定 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用指定的 PostgreSQL 版本，而非通过读取 pg_control 或 WAL 头部自动检测到的版本。此选项主要用于 PostgreSQL 分支版本或开发版本，这些版本的控制文件版本号可能与正式发布版本不同。PostgreSQL 通过 server_version_num 报告的版本必须与强制指定的版本一致。

警告：

使用此选项时请务必谨慎，因为 pg_control 和 WAL 头部仍将按照指定版本所对应的官方 PostgreSQL 格式进行解析。若分支版本或开发版本修改了 pgBackRest 所依赖字段的格式，将导致不可预期的行为。通常情况下，此选项仅在分支版本将所有自定义结构成员追加在标准 PostgreSQL 成员 之后 时才能正常工作。

YAML
example: --pg-version-force=15

仓库选项

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

可通过设置 repo-path=/ 将 pgBackRest 仓库存储在容器根目录，但通常建议指定一个前缀路径（如 /repo），以便日志及其他 Azure 生成的内容也能存储在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加账户名前缀。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

仓库加密算法。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 使用 256 位密钥的高级加密标准

注意，即使仓库类型（如 S3）本身支持加密，pgBackRest 的加密操作也始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

可通过设置 repo-path=/ 将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定一个前缀路径（如 /repo），以便日志及其他 GCS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

连接存储服务所使用的端点地址。可更新为本地 GCS 服务器或其他备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账号授权。
  • service - 使用本地存储的服务账号密钥。
  • token - 用于本地测试，例如 fakegcs。

当 repo-gcs-key-type=service 时，认证令牌续期时将重新加载凭据。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费方的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

若备份和归档均写入本地挂载的文件系统，则无需此设置。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

使用非系统默认的 CA 文件连接仓库主机。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

使用非系统默认的 CA 路径连接仓库主机。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令。

仅当本地主机与仓库主机上的 pgBackRest 命令路径不同时才需要配置。若未定义，仓库主机命令将与本地命令保持一致。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的路径。仅当仓库主机的配置文件路径与本地配置文件路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机的配置包含路径与本地配置包含路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机的配置路径与本地配置路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由其所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

设置了 repo-host 时仓库主机使用的端口。

通过此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口号由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全 Shell。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

设置了 repo-host 时仓库主机使用的用户。

定义在仓库主机上执行操作所使用的用户。建议使用专用用户（如 pgbackrest），而非 postgres 用户。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其拥有仓库的读权限，同时避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的位置。

提前估算所需空间可能较为困难。建议先执行几次备份，记录不同类型备份（全量/增量/差异）的大小，并测量每日产生的 WAL 数据量，以此粗略估算所需空间。随着数据库规模增长，实际需求也会随之变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

可通过设置 repo-path=/ 将 pgBackRest 仓库存储在存储桶根目录，但通常建议指定一个前缀路径（如 /repo），以便日志及其他 AWS 生成的内容也能存储在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义或测试配置，可使用 repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 等选项。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

存储桶所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭据的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加存储桶名前缀。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

存放仓库的 SFTP 主机。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

SFTP 仓库主机指纹的生成方式应与 repo-sftp-host-key-hash-type 一致。可通过以下命令生成指纹：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下 SFTP 主机密钥检查类型：

  • strict - pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts 文件，并拒绝连接主机密钥已更改或不在已知主机文件中的主机。此选项要求用户手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到用户的已知主机文件，但不允许连接主机密钥已更改的主机。
  • fingerprint - pgBackRest 将主机密钥与 repo-sftp-host-fingerprint 选项指定的指纹进行比对验证。
  • none - 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明在 SSH 启动时用于计算远程系统主机密钥摘要的哈希算法。较新版本的 libssh2 除支持 md5 和 sha1 外，还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

存放仓库的主机上使用的用户。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

认证时用于搜索 SFTP 主机匹配的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将仅在这些文件中搜索匹配项。文件路径必须是完整路径或以波浪号开头的路径。此选项可多次指定以搜索多个已知主机文件。使用已知主机文件检查时，不得指定 repo-sftp-host-fingerprint。另请参阅 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件。若编译时使用 OpenSSL，此项为可选；若使用其他库，则为必填项。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

使用非系统默认的 CA 文件验证存储（如 S3、Azure）证书。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file, repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

使用非系统默认的 CA 路径验证存储（如 S3、Azure）证书。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path, repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点以外的主机，通常用于测试场景。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host, repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接存储（如 S3、Azure）端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port, repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

指定在仓库为对象存储（如 S3）时添加到对象上的标签，可多次指定以添加多个标签。

pgBackRest 不提供修改这些标签的功能，因此请在运行 stanza-create 之前确认标签设置正确，以确保整个仓库的标签统一。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

S3 等对象存储在文件过大无法存入内存时，支持分块上传。即使文件可以存入内存，限制上传时的内存用量也能提高内存效率。

较大的分块大小通常能带来更好的性能，因为它可以减少上传请求次数，并允许更多文件在单次请求中完成上传而无需分块。缺点是内存占用更高，且由于分块缓冲区必须按进程分配，process-max 值越大，整体内存消耗越高。

注意，有效的分块大小因存储类型和平台而异。例如，AWS S3 的最小分块大小为 5MiB。各存储类型对分块大小的术语叫法不同：AWS S3 称为"part size"，GCS 称为"chunk size"，Azure 称为"block size"，查询最小/最大值时请注意使用对应术语。

若文件大于 1GiB（PostgreSQL 默认创建的最大文件大小），分块大小将逐步增大，直至达到允许的最大值，以完成文件上传。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

控制是否验证存储（如 S3、Azure）服务器的 TLS 证书。仅在测试场景或使用自签名证书时才应禁用验证。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls, repo-s3-verify-ssl, repo-s3-verify-tls

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google 云存储
  • posix - 符合 POSIX 标准的文件系统
  • s3 - AWS 简单存储服务
  • sftp - 安全文件传输协议

当使用 NFS 挂载作为 posix 类型仓库时，pgBackRest 适用与 PostgreSQL 文档中相同的规则，详见 Creating a Database Cluster - File Systems。

YAML
default: posix
example: --repo1-type=cifs

Stanza 选项

PostgreSQL 数据库选项（--pg-database）

PostgreSQL 数据库。

连接 PostgreSQL 时使用的数据库名称。默认值通常适用，但某些安装环境可能不包含此数据库。

注意，出于历史兼容性原因，PGDATABASE 环境变量的设置将被忽略。

YAML
default: postgres
example: --pg1-database=backupdb

PostgreSQL 主机选项（--pg-host）

远程操作时的 PostgreSQL 主机。

用于 PostgreSQL 主机与仓库主机不同时的备份场景。

YAML
example: --pg1-host=db.domain.com

已弃用名称：db-host

PostgreSQL 主机证书颁发机构文件选项（--pg-host-ca-file）

PostgreSQL 主机证书颁发机构文件。

使用非系统默认的 CA 文件连接 PostgreSQL 主机。

YAML
example: --pg1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

PostgreSQL 主机证书颁发机构路径选项（--pg-host-ca-path）

PostgreSQL 主机证书颁发机构路径。

使用非系统默认的 CA 路径连接 PostgreSQL 主机。

YAML
example: --pg1-host-ca-path=/etc/pki/tls/certs

PostgreSQL 主机证书文件选项（--pg-host-cert-file）

PostgreSQL 主机证书文件。

发送给 PostgreSQL 主机以证明客户端身份。

YAML
example: --pg1-host-cert-file=/path/to/client.crt

PostgreSQL 主机命令选项（--pg-host-cmd）

PostgreSQL 主机上的 pgBackRest 命令。

仅当本地主机与 PostgreSQL 主机上的 pgBackRest 命令路径不同时才需要配置。若未定义，PostgreSQL 主机命令将与本地命令保持一致。

YAML
default: [path of executed pgbackrest binary]
example: --pg1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：db-cmd

PostgreSQL 主机配置文件选项（--pg-host-config）

pgBackRest 数据库主机配置文件。

设置 PostgreSQL 主机上配置文件的路径。仅当 PostgreSQL 主机的配置文件路径与本地配置文件路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --pg1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：db-config

PostgreSQL 主机配置包含路径选项（--pg-host-config-include-path）

pgBackRest 数据库主机配置包含路径。

设置 PostgreSQL 主机上配置包含路径的位置。仅当 PostgreSQL 主机的配置包含路径与本地配置包含路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --pg1-host-config-include-path=/conf/pgbackrest/conf.d

PostgreSQL 主机配置路径选项（--pg-host-config-path）

pgBackRest 数据库主机配置路径。

设置 PostgreSQL 主机上配置路径的位置。仅当 PostgreSQL 主机的配置路径与本地配置路径不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --pg1-host-config-path=/conf/pgbackrest

PostgreSQL 主机密钥文件选项（--pg-host-key-file）

PostgreSQL 主机密钥文件。

用于证明客户端证书由其所有者发送。

YAML
example: --pg1-host-key-file=/path/to/client.key

PostgreSQL 主机端口选项（--pg-host-port）

设置了 pg-host 时 PostgreSQL 主机使用的端口。

通过此选项为 PostgreSQL 主机协议指定非默认端口。

注意： 当 pg-host-type=ssh 时，pg-host-port 没有默认值，端口号由 cmd-ssh 指定的命令配置决定。

YAML
default (depending on pg-host-type):
   tls - 8432

allowed: [0, 65535]
example: --pg1-host-port=25

已弃用名称：db-ssh-port

PostgreSQL 主机协议类型选项（--pg-host-type）

PostgreSQL 主机协议类型。

支持以下协议类型：

  • ssh - 安全 Shell。
  • tls - pgBackRest TLS 服务器。
YAML
default: ssh
example: --pg1-host-type=tls

PostgreSQL 主机用户选项（--pg-host-user）

设置了 pg-host 时 PostgreSQL 主机的登录用户。

该用户同时也是远程 pgBackRest 进程的所有者，并负责发起与 PostgreSQL 的连接。为确保正常工作，此用户应是 PostgreSQL 数据库集群的所有者，通常为 postgres（默认值）。

YAML
default: postgres
example: --pg1-host-user=db_owner

已弃用名称：db-user

PostgreSQL 路径选项（--pg-path）

PostgreSQL 数据目录。

此路径应与 PostgreSQL 报告的 data_directory 一致。尽管可以从多处读取该值，但建议显式配置，以防在恢复或离线备份场景中这些资源不可用。

pg-path 选项在每次在线备份时都会与 PostgreSQL 报告的值进行校验，因此应始终保持最新。

YAML
example: --pg1-path=/data/db

已弃用名称：db-path

PostgreSQL 端口选项（--pg-port）

PostgreSQL 端口。

PostgreSQL 运行的端口号。大多数 PostgreSQL 集群使用默认端口，通常无需指定此项。

YAML
default: 5432
allowed: [0, 65535]
example: --pg1-port=6543

已弃用名称：db-port

PostgreSQL Socket 路径选项（--pg-socket-path）

PostgreSQL Unix Socket 路径。

PostgreSQL 启动时指定的 Unix Socket 目录。pgBackRest 会自动查找操作系统的标准位置，通常无需配置此项，除非通过 postgresql.conf 中的 unix_socket_directories 显式修改了 Socket 目录。

YAML
example: --pg1-socket-path=/var/run/postgresql

已弃用名称：db-socket-path

PostgreSQL 数据库用户选项（--pg-user）

PostgreSQL 数据库用户。

连接 PostgreSQL 时使用的数据库用户名。若未指定，pgBackRest 将使用本地操作系统用户或 PGUSER 环境变量。

YAML
example: --pg1-user=backupuser

4.17 - 启动命令（start）

pgBackRest start 命令选项与行为参考。

原始页面： pgBackRest Command Docs: start

如果 pgBackRest 进程之前已通过 stop 命令停止，可使用 start 命令重新允许它们运行。注意，此命令不会立即启动任何 pgBackRest 进程，只是解除运行限制。详情与示例请参见 启动与停止。

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项可以指定非默认的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

该路径下扩展名为 .conf 的配置文件将与主配置文件合并，形成统一的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置用于覆盖 --config 和 --config-include-path 选项的默认基础路径，但若这两个选项已在命令行中显式指定，则此设置不生效。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 使用锁文件防止并发执行相互冲突的操作，此选项指定锁文件的存放位置。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器为进程分配的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

Stanza 选项（--stanza）

定义 stanza。

stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称，包括集群位置、备份方式、归档选项等。大多数数据库主机只有一个 PostgreSQL 集群，因此只有一个 stanza；备份服务器则需要为每个待备份的集群分别配置一个 stanza。

命名 stanza 时，以主集群名称命名看似直观，但更好的做法是用集群所承载数据库的功能来命名。由于 stanza 名称会同时用于主库和所有副本，因此选择能描述集群实际用途的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

日志选项

控制台日志级别选项（--log-level-console）

控制台日志的输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志的输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 的日志输出级别。

指定哪些日志级别将输出到 stderr 而非 stdout（后者由 log-level-console 控制）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件写入此路径。注意，若 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中启用时间戳输出。某些特殊场景（如生成文档时）会禁用此选项。

YAML
default: y
example: --no-log-timestamp

4.18 - 停止命令（stop）

pgBackRest stop 命令选项与行为参考。

原始页面： pgBackRest Command Docs: stop

禁止任何新的 pgBackRest 进程运行。默认情况下，正在运行的进程将被允许正常完成。使用 --force 选项可强制终止正在运行的进程。

stop 命令执行完成后，此后尝试运行的 pgBackRest 进程将返回错误。详情与示例请参见 启动与停止。

命令选项

强制停止选项（--force）

强制停止所有 pgBackRest 进程。

此选项会向所有正在运行的 pgBackRest 进程发送 TERM 信号，实现立即的优雅关闭。注意，这也会关闭由其他系统发起、但在当前系统上运行的远程进程。例如，若备份是在备份服务器上启动的，在数据库主机上运行 stop --force 将同时关闭备份服务器上的备份进程。

YAML
default: n
example: --force

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

配置文件选项（--config）

pgBackRest 配置文件。

使用此选项可以指定非默认的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加 pgBackRest 配置文件的路径。

该路径下扩展名为 .conf 的配置文件将与主配置文件合并，形成统一的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置用于覆盖 --config 和 --config-include-path 选项的默认基础路径，但若这两个选项已在命令行中显式指定，则此设置不生效。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

锁文件路径选项（--lock-path）

锁文件的存储路径。

pgBackRest 使用锁文件防止并发执行相互冲突的操作，此选项指定锁文件的存放位置。

YAML
default: /tmp/pgbackrest
example: --lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

定义内核调度器为进程分配的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提高自身优先级。

YAML
allowed: [-20, 19]
example: --priority=19

Stanza 选项（--stanza）

定义 stanza。

stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称，包括集群位置、备份方式、归档选项等。大多数数据库主机只有一个 PostgreSQL 集群，因此只有一个 stanza；备份服务器则需要为每个待备份的集群分别配置一个 stanza。

命名 stanza 时，以主集群名称命名看似直观，但更好的做法是用集群所承载数据库的功能来命名。由于 stanza 名称会同时用于主库和所有副本，因此选择能描述集群实际用途的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

日志选项

控制台日志级别选项（--log-level-console）

控制台日志的输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志的输出级别。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 的日志输出级别。

指定哪些日志级别将输出到 stderr 而非 stdout（后者由 log-level-console 控制）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off - 不输出任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详情、信息、警告和错误
  • debug - 记录调试、详情、信息、警告和错误
  • trace - 记录跟踪（非常详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件的存储路径。

pgBackRest 将日志文件写入此路径。注意，若 log-level-file=off，则无需配置日志路径。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中启用时间戳输出。某些特殊场景（如生成文档时）会禁用此选项。

YAML
default: y
example: --no-log-timestamp

4.19 - 验证命令（verify）

pgBackRest verify 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: verify

verify 用于验证仓库中的备份和归档是否有效。

命令选项

输出格式选项（--output）

输出类型。

支持以下输出类型：

  • none — 不输出验证信息。
  • text — 将验证信息输出到标准输出。
YAML
default: none
example: --output=text

备份集选项（--set）

要验证的备份集。

验证与指定备份集关联的所有数据库文件和归档文件。

YAML
example: --set=20150131-153358F_20150131-153401I

详细输出选项（--verbose）

详细输出。

默认不启用详细输出，仅显示包含仓库错误的简要结果。设为 true 后，还将输出成功验证项的详细信息。

YAML
default: n
example: --verbose

通用选项

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

YAML
default: n
example: --allow-root

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

该缓冲区用于复制、压缩、加密等操作。实际使用的缓冲区数量取决于具体选项，每种操作可能额外占用内存，例如 gz 压缩最多可额外使用 256KiB 内存。

允许的值为 16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

YAML
default: 1MiB
example: --buffer-size=2MiB

pgBackRest 命令选项（--cmd）

pgBackRest 命令。

pgBackRest 有时需要构造命令字符串，例如 restore 命令生成 restore_command 设置时。若未通过 cmd 选项显式指定，将使用当前 pgBackRest 进程所用的命令路径。

注意： 对 pgBackRest 命令进行包装可能导致不可预期的行为，不建议使用。

YAML
default: [path of executed pgbackrest binary]
example: --cmd=/var/lib/pgsql/bin/pgbackrest_wrapper.sh

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

如需使用特定的 SSH 客户端，或 ssh 命令不在 $PATH 中，可通过此选项指定。

YAML
default: ssh
example: --cmd-ssh=/usr/bin/ssh

网络压缩级别选项（--compress-level-network）

网络压缩级别。

当 compress-type=none 且命令不在仓库所在主机上执行时，此选项设置网络传输的压缩级别，以减少网络流量。若 compress-type 不等于 none，则忽略此设置，改用 compress-level，避免对文件进行二次压缩。

YAML
default: 1
allowed: [-5, 12]
example: --compress-level-network=1

配置文件选项（--config）

pgBackRest 配置文件。

通过此选项可指定非默认路径的配置文件。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf

配置包含路径选项（--config-include-path）

附加配置文件的目录路径。

该目录下扩展名为 .conf 的文件将与 pgBackRest 主配置文件合并，共同构成最终的配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d

配置基础路径选项（--config-path）

pgBackRest 配置文件的基础路径。

此设置覆盖 --config 和 --config-include-path 的默认基础路径，前提是这两个选项未在命令行中显式指定。

例如，仅传入 --config-path=/conf/pgbackrest 时，--config 的默认值将变为 /conf/pgbackrest/pgbackrest.conf，--config-include-path 的默认值将变为 /conf/pgbackrest/conf.d。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest

I/O 超时选项（--io-timeout）

I/O 超时。

连接、读写操作的超时时间（秒）。

注意，整个读写操作不必在此超时内完成，但必须持续有进展，哪怕每次只传输一个字节。

YAML
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

YAML
default: y
example: --no-neutral-umask

进程优先级选项（--priority）

设置进程优先级。

指定内核调度器为该进程分配的 niceness 值。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限自行提升优先级。

YAML
allowed: [-20, 19]
example: --priority=19

最大进程数选项（--process-max）

压缩与传输使用的最大进程数。

每个进程并行执行压缩和传输操作，可加快命令执行速度。但不宜将 process-max 设置过高，以免影响数据库性能。

YAML
default: 1
allowed: [1, 999]
example: --process-max=4

协议超时选项（--protocol-timeout）

协议超时。

设置本地或远程进程在协议层等待新消息的超时时间（秒），防止进程无限期挂起。

注意： protocol-timeout 的值必须大于 db-timeout。

YAML
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630

保活选项（--sck-keep-alive）

启用 keep-alive。

在套接字连接上启用 keep-alive 消息。

YAML
default: y
example: --no-sck-keep-alive

Stanza 选项（--stanza）

定义 stanza。

stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称，定义了集群的位置、备份方式、归档选项等。大多数数据库主机只有一个 PostgreSQL 集群，因此只有一个 stanza；备份服务器则会为每个需要备份的集群各配置一个 stanza。

stanza 名称很容易直接使用主库集群名，但更好的做法是用名称描述集群中所包含的数据库内容。由于该名称同时用于主库和所有副本，选择能体现集群实际用途的名称（如 app 或 dw）比使用本地集群名称（如 main 或 prod）更为合适。

YAML
example: --stanza=main

TCP 保活计数选项（--tcp-keep-alive-count）

Keep-alive 计数。

指定在判定连接断开之前，允许丢失的 TCP keep-alive 消息数量。

此选项仅在系统支持 TCP_KEEPCNT 套接字选项时有效。

YAML
allowed: [1, 32]
example: --tcp-keep-alive-count=3

TCP 保活空闲时间选项（--tcp-keep-alive-idle）

Keep-alive 空闲时间。

指定在无网络活动达到多少秒后，操作系统开始发送 TCP keep-alive 消息。

此选项仅在系统支持 TCP_KEEPIDLE 套接字选项时有效。

YAML
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60

TCP 保活间隔选项（--tcp-keep-alive-interval）

Keep-alive 间隔时间。

指定未收到确认的 TCP keep-alive 消息重新发送前的等待秒数。

此选项仅在系统支持 TCP_KEEPINTVL 套接字选项时有效。

YAML
allowed: [1, 900]
example: --tcp-keep-alive-interval=30

TLSv1.2 加密套件选项（--tls-cipher-12）

允许的 TLSv1.2 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密，默认情况下与对象存储（如 S3）的连接也会加密。

注意： 所有传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许的加密套件。示例中的配置是合理的选择，除非有特定安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 加密套件选项（--tls-cipher-13）

允许的 TLSv1.3 加密套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密，默认情况下与对象存储（如 S3）的连接也会加密。

注意： 所有传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

YAML
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off — 不记录任何日志（不推荐）
  • error — 仅记录错误
  • warn — 记录警告和错误
  • info — 记录信息、警告和错误
  • detail — 记录详情、信息、警告和错误
  • debug — 记录调试、详情、信息、警告和错误
  • trace — 记录跟踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: warn
example: --log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off — 不记录任何日志（不推荐）
  • error — 仅记录错误
  • warn — 记录警告和错误
  • info — 记录信息、警告和错误
  • detail — 记录详情、信息、警告和错误
  • debug — 记录调试、详情、信息、警告和错误
  • trace — 记录跟踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: info
example: --log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些级别的日志输出到 stderr 而非 stdout（由 log-level-console 控制）。时间戳和进程信息不会输出到 stderr。

支持以下日志级别：

  • off — 不记录任何日志（不推荐）
  • error — 仅记录错误
  • warn — 记录警告和错误
  • info — 记录信息、警告和错误
  • detail — 记录详情、信息、警告和错误
  • debug — 记录调试、详情、信息、警告和错误
  • trace — 记录跟踪（极详细的调试信息）、调试、信息、警告和错误
YAML
default: off
example: --log-level-stderr=error

日志路径选项（--log-path）

日志文件存储路径。

pgBackRest 将日志文件保存到此路径。注意，若 log-level-file=off，则无需配置此项。

YAML
default: /var/log/pgbackrest
example: --log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为该进程创建的所有子进程启用文件日志记录，使用 log-level-file 指定的日志级别。

YAML
default: n
example: --log-subprocess

日志时间戳选项（--log-timestamp）

在日志中启用时间戳。

在控制台和文件日志中输出时间戳。某些特殊场景（如生成文档）下会禁用此选项。

YAML
default: y
example: --no-log-timestamp

维护者选项

强制指定 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用指定的 PostgreSQL 版本，而不是从 pg_control 或 WAL 头部自动检测到的版本。此选项主要用于 PostgreSQL 分支版本或开发版本——这些版本中，自动检测到的值可能与正式发布版本号不同。PostgreSQL 通过 server_version_num 报告的版本号必须与强制指定的版本一致。

警告： 请谨慎使用此选项。启用后，pg_control 和 WAL 头部将按照指定版本（即官方 PostgreSQL 发布版本）的预期格式解析。若分支或开发版本修改了 pgBackRest 所依赖字段的格式，将导致不可预期的行为。通常，只有当分支版本将所有自定义结构成员追加在标准 PostgreSQL 成员之后时，此选项才能正常工作。

YAML
example: --pg-version-force=15

仓库选项

指定仓库选项（--repo）

指定仓库。

指定命令操作的目标仓库。

例如，可通过此选项指定从特定仓库执行恢复，而非由 pgBackRest 自动选择。

YAML
allowed: [1, 256]
example: --repo=1

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

pgBackRest 仓库可通过设置 repo-path=/ 存储在容器根目录，但通常建议指定一个前缀（如 /repo），这样日志及其他 Azure 生成的内容也可存放在同一容器中。

YAML
example: --repo1-azure-container=pg-backup

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared — 共享密钥
  • sas — 共享访问签名
  • auto — 使用 Azure 托管标识自动授权
YAML
default: shared
example: --repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host — 连接到 account.endpoint 主机。
  • path — 连接到 endpoint 主机，并在 URI 中添加账户前缀。
YAML
default: host
example: --repo1-azure-uri-style=path

仓库加密类型选项（--repo-cipher-type）

仓库加密算法。

支持以下加密类型：

  • none — 不加密
  • aes-256-cbc — 256 位密钥的 AES 加密标准

注意，即使仓库存储类型（如 S3）本身支持加密，pgBackRest 的加密始终在客户端执行。

YAML
default: none
example: --repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

pgBackRest 仓库可通过设置 repo-path=/ 存储在存储桶根目录，但通常建议指定一个前缀（如 /repo），这样日志及其他 GCS 生成的内容也可存放在同一存储桶中。

YAML
example: --repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点地址，可替换为本地 GCS 服务器或其他备用端点。

YAML
default: storage.googleapis.com
example: --repo1-gcs-endpoint=localhost

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto — 使用实例服务账号授权。
  • service — 使用本地存储的服务账号密钥。
  • token — 用于本地测试，如 fakegcs。

当 repo-gcs-key-type=service 时，认证令牌续期时会重新加载身份凭据。

YAML
default: service
example: --repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费归属的 GCS 项目 ID。

YAML
example: --repo1-gcs-user-project=my-project

仓库主机选项（--repo-host）

远程操作时的仓库主机。

若备份和归档存储在本地挂载的文件系统中，则无需此设置。

YAML
example: --repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接仓库主机时，使用指定的 CA 文件替代系统默认值。

YAML
example: --repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接仓库主机时，使用指定的 CA 路径替代系统默认值。

YAML
example: --repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

向仓库主机发送此证书以证明客户端身份。

YAML
example: --repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令。

仅当仓库主机上的 pgBackRest 命令路径与本地不同时才需要配置。若未定义，将沿用本地命令路径。

YAML
default: [path of executed pgbackrest binary]
example: --repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置文件选项（--repo-host-config）

pgBackRest 仓库主机配置文件。

设置仓库主机上配置文件的路径。仅当仓库主机的配置文件路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

pgBackRest 仓库主机配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机的配置包含路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

pgBackRest 仓库主机配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机的配置路径与本地不同时才需要配置。

YAML
default: CFGOPTDEF_CONFIG_PATH
example: --repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

用于证明客户端证书由其所有者发送。

YAML
example: --repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

repo-host 已设置时的仓库主机端口。

通过此选项为仓库主机协议指定非默认端口。

注意： 当 repo-host-type=ssh 时，repo-host-port 没有默认值，端口由 cmd-ssh 所指定命令的配置决定。

YAML
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: --repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh — 安全外壳协议。
  • tls — pgBackRest TLS 服务器。
YAML
default: ssh
example: --repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

repo-host 已设置时的仓库主机用户。

定义在仓库主机上执行操作所使用的用户。建议使用专用用户（如 pgbackrest）而非 postgres。若 PostgreSQL 运行在仓库主机上，可将 postgres 用户加入 pgbackrest 组，使其对仓库拥有读取权限，同时避免意外损坏仓库内容。

YAML
default: pgbackrest
example: --repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的位置。

预先估算所需空间可能比较困难。建议先执行几次备份，分别记录全量、增量、差异备份的大小，并统计每天的 WAL 生成量，从而大致估算所需空间。随着数据库的演进，空间需求也会持续变化。

YAML
default: /var/lib/pgbackrest
example: --repo1-path=/backup/db/backrest

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

pgBackRest 仓库可通过设置 repo-path=/ 存储在存储桶根目录，但通常建议指定一个前缀（如 /repo），这样日志及其他 AWS 生成的内容也可存放在同一存储桶中。

YAML
example: --repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与存储桶所在区域匹配。

自定义或测试配置时，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 等选项可能有所帮助。

YAML
example: --repo1-s3-endpoint=s3.amazonaws.com

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
YAML
default: shared
example: --repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS KMS 密钥启用 S3 服务端加密。

YAML
example: --repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

YAML
example: --repo1-s3-process-cmd=/usr/local/bin/get-credentials --repo1-s3-process-cmd=--role --repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

存储桶所在的 AWS 区域。

YAML
example: --repo1-s3-region=us-east-1

S3 仓库请求方付费选项（--repo-s3-requester-pays）

S3 仓库请求方付费。

启用 S3 请求方付费功能。

YAML
default: n
example: --no-repo1-s3-requester-pays

S3 仓库角色选项（--repo-s3-role）

S3 仓库角色。

当 repo-s3-key-type=auto 时，用于获取临时凭据的 AWS 角色名称（非完整 ARN）。

YAML
example: --repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

YAML
default: s3
example: --repo1-s3-service=s3-outposts

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

YAML
default: sts.amazonaws.com
example: --repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host — 连接到 bucket.endpoint 主机。
  • path — 连接到 endpoint 主机，并在 URI 中添加存储桶前缀。
YAML
default: host
example: --repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

存放仓库的 SFTP 主机地址。

YAML
example: --repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

指纹的生成方式须与 repo-sftp-host-key-hash-type 保持一致。可通过以下命令生成：awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b。SSH 主机密钥通常位于 /etc/ssh 目录下。

YAML
example: --repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下检查类型：

  • strict — pgBackRest 不会自动将主机密钥添加到 ~/.ssh/known_hosts，并拒绝连接密钥已变更或不在已知主机文件中的主机。此选项要求手动添加所有新主机。
  • accept-new — pgBackRest 自动将新主机密钥添加到已知主机文件，但不允许连接密钥已变更的主机。
  • fingerprint — 根据 repo-sftp-host-fingerprint 指定的指纹验证主机密钥。
  • none — 不执行主机密钥检查。
YAML
default: strict
example: --repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明 SSH 握手时计算远程主机密钥摘要所用的哈希算法。较新版本的 libssh2 在 md5 和 sha1 之外还支持 sha256。

YAML
example: --repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

YAML
default: 22
allowed: [1, 65535]
example: --repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

存储仓库的主机上对应的用户名。

YAML
example: --repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

认证时用于匹配 SFTP 主机的已知主机文件。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若指定了一个或多个文件路径，pgBackRest 将仅在这些文件中查找匹配项。路径必须为完整路径或以波浪号（~）开头的路径。此选项可多次传入以指定多个文件。使用已知主机文件检查时，不得同时指定 repo-sftp-host-fingerprint。另请参阅 repo-sftp-host-check-type 选项。

YAML
example: --repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于认证的 SFTP 私钥文件路径。

YAML
example: --repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于认证的 SFTP 公钥文件路径。若编译时链接的是 OpenSSL，则此项可选；若链接的是其他库，则为必填。

YAML
example: --repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接对象存储（如 S3、Azure）时，使用指定的 CA 文件替代系统默认值。

YAML
example: --repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file, repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接对象存储（如 S3、Azure）时，使用指定的 CA 路径替代系统默认值。

YAML
example: --repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path, repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到非标准存储端点（如 S3、Azure）的主机地址，通常用于测试。

YAML
example: --repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host, repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接对象存储端点（或指定主机）时使用的端口。

YAML
default: 443
allowed: [1, 65535]
example: --repo1-storage-port=9000

已弃用名称：repo-azure-port, repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库使用对象存储（如 S3）时，为对象添加的标签。此选项可多次指定以添加多个标签。

pgBackRest 不提供修改已有标签的功能，因此请在执行 stanza-create 之前确认标签设置正确，以保证整个仓库的标签一致性。

YAML
example: --repo1-storage-tag=key1=value1

仓库存储上传分块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传分块大小。

S3 等对象存储在文件过大无法整体载入内存时，支持分块上传。即使文件能放入内存，限制单次上传的内存用量也更为高效。

较大的块大小通常有助于提升性能，因为它能减少上传请求次数，在单个请求中传输更多数据。但代价是内存占用更高，且块缓冲区按进程分配，process-max 越大，总内存消耗越多。

不同存储类型和平台对块大小的有效范围要求不同。例如，AWS S3 的最小块大小为 5MiB。各存储类型对此的术语也有差异：AWS S3 称为 “part size”，GCS 称为 “chunk size”，Azure 称为 “block size”。

若文件超过 1GiB（PostgreSQL 默认的单文件上限），块大小将自动逐步增大直至允许的最大值，以确保文件能够上传完成。

YAML
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: --repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

控制是否验证对象存储（如 S3、Azure）服务器的 TLS 证书。仅在测试或使用自签名证书等特殊场景下才应禁用验证。

YAML
default: y
example: --no-repo1-storage-verify-tls

已弃用名称：repo-azure-verify-tls, repo-s3-verify-ssl, repo-s3-verify-tls

仓库目标时间选项（--repo-target-time）

仓库目标时间。

指定读取版本化存储上仓库时所参照的时间点，从而访问某一历史时刻的仓库状态，用于恢复因误操作或恶意软件导致删除或损坏的数据。

S3、GCS 和 Azure 均支持版本化存储，但通常默认未启用。除启用版本控制外，还可以考虑为 S3 启用对象锁定，为 GCS 或 Azure 启用软删除。

使用 repo-target-time 时，必须同时指定 repo 选项。并非所有仓库类型都支持版本控制，通常针对单个仓库进行恢复最为合理。

注意，时间戳比较使用 <= 关系，且提供的时间戳中的毫秒部分会被截断。

YAML
example: --repo-target-time=2024-08-08 12:12:12+00

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure — Azure Blob 存储服务
  • cifs — 类似 posix，但禁用链接和目录 fsync
  • gcs — Google Cloud 存储
  • posix — 符合 POSIX 规范的文件系统
  • s3 — AWS 简单存储服务
  • sftp — 安全文件传输协议

将 NFS 挂载用作 posix 类型仓库时，适用于 pgBackRest 的规则与 PostgreSQL 文档中的描述相同，详见 Creating a Database Cluster - File Systems。

YAML
default: posix
example: --repo1-type=cifs

4.20 - 版本命令（version）

pgBackRest version 命令的选项与行为参考。

原始页面： pgBackRest Command Docs: version

显示已安装的 pgBackRest 版本。

命令选项

输出格式选项（--output）

输出类型。

支持以下输出类型：

  • text — 以文本形式显示已安装的 pgBackRest 版本。
  • num — 以整数形式显示已安装的 pgBackRest 版本。
YAML
default: text
example: --output=num

5 - 配置参考

pgBackRest 完整配置参考，涵盖归档、备份、仓库、云存储等所有配置项。

原始页面： https://pgbackrest.org/configuration.html

简介

pgBackRest 可以完全通过命令行参数使用，但当配置较为复杂或需要设置大量选项时，使用配置文件更为实用。配置文件的默认路径为 /etc/pgbackrest/pgbackrest.conf。若该路径下不存在配置文件，则会检查旧的默认路径 /etc/pgbackrest.conf。

以下是支持的选项类型：

String（字符串）：文本字符串，常见用途包括标识符、密码等。

命令行示例：--stanza=demo
配置文件示例：repo1-cipher-pass=zWaf6XtpjIVZC5444yXB...

Path（路径）：用于唯一标识目录结构中某个位置。路径必须以 / 开头，不允许使用双斜杠 //，且末尾不应有 /。

命令行示例：--repo1-path=/var/lib/pgbackrest
配置文件示例：repo1-path=/var/lib/pgbackrest

Boolean（布尔值）：启用或禁用某个选项。参数值只接受 y 或 n。

命令行示例：--start-fast、--no-start-fast、--start-fast=y、--start-fast=n
配置文件示例：start-fast=y、start-fast=n

Integer（整数）：用于端口号、保留策略/重试次数、并行进程数等。

命令行示例：--compress-level=3
配置文件示例：pg1-port=5432

Size（大小）：用于缓冲区大小、磁盘用量等。大小可以字节（默认）或 KiB、MiB、GiB、TiB、PiB 为单位，倍数为 1024 的幂次。例如，不区分大小写的值 5GiB（或 5GB、5g）等同于 5368709120。不允许使用小数值（如 2.5GiB），请改用 2560MiB。

命令行示例：--archive-get-queue-max=1GiB
配置文件示例：buffer-size=2MiB

Time（时间）：以秒为单位的时间值。

命令行示例：--io-timeout=90
配置文件示例：db-timeout=600

List（列表）：该选项可指定多次。

命令行示例：--db-exclude=db1 --db-exclude=db2 --db-exclude=db5
配置文件示例，每项单独占一行：db-exclude=db1 db-exclude=db2 db-exclude=db5

Key/Value（键值对）：该选项可以 key=value 的形式指定多次。

命令行示例：--tablespace-map=ts_01=/db/ts_01 --tablespace-map=ts_02=/db/ts_02
配置文件示例，每项单独占一行：tablespace-map=ts_01=/db/ts_01 tablespace-map=ts_02=/db/ts_02

归档选项

archive 部分定义了 archive-push 和 archive-get 命令的选项。

异步归档选项（--archive-async）

以异步方式推送/获取 WAL 段。

为 archive-push 和 archive-get 命令启用异步操作。

异步操作效率更高，可复用连接并利用并行处理优势。详情请参阅 spool-path、archive-get-queue-max 和 archive-push-queue-max 选项。

TEXT
default: n
example: archive-async=y

最大 archive-get 队列大小选项（--archive-get-queue-max）

archive-get 队列的最大容量。

启用 archive-async 时，指定 archive-get 队列的最大大小。队列存储在 spool-path 中，用于加速向 PostgreSQL 提供 WAL。

TEXT
default: 128MiB
allowed: [0B, 4PiB]
example: archive-get-queue-max=1GiB

重试缺失 WAL 段选项（--archive-missing-retry）

重试缺失的 WAL 段。

在异步模式下，对之前由 archive-get 命令报告为缺失的 WAL 段进行重试。这可以防止将缓冲区路径中来自先前恢复操作的通知文件用于当前操作，从而避免在尚未达到一致性时导致恢复失败。

禁用此选项可让 PostgreSQL 更可靠地识别归档中 WAL 的末尾，从而切换到从主库进行流式复制。若持续启用重试，连续不断的 WAL 归档流会导致 PostgreSQL 继续从归档获取 WAL，而不是切换到流式复制。

禁用此选项时，务必确保 stanza 的缓冲区路径为空。若在恢复时配置了缓冲区路径，restore 命令会自动清空该路径；否则需要用户手动清空。

TEXT
default: y
example: archive-missing-retry=n

归档推送批量大小选项（--archive-push-batch-size）

每轮异步执行可推送的最大 WAL 量。

在异步模式下，archive-push 进程会在单轮执行中推送所有已就绪的 WAL 段。由于 archive-push-queue-max 只在每轮开始时检查，若单轮处理的 WAL 段数量非常多，队列可能在再次检查前增长到远超限制。

此选项限制每轮处理的 WAL 量，使进程退出，并由下一次 archive-push 再次启动，从而重新检查队列。较小的值会更频繁地检查队列，但代价是更频繁地启动异步进程。该值会向下取整为 WAL 段大小的整数倍，但每轮至少会处理一个 WAL 段。

TEXT
default: 16GiB
allowed: [1MiB, 4PiB]
example: archive-push-batch-size=1GiB

最大 archive-push 队列大小选项（--archive-push-queue-max）

PostgreSQL 归档队列的最大大小。

达到限制后，将发生以下情况：

  • pgBackRest 会通知 PostgreSQL WAL 已成功归档，然后将其 丢弃。
  • 会在 PostgreSQL 日志中输出一条警告。

若发生此情况，归档日志流将被中断，此后将无法执行 PITR。需要执行新的备份才能恢复完整的恢复能力。

在异步模式下会丢弃整个队列，以防队列再次超过上限前仍有零星 WAL 段进入归档。

在异步模式下，此限制仅在每轮 archive-push 开始时检查，因此单轮执行期间队列可能增长到超过此限制。可减小 archive-push-batch-size，以更频繁地检查队列。

此功能的目的是防止日志卷被写满——日志卷写满会导致 PostgreSQL 完全停止。宁可丢失备份，也好过让 PostgreSQL 宕机。

TEXT
allowed: [0B, 4PiB]
example: archive-push-queue-max=1TiB

已弃用名称：archive-queue-max

归档超时选项（--archive-timeout）

归档超时时间。

设置等待每个 WAL 段到达 pgBackRest 归档仓库的最长时间（秒）。该超时适用于 check 和 backup 命令等待备份一致性所需的 WAL 段完成归档的场景。

TEXT
default: 1m
allowed: [100ms, 1d]
example: archive-timeout=30

备份选项

backup 部分定义了与备份相关的设置。

备份注解选项（--annotation）

为备份附加用户自定义键值对注解。

用户可为备份附加信息性键值对。此选项可多次使用，以添加多条注解。

注解会在 info 命令通过 --set 指定备份时以文本形式输出，并始终出现在 JSON 输出中。

TEXT
example: annotation=source="Sunday backup for website database"

归档检查选项（--archive-check）

在备份完成前检查 WAL 段是否已存在于归档中。

检查使备份一致所需的所有 WAL 段是否都已存在于 WAL 归档中。除非使用了其他归档方式，否则建议保留默认值。

若启用了 archive-copy，则必须同时启用此选项。

TEXT
default: y
example: archive-check=n

归档复制选项（--archive-copy）

将保证一致性所需的 WAL 段复制到备份中。

此选项较为严格，通过将保证备份一致性所需的 WAL 段直接存储在备份中，防止因 WAL 段归档损坏而导致问题。WAL 段仍会存储在归档中，因此该选项会占用额外空间。

使用此选项时，最好让 archive-push 和 backup 命令使用相同的 compress-type（如 lz4）。否则，WAL 段需要使用备份所用的 compress-type 重新压缩，根据备份期间生成的 WAL 量，这可能代价较高。

恢复时，WAL 段将出现在 pg_xlog/pg_wal 中，PostgreSQL 会优先使用它们，而不是调用 restore_command。

若启用了 archive-copy，则必须同时启用 archive-check 选项。

TEXT
default: n
example: archive-copy=y

归档模式检查选项（--archive-mode-check）

检查 PostgreSQL 的 archive_mode 设置。

默认启用，此选项禁止 PostgreSQL 使用 archive_mode=always。

从备库推送的 WAL 段在逻辑上可能与从主库推送的 WAL 段相同，但校验和不同。为避免冲突，建议禁止来自多个来源的归档。

注意：

若禁用此选项，则必须确保只有一个归档进程通过 archive-push 命令向仓库写入数据。

TEXT
default: y
example: archive-mode-check=n

从备库备份选项（--backup-standby）

从备库执行备份。

启用从备库备份，以降低主库负载。此选项要求同时配置主库和备库主机。

支持以下模式：

  • y - 备份必须从备库执行。
  • prefer - 优先从备库备份，若备库不可用则从主库备份。
  • n - 仅从主库备份。
TEXT
default: n
example: backup-standby=y

页面校验和选项（--checksum-page）

验证数据页面校验和。

指示 pgBackRest 在备份集群时验证所有数据页面的校验和。当集群启用了数据页面校验和时，此选项会自动启用。

校验和验证失败不会中止备份，而是会在日志中（以及使用默认设置时在控制台中）输出警告，并将无效页面列表存储在备份的清单文件（manifest）中。

TEXT
example: checksum-page=n

路径/文件排除选项（--exclude）

从备份中排除路径或文件。

所有排除路径均相对于 $PGDATA。若排除路径以 / 结尾，则仅排除指定目录中的文件，例如 --exclude=junk/ 将排除 $PGDATA/junk 目录中的所有文件，但保留该目录本身。若排除路径不以 / 结尾，则文件名可以精确匹配该排除路径，或匹配在其后追加 / 的路径，例如 --exclude=junk 将排除 $PGDATA/junk 目录及其所有文件。

请谨慎使用此功能——非常容易误排除关键内容而导致备份不一致。务必测试你的恢复流程！

所有被排除的文件都会以 info 级别记录到日志中，并附带排除规则。请务必审查被排除文件的列表，确认没有意外排除任何内容。

注意：

delta 恢复中不遵守排除规则。备份中被排除的文件/目录在 delta 恢复时将被 删除。

不建议使用此选项来排除 PostgreSQL 日志文件。可以通过 PostgreSQL 的 log_directory 设置将日志移出 PGDATA 目录，这还有一个好处，即恢复后日志仍可保留。

可以在命令行或配置文件中指定多个排除规则。

TEXT
example: exclude=junk/

自动过期选项（--expire-auto）

在成功备份后自动执行 expire 命令。

此设置默认启用。禁用时请谨慎，因为这将导致所有备份和归档被无限期保留，可能耗尽仓库空间。禁用后需定期手动执行 expire 命令以防止此情况发生。

成功备份后自动执行 expire 时，会使用 backup 命令的配置，因此仅设置在 expire 命令配置节（例如 [global:expire]）中的选项不会生效。若要应用 expire 专用配置，请禁用此选项并单独运行 expire 命令。

TEXT
default: y
example: expire-auto=y

清单保存阈值选项（--manifest-save-threshold）

备份期间保存清单文件（manifest）的阈值。

定义备份过程中清单文件的保存频率。定期保存清单文件非常重要，因为它存储了校验和信息，使断点续传功能能够高效工作。实际使用的阈值为备份大小的 1% 与 manifest-save-threshold 中的较大值。

TEXT
default: 1GiB
allowed: [1B, 1TiB]
example: manifest-save-threshold=8GiB

断点续传选项（--resume）

允许从失败的备份处断点续传。

定义是否启用断点续传功能。断点续传可以大幅减少在相同类型的上一次备份失败后重新执行备份所需的时间。但它也增加了复杂性，因此在不需要此功能的环境中可以选择禁用。

TEXT
default: y
example: resume=n

快速启动选项（--start-fast）

强制执行检查点以快速启动备份。

通过强制执行检查点（向备份启动函数的 fast 参数传入 y），使备份立即开始，而不是等待下一个常规检查点。

TEXT
default: n
example: start-fast=y

通用选项

general 部分定义了许多命令共用的选项。

允许以 root 用户运行选项（--allow-root）

允许命令以 root 用户运行。

默认情况下，仅 restore 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

TEXT
default: n
example: allow-root=y

缓冲区大小选项（--buffer-size）

I/O 操作的缓冲区大小。

用于复制、压缩、加密及其他操作的缓冲区大小。实际使用的缓冲区数量取决于具体选项，每个操作可能会使用额外内存，例如 gz 压缩可能额外使用 256KiB 内存。

允许的值为：16KiB、32KiB、64KiB、128KiB、256KiB、512KiB、1MiB、2MiB、4MiB、8MiB 和 16MiB。

TEXT
default: 1MiB
example: buffer-size=2MiB

pgBackRest 命令选项（--cmd）

pgBackRest 可执行文件路径。

pgBackRest 在某些情况下需要生成命令字符串，例如 restore 命令生成 restore_command 设置时。此时将使用运行 pgBackRest 进程的命令，除非显式提供了 cmd 选项。

注意：

对 pgBackRest 命令进行包装可能导致不可预期的行为，不建议这样做。

TEXT
default: [path of executed pgbackrest binary]
example: cmd=/var/lib/pgsql/bin/pgbackrest_wrapper.sh

SSH 客户端命令选项（--cmd-ssh）

SSH 客户端命令。

当需要使用特定的 SSH 客户端，或 ssh 命令不在 $PATH 中时，使用此选项指定 SSH 客户端命令。

TEXT
default: ssh
example: cmd-ssh=/usr/bin/ssh

压缩选项（--compress）

启用文件压缩。

备份文件与命令行压缩工具兼容。

此选项已弃用，请改用 compress-type 选项。

TEXT
default: y
example: compress=n

压缩级别选项（--compress-level）

文件压缩级别。

当 compress-type 不等于 none 或使用（已弃用的）compress=y 时，设置文件压缩所使用的级别。

TEXT
default (depending on compress-type):
   bz2 - 9
   gz - 6
   lz4 - 1
   zst - 3

allow range (depending on compress-type):
   bz2 - [1, 9]
   gz - [-1, 9]
   lz4 - [-5, 12]
   zst - [-7, 22]

example: compress-level=9

网络压缩级别选项（--compress-level-network）

网络传输压缩级别。

当 compress-type=none 且命令不在与仓库相同的主机上运行时，设置网络传输的压缩级别，以减少网络流量。当 compress-type 不等于 none 时，此设置将被忽略，改用 compress-level，从而只对文件压缩一次。

TEXT
default: 1
allowed: [-5, 12]
example: compress-level-network=1

压缩类型选项（--compress-type）

文件压缩类型。

支持以下压缩类型：

  • none - 不压缩
  • bz2 - bzip2 压缩格式
  • gz - gzip 压缩格式
  • lz4 - lz4 压缩格式（并非所有平台均可用）
  • zst - Zstandard 压缩格式（并非所有平台均可用）
TEXT
default: gz
example: compress-type=none

数据库超时选项（--db-timeout）

数据库查询超时时间。

设置对数据库执行查询的超时时间（秒）。这包括备份启动/停止函数，这些函数各自可能耗费相当长的时间。因此，除非确信这些函数会快速返回（例如设置了 start-fast=y 且数据库集群在备份期间不会生成大量 WAL 段），否则应将此超时设置得较大。

注意：

db-timeout 选项的值必须小于 protocol-timeout 选项的值。

TEXT
default: 30m
allowed: [100ms, 7d]
example: db-timeout=600

Delta 选项（--delta）

使用校验和进行恢复或备份。

执行恢复时，默认情况下 PostgreSQL 数据目录和表空间目录应已存在但为空。启用此选项后将使用校验和执行 delta 恢复。

执行备份时，此选项将使用校验和而非时间戳来判断文件是否需要复制。

TEXT
default: n
example: delta=y

I/O 超时选项（--io-timeout）

I/O 超时时间。

用于连接及读写操作的超时时间（秒）。

注意，整个读写操作不需要在此超时时间内完成，但必须有 一定 进展，哪怕只是传输了一个字节。

TEXT
default: 1m
allowed: [100ms, 1h]
example: io-timeout=120

锁文件路径选项（--lock-path）

锁文件存储路径。

pgBackRest 将锁文件存放在此路径下，以防止并发运行相互冲突的操作。

TEXT
default: /tmp/pgbackrest
example: lock-path=/backup/db/lock

中性 umask 选项（--neutral-umask）

使用中性 umask。

将 umask 设置为 0000，使仓库中的文件和目录以合理的权限创建。默认目录权限为 0750，默认文件权限为 0640。

若要使用运行用户自身的 umask，请在配置文件中指定 neutral-umask=n，或在命令行中使用 --no-neutral-umask。

TEXT
default: y
example: neutral-umask=n

设置进程优先级选项（--priority）

设置进程优先级（nice 值）。

定义内核调度器为进程分配的优先级（即 nice 值）。正值降低优先级，负值提高优先级。大多数情况下，进程没有权限提高自身优先级。

TEXT
allowed: [-20, 19]
example: priority=19

最大进程数选项（--process-max）

用于压缩/传输的最大进程数。

每个进程都会执行压缩和传输操作以加快命令运行速度，但不要将 process-max 设置得过高，以免影响数据库性能。

TEXT
default: 1
allowed: [1, 999]
example: process-max=4

协议超时选项（--protocol-timeout）

协议超时时间。

设置本地或远程进程在协议层等待接收新消息的超时时间（秒），以防止进程无限期地等待消息。

注意：

protocol-timeout 选项的值必须大于 db-timeout 选项的值。

TEXT
default: 31m
allowed: [100ms, 7d]
example: protocol-timeout=630

保持连接活跃选项（--sck-keep-alive）

启用 keep-alive。

在套接字连接上启用 keep-alive 消息。

TEXT
default: y
example: sck-keep-alive=n

缓冲区路径选项（--spool-path）

临时数据存储路径。

此路径用于存储异步 archive-push 和 archive-get 命令的数据。

异步 archive-push 命令在成功将 WAL 存储到归档后，会向缓冲区路径写入确认信息（失败时写入错误信息），以便前台进程快速通知 PostgreSQL。确认文件非常小（成功时为零字节，错误时为几百字节）。

异步 archive-get 命令会将 WAL 缓存到缓冲区路径，以便在 PostgreSQL 请求时快速提供。当缓冲区路径与 pg_xlog/pg_wal 在同一文件系统上时，文件传输效率最高。但不建议将缓冲区路径放置在 pg_xlog/pg_wal 目录 内部，这可能会给 pg_rewind 等 PostgreSQL 工具带来问题。

存储在缓冲区路径中的数据并非严格意义上的临时数据，因为它可以且应该在系统重启后保留。但缓冲区路径中的数据丢失也不会造成问题——pgBackRest 只需重新检查每个 WAL 段，以确保 archive-push 操作安全归档，并为 archive-get 重建队列。

缓冲区路径应位于本地 Posix 兼容文件系统上，而非 NFS 或 CIFS 等远程文件系统。

TEXT
default: /var/spool/pgbackrest
example: spool-path=/backup/db/spool

keep-alive 计数选项（--tcp-keep-alive-count）

keep-alive 探测包数量。

指定在连接被认为断开之前，可以丢失的 TCP keep-alive 消息数量。

此选项在支持 TCP_KEEPCNT 套接字选项的系统上可用。

TEXT
allowed: [1, 32]
example: tcp-keep-alive-count=3

keep-alive 空闲时间选项（--tcp-keep-alive-idle）

keep-alive 空闲等待时间。

指定在没有网络活动的情况下，操作系统发送 TCP keep-alive 消息之前的等待时间（秒）。

此选项在支持 TCP_KEEPIDLE 套接字选项的系统上可用。

TEXT
allowed: [1, 3600]
example: tcp-keep-alive-idle=60

keep-alive 间隔选项（--tcp-keep-alive-interval）

keep-alive 重传间隔时间。

指定在未收到确认的情况下，TCP keep-alive 消息被重新发送之前的等待时间（秒）。

此选项在支持 TCP_KEEPINTVL 套接字选项的系统上可用。

TEXT
allowed: [1, 900]
example: tcp-keep-alive-interval=30

TLSv1.2 密码套件选项（--tls-cipher-12）

允许的 TLSv1.2 密码套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，连接到对象存储（如 S3）也会加密。

注意：

任何传输连接的最低安全级别为 TLSv1.2。

可以根据需要调整可接受的密码套件。除非有特定的安全要求，示例中的值是合理的选择。若未设置（默认），则使用底层 OpenSSL 库的默认值。

TEXT
example: tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL

TLSv1.3 密码套件选项（--tls-cipher-13）

允许的 TLSv1.3 密码套件。

pgBackRest 客户端与服务端之间的所有 TLS 连接均已加密。默认情况下，连接到对象存储（如 S3）也会加密。

注意：

任何传输连接的最低安全级别为 TLSv1.2。

可以根据需要调整可接受的密码套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

TEXT
example: tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

日志选项

log 部分定义了与日志相关的设置。

注意：

Trace 级别日志可能会暴露密钥和密码等敏感信息，请谨慎使用！

控制台日志级别选项（--log-level-console）

控制台日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详细信息、信息、警告和错误
  • debug - 记录调试、详细信息、信息、警告和错误
  • trace - 记录追踪（非常详细的调试）、调试、信息、警告和错误
TEXT
default: warn
example: log-level-console=error

文件日志级别选项（--log-level-file）

文件日志级别。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详细信息、信息、警告和错误
  • debug - 记录调试、详细信息、信息、警告和错误
  • trace - 记录追踪（非常详细的调试）、调试、信息、警告和错误
TEXT
default: info
example: log-level-file=debug

标准错误日志级别选项（--log-level-stderr）

stderr 日志级别。

指定哪些日志级别将输出到 stderr 而不是 stdout（由 log-level-console 指定）。输出到 stderr 的日志不包含时间戳和进程信息。

支持以下日志级别：

  • off - 不记录任何日志（不推荐）
  • error - 仅记录错误
  • warn - 记录警告和错误
  • info - 记录信息、警告和错误
  • detail - 记录详细信息、信息、警告和错误
  • debug - 记录调试、详细信息、信息、警告和错误
  • trace - 记录追踪（非常详细的调试）、调试、信息、警告和错误
TEXT
default: off
example: log-level-stderr=error

日志路径选项（--log-path）

日志文件存储路径。

pgBackRest 将日志文件存放在此路径下。注意，若 log-level-file=off，则不需要日志路径。

TEXT
default: /var/log/pgbackrest
example: log-path=/backup/db/log

子进程日志选项（--log-subprocess）

启用子进程日志记录。

为此进程创建的所有子进程启用文件日志记录，日志级别由 log-level-file 指定。

TEXT
default: n
example: log-subprocess=y

日志时间戳选项（--log-timestamp）

启用日志时间戳。

在控制台和文件日志中启用时间戳。此选项在生成文档等特殊情况下会被禁用。

TEXT
default: y
example: log-timestamp=n

维护者选项

维护者选项旨在支持 PostgreSQL 分支版本。正确的设置应由分支维护者确定，然后告知该分支的用户。

警告：

不当使用这些选项可能导致意外行为或数据损坏。

分支维护者有责任使用所需选项测试 pgBackRest 的兼容性。pgBackRest 不保证与任何分支版本的兼容性。

WAL 头部检查选项（--archive-header-check）

检查 WAL 头部中的 PostgreSQL 版本/ID。

默认启用，此选项会将 WAL 头部与 PostgreSQL 版本和系统标识符进行比对，以确保 WAL 被复制到正确的 stanza。这是在检查 pg_control 与 stanza 的匹配性、以及验证 WAL 来自 pg_control 所在的同一 PostgreSQL 数据目录之外的额外校验。

因此，禁用此检查相对安全，但仅在必要时才应禁用，例如 WAL 已加密的情况。

TEXT
default: y
example: archive-header-check=n

页头检查选项（--page-header-check）

检查 PostgreSQL 页头。

默认启用，此选项添加页头检查。

除非必要（例如页面已加密），否则应避免禁用此选项。

TEXT
default: y
example: page-header-check=n

强制 PostgreSQL 版本选项（--pg-version-force）

强制指定 PostgreSQL 版本。

使用指定的 PostgreSQL 版本，而不是通过读取 pg_control 或 WAL 头部自动检测的版本。主要适用于 PostgreSQL 分支版本或开发版本，这些版本中的值可能与发行版本不同。PostgreSQL 通过 server_version_num 报告的版本必须与强制指定的版本匹配。

警告：

使用此选项时请谨慎，因为 pg_control 和 WAL 头部仍将按照指定版本的预期格式（即官方开源 PostgreSQL 版本的格式）进行读取。如果分支或开发版本更改了 pgBackRest 所依赖字段的格式，将导致意外行为。总体而言，此选项只有在分支将所有自定义结构成员添加在标准 PostgreSQL 成员 之后 时，才能按预期工作。

TEXT
example: pg-version-force=15

仓库选项

repository 部分定义了用于配置仓库的选项。

索引：所有 repo- 选项均带有索引，以支持配置多个仓库。例如，单个仓库通过 repo1-path、repo1-host 等选项进行配置。若配置了多个仓库且命令未指定 --repo 选项，则按优先级从高到低依次操作各仓库（例如先 repo1 再 repo2）。

repo-retention-* 选项定义备份的保留时长。过期操作仅在完整备份数量超过允许的保留数量时才会发生。换言之，若 repo1-retention-full-type 设置为 count（默认），且 repo1-retention-full 设置为 2，则必须存在 3 个完整备份才会使最旧的备份过期。若 repo1-retention-full-type 设置为 time，则 repo1-retention-full 表示天数，只有当全量备份的累计天数超过此值时才会触发过期。请确保始终为"保留数量 + 1"个备份预留足够的存储空间。

Azure 仓库账户选项（--repo-azure-account）

Azure 仓库账户。

用于存储仓库的 Azure 账户。

TEXT
example: repo1-azure-account=pg-backup

Azure 仓库容器选项（--repo-azure-container）

Azure 仓库容器。

用于存储仓库的 Azure 容器。

通过设置 repo-path=/，pgBackRest 仓库可以存储在容器根目录下，但通常最好指定一个前缀（如 /repo），以便日志和其他 Azure 生成的内容也能存储在该容器中。

TEXT
example: repo1-azure-container=pg-backup

Azure 仓库端点选项（--repo-azure-endpoint）

Azure 仓库端点。

用于连接 Blob 服务的端点。除非使用 Azure Government，否则默认值通常是正确的。

对于自定义/测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 等选项可能很有用。

TEXT
default: blob.core.windows.net
example: repo1-azure-endpoint=blob.core.usgovcloudapi.net

Azure 仓库密钥选项（--repo-azure-key）

Azure 仓库密钥。

根据 repo-azure-key-type 选项的设置，此选项为共享密钥或共享访问签名。

TEXT
example: repo1-azure-key=T+9+aov82qNhrcXSNGZCzm9mjd4d75/oxxOr6r1JVpgTLA==

Azure 仓库密钥类型选项（--repo-azure-key-type）

Azure 仓库密钥类型。

支持以下授权类型：

  • shared - 共享密钥
  • sas - 共享访问签名
  • auto - 使用 Azure 托管标识自动授权
TEXT
default: shared
example: repo1-azure-key-type=sas

Azure 仓库 URI 风格选项（--repo-azure-uri-style）

Azure URI 风格。

支持以下 URI 风格：

  • host - 连接到 account.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加账户前缀。
TEXT
default: host
example: repo1-azure-uri-style=path

块增量备份选项（--repo-block）

启用块级增量备份。

块级备份通过将文件拆分为可独立备份的块，实现更细粒度的备份。这可以节省仓库空间，并在 delta 恢复时提升性能，因为可以直接获取单个块而无需从仓库读取整个文件。

注意：

必须先启用 repo-bundle 选项，才能启用 repo-block。

文件的块大小根据文件大小和存在时间确定。通常，较旧/较大的文件会获得更大的块大小。若文件足够旧，则不会使用块级增量备份。

块级增量备份在为所有备份类型（包括全量备份）启用时效率最高。这会使全量备份稍大，但后续的差异备份和增量备份可以利用全量备份生成的块映射来节省空间。

TEXT
default: n
example: repo1-block=y

仓库包（Bundle）选项（--repo-bundle）

在仓库中将文件打包。

将较小的文件打包（合并）在一起，以减少写入仓库的文件总数。写入更少的文件通常效率更高，尤其是在 S3 等对象存储上。此外，零字节文件不会被存储（清单文件中除外），从而节省时间和空间。

TEXT
default: n
example: repo1-bundle=y

仓库包大小限制选项（--repo-bundle-limit）

文件包的大小上限。

指定将被纳入包中的文件大小上限。超过此大小的文件将单独存储。

打包后的文件在备份断点续传时无法被复用，因此此选项控制哪些文件可以断点续传——较高的值意味着可续传的文件更少。

TEXT
default: 2MiB
allowed: [8KiB, 1PiB]
example: repo1-bundle-limit=10MiB

仓库包目标大小选项（--repo-bundle-size）

文件包的目标大小。

定义单个包所容纳文件的目标总大小。未压缩的包大小最大可能达到 repo-bundle-size + repo-bundle-limit，因此不要将此选项设置为文件系统允许的最大值。

通常不建议将此选项设置得过高，因为重试时需要重新执行整个包的操作。

TEXT
default: 20MiB
allowed: [1MiB, 1PiB]
example: repo1-bundle-size=10MiB

仓库加密密码选项（--repo-cipher-pass）

仓库加密密码。

用于加密/解密仓库文件的密码。

注意：

未指定 stanza 选项运行时，info 命令只从 global 配置节读取加密设置。若按 stanza 配置了加密设置，读取加密 stanza 时必须为 info 命令指定 stanza 选项。

TEXT
example: repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO

仓库加密类型选项（--repo-cipher-type）

仓库加密算法类型。

支持以下加密类型：

  • none - 仓库不加密
  • aes-256-cbc - 256 位密钥长度的高级加密标准

注意，即使仓库类型（如 S3）支持加密，加密操作始终在客户端执行。

TEXT
default: none
example: repo1-cipher-type=aes-256-cbc

GCS 仓库存储桶选项（--repo-gcs-bucket）

GCS 仓库存储桶。

用于存储仓库的 GCS 存储桶。

通过设置 repo-path=/，pgBackRest 仓库可以存储在存储桶根目录下，但通常最好指定一个前缀（如 /repo），以便日志和其他 GCS 生成的内容也能存储在该存储桶中。

TEXT
example: repo1-gcs-bucket=/pg-backup

GCS 仓库端点选项（--repo-gcs-endpoint）

GCS 仓库端点。

用于连接存储服务的端点。可以更新为使用本地 GCS 服务器或备用端点。

TEXT
default: storage.googleapis.com
example: repo1-gcs-endpoint=localhost

GCS 仓库密钥选项（--repo-gcs-key）

GCS 仓库密钥。

根据 repo-gcs-key-type 选项的设置，此选项为令牌或服务密钥文件。

TEXT
example: repo1-gcs-key=/etc/pgbackrest/gcs-key.json

GCS 仓库密钥类型选项（--repo-gcs-key-type）

GCS 仓库密钥类型。

支持以下授权类型：

  • auto - 使用实例服务账户授权。
  • service - 使用本地存储的服务账户密钥。
  • token - 用于本地测试，例如 fakegcs。

当 repo-gcs-key-type=service 时，身份验证令牌续期时将重新加载凭据。

TEXT
default: service
example: repo1-gcs-key-type=auto

GCS 仓库项目 ID 选项（--repo-gcs-user-project）

GCS 项目 ID。

用于确定请求计费的 GCS 项目 ID。

TEXT
example: repo1-gcs-user-project=my-project

仓库硬链接选项（--repo-hardlink）

在仓库中为备份之间的文件创建硬链接。

为差异备份和增量备份中的文件与其对应的全量备份启用硬链接。这在文件系统层面使每个备份看起来都像一个全量备份。但请注意，修改硬链接的文件会影响集合中的所有备份。

TEXT
default: n
example: repo1-hardlink=y

已弃用名称：hardlink

仓库主机选项（--repo-host）

远程操作时的仓库主机。

若备份和归档到本地挂载的文件系统，则不需要此设置。

TEXT
example: repo1-host=repo1.domain.com

已弃用名称：backup-host

仓库主机证书颁发机构文件选项（--repo-host-ca-file）

仓库主机证书颁发机构文件。

连接到仓库主机时，使用非系统默认的 CA 文件。

TEXT
example: repo1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

仓库主机证书颁发机构路径选项（--repo-host-ca-path）

仓库主机证书颁发机构路径。

连接到仓库主机时，使用非系统默认的 CA 路径。

TEXT
example: repo1-host-ca-path=/etc/pki/tls/certs

仓库主机证书文件选项（--repo-host-cert-file）

仓库主机证书文件。

发送给仓库主机以证明客户端身份。

TEXT
example: repo1-host-cert-file=/path/to/client.crt

仓库主机命令选项（--repo-host-cmd）

仓库主机上的 pgBackRest 命令路径。

仅当本地主机和仓库主机上的 pgBackRest 命令路径不同时才需要设置。若未定义，仓库主机命令将与本地命令相同。

TEXT
default: [path of executed pgbackrest binary]
example: repo1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：backup-cmd

仓库主机配置选项（--repo-host-config）

仓库主机上的 pgBackRest 配置文件路径。

设置仓库主机上配置文件的位置。仅当仓库主机上的配置文件与本地配置文件位于不同位置时才需要设置。

TEXT
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: repo1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：backup-config

仓库主机配置包含路径选项（--repo-host-config-include-path）

仓库主机上的 pgBackRest 配置包含路径。

设置仓库主机上配置包含路径的位置。仅当仓库主机上的配置包含路径与本地配置包含路径位于不同位置时才需要设置。

TEXT
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: repo1-host-config-include-path=/conf/pgbackrest/conf.d

仓库主机配置路径选项（--repo-host-config-path）

仓库主机上的 pgBackRest 配置路径。

设置仓库主机上配置路径的位置。仅当仓库主机上的配置路径与本地配置路径位于不同位置时才需要设置。

TEXT
default: CFGOPTDEF_CONFIG_PATH
example: repo1-host-config-path=/conf/pgbackrest

仓库主机密钥文件选项（--repo-host-key-file）

仓库主机密钥文件。

证明客户端证书由所有者发送。

TEXT
example: repo1-host-key-file=/path/to/client.key

仓库主机端口选项（--repo-host-port）

仓库主机端口。

设置 repo-host 时，使用此选项为仓库主机协议指定非默认端口。

注意：

当 repo-host-type=ssh 时，repo-host-port 没有默认值。此时端口将使用 cmd-ssh 指定命令所配置的端口。

TEXT
default (depending on repo-host-type):
   tls - 8432

allowed: [0, 65535]
example: repo1-host-port=25

已弃用名称：backup-ssh-port

仓库主机协议类型选项（--repo-host-type）

仓库主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（Secure Shell）。
  • tls - pgBackRest TLS 服务端。
TEXT
default: ssh
example: repo1-host-type=tls

仓库主机用户选项（--repo-host-user）

仓库主机登录用户。

设置 repo-host 时，定义在仓库主机上执行操作的用户。最好不要使用 postgres 用户，而是使用 pgbackrest 等其他用户。若 PostgreSQL 运行在仓库主机上，可以将 postgres 用户加入 pgbackrest 组，使其对仓库拥有读取权限，同时避免意外损坏仓库内容。

TEXT
default: pgbackrest
example: repo1-host-user=repo-user

已弃用名称：backup-user

仓库路径选项（--repo-path）

备份和归档的存储路径。

仓库是 pgBackRest 存储备份和归档 WAL 段的地方。

提前估算所需空间可能比较困难。最好的方法是先执行一些备份，然后记录不同类型备份（全量/增量/差异）的大小，并测量每天生成的 WAL 量。这可以让你对所需空间有一个大致了解，当然随着数据库的增长，需求也会随时间变化。

TEXT
default: /var/lib/pgbackrest
example: repo1-path=/backup/db/backrest

归档保留选项（--repo-retention-archive）

保留连续 WAL 归档所对应的备份数量。

注意：

使备份保持一致性所需的 WAL 段，无论此选项如何配置，在备份过期之前都会始终保留。

若未设置此值且 repo-retention-full-type 为 count（默认），则归档过期策略将默认使用与 repo-retention-archive-type 对应的 repo-retention-full（或 repo-retention-diff）值（若类型为 full 或 diff）。这将确保 WAL 仅在对应备份已过期后才过期。若 repo-retention-full-type 为 time，则此值将默认删除早于满足 repo-retention-full 设置后所保留的最旧全量备份的归档。

若 repo-retention-archive-type 设置为 incr，则必须设置此选项。若磁盘空间紧张，可以结合 repo-retention-archive-type 使用此选项来积极清理 WAL 段。但这样做会使具有已过期 WAL 的备份无法执行 PITR，因此 不 推荐这样做。

TEXT
allowed: [1, 9999999]
example: repo1-retention-archive=2

已弃用名称：retention-archive

归档保留类型选项（--repo-retention-archive-type）

WAL 归档保留所依据的备份类型。

若设置为 full，pgBackRest 将为 repo-retention-archive 定义的全量备份数量保留归档日志。若设置为 diff（差异），pgBackRest 将为 repo-retention-archive 定义的全量备份和差异备份数量保留归档日志，即若最近一次备份是全量备份，则在计算 repo-retention 时将其视为差异备份。若设置为 incr（增量），pgBackRest 将为 repo-retention-archive 定义的全量、差异和增量备份数量保留归档日志。建议保留此设置的默认值——默认行为仅在全量备份过期时才清理 WAL。

TEXT
default: full
example: repo1-retention-archive-type=diff

已弃用名称：retention-archive-type

差异备份保留选项（--repo-retention-diff）

保留的差异备份数量。

差异备份过期时，与该差异备份关联的所有增量备份也会一并过期。若未定义此选项，则所有差异备份将保留至其依赖的全量备份过期为止。

注意，在计算过期时，全量备份也会被计入差异备份的数量。这在大多数情况下会略微减少需要保留的差异备份数量。

TEXT
allowed: [1, 9999999]
example: repo1-retention-diff=3

已弃用名称：retention-diff

全量备份保留选项（--repo-retention-full）

全量备份保留数量或时间。

全量备份过期时，与该全量备份关联的所有差异和增量备份也会一并过期。若未定义此选项，将发出警告。若希望永久保留，可将此选项设置为最大值。

TEXT
allowed: [1, 9999999]
example: repo1-retention-full=2

已弃用名称：retention-full

全量备份保留类型选项（--repo-retention-full-type）

全量备份的保留类型。

确定 repo-retention-full 设置表示时间周期（天数）还是要保留的全量备份数量。

若设置为 time，则早于 repo-retention-full 天数的全量备份将从仓库中删除，前提是至少还存在另一个满足或超过 repo-retention-full 设置的备份。例如，若 repo-retention-full 为 30（天），且存在两个全量备份：一个 25 天前，一个 35 天前，则不会过期任何全量备份，因为使 35 天前的备份过期将只剩下 25 天前的备份，违反了在过期较旧备份之前至少保留一个 30 天备份的策略。早于保留的最旧全量备份的归档 WAL 将自动过期，除非显式设置了 repo-retention-archive-type 和 repo-retention-archive。

若设置为 count，则超过 repo-retention-full 数量的全量备份将过期。例如，若 repo-retention-full 为 4，完成第五个全量备份后，最旧的全量备份将过期，使数量保持在 4 个。

注意，备份必须成功完成后才会纳入保留计算。例如，若 repo-retention-full-type 为 count 且 repo-retention-full 为 2，则必须有 3 个完整的全量备份，最旧的才会过期。

TEXT
default: count
example: repo1-retention-full-type=time

备份历史保留选项（--repo-retention-history）

备份历史清单的保留天数。

备份完成时，备份清单文件（manifest）的副本将存储在 backup.history 路径中。默认情况下，这些文件永不过期，因为它们对数据分析（例如测量备份和 WAL 的增长趋势）很有价值。

设置 repo-retention-history 以定义保留备份历史清单的天数。未过期的备份始终保留在备份历史中。指定 repo-retention-history=0 仅为未过期的备份保留备份历史。

当全量备份历史清单过期时，与该全量备份关联的所有差异和增量备份历史清单也会一并过期。

TEXT
allowed: [0, 9999999]
example: repo1-retention-history=365

S3 仓库存储桶选项（--repo-s3-bucket）

S3 仓库存储桶。

用于存储仓库的 S3 存储桶。

通过设置 repo-path=/，pgBackRest 仓库可以存储在存储桶根目录下，但通常最好指定一个前缀（如 /repo），以便日志和其他 AWS 生成的内容也能存储在该存储桶中。

TEXT
example: repo1-s3-bucket=pg-backup

S3 仓库端点选项（--repo-s3-endpoint）

S3 仓库端点。

AWS 端点应与所选区域匹配。

对于自定义/测试配置，repo-storage-ca-file、repo-storage-ca-path、repo-storage-host、repo-storage-port 和 repo-storage-verify-tls 等选项可能很有用。

TEXT
example: repo1-s3-endpoint=s3.amazonaws.com

S3 仓库访问密钥选项（--repo-s3-key）

S3 仓库访问密钥。

用于访问此存储桶的 AWS 密钥。

TEXT
example: repo1-s3-key=AKIAIOSFODNN7EXAMPLE

S3 仓库秘密访问密钥选项（--repo-s3-key-secret）

S3 仓库秘密访问密钥。

用于访问此存储桶的 AWS 秘密密钥。

TEXT
example: repo1-s3-key-secret=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

S3 仓库密钥类型选项（--repo-s3-key-type）

S3 仓库密钥类型。

支持以下类型：

  • shared - 共享密钥
  • auto - 自动获取临时凭据
  • web-id - 自动获取 Web 身份凭据
  • pod-id - 自动获取 EKS Pod 身份凭据
  • process - 通过外部进程获取凭据
TEXT
default: shared
example: repo1-s3-key-type=auto

S3 仓库 KMS 密钥 ID 选项（--repo-s3-kms-key-id）

S3 仓库 KMS 密钥。

使用指定的 AWS 密钥管理服务密钥启用 S3 服务端加密。

TEXT
example: repo1-s3-kms-key-id=bceb4f13-6939-4be3-910d-df54dee817b7

S3 认证进程命令选项（--repo-s3-process-cmd）

S3 认证进程命令。

用于获取临时 S3 凭据的命令（以及可选参数）。列表第一项是命令，其余项作为参数传递。

该进程必须输出包含 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration 字段的 JSON。凭据会在到期前自动刷新。有关格式细节，请参阅 进程凭据提供程序。

TEXT
example: repo1-s3-process-cmd=/usr/local/bin/get-credentials
example: repo1-s3-process-cmd=--role
example: repo1-s3-process-cmd=my-role

S3 仓库区域选项（--repo-s3-region）

S3 仓库区域。

创建存储桶所在的 AWS 区域。

TEXT
example: repo1-s3-region=us-east-1

S3 仓库请求者付费选项（--repo-s3-requester-pays）

S3 请求者付费模式。

启用 S3 请求者付费模式。

TEXT
default: n
example: repo1-s3-requester-pays=n

S3 仓库角色选项（--repo-s3-role）

S3 仓库 IAM 角色。

当 repo-s3-key-type=auto 时，用于获取临时凭据的 AWS 角色名称（非完整 ARN）。

TEXT
example: repo1-s3-role=authrole

S3 仓库服务选项（--repo-s3-service）

S3 签名服务。

在 SigV4 认证中使用的 S3 签名服务。标准 S3 端点默认为 s3；使用 S3 Outposts 端点时请设为 s3-outposts。

TEXT
default: s3
example: repo1-s3-service=s3-outposts

S3 仓库 SSE 客户密钥选项（--repo-s3-sse-customer-key）

S3 仓库 SSE 客户密钥。

使用指定的客户密钥启用 S3 服务端加密。

TEXT
example: repo1-s3-sse-customer-key=bceb4f13-6939-4be3-910d-df54dee817b7

S3 仓库 STS 端点选项（--repo-s3-sts-host）

S3 仓库 STS 端点。

配置 repo-s3-key-type=web-id 时，用于获取临时凭据的 STS 端点。可设为区域端点（例如 sts.us-east-1.amazonaws.com）以使用区域 STS；GovCloud、中国区域或需要降低延迟时可能必须这样设置。

TEXT
default: sts.amazonaws.com
example: repo1-s3-sts-host=sts.us-east-1.amazonaws.com

S3 仓库安全令牌选项（--repo-s3-token）

S3 仓库安全令牌。

与临时凭据一起使用的 AWS 安全令牌。

TEXT
example: repo1-s3-token=AQoDYXdzEPT//////////wEXAMPLEtc764bNrC9SAPBSM22 ...

S3 仓库 URI 风格选项（--repo-s3-uri-style）

S3 URI 风格。

支持以下 URI 风格：

  • host - 连接到 bucket.endpoint 主机。
  • path - 连接到 endpoint 主机，并在 URI 中添加存储桶前缀。
TEXT
default: host
example: repo1-s3-uri-style=path

SFTP 仓库主机选项（--repo-sftp-host）

SFTP 仓库主机。

包含仓库的 SFTP 主机。

TEXT
example: repo1-sftp-host=sftprepo.domain

SFTP 仓库主机指纹选项（--repo-sftp-host-fingerprint）

SFTP 仓库主机指纹。

SFTP 仓库主机指纹的生成方式应与 repo-sftp-host-key-hash-type 匹配。可通过 awk '{print $2}' ssh_host_xxx_key.pub | base64 -d | (md5sum or sha1sum) -b 生成指纹。SSH 主机密钥通常位于 /etc/ssh 目录中。

TEXT
example: repo1-sftp-host-fingerprint=f84e172dfead7aeeeae6c1fdfb5aa8cf

SFTP 主机密钥检查类型选项（--repo-sftp-host-key-check-type）

SFTP 主机密钥检查类型。

支持以下 SFTP 主机密钥检查类型：

  • strict - pgBackRest 永远不会自动将主机密钥添加到 ~/.ssh/known_hosts 文件中，并拒绝连接到主机密钥已更改或在已知主机文件中未找到的主机。此选项要求用户手动添加所有新主机。
  • accept-new - pgBackRest 会自动将新主机密钥添加到用户的已知主机文件中，但不允许连接到主机密钥已更改的主机。
  • fingerprint - pgBackRest 将根据 repo-sftp-host-fingerprint 选项指定的指纹检查主机密钥。
  • none - 不执行主机密钥检查。
TEXT
default: strict
example: repo1-sftp-host-key-check-type=accept-new

SFTP 仓库主机密钥哈希类型选项（--repo-sftp-host-key-hash-type）

SFTP 仓库主机密钥哈希类型。

声明在 SSH 启动时用于计算远程系统主机密钥摘要的哈希类型。较新版本的 libssh2 除 md5 和 sha1 外，还支持 sha256。

TEXT
example: repo1-sftp-host-key-hash-type=sha256

SFTP 仓库主机端口选项（--repo-sftp-host-port）

SFTP 仓库主机端口。

TEXT
default: 22
allowed: [1, 65535]
example: repo1-sftp-host-port=22

SFTP 仓库主机用户选项（--repo-sftp-host-user）

SFTP 仓库主机用户。

用于存储仓库的主机上的用户。

TEXT
example: repo1-sftp-host-user=pg-backup

SFTP 已知主机文件选项（--repo-sftp-known-host）

SFTP 已知主机文件。

身份验证期间，在此文件中搜索 SFTP 主机匹配项。若未指定，pgBackRest 默认搜索 ~/.ssh/known_hosts、~/.ssh/known_hosts2、/etc/ssh/ssh_known_hosts 和 /etc/ssh/ssh_known_hosts2。若配置了一个或多个文件路径，pgBackRest 将在这些路径中搜索匹配项。文件路径必须是完整路径或以波浪号开头的路径。此选项可以多次传入，以指定多个已知主机文件进行搜索。要使用已知主机文件检查，不得指定 repo-sftp-host-fingerprint。另请参阅 repo-sftp-host-check-type 选项。

TEXT
example: repo1-sftp-known-host=/home/postgres/.ssh/known_hosts

SFTP 仓库私钥文件选项（--repo-sftp-private-key-file）

SFTP 私钥文件。

用于身份验证的 SFTP 私钥文件。

TEXT
example: repo1-sftp-private-key-file=~/.ssh/id_ed25519

SFTP 仓库私钥密码选项（--repo-sftp-private-key-passphrase）

SFTP 私钥密码。

用于访问私钥的密码。在创建 SSH 公钥/私钥对时，这是一个可选功能。

TEXT
example: repo1-sftp-private-key-passphrase=BeSureToGenerateAndUseASecurePassphrase

SFTP 仓库公钥文件选项（--repo-sftp-public-key-file）

SFTP 公钥文件。

用于身份验证的 SFTP 公钥文件。若针对 OpenSSL 编译，此项为可选；若针对其他库编译，则为必填。

TEXT
example: repo1-sftp-public-key-file=~/.ssh/id_ed25519.pub

仓库存储 CA 文件选项（--repo-storage-ca-file）

仓库存储 CA 文件。

连接存储（如 S3、Azure）时，使用非系统默认的 CA 文件。

TEXT
example: repo1-storage-ca-file=/etc/pki/tls/certs/ca-bundle.crt

已弃用名称：repo-azure-ca-file、repo-s3-ca-file

仓库存储 TLS CA 路径选项（--repo-storage-ca-path）

仓库存储 CA 路径。

连接存储（如 S3、Azure）时，使用非系统默认的 CA 路径。

TEXT
example: repo1-storage-ca-path=/etc/pki/tls/certs

已弃用名称：repo-azure-ca-path、repo-s3-ca-path

仓库存储主机选项（--repo-storage-host）

仓库存储主机。

连接到存储（如 S3、Azure）端点之外的其他主机。通常用于测试。

TEXT
example: repo1-storage-host=127.0.0.1

已弃用名称：repo-azure-host、repo-s3-host

仓库存储端口选项（--repo-storage-port）

仓库存储端口。

连接到存储（如 S3、Azure）端点（或指定主机）时使用的端口。

TEXT
default: 443
allowed: [1, 65535]
example: repo1-storage-port=9000

已弃用名称：repo-azure-port、repo-s3-port

仓库存储标签选项（--repo-storage-tag）

仓库存储标签。

当仓库为对象存储（如 S3）时，指定添加到对象上的标签。可重复使用此选项以添加多个标签。

pgBackRest 没有提供修改这些标签的功能，因此请在运行 stanza-create 之前正确设置，以确保整个仓库的标签统一。

TEXT
example: repo1-storage-tag=key1=value1

仓库存储上传块大小选项（--repo-storage-upload-chunk-size）

仓库存储上传块大小。

当文件过大无法完全存储在内存中时，S3 等对象存储允许分块上传文件。即使文件可以存储在内存中，限制上传所用的内存量也更为高效。

较大的块大小通常可以提升性能，因为它会减少上传请求次数，并允许在单个请求中上传更多文件而非分块上传。缺点是内存使用量会更高——由于块缓冲区需要按进程分配，较大的 process-max 值将导致整体内存消耗更多。

请注意，有效的块大小因存储类型和平台而异。例如，AWS S3 的最小块大小为 5MiB。块大小的术语因存储类型而异，因此在搜索最小/最大值时，AWS S3 使用"part size"，GCS 使用"chunk size"，Azure 使用"block size"。

若文件大于 1GiB（PostgreSQL 默认创建的最大文件大小），则块大小将逐步增加直至允许的最大值，以完成文件上传。

TEXT
default (depending on repo-type):
   azure - 4MiB
   gcs - 4MiB
   s3 - 5MiB

allow range (depending on repo-type):
   azure - [4MiB, 1GiB]
   gcs - [4MiB, 1GiB]
   s3 - [5MiB, 1GiB]

example: repo1-storage-upload-chunk-size=16MiB

仓库存储证书验证选项（--repo-storage-verify-tls）

仓库存储证书验证。

启用或禁用对存储（如 S3、Azure）服务端 TLS 证书的验证。禁用此选项仅应用于测试场景或使用自签名证书的情况。

TEXT
default: y
example: repo1-storage-verify-tls=n

已弃用名称：repo-azure-verify-tls、repo-s3-verify-ssl、repo-s3-verify-tls

仓库符号链接选项（--repo-symlink）

在仓库中创建符号链接。

启用 latest 和表空间符号链接的创建。这些符号链接在使用快照进行原地恢复时最为有用，这是一种不常见的使用场景。

此功能对绝大多数用户可能没有实际用途，但出于历史兼容性原因仍默认启用。对于不支持符号链接的类 Posix 存储，禁用符号链接可能是有益的。

TEXT
default: y
example: repo1-symlink=n

仓库目标时间选项（--repo-target-time）

仓库的目标时间点。

目标时间定义了命令用于读取版本化存储上仓库的时间点。这允许命令以某个历史时间点的视角读取仓库，以恢复被用户误操作或恶意软件删除或损坏的数据。

版本化存储由 S3、GCS 和 Azure 支持，但通常默认不启用。除了启用版本控制外，为 S3 启用对象锁定，以及为 GCS 或 Azure 启用软删除也可能很有用。

指定 repo-target-time 选项时，必须同时提供 repo 选项。通常并非所有仓库类型都支持版本控制，一般建议针对单个仓库进行恢复。

注意，与存储时间戳的比较为小于等于（<=）所提供的时间戳，且提供的时间戳中的毫秒部分将被截断。

TEXT
example: repo-target-time=2024-08-08 12:12:12+00

仓库类型选项（--repo-type）

仓库使用的存储类型。

支持以下仓库类型：

  • azure - Azure Blob 存储服务
  • cifs - 类似 posix，但禁用链接和目录 fsync
  • gcs - Google Cloud Storage
  • posix - 符合 Posix 规范的文件系统
  • s3 - AWS 简单存储服务（Simple Storage Service）
  • sftp - 安全文件传输协议（SFTP）

当使用 NFS 挂载作为 posix 仓库时，适用于 pgBackRest 的规则与 PostgreSQL 文档中描述的相同，请参阅 Creating a Database Cluster - File Systems。

TEXT
default: posix
example: repo1-type=cifs

恢复选项

restore 部分定义了用于恢复备份的设置。

归档模式选项（--archive-mode）

在已恢复的集群上保留或禁用归档。

此选项允许在已恢复的集群上保留或禁用归档。当集群必须被提升以执行某些操作，但不打算成为新的主库时，此选项很有用。在这种情况下，不应从该集群向仓库推送 WAL。

支持以下模式：

  • off - 通过设置 archive_mode=off 禁用归档。
  • preserve - 保留当前的 archive_mode 设置。

注意：此选项在 PostgreSQL 12 以下版本不可用。

TEXT
default: preserve
example: archive-mode=off

排除数据库选项（--db-exclude）

排除指定数据库进行恢复。

被排除的数据库将以稀疏零填充文件的形式恢复，以节省空间，同时仍允许 PostgreSQL 执行恢复。恢复完成后，这些数据库将无法访问，但可以使用 drop database 命令将其删除。此选项可以多次传入，以指定多个要排除的数据库。

与 --db-include 选项一起使用时，--db-exclude 仅适用于标准系统数据库（template0、template1 和 postgres）。

TEXT
example: db-exclude=db_main

包含数据库选项（--db-include）

仅恢复指定的数据库。

此功能允许仅恢复选定的数据库。未明确包含的数据库将以稀疏零填充文件的形式恢复，以节省空间，同时仍允许 PostgreSQL 执行恢复。恢复完成后，未包含的数据库将无法访问，但可以使用 drop database 命令将其删除。

注意：

内置数据库（template0、template1 和 postgres）始终会被恢复，除非被明确排除。

此选项可以多次传入，以指定多个要包含的数据库。

详细信息和注意事项请参阅 选择性数据库恢复。

TEXT
example: db-include=db_main

链接全部选项（--link-all）

恢复所有符号链接。

默认情况下，符号链接的目录和文件在 $PGDATA 中被恢复为普通目录和文件。这是因为在不同于原始备份执行的系统上，将符号链接恢复到其原始目标位置可能不安全。此选项将完全按照原始系统中的状态恢复所有符号链接。

TEXT
default: n
example: link-all=y

链接映射选项（--link-map）

修改符号链接的目标路径。

允许在恢复时更改符号链接的目标文件或路径。当恢复目标系统的存储布局与原始备份系统不同时，此选项很有用。

TEXT
example: link-map=pg_xlog=/data/xlog

恢复选项设置（--recovery-option）

在 postgresql.auto.conf 或 recovery.conf 中设置选项。

有关 postgresql.auto.conf 或 recovery.conf 选项的详情，请参阅 Server Configuration（请选择对应的 PostgreSQL 版本）。此选项可以多次使用。

对于 PostgreSQL >= 12，选项将写入 postgresql.auto.conf。对于所有其他版本，选项将写入 recovery.conf。

注意：

restore_command 选项将自动生成，但可以通过此选项覆盖。请谨慎指定自定义 restore_command，因为 pgBackRest 本身已设计为处理此项。目标恢复选项（recovery_target_name、recovery_target_time 等）由 pgBackRest 自动生成，不应通过此选项设置。

由于 pgBackRest 在写入 postgresql.auto.conf 或 recovery.conf 文件后不会启动 PostgreSQL，因此在手动重启之前，始终可以编辑/检查 postgresql.auto.conf 或 recovery.conf。

TEXT
example: recovery-option=primary_conninfo=db.mydomain.com

表空间映射选项（--tablespace-map）

将表空间恢复到指定目录。

在恢复期间将表空间移动到新位置。当副本或升级后的系统挂载点不同时，此功能很有用。

表空间位置不存储在 pg_tablespace 中，因此可以随意移动表空间。但不建议将表空间移动到 data_directory，这可能会导致问题。有关移动表空间的更多信息，Moving Tablespaces 是一个很好的参考资源。

TEXT
example: tablespace-map=ts_01=/db/ts_01

所有表空间映射选项（--tablespace-map-all）

将所有表空间恢复到指定目录。

默认情况下，表空间被恢复到其原始位置。可以使用 tablespace-map 选项为每个表空间单独修改此行为，但有时将所有表空间一次性重新映射到新目录更为方便。这在开发或测试环境中尤为有用，因为这些环境的存储布局可能与生产环境不同。

指定的路径将作为父路径，用于创建备份中的所有表空间。

注意：

备份启动后创建的表空间将不会被映射。若需要表空间映射，请在创建表空间后执行新的备份。

TEXT
example: tablespace-map-all=/data/tablespace

服务端选项

server 部分定义了用于配置 TLS 服务端的选项。

TLS 服务端地址选项（--tls-server-address）

TLS 服务端监听地址。

服务端监听客户端请求的 IP 地址。

TEXT
default: localhost
example: tls-server-address=*

TLS 服务端授权客户端选项（--tls-server-auth）

TLS 服务端授权客户端列表。

服务端通过验证客户端证书，将客户端证书 CN（Common Name，通用名称）与 tls-server-auth 选项配置的列表进行比对，来完成客户端授权。

可以通过向 tls-server-auth 选项提供逗号分隔的列表，为一个客户端 CN 授权多个 stanza；也可以通过指定 tls-server-auth=client-cn=* 授权所有 stanza。客户端 CN 不支持通配符。

TEXT
example: tls-server-auth=client-cn=stanza1,stanza2

TLS 服务端证书颁发机构选项（--tls-server-ca-file）

TLS 服务端证书颁发机构文件。

验证客户端证书是否由受信任的证书颁发机构签名。

TEXT
example: tls-server-ca-file=/path/to/server.ca

TLS 服务端证书选项（--tls-server-cert-file）

TLS 服务端证书文件。

发送给客户端以展示服务端身份。

TEXT
example: tls-server-cert-file=/path/to/server.crt

TLS 服务端密钥选项（--tls-server-key-file）

TLS 服务端密钥文件。

证明服务端证书由所有者发送。

TEXT
example: tls-server-key-file=/path/to/server.key

TLS 服务端端口选项（--tls-server-port）

TLS 服务端监听端口。

服务端监听客户端请求的端口。

TEXT
default: 8432
allowed: [1, 65535]
example: tls-server-port=8000

Stanza 选项

stanza（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）定义了特定 PostgreSQL 数据库集群的备份配置。stanza 部分必须定义数据库集群路径，若数据库集群为远程，则还需定义主机/用户信息。此外，任何全局配置部分均可被覆盖，以定义 stanza 特定的设置。

索引：所有 pg- 选项均带有索引，以支持配置多个 PostgreSQL 主机。例如，单个主库通过 pg1-path、pg1-port 等选项进行配置。若配置了备库，则在仓库主机上将 pg- 选项索引为 pg2-（如 pg2-host、pg2-path 等）。

PostgreSQL 数据库选项（--pg-database）

连接 PostgreSQL 时使用的数据库名称。

默认值通常是最佳选择，但某些安装可能不包含此数据库。

注意，出于历史兼容性原因，PGDATABASE 环境变量的设置将被忽略。

TEXT
default: postgres
example: pg1-database=backupdb

PostgreSQL 主机选项（--pg-host）

远程操作时的 PostgreSQL 主机。

用于 PostgreSQL 主机与仓库主机不同的备份场景。

TEXT
example: pg1-host=db.domain.com

已弃用名称：db-host

PostgreSQL 主机证书颁发机构文件选项（--pg-host-ca-file）

PostgreSQL 主机证书颁发机构文件。

连接到 PostgreSQL 主机时，使用非系统默认的 CA 文件。

TEXT
example: pg1-host-ca-file=/etc/pki/tls/certs/ca-bundle.crt

PostgreSQL 主机证书颁发机构路径选项（--pg-host-ca-path）

PostgreSQL 主机证书颁发机构路径。

连接到 PostgreSQL 主机时，使用非系统默认的 CA 路径。

TEXT
example: pg1-host-ca-path=/etc/pki/tls/certs

PostgreSQL 主机证书文件选项（--pg-host-cert-file）

PostgreSQL 主机证书文件。

发送给 PostgreSQL 主机以证明客户端身份。

TEXT
example: pg1-host-cert-file=/path/to/client.crt

PostgreSQL 主机命令选项（--pg-host-cmd）

PostgreSQL 主机上的 pgBackRest 命令路径。

仅当本地主机和 PostgreSQL 主机上的 pgBackRest 命令路径不同时才需要设置。若未定义，PostgreSQL 主机命令将与本地命令相同。

TEXT
default: [path of executed pgbackrest binary]
example: pg1-host-cmd=/usr/lib/backrest/bin/pgbackrest

已弃用名称：db-cmd

PostgreSQL 主机配置选项（--pg-host-config）

PostgreSQL 主机上的 pgBackRest 配置文件路径。

设置 PostgreSQL 主机上配置文件的位置。仅当 PostgreSQL 主机上的配置文件与本地配置文件位于不同位置时才需要设置。

TEXT
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: pg1-host-config=/conf/pgbackrest/pgbackrest.conf

已弃用名称：db-config

PostgreSQL 主机配置包含路径选项（--pg-host-config-include-path）

PostgreSQL 主机上的 pgBackRest 配置包含路径。

设置 PostgreSQL 主机上配置包含路径的位置。仅当 PostgreSQL 主机上的配置包含路径与本地配置包含路径位于不同位置时才需要设置。

TEXT
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: pg1-host-config-include-path=/conf/pgbackrest/conf.d

PostgreSQL 主机配置路径选项（--pg-host-config-path）

PostgreSQL 主机上的 pgBackRest 配置路径。

设置 PostgreSQL 主机上配置路径的位置。仅当 PostgreSQL 主机上的配置路径与本地配置路径位于不同位置时才需要设置。

TEXT
default: CFGOPTDEF_CONFIG_PATH
example: pg1-host-config-path=/conf/pgbackrest

PostgreSQL 主机密钥文件选项（--pg-host-key-file）

PostgreSQL 主机密钥文件。

证明客户端证书由所有者发送。

TEXT
example: pg1-host-key-file=/path/to/client.key

PostgreSQL 主机端口选项（--pg-host-port）

PostgreSQL 主机端口。

设置 pg-host 时，使用此选项为 PostgreSQL 主机协议指定非默认端口。

注意：

当 pg-host-type=ssh 时，pg-host-port 没有默认值。此时端口将使用 cmd-ssh 指定命令所配置的端口。

TEXT
default (depending on pg-host-type):
   tls - 8432

allowed: [0, 65535]
example: pg1-host-port=25

已弃用名称：db-ssh-port

PostgreSQL 主机协议类型选项（--pg-host-type）

PostgreSQL 主机协议类型。

支持以下协议类型：

  • ssh - 安全外壳协议（Secure Shell）。
  • tls - pgBackRest TLS 服务端。
TEXT
default: ssh
example: pg1-host-type=tls

PostgreSQL 主机用户选项（--pg-host-user）

PostgreSQL 主机登录用户。

设置 pg-host 时，指定此用户。该用户还将拥有远程 pgBackRest 进程，并将发起到 PostgreSQL 的连接。为使其正常工作，该用户应为 PostgreSQL 数据库集群的所有者，通常为 postgres（即默认值）。

TEXT
default: postgres
example: pg1-host-user=db_owner

已弃用名称：db-user

PostgreSQL 路径选项（--pg-path）

PostgreSQL 数据目录。

应与 PostgreSQL 报告的 data_directory 相同。尽管可以从多处读取此值，但为防止在恢复或离线备份场景中这些资源不可用，建议在配置文件中明确设置。

每次在线备份时，pg-path 选项都会与 PostgreSQL 报告的值进行比对，因此应始终保持最新。

TEXT
example: pg1-path=/data/db

已弃用名称：db-path

PostgreSQL 端口选项（--pg-port）

PostgreSQL 端口。

PostgreSQL 运行的端口。由于大多数 PostgreSQL 集群使用默认端口，通常不需要指定此选项。

TEXT
default: 5432
allowed: [0, 65535]
example: pg1-port=6543

已弃用名称：db-port

PostgreSQL Unix 套接字路径选项（--pg-socket-path）

PostgreSQL Unix 套接字目录路径。

启动 PostgreSQL 时指定的 Unix 套接字目录。pgBackRest 会自动查找操作系统的标准位置，因此通常不需要指定此设置，除非通过 postgresql.conf 中的 unix_socket_directories 显式修改了套接字目录。

TEXT
example: pg1-socket-path=/var/run/postgresql

已弃用名称：db-socket-path

PostgreSQL 数据库用户选项（--pg-user）

连接 PostgreSQL 时使用的数据库用户名。

若未指定，pgBackRest 将使用本地操作系统用户或 PGUSER 进行连接。

TEXT
example: pg1-user=backupuser

6 - 版本发布说明

pgBackRest 版本发布历史，包含每个版本的详细变更日志。

原始页面： https://pgbackrest.org/release.html

简介

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

当前稳定版本

v2.59.0 版本说明

PostgreSQL 19 支持

发布于 2026 年 7 月 20 日

打包者注意：现已提供新的发行版 tarball，其中包含预生成的 HTML 文档、手册页和代码，从而简化构建流程。该 tarball 作为附件随每个版本发布，命名为 pgbackrest-{version}.tar.gz。详情请参阅 tarball 中的 README.md。请使用新的发行版 tarball，以免今后需要额外的构建工具来生成代码。更多信息请参阅 新的发行版 tarball。打包者注意：新增了对 libsystemd 的可选依赖。重要提示：从此版本开始，默认情况下只有 restore 命令允许由 root 用户运行。若要由 root 用户运行其他命令，请使用 allow-root（但不建议这样做）。

漏洞修复：

  • 修复 expire 删除另一台主机上正在进行的备份的问题。（由 Douglas J Hunley 审核，Dmitrii 报告。）
  • 修复 WAL 文件出错时未执行 archive-push-queue-max 限制的问题。（由 Stefan Fercot 审核，vut12 报告。）
  • 修复跨时间线切换恢复期间异步 archive-get 失败的问题。（由 Douglas J Hunley 审核，Jimmy Yih 报告。）
  • 修复错误模块中潜在的缓冲区越界问题。（由 Christophe Pettus 修复，David Steele 审核。）
  • 修复并行协议客户端释放后使用的问题。（由 Douglas J Hunley 审核，Georgy Shelkovy 报告。）
  • 修复未设置 pg1 却设置 pg 选项时发生的堆溢出。（由 Douglas J Hunley 审核，Naveen 报告。）

新功能：

  • 支持 PostgreSQL 19beta2。（由 Stefan Fercot 审核。）
  • 新增 archive-expire-before 选项，用于清理 WAL 归档。（由 Stefan Fercot 贡献，David Steele 审核。）
  • 为 Azure 存储添加批量删除功能。（由 Douglas J Hunley、Crispy 审核。）
  • 添加对 S3 Outposts 的支持。（由 Shiva Kumar Ambigi 贡献，David Steele、Roberto Mello 审核。）
  • 添加 S3 进程认证支持。（由 Andrew Charlton 审核，Andrew Charlton 建议。）

改进：

  • 服务器断开空闲连接后，重新建立 SFTP 存储连接。（由 Stefan Fercot 审核，mustafa0x、tisserat 建议。）
  • 添加用户/组缓存，加快清单构建速度。（由 Gunnar Lindholm 贡献，David Steele 审核。）
  • 在 info 命令输出中添加各仓库的备份进度。（由 Will Morland 贡献，David Steele、Stefan Fercot 审核。）
  • 为 verify 命令添加 backup.info 检查。（由 Denis Garsh 贡献，David Steele、Douglas J Hunley 审核。）
  • 允许配置 S3 STS 端点。（由 Simon Gratton 贡献，David Steele 审核。）
  • 新增 archive-push-batch-size，用于限制每次异步运行推送的 WAL 数据量。（由 Stefan Fercot 审核。）
  • 异步 archive-push 遇到第一个错误时退出。（由 Stefan Fercot 审核，Lardière Sébastien 建议。）
  • 加固 HTTP 分块响应解析。（由 Shubham 贡献，David Steele 审核。）
  • 未启用 allow-root 时，由 root 用户运行命令将报错。（由 Douglas J Hunley 审核。）
  • 构建清单时减少二分查找次数。（由 Gunnar Lindholm 贡献，David Steele 审核。）
  • 提升块级增量 delta 恢复期间的文件定位性能。（由 David Christensen、Douglas J Hunley 审核。）
  • 按顺序将备份文件打包，不再扫描以寻找更合适的文件组合。（由 Stefan Fercot 审核。）
  • 查询未能完成时报告底层错误。（由 Andrew Pogrebnoi 审核，Marco Fontana 建议。）
  • S3 凭据请求失败时报告实际错误。（由 Douglas J Hunley 审核，Mitchell Grice 建议。）
  • 将 archive-push 的 spool-path 错误报告到 PostgreSQL 日志。（由 Douglas J Hunley 审核，Don Seiler 建议。）
  • 遇到不受支持的版本时，提示 pgBackRest 可能版本过旧。
  • 添加 systemd 通知集成。（由 Andrew Jackson 贡献，David Steele 审核。）
  • 在 meson 编译器探测中抑制 unused parameter 错误。（由 Jörg Plate 贡献，David Steele 审核。）
  • C11 现为最低 C 语言标准。（由 Mohammad Ali Nazir Kosar 审核。）

文档改进：

  • 将 repo-* 命令的 stanza 选项设为内部选项。（由 Stefan Fercot 审核。）
  • 说明 info 会从全局配置节读取加密设置。（由 Stefan Fercot 审核，Ron Johnson 建议。）
  • 说明 expire-auto 使用 backup 命令的配置。（由 Stefan Fercot 审核，Lardière Sébastien 建议。）
  • 说明使用专用用户时需要调整 logrotate 的 su 指令。（由 Douglas J Hunley 审核，lkanbus 建议。）
  • 说明配置文件不支持行尾注释。（由 Douglas J Hunley 审核，Alex Richman 建议。）

测试套件改进：

  • 修复 CI 容器中的 Alpine 用户组冲突。（由 Artur Zakirov 贡献，David Steele 审核。）

稳定版本

v2.58.0 版本说明

对象存储改进

发布于 2026 年 1 月 19 日

重要提示：--repo-storage-upload-chunk-size 选项的最小值已提高，现在代表各云存储供应商所允许的最小值。

漏洞修复：

  • 修复信号处理程序中日志记录引发的死锁问题。（由 Maxim Michkov 修复，David Steele 审核。）

新功能：

  • 为 S3、GCS 和 Azure 添加 HTTP 支持。（由 Will Morland 贡献，David Steele 审核。）
  • 允许直接过期最旧的全量备份，不受当前保留策略限制。（由 Stefan Fercot 贡献，David Steele 审核，Ron Johnson 建议。）
  • 支持 Azure 托管标识（managed identities）。（由 Moiz Ibrar、Matthew Mols 贡献，David Steele 审核。）
  • 实验性 支持 S3 EKS Pod 身份认证。（由 Pierre BOUTELOUP 贡献，David Steele 审核。）
  • 允许配置 TLS 密码套件。（由 Gunnar “Nick” Bluth 贡献，David Steele 审核。）
  • 允许设置进程优先级。（由 Douglas J Hunley 审核。）

改进：

  • 使用 path-style URI 时，允许 S3 桶名中包含点号。（由 Joakim Hindersson 贡献，David Steele 审核。）
  • 除非禁用验证，否则要求 TLS >= 1.2。（由 Douglas J Hunley、Gunnar “Nick” Bluth 审核。）
  • 针对大文件上传，动态调整 S3/GCS/Azure 的分块大小。（由 Douglas J Hunley 审核，Timothée Peignier 建议。）
  • 针对小文件，优化 S3/GCS/Azure 的分块大小。（由 Douglas J Hunley 审核。）
  • 移除对 PostgreSQL 9.5 的支持。（由 Douglas J Hunley 审核。）
  • 改进存在未解析依赖项的选项在默认值日志中的输出信息。（由 Stefan Fercot 审核。）

文档改进：

  • 从用户指南中移除显式的 max_wal_senders/wal_level 配置说明。（由 Jamie Nguyen 建议。）
  • 阐明 bundling（包捆绑）在大块大小文件系统上的优势。（由 Ron Johnson 建议。）

v2.57.0 版本说明

禁止仓库符号链接

发布于 2025 年 10 月 18 日

漏洞修复：

  • 解除 HTTP/TLS/socket 超时的嵌套处理。（由 David Christensen 审核。）
  • 修复页面校验和错误信息中可能出现的段错误。（由 Zsolt Parragi 修复，David Steele 审核。）

新功能：

  • 新增 --repo-symlink 选项，用于禁止创建仓库符号链接。（由 Douglas J Hunley 审核，Ron Johnson 建议。）

改进：

  • 为 HTTP 408 和 429 错误添加重试机制。（由 David Christensen 审核。）

v2.56.0 版本说明

进度信息改进

发布于 2025 年 7 月 21 日

漏洞修复：

  • 修复仓库中无备份时临时过期操作（adhoc expiration）的问题。（由 Stefan Fercot 审核，Anup Gupta 报告。）

新功能：

  • 在 info 命令输出中添加恢复进度信息。（由 Denis Garsh、Maxim Michkov 贡献，David Steele 审核。）
  • 为 info 命令输出添加仅显示进度的详细级别。（由 Denis Garsh 贡献，David Steele、Stefan Fercot 审核。）

改进：

  • 在对象存储上重试失败的读取操作。（由 David Christensen 审核。）
  • 修复命令行帮助中默认值的显示问题。（由 David Christensen、Chris Bandy 审核。）

文档改进：

  • 在适当情况下，以列表形式描述离散选项值。（由 Anton Kurochkin 贡献，David Steele 审核。）
  • 修复 archive-mode 选项帮助输出中"小于"的描述。（由 Anton Kurochkin 贡献，David Steele 审核。）

v2.55.1 版本说明

漏洞修复

发布于 2025 年 5 月 5 日

漏洞修复：

  • 回滚"仅在需要时才在 S3 上计算 content-md5"的变更。（由 David Christensen 审核，Frank Brendel 报告。）
  • 修复选项键的下界检查。（由 David Christensen、Wolfgang Walther 审核，Wolfgang Walther 报告。）

v2.55.0 版本说明

验证功能改进与 PostgreSQL 18 支持

发布于 2025 年 4 月 21 日

漏洞修复：

  • 修复在非默认仓库上进行块级增量恢复的问题。（由 David Christensen、Aleksander Łukasz 审核，Aleksander Łukasz 报告。）
  • 对于 PostgreSQL < 12，不再设置 recovery_target_timeline=current。（由 Stefan Fercot 审核。）
  • 修复归档范围过期的日志记录问题。（由 Stefan Fercot 审核，Aleš Zelený 报告。）
  • 修复无结果查询的错误报告。（由 Stefan Fercot 审核，Susantha Bathige 报告。）

新功能：

  • 支持验证恢复目标时间线。（由 Stefan Fercot 审核。）
  • 允许对指定备份执行验证。（由 Maxim Michkov 贡献，David Steele 审核。）
  • 新增对 S3/GCS 请求方付费（requester pays）的支持。（由 Timothée Peignier 贡献，David Steele 审核。）
  • 支持 PostgreSQL 18。（由 Stefan Fercot 审核。）
  • 允许通过抽象域套接字（abstract domain sockets）连接 PostgreSQL。（由 Chris Bandy 审核，Chris Bandy 建议。）
  • 为 version 命令添加数字格式输出。（由 Stefan Fercot 贡献，David Steele 审核。）

改进：

  • 允许 backup 命令在远程仓库上运行。（由 Stefan Fercot 审核。）
  • 使用 lz4 进行协议压缩。（由 Stefan Fercot 审核。）
  • 仅在需要时才在 S3 上计算 content-md5。（由 David Christensen 审核。）
  • 多键选项的值被覆盖时，发出警告。（由 David Christensen、Stefan Fercot 审核。）
  • 为已过期归档路径添加详细日志记录。（由 Stefan Fercot 贡献，David Steele 审核。）
  • 移除对 PostgreSQL 9.4 的支持。（由 Stefan Fercot 审核。）
  • 移除 autoconf/make 构建方式。（由 David Christensen 审核。）

文档改进：

  • 修复为多个 stanza 指定 --tls-server-auth 时的文档说明。（由 David Christensen、Stefan Fercot 审核，Terry MacAndrew 建议。）
  • 阐明增量备份的过期机制。（由 Stefan Fercot 审核。）
  • 阐明本地与远程 pgBackRest 版本须保持一致的要求。（由 Greg Clough 贡献，David Steele 审核。）
  • 新增关于导出自包含集群的常见问题解答。（由 Stefan Fercot 贡献，David Steele 审核。）
  • 补充 --tablespace-map-all 关于表空间创建的注意事项。（由 Stefan Fercot、Christophe Courtois 审核，Christophe Courtois 建议。）
  • 阐明 --repo-retention-full-type 的行为。（由 Antoine Beaupré 审核，Antoine Beaupré 建议。）
  • 将对象存储的 --process-max 建议改为使用 --repo-bundle。（由 Stefan Fercot 审核。）
  • 将 unix_socket_directory 更新为 unix_socket_directories。（由 hyunkyu han 贡献，David Steele 审核。）
  • 建议不要将 --spool-path 置于 pg_xlog/pg_wal 目录内。（由 Martín Marqués、Don Seiler 审核，Martín Marqués 建议。）

v2.54.2 版本说明

漏洞修复

发布于 2025 年 1 月 20 日

漏洞修复：

  • 修复在启用块级增量的情况下禁用 bundling 后出现的问题。（由 David Christensen 审核。）

文档改进：

  • 阐明多个配置文件的行为方式。（由 Paul Bierly 审核，Paul Bierly 建议。）

v2.54.1 版本说明

漏洞修复

发布于 2024 年 12 月 16 日

漏洞修复：

  • 修复 version/help 命令尝试加载 pgbackrest.conf 的问题。（由 Stefan Fercot 审核，Bradford Boyle、Julian 报告。）

测试套件改进：

  • 稳定集成测试中的异步归档功能。（由 Viktor Kurilko 贡献，David Steele 审核。）

v2.54.0 版本说明

版本化存储的目标时间点

发布于 2024 年 10 月 21 日

打包者注意：这是最后一个支持 autoconf/make 构建方式的功能版本。如尚未迁移，请迁移到 meson。2.54.X 补丁版本（如有）将继续支持 autoconf/make。

漏洞修复：

  • 修复大型数据集上的 PostgreSQL 查询性能问题。（由 Thibault Vincent、David Steele 修复，David Christensen、Antoine Millet 审核，Antoine Millet 报告。）

新功能：

  • 允许在版本化存储（versioned storage）上的仓库中按目标时间点读取数据。（由 Stefan Fercot、David Christensen 审核。）
  • 允许在没有备库的情况下继续执行已请求的备库备份。（由 Stefan Fercot 审核。）

改进：

  • 在 info 命令文本输出中汇总备份引用列表。（由 Stefan Fercot 贡献，David Steele 审核。）
  • 每次 S3 认证时刷新 web-id 令牌。（由 Brent Graveland 贡献，David Steele 审核。）
  • 在帮助信息中正确显示索引选项的当前值。（由 David Christensen 审核。）
  • 仅在内容发生变化时才保存 backup.info。（由 Stefan Fercot 审核。）
  • 移除恢复过程中并行读取文件的数量限制。（由 David Christensen 审核。）
  • 改进 SFTP 错误信息。（由 Reid Thompson 贡献，David Steele 审核。）

文档改进：

  • 在用户指南中添加性能调优章节。（由 Stefan Fercot 审核。）
  • 阐明 data_directory 的来源。（由 Stefan Fercot 贡献，David Steele 审核，Matthias 建议。）
  • 优化摘要（summary）是否使用小写的判断逻辑。（由 Daniel Westermann 建议。）

v2.53.1 版本说明

PostgreSQL 17 支持

发布于 2024 年 8 月 19 日

漏洞修复：

  • 修复以 root 用户运行 restore 时的权限问题。（由 Stefan Fercot 审核，Will M. 报告。）
  • 修复延迟连接报错时的段错误。（由 David Christensen 审核，Anton Glushakov 报告。）
  • 跳过 SFTP 的本地仓库重复检查。（由 Reid Thompson 修复，David Steele 审核，Anton Kurochkin 报告。）

改进：

  • 支持 PostgreSQL 17。

v2.53 版本说明

并发备份

发布于 2024 年 7 月 22 日

重要提示：--log-level-stderr 选项的默认值已从 warn 更改为 off，仅重定向 stdout 时更易捕获错误。如需恢复之前的行为，请设置 --log-level-stderr=warn。打包者注意：meson 构建现在需要 lz4 库。打包者注意：meson 构建现在要求编译器支持 __builtin_clzl() 和 __builtin_bswap64()。

漏洞修复：

  • 修复文件已存在时 SFTP 重命名失败的问题。（由 Reid Thompson 修复，David Steele 审核，ahmed112212 报告。）

新功能：

  • 允许在不同仓库上并发执行备份。（由 Reid Thompson、Stefan Fercot 审核。）
  • 支持基于 IP 的 SAN（主题备用名称）用于 TLS 证书验证。（由 David Christensen 贡献，David Steele 审核。）

改进：

  • 将 --log-level-stderr 选项默认值设为 off。（由 Greg Sabino Mullane、Stefan Fercot 审核。）
  • 允许 PostgreSQL <= 10 使用非默认 WAL 段大小。（由 Viktor Kurilko 贡献，David Steele 审核。）
  • 新增检查 SFTP 授权日志的提示信息。（由 Vitalii Zurian 贡献，Reid Thompson、David Steele 审核。）

文档改进：

  • 阐明 archive-push 多仓库模式的行为。（由 Stefan Fercot 审核。）

v2.52.1 版本说明

漏洞修复

发布于 2024 年 6 月 25 日

漏洞修复：

  • 修复副本上的文件大于主库对应文件时出现的问题。（由 Stefan Fercot 审核，Nicolas Lassimonne 报告。）

v2.52 版本说明

PostgreSQL 17beta1 支持

发布于 2024 年 5 月 27 日

打包者注意：pgBackRest 的构建系统现已切换为 meson。autoconf/make 构建将不再接收新功能，并将在后续版本中移除。

新功能：

  • 新增 GCS 批量删除支持。（由 Reid Thompson 审核。）
  • 支持 S3 SSE-C 加密。（由 Tim Jones 审核，Tim Jones 建议。）
  • 支持 PostgreSQL 17beta1。（由 Stefan Fercot 审核。）

改进：

  • 允许在 meson 构建中显式禁用可选依赖项。（由 Michael Schout 贡献，David Steele 审核。）
  • 在 meson 构建中动态查找 python。（由 Michael Schout 贡献，David Steele 审核。）
  • 在 meson 中将 pgbackrest 构建目标标记为可安装。（由 Bradford Boyle 贡献，David Steele 审核。）

文档改进：

  • 更新 start/stop 文档，以反映实际功能。（由 Stefan Fercot 审核。）

v2.51 版本说明

Meson 构建系统

发布于 2024 年 3 月 25 日

漏洞修复：

  • 跳过块级增量 delta 恢复中的零长度文件。（由 Sebastian Krause、René Højbjerg Larsen 审核，Sebastian Krause 报告。）
  • 修复存储列表中的性能回归问题。（由 Stephen Frost 审核，Maksym Boguk 报告。）
  • 修复备份期间文件大小发生变化时的进度日志记录问题。（由 Stephen Frost 审核，samkingno 报告。）

改进：

  • 改进双栈连接（dual stack）支持。（由 Stephen Frost 审核，Timothée Peignier 建议。）
  • 将 meson 作为主要构建系统。（由 Stephen Frost 审核。）
  • 在非 delta 增量备份期间检测未发生变化的文件。（由 Stephen Frost 审核。）
  • 防止因移除 backup_label 而导致无效恢复。（由 Stephen Frost 审核。）
  • 改进 archive-push 的 WAL 段队列处理。（由 Stephen Frost 审核。）
  • 将恢复继续（resume）功能限制为全量备份。（由 Stephen Frost、Stefan Fercot 审核。）
  • 更新块级增量备份的恢复继续功能。（由 Stephen Frost 审核。）
  • 支持使用 --version 和 --help 查看版本和帮助信息。（由 Greg Sabino Mullane 审核，Greg Sabino Mullane 建议。）
  • 为 autoconf/make 构建添加详细的回溯（backtrace）信息。（由 Stephen Frost 审核。）

文档改进：

  • 更新对 recovery.conf 的引用说明。（由 Stefan Fercot 审核，Stephen Frost 建议。）

v2.50 版本说明

性能改进与漏洞修复

发布于 2024 年 1 月 22 日

漏洞修复：

  • 修复块级增量恢复中的短读（short read）问题。（由 Stephen Frost、Brent Graveland 审核，Adol Rodriguez、Brent Graveland 报告。）
  • 修复 info 输出中因备份进度溢出导致的显示错误。（由 Robert Donovan 修复，Joe Wildish 审核。）

改进：

  • 在块级增量 delta 恢复期间保留部分文件。（由 Stephen Frost 审核。）
  • 新增对备用编译时页面大小的支持。（由 Viktor Kurilko 贡献，David Steele 审核。）
  • 使用 bundling 时，跳过备份期间被截断的文件。（由 Georgy Shelkovy 贡献，David Steele 审核。）
  • 改进 SFTP 存储错误信息。（由 Reid Thompson 贡献，David Steele 审核。）

v2.49 版本说明

移除 PostgreSQL 9.3 支持

发布于 2023 年 11 月 27 日

漏洞修复：

  • 修复重试机制的回归问题。（由 Stephen Frost 审核，Norman Adkins、Tanel Suurhans、Jordan English、Timothée Peignier 报告。）
  • 修复 SFTP 存储驱动中递归路径删除的问题。（由 Reid Thompson 修复，Stephen Frost 审核，Luc 报告。）

改进：

  • 移除对 PostgreSQL 9.3 的支持。（由 Stephen Frost 审核。）

文档改进：

  • 记录维护者选项。（由 Stefan Fercot 审核。）
  • 更新 PostgreSQL >= 13 的时间点恢复（PITR）文档。

测试套件改进：

  • 允许在未安装 libssh2 的情况下运行 config/load 单元测试。（由 Reid Thompson 贡献，David Steele 审核，Wu Ning 建议。）

v2.48 版本说明

仓库存储标签

发布于 2023 年 9 月 25 日

漏洞修复：

  • 修复在没有块列表的情况下恢复块级增量备份的问题。（由 Stephen Frost、Burak Yurdakul 审核，Burak Yurdakul 报告。）

新功能：

  • 新增 --repo-storage-tag 选项，用于创建对象标签。（由 Stephen Frost、Stefan Fercot、Timothée Peignier 审核。）
  • 为 SFTP 存储驱动添加已知主机（known hosts）检查。（由 Reid Thompson 贡献，Stephen Frost、David Steele 审核。）
  • 支持双栈（dual stack）连接。（由 Stephen Frost 审核。）
  • 在 info 命令的 JSON 输出中新增已完成/总计备份大小字段。（由 Stefan Fercot 贡献，David Steele 审核。）

改进：

  • check 命令支持多 stanza。（由 Stephen Frost 审核。）
  • 重试读取 pg_control，直到校验和有效。（由 Stefan Fercot、Stephen Frost 审核。）
  • 优化成功备份后的 WAL 段检查。（由 Stephen Frost 审核。）
  • 改进 GCS 多部分上传性能。（由 Reid Thompson 审核。）
  • 允许在 stanza 停止时运行 archive-get 命令。（由 Tom Swartz、David Christensen、Reid Thompson 审核。）
  • 支持 SFTP 公钥/私钥路径中的前导波浪号（~）。（由 Reid Thompson 贡献，David Steele 审核。）
  • 在续期认证令牌前重新加载 GCS 凭证。（由 Stephen Frost 审核，Daniel Farina 建议。）

文档改进：

  • 修复配置参考中 --tls-server-address 选项的示例。（由 Hartmut Goebel 修复，David Steele 审核。）
  • 修复命令参考中 filter 选项的示例。

测试套件改进：

  • 允许在未安装 libssh2 的情况下运行 storage/sftp 单元测试。（由 Reid Thompson 贡献，David Steele 审核，Wu Ning 建议。）

v2.47 版本说明

性能改进与漏洞修复

发布于 2023 年 7 月 24 日

漏洞修复：

  • 在 delta 备份期间，在 manifest 中保留块级增量信息。（由 Stephen Frost 审核，Francisco Miguel Biete Banon 报告。）
  • 修复 verify 命令中的块级增量文件名问题。（由 Reid Thompson 审核，Francisco Miguel Biete Banon 报告。）
  • 修复从备库备份时错误触发自动 delta 备份的问题。（由 Stephen Frost 审核，krmozejko、Don Seiler 报告。）
  • 恢复类型为 type=none 时，跳过 PostgreSQL >= 12 的 recovery.signal 文件。（由 Stefan Fercot 审核，T.Anastacio 报告。）
  • 修复差异/增量备份的唯一标签生成问题。（由 Andrey Sokolov 修复，David Steele 审核。）
  • 修复无备份过期时基于时间的归档过期问题。（由 Stefan Fercot 审核。）

改进：

  • 提升 SFTP 存储驱动的性能。（由 Stephen Frost、Reid Thompson 贡献，David Steele 审核。）
  • 在 info 命令的日期/时间输出中添加时区偏移量。（由 Stefan Fercot、Philip Hurst 审核，Philip Hurst 建议。）
  • 集中处理不支持功能的错误。（由 Stefan Fercot 审核。）

文档改进：

  • 在用户指南中阐明优先从软件包安装的建议。（由 Stefan Fercot 审核，dr-kd 建议。）

v2.46 版本说明

块级增量备份与 SFTP 存储

发布于 2023 年 5 月 22 日

新功能：

  • 支持块级备份（block incremental backup）。（由 John Morris、Stephen Frost、Stefan Fercot 审核。）
  • 支持 SFTP 作为仓库存储。（由 Reid Thompson 贡献，Stephen Frost、David Steele 审核。）
  • 支持 PostgreSQL 16。（由 Stefan Fercot 审核。）

改进：

  • 允许跳过页头检查。（由 David Christensen 审核，David Christensen 建议。）
  • 恢复期间避免对恢复文件调用 chown()。（由 Stefan Fercot、Marcelo Henrique Neppel 审核，Marcelo Henrique Neppel 建议。）
  • 为 HTTP 重试添加错误重试详情。

文档改进：

  • 添加关于使用恢复类型 type=none 的警告说明。（由 Stefan Fercot 审核。）
  • 添加关于在已创建仓库上运行 stanza-create 的注意事项。

v2.45 版本说明

块级增量备份（测试版）

发布于 2023 年 3 月 20 日

漏洞修复：

  • 默认跳过为离线备份恢复时写入 recovery.signal 的操作。（由 Stefan Fercot 审核，Marcel Borger 报告。）

新功能：

  • 支持块级增量备份（BETA 测试版）。（由 John Morris、Stephen Frost、Stefan Fercot 审核。）

改进：

  • 仅保留一个全为默认值的组索引。（由 Stefan Fercot 审核。）

文档改进：

  • 添加在 2.x 版本之间升级的明确说明。（由 Christophe Courtois 贡献，David Steele 审核。）
  • 移除引入 TLS 后已过时的 SSH 相关说明。

v2.44 版本说明

移除 PostgreSQL 9.0/9.1/9.2 支持

发布于 2023 年 1 月 30 日

改进：

  • 移除对 PostgreSQL 9.0/9.1/9.2 的支持。（由 Stefan Fercot 审核。）
  • 当没有备份与当前 PostgreSQL 版本匹配时，restore 操作报错退出。（由 Stefan Fercot 贡献，David Steele 审核，Soulou 建议。）
  • 为每种 compress-type 添加 compress-level 的范围检查。（由 Stefan Fercot 审核，gkleen、ViperRu 建议。）

文档改进：

  • 添加关于在 Azure 存储上启用"分层命名空间"的警告。（由 Stefan Fercot 审核，Vojtech Galda、Pluggi、asjonos 建议。）
  • 在监控示例中添加换行符替换处理。（由 Stefan Fercot 审核，rudonx、gmustdie、Ivan Shelestov 建议。）
  • 阐明 --target-action 在各 PostgreSQL 版本上的行为。（由 Chris Bandy 贡献，David Steele、Anton Kurochkin、Stefan Fercot 审核，Anton Kurochkin、Chris Bandy 建议。）
  • 更新并完善索引页面内容。（由 Stefan Fercot 审核。）
  • 为网站添加深色模式。（由 Stephen Frost 建议。）

v2.43 版本说明

漏洞修复

发布于 2022 年 11 月 28 日

漏洞修复：

  • 修复差异/增量备份中缺少引用的问题。（由 Stefan Fercot 审核，Marcel Borger、ulfedf、jaymefSO 报告。）

改进：

  • 当选项未指定索引时，添加相应提示信息。（由 Stefan Fercot 审核。）

v2.42 版本说明

漏洞修复

发布于 2022 年 11 月 22 日

漏洞修复：

  • 修复文件 bundle 备份/恢复中的内存泄漏问题。（由 John Morris、Oscar 审核，Oscar 报告。）
  • 修复远程文件短读时的协议错误。（由 Stephen Frost 审核。）

改进：

  • 使用 bundling 时，不为零长度文件存储引用。（由 Stefan Fercot 审核。）
  • 对 pg_start_backup()/pg_stop_backup() 使用更通用的描述文字。（由 Greg Sabino Mullane、David Christensen 审核，Greg Sabino Mullane 建议。）
  • 更新 test.pl 的 --psql-bin 选项以匹配命令行帮助。（由 Koshi Shibagaki 贡献，David Steele 审核。）

v2.41 版本说明

备份注解

发布于 2022 年 9 月 19 日

漏洞修复：

  • 修复非默认仓库使用了错误时间过期策略的问题。（由 Stefan Fercot 审核，Adam Brusselback 报告。）
  • 修复使用过滤器递归列出目录时的问题。（由 Stephen Frost 审核，Efremov Egor 报告。）

新功能：

  • 支持备份键值注解（key/value annotations）。（由 Stefan Fercot 贡献，David Steele 审核，Adam Berlin 建议。）

改进：

  • 在 info 命令的 JSON 输出中支持 --set 参数。（由 Stefan Fercot 贡献，David Steele 审核，Anton Kurochkin 建议。）
  • 允许为对象存储配置上传分块大小。（由 Stefan Fercot 审核，Anton Glushakov 建议。）
  • 备份成功后更新 archive.info 的时间戳。（由 Stefan Fercot 审核，Alex Richman 建议。）
  • 将备库时间线检查移至检查点之后执行。（由 Stefan Fercot、Keith Fiske 审核，Keith Fiske 建议。）
  • 改进备份恢复 resume 时的警告信息。（由 Cynthia Shang 建议。）

文档改进：

  • 在 pgbackrest.service 中为 kill 添加绝对路径。（由 Don Seiler 建议。）

v2.40 版本说明

OpenSSL 3 支持

发布于 2022 年 7 月 18 日

打包者注意：已添加实验性的 meson 构建，但在可预见的未来，打包者应继续使用 autoconf/make 构建。

漏洞修复：

  • 在配置参考中跳过内部选项。（由 Francisco Miguel Biete Banon 报告。）

改进：

  • 支持 OpenSSL 3。（由 Stephen Frost 审核。）
  • 列出路径内容时创建快照。（由 John Morris、Stephen Frost 审核。）
  • 当恢复 type=immediate 时，强制设置 target-timeline=current。（由 Stephen Frost 审核。）
  • 在 delta restore 期间，当文件大于预期时进行截断。（由 Stephen Frost 审核。）
  • 当 resume=n 时，禁用增量 manifest 文件保存。（由 Reid Thompson 贡献，David Steele 审核。）
  • 在复制开始前将备份完成百分比置为零。（由 Reid Thompson 贡献，David Steele 审核。）
  • 使用 S3 的 IsTruncated 标志判断列表是否需要继续。（由 John Morris、Soulou 审核，Christian Montagne 建议。）
  • 添加实验性 Meson 构建。（由 Eli Schwartz、Sam Bassaly 审核。）
  • 允许向 --test-path 选项传递任意路径。（由 Andrey Sokolov 贡献，David Steele 审核。）
  • 修复在定义 DEBUG_EXEC_TIME 但未定义 DEBUG 时的编译错误。（由 Andrey Sokolov 贡献，David Steele 审核。）

文档改进：

  • 在仓库主机章节中添加 PostgreSQL 配置的链接。（由 Stefan Fercot 审核，Julien Cigar 建议。）

v2.39 版本说明

Verify 命令与文件 Bundling

发布于 2022 年 5 月 16 日

漏洞修复：

  • 修复 FINALLY() 中抛出的错误导致无限循环的问题。（由 Stephen Frost 审核。）
  • 除其他进程持有锁之外，对所有锁定失败情况报错。（由 Reid Thompson、Geir Råness 审核，Geir Råness 报告。）
  • 修复用户指南中对 stanza-update 的错误引用。（由 Abubakar Mohammed 修复，David Steele 审核。）
  • 修复配置参考中 repo-gcs-key-type 选项的示例。（由 Reid Thompson 审核。）
  • 修复 tls-server-auth 示例并添加说明。（由 Reid Thompson 审核。）

新功能：

  • 备份文件 bundling，改善对小文件的处理效果。（由 Reid Thompson、Stefan Fercot、Chris Bandy 审核。）
  • 新增 verify 命令，用于验证仓库内容的有效性。（由 Cynthia Shang、Reid Thompson 贡献，David Steele、Stefan Fercot 审核。）
  • 支持 PostgreSQL 15。（由 Stefan Fercot 审核。）
  • 在 info 输出中显示备份完成百分比。（由 Reid Thompson 贡献，David Steele 审核。）
  • 为 restore 命令的 --type=lsn 自动选择备份。（由 Reid Thompson 贡献，Stefan Fercot、David Steele 审核。）
  • 当 archive-mode-check 被禁用时，抑制现有 WAL 的警告信息。（由 Reid Thompson 贡献，David Steele 审核。）
  • 新增 AWS IMDSv2 支持。（由 Nuno Pires 贡献，David Steele 审核。）

改进：

  • 允许在全量备份（full backup）后更改 repo-hardlink 选项。（由 Reid Thompson 审核。）
  • 提高 backup 和 restore 完成百分比日志的精度。（由 Reid Thompson 贡献，David Steele 审核。）
  • 改进 repo-* 命令的路径验证。（由 Reid Thompson 贡献，David Steele 审核。）
  • 改进 stop 命令以遵循 stanza 选项。（由 Reid Thompson 贡献，David Steele 审核，ragaoua 建议。）
  • 改进 repo-azure-key 无效时的错误信息。（由 Reid Thompson 贡献，David Steele 审核，Seth Daniel 建议。）
  • 在 archive-get/archive-push 异步出错时，添加检查日志的提示信息。（由 Reid Thompson 审核。）
  • 新增 ClockError，用于处理意外的时钟偏差和时区变更。（由 Greg Sabino Mullane、Stefan Fercot 审核，Greg Sabino Mullane 建议。）
  • 在错误信息中显示历史 manifest 文件前，去除其扩展名。（由 Stefan Fercot 审核。）
  • 在锁权限错误信息中添加用户：组信息。（由 Reid Thompson 审核。）

文档改进：

  • 简化文档中关于支持版本的描述。（由 Stefan Fercot、Reid Thompson、Greg Sabino Mullane 审核。）
  • 添加选项类型描述。（由 Reid Thompson 贡献，David Steele 审核。）
  • 添加备份类型与恢复速度的常见问题解答。（由 David Christensen 贡献，Reid Thompson 审核。）
  • 记录 Pull Request 所需的基础分支。（由 David Christensen 贡献，Reid Thompson 审核。）

v2.38 版本说明

小型漏洞修复与改进

发布于 2022 年 3 月 6 日

重要提示：info 命令报告的仓库大小现在完全基于 pgBackRest 写入存储的数据量。此前，在某些情况下，pgBackRest 可以检测到存储是否应用了额外的压缩，但此功能已不再支持。

漏洞修复：

  • 对 S3 批量文件删除中的错误进行重试。（由 Reid Thompson 审核，Alex Richman 报告。）
  • 允许对 HTTP connection 头部值进行大小写不敏感的匹配。（由 Reid Thompson 审核，Rémi Vidier 报告。）
  • 将 TLS 文档中的 repo 选项移至 global 部分。（由 Anton Kurochkin 报告。）
  • 从 stanza 命令中移除未使用的 backup-standby 选项。（由 Stefan Fercot 报告。）
  • 修复帮助文档和版本说明中的错别字。（由 Daniel Gustafsson 修复，David Steele 审核。）

新功能：

  • 新增使用 KMS 的 AWS S3 服务端加密支持。（由 Christoph Berg 贡献，David Steele、Tharindu Amila 审核。）
  • 新增 archive-missing-retry 选项。（由 Stefan Fercot 审核。）
  • 为 info 命令添加备份类型过滤功能。（由 Stefan Fercot 贡献，David Steele 审核。）

改进：

  • 在 backup 期间页面验证失败时进行重试。（由 Stephen Frost、David Christensen 审核。）
  • 处理未能优雅关闭连接的 TLS 服务端。（由 Rémi Vidier、David Christensen、Stephen Frost 审核。）
  • 在 info 命令输出中添加备份的 LSN 信息。（由 Stefan Fercot 贡献，David Steele 审核。）
  • 自动去除 repo-ls 路径末尾的斜杠。（由 David Christensen 贡献，David Steele 审核。）
  • 不重试致命错误。（由 Reid Thompson 审核。）
  • 移除对 PostgreSQL 8.3/8.4 的支持。（由 Reid Thompson、Stefan Fercot 审核。）
  • 移除尝试检测额外文件系统压缩的逻辑。（由 Reid Thompson、Stefan Fercot 审核。）

文档改进：

  • 在 systemd 服务配置中添加存活检查。（由 Yogesh Sharma 建议。）
  • 添加解释 WAL 归档后缀的常见问题解答。（由 Stefan Fercot 贡献，David Steele 审核。）
  • 说明复制槽不会在恢复时被还原。（由 Reid Thompson 贡献，David Steele、Stefan Fercot 审核，Christophe Courtois 建议。）

v2.37 版本说明

TLS 服务端

发布于 2022 年 1 月 3 日

重要提示：如果 restore 命令找不到与指定时间目标匹配的备份，现在将抛出错误，而之前仅记录一条警告。

漏洞修复：

  • 修复 restore delta 链接映射中路径/文件已存在时的问题。（由 Reid Thompson 审核，Younes Alhroub 报告。）
  • 修复连接重试时的套接字泄漏问题。（由 Reid Thompson 审核，James Coleman 报告。）

新功能：

  • 新增 TLS 服务端。（由 Stephen Frost、Reid Thompson、Andrew L’Ecuyer 审核。）
  • 新增 --cmd 选项。（由 Reid Thompson 贡献，Stefan Fercot、David Steele 审核，Virgile CREVON 建议。）

改进：

  • 在备份开始后立即检查归档。（由 Reid Thompson、David Christensen 审核。）
  • 为备份添加时间线和检查点检查。（由 Stefan Fercot、Reid Thompson 审核。）
  • 在备份期间检查集群是否存活且配置正确。（由 Stefan Fercot 审核。）
  • 当 restore 无法找到匹配时间目标的备份时，报错退出。（由 Reid Thompson、Douglas J Hunley 审核，Douglas J Hunley 建议。）
  • 解析 S3/Azure 端点中的协议/端口。（由 Reid Thompson 贡献，David Steele 审核。）
  • 当 checkpoint_timeout 超过 db-timeout 时，添加警告信息。（由 Stefan Fercot 贡献，David Steele 审核。）
  • 在 HTTP 错误输出中添加请求方法（verb）。（由 Christoph Berg 贡献，David Steele 审核。）
  • 允许布尔命令行选项使用 y/n 作为参数。（由 Reid Thompson 贡献，David Steele 审核。）
  • 使备份大小日志与 info 命令输出完全一致。（由 Reid Thompson 贡献，David Steele 审核，Mahomed Hussein 建议。）

文档改进：

  • 以合适的单位显示大小选项的默认值和允许范围。（由 Reid Thompson 审核。）
  • 修复 tablespace-map-all 选项的错别字并改进文档。（由 Reid Thompson 审核，Reid Thompson 建议。）
  • 移除关于未来多仓库支持的过时说明。（由 David Christensen 建议。）

v2.36 版本说明

小型漏洞修复与改进

发布于 2021 年 11 月 1 日

漏洞修复：

  • 允许将 global 用作 stanza 名称前缀。（由 Stefan Fercot 审核，Younes Alhroub 报告。）
  • 修复 GCS 密钥文件无效时的段错误。（由 Stephen Frost 审核，Henrik Feldt 报告。）

改进：

  • 允许 link-map 选项创建新链接。（由 Don Seiler、Stefan Fercot、Chris Bandy 审核，Don Seiler 建议。）
  • 将 pg/repo 选项允许的最大索引值提升至 256。（由 Cynthia Shang 审核。）
  • 为 AWS S3 添加 WebIdentity 认证支持。（由 James Callahan、Reid Thompson、Benjamin Blattberg、Andrew L’Ecuyer 审核。）
  • 在 backup.info 中报告备份文件验证错误。（由 Stefan Fercot 贡献，David Steele 审核。）
  • 在在线备份恢复日志中添加恢复开始时间。（由 Tom Swartz、Stefan Fercot 审核，Tom Swartz 建议。）
  • 本地任务失败时，同时报告原始错误和重试信息。（由 Stefan Fercot 审核。）
  • 在 info 文本输出中，将页面校验和错误重命名为错误列表。（由 Stefan Fercot 审核。）
  • 在备库重放超时信息中添加提示。（由 Cynthia Shang、Stefan Fercot 审核，Leigh Downs 建议。）

v2.35 版本说明

二进制协议

发布于 2021 年 8 月 23 日

重要提示：backup/restore 命令中已复制文件的日志级别已更改为 detail。这使 info 日志级别的输出不再冗杂，如需查看这些信息，请将 backup/restore 命令的日志级别设置为 detail。

漏洞修复：

  • 检测 S3 多部分上传完成阶段的错误。（由 Cynthia Shang、Marco Montagna 审核，Marco Montagna、Lev Kokotov、Anderson A. Mallmann 报告。）
  • 修复循环符号链接的检测问题。（由 Stefan Fercot 审核，Rohit Raveendran 报告。）
  • 仅将选定的 repo 选项传递给远端。（由 David Christensen、Cynthia Shang 审核，Greg Sabino Mullane、David Christensen 报告。）
  • 修复用户指南中错误的主机名。（由 Stefan Fercot 审核，Greg Sabino Mullane 报告。）

改进：

  • 新增二进制协议。（由 Cynthia Shang 审核。）
  • 在 restore 时自动创建数据目录。（由 Stefan Fercot 贡献，David Steele 审核，Chris Bandy 建议。）
  • 允许 restore 使用 --type=lsn。（由 Stefan Fercot 贡献，Cynthia Shang 审核，James Coleman 建议。）
  • 将 backup/restore 已复制文件的日志级别更改为 detail。（由 Stefan Fercot 审核，Jens Wilke 建议。）
  • 等待检查点 LSN 赶上重放 LSN 时改为循环等待。（由 Stefan Fercot 贡献，David Steele 审核，Fatih Mencutekin 建议。）
  • 记录 backup 文件总数与 restore 大小/文件总数。（由 Cynthia Shang 审核。）
  • 添加测试路径在仓库路径内的检查。（由 Greg Sabino Mullane 审核，Greg Sabino Mullane 建议。）
  • 添加 CodeQL 静态代码分析。（由 Cynthia Shang 审核。）
  • 更新测试以使用标准模式。（由 Cynthia Shang 贡献，David Steele 审核。）

文档改进：

  • 更新贡献文档并添加 Pull Request 模板。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 在用户指南中重新整理备份文档。（由 Cynthia Shang 审核。）
  • 在命令参考中阐明 restore 的 --type 行为。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 修复文档和注释中的错别字。（由 Eric Radman 贡献，David Steele 审核。）

v2.34 版本说明

PostgreSQL 14 支持

发布于 2021 年 6 月 7 日

漏洞修复：

  • 修复先前 restore 遗留的缓冲区文件问题。（由 Cynthia Shang、Stefan Fercot、Floris van Nee 审核，Floris van Nee 报告。）
  • 修复检查大量表空间链接时的问题。（由 Cynthia Shang、Avinash Vallarapu 审核，Avinash Vallarapu 报告。）
  • 及时释放不再需要的远程连接，避免其在 restore 期间超时。（由 Cynthia Shang 审核，Francisco Miguel Biete Banon 报告。）
  • 修复当有效选项对指定命令无效时的 help 显示问题。（由 Stefan Fercot 审核，Cynthia Shang 报告。）

新功能：

  • 新增 PostgreSQL 14 支持。（由 Cynthia Shang 审核。）
  • 为 GCE 实例添加自动 GCS 认证。（由 Jan Wieck、Daniel Farina 审核。）
  • 新增 repo-retention-history 选项，用于过期备份历史记录。（由 Stefan Fercot 贡献，Cynthia Shang、David Steele 审核。）
  • 新增 db-exclude 选项。（由 Stefan Fercot 贡献，Cynthia Shang 审核。）

改进：

  • 将归档过期日志从 detail 级别提升至 info 级别。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 在 restore 时删除 stanza 归档缓冲（spool）路径。（由 Cynthia Shang、Stefan Fercot 审核。）
  • 在 backup 复制期间，不以原子方式写入文件，也不同步路径。（由 Stephen Frost、Stefan Fercot、Cynthia Shang 审核。）

文档改进：

  • 更新贡献文档。（由 Cynthia Shang 贡献，David Steele、Stefan Fercot 审核。）
  • 将 RHEL/CentOS 用户指南合并为单一文档。（由 Cynthia Shang 审核。）
  • 阐明 repo-s3-role 不是 ARN。（由 Isaac Yuen 贡献，David Steele 审核。）

v2.33 版本说明

多仓库与 GCS 支持

发布于 2021 年 4 月 5 日

漏洞修复：

  • 修复选项警告破坏异步 archive-get/archive-push 的问题。（由 Cynthia Shang 审核，Lev Kokotov 报告。）
  • 修复备份期间归档复制中的内存泄漏。（由 Cynthia Shang 审核，Christian ROUX、Efremov Egor 报告。）
  • 修复加密口令生成中的栈溢出问题。（由 Cynthia Shang 审核，bsiara 报告。）
  • 修复 S3 仓库上 repo-ls / 的问题。（由 Cynthia Shang 审核，Lesovsky Alexey 报告。）

新功能：

  • 支持多仓库。（由 Cynthia Shang、David Steele 贡献，Stefan Fercot、Stephen Frost 审核。）
  • 支持 GCS 作为仓库存储。（由 Cynthia Shang、Daniel Farina 审核。）
  • 新增 archive-header-check 选项。（由 Stephen Frost、Cynthia Shang 审核，Hans-Jürgen Schönig 建议。）

改进：

  • 选择性恢复时包含重建的系统数据库。（由 Stefan Fercot 贡献，Cynthia Shang 审核。）
  • 从 S3 签名头部中排除 content-length。（由 Cynthia Shang 审核，Brian P Bockelman 建议。）
  • 合并较少使用的仓库存储选项。（由 Cynthia Shang 审核。）
  • 允许通过 ./configure --with-configdir 自定义 config-path 的默认值。（由 Michael Schout 贡献，David Steele 审核。）
  • 在 backup 期间记录归档复制日志。（由 Cynthia Shang、Stefan Fercot 审核。）

文档改进：

  • 更新参考文档，添加指向用户指南示例的链接。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 更新选择性恢复文档，添加注意事项。（由 Cynthia Shang、Stefan Fercot 审核。）
  • 为 archive-copy 文档添加 compress-type 说明。（由 Cynthia Shang、Stefan Fercot 审核。）
  • 添加每种 compress-type 值对应的 compress-level 默认值。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 添加关于 NFS 所需设置与 PostgreSQL 相同的注意事项。（由 Cynthia Shang 贡献，David Steele 审核。）

v2.32 版本说明

仓库命令

发布于 2021 年 2 月 8 日

漏洞修复：

  • 修复因先前恢复操作部分删除备份后，再次 resume 时失败的问题。（由 Cynthia Shang 审核，Tom Swartz 报告。）

新功能：

  • 新增 repo-ls 命令。（由 Cynthia Shang、Stefan Fercot 审核。）
  • 新增 repo-get 命令。（由 Stefan Fercot、David Steele 贡献，Cynthia Shang 审核。）
  • 新增 archive-mode-check 选项。（由 Stefan Fercot 贡献，David Steele、Michael Banck 审核。）

改进：

  • 提升 archive-get 性能。（由 Cynthia Shang 审核。）

文档改进：

  • 完善 expire 命令的文档说明。（由 Cynthia Shang 贡献，David Steele 审核。）

v2.31 版本说明

小型漏洞修复与改进

发布于 2020 年 12 月 7 日

漏洞修复：

  • 允许使用 [、# 和空格作为数据库名称的首字符。（由 Stefan Fercot、Cynthia Shang 审核，Jefferson Alexandre 报告。）
  • 仅在 PostgreSQL 12 且 restore 类型为 standby 时才创建 standby.signal。（由 Stefan Fercot 修复，David Steele 审核，Keith Fiske 报告。）

新功能：

  • 支持历史文件的过期清理。（由 Stefan Fercot 贡献，David Steele 审核。）
  • 在 info 命令的文本输出中报告页面校验和错误。（由 Stefan Fercot 贡献，Cynthia Shang 审核。）
  • 新增 repo-azure-endpoint 选项。（由 Cynthia Shang、Brian Peterson 审核，Brian Peterson 建议。）
  • 新增 pg-database 选项。（由 Cynthia Shang 审核。）

改进：

  • 改进 info 命令在指定 stanza 不存在时的输出提示。（由 Stefan Fercot 贡献，Cynthia Shang、David Steele 审核，uspen 建议。）
  • 提升 backup/restore 命令处理大量文件列表时的性能。（由 Cynthia Shang、Oscar 审核。）
  • 启动备份时为 PostgreSQL 连接等待添加重试机制。（由 Cynthia Shang 审核，Vitaliy Kukharik 建议。）

文档改进：

  • 将 RHEL/CentOS 6 的文档替换为 RHEL/CentOS 8。

v2.30 版本说明

PostgreSQL 13 支持

发布于 2020 年 10 月 5 日

漏洞修复：

  • 当备份用户无法读取 pg_settings 时，输出带有提示信息的错误报告。（由 Stefan Fercot、Cynthia Shang 审核，Mohamed Insaf K 报告。）

新功能：

  • 支持 PostgreSQL 13。（由 Cynthia Shang 审核。）

改进：

  • 改进 PostgreSQL 版本识别机制。（由 Cynthia Shang、Stephen Frost 审核。）
  • 改进工作目录相关的错误提示信息。（由 Stefan Fercot 审核。）
  • 当找不到 WAL 段时，添加启动 stanza 的提示信息。（由 David Christensen 贡献，David Steele 审核。）
  • 新增协议版本不匹配时的提示信息。（由 Cynthia Shang 审核，loop-evgeny 建议。）

文档改进：

  • 添加远程运行时 pgBackRest 版本必须一致的说明。（由 Cynthia Shang 审核，loop-evgeny 建议。）
  • 将 info 命令的文本内容移至参考手册，并在用户指南中添加对应链接。（由 Cynthia Shang 审核，Christophe Courtois 建议。）
  • 更新用户指南中 CentOS/RHEL 的 yum 仓库路径。（由 Heath Lord 贡献，David Steele 审核。）

v2.29 版本说明

AWS 自动获取 S3 凭证

发布于 2020 年 8 月 31 日

漏洞修复：

  • 抑制关闭 local/remote 进程时的错误输出。命令已执行完毕，此时抛出错误适得其反；但仍会以 warn 级别记录警告，以说明发生了异常情况。（由 Cynthia Shang 审核，argdenis 报告。）
  • 修复文件名或数据库名中包含 = 字符时的处理问题。（由 Bastian Wegge、Cynthia Shang 审核，Brad Nicholson、Bastian Wegge 报告。）

新功能：

  • 在 AWS 实例上自动获取临时 S3 凭证。（由 David Steele、Stephen Frost 贡献，Cynthia Shang、David Youatt、Aleš Zelený、Jeanette Bromage 审核。）
  • 新增 archive-mode 选项，用于在 restore 时禁用归档。（由 Stephen Frost 审核，Stephen Frost 建议。）

改进：

  • 支持 PostgreSQL 13 beta3。后续 beta 版本中控制/目录/WAL 版本如有变更可能导致兼容性问题，pgBackRest 将随每个版本发布同步更新。
  • S3/Azure 存储的异步 list/remove 操作。（由 Cynthia Shang、Stephen Frost 审核。）
  • 优化 manifest 构建过程中未记录关系检测的内存使用效率。（由 Cynthia Shang、Stephen Frost、Brad Nicholson、Oscar 审核，Oscar、Brad Nicholson 建议。）
  • 派生异步进程后主动关闭文件描述符。（由 Stephen Frost、Cynthia Shang 审核。）
  • 将备份远程连接的关闭延迟至归档检查完成之后。（由 Floris van Nee 贡献，David Steele 审核。）
  • 改进详细错误输出。（由 Cynthia Shang 审核。）
  • 改进 TLS 错误报告。（由 Cynthia Shang、Stephen Frost 审核。）

文档漏洞修复：

  • 在 compress-type 选项参考中补充 none 并修正示例。（Ugo Bellavance、Don Seiler 报告。）
  • 在 repo-type 选项参考中补充缺失的 azure 类型。（由 Don Seiler 修复，David Steele 审核。）
  • 修正 repo-cipher-type 选项参考中的拼写错误。（由 Don Seiler 修复，David Steele 审核。）

文档改进：

  • 明确说明当 expire-auto 禁用时，必须定期手动运行 expire。（由 Douglas J Hunley 审核，Douglas J Hunley 建议。）

v2.28 版本说明

Azure 仓库存储

发布于 2020 年 7 月 20 日

漏洞修复：

  • 修复 restore --force 行为等同于 --force --delta 的问题。该问题导致 restore 根据时间戳和文件大小判断是否替换文件，而非直接覆盖，造成部分应被更新的文件保持不变。普通 restore 和 restore --delta 不受此问题影响。（由 Cynthia Shang 审核。）

新功能：

  • 支持 Azure 作为仓库存储后端。（由 Cynthia Shang、Don Seiler 审核。）
  • 新增 expire-auto 选项，用于禁止在成功备份后自动执行过期清理。（由 Stefan Fercot 贡献，Cynthia Shang、David Steele 审核。）

改进：

  • 支持 S3 分片上传的异步处理。（由 Stephen Frost 审核。）
  • 为 backup、restore、archive-get 和 archive-push 添加自动重试机制。（由 Cynthia Shang 审核。）
  • 在用于备份控制的 PostgreSQL 会话中禁用查询并行化。（由 Stefan Fercot 审核。）
  • 支持 PostgreSQL 13 beta2。后续 beta 版本中控制/目录/WAL 版本如有变更可能导致兼容性问题，pgBackRest 将随每个版本发布同步更新。
  • 改进对无效 HTTP 响应状态码的处理。（由 Cynthia Shang 审核。）
  • 改进 archive-get 命令缺少 pg1-path 选项时的错误提示。（由 Cynthia Shang 审核。）
  • 在时间线切换后启用校验和 delta 时，添加相应提示信息。（由 Matt Bunter、Cynthia Shang 审核。）
  • 在适当场合以 PostgreSQL 替代 postmaster。（由 Cynthia Shang 审核。）

文档漏洞修复：

  • 修正 repo-retention-full-type 选项的错误示例。（Höseyin Sönmez 报告。）
  • 从 HTML 和 man 页面的命令参考中移除内部命令。（Cynthia Shang 报告。）

文档改进：

  • 更新用户指南使用的 PostgreSQL 版本，并添加版本范围说明，以表明用户指南适用于一定范围内的 PostgreSQL 版本，即使其针对特定版本构建。（由 Stephen Frost 审核。）
  • 更新关于过期特定备份集的 FAQ。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 更新 FAQ 以明确默认 PITR 行为。（由 Cynthia Shang 贡献，David Steele 审核。）

v2.27 版本说明

过期改进与压缩驱动

发布于 2020 年 5 月 26 日

漏洞修复：

  • 修复检测文件链接是否包含在路径链接中的逻辑问题。（由 Cynthia Shang 审核，Christophe Cavallié 报告。）
  • 允许 pg-path1 在同步 archive-push 中为可选项。（由 Cynthia Shang 审核，Jerome Peng 报告。）
  • expire 命令现在会检查停止文件是否存在。（由 Cynthia Shang 修复，David Steele 审核。）
  • 处理 HTTP 响应中缺少原因短语的情况。（由 Cynthia Shang 审核，Tenuun 报告。）
  • 增大 lz4 压缩刷新的缓冲区大小。（由 Cynthia Shang 审核，Eric Radman 报告。）
  • 在 remote 命令中忽略 pg-host* 和 repo-host* 选项。（由 Cynthia Shang 审核，Pavel Suderevsky 报告。）
  • 修复 remote 命令中可能缺少 pg1-* 选项的问题。（由 Cynthia Shang 审核，Andrew L’Ecuyer 报告。）

新功能：

  • 全量备份的基于时间的保留策略。--repo-retention-full-type 选项支持按天数指定全量备份的保留周期。（由 Cynthia Shang、Pierre Ducroquet 贡献，David Steele 审核。）
  • 临时备份过期清理。允许用户无视保留策略设置，直接删除指定备份。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 支持 Zstandard 压缩。注意：设置 compress-type=zst 将使新备份和归档与旧版本的 pgBackRest 不兼容（无法恢复）。（由 Cynthia Shang 审核。）
  • 支持 bzip2 压缩。注意：设置 compress-type=bz2 将使新备份和归档与旧版本的 pgBackRest 不兼容（无法恢复）。（由 Stephen Frost 贡献，David Steele、Cynthia Shang 审核。）
  • 在 info 命令中显示 backup/expire 的运行状态。（由 Stefan Fercot 贡献，David Steele 审核。）

改进：

  • 仅当满足 repo-retention-archive 阈值时才过期 WAL 归档。此前，首次全量备份之前的 WAL 会在第一次全量备份后被清理；现在将按保留策略进行保留。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 添加本地 MD5 实现，使 S3 在启用 FIPS 时仍可正常工作。（由 Cynthia Shang、Stephen Frost 审核，Brian Almeida、John Kelly 建议。）
  • 支持 PostgreSQL 13 beta1。后续 beta 版本中控制/目录/WAL 版本如有变更可能导致兼容性问题，pgBackRest 将随每个版本发布同步更新。（由 Cynthia Shang 审核。）
  • 将 buffer-size 默认值降低至 1MiB。（由 Stephen Frost 审核。）
  • 若 expire 未在仓库主机上运行，则输出用户友好的错误信息。（由 Cynthia Shang 贡献，David Steele 审核。）

v2.26 版本说明

非阻塞 TLS

发布于 2020 年 4 月 20 日

漏洞修复：

  • 从 manifest 正则表达式中移除空子表达式。MacOS 对此不兼容，其他平台似乎可以正常运行。（由 David Raftis 修复，David Steele 审核。）

改进：

  • 实现非阻塞 TLS。（由 Slava Moudry、Cynthia Shang、Stephen Frost 审核。）
  • 仅对 WAL 记录的文件限制备份复制大小。此前的行为可能导致 postgresql.conf 或 postgresql.auto.conf 在备份中被截断。（由 Cynthia Shang 审核。）
  • TCP keep-alive 选项现在支持配置。（Marc Cousin 建议。）
  • 新增 io-timeout 选项。（由 Cynthia Shang 审核。）

v2.25 版本说明

lz4 压缩支持

发布于 2020 年 3 月 26 日

新功能：

  • 新增 lz4 压缩支持。注意：设置 compress-type=lz4 将使新备份和归档与旧版本的 pgBackRest 不兼容（无法恢复）。（由 Cynthia Shang 审核。）
  • 为 expire 命令新增 --dry-run 选项。使用 dry-run 可以预览 expire 命令将删除哪些备份/归档，而不会实际执行删除操作。（由 Cynthia Shang、Luca Ferrari 贡献，David Steele 审核，Marc Cousin 建议。）

改进：

  • 提升远程 manifest 构建的性能。（Jens Wilke 建议。）
  • 修复 Linux 上 keepalive 选项的检测问题。（由 Marc Cousin 贡献，David Steele 审核。）
  • 添加 configure 主机检测，以正确设置标准编译标志。（由 Marc Cousin 贡献，David Steele 审核。）
  • 从不使用压缩选项的命令中移除 compress/compress-level 选项。这些命令（如 restore、archive-get）从未使用过压缩选项，但此前允许在命令行中传入；现在若传入这些选项将报错。如果遇到此类错误，请移除无效选项。（由 Cynthia Shang 审核。）
  • 将备份文件复制大小限制为备份开始时报告的大小。若文件在备份过程中增大，恢复期间会通过 WAL 回放重建，无需复制额外数据。（由 Cynthia Shang 审核。）

v2.24 版本说明

时间目标的备份集自动选择

发布于 2020 年 2 月 25 日

漏洞修复：

  • 修复异步归档命令产生僵尸进程的问题。（由 Stephen Frost 审核，Adam Brusselback、ejberdecia 报告。）
  • 当 archive-get/archive-push/restore 未在 PostgreSQL 主机上运行时报错。（由 Stephen Frost 审核，Jesper St John 报告。）
  • 当未指定大小/编码时，读取 HTTP 内容直至 EOF。（由 Cynthia Shang 审核，Christian ROUX 报告。）
  • 修复由 Perl 创建的可续传备份在恢复时的处理问题。此情况下应忽略该可续传备份，但 C 代码无法加载 Perl 写入的部分 manifest（格式略有差异）。已添加相关校验以正常处理此情况。（Kacey Holston 报告。）

新功能：

  • 指定时间目标时自动选择备份集进行恢复。仅在未指定 --set 时执行自动选择；若找不到适合目标时间的备份集，则使用最新（默认）备份集。（由 Cynthia Shang 贡献，David Steele 审核。）

改进：

  • 备份期间跳过 pg_internal.init 临时文件。（由 Cynthia Shang 审核，Michael Paquier 建议。）
  • backup 时对 manifest 添加更多校验。（由 Cynthia Shang 审核。）

文档改进：

  • 阻止 lock-bot 向已锁定的 issue 添加评论。（Christoph Berg 建议。）

v2.23 版本说明

漏洞修复

发布于 2020 年 1 月 27 日

漏洞修复：

  • 修复文件缺失导致 manifest 损坏的问题。若 PostgreSQL 在备份过程中删除了某个文件（或该文件在备库上缺失），则下一个文件可能不会被复制并更新到 manifest 中；发生此情况时，恢复该备份将报错。（由 Cynthia Shang 审核，Vitaliy Kukharik 报告。）

改进：

  • 使用 pkg-config 替代 xml2-config 获取 libxml2 构建选项。（由 David Steele、Adrian Vondendriesch 贡献。）
  • 在 backup/restore 时校验 manifest 中的校验和是否已设置。（由 Cynthia Shang 审核。）

v2.22 版本说明

漏洞修复

发布于 2020 年 1 月 21 日

漏洞修复：

  • 修复时间线转换中的错误。时间线用于备份后验证归档中的 WAL 段。转换使用了十进制（base 10）而非十六进制（base 16），导致时间线 ≥ 0xA 时出现错误。（Lukas Ertl、Eric Veldhuyzen 报告。）

v2.21 版本说明

C 语言迁移完成

发布于 2020 年 1 月 15 日

漏洞修复：

  • 修复异步命令忽略选项的问题。异步 archive-get/archive-push 进程未加载命令配置节（如 [global:archive-get]）中配置的选项。（由 Cynthia Shang 审核，Urs Kramer 报告。）
  • 修复文件名中包含 \ 的处理问题。计算 manifest 校验和时 \ 未被正确转义，导致 manifest 无法加载。由于集群文件名中出现 \ 的情况极为罕见，此问题在实际使用中影响应该不大。

新功能：

  • pgBackRest 现已完全用 C 语言实现。
  • 新增 pg-user 选项，用于指定连接 PostgreSQL 时使用的数据库用户名。若未指定，pgBackRest 将使用本地操作系统用户或 PGUSER，与先前行为一致。（由 Mike Palmiotto 贡献，David Steele 审核。）
  • 允许在 S3 驱动中使用路径风格的 URI。

改进：

  • backup 命令已完全用 C 实现。（由 Cynthia Shang 审核。）

v2.20 版本说明

漏洞修复

发布于 2019 年 12 月 12 日

漏洞修复：

  • 修复 PGDATA 为符号链接时 archive-push/archive-get 失败的问题。这些命令尝试使用 cwd() 作为 PGDATA，但若 PGDATA 是符号链接，其结果与 pgBackRest 配置的路径可能不一致。修复方案：若 cwd() 与 pgBackRest 路径不匹配，则 chdir() 到该路径，并确保后续 cwd() 的结果与首次调用一致。（Stephen Frost、Milosz Suchy 报告。）
  • 修复 expire 命令重建 backup.info 时的引用列表问题。由于 backup 命令仍使用 Perl 版本的重建逻辑，此问题仅在以下两个条件同时满足时才会触发：1） backup.info 中存在缺失的备份；2） 直接运行 expire 命令而非在 backup 后自动运行。两个条件同时成立的概率极低，在实际使用中应该不是问题。
  • 修复 gzip 解压时意外遇到 EOF 导致的段错误。（Stephen Frost 报告。）

v2.19 版本说明

C 语言迁移与漏洞修复

发布于 2019 年 11 月 12 日

漏洞修复：

  • 修复 delta restore 中的远程超时问题。对基本未变化的集群执行 delta restore 时，若在 protocol-timeout 时间内未从仓库获取任何文件，远程端可能超时。已添加 keep-alive 机制以防止远程超时。（James Sewell、Jens Wilke 报告。）
  • 修复重复 HTTP 响应头的处理问题。HTTP 响应头重复出现时，应视为等同于单个逗号分隔的响应头，而非报错（此前的行为）。（donicrosby 报告。）

改进：

  • info 命令的 JSON 输出不再格式化（pretty-print）。不含换行符的 JSON 更便于监控系统解析；如需格式化输出，可使用 jq 等外部工具。（由 Cynthia Shang 贡献，David Steele 审核。）
  • check 命令已完全用 C 实现。（由 Cynthia Shang 贡献，David Steele 审核。）

文档改进：

  • 说明如何为 pgBackRest 做出贡献。（由 Cynthia Shang、David Steele 贡献。）
  • 说明 auto-stop 选项的最大支持版本。（由 Brad Nicholson 贡献，David Steele 审核。）

测试套件改进：

  • 修复使用 --vm=none 时容器测试路径的问题。（Stephen Frost 建议。）
  • 修复期望测试中时区不匹配的问题。（Stephen Frost 建议。）
  • 默认不自动生成嵌入式 libc 代码。（Stephen Frost 建议。）

v2.18 版本说明

PostgreSQL 12 支持

发布于 2019 年 10 月 1 日

新功能：

  • 支持 PostgreSQL 12。
  • 为 info 命令新增 set 选项以显示详细文本输出。额外信息包括：可用于选择性恢复的数据库列表，以及表空间、符号链接及其默认目标的列表。（由 Cynthia Shang 贡献，David Steele 审核，Stephen Frost、ejberdecia 建议。）
  • 新增 standby 恢复类型。在 PostgreSQL < 12 时自动向 recovery.conf 添加 standby_mode=on，在 PostgreSQL ≥ 12 时创建 standby.signal，为不同 PostgreSQL 版本提供统一接口。（由 Cynthia Shang 审核。）

改进：

  • restore 命令已完全用 C 实现。（由 Cynthia Shang 审核。）

文档改进：

  • 说明 db-timeout 与 protocol-timeout 之间的关系。（由 Cynthia Shang 贡献，David Steele 审核，James Chanco Jr 建议。）
  • 添加关于备库仓库的文档说明。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 添加基于时间的 PITR FAQ。（由 Cynthia Shang 贡献，David Steele 审核。）

v2.17 版本说明

C 语言迁移与漏洞修复

发布于 2019 年 9 月 3 日

漏洞修复：

  • 改进超大量表/段文件时 manifest 构建速度过慢的问题。（Jens Wilke 报告。）
  • 修复特殊文件的排除处理问题。（CluelessTechnologist、Janis Puris、Rachid Broum 报告。）

改进：

  • stanza-create/stanza-update/stanza-delete 命令已完全用 C 实现。（由 Cynthia Shang 贡献，David Steele 审核。）
  • start/stop 命令已完全用 C 实现。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 以 0750/0640 模式创建日志目录/文件。（Damiano Albani 建议。）

文档漏洞修复：

  • 修复指定自定义包时仍安装 yum.p.o 包的问题。（Joe Ayers、John Harvey 报告。）

文档改进：

  • 说明以非特权用户构建 pgBackRest 的方式。（Laurenz Albe 建议。）

v2.16 版本说明

C 语言迁移与漏洞修复

发布于 2019 年 8 月 5 日

漏洞修复：

  • 对 S3 RequestTimeTooSkewed 错误执行重试而非立即终止。（sean0101n、Tim Garton、Jesper St John、Aleš Zelený 报告。）
  • 修复对 HEAD 请求响应中 transfer-encoding 的错误处理。（Pavel Suderevsky 报告。）
  • 修复 gcc 9 优化暴露的作用域违规问题。（Christian Lange、Ned T. Crigler 报告。）

新功能：

  • 新增 repo-s3-port 选项，用于设置非标准 S3 服务端口。

改进：

  • backup 的 local 命令已完全用 C 实现。（由 David Steele、Cynthia Shang 贡献。）
  • check 命令已部分用 C 实现。（由 Cynthia Shang 审核。）

v2.15 版本说明

expire 命令的 C 语言实现

发布于 2019 年 6 月 25 日

漏洞修复：

  • 修复归档保留过期清理过于激进的问题。（由 Cynthia Shang 修复，David Steele 审核，Mohamad El-Rifai 报告。）

改进：

  • expire 命令已完全用 C 实现。（由 Cynthia Shang 贡献，David Steele 审核。）
  • restore 的 local 命令已完全用 C 实现。
  • 移除硬编码的 PostgreSQL 用户，使 $PGUSER 生效。（Julian Zhang、Janis Puris 建议。）
  • 支持 configure 的 --prefix 选项。（Daniel Westermann 建议。）
  • 将 repo-s3-verify-ssl 选项重命名为 repo-s3-verify-tls。新名称更为准确，因为 pgBackRest 不支持任何 SSL 协议版本（均视为不安全）。旧选项名称仍可继续使用。

文档改进：

  • 在文档中添加 FAQ。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 在 PostgreSQL ≥ 9.6 的文档中使用 wal_level=replica。（Patrick McLaughlin 建议。）

v2.14 版本说明

漏洞修复与改进

发布于 2019 年 5 月 20 日

漏洞修复：

  • 修复当 process-max > 8 时 archive-push/archive-get 发生段错误的问题。（Jens Wilke 报告。）

改进：

  • 使用 force 执行 stanza-delete 时绕过数据库检查。（由 Cynthia Shang 贡献，David Steele 审核，hatifnatt 建议。）
  • 添加 configure 脚本以改善多平台支持。

文档新功能：

  • 添加 CentOS/RHEL 6/7 的用户指南。

v2.13 版本说明

漏洞修复

发布于 2019 年 4 月 18 日

漏洞修复：

  • 修复零长度读取导致不期望接收零长度数据的 IO 过滤器出现异常的问题。（brunre01、Jens Wilke、Tomasz Kontusz、guruguruguru 报告。）
  • 修复 local/remote 进程错误报告的可靠性问题。
  • 修复 Posix/CIFS 在写入/同步/关闭时报告错误文件名的问题。

v2.12 版本说明

archive-push 命令的 C 语言实现

发布于 2019 年 4 月 11 日

重要提示：新的 TLS/SSL 实现根据 RFC-2818 禁止 S3 存储桶名称中包含点号（.）。这是合规主机名验证所必需的安全修复。

漏洞修复：

  • 修复路径选项以 / 结尾时的处理问题。（Marc Cousin 报告。）
  • 修复 archive-get 命令中设置 log-level-file=off 时的问题。（Brad Nicholson 报告。）
  • 修复 C 代码无法识别 host:port 选项格式（Perl 可以识别）的问题。（Kyle Nevins 报告。）
  • 修复 remote/local 命令日志选项的问题。

改进：

  • archive-push 命令已完全用 C 实现。
  • 将 process-max 上限提升至 999。（Rakshitha-BR 建议。）
  • 改进 S3 存储桶名称包含点号时的错误提示信息。

文档改进：

  • 明确说明支持兼容 S3 协议的对象存储。（Magnus Hagander 建议。）

v2.11 版本说明

archive-get 命令的 C 语言实现

发布于 2019 年 3 月 11 日

漏洞修复：

  • 修复写入过程中出错可能导致 WAL 段被截断的问题。（blogh 报告。）
  • 修复 info 命令在指定 stanza 时缺少 WAL 最小/最大值的问题。（由 Stefan Fercot 修复，David Steele 审核。）
  • 修复从 C 传递给 Perl 的选项中不符合规范的 JSON 格式。（Leo Khomenko 报告。）

改进：

  • archive-get 命令已完全用 C 实现。
  • 在较旧的 Perl 版本上启用 socket keep-alive。（由 Marc Cousin 贡献，David Steele 审核。）
  • 当参数传递给不接受参数的命令时报错。（Jason O’Donnell 建议。）
  • 在归档中找不到 WAL 段时添加提示信息。（Hans-Jürgen Schönig 建议。）
  • 改进证书中找不到主机名时的错误提示。（James Badger 建议。）
  • 为 backup.manifest 添加额外的调试选项。（由 blogh 贡献，David Steele 审核。）

文档改进：

  • 将默认文档版本更新为 PostgreSQL 10。

v2.10 版本说明

漏洞修复

发布于 2019 年 2 月 9 日

漏洞修复：

  • 补充 archive-get 所需但尚未实现的 S3 驱动方法。（mibiio 报告。）
  • 修复对 pg-path 配置错误的检查逻辑。（James Chanco Jr 报告。）

v2.09 版本说明

小型改进与缺陷修复

发布于 2019 年 1 月 30 日

漏洞修复：

  • 修复多个异步状态文件引发硬错误的问题。（报告：Vidhya Gurumoorthi、Joe Ayers、Douglas J Hunley。）

改进：

  • info 命令已完全用 C 重新实现。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 简化 info 命令在无 stanza 时的文本提示，将仓库路径替换为"the repository"。
  • 为 macOS 构建在 Makefile 中添加 _DARWIN_C_SOURCE 标志。（由 Douglas J Hunley 贡献，David Steele 审核。）
  • 将 C TLS 客户端的地址查找更新为使用现代接口。（建议：Bruno Friedmann。）
  • 包含符合 POSIX 规范的 strcasecmp() 和 fd_set 头文件。（建议：ucando。）

文档改进：

  • 修复硬编码的仓库路径。（报告：Heath Lord。）
  • 明确说明加密始终在客户端执行。（建议：Bruce Burdick。）
  • 添加构建文档主机的示例。
  • 在 manifest 变量、列表及列表项中允许使用 if。

v2.08 版本说明

小型改进与缺陷修复

发布于 2019 年 1 月 2 日

漏洞修复：

  • 移除在 PUT S3 对象后立即请求其元数据的操作。（报告：Matt Kunkel。）
  • 将 archive-get-queue-max 类型修正为 size。（报告：Ronan Dunklau。）
  • 添加当前用户的 uid/gid 无法映射到用户名时的错误提示。（报告：Camilo Aguilar。）
  • 在 PostgreSQL < 9.5 时指定 --target-action=shutdown 时报错。

改进：

  • 在 S3 连接上启用 TCP keepalive。（建议：Ronan Dunklau。）
  • 调整 info 命令文本输出顺序，使最新备份排在最后。（由 Cynthia Shang 贡献，David Steele 审核，Ryan Lambert 建议。）
  • 仅在必要时变更文件所有权。
  • 在抛出 S3 错误时对 authentication 头进行脱敏处理。（建议：Brad Nicholson。）

文档改进：

  • 明确说明 target-action 的生效条件及 PostgreSQL 版本支持情况。（建议：Keith Fiske。）
  • 明确说明 region/endpoint 必须与存储桶正确匹配。（建议：Pritam Barhate。）
  • 添加构建文档的说明。

v2.07 版本说明

备份校验和 Delta 自动启用

发布于 2018 年 11 月 16 日

漏洞修复：

  • 修复 archive-push-queue-max 在连接错误时未被遵守的问题。（报告：Lardière Sébastien。）
  • 修复用于判断是否超过 archive-push-queue-max 阈值时使用静态 WAL 段大小的问题。
  • 修复日志文件打开失败后处理应继续却仍报错的问题。（报告：vthriller。）

新功能：

  • 检测到异常情况（如时间线切换）时自动启用备份校验和 delta。（由 Cynthia Shang 贡献，David Steele 审核。）

改进：

  • 对所有 S3 5xx 错误执行重试，而非仅对 500 内部错误重试。（建议：Craig A. James。）

v2.06 版本说明

校验和 Delta 备份与 PostgreSQL 11 支持

发布于 2018 年 10 月 15 日

漏洞修复：

  • 修复 S3 驱动中缺失 URI 编码的问题。（报告：Dan Farrell。）
  • 修复配置文件中出现重复选项时错误提示不正确的问题。（报告：Jesper St John。）
  • 修复 info 日志中错误报告的返回码问题。archive-get 返回码 1 被以 info 级别记录为错误消息，但实际运行正常。

新功能：

  • 为增量备份添加校验和 delta 支持。校验和 delta 备份使用文件校验和而非时间戳来判断文件是否发生变更。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 支持 PostgreSQL 11，包括可配置的 WAL 段大小。

改进：

  • 忽略链接表空间目录中当前 PostgreSQL 版本子目录以外的所有文件。此前若表空间目录中存在非 PostgreSQL 用户所有的其他文件，会产生报错。
  • 改进 info 命令，使其显示 stanza 的加密类型。（由 Cynthia Shang 贡献，David Steele 审核，Douglas J Hunley 建议。）
  • 改进对文件名中特殊字符的支持。
  • 允许在 pgBackRest 配置文件中指定 delta 选项。（由 Cynthia Shang 贡献，David Steele 审核。）

文档改进：

  • 在 authorized_hosts 中使用 command 以提升 SSH 安全性。（建议：Stephen Frost、Magnus Hagander。）
  • 在配置参考中列出 buffer-size 选项的允许值。（由 Cynthia Shang 贡献，David Steele 审核，Stéphane Schildknecht 建议。）

v2.05 版本说明

环境变量选项与临时/未记录关系的排除

发布于 2018 年 8 月 31 日

漏洞修复：

  • 修复 $PGDATA 中 相对 链接可能以错误路径存入备份的问题。此问题不影响绝对链接，相对表空间链接已由其他检查捕获。（报告：Cynthia Shang。）
  • 从 check 命令中移除未完全实现的 online 选项。离线操作与该命令的目的（检查归档和备份是否正常工作）相悖。（报告：Jason O’Donnell。）
  • 修复 C 中抛出的错误在由 Perl 调用时未被记录的问题。pgBackRest 以正确的错误码退出，但缺少有助于调试的错误消息。（报告：Douglas J Hunley。）
  • 修复布尔型选项（如 delta）被多次指定时的错误。（报告：Yogesh Sharma。）

新功能：

  • 允许通过环境变量设置任意选项，包括之前只能在命令行指定的选项（如 stanza），以及不能在命令行指定的加密选项（如 repo1-s3-key-secret）。
  • 从备份中排除临时和未记录的关系（表/索引）文件。实现逻辑与 PostgreSQL 中引入此功能的补丁一致，参见 8694cc96 和 920a5e50。临时关系排除在 PostgreSQL ≥ 9.0 时启用，未记录关系排除在 PostgreSQL ≥ 9.1（该功能引入版本）时启用。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 允许从备份中排除任意目录和/或文件。滥用此功能可能导致备份不一致，使用前请仔细阅读 --exclude 文档。（由 Cynthia Shang 审核。）
  • 添加 log-subprocess 选项，允许为 local 和 remote 子进程启用文件日志。
  • 支持 PostgreSQL 11 Beta 3。

改进：

  • 允许备份 manifest 中零大小文件引用之前的 manifest，不受时间戳 delta 的限制。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 通过直接检查状态文件改善异步 archive-get/archive-push 性能。（由 Stephen Frost 贡献，David Steele 审核。）
  • 改进命令缺少 stanza 选项时的错误提示。（建议：Sarah Conway。）

文档改进：

  • 修复 log-path 选项参考中无效的日志级别。（报告：Camilo Aguilar。）
  • 停止尝试在 release.xml 中按姓/名排列贡献者。贡献者名称始终按原样呈现在发布说明中，但我们曾尝试基于姓/名分配内部 ID，这既难以判断又毫无意义。受 Christophe 在 PostgresOpen 2017 演讲"Human Beings Do Not Have a Primary Key"的启发。（建议：Christophe Pettus。）

测试套件改进：

  • 若在测试环境之外执行 LibC 构建则报错。LibC 不再是生产构建所必需的。

v2.04 版本说明

备份恢复关键缺陷修复

发布于 2018 年 7 月 5 日

重要提示：本版本修复了备份 resume 功能中的一个关键缺陷。此版本之前所有已 resume 的备份均应视为不一致。当先前的备份失败时，若未指定 resume=n，则会触发备份 resume。可通过检查备份日志中是否存在"aborted backup of same type exists, will be cleaned to remove invalid files and resumed"消息来判断备份是否已被 resume。若存在该消息，请勿使用该备份或同一备份集中的任何备份进行恢复，并检查恢复日志确认是否用到了 resume 备份。若已使用，集群中可能存在不一致数据。

漏洞修复：

  • 修复 resume 中导致备份不一致的关键缺陷。v0.82 中的一次回归移除了在决定恢复哪些已中止备份文件时的时间戳比较逻辑，详情参见上方说明。（报告：David Youatt、Yogesh Sharma、Stephen Frost。）
  • 修复集群中只存在一个用户数据库时选择性恢复报错的问题。（由 Cynthia Shang 修复，David Steele 审核，Nj Baliyan 报告。）
  • 修复 S3 授权头中不符合 ISO-8601 规范的时间戳格式。AWS 和部分网关对空格与零填充小时均可容忍，但其他实现则不然。（由 Andrew Schwartz 修复，David Steele 审核。）

新功能：

  • 支持 PostgreSQL 11 Beta 2。

改进：

  • 改进 HTTP 客户端，在服务端未指定时将 content-length 设为 0。S3（及其网关）始终设置 content-length 或 transfer-encoding，但 HTTP 1.1 并不强制要求，部分代理（如 HAProxy）可能不包含任一字段。（建议：Adam K. Sumner。）
  • 在 PostgreSQL 连接上设置 search_path = 'pg_catalog'。（建议：Stephen Frost。）

文档改进：

  • 新增章节，说明如何在独立主机上构建 pgBackRest。
  • 添加 S3 策略示例以限制存储桶权限。（建议：Douglas J Hunley、Jason O’Donnell。）

v2.03 版本说明

单一可执行文件部署

发布于 2018 年 5 月 22 日

漏洞修复：

  • 修复错误消息处理中潜在的缓冲区溢出问题。（报告：Lætitia。）
  • 修复同步 archive-get 命令错误获取归档写锁的问题。（报告：uspen。）

改进：

  • 将导出的 C 函数和 Perl 模块直接嵌入 pgBackRest 可执行文件中。
  • 使用 time_t 替代 __time_t 以提升可移植性。（建议：Nick Floersch。）
  • 在命令结束时以毫秒为单位打印总运行时长。

v2.02 版本说明

并行异步 archive-get 与配置文件包含

发布于 2018 年 5 月 6 日

漏洞修复：

  • 修复目录同步在仅应同步指定目录时递归执行的问题。（报告：Craig A. James。）
  • 修复增量/差异备份中 archive-copy 抛出"path not found"错误的问题。（报告：yummyliu、Vitaliy Kukharik。）
  • 修复 PGDATA 中两个或多个文件链接到同一目录时 manifest 构建失败的问题。（报告：Vitaliy Kukharik。）
  • 修复链接文件缺失时 delta restore 失败的问题。
  • 修复帮助信息中键值和列表选项的渲染问题。（报告：Clinton Adams。）

新功能：

  • 添加异步并行 archive-get。该特性维护一个 WAL 段预取队列，在 PostgreSQL 通过 restore_command 请求 WAL 段时降低等待延迟。
  • 支持附加的 pgBackRest 配置文件。配置文件目录由 --config-include-path 选项指定；新增 --config-path 选项用于覆盖 --config 和 --config-include-path 的默认基础路径。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 添加 repo-s3-token 选项，支持配置临时凭证令牌。pgBackRest 目前不具备主动刷新凭证的能力，因此整个命令（如 backup、restore）必须在凭证过期前完成。（由 Yogesh Sharma 贡献，David Steele 审核。）

改进：

  • 更新 archive-push-queue-max、manifest-save-threshold 和 buffer-size 选项，支持接受 KB、MB、GB、TB 或 PB 为单位的值（乘数以 1024 的幂计算）。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 提升备份/恢复路径同步效率。扫描整个目录在小表数量众多时代价高昂；备份 manifest 中已包含路径列表，现改为使用该列表执行同步，而非扫描备份/恢复路径。
  • 在初始 info 日志消息中同时显示命令参数和选项。
  • 将 archive-queue-max 选项重命名为 archive-push-queue-max，与新增的 archive-get-queue-max 选项保持命名一致。旧选项名称仍可继续使用。

文档改进：

  • 更新文档，添加 32 位支持说明及注意事项。32 位支持已于 v1.26 添加。（报告：Viorel Tabara。）
  • 添加使用 PostgreSQL 和 jq 的监控示例。（建议：Stephen Frost、Brian Faherty。）
  • 添加归档配置中命令节使用示例。（建议：Christophe Courtois。）
  • 移除将 info --output=json 描述为实验性功能的说明。
  • 更新 spool-path 选项的过时描述。

测试套件改进：

  • 使用 lcov 进行 C 单元测试覆盖率报告，从 Devel::Cover 切换，原因是后者无法报告从 gcov 转换的报告中的分支覆盖率。模块的不完整分支覆盖率现在会产生错误。单元测试覆盖率仅在语句或分支覆盖不完整时才会出现在报告中。

v2.01 版本说明

小型缺陷修复与改进

发布于 2018 年 3 月 19 日

漏洞修复：

  • 修复使用 --type=immediate 恢复时 --target-action 和 --recovery-option 选项被报告为无效的问题。（报告：Brad Nicholson。）
  • 在命令行传入加密选项（如 repo1-s3-key）时立即报错。由于 pgBackRest 不会将加密选项传递给子进程，之前会抛出晦涩的错误；新错误更加清晰并提示了解决方法。同时更新命令文档，省略不能在命令行指定的加密选项。（报告：Brad Nicholson。）
  • 修复向嵌入式 Perl 传递 --no-config 时的问题。（报告：Ibrahim Edib Kokdemir。）
  • 修复将 log-level-stderr 设置高于 warn 时 local/remote 进程因 stderr 出现意外输出而报错退出的问题。local/remote 进程的日志级别上限现调整为 error，因为这些进程本不应输出警告。（报告：Clinton Adams。）
  • 修复存在表空间时 check 命令中 manifest 测试的问题。（由 Cynthia Shang 修复，David Steele 审核，Thomas Flatley 报告。）

改进：

  • 在配置文件中为不接受多个参数的选项设置多个值时报错。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 从 src/Makefile 中移除多余的 sudo 命令。（由 Adrian Vondendriesch 贡献，David Steele 审核。）

文档改进：

  • 在示例中为带索引的选项（如 repo-*、pg-*）显示索引。（建议：Stephen Frost。）
  • 简化命令页面目录，仅列出命令。（建议：Stephen Frost。）
  • 移除关于 C 库为可选项的说明。

测试套件改进：

  • 添加 CentOS/RHEL 软件包构建。
  • 使用 clang 进行静态代码分析。初始分析未发现问题，仅发现部分函数应标记为 __noreturn__。

v2.00 版本说明

archive-push 性能改进

发布于 2018 年 2 月 23 日

新功能：

  • archive-push 命令现已部分用 C 实现，使 PostgreSQL 的 archive_command 在处理来自异步归档进程的状态消息时运行速度显著提升。（由 Cynthia Shang 审核。）

改进：

  • 改进 check 命令，增加对备份 manifest 是否可构建的验证。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 提升 HTTPS 客户端性能。缓冲现在会在 socket 上有 pending 字节时将其计入，而非完全依赖 select()。在某些情况下，最后几个字节直到连接关闭才会被刷出。
  • 提升 S3 删除性能。常量 S3_BATCH_MAX 曾被替换为硬编码值 2（可能是测试时遗留）。
  • 允许在命令行将任意非命令行选项重置为默认值，从而无需为特定需求另写配置文件即可覆盖 pgbackrest.conf 中的设置。
  • C 库现为必需项，取消了条件加载，简化了新库特性的开发。
  • pgbackrest 可执行文件现在是 C 二进制文件而非 Perl，使对时间敏感的命令（如异步 archive-push）运行更快。
  • 将 db-* 选项重命名为 pg-*，将 backup-* 选项重命名为 repo-*，以提高一致性。repo-* 选项现已带索引，但目前仅允许使用一个。

文档改进：

  • 文档中所有集群均使用校验和初始化。
  • 在文档和命令行帮助中列出已弃用的选项名称。
  • 明确说明 S3 存储桶必须由用户自行创建。（建议：David Youatt。）

v1.29 版本说明

备份恢复关键缺陷修复

发布于 2018 年 7 月 5 日

重要提示：本版本修复了备份 resume 功能中的一个关键缺陷。此版本之前所有已 resume 的备份均应视为不一致。当先前的备份失败时，若未指定 resume=n，则会触发备份 resume。可通过检查备份日志中是否存在"aborted backup of same type exists, will be cleaned to remove invalid files and resumed"消息来判断备份是否已被 resume。若存在该消息，请勿使用该备份或同一备份集中的任何备份进行恢复，并检查恢复日志确认是否用到了 resume 备份。若已使用，集群中可能存在不一致数据。

漏洞修复：

  • 修复 resume 中导致备份不一致的关键缺陷。v0.82 中的一次回归移除了在决定恢复哪些已中止备份文件时的时间戳比较逻辑，详情参见上方说明。（报告：David Youatt、Yogesh Sharma、Stephen Frost。）
  • 修复 S3 授权头中不符合 ISO-8601 规范的时间戳格式。AWS 和部分网关对空格与零填充小时均可容忍，但其他实现则不然。（由 Andrew Schwartz 修复，David Steele 审核。）
  • 修复目录同步在仅应同步指定目录时递归执行的问题。（报告：Craig A. James。）
  • 修复使用 --type=immediate 恢复时 --target-action 和 --recovery-option 选项被报告为无效的问题。（报告：Brad Nicholson。）
  • 修复增量/差异备份中 archive-copy 抛出"path not found"错误的问题。（报告：yummyliu、Vitaliy Kukharik。）
  • 修复 PGDATA 中两个或多个文件链接到同一目录时 manifest 构建失败的问题。（报告：Vitaliy Kukharik。）
  • 修复链接文件缺失时 delta restore 失败的问题。
  • 修复集群中只存在一个用户数据库时选择性恢复报错的问题。（由 Cynthia Shang 修复，David Steele 审核，Nj Baliyan 报告。）

改进：

  • 改进 HTTP 客户端，在服务端未指定时将 content-length 设为 0。S3（及其网关）始终设置 content-length 或 transfer-encoding，但 HTTP 1.1 并不强制要求，部分代理（如 HAProxy）可能不包含任一字段。（建议：Adam K. Sumner。）
  • 提升 HTTPS 客户端性能。缓冲现在会在 socket 上有 pending 字节时将其计入，而非完全依赖 select()。在某些情况下，最后几个字节直到连接关闭才会被刷出。
  • 提升 S3 删除性能。常量 S3_BATCH_MAX 曾被替换为硬编码值 2（可能是测试时遗留）。
  • 提升备份/恢复路径同步效率。扫描整个目录在小表数量众多时代价高昂；备份 manifest 中已包含路径列表，现改为使用该列表执行同步，并移除不再使用的递归路径同步功能。

文档改进：

  • 更新文档，添加 32 位支持说明及注意事项。32 位支持已于 v1.26 添加。（报告：Viorel Tabara。）
  • 明确说明 S3 存储桶必须由用户自行创建。（建议：David Youatt。）
  • 更新 spool-path 选项的过时描述。

v1.28 版本说明

Stanza 删除

发布于 2018 年 2 月 1 日

漏洞修复：

  • 修复使用 --db-include 恢复表空间中单个数据库时失败的问题。（由 Cynthia Shang 修复，David Steele 审核，Chiranjeevi Ravilla 报告。）
  • 确保在将 archive.info 匹配到 backup.info 时选择最新的 db-id。在存在 system-id 和 db-version 重复项时（例如回滚 pg_upgrade 后），此改动可提供正确匹配。（由 Cynthia Shang 修复，David Steele 审核，Adam K. Sumner 报告。）
  • 修复报告无效命令时过于冗长的错误消息。（报告：Jason O’Donnell。）

新功能：

  • 添加 stanza-delete 命令，用于清理不再使用的 stanza。（由 Cynthia Shang 贡献，David Steele 审核，Magnus Hagander 建议。）

改进：

  • 改进 stanza-create 命令，使其在 stanza 已存在时不再报错。（由 Cynthia Shang 贡献，David Steele 审核。）

文档改进：

  • 更新 stanza-create --force 文档，提示使用时需谨慎。（建议：Jason O’Donnell。）

v1.27 版本说明

缺陷修复与文档

发布于 2017 年 12 月 19 日

漏洞修复：

  • 修复 backup 和 restore 的本地性检查错误被抑制的问题。存在备份主机时，备份应仅允许在备份主机上执行，恢复应仅允许在数据库主机上执行，除非创建了忽略远程主机的备用配置。（报告：Lardière Sébastien。）
  • 修复 PostgreSQL 10 上 WAL 未过期的问题。原因是正则表达式存在缺陷，期望所有 PostgreSQL 主版本号均为 X.X 格式。（报告：Adam Brusselback。）
  • 修复 --no-config 选项未传递给子进程的问题。这会导致子进程仍读取本地配置文件，可能引发意外行为。
  • 修复 info 命令在先前版本集群没有备份或归档时仍显示 "db (prior)" 输出的问题。（由 Cynthia Shang 修复，David Steele 审核，Stephen Frost 报告。）

文档改进：

  • 说明 archive-copy 和 archive-check 选项之间的关系。（建议：Markus Nullmeier。）
  • 改进 archive-copy 参考文档。

v1.26 版本说明

仓库加密

发布于 2017 年 11 月 21 日

漏洞修复：

  • 修复恢复时复制大型 manifest 可能失败的问题。（报告：Craig A. James。）
  • 修复 32 位架构下不正确的 WAL 偏移量。（由 Javier Wilson 修复，David Steele 审核。）
  • 修复获取旧数据库版本 WAL 时的问题。执行 stanza-upgrade 后，应仍能恢复之前版本的备份并通过 archive-get 进行恢复。但 archive-get 仅检查最新的 db 版本/id 而失败。同时清理了同一 db 版本/id 多次出现时的相关问题。（由 Cynthia Shang 修复，David Steele 审核，Clinton Adams 报告。）
  • 修复恢复时无效备份组未被正确设置的问题。若备份无法将某个组映射到名称，则将该组以 false 存入 manifest，恢复时使用 $PGDATA 所有者或当前用户的组来设置。该逻辑存在缺陷，导致所选的组覆盖了用户，组未定义而用户被错误设置为组。（报告：Jeff McCormick。）
  • 修复向远程传递参数时的问题。指定多个 db 时，无论实际处理的是哪个 db，都会传递 db1 的路径、端口和 socket 路径。（报告：uspen。）

新功能：

  • 支持仓库加密。（由 Cynthia Shang、David Steele 贡献。）

改进：

  • 当 --compress-level-network=0 时禁用 gzip 过滤器。该过滤器曾以压缩级别 0 运行，带来额外开销却毫无收益。
  • 改进 gzip 过滤器的解压性能。

文档改进：

  • 添加用于改善 issue 提交时初始信息收集的模板。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 明确说明 archive-timeout 选项的用法及其与 PostgreSQL archive_timeout 设置的区别。（由 Cynthia Shang 贡献，David Steele 审核，Keith Fiske 建议。）

测试套件改进：

  • 支持 32 位 i386/i686 架构的自动化测试。

v1.25 版本说明

S3 性能改进

发布于 2017 年 10 月 24 日

漏洞修复：

  • 修复 compress-level 选项自定义设置被忽略的问题。（报告：Jens Wilke。）
  • 移除检测到重叠时间线时的报错。重叠时间线在许多时间点恢复（PITR）场景中是有效的。（报告：blogh。）
  • 修复 JSON info 输出中 database-id 未渲染为整数的问题。（由 Cynthia Shang 修复，David Steele 审核，Jason O’Donnell 报告。）

新功能：

  • 提升 S3 列表请求的性能。过滤表达式中任何起始字面量部分均用于生成搜索前缀，通常可将请求范围控制在足够小，从而避免触发限流。（建议：Mihail Shvein。）

测试套件改进：

  • 添加 I/O 性能测试。

v1.24 版本说明

新增备份排除项

发布于 2017 年 9 月 28 日

漏洞修复：

  • 修复从备库初始化备份期间警告消息覆盖低优先级日志消息输出的问题。（报告：uspen。）
  • 修复部分 db-* 选项（如 db-port）未传递给远程的问题。（报告：uspen。）

新功能：

  • 从备份中排除 pg_snapshots、pg_serial、pg_notify 和 pg_dynshmem 目录的内容，因为这些内容在启动时会重建。
  • 从备份中排除 pg_internal.init 文件，因为这些文件在启动时会重建。

改进：

  • 在异步进程完全从主进程分离后才打开日志文件，以防止主进程向该文件写入日志。（建议：Jens Wilke。）

文档改进：

  • 添加无密码 SSH 配置说明。
  • 在文档中将 master 重命名为 primary，与 PostgreSQL 惯例保持一致。

v1.23 版本说明

多备库与 PostgreSQL 10 支持

发布于 2017 年 9 月 3 日

漏洞修复：

  • 修复文件持续增大时压缩可能中止的问题。（报告：Jesper St John、Aleksandr Rogozin。）
  • 修复本地进程未向远程发送 keep-alive 的问题。（报告：William Cox。）

新功能：

  • 支持配置最多七个备库用于从备库备份。（由 Cynthia Shang 贡献，David Steele 审核。）
  • 支持 PostgreSQL 10。
  • 在读取 XML 数据时允许使用 content-length（除分块编码外），以提升与第三方 S3 网关的兼容性。（建议：Victor Gdalevich。）

改进：

  • 增加 S3 的 HTTP 超时时间。
  • 添加 HTTP 重试，增强对 S3 瞬时网络错误的容错能力。

文档改进：

  • 修复文档生成，在配置页面中包含章节摘要。（由 Cynthia Shang 修复，David Steele 审核。）

v1.22 版本说明

修复 S3 重试

发布于 2017 年 8 月 9 日

漏洞修复：

  • 修复 S3 重试中的身份验证问题。

v1.21 版本说明

改进 info 输出及 SSH 端口选项

发布于 2017 年 8 月 8 日

漏洞修复：

  • 恢复时现在会重新创建 archive_status 目录，以支持 PostgreSQL 8.3——该版本与较新版本不同，不会自动重建此目录。（报告者：Stephen Frost。）
  • 修复了执行 stanza-upgrade 后，旧版 PostgreSQL 的空归档目录可能残留的问题。（修复者：Cynthia Shang。审阅者：David Steele。）

新功能：

  • 改进了 info 命令的文本与 JSON 输出，新增归档 ID 字段，以及当前与历史数据库集群版本（如有）在归档中的最小/最大 WAL 信息。（贡献者：Cynthia Shang。审阅者：David Steele。）
  • 新增 --backup-ssh-port 和 --db-ssh-port 选项，支持非默认 SSH 端口。（贡献者：Cynthia Shang。审阅者：David Steele。）

改进：

  • 当 S3 返回内部错误（500）时自动重试。

文档漏洞修复：

  • 根据命令上下文修正了 --online 选项的描述。

文档新功能：

  • 在手动安装说明中新增了创建 /etc/pgbackrest.conf 的步骤。

文档改进：

  • 将仓库选项移入命令行帮助的独立章节。（建议者：Stephen Frost。）

v1.20 版本说明

关键 8.3/8.4 漏洞修复

发布于 2017 年 6 月 27 日

重要说明：使用了表空间的 PostgreSQL 8.3 和 8.4 环境，应立即从任意 v1 版本升级并执行一次全量备份。本版本修复了一个仅影响上述两个版本的漏洞——该漏洞会导致表空间无法被备份。PostgreSQL >= 9.0 不受影响。

漏洞修复：

  • 修复了 PostgreSQL <= 8.4 上表空间无法备份的问题。
  • 修复了 C 库构建时缺少编译标志的问题，该问题会导致在 32 位系统上生成不匹配的二进制文件。（报告者：Adrian Vondendriesch。）

新功能：

  • 新增 s3-repo-ca-path 和 s3-repo-ca-file 选项，支持 IO::Socket::SSL 无法自动定位 CA 的系统（如 RHEL7），或加载自定义 CA。（建议者：Scott Frazer。）

测试套件新功能：

  • 将文档构建纳入 CI 流程。

v1.19 版本说明

S3 支持

发布于 2017 年 6 月 12 日

漏洞修复：

  • 修复了 info 命令，确保显示的 WAL 归档最小/最大值对应当前数据库版本。（修复者：Cynthia Shang。审阅者：David Steele。）
  • 修复了 backup 命令：当备库未配置或不可达时，--backup-standby 选项现在会被重置，并继续在主库上执行备份。（修复者：Cynthia Shang。审阅者：David Steele。）
  • 修复了远程进程产生的配置警告导致主进程报错的问题。（修复者：Cynthia Shang。审阅者：David Steele。）

新功能：

  • 支持将 Amazon S3 作为备份仓库。（审阅者：Cynthia Shang。）

文档漏洞修复：

  • 将配置参考中无效的 max-archive-mb 选项更正为 archive-queue-max。
  • 修复了安装章节中缺少 sudo 的问题。（修复者：Lætitia。审阅者：David Steele。）

v1.18 版本说明

stanza 升级、代码重构与锁机制改进

发布于 2017 年 4 月 12 日

漏洞修复：

  • 修复了一个问题：使用本地工作进程的只读操作（如 restore）会创建写锁，干扰并行 archive-push。（报告者：Jens Wilke。）

新功能：

  • 新增 stanza-upgrade 命令，为 PostgreSQL 主版本升级后的 stanza 升级提供了正式机制。（贡献者：Cynthia Shang。审阅者：David Steele。）
  • 新增对 pgbackrest.conf 的验证功能，当选项无效或所在章节不正确时输出警告。（贡献者：Cynthia Shang。审阅者：David Steele。）

改进：

  • 简化了锁机制。现在仅主进程持有写锁（用于 archive-push 和 backup 命令），不再要求所有本地和远程工作进程都持锁。
  • 不再将备份目录中文件的时间戳同步为与集群目录一致。此做法原本为支持备份续传而设计，该功能现已改由校验和机制实现。
  • 改进了 restore 命令检测到 postmaster.pid 时的错误提示信息。（建议者：Yogesh Sharma。）
  • 将返回码范围从 25~125 重新编号，以避免 PostgreSQL 将某些返回码解释为致命信号异常。（建议者：Yogesh Sharma。）

v1.17 版本说明

页面校验和漏洞修复

发布于 2017 年 3 月 13 日

漏洞修复：

  • 修复了新初始化但未使用的页面触发页面校验和警告的问题。（报告者：Stephen Frost。）

v1.16 版本说明

页面校验和改进、CI 与包测试

发布于 2017 年 3 月 2 日

漏洞修复：

  • 修复了超过 1GB 的表在第一个段之后报告页面校验和警告的问题。（报告者：Stephen Frost。）
  • 修复了使用非默认表空间创建的数据库，对 pg_filenode.map 和 pg_internal.init 产生虚假页面未对齐警告的问题。（报告者：blogh。）

测试套件新功能：

  • 集成 travis-ci 进行持续集成。
  • 为所有受支持发行版自动构建 Debian 软件包。

v1.15 版本说明

代码重构与漏洞修复

发布于 2017 年 2 月 13 日

漏洞修复：

  • 修复了 v1.13 引入的回归问题：构建 manifest 期间若有文件被删除（如表被删除），备份可能失败。（报告者：Navid Golpayegani。）

v1.14 版本说明

代码重构与漏洞修复

发布于 2017 年 2 月 13 日

漏洞修复：

  • 修复了 archive-push 报错后不重试、而是无限期向 PostgreSQL 返回错误（除非手动删除 .error 文件）的问题。（报告者：Jens Wilke。）
  • 修复了并行归档中的竞争条件：多个进程同时尝试创建新路径时会产生错误。（报告者：Jens Wilke。）

改进：

  • 提升了 info 命令中 wal archive min/max 的查询性能。（建议者：Jens Wilke。）

文档新功能：

  • 更新了异步归档文档，更准确地描述了新方法的工作原理及其与旧方法的差异。（建议者：Jens Wilke。）

v1.13 版本说明

并行归档、stanza 创建、改进的 info 与 check

发布于 2017 年 2 月 5 日

重要说明：异步归档的新实现不再将 WAL 复制到独立队列。升级到 1.13 后，旧队列中残留的 WAL 将被放弃，不会 推送到仓库。为避免数据丢失，请在升级前通过设置 archive_command = false 停止归档，然后执行 pgbackrest --stanza=[stanza-name] archive-push 清空异步队列并等待进程结束，确认 [spool-path]/archive/[stanza-name]/out 中的队列已清空，最后再安装 1.13 并恢复原始 archive_command。重要说明：stanza-create 命令不再是可选步骤，在 新 stanza 上执行备份或归档前必须先执行该命令。已有 stanza 无需重新执行。

漏洞修复：

  • 修复了 C 库中 const 赋值导致编译器警告的问题。（修复者：Adrian Vondendriesch。审阅者：David Steele。）
  • 修复了 --repo-sync 选项遗漏的若干目录同步操作。
  • 修复了恢复时因用户/组缺失导致 File->owner() 出现"未初始化值"错误的问题。（报告者：Leonardo GG Avellar。）
  • 修复了协议不匹配错误未输出预期值的问题。
  • 修复了 archive-get 的一条虚假日志消息，该消息错误地将退出码 1 标记为异常终止。

新功能：

  • 改进了异步归档的多进程实现。
  • 改进了 stanza-create 命令，使其能在大多数情况下修复损坏的仓库，并具备足够的健壮性以成为强制执行步骤。（贡献者：Cynthia Shang。审阅者：David Steele。）
  • 改进了 check 命令，使其可在备库上运行；由于副本无法执行 pg_switch_xlog()，仅执行基本检查。（贡献者：Cynthia Shang。审阅者：David Steele。）
  • 在 info 命令中新增了归档和备份的 WAL 范围信息。
  • 在 PostgreSQL < 9.2 中重映射表空间时，新增更新 pg_tablespace.spclocation 的警告提示。（贡献者：blogh。审阅者：David Steele。）
  • 移除了 archive-get、restore、info 和 check 命令的远程锁需求，因为上述均为只读操作。（建议者：Michael Vitale。）

改进：

  • 日志文件头信息现在等到第一条日志条目写入时才输出。（建议者：Jens Wilke。）
  • 通过以备份起始 LSN 过滤，降低了撕裂页面导致页面校验和误报的概率。
  • 从 C 库构建标志中移除了 Intel 专用优化。（贡献者：Adrian Vondendriesch。审阅者：David Steele。）
  • 移除了 --lock 选项。该选项在锁目录可以位于仓库之外前引入，现已废弃。
  • 新增 --log-timestamp 选项，允许在日志中抑制时间戳输出，主要用于自动化文档场景以避免过滤器干扰。
  • 修复了无法将相对路径转换为绝对路径时未返回正确错误码的问题。（建议者：Yogesh Sharma。）

文档新功能：

  • 在用户指南中新增了 process-max 选项的说明文档。（贡献者：Cynthia Shang。审阅者：David Steele。）

v1.12 版本说明

页面校验和、配置改进与漏洞修复

发布于 2016 年 12 月 12 日

重要说明：在此前版本中，命令行上指定对当前命令无效的选项不会报错。现在无效选项将产生错误，请仔细检查环境中的命令行参数以避免升级中断。

漏洞修复：

  • 修复了命令行上提供对指定命令无效的选项时不报错的问题。这些选项虽被忽略且不影响行为，但容易造成混淆。无效选项现在将产生错误。（报告者：Nikhilchandra Kulkarni。）
  • 修复了仓库中表空间内部符号链接未被创建的问题。此问题仅在尝试通过文件系统快照在原地手动启动集群时才会出现，不影响正常的备份与恢复。
  • 修复了日志系统初始化之前（即解析选项期间）错误信息无法输出到控制台的问题。错误码仍会准确返回，进程不会在实际失败时显示为成功。（报告者：Adrian Vondendriesch。）
  • 修复了备份服务器上指定的 db-port 选项，若不来自第一个已配置的数据库则无法正确传递给远程的问题。（报告者：Michael Vitale。）

新功能：

  • 新增 --checksum-page 选项，允许 pgBackRest 在 PostgreSQL >= 9.3 且启用了页面校验和的情况下，验证数据文件中的页面校验和。注意：此功能依赖 C 库，操作系统软件包中可能暂不提供。当 C 库存在且集群启用了校验和时，该选项将自动启用。（建议者：Stephen Frost。）
  • 新增 --repo-link 选项，允许在仓库位于不支持符号链接的文件系统时抑制内部符号链接的创建。这不影响 pgBackRest 的任何核心功能，但不会创建 latest 便捷链接及内部表空间符号链接，从而影响通过文件系统快照在原地手动启动集群的能力。
  • 新增 --repo-sync 选项，允许在不支持目录同步的文件系统（如 NTFS）上禁用仓库目录同步。
  • 新增可预测的日志条目，用于标识命令已成功完成。例如，备份成功结束时将输出：INFO: backup command end: completed successfully。（建议者：Jens Wilke。）

改进：

  • 为简化处理，pg_control 文件现在与其他文件一同复制，不再单独在流程末尾复制。backup 命令不依赖此行为，restore 命令则将文件复制到临时文件，在恢复结束时重命名。

文档漏洞修复：

  • 修复了 PDF 构建中异常抑制的问题。
  • 修复了 v1.10 引入的章节链接回归问题。

文档新功能：

  • 在快速入门章节中新增了保留策略相关内容。

v1.11 版本说明

异步归档效率漏洞修复

发布于 2016 年 11 月 17 日

漏洞修复：

  • 修复了异步归档每次执行只传输一个文件而非批量传输的问题。此回归问题自 v1.09 引入，仅影响效率——异步模式下所有 WAL 段均被正确归档。（报告者：Stephen Frost。）

v1.10 版本说明

stanza 创建与小型漏洞修复

发布于 2016 年 11 月 8 日

漏洞修复：

  • 修复了两次备份之间数据库没有任何变更、仅 pg_control 发生变化时备份可能报错的问题。
  • 修复了前缀相同的表空间路径触发无效链接错误的问题。（报告者：Nikhilchandra Kulkarni。）

新功能：

  • 新增 stanza-create 命令，正式化了在仓库中创建 stanza 的流程。（贡献者：Cynthia Shang。审阅者：David Steele。）

改进：

  • 从 Perl 模块中移除了多余的 use lib 指令。（建议者：Devrim Gündüz。）

v1.09 版本说明

9.6 支持、可配置性改进与漏洞修复

发布于 2016 年 10 月 10 日

漏洞修复：

  • 修复了 check 命令在备份目录不存在时仍记录错误日志消息的问题。（修复者：Cynthia Shang。审阅者：David Steele。）
  • 修复了检测到无效归档命令时错误消息未正确显示该命令的问题。（报告者：Jason O’Donnell。）
  • 修复了一个问题：当 archive-push 没有足够空间排队新 WAL 段时，异步归档进程不会被启动，导致队列永远无法清空（除非手动干预）。现在，当空间不足时 PostgreSQL 会收到错误，但异步进程仍会被启动，以便最终释放空间。（报告者：Jens Wilke。）
  • 修复了一个远程超时问题：本地进程在生成校验和（续传或恢复期间）而未复制文件时，远程进程可能进入空闲状态。（报告者：Jens Wilke。）

新功能：

  • 在 PostgreSQL 9.6 上将自动使用非独占备份。
  • 新增 cmd-ssh 选项，允许指定 SSH 客户端。（建议者：Jens Wilke。）
  • 新增 log-level-stderr 选项，控制台日志消息输出到 stderr 还是 stdout。默认值为 warn，与旧版本行为略有不同，但更符合直觉。设置 log-level-stderr=off 可恢复旧行为。（建议者：Sascha Biberhofer。）
  • 将数据库连接的 application_name 设置为 "pgBackRest [command]"。（建议者：Jens Wilke。）
  • 当 archive-check 选项启用时，检查 archive_mode 是否已开启。

改进：

  • 优化了无法获取 pgBackRest 顾问锁时的错误提示，明确说明这不是 PostgreSQL 备份锁。（建议者：Jens Wilke。）
  • 命令启动的 INFO 日志中包含 pgBackRest 版本号。
  • 本地进程启动/停止的 INFO 日志中记录进程 ID。

文档新功能：

  • 在用户指南中新增了 archive-timeout 选项的说明文档。（贡献者：Cynthia Shang。审阅者：David Steele。）

v1.08 版本说明

漏洞修复与日志改进

发布于 2016 年 9 月 14 日

漏洞修复：

  • 修复了本地进程完成后未断开连接、可能导致稍后超时的问题。（报告者：Todd Vernick。）
  • 修复了协议层在等待 WAL 段到达归档时可能超时的问题。（报告者：Todd Vernick。）

改进：

  • 缓存文件日志输出，直到文件创建完成，以生成更完整的日志记录。

v1.07 版本说明

线程转进程及漏洞修复

发布于 2016 年 9 月 7 日

漏洞修复：

  • 修复了备库备份期间表空间从主库复制的问题。
  • 修复了 check 命令：备份信息现在同时在远程和本地进行检查，而不仅仅在本地。（修复者：Cynthia Shang。审阅者：David Steele。）
  • 修复了 retention-archive-type=diff 时 retention-archive 未被自动设置、导致归档过期不积极的问题。（修复者：Cynthia Shang。审阅者：David Steele。）

新功能：

  • 将 Perl 线程转换为进程，提高兼容性与性能。
  • 排除 $PGDATA/pg_replslot 目录内容，防止主库上的复制槽被纳入备份。
  • 即使 archive-check=n，archive-start 和 archive-stop 设置也会写入 backup.manifest。（建议者：Jens Wilke。）
  • 当归档保留策略设置可能未达到预期效果或会导致无限期保留时，新增额外警告。（贡献者：Cynthia Shang。审阅者：David Steele。）
  • 对 PostgreSQL 9.6 rc1 的非独占备份提供实验性支持。后续候选版本中控制/目录/WAL 版本的变更可能破坏兼容性，但 pgBackRest 将跟随每个版本更新。

文档漏洞修复：

  • 修复了与二进制路径相关的文档可复现性问题。

文档新功能：

  • 新增归档保留策略文档。（贡献者：Cynthia Shang。审阅者：David Steele。）

v1.06 版本说明

从备库备份与漏洞修复

发布于 2016 年 8 月 25 日

漏洞修复：

  • 修复了引用另一个链接的表空间链接不报错、而是直接跳过该表空间的问题。（报告者：Michael Vitale。）
  • 修复了 pgbackrest.conf 中不允许多值的选项可被多次指定而不报错的问题。（报告者：Michael Vitale。）
  • 修复了增大 db-timeout 选项时 protocol-timeout 未自动同步增大的问题。（报告者：Todd Vernick。）

新功能：

  • 支持从备库集群执行备份。仍需连接主库以启动/停止备份并复制未被复制的文件，但绝大多数文件从备库复制，从而降低主库负载。
  • 更灵活的数据库配置。主库和备库均可在备份服务器上配置，pgBackRest 将自动判断哪个是主库。使用独立备份服务器时，主备切换后无需修改备份配置。
  • 备份时排除 PostgreSQL 启动时会清理、重建或清零的目录，包括 pgsql_tmp 和 pg_stat_tmp。postgresql.auto.conf.tmp 文件现在也被排除，此外还有之前已排除的文件：backup_label.old、postmaster.opts、postmaster.pid、recovery.conf、recovery.done。
  • 对 PostgreSQL 9.6 beta4 的非独占备份提供实验性支持。后续 Beta 版本中控制/目录/WAL 版本的变更可能破坏兼容性，但 pgBackRest 将跟随每个版本更新。

改进：

  • 改进了 manifest 构建中链接指向另一链接时的错误消息。
  • 在 archive-push 或 archive-get 中检测到相对路径时，在错误消息中添加了提示信息。
  • 改进了备份日志消息，明确指出文件正在从哪台主机复制。

v1.05 版本说明

表空间链接检查漏洞修复

发布于 2016 年 8 月 9 日

漏洞修复：

  • 修复了一个问题：以 $PGDATA 为子字符串的表空间路径，即使实际上不是 $PGDATA 的子目录，也会被误识别为子目录。同时对相对路径检查进行了加固。（报告者：Chris Fort。）

文档新功能：

  • 新增了使用 cron 调度备份的文档。（贡献者：Cynthia Shang。审阅者：David Steele。）

文档改进：

  • 将积压事项从 pgBackRest 网站迁移到 GitHub 仓库 Wiki。（贡献者：Cynthia Shang。审阅者：David Steele。）

v1.04 版本说明

各类漏洞修复

发布于 2016 年 7 月 30 日

漏洞修复：

  • 修复了多余远程连接导致多线程备份/恢复可能超时或产生锁冲突的问题。（报告者：Michael Vitale。）
  • 修复了 check 命令未强制要求 db-path、缺失时触发断言而非友好错误消息的问题。（报告者：Michael Vitale。）
  • 修复了 check 命令在数据库版本/ID 与归档不匹配时未抛出错误的问题。（修复者：Cynthia Shang。审阅者：David Steele。）
  • 修复了数据库服务器的 pgbackrest.conf 中没有 backup-host 选项时，远程进程可能尝试启动自身远程进程的问题。（报告者：Lardière Sébastien。）
  • 修复了 pg_xlog 目录为符号链接时其内容被纳入备份的问题。这不会影响恢复，但会浪费存储空间。
  • 修复了锁操作中一个无效的 log() 调用。

新功能：

  • 对 PostgreSQL 9.6 beta3 的非独占备份提供实验性支持。后续 Beta 版本中控制/目录/WAL 版本的变更可能破坏兼容性，但 pgBackRest 将跟随每个版本更新。

改进：

  • 抑制 SSH 协议连接上的横幅信息。
  • 改进了远程错误消息，标识出发生错误的主机。
  • 所有远程类型现在都会获取锁。此前的例外情况源于测试框架和 pgBackRest 运行在同一虚拟机中的历史原因，现已不再适用。

文档新功能：

  • 新增了关于 backrest-user 选项默认值为 backrest 的说明。（建议者：Michael Vitale。）
  • 更新了受支持平台上软件包可用性的相关信息。（建议者：Michael Vitale。）

v1.03 版本说明

check 命令与漏洞修复

发布于 2016 年 7 月 2 日

漏洞修复：

  • 修复了多线程 backup 期间大量小文件导致 keep-alive 被抢占，以及单/多线程备份续传和 restore 校验和计算中完全缺少 keep-alive 的问题。（报告者：Janice Parkinson、Chris Barber。）
  • 修复了设置 db-host 选项后从命令行显式调用 expire 命令被拒绝执行的问题。备份后自动运行 expire 时不受此问题影响。（报告者：Chris Barber。）
  • 修复了即使禁用 archive-check 选项，仍会验证 archive_command 的问题。

新功能：

  • 新增 check 命令，用于验证 pgBackRest 的归档和备份配置是否正确。（贡献者：Cynthia Shang。审阅者：David Steele。）
  • 新增 protocol-timeout 选项。此前该值固定为 db-timeout + 30 秒。
  • 备份结束时远程关闭失败不再抛出异常，改为生成建议提高 protocol-timeout 的警告。
  • 对 PostgreSQL 9.6 beta2 的非独占备份提供实验性支持。后续 Beta 版本中控制/目录/WAL 版本的变更可能破坏兼容性，但 pgBackRest 将跟随每个版本更新。

改进：

  • 改进了备份时捕获的用户/组在恢复主机上不存在的处理方式，同时明确处理了用户/组未映射到名称的情况。
  • 选项处理现在更加严格。此前命令可能使用未明确分配给它的选项，backup-host 和 db-host 选项尤为如此，这两个选项用于判断操作是否为本地执行。

文档改进：

  • 允许在文档中使用静态日期，以生成可复现的构建结果。（建议者：Adrian Vondendriesch。）
  • 在用户指南中新增了异步归档的文档。（贡献者：Cynthia Shang。审阅者：David Steele。）
  • pgBackRest 模块的推荐安装位置更改为 /usr/share/perl5，因为 /usr/lib/perl5 在较新版本的 Perl 中已从搜索路径中移除。
  • 新增了删除旧版本 pgBackRest 的操作说明。

v1.02 版本说明

修复 Perl 5.22 兼容性

发布于 2016 年 6 月 2 日

漏洞修复：

  • 修复了 sprintf() 的使用方式，使其符合 Perl 5.22 的新限制——格式字符串中不再允许未引用的参数。（修复者：Adrian Vondendriesch。审阅者：David Steele。）

文档漏洞修复：

  • 修复了与 Perl 5.2X 不兼容的语法。（修复者：Christoph Berg、Adrian Vondendriesch。审阅者：David Steele。）
  • 修复了 PDF 徽标中使用绝对路径的问题。（报告者：Adrian Vondendriesch。）

文档新功能：

  • 发布说明现在按章节划分，明确区分漏洞修复、新功能和代码重构。新增"附加说明"章节，用于记录不影响核心代码的文档和测试套件变更。
  • 新增 man 页面生成功能。（贡献者：Adrian Vondendriesch、David Steele。）
  • 变更日志是最后一个仅以 Markdown 格式渲染的文档。现编写了转换器使其可由标准渲染器输出。变更日志现已发布在网站上，并更名为"发布说明（Releases）"。（贡献者：Cynthia Shang。审阅者：David Steele。）

v1.01 版本说明

增强的 info、选择性恢复与 9.6 支持

发布于 2016 年 5 月 17 日

新功能：

  • 增强了 info 命令的文本输出，包含所有备份的时间戳、大小和参考列表。（贡献者：Cynthia Shang。审阅者：David Steele。）
  • 支持从集群备份中选择性恢复指定数据库。当只需恢复特定数据库时，此功能可大幅节省空间和时间。未恢复的数据库将不可访问，在从共享目录中删除前须手动处理。（审阅者：Cynthia Shang、Greg Smith、Stephen Frost。建议者：Stephen Frost。）
  • 对 PostgreSQL 9.6 beta1 的非独占备份提供实验性支持。后续 Beta 版本中控制/目录/WAL 版本的变更可能破坏兼容性，但 pgBackRest 将跟随每个版本更新。（审阅者：Cynthia Shang。）

v1.00 版本说明

新仓库格式与配置方案、链接支持

发布于 2016 年 4 月 14 日

重要说明：此次重大版本变更与旧版本 pgBackRest 不兼容。manifest 格式、磁盘目录结构、配置方案以及可执行文件/路径名称均已变更。您必须为此版本的 pgBackRest 创建新仓库以存储备份，并暂时保留旧仓库以备恢复之需。从旧仓库恢复需使用旧版本的 pgBackRest，但由于名称变更，可同时安装 1.00 与旧版本。具体变更如下。

新功能：

  • 实现了全新的配置方案，使用更为简便。详见用户指南和配置参考。对于简单配置，所有选项现在都可以放在 stanza 章节中；多个 stanza 间共享的选项可以放在 [global] 章节；更复杂的配置仍可使用命令章节，但这应属于少见情况。（建议者：Michael Renner。）
  • repo-path 选项现在始终指向存储备份和归档的仓库，无论本地还是远程，因此 repo-remote-path 选项已被移除。新增 spool-path 选项，可用于定义异步归档时排队 WAL 段的位置。本地仓库不再是必需的。
  • 默认配置文件名由 pg_backrest.conf 改为 pgbackrest.conf，以与其他命名变更保持一致，同时防止迁移到 1.00 时意外加载旧配置文件。（建议者：Michael Renner、Stephen Frost。）
  • 默认仓库路径由 /var/lib/backup 改为 /var/lib/pgbackrest。（建议者：Michael Renner、Stephen Frost。）
  • 锁文件现在默认存储在 /tmp/pgbackrest 中。目前 /run/pgbackrest 是首选位置，但这需要初始化脚本，本版本暂不包含。可使用 lock-path 选项配置锁目录。
  • 日志文件现在默认存储在 /var/log/pgbackrest 中，文件名不再追加日期，便于使用 logrotate 管理。可使用 log-path 选项配置日志目录。（建议者：Stephen Frost。）
  • 可执行文件名由 pg_backrest 改为 pgbackrest。（建议者：Michael Renner、Stephen Frost。）
  • PGDATA 中所有链接的文件和目录现在均包含在备份中。默认情况下，链接在恢复时将直接作为文件或目录还原到 PGDATA 中。可使用 --link-all 选项将所有链接恢复到其原始位置，或使用 --link-map 选项将链接重新映射到新位置。
  • 移除了 --tablespace 选项，以 --tablespace-map-all 选项替代，更清晰地表达其功能。
  • 新增 detail 日志级别，输出介于 info 和 debug 之间的详细信息。

预稳定版本

v0.92 版本说明

命令行仓库路径修复

发布于 2016 年 4 月 6 日

漏洞修复：

  • 修复了主进程将 --repo-remote-path 而非 --repo-path 传递给远程的问题，该问题导致锁文件被创建在默认仓库目录（/var/lib/backup）中，通常以失败告终。此问题仅在命令行（而非 pg_backrest.conf）中定义了 --repo-remote-path 时才会出现。（报告者：Jan Wieck。）

v0.91 版本说明

表空间漏洞修复与小型改进

发布于 2016 年 3 月 22 日

表空间重要漏洞修复：v0.90 意外引入了仓库格式变更，导致包含表空间的备份在磁盘上不再是有效的 PostgreSQL 集群。此问题仅影响直接复制备份来恢复 PostgreSQL 集群（而非使用 restore 命令）的用户。无论采用哪种恢复方式，此修复与包含表空间的旧备份均不兼容（pgBackRest 将抛出错误并拒绝恢复）。对于包含表空间的集群，安装 v0.91 后应立即执行新的全量备份。如需恢复旧备份，请使用与备份版本匹配的 pgBackRest 版本。

漏洞修复：

  • 修复了 pgBackRest v0.90 引入的仓库不兼容问题。（报告者：Evan Benoit。）

新功能：

  • 备份时最后复制 global/pg_control。
  • 将 .info 和 .manifest 文件先写入临时文件，再移动到最终位置并执行 fsync。
  • 将 --no-start-stop 选项重命名为 --no-online。

测试套件新功能：

  • 使用 Perl-Critic 进行静态源码分析，目前在 gentle（宽松）级别通过。

v0.90 版本说明

9.5 支持、各类改进与小型漏洞修复

发布于 2016 年 2 月 7 日

漏洞修复：

  • 修复了指定 --no-archive-check 时抛出配置错误的问题。（报告者：Jason O’Donnell。）
  • 修复了系统在恰当时机崩溃后遗留的临时 WAL 文件导致下次 archive-push 失败的问题。
  • retention-archive 选项现在可以安全地设置为低于备份保留值（retention-full 或 retention-diff），而无需同时指定 archive-copy=n。使超出归档保留范围的备份保持一致性所需的 WAL 将被保留在归档中。但在此情况下，超出归档保留范围的备份将无法进行 PITR。

新功能：

  • 备份和恢复表空间时，pgBackRest 仅操作为当前运行的 PostgreSQL 版本创建的子目录。由于多个版本可以共用同一个表空间目录（尤其是在二进制升级期间），这可以防止备份时复制过多文件，以及恢复时可能清除其他版本数据。此特性仅适用于 PostgreSQL >= 9.0——更早版本不支持共享表空间目录。
  • 当 archive-check=y 但 archive_command 不执行 pg_backrest 时，生成错误。（贡献者：Jason O’Donnell。审阅者：David Steele。）
  • 改进了 repo-path 或 repo-remote-path 不存在时的错误消息。
  • 为 --delta 和 --force 恢复选项新增了检查，确保目标是有效的 $PGDATA 目录。pgBackRest 将检查 PG_VERSION 或 backup.manifest（中止恢复的遗留文件）是否存在。如果两个文件均不存在，--delta 和 --force 将被禁用，但恢复仍会继续——除非 $PGDATA 目录（或任何表空间目录）中有文件存在，此时操作将被中止。
  • 当 restore --set=latest（默认值）时，实际恢复的备份将输出到日志中。
  • 支持 PostgreSQL 9.5 的部分 WAL 段和 recovery_target_action 设置。archive_mode = 'always' 暂不支持。
  • 支持 PostgreSQL 9.4 引入的 recovery_target = 'immediate' 恢复设置。
  • 新增以下表空间检查：pg_tblspc 中存在路径或普通文件、pg_tblspc 中存在相对链接、$PGDATA 中存在表空间。以上三种情况均会产生错误。

v0.89 版本说明

超时漏洞修复与只读仓库恢复

发布于 2015 年 12 月 24 日

漏洞修复：

  • 修复了使用远程和多线程时，长时间运行的备份/恢复会超时的问题。现在使用 keepalive 确保主进程的远程连接在线程处理所有工作期间不会超时。同时改进了超时的错误消息，便于调试。（报告者：Stephen Frost。）

新功能：

  • 允许通过 --no-lock 和 --log-level-file=off 在只读仓库上执行恢复。--no-lock 选项仅用于恢复操作。

v0.88 版本说明

文档与小型漏洞修复

发布于 2015 年 11 月 22 日

漏洞修复：

  • 修复了 start/stop 命令要求提供 --config 选项的问题。（报告者：Dmitry Didovicher。）
  • 修复了日志文件被覆盖而非追加写入的问题。（报告者：Stephen Frost、Dmitry Didovicher。）
  • 修复了 backup-user 不是可选项的问题。

新功能：

  • 备份仓库目录中不再创建符号链接。这些符号链接可能指向任意位置，存在安全风险。恢复时仍会重新创建符号链接。（建议者：Stephen Frost。）
  • 改进了备份过期的消息输出。全量和差异备份的过期信息现在合并为一行记录，并附带所有关联备份的列表。
  • 如果归档保留策略未显式配置，则自动设置为与全量备份保留策略一致。

文档新功能：

  • 在用户指南中新增了 delta 恢复、过期策略、专用备份主机、启动和停止 pgBackRest 以及复制相关文档。

v0.87 版本说明

网站与用户指南

发布于 2015 年 10 月 28 日

新功能：

  • backup_label.old 和 recovery.done 文件现在从备份中排除。

文档新功能：

  • 新增用户指南，涵盖 pgBackRest 基础知识及部分高级主题（包括 PITR）。内容还会持续扩充，这是一个良好的开端。（贡献者：David Steele、Stephen Frost。审阅者：Michael Renner、Cynthia Shang、Eric Radman、Dmitry Didovicher。）

v0.85 版本说明

start/stop 命令与小型漏洞修复

发布于 2015 年 10 月 8 日

漏洞修复：

  • 修复了备份或恢复成功完成后仍可能返回错误的问题。
  • 修复了备份失败时根备份目录中残留临时文件、导致续传失败的问题。备份进程在复制阶段被终止时很可能出现此情形。

新功能：

  • 新增 stop 和 start 命令，用于在 PostgreSQL 关闭或系统需要以其他原因静默时，阻止 pgBackRest 进程运行。
  • 对 PostgreSQL 9.5 beta1 提供实验性支持。未来版本中控制版本或 WAL magic 变更时可能发生兼容性问题，但 pgBackRest 将跟随每个版本更新。除 --target-resume 测试（此功能在 9.5 中已更改）外，所有回归测试均通过，.partial WAL 段暂未测试。

v0.82 版本说明

代码重构、命令行帮助与小型漏洞修复

发布于 2015 年 9 月 14 日

漏洞修复：

  • 修复了续传的压缩备份未保留已有文件的问题。
  • 修复了续传与增量/差异备份未检验前序备份是否具有相同压缩和硬链接设置的问题。
  • 修复了未指定 --force 时，使用 --no-start-stop 的冷备份可能在运行中的 PostgreSQL 集群上启动的问题。
  • 修复了即使未请求线程也可能启动一个线程的问题。
  • 修复了升级/降级后 backup.info 和 archive.info 中 pgBackRest 版本号未被更新的问题。
  • 修复了仓库中没有 stanza 时 info 命令抛出异常的问题。（报告者：Stephen Frost。）
  • 修复了 PostgreSQL 的 pg_stop_backup() NOTICE 信息被输出到 stderr 的问题。（报告者：Stephen Frost。）

新功能：

  • 对 PostgreSQL 9.5 alpha2 提供实验性支持。未来版本中控制版本或 WAL magic 变更时可能发生兼容性问题，但 pgBackRest 将跟随每个版本更新。除 --target-resume 测试（此功能在 9.5 中已更改）外，所有回归测试均通过，.partial WAL 段暂未测试。

改进：

  • 将 recovery-setting 选项和章节重命名为 recovery-option，与 pgBackRest 命名约定保持一致。
  • 新增动态模块加载，加快命令执行速度，尤其是异步归档场景。

文档新功能：

  • 命令行帮助现在从与其他文档共用的同一 XML 源中提取，包含更多详细信息。

v0.80 版本说明

DBI 支持、稳定性与便利性改进

发布于 2015 年 8 月 9 日

漏洞修复：

  • 修复了 info 命令将最旧和最新备份的格式化时间戳都显示为当前时间的问题。仅 text 输出受影响，json 输出报告的 epoch 值是正确的。（报告者：Michael Renner。）
  • 修复了阻止 SSH 错误（尤其是连接时）被记录的协议问题。

新功能：

  • 仓库现在以统一的目录和文件权限模式创建和更新。默认情况下 umask 被设置为 0000，可通过 neutral-umask 设置禁用。（建议者：Cynthia Shang。）
  • 新增 stop-auto 选项，允许在启动新备份时自动停止失败的备份。
  • 新增 db-timeout 选项，限制 pgBackRest 等待 pg_start_backup() 和 pg_stop_backup() 返回的最长时间。
  • 恢复开始时移除 pg_control 文件，在最后才将其复制回去，防止 PostgreSQL 启动部分恢复的实例。
  • 新增检查，通过比较集群报告的 data_directory 与 db-path 设置，以及集群报告的版本与从 pg_control 读取的值，确保 db-path 与 db-port 设置一致。同时检查 db-socket-path 是否为绝对路径。
  • 对 PostgreSQL 9.5 alpha1 提供实验性支持。未来版本中控制版本或 WAL magic 变更时可能发生兼容性问题，但 pgBackRest 将跟随每个版本更新。除 --target-resume 测试（此功能在 9.5 中已更改）外，所有回归测试均通过，.partial WAL 段暂未测试。

改进：

  • 现在使用 Perl 的 DBI 和 DBD::Pg 连接 PostgreSQL，替代原来的 psql。cmd-psql 和 cmd-psql-option 设置已被移除，替换为 db-port 和 db-socket-path。请按照安装指南在您的操作系统上安装 DBD::Pg。

测试套件新功能：

  • 新增了 Ubuntu 14.04 和 CentOS 7 的 vagrant 测试配置。

v0.78 版本说明

移除 CPAN 依赖、稳定性改进

发布于 2015 年 7 月 13 日

改进：

  • 移除了多线程操作对 CPAN 软件包的依赖。更新 threads 和 Thread::Queue 软件包并非坏事，但现在不再是必须。
  • 将等待退避策略由等比数列改为斐波那契数列，等待时间增长更为平缓，同时保持合理的上限。

测试套件新功能：

  • 新增了 Ubuntu 12.04 和 CentOS 6 的 vagrant 测试配置。

v0.77 版本说明

CentOS/RHEL 6 支持与协议改进

发布于 2015 年 6 月 30 日

新功能：

  • 在 File 对象中新增了文件和目录同步，为备份/恢复和归档操作提供额外的数据安全保障。（建议者：Andres Freund。）
  • 新增对 CentOS/RHEL 6 默认版本 Perl 5.10.1 和 OpenSSH 5.3 的支持。（建议者：Eric Radman。）
  • 改进了未设置 archive_command 且未指定 --no-archive-check 时运行备份的错误消息。（建议者：Eric Radman。）

v0.75 版本说明

新仓库格式、info 命令与实验性 9.5 支持

发布于 2015 年 6 月 14 日

重要说明：此次重大版本变更与旧版本 pgBackRest 不兼容。manifest 格式、磁盘目录结构以及二进制文件名均已变更。您必须为此版本的 pgBackRest 创建新仓库以存储备份，并暂时保留旧仓库以备恢复之需。pg_backrest.conf 配置文件未变更，但需要将 cron（或其他位置）中对 pg_backrest.pl 的引用改为 pg_backrest（去掉 .pl 扩展名）。

新功能：

  • 新增 info 命令。
  • 日志现在使用非缓冲输出，使多线程并发写入的日志文件更加有序。（建议者：Michael Renner。）
  • 对 PostgreSQL 9.5 提供实验性支持。控制版本或 WAL magic 变更时可能发生兼容性问题，但将在每个版本中同步更新。

改进：

  • 改进了 backup 的文件处理顺序，按文件大小降序复制，防止单个线程在末尾处理大文件。此优化此前已在 restore 中实现。

v0.70 版本说明

归档稳定性改进、日志与帮助优化

发布于 2015 年 6 月 1 日

漏洞修复：

  • 修复了 hardlink=n 时 archive-copy 在增量/差异备份中失败的问题。此情况下 pg_xlog 路径不存在，必须先创建。（报告者：Michael Renner。）
  • 修复了异步归档中 archive-max-mb 达到上限时 archive-push 未正确返回 0 的问题；同时将异步检查移到传输之后，以避免重复删除停止文件。新增了此情况的单元测试，并改进了错误消息，使用户更清楚地了解出错原因。（报告者：Michael Renner。）
  • 修复了一个锁定问题，该问题可能允许对同一 stanza 同时执行多个相同类型的操作。此问题在数据完整性方面似乎无害，但在归档时会引起虚假错误，并可能导致备份/恢复出错。（报告者：Michael Renner。）

新功能：

  • 允许在校验和匹配的情况下归档重复 WAL 段，这对某些恢复场景是必要的。
  • 允许在 pg_backrest.conf 中使用 # 字符进行注释/禁用。仅当 # 位于行首时才生效。（建议者：Michael Renner。）
  • 改进了 pg_start_backup() 之前的日志输出，当备份在等待检查点时输出更为明确。（建议者：Michael Renner。）
  • 各命令行为和日志修复。（审阅者：Michael Renner。建议者：Michael Renner。）

改进：

  • 将 JSON 模块替换为随核心 Perl 一起发布的 JSON::PP。

文档漏洞修复：

  • 各类帮助文档修复。（审阅者：Michael Renner。报告者：Michael Renner。）

v0.65 版本说明

改进的续传与恢复日志、紧凑恢复

发布于 2015 年 5 月 11 日

漏洞修复：

  • 修复了使用相对路径运行恢复时 recovery.conf 中未写入绝对路径的问题。

新功能：

  • 改进了续传支持。续传的文件会被检查以确保未被修改，manifest 保存频率更高，以在备份进行时保留校验和。新增了更多单元测试以验证各续传场景。
  • 续传现在是可选的，可通过 resume 设置或命令行的 --no-resume 禁用。
  • 恢复时的 info 级别消息更加详尽。此前大部分恢复消息为 debug 级别，日志中输出内容有限。
  • 新增 tablespace 设置，允许将表空间恢复到 pg_tblspc 路径中，产生紧凑型恢复，便于开发、测试等场景使用。目前此类恢复无法再次备份，因为 pgBackRest 要求 pg_tblspc 路径中只能有链接。

v0.61 版本说明

非压缩远程目标漏洞修复

发布于 2015 年 4 月 21 日

漏洞修复：

  • 修复了将大型高可压缩文件复制到非压缩远程目标时可能出现的缓冲错误。该错误在解压代码中被检测到并导致备份失败，而非产生数据损坏，因此不应影响使用旧版本成功完成的备份。

v0.60 版本说明

更好的版本支持与 WAL 改进

发布于 2015 年 4 月 19 日

漏洞修复：

  • 修复了推送重复 WAL 段不产生错误的问题。此前仅在禁用校验和时有效。

新功能：

  • 使用数据库系统 ID 确保归档中所有 WAL 均来自同一集群，有助于防止将多个集群的 WAL 发送到同一归档的配置错误。

测试套件新功能：

  • 回归测试支持追溯至 PostgreSQL 8.3。

v0.50 版本说明

恢复功能及更多改进

发布于 2015 年 3 月 25 日

漏洞修复：

  • 修复了校验和问题，现在校验和可以在正常备份和续传备份中正常工作。校验和与校验和 delta 在功能上应该分离，这简化了许多逻辑。Issue #28 已为校验和 delta 创建。
  • 修复了可能从类型或前序备份不匹配的中止备份中续传的问题。

新功能：

  • 新增恢复功能。
  • 所有选项现在均可在命令行上设置，pg_backrest.conf 成为可选。
  • 压缩/解压现在在非线程模式下执行，校验和/大小在流中计算，文件校验和不再是可选项。
  • 新增 --no-start-stop 选项，允许在 PostgreSQL 关闭时进行备份。如果 postmaster.pid 存在，则需要 --force 才能运行备份（但如果 PostgreSQL 正在运行，可能会创建不一致的备份）。此选项主要为单元测试目的而添加，但在实际环境中也可能有应用场景。
  • 为 backup.manifest 添加校验和，以检测损坏或被修改的 manifest 文件。
  • latest 链接始终指向最后一次备份，便于使用并简化恢复操作。

测试套件新功能：

  • 在各方面新增了更全面的单元测试。

v0.30 版本说明

核心重构与单元测试

发布于 2014 年 10 月 5 日

文档新功能：

  • 新增了亟需的文档。

测试套件新功能：

  • 对所有基本操作进行了相当全面的单元测试。当然，单元测试方面总是还有更多工作可做。

v0.19 版本说明

改进的错误报告/处理

发布于 2014 年 5 月 13 日

漏洞修复：

  • 发现并修复了一个严重漏洞：file_copy() 被默认设置为忽略错误。file_exists() 中也存在一个问题，会导致在文件实际存在时测试失败。两者共同作用，理论上可能在无任何错误提示的情况下产生损坏的备份，但概率极低。

v0.18 版本说明

归档缺失时返回软错误

发布于 2014 年 4 月 13 日

漏洞修复：

  • 当归档文件缺失时，archive-get 命令现在返回 1，以区别于硬错误（SSH 连接失败、文件复制错误等），让 PostgreSQL 知道归档流已正常终止。但需注意，这并未考虑归档流中可能存在空洞的情况。（报告者：Stephen Frost。）

v0.17 版本说明

归档目录无法删除时发出警告

发布于 2014 年 4 月 3 日

漏洞修复：

  • 如果应为空的归档目录无法被删除，之前 pgBackRest 会抛出错误。目前有一个更好的修复方案正在开发中，暂时将其改为警告以允许处理继续。此问题影响了备份流程——在某些情况下，如果第一个归档文件与第二个归档文件在不同目录中，最后的归档文件可能无法被推送。

v0.16 版本说明

SSH 会话添加 RequestTTY=yes

发布于 2014 年 4 月 1 日

漏洞修复：

  • 在 SSH 会话中添加了 RequestTTY=yes，以防止随机挂起问题。

v0.15 版本说明

新增 archive-get

发布于 2014 年 3 月 29 日

新功能：

  • 新增 archive-get 功能，辅助恢复操作。
  • 新增启动备份时强制执行检查点的选项：start-fast=y。

v0.11 版本说明

小型修复

发布于 2014 年 3 月 26 日

漏洞修复：

  • 移除了数据库 SSH 连接上的 master_stderr_discard 选项。此前偶发挂起问题，可能与文件代码中最初发现的问题相关。（报告者：Stephen Frost。）
  • 将 backup 和 expire 命令的锁文件冲突级别改为 ERROR。此前由于从归档锁代码复制粘贴，误设为 DEBUG。

v0.10 版本说明

备份与归档功能可用

发布于 2014 年 3 月 5 日

新功能：

  • 暂无恢复功能，但备份目录是一致的 PostgreSQL 数据目录。需要手动解压文件，或在备份时关闭压缩。在 ZFS（或类似）文件系统上使用非压缩备份是一个好选择，可以通过快照在本地恢复备份，用于创建逻辑备份或进行点数据恢复。
  • 归档为单线程。在多太字节数据库（高写入量）上，这并未造成问题。建议使用较大的 WAL 卷，或配合大容量卷使用异步选项。
  • 备份为多线程，但 Net::OpenSSH 库似乎并非 100% 线程安全，偶尔会在某个线程上发生死锁。现有一个整体进程超时机制，通过终止进程来解决此问题——是的，这很粗糙。
  • 任何续传备份都会丢失校验和。多次续传时只有最终备份会记录校验和。之前备份的校验和可以正确记录，全量备份将重置所有内容。
  • backup.manifest 正在以 Storable 格式写入，因为 Config::IniFile 似乎不能很好地处理大文件。理想情况下希望将这些文件保存为人类可读的文本格式。

文档新功能：

  • 完全没有文档（代码之外）。嗯，除了这份发布说明。

7 - 常见问题解答

关于 pgBackRest 备份、恢复、配置与故障排查的常见问题解答。

原始页面： https://pgbackrest.org/faq.html

简介

常见问题解答旨在针对一些具体问题提供详细说明，这些问题可能未在用户指南、配置参考或命令参考中涵盖。如果在此处找不到您的问题，pgBackRest 在 GitHub 上的 Issues List 也是一个宝贵的资源。

遇到"could not find WAL segment"错误该怎么办？

此错误可能有多种原因，包括但不限于：

  • archive_command 配置错误
  • pgBackRest 配置文件配置错误
  • 网络或权限问题
  • 第三方产品（如 S3、Swift 或 MinIO）配置问题
  • 大量 WAL 积压等待归档

建议按以下步骤排查：

  • 检查 PostgreSQL 中的 archive_command 配置
  • 检查每台主机上的 pgBackRest 配置（例如，pg* 系列选项应配置在仓库主机上，repo* 系列选项应配置在数据库主机上）
  • 使用比配置文件（或默认值）更大的 --archive-timeout 值运行 check 命令，判断 WAL 队列是否需要更长时间才能清空。若系统产生大量 WAL，可考虑配置 异步归档。

如何手动清除一个备份集？

可以使用 --set 选项手动使某个全量备份集过期，详见 命令参考：expire。

如何为每个命令独立配置选项？

pgBackRest 支持在配置文件中为每个命令单独设置选项。 配置集群 stanza 章节详细介绍了此功能及选项优先级规则。

例如，可以针对每个命令分别优化 process-max 选项：

INI
[global]
# 未被覆盖时的通用配置
process-max=2

[global:backup]
# 备份时使用更多核心
process-max=4

[global:restore]
# 恢复时使用全部核心
process-max=8

[global:archive-push]
# 归档推送时使用更多核心
process-max=3

[global:archive-get]
# 归档获取时使用较少核心
process-max=1

S3 存储桶名称中可以使用点号（句点）吗？

不可以。RFC-2818 不允许通配符匹配点号（.），因此 S3 存储桶名称不得包含点号。若存储桶名称中含有点号，将会出现类似"unable to find hostname ‘my.backup.bucket.s3.amazonaws.com’ in certificate common name or subject alternative names"的错误。

在哪里可以找到旧版本 pgBackRest 的软件包？

apt.postgresql.org 仓库维护了一个 旧版本归档。Debian 也维护了所有测试构建版本的 快照。

为什么当 backup-standby=y 且备库宕机时，备份会失败？

从备库执行备份，初衷通常是减轻主库的压力。因此，当备库宕机时将备份切换到主库往往适得其反——系统已出现故障，不建议此时再增加主库负担。只要有相对新鲜的备份，备份本身并不紧迫；更重要的是保持 WAL 归档持续进行。等系统恢复稳定后再补做备份，时间仍然充裕。

如果确实需要立即执行备份，可以增加备库数量，或移除 backup-standby 配置。也可以在命令行使用 --no-backup-standby 临时覆盖，无需修改配置文件即可执行一次性备份。

是否应该将仓库部署在备库主机上？

不应该。同时配置了主库和备库时，pgBackRest 的配置文件应保持对称，以便在故障切换后无缝衔接。若配置不对称，故障切换后需要手动修改配置，否则可能引发更多问题。

详情请参阅用户指南中的 专用仓库主机 章节。

基于时间的时间点恢复（PITR）似乎不起作用，为什么？

使用基于时间的 PITR 时，最常见的错误是忘记选择目标时间点之前的备份集。若未指定 --set 选项，pgBackRest 会从 --target= 所指定的时间点往前查找可用的备份集；若找不到合适的备份集，则默认使用最新备份。然而，若最新备份的时间晚于目标时间，PostgreSQL 会认为 --target= 指定的时间无效而忽略它，最终恢复到可用的最新时间点。

要使用 --set 选项，请先运行 info 命令查看备份列表，找到停止时间戳早于目标时间的备份集，然后在执行恢复时指定 --set=BACKUP_LABEL，其中 BACKUP_LABEL 为所选备份集的标签。

详情请参阅用户指南中的 时间点恢复 章节。

WAL 归档文件的后缀是什么含义？

该后缀是用于验证文件完整性的 SHA1 校验和，不可省略。

不同备份类型（全量、差异、增量）的恢复时间是否有差异？

各种备份类型所需的恢复时间相同。恢复操作依据清单文件（manifest）检索文件，对于增量备份或差异备份，该清单可能引用之前备份中的文件。尽管 创建 备份所需时间因类型而异，但恢复时间主要取决于数据库大小（在磁盘 I/O、网络 I/O 等条件相同的情况下）。

如何将备份导出到网络隔离的环境中使用？

pgBackRest 不仅使用仓库存储备份和 WAL 归档，还依赖仓库维护压缩、加密、文件捆绑等功能所需的关键元数据。因此，除非满足非常严格且特定的条件，否则单纯复制备份文件和部分 WAL 文件通常行不通。

如果目的是创建一个可转移的自包含数据库副本（例如通过 USB 传输），可以采用如下变通方法：使用启用了 --archive-copy 选项的 backup 命令，确保所需的 WAL 段随备份一同存储；然后使用 --type=none 配合 --pg1-path=/your/target/path 执行恢复。这将生成一个已恢复的 PostgreSQL 数据目录，所有必要的 WAL 文件已就位于 pg_wal 中，效果类似于 pg_basebackup 的输出结果。

之后可将该目录复制到另一台系统，PostgreSQL 无需访问 pgBackRest 仓库即可从中启动。

请注意，从此备份恢复不会产生时间线切换，这意味着新集群不应向导出源所在的原始仓库推送 WAL。若新集群处于网络隔离环境中，这一点通常不成问题。

8 - 项目指标

pgBackRest 项目代码覆盖率指标与质量统计。

原始页面： https://pgbackrest.org/metric.html

代码覆盖率

pgBackRest 致力于对 /src 目录下的核心 C 代码实现完整的函数、分支和行覆盖。

函数覆盖率和行覆盖率均已达到 100%，无任何例外。

分支覆盖率排除了宏内部的分支和 assert() 调用。宏有专属的单元测试，因此无需在每处调用时都进行测试。assert 断言不要求完整的分支覆盖，因为它们测试的是应当始终为真的条件。

目录函数分支行
build/common32/32 (100.00%)72/72 (100.00%)268/268 (100.00%)
build/config39/39 (100.00%)564/564 (100.00%)1142/1142 (100.00%)
build/error6/6 (100.00%)22/22 (100.00%)71/71 (100.00%)
build/help13/13 (100.00%)138/138 (100.00%)265/265 (100.00%)
build/postgres8/8 (100.00%)58/58 (100.00%)149/149 (100.00%)
command17/17 (100.00%)104/104 (100.00%)210/210 (100.00%)
command/annotate1/1 (100.00%)12/12 (100.00%)30/30 (100.00%)
command/archive14/14 (100.00%)98/98 (100.00%)189/189 (100.00%)
command/archive/get10/10 (100.00%)208/208 (100.00%)447/447 (100.00%)
command/archive/push12/12 (100.00%)142/142 (100.00%)359/359 (100.00%)
command/backup50/50 (100.00%)786/786 (100.00%)1640/1640 (100.00%)
command/check13/13 (100.00%)106/106 (100.00%)214/214 (100.00%)
command/control4/4 (100.00%)34/34 (100.00%)48/48 (100.00%)
command/expire11/11 (100.00%)274/274 (100.00%)392/392 (100.00%)
command/help8/8 (100.00%)178/178 (100.00%)283/283 (100.00%)
command/info16/16 (100.00%)430/430 (100.00%)748/748 (100.00%)
command/local1/1 (100.00%)—4/4 (100.00%)
command/remote1/1 (100.00%)6/6 (100.00%)18/18 (100.00%)
command/repo9/9 (100.00%)110/110 (100.00%)195/195 (100.00%)
command/restore37/37 (100.00%)726/726 (100.00%)1350/1350 (100.00%)
command/server6/6 (100.00%)24/24 (100.00%)81/81 (100.00%)
command/stanza5/5 (100.00%)106/106 (100.00%)125/125 (100.00%)
command/verify22/22 (100.00%)366/366 (100.00%)733/733 (100.00%)
common146/146 (100.00%)624/624 (100.00%)1350/1350 (100.00%)
common/compress12/12 (100.00%)24/24 (100.00%)80/80 (100.00%)
common/compress/bz213/13 (100.00%)20/20 (100.00%)123/123 (100.00%)
common/compress/gz13/13 (100.00%)26/26 (100.00%)118/118 (100.00%)
common/compress/lz415/15 (100.00%)24/24 (100.00%)116/116 (100.00%)
common/compress/zst13/13 (100.00%)12/12 (100.00%)96/96 (100.00%)
common/crypto32/32 (100.00%)88/88 (100.00%)424/424 (100.00%)
common/error33/33 (100.00%)66/66 (100.00%)179/179 (100.00%)
common/io61/61 (100.00%)182/182 (100.00%)523/523 (100.00%)
common/io/filter31/31 (100.00%)92/92 (100.00%)276/276 (100.00%)
common/io/http58/58 (100.00%)292/292 (100.00%)685/685 (100.00%)
common/io/socket28/28 (100.00%)110/110 (100.00%)339/339 (100.00%)
common/io/tls37/37 (100.00%)122/122 (100.00%)409/409 (100.00%)
common/type335/335 (100.00%)922/922 (100.00%)3123/3123 (100.00%)
config93/93 (100.00%)1025/1026 (99.90%)1649/1649 (100.00%)
db23/23 (100.00%)94/94 (100.00%)301/301 (100.00%)
info48/48 (100.00%)240/240 (100.00%)712/712 (100.00%)
info/manifest10/10 (100.00%)132/132 (100.00%)303/303 (100.00%)
postgres36/36 (100.00%)140/140 (100.00%)336/336 (100.00%)
postgres/interface4/4 (100.00%)10/10 (100.00%)35/35 (100.00%)
protocol60/60 (100.00%)266/266 (100.00%)860/860 (100.00%)
storage68/68 (100.00%)298/298 (100.00%)754/754 (100.00%)
storage/azure26/26 (100.00%)164/164 (100.00%)487/487 (100.00%)
storage/cifs2/2 (100.00%)—6/6 (100.00%)
storage/gcs34/34 (100.00%)176/176 (100.00%)574/574 (100.00%)
storage/posix29/29 (100.00%)165/166 (99.40%)328/328 (100.00%)
storage/remote40/40 (100.00%)128/128 (100.00%)568/568 (100.00%)
storage/s331/31 (100.00%)194/194 (100.00%)651/651 (100.00%)
storage/sftp39/39 (100.00%)408/408 (100.00%)762/762 (100.00%)
合计1705/1705 (100.00%)10608/10610 (99.98%)25128/25128 (100.00%)

/test/src/module 中的 C 单元测试模块同样实现了完整的函数覆盖率和行覆盖率，但不包含在上述报告中。