跳转到主要内容

常见问题

用户​

如何重置管理员密码？​

可以通过在 Immich 服务器上运行 reset-admin-password 命令来重置管理员密码。

如何查看 Immich 中所有用户的列表？​

可以通过在 Immich 服务器上运行 list-users 命令来查看所有用户的列表。

移动应用​

移动应用中的云图标有何区别？​

图标描述
cloud资源只在服务器上可用，并且是从其他设备（例如 Web 客户端）上传的，或者在上传后从此设备上删除
cloud-cross资源仅本地可用，尚未备份
cloud-done资源是从此设备上传的，并已备份到服务器；原始文件仍保存在设备上

更新后无法登录应用程序。我该怎么办？​

请确认移动应用和服务器运行的是相同的版本（主版本号和次版本号一致）。

备注

由于应用商店（Google Play 商店和 Apple 应用商店）需要先批准更新，应用商店的更新有时可能需要更长时间。

如果仍然无法登录，请尝试以下操作：

  • 检查移动端日志
  • 确保登录凭据正确，可通过 Web 应用进行登录验证

为什么前台备份在离开应用时会停止？它不应该移交给后台备份吗？​

前台备份和后台备份是两个独立的机制。它们彼此之间没有通信或交互。

前台备份由用户的操作控制，而后台备份则由设备的操作系统控制。当应用被切换到后台时，后台任务的调用由设备的操作系统调度器负责，操作系统根据自身规则决定何时允许启动后台任务以及运行时间的长短。

不同的设备制造商和操作系统的行为可能不同，但大多数与节约电池的策略有关。

为什么 iOS 上的后台备份无法工作？​

在 iOS（iPhone 和 iPad）上，操作系统会根据多个因素决定是否允许某个应用调用后台任务，而这些因素大部分不受 Immich 应用控制。为增加后台备份任务运行的可能性，请执行以下步骤：

  • 在 iOS 设置中的 设置 > 通用 > 后台应用刷新 中为 Immich 启用后台应用刷新。
  • 在不需要时禁用低电量模式，因为这可能会阻止应用在后台运行。
  • 为不需要后台任务运行的应用禁用后台应用刷新。这将减少与 Immich 后台任务调用的竞争。
  • 更频繁地使用 Immich 应用。

为什么移动应用的一些功能不支持自签名证书、基本身份认证、自定义头或双向 TLS？​

这些网络功能是实验性的。它们通常在视频播放、资源上传或下载以及其他功能上不起作用。 许多这类限制记录在 #15230。 我们建议使用 URL 切换功能、VPN 或为您的域获取 免费的可信 SSL 证书 来替代这些实验功能。

我们目前并未积极开发这些功能，无法提供支持，但欢迎贡献代码以改进这些功能。 对于较大的 PR，请在开发之前先与我们的开发团队讨论，以确保您的时间不会浪费。

为什么移动应用程序还没有更新？​

应用商店可能需要几天时间才能批准该应用的新版本。如果您急切等待，可以从 GitHub 发布页面下载 Android 的 APK。

资源​

Immich 是否更改文件？​

不会，Immich 不会修改原始文件。 所有编辑的元数据都保存在伴随的 .xmp 辅助文件和数据库中。 但当垃圾箱在 Immich UI 中被清空时，Immich 会删除原始文件。

为什么在文件管理器中我的文件名显示为随机字符串？​

当存储模板被关闭（默认设置）时，Immich 会将文件名保存为随机字符串（也称为随机 UUID），以防止文件名重复。 要获取原始文件名，您需要启用存储模板并运行存储模板迁移任务。 建议在启用前了解 存储模板。

我可以添加现有的照片库吗？​

可以，通过使用 外部库。

选择新的 存储模板 后，现有文件会如何处理？​

模板更改仅适用于新的资源。要对之前上传的资源应用模板，请运行可在 任务 页面上找到的存储迁移任务。

为什么只有照片而不是视频被上传到 Immich？​

这通常发生在使用反向代理时。 确保为 反向代理设置 允许大请求。 同时检查反向代理的磁盘空间。 某些情况下，代理会在将请求传递出去之前将其缓存到磁盘，如果磁盘空间不足，请求将失败。

