[原创]  SeaweedFS 副本数据不一致修复方案

一、场景描述

假设场景：同一个 Volume ID，有多个副本（多台 volume server 上同一个卷），但副本之间数据内容出现不一致（文件条目数、大小不同，甚至读出内容不同）。

适用版本：3.7以上 （ 低版本部分命令参数可能没有 ）

二、seaweedfs 副本的一致性保障原理

• SeaweedFS 的复制是在 Volume 级别做的，同一个 Volume ID 的多个副本应该逻辑上表示同一套数据。
• 但在以下情况中，数据有可能短时间或永久不一致：
  1. 某个 volume server 在写入过程中宕机或网络中断；
  2. 磁盘损坏、坏块，导致 .dat/.idx 文件出错；
  3. 出现 bug 或异常，例如 volume.tier.move、ec.encode 早期版本在只基于某个副本做操作前，没有先跨副本检查一致性，可能放大已有不一致问题[2]。
• SeaweedFS 提供了一系列“自愈”命令，官方推荐用于发现和修复：volume.check.disk、volume.fix.replication、weed fix 等[1][3][4][5]。

三、总体修复思路

1. 确认哪些 Volume 存在不一致（统计信息不同、读文件异常等）。
2. 优先使用 volume.check.disk 自动修复副本间条目差异。
3. 如 volume.check.disk 无法修复或其中一个副本已经物理损坏：
   1. 用 volume.fix.replication 补齐/重建副本；
   2. 必要时手动删除损坏副本文件，再由健康副本复制过去。
4. 如果索引文件 (.idx) 损坏或卷变只读，用 weed fix 重建索引。
5. 复查：卷的各副本统计信息应恢复一致，再做 volume.balance 等后续维护

四、具体操作步骤

1、在 weed shell 中检查卷拓扑和统

应当重点对比每个副本的：

• file_count（文件条数）
• size（逻辑大小、删除大小等）
• 副本数量是否符合你的 replication 配置，比如复制策略是 001 就应该有 2 份数据，010 一般是 2 份（跨 rack）等。

如果某个 Volume ID 的不同副本 file_count、size 或 delete size/count 差异很大，基本可判定存在不一致[2]。

2、用 volume.check.disk 自动修复副本间差异

volume.check.disk 的官方说明：“check all replicated volumes to find and fix inconsistencies. It is optional and resource intensive. How it works:

• 对每个有 2 个以上副本的卷，取 file count 最大的两个副本 A、B
• 把 A 中有但 B 中没有的条目 append 到 B
• 把 B 中有但 A 中没有的条目 append 到 A
• 对只读副本可选地与某个可写副本对比，修剪不一致条目并补齐缺失条目”[1]

2.1、先做“模拟运行”，只检查不修改

观察输出是否类似：

如果显示 missed N 或 partially deleted M，说明确有不一致。

2.2、确认无误后，执行真正修复

关键参数说明（结合源码和帮助信息）[1]：

• -apply / -force：默认只“模拟”，加上才会实际修改磁盘文件。
• -slow：即使 file count 一样，也会做更全面检查，适合怀疑 silent corruption 的场景。
• -syncDeleted：会同步删除标记，否则可能只补写未删除文件条目。
• -nonRepairThreshold：缺失条目比例上限，超过则不修，防止非常严重的损坏被“无脑同步”放大。
• -volumeId ：指定具体要同步数据的卷ID，不写或者写0将修复集群所有卷

修复完成后，再执行一次不带 -apply 的 volume.check.disk 检查，确认 missed 0、partially deleted 0。

五、副本损坏或丢失修复方案

以上只能修复副本volume id正常存在，但是副本 size/file_count 不一致问题，如果遇到集群副本损坏，尤其是副本丢失问题，需要使用volume.fix.replication 命令，按照以下步骤修复：

volume.fix.replication 作用：“add or remove replicas to volumes that are missing replicas or over-replicated”[3]

• 找出 欠副本 的卷，自动从健康副本复制一份内容到有空槽的 dataNode 上；
• 找出 多余副本 的卷，可以在 -doDelete 情况下删除最旧的副本。

六、References