Skip to content

Fix #20: fail fast in the API entrypoint when production deps are missing - #33

Open
xiaoyao-666-coder wants to merge 2 commits into
zhengdaodeguL:mainfrom
xiaoyao-666-coder:fix/issue-20-compose-fail-fast
Open

xiaoyao-666-coder wants to merge 2 commits into
zhengdaodeguL:mainfrom
xiaoyao-666-coder:fix/issue-20-compose-fail-fast

Conversation

@xiaoyao-666-coder

Copy link
Copy Markdown

问题

主 compose 缺必填外部依赖时,API 容器起来了但 /api/ready 永远不 healthy,于是 UI(depends_on: service_healthy)和网关永远不启动,整站永久不 healthy,且没有任何明确报错。

修复

只做 API 入口 fail-fast,不做 compose ${VAR:?}:

  • backend/docker-entrypoint.sh:新增一个 production-only 的 Python 预检块,放在已有 CIDR 校验之前、ingestion/服务启动之前;缺失时一次性列出所有缺失变量(各附一句原因)+ 指引(补 .env,参考 .env.template,重跑 docker compose up --build -d),exit 1。生产必填:OPENAI_API_KEY、OPENAI_MODEL、REDIS_URL、MILVUS_URI(仅 milvus 后端,缺省即 milvus)、MEDGUIDE_AUTH_DSN(除非显式选 SQLite 认证:MEDGUIDE_AUTH_BACKEND=sqlite + MEDGUIDE_ALLOW_SQLITE_AUTH=true)。
  • 刻意不用 ${VAR:?},三个理由:MILVUS_URI 只在 milvus 后端必填、MEDGUIDE_AUTH_DSN 有 SQLite escape hatch,compose 插值没有条件语法,会误拦合法部署;CI 的 docker compose config --quiet 在无任何环境变量下跑,${VAR:?} 会让它直接失败;入口检查只在生产模式生效,local/offline/test 不受影响。
  • README.md:部署章节加一句话,说明 API 容器启动前会校验上述必填依赖。
  • 刻意不标必填的:OPENAI_BASE_URL(代码里缺省走 api.openai.com,要求它会破坏纯 OpenAI 部署)、MYSQL_DSN(缺了只禁用结构化查询,是设计好的降级)、MEDGUIDE_API_TOKENS(只在 MEDGUIDE_REQUIRE_PROXY_TOKEN 设置时才需要)。

验证

  • 后端:MEDGUIDE_MODE=test python -m pytest -q backend/tests 525 passed(基线 521 + 4 新,test_deployment_contracts.py,真实跑入口脚本、环境从零构造)。
  • 手动实跑入口校验分支(env -i 干净环境):生产模式无任何变量 → exit 1,一次列出全部 5 个缺失变量;只设 OPENAI_API_KEY/OPENAI_MODEL → exit 1,只列剩下的 3 个;依赖齐全 → exit 0;test 模式无配置 → exit 0。
  • docker-compose.yml、demo、local 三个 compose 文件 pyyaml 解析均合法;sh -n 语法检查通过;CI 的 docker compose config --quiet 不受影响。
  • 前端未动。

已知遗留

  • 无 Docker,没法验证 docker compose up 的真实端到端行为(包括“缺依赖时 API 容器立即退出、UI/网关不再永久 unhealthy”的完整链路),需在有 Docker 的环境按 issue 复现步骤确认。
  • README“至少填写”列表里仍有 OPENAI_BASE_URL,但入口校验不要求它(纯 OpenAI 部署不需要);如认为文档应与校验严格一致,需另改 README 措辞。

Closes #20

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[高] 主 compose 不自带 Redis/Milvus/MySQL,必填外部依赖缺配时整站永久不 healthy(待实机验证)

1 participant