DeerFlow部署与排障记录

DeerFlow 多智能体系统部署指南环境前提Windows 系统已安装Git Bash。已安装并启动Docker Desktop建议开启 WSL2 模式。已克隆或下载 DeerFlow 的源码且当前在项目根目录下操作。DeerFlow部署步骤Docker 方式1.前置要求本次安装Docker Python 3.12 Node.js 222.整体流程bash# 第一步克隆仓库 git clone https://github.com/bytedance/deer-flow.git cd deer-flow # 第二步生成配置文件重要 make config # 第三步编辑 .env 文件填入你的 API Key # 支持 OpenAI、Claude、DeepSeek 等 # 第四步启动服务 make docker-start3.具体步骤第一步克隆项目bashgit clone https://github.com/bytedance/deer-flow.git cd deer-flow第二步检查 make 是否可用bashmake --version如果提示找不到 make用这个替代方法安装用 Windows PowerShell 安装 make1.powershellwinget install GnuWin32.Make2.装完后把 make 加入环境变量powershell$env:PATH ;C:\Program Files (x86)\GnuWin32\bin3.关掉 Git Bash重新打开进入项目目录bashcd deer-flow make --versionmake装好后需要让 Git Bash 也能找到它-把路径永久加进去echo export PATH$PATH:/c/Program Files (x86)/GnuWin32/bin ~/.bashrcsource ~/.bashrcmake --version第三步生成配置文件bashmake config第四步用 VS Code 或记事本打开deer-flow文件夹里的.env文件填入你的 AI 模型 Key。在 Git Bash 里运行bashnotepad ~/deer-flow/.env第五步打开 config.yaml 确认模型配置notepad ~/deer-flow/config.yamlmodels:后添加模型配置第六步保存文件CtrlS然后回到 Git Bash 运行make docker-start△常用命令备忘bashmake docker-start # 启动 make docker-stop # 停止 make docker-logs # 查看日志出问题时用 DeerFlow 排障全记录第一部分打开浏览器访问 http://localhost:2026产生“页面抖动”、“创建失败”、502bad页面剧烈抖动、创建账户显示网络问题时后端“反复自杀” (Crash Loop Backoff)由于config.yaml格式错误后端 Gateway 每次启动到一半就因为报错而退出Docker 随即又尝试重启它。前端“无能为力”前端 UI 不断尝试向后端发送“注册/登录”请求。由于后端处于崩溃状态请求被 Nginx 拦截并返回502。UI 表现为抖动前端逻辑在“显示错误弹窗”和“尝试重新拉取用户信息”之间高频切换在浏览器端表现为视觉上的抖动或闪烁。数据库权限/路径锁定在路径未修复前容器内的数据库SQLite由于找不到映射路径无法执行写入操作导致“创建账户”动作因 IO 异常而报错。第二部分排障复盘错误信号根本原因 (Root Cause)修复方案No package.json foundworking_dir在容器根目录而代码在子目录。使用docker exec -w指定运行路径。mapping values are not allowedYAML 语法敏感冒号后缺空格或缩进不整齐。严格执行 2 空格缩进清理“幽灵空格”。Field required: usePydantic 校验未通过缺少底层驱动类声明。补充use: langchain_openai:ChatOpenAI。Environment variable not foundDocker 无法从.env读取 Windows 变量。在config.yaml中使用双引号硬编码密钥。502 Bad Gateway后端程序崩溃重启中Nginx 找不到上游。修复后端 Bug 后依次重启 Gateway 和 Nginx。第三部分解决流程 一环境清理与路径锁定目标防止 Git Bash 篡改路径Bash# 1. 强行关闭自动路径转换极其关键 export MSYS_NO_PATHCONV1 # 2. 清理残缺容器确保干净起步 docker-compose -f docker/docker-compose-dev.yaml down 二绝对路径硬编码目标彻底解决 Windows 环境变量传递失效导致的“空壳挂载”问题。操作位置 VS Code操作内容打开docker/docker-compose-dev.yaml将volumes和environment下的所有${DEER_FLOW_ROOT}替换为 Windows 绝对路径如C:/Users/sh/deer-flow。 三规避网络孤岛目标强制 Docker 在构建阶段使用国内镜像源避免 Python 依赖超时。Bash# 带着清华源参数重新构建底层镜像 docker-compose -f docker/docker-compose-dev.yaml build --build-arg PIP_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simple provisioner # 强制拉起所有容器 docker-compose -f docker/docker-compose-dev.yaml up -d --force-recreate 四前端依赖精准安装目标解决“找不到 package.json”的问题。Bash# 使用 -w 指定工作目录 /app/frontend docker exec -w /app/frontend -it deer-flow-frontend pnpm install --registryhttps://registry.npmmirror.com 五后端 Pydantic 校验与模型配置目标注入 API Key满足驱动校验。操作位置 VS Code (config.yaml)YAML六唤醒与审计目标重启服务查看实时日志。Bash# 重启后端与网关 docker restart deer-flow-gateway docker restart deer-flow-nginx # 监控启动日志看到 Application startup complete 即代表通关 docker exec -it deer-flow-gateway tail -f /app/logs/gateway.log最后 http://localhost:2026