dedup —— 高可靠文件去重与安全隔离工具

dedup 是一个以“绝不误删”为第一原则设计的本地文件去重工具，适用于照片、视频、文档等大规模文件目录的重复扫描与整理。

核心特点：

• 只读扫描 + 离线确认 + 显式执行移动

• 多阶段判重，默认极度保守

• 支持大目录、高并发、可中断

• 生成 TSV + HTML 可视化报告

• 跨磁盘安全移动，避免数据损坏

---

一、整体工作流程

工具严格分为两个阶段：

1. scan 阶段（只读）

• 扫描重复文件

• 生成去重报告

• 不做任何文件修改

2. move 阶段（可选）

• 读取 scan 生成的 TSV 报告

• 将“确认重复”的文件移动到隔离目录

• 支持 dry-run 试运行

这种设计确保：
扫描阶段永远不会造成数据丢失风险。

---

二、安装与编译

1. 环境要求

• Go 1.20 或更高版本

• Windows / Linux / macOS 均可

2. 编译

go build -ldflags="-s -w" -o dedup

Windows 下：

go build -ldflags="-s -w" -o dedup.exe

---

三、scan 命令（扫描重复文件）

1. 基本用法

dedup scan --folder1 <基准目录> --folder2 <扫描目录>

说明：

• folder1：基准目录

  • 这里的文件视为“原件”

  • 永远不会被移动或删除

• folder2：扫描目录

  • 在这里查找与基准目录重复的文件

默认会生成：

• report.tsv

• report.html

---

2. scan 参数详解

参数	是否必填	说明
--folder1	是	基准目录
--folder2	是	扫描目录
--out	否	报告前缀，默认 report
--mtime-tol-ms	否	修改时间容差（毫秒），默认 0
--fast-hash-bytes	否	快速指纹大小，默认 65536
--enable-full-md5	否	是否启用完整 MD5 校验，默认 true

---

3. 判重逻辑说明（非常重要）

dedup 使用多阶段过滤模型，优先保证安全性：

第一阶段：文件大小（Size）

• 大小不同 → 一定不是重复

• 大小相同 → 进入下一阶段

第二阶段：修改时间（MTime）

• 大小 + 时间一致（允许容差） → 高度疑似

• 时间不一致 → 进入内容校验

第三阶段：快速指纹（Fast Hash）

• 读取文件 头部 + 尾部 各 N 字节

• 用于快速排除“大小相同但内容不同”的文件

• 默认 N = 64KB

第四阶段：完整 MD5（Full MD5）

• 只有在必要时才触发

• 用于最终确认内容完全一致

最终只有通过全部必要阶段的文件，才会被标记为重复。

---

4. 常见 scan 使用示例

示例 1：最严格模式（默认）

dedup scan --folder1 "D:\Photos" --folder2 "E:\Backup"

• 要求文件大小一致

• 修改时间完全一致

• 内容一致

适合：
原始拷贝、镜像目录比对。

---

示例 2：手机照片场景（允许时间微差）

dedup scan \ --folder1 "D:\Camera" \ --folder2 "E:\Phone" \ --mtime-tol-ms 1000

说明：

• 允许 1 秒内的时间差

• 解决复制 / 导入导致的时间偏移

---

示例 3：超大目录，强调性能

dedup scan \ --folder1 "/data/main" \ --folder2 "/data/archive" \ --fast-hash-bytes 32768

说明：

• 使用 32KB 快速指纹

• 减少 IO 压力

---

5. scan 输出说明

1）TSV 文件（机器可读）

字段说明：

字段	含义
BasePath	基准文件路径
DupPath	扫描目录中的重复文件
Size	文件大小（字节）
MatchType	判重方式
MD5	完整 MD5（如未算则为 skipped）

TSV 文件用于后续 move 操作。

---

2）HTML 文件（人工确认）

HTML 报告特点：

• 可点击打开文件

• 图片支持预览

• 支持按路径 / 大小排序

• 显示判重方式标签

强烈建议在执行 move 前人工浏览 HTML 报告。

---

四、move 命令（安全隔离重复文件）

1. 基本用法

dedup move \ --log report.tsv \ --folder2 <扫描目录> \ --quarantine <隔离目录>

说明：

• 只处理 TSV 中列出的 DupPath

• 不会影响 folder1

• 会尽量保留原目录结构

---

2. move 参数说明

参数	是否必填	说明
--log	是	scan 生成的 TSV 文件
--folder2	是	扫描目录根路径
--quarantine	是	隔离目录
--dry-run	否	试运行，不实际移动

---

3. 强烈建议的使用流程

第一步：试运行

dedup move \ --log report.tsv \ --folder2 "E:\Phone" \ --quarantine "D:\DupFiles" \ --dry-run

确认：

• 数量是否合理

• 路径是否符合预期

---

第二步：正式移动

dedup move \ --log report.tsv \ --folder2 "E:\Phone" \ --quarantine "D:\DupFiles"

---

4. safeMove 的安全保证

每一个文件移动都遵循：

1. 同盘：原子 rename

2. 跨盘：

• 复制

• 强制落盘（fsync）

• 校验文件大小

• 再删除源文件

任何一步失败，源文件都会保留。

---

五、中断与异常处理

• 支持 Ctrl+C

• 中断时会：

  • 停止新任务

  • Flush 报告文件

• 已写入的结果不会丢失

---

六、设计原则总结

这个工具遵循以下原则：

• 扫描阶段只读

• 删除动作延后

• 所有危险操作显式执行

• 默认策略宁可漏报，不可误删

---

七、适用场景

• 照片 / 视频去重

• 多备份盘比对

• NAS / 外置硬盘整理

• 历史数据清理前的安全扫描

---

八、不适合的场景

• 实时去重

• 数据库 / 程序文件去重

• 自动删除无人确认的文件