Proxmox Backup Server 4.2 配置参数详解

Proxmox Backup Server 4.2 配置详解：配置文件体系、用户/API token/ACL 权限模型（含 token 权限交集实测）、datastore 与保留策略 prune/GC、remote/sync 远程同步、证书管理，以及 proxmox-backup-client 真实备份与恢复全流程实测

Proxmox Backup Server2026/10/19

Proxmox Backup Server 4.2 配置参数详解

目标：逐类讲清 Proxmox Backup Server（PBS）4.2 的配置体系——配置文件布局、用户与 API token 及 ACL 权限模型、datastore 与保留策略（prune/garbage-collection）、远程同步（remote/sync job）、证书，并用 proxmox-backup-client 完成一次真实的备份与恢复闭环。全部命令与回显已在 Debian 13 (trixie) + proxmox-backup-server 4.2.8-1 实测通过（安装过程见《Debian 13 安装 Proxmox Backup Server 4.2 指南》）。

一、环境信息

  • 操作系统：Debian GNU/Linux 13 (trixie)，x86_64（cat /etc/debian_version → 13.7）
  • 服务端：proxmox-backup-server 4.2.8-1（proxmox-backup-manager version → proxmox-backup-server 4.2.8-1 running version: 4.2.8）
  • 客户端：proxmox-backup-client 4.2.8（同机安装）
  • Web/API 端口：TCP 8007（HTTPS）
  • datastore：pbs-demo（路径 /datastore）；同步演示用第二个 datastore pbs-sync（路径 /srv/pbs-sync）
  • 演示账号：root@pam / admin@pbs，密码均为 q1w2e3r4；API token admin@pbs!backup-token
  • 证书指纹（sha256）：70:83:f5:bb:06:78:77:8f:72:66:13:d8:79:ef:4f:cf:c4:bf:0e:c9:d5:28:a4:d2:da:8f:64:a9:73:10:c2:79

二、前置条件

  1. 已按《Debian 13 安装 Proxmox Backup Server 4.2 指南》完成安装：两个服务 proxmox-backup/proxmox-backup-proxy 为 active，8007 监听，datastore 已创建。

  2. 已设置 PBS 密码（包安装方式必须，ISO 安装在向导中已设置）：

    proxmox-backup-manager user update root@pam --password q1w2e3r4

  3. 客户端认证三要素（本文大量命令会用到，先统一定义）：

    export PBS_REPOSITORY=root@pam@localhost:pbs-demo
export PBS_PASSWORD=q1w2e3r4
export PBS_FINGERPRINT=70:83:f5:bb:06:78:77:8f:72:66:13:d8:79:ef:4f:cf:c4:bf:0e:c9:d5:28:a4:d2:da:8f:64:a9:73:10:c2:79

    ⚠️ 注意：PBS_REPOSITORY 的 authid 部分必须是 用户@域 完整形式（root@pam）。只写 root@localhost 会在备份时报 parameter verification failed: 'repository': value does not match the regex pattern（实测报错，详见 8.2）。

三、参数查看与修改方式

PBS 的配置有三套等价入口，修改任一入口最终都落在服务端配置文件上：

