[Question]: Build docker Image Fail

问题场景

用户在本地执行 RAGFlow Docker 镜像构建命令（含 embedding 模型），构建过程长时间无响应或反复重试，最终失败。

报错原文

[Question]: Build docker Image Fail
（典型伴随日志：Could not find a version that satisfies the requirement pip / No matching distribution found for pip / 连接 mirrors.aliyun.com 超时）

原因分析

最可能原因是网络连通性故障，特别是在设置了 NEED_MIRROR=1 时，构建脚本会尝试从阿里云或清华镜像站下载依赖，若镜像站不可达、超时或不同步，将导致 pip 安装失败或“卡死”。少数情况与 Docker 版本（未使用 Buildx）、构建上下文包含大文件或内存不足有关。

环境排查

• 检查能否从构建环境访问镜像站：curl -I https://mirrors.aliyun.com/pypi/simple/
• 确认 NEED_MIRROR 环境变量是否被设置（echo $NEED_MIRROR）
• 检查 Docker 版本及是否启用了 Buildx：docker buildx version
• 检查构建上下文目录大小（du -sh .），避免包含过大 log 或数据文件
• 确认系统内存/磁盘空间充足（构建 embedding 模型需要额外空间）

解决步骤

1. 取消镜像源（最优先尝试）：执行构建时不设置 NEED_MIRROR，例如 docker build -t ragflow:latest .（不加 --build-arg NEED_MIRROR=1）。
2. 切换其他可用镜像：若必须使用镜像，可尝试将 NEED_MIRROR 指向其他稳定源（如清华镜像 https://pypi.tuna.tsinghua.edu.cn/simple）。
3. 使用 Docker Buildx：在 macOS 或 Windows 上，docker buildx build --load -t ragflow:latest . 可规避 SSL/包安装异常。
4. 构建精简镜像（跳过模型）：添加参数 --build-arg LIGHTEN=1，如 docker build --build-arg LIGHTEN=1 -t ragflow:slim .。
5. 清理构建上下文：将 Dockerfile 移至空目录，或使用 .dockerignore 排除不需要的文件。

验证方法

构建命令顺利完成，不出现卡死或输出明显错误日志，最终生成镜像并可通过 docker images 看到 ragflow 镜像。

参考来源

infiniflow/ragflow #8101

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。