Immich 自托管照片备份系统在HassOS中的权限问题分析与解决

问题背景

Immich是一款优秀的自托管照片和视频备份解决方案，可以方便地从移动设备直接备份媒体文件。在Home Assistant OS环境中通过AlexBelgium的Hassio插件安装Immich时，许多用户遇到了一个典型的权限问题：系统无法在指定存储位置创建或访问.immich隐藏文件，导致服务无法正常启动。

问题现象

当用户尝试在HassOS中配置Immich插件并指向外部存储（如CIFS/SMB共享或本地挂载的SSD）时，系统日志会显示类似以下错误：

[Nest] 1230 - 11/04/2024, 11:47:07 AM ERROR [Api:StorageService] Failed to write /share/immich/encoded-video/.immich: Error: EACCES: permission denied, open '/share/immich/encoded-video/.immich'

根本原因分析

经过多位用户的测试和验证，这个问题主要由以下几个因素导致：

1. 文件系统权限问题：Immich服务默认以UID/GID 1000运行，而挂载的外部存储可能没有正确配置这些权限。

2. 隐藏文件处理差异：某些文件系统（特别是CIFS/SMB）对隐藏文件（以点开头的文件）有特殊处理方式，可能导致权限检查失败。

3. Home Assistant的挂载机制：HAOS对某些网络文件系统的挂载方式可能限制了容器内应用对隐藏文件的访问权限。

解决方案汇总

方法一：修改运行用户权限（推荐）

1. 进入Immich插件的配置页面
2. 将PUID和PGID参数从默认的1000改为0（root用户）
3. 保存配置并重启插件

这种方法最简单有效，且在HassOS环境下安全风险可控。

方法二：手动创建目录结构

如果希望保持非root用户运行，可以尝试以下步骤：

1. 在目标存储位置手动创建以下目录结构：

   /upload
   /thumbs  
   /profile
   /machine-learning
   /library
   /encoded-video
   

2. 在每个目录中创建.immich隐藏文件：

   touch /path/to/storage/upload/.immich
   touch /path/to/storage/thumbs/.immich
   # 其他目录同理
   

3. 递归设置所有权：

   chown -R 1000:1000 /path/to/storage
   

方法三：调整文件系统挂载选项

对于Synology NAS用户，可以尝试：

1. 在Synology控制面板中禁用SMB VFS兼容模式
2. 或者降级到SMB 2.0协议
3. 确保挂载时包含dotfile参数（如果通过命令行挂载）

存储空间显示问题

部分用户反馈，即使成功配置外部存储后，Immich界面显示的仍然是HAOS系统磁盘的容量。这是因为：

1. 数据库文件默认仍存储在系统磁盘上
2. 需要确保在配置中正确设置了所有相关路径指向外部存储

技术建议

1. 生产环境部署：对于正式使用场景，建议考虑使用独立的PostgreSQL数据库而非内置数据库，以提高性能和可靠性。

2. 备份策略：定期备份Immich数据库和存储目录，特别是当使用外部存储时。

3. 性能考量：网络存储（如CIFS/SMB）可能影响照片处理速度，对于大型媒体库建议使用本地SSD存储。

4. 安全实践：虽然root用户可以解决问题，但在企业环境中应考虑更精细的权限控制方案。

通过以上方法，大多数用户应该能够成功在HassOS环境中部署Immich照片备份系统，并充分利用其强大的媒体管理功能。