跳转到主要内容

外部库

外部库跟踪存储在 Immich 之外文件系统中的资产。当扫描外部库时，Immich 会从磁盘加载视频和照片并创建相应的资产。这些资产将显示在主时间线上，就像其他资产一样，包括地图查看、添加到相册等功能。如果文件在 Immich 外部被修改，你需要重新扫描库以显示更改。

如果外部资产从磁盘上删除，Immich 在重新扫描时会将其移动到垃圾桶。要恢复资产，你需要恢复原始文件。30 天后，文件将从垃圾桶中删除，且在 Immich 内的任何元数据更改将丢失。

备注

如果你以任何方式向外部资产添加元数据（例如将其添加到相册或编辑描述），这些元数据只会存储在 Immich 内部，而不会保存在外部资产文件中。如果你在库中将资产移动到另一个位置，则在重新扫描时这些元数据将丢失。这是因为移动后该资产被视为新资产。这是一个已知问题，未来版本将修复。

备注

由于激进的缓存机制，刷新后的资产可能需要一些时间才能在网页视图中正确显示。你需要清除浏览器缓存以查看更改。这是一个已知问题，未来版本将修复。在 Chrome 浏览器中，需要使用 F12 打开开发者控制台，然后按 F5 重新加载页面，最后右键单击刷新按钮并选择“清空缓存并强制刷新”。

导入路径​

外部库使用导入路径确定要扫描的文件。每个库可以有多个导入路径，以便来自不同位置的文件可以添加到同一个库。导入路径会递归扫描，如果文件存在于多个导入路径中，它将只被添加一次。每个导入文件必须是文件系统上可读的目录；导入路径对话框将提醒你任何不可访问的路径。

如果编辑导入路径使得外部文件不再存在于任何导入路径中，它将像被删除的文件一样从库中移除。如果文件移回导入路径，它将像新文件一样再次被添加。

故障排除​

有时候，外部库无法正确扫描，这可能由于 Immich 无法访问文件。以下是一些检查项：

  • 在 docker-compose 文件中，卷是否正确挂载？
  • 卷是否也挂载到了任何 worker 容器？
  • 导入路径是否正确设置，它们是否与 docker-compose 文件中设置的路径匹配？
  • 确保不要在导入库中使用符号链接，且不要跨 docker 挂载链接。
  • 权限是否正确设置？
  • 确保使用正斜杠(/)而不是反斜杠。

为了验证 Immich 是否可以访问你的外部库，请在容器内启动一个 shell。运行 docker exec -it immich_server bash 到 bash shell。如果你的导入路径是 /data/import/photos，使用 ls /data/import/photos 检查它。在任何微服务容器中进行同样的检查。

排除模式​

默认情况下，导入路径中的所有文件都会被添加到库中。如果有文件不应该被添加，可以使用排除模式将它们排除。排除模式是全局模式，匹配完整的文件路径。如果文件匹配排除模式，它将不会被添加到库中。排除模式可以在每个库的扫描设置页面中添加。

一些基本示例：

  • **/*.tif 将排除所有扩展名为 .tif 的文件
  • **/hidden.jpg 将排除所有名为 hidden.jpg 的文件
  • **/Raw/** 将排除任何目录名为 Raw 的文件
  • **/*.{tif,jpg} 将排除所有扩展名为 .tif 或 .jpg 的文件

