你在 Ubuntu 服务器上照着文档装 RAGFlow，多半会卡在这几处：Docker 版本太老、内核参数没调、内存不够被 OOM 杀掉、端口被占、模型和能力对不上。这篇不讲原理，只给一条能照着走的部署路径和一份排错顺序。具体版本号、镜像大小和资源数字，站内对应页面会随发布更新，以那边为准。
在 Ubuntu 服务器上装 RAGFlow，卡住的地方基本不在 RAGFlow 本身，而在宿主机：Docker 太旧、内核参数没调、内存不够被系统 OOM 杀掉、端口被占、模型配错。这篇不给原理，只给一条能照着敲的路径和一份排错顺序。
先说清楚一个前提：RAGFlow 是「容器组 + 数据落盘 + 模型接入」三件事拼起来的，任何一环在宿主机上没准备好，容器起来了也会中途挂掉。具体镜像大小、内存占用、镜像 tag，以站内页面发布时更新为准，别照抄别人博客里的数字。
先确认机器够不够：系统、内核与资源基线
很多失败案例在装之前就注定了。先花五分钟把宿主机摸清楚，比装完再拆快得多。
- 确认发行版和内核版本：老内核的 cgroup 和 overlayfs 行为和新版不一样，容器可能直接卡在启动阶段
- CPU 指令集要看清：向量检索和嵌入推理对指令集有要求，缺了不是报错就是慢到没法用
- 内存和磁盘是硬门槛：向量库和文档解析都吃内存，Swap 只能救急不能当方案，先按你知识库的规模估一遍
- Docker 与 Compose 版本要够新，装之前先跑 docker info，重点看 Storage Driver 和 Cgroup 是不是正常
- 时区、DNS、出网三件事在宿主机就解决掉，否则后面拉镜像和调模型都会莫名其妙失败
| 检查项 | 怎么看 | 不达标会怎样 |
|---|---|---|
| 内核与发行版 | uname -r 结合发行版版本 | 容器起不来或 cgroup 报错 |
| CPU 指令集 | 看 /proc/cpuinfo 里的 flags | 推理慢或直接崩 |
| 内存与 Swap | free -h 看真实余量 | 容器无征兆重启 |
| 磁盘与挂载点 | df -h 看数据盘剩余 | 知识库写不进去 |
| Docker 状态 | docker info 看驱动与 cgroup | 镜像拉不动或容器异常退出 |
部署顺序：内核参数、容器编排、配置文件
顺序错了会白折腾。正确姿势是：先在宿主机调内核参数，再拉代码和配置文件，最后才拉起容器组。别进容器里手工装依赖，容器一重建全没了。
- 调宿主机内核参数文件句柄数、虚拟内存映射上限这类参数不调，容器起来也会中途退出。改完用 sysctl 确认已生效，不是写完文件就算数。
- 拉代码、建数据目录把数据目录建在宿主机持久卷上，独立于代码目录。知识库、上传的文档、向量数据都往这里落。
- 改环境变量文件只改三项：对外端口、数据落盘路径、模型接入地址。其余保持默认，减少变量。改动前先备份原文件。
- 拉起容器组用编排工具一起拉起。起完立刻看容器状态和重启次数，反复重启的那个就是问题源头。
- 确认数据持久化重启一次容器组，看登录后知识库还在不在。这一步过了，部署才算稳。
接模型与开端口：让服务和能力都对上
RAGFlow 里对话模型、嵌入模型、重排模型是三套独立配置。只填对话模型，能聊但不能检索，用起来像坏的。三套都要配，才叫跑通。
- 对话模型
- 负责生成回答，决定说话质量
- 嵌入模型
- 把文档和问题转成向量，决定能不能搜到
- 重排模型
- 对召回结果二次排序，决定答得准不准
- 向量维度
- 由嵌入模型决定，中途换模型会让已有知识库对不上
- 端口映射
- 分容器内部端口和宿主机映射端口，外部不通先分清是哪层没通
选型建议在入库之前定死，尤其嵌入模型。已经建了知识库再换嵌入模型，等于把库废掉重来。生产环境建议前面加一层反向代理做 TLS 和访问控制，裸暴露端口只适合内网自测。
起完之后怎么验：三件事逐个确认
页面能打开不等于部署成功。按下面三层顺序验，每层都过了才算数。
- 进程层：所有容器状态正常且没有反复重启，重启次数明显偏高的那个优先排查
- 接口层：用宿主机 IP 和对外端口能打开页面并登录，说明网络和映射没问题
- 业务层：传一份小文档，走完解析到问答全过程，能答出来才算真的可用
- 持久层：重启容器组再登录，知识库还在，说明数据落盘配置正确
- 模型层：三套模型各跑一次，检索能出结果、重排能改变顺序，才算配齐
卡住了按这个顺序查，别来回猜
出问题别东改西改，按下面四步走。前三步能覆盖绝大多数情况，第四步再怀疑配置。
- 第一步看容器日志先分辨是拉不起来、起来了就退、还是起来了但接口报错。三类问题方向完全不同，日志里写得明明白白。
- 第二步看资源内存不足被系统杀掉最常见，表现为容器无征兆重启。用系统日志确认是不是 OOM，是就加内存或缩小知识库规模。
- 第三步看端口与防火墙本机能通、外面不通，九成是映射或安全组，不是应用问题。先在本机 curl 一下，再确认安全组规则。
- 第四步才怀疑配置模型地址写错、协议不匹配（OpenAI 兼容还是原生接口）都会在日志里留痕迹。对着日志里的报错逐条改。
如果你要拿 RAGFlow 和别的检索方案对比，或者想知道它在你这类机器上大概什么体验，别只看别人给的数字，站内对应页面会随发布更新。
下一步部署完成后，如果你在挑中转站来跑模型接入，可以用站内的可信度检测逐个核验，别直接拿主站当生产环境。→常见问题
Ubuntu 上装 RAGFlow，最低要什么配置？
没有一句话的固定答案，取决于你打算灌多少文档以及用不用本地模型。纯做轻量知识库和宿主机共用一台机器，和要把嵌入模型也放本地，差别很大。站内有部署测算和设备规格相关页面，按你的文档量和模型摆放方式对一遍，再决定是加内存还是加盘。
容器一直重启是什么原因？
优先怀疑内存被杀和内核参数没调这两件事，其次才是配置写错。看容器日志末尾有没有进程被强制结束的痕迹，再看宿主机剩余内存。如果日志里是启动后立刻退出，多半是环境变量文件没生效，或者数据目录权限不对导致挂载失败。
部署完页面能开但问答一直失败，先查哪里？
先查模型配置三件套是否齐全：对话、嵌入、重排。只配了对话模型时页面正常但检索为空或直接报错。其次确认嵌入模型和已有知识库的向量维度是否一致，中途换过模型的话旧库要重建。最后看模型服务地址在容器内能否访问，容器里的 localhost 不是宿主机。