如果您使用的是 Cloudflare Tunnel，需要注意它们设置了 100 MB 不可更改的最大文件大小限制。 有时，更大的文件（潜在地高达 1 GB）可能会成功上传，但官方的限制是 100 MB。 如果遇到问题，建议更换网络部署方式。

为什么某些照片在文件系统中存储的日期不正确？​

有几种情况可能导致这种状况。解决办法是重新运行存储迁移任务。 该任务在上传后默认仅为每个资源自动运行一次。如果最初元数据提取失败、任务被清除/取消等，任务可能不会自动运行。

如何在时间轴中隐藏照片？​

您可以将它们 归档。

如何从 Immich 备份数据？​

请参阅 备份与恢复。

Immich 是否支持读取现有的人脸标签元数据？​

支持，它会从导入的资源元数据中创建新的人脸和人物。详情请参阅 功能请求 #4348 和 PR #6455。

Immich 支持过滤 NSFW 图片吗？​

目前不支持。有关详细情况，请查看 GitHub 上的开放功能请求。

为什么有这么多缩略图生成任务？​

每个资源有三种缩略图任务：

  • 模糊缩略图（thumbhash）
  • 预览缩略图（Webp 格式）
  • 缩略图（Jpeg 格式）

此外，还有用于人物（人脸）缩略图的额外任务。

为什么来自 WhatsApp 的文件显示的日期不正确？​

通过 WhatsApp 发送的文件保存时没有元数据。因此，当文件从 WhatsApp 上传时，Immich 无法知道文件的原始日期或设备上的到达顺序。 参阅讨论 #9116。

当一个资源存在于多个账户中会发生什么？​

用户之间的资源无需唯一。如果多个用户上传了相同图片，它会被视为不同的资源进行处理，相应的任务会运行并生成缩略图。

为什么 HDR 视频在 Immich 播放器中呈现苍白，但下载后正常？​

Immich 使用的播放器已知存在 HDR 颜色显示问题。我们正在尝试实验一个不同的播放器，以为未来改进提供更好的 HDR 内容颜色配置文件。

为什么 Immich 会将我的视频转码为更低质量？​

Immich 始终保留您的原始文件。同时，为了兼容性和性能原因，它会生成转码版本。

如何在不删除原始文件的情况下删除转码视频？​

可以通过设置一个不需要转码的视频策略并运行转码任务来删除资源的转码版。这可以在单个资源视图中通过选择“刷新编码视频”按钮来完成，或通过管理页面为所有资源运行转码任务。

要更新转码策略，请导航到管理>视频转码设置>转码策略，从下拉菜单中选择一个策略。这个策略会决定在运行转码任务时已存在的转码是否被删除或覆盖。如果根据策略视频需要转码，则现有转码会被覆盖；如果不需要，则会被删除。

备注

例如，假设您已有转码的策略是“高于普通分辨率或不在期望格式的视频”，现在切换到更严格的策略：“不在期望格式的视频”。如果某个资源因其分辨率被转码，则运行转码任务会删除现有转码。这是因为分辨率不再属于转码策略，转码变得多余。同样，如果设置的策略为“不要转码任何视频”，并为所有资源运行转码任务，则会删除所有现有的转码，因为它们没有必要。

备份时是否可以压缩图片？​

不可以。我们的设计原则是保持原始资源始终原封不动。

如何在 Docker 中挂载 CIFS/Samba 共享卷？​

如果您无法或不想在主机上挂载 Samba（例如在 Windows 环境中），可以直接在 Docker 中挂载该共享卷。 以下是一个 docker-compose.yml 文件中的示例。

替换为您的用户名、密码、本地 IP 和共享名称，并注意下面 - originals:/usr/src/app/originals 这行， 对应的是 originals 卷被创建的部分。您可以根据需要命名此卷，并将其映射到 Docker 容器上的任何路径。 例如，您可以将 originals: 改为 Photos:，并将 - originals:/usr/src/app/originals 改为 Photos:/usr/src/app/photos。

...
services:
  immich-server:
...
    volumes:
      # 不要修改下一行。如果您希望更改系统上的媒体存储位置，请更改 .env 文件中 UPLOAD_LOCATION 的值
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
+     - originals:/usr/src/app/originals
...
volumes:
  model-cache:
