Resume-Matcher 健康检查修复实战：让 Docker Liveness Probe 停止消耗 LLM 调用配额

Resume-Matcher 健康检查修复实战让 Docker Liveness Probe 停止消耗 LLM 调用配额【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher导读本文深入解析 Resume-Matcher 仓库中一份真实的设计与修复文档——《Health Check Fix — Stop LLM Calls on Docker Liveness Probe》。这份文档记录了一次典型且极具代表性的基础设施优化由于 DockerHEALTHCHECK每 10 秒探测一次GET /api/v1/health而该端点此前会真实调用litellm.acompletion()向 LLM 服务商发起请求导致每天浪费约 8,640 次计费 API 调用。读完本文你将掌握存活探针liveness与就绪探针readiness职责分离的设计思想、Resume-Matcher 后端健康检查端点的具体实现方式、Dockerfile 中HEALTHCHECK的正确配置以及如何用集成测试为这类修复建立回归防线。一、问题剖析为什么HEALTHCHECK会烧掉 LLM 调用配额1.1 Docker 存活探针的触发频率Resume-Matcher 的镜像在 Dockerfile 中声明了如下健康检查# Health check on internal backend port only (independent of host port mapping). HEALTHCHECK --interval10s --timeout10s --start-period30s --retries5 \ CMD curl -f http://127.0.0.1:8000/api/v1/health || exit 1这段配置的含义是参数值说明--interval10s每 10 秒执行一次探针命令--timeout10s单次探针最多等待 10 秒--start-period30s容器启动后 30 秒内不计失败--retries5连续失败 5 次判定容器为 unhealthy探针命令curl -f http://127.0.0.1:8000/api/v1/health后端内部端口 8000与宿主端口映射无关关键点是--interval10s每分钟 6 次、每小时 360 次、每天8,640 次探针请求。这只是单个容器单天的量如果集群中运行多个副本消耗会成倍放大。1.2 高成本根因探针端点内部发起了真实 LLM 调用在修复之前/api/v1/health的处理函数会调用check_llm_health()。该函数定义在 apps/backend/app/llm.pyasync def check_llm_health( config: LLMConfig | None None, *, include_details: bool False, test_prompt: str | None None, ) - dict[str, Any]: ... model_name get_model_name(config) prompt test_prompt or Hi try: kwargs: dict[str, Any] { model: model_name, messages: [{role: user, content: prompt}], max_tokens: 64, api_key: _effective_api_key(config.provider, config.api_key), api_base: _normalize_api_base(config.provider, config.api_base), timeout: LLM_TIMEOUT_HEALTH_CHECK, } ... response await litellm.acompletion(**kwargs)也就是说每一次 Docker 探针请求都会以max_tokens64的真实请求打到 LiteLLM再转发给配置的 LLM 服务商。按设计文档中的估算在通过 OpenRouter 使用 GPT-5.4 的场景下这笔无意义的开销约为每天 1.5 美元。这既污染了计费账单也增加了服务商的限流压力还让健康检查本身变慢受网络往返与LLM_TIMEOUT_HEALTH_CHECK超时影响。1.3 概念混淆存活探针不该做深度检查DockerHEALTHCHECK的本意是判断进程是否存活、容器是否需要被调度器重启而不是判断业务功能是否完备。把 LLM 连通性这类就绪语义塞进存活探针属于典型的职责混淆存活liveness进程还活着、能响应 HTTP 请求即可必须廉价、快速、无副作用就绪readiness依赖项LLM、数据库是否可用、系统能否对外提供完整服务通常由用户主动触发或业务探针检查。原设计的直接后果是一旦 LLM 服务商故障或 API Key 失效探针会因超时/失败而判定容器 unhealthy进而触发不必要的容器重启即便没有故障也在持续烧钱。二、修复方案liveness 与 readiness 的职责分离2.1 总体思路Approach A: Minimal设计文档选择了最小改动方案Approach AMake/healtha zero-cost liveness check. The LLM connectivity check remains available via/status(user-initiated only).即/health退化为零成本存活探针LLM 连通性检查保留在/status端点由用户前端设置页主动触发。2.2 路由层修改health.py修复后的 apps/backend/app/routers/health.py 实现如下Health check and status endpoints. import logging from fastapi import APIRouter from app.database import db from app.llm import check_llm_health, get_llm_config from app.schemas import HealthResponse, StatusResponse logger logging.getLogger(__name__) router APIRouter(tags[Health]) # Returned for database_stats when the stats query itself fails, so /status can # still respond (degraded) instead of 500-ing. _EMPTY_DB_STATS { total_resumes: 0, total_jobs: 0, total_improvements: 0, has_master_resume: False, } router.get(/health, response_modelHealthResponse) async def health_check() - HealthResponse: Lightweight liveness check for Docker HEALTHCHECK. Does NOT call the LLM provider. Use GET /status for full LLM health. return HealthResponse(statushealthy) router.get(/status, response_modelStatusResponse) async def get_status() - StatusResponse: Get comprehensive application status. llm_configured False llm_healthy False try: config get_llm_config() # ollama / openai_compatible run without a key, matching check_llm_health. llm_configured bool(config.api_key) or config.provider in (ollama, openai_compatible) llm_status await check_llm_health(config) llm_healthy bool(llm_status.get(healthy)) except Exception: logger.exception(Status: LLM health check failed) db_stats: dict dict(_EMPTY_DB_STATS) try: db_stats await db.get_stats() except Exception: logger.exception(Status: database stats failed) has_master_resume bool(db_stats.get(has_master_resume)) return StatusResponse( statusready if llm_healthy and has_master_resume else setup_required, llm_configuredllm_configured, llm_healthyllm_healthy, has_master_resumehas_master_resume, database_statsdb_stats, )对照设计文档的变更清单可以逐一确认落地情况文档要求代码现状/healthhandler 返回HealthResponse(statushealthy)不调用 LLM✅ 函数体仅一行return HealthResponse(statushealthy)文档字符串明确标注 Does NOT call the LLM provider/statushandler 不变仍调用check_llm_health()✅get_status()中通过get_llm_config()check_llm_health(config)完成真实探测check_llm_healthimport 移除保留get_llm_configimport✅ 文件顶部仍导入两者因为/status需要/health不再引用前者2.3 Schema 层修改HealthResponse瘦身设计文档要求从 apps/backend/app/schemas/models.py 的HealthResponse中移除llm: dict[str, Any]字段# Health/Status Models class HealthResponse(BaseModel): Health check response. status: str class StatusResponse(BaseModel): Application status response. status: str llm_configured: bool llm_healthy: bool has_master_resume: bool database_stats: dict[str, Any]HealthResponse现在只保留status: str一个字段响应体固定为{status: healthy}完整的就绪信息LLM 是否配置、是否健康、是否有 Master Resume、数据库统计全部收归StatusResponse。2.4 端点挂载与整体路由两个端点在 apps/backend/app/main.py 处以统一前缀挂载app.include_router(health_router, prefix/api/v1)因此对外暴露路径为GET /api/v1/health—— 存活探针零 LLM 调用GET /api/v1/status—— 完整状态检查含真实 LLM 探测三、/status端的健壮性设计子系统隔离降级虽然文档把重点放在/health的瘦身上但/status本身也蕴含了值得借鉴的设计——每个子系统检查彼此隔离单点失败只降级自己的字段绝不让整个端点 500。从源码可以看到三处防御LLM 检查失败降级get_llm_config()或check_llm_health()抛异常时except Exception捕获后记录日志llm_healthy保持False继续执行后续数据库统计数据库统计失败降级db.get_stats()抛异常时返回_EMPTY_DB_STATS占位值各字段均为 0/False保证/status仍能响应无 Key 的本地 Provider 特判ollama与openai_compatible这类本地/自托管 Provider 通常不需要 API Key因此llm_configured的计算为bool(config.api_key) or config.provider in (ollama, openai_compatible)与check_llm_health内部的 Key 校验逻辑保持一致。最终的状态语义也值得一提status字段只在llm_healthy and has_master_resume同时成立时返回ready否则返回setup_required让前端能据此引导用户完成配置。四、前端消费方为什么修复对StatusCacheProvider零影响设计文档明确列出保持不变的清单其中前端最关键的是StatusCacheProvider及其所有useStatusCache消费者。从源码看前端缓存逻辑位于 apps/frontend/lib/context/status-cache.tsx// Cache duration constants const LLM_HEALTH_CHECK_INTERVAL 30 * 60 * 1000; // 30 minutes const STATUS_STALE_THRESHOLD 5 * 60 * 1000; // 5 minutes for DB stats关键设计点LLM 健康检查刷新周期长达 30 分钟本身就通过前端缓存把/status的调用频率压得很低与后端修复的意图一致数据库统计的过期阈值是 5 分钟区分对待慢变的 LLM 状态与相对频繁变化的简历/职位数量提供refreshStatus()/refreshLlmHealth()显式刷新动作以及incrementResumes/decrementResumes/incrementJobs等乐观计数更新避免每次操作都拉取全量状态。StatusCacheProvider在 apps/frontend/app/(default)/layout.tsx/layout.tsx#L8) 中被挂载为根级 Provider其消费方覆盖 dashboardapps/frontend/app/(default)/dashboard/page.tsx/dashboard/page.tsx#L52)、settingsapps/frontend/app/(default)/settings/page.tsx/settings/page.tsx#L136)、tailorapps/frontend/app/(default)/tailor/page.tsx/tailor/page.tsx#L77)、resumes 详情页与 resume-wizard 页面等。由于这次后端修复只改变/health的响应内容字段未破坏且/status的响应契约完全不变因此前端所有消费者都不需要任何改动——这正是Approach A: Minimal的价值以最小的契约面变更换取最大的成本收益。五、验证与回归防线集成测试如何守护这次修复5.1 官方验证清单设计文档给出的验收标准是GET /health返回{status: healthy}且不发起任何外部调用GET /status仍返回llm_healthy: true/false且执行真实 LLM 检查设置页仍能正确展示 LLM 健康状态。5.2 集成测试源码印证仓库中的 apps/backend/tests/integration/test_health_api.py 正是这份验收标准的自动化形态其中最关键的是这条回归防线patch(app.routers.health.check_llm_health, new_callableAsyncMock) async def test_health_is_independent_of_llm(self, mock_health, client): /health is a liveness probe: it stays healthy even when the LLM is unhealthy, and must NOT call the provider. Readiness lives at /status. Regression guard for the liveness-vs-readiness split — the previous version of this test asserted the deleted /health returns degraded behavior and failed silently because nothing ran the suite. mock_health.return_value {healthy: False, error_code: api_key_missing} async with client: resp await client.get(/api/v1/health) assert resp.status_code 200 assert resp.json()[status] healthy mock_health.assert_not_awaited()这条测试同时断言了三件事即使 LLM 不健康模拟api_key_missing/health依然返回 200 与healthy—— 证明存活与就绪解耦check_llm_health从未被 awaitmock_health.assert_not_awaited()—— 从调用层面杜绝任何 LLM 请求测试注释还记录了历史教训旧版测试断言的是已删除的 /health returns degraded 行为且因无人运行而静默失效新版将其重写为正向断言确保修复不再回退。/status端的测试同样完备覆盖以下场景test_status_readyLLM 健康 有 Master Resume →status readytest_status_setup_required未配置 Key / 无 Master Resume →status setup_requiredtest_status_degrades_when_llm_check_failsLLM 探测抛RuntimeError→ 端点仍返回 200llm_healthyFalse数据库统计照常执行test_status_degrades_when_db_stats_failsDB 统计抛RuntimeError→ 端点仍返回 200LLM 检查照常执行test_status_openai_compatible_is_configured_without_keyopenai_compatible无 Key 时llm_configuredTrue。这套测试矩阵与每个子系统隔离降级的实现一一对应任何一端点行为回归都会被 CI 拦截。5.3 启动脚本中的健康检查配合除了 Docker 镜像内的HEALTHCHECKdocker/start.sh 在容器启动时也会轮询/api/v1/health等待后端就绪for i in {1..30}; do if curl -s http://127.0.0.1:${BACKEND_PORT}/api/v1/health /dev/null 21; then status Backend is ready (PID: $BACKEND_PID) break fi ... done修复前start.sh的健康轮询同样会被迫触发 LLM 调用修复后这一启动就绪探测也变为零成本请求容器启动流程不再依赖 LLM 服务商可用性。六、修复要点速查与扩展思考6.1 变更清单速查文件变更内容apps/backend/app/routers/health.py/health返回HealthResponse(statushealthy)不再调用check_llm_health/status保留真实 LLM 探测apps/backend/app/schemas/models.pyHealthResponse移除llm字段仅保留status: strDockerfileHEALTHCHECK命令与间隔无需改动继续探测/api/v1/healthapps/backend/app/llm.pycheck_llm_health()保持原样仅由/status与前端设置页触发apps/frontend/lib/context/status-cache.tsx零改动仍以 30 分钟缓存间隔消费/status6.2 可以直接复用的工程原则存活探针必须零副作用凡是会被调度器高频调用的端点一律不得携带真实业务请求LLM 调用、外部写入等否则每 10 秒一次的探测就是持续烧钱把深度检查放到用户主动触发或低频缓存的路径上Resume-Matcher 的做法是前端 30 分钟缓存/status 用户可手动刷新既保证功能可见又把调用频率压到可忽略契约最小化变更只改/health的响应结构、不动/status的响应契约前端所有消费者零迁移成本用测试锁死行为边界assert_not_awaited()这类负向断言能精确防止将来某天又有人把 LLM 调用加回存活探针。6.3 适用前提与限制上述成本估算每天约 8,640 次调用、约 1.5 美元/天基于设计文档针对特定模型与路由OpenRouter GPT-5.4的测算实际成本取决于你所配置的 Provider、模型与单价本修复适用于 Resume-Matcher 的 Docker 部署形态若你在本地以uvicorn直接运行参见 docker/start.sh 中的启动命令/api/v1/health同样不再产生 LLM 开销若你的部署依赖/health来感知 LLM 故障例如自建调度器按健康状态伸缩应改用/api/v1/status的llm_healthy字段或自行扩展就绪探针。七、结语这份设计文档的价值远超删几行代码本身它完整示范了一次低成本、高收益的基础设施修复——通过存活探针与就绪检查的职责分离Resume-Matcher 在保持 Docker 健康检查能力、前端状态展示能力与 LLM 连通性诊断能力完全不变的前提下消除了每天数千次的无意义计费调用。文中所有实现细节都可以在仓库的 health.py、models.py、test_health_api.py 与 Dockerfile 中直接验证是一份可迁移、可复现、经得起回归测试检验的工程范本。【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考