docs(deploy): DEPLOY_FLOW 增补 §5e figures 本地图片源/§5f BFF 重启陷阱/§5g r4 部署清单

docs/DEPLOY_FLOW.md

@@ -334,6 +334,60 @@ VSTORE_EMBED_MODEL=bge-m3:567m
 - 短句（12 字）单次嵌入 4.1s；780 字长文本 1.0s（2026-09-10 实测，模型常驻后）；
 - 单篇文档全量嵌入（多 chunk 累计）约 52s 属历史实测值——功能正常，纯性能差距，无 GPU 机器属预期。
 
+### 5e. 论文图片本地源部署（figures 双源，2026-09-11 起部署必做）
+
+> BFF 答案配图走双源：本地 MinerU 图片优先，PMC 外网兜底。本地源三个条件缺一
+> 即**静默降级**为纯 PMC（无报错、无日志，唯一症状是配图变少或全走外网）。
+
+1. **env 两键**（sdk/.env，与 BFF 同 env，BFF 重启后生效）：
+
+   ```bash
+   PLANTAI_FIGURES_MINERU_ROOT=/srv/plantai/data/evaluation/methodology_upload_jobs
+   PLANTAI_FIGURES_REGISTRY=/srv/plantai/data/knowledge_base/paper_metadata_registry_v1_20260717/paper_metadata_registry_full.jsonl
+   ```
+
+2. **registry 文件传输**：源机 `knowledge_base/paper_metadata_registry_v1_20260717/
+   paper_metadata_registry_full.jsonl`（16.9MB）经 p2p 传到目标机上述路径；该文件
+   是 pmcid→paper_id 映射，缺失时本地索引即使有图也映射不出 PMCID。
+3. **BFF 重启**：必须手动 kill 旧 BFF（见 §5f 陷阱）。
+
+**验证**：用 /tmp 假任务目录受控测试——`demo_job/mineru/paper/txt/*_content_list.json`
+（type=image 条目）+ `methodology_papers.csv`（paper_id 取 registry 内带 pmcid 的），
+加载 figures 模块 `_build_local_index()` 应产出 `source=local` 条目；或部署后真实上传
+一篇 registry 内论文后提问验证。
+
+**已知限制（2026-09-11 实测）**：本地图片只对「paper_id 在 registry 中」的任务命中；
+历史 demo_paper/e2e_check 测试任务不产生本地图片索引。
+
+### 5f. 部署陷阱：BFF 重启必须手动 kill（start_all 不替换在跑进程）
+
+**start_all.sh 不杀已运行的 BFF**：8090 被旧进程占住时，脚本内 uvicorn 新进程因端口
+占用静默退出，自检看到的仍是旧进程（新 env 不生效）。三步：
+
+```bash
+pgrep -f "uvicorn app.main:app" | xargs kill     # 1. 杀旧 BFF
+cd install/sdk && set -a && . .env && set +a     # 2. source env
+setsid venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8090 > /tmp/plantai-sdk.log 2>&1 < /dev/null &
+tr "\0" "\n" < /proc/$(pgrep -f "port 8090" | head -1)/environ | grep FIGURES   # 3. 验证新 env 注入
+```
+
+### 5g. r4 部署清单（2026-09-12，六项缺陷修复轮）
+
+1. **QA 双域相关性阈值**（qa/env/prod.env，可选；不设则用代码默认值）：
+
+   ```bash
+   QA_MIN_VECTOR_SCORE=0.45   # 检索模式向量域（Qdrant score_threshold 同源）
+   QA_MIN_SOURCE_SCORE=0.25   # chat 模式最终域（rerank 后过滤）
+   ```
+
+2. **MinerU 依赖 accelerate**：目标机 mineru 环境需 `pip install accelerate`——缺失
+   症状为启动期失败「requires accelerate」（r4 的自动重试会报中文可读错误但不会自愈）。
+3. **figures 两键 + registry**：见 §5e。
+4. **vstore 内容去重**：vault.add 按 SHA256 覆盖旧 doc，无需 env；存量重复数据如需清理
+   走 rebuild-index/rebuild-chunks 端点。
+5. **r4 前端 dist**：ui/dist 重构建（含 intent 词典「总结/概括/归纳」、KgPane 空态提示、
+   SourceRow 标题 fallback、DocPane 状态机修复）。
+
 ## 6. 部署后完整质检（agent 逐条执行并记录结果，全过才算部署成功）
 
 ```bash
@@ -477,4 +531,5 @@ NEO4J_URI=bolt://127.0.0.1:19888 NEO4J_PASSWORD='<密码>' bash deploy/qa-db/cre
 4. **构建机与目标机若为同一台机器**（内网 192.168.0.175 现状），部署就是替换现有 `plantai-rag-new-deploy-unified/` 部署树；执行前先备份、执行后按 §6 全量质检。
 5. 本手册基于 2026-09-08 服务器实测编写；如工具链或目录结构有变，先对照仓库实际脚本修正本手册再执行。
 6. **当前生产服务器（192.168.0.175）仍是 0.0.0.0:8090 直连形态，尚未执行 §5b 的 nginx 迁移**——启动脚本默认值已改为 127.0.0.1，但现网进程仍是旧绑定；迁移时按 §5b 顺序执行（先 nginx 后改绑），不要直接无参重启 bff_restart.sh 以免客户访问断档。
+8. **start_all.sh 不会替换在跑的 BFF**（2026-09-11 实测）：BFF 更新 env/代码后必须手动 kill + 重启，详见 §5f。
 7. **175 上 QA 数据库 docker 容器（27333/19788）为其他项目共享服务，不随 PlantAI 部署流程管理**；PlantAI-rag-new 一律走裸进程（§5.0/5.0b）；遗留库（26333/18788）现网无引用，清理需用户单独命令。