【记录一下】RagFlow 本地安装详细步骤（Windows + Linux）

RagFlow 本地安装详细步骤（Windows + Linux）

一、系统要求

• 硬件：CPU ≥ 4核，内存 ≥ 16GB，磁盘 ≥ 50GB（推荐SSD）
• 软件：
  • Windows：WSL2 + Docker Desktop（需启用WSL集成）
  • Linux：Docker ≥ 24.0.0，Docker Compose ≥ v2.26.1
• 其他：需科学上网或配置国内镜像源加速下载

二、Windows 安装步骤

1. 安装 WSL2 与 Docker Desktop

1. 启用 WSL2：

   • 以管理员身份打开PowerShell，执行：

     wsl --install
     

   • 重启系统后，从Microsoft Store安装 Ubuntu 20.04+ 发行版。

2. 安装 Docker Desktop：

   • 访问Docker官网下载安装包。
   • 安装时勾选 “Use WSL 2 based engine”，并在设置中启用 WSL集成（选择已安装的Ubuntu）。

2. 部署 Ollama 服务（AI后端）

1. 访问Ollama官网下载Windows版安装包。
2. 解压后启动服务：

   ollama serve
   

3. 克隆 RagFlow 仓库

1. 打开Ubuntu终端，执行：

   git clone https://github.com/infiniflow/ragflow.git
   cd ragflow
   

4. 配置环境

1. 修改 .env 文件（按需调整端口和存储路径）：

   cp .env.example .env
   # 示例修改
   API_PORT=9380
   WEB_PORT=3000
   VOLUME_DIR=/mnt/d/ragflow_data  # 推荐使用WSL内路径
   

5. 启动服务

1. 使用Docker Compose启动：

   docker-compose up -d
   

   • 首次启动需下载约10GB镜像，耐心等待。

6. 验证安装

1. 检查容器状态：

   docker ps
   

   • 应看到 ragflow-server、elasticsearch、redis 3个容器运行中。
2. 浏览器访问：

   http://localhost:3000
   

三、Linux 安装步骤（Ubuntu 20.04+ 示例）

1. 环境准备

1. 更新系统并安装依赖：

   sudo apt update && sudo apt upgrade -y
   sudo apt install docker.io docker-compose python3-pip git -y
   

2. 调整系统参数（防止内存映射不足）：

   sudo sysctl -w vm.max_map_count=262144
   # 永久生效（需重启）
   echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
   

2. 安装 Ollama（AI后端）

1. 下载并解压：

   curl -L https://ollama.com/download/ollama-linux-amd64.tgz -o ollama-linux-amd64.tgz
   tar xzvf ollama-linux-amd64.tgz
   sudo mv ollama /usr/local/bin/
   

2. 启动服务：

   ollama serve &
   

3. 克隆 RagFlow 仓库

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

4. 配置镜像加速（可选）

1. 修改 docker/.env 文件，设置国内镜像源：

   # 示例：使用阿里云镜像
   RAGFLOW_IMAGE=registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:v0.16.0
   

5. 启动服务

docker compose -f docker-compose-CN.yml up -d

6. 验证安装

1. 检查日志：

   docker logs -f ragflow-server
   

   • 看到 Running on http://0.0.0.0:9380 表示启动成功。
2. 浏览器访问：

   http://localhost:9380
   

四、通用配置与问题解决

1. 端口冲突

• 修改 .env 文件中的 HTTP_PORT 或 API_PORT 值，重启服务：

  docker-compose down && docker-compose up -d
  

2. 镜像下载慢

• Windows/Linux：在 docker/.env 中配置国内镜像源：

  # 示例：Docker Hub镜像加速
  DOCKER_REGISTRY=registry.cn-hangzhou.aliyuncs.com
  

3. 权限问题

• 将当前用户加入 docker 组：

  sudo usermod -aG docker $USER
  newgrp docker  # 立即生效
  

4. 数据持久化

• 默认数据存储在 ./docker/volumes，可通过 VOLUME_DIR 修改路径。

五、安装后操作

1. 注册与登录：
   • 浏览器访问控制台，使用邮箱注册账号。
2. 配置模型：
   • 进入 Model Providers 页面，添加本地或在线模型（如Ollama、OpenAI）。
3. 创建知识库：
   • 上传文档（支持PDF/DOCX/TXT等），选择分块模板和嵌入模型（推荐 BAAI/bge-large-zh-v1.5）。
4. 测试问答：
   • 在 Chat 模块输入问题，验证知识库检索效果。

---

附：常见错误解决

• 镜像拉取失败：检查网络或手动下载镜像后导入。
• 容器退出：查看日志定位错误（docker logs <容器名>）。
• 性能不足：增加内存分配（Docker设置中调整资源限制）。