Immich 系统完整性

完整性报告

Immich 会按可自定义的间隔执行完整性检查，确认资料库仍然完整，且不存在损坏文件。检查包括三类问题：

• 未跟踪文件：在 Immich 目录中发现了文件路径，但 Immich 数据库中没有相应引用。
• 缺失文件：Immich 内部数据库记录了路径，但磁盘上对应位置并不存在文件。
• 校验和不匹配：Immich 数据库保存的文件校验和与实际文件的校验和不再一致。

三类检查默认每天凌晨 3 点运行。由于文件校验和检查最耗费资源，它还设置了额外的时间及进度限制，以便在几天内逐步完成全部文件的校验和检查。

可以在维护页面查看检查结果，也可以为某个任务或全部任务触发完整扫描。此外，还可以刷新检查：刷新只重新查看当前已报告的问题，判断它们是否已经修复。

常见原因

最常见的是未跟踪文件。很多情况下，它们是损坏的缩略图，或只生成了一部分、后来未正确清理的转码视频。这些文件通常可以删除，因为之后可以重新生成。其他文件则需要逐一调查，确认相应资源是否已经存在于 Immich 中，并分析它们为何失去跟踪。

缺失文件指的是 Immich 内部仍引用某个文件，但磁盘上的对应位置已经没有这个文件。可能是有人从内部资料库目录中直接删除了文件；请勿这样操作，因为 Immich 不支持。也可能是文件存储本身存在问题。请仔细调查缺失文件；如有疑问，可以通过 Immich Discord 寻求帮助。

校验和不匹配通常意味着文件系统损坏，也可能是此前直接修改了磁盘上的内部资料库文件。后者同样不受支持，会导致校验和不匹配。建议逐一查看报告中的项目，检查文件，并回想是否曾修改文件或元数据。如果确实编辑过文件，受支持的解决办法是先从 Immich 中删除不匹配的资源，再把文件作为新资源上传。

目录检查

Immich 启动时会执行一系列检查，确认能够在存储系统使用的卷挂载目录中读写文件。如果无法完成全部必要操作，服务将无法启动。检查包括：

• 在每个目录中创建初始隐藏文件 .immich。
• 读取每个目录中的隐藏文件 .immich。
• 覆盖写入每个目录中的隐藏文件 .immich。

这些检查旨在发现以下情况：

• 权限不正确，导致无法读写文件。
• 卷未挂载：预期应存在的 .immich 文件却缺失。

常见问题

.immich 文件缺失

Verifying system mount folder checks (enabled=true)...ENOENT: no such file or directory, open 'upload/encoded-video/.immich'

上面的错误消息表示服务器此前已经成功在每个目录中写入 .immich 文件，但现在检测不到它们。可能原因如下：

• 权限错误：文件存在，但无法读取。
• 文件不存在：卷挂载发生变化，应修正挂载。
• 文件不存在：用户手动删除了文件，需要手动重新创建，可使用 touch .immich。
• 文件不存在：从备份恢复时没有恢复全部目录，应恢复所有目录，或在缺失的目录中手动创建 .immich。

忽略检查

IMMICH_IGNORE_MOUNT_CHECK_ERRORS=true

原文：System Integrity。作者／来源：Immich 文档贡献者。本文依据所列原文整理为中文，代码、命令与配置示例保留原文。