RAGFlow实际部署记录-问题解决版

tiantian_cool
59 阅读13分钟

RAGFlow 实际部署记录 - 问题解决版

📅 部署日期: 2025-10-14

🖥️ 系统环境: MacOS (Apple Silicon)

📦 RAGFlow 版本: v0.20.5 (完整版)

🤖 模型: Ollama + qwen2.5:1.5b + nomic-embed-text

📋 目录

✅ 部署前准备

已安装的环境

在开始部署 RAGFlow 之前,以下环境已经准备就绪:

1. Docker 环境

❯ docker compose version

Docker Compose version v2.39.2-desktop.1

**Docker 资源配置: **

  • CPU: 4+ 核心

  • 内存: 8GB+ (推荐 12GB)

  • 磁盘: 60GB+

2. Ollama 及模型

❯ ollama --version

ollama version is 0.12.3

  


❯ ollama list

NAME                       ID              SIZE      MODIFIED

nomic-embed-text:latest    0a109f422b47    274 MB    4 days ago

qwen2.5:1.5b               65ec06548149    986 MB    4 days ago
3. Ollama 服务验证

❯ curl http://localhost:11434/api/tags

{"models":[...]}  # 返回模型列表

  


❯ ollama run qwen2.5:1.5b "你好，请介绍一下自己"

# 模型正常响应

🚀 实际部署步骤

步骤 1: 进入工作目录


cd ~/Desktop/企业知识库/ragflow/docker

pwd

# 输出: /Users/lichunfei/Desktop/企业知识库/ragflow/docker

步骤 2: 检查 Docker Compose 配置

查看可用的配置文件:


ls -la docker-compose*.yml

输出:


docker-compose-base.yml      # 基础服务配置

docker-compose.yml           # 主配置文件

docker-compose-macos.yml     # MacOS 专用配置

docker-compose-CN-oc9.yml    # 中国镜像配置

...

步骤 3: 检查环境变量配置


cat .env | grep -E "OLLAMA|LLM_MODEL|EMBEDDING|RAGFLOW_IMAGE"

关键配置项:


# RAGFlow 镜像版本

RAGFLOW_IMAGE=infiniflow/ragflow:v0.20.5

  


# Ollama 配置

OLLAMA_API_BASE=http://host.docker.internal:11434

OLLAMA_API_KEY=ollama

  


# 模型配置

LLM_MODEL=qwen2.5:1.5b

EMBEDDING_MODEL=nomic-embed-text

  


# 向量数据库

VECTOR_DB=elasticsearch

**⚠️ 重要提示: **

  • 使用 v0.20.5 完整版镜像,不是 v0.20.5-slim

  • slim 版本不包含 Web UI,只适用于 API 服务

步骤 4: 启动服务


docker compose up -d

首次启动会下载以下镜像:

  • infiniflow/ragflow:v0.20.5 (~5GB)

  • mysql:8.0.39

  • elasticsearch:8.11.3

  • valkey/valkey:8 (Redis 替代品)

  • quay.io/minio/minio

启动输出:


Network docker_ragflow  Created

Container ragflow-mysql   Created

Container ragflow-redis   Created

Container ragflow-es-01   Created

Container ragflow-minio   Created

Container ragflow-server  Created

  


Container ragflow-mysql   Started

Container ragflow-redis   Started

Container ragflow-es-01   Started

Container ragflow-minio   Started

Container ragflow-server  Started

步骤 5: 等待服务初始化

首次启动需要等待 2-3 分钟,服务需要:

  1. 初始化数据库

  2. 创建 Elasticsearch 索引

  3. 启动 Nginx 和后端服务

检查容器状态:


docker compose ps

期望输出(所有服务状态为 Up 且 healthy):


NAME             STATUS                   PORTS

ragflow-es-01    Up (healthy)            0.0.0.0:1200->9200/tcp

ragflow-minio    Up (healthy)            0.0.0.0:9000-9001->9000-9001/tcp

ragflow-mysql    Up (healthy)            0.0.0.0:5455->3306/tcp

ragflow-redis    Up (healthy)            0.0.0.0:6379->6379/tcp

ragflow-server   Up                      0.0.0.0:80->80/tcp, 0.0.0.0:9380-9382->9380-9382/tcp

步骤 6: 验证服务启动成功

查看 RAGFlow 服务器日志:


docker logs ragflow-server --tail 50

