简介：本资源为 RAGFlow 开源项目 v0.17.2 的完整可部署代码包，专为 Windows 平台 Docker Desktop 环境优化，面向希望快速本地搭建企业级 RAG（检索增强生成）应用的开发者与 AI 工程师。压缩包含 1409 个文件，主体为 474 个 TypeScript/React 前端组件（.tsx）、237 个 Python 后端服务与数据处理脚本（.py），辅以 203 个 SVG 图标、153 个 TypeScript 类型定义（.ts）及 93 个 Less 样式文件，完整覆盖前后端、配置（nginx.conf、ragflow.conf、proxy.conf）、向量库适配（school.rank.csv、corp_baike_len.csv）、UI 主题（tailwind.css、options.css）与部署资源（Dockerfile、yaml 配置）。包体大小 45.6MB，结构清晰，模块解耦度高，便于二次开发与调试。目前已有 289 人学习下载，适合需在 Windows 环境下零基础启动 RAGFlow、理解其目录组织逻辑、复用配置模板或定制化前端 UI 的中高级实践者。

1. RAGFlow 0.17.2 在 Windows + Docker Desktop 上跑通：别被“一键部署”骗了，这个版本卡在 Python 3.11 和 Chroma 0.4.23 的兼容缝里

你是不是也试过下载 RAGFlow 官方 release 里的ragflow-0.17.2.zip，双击解压、docker-compose up -d一气呵成，结果浏览器打不开http://localhost:3000，日志里满屏ModuleNotFoundError: No module named 'chromadb'或者ImportError: cannot import name 'AsyncClient' from 'httpx'？这不是你环境脏，也不是 Docker Desktop 没开 WSL2——是 RAGFlow 0.17.2 这个特定版本，在 Windows 下的 Docker Desktop 环境里，对底层依赖有极其隐蔽的版本咬合要求：它硬性依赖 ChromaDB 0.4.23（不是 0.4.24，更不是 0.5.x），而这个版本又只认 Python 3.11.9（不是 3.11.10，也不吃 3.12）。我帮某高校实验室部署时，就因为本地 Docker Desktop 默认拉的是python:3.12-slim镜像，硬生生卡了两天。这套环境不是给“想试试 RAG”的人准备的玩具，而是给需要在 Windows 笔记本上快速验证 RAG pipeline、做文档问答 Demo、或对接内部知识库的开发者/教学人员用的——它不追求生产级高可用，但必须“解压即跑通”。下面所有步骤，我都按 Windows 10/11 + Docker Desktop 4.34+ + WSL2 后端实测过，跳过任何玄学操作，只留血泪验证过的路径。

2. 准备工作：确认 Docker Desktop 状态、WSL2 引擎与基础镜像源

RAGFlow 是容器化应用，它的“安装”本质是让 Docker Desktop 正确加载并运行一组预定义服务（web、api、celery、redis、mysql、minio、chroma）。Windows 下一切的前提，是 Docker Desktop 不只是“开着”，而是真正以 WSL2 为后端、且镜像源能稳定拉取国内可访问的层。别跳这步——很多“启动失败”其实卡在镜像拉一半就断。

2.1 检查 WSL2 是否启用并设为默认

打开 PowerShell（管理员权限），逐条执行：

# 查看已安装的 WSL 发行版及状态 wsl -l -v # 如果没有输出，或状态是 "Stopped"，先启动 wsl --shutdown wsl -d Ubuntu-22.04 # 假设你装的是 Ubuntu 22.04，替换成你实际的发行版名

提示：如果wsl -l -v报错说未启用 WSL，需先在“启用或关闭 Windows 功能”中勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”，然后重启。Docker Desktop 安装时会提示是否自动配置 WSL2，务必选“是”。

2.2 验证 Docker Desktop 后端为 WSL2

打开 Docker Desktop 设置（Settings → General），确认Use the WSL 2 based engine已勾选。再进Resources → WSL Integration，确保你的 WSL 发行版（如 Ubuntu-22.04）右侧开关是开启状态。这是关键——如果这里关着，Docker Desktop 会退回到 Hyper-V 模式，在 Windows 上极易因内存/驱动问题导致容器启动失败或网络不通。

2.3 配置国内镜像源（加速拉取基础镜像）

RAGFlow 的docker-compose.yml里大量使用python:3.11-slim、mysql:8.0、redis:7-alpine等官方镜像。默认走 Docker Hub 官方源，在国内极慢甚至超时。必须手动配置镜像加速器：

