最近团队内部攒了一堆产品文档、会议纪要和售后 FAQ，散落在各种共享目录里，每次找资料都要翻半天。于是大家把目光投向了这两年很火的 RAG（检索增强生成）技术，想搭一个"私有知识库"——把内部资料全部丢进去，之后问什么问题，它都能基于这些资料给出带出处的回答。RAGFlow 是目前开源社区里把这件事做得最省心的项目之一，部署起来也不复杂。这篇教程我从环境准备到跑通第一轮问答完整走了一遍，把关键配置和踩过的坑都整理出来，给同样想搞私有知识库的朋友做个参考。
1. 为什么选 RAGFlow：私有知识库不是"向量库加聊天框"那么简单
1.1 传统 RAG 方案的常见翻车点
很多人一开始想的方案是：把文档切成小块 → 用向量模型转成向量 → 存进向量数据库 → 用户提问时检索最相关的几块 → 丢给大模型生成回答。这个链路听起来很顺，但真正落地后问题会一个接一个冒出来。
最典型的是切块切碎了上下文。一份 PDF 里明明是一张跨页的表格，要是按固定字符数硬切，表格被拦腰截断，检索到的"答案"就是半张表，大模型拿到这种残缺上下文，只能一本正经地编。还有多栏排版、页眉页脚、脚注、图文混排，按纯文本提取基本等于直接放弃这些内容。其次是答案没有出处，模型答错了你都不知道它依据的是哪段内容，排查起来很痛苦。更别提很多方案要自己写一套文档解析、入库、检索、UI 的代码，还没跑到问答环节，人先被预处理脚本耗干了。
我见过不少团队折腾了好几个月自研 RAG，最后效果还不如一个配置得当的开源项目。原因很简单：RAG 的瓶颈往往不在大模型，而在"文档理解"这一步——资料都没读明白，检索和生成自然全崩。
1.2 RAGFlow 的核心理念：深度文档理解
RAGFlow 和那些"给你一个向量库 + 聊天窗口"的方案最大的区别，是它把深度文档理解放在了核心位置。它内置的文档解析引擎不是简单把 PDF 转成文本，而是先做版面分析：识别出标题层级、正文区块、表格结构、图片位置、阅读顺序，甚至能处理扫描件的 OCR。
我起初对这个说法将信将疑，直到拿了一份带复杂三层表头的季度报表去试。传统切块把表头拆得七零八落，而 RAGFlow 解析后保留了完整的表格结构和行列关系，后续检索能直接定位到"某部门某季度"对应的数据行。这种"先理解文档，再决定怎么切"的思路，解决的是 RAG 链路中"垃圾进、垃圾出"的根源问题。
另外，RAGFlow 在检索和生成环节也做了不少工程化的设计：答案会带引用标注，每句话都能回溯到具体的切片和原始文档；知识库支持多种切块模板；底层存储和中间件全部容器化，部署是一套完整的方案而不是拼积木。
1.3 几个"用一次就回不去"的能力
真正用起来之后，有几个细节是我觉得最值回票价的：
答案带引用，可溯源。这是我最看重的一点。模型回答的每一条结论后面会挂上引用标记，点开就能看到命中的文档切片，甚至能定位到原文档的对应区域。对内部知识问答来说，这几乎解决了"不知道它为什么这么说"的信任问题。
切片可以人工干预。文档解析完进入知识库后，可以逐个切片查看、修改、删除。某些关键文档，我可以手动调整切片的边界，确保每块内容语义完整。这比纯自动切块灵活太多了。
切块模板丰富。普通文档、问答对、连续文本用不同的模板处理，后面会细讲。
自带完整界面。知识库管理、文档解析状态、聊天问答都在网页里完成，团队成员不需要懂技术就能用。
1.4 谁适合部署它
部署它之前，建议先对照一下自己的场景。如果你有大量格式复杂的内部文档（PDF、Word、PPT、表格），想让团队通过自然语言检索这些资料，又对数据私密性有要求，那它是非常合适的选择。如果你只想把公司官网 FAQ 接进公众号自动回复，或者只有几篇 Markdown 笔记想做个问答玩具，这项目就有点重了——毕竟它要跑一整套中间件，至少需要 16G 内存的机器，小场景用更轻的方案反而划算。
2. 部署前的环境规划：硬件、系统与目录设计
2.1 硬件门槛怎么算
先给个结论：官方说最低 4 核 CPU、16G 内存、50G 磁盘，这个配置能跑起来，但只是"能跑"的级别。为什么这么吃内存？因为部署的不是一个进程，而是一整套服务：应用服务本身、Elasticsearch 负责全文和向量检索、MySQL 存元数据、MinIO 存文件、Redis 做缓存。
| 场景 | CPU | 内存 | 磁盘 | 说明 |
|---|---|---|---|---|
| 最低可用 | 4 核 | 16G | 50G | 跑通全流程，解析大数据量文档会比较慢 |
| 舒适体验 | 8 核 | 32G | 100G+ | 团队内部日常使用，文档解析速度可接受 |
| 本地也要跑大模型 | 16 核+ | 64G | 200G+ | 对话模型和向量模型全本地化部署 |
磁盘是很多人忽略的点。文档解析后要存原始文件、切片、向量索引，加上 Elasticsearch 的索引文件，积累几个月很容易到几十 G。建议预留的空间给足，后面不用再折腾扩容。
如果打算在同一台机器上本地跑对话大模型，内存预算直接往 64G 走，或者至少保证有一块不错的显卡。没有 GPU 的话，本地跑 7B 模型也能用，但并发一高就明显卡顿。
2.2 Docker 环境检查
部署基于 Docker Compose，所以第一步是把 Docker 环境准备好。我建议使用 Ubuntu 22.04 这类主流 Linux 发行版，安装 Docker Engine 和 Docker Compose v2 插件。Compose v1（docker-compose 命令）和新版语法有差异，项目要求 v2，装好之后先验证一下：
docker --version docker compose version如果 docker compose 命令提示找不到，说明 Compose 插件没装好；如果只有 docker-compose（带横杠）的旧版，建议升级。顺手把 CPU、内存、磁盘也确认一遍：
nproc free -h df -h /这一步别跳过。我遇到过在虚拟机上分配了 16G 内存，但实际宿主机只剩 8G 的情况，docker 容器启动后过一会儿就被 OOM 杀掉，排查了半天才发现是资源分配的问题。
2.3 端口与挂载目录
RAGFlow 默认把 Web 控制台挂在 80 端口，SSL 是 443，内部后端服务监听 9380。除此之外，Elasticsearch、MySQL、MinIO、Redis 也都会占用内部端口，不过这些一般不需要对外暴露。
部署前想清楚 80 端口是否空闲。如果机器上已经跑了 Nginx 或别的 Web 服务，先把端口规划好，后面我会说怎么改端口。
数据持久化方面，项目的 docker 部署目录下会生成 nginx、ragflow 等数据目录，存放日志、上传的原始文档、MinIO 的对象数据。这些目录和 .env 配置文件是整个部署的灵魂，备份、迁移、升级全靠它们。建议统一放到一个清晰路径下，比如 /opt/ragflow，方便日后维护。
2.4 虚拟机部署的特殊注意事项
很多朋友喜欢先在虚拟机里试，这没问题，但有两个坑提前说一下。
第一个是内存预留。虚拟机软件默认会给系统动态分配内存，但如果你在虚拟机设置里只给了 8G，那不管里面怎么调都是这个上限。16G 的要求，指的是虚拟机本身分配到的内存，别被宿主机的总量误导。
第二个是嵌套虚拟化。如果你是在云服务器上再套一层虚拟化环境跑 Docker，磁盘 IO 和网络性能都会打折扣，文档解析会明显变慢。普通测试无所谓，生产使用最好直接上物理机或独立云主机。
如果你是 Windows / macOS 上用桌面版 Docker，需要注意容器内访问宿主机的方式和 Linux 上不一样，这个问题在接入本地大模型那一步会重点讲，先记个印象即可。
3. 正式部署：一条命令起服务
3.1 拉取项目与进入部署目录
先把官方仓库拉到服务器上。仓库地址以项目主页的说明为准，这里用占位符表示：
git clone <项目仓库地址> cd ragflow/docker进入 docker 目录后，你会看到一堆 docker-compose 文件和 env 示例文件。部署的入口就是这里。项目默认提供的 compose 文件会一次性拉起所有依赖服务，不需要你手动单独装 Elasticsearch 或 MySQL。
3.2 修改 .env 的几个关键项
部署配置集中在 .env 文件里。先复制示例文件再改：
cp .env.example .env vi .envenv 文件内容不少，但实际要动的就几个地方：
# 使用哪个镜像版本 RAGFLOW_IMAGE=infiniflow/ragflow:v0.19.1 # Web 控制台对外端口 RAGFLOW_PORT=80 RAGFLOW_HTTPS_PORT=443 # 内部服务端口，一般不用动 SVR_HTTP_PORT=9380 # 数据库等中间件的默认密码，部署完记得改 MYSQL_PASSWORD=infini_rag_flow MINIO_PASSWORD=infini_rag_flow镜像版本建议固定到具体版本号，不要用 latest。我吃过 latest 的亏：某次升级后镜像 tag 指向了新版本，compose 重新拉镜像后中间件行为变了，排查了很久才发现是版本差异。固定版本号，哪天要升级也是主动操作，可控得多。
端口如果和现有服务冲突，在 RAGFLOW_PORT 处改成别的，比如 8080。改完保存后，后续访问地址就变成 http://服务器IP:8080。
3.3 启动、等待与健康检查
配置没问题就可以启动了：
docker compose up -d第一次启动会拉取镜像，包括应用镜像和 Elasticsearch、MySQL、MinIO、Redis 等依赖。镜像体积不小，加上网络带宽因素，等个十几分钟很正常。这个阶段别急，更别反复重启。
启动后观察容器状态：
docker compose ps docker compose logs -f ragflow-server看到日志里出现类似"服务启动完成"或接口监听成功的提示，基本就绪了。此时在浏览器打开 http://服务器IP:80（或你指定的端口）。如果看到 502 之类的错误，大概率是 Elasticsearch 还在初始化，再等一两分钟刷新即可。
3.4 第一次登录控制台
初始账号是 admin，初始密码是 ragflow。登录后第一件事就是去改密码。这套默认口令是公开文档里的，不改等于门户大开，尤其是部署在公网服务器时。
进入控制台后，页面主要分三块：知识库（管理文档和数据）、聊天（与知识库对话）、模型提供商（配置大模型接入）。这三块基本覆盖了整个使用链路。接下来最重要的就是接模型——这一步没做完，知识库建了也没法问答。
4. 接入大模型：知识库会不会"说话"全看这一步
4.1 为什么 RAGFlow 不自带模型
很多人第一次打开控制台会疑惑：怎么没有模型？这不是缺陷，而是有意设计。RAGFlow 定位是"知识库 + RAG 编排"层，大模型则留给用户按需选择：你可以接第三方 API 服务，也可以接本地模型，甚至某个场景用 API、另一个场景用本地模型混合搭配。这样既避免了模型捆绑，也让数据私密性要求高的团队可以选择完全本地化。
它需要两类模型：对话模型，负责最终生成回答；向量模型（Embedding），负责把文档切片转成向量用于检索。两者都要配，缺一个都跑不通。
4.2 方式一：接入第三方 API 服务
如果你有能访问的 API 模型服务（现在主流模型服务商大多提供兼容 Chat Completions 格式的标准接口），配置流程在"模型提供商"页面里就能完成：
- 选择一个兼容标准接口的模型供应商类型。
- 填写你的 API Key。
- 填写接口地址（Base URL），注意有些服务商的地址需要带版本路径，以服务商文档为准。
- 填入模型名称，这里有个坑：模型名称必须与服务商侧的模型 ID 完全一致，填"模型别名"或"展示名"都会导致连接失败。
- 点击测试，提示成功后保存。
保存后，记得在页面里把该供应商的模型分别设为"对话模型"和"向量模型"的默认项。这一步很多教程没强调，漏了的话，创建知识库时会发现没有可选的向量模型。
4.3 方式二：接入本地模型运行器
不想把文档向量和问答请求发到外部，可以跑一个本地模型运行工具。部署也很简单：在宿主机上装好本地模型运行时，下载一个 7B 左右的中文对话模型，启动后它会在本地暴露一个接口，默认端口一般是 11434 之类的。
然后在 RAGFlow 的模型提供商里，同样按兼容接口的方式配置，但要注意一个关键点：RAGFlow 跑在容器里，容器里访问宿主机不能写 localhost。localhost 在容器内指向容器自己，不是你那台物理机。正确做法是填宿主机在局域网里的 IP，比如 http://192.168.1.100:11434。
如果你是桌面版 Docker（Windows/Mac），可以直接用 host.docker.internal 这个特殊主机名指向宿主机，Linux 上则需要在 docker compose 里加 host 映射或者改用局域网 IP。这个细节如果不知道，会是新手排查半天都解决不了的"玄学问题"。
4.4 对话模型与向量模型的搭配建议
| 组合方式 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|
| 对话模型本地 + 向量模型本地 | 数据完全不出机器，隐私性最强 | 对硬件要求高，无 GPU 时响应慢 | 涉密资料、离线环境 |
| 对话模型走 API + 向量模型走 API | 效果好、部署最简单 | 文档内容会发给外部服务 | 个人测试、非敏感资料 |
| 对话模型本地 + 向量模型走 API | 回答不依赖外部，向量成本低 | 两部分依赖不同链路，配置稍多 | 企业内部常规知识库 |
向量模型的选择直接影响检索质量。处理中文文档，优先考虑中文优化的向量模型，比如 bge 系列；如果你发现检索结果老是"答非所问"，先怀疑向量模型选得不对，而不是文档没传对。
5. 创建知识库：从上传文档到第一次问答
5.1 创建时就要定死的两件事
进入"知识库"页面，新建一个知识库，此时有两个决定要做死：
第一是名称和描述，这个无所谓，后期能改。第二是向量模型，这个创建后就很难改。
为什么？因为文档入库时，切片已经用这个向量模型转成了向量并写进索引。中途换向量模型，新旧向量的语义空间不一致，检索结果必然错乱，只能重建知识库重新上传文档。所以创建前想清楚：用哪个向量模型，就和这个知识库"绑定"了。
建议按文档的语言和类型来建库：中文技术文档一个库，英文资料一个库，FAQ 单独一个库。不同库可以用不同向量模型，互不影响。
5.2 上传与解析：PDF、表格与扫描件都怎么处理
创建完知识库，直接在页面上拖拽上传文档。支持常见的 PDF、Word、PPT、Excel、TXT 等格式。
上传后系统会自动进入解析流程，重点来了：解析不是瞬间完成的。项目会先做版面分析，再抽取文本结构、识别表格、按模板切块。文档页数多、扫描件多的话，解析可能需要几分钟。
上传页里一般有解析方式的选择：普通文档用"版面分析 + 文本抽取"模式即可，扫描版 PDF 需要启用 OCR 模式。如果你发现解析出来的切片里全是乱码或空白，十有八九是扫描件没开 OCR。
解析完成后，一定要去切片预览里翻一翻：表格是不是完整保留了？段落是不是被切得离谱？这一步值得多花几分钟，因为切片质量直接决定后续检索效果。发现不合适的切片可以手动删掉或改边界，这是 RAGFlow 比纯自动方案强的地方。
5.3 切块模板的选择
RAGFlow 提供了几种切块模板，选错也会显著影响效果：
| 模板 | 适用场景 | 说明 |
|---|---|---|
| 朴素切块 | 纯文本、结构简单的笔记 | 按固定大小切，实现最简单但效果一般 |
| 通用模板 | 大部分办公文档、报告 | 结合版面结构切块，表格和段落保留完整，推荐首选 |
| 问答模板 | FAQ、客服话术 | 按"问题-答案"对切块，检索时直接命中问答对 |
| 手动模板 | 关键文档 | 完全由人工划定边界，质量最高但费人力 |
切块大小也影响很大。块太大，检索粒度粗，容易把不相关内容带进来；块太小，上下文语义不完整。常见做法是控制在 256~512 个 token 之间，保留一定的重叠（overlap），避免跨块语义断裂。具体数值要看文档类型，表格多的文档块适当大一点，FAQ 类小块更精准。
5.4 第一次提问：感受带引用的回答
进入"聊天"页面，新建一个会话，勾选刚才建好的知识库，就可以提问了。
问一个问题，你会看到回答后面跟着引用标记，点开能跳转到命中的原文切片。这是我建议每个新用户都先做一遍的操作——它让你直观看到"模型到底依据了什么内容回答"。如果回答没有引用，或者引用内容明显不对，说明检索链路有问题，往下看排查部分。
之后你还可以做多轮追问，系统会结合对话历史继续检索补全上下文。整个体验已经接近商业产品，而数据全在自己服务器上。
6. 实测调优与排错：踩过的坑一次讲完
6.1 端口被占用、容器反复重启
症状是docker compose up -d后部分容器启动失败，日志里出现"端口已被占用"或"bind: address already in use"。
处理方式：改 .env 里的 RAGFLOW_PORT 换成空闲端口，然后重新执行：
docker compose up -d注意：如果已经用旧端口启动过，需要先docker compose down再重新up，否则旧容器还在占着端口。另外也要排查宿主机的其他服务是否占用了 80/443/9380 等端口。
6.2 内存不够怎么办
如果你只有 16G 内存，跑一段时间后容器开始反复重启，多半是内存被 Elasticsearch 吃光了。ES 是内存大户，默认堆内存设置不小，在小内存机器上要主动限制。
在 .env 里调整 Elasticsearch 的 JVM 堆内存参数，把它压到 2G 左右，重启 ES 容器生效。再配合系统 swap（交换分区）兜底，大部分测试场景都能稳定运行。但生产环境不要依赖 swap，性能会很难看，老老实实加内存更靠谱。
也可以这样排查内存到底被谁吃了：
docker stats这个命令能实时看到每个容器的 CPU、内存占用，定位问题容器后针对性优化。
6.3 向量模型变更导致的"检索失败"
一个非常常见的坑：知识库创建时用了模型 A，后来你觉得模型 B 效果好，就在系统设置里改了默认向量模型，然后去聊天页面提问——结果什么都检索不到。
原因就是前面说的：库里的向量是模型 A 生成的，现在却用模型 B 去编码查询语句，语义空间不匹配。RAGFlow 的检索链路里"入库模型"和"查询模型"必须一致。
处理方法只能重建：确认好最终要用的向量模型，把原来的知识库删掉重新创建、重新上传文档，或者导入导出知识库后在新库上重建。这个坑一次就能长记性：向量模型绑定的是知识库，而不是全局默认设置。
6.4 回答质量不好？先查这三项
如果问答效果不理想，别急着换大模型，按这个顺序排查：
第一，数据本身干不干净。我遇到过一个团队怎么调都答不对，最后发现文档里全是旧版本的过期信息，模型当然照着错的答。先清理知识库里的垃圾数据，比调任何参数都有效。
第二，切片质量。去切片预览里看切出来的块是不是语义完整。如果表格被切碎、段落错位，再强的检索也救不回来。该手动调整就手动调整，或者换一种切块模板。
第三，检索参数。聊天页面通常有"检索条数"（Top N）和"相似度阈值"之类的参数。Top N 太小，相关切片漏检；阈值太高，啥都匹配不上。建议先调大 Top N，同时把阈值放宽，观察检索命中情况后再收紧。有条件的话，开启重排序（Rerank）功能，能显著提升关键内容排序的准确率，代价是响应时间变长。
6.5 数据备份与版本升级
最后说两个运维相关的话题。
备份：别忘了 .env、docker 部署目录下的数据目录（含原始文档、上传文件、MinIO 对象数据）以及 MySQL / Elasticsearch 的数据卷。最稳妥的方式是写个定时任务，把整个数据目录打包，连同 .env 一起归档。恢复前先 docker compose down，避免容器占用导致文件不一致。
升级：先看项目发布说明，确认没有破坏性变更；然后备份数据；修改 .env 里的镜像版本号，拉取新镜像后docker compose up -d逐容器滚动升级。如果升级后异常，用之前的版本号和备份目录回滚。
最后再分享一点个人体会：部署 RAGFlow 只是起点，真正决定知识库好不好用的，是数据和配置的耐心。先挑一小批高质量文档建库，跑通流程、调好切片和检索参数，再逐步扩大资料范围。比起一次性把所有资料灌进去然后面对一团乱麻，这种小步快跑的方式反而最省时间。私有知识库这件事，工具只是把赛道铺好了，跑得好不好，还得看你怎么组织自己的文档。