+ originals:
+   driver_opts:
+     type: cifs
+     o: 'iocharset=utf8,username=USERNAMEHERE,password=PASSWORDHERE,rw' # 如果只读需要，将 `rw` 改为`ro`
+     device: '//localipaddress/sharename'

相册​

在将资源导入 Immich 时，我可以保留现有的相册结构吗？​

可以，通过使用 Immich CLI 和 --album 参数。

是否有办法在相册中重新排列照片？​

目前还没有。关于此计划功能的更新，请关注 GitHub 讨论。

外部库​

我可以在保持现有相册结构的同时添加外部库吗？​

我们尚未实现从外部库创建相册的官方机制，但社区提供了一些解决方法可以帮助您实现这一点。

外部库中的重复项会怎样处理？​

仅使用文件哈希值检查上传库中的重复项。此外，重复项检查不是全局的，而是针对 每个库 的。因此，可能会出现同一个文件两次出现在时间轴中的情况，特别是在使用外部库时。

为什么我对只读外部库中的文件进行了编辑但未被保存？​

可以正常编辑可读写的外部库（默认设置）中的图像。 在只读库中（docker-compose.yml 中的 :ro），Immich 无法创建 .xmp 辅助文件来保存编辑后的文件元数据。 因此，无法编辑只读外部库中的文件元数据（时间戳、位置、描述、星级等）。

外部库文件的删除如何处理？​

当清空回收站时，Immich 将尝试删除被移至回收站的原始文件。 在可读写的外部库中（默认设置），Immich 会删除原始文件。 在只读库中（docker-compose.yml 中的 :ro），文件仍然可以在 UI 中放入回收站。 但是，当清空回收站时，这些文件会重新出现在主时间轴中，因为 Immich 无法删除原始文件。

机器学习​

智能搜索是如何工作的？​

Immich 使用 CLIP 模型。一个机器学习模型会将每张图片转换成一个"嵌入"，这本质上是一串含义化编码图片内容的数字。这同样适用于您搜索时输入的文本，文本嵌入与图片嵌入会对比以找到相似内容。因此，这并不会生成您可查看的"标签"、"标注"或"描述"。若要了解更多关于 CLIP 及其功能，请查看这里。

面部识别是如何工作的？​

详情请参阅面部识别工作原理。

我如何禁用机器学习？​

信息

禁用机器学习将使搜索和“探索”页面的体验变差，因为这些依赖于机器学习功能。

您可以在 管理 > 设置 > 机器学习设置 中禁用机器学习功能，可以选择完全禁用或者按模型类型禁用。例如，您可以选择禁用 CLIP 智能搜索，但保持面部识别功能启用。这意味着机器学习服务将仅处理启用的作业。

但是，禁用所有作业并不会禁用机器学习服务本身。为了防止它完全启动，您可以注释掉 docker-compose.yml 文件中的 immich-machine-learning 部分。

出现关于模型损坏或下载失败的错误时，我该怎么办？​

您可以删除模型缓存卷，其中存储了已下载的模型。这将为服务提供一个干净的环境以重新下载模型。如果模型始终无法下载，您可以从 Hugging Face 网站手动下载并放置在缓存文件夹中。

我可以使用自定义的 CLIP 模型吗？​

不支持。目前仅支持 Hugging Face 页面列出的模型。如果此处未列出某个您认为应该添加的模型，可以提交功能请求。

我想使用除了英语以外的其他语言搜索，这该怎么办？​

您可以切换到一个多语言 CLIP 模型，具体操作请参见这里。

Immich 是否支持视频内的面部识别？​

Immich 的机器学习功能会对生成的缩略图进行操作。如果视频缩略图中有面部，则会被面部识别捕捉到。 扫描整个视频中的面部可能会在未来实现。

Immich 是否支持动物识别？​

不支持。

提示

您可以使用一定程度的 智能搜索。例如，如果您有一只金毛和一只吉娃娃，可在智能搜索中输入这些单词，查看搜索结果。

为什么我看到很多并不是面部的“面部”，我该怎么办？​

