LibrePhotos 服务管理改进解析：Django 托管 Sidecar 服务与健康检查看门狗

LibrePhotos 服务管理改进解析：Django 托管 Sidecar 服务与健康检查看门狗

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

2024 年 5 月（2024 W18）发布的 LibrePhotos 开发日志带来了一项关键的后端架构改进：所有机器学习与媒体处理服务（Sidecar）不再由外部进程管理器单独维护，而是随 Django 一起启动，并由一个每分钟执行的cron 看门狗持续监控健康状态、自动拉起异常退出的服务；同时新增了一组用于查看与操控服务的 REST 端点。本文以该版本更新为骨架，结合当前仓库中 services.py 与 services.py 视图 等源码，完整梳理服务管理机制、四个新端点、功能开关与模型下载联动逻辑，帮助你理解并运维这套服务治理体系。

版本更新概览：2024 W18 服务管理改进

原版开发日志的核心内容如下：

• 服务随 Django 启动：此前需要手工启动的 image_similarity、thumbnail、face_recognition、clip_embeddings、image_captioning、exif、tags、ocr 等 Sidecar 服务，现在由 Django 进程统一拉起；
• cron 看门狗：新增一个每分钟运行的定时任务，检测服务是否仍存活，若健康检查失败则自动停止并重启该服务；
• 新增服务管理端点：
  • GET /services/：列出所有服务；
  • GET /services/{id}/：获取指定服务的健康状态；
  • POST /services/{id}/start/：启动指定服务；
  • POST /services/{id}/stop/：停止指定服务；
• 模型下载优化：选择 "none"（不选择模型）时不再下载模型；模型下载与依赖服务之间改为链式联动；
• 前端修复：修复头像更新问题；即使没有图片也始终显示页头；
• 部署更新：Docker 基础镜像升级到 Ubuntu 24.04 并移除构建工具；依赖包与社区翻译字符串批量更新。

其中“模型下载与依赖服务链式联动”“选择 none 不下载模型”两条，与“服务随 Django 启动 + 看门狗”共同构成一个完整的服务生命周期体系，下文逐一展开。

服务目录与特征开关：哪些服务、如何被管理

所有可管理服务在 apps/backend/api/services.py 中以两个字典集中定义：

服务名	端口	对应功能开关
image_similarity	8002	无（核心扫描/检索，始终开启）
thumbnail	8003	无（核心，始终开启）
face_recognition	8005	FEATURE_FACE_DETECTION
clip_embeddings	8006	无（核心，始终开启）
image_captioning	8007	FEATURE_IMAGE_CAPTIONING
exif	8010	无（核心，始终开启）
tags	8011	FEATURE_SCENE_CLASSIFICATION
ocr	8012	站点设置 OCR_MODEL（site setting，而非环境变量）

SERVICE_FEATURE_FLAGS中值为None的服务属于核心扫描/检索链路，默认永远启用；其余服务则受环境变量开关约束。开关的解析逻辑位于 apps/backend/librephotos/settings/production.py：_env_flag()把true/1/yes/on（不区分大小写）视为开启，未设置时默认开启——即升级不改变既有行为，只有显式设置false/0/no/off才会关闭对应功能。

is_service_enabled()（services.py）是判断服务是否应当运行的唯一入口，它的判定顺序是：先检查站点级门（site gate），再检查环境变量开关。特别值得注意的是两点容错设计：

• 若 settings 模块中未定义某开关，getattr(settings, flag, True)返回True，即未知开关不会把原本在运行的服务夺走；
• 数据库尚未就绪、constance 配置读取失败时，_ocr_model_selected()返回True（services.py），保证数据库不可读不会导致服务被误停。

看门狗机制：每分钟的健康巡检与自动重启

看门狗的核心是check_services()（services.py），它遍历SERVICES中的每个服务并依次执行：

1. 若服务已被标记为INCOMPATIBLE_SERVICES（系统不兼容，如缺失必需 CPU 指令集），跳过并记录日志；
2. 若is_service_enabled()判定服务未启用，静默跳过——该函数每分钟运行一次，若每个被跳过的服务都打日志会刷爆日志文件（测试 test_service_feature_flags.py 专门验证了这一点）；
3. 调用is_healthy()探测健康端点，不健康则先stop_service()再start_service()重启。

is_healthy()（services.py）会向http://localhost:{port}/health发起 HTTP 请求，超时配置取自 apps/backend/api/http_timeouts.py，HEALTH_CHECK = (5, 5)（连接超时 5 秒、读取超时 5 秒）。除 HTTP 200 之外，它还检查响应体中的last_request_time时间戳：若该时间戳距今超过 120 秒，说明服务虽活着但已“僵死”（stale），同样判定为不健康并触发重启。任何异常（连接拒绝、超时等）都会被捕获并记录，返回False。

看门狗任务通过 Django Q 的 Schedule 注册。执行python manage.py start_service all（见 apps/backend/api/management/commands/start_service.py）时，除了逐个启动已启用的服务，还会在api.services.check_services调度不存在时注册一个每分钟运行的Schedule.MINUTES任务：

python manage.py start_service all

该命令同时完成了两件事：立即拉起全部可用服务+注册每分钟执行的健康巡检。

对应的自动化测试完整覆盖了看门狗行为（apps/backend/api/tests/ml_services/test_service_feature_flags.py）：所有服务不健康时全部重启；禁用某功能后对应服务既不探测也不重启；看门狗对跳过的服务保持安静；管理员在站点设置中选择 OCR 模型后，无需重启即可在下一次巡检中拉起 ocr 服务。

健康状态判定细节：服务如何报告自身状态

