---
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 安全策略