• 打开 Docker Desktop → Settings → Docker Engine
• 在 JSON 配置中找到"registry-mirrors"字段，追加国内可信镜像源（注意逗号分隔）：

{ "registry-mirrors": [ "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com", "https://mirror.baidubce.com" ], "insecure-registries": [], "experimental": false }

• 点击Apply & Restart。重启后，执行docker info | findstr "Registry Mirrors"应能看到上述地址。

2.4 预拉取关键基础镜像（防 compose 启动时卡死）

RAGFlow 0.17.2 的docker-compose.yml中指定了以下核心镜像标签，我们提前拉下来，避免up -d时因网络抖动失败：

# 在 PowerShell 或 WSL 终端中执行 docker pull python:3.11.9-slim docker pull mysql:8.0.33 docker pull redis:7.0.12-alpine docker pull minio/minio:RELEASE.2023-07-07T00-10-21Z docker pull chromadb/chroma:0.4.23

注意：chromadb/chroma:0.4.23是 RAGFlow 0.17.2 的硬性依赖，官方chroma:latest已升到 0.5.x，API 不兼容。python:3.11.9-slim也必须精确到 patch 版本，因为 3.11.10 修复了一个异步 I/O bug，反而导致 RAGFlow 的 Celery worker 初始化失败。这是我翻遍 GitHub Issues 和 Chroma commit log 才确认的细节。

3. 解压与修改：修补 ragflow-0.17.2.zip 中的 Docker Compose 配置

官方发布的ragflow-0.17.2.zip是一个“半成品”压缩包——它包含了所有源码和配置，但docker-compose.yml并未针对 Windows + Docker Desktop 场景做适配。直接docker-compose up必然失败，原因有三：端口映射冲突、Chroma 服务启动顺序错误、以及 MySQL 初始化脚本路径在 Windows 路径格式下失效。我们必须手动修补。

3.1 解压并定位关键文件

将ragflow-0.17.2.zip解压到一个全英文、无空格、无中文的路径下，例如C:\ragflow-0.17.2。解压后进入目录，重点文件结构如下：

C:\ragflow-0.17.2\ ├── docker-compose.yml ← 主编排文件，需修改 ├── docker\ ← 包含各服务的 Dockerfile │ ├── api\ │ │ └── Dockerfile ← 构建 API 服务的镜像 │ └── web\ │ └── Dockerfile ← 构建 Web 前端的镜像 ├── scripts\ │ └── init.sql ← MySQL 初始化 SQL，需检查路径 └── .env ← 环境变量文件，需补全

3.2 修改 docker-compose.yml：修复端口、依赖与 Chroma 启动

用 VS Code 或 Notepad++ 打开docker-compose.yml，找到services:下的chroma和api两节，按以下方式修改：

修改 Chroma 服务（关键！）

原配置中chroma的image是chromadb/chroma:latest，必须强制指定为0.4.23；同时增加restart: on-failure和显式端口映射：

chroma: image: chromadb/chroma:0.4.23 container_name: ragflow_chroma restart: on-failure:3 ports: - "8000:8000" # 显式暴露，避免 Docker Desktop 自动分配端口导致前端连不上 environment: - CHROMA_SERVER_AUTH_CREDENTIALS=ragflow - CHROMA_SERVER_AUTH_PROVIDER=chromadb.auth.basic.BasicAuthServerProvider volumes: - ./volumes/chroma:/chroma/chroma_db networks: - ragflow_net

修改 API 服务：强制依赖 Chroma 并修正 Python 镜像

api服务必须等chroma完全就绪后再启动，否则会因连接失败而崩溃退出。在api的depends_on下添加健康检查，并锁定 Python 镜像：

api: build: context: . dockerfile: docker/api/Dockerfile image: ragflow/api:0.17.2 container_name: ragflow_api depends_on: chroma: condition: service_healthy # 关键！等待 chroma 返回 200 mysql: condition: service_started redis: condition: service_started # ... 其他配置保持不变，但确保下面有 healthcheck healthcheck: test: ["CMD", "curl", "-f", "http://chroma:8000/health"] interval: 30s timeout: 10s retries: 5 start_period: 40s

3.3 补全 .env 文件：填满所有占位符

根目录下的.env文件常为空或只有部分变量。RAGFlow 0.17.2 至少需要以下 7 个环境变量才能启动成功（缺一不可）：

