AM Music Deduper

轻量级家庭 NAS 音乐库去重服务，面向 AllMusic/{username}/ 场景。

处理模型

AllMusic
  ↓
文件稳定检测（size + mtime）
  ↓
L1：size + head/tail 64 KiB
  ↓
完整 SHA-256
  ├─ 相同 → Exact Duplicate → hard link
  └─ 不同 → duration ±3s → Chromaprint
                       ├─ 高相似且版本一致 → hard link
                       ├─ 中等相似/版本冲突 → review
                       └─ 低相似 → 保留

安全规则

• SHA-256 是 Exact Duplicate 的最终依据；L1 只负责缩小候选范围。
• 不根据文件名、歌手、歌名、专辑或来源单独判重。
• 确认相同版本后，优先使用 hard link 保留每个用户原来的逻辑路径。
• 用户删除自己的路径不会影响其他 hard link；最后一个 link 删除后数据才释放。
• hard link 要求源文件和目标文件位于同一文件系统。
• 正在写入的文件必须先通过稳定性检查。
• L2 对版本标记冲突的文件进入 review，不自动合并。
• SQLite 是加速索引，文件系统是最终事实；数据库丢失后可以重新扫描。
• .dedupe 不参与音乐扫描，避免把内部文件再次处理。

CLI

# 建立/更新索引，不修改音乐文件
am-deduper scan /music/AllMusic --db /data/dedupe.db

# Exact + L2；首次执行建议 dry-run
am-deduper dedupe /music/AllMusic --db /data/dedupe.db --dry-run

# 确认后执行
am-deduper dedupe /music/AllMusic --db /data/dedupe.db

# 长驻监听：默认只自动执行安全的 Exact hard-link
am-deduper watch /music/AllMusic --db /data/dedupe.db

# 开启 L2 acoustic 匹配；建议先 dry-run 验证
am-deduper watch /music/AllMusic --db /data/dedupe.db --l2

Feiniu NAS 部署

生产环境采用 Gitea Container Registry → NAS 拉取镜像 → NAS 本地运行。 镜像由 wjyhk 构建并推送到 gitea.king.nyc.mn，Feiniu NAS 不需要本地 build。

建议目录：

NAS
├── Gitea Registry
│   └── gitea.king.nyc.mn/openclaw/am-deduper:latest
├── AllMusic/
│   ├── admin/
│   ├── alice/
│   └── bob/
└── AppData/
    └── am-deduper/
        └── dedupe.db

NAS .env

ALLMUSIC_PATH=<NAS绝对路径>/AllMusic
DEDUPE_DATA_PATH=<NAS绝对路径>/AppData/am-deduper

首次部署

先登录 Gitea Container Registry：

docker login gitea.king.nyc.mn

拉取生产镜像并准备数据目录：

docker pull gitea.king.nyc.mn/openclaw/am-deduper:latest
mkdir -p <NAS绝对路径>/AppData/am-deduper

然后使用 Compose 启动容器；首次执行建议先运行 scan 和 dry-run：

docker compose run --rm am-deduper scan /music/AllMusic --db /data/dedupe.db
docker compose run --rm am-deduper dedupe /music/AllMusic --db /data/dedupe.db --dry-run

确认 dry-run 输出后，再执行正式 Exact/L2：

docker compose run --rm am-deduper dedupe /music/AllMusic --db /data/dedupe.db

然后启动长期监听：

docker compose up -d

更新版本：

docker pull gitea.king.nyc.mn/openclaw/am-deduper:latest
docker compose up -d

当前生产镜像：

gitea.king.nyc.mn/openclaw/am-deduper:latest

wjyhk 已验证推送成功；当前镜像 digest：

sha256:96e0b87e454bc9fa96aa5171b117a029bbcef34d20099577db6442544ce5c9ee