常见问题

1. 如何查看日志？

docker compose logs -f app docreader postgres

2. 如何启动和停止服务？

./scripts/start_all.sh           # 启动服务
./scripts/start_all.sh --stop    # 停止服务
./scripts/start_all.sh --stop && make clean-db  # 清空数据库

开发模式下的启停参见 开发指南

3. 服务启动后无法正常上传文档？

通常是 Embedding 模型和对话模型没有正确被设置导致。

排查步骤

1. 查看 .env 配置中的模型信息是否配置完整：

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 日志输出

模型管理参见 内置模型管理

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。

# SSRF_WHITELIST=internal.service,*.corp.example,172.16.0.0/12

生产环境请谨慎配置。搜索引擎的 API 端点硬编码策略参见 添加网络搜索引擎

相关主题

• 开发指南 — 开发环境问题排查
• 开启知识图谱功能 — 知识图谱功能故障排查
• 内置模型管理 — 模型配置问题
• IM集成开发 — IM 集成相关问题

反向链接

• Home — Wiki 首页导航
• 开发指南 — 开发环境搭建与问题排查
• 开启知识图谱功能 — 知识图谱功能相关故障排查
• 内置模型管理 — 模型配置相关问题
• 快速开发模式 — 开发模式相关问题
• 添加网络搜索引擎 — SSRF 白名单与搜索 API 安全策略