docs(deploy): BFF 手动重启 venv 绝对路径陷阱(2026-09-15 实测)

根因:venv 在部署根 install/venv,BFF 必须 cd sdk 起 app.main:app——
cd sdk 后相对路径 venv/bin/python 解析成不存在的
install/sdk/venv/bin/python(setsid failed to execute,端口静默 DOWN)。
修正 5f 示例命令(cd 前解析绝对路径)并补老进程 socket 失效场景。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/DEPLOY_FLOW.md

@@ -372,15 +372,23 @@ VSTORE_EMBED_MODEL=bge-m3:567m
 ### 5f. 部署陷阱：BFF 重启必须手动 kill（start_all 不替换在跑进程）
 
 **start_all.sh 不杀已运行的 BFF**：8090 被旧进程占住时，脚本内 uvicorn 新进程因端口
-占用静默退出，自检看到的仍是旧进程（新 env 不生效）。三步：
+占用静默退出，自检看到的仍是旧进程（新 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 注入
+pgrep -f "uvicorn app.main:app" | xargs kill     # 1. 杀旧 BFF（杀不掉用 kill -9；老进程可能活着但 socket 已失效，ss 看不到监听）
+cd /srv/plantai/install && set -a && . sdk/.env && set +a   # 2. 先回部署根 source env
+( cd sdk && setsid /srv/plantai/install/venv/bin/python -m uvicorn app.main:app \
+  --host 127.0.0.1 --port 8090 > /tmp/plantai-sdk.log 2>&1 < /dev/null & ) && disown -a
+# 3. 验证：ss 与 health 都要查（不能只看进程）
+ss -tln | grep ':8090 ' && curl -s http://127.0.0.1:8090/api/health
 ```
 
+**venv 路径陷阱（2026-09-15 实测）**：venv 在部署根 `/srv/plantai/install/venv`，而 BFF 必须
+`cd sdk` 才能找到 `app.main:app`——**必须在 `cd sdk` 之前把 python 解析成绝对路径**
+（或 `../venv/bin/python`），否则 `cd sdk && venv/bin/python` 解析成不存在的
+`install/sdk/venv/bin/python`（`setsid: failed to execute venv/bin/python: No such file or directory`，
+错误在 /tmp/plantai-sdk.log，端口静默 DOWN）。start_all 模板与此处均已按此纪律修正。
+
 ### 5g. r4 部署清单（2026-09-12，六项缺陷修复轮）
 
 1. **QA 双域相关性阈值**（qa/env/prod.env，可选；不设则用代码默认值）：

docs/DEPLOY_SKILL.md

@@ -1,8 +1,8 @@
 # PlantAI-rag-new 打包部署 Skill(175 构建机 → 176 生产)
 
 > 本文件是 Claude Code skill 形态的部署方法(与 DEPLOY_FLOW.md 流程互补,侧重 agent 自动执行)。
-> 生成于 2026-09-12;2026-09-14 增补部署变体(换机/无生信/自定义库路径)与提示词示例、
-> **环境镜像全量同步原则(§7.4)**。skill 源文件:本地 ~/.claude/skills/plantai-deploy/SKILL.md。
+> 生成于 2026-09-12;2026-09-14 增补部署变体与提示词示例、环境镜像全量同步原则(§7.4);
+> 2026-09-15 增补 BFF 手动重启 venv 绝对路径陷阱(§4)。skill 源文件:本地 ~/.claude/skills/plantai-deploy/SKILL.md。
 
 ## 0. 前置事实(agent 必读,勿想当然)
 
@@ -82,6 +82,16 @@ bash /srv/plantai/install/vstore_restart.sh              # vstore 幂等重启(
 bash /srv/plantai/bioflow/bioflow_service/restart.sh     # 生信(独立树,不在 install 内)
 ```
 
+**BFF 手动重启的 venv 路径陷阱(2026-09-15 实测)**:venv 在部署根 `/srv/plantai/install/venv`,而 BFF 必须 `cd sdk` 才能找到 `app.main:app`——**必须在 `cd sdk` 之前把 python 解析成绝对路径**(或 `../venv/bin/python`),否则 `cd sdk && venv/bin/python` 会解析成不存在的 `install/sdk/venv/bin/python`(`setsid: failed to execute venv/bin/python: No such file or directory`,且该错误在 /tmp/plantai-sdk.log 里,端口静默 DOWN):
+
+```bash
+cd /srv/plantai/install && set -a && . sdk/.env && set +a && \
+( cd sdk && setsid /srv/plantai/install/venv/bin/python -m uvicorn app.main:app \
+  --host 127.0.0.1 --port 8090 > /tmp/plantai-sdk.log 2>&1 < /dev/null & ) && disown -a
+```
+
+另:老 BFF 可能「进程活着但 socket 已失效」(ss 无 8090 监听、curl 空响应),SIGTERM 杀不掉时用 `kill -9`;重起后验证 `ss -tln | grep ':8090 '` 与 `/api/health` 两者,不能只看进程。
+
 **start_all 编排行为**(2026-09-12 起):ollama → QA/methodology/legacy(已跑则跳过)→ vstore → **探测 install 同级 bioflow/ 树,存在则启动/重启生信 8098**(不存在静默跳过)→ BFF。BFF 段有 `disown -a`,脚本正常退出不会卡。
 
 ## 5. 部署后质检(逐条核对)