Beta 切换变重复上传？Immich 专辑重新同步导致的“文件爆炸”修复指南。

在 Immich 的迭代路径中，从早期的实验性版本到如今趋于稳定的架构，其底层的**资产去重逻辑（Deduplication Logic）**经历过数次微调。最让用户崩溃的场景莫过于：你更新了 Docker 镜像，重新挂载了路径，结果系统开始疯狂扫描并把几十 GB 甚至 TB 级的照片重新上传了一遍，导致相册里出现了无数成对的“双胞胎”。

作为底层架构师，我必须指出：Immich 判断“重复”的核心依赖于文件的 SHA-1 或 MD5 校验和。如果你在 Beta 切换过程中改变了挂载方式（比如从直接挂载改为通过子路径挂载），或者某些移动端备份策略导致元数据被微改，系统就会判定其为“独立资产”，从而引发文件爆炸。

💡 报错现象总结：更新版本或迁移数据后，相册中出现大量内容完全一致但 ID 不同的照片。后台日志显示 [Nest] 7 - DEBUG [Microservices:StorageService] 发现新资产，执行写入...。即便开启了“拒绝重复上传”开关，系统依然因为校验和或路径映射的细微差异绕过了拦截。

---

根源拆解：为什么“去重开关”拦截失败？

Immich 的去重机制主要分为两个维度：

1. 客户端去重：App 会记录已上传文件的本地 ID，但如果你重装了 App 或清除了缓存，这个记录就没了。
2. 服务端去重：依靠数据库中的 assets 表存储的 checksum 字段。

“文件爆炸”的导火索通常是：你在切换版本时，由于环境变量或挂载点的变动，导致文件在进入服务端之前被添加了某种“干扰项”（例如：某些同步工具在备份时修改了文件的修改时间戳，导致某些特定版本下的校验和计算偏移）。

-- 架构师实战：查询数据库中的重复指纹
-- 如果这个查询返回了大量记录，说明你的库已经“爆炸”了
SELECT checksum, COUNT(*) 
FROM assets 
GROUP BY checksum 
HAVING COUNT(*) > 1;

针对不同阶段的“重复爆炸”修复策略：

爆炸程度	修复手段	风险等级	架构师建议
轻度 (少量重复)	Web 端手动多选删除	极低	耗时但最稳妥，适合几十张照片
中度 (专辑级重复)	调用 API 批量匹配校验和删除	中	需具备基础脚本能力，能精准删除后上传的冗余项
重度 (全库翻倍)	数据库级 SQL 清理 + 磁盘物理扫描	极高	必须先备份 DB，通过 SQL 找出重复 ID 并联动物理文件删除

---

填坑实战：如何优雅地“回滚”重复资产？

如果你已经面对成千上万的重复照片，千万不要手动点。硬核架构师的操作流程如下：

1. 锁定冲突时间段：利用 Immich 侧边的时间轴，确定“爆炸”发生的具体时间点。Immich 的 assets 表记录了 createdAt。
2. 执行“影子匹配”脚本：编写脚本通过 API 获取所有资产列表，对比 checksum。对于指纹一致的资产，保留 createdAt 最早的那条，将其余的 id 记录下来。
3. 调用 Bulk Delete API：将记录下来的冗余 ID 发送到 /api/assets 执行 DELETE。注意，一定要开启 force: true 确保物理文件同步删除。

---

预防逻辑：Beta 切换的“三不”原则

为了避免下一次更新再出这种惨案，请务必记住：

• 不要在扫描未完成时切换路径：确保上一个版本的 Job 队列全部清空（显示为 0）再停止容器。
• 不要改变外部存储的读写权限：权限变动有时会导致系统无法读取原有指纹，从而误判为新文件。
• 不要开启多个同步源：如果你同时开启了手机 App 备份和外置路径扫描（External Library），且它们指向同一批文件，Immich 可能会因为路径识别逻辑不同而存入两份。

---

降维打击：获取 GitCode 《Immich 重复图片自动化清理工具》

与其在数据库里提心吊胆地写 DELETE 语句，不如使用经过社区验证的自动化工具。

我已经针对 Immich 的“文件爆炸”问题，在 GitCode 维护了一个**《Immich 重复资产清理大师（Python 版）》**。这个工具能够自动连接你的 Immich 数据库，基于指纹识别出所有重复项，并提供“预览模式”，让你在真正执行物理删除前确认无误。

直接前往 GitCode 访问这个工具。别让 Beta 版的 Bug 毁了你的存储空间，用最精确的指纹算法，还你一个清爽的数字相册。

[获取 GitCode 《Immich 重复资产清理大师：指纹识别与一键去重脚本》]