# 数据库配置（MySQL） MYSQL_HOST=mysql MYSQL_PORT=3306 MYSQL_USER=ragflow MYSQL_PASSWORD=ragflow123 MYSQL_DATABASE=ragflow # Redis 配置 REDIS_HOST=redis REDIS_PORT=6379 REDIS_PASSWORD= # Chroma 配置（必须与 docker-compose.yml 中一致） CHROMA_HOST=chroma CHROMA_PORT=8000 CHROMA_AUTH_CREDENTIALS=ragflow # Web 服务端口（前端访问用） WEB_PORT=3000 # API 服务端口（内部调用用） API_PORT=5001

注意：CHROMA_AUTH_CREDENTIALS必须与docker-compose.yml中chroma服务的CHROMA_SERVER_AUTH_CREDENTIALS完全一致，否则 API 服务初始化 Chroma client 时会 401。这是个典型的“配置漂移”坑，官方文档没写清楚。

4. 构建与启动：从零构建 API 镜像并运行全栈服务

RAGFlow 0.17.2 的docker-compose.yml中api服务采用build方式而非image，意味着每次启动都要基于docker/api/Dockerfile重新构建。这个过程在 Windows 下极易因路径、权限或缓存问题失败。我们必须用最稳妥的方式构建。

4.1 进入 WSL2 环境执行构建（绕过 Windows 路径陷阱）

不要在 Windows PowerShell 或 CMD 中执行docker-compose up。必须切换到 WSL2 终端（如 Ubuntu-22.04）：

# 在 WSL2 终端中执行 cd /mnt/c/ragflow-0.17.2 # 注意路径是 /mnt/c/...，不是 C:\... ls -la # 确认能看到 docker-compose.yml 和 .env

提示：Windows 路径在 WSL2 中挂载为/mnt/c/...，直接在 Windows 终端构建会导致COPY指令找不到requirements.txt（因为 Docker daemon 运行在 WSL2 内，它看到的是 WSL2 的文件系统视图）。

4.2 构建 API 镜像：指定 Python 版本与依赖源

docker/api/Dockerfile默认用FROM python:3.11-slim，但我们必须强制指定3.11.9，并在pip install时换国内源：

# 编辑 docker/api/Dockerfile，将第一行改为： FROM python:3.11.9-slim # 在 RUN pip install ... 行之前，插入清华源配置： RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/ && \ pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn

保存后，在 WSL2 终端中执行构建命令（加--no-cache避免旧缓存干扰）：

docker build -t ragflow/api:0.17.2 -f docker/api/Dockerfile --no-cache .

构建成功后，终端应显示Successfully built xxxxxxxx。如果报ERROR: Could not find a version that satisfies the requirement chromadb==0.4.23，说明镜像源没生效或网络问题，此时可临时在Dockerfile的pip install行末尾加-i https://pypi.tuna.tsinghua.edu.cn/simple/。

4.3 启动全栈服务并观察日志

确保当前目录是ragflow-0.17.2根目录（有docker-compose.yml），执行：

docker-compose up -d

启动后，立即检查各容器状态：

docker-compose ps # 应看到所有服务状态为 "Up (healthy)" 或 "Up (starting)" # 特别关注 chroma 和 api 的状态

若chroma状态是Up (unhealthy)，说明健康检查失败，大概率是端口没通或认证失败。此时查看日志：

docker logs ragflow_chroma | tail -20 docker logs ragflow_api | tail -20

常见日志线索：

• chroma日志出现Authentication failed→ 检查.env中CHROMA_AUTH_CREDENTIALS与docker-compose.yml是否一致；
• api日志出现ConnectionRefusedError: [Errno 111] Connection refused→ 检查chroma容器是否真在运行（docker ps | grep chroma），以及depends_on的condition是否写对。

5. 避坑指南：Windows 下 Docker Desktop 运行 RAGFlow 0.17.2 的 5 个真实翻车现场

部署 RAGFlow 0.17.2 到 Windows Docker Desktop，我踩过的坑比代码还长。下面这 5 条，每一条都来自真实故障现场，附带现象、根因和一招毙命的解法。别当故事看，它们就是你下一秒要遇到的报错。

5.1 现象：docker-compose up后ragflow_api容器反复重启，docker logs ragflow_api显示ModuleNotFoundError: No module named 'pymysql'

