Barman 3.20.1 配置参数详解

目标：讲清 Barman 3.20.1 的配置体系——配置文件查找顺序、全局节与服务器节的分层作用域、核心参数的官方语义与实测默认值，以及参数修改的生效方式与常见踩坑。已在 barman01（Barman 3.20.1）+ pg01（PostgreSQL 17.11）双服务器环境实测验证，所有默认值取自 barman show-server 实际输出。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64
• 备份服务器：主机名 barman01（IP 10.0.0.32，示意网段），Barman 3.20.1-1.pgdg22.04+1（PGDG apt 源安装，PGDG 客户端组件为 postgresql-client 18.6，被备份库为 17.11——跨大版本客户端兼容实测通过）
• 数据库服务器：主机名 pg01（IP 10.0.0.31，示意网段），PostgreSQL 17.11-1.pgdg22.04+2
• 两台服务器 /etc/hosts 互配主机名映射，备份走纯 TCP 流复制（无 SSH 依赖）
• Barman 主配置：/etc/barman.conf；服务器配置节：/etc/barman.d/pg01.conf；数据目录：/var/lib/barman/pg01/
• 版本实查：官网 https://www.pgbarman.org/ 显示最新稳定版 3.20.1（2026-09-29，查询日期 2026-10-20）

二、前置条件：配置体系的三层结构

2.1 配置文件查找顺序

Barman 每次运行都会读取配置（barman --help 官方说明，实测输出）：

defaults: ~/.barman.conf, /etc/barman.conf, /etc/barman/barman.conf

查找顺序为：运行用户家目录的 ~/.barman.conf → /etc/barman.conf → /etc/barman/barman.conf，先找到先用。apt 安装的默认路径是 /etc/barman.conf。

2.2 全局节 / 服务器节 / 模型三层作用域

• 全局节 [barman]：/etc/barman.conf 中定义运行用户、目录、日志等，所有服务器继承；
• 服务器节 [<server_name>]：每台被管数据库一个配置节，官方推荐放进 configuration_files_directory 指向的目录（默认 /etc/barman.d/）每台一个 .conf 文件；
• 模型（Model）：3.x 支持同一服务器的多套参数模型（如「日常备份」与「月度全备」），用 config-switch 切换，barman show-server 的 active_model 字段可查（本实验未启用，实测值 None）。

官方文档对参数作用域的通用标注（来源：docs.pgbarman.org 3.20.1 配置参考，查询日期 2026-10-20）：

• Scope: Global / Server / Model：三层均可设置，服务器节覆盖全局节；
• Scope: Server：仅服务器节有效。

2.3 修改生效方式

Barman 是「每次运行读配置」的一次性进程模型——改完配置文件无需重启任何服务即对下一条 barman 命令生效；唯一的常驻进程是 WAL 接收器（receive-wal），streaming_archiver 系列参数改动后需要重启该进程（先 barman terminate-process pg01 receive-wal，再 barman cron 拉起）。

⚠️ 注意：非法的配置键不会导致命令失败，只会被静默忽略并写一条 WARNING 到 barman.log——排障时先看日志（实测：误写 archive_timeout 得到 barman.config WARNING: Invalid configuration option "archive_timeout" in [pg01] section.，参数值维持默认 0）。

三、参数总览

以本环境 barman show-server pg01 的 170 行输出为口径（实测），参数按用途分为十类：

💡 技术拓展：show-server 输出里混有两类字段——可配置参数（如 backup_method）与运行时状态（如 current_lsn、postgres_systemid、pg_basebackup_version）。状态字段不可配置，但排障极有用：streaming_supported/compatible 反映客户端与库端版本兼容性，replication_slot 显示槽的活动状态，wal_level 回读库端实际值。

四、核心参数详解

4.1 全局运行参数（[barman] 节）

barman_user Barman 运行身份。默认 barman（apt 安装自动创建系统用户）。所有备份目录、锁文件的属主都应是该用户。

