做企业级应用的人大概率都遇到过这种场景业务系统里散落着几十份操作手册、制度文件、项目文档新人培训要翻半天群记录售后客服回复一个问题要打开五六个页面。这时候大家都会想到搞一个知识库把文档统一管起来再让员工用自然语言提问直接得到答案。但真的开始做就会发现“导入文档—搜索命中”这个闭环看起来简单实际落地时扯皮的点特别多切片粒度怎么定表格怎么解析追问怎么处理引用来源怎么展示更麻烦的是和现有的后台管理系统整合很多开源方案要么太重要么API太封闭。我最近在一个项目里把RuoYi和RAGFlow组合起来做了一个完整的私有化知识库。RuoYi负责用户权限、菜单管理、操作日志这些业务底座RAGFlow负责文档解析、向量检索、生成问答。整套方案下来既有现成的后台管理能力又有靠谱的RAG能力关键是所有数据都在内网不依赖外部服务。这篇文章把集成过程中的设计思路、踩坑记录、关键代码全部梳理出来给正在做类似需求的团队一个参考。1. 整体设计为什么是RuoYi RAGFlow1.1 私有化知识库的典型架构私有化知识库不是一个单点应用它至少包含三层存储层文档源文件、向量索引、关系型元数据、服务层文档解析、切片、向量化、检索、生成、应用层后台管理、问答交互、权限控制。很多团队一开始只想用向量数据库LLM API快速搭建做了Demo发现没法用因为没有管理后台、没有文档状态流转、没有权限体系。所以我的思路是让RuoYi承担应用层和一部分存储层让RAGFlow承担服务层。RuoYi本身是成熟的Java后台框架用户表、角色表、菜单表、数据权限、操作日志都是现成的直接拿来做知识库的管理端非常省事。RAGFlow则自带完整的文档解析pipeline支持PDF、Word、Excel、Markdown等多种格式能自动做版面分析、表格识别、标题层级梳理这些能力如果自己用Python从头搞至少要一两个月。1.2 为什么选择RAGFlow而不是其他方案之前也对比过Dify、FastGPT、Weaviate、Milvus这类工具。如果只是做简单的“文档检索问答”Dify上手更快界面也友好但它的设计更偏向工作流编排和业务系统的API对接反而不是强项。FastGPT的问答体验不错但文档解析能力偏弱尤其是PDF里的表格和多栏排版效果不太理想。RAGFlow最打动我的地方是它对“文档结构”的处理。它不是粗暴地把文本切成固定长度的chunk而是先做版面识别把段落、表格、页眉页脚分开再依据文档语义层级做切片。这样生成的chunk里有完整的上下文问答时引用定位也准。另外它支持对接本地嵌入模型和本地LLM这对私有化部署来说是硬指标。RAGFlow的API设计也比较规范知识库管理、文档上传、会话问答都有对应的REST接口方便RuoYi后端统一调用。1.3 集成方案的整体数据流最终落地的架构是用户在RuoYi前端上传文档RuoYi后端把文件保存到本地存储同时调用RAGFlow的API创建文档、上传文件并启动解析。解析完成后RAGFlow自动做切片和向量化RuoYi这边通过轮询或回调更新文档状态。用户提问时RuoYi后端调用RAGFlow的会话API把问题发过去RAGFlow检索相关chunk并构造提示词调用LLM生成回答然后把回答和引用来源返回给RuoYi前端展示。权限控制上RuoYi只让有权限的人访问知识库菜单但RAGFlow本身并不知道RuoYi的用户体系。我的处理方式是让RuoYi后端统一代理RAGFlow的请求不在前端直接暴露RAGFlow的API地址和密钥。这样既解决了权限问题也避免了跨域和密钥泄露的风险。2. 环境准备与RAGFlow部署2.1 硬件与依赖要求RAGFlow对机器的要求不算低官方建议最低配置是16G内存、4核CPU磁盘空间根据文档量预留。如果只是demo可以适当降低要求但生产环境建议32G内存起步尤其是还要跑本地嵌入模型和LLM的时候。操作系统我用的Ubuntu 22.04Docker和Docker Compose是必须的。RAGFlow官方提供了docker compose部署脚本但默认配置里面嵌入模型和聊天模型都指向在线API私有化环境必须改成离线模型或内网可访问的模型服务。我这边是用Ollama部署了一个本地LLM嵌入模型选了兼容OpenAI接口的本地服务。这样整个链路完全在内网不依赖外网。2.2 Docker Compose部署步骤先拉取RAGFlow的部署脚本git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker cp .env.example .env.env文件里有几个关键配置需要关注。SVR_HTTP_PORT是RAGFlow服务对外暴露的端口默认9380MYSQL_PASSWORD和REDIS_PASSWORD建议改成强密码MINIO_USER和MINIO_PASSWORD是对象存储的凭证也要改。改完直接启动docker compose -f docker-compose.yml up -d第一次启动会拉取镜像需要一些时间。启动完成后可以通过docker compose ps确认所有容器状态。正常情况下会有mysql、redis、minio、ragflow等容器在运行。RAGFlow的入口是http://IP:9380第一次访问会让你注册管理员账号。启动过程中最容易遇到的问题有两个。一个是docker compose版本太低导致配置文件里的某些语法不识别升级Docker Compose到v2版本即可。另一个是端口冲突比如宿主机上已经占了3306或者6379把.env里的MYSQL_PORT和REDIS_PORT改掉就行RAGFlow内部容器之间的通信还是走默认端口不会受影响。2.3 初始化配置与模型对接进入RAGFlow后台之后要做的第一件事是配置模型供应商。登录后点击头像进入“模型供应”页面这里支持多种协议。如果你用的是Ollama可以直接选Ollama类型填上Ollama服务的地址比如http://192.168.1.100:11434然后填模型名称例如qwen2.5:14b。注意RAGFlow需要模型具备对话和嵌入两种能力所以“聊天模型”和“嵌入模型”都要配置。嵌入模型很重要推荐选择维度适中、中文效果好的模型比如bge-m3或者bce-embedding-base_v1。如果RAGFlow的模型供应商列表里没有你想要的可以选择“OpenAI-Compatible”类型填上兼容OpenAI协议的本地服务地址。配置完之后可以进行一次“测试”连接确认模型能被正常调用。另外还有一个关键设置.env里的DOC_ENGINE默认是elasticsearch这个不用改RAGFlow的向量检索和全文检索都依赖它。如果文档量特别大可以调ELASTICSEARCH_HEAP_SIZE默认是1G调成2G或4G能减少大文档解析时的内存压力。2.4 验证RAGFlow服务是否正常部署完成后建议先用RAGFlow自带的界面做一次小规模验证。创建一个测试知识库上传一份带标题和表格的PDF等待解析完成后在“聊天”页面提问确认能返回带引用的答案。这一步走通了再接入RuoYi否则后面联调时问题会混在一起很难排查。验证时重点看两个地方文档解析状态是否变成“已完成”聊天回复是否显示引用来源。RAGFlow的解析日志可以在docker logs ragflow-server里看到如果解析失败日志里通常会有具体的异常信息。这一步稳定后再进入RuoYi侧的开发。3. RuoYi侧集成方案设计3.1 复用RuoYi的现有能力RuoYi本身提供了很好的基础设施我们没必要重复造轮子。文件上传方面RuoYi有RuoyiConfig.getProfile()本地存储路径也有基于MinIO的扩展方案。知识库的文件建议统一存放在指定目录由RuoYi的FileUploadUtils处理上传同时把文件元数据记录到自己建的库里。用户认证和权限方面直接用RuoYi的PreAuthorize注解控制接口权限。比如PreAuthorize(ss.hasPermi(knowledge:doc:upload))就能限制只有拥有该权限的用户才能调用上传接口。RuoYi的验证码机制默认登录时需要如果做内部系统想去掉在SysLoginService里把validateCaptcha的校验注释掉即可但这个会影响安全策略最好只在内网环境使用。另外RuoYi会把登录用户信息存在SecurityUtils.getLoginUser()里集成时可以在上传文档时记录操作人在问答接口里记录提问者方便后续做数据审计。3.2 数据库模型设计我新增了三张业务表知识库表、文档表、问答记录表。CREATE TABLE kb_knowledge_base ( id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) NOT NULL, description VARCHAR(500), ragflow_dataset_id VARCHAR(64) COMMENT RAGFlow侧的知识库ID, status CHAR(1) DEFAULT 0, create_by VARCHAR(64), create_time DATETIME ); CREATE TABLE kb_document ( id BIGINT PRIMARY KEY AUTO_INCREMENT, kb_id BIGINT NOT NULL, file_name VARCHAR(255) NOT NULL, file_path VARCHAR(500), file_size BIGINT, ragflow_doc_id VARCHAR(64) COMMENT RAGFlow侧的文档ID, parse_status VARCHAR(20) COMMENT UNSTART/PARSING/DONE/FAIL, chunk_num INT, create_by VARCHAR(64), create_time DATETIME ); CREATE TABLE kb_chat_record ( id BIGINT PRIMARY KEY AUTO_INCREMENT, user_id BIGINT, question TEXT, answer LONGTEXT, references_json TEXT, cost_ms BIGINT, create_time DATETIME );设计思路是RuoYi侧的表只存业务元数据不存向量。RAGFlow的知识库ID和文档ID都作为外键字段关联这样RuoYi可以直接通过API操作RAGFlow资源同时保留自己的业务状态。3.3 后端对接模块设计我在RuoYi的ruoyi-admin模块下新增了一个包com.ruoyi.web.controller.knowledge专门处理知识库相关的接口。为了避免在业务代码里到处写HTTP调用我封装了一个RagflowClient用RestTemplate或者OkHttp调用RAGFlow的API。RAGFlow的API鉴权是通过请求头里的Authorization: Bearer API_KEY实现的。API Key在RAGFlow后台的“API Key”页面生成。我不会把Key硬编码到代码里而是放到application-druid.yml或者Nacos配置中心用Value注入。RagflowClient核心方法大概是这样Service public class RagflowClient { Value(${ragflow.base-url}) private String baseUrl; Value(${ragflow.api-key}) private String apiKey; public JsonNode createDataset(String name) { String url baseUrl /api/v1/datasets; HttpHeaders headers new HttpHeaders(); headers.setBearerAuth(apiKey); headers.setContentType(MediaType.APPLICATION_JSON); MapString, Object body new HashMap(); body.put(name, name); HttpEntityMapString, Object entity new HttpEntity(body, headers); ResponseEntityJsonNode resp restTemplate.postForEntity(url, entity, JsonNode.class); return resp.getBody(); } public JsonNode uploadDocument(String datasetId, MultipartFile file) { String url baseUrl /api/v1/datasets/ datasetId /documents; HttpHeaders headers new HttpHeaders(); headers.setBearerAuth(apiKey); MultiValueMapString, Object body new LinkedMultiValueMap(); body.add(file, file.getResource()); HttpEntityMultiValueMapString, Object entity new HttpEntity(body, headers); ResponseEntityJsonNode resp restTemplate.exchange(url, HttpMethod.POST, entity, JsonNode.class); return resp.getBody(); } }这里要注意上传文件时如果MultipartFile直接传过去RestTemplate需要正确设置资源类型否则RAGFlow会拒绝请求。我习惯先把文件转成ByteArrayResource并设置filename这样更稳定。3.4 前端页面集成思路RuoYi的前端是Vue2或Vue3可以用现成的ruoyi-ui脚手架加一个“知识库管理”菜单。页面分三个区域左侧是知识库列表中间是文档列表右侧是问答测试面板。知识库管理页使用RuoYi的Table组件展示文档列表轮询状态时用setInterval。问答测试面板用ChatPanel组件输入问题后调用后端接口这里我没有做流式输出而是等RAGFlow把完整答案生成完后一次性返回因为RuoYi的接口层默认处理JSON响应改造流式比较麻烦。如果要做流式输出需要把问答接口改成text/event-stream前端用fetch配合ReadableStream解析这个后续可以单独说。4. 核心流程实现文档入库与智能问答4.1 创建知识库与上传文档RuoYi后台新增知识库时调用RagflowClient.createDataset把返回的id存到kb_knowledge_base.ragflow_dataset_id。上传文档时前端先把文件传到RuoYi本地存储落库记录文件信息再异步调用RagflowClient.uploadDocument把文件传给RAGFlow。之所以先落RuoYi本地再转发是为了保证“即使RAGFlow暂时挂了文件也已经持久化到RuoYi后续可以补传”。上传接口的返回结果里包含了RAGFlow文档ID和文件解析状态初始状态通常是UNSTART。记住这个ID后面轮询解析进度要用。PostMapping(/kb/doc/upload) PreAuthorize(ss.hasPermi(knowledge:doc:upload)) public AjaxResult uploadDoc(RequestParam(file) MultipartFile file, RequestParam(kbId) Long kbId) { // 1. 保存文件到本地 String fileName FileUploadUtils.upload(RuoYiConfig.getKnowledgePath(), file); // 2. 查询知识库的ragflow_dataset_id KbKnowledgeBase kb kbKnowledgeBaseService.selectById(kbId); // 3. 调用RAGFlow上传 JsonNode result ragflowClient.uploadDocument(kb.getRagflowDatasetId(), file); // 4. 记录文档元数据 KbDocument doc new KbDocument(); doc.setKbId(kbId); doc.setFileName(file.getOriginalFilename()); doc.setFilePath(fileName); doc.setRagflowDocId(result.get(data).get(0).get(id).asText()); doc.setParseStatus(UNSTART); kbDocumentService.insert(doc); return AjaxResult.success(doc); }4.2 文档解析状态跟踪RAGFlow解析文档是异步的文件解析需要几十秒甚至几分钟RuoYi侧要通过轮询接口获取状态。RAGFlow提供了获取文档列表的APIGET /api/v1/datasets/{dataset_id}/documents/{doc_id}返回的run字段里有status可能为UNSTART、RUNNING、DONE、FAIL。我写了一个定时任务每30秒扫描一次parse_status不是DONE和FAIL的文档记录然后逐条查询RAGFlow状态并更新。Scheduled(cron 0/30 * * * * ?) public void syncParseStatus() { ListKbDocument docs kbDocumentService.selectPendingParse(); for (KbDocument doc : docs) { JsonNode result ragflowClient.getDocument(kb.getRagflowDatasetId(), doc.getRagflowDocId()); String status result.get(data).get(run).get(status).asText(); if (DONE.equals(status)) { doc.setParseStatus(DONE); doc.setChunkNum(result.get(data).get(chunk_count).asInt()); kbDocumentService.update(doc); } else if (FAIL.equals(status)) { doc.setParseStatus(FAIL); kbDocumentService.update(doc); } } }轮询间隔可以做成配置文档量大时建议用消息队列或线程池并发处理否则大批量导入时定时任务会积压。RAGFlow还支持Webhook回调但需要配置回调地址内网穿透比较麻烦我直接用了轮询稳定简单。4.3 问答接口对接与参数调优问答的核心是调用RAGFlow的会话API。创建会话后发送消息POST /api/v1/chats/{chat_id}/completions请求体里带上question如果不传session_idRAGFlow会创建一个新会话传了之后会保持上下文支持多轮追问。响应里的data.answer是最终答案data.reference里包含引用的chunk列表和原文片段。RuoYi后端把问答接口暴露为PostMapping(/kb/chat/ask) PreAuthorize(ss.hasPermi(knowledge:chat:ask)) public AjaxResult ask(RequestBody ChatAskRequest req) { // 记录开始时间 long start System.currentTimeMillis(); JsonNode result ragflowClient.chatCompletions(kb.getRagflowChatId(), req.getQuestion(), sessionId); // 保存问答记录 String answer result.get(data).get(answer).asText(); kbChatRecordService.insert(userId, req.getQuestion(), answer, referencesJson, costMs); return AjaxResult.success(result); }问答效果不好时重点检查RAGFlow侧的几个参数。similarity_threshold控制最低相似度默认0.2太低很多不相关的内容也会被检索出来我调到0.3之后引用更干净。vector_similarity_weight控制向量检索和全文检索的比重对于专业术语多的文档可以给关键字检索更高权重。还建议启用rerankRAGFlow的DeepDoc里有rerank模型选项启用后检索准确性会有明显提升但会多花费一些推理时间。4.4 权限控制与数据隔离私有化知识库最敏感的是数据隔离。如果不同部门的知识库不能互相看需要在RuoYi层面做“数据权限”。我利用RuoYi已有的DataScope注解在知识库表增加dept_id字段这样部门管理员只能看到本部门的知识库。文档级权限我在问答接口里先根据知识库ID检查当前用户是否有权限再调用RAGFlow问答。RAGFlow的API没有细粒度的用户权限所有请求都靠API Key所以一定不能让普通用户绕过RuoYi直接访问RAGFlow。生产环境最好把RAGFlow部署在独立网段只开放给RuoYi后端服务访问前端浏览器不直接触达RAGFlow。5. 常见问题与排查实录5.1 Docker容器频繁重启现象执行docker compose up -d后ragflow-server容器一直重启。排查先用docker logs ragflow-server --tail 200看日志常见原因有内存不足导致启动时被杀掉、.env里配置的模型服务不可达、ES健康检查失败。我遇到过最典型的是JVM堆内存设置过大和容器内存配额冲突。解决方法是调整.env里的MEM_LIMIT比如设为16g同时把容器的mem_limit对应增加。5.2 解析PDF后乱码或表格错乱PDF里如果都是扫描图片RAGFlow需要先做OCR默认OCR模型可能没有启用。我在RAGFlow知识库配置里把“OCR”打开并选择本地可用的OCR模型。如果还想保留表格结构可以打开“表格增强”选项。另外有些PDF是加密的解析时会直接报错需要先用工具解除密码保护。中文乱码问题多半是文件编码或者字体缺失。RAGFlow的容器里如果缺中文字体渲染出来的版式分析图会乱但最终chunk内容一般不受影响。真的遇到乱码建议先重新安装字体docker exec -it ragflow-server bash apt-get install -y fonts-noto-cjk5.3 问答答非所问或无法生成回答排查步骤按照由简入繁先确认知识库里有文档且状态是DONE然后在RAGFlow界面的“聊天”里直接提问如果也是答非所问说明是模型或检索问题。检查模型供应商里聊天模型是否正常工作用RAGFlow自带的模型测试功能跑一次。如果单模型没问题再看检索打开问答日志看引用chunk的内容是否和问题相关。相关度低就把similarity_threshold调高vector_similarity_weight往关键字方向调。还有一个容易被忽略的问题问答时如果问题太啰嗦RAGFlow的意图识别会跑偏。我在RuoYi的问答接口里加了问题预处理去掉无意义的开场白比如“你好请问”“麻烦帮我看看”只保留核心问题。这个小改动对回答质量提升很明显。5.4 跨域和API鉴权问题如果RuoYi前端直接调RAGFlow的API必然遇到跨域。我的方案是前端只调RuoYi的后端接口由后端转发。如果后端接口也报了401检查RagflowClient的Authorization头是否每次都正确设置注意RAGFlow的API Key是Bearer模式不是Basic别把Key放在请求体里。日志里出现403时大概率是RAGFlow的API Key权限不足需要在RAGFlow后台创建一个有“知识库”权限的Key。5.5 性能优化与大批量导入RuoYi定时任务轮询解析状态在文档量大的时候会变成瓶颈。我改成每1分钟批量查询一次每次最多处理20条并且用CompletableFuture并行调用RAGFlow接口。大批量导入建议串行上传避免一次性开太多连接把RAGFlow压垮。RAGFlow的ES索引也需要定期优化.env里的ELASTICSEARCH_HEAP_SIZE如果太小文档多了之后查询会非常慢。另外上传大文件时RuoYi的request默认大小限制是10MB需要修改application.yml里的max-file-size建议根据实际文档大小调整为100MB。同时Nginx代理层也要同步调client_max_body_size否则上传到一半会被断开。6. 一些实操中的体会这套集成做完我的最大感受是“分工明确比功能多更重要”。RuoYi专注做业务管理和权限控制RAGFlow专注做文档和检索两者通过API连接中间层只做简单的状态同步和数据转发。后续如果要升级我可以把RAGFlow替换成其他引擎只需要替换RagflowClient这个接口RuoYi侧的业务代码几乎不用动。还有一个小技巧RAGFlow的API返回里带了很多字段联调时重点看code如果code不为0说明请求有问题具体错误原因在message里。另外RAGFlow的文档解析结果是可以手动修正的如果自动解析出来的chunk不满意可以在RAGFlow后台的“文档标注”里编辑改完再重新生成索引这个功能比重新调整全局参数更精准。最后提醒一句任何私有化知识库都离不开“文档治理”这一步。RAGFlow再强也救不了杂乱无章的源文件。我的经验是建库之前先定一套文档命名规范图片、表格尽量转成PDF再入库不要直接喂Word和PPT解析稳定性和最终效果都会上一个台阶。
做企业级应用的人大概率都遇到过这种场景业务系统里散落着几十份操作手册、制度文件、项目文档新人培训要翻半天群记录售后客服回复一个问题要打开五六个页面。这时候大家都会想到搞一个知识库把文档统一管起来再让员工用自然语言提问直接得到答案。但真的开始做就会发现“导入文档—搜索命中”这个闭环看起来简单实际落地时扯皮的点特别多切片粒度怎么定表格怎么解析追问怎么处理引用来源怎么展示更麻烦的是和现有的后台管理系统整合很多开源方案要么太重要么API太封闭。我最近在一个项目里把RuoYi和RAGFlow组合起来做了一个完整的私有化知识库。RuoYi负责用户权限、菜单管理、操作日志这些业务底座RAGFlow负责文档解析、向量检索、生成问答。整套方案下来既有现成的后台管理能力又有靠谱的RAG能力关键是所有数据都在内网不依赖外部服务。这篇文章把集成过程中的设计思路、踩坑记录、关键代码全部梳理出来给正在做类似需求的团队一个参考。1. 整体设计为什么是RuoYi RAGFlow1.1 私有化知识库的典型架构私有化知识库不是一个单点应用它至少包含三层存储层文档源文件、向量索引、关系型元数据、服务层文档解析、切片、向量化、检索、生成、应用层后台管理、问答交互、权限控制。很多团队一开始只想用向量数据库LLM API快速搭建做了Demo发现没法用因为没有管理后台、没有文档状态流转、没有权限体系。所以我的思路是让RuoYi承担应用层和一部分存储层让RAGFlow承担服务层。RuoYi本身是成熟的Java后台框架用户表、角色表、菜单表、数据权限、操作日志都是现成的直接拿来做知识库的管理端非常省事。RAGFlow则自带完整的文档解析pipeline支持PDF、Word、Excel、Markdown等多种格式能自动做版面分析、表格识别、标题层级梳理这些能力如果自己用Python从头搞至少要一两个月。1.2 为什么选择RAGFlow而不是其他方案之前也对比过Dify、FastGPT、Weaviate、Milvus这类工具。如果只是做简单的“文档检索问答”Dify上手更快界面也友好但它的设计更偏向工作流编排和业务系统的API对接反而不是强项。FastGPT的问答体验不错但文档解析能力偏弱尤其是PDF里的表格和多栏排版效果不太理想。RAGFlow最打动我的地方是它对“文档结构”的处理。它不是粗暴地把文本切成固定长度的chunk而是先做版面识别把段落、表格、页眉页脚分开再依据文档语义层级做切片。这样生成的chunk里有完整的上下文问答时引用定位也准。另外它支持对接本地嵌入模型和本地LLM这对私有化部署来说是硬指标。RAGFlow的API设计也比较规范知识库管理、文档上传、会话问答都有对应的REST接口方便RuoYi后端统一调用。1.3 集成方案的整体数据流最终落地的架构是用户在RuoYi前端上传文档RuoYi后端把文件保存到本地存储同时调用RAGFlow的API创建文档、上传文件并启动解析。解析完成后RAGFlow自动做切片和向量化RuoYi这边通过轮询或回调更新文档状态。用户提问时RuoYi后端调用RAGFlow的会话API把问题发过去RAGFlow检索相关chunk并构造提示词调用LLM生成回答然后把回答和引用来源返回给RuoYi前端展示。权限控制上RuoYi只让有权限的人访问知识库菜单但RAGFlow本身并不知道RuoYi的用户体系。我的处理方式是让RuoYi后端统一代理RAGFlow的请求不在前端直接暴露RAGFlow的API地址和密钥。这样既解决了权限问题也避免了跨域和密钥泄露的风险。2. 环境准备与RAGFlow部署2.1 硬件与依赖要求RAGFlow对机器的要求不算低官方建议最低配置是16G内存、4核CPU磁盘空间根据文档量预留。如果只是demo可以适当降低要求但生产环境建议32G内存起步尤其是还要跑本地嵌入模型和LLM的时候。操作系统我用的Ubuntu 22.04Docker和Docker Compose是必须的。RAGFlow官方提供了docker compose部署脚本但默认配置里面嵌入模型和聊天模型都指向在线API私有化环境必须改成离线模型或内网可访问的模型服务。我这边是用Ollama部署了一个本地LLM嵌入模型选了兼容OpenAI接口的本地服务。这样整个链路完全在内网不依赖外网。2.2 Docker Compose部署步骤先拉取RAGFlow的部署脚本git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker cp .env.example .env.env文件里有几个关键配置需要关注。SVR_HTTP_PORT是RAGFlow服务对外暴露的端口默认9380MYSQL_PASSWORD和REDIS_PASSWORD建议改成强密码MINIO_USER和MINIO_PASSWORD是对象存储的凭证也要改。改完直接启动docker compose -f docker-compose.yml up -d第一次启动会拉取镜像需要一些时间。启动完成后可以通过docker compose ps确认所有容器状态。正常情况下会有mysql、redis、minio、ragflow等容器在运行。RAGFlow的入口是http://IP:9380第一次访问会让你注册管理员账号。启动过程中最容易遇到的问题有两个。一个是docker compose版本太低导致配置文件里的某些语法不识别升级Docker Compose到v2版本即可。另一个是端口冲突比如宿主机上已经占了3306或者6379把.env里的MYSQL_PORT和REDIS_PORT改掉就行RAGFlow内部容器之间的通信还是走默认端口不会受影响。2.3 初始化配置与模型对接进入RAGFlow后台之后要做的第一件事是配置模型供应商。登录后点击头像进入“模型供应”页面这里支持多种协议。如果你用的是Ollama可以直接选Ollama类型填上Ollama服务的地址比如http://192.168.1.100:11434然后填模型名称例如qwen2.5:14b。注意RAGFlow需要模型具备对话和嵌入两种能力所以“聊天模型”和“嵌入模型”都要配置。嵌入模型很重要推荐选择维度适中、中文效果好的模型比如bge-m3或者bce-embedding-base_v1。如果RAGFlow的模型供应商列表里没有你想要的可以选择“OpenAI-Compatible”类型填上兼容OpenAI协议的本地服务地址。配置完之后可以进行一次“测试”连接确认模型能被正常调用。另外还有一个关键设置.env里的DOC_ENGINE默认是elasticsearch这个不用改RAGFlow的向量检索和全文检索都依赖它。如果文档量特别大可以调ELASTICSEARCH_HEAP_SIZE默认是1G调成2G或4G能减少大文档解析时的内存压力。2.4 验证RAGFlow服务是否正常部署完成后建议先用RAGFlow自带的界面做一次小规模验证。创建一个测试知识库上传一份带标题和表格的PDF等待解析完成后在“聊天”页面提问确认能返回带引用的答案。这一步走通了再接入RuoYi否则后面联调时问题会混在一起很难排查。验证时重点看两个地方文档解析状态是否变成“已完成”聊天回复是否显示引用来源。RAGFlow的解析日志可以在docker logs ragflow-server里看到如果解析失败日志里通常会有具体的异常信息。这一步稳定后再进入RuoYi侧的开发。3. RuoYi侧集成方案设计3.1 复用RuoYi的现有能力RuoYi本身提供了很好的基础设施我们没必要重复造轮子。文件上传方面RuoYi有RuoyiConfig.getProfile()本地存储路径也有基于MinIO的扩展方案。知识库的文件建议统一存放在指定目录由RuoYi的FileUploadUtils处理上传同时把文件元数据记录到自己建的库里。用户认证和权限方面直接用RuoYi的PreAuthorize注解控制接口权限。比如PreAuthorize(ss.hasPermi(knowledge:doc:upload))就能限制只有拥有该权限的用户才能调用上传接口。RuoYi的验证码机制默认登录时需要如果做内部系统想去掉在SysLoginService里把validateCaptcha的校验注释掉即可但这个会影响安全策略最好只在内网环境使用。另外RuoYi会把登录用户信息存在SecurityUtils.getLoginUser()里集成时可以在上传文档时记录操作人在问答接口里记录提问者方便后续做数据审计。3.2 数据库模型设计我新增了三张业务表知识库表、文档表、问答记录表。CREATE TABLE kb_knowledge_base ( id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) NOT NULL, description VARCHAR(500), ragflow_dataset_id VARCHAR(64) COMMENT RAGFlow侧的知识库ID, status CHAR(1) DEFAULT 0, create_by VARCHAR(64), create_time DATETIME ); CREATE TABLE kb_document ( id BIGINT PRIMARY KEY AUTO_INCREMENT, kb_id BIGINT NOT NULL, file_name VARCHAR(255) NOT NULL, file_path VARCHAR(500), file_size BIGINT, ragflow_doc_id VARCHAR(64) COMMENT RAGFlow侧的文档ID, parse_status VARCHAR(20) COMMENT UNSTART/PARSING/DONE/FAIL, chunk_num INT, create_by VARCHAR(64), create_time DATETIME ); CREATE TABLE kb_chat_record ( id BIGINT PRIMARY KEY AUTO_INCREMENT, user_id BIGINT, question TEXT, answer LONGTEXT, references_json TEXT, cost_ms BIGINT, create_time DATETIME );设计思路是RuoYi侧的表只存业务元数据不存向量。RAGFlow的知识库ID和文档ID都作为外键字段关联这样RuoYi可以直接通过API操作RAGFlow资源同时保留自己的业务状态。3.3 后端对接模块设计我在RuoYi的ruoyi-admin模块下新增了一个包com.ruoyi.web.controller.knowledge专门处理知识库相关的接口。为了避免在业务代码里到处写HTTP调用我封装了一个RagflowClient用RestTemplate或者OkHttp调用RAGFlow的API。RAGFlow的API鉴权是通过请求头里的Authorization: Bearer API_KEY实现的。API Key在RAGFlow后台的“API Key”页面生成。我不会把Key硬编码到代码里而是放到application-druid.yml或者Nacos配置中心用Value注入。RagflowClient核心方法大概是这样Service public class RagflowClient { Value(${ragflow.base-url}) private String baseUrl; Value(${ragflow.api-key}) private String apiKey; public JsonNode createDataset(String name) { String url baseUrl /api/v1/datasets; HttpHeaders headers new HttpHeaders(); headers.setBearerAuth(apiKey); headers.setContentType(MediaType.APPLICATION_JSON); MapString, Object body new HashMap(); body.put(name, name); HttpEntityMapString, Object entity new HttpEntity(body, headers); ResponseEntityJsonNode resp restTemplate.postForEntity(url, entity, JsonNode.class); return resp.getBody(); } public JsonNode uploadDocument(String datasetId, MultipartFile file) { String url baseUrl /api/v1/datasets/ datasetId /documents; HttpHeaders headers new HttpHeaders(); headers.setBearerAuth(apiKey); MultiValueMapString, Object body new LinkedMultiValueMap(); body.add(file, file.getResource()); HttpEntityMultiValueMapString, Object entity new HttpEntity(body, headers); ResponseEntityJsonNode resp restTemplate.exchange(url, HttpMethod.POST, entity, JsonNode.class); return resp.getBody(); } }这里要注意上传文件时如果MultipartFile直接传过去RestTemplate需要正确设置资源类型否则RAGFlow会拒绝请求。我习惯先把文件转成ByteArrayResource并设置filename这样更稳定。3.4 前端页面集成思路RuoYi的前端是Vue2或Vue3可以用现成的ruoyi-ui脚手架加一个“知识库管理”菜单。页面分三个区域左侧是知识库列表中间是文档列表右侧是问答测试面板。知识库管理页使用RuoYi的Table组件展示文档列表轮询状态时用setInterval。问答测试面板用ChatPanel组件输入问题后调用后端接口这里我没有做流式输出而是等RAGFlow把完整答案生成完后一次性返回因为RuoYi的接口层默认处理JSON响应改造流式比较麻烦。如果要做流式输出需要把问答接口改成text/event-stream前端用fetch配合ReadableStream解析这个后续可以单独说。4. 核心流程实现文档入库与智能问答4.1 创建知识库与上传文档RuoYi后台新增知识库时调用RagflowClient.createDataset把返回的id存到kb_knowledge_base.ragflow_dataset_id。上传文档时前端先把文件传到RuoYi本地存储落库记录文件信息再异步调用RagflowClient.uploadDocument把文件传给RAGFlow。之所以先落RuoYi本地再转发是为了保证“即使RAGFlow暂时挂了文件也已经持久化到RuoYi后续可以补传”。上传接口的返回结果里包含了RAGFlow文档ID和文件解析状态初始状态通常是UNSTART。记住这个ID后面轮询解析进度要用。PostMapping(/kb/doc/upload) PreAuthorize(ss.hasPermi(knowledge:doc:upload)) public AjaxResult uploadDoc(RequestParam(file) MultipartFile file, RequestParam(kbId) Long kbId) { // 1. 保存文件到本地 String fileName FileUploadUtils.upload(RuoYiConfig.getKnowledgePath(), file); // 2. 查询知识库的ragflow_dataset_id KbKnowledgeBase kb kbKnowledgeBaseService.selectById(kbId); // 3. 调用RAGFlow上传 JsonNode result ragflowClient.uploadDocument(kb.getRagflowDatasetId(), file); // 4. 记录文档元数据 KbDocument doc new KbDocument(); doc.setKbId(kbId); doc.setFileName(file.getOriginalFilename()); doc.setFilePath(fileName); doc.setRagflowDocId(result.get(data).get(0).get(id).asText()); doc.setParseStatus(UNSTART); kbDocumentService.insert(doc); return AjaxResult.success(doc); }4.2 文档解析状态跟踪RAGFlow解析文档是异步的文件解析需要几十秒甚至几分钟RuoYi侧要通过轮询接口获取状态。RAGFlow提供了获取文档列表的APIGET /api/v1/datasets/{dataset_id}/documents/{doc_id}返回的run字段里有status可能为UNSTART、RUNNING、DONE、FAIL。我写了一个定时任务每30秒扫描一次parse_status不是DONE和FAIL的文档记录然后逐条查询RAGFlow状态并更新。Scheduled(cron 0/30 * * * * ?) public void syncParseStatus() { ListKbDocument docs kbDocumentService.selectPendingParse(); for (KbDocument doc : docs) { JsonNode result ragflowClient.getDocument(kb.getRagflowDatasetId(), doc.getRagflowDocId()); String status result.get(data).get(run).get(status).asText(); if (DONE.equals(status)) { doc.setParseStatus(DONE); doc.setChunkNum(result.get(data).get(chunk_count).asInt()); kbDocumentService.update(doc); } else if (FAIL.equals(status)) { doc.setParseStatus(FAIL); kbDocumentService.update(doc); } } }轮询间隔可以做成配置文档量大时建议用消息队列或线程池并发处理否则大批量导入时定时任务会积压。RAGFlow还支持Webhook回调但需要配置回调地址内网穿透比较麻烦我直接用了轮询稳定简单。4.3 问答接口对接与参数调优问答的核心是调用RAGFlow的会话API。创建会话后发送消息POST /api/v1/chats/{chat_id}/completions请求体里带上question如果不传session_idRAGFlow会创建一个新会话传了之后会保持上下文支持多轮追问。响应里的data.answer是最终答案data.reference里包含引用的chunk列表和原文片段。RuoYi后端把问答接口暴露为PostMapping(/kb/chat/ask) PreAuthorize(ss.hasPermi(knowledge:chat:ask)) public AjaxResult ask(RequestBody ChatAskRequest req) { // 记录开始时间 long start System.currentTimeMillis(); JsonNode result ragflowClient.chatCompletions(kb.getRagflowChatId(), req.getQuestion(), sessionId); // 保存问答记录 String answer result.get(data).get(answer).asText(); kbChatRecordService.insert(userId, req.getQuestion(), answer, referencesJson, costMs); return AjaxResult.success(result); }问答效果不好时重点检查RAGFlow侧的几个参数。similarity_threshold控制最低相似度默认0.2太低很多不相关的内容也会被检索出来我调到0.3之后引用更干净。vector_similarity_weight控制向量检索和全文检索的比重对于专业术语多的文档可以给关键字检索更高权重。还建议启用rerankRAGFlow的DeepDoc里有rerank模型选项启用后检索准确性会有明显提升但会多花费一些推理时间。4.4 权限控制与数据隔离私有化知识库最敏感的是数据隔离。如果不同部门的知识库不能互相看需要在RuoYi层面做“数据权限”。我利用RuoYi已有的DataScope注解在知识库表增加dept_id字段这样部门管理员只能看到本部门的知识库。文档级权限我在问答接口里先根据知识库ID检查当前用户是否有权限再调用RAGFlow问答。RAGFlow的API没有细粒度的用户权限所有请求都靠API Key所以一定不能让普通用户绕过RuoYi直接访问RAGFlow。生产环境最好把RAGFlow部署在独立网段只开放给RuoYi后端服务访问前端浏览器不直接触达RAGFlow。5. 常见问题与排查实录5.1 Docker容器频繁重启现象执行docker compose up -d后ragflow-server容器一直重启。排查先用docker logs ragflow-server --tail 200看日志常见原因有内存不足导致启动时被杀掉、.env里配置的模型服务不可达、ES健康检查失败。我遇到过最典型的是JVM堆内存设置过大和容器内存配额冲突。解决方法是调整.env里的MEM_LIMIT比如设为16g同时把容器的mem_limit对应增加。5.2 解析PDF后乱码或表格错乱PDF里如果都是扫描图片RAGFlow需要先做OCR默认OCR模型可能没有启用。我在RAGFlow知识库配置里把“OCR”打开并选择本地可用的OCR模型。如果还想保留表格结构可以打开“表格增强”选项。另外有些PDF是加密的解析时会直接报错需要先用工具解除密码保护。中文乱码问题多半是文件编码或者字体缺失。RAGFlow的容器里如果缺中文字体渲染出来的版式分析图会乱但最终chunk内容一般不受影响。真的遇到乱码建议先重新安装字体docker exec -it ragflow-server bash apt-get install -y fonts-noto-cjk5.3 问答答非所问或无法生成回答排查步骤按照由简入繁先确认知识库里有文档且状态是DONE然后在RAGFlow界面的“聊天”里直接提问如果也是答非所问说明是模型或检索问题。检查模型供应商里聊天模型是否正常工作用RAGFlow自带的模型测试功能跑一次。如果单模型没问题再看检索打开问答日志看引用chunk的内容是否和问题相关。相关度低就把similarity_threshold调高vector_similarity_weight往关键字方向调。还有一个容易被忽略的问题问答时如果问题太啰嗦RAGFlow的意图识别会跑偏。我在RuoYi的问答接口里加了问题预处理去掉无意义的开场白比如“你好请问”“麻烦帮我看看”只保留核心问题。这个小改动对回答质量提升很明显。5.4 跨域和API鉴权问题如果RuoYi前端直接调RAGFlow的API必然遇到跨域。我的方案是前端只调RuoYi的后端接口由后端转发。如果后端接口也报了401检查RagflowClient的Authorization头是否每次都正确设置注意RAGFlow的API Key是Bearer模式不是Basic别把Key放在请求体里。日志里出现403时大概率是RAGFlow的API Key权限不足需要在RAGFlow后台创建一个有“知识库”权限的Key。5.5 性能优化与大批量导入RuoYi定时任务轮询解析状态在文档量大的时候会变成瓶颈。我改成每1分钟批量查询一次每次最多处理20条并且用CompletableFuture并行调用RAGFlow接口。大批量导入建议串行上传避免一次性开太多连接把RAGFlow压垮。RAGFlow的ES索引也需要定期优化.env里的ELASTICSEARCH_HEAP_SIZE如果太小文档多了之后查询会非常慢。另外上传大文件时RuoYi的request默认大小限制是10MB需要修改application.yml里的max-file-size建议根据实际文档大小调整为100MB。同时Nginx代理层也要同步调client_max_body_size否则上传到一半会被断开。6. 一些实操中的体会这套集成做完我的最大感受是“分工明确比功能多更重要”。RuoYi专注做业务管理和权限控制RAGFlow专注做文档和检索两者通过API连接中间层只做简单的状态同步和数据转发。后续如果要升级我可以把RAGFlow替换成其他引擎只需要替换RagflowClient这个接口RuoYi侧的业务代码几乎不用动。还有一个小技巧RAGFlow的API返回里带了很多字段联调时重点看code如果code不为0说明请求有问题具体错误原因在message里。另外RAGFlow的文档解析结果是可以手动修正的如果自动解析出来的chunk不满意可以在RAGFlow后台的“文档标注”里编辑改完再重新生成索引这个功能比重新调整全局参数更精准。最后提醒一句任何私有化知识库都离不开“文档治理”这一步。RAGFlow再强也救不了杂乱无章的源文件。我的经验是建库之前先定一套文档命名规范图片、表格尽量转成PDF再入库不要直接喂Word和PPT解析稳定性和最终效果都会上一个台阶。
