1. 安装第三方组件：

k3s中安装es, mysql, redis, minio ，如果不想用k3s安装可以采用docker方式

2. 下载源码

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

3. 安装 Python 依赖

安装 uv

pipx install uv

安装 Python 依赖

uv sync --python 3.10 --all-extras # install RAGFlow dependent python modules

系统将创建一个名为 .venv 的虚拟环境，并将所有 Python 依赖项安装到该新环境中。

4. 修改配置

修改 conf/service_conf.yaml 中第三方组件的配置地址，如mysql端口等。

5. 启动 RAGFlow 后端服务

注释掉 docker/entrypoint.sh 文件中的 nginx 行。

# /usr/sbin/nginx

激活 Python 虚拟环境

source .venv/bin/activate
export PYTHONPATH=$(pwd)

设置 HF_ENDPOINT 环境变量以使用镜像站点：

export HF_ENDPOINT=https://hf-mirror.com

检查 conf/service_conf.yaml 中的配置，确保所有主机和端口都已正确设置。

运行 entrypoint.sh 脚本启动后端任务执行器：

JEMALLOC_PATH=$(pkg-config --variable=libdir jemalloc)/libjemalloc.so;
LD_PRELOAD=$JEMALLOC_PATH python rag/svr/task_executor.py 1;

启动后端服务API：

python api/ragflow_server.py;

启动 RAGFlow 前端服务:

# 进入 web 目录并安装前端依赖项：
cd web
npm install

在 .umirc.ts 文件中，将 proxy.target 更新为 http://127.0.0.1:9380

vim .umirc.ts

启动 RAGFlow 前端服务

npm run dev 

VSCODE单步调试

1. 找到图片中位置
   
2. 编辑launch.json文件
3. 根据手动启动流程添加配置
   下面是api_server的配置

{
            "name": "Python Debugger:api_server",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/api/ragflow_server.py",
            "console": "integratedTerminal",
            "justMyCode": true,
            "env": {
                // 激活虚拟环境的环境变量（等效于 source .venv/bin/activate）
                "PATH": "${workspaceFolder}/.venv/bin:${env:PATH}",
                "VIRTUAL_ENV": "${workspaceFolder}/.venv",
                // PYTHONPATH：当前工作目录（pwd 等效）
                "PYTHONPATH": "${workspaceFolder}",
                // Hugging Face 镜像源
                "HF_ENDPOINT": "https://hf-mirror.com",
                // JEMALLOC 路径（通过 pkg-config 动态获取）
                // "JEMALLOC_PATH": "${command:shellCommand.execute('pkg-config --variable=libdir jemalloc')}/libjemalloc.so"
                "LD_PRELOAD": "${env:/libjemalloc.so}"
            },
        }

报错处理

1. 知识库解析报错

错误一：

no_shard_available_action_exception 

解决方案：
es未分配分片导致。
执行 kubectl edit 编辑部署配置：

kubectl edit statefulset elasticsearch-master -n default

在打开的 YAML 配置中，找到 spec.template.spec.containers.env 部分，添加 / 修改 node.roles 环境变量：

spec:
  template:
    spec:
      containers:
      - name: elasticsearch  # 容器名称（通常是这个）
        env:
        # 找到或添加以下环境变量，设置角色为 master + data
        - name: node.roles
          value: master,data # 关键：同时启用主节点和数据节点角色
        # 其他环境变量（如 discovery.seed_hosts、cluster.initial_master_nodes 等）保持不变

错误二：
pptx解析失败：

1. ICU报错：
   Process terminated. Couldn’t find a valid ICU package installed on the system. Set the configuration flag System.Globalization.Invariant to true if you want to run with no globalization support.

解决方案：export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=true

2.libssl报错：
No usable version of libssl was found
解决方案：wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.24_amd64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.24_amd64.deb
sudo apt-get install -y libgdiplus libc6-dev