入口适用场景典型命令/位置
Web 管理台日常图形化管理https://<主机>:8007
CLI：proxmox-backup-manager服务端自动化/脚本datastore/user/acl/remote/sync-job/notification/... 子命令
配置文件审计/备份/批量编辑/etc/proxmox-backup/*.cfg（TOML 风格分段）

配置文件清单（实测 ls /etc/proxmox-backup/）：

acl.cfg  acme  authkey.key  authkey.pub  csrf.key  datastore.cfg  domains.cfg
proxy.key  proxy.pem  remote.cfg  shadow.json  sync.cfg  token.shadow  user.cfg

关键配置文件与本篇章节对应关系：

配置文件内容对应章节
user.cfg / domains.cfg / token.shadow / shadow.json用户、认证域、token 密钥四
acl.cfg访问控制（authid → 路径 → 角色）四
datastore.cfgdatastore 定义与保留策略五
remote.cfg / sync.cfg远端与同步任务六
proxy.pem / proxy.key / acme证书七

⚠️ 注意：不要手工并发编辑配置文件——manager 命令与 Web 会基于 SHA256 digest 防冲突（多数子命令带 --digest 参数说明），手改文件易丢注释与格式。生产建议统一走 Web/CLI。

四、用户、API token 与 ACL 权限

4.1 用户管理

PBS 内置认证域 pbs（PBS 自管密码）与 pam（映射 Linux 系统账号），另支持 OpenID/LDAP/AD 域（manager 子命令 openid/ldap/ad）。创建一个业务用户：

proxmox-backup-manager user create admin@pbs --password q1w2e3r4
proxmox-backup-manager user list

实测回显：

+===========+========+========+===========+==========+=======+===========+
| userid    | enable | expire | firstname | lastname | email | comment   |
+===========+========+========+===========+==========+=======+===========+
| admin@pbs |      1 |  never |           |          |       |           |
+-----------+--------+--------+-----------+----------+-------+-----------+
| root@pam  |      1 |  never |           |          |       | Superuser |
+===========+========+========+===========+==========+=======+===========+

常用维护命令（均实测可用）：

proxmox-backup-manager user update admin@pbs --email admin@example.com   # 修改属性
proxmox-backup-manager user remove admin@pbs                             # 删除用户

⚠️ 注意：用户的 email 不只是联系方式——PBS 内置通知目标 mail-to-root 会读取 root@pam 的 email 投递告警邮件（实测：未配置 email 时通知链路报 'root@pam' does not have a configured email address，详见运维手册篇）。

4.2 API token

为脚本/CI 创建 API token（避免在脚本里放用户密码）：

proxmox-backup-manager user generate-token admin@pbs backup-token
proxmox-backup-manager user list-tokens admin@pbs

实测回显（token secret 仅在生成时显示一次，务必当场保存）：

Result: {
  "tokenid": "admin@pbs!backup-token",
  "value": "691b59a0-75cc-4706-b7f5-c4dc06eca215"
}
+========================+========+========+=========+
| tokenid                | enable | expire | comment |
+========================+========+========+=========+
| admin@pbs!backup-token |      1 |  never |         |
+========================+========+========+=========+

token 的客户端用法（authid 为 用户@域!token名）：

export PBS_REPOSITORY='admin@pbs!backup-token@localhost:pbs-demo'
export PBS_PASSWORD='691b59a0-75cc-4706-b7f5-c4dc06eca215'
export PBS_FINGERPRINT=70:83:f5:bb:06:78:77:8f:72:66:13:d8:79:ef:4f:cf:c4:bf:0e:c9:d5:28:a4:d2:da:8f:64:a9:73:10:c2:79
proxmox-backup-client backup demo.pxar:/opt/demo-data

4.3 ACL：角色、路径与 token 权限交集（重点实测）

授权语法：

proxmox-backup-manager acl update <路径> <角色> --auth-id <用户或token>
proxmox-backup-manager acl list

实测（先给 token 授权）：

+========================+=====================+===========+================+
| ugid                   | path                | propagate | roleid         |
+========================+=====================+===========+================+
| admin@pbs!backup-token | /datastore/pbs-demo |         1 | DatastoreAdmin |
+------------------------+---------------------+-----------+----------------+

ACL 路径体系与常用角色：/（根）、/datastore、/datastore/<名>、/remote/<名> 等；角色含 Admin、DatastoreAdmin、DatastoreReader、DatastoreAudit、RemoteSyncOperator 等。注意角色名不带点号，写成 Datastore.Backup 会报 parameter verification failed - 'role': value 'Datastore.Backup' is not defined in the enumeration.（实测报错——那是 PVE 的命名习惯，不是 PBS 的）。

⚠️ 重点排障实录：token 备份报 missing permissions 'Datastore.Backup'。 即使给 token 授了 Admin 角色，token 执行备份仍失败：

Error: missing permissions 'Datastore.Backup' on '/datastore/pbs-demo'

根因（实测验证）：token 的有效权限 = token 自身 ACL 与其属主用户 ACL 的交集。属主 admin@pbs 用户本身没有任何 ACL，交集为空。给属主用户也授 ACL 后：

proxmox-backup-manager acl update /datastore/pbs-demo DatastoreAdmin --auth-id admin@pbs
proxmox-backup-manager user permissions admin@pbs

实测回显（token 属主与 token 双双获得权限）：

Path: /datastore/pbs-demo
- Datastore.Audit (*)
- Datastore.Backup (*)
- Datastore.Modify (*)

备份组 owner 校验：权限修好后再次用 token 备份，又遇到组归属校验（该备份组此前由 root@pam 创建）：

Error: backup owner check failed (admin@pbs!backup-token != root@pam)

用 change-owner 转移组归属（需管理员凭据执行）：

PBS_PASSWORD=q1w2e3r4 PBS_REPOSITORY=root@pam@localhost:pbs-demo \
  proxmox-backup-client change-owner host/pbs-demo admin@pbs!backup-token

实测回显 OWNER-CHANGED 后，token 备份成功：

demo.pxar: backup was done incrementally, reused 128 MiB (100.0%)
Uploaded backup catalog (95 B)
Duration: 0.27s
End Time: Mon Oct 19 09:36:20 2026

最终落盘的 ACL 配置（/etc/proxmox-backup/acl.cfg 实测内容）：

acl:1:/datastore/pbs-demo:admin@pbs!backup-token:DatastoreAdmin
acl:1:/datastore/pbs-demo:admin@pbs:DatastoreAdmin

五、datastore 与保留策略（prune / garbage-collection）

5.1 datastore 定义与生命周期

/etc/proxmox-backup/datastore.cfg 实测内容（两个 datastore）：

datastore: pbs-demo
        path /datastore

datastore: pbs-sync
        path /srv/pbs-sync

管理命令（全部实测）：

proxmox-backup-manager datastore create <名> <独立路径>   # 创建（初始化 .chunks 块库）
proxmox-backup-manager datastore list                     # 列表
proxmox-backup-manager datastore show pbs-demo            # 详情
proxmox-backup-manager datastore update pbs-demo --comment "主备份仓"  # 更新属性
proxmox-backup-manager datastore remove <名>              # 移除（含 --destroy-data 选项控制是否删数据）

5.2 保留策略（keep-* 参数）

保留策略由 keep-hourly/daily/weekly/monthly/yearly 组成，可挂在 datastore、prune job 或客户端 prune 命令上。语义：每个档位内按时间粒度保留最近 N 个快照，其余标记移除。客户端侧实测（组 host/pbs-demo 当时有两个快照）：

export PBS_REPOSITORY=root@pam@localhost:pbs-demo PBS_PASSWORD=q1w2e3r4
export PBS_FINGERPRINT=70:83:f5:bb:06:78:77:8f:72:66:13:d8:79:ef:4f:cf:c4:bf:0e:c9:d5:28:a4:d2:da:8f:64:a9:73:10:c2:79
proxmox-backup-client prune host/pbs-demo --keep-daily 1 --keep-weekly 1

实测回显（prune 计划 + 执行）：

+====================================+==========================+========+
| snapshot                           |                     date | action |
+====================================+==========================+========+
| host/pbs-demo/2026-10-19T09:23:46Z | Mon Oct 19 09:23:46 2026 | remove |
+------------------------------------+--------------------------+--------+
| host/pbs-demo/2026-10-19T09:23:59Z | Mon Oct 19 09:23:59 2026 |   keep |
+------------------------------------+--------------------------+--------+

💡 技术拓展：快照保留策略的常见档位设计不止 keep-daily 一种，常用组合对比如下。

策略组合保留效果适用场景
keep-daily 7 + keep-weekly 4近 7 天每天一份 + 近 4 周每周一份常规服务器日备
keep-hourly 24 + keep-daily 7近 24 小时每小时 + 近一周每天高频变更（数据库/日志）
keep-monthly 12 + keep-yearly 512 个月 + 5 年合规/审计留档
keep-last N只留最近 N 份临时环境/开发机

本文示例采用 keep-daily 1 + keep-weekly 1（演示用最小集），生产建议按「日备 7 + 周 4 + 月 6」起步。

定时 prune 可用 prune job（服务端侧统一调度，不依赖客户端）：proxmox-backup-manager prune-job create <id> --schedule "daily" --store pbs-demo --keep-daily 7 ...。

5.3 garbage-collection（物理回收）

prune 只是「解除快照引用」，被移除快照独有的数据块要等 GC 才物理删除。实测手动 GC：

proxmox-backup-manager garbage-collection start pbs-demo
proxmox-backup-manager garbage-collection status pbs-demo

实测回显（status 全表）：

+==================+============================================================================================+
| Name             | Value                                                                                      |
+==================+============================================================================================+
| store            | pbs-demo                                                                                   |
| disk-bytes       | 134218959                                                                                  |
| disk-chunks      | 40                                                                                         |
| index-data-bytes | 134218332                                                                                  |
| index-file-count | 2                                                                                          |
| pending-bytes    | 3781841                                                                                    |
| pending-chunks   | 3                                                                                          |
| removed-bad      | 0                                                                                          |
| removed-bytes    | 0                                                                                          |
| removed-chunks   | 0                                                                                          |
| still-bad        | 0                                                                                          |
| duration         | 2                                                                                          |
| last-run-endtime | 1792401899                                                                                 |
| last-run-state   | OK                                                                                         |
| upid             | UPID:pbs-demo:0000170C:0108EB02:00000005:6AD5E1E9:garbage_collection:pbs\x2ddemo:root@pam: |
+==================+============================================================================================+

关键指标解读：disk-bytes/disk-chunks 为 datastore 实际占用的块数据；pending-* 是刚解除引用、尚未达到安全删除期（PBS 为防止并发引用设有了宽限期）的块；removed-* 为本次 GC 实际删除量；still-bad 为校验失败仍保留的坏块数（应长期为 0，非 0 立即 verify 排查）。

5.4 verify（完整性校验）

proxmox-backup-manager verify pbs-demo

实测回显（尾部）：

  verified 0.00/0.00 MiB in 0.00 seconds, speed 0.41/0.37 MiB/s (0 errors)
percentage done: 100.00% (1/1 snapshots)
TASK OK

六、远程同步（remote / sync job）

PBS 支持 pull（本端拉远端）与 push（本端推远端）两种同步方向，4.2 新增同步服务端加解密与 worker-threads 并发组同步（官方 4.2 公告）。单机演示时可把「远端」指向本机（实测即此做法）。

6.1 定义 remote

proxmox-backup-manager remote create pbs-local \
  --auth-id root@pam --host 127.0.0.1 \
  --password q1w2e3r4 \
  --fingerprint 70:83:f5:bb:06:78:77:8f:72:66:13:d8:79:ef:4f:cf:c4:bf:0e:c9:d5:28:a4:d2:da:8f:64:a9:73:10:c2:79
proxmox-backup-manager remote list

实测回显：

+===========+===========+==========+=================================================================================================+=========+
| name      | host      | auth-id  | fingerprint                                                                                     | comment |
+===========+===========+==========+=================================================================================================+=========+
| pbs-local | 127.0.0.1 | root@pam | 70:83:f5:bb:06:78:77:8f:72:66:13:d8:79:ef:4f:cf:c4:bf:0e:c9:d5:28:a4:d2:da:8f:64:a9:73:10:c2:79 |         |
+===========+===========+==========+=================================================================================================+=========+

⚠️ 注意：--fingerprint 必填（自签证书场景凭指纹建立信任）。指纹来源见第七节 cert info。remote 密码落盘为 base64（remote.cfg 实测 password cTF3MmUzcjQ=，即 q1w2e3r4 的 base64）。

6.2 创建并执行 sync job

先准备目标 datastore（pbs-sync，路径 /srv/pbs-sync），再建同步任务：

proxmox-backup-manager sync-job create sync-demo \
  --remote pbs-local --remote-store pbs-demo --store pbs-sync \
  --schedule daily --remove-vanished true
proxmox-backup-manager sync-job run sync-demo

实测执行回显（完整链路）：

Starting datastore sync job 'pbs-local:pbs-demo:pbs-sync::sync-demo'
sync datastore 'pbs-sync' from 'pbs-local/pbs-demo'
----
Syncing datastore 'pbs-demo', root namespace into datastore 'pbs-sync', root namespace
Found 1 groups to sync (out of 1 total)
[host/pbs-demo]: 2026-10-19T09:23:59Z: start sync
[host/pbs-demo]: 2026-10-19T09:23:59Z/demo.pxar.didx: sync archive
[host/pbs-demo]: 2026-10-19T09:23:59Z/demo.pxar.didx: downloaded 128.001 MiB (747.831 MiB/s)
[host/pbs-demo]: 2026-10-19T09:23:59Z: sync done
[host/pbs-demo]: percentage done: 100.00% (1/1 snapshots)
Summary: sync job pulled 128.001 MiB in 39 chunks (average rate: 745.409 MiB/s)
Summary: removed vanished: snapshots: 0, groups: 0, namespaces: 0
sync job 'pbs-local:pbs-demo:pbs-sync::sync-demo' end
TASK OK

同步落盘的 sync.cfg 实测内容：

sync: sync-demo
        remote pbs-local
        remote-store pbs-demo
        remove-vanished true
        schedule daily
        store pbs-sync

--remove-vanished true 表示远端已删除的快照在本端同步目标里也删除（保持与源端一致）；--schedule 用 calendar-event 语法（daily/ hourly/Mon 02:30 等）。

七、证书管理

PBS 自签发初始证书（/etc/proxmox-backup/proxy.pem + proxy.key），客户端以「指纹信任」方式使用：

proxmox-backup-manager cert info

实测回显（关键字段）：

Fingerprint (sha256): 70:83:f5:bb:06:78:77:8f:72:66:13:d8:79:ef:4f:cf:c4:bf:0e:c9:d5:28:a4:d2:da:8f:64:a9:73:10:c2:79

生产环境替换为受信证书有两种路径：用 acme 子命令族自动签发（proxmox-backup-manager acme account register → acme cert order，支持 DNS/HTTP 验证插件），或直接替换 proxy.pem/proxy.key 后重启 proxmox-backup-proxy。

八、真实备份与恢复全流程（client 实测）

8.1 首次备份

准备演示数据并执行备份：

dd if=/dev/urandom of=/opt/demo-data/random.bin bs=1M count=64
echo "PBS backup demo 2026-10-19" > /opt/demo-data/readme.txt
export PBS_PASSWORD=q1w2e3r4 PBS_REPOSITORY=root@pam@localhost:pbs-demo
export PBS_FINGERPRINT=70:83:f5:bb:06:78:77:8f:72:66:13:d8:79:ef:4f:cf:c4:bf:0e:c9:d5:28:a4:d2:da:8f:64:a9:73:10:c2:79
proxmox-backup-client backup demo.pxar:/opt/demo-data

实测回显（完整）：

Starting backup: host/pbs-demo/2026-10-19T09:23:46Z
Client name: pbs-demo
Starting backup protocol: Mon Oct 19 09:23:46 2026
No previous manifest available.
Upload directory '/opt/demo-data' to 'root@pam@localhost:8007:pbs-demo' as demo.pxar.didx
demo.pxar: had to backup 64 MiB of 64 MiB (compressed 64.001 MiB) in 0.11 s (average 560.448 MiB/s)
Uploaded backup catalog (76 B)
Duration: 0.25s
End Time: Mon Oct 19 09:23:46 2026

8.2 增量备份与去重验证

追加 64 MiB 新文件后再次备份：

dd if=/dev/urandom of=/opt/demo-data/app2.bin bs=1M count=64
proxmox-backup-client backup demo.pxar:/opt/demo-data

实测回显：

Downloading previous manifest (Mon Oct 19 09:23:46 2026)
demo.pxar: had to backup 67.607 MiB of 128 MiB (compressed 67.607 MiB) in 0.15 s (average 436.448 MiB/s)
demo.pxar: backup was done incrementally, reused 60.394 MiB (47.2%)
Uploaded backup catalog (95 B)
Duration: 0.34s
End Time: Mon Oct 19 09:24:00 2026

reused 60.394 MiB (47.2%) 即服务端去重复用量——原 64 MiB 随机文件与 readme 无变化，其分块全部命中已有块，只上传了新文件的块与变化的索引。

快照列表：

+====================================+=============+====================================+
| snapshot                           |        size | files                              |
+====================================+=============+====================================+
| host/pbs-demo/2026-10-19T09:23:46Z |  64.001 MiB | catalog.pcat1 demo.pxar index.json |
+------------------------------------+-------------+------------------------------------+
| host/pbs-demo/2026-10-19T09:23:59Z | 128.001 MiB | catalog.pcat1 demo.pxar index.json |
+====================================+=============+====================================+

8.3 恢复与一致性校验

⚠️ 注意：restore 是三段式参数 <snapshot> <archive-name> <target>，不要写成备份时的 归档名:路径 冒号形式。实测错误写法的报错：

Error: parameter verification failed - 'target': missing argument
Usage: proxmox-backup-client restore <snapshot> <archive-name> <target> [OPTIONS]

正确执行：

proxmox-backup-client restore host/pbs-demo/2026-10-19T09:23:46Z demo.pxar /opt/restore-test/
md5sum /opt/demo-data/random.bin /opt/restore-test/random.bin

实测回显：

restore complete (64 MiB processed in 0.2s, average 271.211 MiB/s)
e8eb8c602e0e527568b17a3bb493dd45  /opt/demo-data/random.bin
e8eb8c602e0e527568b17a3bb493dd45  /opt/restore-test/random.bin

md5 一致，恢复闭环通过。

8.4 备份常用参数速查（实测 --help 取证）

参数默认值说明
--chunk-size4096（KB）分块大小，64–4096，必须为 2 的幂
--crypt-modeencryptnone / sign-only / encrypt
--change-detection-modelegacylegacy / data / metadata（增量检测策略）
--ns无目标命名空间
--exclude无排除模式，可多次
--rate / --burst无令牌桶限速
--dry-runfalse只演练不上传
--port8007服务端口

九、生产配置模板（16GB 内存 / NVMe+HDD / 中小型机房日备）

按「PVE 集群 3 节点 + 若干物理机」的典型场景，给出一套经实测验证命令形态的配置基线：

# 1. datastore：独立 ZFS/XFS 挂载点，命名与用途对应
proxmox-backup-manager datastore create prod-main /data/prod-main
proxmox-backup-manager datastore update prod-main --comment "PVE集群+物理机主备份仓"

# 2. 业务用户 + token，权限最小化（属主与 token 都要授权，见 4.3 交集规则）
proxmox-backup-manager user create backup@pbs --password q1w2e3r4
proxmox-backup-manager acl update /datastore/prod-main DatastoreAdmin --auth-id backup@pbs
proxmox-backup-manager user generate-token backup@pbs ci-token

# 3. 保留策略：日 7 + 周 4 + 月 6（挂 datastore，全组生效）
proxmox-backup-manager datastore update prod-main \
  --keep-daily 7 --keep-weekly 4 --keep-monthly 6

# 4. 每周六 02:30 全仓 verify + 每日 04:00 GC + 03:00 prune
proxmox-backup-manager verify-job create verify-weekly --store prod-main --schedule "sat 02:30"
proxmox-backup-manager prune-job create prune-daily --store prod-main --schedule "daily 03:00" \
  --keep-daily 7 --keep-weekly 4 --keep-monthly 6
proxmox-backup-manager garbage-collection start prod-main   # GC 也可仅手动跑

# 5. 异地同步（pull 方向，并发加速）
proxmox-backup-manager remote create dr-site --auth-id backup@pbs \
  --host <异地PBS地址> --password q1w2e3r4 --fingerprint <异地指纹>
proxmox-backup-manager sync-job create sync-dr --remote dr-site \
  --remote-store prod-main --store prod-main-mirror \
  --schedule "daily 05:00" --remove-vanished true --worker-threads 4

配套说明：keep-* 挂在 datastore 上时对写入该 datastore 的所有备份组统一生效；--worker-threads 为 4.2 新增并发同步参数（官方 4.2 公告）；verify/prune-job 的 schedule 与系统 cron 无关，由 PBS 内部调度器执行。

十、常见问题（FAQ）

Q1：备份报 'repository': value does not match the regex pattern。

PBS_REPOSITORY 的 authid 缺 realm。必须写 root@pam@host:datastore（或 user@pbs!token@host:datastore），只写 root@host:... 不合法（实测报错复现）。

Q2：备份命令不认识 --fingerprint 参数。

proxmox-backup-client backup 子命令没有 --fingerprint 选项（实测 schema does not allow additional properties 报错）。指纹通过环境变量传递：export PBS_FINGERPRINT=<sha256指纹>。

Q3：token 备份报 missing permissions 'Datastore.Backup' / backup owner check failed。

两步排障（均实测）：① token 权限 = token ACL ∩ 属主 ACL，给属主用户也补 ACL；② 备份组已有 owner（首个写入者），用 proxmox-backup-client change-owner host/<组> <新authid> 转移（见 4.3）。

Q4：prune 后磁盘没变小。

prune 只解除引用；物理释放需等 GC（proxmox-backup-manager garbage-collection start <store>），且 PBS 有块删除宽限期，garbage-collection status 里的 pending-chunks 即待回收块（实测见 5.3）。

Q5：restore 报 'target': missing argument。

restore 是 <snapshot> <archive-name> <target> 三段式参数，不是 归档名:路径 冒号形式（见 8.3 实测）。

Q6：Web 登录认证失败但密码没记错。

区分两套凭据：PBS 用户密码（shadow.json）与 Linux 系统密码。用 proxmox-backup-manager user update <user> --password <新密码> 重设 PBS 侧密码。

Q7：API 用 curl 调用怎么认证？

Web 登录用 ticket 方式（POST /api2/json/access/ticket 换取 ticket + CSRFPreventionToken，GET 请求带 auth_cookie Cookie）；实测中 root@pam 的 HTTP Basic 密码认证在 4.2.8 返回 authentication failed（ticket 方式成功），生产脚本建议统一用 API token 或 ticket 方式。

十一、参考链接

  1. 官方文档：Backup Client（backup/restore/prune 参数）：https://pbs.proxmox.com/docs/backup-client.html
  2. 官方文档：User Management / Access Control：https://pbs.proxmox.com/docs/user-management.html
  3. 官方文档：Datastore 与同步（remote/sync job）：https://pbs.proxmox.com/docs/storage.html
  4. PBS 4.2 发布公告（同步加密、worker-threads、S3 后端等新特性）：https://www.proxmox.com/en/about/company-details/press-releases/proxmox-backup-server-4-2
  5. 系列文档：《Debian 13 安装 Proxmox Backup Server 4.2 指南》（安装与 Ubuntu 差异实测）、《Proxmox Backup Server 日常运维手册》（巡检/告警/排障）