LibrePhotos 全库自动扫描指南：从 `manage.py scan` 到 cron 定时增量扫描

LibrePhotos 全库自动扫描指南：从manage.py scan到 cron 定时增量扫描

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

本篇技术指南以 LibrePhotos 官方文档《Auto scan all folders》为骨架，完整讲解如何通过manage.py scan管理命令扫描照片库：包括增量扫描、强制全量重扫（-f）、指定文件扫描（-s）、Nextcloud 库扫描（-n）以及如何用 cron 实现每日定时自动扫描。同时结合仓库源码（scan.py、scan_jobs.py）剖析扫描命令的底层两阶段架构与增量判定原理，帮助读者既能直接上手运维，也能理解扫描究竟做了什么。

快速开始：一条命令触发全库扫描

LibrePhotos 的扫描入口是一个 Django 管理命令，位于后端容器内。默认部署下直接执行：

sudo docker exec --user root backend python3 manage.py scan

命令中的backend是后端容器的默认名称，由 docker-compose.yml 中后端服务（backend 服务）的container_name:键定义。如果你修改过容器名（例如在同一台主机上跑多套 LibrePhotos 栈），需要把backend替换成你自己的容器名——这些名称正是docker exec、docker logs等命令要使用的名字。修改方式参见环境变量文档，那里明确指出容器名与 Compose 中的服务名（proxy:、db:、frontend:、backend:）是两套概念：服务名用于容器间互相访问，container_name才是宿主机上docker exec要用到的名称。

提示：--user root是为了保证后端容器内运行命令的用户权限足够读取扫描目录；若你的部署环境有自定义用户，可按需调整。

scan 命令的三种运行模式

manage.py scan支持三种互斥的运行模式，由 scan.py 中的命令行解析器定义（add_mutually_exclusive_group，即-f、-s、-n三者不可同时使用）：

例如：

# 强制全量重扫 sudo docker exec --user root backend python3 manage.py scan -f # 只扫描两个指定的文件 sudo docker exec --user root backend python3 manage.py scan -s /path/a.jpg /path/b.jpg

scan.py中handle()的分发逻辑很直观：先判断-n，再判断是否传入了scan_files，否则走普通目录扫描。此外命令默认对所有用户（排除系统内部自动创建的 deleted 用户，见scannable_users()）逐个执行扫描；-s模式下还会按user.scan_directory前缀过滤文件，把属于不同用户的文件分发给各自账号处理，因此-s传入的文件必须落在某位用户的扫描目录内才会被处理。

更完整的命令清单（含build_similarity_index、save_metadata、start_service all、clear_cache、createuser、createadmin等）见《Library Management》文档的管理命令一节。

增量扫描的判定原理：它如何知道"哪些文件是新的"

默认的scan是增量式：只拾取自上次成功完成的扫描以来新增或修改过的文件。要理解这条规则，需要看扫描的核心实现 scan_jobs.py：

• 基线是"上次完成的扫描"：_last_finished_scan()取该用户最近一条finished=True且类型为JOB_SCAN_PHOTOS的LongRunningJob记录，以其finished_at作为时间基线；
• 判定函数_group_needs_processing()对每个文件组做三件事：文件路径是否已存在于数据库（Photo.objects.filter(files__path=...)）、是否是全量扫描、以及修改时间检查——_file_was_modified_after()用os.path.getmtime()与基线时间比较；
• 值得一提的是，修改时间检查不仅针对照片本身，还会遍历其按优先级排序的 XMP sidecar 文件（get_sidecar_files_in_priority_order），sidecar 元数据文件被修改同样会触发该组照片重新处理，这是编辑 EXIF/标签后能通过增量扫描刷新的关键机制；
• 若不存在已完成的历史扫描记录（首次扫描），则视为全量处理。

为了在大图库上提速，scan_jobs.py 还引入了按批（默认 10000 个文件组一批）查询已知路径的优化_select_groups_to_process()：把"每个文件一次数据库 round-trip"降为"每批一次files__path__in查询"，同时控制常驻内存只占一个批次，避免加载全部已知路径导致的 RAM 峰值。

扫描到底做了什么：两阶段架构与后续任务链

理解了增量判定后，再看扫描任务的完整流程。scan_photos()（scan_jobs.py）采用两阶段扫描架构，专门用于规避 RAW+JPEG 并发分组时的竞态条件：

• Phase 1（收集与分组）：walk_directory()递归遍历用户扫描目录（跳过隐藏文件与SKIP_PATTERNS匹配的路径，见 utils.py），随后_partition_scan_paths()把所有文件按(目录, 小写基名)分组——例如IMG_001.jpg、IMG_001.CR2、IMG_001.xmp会被归为同一组，元数据文件（XMP 等）则被单独暂存，等待其所属照片先创建；
• Phase 2（排队处理）：每个文件组通过handle_file_group()作为一个整体排队（file_handlers.py），为每组创建一条Photo 记录并挂接全部文件变体（RAW、JPEG、视频、sidecar），从根上杜绝了 RAW 与 JPEG 被并发处理成两条照片记录的问题。

