一、環境準備

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