VaultS3生产运维手册：磁盘故障与服务器宕机恢复的完整Runbook

VaultS3 是一款轻量级、S3 兼容的对象存储服务器，单二进制、低内存占用、自带 Web 仪表盘。生产环境里最头疼的两件事无非：磁盘坏了和服务器宕机。本文基于官方docs/SCALING.md 的恢复手册，整理成一份可直接照做的完整 Runbook，帮你把故障恢复时间从"查半天文档"压缩到几分钟。

先搞懂 VaultS3 的两层冗余架构

故障恢复的前提，是搞清楚 VaultS3 在两个独立层面保护数据：

记住三条关键事实（摘自 docs/SCALING.md）：

• 纠删码不跨服务器，分片只存在于单节点本地磁盘；
• 集群副本是整对象拷贝，保护不了单块磁盘，磁盘冗余仍靠纠删码；
• 元数据在每个节点是 BoltDB 文件，集群中靠 **Raft 多数派（quorum）**保证持久，节点数务必取奇数（3/5/7）。

💡 推荐生产拓扑：每台服务器 4 块盘开纠删码（任意挂 2 块盘不丢数据）+ 3 节点集群replica_count: 3，可同时容忍 2 块盘 + 1 台整机宕机。

恢复前的监控与日常体检

恢复动作是否及时，取决于你能多快发现故障。建议监控以下端点与日志：

# 集群状态：leader、成员列表、suffrage curl -s http://<leader>:9000/cluster/status | jq # 节点存活 curl -s http://<node>:9000/health # Prometheus 指标：关注复制延迟、heal 活动、各节点请求分布 curl -s http://<node>:9000/metrics

日志中值得设告警的关键行：

Web 仪表盘（http://<host>:9000/dashboard/）也能直观查看运行状态、对象数量与磁盘占用，详见docs/DASHBOARD.md。恢复完成后记得回来确认 Errors 计数为 0。

Runbook 一：磁盘故障恢复（纠删码场景）

故障现象：data_dirs中某个挂载点失效。只要失效磁盘数 ≤parity_shards，受影响对象处于degraded状态但仍然可读。

恢复步骤：

1. 确认容忍度：挂掉的磁盘不能超过parity_shards数量（如4+2配置容忍 2 块）。超出的部分 EC 救不了，只能靠集群副本或备份恢复；
2. 换盘并挂载到原路径：把新盘格式化（推荐 XFS）并挂载到 configs/vaults3.yaml 中data_dirs列出的同一路径（如/mnt/disk3），确认属主与权限和 VaultS3 用户一致；
3. 触发重建：后台 Healer 会按heal_interval_secs（示例配置为 300 秒）自动扫描并从校验分片重建缺失分片。想立即修复，手动触发一次 heal：

curl -X POST 'http://<host>:9000/api/v1/heal' # 扫描全部桶 curl -X POST 'http://<host>:9000/api/v1/heal?bucket=my-bucket&prefix=logs/'

4. 验证：重读一批受影响对象，确认日志中不再出现 degraded 读取告警，且新盘上分片文件在持续回填。

如果你的磁盘前面还有硬件/软件 RAID，按 RAID 控制器的重建流程走即可，VaultS3 只看到一个卷，无需任何额外操作。

Runbook 二：服务器宕机恢复（集群场景）

故障现象：某节点不可达，cluster/status显示为down。只要 Raft 多数派存活，集群会通过 failover proxy 和存活副本继续服务。

场景 A：节点只是短暂宕机（能自己回来）

1. 用原来的node_id和原配置（bootstrap: false）重启该节点的 VaultS3 进程，它会自动重新加入集群并通过 Raft 追赶进度；
2. 它丢失的对象副本由**副本修复（replica repair）**在下一次扫描（cluster.repair.interval_secs，默认 600 秒）恢复，带宽受repair.max_bandwidth_mbps限制。想立即修复：

vaults3-cli cluster repair # 立即执行一轮修复 vaults3-cli cluster repair --status # 查看结果：repaired / undecidable / unrecoverable

3. 用curl http://<leader>:9000/cluster/status确认节点回到Voter健康状态。