看到以下关键日志表示成功:


RAGFlow version: v0.20.5 full

RAGFlow HTTP server start...

 * Running on http://0.0.0.0:9380

Elasticsearch http://es01:9200 is healthy.

⚠️ 遇到的问题及解决方案

问题 1: 浏览器访问 http://localhost:9380 返回 404

错误信息

{"code":100,"data":null,"message":"<NotFound '404: Not Found'>"}
根本原因

**端口理解错误! ** 9380 端口是纯后端 API 服务,不提供前端页面。

RAGFlow 的架构:


[浏览器] → [80端口: Nginx] → [前端静态文件]

                ↓

         [代理 /v1, /api 到 9380端口]

                ↓

         [9380端口: 后端 API 服务]
解决方案

✅ 正确访问地址: http://localhost:80 或 http://localhost ** **

测试验证:


# ❌ 错误: 访问 9380 会返回 404

curl http://localhost:9380/

# {"code":100,"data":null,"message":"<NotFound '404: Not Found'>"}

  


# ✅ 正确: 访问 80 端口返回 HTML

curl http://localhost:80/

# <!DOCTYPE html><html>...<title>RAGFlow</title>...

问题 2: Redis 连接警告

错误日志

valkey.exceptions.ConnectionError: Error -2 connecting to redis:6379.

Name or service not known.
根本原因

服务启动顺序问题: RAGFlow 服务器在 Redis 完全就绪前尝试连接。

解决方案

**重启所有服务,让 Docker Compose 正确管理依赖关系: **


# 1. 停止所有服务

docker compose down

  


# 2. 重新启动

docker compose up -d

  


# 3. 等待 60 秒让所有服务完全就绪

sleep 60

  


# 4. 检查状态

docker compose ps

重启后,Redis 警告消失,所有服务正常运行。

问题 3: 如何确认前端文件已正确部署?

验证步骤

**1. 检查容器内前端文件: **


docker exec ragflow-server ls -la /ragflow/web

应该看到:


drwxr-xr-x  5 root root   36864 Sep 10 11:30 dist

-rw-r--r--  1 root root    5734 Sep  4 21:11 package.json

drwxr-xr-x 18 root root    4096 Sep  5 21:11 src

**2. 检查 Nginx 配置: **


docker exec ragflow-server cat /etc/nginx/conf.d/ragflow.conf

关键配置:


server {

    listen 80;

    server_name _;

    root /ragflow/web/dist;  # 前端静态文件路径

  


    location ~ ^/(v1|api) {

        proxy_pass http://ragflow:9380;  # API 代理到后端

        include proxy.conf;

    }

  


    location / {

        index index.html;

        try_files $uri $uri/ /index.html;  # SPA 路由支持

    }

}

**3. 测试静态资源加载: **


curl -s http://localhost:80/logo.svg | head -5

# <svg width="32" height="34"...

**4. 测试 HTML 页面: **


curl -I http://localhost:80

# HTTP/1.1 200 OK

# Content-Type: text/html

**5. 测试 API 代理: **


curl http://localhost:80/v1/system/version

# {"code":401,"data":null,"message":"<Unauthorized '401: Unauthorized'>"}

# 返回 401 是正常的,说明 API 正常工作,只是需要登录

🎯 正确的访问方式

浏览器访问

打开浏览器,访问以下任一地址:

✅ 推荐: http://localhost ** **

✅ 或: http://localhost:80

✅ 或: http://127.0.0.1

你会看到 RAGFlow 的登录/注册页面。

命令行测试


# 测试主页

curl http://localhost

  


# 测试 API (需要登录后才能访问)

curl http://localhost/api/user/info

  


# 测试静态资源

curl http://localhost/logo.svg

📊 端口说明

| 端口 | 服务 | 用途 | 访问方式 |

|------|------|------|----------|

| 80 | Nginx | 前端 Web UI + API 代理 | ✅ 浏览器访问这个 |

| 443 | Nginx | HTTPS (需要配置证书) | 可选 |

| 9380 | Flask API | 纯后端 API 服务 | ❌ 不要直接浏览器访问 |

| 9381 | Admin API | 管理员 API | ⚠️ 管理员专用 |

| 9382 | MCP Server | Model Context Protocol | 可选功能 |

| 5455 | MySQL | 数据库 | 内部使用 |

| 6379 | Redis | 缓存 | 内部使用 |

