RAGFlow 部署与知识库搭建全流程

适用场景

手上有一批 PDF、Word、Excel、扫描件混杂的内部资料，想让 AI 基于这些资料回答问题，但直接用通用大模型会答错、编造。RAGFlow 是一套开源的AI 词典：检索增强生成">检索增强生成引擎，特点是内置了较完整的文档解析能力（版面识别、表格识别、OCR），适合把"格式很乱的真实文档"变成可检索的知识库。这套方案适合有一定 Linux 基础、能操作 Docker 的开发者或运维人员，个人机器和公司内网服务器都能跑。

环境与前置条件

硬件建议

• CPU：4 核起步，8 核以上体验更顺；建议确认 CPU 支持 AVX 指令集（文档解析里的深度学习组件依赖它）
• 内存：16GB 起步，32GB 更稳。内置的检索组件和文档解析模型都吃内存，8GB 机器基本跑不动
• 磁盘：50GB 以上可用空间，文档多、扫描件多的话按每千页 2～5GB 预留
• GPU：可选。有 NVIDIA 显卡并且装好驱动与容器工具包，可以换成 GPU 版镜像加速解析，纯 CPU 也能用

软件要求

• 64 位 Linux（Ubuntu / Debian / CentOS 系均可），macOS 也能跑但性能一般
• Docker 与 Docker Compose 插件（能执行 docker compose version）。具体版本以 Docker 官方文档当前版本为准
• Git
• 能访问外网拉取镜像；内网环境需要提前把镜像同步到私有仓库

内核参数：内置检索组件要求 vm.max_map_count 不低于 262144，这是部署阶段最常见的坑，先改好。

分步骤部署

第 1 步：调整内核参数

```bash

查看当前值

sysctl vm.max_map_count

临时生效（重启失效）

sudo sysctl -w vm.max_map_count=262144

永久生效

echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

sudo sysctl -p

```

再确认一下 CPU 是否支持 AVX：

```bash

grep -m1 -o avx /proc/cpuinfo

```

有输出（打印出 avx）就说明支持；什么都没有的话，文档解析部分可能会异常。

第 2 步：安装 Docker 与 Compose

```bash

curl -fsSL https://get.docker.com | sudo sh

sudo systemctl enable --now docker

让当前用户免 sudo 使用 docker（重新登录后生效）

sudo usermod -aG docker $USER

```

验证：

```bash

docker version

docker compose version

```

两条命令都能正常输出版本信息即为成功。装好后建议顺手配置镜像加速，编辑 /etc/docker/daemon.json：

```json

{

"registry-mirrors": ["https://<你的镜像加速地址>"]

}

```

然后 sudo systemctl restart docker。加速地址请用你所在网络环境可用的服务，以对应服务商当前说明为准。

第 3 步：获取代码

```bash

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

cd ragflow/docker

```

仓库结构和默认配置会随版本变化，操作前先看一眼官方文档的部署章节。

第 4 步：修改配置文件

```bash

cp .env .env.bak

vi .env

```

需要关注的几项（不同版本字段名可能略有差异）：

• RAGFLOW_IMAGE：镜像名与 tag，改成你要用的版本。tag 不要在教程里照抄，去官方文档或镜像仓库确认当前可用 tag
• SVR_HTTP_PORT：Web 访问端口，默认 80。80 被占用就改成 8080 之类
• DOC_ENGINE：检索后端，可选 elasticsearch / opensearch / infinity，按官方文档说明选一个即可
• MEM_LIMIT：给检索后端的内存上限。默认值通常偏大，小内存机器要按实际内存往下调
• TIMEZONE：设成 Asia/Shanghai，日志时间对得上

改完保存。如果你的服务器内存只有 16GB，把 MEM_LIMIT 调到 6G 左右比较稳妥。

第 5 步：启动服务

```bash

cd ~/ragflow/docker

docker compose up -d

```

首次启动要拉镜像，几分钟到十几分钟都正常。启动后看状态：

```bash

docker compose ps

```

预期：一排容器都是 Up 或 running。再跟踪主服务日志：

```bash

docker compose logs -f ragflow-server

```

看到类似 "Running on all addresses" 或服务已就绪的提示，说明 Web 服务起来了。按 Ctrl+C 退出日志跟踪，容器不受影响。

第 6 步：初始化账号

浏览器打开 http://<服务器IP>:<SVR_HTTP_PORT>，注册一个账号。首次注册的账号通常就是管理员账号，注册完用这个账号登录。

第 7 步：接入模型

进「设置 → 模型提供商」，添加对话模型和嵌入模型。两种常见接法：

• 云端 API：选对应厂商，填入 API Key 和 Base URL。任何 OpenAI 兼容接口都可以按这个方式接
• 本地模型：如果用宿主机上的 Ollama，Base URL 填 http://host.docker.internal:11434，容器内用这个地址才能访问到宿主机

