Windows+PyCharm下RAGFlow二次开发环境搭建：Docker与WSL2最佳实践-代码聚汇网

Windows+PyCharm下RAGFlow二次开发环境搭建：Docker与WSL2最佳实践

RAGFlow二次开发Windows环境搭建PyCharm调试

|难度：普通|阅读约 43 分钟

先说结论：把RAGFlow做二次开发，最舒服的路线不是把它当成一个普通Python项目，在Windows上直接python xxx.py，而是让Docker Desktop接管MySQL、Redis、MinIO这些基础设施，代码和调试过程交给PyCharm。如果你还想让前端和后端都能自由改、随时断点，那最好再把项目主体放进WSL2，让PyCharm直接连接WSL2里的Python解释器。

这个组合我最近刚完整跑通一遍，中间踩了不少文档里没写的坑。这篇文章就从零开始，把我实际操作的每一步、每个配置、每个排查思路都记录下来。目标是让同样想在window + PyCharm环境里做ragflow二次开发的人，看完就能搭出自己的调试环境，而不是只会跑官方Docker一键部署。

1. RAGFlow项目结构和Windows二开的真实难点

1.1 你要改的是什么：前后端加依赖服务

RAGFlow不是那种只有一两个入口的轻量项目。它的代码仓库里大致能分成几块：

api/：Python写的后端服务，主要提供REST API、文档解析任务调度、知识库管理逻辑。
web/：React + TypeScript + Vite写的前端页面，管理知识库、对话测试、Agent编排都在这层。
一堆基础设施：MySQL存业务数据，Redis做缓存，MinIO存文档与切片后的文件，Elasticsearch或者其他检索引擎做全文搜索。
还需要模型服务：要么接OpenAI兼容接口，要么接本地的Ollama、DeepSeek等embedding和chat模型。

如果你只是部署使用，最简单的办法是直接执行docker compose up -d，让所有服务都在容器里跑。但二次开发的情况完全不同：你可能要改一个Knowledge Base的API接口，或者想在前端加一个业务按钮。每次改动都重新构建整个Docker镜像？且不说构建时间，光是排查问题就够折腾的。

所以二开环境的正确形态是：基础设施继续留在容器里，后端API进程从前端、从你的IDE里启动，前端也用开发服务器热加载。你可能只是改了某一行Python代码，PyCharm里点一下重启，几秒钟就能看到效果；也可能只改了某个组件，页面自动刷新。

1.2 为什么官方Docker Compose不适合直接改代码

官方仓库的Docker Compose默认会启动ragflow-server容器，而且它的Dockerfile会把整个项目源码复制进镜像。如果你在宿主机上把代码改了，要么把代码目录挂载进容器，要么在容器里改代码。后者的痛苦我相信做过的人都懂：容器内编辑器不好用，想在PyCharm里断点又跨越了容器和宿主机两层。另外，RAGFlow的镜像经常是已经部署好的环境，很多依赖是你不需要管的，一旦你改了依赖版本，容器内和拉取的镜像版本不一致，各种诡异问题就来了。

实时调试的最佳体验一定是：后端进程是PyCharm里那个可以右键Run的进程，而不是某个黑盒容器。前端同理，Vite开发服务器。那MySQL、Redis、MinIO这些又不好在Windows上原生安装和配置，所以把它们留在容器里，用端口映射暴露给宿主机，是最省事的方案。

1.3 Windows二开方案设计：容器与代码分离

RAGFlow官方文档明确推荐在Linux上运行。为了在Windows上达到接近Linux的效果，我最终采用的方案是这样的：

在Windows上安装Docker Desktop，并启用WSL2后端。
在WSL2的Ubuntu发行版中放RAGFlow代码，同时使用Docker Desktop提供的docker命令来启动依赖服务。
PyCharm打开WSL2里的项目，Python解释器也选择WSL2中的虚拟环境。
依赖服务如MySQL、Redis、MinIO通过容器的端口映射暴露出来，本地后端通过localhost访问它们。
前端在WSL2里执行npm run dev，PyCharm里能看到日志，浏览器打开Vite提供的地址访问。

整套方案里，代码总共有两份副本：一份是Docker Compose启动的基础服务，一份是你正在修改的源码。两者通过端口连接，互不覆盖。

