docs(deploy): 记录 wtfllm 生产部署要点与固定版本清单

项目部署须知.md

@@ -0,0 +1,32 @@
+## 部署须知
+
+1. 当前项目生产环境部署在 本地服务器 192.168.5.2上；
+2. 可使用ssh技能，搭配本地密钥进行连接；
+3. 服务器上的项目路径为：/bot/danding-bot
+
+
+
+## 常规升级、部署流程
+
+1. 推送git代码；
+2. 到指定服务器、指定程序目录，拉取git最新代码；
+
+
+
+## 注意点
+
+- 所有服务器都使用1panel进行管理，包含网站、反代的搭建等；
+- 需要使用git进行代码版本的管理、同步；
+- 一切代码需要以git云端代码为准，若生产环境无法拉取，需要覆盖强制拉取；
+- 所有的代码升级或部署后，需要确保服务正在运行最新版本的代码(重启当前服务，并确保服务可正常运行)；
+- 升级或部署前，若本地有未推送的代码，需要先推送到云端git；
+
+
+## wtfllm(AI 帮助助手)部署要点(2026-08-30)
+
+1. 生产环境已切换到 `/bot/danding-bot/.venv`(Python 3.12),启动命令改为 `start_bot.sh`(内含 `FASTEMBED_CACHE_PATH` 与 `HF_HUB_OFFLINE=1` 环境变量);
+2. 依赖按 `kb_build/req_freeze.txt` + `kb_build/req_extra.txt` 固定版本安装;`amis-python`、`nonebot_plugin_learning_chat`、`pyppeteer`、`nonebot-plugin-wtfllm` 需 `pip install --no-deps` 单独处理;
+3. 模型缓存已预置在 `/bot/danding-bot/.fastembed_cache`(bge-small-zh + Qdrant/bm25),服务器无法直连 HuggingFace/GitHub,勿删除;
+4. 知识库重灌:`cd /bot/danding-bot && FASTEMBED_CACHE_PATH=/bot/danding-bot/.fastembed_cache HF_HUB_OFFLINE=1 .venv/bin/python kb_build/import_kb.py --agent-id 1411350196`;
+5. 若启动报 Qdrant 启动超时,先 `kill -9` 残留的 qdrant.exe/qdrant 进程(数据目录被锁)再重启;
+6. wtfllm 仅在群 621016172 响应(见 `danding_bot/plugins/wtfllm_gate.py`)。