# P4 部署清单（TL 执行，逐步核对）

> 纪律：备份先行、只动服务器、不 push git、不碰 QA 树（8091）、生产 BFF 8090 只在最后一步重启。

## 0. 前置确认
- [ ] dev1/dev2/dev3/QA v1.1 全部交付且 TL 审核通过
- [ ] dev1 交付后：TL 统一删除 routers/docgen.py 顶部 _STUB 桩段并核对签名
- [ ] 意图 30 条双跑（后端 pytest + 前端 node）通过

## 1. 备份（不可跳过）
```bash
TS=$(date +%Y%m%d-%H%M); BK=/home/xzq/backups/docgen-$TS; mkdir -p $BK
tar czf $BK/deploy-sdk.tar.gz -C /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified sdk
cp /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified/sdk/data/plantai.db $BK/plantai.db
cp /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified/sdk/.env $BK/env.backup
```

## 2. 全量测试（服务器仓库，venv）
```bash
cd /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new
/home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv/bin/python -m pytest \
  vstore/tests/ sdk/app/services/test_docgen_*.py sdk/app/routers/test_docgen_api.py \
  tooling/scripts/test_docgen_import.py tests/docgen/ -c tests/docgen/pytest.ini -q
```

## 3. BFF 编译 + 替换部署树
```bash
bash tooling/compile/compile_sdk.sh sdk /tmp/sdk-docgen-build /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv/bin/python
rsync -a --delete --exclude data --exclude .env --exclude mock /tmp/sdk-docgen-build/ /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified/sdk/
# 部署树 .env 追加（不覆盖已有）：
#   VSTORE_BASE_URL=http://127.0.0.1:8094
#   DOCGEN_LLM_API_KEY / DOCGEN_LLM_BASE_URL / DOCGEN_LLM_MODEL（复制 QA 的 deepseek 值）
#   DOCGEN_ROOT
```

## 4. vstore 部署 + 起服
```bash
mkdir -p /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified/vstore
rsync -a REPO/vstore/ /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified/vstore/
# 部署树 vstore/.env：VSTORE_KEY（取自 /home/xzq/backups/docgen-vstore-key.txt）、
#   VSTORE_ROOT 或 VSTORE_VAULT_PATH/VSTORE_INDEX_PATH（本地路径或 URL）、
#   VSTORE_EMBED_URL=http://127.0.0.1:11434、VSTORE_EMBED_MODEL=bge-m3:567m
bash deploy/vstore_restart.sh
curl -s http://127.0.0.1:8094/api/vstore/health
```

## 5. BFF 重启 + 前端构建
```bash
bash deploy/bff_restart.sh
cd ui && npm run build  # 生产 dist → 部署树 ui/dist（按现有 sync 规则）
```

## 6. 通知测试 agent 开始 R1（受控端口：vstore 8094 / BFF 8090 / UI 5180 或 dist）

## 7. 回滚（出问题时）
```bash
rsync -a --delete --exclude data --exclude .env $BK/deploy-sdk.tar.gz 解包覆盖 sdk/
cp $BK/plantai.db 回原位; bash deploy/bff_restart.sh
```

## 附：P4 部署实际记录（2026-09-03 15:05）

- 备份：/home/xzq/backups/docgen-20260903-1425（deploy-sdk.tar.gz + plantai.db + env.backup）
- 编译：30 模块 Cython 3.2.8 硬化成功（docgen 全链路 .so）；rsync 替换部署树（保留 data/.env/mock）
- vstore：8094 已起服，local 后端；部署树 vstore/.env 曾因 key 值二次加前缀报 Fernet 格式错（已修，重写 .env 后 ingest 正常）
- vstore_restart.sh 已修 cd 目标（vstore 是包，须从部署根 -m vstore.api:app）
- BFF：8090 重启后 openapi 确认 8 个 docgen 端点；健康检查五上游 + db 正常
- 冒烟：vstore ingest 成功、vault 仅 .enc、明文 grep 无命中；BFF 透传入库/list 正常；完整 QA 流（不断流）7 progress + complete 正常
- vite：5180 已重启（v5.4.11，19s 就绪）

## 附：既有问题归档（非本次引入，A/B 证据）

**「客户端中途断流 → BFF 崩溃」**：`__Pyx_Coroutine_SendEx: Assertion f->f_back == NULL`（db.c）。
- 复现：curl --max-time 20 打 /api/qa/chat/stream 后超时断连 → BFF abort
- A/B：本次构建（db.c:13468）与 9月2日旧构建（db.c:13218，tooling/build/sdk-compiled 备份）**均崩溃**，断言一致 → 既有问题（Cython 3.2.8 协程取消缺陷，与 docgen 无关）
- 影响：用户点「停止」或网络断连可能触发 BFF 进程退出（bff_restart.sh 可快速恢复）；前端「停止」按钮走 AbortController 的路径是否触发待 V1.5 专项验证与修复
- 决策：不纳入本轮 docgen 闭环；记录后另立专项

## 附：断流崩溃根治专项（用户指令 2026-09-03，doc_writer 闭环完成后立即开始）

**用户指令**：记录下来，当前任务完成后立即开始根治断流崩溃。

**已知事实（A/B 证据）**：旧构建（9月2日，db.c:13218）与新构建（db.c:13468）断流均崩，Cython 3.2.8 协程取消缺陷；当前无任何自动拉起（无 systemd/supervisor/cron 守护）。

**拟修路径（按序验证）**：
1. Cython 3.2.8 → 3.3.0 重编译 → 隔离实例断流探针 10 连发 A/B
2. 仍崩则取消敏感模块（db.py / sse_relay.py）降级明文 Python（compile_sdk.sh 白名单机制支持）
3. 配套加固（可选）：BFF 自动守护（systemd Restart=always 或 cron 探测重启）

**验收**：隔离实例断流探针不崩 + 生产替换后「停止按钮/断网」实测 + 三模式问答回归。

## 附：断流崩溃根治完成记录（2026-09-03 19:30）

**修复方案（最终）**：编译白名单追加 3 个模块（app/db.py、app/routers/qa.py、app/services/sse_relay.py）——SSE 流取消链明文化，取消路径全程走 CPython 原生协程。

**证据链**：
- Cython 3.2.8 构建：崩溃 db.c:13468
- Cython 3.3.0 构建：崩溃 db.c:14416（升级无效，3.3.0 未修复此缺陷）
- db.py 明文：崩溃迁移 sse_relay.c:29531（同一断言）→ 证明取消链上任意 Cython 协程均可能触发
- db+qa+sse_relay 明文化：隔离实例断流探针 10/10 存活
- 生产同构建替换后：真实断流探针存活 + 完整 QA 流 7 progress + complete 正常 + 五上游健康

**代价与风险**：3 个模块失去 Cython 硬化（源码可读，无敏感凭据——凭据在 .env/环境）；编译模块 30→27。白名单理由已写入 compile_sdk.sh 注释。

**备份**：/home/xzq/backups/docgen-crashfix-20260903-1922（可回滚）