RAGFlow VPS 部署教程：文档解析、向量库和知识库实践

RAGFlow 是 Infinigence AI 开源的知识库引擎，主打文档解析和检索增强生成（RAG）。如果你需要在 VPS 上搭建一个能处理 PDF、Word、Excel 等复杂文档的知识库系统，RAGFlow 比 LangChain 自带的 RAG 方案更省心——它内置了版面分析、表格识别、公式提取，解析效果接近商用产品。主机选在实测中发现，RAGFlow 对 VPS 配置有一定要求，尤其是内存和 CPU，但部署流程并不复杂。本文带你从零开始，在 VPS 上部署 RAGFlow，跑通文档解析、向量库和知识库全流程，并附上常见坑点。

一、RAGFlow VPS 部署前的准备工作

1.1 硬件配置建议

RAGFlow 默认使用 Elasticsearch 作为向量库，同时需要运行后台服务。实测最低配置：

•CPU：2 核以上（推荐 4 核）

•内存：4GB 起步（8GB 更稳，文档多时内存会飙）

•磁盘：20GB 以上（SSD 优先，ES 写索引吃 I/O）

•系统：Ubuntu 22.04 / Debian 12，CentOS 7 也行但踩坑多

如果 VPS 内存只有 2GB，建议先关掉其他服务，或者用 Docker 限制资源（后面会讲）。

1.2 安装 Docker 和 Docker Compose

RAGFlow 官方推荐 Docker 部署。别手动编译，版本迭代快，Docker 一键最省事。

sudo apt update && sudo apt upgrade -y

curl -fsSL https://get.docker.com | bash

docker compose version
sudo apt install docker-compose-plugin

1.3 克隆 RAGFlow 仓库并配置环境

git clone https://github.com/infiniflow/ragflow.git
cd ragflow

cp .env.example .env

编辑 `.env` 文件，至少改两个地方：

• `RAGFLOW_IMAGE`：官方镜像 tag，建议用 `v0.14.0` 或最新稳定版（去 GitHub Releases 看）

• `SVR_HTTP_PORT`：默认 9380，如果 VPS 上已有服务占用，改成 8080 或 8888

• `MYSQL_PASSWORD`：改成一个强密码，别用默认

• `ES_PASSWORD`：同理

nano .env

老鸟叮嘱：`.env` 里的 `RAGFLOW_IMAGE` 不要留空，否则 docker compose 会拉取 latest，latest 可能不稳定。建议写死版本号。

二、启动 RAGFlow 服务

2.1 启动所有容器

docker compose -f docker-compose.yml up -d

docker compose logs -f

看到类似 `ragflow-server | INFO: Started server process [1]` 说明服务跑起来了。如果报错 `no matching manifest for linux/arm64`，说明你的 VPS 是 ARM 架构（比如 Oracle 免费 ARM），需要换用官方 ARM 镜像：在 `.env` 里把 `RAGFLOW_IMAGE` 改成 `infiniflow/ragflow:latest-arm64`（或对应 tag）。

2.2 检查服务状态

docker compose ps

正常情况下应该有 4 个容器：`ragflow-server`、`mysql`、`elasticsearch`、`ragflow-es`（或类似名称）。如果 `elasticsearch` 启动失败，多半是内存不足，可以调整 ES 的 JVM 堆大小。

2.3 放行端口并访问

默认端口 9380，在 VPS 防火墙（ufw / firewalld）和云平台安全组放行。

sudo ufw allow 9380/tcp

访问 `http://你的VPSIP:9380`，首次打开会进入初始化页面，设置管理员账号密码（邮箱随意，用 admin@ragflow.com 也行）。

三、文档解析与知识库实践

3.1 创建知识库

登录后，点击「知识库」→「新建知识库」：

•名称：随便起，比如“技术文档库”

•解析方法：选“通用”（支持 PDF、Word、Excel、PPT、TXT、图片等）

•分块策略：默认按段落分块，长度 512 字符。如果你文档格式复杂（含表格、代码），建议选“智能分块”，RAGFlow 会分析版面。

3.2 上传文档并解析

点击知识库名称进入，点「上传文档」，支持拖拽或选择文件。上传后系统自动进入解析队列。

解析过程会调用内置的 OCR 和版面分析模型，CPU 占用会飙升。如果是 2 核 VPS，建议一次只上传 3-5 个文档，不要一次性塞几百个。

常见坑：解析失败时，先看日志：

docker compose logs ragflow-server | grep -i error

常见原因：

• 文档损坏或密码保护

• 中文字体缺失（VPS 上没装中文字体包）

• 内存不足导致解析进程被 kill

3.3 向量库配置

RAGFlow 默认使用 Elasticsearch 作为向量库，同时支持 Milvus（需额外配置）。在知识库设置里可以选「向量模型」：

• 本地模型：RAGFlow 自带 `BAAI/bge-large-zh-v1.5`（中文效果好），但需要下载模型文件，首次启动会拉取，比较慢。

