feat(govai): 0617 优化首批 — 安全/私有化/深度研究/服务层/可观测性

借鉴 odysseus 的能力设计，全程净室实现、零 AGPL 代码、不引入 AGPL 依赖。

T1 提示注入防护: pkg/promptguard 包裹外部/知识库内容为不可信数据，buildMessages 移出 system 指令区。 T2 安全 CI: .github/workflows(ci+security: govulncheck/gitleaks/actionlint/hadolint/trivy)+dependabot+.hadolint.yaml；go.mod 加 toolchain go1.25.11 修复 20 个 stdlib CVE。 T3 管理员 2FA: 迁移 000016 + RFC6238 TOTP/备份码(pkg/auth, 零依赖) + 登录流程集成(后端)。 T4 本地模型: LLM/embedding 支持本地 vLLM/Ollama(OpenAI 兼容, 鉴权头条件发送, NoAuth) + docs/local-deploy.md。 T6 深度研究: 迁移 000017 + Python research-worker(净室多步流水线, 检索避开 SearXNG) + Go research 服务/handler/路由。 T7 service 层: 新增 internal/service/{research,twofa}, 2FA 业务逻辑从胖 handler 下沉, 接口注入可单测。 T10 缓存/可观测性: internal/cache(Redis+内存, 优雅降级) 接入 store 热点列表; Prometheus 指标+/metrics; docs/openapi.yaml。 验证: go build/vet/test ./... 全绿(8 包); research-worker 12 单测过; 真实 PG 应用迁移并烟测。

docs/local-deploy.md

@@ -0,0 +1,87 @@
+# 本地模型部署（私有化 / 内网）指南
+
+面向数据主权、信创、等保要求的场景：把对话推理与向量化（RAG）全部切到**本地 / 内网**的模型服务，数据全程不出公网。GovAi 后端通过统一的 OpenAI 兼容接口对接，无需改代码，仅配置环境变量即可。
+
+> 本指南为 GovAi 自行编写。所涉开源组件（Ollama、vLLM 等）各自遵循其许可证，请按各自条款使用。
+
+## 一、原理
+
+- 对话推理：GovAi 的 `LLM_PROVIDER=local` 会启用一个 **OpenAI 兼容** 的本地 provider（`/v1/chat/completions`，支持流式 SSE）。
+- 向量化：`EMBEDDING_BASE_URL` 指向本地 `/v1/embeddings` 即可；本地无鉴权时设 `EMBEDDING_NO_AUTH=true`。
+- 凡是暴露 OpenAI 兼容接口的本地引擎（vLLM、Ollama、llama.cpp server、LM Studio、SGLang 等）都可对接。
+
+## 二、起本地模型服务（任选其一）
+
+### 方式 A：Ollama（最简单，适合单机试点）
+
+```bash
+# 安装后拉起模型（示例为通义千问 7B）
+ollama pull qwen2.5:7b
+ollama pull bge-m3            # 向量模型（RAG 用）
+# Ollama 默认在 11434 提供服务，并暴露 OpenAI 兼容端点 /v1
+```
+
+- Chat 端点：`http://127.0.0.1:11434/v1`
+- Embedding 端点：`http://127.0.0.1:11434/v1`
+- Ollama 忽略鉴权，密钥留空即可。
+
+### 方式 B：vLLM（吞吐更高，适合生产 GPU 服务器）
+
+```bash
+# 以 OpenAI 兼容服务启动（示例）
+python -m vllm.entrypoints.openai.api_server \
+  --model Qwen/Qwen2.5-7B-Instruct \
+  --host 0.0.0.0 --port 8000
+# 如需鉴权：追加 --api-key <你的密钥>，并在下方填入 LOCAL_LLM_API_KEY
+```
+
+- Chat 端点：`http://127.0.0.1:8000/v1`
+- 向量化建议另起一个 embedding 服务（如用 vLLM/`text-embeddings-inference` 部署 `bge-m3`）。
+
+## 三、配置 GovAi（`.env`）
+
+```bash
+# 对话推理切到本地
+LLM_PROVIDER=local
+LOCAL_LLM_BASE_URL=http://127.0.0.1:11434/v1   # 或 vLLM 的 http://127.0.0.1:8000/v1
+LOCAL_LLM_MODEL=qwen2.5:7b                      # 与本地实际模型名一致
+LOCAL_LLM_API_KEY=                              # Ollama 留空；vLLM 若设了 --api-key 则填
+
+# 向量化切到本地（RAG 全链路离线）
+EMBEDDING_BASE_URL=http://127.0.0.1:11434/v1
+EMBEDDING_MODEL=bge-m3
+EMBEDDING_DIMENSIONS=1024                        # 必须与模型输出维度一致，详见下文
+EMBEDDING_NO_AUTH=true                           # 本地无鉴权
+```
+
+重启后端（`make dev-api` 或容器）后即生效。云端与本地可共存：`openai`/`anthropic`/`local` 三个 provider 同时注册，由 `LLM_PROVIDER` 决定默认使用哪个。
+
+## 四、⚠️ 向量维度一致性（重要）
+
+`EMBEDDING_DIMENSIONS` 必须同时满足三方一致：
+
+1. 本地 embedding 模型的实际输出维度（如 `bge-m3` = 1024，`nomic-embed-text` = 768）；
+2. `pgvector` 中 `knowledge_chunks.embedding` 列声明的维度；
+3. 已入库的历史向量维度。
+
+**更换 embedding 模型导致维度变化时**，需要新建/调整向量列维度，并对知识库**重新向量化**：
+
+```bash
+# 清空旧向量后，通过接口或工具重嵌入
+# POST /api/v1/knowledge/reembed   （或 server/cmd/embed-chunks）
+```
+
+维度不一致会导致向量检索报错或失效（此时系统会优雅降级为关键词检索）。
+
+## 五、验证
+
+1. 启动本地模型服务与后端。
+2. 在应用商店打开任一对话型应用，发送一条消息，确认**流式逐字输出**正常。
+3. 打开一个绑定知识库的应用，提问知识库内问题，确认能检索到文献并标注来源（RAG 生效）。
+4. **离线验证**：临时切断后端所在主机的公网出口（仅保留到本地模型服务的内网连通），重复第 2、3 步，确认对话与 RAG 仍可完成——即数据不出网。
+
+## 六、安全提示
+
+- 本地模型端口（11434 / 8000 等）只在内网开放，**不要暴露到公网**。
+- 生产建议在后端与模型服务之间加内网网关/反向代理，并对模型服务启用鉴权（vLLM `--api-key`）。
+- 私有化下仍建议开启管理员 2FA（见 0617task.md T3）与提示注入防护（T1）。