为什么不是用Windows原生Python直接跑后端？因为RAGFlow的某些Python依赖在Windows上可能会出现编译兼容问题，尤其是和documents解析相关的依赖，与其花时间解决这类问题，不如直接用WSL2。PyCharm对WSL2的支持已经很成熟，使用体验和本地解释器差别不大。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 前置环境：WSL2、Docker Desktop、PyCharm的正确组合

2.1 硬件底线和Windows版本

先泼一盆冷水：RAGFlow全家桶比较吃内存。我自己的机器是32GB内存，16GB跑起来只能说勉强顺滑，8GB几乎没法看。建议至少16GB内存起步，越往上越好。

磁盘方面，RAGFlow镜像、模型文件、知识库解析后的数据都能占掉不少空间，我给这个环境预留了100GB，实际用下来不算宽裕。Windows系统建议使用Windows 10 21H2以上或者Windows 11，因为旧版本对WSL2和Docker Desktop的支持比较差。

CPU没有太大讲究，支持虚拟化就行。如果是Windows 10，要确认BIOS里已经开启VT-x/AMD-V。Windows 11默认开启，一般不用管。

2.2 WSL2 Ubuntu安装与Docker整合

第一步是打开管理员PowerShell，执行：

powershell复制wsl --install -d Ubuntu-22.04

安装完成后重启电脑，系统提示设置Linux用户名密码。建议密码设置简单点，最好能记住，因为后面sudo安装依赖经常用到。如果你不想每次输入密码，可以之后把这个用户加入sudo免密区间，但那是后话。

接着安装Docker Desktop。安装包从官网下载即可。安装完成后，打开Docker Desktop的Settings页面，找到Resources->WSL Integration，确保你的Ubuntu-22.04被勾选。

进入WSL2终端，输入docker version确认docker客户端可用。正常情况下你会看到client和server都有版本号，如果只有client没有server，说明Docker Desktop没启动，或者WSL Integration没开好。

这里有个关键点：Docker Desktop默认会创建一个专用的WSL发行版来跑docker daemon。你代码放置的那个Ubuntu-22.04不需要自己安装docker引擎，只要通过Integration连过去就行。很多初学者会跑到Ubuntu里执行curl -fsSL get.docker.com | sh，装一个独立的Docker，反而造成端口冲突，这个坑一定要避开。

2.3 PyCharm版本选择和WSL解释器路径

PyCharm建议直接用专业版。社区版虽然也能写Python，但对WSL解释器和前端开发的支持都不够完整。专业版有30天评估期，你只需要搭建环境并验证二次开发流程，完全够用了。

安装完PyCharm后，你不需要在Windows里创建项目，而是打开WSL2里的项目目录。WSL2文件系统在Windows资源管理器里可以看到，路径类似\\wsl$\Ubuntu-22.04\home\你的用户名\ragflow。PyCharm里直接通过File -> Open打开这个UNC路径，IDE会自动识别它属于WSL2环境。

有一点务必注意：WSL2的Linux文件系统在宿主Windows里通过网络协议访问，文件操作速度比本地磁盘慢一些。如果你的代码很大，建议永远在WSL2内部进行clone和依赖安装操作，不要在Windows里把文件拖进WSL路径，否则文件权限和行尾符很容易出问题。

2.4 基础软件安装：git、node、python

下面的操作都在WSL2 Ubuntu终端中执行。先更新软件源：

bash复制sudo apt update
sudo apt install -y git build-essential

Ubuntu自带的Python版本可能是3.10或者3.12，RAGFlow一般要求Python3.10以上。如果你怕系统Python被搞乱，可以用python3 -m venv创建虚拟环境，或者安装独立Python版本。我建议使用系统自带的Python3版本，先跑一遍依赖，如果项目要求特定版本再另外装。

Node.js建议安装18以上的LTS版本。Ubuntu的官方源可能提供很老的Node版本，推荐直接用NodeSource或者nvm安装。我习惯用nvm：

bash复制curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
node -v

装完基础软件后，开始拉RAGFlow源码。

3. 拉取RAGFlow源码并启动依赖容器

3.1 clone分支与版本保持一致

在WSL2的home目录下执行：

bash复制git clone https://github.com/infiniflow/ragflow.git
cd ragflow
git tag -l | tail -20

我写这篇文章时比较新的是v0.27.1。建议不要直接切到最新主分支，而是选择稳定的tag。因为主分支可能带有尚未发布的改动，文档和实际代码对不上会让人崩溃。我的做法是：

