ragflow本地部署

想在本地跑一套知识库问答，搜到 RAGFlow 却卡在第一步：镜像拉不下来、容器起不来、模型和向量库不知道填什么。这篇按顺序把部署拆成准备、起服务、初始化、验证四步，每步给检查项和失败时的排查方向。数字类和选型类的信息，文中会指到站内对应页面去核对当时的实际情况。

想在本地跑一套知识库问答，搜到 RAGFlow 却卡在第一步：镜像拉不下来、容器起不来、模型和向量库不知道填什么。这篇按顺序把部署拆成准备、起服务、初始化、验证四步，每步给检查项和失败时的排查方向。

先说清一个前提：本文只讲动作和排查顺序，不替你拍板选型。硬件要求、镜像体积、各家模型的价位与能力差异，站内都做过整理，动手前建议先去 /tools 和 /price-watch 核对当时的实际情况，再回来看这篇按步骤操作。

部署前先把环境和资源对齐

部署失败十有八九不是软件问题，是机器条件没对齐。先在纸上把三件事写清楚：跑在哪台机器、数据放哪个盘、要不要用 GPU。想不清楚就先找一台闲置机器试跑，别直接上生产机。

1. 估一遍资源CPU 核数、内存、可用磁盘分别填进部署测算页面走一遍，重点看内存和磁盘两项。磁盘要按「镜像 + 依赖 + 模型权重 + 你后续入库的原始文档」加总算，权重和文档通常才是大头。内存不够的表现是容器起得来但解析阶段被系统杀掉，日志里能看到 OOM 字样。
2. 配好容器与镜像源确认本机容器编排工具版本可用，并提前配置镜像加速地址。国内拉镜像慢或超时是最常见的第一个坑，先在命令行手动拉一个基础镜像验证网络通不通，不通就先解决网络，别急着改编排文件。
3. 规划挂载目录把数据目录、模型权重目录、日志目录分三个路径挂载到宿主机。判断标准很简单：删掉容器重建后，你的知识库和已上传文档还在不在。不在了说明挂载没生效，后面升级会很难受。
4. 定路线先决定走全容器一键起，还是只起服务端、模型和向量库都用外部的。两条路配置文件字段不一样，中途换路线很容易出现「界面能打开、功能全报错」的假成功。

把服务拉起来：容器、网络与镜像源

这一节的目标只有一个：让所有容器处在一个稳定运行的状态。不要一边起服务一边改配置，改一次、重启一次、看一次日志，节奏慢一点反而快。

• 镜像拉取失败按顺序查：镜像源是否可达、本机架构是否匹配、磁盘剩余空间、代理有没有进到容器环境变量里。
• 容器起来后立刻退出，先看日志最后几十行，区分是配置解析错、依赖服务连不上，还是挂载路径权限不对。
• 改端口或改数据目录时，编排文件和对应环境变量要一起改，只改一处就会出现「前端能开、后端连不上」的假成功。
• 确认容器之间能互相解析到服务名，这是最容易忽略的一环，网络隔离没配好会表现成莫名的连接超时。

# 查看某个容器最近日志，定位启动失败原因（把 <容器名> 换成实际名字）
docker logs --tail 80 <容器名>
# 确认容器是退出还是仍在运行
docker ps -a
# 看这台机器还剩多少磁盘
df -h

初始化配置：模型、向量库与账号

服务跑起来后打开管理界面，第一件事是接模型。这里不替你选具体型号，选型标准和当时的价位请到 /price-watch 和 /tools 核对，本文只讲「怎么填才不出错」。

对话模型

负责生成回答，填的是接口地址加密钥，走云 API 还是内网推理服务决定填外网地址还是内网地址。

嵌入模型

负责把文档和问题变成向量，决定检索质量，一般体积小、显存占用低，但要确认中英文支持情况。

向量库

存向量的地方，可以先跑默认的，量级上来再换。换库意味着已有资料要重新入库。

Base URL

模型服务的接入地址，写错的表现通常是保存成功但一测试就报连接错误。

接外部服务前，先确认对方的接口协议跟你填的格式是不是一类，协议兼容性的差异站内有专门一篇讲，别硬套参数。接入本地推理服务时，注意容器能不能访问到宿主机的服务地址，这一步经常被忽略。

• 对话模型和嵌入模型分开配置，不要用同一个模型顶两件事。
• 初始化时创建的管理员账号，第一时间改掉默认密码。
• 确认这套服务没有直接暴露在公网，内网访问先用内网地址验证。
• 配置改完点一下连接测试，通了再往库里传文档，顺序反了很难定位问题。

验证：能登录、能建库、能问答

别用「页面能打开」当部署成功的标准。按三层验证走一遍，每一层都有明确的通过条件，哪层断了就回到对应环节排查。

1. 第一层：登录管理界面能正常登录，页面上的主要功能入口都在。打不开就先回头查端口和反向代理。
2. 第二层：建库并上传新建一个小知识库，上传一份纯文本文件，看它能不能走到解析完成。一直卡在解析状态，多半是解析器或 OCR 依赖没就绪，先换纯文本排除文档本身的问题。
3. 第三层：提问提一个只有这份文档里有答案的问题，能答对才算通。答非所问的情况，先查切片是否完整、检索命中的是不是无关段落，这属于入库和检索的问题，不一定是部署没成功。

到这里部署和初始化就走完了。如果后续想对照不同中转服务的稳定性和价格变化，或者想换一套更适合自己文档类型的解析方案，站内都有现成的页面可以查，不用重新试错一遍。