版本: RAGFlow v0.26.3环境: Windows WSL 2 Docker Desktop最终状态: ✅ 服务正常运行Nginx 配置已永久修复目录环境准备安装 RAGFlow问题排查与修复端口冲突502 Bad GatewayNginx 配置配置 Embedding 模型配置 DeepSeek Chat 模型使用 RAGFlow日常维护方案对比与决策记录常见问题速查一、环境准备1.1 系统要求Windows 10/11 专业版/企业版或 Windows 11 家庭版启用 WSL 2Docker Desktop配置为 WSL 2 后端1.2 检查虚拟化是否开启按Ctrl Shift Esc打开任务管理器 →性能→CPU→ 确认右下角虚拟化显示为已启用。若未启用需进入 BIOS 开启Intel VT-x或AMD-V具体操作因主板而异通常是开机按 Del/F2 进入 BIOS在 Advanced → CPU Configuration 中找到虚拟化选项。1.3 启用 Windows 功能以管理员身份打开 PowerShell依次执行# 启用 WSL 子系统dism.exe/online/enable-feature/featurename:Microsoft-Windows-Subsystem-Linux/all/norestart# 启用虚拟机平台dism.exe/online/enable-feature/featurename:VirtualMachinePlatform/all/norestart或者手动操作控制面板 → 程序 → 启用或关闭 Windows 功能 → 勾选以下两项适用于 Linux 的 Windows 子系统虚拟机平台执行完毕后重启电脑。1.4 安装 WSL 2# 设置 WSL 2 为默认版本wsl--set-default-version 2# 更新 WSL 内核确保版本足够新wsl--update--web-download# 安装 Ubuntuwsl--install-d Ubuntu-22.04首次进入 Ubuntu 终端时会提示创建 Linux 用户名和密码可与 Windows 不同。1.5 安装 Docker Desktop从 Docker 官网 下载 Docker Desktop for Windows安装时确保勾选Use WSL 2 instead of Hyper-V如需自定义安装路径如 D 盘可用命令行start/wDocker Desktop Installer.exeinstall--installation-dirD:\Docker安装完成后打开 Docker Desktop →Settings → Resources → WSL Integration→ 启用与 Ubuntu 的集成。1.6 配置国内镜像加速重要由于国内直接拉取 Docker Hub 镜像非常慢甚至超时必须配置镜像加速。打开 Docker Desktop → ⚙️Settings→Docker Engine将registry-mirrors修改为{builder:{gc:{defaultKeepStorage:20GB,enabled:true}},experimental:false,registry-mirrors:[https://docker.m.daocloud.io,https://docker.mirrors.ustc.edu.cn,https://registry.docker-cn.com,https://mirror.ccs.tencentyun.com,https://huecker.io,https://dockerhub.timeweb.cloud,https://noohub.ru]}推荐如果你有阿里云账号登录 阿里云容器镜像服务 获取专属加速地址https://{your_id}.mirror.aliyuncs.com速度更快更稳定。点击Apply restart等待 Docker 重启。1.7 验证 Docker 安装# 检查镜像源是否生效docker info|findstrRegistry Mirror# 拉取测试镜像docker run hello-world# 输出 Hello from Docker! 表示安装成功二、安装 RAGFlow2.1 克隆仓库git clone https://github.com/infiniflow/ragflow.git ragflow-latest cd ragflow-latest\docker2.2 配置环境变量.env文件关键配置项# Web 访问端口 SVR_WEB_HTTP_PORT8080 # MySQL 外部映射端口若 3306 被占用则修改 EXPOSE_MYSQL_PORT3307 # API 代理模式python / go / hybrid API_PROXY_SCHEMEpython2.3 启动服务docker compose-f docker-compose.yml up-d首次启动会拉取镜像约 3.6 GB耐心等待。三、问题排查与修复问题 1端口冲突80 / 3306现象:Error response from daemon: ports are not available原因: 宿主机已有服务占用 80 或 3306 端口。解决: 在.env中修改SVR_WEB_HTTP_PORT和EXPOSE_MYSQL_PORT为未占用的端口。问题 2502 Bad Gateway 或 “network anomaly”2.1 现象重启后访问http://localhost:8080时出现502 Bad Gateway或前端显示network anomaly。2.2 诊断过程步骤 1— 进入容器检查 Nginx 配置dockerexecdocker-ragflow-cpu-1cat/etc/nginx/conf.d/ragflow.conf结果:ragflow.conf文件大小为0 bytes空文件只有default.conf在生效。步骤 2— 检查入口脚本逻辑# 查看 entrypoint.sh 第 189-206 行catentrypoint.sh|grep-A20Select Nginx Configuration发现在容器每次启动时entrypoint.sh都会执行cp -f将模板文件覆写到ragflow.conf。即使通过 volume 挂载了正确的配置也会被覆盖。步骤 3— 对比正确的配置nginx-fix.conf与默认模板的差异配置项默认模板 (ragflow.conf.python)正确配置 (nginx-fix.conf)proxy_pass地址127.0.0.1:9380127.0.0.1:9380✅proxy_pass路径/v1//api/v1/❌ 模板路径错误proxy_http_version未设置1.1proxy_*_timeout未设置connect/send/read 60s2.3 修复方案临时修复单次有效重启失效# 复制正确配置到容器dockercpnginx-fix.conf docker-ragflow-cpu-1:/etc/nginx/conf.d/ragflow.conf# 测试语法dockerexecdocker-ragflow-cpu-1 nginx-t# 重载 Nginx无需重启容器dockerexecdocker-ragflow-cpu-1 nginx-sreload永久修复修改 3 个文件修改一—ragflow-nginx.conf补充超时参数location /api/v1/ { proxy_pass http://127.0.0.1:9380/api/v1/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_http_version 1.1; # ← 新增 proxy_connect_timeout 60s; # ← 新增 proxy_send_timeout 60s; # ← 新增 proxy_read_timeout 60s; # ← 新增 }修改二—entrypoint.sh添加守卫逻辑第 189-206 行# 修改前无条件 cp -f 覆盖cp-f$NGINX_CONF_DIR/ragflow.conf.python$NGINX_CONF_DIR/ragflow.conf# 修改后文件非空则跳过if[!-s$NGINX_CONF_DIR/ragflow.conf];then# 原 cp -f 逻辑elseechoUsing host-mounted nginx config: ragflow.conf (non-empty, skipping template)fi修改三—docker-compose.yml为 CPU profile 添加 volume 挂载# ragflow-cpu 的 volumes 部分volumes:-./ragflow-logs:/ragflow/logs-./ragflow-nginx.conf:/etc/nginx/conf.d/ragflow.conf# ← 取消注释并修正路径-./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template2.4 验证# 完整重启测试dockercompose-fdocker-compose.yml downdockercompose-fdocker-compose.yml--profilecpu up-d# 检查容器日志关键行dockerlogs docker-ragflow-cpu-1|grepnginx config# 输出: Using host-mounted nginx config: ragflow.conf (non-empty, skipping template)# 检查文件大小dockerexecdocker-ragflow-cpu-1wc-c/etc/nginx/conf.d/ragflow.conf# 输出: 967 (之前是 0)# 测试 APIcurlhttp://localhost:8080/api/v1/users/me# 输出: {code:401,message:Unauthorized} ← 401 表示代理正常# 测试主页curl-o/dev/null-w%{http_code}http://localhost:8080/# 输出: 200✅永久修复成功Nginx 配置在容器重启后不再被重置。四、配置 Embedding 模型RAGFlow v0.22 不再内置 Embedding 模型需自行配置。方案 A阿里云百炼 API在线在 RAGFlow 界面 →模型提供商→ 添加选择 OpenAI-API-Compatible 或 Tongyi-Qianwen填写 API KeyBase URL:https://dashscope.aliyuncs.com/compatible-mode/v1模型名:text-embedding-v4⚠️注意: 需要确保 Docker 容器能正常访问阿里云 API。方案 BTEI 本地服务推荐免网络依赖在.env中启用 TEI profileCOMPOSE_PROFILES${DOC_ENGINE},${DEVICE},tei-cpu重启服务后 TEI 会自动拉取镜像并下载模型约 1.2 GB启动后无需外网即可使用。RAGFlow 界面的模型提供商将自动出现 TEI 实例。五、配置 DeepSeek Chat 模型对话模型要让 RAGFlow 能够与知识库进行对话问答需要配置一个大语言模型Chat 模型。这里使用 DeepSeek 官方 API无需本地部署模型。5.1 获取 DeepSeek API Key前往 DeepSeek 开放平台 注册/登录在控制台中创建 API Key复制备用 DeepSeek API 按量计费价格低廉新用户通常有免费额度。5.2 在 RAGFlow 中添加模型登录 RAGFlow → 点击右上角头像 →模型提供商找到OpenAI-API-Compatible卡片DeepSeek API 兼容 OpenAI 格式点击添加模型按以下参数填写参数填写内容模型类型chat模型名称deepseek-chatDeepSeek-V3或deepseek-reasonerDeepSeek-R1基础 URLhttps://api.deepseek.com/v1API-Key粘贴 5.1 获取的 DeepSeek API Key最大 Token 数8192点击确定保存5.3 设为默认模型在模型提供商页面 →系统模型设置→ 将刚添加的 DeepSeek 模型设为默认Chat 模型。5.4 配置说明ℹ️Chat 模型对话和Embedding 模型文档向量化是两类不同的模型需要分别配置Chat 模型 → DeepSeek API本节配置Embedding 模型 → 阿里云百炼 / TEI 本地第四章配置六、使用 RAGFlow6.1 每次使用的完整流程启动 Docker Desktop → 等待引擎就绪 → 运行启动脚本 → 等待服务初始化 → 打开浏览器步骤操作预计耗时1启动 Docker Desktop30-60 秒2双击项目下的启动脚本—3等待容器启动 后端初始化30-60 秒4浏览器打开http://localhost:8080—6.2 基本操作1. 注册/登录首次使用需注册账号或使用默认adminragflow.io / admin。2. 创建知识库点击知识库→创建知识库输入名称关键配置配置项建议值说明Embedding 模型选择第四章配置的模型决定文档向量化的质量切片方法General通用适合 PDF/Word/TXT 等大多数文档切片大小 (chunk_size)默认 512文本块大小越大上下文越完整但检索精度越低重叠量 (overlap)默认 64相邻文本块之间的重叠字符数防止信息在边界被截断 如果上传的是QA 格式的 Excel第一列问题、第二列答案切片方法选QA 模式RAGFlow 会按问答对自动切分。3. 上传文档支持格式PDF、DOCX、TXT、Markdown、Excel、PPT、图片等上传后点击文档右侧的运行按钮开始解析等待状态变为绿色勾✅表示解析完成可以点击文件名查看每个文本切片的具体内容4. 检索测试在知识库页面的检索测试输入框中输入问题验证知识库能否检索到相关内容。这一步可以在创建对话之前确认知识库是否能正常工作。5. 创建聊天助手点击聊天→新建助理填写名称后关键配置配置项设置知识库勾选你创建的知识库Chat 模型选择 DeepSeek API 模型第五章配置的召回数量Top K建议 3~5检索到的相关文本块数量系统提示词自定义见下方推荐模板推荐系统提示词模板你是一个智能助手请总结知识库的内容来回答问题请列举知识库中的数据详细回答。 当所有知识库内容都与问题无关时你的回答必须包括知识库中未找到您要的答案这句话。 回答需要考虑聊天历史。 以下是知识库 {knowledge} 以上是知识库。{knowledge}是占位符RAGFlow 会自动替换为检索到的知识库内容。6. 开始对话在聊天框中输入问题模型将结合知识库中的文档内容生成回答并标注引用来源。6.3 工作架构用户提问 ↓ Embedding 模型 → 将问题转向量 ↓ 向量相似度检索 → 在知识库中找到最相关的文本块Top K ↓ 检索结果 原问题 → 拼接 Prompt ↓ DeepSeek API云端→ 基于知识库内容生成答案 ↓ 返回带引用的回答Chat 模型: DeepSeek 官方 API — 云端推理无需本地 GPUEmbedding 模型: 阿里云百炼 API 或 TEI 本地 — 文档向量化知识库存储: RAGFlow 内置向量数据库文档保留在本地兼顾隐私性和便捷性七、日常维护常用命令# 进入项目目录cd...\ragflow-main\docker# 启动所有服务docker compose-f docker-compose.yml--profile cpu up-d# 停止所有服务docker compose-f docker-compose.yml--profile cpu down# 查看 ragflow 容器日志docker compose logs-f ragflow-cpu# 查看所有容器状态dockerps# 仅重载 Nginx不改配置docker exec docker-ragflow-cpu-1 nginx-s reload数据备份说明数据存储在 Docker 卷中MySQL、Elasticsearch、MinIO执行docker compose down不会删除数据卷。不要执行docker compose down -v否则会清空所有数据。八、方案对比与决策记录Nginx 配置修复方案方案描述持久化最终选择docker cp覆盖启动后手动复制配置❌ 重启失效临时应急Volume 挂载通过 docker-compose 挂载文件⚠️ 被 entrypoint 覆写无效已废弃Volume entrypoint 守卫挂载文件 脚本跳过覆写✅最终采用九、常见问题速查问题可能原因解决方法文档解析速度很慢机器配置低批处理量太大.env中调低EMBEDDING_BATCH_SIZE2或4DeepSeek API 连接失败API Key 错误 或 网络不通检查 Key 是否正确确认api.deepseek.com可访问知识库检索结果不准切片大小不合适调小 chunk_size如 256增大 overlap如 128镜像拉取超时镜像源失效更新registry-mirrors地址列表优先用阿里云专属加速容器启动后马上退出端口冲突 或 内存不足docker logs docker-ragflow-cpu-1查看日志参考资料视频链接内容保姆级 Docker 安装 镜像加速B站 BV1xHA3euEcnDocker Desktop 安装、WSL2 配置、国内镜像加速DeepSeek RAGFlow 构建个人知识库B站 BV1WiP2ezE5aRAGFlow 纯本地化部署、DeepSeek 模型对接