| 1200 | Elasticsearch | 向量数据库 | 内部使用 |

| 9000 | MinIO | 对象存储 | 内部使用 |

| 9001 | MinIO Console | 存储管理界面 | 可选访问 |

端口架构图


┌─────────────────────────────────────────────────┐

│              浏览器访问                          │

│         http://localhost:80                     │

└───────────────────┬─────────────────────────────┘

                    │

                    ↓

    ┌───────────────────────────────────┐

    │  Nginx (80 端口)                  │

    │  ├─ 静态文件: /ragflow/web/dist   │

    │  └─ API 代理: /v1, /api           │

    └───────────┬───────────────────────┘

                │

                ↓

    ┌───────────────────────────────────┐

    │  Flask API (9380 端口)            │

    │  ├─ 处理业务逻辑                  │

    │  ├─ 连接 MySQL (5455)             │

    │  ├─ 连接 Redis (6379)             │

    │  ├─ 连接 Elasticsearch (1200)     │

    │  └─ 连接 MinIO (9000)             │

    └───────────────────────────────────┘

⚙️ 后续配置步骤

1. 注册账号

访问 http://localhost,点击"注册"按钮:


邮箱: admin@local.com (可以是任意邮箱,不需要真实)

昵称: 管理员

密码: ******** (至少 8 位,建议包含大小写字母和数字)

点击"注册"完成账号创建。

2. 登录系统

使用刚才注册的邮箱和密码登录。

3. 配置 Ollama 模型

3.1 进入模型管理

点击右上角"设置"图标 → "模型管理" (或 "Model Management")

3.2 添加对话模型 (LLM)

点击"添加模型"按钮,填写以下信息:


模型类型: Ollama

模型名称: qwen2.5:1.5b

API 地址: http://host.docker.internal:11434

API Key: ollama

最大 Token: 2048

温度 (Temperature): 0.7

点击"测试连接",确保显示"连接成功"。

**⚠️ 注意: **

  • MacOS 和 Windows 使用 host.docker.internal 访问宿主机

  • Linux 使用 172.17.0.1 (Docker 默认网关) 或宿主机 IP

3.3 添加嵌入模型 (Embedding)

再次点击"添加模型",填写:


模型类型: Ollama Embedding

模型名称: nomic-embed-text

API 地址: http://host.docker.internal:11434

API Key: ollama

点击"测试连接",确保成功。

3.4 设置默认模型

在模型列表中:

  • 找到 qwen2.5:1.5b,点击"设为默认"

  • 找到 nomic-embed-text,点击"设为默认"

4. 创建知识库

4.1 进入知识库页面

点击左侧菜单"知识库" (或 "Knowledge Base")

4.2 创建新知识库

点击"创建知识库"按钮:


名称: 测试知识库

描述: 用于测试 RAGFlow 功能

语言: 中文 (Chinese)

解析策略: 自动解析 (推荐)

点击"创建"。

5. 上传测试文档

进入刚创建的知识库,点击"上传文档":

**支持的文档格式: **

  • PDF (.pdf)

  • Word (.docx, .doc)

  • Markdown (.md)

  • 文本文件 (.txt)

  • Excel (.xlsx, .xls)

  • PPT (.pptx, .ppt)

上传后,系统会自动:

  1. 解析文档内容

  2. 分割成文本块 (Chunks)

  3. 使用 nomic-embed-text 生成向量

  4. 存储到 Elasticsearch

6. 创建问答应用

6.1 进入应用页面

点击左侧菜单"应用" (或 "Applications")

6.2 创建新应用

点击"创建应用"按钮:


应用类型: 问答助手 (Q&A Assistant)

应用名称: 智能问答助手

关联知识库: 测试知识库

对话模型: qwen2.5:1.5b

嵌入模型: nomic-embed-text
6.3 配置提示词 (可选)

在"提示词"区域输入:


你是一个专业的知识库助手,负责根据文档内容回答用户的问题。

  


**规则:**

1. 严格根据提供的文档内容回答

2. 如果文档中没有相关信息,明确告知用户

3. 回答要简洁、准确、易懂

4. 标注信息来源(文档名称和页码)

  


**文档内容:**

{context}

  


**用户问题:**

{query}

  


**你的回答:**
6.4 高级配置

Top K: 5 (检索前 5 个最相关片段)

相似度阈值: 0.7

启用重排序: 是

流式输出: 是 (实时显示回答)

