ragflow docker compose 部署

很多人第一次跑 RAGFlow 都是在服务器上敲一条 compose 命令，然后卡在拉镜像慢、容器反复重启、网页打得开但检索没结果这几步上，却不知道先看哪里。这篇不讲原理，只给可执行的部署顺序和排查路径：起服务前该核对哪些配置项、容器起来后按什么顺序验证、常见报错分别对应哪一层。需要具体配置数值和版本要求时，去站内对应页面看当时的说明。

很多人第一次跑 RAGFlow 都是在服务器上敲一条 compose 命令，然后卡在拉镜像慢、容器反复重启、网页打得开但检索没结果这几步上，却不知道先看哪里。这篇不讲原理，只给可执行的部署顺序和排查路径：起服务前该核对哪些配置项、容器起来后按什么顺序验证、常见报错分别对应哪一层。需要具体配置数值和版本要求时，去站内对应页面看当时的说明。

下面的流程按「先对齐环境、再按依赖起服务、最后按日志排查」来走。每一步都配了判断标准，做到哪一步算过，做不过去该往哪看，都写清楚。照着做，比反复重装能省不少时间。

起容器之前先对三样东西

部署失败十有八九不是 compose 文件写错，而是环境没对齐。起服务前把机器、依赖、网络这三样各花几分钟确认一遍，能避免后面大部分莫名其妙的报错。具体的内存、磁盘、内核下限以镜像说明为准，不要用去年的经验值套。

机器侧

确认目标机可用内存、磁盘余量和内核版本是否满足镜像声明下限，到 /models/deploy 按当前镜像说明核对

依赖侧

Docker 与 Compose 插件装到同一代版本，Compose 大版本变了 YAML 字段写法也会变，混装最容易起服务时报字段错误

网络侧

先确认镜像仓库能否直连，决定要不要提前配代理或换源，别拉到一半超时再回头重来

• 内存与磁盘留出余量，别按刚好够用去配，后面还要接模型和批量入库；
• Docker 与 Compose 版本成对升级，不要只升一个；
• 镜像源在起服务前就配好，不要边拉边调；
• 时区和字符集提前设对，日志时间戳错乱会干扰排查；
• 把这次的机器配置记一份，换机器直接对照。

起服务时按依赖顺序看，不要一把梭

容器化部署的常见误区是把所有服务一把拉起来，然后盯着容器列表看谁红了。正确做法是先起底座、确认它们健康，再起应用层。应用层启动时会连数据库和缓存，底座没就绪，应用就一直重连，最后被判成不健康甚至重启循环。

1. 先起底座把数据库、缓存、向量库这类依赖容器拉起来，等健康检查通过再继续，验证方式是看它们的状态是否变为健康。
2. 再起应用底座健康后起应用层，应用会去连依赖，连不上会直接报错而不是静默等待。
3. 跟日志别跟界面用 compose 的日志跟踪看输出，容器列表里的「运行中」不等于内部服务已经就绪。
4. 等初始化第一次启动常会自动建表和初始化，慢是正常的，判断标准是日志有没有继续往下走，而不是盯着进度条。

出问题时的排查顺序

出问题不要乱试，按「退出码与日志 → 端口与环境变量 → 数据卷权限」这个顺序查，能覆盖大部分情况。乱改配置只会把问题搅得更复杂，还可能把原本正常的部分弄坏。

这张表能帮你把「哪一层出问题」先定位出来，再去看具体日志。定位对了，修起来通常很快；定位错了，就会在无关的配置上反复折腾。

网页能开之后还要验的两件事

看到登录页只能说明应用层起来了，不等于部署成功。基础链路和资源水位这两件事都要验，不然等问题在正式使用中冒出来，排查成本更高。

• 验基础链路：上传一份小文档、跑一次解析、发一次问答，走完一遍才算部署成功；
• 验资源水位：跑完一两个任务后回看内存和磁盘占用，确认不是靠吃满内存勉强撑住；
• 验重启恢复：手动重启一次容器，确认数据还在、服务能自动恢复；
• 留余量：为后面接模型和批量入库留出余量。

改配置和升级怎么做得不翻车

容器化部署最怕改一半失败、旧配置也没了。改 YAML 前先备份原文件和数据卷，升级镜像前先看说明里有没有涉及数据结构变更。写死的数字和变更细节以下游校验为准，这里只给动作。

1. 备份先行改 YAML 前备份原文件和数据卷，改坏了能回退。
2. 看变更说明升级镜像时先看说明里有没有涉及数据结构变更，涉及的话先备份数据，具体变更以站内资料库当前版本页为准。
3. 记录过程把每一步成功了什么记下来，换机器或换团队接手时，这份记录比命令本身更值钱。
4. 小步验证改完先起一遍，确认基础链路还在，再往下改别的。

部署这件事，能回退比一次成功更重要。