1. 环境准备:从零开始的Ubuntu 22.04 LTS基础配置
大家好,我是老张,一个在AI和智能硬件领域摸爬滚打了十多年的老码农。今天咱们不聊虚的,直接上手,带大家在最新的Ubuntu 22.04 LTS系统上,从源码开始,一步步把RAGFlow这个强大的深度文档理解引擎给搭起来。我最近刚在自己的开发服务器上完整走了一遍这个流程,踩了几个坑,也总结了不少省时省力的技巧,保证你跟着做,一次就能跑通。
为什么选择源码部署?我见过太多朋友图省事直接拉Docker镜像,结果遇到版本不兼容、网络问题或者想自定义某个模块时,两眼一抹黑。源码部署虽然前期步骤多点,但它给你的是最彻底的控制权和最清晰的问题排查路径。特别是对于想在生产环境做深度定制,或者像我一样有“强迫症”、喜欢搞清楚每一个依赖关系的开发者来说,源码部署是必经之路。Ubuntu 22.04 LTS作为长期支持版本,系统稳定,社区支持完善,是我们搭建服务的绝佳基石。
在开始敲命令之前,有件事必须做:确保你手头的是一台“干净”的Ubuntu 22.04 LTS系统。我建议直接用云服务商提供的最新LTS镜像,或者从官网下载ISO全新安装。如果你是在已有的、装了一堆杂七杂八软件的系统上操作,很可能会遇到依赖地狱,到时候排查起来可比重装系统麻烦多了。拿到系统后,第一件事不是急着装软件,而是先更新软件源列表。打开你的终端(我用的是MobaXterm连远程服务器,你也可以直接用系统终端),输入 sudo apt update 这个命令。它的作用是从配置的软件源服务器获取最新的软件包列表信息,就像你去超市前先得知道今天有什么货一样。接着,运行 sudo apt upgrade -y 来升级所有已安装的包到最新版本。-y 参数是为了自动确认,省得你一直按回车。这个过程可能会花点时间,取决于你的网络和需要更新的包数量,耐心等它完成。这一步是基础中的基础,能避免很多因系统组件过旧导致的诡异问题。
系统更新好后,我们就要准备核心的“施工工具”了。这里我强烈推荐使用 Miniconda 来管理Python环境,而不是直接用系统自带的Python。原因很简单:隔离。RAGFlow的依赖包非常多,版本要求也严格,用Conda创建一个独立的环境,就像给你的项目单独划了一个干净的“工作间”,无论你在里面怎么折腾,都不会影响到系统其他Python项目。先去清华大学开源软件镜像站找最新的Miniconda安装脚本,用 wget 命令下载下来。比如我当时的命令是 wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86_64.sh。下载完成后,用 bash Miniconda3-latest-Linux-x86_64.sh 来安装,安装过程中会问你是否将conda加入环境变量,一定要选“yes”。安装完成后,记得执行 source ~/.bashrc 或者新开一个终端,让配置生效。验证一下,输入 conda --version,能看到版本号就说明成功了。
接下来,在Conda环境里安装Python。RAGFlow官方推荐Python 3.10+,我实测用3.10.14和3.12.4都顺利跑通了。这里有个小经验:如果你打算用GPU来加速推理(特别是深度文档理解里的OCR和Embedding模型),最好在创建环境时就指定好Python版本,比如 conda create -n ragflow python=3.10.14。环境创建好后,用 conda activate ragflow 激活它。你会发现命令行提示符前面多了个 (ragflow),这表示你已经在这个独立环境里了。最后,把Git也装上,命令是 sudo apt install git -y,我们待会儿要靠它拉取源码。
2. 源码获取与依赖解析:避开安装路上的那些“坑”
环境准备好了,现在可以请出今天的主角——RAGFlow的源码了。源码部署的魅力就在于你能看到每一行代码,理解整个项目的结构,这对于后续的调试和二次开发至关重要。打开终端,确保你在你打算放置项目的目录下,比如我习惯放在 /home/username/Projects 下面。然后执行克隆命令:git clone https://github.com/infiniflow/ragflow.git。这个仓库有点大,包含前端和后端的所有代码,如果网络不太好可能会慢一点,耐心等待它完成。克隆成功后,你会得到一个 ragflow 文件夹,进去看一眼,cd ragflow,里面结构挺清晰的,docker 目录放着容器编排文件,web 是前端,api 和 scripts 这些是后端核心。
现在进入最关键的环节:安装Python依赖。这是源码部署最容易出问题的地方,也是我今天要重点分享的。首先,确保你已经在之前创建的 ragflow Conda环境里。然后,找到项目根目录下的 requirements.txt 文件。这个文件列出了项目运行所需的所有Python包及其版本。先别急着安装,我建议你花两分钟用 cat requirements.txt | wc -l 数一下,好家伙,一百五十多个依赖,是不是有点头皮发麻?别怕,大部分都能顺利安装,我们只需要关注几个“刺头”。
第一个“坑”是 Aspose.Slides。这个库用于处理PPT文档,但它的某个版本对Python版本有比较严格的限制。我当初用Python 3.12.4安装时,就卡在了 Aspose.Slides==24.2.0 这里,报错提示它只支持Python 3.5到3.11。解决方法很简单,用文本编辑器(比如 vim 或 nano)打开 requirements.txt 文件,找到这一行,把版本号改成 Aspose.Slides==24.6.0。新版本已经支持了Python 3.12,亲测有效。改完之后保存。
第二个需要注意的点是关于GPU的。如果你的服务器有NVIDIA GPU,并且CUDA版本高于12.0(可以用 nvidia-smi 命令查看CUDA版本),那么 onnxruntime-gpu 这个包需要特殊处理。在标准的 requirements.txt 里,它可能指向一个通用的版本。为了获得更好的GPU兼容性和性能,我们需要卸载默认安装的,然后从微软官方的特定索引地址安装。命令如下:
pip uninstall -y onnxruntime-gpu
pip install onnxruntime-gpu --extra-index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-cuda-12/pypi/simple/
这个 --extra-index-url 参数指定了一个包含CUDA 12版本onnxruntime-gpu的源。这一步很多人会忽略,结果就是虽然装了GPU版,但跑起来还是用CPU,速度慢得让人怀疑人生。
处理好这两个潜在问题后,就可以开始安装依赖了。执行 pip install -r requirements.txt。这个过程会非常漫长,因为要下载、编译和安装一百多个包。我当时的网络平均速度500KB/s左右,足足等了两个多小时。你可以去泡杯茶,或者处理点别的事情。安装过程中,如果遇到某个包暂时下载失败(网络波动),可以多试几次 pip install 命令,它会跳过已经安装成功的包。全部安装完成后,建议用 pip list 命令大致浏览一下,确认没有明显的版本冲突或安装失败。
3. 服务配置与启动:让RAGFlow真正“跑”起来
依赖全部搞定,我们的“房子”主体结构就算完工了。接下来是通水通电,配置各种服务,让RAGFlow能够正常运转。RAGFlow的架构设计得很清晰,它依赖几个核心的基础服务:一个向量数据库(用于存储和检索文档切片后的“块”),一个对象存储(用于存放上传的原始文档),以及一个关系型数据库(用于存元数据信息)。在源码部署中,官方提供了Docker Compose脚本来一键启动这些基础服务,这大大简化了我们的操作。
首先,进入项目中的 docker 目录:cd docker。你会看到几个 docker-compose 文件,我们主要用 docker-compose-base.yml。这个文件定义了MinIO(对象存储)、MySQL(关系数据库)和Infinity(向量数据库)的容器配置。在启动之前,我强烈建议你先检查一下这个文件,用 cat docker-compose-base.yml 看看端口映射和卷挂载。默认配置通常没问题,但如果你服务器的某些端口(比如9000, 3306)已经被占用,就需要在这里修改。确认无误后,运行启动命令:docker compose -f docker-compose-base.yml up -d。-d 参数是让容器在后台运行。执行后,用 docker ps 命令检查一下,应该能看到三个容器都处于 Up 状态。
基础服务跑起来了,但我们的RAGFlow后端应用还没配置。这里需要复制一个关键的启动脚本并配置环境变量。回到项目根目录,执行 cp docker/entrypoint.sh .,把容器用的入口脚本复制到当前目录。然后,用编辑器打开这个 entrypoint.sh 文件。我们需要修改里面的几个关键路径。找到设置 PYTHONPATH 的地方,它默认可能指向容器内的路径,我们需要把它改成我们当前源码的绝对路径。怎么获取呢?在终端输入 pwd,会打印出当前绝对路径,比如 /home/username/ragflow。把这个值赋给 PYTHONPATH。同时,确认 PY 变量指向的是你Conda环境中Python解释器的路径,可以用 which python 命令获取。修改后的片段大概长这样:
PY=/home/username/miniconda3/envs/ragflow/bin/python
export PYTHONPATH=/home/username/ragflow
另外,脚本里可能有一个设置 LD_LIBRARY_PATH 的地方,如果你没有单独配置CUDA等库的路径,这一行可以先注释掉(在行首加#)。还有一个非常有用的配置是设置Hugging Face镜像,国内访问会快很多:export HF_ENDPOINT=https://hf-mirror.com。改完后保存脚本,并给它加上执行权限:chmod +x ./entrypoint.sh。
接下来,我们需要确保应用配置文件能正确连接到刚启动的基础服务。主要看两个文件:docker/.env 和 conf/service_conf.yaml。.env 文件里定义了MySQL、MinIO等服务的连接密码,默认是开发环境用的,在生产环境你一定要改成强密码!service_conf.yaml 则是应用核心配置文件,你需要把里面 infinity、mysql、minio 这些服务对应的 host 地址,从原来的容器服务名(比如 mysql)改成你服务器的本机IP地址(或者 127.0.0.1),端口也要对应容器映射到宿主机的端口。比如,docker-compose-base.yml 里把MySQL的3306端口映射到了宿主机的 3306,那么这里 mysql 的 host 就填 127.0.0.1,port 填 3306。这一步是连通性的关键,配错了服务就启动不了。
万事俱备,现在可以启动RAGFlow的后端服务了。在项目根目录下,直接运行我们修改好的脚本:bash ./entrypoint.sh。如果一切配置正确,你会看到日志开始滚动输出,没有报错,最后服务在 9380 端口启动成功。你可以用 curl http://127.0.0.1:9380/v1/health 测试一下,如果返回健康的JSON信息,说明后端API服务已经正常工作了。
4. 前端部署与初步验证:完成最后一块拼图
后端服务在 9380 端口跑起来了,但我们还需要一个用户界面来操作和体验。RAGFlow的前端是一个基于Umi.js的React应用,我们需要把它构建出来并服务化。首先,进入前端目录:cd web。第一件事是安装Node.js依赖。由于网络原因,直接使用npm官方源可能会很慢甚至失败,所以这里指定使用国内的淘宝镜像源:npm install --registry=https://registry.npmmirror.com --force。--force 参数是为了强制重新安装,避免缓存导致的问题。这个过程也会下载不少包,请耐心等待。
依赖安装好后,在开发阶段,我们可以直接启动一个开发服务器来实时预览和调试。但在这之前,需要配置一下代理,让前端开发服务器能把API请求转发到我们刚启动的后端。找到 web 目录下的 .umirc.ts 文件(如果不存在,可能是 .umirc.js),用编辑器打开。找到 proxy 配置项,将其中的 target 修改为 http://127.0.0.1:9380。这样,前端在开发模式下发起的API请求就会被代理到本地的后端服务。配置好后,运行 npm run dev,开发服务器就会启动,通常默认在 8000 端口。打开浏览器访问 http://你的服务器IP:8000,应该就能看到RAGFlow的登录界面了。这是一种快速验证前后端联调是否成功的方式。
不过,开发模式不适合生产环境。我们需要构建出静态文件,并用一个更稳定的Web服务器来托管。在 web 目录下,运行构建命令:umi build。这个命令会编译、打包所有前端资源,生成一个 dist 文件夹。接下来,我们需要把这个 dist 目录放到一个Web服务器(比如Nginx)的根目录下。假设我们计划把前端部署在 /ragflow/web 目录。先创建目录:sudo mkdir -p /ragflow/web,然后把构建好的文件复制过去:sudo cp -r dist /ragflow/web/。这样,静态文件就位了。
最后一步,配置Nginx作为反向代理服务器。首先安装Nginx:sudo apt install nginx -y。安装完成后,我们需要修改Nginx的配置。RAGFlow的 docker 目录下贴心地提供了参考配置。我们把它们复制到Nginx的配置目录:sudo cp ../docker/nginx/proxy.conf /etc/nginx/, sudo cp ../docker/nginx/nginx.conf /etc/nginx/, sudo cp ../docker/nginx/ragflow.conf /etc/nginx/conf.d/。现在,重点编辑 /etc/nginx/conf.d/ragflow.conf 这个文件。你需要修改 server 块里的 root 指令,将其指向我们刚才放置前端文件的路径,比如 root /ragflow/web/dist;。同时,确保 location /api/ 或其他后端API的代理配置,指向正确的后端地址和端口(http://127.0.0.1:9380)。配置完成后,检查一下语法:sudo nginx -t,如果显示 syntax is ok,就可以重启Nginx服务了:sudo systemctl restart nginx。
现在,打开浏览器,直接访问你的服务器IP地址(HTTP默认80端口),或者你配置的域名,应该就能看到RAGFlow完整的前端界面了。你可以尝试注册一个账号,上传一份PDF或Word文档,体验一下从文档解析、智能切片到提问回答的完整流程。当你看到它不仅能准确回答你基于文档内容提出的问题,还能高亮显示答案在原文中的出处时,那种成就感,就是对我们这几个小时折腾的最好回报。整个部署过程虽然步骤不少,但每一步都有其意义,理解了这个过程,以后无论是升级、迁移还是排查问题,你都会胸有成竹。
483



被折叠的 条评论
为什么被折叠?