bash复制git checkout v0.27.1

然后先大致看一下目录结构。注意有一点：RAGFlow的源码目录在不同版本里变化比较大，比如docker编排文件、配置文件位置都有可能移动。在你实际操作时，一定要以仓库内的文件结构为准，不要照搬我的路径就完事了。

3.2 准备.env和service_conf.yaml

RAGFlow目录里通常有几个模板文件，例如docker/.env、docker/service_conf.yaml。你需要复制一份出来改成自己的配置：

bash复制cp docker/.env .env
cp docker/service_conf.yaml service_conf.yaml

.env文件里核心配置项包括：

bash复制MYSQL_PASSWORD=infini_rag_flow
REDIS_PASSWORD=infini_rag_flow
MINIO_PASSWORD=infini_rag_flow
SVR_HTTP_PORT=9380

注意这些密码要保持一致，因为后续连接数据库、Redis、MinIO都依赖它们。SVR_HTTP_PORT是后端RAGFlow服务对外监听的端口，默认应该是9380。

service_conf.yaml里配置了各个依赖服务的地址，比如MySQL连接地址、Redis地址、MinIO地址。在本地二开模式下，这些地址理论上应该指向localhost，因为容器已经把端口映射到了宿主机上，而你的后端代码跑在WSL2里，WSL2访问宿主机的localhost可能要小心。这里有个小技巧：如果你的后端跑在WSL2里，容器也跑在Docker Desktop管理的WSL2里，那么访问localhost通常没问题，因为Docker会帮忙做网络转发。如果访问不通，把地址换成你WSL2里查到的默认网关地址ip route show | grep default。

3.3 手动拉起MySQL、Redis、MinIO、ES等依赖

先看这个项目compose里到底有哪些服务：

bash复制docker compose -f docker/docker-compose.yml config --services

以v0.27.1附近的版本为例，服务大概包括mysql、redis、minio、es、ragflow-server等。我们的目标是只启动依赖服务，不启动ragflow-server，否则端口9380会被容器里的后端占掉，本地调试的后端就起不来了。

执行类似这样的命令，按你实际看到的服务名调整：

bash复制docker compose -f docker/docker-compose.yml up -d mysql redis minio es

命令执行完后，用docker compose ps查看状态。等所有依赖服务都显示healthy，再进入下一步。

如果不小心把ragflow-server也启动了，先执行：

bash复制docker compose -f docker/docker-compose.yml stop ragflow-server

这样才能把9380端口让出来。

3.4 验证依赖容器可用

不要急着跑后端，先做几件验证工作。

检查MySQL：

bash复制docker exec -it <mysql容器名> mysql -uroot -pinfini_rag_flow -e "show databases;"

检查Redis：

bash复制docker exec -it <redis容器名> redis-cli -a infini_rag_flow ping

检查MinIO：浏览器打开http://localhost:9001，账号密码一般默认是infini_rag_flow。如果打不开，检查容器日志里有没有报错。

MinIO这里有个容易被忽略的点：RAGFlow会创建存储桶，比如ragflow这个bucket。如果MinIO是全新启动的，应用第一次连接时通常会自己创建；但如果你本地连不上，先手动在MinIO控制台确认有没有对应bucket。经验是等后端代码第一次跑起来再处理也行，但提前知道这个逻辑会省很多排查时间。

4. 在PyCharm中用WSL解释器启动后端API

4.1 创建Python虚拟环境并安装依赖

在WSL2终端里，进入ragflow目录，然后创建虚拟环境：

bash复制python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

接下来安装后端依赖。RAGFlow的后端依赖通常放在requirements.txt中。但要注意，不同版本可能拆成多个requirements文件。你可以用find . -name "requirements*.txt" -maxdepth 3查看。

然后安装：

bash复制pip install -r requirements.txt

这个步骤会花比较久的时间，尤其是某些包含numpy、pandas、docx解析的包。如果你用了WSL2且内存不太够，pip安装过程中可能被系统OOM杀掉，建议关闭多余应用，或者先限制一下构建并发。

等你装完再回到PyCharm。如果过程中出现某个包编译失败，大概率是系统缺少某个Linux依赖库，比如libxml2-dev、libxslt1-dev、libssl-dev等。我的建议是：不要一遇到缺包就在pip层面死磕，先用sudo apt install把编译基础库装全。