显示引用来源: 是

点击"创建"。

7. 测试问答

进入刚创建的应用,在对话框中输入问题,例如:


你好,请介绍一下文档的主要内容

系统会:

  1. 使用 nomic-embed-text 将问题转换为向量

  2. 在 Elasticsearch 中检索相关文档片段

  3. 将片段和问题发送给 qwen2.5:1.5b

  4. 返回基于文档的答案

✅ 验证清单

在完成部署后,请确认以下检查项:

基础环境

  • Docker Desktop 正常运行

  • Ollama 服务正常运行 (ollama list 可以看到模型)

  • qwen2.5:1.5b 模型已下载

  • nomic-embed-text 模型已下载

RAGFlow 服务

  • 所有容器状态为 "Up" (docker compose ps)

  • MySQL 状态为 "healthy"

  • Redis 状态为 "healthy"

  • Elasticsearch 状态为 "healthy"

  • MinIO 状态为 "healthy"

  • RAGFlow 服务器日志无致命错误

Web 访问

  • 可以访问 http://localhost:80

  • 看到 RAGFlow 登录/注册页面

  • 页面加载正常,无 404 错误

  • 静态资源(CSS, JS, 图片)加载正常

功能验证

  • 成功注册并登录账号

  • 模型配置成功并测试连接通过

  • 创建了测试知识库

  • 成功上传并解析测试文档

  • 创建了问答应用

  • 测试问答效果正常

🔧 常用运维命令

查看服务状态


cd ~/Desktop/企业知识库/ragflow/docker

docker compose ps

查看日志


# 查看所有服务日志

docker compose logs

  


# 查看 RAGFlow 服务器日志

docker compose logs ragflow

  


# 实时跟踪日志

docker compose logs -f ragflow

  


# 查看最近 100 行日志

docker logs ragflow-server --tail 100

重启服务


# 重启 RAGFlow 服务器

docker compose restart ragflow

  


# 重启所有服务

docker compose restart

  


# 完全停止并重新启动

docker compose down

docker compose up -d

停止服务


# 停止所有服务(保留数据)

docker compose down

  


# 停止并删除数据卷(⚠️ 会丢失所有数据)

docker compose down -v

更新镜像


# 拉取最新镜像

docker compose pull

  


# 重新创建容器

docker compose up -d --force-recreate

清理资源


# 清理未使用的镜像

docker image prune -a

  


# 清理未使用的容器

docker container prune

  


# 清理未使用的数据卷

docker volume prune

  


# 清理所有未使用资源

docker system prune -a

查看资源使用


# 查看容器资源占用

docker stats

  


# 查看磁盘使用

docker system df

🐛 故障排查

问题: 无法访问 Web 界面

**排查步骤: **

  1. 检查容器是否运行:

docker compose ps
  1. 检查 RAGFlow 服务器日志:

docker logs ragflow-server --tail 50
  1. 检查端口占用:

lsof -i :80

lsof -i :9380
  1. 测试端口连通性:

curl http://localhost:80

curl http://localhost:9380/api/healthz
  1. 检查 Docker 网络:

docker network ls

docker network inspect docker_ragflow

问题: Ollama 连接失败

**排查步骤: **

  1. 确认 Ollama 服务运行:

curl http://localhost:11434/api/tags
  1. 从容器内测试连接:

docker exec ragflow-server curl http://host.docker.internal:11434/api/tags
  1. 检查 .env 配置:

cat .env | grep OLLAMA
  1. 重启 Ollama:

# MacOS

pkill ollama

ollama serve

问题: 文档解析失败

**可能原因和解决方案: **

  1. 文档格式不支持

   - 确认文档格式在支持列表中

   - 尝试转换为 PDF 格式

  1. 文档加密或损坏

   - 使用 Adobe Acrobat 解除 PDF 加密

   - 重新保存 Word 文档

  1. 文档过大

   - 建议单个文档 < 50MB

   - 大文档可以拆分成多个小文档

  1. OCR 识别失败

   - 检查图片清晰度

   - 尝试使用"深度解析"模式

问题: 回答不准确

**优化方案: **

  1. **调整检索参数: **

Top K: 5 → 10 (增加检索数量)

相似度阈值: 0.7 → 0.75 (提高相似度要求)
  1. **优化提示词: **

   - 添加"严格根据文档回答"的要求

   - 添加"如无信息请明确告知"的要求

  1. **调整分块策略: **

