本以为docker compose up -d一把梭结果接连踩进镜像拉取超时、80 端口被锁、Nginx 疯狂 502 的连环坑。这篇文章把硬骨头一块块啃下来的全过程以及最终那行RAGFlow server is ready after 390s背后的真实原因都摊开来讲。资源链接https://download.csdn.net/download/u012551928/93315046为什么要折腾 RAGFlow团队需要一个开箱即用的 RAG 知识库系统调研了一圈RAGFlow 的文档预览、版面识别和可编排的 Agent 机制最贴合需求。官方推荐 Docker 部署Windows 机器上一套 WSL2 Docker Desktop 就能干省去配 Linux 虚拟机的麻烦。先说机器配置Win11 专业版16GB 内存i7-10700Docker Desktop 开了 WSL2 后端分配了 8GB 内存和 4 核。官方建议 16GB 起步内存不足的话后面 Elasticsearch 和 MySQL 会抢资源容易 OOM。第一步拉代码配环境git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker这里有个习惯永远不要在 Windows 文件系统直接跑 Docker 挂载性能差且权限容易乱。我把 repo 直接克隆到了 WSL 的~/workspace下\\wsl.localhost\Ubuntu\home\xxx\workspace用 VSCode 的 Remote-WSL 打开所有 docker 命令都在 WSL 里执行。第二步调整 vm.max_map_countElasticsearch 的硬要求ES 需要内存映射区域数量不低于 262144否则启动就崩。Windows 下得进 Docker 的 Linux 内核改wsl -d docker-desktop sysctl -w vm.max_map_count262144 exit这条命令每次重启电脑都会重置我干脆写了个.bat开机自启省得忘了。第三步起服务第一次翻车镜像拉取超时执行docker compose -f docker-compose.yml up -d然后看到valkey/valkey这个镜像卡住最后报net/http: timeout awaiting response headersDocker 默认的 registry 在国内慢得像蜗牛。虽然我在 Docker Desktop 里配了registry-mirrors指向docker.1ms.run但这家源当天似乎挂了。换源进Settings→Docker Engine把registry-mirrors改成https://docker.m.daocloud.io https://docker.rainbond.ccApply Restart。之后重新docker compose up -d镜像拉取速度瞬间到几十 MB/s。第四步80 端口被 Windows 锁死Permission denied所有镜像拉完容器纷纷启动但ragflow-cpu报错退出listen tcp 0.0.0.0:80: bind: An attempt was made to access a socket in a way forbidden by its access permissions.Windows 的 HTTP.sys 驱动经常霸占 80 端口IIS、SQL Server Reporting Services 都可能。关掉这些服务太麻烦我选择改端口映射。打开docker/docker-compose.yml实际上是include.txt引用的基础文件但最终生效的是.env里的变量发现 RAGFlow 用环境变量定义端口ports:-${SVR_WEB_HTTP_PORT}:8899于是编辑同目录下的.env文件加上SVR_WEB_HTTP_PORT8899这样宿主机走8899容器内依然走8899注意默认是80:80这里改成了8899:8899实际看 RAGFlow 默认容器内监听80但8899:80才是正确映射——不过更准确地说它容器内是80端口但配置里把容器内的8899映射到宿主机的变量所以我把宿主端口设为8899容器端口不变。我的最终配置是SVR_WEB_HTTP_PORT8899对应映射8899:8899其实容器内是80但.env里SVR_WEB_HTTP_PORT是宿主机端口容器内固定80吗查了一下官方docker-compose.yml它是${SVR_WEB_HTTP_PORT}:80所以这样改没问题。改完后docker compose down docker compose up -d这次容器跑起来了没有端口冲突。第五步打开浏览器迎来 502 Bad Gateway容器全绿docker compose ps全Up访问http://localhost:8899满屏 502。Nginx 错误日志容器内/var/log/nginx/error.log刷屏connect() failed (111: Connection refused) while connecting to upstream, client: 172.18.0.1, request: GET /api/v1/users/me明明后端9380和9381端口都在Nginx 却说连不上。第六步进容器探究竟发现时间差谜团我用docker exec -it docker-ragflow-cpu-1 /bin/bash进去直接curl -v http://localhost:9380/居然返回了{code:404}——说明 9380 服务是活着的那 Nginx 为什么报 refused翻看docker logs docker-ragflow-cpu-1 --tail 200发现了关键时间线Nginx 日志里最早的connect() failed时间戳是14:18而应用日志里出现Running on http://0.0.0.0:9380的时间是14:24:46之间差了足足 6 分多钟也就是说容器启动后RAGFlow 的 API 服务需要将近 7 分钟才能完全初始化加载模型、检查数据库、建表、加载插件。在这段时间里Nginx 已经启动并试图转发请求自然连不上。为什么初始化这么久看启动日志里有大量Loaded and normalized template file还有Init message_id sequence done然后还有一行RAGFlow server is ready after 390.22442984580994s initialization.390 秒正好 6 分半。第七步解决方案 —— 等就硬等没有黑科技就是等。在第一次up -d后用docker logs -f docker-ragflow-cpu-1盯着直到看到RAGFlow server is ready after ...这行再刷新浏览器页面秒开。中间我犯了个错误看到 502 就以为挂了反复重启容器导致初始化进程每次被打断永远看不到 ready。后来耐着性子让它跑完就成了。第八步登录 后续配置浏览器输入http://localhost:8899出现登录页。默认账号admin密码Infini123注意大小写。登录后建议立刻改密码。进入系统第一件事配置大模型。在“设置”里填好 API Key 和 Base URL我用的是 DeepSeek 的 API不然上传文档后无法生成答案。踩坑总览 经验现象根因解决方案镜像拉取超时国内镜像源不稳定换 DaoCloud/rainbond 源80 端口绑定失败Windows HTTP.sys 占坑改.env里的SVR_WEB_HTTP_PORT为 8899502 持续数分钟后端服务初始化慢Nginx 过早代理查看日志等待ready信息或增加proxy_connect_timeout可选容器内 curl 能通Nginx 不通时间错位Nginx 是在服务未就绪时尝试的连接之后缓存了失败状态等待后重启 Nginx 或直接刷新给后来者的几点建议别急着刷页面执行docker compose up -d后立刻docker logs -f盯着看到ready再访问能省一半折腾时间。内存给足RAGFlow ES MySQL MinIO Redis 全家桶至少 16GB否则 ES 会因内存不足退出。端口规划提前把 Web、API、Admin 端口在.env里规划好避免冲突。生产环境建议用docker compose -f docker-compose-gpu.yml启用 GPU或者单独拆数据库到外部。最终状态现在我的 RAGFlow 已经稳定跑了三天传了几十份技术文档Agent 串联了知识库检索和 LLM 回答效果符合预期。整个部署过程虽然曲折但把 Docker 网络、服务启动依赖、Nginx 反向代理这些点都摸了一遍也算值了。如果你也遇到 502先别慌——去看看容器的日志很多时候只是它还没准备好而不是它坏了。本文所有命令均在 Windows 11 WSL2 (Ubuntu 22.04) Docker Desktop 4.28 环境下验证。RAGFlow 版本 v0.27.0。