4.2 PyCharm配置WSL2解释器

打开PyCharm，选择你已经clone下来的ragflow目录。然后进入File -> Settings -> Project -> Python Interpreter，点击Add Interpreter -> Add Local Interpreter，选择WSL。

PyCharm会扫描可用的WSL发行版，选中Ubuntu-22.04，然后在解释器路径里指定刚才创建的虚拟环境：

bash复制/home/你的用户名/ragflow/.venv/bin/python

如果你是第一次配置，PyCharm可能要求你输入WSL用户密码。配置成功后，项目的默认解释器就是WSL2里的Python了。

这里要特别说明：PyCharm的WSL集成是通过\\wsl$\路径完成的。有时候你直接在Windows资源管理器里打开并编辑WSL里的文件，会导致文件权限变成Windows用户，影响Linux里的读写。最稳妥的方式是始终在PyCharm里编辑这些文件，或者在WSL终端里用vim等工具，避免混用。

4.3 运行参数与环境变量

后端入口文件通常叫api/ragflow_server.py。不同版本可能有所调整，如果用PyCharm打开项目后找不到这个入口，去api目录下找包含FastAPI()或者uvicorn.run的Python文件。

启动前，需要设置一些环境变量，我本地配置大致是这样的：

bash复制PYTHONPATH=/home/你的用户名/ragflow

在PyCharm的Run Configuration里面，点击Edit Configurations，新增一个Python配置，脚本路径选择ragflow_server.py，工作目录是项目根目录，环境变量添加：

PYTHONPATH指向项目根目录
如果日志用到了LOG_PATH等变量，根据项目代码再补

注意一点：service_conf.yaml里的路径很可能是在Docker环境下配置的，比如数据目录是/ragflow，或者/root。如果你直接本地启动，需要用你本机的WSL目录去替换。一个简单的做法是检查service_conf.yaml中最外层的path字段：

yaml复制path:
  data: /home/你的用户名/ragflow/data
  logs: /home/你的用户名/ragflow/logs

如果不在本地创建这些目录，RAGFlow可能会在启动时自己创建。但权限不对时会报错。建议在WSL里先手动创建：

bash复制mkdir -p data logs

然后启动运行，看日志输出。

4.4 后端起来之后的验证方法

后端监听端口是9380。起来之后，先在WSL2里测试一下：

bash复制curl http://localhost:9380/

正常会返回RAGFlow后端的欢迎信息，或者某些路由的JSON。如果curl不通，用ss -tlnp查看9380端口有没有进程监听。如果没有监听，大概率是启动过程抛异常了，回PyCharm的Console里看完整错误。

如果你使用浏览器访问后端，可能会遇到登录界面。RAGFlow默认需要一个管理员账号，初次使用时需要通过界面注册或者由初始化脚本创建。这个流程我后面统一讲。

5. 前端Vite联调：PyCharm同时管前后端

5.1 安装前端依赖与Node版本坑

后端能通之后，马上来处理前端。前端代码在web目录下。进入目录：

bash复制cd web
npm install

如果你在安装依赖时遇到大量peer dependency冲突，很可能是Node版本与项目要求不匹配。比如RAGFlow的web端可能要求Node 18以上，但如果你装的是Node 21或22，某些依赖可能还在兼容边缘徘徊。用nvm切到一个LTS版本比较稳。

依赖安装的时间视网速而定，有时需要十几分钟。安装完成后，先直接执行：

bash复制npm run dev

如果Vite能跑起来，会输出一个本地访问地址，通常是http://localhost:3000。如果端口被占用，Vite会自己换端口，或者你手动在vite.config.ts里加server.port配置。

5.2 配置API请求地址指向本地后端

前端默认会请求某个后端地址。如果是打包好的生产环境，前端会把API请求发给同源的nginx，再由nginx代理到后端9380。但在开发模式下，Vite需要自己代理API请求。

RAGFlow的web目录下应该有vite.config.ts或者类似的配置。你可以在里面找到proxy相关配置：

typescript复制server: {
  host: '0.0.0.0',
  port: 3000,
  proxy: {
    '/api': {
      target: 'http://localhost:9380',
      changeOrigin: true,
    },
    // 可能还有别的以'/'开头的路径也要代理
  },
}

如果项目里已经写好了target，但指向的是容器地址或者默认80端口，你需要手动改成http://localhost:9380。改动后重启Vite。

