pbm-agent 必须部署在所有shard节点（含primary/secondary）和config server节点，不可装在arbiter、hidden或non-voting节点；漏配config server会导致备份卡在“waiting for agents”或报错no pbm-agent found。
pbm-agent 必须装在所有分片节点和 config server，但不能装在 arbiter
分片集群里，pbm-agent 不是“装一台就行”，它必须部署在每个实际承载数据的 mongod 实例上：所有 shard 节点（包括每个 shard 的 primary/secondary）、所有 config server 节点（config replica set 成员）。arbiter、hidden、non-voting 节点不参与数据存储，也不运行 pbm-agent —— 装了也无效，还会干扰锁协调。
常见错误是漏掉 config server 节点。一旦 config server 上没跑 pbm-agent，pbm CLI 就无法写入或读取 admin.pbmConfig 和 admin.pbmBackups 这些关键集合，执行 pbm backup 会卡在 “waiting for agents” 或直接报 no pbm-agent found for config server。
- 检查方式：
pbm status --mongodb-uri="mongodb://user:pass@config01:27019/admin?replicaSet=csRepl"应显示所有 config 成员在线 - 每个节点启动后，用
systemctl status pbm-agent确认服务运行，且日志里有connected to MongoDB和listening on control collection - 确保所有节点使用完全相同的
pbm-agent版本，混用 2.14 和 2.15 会导致pbm list返回空或部分备份不可见
备份前必须配置统一的远程存储，且所有 pbm-agent 要能凭同一凭证访问
pbm 本身不存备份文件，它只协调各 pbm-agent 把快照推到 S3/NFS/GCS 等远程位置。这意味着：所有节点上的 pbm-agent 进程，必须能用完全一致的密钥/凭证/挂载路径访问同一个存储端点。哪怕一个 shard 节点挂载的 NFS 路径少了个 trailing slash，或 S3 region 配错，那个节点的备份就会失败并拖垮整个分片备份流程。
典型配置命令是：pbm config --file ./s3-conf.yaml，其中 s3-conf.yaml 至少包含 storage.type: s3、storage.s3.bucket、storage.s3.region、storage.s3.credentials.key 等字段。注意：storage.s3.path 是可选前缀（如 backups/prod/），不是本地路径。
- NFS 场景下，所有节点必须用相同 UID/GID 挂载，且
pbm-agent进程用户（如pbm）对该目录有读写权限 - S3 场景下，避免用 IAM role（容器/K8s 外环境难统一），优先用 static credentials，并确认 endpoint URL 格式正确（例如
https://s3.us-east-1.amazonaws.com不能写成http） - 配置后务必运行
pbm-speed-test --type upload --size 100M在至少两个不同分片节点上测试，验证带宽和权限无差异
备份命令要指向 config server 的 URI，不是某个 shard
执行 pbm backup 时，传入的 --mongodb-uri 必须是 config server replica set 的连接串，例如 mongodb://pbm:secret@cfg01:27019,cfg02:27019,cfg03:27019/admin?replicaSet=cfgRepl&authSource=admin。如果误用 shard 的 URI（比如 shard01/...），pbm CLI 会连到错误的 admin 数据库，找不到 admin.pbmConfig，直接报 collection not found 或静默失败。
这个 URI 决定了操作上下文：它告诉 pbm 去哪个 admin 数据库读写控制集合，而不是指定备份哪部分数据。实际备份范围由集群拓扑自动识别 —— 只要所有 shard 和 config 的 pbm-agent 都在线且可通信，pbm 就会触发全集群一致性快照。
- URI 中必须显式指定
authSource=admin，否则认证可能失败（尤其启用了security.authorization: enabled时） - 不要加
readPreference=secondary，pbm内部需要直连 primary 写 control 集合 - 首次备份建议加
--force参数跳过预检（如 oplog size 检查），避免因 config server oplog 较小而中止
逻辑备份下，PITR 恢复依赖 config server 的 oplog 归档，不是 shard 自身的
Point-in-Time Recovery（PITR）在分片集群中不是靠每个 shard 单独归档 oplog，而是由 pbm-agent 统一从 config server 的 oplog 中拉取并切块存为 admin.pbmPITRChunks。这意味着：config server 的 oplog 必须足够大（建议 ≥ 24 小时容量），且其副本集必须启用 oplogSizeMB 显式配置 —— 如果 config server 是默认 5% 磁盘空间，很容易被轮转掉早期 chunk，导致 PITR 只能恢复最近几小时。
恢复时，pbm restore --pitr 会先还原最近全量备份，再重放 config server oplog 中对应时间段的变更。这个过程对 shard 数据库是透明的，但要求所有 shard 在恢复期间保持可写状态（即不能停机），否则 replay 会卡在某个 shard 的未确认写入上。
- 检查当前 PITR 状态：
pbm describe-backup <name></name>查看pitr字段是否为true，以及last-pitr时间戳 - 若需延长 PITR 窗口，调整 config server oplog 并重启 mongod：
mongosh --eval "rs.reconfig({oplogSizeMB: 4096}, {force: true})" - 注意：Community 版本仅支持逻辑备份 + PITR；物理备份（
--type physical）仅限 Percona Server for MongoDB，且分片集群暂不支持
分片集群备份最易被忽略的一点：config server 的稳定性权重远高于单个 shard。它的 oplog 容量、网络可达性、pbm-agent 健康度，直接决定整个集群能否备份成功、能否 PITR 恢复。别只盯着 shard 节点的 CPU 和磁盘，先守住 config server 这条线。