特殊字符例如 @ 需要转义，例如：

  • **/\@eaDir/** 将排除任何目录名为 @eaDir 的文件
信息

在内部，Immich 使用 glob 包来处理排除模式，有时这些模式会被翻译成 Postgres LIKE 模式。目的是支持基本的文件夹排除，但我们建议不要使用高级用法，因为这些无法可靠地翻译成 Postgres 语法。有关 glob 模式的基本概述，请参阅 glob 文档。

自动监控（实验性）​

此功能被视为实验性功能，仅适合高级用户。如果启用，它将允许对文件系统进行自动监控，这意味着新资产会自动导入到 Immich 中，而无需重新扫描。

如果你的照片在网络驱动器上，自动文件监控可能无法工作。在这种情况下，你需要依靠定期的库刷新来拉取更改。

故障排除​

如果你遇到 ENOSPC 错误，需要增加文件监控器的限制。在 sysctl 中，此键名为 fs.inotify.max_user_watches，默认值为 8192。将此数字增加到一个适合你将监控文件数的值。请注意，Immich 必须监控导入路径中的所有文件，包括任何被忽略的文件。

错误 [LibraryService] 库监视器对库 c69faf55-f96d-4aa0-b83b-2d80cbc27d98 遇到错误：错误：ENOSPC：文件监视器的系统限制已达到，监视 '/media/photo.jpg'

在极少数情况下，库监视器可能会挂起，阻止 Immich 启动。在这种情况下，请在配置文件中禁用库监视器。如果监视器在 Immich 中启用，应用必须在没有微服务启动的情况下启动。禁用 docker-compose 文件中的微服务，启动 Immich，禁用管理员设置中的库监视器，关闭 Immich，重新启用微服务，然后可以正常启动 Immich。

每日任务​

有一个自动扫描任务，每天运行一次。此任务还会清理任何卡在删除中的库。可以通过点击库管理页面中的“扫描所有库”来触发清理。

使用方法​

让我们举一个具体的例子，展示如何向 Immich 添加现有的图库。这里我们有以下文件夹需要添加：

  • /home/user/old-pics：包含童年照片的文件夹。
  • /mnt/nas/christmas-trip：圣诞旅行的照片。子文件夹 /mnt/nas/christmas-trip/Raw 包含直接从 DSLR 来的原始文件。我们不希望将原始文件导入到 Immich。
  • /mnt/media/videos：来自同一圣诞旅行的视频。

首先，我们需要规划如何组织这些库。圣诞旅行的照片应该属于自己的库，因为我们希望排除原始文件。视频和旧照片可以在同一个库中，因为我们希望导入所有文件。如果在其他文件夹中没有匹配 Raw 排除模式的文件，我们也可以将这三个文件夹添加到同一个库中。

挂载 Docker 卷​

immich-server 容器需要访问图库。修改你的 docker-compose 文件如下

docker-compose.yml
  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
+     - /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 # 警告：Immich 可以删除此文件夹中的文件，因为它没有以 :ro 结束
+     - "C:/Users/user_name/Desktop/my media:/mnt/media/my-media:ro" # Windows 系统中的导入路径
提示

末尾的 ro 标记仅赋予卷的只读访问权限。 这将禁止在 Web UI 中删除图像或向库添加元数据（XMP 副文件）。

信息

记得运行 docker compose up -d 以注册更改。确保你可以在容器中看到挂载的路径。

创建新库​

这些操作必须由 Immich 管理员执行。

  • 点击右上角的头像
  • 点击 管理 -> 外部库
  • 点击 创建外部库…
  • 选择哪个用户拥有库，这不能更改
  • 输入 /mnt/media/christmas-trip 然后点击 添加
  • 点击 保存
  • 点击新创建库上的下拉菜单
  • 点击 扫描
  • 点击新创建库上的下拉菜单
  • 点击 重命名库，将其命名为“圣诞旅行”

注意：我们必须使用 /mnt/media/christmas-trip 路径，而不是 /mnt/nas/christmas-trip 路径，因为所有路径必须是 Docker 容器看到的路径。

接下来，我们将添加一个排除模式来过滤原始文件。

  • 点击刚刚创建的圣诞库上的下拉菜单
  • 点击 管理
  • 点击 扫描设置
  • 点击 添加排除模式
  • 输入 **/Raw/** 然后点击保存。
  • 点击保存
  • 点击新创建库上的下拉菜单
  • 点击 扫描

圣诞旅行库现在将在后台扫描。同时，让我们将视频和旧照片添加到另一个库。

  • 点击 创建外部库。
备注

如果你在这里遇到错误，请将其他外部库重命名为其他名称。这是一个将在未来版本中修复的错误。

  • 点击新创建库上的下拉菜单
  • 点击 编辑导入路径
  • 点击 添加路径
  • 输入 /mnt/media/old-pics 然后点击 添加
  • 点击 添加路径
  • 输入 /mnt/media/videos 然后点击 添加
  • 点击 保存
  • 点击 扫描

几秒钟内，old-pics 和 videos 文件夹中的资产应该出现在主时间线中。

文件夹视图​

文件夹视图提供了除了时间线视图之外的另一种额外视图，类似于文件资源管理器。它允许您浏览库中的文件夹和文件。这对于一个经过精心整理和定制的外部库或配置良好的存储模板非常方便。

您可以在 账户设置 > 功能 > 文件夹 中启用此功能。

设置自定义扫描间隔​

备注

此操作仅管理员可以执行。

您可以在管理 -> 设置 -> 外部库中定义触发外部库重新扫描的自定义间隔。 可以使用预设值或 Cron 格式设置扫描间隔。有关更多信息，可以参考 Crontab Guru。