LibrePhotos 缺失照片机制详解：标记原理、自动重链与批量清理实战

LibrePhotos 缺失照片机制详解：标记原理、自动重链与批量清理实战

【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotos

当照片文件被移动、重命名或存储介质断开时，LibrePhotos 不会直接删除数据库记录，而是将其标记为"缺失照片"（Missing Photos）。本文基于官方用户指南，结合后端源码（扫描任务、文件检查与批量删除作业）深入讲解缺失照片的标记时机、自动重链（hash 匹配）原理、识别方式与四种处理方案，帮助你在自托管图库中安全地管理文件与元数据的一致性。

什么是缺失照片

缺失照片是指其元数据（metadata）和缩略图（thumbnails）仍然保存在 LibrePhotos 数据库中，但实际的图像文件在文件系统中找不到的照片。这一状态通常由两类场景触发：

1. 文件被外部移动或重命名—— 通过文件管理器、操作系统工具或 LibrePhotos 以外的其他程序移动/重命名了文件；
2. 存储或挂载问题—— 外置硬盘未挂载、网络存储（NAS）断开、Docker 挂载点配置错误等。

从源码结构看，"缺失"状态落在File模型上：缺失文件不会被物理删除，而是被设置missing=True标记（见 File 模型 及历史迁移 0036_handle_missing_files.py），这正是"数据库保留记录、磁盘文件缺席"这一设计在实现层的对应。

为什么 LibrePhotos 要保留缺失照片

LibrePhotos 有意在数据库中保留缺失照片，而不是立即删除。这是基于真实使用场景的设计决策：

• 文件往往会回来—— 重新挂载硬盘、修复存储配置，或发现文件被误移动后，文件通常会重新出现；
• 元数据得以保留—— 你的评分（ratings）、说明文字（captions）、人脸标签（face tags）和相册归属都会被完整保存；
• 可自动重链（automatic relinking）—— 当文件重新出现在扫描目录中时，LibrePhotos 可以基于内容哈希（hash-based matching）自动把文件与原有元数据重新关联。

照片何时被标记为缺失

LibrePhotos只在执行缺失文件检查（missing-file check）时标记缺失照片。该检查作为照片扫描（photo scan）的最后步骤之一自动运行，但仅在以下两种情况下触发：

• 扫描是全量扫描（full scan，即对整个图库的重扫）；
• 或者扫描覆盖了用户配置的扫描目录（scan directory），且没有指定某个具体文件列表。

因此，只针对特定文件或单个子目录的扫描（例如一次上传）会被跳过——除非它本身就是全量扫描。检查只针对你自己的照片：对每一张在磁盘上已找不到文件的照片，将其标记为缺失。

重要澄清：仅仅是打开、查看或下载一张文件已丢失的照片，不会把它标记为缺失——你会为那一张照片收到一个错误而已。缺失照片计数只会在扫描执行了该检查之后才更新。

这一点在源码中可以直接印证。扫描任务在派发完毕后，由 _queue_followup_jobs 决定是否追加缺失检查作业：

def _queue_followup_jobs(user, full_scan, scan_directory, scan_files): """Queue the jobs that run once the scan itself has been dispatched.""" # if the scan type is not the default user scan directory, or if it is specified as only scanning # specific files, there is no need to rescan fully for missing photos. if full_scan or (scan_directory == user.scan_directory and not scan_files): AsyncTask(scan_missing_photos, user, uuid.uuid4()).run() ...

即：只有full_scan为真，或扫描目录等于user.scan_directory且未指定scan_files时，才会异步派发 scan_missing_photos 作业。该作业以每页 5000 张的分页方式遍历当前用户的所有照片，并逐张调用Photo模型上的_check_files()：

def scan_missing_photos(user, job_id: UUID): lrj = LongRunningJob.get_or_create_job( user=user, job_type=LongRunningJob.JOB_SCAN_MISSING_PHOTOS, job_id=job_id, ) existing_photos = Photo.objects.filter(owner=user.id).order_by("image_hash") paginator = Paginator(existing_photos, 5000) ... for existing_photo in paginator.page(page).object_list: existing_photo._check_files()

而 _check_files() 的核心逻辑非常直白：