这里有个坑：你在浏览器里访问Vite的3000端口时，浏览器请求的是http://localhost:3000/api/xxx，Vite代理到9380端口。但是后端RAGFlow可能会校验域名或者token，如果changeOrigin没有设置成true，请求头里的Host还是localhost:3000，后端可能认为是跨域请求，返回403。所以我一般会在proxy里把changeOrigin开起来。

5.3 PyCharm启动npm脚本

PyCharm作为Python IDE，虽然不像WebStorm那样天生为前端设计，但一样能添加npm脚本。在web/package.json右键，选择Show npm Scripts，然后双击dev即可运行。

如果你用的是PyCharm专业版，它还能识别package.json里的脚本，并且在Run面板里显示npm run dev的输出。这样你就不用在WSL终端和IDE之间来回切了。不过老实说，前端日志在PyCharm里看确实方便，但模块太多了反而眼花，我习惯把终端单独开一个窗口跑Vite，PyCharm专注Python后端调试。这个看个人偏好。

5.4 页面确认后端是否用的是本地调试版本

前端跑起来后，浏览器打开http://localhost:3000。此时如果界面能显示并且能登录，说明前后端已通。但怎么确认请求确实打到了你本地PyCharm起的后端，而不是某个还在运行的容器服务？

有几种方法，推荐最直观的：在后端代码里故意改一个日志或者接口返回值，比如在某个API返回的JSON里加一个字段，然后刷新前端页面，看有没有变化。如果变化了，就说明二开链路已经通了。

另外，你可以在PyCharm后端的Console里看到每个HTTP请求的日志。只要浏览器里有点击操作，PyCharm里就应该出现相应的访问记录。只要有记录，说明前端确实在访问你的本地代码。

6. 二开过程中会被挂起来的第一批问题

6.1 数据目录、MinIO初始化失败

最常见的启动报错就是提示MinIO连接失败，或者某个bucket不存在。默认MinIO的监听端口是9000和9001，前者是API，后者是控制台。如果容器已经健康，依然连不上，先检查service_conf.yaml里的MinIO配置：

yaml复制minio:
  endpoint: http://localhost:9000
  access_key: infini_rag_flow
  secret_key: infini_rag_flow
  bucket: ragflow

还要检查一下容器启动时的环境变量有没有设置好。有时候你修改了.env里的MINIO_PASSWORD，但容器没有重建，还是用的默认密码。

遇到这种情况，最简单的方案是重建容器：

bash复制docker compose -f docker/docker-compose.yml up -d --force-recreate minio mysql redis

如果依然连不上，在WSL2里手动测试：

bash复制curl http://localhost:9000/minio/health/live

如果返回正常，问题多半出在密码不一致。用MinIO客户端在容器内检查：

bash复制docker exec -it <minio容器名> sh
mc alias set local http://localhost:9000 <access_key> <secret_key>
mc ls local

6.2 页面跨域、代理问题

前端能打开，但是登录时提示网络错误、或者回调到错误的地址，这通常是Vite代理和目标后端没配对。先看浏览器开发者工具里的Network面板，找到/api/v1/user/login之类的请求，看它的状态码。

如果是502，基本是Vite代理的target指向了不存在的端口；如果是504，可能是WSL2里访问localhost不稳定；如果是403，大概率是changeOrigin少设置了或者凭据没有带。如果请求落到生产服务器而非你本地，检查是不是前端用了硬编码的API地址，Vite的proxy没生效。

要解决这类问题，不要只看代码，先用浏览器直接访问后端的API地址，确认后端本身是通的：

bash复制curl -X POST http://localhost:9380/api/v1/user/login -H "Content-Type: application/json" -d '{"email":"test@test.com","password":"test"}'

有响应再排查前端代理配置。

6.3 断点调试时别把整个服务带崩

后端跑起来后，在PyCharm里打上断点，注意一个基本原则：断点不要打在FastAPI启动、依赖初始化这类生命周期方法里，否则启动过程会挂住，还没到监听端口就卡死。

我觉得在RAGFlow二开中，最有用的断点是知识库创建接口、文档上传解析接口、对话接口。举个例子，你想看用户上传一个PDF后，文档状态是怎么流转的，可以直接在api/目录下搜索document相关的service或者task代码，在文档解析任务的分发处打一个断点。这样前端点击上传后，PyCharm会停下来，你可以看到当前任务上下文里塞着哪些元数据。