您可以将 MIN DETECTION SCORE 增加到 0.8，以减少错误的缩略图。将分数设置得过高（如高于 0.9）可能会根据所用的库过滤掉太多真实面孔。如果您想隐藏特定面孔，可以调整管理面板中的 "MIN FACES DETECTED" 设置， 从而提高算法对某人的 "核心面孔" 的判定标准，减少错误缩略图的选择概率。

immich_model-cache 卷占用了很多空间，这可能是什么问题？​

如果您安装了多个模型但选择不使用它们，可能需要删除 immich_model-cache 中的旧模型。为此，您可以挂载模型缓存并删除不需要的模型。

步骤
docker run -it --rm -v immich_model-cache:/mnt-models alpine sh
cd /mnt-models
ls clip/ facial-recognition/
# rm -r clip/ABC facial-recognition/DEF # 删除不需要的模型

性能​

为什么在像 Raspberry Pi 这样的低内存系统上 Immich 运行缓慢？​

Immich 可选启用了包括转码和机器学习在内的多个功能。然而，这些运行在 Raspberry Pi 上可能会过于复杂。您可以 减轻负担，或将 Immich 的机器学习容器托管在性能更高的系统上，或者完全禁用机器学习功能。

我可以降低 CPU 和内存使用率吗？​

最初的备份是最密集的阶段，因为会启动大量作业。使用 CPU 最密集的是转码和机器学习作业（智能搜索、面部检测），其次是缩略图生成。以下是一些降低 CPU 使用率的方法：

  • 将这些作业的并发数量降低到 1。
  • 在设置中找到 转码设置 > 线程，将线程数量设置为 1 或 2。
  • 在设置中找到 机器学习设置 > 面部识别 > 模型名称，可以将面部识别模型更改为 buffalo_s，而不是 buffalo_l。前者是更小且更快的模型，但精度略低。
    • 为了让新图像的面部识别正常工作，您需要重新运行所有图像的面部检测作业。
  • 在容器级别，您可以设置资源限制进一步降低使用率。
    • 推荐在采用上述措施后再应用资源限制以获得最佳性能。
  • 如果这些更改仍然无法满足要求，请参见上文禁用机器学习的说明。

我可以限制 CPU 和内存使用率吗？​

默认情况下，容器对资源没有约束，可以使用内核允许的任意资源。为了限制这一点，您可以在 docker-compose.yml 文件中为任何容器添加以下配置以限制资源使用。

docker-compose.yml
deploy:
  resources:
    limits:
      # CPU 线程数
      cpus: '1.00'
      # 内存（单位为 GB）
      memory: '1G'

更多详情请参阅 Docker 文档或使用这篇指南。

请注意，内存限制会通过终止容器来实现，因此如果设置过低可能会导致不稳定。

如何提升机器学习的速度？​

备注

以下建议提高吞吐量而非延迟。这意味着智能搜索作业会处理得更快，但搜索本身时间不会缩短。

您可以通过增加机器学习作业（智能搜索、面部检测）的作业并发数来提高吞吐量。增加并发数后，主机将同时处理更多资源。可通过 管理 > 设置 > 作业设置 中更改并发数。

危险

在普通机器上，2到3个并发任务可能已经最大化了CPU。存储速度和延迟很快就会成为限制因素，尤其是在使用硬盘驱动器（HDD）时。

使用GPU可以更轻松地增加并发性，但在大多数情况下仍不应超过16。

不要过度夸大任务并发性，因为这可能会使服务器严重超载。

我的服务器显示服务状态离线 | 版本未知。我该怎么办？​

您需要在反向代理上启用WebSockets。

Docker​

我如何查看Immich日志？​

Immich组件通常使用Docker进行部署。要查看已部署的Docker容器的日志，可以使用Docker CLI，特别是docker logs命令。有关示例，请参阅Docker帮助。

我如何减少Redis日志的冗长程度？​

要减少Redis日志，可以在docker-compose.yml文件的redis:部分添加以下行：

command: redis-server --loglevel warning

我如何以非root用户身份运行Immich？​

您可以通过在每个服务的docker-compose.yml文件中设置user参数来更改容器中的用户。 您可能需要为以下内部容器路径添加挂载点或Docker卷：

  • immich-machine-learning:/.config
  • immich-machine-learning:/.cache
  • redis:/data