def _check_files(self): for file in self.files.all(): if not file.path or not os.path.exists(file.path): self.files.remove(file) file.missing = True file.save() self.save()

注意其中的关键细节：缺失的文件会被从Photo.files多对多关系中解绑（detach），但File行本身被保留并标记missing=True。这正是后续"文件重现时自动重链"能够成立的前提。

常见的导致照片缺失的场景包括：

• 用文件管理器把照片移动到其他文件夹
• 在 LibrePhotos 之外重命名照片文件
• 外置硬盘在启动时未挂载
• 网络附加存储（NAS）断开
• Docker 配置中的挂载点被修改
• 云存储同步出现问题

如何识别缺失照片

LibrePhotos 提供两种发现缺失照片的方式：

方式一：Library 页的缺失照片徽章（Badge）

点击右上角头像选择Library。如果有任何照片缺失，Photos标题旁会出现一个红色的"N Missing Photos"徽章；计数为零时该徽章隐藏。将鼠标悬停在徽章上可以阅读一段关于 LibrePhotos 如何标记缺失照片的简短说明。

注意：点击徽章会打开Remove missing photos确认对话框，它会永久删除这些照片的数据库记录。除非你确实打算删除，否则请只悬停、不要点击。

方式二：照片详情视图

缺失照片保留缩略图，因此它在时间线和相册中仍然显示正常。区别只体现在照片详情视图：由于文件已从照片上解绑，文件名显示为"Unknown filename"，文件夹路径面包屑也被隐藏。

此外，媒体服务层对"文件真的不在磁盘上"这一事实有专门诊断：在 serving_permissions.py 中定义了CAUSE_MISSING = "missing"，供媒体访问诊断接口区分"文件不存在"与其他故障原因。

处理缺失照片的四种方案

方案 1：把文件恢复回原位置

如果你知道文件去了哪里：

1. 将文件移动或复制回原始位置；
2. 如果文件被移动到了扫描目录内的新位置，LibrePhotos 可以自动重链它；
3. 运行一次照片扫描以更新数据库。

方案 2：修复存储配置

如果问题是挂载或存储相关的：

1. 确认外置硬盘已正确挂载；
2. 检查 Docker 卷挂载配置；
3. 验证网络存储可访问；
4. 修复存储问题后重启 LibrePhotos；
5. 从Library页面运行扫描（头像菜单 →Library→Scan Library→Scan），让 LibrePhotos 重新检查并重链恢复的文件。

方案 3：自动重链（Automatic Relinking）

LibrePhotos 在文件重新出现时会自动重链照片：

• 常规照片扫描期间，系统使用基于哈希的匹配；
• 如果扫描目录中任何位置出现内容哈希相同的文件，它会自动关联到已有的照片元数据；
• 即使文件被重命名或移动到了不同文件夹，这一机制也有效。

手动触发自动重链的步骤：

1. 点击右上角头像选择Library（或按Ctrl+K搜索 "Library"）；
2. 在Scan Library一行点击Scan执行新扫描（完整重读所有文件的全量重扫可在其旁边的下拉菜单中通过Rescan触发）；
3. LibrePhotos 会检测并重新链接匹配的文件。

源码层面，这一"收养"逻辑位于 file_handlers.py 中的 group_files_into_photo：创建 Photo 之前，它先用文件集合与main_file双重匹配查找已有照片——注释明确解释了为什么必须同时匹配main_file：

# Check if a Photo already exists with any of these files. Matching on # main_file as well as the files m2m re-adopts photos whose file went # missing and reappeared: _check_files detaches a missing file from the # m2m but keeps main_file pointing at it, so without that match a # reappearing file would spawn a duplicate Photo with the same image_hash. existing_photo = Photo.objects.filter( Q(owner=user) & (Q(files__in=files) | Q(main_file__in=files)) ).first() if existing_photo: _adopt_files_into_photo(existing_photo, files, main_file, job_id) return existing_photo

命中后，_adopt_files_into_photo 把重新出现的文件挂回既有 Photo，并且当新主文件的类型优先级更高时（按FILE_TYPE_PRIORITY，IMAGE > VIDEO > RAW > METADATA）自动升级main_file。这样设计避免了同一image_hash的照片被重复创建，也保证了重链后元数据、评分与人脸标签全部保留。

