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三者不可同时使用参数全称行为适用场景无参数—增量扫描仅处理自上次成功完成的扫描以来新增或被修改的文件日常定时扫描默认推荐-f--full-scan强制全量重新处理每一个文件更换了 EXIF/标签/人脸等处理逻辑后需要重建索引、或怀疑增量判定漏文件-s--scan-files只扫描指定的一批文件后跟空格分隔的文件路径列表单独修复个别照片不触发全库扫描-n--nextcloud改为扫描已连接的 Nextcloud 库见下文专节接入 Nextcloud 的用户例如# 强制全量重扫 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.jpgscan.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()取该用户最近一条finishedTrue且类型为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_ordersidecar 元数据文件被修改同样会触发该组照片重新处理这是编辑 EXIF/标签后能通过增量扫描刷新的关键机制若不存在已完成的历史扫描记录首次扫描则视为全量处理。为了在大图库上提速scan_jobs.py 还引入了按批默认 10000 个文件组一批查询已知路径的优化_select_groups_to_process()把每个文件一次数据库 round-trip降为每批一次files__path__in查询同时控制常驻内存只占一个批次避免加载全部已知路径导致的 RAM 峰值。扫描到底做了什么两阶段架构与后续任务链理解了增量判定后再看扫描任务的完整流程。scan_photos()scan_jobs.py采用两阶段扫描架构专门用于规避 RAWJPEG 并发分组时的竞态条件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()scan_missing_photos全量扫描或扫描默认目录时检查磁盘上已不存在的照片触发缺失照片清理repair_ungrouped_file_variants修复历史扫描中因竞态未能归组的文件变体generate_tags受FEATURE_SCENE_CLASSIFICATION控制按场景生成 AI 标签add_geolocation受FEATURE_REVERSE_GEOCODING控制GPS 坐标反查地名一条 django-q 链先batch_calculate_clip_embedding计算 CLIP 向量语义搜索依赖随后scan_faces受FEATURE_FACE_DETECTION控制做人脸检测——注释明确说明人脸任务必须先等 embedding 生成完毕这正是用Chain串行的原因。此外扫描结束后还会执行backfill_missing_aspect_ratios()修复有缩略图但缺少宽高比的照片网格视图过滤条件thumbnail__aspect_ratio__isnullFalse会让这类照片在 UI 里隐形。扫描进度会写入LongRunningJob并呈现在任务系统中缩略图生成被优先调度让照片尽快出现在界面上。Nextcloud 用户为云库单独建立定时扫描manage.py scan默认只扫描本地扫描目录。如果你的实例启用了 Nextcloud 集成管理员在 Site Settings 打开Enable Nextcloud integration开关或首次启动前在librephotos.env中设nextcloudEnabledtrue需要在命令行扫描 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 21几点实用的运维建议结合仓库行为因为是增量扫描每天执行的成本很低——没有新文件时几乎不产生处理任务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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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三者不可同时使用参数全称行为适用场景无参数—增量扫描仅处理自上次成功完成的扫描以来新增或被修改的文件日常定时扫描默认推荐-f--full-scan强制全量重新处理每一个文件更换了 EXIF/标签/人脸等处理逻辑后需要重建索引、或怀疑增量判定漏文件-s--scan-files只扫描指定的一批文件后跟空格分隔的文件路径列表单独修复个别照片不触发全库扫描-n--nextcloud改为扫描已连接的 Nextcloud 库见下文专节接入 Nextcloud 的用户例如# 强制全量重扫 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.jpgscan.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()取该用户最近一条finishedTrue且类型为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_ordersidecar 元数据文件被修改同样会触发该组照片重新处理这是编辑 EXIF/标签后能通过增量扫描刷新的关键机制若不存在已完成的历史扫描记录首次扫描则视为全量处理。为了在大图库上提速scan_jobs.py 还引入了按批默认 10000 个文件组一批查询已知路径的优化_select_groups_to_process()把每个文件一次数据库 round-trip降为每批一次files__path__in查询同时控制常驻内存只占一个批次避免加载全部已知路径导致的 RAM 峰值。扫描到底做了什么两阶段架构与后续任务链理解了增量判定后再看扫描任务的完整流程。scan_photos()scan_jobs.py采用两阶段扫描架构专门用于规避 RAWJPEG 并发分组时的竞态条件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()scan_missing_photos全量扫描或扫描默认目录时检查磁盘上已不存在的照片触发缺失照片清理repair_ungrouped_file_variants修复历史扫描中因竞态未能归组的文件变体generate_tags受FEATURE_SCENE_CLASSIFICATION控制按场景生成 AI 标签add_geolocation受FEATURE_REVERSE_GEOCODING控制GPS 坐标反查地名一条 django-q 链先batch_calculate_clip_embedding计算 CLIP 向量语义搜索依赖随后scan_faces受FEATURE_FACE_DETECTION控制做人脸检测——注释明确说明人脸任务必须先等 embedding 生成完毕这正是用Chain串行的原因。此外扫描结束后还会执行backfill_missing_aspect_ratios()修复有缩略图但缺少宽高比的照片网格视图过滤条件thumbnail__aspect_ratio__isnullFalse会让这类照片在 UI 里隐形。扫描进度会写入LongRunningJob并呈现在任务系统中缩略图生成被优先调度让照片尽快出现在界面上。Nextcloud 用户为云库单独建立定时扫描manage.py scan默认只扫描本地扫描目录。如果你的实例启用了 Nextcloud 集成管理员在 Site Settings 打开Enable Nextcloud integration开关或首次启动前在librephotos.env中设nextcloudEnabledtrue需要在命令行扫描 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 21几点实用的运维建议结合仓库行为因为是增量扫描每天执行的成本很低——没有新文件时几乎不产生处理任务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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考