前言
这两年深切的感受到AI的大爆发，干活越来越快也越来越懂自己了，但是完全依靠外在力量总感觉会对个人的成长不利，有工具不用也更像个傻子。AI本身不会形成壁垒，你能用别人也会用，想要在当前环境更突出，个人技术实力当然是一方面，毕竟AI是个人能力放大器；同时，同样的工具用的更好我觉得也是一方面，建立自己或者企业的知识库，让你的AI更懂自己，更贴近生产需要，作为知识沉淀我觉得是一个很好的方向。
本文记录一次在 Ubuntu 24.04 上部署 RAGFlow 的过程，部署方式为 Docker Compose，并启用 NVIDIA GPU 与 Docling 解析器。整体思路是：先准备 Docker 与 NVIDIA Container Toolkit，再拉取 RAGFlow 官方仓库，最后通过 .env 调整 GPU、端口和 Docling 配置。
文中的端口、软件源和访问地址均为示例，请按自己的环境替换。
部署环境
| 项目 | 说明 |
|---|---|
| 操作系统 | Ubuntu 24.04 LTS |
| 部署方式 | Docker Compose |
| RAGFlow 镜像 | infiniflow/ragflow:latest |
| 检索引擎 | Elasticsearch |
| 文档解析 | Docling |
| GPU | NVIDIA GPU，宿主机 nvidia-smi 可正常输出 |
| Web 端口 | 示例使用 8080 |
最低建议配置：
| 项目 | 建议 |
|---|---|
| CPU | 4 核及以上 |
| 内存 | 16 GB 及以上 |
| 磁盘 | 50 GB 以上可用空间，建议预留更多 |
| GPU | NVIDIA 显卡，并已安装驱动 |
| 网络 | 能访问 GitHub、Docker 镜像仓库和相关依赖源 |
一、安装基础依赖
bash
sudo apt-get update -qq
sudo apt-get install -y git ca-certificates curl gnupg lsb-release二、安装 Docker Engine
2.1 添加 Docker 软件源
如果访问 Docker 官方源稳定，可以使用官方文档中的安装方式。国内网络环境下，也可以切换为可访问的镜像源。下面以阿里云 Docker CE 源为例：
bash
sudo bash -c '
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list
apt-get update -qq
'2.2 安装 Docker 和 Compose 插件
bash
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin2.3 配置 Docker 权限和镜像加速
将当前用户加入 docker 组：
bash
sudo usermod -aG docker $USER加入用户组后，需要重新登录 shell，或者临时使用 sg docker -c '<command>' 执行 Docker 命令。
如果拉取镜像速度较慢，可以配置 Docker 镜像加速器。下面的地址只是示例，请替换成自己可用的镜像源：
bash
sudo bash -c 'cat > /etc/docker/daemon.json << EOF
{
"registry-mirrors": [
"https://docker.1ms.run",
"https://docker.xuanyuan.me"
]
}
EOF'
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl enable docker验证：
bash
docker --version
docker compose version三、安装 NVIDIA Container Toolkit
RAGFlow 启用 GPU 时，容器需要能访问宿主机 NVIDIA 驱动。
bash
sudo bash -c '
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
sed "s#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g" > /etc/apt/sources.list.d/nvidia-container-toolkit.list
apt-get update -qq
apt-get install -y nvidia-container-toolkit
nvidia-ctk runtime configure --runtime=docker
systemctl restart docker
'验证容器内是否可以访问 GPU：
bash
sg docker -c 'docker run --rm --gpus all nvidia/cuda:12.6.3-base-ubuntu24.04 nvidia-smi'如果能看到完整的 nvidia-smi 输出，说明 Docker GPU 运行时配置成功。
四、部署 RAGFlow
4.1 克隆 RAGFlow 仓库
bash
cd ~
git clone https://github.com/infiniflow/ragflow.git如果直连 GitHub 不稳定，可以使用自己信任的代理或镜像方式拉取仓库。
4.2 修改 .env
进入 Docker 配置目录：
bash
cd ~/ragflow/docker
cp .env .env.bak修改关键配置：
bash
sed -i 's/^DEVICE=${DEVICE:-cpu}/DEVICE=${DEVICE:-gpu}/' .env
sed -i 's/^USE_DOCLING=false/USE_DOCLING=true/' .env
sed -i 's/^SVR_WEB_HTTP_PORT=80$/SVR_WEB_HTTP_PORT=8080/' .env
sed -i 's/^SVR_WEB_HTTPS_PORT=443$/SVR_WEB_HTTPS_PORT=8443/' .env配置说明：
| 配置项 | 建议值 | 说明 |
|---|---|---|
DEVICE |
gpu |
启用 GPU |
USE_DOCLING |
true |
启用 Docling 文档解析 |
SVR_WEB_HTTP_PORT |
8080 |
避免占用宿主机 80 端口 |
SVR_WEB_HTTPS_PORT |
8443 |
避免占用宿主机 443 端口 |
DOC_ENGINE |
elasticsearch |
默认检索引擎 |
SVR_HTTP_PORT |
9380 |
RAGFlow API 端口 |
安全提醒：.env 中包含 MySQL、Elasticsearch 等组件密码。测试环境可以先使用默认值，生产环境建议修改为强密码，并妥善保存。
4.3 拉取镜像
RAGFlow 相关镜像体积较大，首次拉取可能需要较长时间。建议放到后台执行，避免 SSH 会话断开导致任务中断：
bash
cd ~/ragflow/docker
nohup sg docker -c 'docker compose pull' > ~/ragflow_pull.log 2>&1 &查看进度：
bash
tail -f ~/ragflow_pull.log
sg docker -c 'docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}"'如果拉取过程中出现网络 EOF、连接重置或单个镜像层失败，通常可以重新执行 docker compose pull 继续拉取。
常见镜像包括：
| 镜像 | 用途 |
|---|---|
infiniflow/ragflow:latest |
RAGFlow 主服务 |
elasticsearch:8.11.3 |
检索与索引 |
mysql:8.0.39 |
元数据存储 |
minio |
对象存储 |
valkey/valkey:8 |
缓存 |
4.4 启动服务
bash
cd ~/ragflow/docker
sg docker -c 'docker compose up -d'查看容器：
bash
sg docker -c 'docker compose ps'4.5 等待首次初始化
首次启动时，RAGFlow 容器可能会继续下载 GPU 依赖、Python 包或文档解析相关模型。这个阶段 Web UI 不一定马上可用，等待 10 到 20 分钟是正常的。
查看 RAGFlow 日志：
bash
sg docker -c 'docker logs -f docker-ragflow-gpu-1'看到类似下面的日志，说明服务基本就绪：
text
RAGFlow server is ready after XX.Xs initialization.
task_executor_xxx reported heartbeat五、验证部署
5.1 检查容器状态
bash
cd ~/ragflow/docker
sg docker -c 'docker compose ps'正常情况下，RAGFlow、Elasticsearch、MySQL、MinIO、Valkey 等容器应处于 Up 或 healthy 状态。
5.2 检查 Web UI
如果在服务器本机验证：
bash
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8080如果从其他设备访问，将 SERVER_IP 替换为服务器 IP 或域名：
bash
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://SERVER_IP:8080浏览器访问：
text
http://SERVER_IP:80805.3 检查 GPU 和 Docling
bash
sg docker -c 'docker exec docker-ragflow-gpu-1 env' | grep -E 'DEVICE|DOCLING|DOC_ENGINE'期望能看到：
text
DEVICE=gpu
USE_DOCLING=true
DOC_ENGINE=elasticsearch检查容器内 GPU：
bash
sg docker -c 'docker exec docker-ragflow-gpu-1 nvidia-smi' | head -10如果能显示 GPU 信息，说明容器已经正确挂载 NVIDIA 设备。
到此部署结束
六、端口说明
| 服务 | 容器端口 | 宿主机端口 | 说明 |
|---|---|---|---|
| RAGFlow Web UI | 80 | 8080 | Web 入口 |
| RAGFlow HTTPS | 443 | 8443 | HTTPS 入口，需要自行配置证书 |
| RAGFlow API | 9380 | 9380 | 后端 API |
| Admin Server | 9381 | 9381 | 管理后端 |
| MCP Server | 9382 | 9382 | MCP 服务 |
| Elasticsearch | 9200 | 1200 | 检索引擎 |
| MySQL | 3306 | 3306 | 元数据库 |
| Valkey | 6379 | 6379 | 缓存 |
| MinIO API | 9000 | 9000 | 对象存储 API |
| MinIO Console | 9001 | 9001 | 对象存储控制台 |
实际端口以 ~/ragflow/docker/.env 和 Docker Compose 配置为准。如果服务器还有其他服务，建议先检查端口占用：
bash
sudo ss -tulpen | grep -E ':80|:443|:8080|:8443|:9380'七、常用运维命令
进入部署目录：
bash
cd ~/ragflow/docker查看日志：
bash
sg docker -c 'docker logs -f docker-ragflow-gpu-1'
sg docker -c 'docker logs --tail 100 docker-ragflow-gpu-1'查看状态：
bash
sg docker -c 'docker compose ps'停止服务：
bash
sg docker -c 'docker compose down'启动服务：
bash
sg docker -c 'docker compose up -d'重启 RAGFlow 主容器：
bash
sg docker -c 'docker compose restart ragflow-gpu'进入 RAGFlow 容器：
bash
sg docker -c 'docker exec -it docker-ragflow-gpu-1 /bin/bash'数据位置：
| 数据 | 位置 |
|---|---|
| Elasticsearch | Docker volume，例如 docker_esdata01 |
| MySQL | Docker volume，例如 docker_mysql_data |
| MinIO | Docker volume，例如 docker_minio_data |
| Valkey | Docker volume，例如 docker_redis_data |
| RAGFlow 日志 | ~/ragflow/docker/ragflow-logs/ |
如果需要完全删除数据卷，务必先确认已有备份：
bash
sg docker -c 'docker compose down -v'-v 会删除 Compose 创建的数据卷，MySQL、Elasticsearch、MinIO 等数据都会被清理。
八、常见问题
1. Docker 官方源连接失败
症状可能是 curl: (35) Recv failure、连接重置或超时。可以换成当前网络可访问的软件源，例如阿里云、清华源或 Docker 官方推荐方式。
2. GitHub 克隆失败
如果出现 TLS 连接中断、超时等问题，可以换网络、配置代理，或使用可信的 GitHub 加速方式。仓库拉取成功后，后续主要依赖 Docker 镜像和容器启动。
3. Docker 镜像层拉取失败
大镜像拉取过程中偶发 EOF、timeout、not found 等错误时，可以重复执行：
bash
sg docker -c 'docker compose pull'Docker 会复用已经下载完成的镜像层。
4. 80 或 443 端口被占用
如果宿主机已经有 Nginx、Apache、面板程序或其他 Web 服务，直接使用 80/443 可能冲突。可以在 .env 中将 RAGFlow Web 端口改为 8080/8443，然后重新启动：
bash
sg docker -c 'docker compose up -d'5. 首次启动后 Web 页面打不开
首次启动会初始化数据库、下载依赖和加载模型，GPU + Docling 模式下耗时更明显。建议先看日志，不要急着反复重启：
bash
sg docker -c 'docker logs -f docker-ragflow-gpu-1'九、部署建议
- 生产环境不要直接使用默认数据库密码，应在
.env中改成强密码。 - 对外开放 Web UI 前，建议增加反向代理、HTTPS 和访问控制。
- RAGFlow 镜像如果用于长期运行，建议固定版本标签，避免
latest自动变化带来不可控差异。 - 重要数据在 Docker volume 中，升级或清理前先备份。
- 网络和 DNS 相关改动要谨慎，尤其是远程 SSH 部署时，建议保留一个可回滚的连接方式。
总结
这次部署的关键点主要有三个：Docker Compose 环境要干净可用，NVIDIA Container Toolkit 要让容器正确访问 GPU，RAGFlow 的 .env 要明确开启 DEVICE=gpu 和 USE_DOCLING=true。首次启动时间较长是正常现象，只要日志持续推进，等初始化完成后就可以通过 Web UI 使用 RAGFlow。