Sidecar 服务各自实现/health端点。以 thumbnail 服务为例（apps/backend/service/thumbnail/main.py）：

@app.route("/health", methods=["GET"]) def health(): return {"status": "OK"}, 200

服务进程本身是独立的 Python 进程，由 Django 通过subprocess.Popen拉起（services.py）：image_similarity运行image_similarity/main.py，其余服务运行service/{service}/main.py。启动时通过_service_environment()（services.py）注入BASE_LOGS与LOG_LEVEL环境变量，使子进程使用与 Django 一致的日志配置；子进程 stdout 被刻意保留，避免把日志文件 fd 传给子进程导致日志轮转后空间无法回收的问题。

停止服务则通过ps aux | grep查找匹配python.*{service}/main.py的 PID 并kill -9（services.py）。此外，启动前还有 CPU 兼容性检查（has_required_cpu_features）：当前SERVICE_CPU_REQUIREMENTS为空字典，但保留了对 ARM 架构（aarch64/arm64/armv7l/armv8）跳过 x86 指令集（AVX/AVX2/SSE4.2/FMA/F16C）检查的逻辑框架，为后续需要特定指令集的 Sidecar 预留了扩展点。

四个新端点：查看与操控服务的 REST API

服务管理端点由ServiceViewSet提供（apps/backend/api/views/services.py），在 apps/backend/librephotos/urls.py 注册为api/services路由。该 ViewSet 的权限为IsAdminUser，即仅管理员可访问。

GET /api/services/ —— 列出所有服务

返回服务名字典（含端口映射），响应形如：

{"services": {"image_similarity": 8002, "thumbnail": 8003, "face_recognition": 8005, "clip_embeddings": 8006, "image_captioning": 8007, "exif": 8010, "tags": 8011, "ocr": 8012}}

GET /api/services/{id}/ —— 查询单个服务健康状态

返回该服务的名称、是否启用、是否健康以及所依赖的功能开关：

{ "service_name": "ocr", "healthy": false, "enabled": false, "feature_flag": null }

注意feature_flag为null表示该服务受站点设置（OCR_MODEL）而非环境变量控制。源码中有一个巧妙设计：被关闭的服务不做健康探测（views/services.py），因为端口上根本没有进程在监听，每次探测都会产生一次连接拒绝与一条日志堆栈，与看门狗跳过未启用服务的理由一致。

POST /api/services/{id}/start/ —— 启动服务

若服务名不存在返回 404；若服务被功能开关禁用，返回 409 Conflict 并附上禁用原因（如FEATURE_FACE_DETECTION is disabled或no model is selected for it in the site settings，见disabled_reason()）；启动成功返回 200，失败返回 500。

POST /api/services/{id}/stop/ —— 停止服务

服务名不存在返回 404；进程不存在或 kill 失败返回 500；成功返回 200。

这四个端点可以直接用 curl 验证（需携带管理员 JWT，认证细节见 docs/docs/user-guide/api-authentication.md）：

curl -H "Authorization: Bearer <token>" http://localhost:8080/api/services/ curl -H "Authorization: Bearer <token>" http://localhost:8080/api/services/ocr/ curl -X POST -H "Authorization: Bearer <token>" http://localhost:8080/api/services/ocr/start/ curl -X POST -H "Authorization: Bearer <token>" http://localhost:8080/api/services/ocr/stop/

模型下载联动：“none”不再下载，下载与依赖链式进行

开发日志中的两条改进与上述服务体系直接相关。

“选择 none 不下载模型”：模型选择逻辑集中在 apps/backend/api/ml_models.py，_is_model_not_selected()（ml_models.py）统一界定“未选择”的语义——OCR 服务的启动门_ocr_model_selected()复用了这一判断（services.py），确保启动门、模型下载、OCR 任务三方对“未选择”的判定永远不会分歧。用户选择none时不再触发对应模型的下载流程，避免浪费带宽与磁盘。

“模型下载与依赖链式联动”：模型下载入口download_models()（ml_models.py）按依赖关系依次处理各模型；download_model()（ml_models.py）负责单个模型下载，包括_download_file()的流式写入临时文件、_verify_checksum()的 SHA-256 校验与_unpack_archive()的解包（ml_models.py）。所谓“链式”，从服务侧看就是：先确保依赖模型就绪，再启动依赖该模型的 Sidecar 服务，且站点级门（OCR）在每次看门狗巡检时被重新读取，因此“管理员在设置里选定模型 → 下一分钟巡检自动拉起 ocr 服务”无需任何重启。

从 Django 启动到持续自愈：整体流程串讲

将以上机制串联起来，一次完整的服务生命周期如下：

1. 部署启动后执行python manage.py start_service all（容器 entrypoint 中完成，见 deploy/docker/backend/entrypoint.sh），按is_service_enabled()逐个拉起启用的 Sidecar，并注册每分钟的api.services.check_services看门狗调度；
2. 每过一分钟，看门狗对所有已启用服务执行健康检查：HTTP 200 且last_request_time距今不超过 120 秒视为健康，否则停止并重启；
3. 管理员通过GET/POST /api/services/{id}/...端点随时查看状态、手动启停（仅限管理员，未启用的服务 start 会被 409 拒绝）；
4. 若某服务依赖的模型在站点设置中被选定，下一次巡检即自动把它拉起，无需重启 Django 进程。

这套“随主进程启动 + 定时自愈 + 显式管理端点”的机制，把原本分散在各容器/进程中的媒体处理服务收敛为 Django 统一治理的对象，配合功能开关的默认开启策略与严格的容错设计（配置缺失不夺权、数据库不可读不停服），为 LibrePhotos 的扫描、人脸、缩略图、OCR、语义检索等能力提供了可靠的服务基座。

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