barman_home / barman_lock_directory 数据根目录与锁目录。默认 barman_home = /var/lib/barman，锁目录默认即 barman_home；每台服务器一个子目录（实测 /var/lib/barman/pg01/），其下再分 base/（全量备份）、wals/（归档 WAL）、streaming/（流归档 WAL）、incoming/（archiver 模式 WAL）、errors/。

configuration_files_directory 服务器配置节目录，默认 /etc/barman.d，加载其中所有 .conf。目录里还有两个模板可参考（实测文件清单）：streaming-server.conf-template（流式服务器模板）、passive-server.conf-template（级联/被动节点模板）、ssh-server.conf-template（rsync over SSH 模板）。

log_file / log_level 日志路径与级别。默认 /var/log/barman/barman.log 与 INFO。排障临时调 DEBUG。

retention_policy / minimum_redundancy（全局） 全局保留策略与最低冗余，服务器节可覆盖。语义见 4.6。

4.2 连接类参数（服务器节）

conninfo 管理连接串：备份起止协调（调用 pg_backup_start/stop）、目录信息采集。默认 dbname=postgres。实测：

conninfo = host=pg01 port=5432 user=barman dbname=postgres password=q1w2e3r4

💡 说明：show-server 回显时密码自动脱敏为 *REDACTED*（实测 conninfo: host=pg01 port=5432 user=barman dbname=postgres password=*REDACTED*），日志同理——配置文件本身明文，生产建议把口令挪到 barman 用户家目录 .pgpass（chmod 600）并在 conninfo 中省略 password。

streaming_conninfo 流复制连接串：pg_basebackup 传输基线、pg_receivewal 接收 WAL 都走它。默认 dbname=postgres。账号需 REPLICATION 权限（实测 barman_streaming 专用账号）。

primary_conninfo / primary_ssh_command 级联场景参数：Barman 直接连物理备用库备份时，用 primary_conninfo/primary_ssh_command 指向主库做系统标识核验。默认 None。实测默认值：primary_conninfo: None。

wal_conninfo / wal_streaming_conninfo 复制槽监控专用连接：wal_conninfo 用于监控接收 WAL 的复制槽状态，未设置时逐级回退到 wal_streaming_conninfo → conninfo（来源：官方配置参考，查询日期 2026-10-20）。默认均 None。

sslmode 连接加密模式，标准 libpq 取值（disable/require/verify-ca/verify-full 等），走 conninfo 字符串或环境变量控制，生产跨机房建议 verify-full。

ssh_command rsync 备份方法与远程恢复使用的 SSH 命令模板（如 ssh postgres@pg01）。backup_method = postgres 时不需要。默认 None。

4.3 备份方法与并行控制（服务器节）

backup_method 备份方式，可选 postgres（pg_basebackup 流式）、rsync（SSH+rsync 文件级）、local-to-cloud（直推对象存储，不落本地盘）。默认 postgres。实测 backup_method: postgres。

backup_options 备份行为选项集合，默认 concurrent_backup（并发备份，PG 9.6+ 走非排他模式）。实测 BackupOptions({'concurrent_backup'})。可选值还包括 exclusive_backup（PG 9.5 及以下的排他模式，老库专用）。

parallel_jobs 备份/恢复的并行子进程数（rsync 方法、云方法及 3.x 流式恢复管线）。默认 1。相关联的还有 parallel_jobs_start_batch_period（默认 1）与 parallel_jobs_start_batch_size（默认 10），控制子进程的启动节奏避免打满 I/O。

bandwidth_limit 备份传输限速，单位字节/秒（kbps 语义按官方文档）。默认 None（不限速）。生产共享带宽链路建议显式限制，配合 tablespace_bandwidth_limit 可按表空间差异化限速（默认 None）。

immediate_checkpoint 备份开始时立即在库端触发 checkpoint（而非等待下一个自动 checkpoint），缩短备份窗口但增加库端 I/O 峰值。默认 False。相关联的 checkpoint_timeout 回读库端自动 checkpoint 间隔（实测 300 秒）。