--status三个结果的含义：repaired是补回的副本数；undecidable表示有节点不可达、本轮没下结论（节点宕机期间属正常，集群恢复后应降为 0）；unrecoverable表示没有任何节点还持有该数据，对应的 key 会直接命名在服务器日志里——这是唯一需要你人工介入的信号。

场景 B：节点永久损坏，需要换机

1. 把死节点移出集群，让它不再占 quorum 名额：

curl -X POST http://<leader>:9000/cluster/leave -d '{"node_id":"node-3"}' # 或 vaults3-cli cluster leave node-3

2. 准备替换机：安装相同版本，使用新的node_id（如node-3b），bootstrap: false，peers 指向现存成员，并带上集群共享 secret；
3. 加入集群：

curl -X POST http://<leader>:9000/cluster/join \ -d '{"node_id":"node-3b","addr":"<new-host>:9001"}' # 或 vaults3-cli cluster join node-3b <new-host>:9001

4. rebalance + repair 双管齐下（两者分工不同，缺一不可）：

vaults3-cli cluster rebalance # 把对象挪到新的归属节点 vaults3-cli cluster repair # 补齐因节点死亡而缺的副本 vaults3-cli cluster repair --status # 反复执行直到 repaired 收敛

rebalance 回答"这个对象应该归谁"，repair 回答"这个对象还差几份副本"——节点死亡只有 repair 能补救。

⚠️ 在 4.4.75 之前的版本没有 repair 这个动作：永久丢失的节点会让所有曾有副本的物体永远少一份。如果你是在旧版本上换过节点，升级后务必补跑一轮vaults3-cli cluster repair。

场景 C：quorum 丢失（多数节点同时宕机）

• 写入被拒绝、无法选出 leader，直到多数派恢复。优先恢复/重启足够的原始节点——它们的 Raft 日志和快照足以重建状态；
• 如果多数派永久丢失，集群无法自愈，只能从备份（见下文）或跨站点复制对端恢复。这就是"奇数节点数 + 集群外备份"两个原则存在的原因。

恢复后的验证与清理

故障恢复不等于数据完整，建议按序执行：

# 1. 找出"能列出但读不到"的对象（元数据/数据不同步） vaults3-cli object verify my-bucket vaults3-cli object verify my-bucket --repair # 清理孤儿元数据 # 2. 清理磁盘上无元数据指向的孤儿文件（先 dry run，再 --apply） vaults3-cli storage reclaim vaults3-cli storage reclaim --apply # 3. 核对容量放大比（vaultBytes / objectBytes 应接近 replica_count × 纠删开销） vaults3-cli info

在仪表盘上复查各桶对象数与容量是否和故障前一致（可在桶详情页直接核对数量、大小与生命周期规则）：

最后的安全网：备份与跨站点复制

无论冗余做得多厚，备份是最后一道防线：

# 定时全量/增量备份（目标仅支持本地文件系统） backup: enabled: true targets: - { name: "nightly", type: "local", path: "/backups/vaults3" } schedule_cron: "0 2 * * *" retention_days: 30 incremental: false

• 恢复是手动的：停服（或新建实例），把备份的对象树拷回data_dir，重启让元数据重建索引；
• 元数据与对象必须同一时刻、成对备份——没有元数据的对象是"无索引的文件"，没有对象的元数据是"指向空气的索引"（见 docs/INSTALL.md 存储布局章节）；
• 异地灾备可配置replication块（push 单向异步或 active-active 双向，带向量时钟冲突解决），目标必须是另一个 VaultS3 实例。

在仪表盘 Settings 页面可以只读确认这些能力（备份调度、复制、加密等）当前是否开启：

快速参考：一张表看懂所有恢复动作

收尾清单✅

1. vaults3-cli cluster status所有节点均为 Voter 且 leader 正常；
2. cluster repair --status中 undecidable 与 unrecoverable 均为 0；
3. object verify抽样检查无不同步对象；
4. 监控中503 SlowDown与 degraded 读取告警消失；
5. 本次故障原因与恢复时长记入运维手册，更新告警规则。

完整原理、容量规划与一致性模型细节，请阅读docs/SCALING.md与docs/CLI.md。