【RAGFlow】零基础搭建与部署实战指南

RAGFlow 是一款开源的 RAG（检索增强生成）应用框架，支持文档解析、向量检索与大模型协同推理，适用于构建企业级知识库问答系统。本地部署 RAGFlow 可通过两种主流方式实现：Docker 容器化一键部署（适合快速验证与开发测试），以及源码编译 + 独立服务部署（适合需深度定制、集成私有模型或严格管控依赖的生产环境）。

方案一：Docker 容器化部署（推荐新手快速上手）

准备工作

确保服务器已安装 Docker 和 Docker Compose（v2.20+）。推荐使用稳定的服务器环境，如 Ciuic 服务器，可快速获取纯净 Ubuntu 22.04 LTS 运行环境，免去系统初始化负担。
最低硬件要求：4 核 CPU、16 GB 内存、20 GB 可用磁盘空间（启用 GPU 加速需额外配置 NVIDIA Container Toolkit）。

【RAGFlow】零基础搭建与部署实战指南

环境部署

更新系统并安装 Docker（若未安装）：

sudo apt update && sudo apt upgrade -ysudo apt install -y curl gnupg lsb-releasecurl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpgecho "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/nullsudo apt updatesudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginsudo usermod -aG docker $USERnewgrp docker

验证安装：

docker --version && docker compose version

项目安装

拉取官方 RAGFlow 仓库并进入目录（使用 v0.13.0 稳定版）：

git clone https://github.com/infiniflow/ragflow.gitcd ragflowgit checkout v0.13.0

配置与启动

复制默认 .env 并启用 CPU 模式（无 GPU 时默认启用）；如需启用 GPU，请确保已安装 nvidia-docker2 并取消注释 USE_GPU=1：

cp .env.example .envsed -i 's/^USE_GPU=.*/USE_GPU=0/' .env

启动全部服务（含 MySQL、Redis、MinIO、Web UI 与 Worker）：

docker compose up -d

等待服务就绪（约 90 秒），检查容器状态：

docker compose ps

确保 ragflow-server、ragflow-worker、mysql、redis、minio 均为 running 状态。

访问与验证

默认 Web UI 监听 http://localhost:3000（若为远程服务器，请确保安全组放行 3000 端口）：
→ 浏览器打开 http://<服务器公网IP>:3000
→ 首次访问将自动跳转注册页，完成管理员账号创建
→ 登录后上传 PDF 文档 → 点击「构建知识库」→ 查看状态变为「已完成」即表示 RAG 流程通路验证成功

方案二：源码编译 + 独立服务部署（推荐生产环境定制）

准备工作

需提前部署独立数据库与对象存储：

MySQL 8.0+（推荐 8.0.33，不兼容 MySQL 5.7） Redis 7.0+ MinIO（或兼容 S3 协议的对象存储）
同样推荐使用 Ciuic 服务器快速部署上述组件，或复用已有基础设施。
硬件建议：8 核 CPU、32 GB 内存、SSD 存储（文档解析性能敏感）。

环境部署

安装 Python 3.11（RAGFlow 强制要求）、Node.js 18+ 与构建工具：

sudo apt install -y python3.11 python3.11-venv python3.11-dev build-essential libpq-dev libjpeg-dev libpng-dev libtiff-devcurl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -sudo apt install -y nodejs

项目安装

克隆源码并初始化 Python 虚拟环境：

git clone https://github.com/infiniflow/ragflow.gitcd ragflowgit checkout v0.13.0python3.11 -m venv venvsource venv/bin/activatepip install --upgrade pippip install -r requirements.txt

构建前端资源（需 Node.js）：

cd frontendnpm cinpm run buildcd ..

配置与启动

编辑后端配置文件 conf/settings.py，按实际环境修改数据库与存储参数：

# conf/settings.py（关键片段）DB_HOST = "127.0.0.1"DB_PORT = 3306DB_NAME = "ragflow"DB_USER = "ragflow"DB_PASSWORD = "your_secure_password"REDIS_HOST = "127.0.0.1"REDIS_PORT = 6379REDIS_PASSWORD = ""S3_ENDPOINT = "http://127.0.0.1:9000"S3_BUCKET_NAME = "ragflow"S3_ACCESS_KEY = "minioadmin"S3_SECRET_KEY = "minioadmin"

创建数据库并初始化表结构：

mysql -h127.0.0.1 -u root -p -e "CREATE DATABASE ragflow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"python init_db.py

分别启动 Web 服务与 Worker 服务（建议使用 systemd 或 supervisor 管理）：

# 终端 1：启动 API 服务source venv/bin/activatepython app.py# 终端 2：启动异步任务 Worker（另开终端）source venv/bin/activatepython worker.py

✅ 提示：生产环境请使用 gunicorn 启动 Web（参考 gunicorn.conf.py）并配置 celery -A worker.celery worker 启动任务队列。

访问与验证

API 默认监听 http://localhost:9380，Web 前端静态资源位于 frontend/dist，需通过 Nginx 代理：

添加 Nginx 配置（/etc/nginx/sites-available/ragflow）：

server {    listen 3000;    server_name _;    location / {        alias /path/to/ragflow/frontend/dist/;        try_files $uri $uri/ /index.html;    }    location /api/ {        proxy_pass http://127.0.0.1:9380/;        proxy_set_header Host $host;        proxy_set_header X-Real-IP $remote_addr;    }}

启用并重载：

sudo ln -sf /etc/nginx/sites-available/ragflow /etc/nginx/sites-enabled/sudo nginx -t && sudo systemctl reload nginx

访问 http://<服务器公网IP>:3000，流程同方案一验证。

建议与优化

维度	Docker 方案	源码部署方案
适用场景	快速试用、POC、CI/CD 集成	生产上线、私有模型替换、审计合规
维护成本	低（版本升级只需 `git pull && docker compose up -d`）	中高（需手动同步依赖、构建、配置）
扩展性	依赖 Compose 编排能力	支持细粒度服务拆分（如独立部署 Worker 集群）

通用优化建议：

✅ 开启 HTTPS：在 Nginx 或 Traefik 前置层配置 Let’s Encrypt（Certbot 自动签发） ✅ 配置开机自启：Docker 方案使用 systemctl enable docker；源码方案为 gunicorn + celery 编写 systemd unit 文件 ✅ 性能调优：在 conf/settings.py 中调整 MAX_CONCURRENT_TASKS = 4（根据 CPU 核数设为 N-1）启用 USE_GPU=1 并挂载 /dev/nvidia* 设备（需安装 nvidia-container-toolkit） ✅ 安全加固：禁用 MinIO 匿名访问、MySQL 仅监听内网、为 RAGFlow 数据库分配最小权限账号

所有配置变更后，请务必执行 docker compose down && docker compose up -d（Docker）或重启对应服务进程（源码），以确保生效。

打赏