basebackup_retry_times / basebackup_retry_sleep pg_basebackup 连接失败重试次数（默认 0，不重试）与重试间隔（默认 30 秒）。网络抖动环境建议设 2~3 次。

autogenerate_manifest 备份完成时生成 backup_manifest（兼容 pg_verifybackup 校验）。仅 rsync 方法有效（postgres 方法的 pg_basebackup 本身就产出 manifest）——这是容易误配的参数（官方 Note 明确：该选项在 backup_method 非 rsync 时被忽略，来源：官方配置参考，查询日期 2026-10-20）。默认 False。

4.4 备份压缩参数组（服务器节，backup_method=postgres 专用）

该参数组把压缩下推到 pg_basebackup（PG15+ 才有 lz4/zstd），五个参数联用：

实测一（压缩效果，同一库 gzip 压缩前后对比）：

backup_compression = gzip

Backup size: 4.1 MiB        ← 压缩后（本次备份）
Backup size: 29.5 MiB       ← 压缩前（首次全量备份）

关键差异解读：29.5 MiB → 4.1 MiB（约 7:1），演示库文本占比高、压缩收益大；真实库按数据构成评估，一般 2:1~5:1。

实测二（格式与压缩位置组合约束）：

backup_compression = gzip
backup_compression_format = plain

ERROR: backup_compression_format plain is not compatible with backup_compression_location None

⚠️ 排障：plain 格式必须同时指定 backup_compression_location = server（压缩在库端做，PG15+），未指定时直接报错——配置不生效但有明确提示，比静默忽略友好。

4.5 WAL 归档与复制槽参数（服务器节）

WAL 持续归档是 PITR 的生命线，两条路线可并存：

实测配置（本环境采用纯流归档，show-server 回显验证）：

streaming_archiver = on
slot_name = barman
create_slot = auto

streaming_archiver: True
slot_name: barman
replication_slot: Record(slot_name='barman', active=True, restart_lsn='0/C000000')

💡 说明：replication_slot.active=True 表示槽被 receive-wal 进程占用，WAL 会在库端持续保留直到被接收——槽一旦无人消费，库端磁盘会被 WAL 撑爆，监控必须覆盖 pg_replication_slots 的滞后量（wal_keep_size、max_wal_senders、max_replication_slots 是 show-server 回读的库端参数，实测默认 10/10）。

last_wal_maximum_age 最新归档 WAL 的时间新鲜度门槛：最近一条 WAL 早于该值时 barman check 报错，用于发现「归档断流」。默认 None（不检查）。生产强烈建议设置（如 2 hours），配合 last_backup_maximum_age 构成完整的新鲜度体检。

4.6 保留策略与体检参数（服务器节）

minimum_redundancy 最少可用全量备份数，默认 0。设为 1 后 barman delete 删除最后一份全量时会被拒绝（保护兜底）。实测 minimum_redundancy: 1。

retention_policy 保留策略，两种口径：

• RECOVERY WINDOW OF N DAYS：保留足以恢复到最近 N 天内任意时刻的备份链；
• REDUNDANCY N：保留最近 N 份全量。

默认 ""（无策略，备份永久保留）。实测 RECOVERY WINDOW OF 7 DAYS。配合 retention_policy_mode（默认 auto，cron 自动清理过期备份）。

last_backup_maximum_age 最新全量备份的新鲜度门槛：超过该时长没有新全量，barman check 报 backup maximum age: FAILED。默认 None。与 last_backup_minimum_size（最小体积门槛，防备份空跑）联用构成备份有效性体检。

check_timeout 体检命令的单项超时。默认 30 秒。

4.7 rsync 压缩与自定义过滤器（服务器节）

compression rsync 方法备份的压缩算法（gzip/bzip2/pigz 等），备份文件以压缩存放、恢复时自动解压。默认 None。与 backup_compression 是两套体系——后者是 pg_basebackup 流式内建压缩（4.4），前者只作用于 rsync 方法产物。

compression_level 压缩级别。默认 medium。

