Immich-Go上传工具在处理Google相册导出文件时的常见问题分析

背景介绍

Immich-Go是一款用于将Google相册导出文件迁移到Immich自托管相册服务的工具。在实际使用过程中，用户报告了多种导致上传过程中断的问题。本文将对这些问题进行技术分析，并探讨解决方案。

主要问题分析

1. 资产堆叠(Stacking)导致的权限问题

当用户尝试上传Google相册导出文件时，Immich-Go会尝试将相似的图片(如连拍照片)自动堆叠在一起。然而，在以下场景中会出现问题：

• 用户A和用户B建立了Google相册的"伴侣共享"关系
• 用户B启用了"将照片存储到我的库中"选项
• 当用户A尝试上传照片时，系统发现部分照片已存在于用户B的库中
• Immich-Go尝试将这些照片堆叠时，由于权限不足(用户A无法修改用户B的资产)导致400错误

技术细节： 服务器端会抛出"Not found or no asset.update access"错误，这是因为Immich的权限系统阻止了跨用户资产的修改操作。

2. 文件扩展名大小写问题

用户报告了".JPG"(大写扩展名)文件上传失败的问题。虽然Immich-Go理论上支持大小写不敏感的扩展名识别，但在某些情况下仍会出现"Unsupported file type .JPG"的错误。

根本原因：

• 服务器端的文件类型检测可能对扩展名大小写敏感
• 数据库唯一性约束冲突(UQ_assets_owner_checksum)
• 文件元数据中的标题包含转义字符(如"123123\.JPG")导致解析异常

3. 上传过程中的EOF错误

用户报告了上传过程中频繁出现连接中断的问题，错误信息为"EOF"。这表明客户端与服务器之间的连接意外终止。

可能原因包括：

• 网络不稳定
• 服务器处理大文件时超时
• 客户端或服务器资源不足

解决方案与最佳实践

对于堆叠权限问题

1. 临时解决方案： 使用以下参数完全禁用堆叠功能：

   --manage-burst= --manage-heic-jpeg= --manage-raw-jpeg=
   

2. 长期改进建议：

   • 实现堆叠前的权限检查
   • 提供"keepIndividual"选项跳过堆叠
   • 改进错误处理机制，避免进程中断

对于文件扩展名问题

1. 临时解决方案：

   • 手动修改元数据文件中的title字段，使其与实际文件名匹配
   • 批量重命名文件扩展名为小写

2. 长期改进建议：

   • 在Immich-Go中添加扩展名规范化处理
   • 改进元数据解析逻辑，正确处理转义字符

对于上传中断问题

1. 临时解决方案：

   • 检查网络连接稳定性
   • 增加服务器资源
   • 分批上传文件

2. 长期改进建议：

   • 实现自动重试机制
   • 增加断点续传功能
   • 优化超时设置

技术实现建议

对于开发者而言，可以考虑以下改进方向：

1. 错误恢复机制：

   • 实现错误分类处理
   • 对可恢复错误自动重试
   • 记录失败文件以便后续处理

2. 元数据处理增强：

   • 添加对特殊字符的转义处理
   • 实现更健壮的JSON解析
   • 增加元数据验证逻辑

3. 性能优化：

   • 实现并行上传
   • 优化内存使用
   • 添加进度保存功能

总结

Immich-Go作为Google相册到Immich的迁移工具，在实际使用中会遇到各种边界情况。通过分析这些问题，我们不仅找到了临时解决方案，也为工具的持续改进指明了方向。对于普通用户，建议在上传前做好文件检查和预处理；对于开发者，则需要关注错误处理和边界情况的兼容性。

随着这些问题的逐步解决，Immich-Go将成为一个更加稳定可靠的迁移工具，帮助用户更好地管理他们的数字记忆。