方案 4：删除缺失照片

如果你确定文件已永久丢失：

1. 打开Library页面（头像菜单 →Library）；
2. 在Photos标题旁点击红色的"N Missing Photos"徽章——仅当你的库中确实存在缺失照片时它才会出现；
3. 在Remove missing photos对话框中点击Confirm；
4. 这会从数据库永久移除所有缺失照片，包括：
   • 照片元数据与 EXIF 信息
   • 缩略图
   • 人脸检测记录
   • 相册关联
   • 评分与说明文字

同一操作也可以通过 Spotlight 命令面板（Ctrl+K）中的Delete Missing Photos触发。

注意：删除缺失照片是永久性的。请确认文件确实已丢失且不会恢复后再使用此选项。

对应的后端实现是 views.py 中的 DeleteMissingPhotosView，它通过AsyncTask异步派发 delete_missing_photos 作业（长任务类型JOB_DELETE_MISSING_PHOTOS，见 long_running_job.py）。该作业的实现值得注意几个工程细节：

• 缺失照片的判定条件是files与main_file均为空：Photo.objects.filter(Q(owner=user) & (Q(files=None) | Q(main_file=None)))；
• 分批删除：以_DELETE_MISSING_BATCH_SIZE = 200为批次调用Photo.objects.filter(pk__in=...).delete()，依赖数据库级联（CASCADE）清理 Face、缩略图等关联行，并通过长任务进度条实时更新；
• 级联绕过信号后的手动补偿：AlbumThing.photos.through与Tag.photos.through的信号接收器负责维护photo_count/cover_photos，但级联删除会绕过信号，因此作业在每个批次后快照受影响的相册/标签 ID，并在全部删除完成后统一刷新photo_count、重算默认封面、刷新标签计数；
• 清理悬空 File 行：最后还会按File.hash以md5 + str(user.id)组合规则筛出当前用户名下的missing=True的File记录并删除，避免数据库残留无主文件行。

删除完成后，你可以在管理区（Admin Area）的长任务列表中查看该作业的执行状态——这属于 LibrePhotos 任务系统（Job System）的一部分。

常见场景与解决方案

场景一：外置硬盘未挂载

问题：LibrePhotos 启动时，存放照片的外置硬盘尚未挂载。

解决：

1. 挂载外置硬盘；
2. 重启 LibrePhotos 容器以识别已挂载的硬盘；
3. 照片应能自动恢复可用。

场景二：Docker 挂载点被修改

问题：修改了 Docker 卷配置后，照片路径不再匹配。

解决：

1. 将 Docker 配置改回原始挂载点，或者
2. 把照片移动以匹配新挂载点；
3. 重启 LibrePhotos；
4. 从Library页面运行扫描以更新数据库。

场景三：文件被移动到其他文件夹

问题：你用文件管理器重新整理了照片集合。

解决：

1. 如果新位置在你的扫描目录内，只需从Library页面运行一次扫描（Scan Library→Scan）；
2. LibrePhotos 会通过哈希检测文件并自动重链；
3. 原有元数据、评分和人脸标签都会保留。

场景四：文件被移到回收站

问题：照片移到回收站后显示为缺失。

解决：

• 想保留：从回收站恢复文件并运行一次扫描；
• 想移除：使用 Library 页面上的"N Missing Photos"徽章（或 Spotlight 面板中的Delete Missing Photos操作）清理数据库。

未来改进：实时文件系统监控

LibrePhotos 正在推进实时文件系统监控，届时将：

• 自动检测文件的移动或重命名；
• 无需手动扫描即可即时更新照片路径；
• 大幅减少照片被标记为缺失的情况；
• 在文件于扫描目录内移动时提供即时重链。

该实时监控计划使用文件系统监视器（Linux 上的 inotify、macOS 上的 FSEvents）在变更发生的当下追踪变化，让缺失照片体验更加无缝。

相关文档

• 回收站管理（Trash Management） —— 了解 LibrePhotos 的回收站系统
• 任务系统（Job System） —— 理解 "Delete Missing Photos" 等长任务，以及如何在管理区监控它们
• 自动扫描（Auto Scan） —— 配置照片自动扫描

【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotos