Immich 外部图库使用指南-未完纪

说明：目前，一个外部图库只能属于一个用户。创建图库时选择所属用户。

外部图库跟踪存储在 Immich 之外的文件系统中的资源。扫描外部图库时，Immich 从磁盘载入视频和照片，并创建对应资源。它们会显示在主时间轴中，外观和行为与其他资源相同，例如可以在地图上查看、加入相册等。以后若在 Immich 外部修改文件，需要重新扫描图库，变化才会显示出来。

如果外部资源从磁盘删除，Immich 会在重新扫描时将它移入回收站。要恢复资源，必须恢复原始文件。30 天后，它会从回收站移除，在 Immich 内所做的任何元数据修改也会丢失。

注意：以任何方式为外部资源添加元数据，例如加入相册或编辑描述，这些元数据都只保存在 Immich 中，不会写入外部资源文件。如果把资源移到图库内的其他位置，重新扫描时这些元数据都会丢失，因为移动后的资源会被视为新资源。这是已知问题，计划在未来版本修复。

注意：由于缓存策略较强，刷新后的资源可能需要一些时间才能在 Web 界面正确显示。需要清除浏览器缓存才能看到变化，这也是计划在未来版本修复的已知问题。在 Chrome 中，先按 F12 打开开发者控制台，再按 F5 重新加载，最后右键点击重新加载按钮，选择“清空缓存并硬性重新加载”。

导入路径

外部图库通过导入路径确定扫描哪些文件。每个图库可以有多个导入路径，将不同位置的文件加入同一图库。扫描会递归进行；如果文件同时位于多个导入路径中，只会添加一次。每个导入路径都必须是文件系统中存在且可读取的目录。路径不可访问时，导入路径对话框会提示。

如果修改导入路径后，某个外部文件不再属于任何导入路径，它会像已删除文件一样从图库移除。之后若将它移回导入路径，会作为新文件重新添加。

故障排查

有时外部图库无法正确扫描，原因可能是 Immich 无法访问文件。请检查：

Docker Compose 文件中的卷挂载是否正确。
所有工作容器是否也挂载了这些卷。
导入路径是否正确，是否与 Docker Compose 中设置的容器路径一致。
导入图库中不要使用符号链接，也不要通过链接跨越 Docker 挂载点。
权限是否正确。
使用正斜杠 /，而不是反斜杠。

要确认 Immich 能访问外部图库，可运行 docker exec -it immich_server bash，在容器内打开 Bash。如果导入路径是 /mnt/photos，运行 ls /mnt/photos 查看。使用独立微服务容器时，也必须添加相同挂载点，并在微服务容器中确认可访问。

排除模式

默认情况下，导入路径内的所有文件都会加入图库。若不希望导入某些文件，可以配置排除模式。排除模式采用 glob 语法，匹配完整文件路径；匹配的文件不会加入图库。可在各图库的“Scan Settings”页面添加。

一些基本例子：

**/*.tif：排除所有扩展名为 .tif 的文件。
**/hidden.jpg：排除所有名为 hidden.jpg 的文件。
**/Raw/**：排除任意名为 Raw 的目录内的全部文件。
**/*.{tif,jpg}：排除扩展名为 .tif 或 .jpg 的文件。

* 匹配零个或多个字符，范围限于文件名或单个目录名。** 递归匹配零个或多个子目录；放在模式末尾时，也会涵盖子目录内的所有文件。例如，**/exclude_me/** 会排除任意 exclude_me 目录内的文件，以及其所有子目录中的文件。

@ 等特殊字符需要转义。例如，**/\@eaDir/** 排除所有名为 @eaDir 的目录中的文件。

说明：Immich 内部使用 glob 包处理排除模式，有时会将模式转换为 Postgres LIKE 模式。这一功能旨在支持基本目录排除，不建议使用复杂模式，因为复杂模式无法可靠转换为 Postgres 语法。基本语法可参考 glob 文档。

自动监听：实验性功能

这项功能仍处于实验阶段，仅面向高级用户。启用后，会自动监听文件系统，无需重新扫描就能将新资源导入 Immich。

如果照片位于网络驱动器上，自动监听很可能无法工作。这时需要依靠定期图库刷新同步变化。

故障排查

出现 ENOSPC 错误时，需要提高文件监听器数量上限。对应 sysctl 键为 fs.inotify.max_user_watches，默认值是 8192。将它提高到大于所监听文件数量的适当值。注意，Immich 必须监听导入路径中的全部文件，包括已被忽略的文件。

ERROR [LibraryService] Library watcher for library c69faf55-f96d-4aa0-b83b-2d80cbc27d98 encountered error: Error: ENOSPC: System limit for number of file watchers reached, watch '/media/photo.jpg'

少数情况下，图库监听器可能挂起，导致 Immich 无法启动。此时应在配置文件中禁用图库监听器。如果是在 Immich 内部启用的监听器，需要先不启动微服务：在 Docker Compose 中禁用微服务，启动 Immich，在管理员设置中关闭图库监听器，再关闭 Immich、重新启用微服务，之后即可正常启动。

每日夜间作业

系统每天自动执行一次扫描，运行时间可以配置，详见下文“设置自定义扫描间隔”。

该作业还会清理删除过程中卡住的图库。也可以在图库管理页面点击“Scan all libraries”触发清理。

删除图库

删除外部图库时，图库中的全部资源记录会随图库立即删除。虽然后台完全删除可能耗时较长，但它会马上从图库列表消失。如果删除被中断，例如服务器重启，下一次夜间定时任务会继续清理。也可以点击图库列表中的“Scan All Libraries”手动触发清理。

使用示例

下面将一个已有相册目录导入 Immich。假设有三个待添加目录：

/home/user/old-pics：童年照片。
/mnt/nas/christmas-trip：圣诞旅行照片。其子目录 /mnt/nas/christmas-trip/Raw 保存直接来自单反相机的原始文件，不希望导入。
/mnt/media/videos：同一次圣诞旅行的视频。

首先规划图库组织方式。旅行照片应单独建库，因为需要排除 Raw 文件。视频与旧照片可以放在同一个图库，因为希望导入全部文件。如果其他目录没有匹配 Raw 排除模式的文件，也可以将三个目录放进同一个图库。

挂载 Docker 卷

immich-server 容器需要访问这些目录，修改 Docker Compose 文件如下。文件：docker-compose.yml。

  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
+     - /mnt/nas/christmas-trip:/mnt/media/christmas-trip:ro
+     - /home/user/old-pics:/mnt/media/old-pics:ro
+     - /mnt/media/videos:/mnt/media/videos:ro
+     - /mnt/media/videos2:/mnt/media/videos2 # WARNING: Immich will be able to delete the files in this folder, as it does not end with :ro
+     - "C:/Users/user_name/Desktop/my media:/mnt/media/my-media:ro" # import path in Windows system.

提示：挂载末尾的 ro 表示只读访问。这会禁止通过 Web 界面删除图片，也不允许通过 XMP 旁车文件向图库添加元数据。

说明：记得运行 docker compose up -d 使更改生效，并确认容器内能看到挂载路径。