添加完，把 Embedding 模型设为默认。注意：嵌入模型一旦被知识库使用并完成解析，中途换模型会导致已有向量失效，需要重新解析。 所以第一次就选好。

第 8 步：创建知识库并解析文档

1. 左侧「知识库 → 创建知识库」，填写名称，选择分块方法（Chunk method）

2. 上传文件，点击「解析」

分块方法的选择直接决定检索效果，常见对应关系：

选错分块方法的典型后果：把一份问答对照的文档按 General 切，问题和答案被切到不同块里，检索时只能召回半截，回答自然不准。

解析进度在页面上可见。解析完成后，点开文档能看到「切片」（chunk）列表，这是后面调优的关键入口。

验证部署是否成功

第一层：容器层面

```bash

cd ~/ragflow/docker

docker compose ps

```

所有服务都是运行状态，没有反复重启的容器。

第二层：接口层面

```bash

curl -I http://127.0.0.1

```

返回 200 或 302 都算正常（302 通常是没有登录时跳转登录页）。如果返回 Connection refused，说明 Web 容器没起来，回去看 docker compose logs ragflow-server。

第三层：业务层面（最重要）

传一份 10 页以内的测试文档进去，解析完成后打开切片列表，人工扫一眼：段落有没有被切断、表格有没有散架、标题有没有丢失。然后在聊天页提一个文档里明确写了答案的问题，看引用来源是否正确指向那份文档。

三层都通过，才算真正部署成功。

常见报错与解决

报错 1：max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

• 原因：检索后端对内存映射区域数量的要求没满足
• 解决：

```bash

sudo sysctl -w vm.max_map_count=262144

docker compose down && docker compose up -d

```

报错 2：Ports are not available: exposing port TCP 0.0.0.0:80 ... address already in use

• 原因：80 端口被 Nginx、Apache 或其他服务占用
• 解决：先查占用 sudo ss -lntp | grep :80，要么停掉占用方，要么改配置

```bash

vi .env # SVR_HTTP_PORT=8080

docker compose down && docker compose up -d

```

报错 3：容器状态是 Exited (137)

• 原因：137 通常是被 OOM Killer 杀掉，内存不够
• 解决：加内存或下调检索后端内存上限

```bash

free -h

vi .env # 调小 MEM_LIMIT

docker compose down && docker compose up -d

```

报错 4：拉镜像时报 TLS handshake timeout 或长时间卡住

• 原因：网络到镜像仓库不通
• 解决：配置 registry-mirrors 后重启 Docker，或改用内网私有仓库地址

```bash

sudo systemctl restart docker

docker compose pull

```

报错 5：文档解析长时间停在解析中，或提示解析失败

• 原因：文件加密、体积过大、扫描件需要 OCR 但内存不足，或磁盘写满
• 解决：

```bash

df -h # 先看磁盘

docker compose logs --tail=200 ragflow-server

```

加密 PDF 先解密；扫描件确认 OCR 组件正常；超大文件拆成几个小文件再试。

后续维护

备份

需要备份三部分：docker/.env 和 compose 文件、数据库数据卷、对象存储数据卷。数据卷用 docker volume ls 查看，常见命名带项目前缀。备份动作要在停止服务或至少低峰期做：

```bash

docker compose stop

sudo tar -czf ragflow-backup-$(date +%F).tar.gz /var/lib/docker/volumes/<项目前缀>_*

docker compose start

```

重要知识库建议同时在界面里导出切片文本作为第二份留底。

升级

```bash

cd ~/ragflow/docker

docker compose down

cd .. && git pull

按官方文档核对 .env 与 compose 文件是否有新增字段

cd docker

docker compose pull

docker compose up -d

```

升级前一定先备份。跨大版本升级时，若官方文档提示需要数据迁移，按文档执行，不要直接跳过。

日志与监控

• 查日志：docker compose logs --tail=200 ragflow-server，需要实时跟踪加 -f
• 盯磁盘：向量库和对象存储增长很快，df -h 建议做成定时巡检
• 盯内存：docker stats 看各容器占用，接近上限时提前扩容
• 盯容器：把「某个容器不在运行状态」做成告警规则，比人工定期看更靠谱

日常调优的重点

知识库跑起来之后，真正花时间的在检索效果上。三个高频动作：

1. 看切片：检索不准，先回到切片列表看切得对不对，多数问题出在这一步，而不是参数

2. 调相似度阈值：检索不到就往下调，误召回太多就往上调；关键词相似度权重用于平衡语义匹配和字面匹配，术语、型号、编号多的场景可以适当提高

3. 上重排模型：文档多、检索质量要求高时，接一个 Rerank 模型，对召回结果重排序，效果提升通常比反复微调阈值明显

按「先看切片、再调参数、最后加重排」的顺序排查，多数检索问题都能收敛。