LibrePhotos 2023 年 7 月开发进展解读：Django-Q2 任务队列迁移与面部检测/聚类参数

LibrePhotos 2023 年 7 月开发进展解读：Django-Q2 任务队列迁移与面部检测/聚类参数

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

本文基于 LibrePhotos 官方开发周报（apps/docs/blog/2023-08-01-2023w31.md）整理，围绕该版本两个核心架构变更——将后台任务队列从 Redis/RQ 迁移至 Django-Q2、为面部检测与聚类新增五项可调参数——结合当前仓库源码进行纵深解析，并汇总前端交互优化与关键问题修复。读者读完可掌握 LibrePhotos 后台任务体系的实际运行机制、面部识别参数的含义与调优入口，以及该版本前后端改动在源码中的对应落点。

一、背景：2023 年 7 月的开发主线

2023 年 7 月，LibrePhotos 发布了一轮以架构稳健性和面部识别可调性为核心的更新（对应周报标题 "Development: 2023 - July"，slug 为2023w31）。周报将其归纳为四条主线：

• 🚀弃用 Redis 与 RQ，迁移至 Django-Q2：任务队列将被真正持久化，且未来支持队列修改与原生 cron 任务；
• 🚀面部检测与聚类新增五项设置：用于让面部识别更好地适配用户自己的照片数据集；
• 🚀上传照片扫描完成后自动触发；
• ✨前端 PhotoListView 优先加载顶部群组、photoDetails 重构为 RTK 数据流。

此外还有全量依赖升级、社区翻译扩充，以及视频播放、封面、滚动布局、Nextcloud 导入、人物缩略图、长任务启动、JXL EXIF 读取等一系列修复。

需要说明的是，该周报属于发布记录性质的简短文档，因此本文以其中两项最具技术深度的变更（任务队列迁移、面部参数）为主体展开，其余改动作为补充小节呈现。

二、任务队列架构：从 Redis/RQ 到 Django-Q2

2.1 迁移动机：队列需要"被记住"

周报明确指出迁移 Django-Q2 的核心收益："the queue will actually be remembered"——任务队列将真正被记住/持久化。在旧架构（Redis + django-rq）下，任务队列存放在内存型存储中，进程重启即可能丢失；而 Django-Q2 采用ORM Broker（即直接使用数据库表作为任务存储），任务提交后先落库，再由 worker 拉取执行，因此任务不再因缓存失效或进程重启而丢失。周报还预告了两个后续能力：队列可被修改，以及原生支持 cron 定时任务。

2.2 源码中的实际落点

当前仓库已将 Django-Q2 全面铺开，任务提交统一走django_q.tasks的AsyncTask、Chain与scheduleAPI：

• apps/backend/api/all_tasks.py 是任务定义中心，其中使用AsyncTask提交 zip 清理等任务，并用schedule("api.all_tasks.delete_zip_file", filename, next_run=execution_time)实现延迟调度；
• apps/backend/api/directory_watcher/scan_jobs.py 中的扫描编排大量使用AsyncTask与Chain：例如第 347/365/372/374 行分别以AsyncTask(...).run()提交缩略图、缺失照片扫描、标签生成、地理信息标注等任务，第 377 行通过Chain串联扫描流水线，第 148 行还使用count_group统计任务组完成进度；
• apps/backend/api/directory_watcher/processing_jobs.py 中，标签生成（generate_tag_job）、OCR（generate_ocr_job）、地理编码（geolocation_job）等后处理任务均通过AsyncTask(...).run()异步派发，worker 内执行时对调用方不阻塞；
• apps/backend/api/face_classify.py 中的人脸训练任务同样通过AsyncTask(train_faces, user, train_job_id).run()提交；
• 后台管理入口 apps/backend/api/admin.py 也直接引用了django_q.tasks.AsyncTask。

由此可以推断，Django-Q2 已成为整个 LibrePhotos 后台任务体系的统一底座，从扫描、后处理到人脸训练全部经由同一套队列机制调度。

2.3 集群配置与 worker 并发控制