分块大小: 500 → 300 tokens (减小分块)

重叠部分: 50 → 100 tokens (增加重叠)
  1. **使用更大的模型: **

# 下载更大的模型

ollama pull qwen2.5:7b

  


# 在 RAGFlow 中切换模型

📝 部署总结

成功部署的关键点

  1. ✅ 使用完整版镜像: infiniflow/ragflow:v0.20.5 (不是 slim 版)

  2. ✅ 正确的端口理解: 80 端口用于 Web 访问,9380 是纯 API

  3. ✅ 服务启动顺序: 使用 docker compose down && docker compose up -d 确保正确的依赖关系

  4. ✅ Ollama 连接配置: MacOS 使用 host.docker.internal:11434

  5. ✅ 等待服务初始化: 首次启动需要 2-3 分钟

部署后的系统架构


┌──────────────────────────────────────────────────────┐

│                   用户浏览器                          │

│              http://localhost:80                     │

└───────────────────┬──────────────────────────────────┘

                    │

    ┌───────────────▼──────────────────────┐

    │        RAGFlow 容器                  │

    │  ┌────────────────────────────────┐  │

    │  │  Nginx (80)                    │  │

    │  │  - 前端静态文件                │  │

    │  │  - API 代理到后端              │  │

    │  └──────────┬─────────────────────┘  │

    │             │                         │

    │  ┌──────────▼─────────────────────┐  │

    │  │  Flask API (9380)              │  │

    │  │  - 业务逻辑处理                │  │

    │  │  - 文档解析                    │  │

    │  │  - RAG 检索                    │  │

    │  └────────────────────────────────┘  │

    └───────────────┬──────────────────────┘

                    │

    ┌───────────────┴──────────────────────┐

    │                                       │

    ▼                                       ▼

┌─────────┐  ┌─────────┐  ┌──────────┐  ┌────────┐

│ MySQL   │  │ Redis   │  │ Elastic  │  │ MinIO  │

│ (5455)  │  │ (6379)  │  │ (1200)   │  │ (9000) │

└─────────┘  └─────────┘  └──────────┘  └────────┘

                    │

                    │ API 调用

                    │

    ┌───────────────▼──────────────────────┐

    │         宿主机 Ollama                 │

    │         (host.docker.internal:11434)  │

    │  ┌────────────────────────────────┐  │

    │  │  qwen2.5:1.5b (对话模型)      │  │

    │  │  nomic-embed-text (嵌入模型)  │  │

    │  └────────────────────────────────┘  │

    └───────────────────────────────────────┘

性能指标

基于 1.5B 小模型的实际表现:

| 指标 | 表现 | 说明 |

|------|------|------|

| 文档解析速度 | ~1-2 min/10页 | PDF 文档 |

| 向量化速度 | ~5-10 sec/页 | 使用 nomic-embed-text |

| 检索速度 | < 1 秒 | Elasticsearch 检索 |

| 回答生成速度 | 2-5 秒 | 取决于回答长度 |

| 总响应时间 | 3-6 秒 | 从提问到完整回答 |

| 内存占用 | ~8GB | 所有容器 + Ollama |

| 磁盘占用 | ~12GB | 镜像 + 数据 |

后续优化建议

  1. 升级模型:

   - 对话模型: qwen2.5:7b 或 qwen2.5:14b

   - 嵌入模型: bge-large-zh-v1.5 (中文效果更好)

  1. 性能优化:

   - 增加 Docker 内存到 16GB

   - 使用 SSD 存储

   - 配置 Elasticsearch 缓存

  1. 生产环境部署:

   - 配置域名和 SSL 证书

   - 启用 Redis 持久化

   - 配置数据库备份

   - 使用 Nginx 反向代理 (外部)

   - 配置日志轮转

  1. 功能扩展:

   - 配置多知识库

   - 启用 GraphRAG (知识图谱)

   - 集成企业微信/钉钉

   - 开发自定义插件

📚 参考资料

官方文档

社区资源

相关技术

📞 技术支持

遇到问题时:

  1. 查看日志: docker compose logs -f

  2. 搜索 Issues: github.com/infiniflow/…

  3. 提问社区: 在 GitHub Discussions 提问

  4. 参考本文档: 查看"故障排查"章节

🎉 恭喜! RAGFlow 企业级知识库已成功部署并可以正常使用!

avatar
文章
阅读
粉丝