一、环境准备

1. 安装 uv 和 pre-commit

如果已安装，可跳过。推荐使用官方方式安装，避免报错：

pipx install uv pre-commit
export UV_INDEX=https://mirrors.aliyun.com/pypi/simple

安装报错

使用清华源安装：

pipx install uv --pip-args="--index-url https://pypi.tuna.tsinghua.edu.cn/simple"
pipx install pre-commit --pip-args="--index-url https://pypi.tuna.tsinghua.edu.cn/simple"

设置环境变量：

pipx ensurepath

执行后请开启新终端。

---

二、下载项目源码并安装依赖

2. 下载代码并同步依赖

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/
uv sync --python 3.10 --all-extras  # 安装依赖模块

设置 HuggingFace 镜像地址：

export HF_ENDPOINT=https://hf-mirror.com
uv run download_deps.py
# 如果要使用镜像请执行：uv run download_deps.py --china-mirrors
pre-commit install

⚠️ 注意事项：

• download_deps文件中只有部分下载可以有镜像源，nltk部分的镜像源是没有的
• 安装中可能失败，因为墙的原因，需要想办法去下载nltk部分的内容，笔者这边wsl子系统，可以使用代理，手动执行以下命令下载：uv run download_nltk.py
• download_nltk.py其实就是download_deps.py的部分代码， 我拷贝出来了，因为我其他的部分都安装成功了

#!/usr/bin/env python3# PEP 723 metadata
# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "huggingface-hub",
#   "nltk",
#   "argparse",
# ]
# ///
import nltk
import os
import argparseif __name__ == "__main__":parser = argparse.ArgumentParser(description='Download dependencies with optional China mirror support')parser.add_argument('--china-mirrors', action='store_true', help='Use China-accessible mirrors for downloads')args = parser.parse_args()local_dir = os.path.abspath('nltk_data')for data in ['wordnet', 'punkt', 'punkt_tab']:print(f"Downloading nltk {data}...")nltk.download(data, download_dir=local_dir)

3. 处理 pyicu 安装失败问题

uv sync 时 pyicu 报错的解决方案：

官方仓库：https://gitlab.pyicu.org/main/pyicu

推荐执行以下步骤后重新安装依赖：

# EITHER - from apt directly https://packages.debian.org/source/stable/pyicu
apt-get install python3-icu
# OR - from source
apt-get install pkg-config libicu-dev
# pip install --no-binary=:pyicu: pyicu

---

三、启动依赖服务

4. 启动基础服务（MinIO、Elasticsearch、Redis、MySQL）

docker compose -f docker/docker-compose-base.yml up -d

5. 修改 /etc/hosts

添加以下内容，确保 conf/service_conf.yaml 中的 host 地址解析成功：

127.0.0.1       es01 infinity mysql minio redis sandbox-executor-manager

---

四、其他环境依赖

6. 安装 jemalloc（如系统未安装）

# ubuntu
sudo apt-get install libjemalloc-dev# centos
sudo yum install jemalloc

---

五、启动后端服务

7. 启动后端脚本

source .venv/bin/activate
export PYTHONPATH=$(pwd)
bash docker/launch_backend_service.sh

如果 .sh 无执行权限，执行：

chmod 744 docker/launch_backend_service.sh

8. 常见报错处理

报错内容：

import pyodbc ImportError: libodbc.so.2: cannot open shared object file: No such file or directory

解决方法：

sudo apt install libodbc2

---

六、启动前端服务

9. 安装依赖

cd web
npm install

10. 启动开发服务器

npm run dev

---

七、调试模式说明（Debug）

阅读源码发现其实就是启动 task_executor.py 和 ragflow_server.py 两个服务，但是还有相关的环境变量不知道怎么设置

调试相关截图：

在pycharm的debug配置中配置环境变量

可能报错

#redis_port 无法解析

不知道原因：后面新建了个环境变量文件，把所有的注释都去掉，就能用了

---

环境变量配置（Debug用）

配置文件示例（建议放入 .env 或手动 export）：

DOC_ENGINE=elasticsearch
STACK_VERSION=8.11.3
ES_HOST=es01
ES_PORT=1200
ELASTIC_PASSWORD=infini_rag_flow
OS_PORT=1201
OS_HOST=opensearch01
OPENSEARCH_PASSWORD=infini_rag_flow_OS_01
KIBANA_PORT=6601
KIBANA_USER=rag_flow
KIBANA_PASSWORD=infini_rag_flow
MEM_LIMIT=8073741824
INFINITY_HOST=infinity
INFINITY_THRIFT_PORT=23817
INFINITY_HTTP_PORT=23820
INFINITY_PSQL_PORT=5432
MYSQL_PASSWORD=infini_rag_flow
MYSQL_HOST=mysql
MYSQL_DBNAME=rag_flow
MYSQL_PORT=5455
MINIO_HOST=minio
MINIO_CONSOLE_PORT=9001
MINIO_PORT=9000
MINIO_USER=rag_flow
MINIO_PASSWORD=infini_rag_flow
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=infini_rag_flow
SVR_HTTP_PORT=9380
RAGFLOW_IMAGE=infiniflow/ragflow:v0.19.0-slim
TIMEZONE='Asia/Shanghai'
DOC_BULK_SIZE=4
EMBEDDING_BATCH_SIZE=16
REGISTER_ENABLED=1
NLTK_DATA=/home/ubuntu/data/code/ragflow/nltk_data