• 远程 API：可以用 OpenAI、DeepSeek、通义千问等 Embedding API，速度更快，适合低配 VPS。

如果你 VPS 内存只有 4GB，建议选远程 API，否则本地模型 + ES 一起跑很容易 OOM。

3.4 测试检索效果

在知识库页面点击「测试」，输入问题，看召回结果。如果召回内容不相关，调整分块大小或换向量模型。RAGFlow 支持调整检索参数（TopK、相似度阈值），一般保持默认即可。

四、接入 AI Agent 或自动化工作流

4.1 配置 API Key 和模型

进入「设置」→「模型提供商」，添加 LLM（比如 OpenAI、DeepSeek、Claude）：

•API Key：从对应平台获取，注意不要暴露在公网

•模型名称：比如 `gpt-4o-mini`、`deepseek-chat`

•Base URL：如果使用代理，填写代理地址

4.2 构建对话应用

点击「聊天」→「新建应用」：

•知识库绑定：选择刚才创建的库

•提示词：可以写“你是一个技术顾问，根据知识库内容回答”

•模型：选择已配置的 LLM

保存后获得一个聊天 URL，可以直接在浏览器测试。也可以获取 API 接口，接入 n8n、Claude Code 等自动化工具。

老鸟叮嘱：不要把 API Key 硬编码在前端页面，RAGFlow 的 API 支持 Bearer Token 鉴权，生产环境务必开启 HTTPS 并限制 IP。

五、老鸟叮嘱：避坑指南

1.内存不够怎么办？
编辑 `docker-compose.yml`，给 ES 和 RAGFlow 容器加 `mem_limit`。例如 `mem_limit: 2g`。同时关掉不必要的服务。

2.解析中文 PDF 乱码？
安装中文字体包：

sudo apt install fonts-noto-cjk

然后重启容器：`docker compose restart ragflow-server`

3.Elasticsearch 启动失败？
检查 `/etc/security/limits.conf`，增加 `elasticsearch` 用户的 `nofile` 和 `memlock` 限制。或者用 Docker 的 `ulimits` 配置。

4.知识库检索结果为空？
检查向量模型是否正常加载，在日志里搜 `embedding`。如果用的是远程 API，确认 API Key 有效且网络通。

5.端口冲突？
RAGFlow 默认使用 9380（前端）、3306（MySQL）、9200（ES）。如果 VPS 上已有 MySQL，把 `.env` 里的 MySQL 端口映射改掉，比如 `MYSQL_PORT=3307:3306`。

六、FAQ

Q1：RAGFlow 支持哪些文档格式？
A：PDF、Word、Excel、PPT、TXT、图片（含 OCR）、Markdown。不支持加密 PDF 和 WPS 专有格式。

Q2：2 核 4GB VPS 能跑 RAGFlow 吗？
A：勉强能跑，但只能处理小规模文档（几十页），且必须用远程 Embedding API，关闭 ES 的 X-Pack 安全模块以节省内存。建议至少 4 核 8GB。

Q3：RAGFlow 和 Open WebUI 有什么区别？
A：Open WebUI 偏向聊天界面和模型管理，RAGFlow 专注文档解析和知识库 RAG。两者可以配合使用：RAGFlow 做知识库，Open WebUI 做前端。

Q4：如何把 RAGFlow 知识库接入 n8n？
A：通过 RAGFlow 的 API 接口（`/api/v1/retrieval`），在 n8n 中用 HTTP Request 节点发送 POST 请求，携带 query 和知识库 ID。

Q5：向量库可以换成 Milvus 吗？
A：可以，RAGFlow 支持切换向量库类型。修改 `.env` 里的 `DOC_ENGINE=elasticsearch` 为 `milvus`，并配置 Milvus 连接信息。但 Milvus 比 ES 更吃内存，低配 VPS 不建议。

Q6：RAGFlow 部署后怎么升级？
A：备份 `.env` 和 `docker-compose.yml`，然后 `git pull` 拉取最新代码，修改 `.env` 里的镜像 tag，最后 `docker compose pull && docker compose up -d`。

总结

RAGFlow 在 VPS 上部署并不复杂，核心是搞定 Docker 和配置好模型。文档解析能力很强，尤其适合需要处理复杂版面的企业知识库场景。内存是瓶颈，低配 VPS 建议用远程 API 并限制容器资源。主机选实测下来，只要避开那几个常见坑，RAGFlow 跑起来很稳，配合 n8n 或 AI Agent 能实现不少自动化工作流。

—

**相关阅读：**

– [VPS部署AI工具100讲：AI Agent、Codex、Claude Code、Hermes Agent、Ollama与自动化工作流实战教程](https://www.zhujixuan.com/jishujiaocheng/9606.html)
– [n8n VPS 部署教程：搭建自己的自动化工作流平台](https://www.zhujixuan.com/jishujiaocheng/9892.html)
– [AI Agent自动化运维实战100讲：VPS巡检、日志分析、告警处理与工作流教程](https://www.zhujixuan.com/jishujiaocheng/10066.html)