很多人是在 docker compose 拉起来之后才发现跑不动：镜像能下、容器能起，但一解析文档就卡死或者直接把内存吃满。问题多半不在 RAGFlow 本身，而是部署前没算过这台机器的账。这篇不讲安装步骤，只给一套部署前的评估顺序：硬件看哪几项、依赖哪些必须提前装、存储和内存怎么估，以及判断「能跑」和「能长期跑」的区别在哪。
很多人是在 docker compose 拉起来之后才发现跑不动：镜像能下、容器能起，但一解析文档就卡死，或者直接把内存吃满。问题多半不在 RAGFlow 本身，而是部署前没算过这台机器的账。
这篇不讲安装步骤，只给一套部署前的评估顺序：硬件看哪几项、依赖哪些必须提前装、存储和内存怎么估，以及「能跑」和「能长期跑」的区别在哪。目标很明确，让你拿着这份清单去看手头这台机器，先判断够不够，再决定要不要动手。
先明确：你要的是「跑起来」还是「用得下去」
同样一台机器，验证流程和长期投用是两个完全不同的门槛。先把自己的需求归到某一档，再往下看配置，否则拿试跑的标准去评估生产，装完必然后悔。
| 场景 | 关注点 | 可以放宽的项 |
|---|---|---|
| 本地试一下、验证流程能不能通 | 服务起得来、能解析一份文档 | CPU、磁盘余量、并发 |
| 团队长期灌文档、多人同时用 | 解析速度、并发上限、内存峰值 | 界面美观度、加载动画 |
- 评估之前先确认三件事：要灌多少文档、单份文档多大（有没有大量扫描件和表格）、同时几个人用。这三项决定了后面所有估算，比抄一份别人的配置表有用。
- 官方文档里写的最低配置，只能保证容器起得来，解析环节才是真正吃资源的步骤，所以看要求时要把「启动占用」和「解析峰值」分开算。
- 如果只是想让模型用上自己的资料、不打算做重度文档解析，可以先考虑更轻的方案，不用一上来就上 RAGFlow，取舍思路可对照 /guides/api-vs-self-host-decision。
硬件三件套：内存、CPU、磁盘怎么估
内存是第一个卡点，也是最容易被低估的。除了应用本身，文档解析和向量化都会额外占内存，机器上如果还同时跑着本地大模型或向量库，两者会互相挤。建议先把要共存的组件列出来，再定总内存。
| 硬件项 | 影响的是什么 | 估不准时的保守做法 |
|---|---|---|
| 内存 | 解析和向量化的峰值，决定会不会被 OOM 杀掉 | 先列共存组件，再按文档体积留余量 |
| CPU | 解析与切片速度，不是能不能跑 | 分批入库可让步，一次性导入要看清 |
| 磁盘 | 原始文件、中间产物、向量索引三份 | 只按原始体积估通常偏小，往上加一档 |
- CPU 核心数少，主要表现是「灌数据很慢」，不赶时间可以适当让步；一次性导入大量资料时，核心数和主频就要认真看。
- 磁盘要同时算三份：原始文件、解析后的中间产物、向量索引。很多人只按原始文件大小估，结果索引占的空间反而更大。
- 判断机器够不够，与其靠猜，不如去官方文档核对部署配置说明，数值以你部署时那一版为准，别用别人半年前的截图。
依赖项与运行时：部署前该装齐什么
容器化部署是主流做法，但容器能跑起来不等于流程能跑通。依赖这一块分两层：系统与容器运行时是一层，模型与外部服务是另一层，两层都要在启动前定下来。
- 确认运行时版本核对 Docker 与 compose 是否满足当前发布说明的要求。低版本 compose 语法不兼容，是启动失败里很常见的一类原因，具体版本对照以官方发布说明和 /guides/ragflow-docker-selfhost 为准。
- 定模型接入方式向量模型、重排模型、对话模型分别走本地推理还是外部接口，要在启动前想清楚。走本地推理等于给机器再加一份负载；走外部接口则要确认网络能不能通、密钥怎么放。
- 调系统层参数文件句柄数、共享内存大小、容器可用的 CPU 与内存上限，这几项在默认配置下容易被卡住，共享内存太小会让解析进程直接崩掉。
- 规划路径与端口部署前把端口、数据目录挂载点、环境变量文件先规划好，改动集中在一个地方，后面排查问题不用满系统找配置。
上线前的验收顺序：怎么确认这台机器真的够
配置表看得再仔细，也不如自己跑一遍。关键是按顺序测，别跳步，跳步之后出问题很难定位是配置不够还是文档本身有问题。
- 先确认服务能正常启动并打开界面，再拿一份中等大小的文档走完整解析流程，最后才是批量导入。
- 解析测试时盯着内存和 CPU 曲线看峰值，而不是只看任务有没有成功。短时间冲高可以接受，持续贴着上限跑，说明批量导入时会撑不住。
- 批量阶段控制并发导入数量，观察解析耗时有没有明显拉长。拉长通常意味着资源已经饱和。
- 测完留一份记录：文档规模、耗时、资源峰值。下次扩容或者换机器时，这份记录比任何配置建议都准。
# 解析测试期间另开一个终端观察资源峰值；具体命令参数按你机器的实际情况调整
docker stats --no-stream
# 想看成曲线而不只是瞬时值，可用 htop 或系统自带监控工具跑不动时，先改什么再换机器
发现跑不动，第一反应不该是下单买机器。多数情况下是负载叠加或者并发没控住，调一调就能撑过去；只有确认是配置天花板，才值得动硬件。
| 现象 | 优先尝试的动作 | 什么时候说明确实是配置不够 |
|---|---|---|
| 解析慢但能跑完 | 降并发、拆小批量、把重排切到外部接口 | 降并发后耗时仍线性拉长 |
| 解析中途进程被杀 | 先看共享内存和内存上限 | 单份中等文档就吃满内存 |
| 界面卡、响应慢 | 看是不是本地模型和解析在抢资源 | 错峰后仍然持续卡顿 |
- 优先降负载而不是加硬件：减少同时解析的任务数、把大批量导入拆成小批、把重排和向量化切到外部接口，这几项通常比升级配置见效更快。
- 本地大模型推理和文档解析同时开，任何一项都会被拖慢，把两者分到不同机器或错峰执行。
- 如果确实要扩，先补内存再补 CPU，磁盘一般靠加盘解决而不是换整机，顺序错了容易花冤枉钱。
先算账再装环境，比装完再想办法省事得多。下一步想估算这台机器跑起来大概是什么体验，可以先用站内的速度测试和配置经验做一次对照，再决定是直接部署还是先换更轻的方案。→
常见问题
用一台普通的家用电脑或者轻薄本，能跑 RAGFlow 吗？
能不能跑取决于你要拿它干什么。只是想打开界面、导入一两份小文档试试流程，通常可以；但只要开始批量解析真实文档，内存会先撑不住。轻薄本的瓶颈一般在内存和散热，长时间解析容易降频。建议把这类机器定位成「验证环境」，跑通流程后再挪到正经服务器上灌数据。
没有独立显卡能不能部署？
多数情况下可以，前提是向量化和重排不走本地 GPU 推理，而是接外部模型接口。这样 GPU 就不是必需项，机器压力主要落在 CPU 和内存上。要注意的是，外部接口会带来额外的网络延迟和调用成本，批量入库时感受明显。如果你的场景要求完全断网、全部本地推理，那 GPU 基本就是硬门槛了。
怎么判断配置不够，而不是文档本身有问题？
看失败的模式。配置不够通常表现为：解析过程中进程被杀、内存持续贴顶、并发一高耗时成倍上升。文档问题更多是个别文件解析不出内容、报格式相关的错误，而其他文件正常。最快的区分办法是拿一份确定能正常解析的小文档做对照，它能过而大文件过不了，基本就是资源问题。
