tian~
RAGFlow 全流程部署与知识库实战指南
本指南旨在帮助开发者在本地快速搭建基于深度文档理解的 RAGFlow 系统。
一、 核心业务逻辑流程图 (RAG 核心原理)
二、 环境准备 (Pre-requisites)
1. 硬件要求（硬性指标）
- 内存 (RAM): 16GB+ (核心组件如 Elasticsearch、MinIO 非常吃内存)。
- CPU: 4 核以上。
- 磁盘: 50GB 以上可用空间。
2. 软件依赖
- Docker: 24.0.0+
- Docker Compose: 2.26.1+
- 操作系统: Windows (WSL2), Linux, 或 macOS。
三、 本地搭建步骤 (Installation)
1. 克隆仓库与配置
bash
# 克隆项目
git clone https://github.com/infiniflow/ragflow.git
cd ragflow
git checkout v0.24.0
# (可选) 如果需要修改端口，请编辑 docker-compose.yml
# 将 - 80:80 改为 - 8080:80 以避免端口冲突
2. 启动服务
由于镜像较多（约 10GB+），请耐心等待下载完成。
bash
# 后台启动所有容器
docker compose up -d
3. 检查运行状态
bash
# 查看所有容器是否为 Up (healthy)
docker ps
4. 启动后没多久接口502问题
注意: 大概率为桌面版的dokcer desktop中资源节省导致的
提示：如果看到某些容器在重启，通常是因为内存分配不足导致的。
四、 知识库配置全流程 (Setup)
1. 登录管理后台
- 访问地址: 浏览器打开 http://localhost (默认 80 端口)。
- 初始操作: 注册一个新账号并登录。
2. 接入 AI 模型 (最关键一步)
RAGFlow 本身不产出内容，需要接入 LLM（大脑）和 Embedding（翻译官）：
- 进入右上角 "User Setting" -> "Model Providers"。
- 接入模型:
在线 API: 填入 DeepSeek 或 OpenAI 的 API Key。
本地 Ollama: 地址填写 http://host.docker.internal:11434。
设置默认模型: 在 "System Model Config" 中，务必选定一个 Embedding Model，否则无法对文档进行向量化。
- 设置默认模型: 在 "System Model Config" 中，务必选定一个 Embedding Model，否则无法对文档进行向量化。
3. 构建私有知识库
- 点击导航栏 "Knowledge Base" -> "Create Knowledge Base"。
- 上传文件: 支持 PDF, Word, Excel, Markdown。
- 解析策略 (Chunk Method):
- General: 适用于常规文档。
- Table: 专门处理复杂表格。
- 开始解析: 点击 "Parse"，等待状态变为 "Success"。
五、 实现 AI 对话 (Chat)
- 进入 "Chat" 页面，新建一个聊天窗口。
- 挂载知识库: 在右侧设置面板的 Knowledge Bases 中勾选刚才创建的库。
- 开始对话: 询问文档内容，系统会基于检索到的片段回答，并标注 Citations (来源引用)。
六、 踩坑避雷针 (Troubleshooting) ⚡
| 报错/问题 | 常见原因 | 解决方案 |
|---|---|---|
| 80 端口被占用 | 本地有 Nginx 或 IIS 服务 | 编辑 docker-compose.yml，将 - 80:80 改为 - 8080:80 |
| 解析一直 Pending | 未配置 Embedding 模型 | 在用户设置里检查是否选择了默认的向量模型 |
| Docker 容器闪退 | 宿主机内存不足 (OOM) | 增加系统虚拟内存，或在 Docker 设置中调高内存限额至 16G。 |
| 无法连接本地 Ollama | Docker 网络隔离 | 不要写 127.0.0.1，必须写 http://host.docker.internal:11434 |
| PDF 解析不准 | 文档布局过于复杂 | 在解析设置中尝试更换 Layout Analysis 模板。 |
七、 维护建议
- 更新版本: git pull 后重新执行 docker compose up -d。
- 清理缓存: 定期检查 Docker 占用的磁盘空间，使用 docker system prune（慎用）。