cfc/docs/deployment/report-parse-langgraph-env.md

报告解析服务部署依赖（LangGraph + 共享 uploads 卷）

任务：T29-B3-5（P2-8 环境依赖补强） 适用：健康报告「代传」链路（/api/health/report/proxy-parse → LangGraph /api/v1/report/parse）及 非代传两阶段链路（/report/upload + /report/parse）在生产/容器化环境部署时的强制检查项。

背景

Java 后端（Spring Boot，cfc-backend）解析健康报告 PDF 时，优先调用 LangGraph 服务 （cfc-langgraph，FastAPI，端口 9000，生产域名 ai.etotem.com.cn）做结构化解析，失败才回退本地 Java 解析。

• 后端配置：cfc-backend/src/main/resources/application.yml 的 langgraph.base-url （默认 http://localhost:9000，仅开发环境可用）。
• 文件通路：后端先把上传的 PDF 落盘/落 OSS，再经 storageService.getFilePath(fileUrl) 得到本地绝对路径， 传给 LangGraph 的 file_path。LangGraph 容器必须能读到该路径。

强制检查项清单（部署前逐条确认，缺一不可）

1. LANGGRAPH_BASE_URL 环境变量必须显式设置，禁止使用默认 localhost

# application.yml（生产必须覆盖默认值）
langgraph:
  base-url: ${LANGGRAPH_BASE_URL:http://localhost:9000}

环境	要求
开发	可保持默认 http://localhost:9000（需本机已启动 cfc-langgraph）
生产/容器化	必须设置 LANGGRAPH_BASE_URL=https://ai.etotem.com.cn（或内网 LangGraph 地址），否则后端会尝试连容器内 localhost:9000 而失败，报告解析退化为本地 Java 解析（功能可用但解析质量下降）

检查命令：确认部署清单/启动脚本中已注入 LANGGRAPH_BASE_URL，且值与 LangGraph 服务实际地址一致。

2. uploads 目录必须与 LangGraph 容器共享同一 volume

后端 upload.base-dir（默认 /data/cfc-uploads）存放上传文件；getFilePath 返回的绝对路径 会被直接作为 LangGraph 请求体 file_path。若 Java 容器与 LangGraph 容器不共享该目录， LangGraph 侧 File(file_path) 不存在 → 解析失败 → 回退本地解析（或整链失败）。

环境	要求
本地非容器	同一主机目录即可，无额外要求
容器化	cfc-backend 与 cfc-langgraph 两个容器必须挂载同一个 host 目录（如 /data/cfc-uploads）到各自容器内相同路径；cfc-backend 的 upload.base-dir 与 LangGraph 读取 file_path 的目录必须是同一目录

检查命令：

# 确认两个容器挂载同一 uploads 卷
docker inspect cfc-backend   # 查看 Mounts → Source/Target
docker inspect cfc-langgraph # 查看 Mounts → Source/Target
# 两者 target（容器内路径）必须一致，且等于 upload.base-dir 解析后的绝对路径

3. python.executable 本地兜底依赖（非容器可跳过）

本地（非容器）环境使用本地 Java 解析兜底时，pdfParseService 不依赖外部脚本；仅异步采集链路 （report.collect）依赖 python 可执行文件。生产容器化环境无需该检查（LangGraph 承担解析）。

环境变量一览（报告解析相关）

变量	默认值	生产必须	说明
LANGGRAPH_BASE_URL	http://localhost:9000	✅	LangGraph 报告解析服务地址（生产 https://ai.etotem.com.cn）
upload.base-dir	/data/cfc-uploads	✅	上传文件根目录，须与 LangGraph 容器共享
storage.type	jdcloud	—	jdcloud（OSS）或 local（本地磁盘）；local 时共享卷要求更严格

验收（部署后自检）

1. 用一份真实募极生物肠道菌群报告 PDF 走 /api/health/report/proxy-parse，响应 parseMethod="langgraph" （而非 "local"）→ 证明 LangGraph 通路可用。
2. 若返回 parseFallback=true（parseMethod="local"），说明 LangGraph 未打通，按本清单第 1/2 项排查。