ragflow docker build

自己动手搭 RAGFlow 时，最常见卡点不是代码写错，而是 docker build 半路报错、或者卡在拉基础镜像那一行半天不动。这篇按「先分清是拉不动还是编不过」的顺序，给你一份逐步排查的清单：怎么判断瓶颈在网络还是在构建层、怎么改镜像源、怎么清缓存重来、什么情况下干脆换部署方式更省事。

自己动手搭 RAGFlow，最容易卡住的不是代码写错，而是两条路：一条是 docker build 跑一半报错，另一条是卡在拉基础镜像那一行，进度条半天不动。两种情况看着都像「构建失败」，但根因一个在网络、一个在构建层，处理方式完全不一样。下面按顺序给你一份能直接照着做的排查清单。

先说清楚一个判断原则：不要一上来就重跑。重跑大概率还会在同一个位置断，白白浪费一次等待。先把日志停在哪一行看清楚，再决定是去改镜像源，还是去查构建指令。整篇的目标是让你把「拉不动」和「编不过」拆开，各自用对应手段解决，而不是靠反复重试碰运气。

先分清是拉不动还是编不过

判断方法很简单：打开构建时的终端输出，看最后停在哪一类行。如果停在打基础镜像、下载某某 tar、解压层这类动作上，属于网络侧；如果已经进入某条 RUN 指令、在装包或编代码时报错退出，属于构建侧。两类问题的处理路径没有交集，先贴对标签再动手。

网络侧

卡在 pulling、downloading，进度条长时间不动后超时，日志里多半只有拉取相关的行

构建侧

已经走到某条 RUN 命令，报出明确的错误码和命令名，进程以非零状态退出

灰区

看起来在装依赖，其实依赖是从外网拉的，这类既可能是网络也可能是指令问题，按下一步的顺序逐层排

1. 抄下最后几行把报错末尾的命令名、错误码、涉及的包名原样记下来，别只看「failed」两个字。这一步决定了后面往哪查。
2. 网络侧先量延迟如果判断是拉取慢，先到 /tools/speed-test 量一下当前网络到镜像源的实际延迟，拿到一个基线数字，再决定要不要换源，而不是凭感觉换。
3. 构建侧单独复现如果是某条 RUN 报错，把那条命令拆出来在容器里手动跑一遍，确认是命令本身的问题还是环境差异。
4. 别急着重跑在没搞清楚哪一类问题之前重跑，只会把同样的等待再走一遍，收益很低。

网络侧：换源、走代理、避开高峰

• 给 docker 配置镜像加速地址后，一定要重启守护进程，否则配置不生效，你会以为换了源没效果
• 公司网络带拦截时，只让拉取阶段走代理，不要给整个 docker 挂全量代理，否则构建里装包也会被绕路，反而更慢
• 先把基础镜像单独 docker pull 下来，再执行构建，这样网络问题和构建问题就彻底分开了
• 同一台机器上并行拉多个大镜像容易互相抢带宽，串行往往比并行更快出结果

这里有个常见误区：以为换源一定更快。实际上如果瓶颈在出口带宽或者拦截策略，换源只会换一个变慢的地址。所以先量基线、再换源、换完再量一次，用两次数字对比，而不是换完就默认好了。具体到不同镜像源的当前表现，可以到 /tools/speed-test 上看当时的实测情况。

构建侧：缓存、依赖与磁盘

构建侧报错，八成集中在三件事：缓存没命中导致整层重建、磁盘空间不够、依赖装不上。排查顺序建议从磁盘开始，因为磁盘满了会伪装成各种奇怪的错误，先排除这个最简单的可能。

1. 看磁盘占用执行 docker system df，确认镜像、容器、构建缓存各占多少，有没有大量悬空镜像和残留缓存。
2. 清无用缓存再试清掉悬空镜像和无用构建缓存，腾出空间后再跑一次构建，看报错是否消失。
3. 检查指令顺序如果只是改了一个小文件却导致依赖整层重装，多半是依赖文件在缓存层之后才被拷贝，调整 Dockerfile 里的指令顺序，把装依赖和拷代码分开。
4. 串行执行拉取和构建同时进行会占满带宽，容易在装包阶段超时，改成拉完再build。

• 报磁盘不足或空间警告时，先清缓存再判断是不是真的空间不够，别急着扩容
• 改动小文件却整层重建，看的是 Dockerfile 里拷贝指令的位置，而不是改动本身的大小
• 依赖装不上时，先确认是不是网络问题伪装成了构建问题，参考上一节的方法
• 构建日志里出现被 kill 的字样，通常指向内存不足，而不是代码错误

什么情况下别自己编

不是所有场景都值得本地 build。如果你只是想跑通一套知识库、机器内存和磁盘本来就紧张，用官方预构建镜像会比本地编译省事得多。需要改源码、加自定义依赖时才自己编；只是调参数、换模型，配置层能解决就别动镜像。

如果你判断自己属于「不该编」的那一类，但又不确定官方镜像当前的体积、拉取难度和适用场景，可以到 /sites 看看导航里收录的部署入口，再到 /rankings 对比不同部署方式的实际反馈，别只凭一篇教程就决定自己编。