要知道，RAGFlow的文档解析链路相对较长，从上传到文件解析、切片、embedding生成、入库，经历了很多异步任务。如果你想调试完整的解析过程，仅靠PyCharm可能不够，因为很多异步任务可能由Worker进程处理，而不是API服务进程。你需要找到项目里的Worker入口，同样用PyCharm把它作为另一个配置启动。不过这个复杂度较高，第一次二开不建议一上来就调异步链路，先把API和前端打通，业务逻辑熟悉了再深入。

6.4 模型接入与向量化配置

RAGFlow运行知识库离不开embedding模型。如果你本地没有GPU，又不想花钱调用云端服务，常见方案是接Ollama或DeepSeek这类兼容接口。RAGFlow有模型管理页面，可以在页面里填模型供应商和API地址。

配置embedding模型时，要注意RAGFlow对embedding向量的维度是有要求的，不同模型输出的向量维度不一样，部分模型可能需要几百上千维。如果数据库中已有的向量数据维度不一致，会出现检索失败。

我的建议是：如果只是为了开发调试，先用一个便宜的云端embedding模型或者本地Ollama里的bge系列模型。DeepSeek的embedding接口也经常被用到，但是要仔细确认它是否属于OpenAI兼容格式、模型名称是否能在RAGFlow的下拉里找到。如果找不到，就手动添加一个OpenAI-API-compatible供应商，填上Base URL和API Key。

还有一个容易踩的坑：模型配置里填的Base URL如果在容器外，而本地后端跑在WSL2里，访问外网没问题。但如果你的模型服务跑在Windows宿主机上，WSL2访问宿主机不能用localhost，需要用宿主机在局域网里的IP，或者WSL2的默认网关地址。这个坑在配置Ollama时会经常遇到，提前写好可以省不少事。

7. 一个最小二次开发改动Demo

7.1 改一个接口并验证前端联动

讲到二开环境搭好了，那到底能不能顺手做个最小验证？这里用一个特别简单的例子：让前端首页的后端版本号显示变成带自定义后缀。

找到后端返回版本信息的接口，通常会有类似GET /api/v1/system/version的handler，或者启动时注册在某个router里。搜索包含system_version或者version的Python文件，找到返回JSON的位置，把里面的版本字符串改一下：

python复制return {
    "version": "v0.27.1-2dev",
    "edition": "Community"
}

保存后重启PyCharm里的后端进程。然后在浏览器里刷新页面，找到展示版本号的位置，确认已经变成你改的值。

前端如果没显示版本号，直接在控制台里执行：

javascript复制fetch('/api/v1/system/version').then(r=>r.json()).then(console.log)

只要返回里有你改的内容，说明前后端二开链路是通的。

7.2 从本地改动回到Docker镜像的思路

本地开发调试好之后，如果要发布或部署到别的机器，最终还是要构建镜像。RAGFlow仓库的Docker目录里应该有构建脚本，比如docker/build_rag_image.sh之类的。它会先构建前端静态资源，再打入Python后端镜像。这时候你本地已经验证过的改动，会被打包进去。

构建镜像前，前端需要先执行一次生产构建：

bash复制cd web
npm run build

然后用项目脚本重新构建镜像。这个环节会比较久，但好处是你不再依赖本地二开环境了，部署到哪里都只需要一个镜像。二开环境主要负责代码逻辑正确性，镜像构建负责可交付性，这两条线分开之后，整个开发流程就很清晰了。

一些实操层面的个人建议

二开环境搭完之后，我的体感是：Windows生态里想稳定跑RAGFlow这类后端项目，最省心的不是硬装在Windows里，而是接受WSL2和Docker Desktop的组合。把基础设施交给Docker，把代码调试交给PyCharm，把前端代理配对，剩下的就是正常的Python/TypeScript开发体验。

尤其推荐第一次搭的时候把每一步日志都打开，尤其是PyCharm的Console、Vite的终端、Docker Desktop的日志。三个窗口一起看，很多问题能很快定位。不要在一开始就追求所有功能都在本地跑通，先保证后端API能起、前端能登录、模型能配置出一个embedding，这个最小闭环完成后，再逐步增加Agent、知识库、文档解析等模块。这样排错范围小，过程也不容易劝退。