Immich-go 文件上传中的重复文件处理机制分析

问题背景

在使用immich-go工具进行大规模媒体文件上传时，用户发现了一个异常现象：当重复运行上传命令时，"Server has same quality"指标与预期不符。具体表现为首次上传约6000张图片后，第二次运行时仅有约1000张被识别为"相同质量"，这与预期中应该匹配文件夹内图片数量的情况相矛盾。

技术分析

经过深入调查，发现这一问题源于immich服务与immich-go工具在处理重复文件时的协同工作机制存在差异。

核心问题

1. 服务端行为：Immich服务在接收重复文件时，API会返回成功响应（"duplicate": false），但实际上只有第一个文件会被真正存储。这是由于数据库的唯一约束（UQ_assets_owner_checksum）阻止了重复记录。

2. 客户端行为：immich-go工具在第二次上传时，会检测到第一个文件副本已存在（标记为"exists on server"），但对后续相同内容的文件副本无法识别为重复，会再次尝试上传。

具体表现

• 首次上传：所有文件都被成功"上传"（从API获得成功响应）
• 第二次上传：
  • 第一个文件副本被正确识别为已存在
  • 后续相同内容的文件副本被当作新文件处理
  • 服务端API再次返回成功（实际上未存储）
• 结果导致统计指标异常

解决方案

针对这一问题，建议采取以下措施：

1. 客户端改进：immich-go应增强重复文件检测机制，不仅检查文件名，还应比较文件内容的哈希值。

2. 服务端协作：建议Immich服务在API响应中更准确地反映重复状态，即使返回成功也应明确标识实际存储状态。

3. 用户实践建议：

   • 在上传前先整理文件，去除重复内容
   • 监控上传后的实际存储情况，而非仅依赖工具输出
   • 对于关键数据，建议分批验证上传结果

技术影响

这一问题的存在可能导致以下影响：

1. 数据完整性风险：用户可能误以为所有文件都已成功上传，而实际上部分重复文件未被存储。

2. 性能影响：重复上传尝试会消耗额外的网络和计算资源。

3. 统计失真：工具提供的上传统计信息不能准确反映实际存储状态。

最佳实践

对于使用immich-go进行大规模文件上传的用户，建议：

1. 在上传前使用专用工具检查并去除重复文件
2. 分批次上传并验证
3. 关注服务端实际存储数量而非仅依赖客户端统计
4. 定期检查上传日志中的异常记录

通过理解这一机制，用户可以更有效地使用immich-go工具，并准确评估其文件上传状态。