扫描派发完成后，还会自动追加一系列后续任务（_queue_followup_jobs()）：

1. scan_missing_photos：全量扫描或扫描默认目录时，检查磁盘上已不存在的照片（触发"缺失照片"清理）；
2. repair_ungrouped_file_variants：修复历史扫描中因竞态未能归组的文件变体；
3. generate_tags（受FEATURE_SCENE_CLASSIFICATION控制）：按场景生成 AI 标签；
4. add_geolocation（受FEATURE_REVERSE_GEOCODING控制）：GPS 坐标反查地名；
5. 一条 django-q 链：先batch_calculate_clip_embedding计算 CLIP 向量（语义搜索依赖），随后scan_faces（受FEATURE_FACE_DETECTION控制）做人脸检测——注释明确说明人脸任务必须先等 embedding 生成完毕，这正是用Chain串行的原因。

此外扫描结束后还会执行backfill_missing_aspect_ratios()修复有缩略图但缺少宽高比的照片（网格视图过滤条件thumbnail__aspect_ratio__isnull=False会让这类照片在 UI 里"隐形"）。扫描进度会写入LongRunningJob并呈现在任务系统中，缩略图生成被优先调度，让照片尽快出现在界面上。

Nextcloud 用户：为云库单独建立定时扫描

manage.py scan默认只扫描本地扫描目录。如果你的实例启用了 Nextcloud 集成（管理员在 Site Settings 打开Enable Nextcloud integration开关，或首次启动前在librephotos.env中设nextcloudEnabled=true），需要在命令行扫描 Nextcloud 库时使用：

sudo docker exec --user root backend python3 manage.py scan -n

-n会遍历所有配置了nextcloud_scan_directory的用户，从 Nextcloud 下载并扫描照片（文件先复制到本地nextcloud_media/<username>/再处理）；未配置扫描目录的用户会被跳过并打印提示，单个用户失败也不会中断整体（异常被捕获后打印 traceback 继续下一个）。

:::note 因为-f、-s、-n互斥，Nextcloud 扫描不能与全量重扫或指定文件扫描组合。官方文档明确建议：把scan -n单独放进 cron，与本地扫描任务分开调度。 :::

用 cron 实现"每天自动扫描"

把manage.py scan交给 cron 定时执行即可实现全库自动扫描。官方文档给出的示例是每天凌晨 3 点执行一次：

# Every day at 3 AM 0 3 * * * sudo docker exec --user root backend python3 manage.py scan >/dev/null 2>&1

几点实用的运维建议（结合仓库行为）：

• 因为是增量扫描，每天执行的成本很低——没有新文件时几乎不产生处理任务；scan_jobs.py中"如果没有任何文件需要处理，进度目标与当前进度均为 0，任务立即标记完成"的分支保证了空扫秒级结束；
• 把输出重定向到/dev/null避免 cron 邮件被刷屏，排查问题时再临时去掉重定向查看输出；
• 如果想每天全量重扫（代价高，一般不建议），把命令换成scan -f；
• 若本地扫描与 Nextcloud 扫描并存，为scan -n单独建一条 cron 条目；
• 需要避开高峰期、或机器资源紧张时，可结合环境变量文档中的workerConcurrency与FEATURE_*开关调节扫描负载——扫描消耗几乎全部来自后台 worker，控制 worker 数量比直接cpus:限流更有效。

常见问题与排查思路

• 手动改了照片文件的 EXIF/XMP，增量扫描不更新？按上述判定逻辑，sidecar 或照片自身的mtime晚于上次完成扫描即会重新处理；若确认 mtime 未变化，请用scan -f强制重扫。
• 新增照片没有出现在界面？优先确认扫描任务在任务系统中是否正常完成、是否生成了缩略图（宽高比缺失会导致网格视图不显示）；同时检查SKIP_PATTERNS站点配置是否误匹配了目录名。
• 容器名不是backend？参考环境变量文档直接编辑docker-compose.yml的container_name，随后用新名字执行docker exec。
• 想看扫描日志？后端日志写入BASE_LOGS目录（默认/logs/）下的ownphotos.log，也可在 Admin Area 的 Server Logs 面板直接查看与下载。

综上，LibrePhotos 的自动扫描是一套"命令入口极简、底层逻辑严谨"的机制：scan.py负责解析三种模式与多用户分发，scan_jobs.py负责两阶段分组、增量判定与后续任务编排，utils.py负责遍历过滤与进度记录。配合一条 cron 条目，即可让照片库在无人值守下持续保持最新。

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