custom_compression_filter / custom_decompression_filter / custom_compression_magic 自定义压缩/解压命令（如 zstd、lz4），Barman 用文件魔数识别压缩格式。默认均 None。非主流算法需求的扩展点。

4.8 云备份参数（服务器节）

Barman 的云能力由独立工具族 barman-cloud-* 承载（apt 包 barman-cli-cloud），以下参数控制其行为（默认值均来自实测 show-server）：

AWS S3 系列：aws_region/aws_profile/aws_read_timeout（默认 None）、aws_encryption（如 aws:kms）、aws_sse_kms_key_id、aws_sse_customer_key（3.20 新增，SSE-C 客户自带密钥，值为 file:// 指向 base64 编码的 32 字节密钥文件，与 KMS 加密互斥；同一服务器所有备份与 WAL 必须用同一密钥，混用会导致云端拒绝请求——来源：官方配置参考，查询日期 2026-10-20）、aws_check_object_lock（默认 False，WORM 桶校验）。

云快照系列（snapshot_*）：snapshot_provider（None/aws/gcp/azure）、snapshot_instance、snapshot_disks、snapshot_zone、snapshot_gcp_project；AWS 快照锁参数为 3.20 新增：aws_snapshot_lock_mode/duration/expiration_date/cool_off_period（合规快照锁定，默认均 None）。

Azure/GCS 系列：azure_credential/azure_resource_group/azure_subscription_id、gcp_project/gcp_zone 等（默认均 None）。

4.9 Hook 脚本参数（服务器节）

围绕四类生命周期事件（备份、归档、删除、恢复）各提供 pre/post 两级钩子，共 12 个参数（实测全量清单）：pre_backup_script/post_backup_script/pre_backup_retry_script/post_backup_retry_script，pre_archive_* 同构，另有 pre/post_delete_script、pre/post_wal_delete_script、pre/post_recovery_script。默认均 None。

• _script 事件发生时执行一次；_retry_script 失败后按 retry_times/retry_sleep（全局继承）重试；
• 钩子按字典序同步执行，返回非零码会中断对应 Barman 阶段——报警、触发异地同步、清理临时文件的挂载点。

4.10 目录与杂项（服务器节）

五、生产配置模板

按「中大型单实例、流归档、本地磁盘 + 保留 14 天」给出可直接套用的模板（参数值均为本环境实测验证过的合法键）：

# /etc/barman.conf（全局节，节选）
[barman]
barman_user = barman
configuration_files_directory = /etc/barman.d
barman_home = /var/lib/barman
log_file = /var/log/barman/barman.log
log_level = INFO
compression = gzip                # rsync 方法压缩；postgres 方法不读此值
minimum_redundancy = 1
retention_policy = RECOVERY WINDOW OF 7 DAYS

# /etc/barman.d/pg01.conf（服务器节）
[pg01]
description = "pg01 PostgreSQL 17 primary server"
conninfo = host=pg01 port=5432 user=barman dbname=postgres
streaming_conninfo = host=pg01 port=5432 user=barman_streaming dbname=postgres

# 备份方法
backup_method = postgres
backup_options = concurrent_backup
parallel_jobs = 2
bandwidth_limit = 41943040        # 40 MB/s
backup_compression = gzip         # 流式压缩，实测 29.5 MiB -> 4.1 MiB
backup_compression_location = client

# WAL 流归档
streaming_archiver = on
slot_name = barman
create_slot = auto
last_wal_maximum_age = 2 hours

# 保留与体检
minimum_redundancy = 2
retention_policy = RECOVERY WINDOW OF 14 DAYS
last_backup_maximum_age = 1 day

应用顺序（逐条实测命令）：

barman check pg01          # 全 OK 再继续
barman cron                # 拉起 receive-wal、创建复制槽
barman backup pg01 --wait  # 首次全量，--wait 等 WAL 到位
barman list-backup pg01

六、参数修改生效流程（实测）

Barman 无守护常驻状态（除 receive-wal），生效流程分三种情形：

1. 普通参数（连接/备份方法/保留策略等）：编辑配置文件即对下一条命令生效，无需任何重载。实测：在 pg01.conf 修改 minimum_redundancy 后 barman show-server 立即反映新值；
2. 流归档参数（slot_name/batch_size 等）：receive-wal 是常驻进程，需 barman terminate-process pg01 receive-wal 停止后由 barman cron 按新配置拉起（3.20 起 receive-wal --stop 已弃用，统一走 terminate-process）；
3. 模型参数（多套模型切换）：barman config-switch <server> <model> 切换生效模型，config-update 通过 JSON 批量更新模型配置（两命令均 3.20 在册子命令，barman config-switch --help 可查语法）。

⚠️ 注意：非法键的静默忽略是最常见的「改了没生效」（见 2.3 的 WARNING 实测）；另一个隐蔽点是同名参数写进多个作用域——服务器节覆盖全局节，但 barman.d/*.conf 里若同一服务器节出现两次 [pg01]，后一次出现会叠加覆盖，容易造成配置漂移，建议一机一文件。

七、常见问题（FAQ）

Q1：改了 /etc/barman.d/pg01.conf，show-server 显示还是旧值？ 三种可能：键名非法（看 /var/log/barman/barman.log 的 Invalid configuration option WARNING）；改的是全局节而服务器节同键覆盖；receive-wal 类参数需 terminate-process 后重启（见第六章三种情形）。

Q2：backup_compression = zstd 报不兼容？ zstd/lz4 依赖 PG15+ 的 pg_basebackup；且客户端（barman01）与库端（pg01）两侧都要有对应 CLI 工具。PG17 环境可用 zstd；PG14 及以下只能 gzip。

Q3：conninfo 里写密码不安全怎么办？ 把口令写进 barman 用户家目录 ~/.pgpass（pg01:5432:*:barman:q1w2e3r4，chmod 600），conninfo 中省略 password 字段；libpq 会自动读取。show-server 对 conninfo 回显时密码始终脱敏（*REDACTED*），配置文件本身仍需文件权限保护。

Q4：minimum_redundancy=1 但 delete 还是把唯一备份删了？ 检查两个点：retention_policy_mode 是否被改成 manual（cron 不再自动清理，但手工 delete 不受策略限制）；worm_mode 是否为 False（True 时 delete 被彻底禁止）。minimum_redundancy 的保护在 delete 时会给出确认提示，脚本化删除务必先核对备份清单。

Q5：槽 barman 让库端 WAL 堆积怎么办？ streaming_archiver 断流（barman01 宕机/receive-wal 挂掉）时槽会无限保留 WAL。短期：恢复 receive-wal（barman cron）；长期：给 last_wal_maximum_age 设体检门槛、监控 pg_replication_slots 的 restart_lsn 滞后；确实要放弃槽内 WAL 时先停用服务器节再用 pg_drop_replication_slot 删槽（会破坏 PITR 连续性，需重新做全量）。

Q6：多套保留策略想按月切换？ 用 Model：为同一服务器定义多个参数模型（如 daily/monthly），barman config-switch pg01 monthly 切换；show-server 的 active_model 字段可确认当前模型（未启用时为 None，实测）。

八、参考链接

• 官方配置参考：https://docs.pgbarman.org/release/3.20.1/user_guide/configuration.html （参数定义与 Scope 标注，查询日期 2026-10-20）
• 官方服务器配置章：https://docs.pgbarman.org/release/3.20.1/user_guide/server.html
• 官方发布说明：https://github.com/EnterpriseDB/barman/blob/release/3.20.1/RELNOTES.md （SSE-C、快照锁等新参数）
• 站内延伸阅读：《Barman 3.20.1 介绍与选型指南》（架构与 WAL 归档两种路线对比）、《Ubuntu 22.04 安装 Barman 3.20.1 指南》（安装与首次配置实测）、《Barman 3.20.1 常用 CLI 命令与工具详解》（命令实操与排障）