RAGFlow本地化部署指南：从零搭建企业级知识库与智能问答系统

在实际企业级知识库和智能问答系统构建中RAG检索增强生成技术因其能有效结合外部知识库与大模型生成能力而备受关注。RAGFlow 作为一个基于深度文档理解的开源 RAG 引擎提供了从文档解析、向量检索到答案生成的完整流水线尤其适合处理复杂格式的文档。对于希望将 RAGFlow 私有化部署到本地环境以保障数据安全、实现定制化开发或进行深度集成的开发者和团队而言掌握其安装部署流程是第一步也是至关重要的一步。本文将带你完成 RAGFlow 从零开始的本地化部署。整个过程不仅包括基础的软件安装和环境配置更会深入到依赖服务的部署、关键参数的调整以及部署后的验证和初步排错。无论你是想在个人开发机上搭建学习环境还是在公司内网服务器上构建生产级应用本文提供的步骤和思路都将为你提供清晰的指引。我们将以 Docker 作为主要的部署方式因为它能最大程度地保证环境的一致性简化依赖管理。1. 理解 RAGFlow 的架构与核心依赖在动手部署之前先理解 RAGFlow 的组件构成和它依赖的外部服务这能帮助你在后续步骤中明确每个操作的目的并在出现问题时快速定位。RAGFlow 的核心是一个 Web 应用后端它本身不直接包含向量数据库和大语言模型LLM而是作为协调者与这些外部服务进行交互。一个典型的 RAGFlow 部署架构包含以下部分RAGFlow 服务本身提供文档解析、检索、问答的 API 和用户界面。向量数据库用于存储文档切片后生成的向量嵌入Embeddings。RAGFlow 支持多种向量数据库如 Milvus、Chroma、Qdrant 等。这是实现高效语义检索的关键。关系型数据库用于存储元数据、用户信息、对话记录等结构化数据。通常使用 MySQL 或 PostgreSQL。对象存储用于存储上传的原始文档文件。可以使用本地文件系统、MinIO 或 AWS S3 等兼容 S3 协议的服务。大语言模型LLM服务用于生成最终的答案。RAGFlow 支持通过 OpenAI API 格式访问的各类模型包括本地部署的模型如 Ollama、vLLM 部署的模型或云端 API如 OpenAI、DeepSeek、智谱 AI 等。文本嵌入模型服务用于将文本转换为向量。同样支持通过 OpenAI API 格式访问的嵌入模型可以是本地部署的如 BGE、text2vec 等或云端的。对于本地部署最常见的组合是RAGFlow (Docker) MySQL (Docker) Milvus (Docker) 本地文件存储 Ollama (本地 LLM/Embedding 服务)。这种组合完全在本地运行无需连接外网。2. 部署前的环境准备与规划部署的成功与否很大程度上取决于前期环境的准备。本节将详细列出软硬件要求并规划一个清晰的部署目录结构。2.1 系统与硬件要求操作系统Linux如 Ubuntu 20.04/22.04, CentOS 7/8、macOS 或 Windows通过 WSL2 或 Docker Desktop。生产环境推荐使用 Linux 服务器。Docker 与 Docker Compose这是部署的核心工具。确保已安装最新稳定版本。Docker: 20.10Docker Compose: v2.0硬件资源CPU建议 4 核以上。文档解析和向量化是 CPU 密集型操作。内存至少 8GB推荐 16GB 或以上。Milvus 和 LLM 服务对内存需求较高。磁盘至少 20GB 可用空间用于存储镜像、数据库和文档。如果处理大量文档需要预留更多空间。网络部署过程中需要从 Docker Hub 拉取镜像。如果服务器在内网请确保能访问外网或已配置内部镜像仓库。2.2 安装 Docker 与 Docker Compose如果你的系统尚未安装 Docker以下是 Ubuntu 系统的安装示例。其他系统请参考 Docker 官方文档。# 1. 卸载旧版本如有 sudo apt-get remove docker docker-engine docker.io containerd runc # 2. 更新 apt 包索引并安装依赖 sudo apt-get update sudo apt-get install ca-certificates curl gnupg lsb-release # 3. 添加 Docker 官方 GPG 密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 4. 设置 Docker 稳定版仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 5. 安装 Docker Engine sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 6. 验证安装 sudo docker --version sudo docker compose version # 7. 可选将当前用户加入 docker 组避免每次使用 sudo sudo usermod -aG docker $USER # 执行此命令后需要退出当前终端并重新登录或执行 newgrp docker 使更改生效2.3 规划部署目录与获取配置文件创建一个清晰的工作目录用于存放所有配置和数据便于管理和备份。# 创建一个工作目录例如 /opt/ragflow sudo mkdir -p /opt/ragflow cd /opt/ragflow # 在此目录下我们通常会创建以下子目录后续配置会用到 # - storage用于挂载 RAGFlow 的本地文件存储 # - mysql_data用于持久化 MySQL 数据 # - milvus_data用于持久化 Milvus 数据 # - config用于存放自定义配置文件 mkdir -p storage mysql_data milvus_data config接下来获取 RAGFlow 的官方 Docker Compose 配置文件。你可以从 RAGFlow 的 GitHub 仓库获取最新的docker-compose.yml。# 使用 curl 下载示例的 docker-compose 文件请检查仓库是否有更新 curl -o docker-compose.yml https://raw.githubusercontent.com/infiniflow/ragflow/main/docker-compose.yml注意直接下载的docker-compose.yml可能包含连接云端服务的配置。对于纯本地部署我们需要对其进行修改。如果没有现成文件也可以根据以下章节内容手动创建。3. 配置与启动核心依赖服务我们将先部署 MySQL 和 Milvus因为 RAGFlow 启动时需要连接它们。3.1 配置 MySQL 数据库创建一个自定义的 MySQL 配置文件并修改 Docker Compose 文件。首先在config目录下创建 MySQL 配置文件my.cnfcat /opt/ragflow/config/my.cnf EOF [mysqld] character-set-serverutf8mb4 collation-serverutf8mb4_unicode_ci max_connections1000 default-authentication-pluginmysql_native_password # 解决 Docker 容器时区问题 default-time-zone08:00 EOF然后编辑docker-compose.yml文件定义 MySQL 服务。以下是关键部分version: 3.8 services: mysql: image: mysql:8.0 container_name: ragflow-mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: ragflow123 # 请修改为强密码 MYSQL_DATABASE: ragflow TZ: Asia/Shanghai volumes: - ./mysql_data:/var/lib/mysql # 数据持久化 - ./config/my.cnf:/etc/mysql/conf.d/my.cnf # 自定义配置 ports: - 3306:3306 networks: - ragflow-network command: --default-authentication-pluginmysql_native_password3.2 配置 Milvus 向量数据库Milvus 是高性能向量数据库。我们使用其单机版 Docker 镜像。在docker-compose.yml中继续添加milvus-standalone: image: milvusdb/milvus:v2.3.3 # 建议使用与 RAGFlow 兼容的稳定版本 container_name: ragflow-milvus restart: unless-stopped environment: ETCD_ENDPOINTS: milvus-standalone:2379 MINIO_ADDRESS: milvus-standalone:9000 volumes: - ./milvus_data:/var/lib/milvus # 数据持久化 ports: - 19530:19530 # Milvus 服务端口 - 9091:9091 # 监控端口 networks: - ragflow-network healthcheck: test: [CMD, curl, -f, http://localhost:9091/healthz] interval: 30s timeout: 20s retries: 33.3 启动依赖服务并验证现在启动 MySQL 和 Milvus# 在 /opt/ragflow 目录下执行 sudo docker compose up -d mysql milvus-standalone使用以下命令检查服务状态# 查看容器运行状态 sudo docker compose ps # 查看 MySQL 日志确保无报错且初始化完成 sudo docker compose logs -f mysql # 等待几十秒后尝试进入 MySQL 容器并连接数据库 sudo docker exec -it ragflow-mysql mysql -u root -pragflow123 # 在 MySQL 提示符下执行 mysql SHOW DATABASES; # 应该能看到 ragflow 数据库。 mysql exit;4. 部署与配置 RAGFlow 服务依赖服务就绪后我们来部署 RAGFlow 本身。4.1 配置 RAGFlow 的 Docker Compose 服务在docker-compose.yml中添加 RAGFlow 服务配置。这里是最关键的一步需要正确配置数据库连接、向量库连接和模型端点。ragflow: image: infiniflow/ragflow:latest # 或指定特定版本如 v0.10.0 container_name: ragflow-server restart: unless-stopped depends_on: mysql: condition: service_healthy milvus-standalone: condition: service_started environment: # 数据库配置 MYSQL_HOST: mysql MYSQL_PORT: 3306 MYSQL_USER: root MYSQL_PASSWORD: ragflow123 # 与上面设置的密码一致 MYSQL_DATABASE: ragflow # 向量数据库配置 (Milvus) MILVUS_HOST: milvus-standalone MILVUS_PORT: 19530 # 本地文件存储路径容器内路径 DOC_STORAGE_PATH: /app/storage # LLM 和 Embedding 模型配置关键 # 假设我们在本地 11434 端口运行了 Ollama 服务 LLM_API_BASE: http://host.docker.internal:11434 # 对于 Linux可能需要改为宿主机IP如 http://172.17.0.1:11434 LLM_MODEL: qwen2.5:7b # Ollama 中拉取的模型名称 EMBEDDING_API_BASE: http://host.docker.internal:11434 EMBEDDING_MODEL: nomic-embed-text # Ollama 中拉取的嵌入模型名称 # 其他配置 SECRET_KEY: your-secret-key-change-this # 用于加密请务必修改 API_PORT: 9380 volumes: - ./storage:/app/storage # 将本地 storage 目录挂载到容器 ports: - 9380:9380 # RAGFlow API 端口 networks: - ragflow-network healthcheck: test: [CMD, curl, -f, http://localhost:9380/v1/health] interval: 30s timeout: 10s retries: 34.2 关键配置项详解LLM_API_BASE和EMBEDDING_API_BASE这是连接本地 LLM 服务的关键。host.docker.internal是 Docker 提供的特殊域名指向宿主机。这适用于 macOS/Windows 的 Docker Desktop。在 Linux 原生 Docker 环境中此域名可能无效需要替换为宿主机的实际 IP如172.17.0.1或使用network_mode: host不推荐会带来端口冲突。更可靠的方式是创建一个共享网络。LLM_MODEL和EMBEDDING_MODEL需要与 Ollama或其他兼容 OpenAI API 的服务中已拉取pull的模型名称完全一致。SECRET_KEY务必修改为一个随机的强密码用于会话加密等安全功能。DOC_STORAGE_PATH文档存储路径通过卷挂载实现数据持久化。4.3 部署并验证 RAGFlow启动 RAGFlow 服务sudo docker compose up -d ragflow查看启动日志确认没有错误sudo docker compose logs -f ragflow等待片刻当看到日志中出现类似Application startup complete或Uvicorn running on http://0.0.0.0:9380的信息时表示服务已启动。通过健康检查接口验证服务curl http://localhost:9380/v1/health如果返回{status:healthy}或类似信息说明 RAGFlow 核心服务已正常运行。5. 部署本地 LLM 与 Embedding 服务以 Ollama 为例为了让 RAGFlow 完全在本地工作我们需要一个提供 LLM 和 Embedding 模型 API 的服务。Ollama 是一个简单易用的工具。5.1 安装并运行 Ollama请根据 Ollama 官方文档在宿主机上安装。以 Linux 为例curl -fsSL https://ollama.com/install.sh | sh安装后启动 Ollama 服务ollama serve # 或者使用 systemd 管理sudo systemctl enable ollama sudo systemctl start ollama5.2 拉取所需的模型Ollama 需要先拉取模型文件。我们拉取一个常用的 7B 参数聊天模型和一个嵌入模型。# 拉取一个对话模型例如 Qwen2.5 ollama pull qwen2.5:7b # 拉取一个嵌入模型例如 nomic-embed-text ollama pull nomic-embed-text注意模型拉取需要较长时间和大量磁盘空间约 4-8GB 每个。请确保网络通畅和磁盘空间充足。5.3 验证 Ollama APIOllama 默认在11434端口提供兼容 OpenAI API 的接口。验证其是否工作curl http://localhost:11434/api/tags应返回已拉取模型的列表。也可以测试一下生成接口curl http://localhost:11434/api/generate -d { model: qwen2.5:7b, prompt: Hello, stream: false }5.4 调整 RAGFlow 连接配置针对 Linux Docker如前所述在 Linux 环境下Docker 容器可能无法通过host.docker.internal访问宿主机服务。我们需要找到正确的 IP。方案一使用宿主机桥接网络 IP查看docker0网桥的 IPip addr show docker0 | grep inet通常为172.17.0.1。然后将docker-compose.yml中 RAGFlow 的环境变量改为LLM_API_BASE: http://172.17.0.1:11434 EMBEDDING_API_BASE: http://172.17.0.1:11434方案二使用自定义网络和别名创建一个自定义网络并将 Ollama 也容器化部署在其中是更优雅和可移植的方案。修改docker-compose.yml为现有网络添加name属性并添加 Ollama 服务networks: ragflow-net: name: ragflow-net # 显式命名网络 services: # ... 其他服务定义 ... ollama: image: ollama/ollama:latest container_name: ragflow-ollama restart: unless-stopped volumes: - ./ollama_data:/root/.ollama # 持久化模型数据 networks: - ragflow-net # 注意Ollama 容器内端口是 11434我们不需要映射到宿主机仅供内部服务访问修改 RAGFlow 服务的环境变量指向容器名ragflow: # ... environment: LLM_API_BASE: http://ollama:11434 EMBEDDING_API_BASE: http://ollama:11434 # ... networks: - ragflow-net修改 MySQL 和 Milvus 服务也连接到ragflow-net。重启所有服务sudo docker compose down sudo docker compose up -d采用方案二后所有服务都在同一个 Docker 网络内通过容器名互访更加稳定。6. 访问 Web UI 与初步功能验证RAGFlow 提供了开箱即用的 Web 界面。访问界面打开浏览器访问http://你的服务器IP:9380。你将看到 RAGFlow 的登录/注册界面。初始账号首次访问需要注册一个管理员账号。创建知识库登录后尝试创建一个新的知识库Knowledge Base。上传文档在知识库中上传一个测试文档如 TXT、PDF、Word 文件。解析与切分RAGFlow 会自动进行文档解析、文本切分。向量化点击“开始解析”或类似按钮RAGFlow 会调用配置的 Embedding 模型将文本块转化为向量并存入 Milvus。问答测试在问答界面针对文档内容提问系统会从 Milvus 中检索相关片段并发送给 LLM 生成答案。如果以上步骤都能成功执行恭喜你一个完整的本地化 RAGFlow 系统已经部署完成。7. 常见问题排查清单部署过程很少一帆风顺。下表列出了从部署到初步使用中可能遇到的典型问题及排查思路。问题现象可能原因检查方式处理建议Docker 容器启动失败端口冲突、镜像拉取失败、配置错误sudo docker compose logs [服务名]查看具体错误日志。根据日志调整配置如修改端口、检查网络、确认镜像名称。RAGFlow 健康检查失败MySQL/Milvus 未就绪、连接配置错误1. 检查依赖容器是否运行正常 (docker compose ps)。2. 进入 RAGFlow 容器手动测试连接curl mysql:3306,curl milvus-standalone:19530。确保依赖服务健康检查通过后再启动 RAGFlow。检查环境变量中的主机名、端口、密码是否正确。上传文档后解析失败文档格式不支持、解析器依赖缺失查看 RAGFlow 容器日志中关于文档解析的错误信息。RAGFlow 镜像已内置常见解析器。确认文档非损坏、非扫描图片。对于极特殊格式可能需要自定义解析器。向量化Embedding失败Embedding 模型服务连接失败、模型未加载1. 检查 RAGFlow 日志中调用 Embedding API 的错误。2. 验证 Ollama 服务是否运行且模型已拉取curl http://ollama:11434/api/tags。确认EMBEDDING_API_BASE和EMBEDDING_MODEL配置正确。在 Ollama 中确认模型名称拼写无误。问答时返回“找不到答案”或无关答案检索相关度低、LLM 生成问题、提示词问题1. 检查检索到的文本片段是否相关查看问答界面的“引用”或“来源”。2. 测试 LLM 基础对话是否正常。调整知识库的文本切分策略块大小、重叠度。尝试不同的 Embedding 模型。检查 LLM 模型是否适合问答任务。Web UI 无法访问防火墙限制、端口未映射、容器未运行1.sudo docker compose ps确认容器状态。2. sudo netstat -tlnpgrep 9380 查看端口监听情况。3. 检查服务器安全组/防火墙规则。性能慢文档处理/问答资源不足CPU/内存、模型首次加载使用docker stats查看容器资源占用。观察日志中耗时步骤。升级服务器配置。对于生产环境考虑使用 GPU 加速 Embedding 和 LLM 推理。确保模型已加载到内存。8. 生产环境部署建议与优化方向将 RAGFlow 用于生产环境需要考虑更多因素。配置外置与安全不要将密码等敏感信息硬编码在docker-compose.yml中。使用 Docker Secrets 或环境变量文件.env。创建独立的配置文件并通过卷挂载到容器中便于管理和版本控制。服务高可用MySQL考虑主从复制或使用云数据库服务。Milvus单机版不适合高并发生产环境。应部署 Milvus 集群至少包含协调节点、数据节点、查询节点等。RAGFlow可以部署多个实例通过 Nginx 等负载均衡器进行分发。存储与备份将storage、mysql_data、milvus_data等卷挂载到高性能、高可靠的存储设备上。建立定期的数据库和向量数据库备份策略。监控与日志为 Docker 容器配置日志轮转避免日志占满磁盘。集成 Prometheus 和 Grafana 监控容器资源使用率、服务健康状态和业务指标如问答延迟、吞吐量。收集并集中管理应用日志便于问题追踪。性能优化GPU 加速如果处理大量文档或高并发问答为 Ollama或其他推理框架配置 GPU 可以极大提升 Embedding 和 LLM 生成速度。缓存对频繁访问的文档片段或相似问题的答案引入缓存机制如 Redis减轻向量检索和 LLM 负担。索引优化根据数据特性调整 Milvus 的索引类型如 IVF_FLAT, HNSW和参数在召回率和查询速度间取得平衡。模型选择Embedding 模型根据中文/英文场景选择针对性的模型如bge-large-zh-v1.5对于中文效果更好。LLM 模型在效果、速度和资源消耗之间权衡。7B 模型适合入门和中等负载13B/34B/70B 模型效果更好但资源需求呈指数增长。部署完成只是第一步接下来可以根据业务需求深入探索 RAGFlow 的高级功能如自定义解析器、复杂检索策略混合搜索、重排序、多路召回、对话历史管理等以构建更强大、更智能的企业级知识问答系统。