原因：docker/api/Dockerfile中pip install -r requirements.txt安装的pymysql版本与 MySQL 8.0.33 不兼容。RAGFlow 0.17.2 的requirements.txt锁定的是PyMySQL==1.0.2，但该版本存在一个字符集协商 bug，导致连接 MySQL 8.0+ 时抛出ModuleNotFoundError（实际是 ImportError，但被异常处理掩盖了）。

解决：编辑docker/api/requirements.txt，将PyMySQL==1.0.2改为PyMySQL==1.1.0，然后重新构建 API 镜像（docker build -t ragflow/api:0.17.2 -f docker/api/Dockerfile .）。1.1.0 修复了 MySQL 8.0 的 utf8mb4 默认字符集握手。

5.2 现象：浏览器打开http://localhost:3000显示白屏，F12 控制台报Failed to load resource: net::ERR_CONNECTION_REFUSED，但docker-compose ps显示web容器状态是Up

原因：web容器的 Nginx 配置中，proxy_pass指向了http://api:5001，但api容器的API_PORT环境变量在.env中被误设为5000（默认值），导致 Nginx 尝试代理到一个不存在的端口。

解决：检查.env文件，确保API_PORT=5001（不是 5000）。RAGFlow 0.17.2 的 API 服务默认监听 5001，web的 Nginx 配置硬编码了这个端口。改完后，重启web容器：docker-compose restart web。

5.3 现象：ragflow_chroma容器启动后立即退出，docker logs ragflow_chroma显示OSError: [Errno 95] Operation not supported，日志末尾有mount: /chroma/chroma_db: wrong fs type, bad option, bad superblock

原因：chroma容器的volumes挂载点./volumes/chroma在 Windows 下被映射为 NTFS 卷，而 ChromaDB 0.4.23 的底层 SQLite 依赖 POSIX 文件锁，NTFS 不支持fcntl锁机制。

解决：绝对不要让 Chroma 的数据卷挂载到 Windows 主机路径。修改docker-compose.yml中chroma的volumes，改为命名卷（Docker 自动管理）：

chroma: # ... 其他配置不变 volumes: - chroma_data:/chroma/chroma_db # 改为命名卷 # 在文件末尾添加 volumes 定义 volumes: chroma_data:

然后执行docker volume create chroma_data，再docker-compose down && docker-compose up -d。

5.4 现象：ragflow_mysql容器启动失败，日志循环打印mysqld: Can't read dir of '/etc/mysql/conf.d/'，最后Aborting

原因：MySQL 8.0.33 的 Docker 镜像要求/etc/mysql/conf.d/目录存在且可读，但 RAGFlow 的docker-compose.yml中未挂载任何配置文件到该路径，导致 MySQL 启动时校验失败。

解决：创建一个空的mysql-conf目录，并挂载进去。在ragflow-0.17.2根目录下执行：

mkdir -p mysql-conf

然后修改docker-compose.yml中mysql服务的volumes：

mysql: # ... 其他配置 volumes: - ./volumes/mysql:/var/lib/mysql - ./mysql-conf:/etc/mysql/conf.d # 新增这一行

5.5 现象：所有容器都显示Up (healthy)，但上传 PDF 文档后，ragflow_api日志疯狂刷celery worker: Received unregistered task of type 'process_document'

原因：Celery worker 服务（celery_worker容器）未正确连接到 Redis，或任务队列名称不匹配。RAGFlow 0.17.2 的celery_worker默认使用redis://redis:6379/1作为 broker，但.env中REDIS_PORT若被误设为6380，就会连错端口。

解决：检查.env中REDIS_PORT=6379（必须是 6379），并确认docker-compose.yml中celery_worker的environment没有覆盖该变量。最保险的做法是，在celery_worker的environment下显式声明：

celery_worker: # ... environment: - REDIS_URL=redis://redis:6379/1

6. 验证与调试：用 curl 和浏览器完成端到端 RAG 流程测试

装完不是终点，跑通才是。RAGFlow 的价值在于“文档上传 → 向量入库 → 语义检索 → 生成回答”，我们必须亲手走一遍这个闭环，而不是只看docker-compose ps的绿色Up。下面是一套我在某跨平台系统教学中反复验证的端到端测试流程，包含命令、预期响应和关键检查点。

6.1 第一步：确认 API 服务健康并获取登录 Token

在 WSL2 或 Windows PowerShell 中执行：

# 1. 检查 API 是否返回健康状态 curl -s http://localhost:5001/health | jq . # 预期输出：{"status":"ok","version":"0.17.2"} # 2. 用默认账号密码登录，获取 JWT Token（RAGFlow 0.17.2 默认 admin/admin） TOKEN=$(curl -s -X POST http://localhost:5001/api/v1/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"admin"}' | jq -r '.access_token') echo $TOKEN # 应输出一长串 JWT 字符串，如 eyJhbGciOi...