非root用户/组需要对卷挂载点具有读写权限，包括UPLOAD_LOCATION和机器学习中的/cache。

Docker Compose卷

Docker Compose顶级卷元素不支持非root访问，上述所有卷都必须是本地卷挂载。

为了进一步强化系统，您可以为每个容器添加以下块。

docker-compose.yml
security_opt:
  # 防止容器启动后权限升级
  - no-new-privileges:true
cap_drop:
  # 防止访问原始网络流量
  - NET_RAW

我如何清除Immich中的数据？​

Immich的数据有两种形式：

  1. 元数据存储在Postgres数据库中，存储在DB_DATA_LOCATION文件夹中（以前是pg_data Docker卷）。
  2. 文件（原始文件、缩略图、个人资料等），存储在UPLOAD_LOCATION文件夹中，更多信息。
警告

这将销毁您的数据库并重置您的实例，意味着您将从头开始。

移除Immich（容器和卷）
docker compose down -v

在移除容器和卷后，需要删除一些目录以将Immich重置为新的安装。一旦删除这些目录，就可以重新启动Immich，它将成为一个全新的安装。

  • DB_DATA_LOCATION包含数据库、媒体信息和设置。
  • UPLOAD_LOCATION包含上传到Immich的所有媒体。
Portainer

如果您使用Portainer，请在Portainer中下拉堆栈。进入卷部分， 删除所有与Immich相关的卷然后重新启动堆栈。

为什么机器学习服务报告工作线程崩溃？​

备注

如果错误提示工作线程正在退出，那么这是正常现象。这是一项旨在减少在服务未被使用时消耗RAM的功能。

可能出现这种情况的几个原因。

如果错误提到SIGKILL或错误代码137，这很可能意味着服务内存不足。 考虑增加服务器的内存或将服务移到具有更多内存的服务器。

如果提到SIGILL（注意缺少K）或错误代码132，这很可能意味着您的服务器CPU与Immich不兼容。

数据库​

为什么我收到数据库所有权错误？​

如果您在数据库启动时收到诸如FATAL: data directory "/var/lib/postgresql/data" has wrong ownership之类的数据库错误，这可能是由于文件系统问题。 不支持NTFS和ex/FAT/32文件系统。更多详情请参阅此处。

我如何验证数据库的完整性？​

自v1.104.0以来，新安装默认启用了数据库校验和。您可以运行以下命令检查是否启用。结果为on表示校验和已启用。

检查校验和是否启用
docker exec -it immich_postgres psql --dbname=postgres --username=<DB_USERNAME> --command="show data_checksums"
 data_checksums
----------------
 on
(1 row)

如果校验和已启用，您可以使用以下命令检查数据库状态。正常结果是所有值都为0。

检查数据库是否损坏
docker exec -it immich_postgres psql --dbname=postgres --username=<DB_USERNAME> --command="SELECT datname, checksum_failures, checksum_last_failure FROM pg_stat_database WHERE datname IS NOT NULL"
  datname  | checksum_failures | checksum_last_failure
-----------+-------------------+-----------------------
 postgres  |                 0 |
 immich    |                 0 |
 template1 |                 0 |
 template0 |                 0 |
(4 rows)

您还可以扫描Postgres数据库文件结构是否存在错误：

扫描文件结构错误
docker exec -it immich_postgres pg_amcheck --username=<DB_USERNAME> --heapallindexed --parent-check --rootdescend --progress --all --install-missing

正常结果将以类似于以下内容结束，并返回退出代码为0：

7470/8832 relations (84%), 730829/734735 pages (99%)
8425/8832 relations (95%), 734367/734735 pages (99%)
8832/8832 relations (100%), 734735/734735 pages (100%)

如果检测到损坏，您应立即进行备份，在数据库中进行任何其他操作之前。 为此，您可能需要为数据库服务器设置zero_damaged_pages=on标志以使pg_dumpall成功。 完成备份后，推荐的下一步是从检测到损坏之前的健康备份中恢复数据库。 如有需要，可以使用损坏的数据库转储手动恢复备份后做出的任何更改。

可能的损坏原因有很多，包括意外断电或卸载、使用网络共享存储Postgres数据或者存储介质质量问题（如SD卡或损坏的硬盘/固态硬盘）。