WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

2026-09-22 16:19:06 +08:00
commit f7fc992f57
3929 changed files with 1006607 additions and 0 deletions
@@ -0,0 +1,106 @@
+---
+title: 常见问题
+tags: [运维排障, FAQ, 故障排查, 部署]
+aliases: [FAQ, 故障排查, QA]
+source: QA.md
+---
+
+# 常见问题
+
+## 1. 如何查看日志？
+
+```bash
+docker compose logs -f app docreader postgres
+```
+
+## 2. 如何启动和停止服务？
+
+```bash
+./scripts/start_all.sh           # 启动服务
+./scripts/start_all.sh --stop    # 停止服务
+./scripts/start_all.sh --stop && make clean-db  # 清空数据库
+```
+
+> 开发模式下的启停参见 [开发指南](../开发部署/开发指南.md)
+
+## 3. 服务启动后无法正常上传文档？
+
+通常是 Embedding 模型和对话模型没有正确被设置导致。
+
+### 排查步骤
+
+1. 查看 `.env` 配置中的模型信息是否配置完整：
+
+```bash
+INIT_LLM_MODEL_NAME=your_llm_model
+INIT_EMBEDDING_MODEL_NAME=your_embedding_model
+INIT_EMBEDDING_MODEL_DIMENSION=your_embedding_model_dimension
+INIT_EMBEDDING_MODEL_ID=your_embedding_model_id
+```
+
+2. 如果使用 remote API，还需提供 `BASE_URL` 和 `API_KEY`
+3. 如需重排序功能，额外配置 Rerank 模型
+4. 查看主服务日志，是否有 `ERROR` 日志输出
+
+> 模型管理参见 [内置模型管理](../核心功能/内置模型管理.md)
+
+## 4. 没有图片或者显示无效的图片链接？
+
+1. 确认多模态功能已正确配置（知识库设置 → 高级设置 → 多模态功能）
+2. 确认 MinIO 服务已启动
+3. 检查 MinIO Bucket 权限
+4. 配置 `MINIO_PUBLIC_ENDPOINT`（如需从其他设备访问）
+
+**重要**：Bucket 名称不要包含特殊字符；如无法修改权限，可填入不存在的 bucket 名称，系统会自动创建。
+
+## 5. 平台兼容性说明
+
+`OCR_BACKEND=paddle` 在部分平台上可能无法正常运行。
+
+- **方案一**：关闭 OCR 识别（删除 `OCR_BACKEND` 配置）
+- **方案二**：使用外部 OCR 模型（推荐）— 配置 `OCR_BACKEND=vlm`
+
+## 6. 如何使用数据分析功能？
+
+- **智能推理**：需在工具配置中勾选「查看数据元信息」和「数据分析」
+- **快速问答智能体**：无需手动选择工具
+
+### 注意事项
+
+- 仅支持 CSV 和 Excel 格式
+- 仅支持只读查询（SELECT、SHOW 等）
+
+## 7. 页面里刚保存的配置几秒后又消失了？
+
+通常是浏览器代理、缓存或插件干扰导致。建议：
+1. 关闭浏览器代理和抓包工具
+2. 强制刷新或使用无痕窗口
+3. 检查 Network 面板确认请求未被代理改写
+
+## 8. SSRF 校验白名单
+
+`SSRF_WHITELIST` 配置项用于绕过常规 SSRF 限制，支持：精确域名、通配域名、IPv4/IPv6、CIDR。
+
+```bash
+# SSRF_WHITELIST=internal.service,*.corp.example,172.16.0.0/12
+```
+
+> 生产环境请谨慎配置。搜索引擎的 API 端点硬编码策略参见 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md)
+
+## 相关主题
+
+- [开发指南](../开发部署/开发指南.md) — 开发环境问题排查
+- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 知识图谱功能故障排查
+- [内置模型管理](../核心功能/内置模型管理.md) — 模型配置问题
+- [IM集成开发](../集成扩展/IM集成开发.md) — IM 集成相关问题
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [开发指南](../开发部署/开发指南.md) — 开发环境搭建与问题排查
+- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 知识图谱功能相关故障排查
+- [内置模型管理](../核心功能/内置模型管理.md) — 模型配置相关问题
+- [快速开发模式](../开发部署/快速开发模式.md) — 开发模式相关问题
+- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — SSRF 白名单与搜索 API 安全策略