注意：如果curl报Could not resolve host，说明 DNS 解析失败，检查 Docker Desktop 的 DNS 设置（Settings → Resources → Network → DNS Server 设为8.8.8.8）；如果返回401 Unauthorized，确认.env中MYSQL_USER和MYSQL_PASSWORD与docker-compose.yml中mysql服务的MYSQL_ROOT_PASSWORD一致（RAGFlow 0.17.2 的初始化脚本会用 root 创建 ragflow 用户）。

6.2 第二步：创建知识库并上传测试文档

RAGFlow 的核心是 Knowledge Base（KB）。我们创建一个名为test_kb的 KB，并上传一个极简的test.txt（内容为RAGFlow is a RAG application.）：

# 1. 创建知识库（返回 kb_id） KB_ID=$(curl -s -X POST http://localhost:5001/api/v1/knowledge_bases \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"test_kb","description":"Test KB for validation","language":"English"}' | jq -r '.data.id') echo "Created KB ID: $KB_ID" # 应输出类似 'kb-xxx' # 2. 上传 test.txt 文件（需先创建文件） echo "RAGFlow is a RAG application." > /tmp/test.txt # 3. 上传文件到 KB（注意 multipart/form-data 格式） curl -s -X POST "http://localhost:5001/api/v1/knowledge_bases/$KB_ID/upload" \ -H "Authorization: Bearer $TOKEN" \ -F "file=@/tmp/test.txt" \ -F "notion_page_url=" \ -F "parser_id=naive" | jq . # 预期输出：{"code":200,"message":"success","data":{"id":"doc-xxx","name":"test.txt",...}}

6.3 第三步：触发文档解析并等待完成

上传只是第一步，RAGFlow 会将文件交给 Celery Worker 异步解析、切片、向量化并存入 Chroma。我们需要轮询文档状态，直到status变为completed：

# 轮询文档状态（最多等 60 秒） for i in {1..12}; do STATUS=$(curl -s "http://localhost:5001/api/v1/knowledge_bases/$KB_ID/documents" \ -H "Authorization: Bearer $TOKEN" | jq -r '.data[0].status') echo "Document status: $STATUS" if [ "$STATUS" = "completed" ]; then echo "✅ Document parsing completed!" break fi sleep 5 done # 如果 60 秒后仍是 'parsing' 或 'error'，检查 celery_worker 日志 # docker logs ragflow_celery_worker | tail -20

6.4 第四步：发起 RAG 问答，验证向量检索与 LLM 生成

现在 KB 中已有向量化文本，我们模拟一次用户提问：

# 向 RAGFlow 的 chat 接口提问（注意：query 是问题，knowledge_base_id 是 KB ID） curl -s -X POST http://localhost:5001/api/v1/chat/completion \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "What is RAGFlow?", "knowledge_base_id": "'"$KB_ID"'", "history": [], "response_mode": "streaming" }' | jq -r '.answer' # 预期输出（非流式）："RAGFlow is a RAG application." # 如果返回空或 error，检查 chroma 日志是否有 "No documents found for query"

6.5 最终验证：浏览器 UI 全流程走通

打开http://localhost:3000，执行以下操作：

• 登录（admin/admin）；
• 左侧导航点击Knowledge Bases→ 点击test_kb→ 确认文档列表中有test.txt且状态为Completed；
• 点击顶部Chat→ 在输入框输入What is RAGFlow?→ 按回车；
• 观察右下角是否出现回答框，内容是否为RAGFlow is a RAG application.。

这一步看似简单，但它串联了：前端 React 请求 → API 服务路由 → Chroma 向量相似度检索 → LLM 模型（RAGFlow 0.17.2 内置轻量模型）生成 → 流式返回。任何一个环节断掉，UI 就会卡在 loading 或报错。我每次部署完，都强制走一遍这个流程，哪怕只是问一句 “hi” —— 因为只有 UI 走通，才代表整个 RAG pipeline 的数据流、控制流、错误流全部就绪。从那以后我每次给新同事配环境，都强制走一遍这个curl + 浏览器组合拳，宁可多花 5 分钟，也不愿第二天被“为什么我的文档搜不到”堵在工位上。希望帮到你。

本文还有配套的精品资源，点击获取