Immich-go工具中干跑与湿跑结果差异的技术解析

现象描述

在使用immich-go工具进行媒体文件上传时，用户发现干跑(dry-run)和实际执行(wet-run)两种模式产生了不同的结果报告。具体表现为：干跑模式报告有3184个文件需要上传，而实际执行时却显示所有文件都已存在于服务器上。

技术背景

immich-go是一个用于Immich自托管照片管理系统的命令行工具，它提供了强大的文件上传和管理功能。该工具在上传过程中实现了多层次的重复文件检测机制：

1. 客户端检测：immich-go首先获取服务器上已有的文件列表
2. 逻辑重复检测：基于文件名和拍摄日期进行初步判断
3. 文件大小比较：对于同名同日期文件，会选择上传较大的版本
4. 服务端校验：Immich服务器会计算上传文件的SHA-1哈希值进行最终确认

问题根源分析

出现干跑与实际执行结果差异的原因在于：

1. 干跑模式局限性：干跑仅执行客户端检测，无法进行服务端的SHA-1哈希校验
2. 文件重复本质：用户目录中存在内容相同但文件名不同的文件副本
3. 检测机制差异：干跑只能识别显式重复(同名同日期)，而实际执行会识别隐式重复(内容相同)

解决方案与最佳实践

针对这类问题，建议采取以下方法：

1. 启用详细日志：使用-log-level=INFO参数获取更详细的处理信息
2. 文件内容检查：确认是否存在内容相同但文件名不同的文件
3. 分批次上传：对于大型媒体库，可分目录分批上传以便排查
4. 哈希预校验：可预先计算本地文件的SHA-1值进行比对

技术启示

这一案例揭示了文件同步工具中几个关键技术点：

1. 多阶段重复检测的重要性
2. 客户端与服务端协同的工作机制
3. 干跑模式的预期与实际限制
4. 内容寻址在媒体管理中的应用

理解这些原理有助于用户更好地使用immich-go工具，并在遇到类似问题时能够快速定位原因。