Django-Q2 的 worker 集群在 apps/backend/librephotos/settings/production.py 中配置，关键配置项如下：

Q_CLUSTER = { "name": "DjangORM", "queue_limit": 50, # 队列中最多容纳的任务数 "recycle": 50, # worker 处理满 50 个任务后回收重启 "timeout": 10000000, # 单任务超时（毫秒） "retry": 20000000, # 任务重试间隔上限（毫秒） "orm": "default", # 使用 ORM（数据库）作为 broker "max_rss": 300000, # worker 内存上限（KB），超出即重启 "poll": 1, # 轮询间隔（秒） }

其中"orm": "default"正是"队列会被记住"的机制来源——任务直接写入数据库而非内存缓存。worker 数量默认回落到 CPU 核心数，但源码注释明确指出：当容器被 compose 的cpus:限制时，cpu_count()报告的仍是宿主机的核数，导致线程池过宽、资源受限反而饿死任务。因此生产配置支持用环境变量显式收紧：

if os.environ.get("WORKER_CONCURRENCY"): Q_CLUSTER["workers"] = int(os.environ["WORKER_CONCURRENCY"])

从源码结构看，WORKER_CONCURRENCY是实际降低 LibrePhotos CPU 与内存占用的推荐手段；此外 apps/backend/api/views/jobs.py 中也有"受Q_CLUSTER["queue_limit"]（默认 50）约束"的说明，任务提交侧会主动检查队列水位，避免无限堆积。

在运行层面，Django-Q2 worker 通过qcluster命令启动（见 apps/backend/CLAUDE.md 中 "Background Jobs (django-q2): Runs automatically viaqclustercommand"），并在 apps/backend/README.md 中作为 "Task Queue: Django-Q2" 被列为后端核心组件。数据库侧的 cron 调度能力也已落地：start_cleaning_service、start_job_cleanup_service等管理命令（apps/backend/api/management/commands/start_cleaning_service.py）直接使用django_q.models.Schedule与schedule()注册周期性任务，印证了周报预告的"原生 cron 任务"能力。

小结：迁移到 Django-Q2 让任务队列从"易失的内存缓存"升级为"持久化的数据库记录"，配合Schedule原生定时能力，LibrePhotos 的后台任务体系在可靠性、可观测性与可扩展性上都有了实质提升。

三、面部检测与聚类：五项新增可调参数

3.1 参数存在的意义

周报原文表示新增了五个可调设置，让面部识别"better fit your dataset"（更好地适配你的数据集），并希望更多用户尝试不同取值以帮助项目方确定更优默认值。这反映了一个工程事实：面部检测与聚类的效果高度依赖照片集的拍摄场景、清晰度与人脸分布，不存在万能参数。

3.2 源码中的对应字段

这五个参数在 apps/backend/api/models/user.py 的用户模型上以默认值形式存在：

min_cluster_size = models.IntegerField(default=0) # 聚类最小簇规模 confidence_unknown_face = models.FloatField(default=0.5) # 未知人脸置信度阈值 min_samples = models.IntegerField(default=1) # 聚类最少样本数 cluster_selection_epsilon = models.FloatField(default=0.05) # 聚类选择 epsilon

结合仓库中的人脸服务实现可以推断其作用方向：

• min_samples/cluster_selection_epsilon：直接对应 DBSCAN 密度聚类的两个核心参数。min_samples决定一个簇至少需要多少人脸样本（default=1，值越大簇越"挑剔"）；cluster_selection_epsilon是聚类选择时的邻域半径（default=0.05，值越小人脸划分越严格、簇越多）。二者共同决定同一人物的多张人脸能否被归并成一个人；
• min_cluster_size：过滤过小的簇，避免把噪声或误检的零星人脸当作一个"人物"；
• confidence_unknown_face：判断一张脸是否应标记为"未知"的置信度阈值（default=0.5），阈值越高越保守；
• 第五项：与检测尺度相关。周报提到的检测类参数在历史版本中对应image_scale等缩放/检测设置，而当前版本的人脸识别模型选择已升级为站点级配置：FACE_RECOGNITION_MODEL通过 Constance 数据库后端动态管理（见 apps/backend/api/migrations/0125_add_default_face_recognition_model.py，默认值为"buffalo_sc"），并在 apps/backend/api/face_recognition.py 与 apps/backend/api/ml_models.py 中按模型名分发调用。

上述数值型参数均以用户维度存储（User模型字段），意味着不同用户可以针对自己的照片集单独调优，互不影响；而识别模型选择则是站点级（site-wide）设置，由管理员统一控制。

3.3 调优建议与使用方式

• 参数入口：用户级参数在 Web 前端"设置"页面的面部识别区域进行配置（对应 apps/backend/api/views/faces.py 提供的接口与 apps/backend/api/serializers/user.py 的序列化层）；站点级FACE_RECOGNITION_MODEL则在管理后台 Site Settings 中调整；
• 调优路径：当"一个人被拆成多个人"时，可尝试增大min_samples并减小cluster_selection_epsilon，让人脸归并更宽松；当"不同人混入同一个人"时，则反向收紧；
• 事后修复：周报同期收集的 issue #919"错误分配时从照片移除人脸"、#921"允许一张脸归属多个人的可能性"反映了社区对误检修正流程的诉求，配合这些参数可减少需要手动修正的样本量；
• 效果验证：调整参数后，在"人物"页面重新触发人脸训练任务（见 apps/backend/api/face_classify.py 的train_faces任务），观察聚类结果变化。周报同时承认 "Face training is ineffective"（issue #879）是当时已知痛点，参数调优正是缓解该问题的社区反馈渠道。

四、配套改动：前端交互与周边修复

4.1 前端改动

• PhotoListView 优先加载顶部组：照片列表按日期分组展示时，先渲染顶部最新组、再异步补全历史组，改善大库的初始渲染体验；
• photoDetails 重构为 RTK：照片详情的数据获取迁移到 Redux Toolkit 数据流，与项目前后端 API 客户端架构（apps/frontend/src/api_client）保持一致，便于状态管理与缓存控制；
• 移动端与布局修复：修复滚动到底部出现空白与失效页、移动端相册对齐错乱、Nextcloud 导入失败等问题。

4.2 后端修复

• 人物缩略图修复：涉及 apps/backend/api/thumbnails.py 对应的人物封面生成逻辑；
• 长任务不启动修复：与 Django-Q2 迁移直接相关，印证了队列迁移初期"任务持久化 + worker 正常消费"的必要性；
• JXL 文件 EXIF 读取修复：保证 JPEG XL 格式照片的元数据（拍摄时间、定位等，见 apps/backend/api/date_time_extractor.py）能被正确解析，避免日期分组与时间线错乱。

4.3 依赖与翻译

• 后端全量升级依赖，前端亦升级大量依赖，为后续功能（如 apps/frontend/package.json 所管理的 React/Vite 技术栈）打好版本基础；
• 社区贡献了多项新增与改进翻译，覆盖 apps/frontend/src/locales 下的多语言文件。

五、同期 Issue 观察：社区反馈驱动的路线图

周报列出的新 Issue 中，与上述两项架构变更直接相关的有：

这些 issue 表明：队列的可靠性（#904、#972）与人脸识别的可用性（#879、#919、#921）正是该阶段社区最关心的两个方向，与本次发布的两大主题完全吻合。

六、延伸阅读

• 任务队列架构说明：apps/backend/CLAUDE.md（"Background Jobs (django-q2)" 一节）
• 后端任务定义清单：apps/backend/api/all_tasks.py
• 扫描编排与任务链：apps/backend/api/directory_watcher/scan_jobs.py
• 面部识别服务：apps/backend/api/face_recognition.py、apps/backend/api/face_classify.py
• 用户级面部参数模型：apps/backend/api/models/user.py
• 站点级模型选择迁移：apps/backend/api/migrations/0125_add_default_face_recognition_model.py
• 前端照片列表与详情数据流：apps/frontend/src/routes/_protected、apps/frontend/src/api_client

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