Windows下使用 Docker部署DeerFlow

Windows 下使用 Docker 部署 DeerFlow一次完整实战记录本文记录一次在 Windows 环境中通过 Docker 部署 DeerFlow 的完整过程。重点不只是“命令怎么敲”也包括实际部署中遇到的几个典型问题Docker Desktop 无法启动、WSL2 内核缺失、当前用户没有 Docker 权限、Docker Hub 拉取镜像超时等。本文环境系统WindowsDockerDocker DesktopDeerFlow 项目目录E:\deer-flow访问地址http://localhost:2026说明DeerFlow 官方仓库为 bytedance/deer-flow。本文以项目自带的 Docker 脚本为主不手工改 Compose 配置。1. 确认 Docker 是否安装先检查 Docker CLI 是否存在docker--version如果已经安装会看到类似输出Docker version 29.5.3, build d1c06ef再检查 Docker 引擎是否可用docker info我这里一开始 Docker CLI 存在但 Docker 引擎不可用报错大致是permission denied while trying to connect to the docker API at npipe:////./pipe/docker_engine这说明 Docker Desktop 组件在但当前用户没有权限连接 Docker 引擎或者 Docker Desktop 后端没有正常起来。2. 检查 Docker Desktop 和用户权限查看 Docker Desktop 是否在运行Get-Process|Where-Object{$_.ProcessName-like*Docker*}|Select-ObjectProcessName,Id,Path再检查当前docker-users组成员Get-LocalGroupMember-Groupdocker-users如果当前执行命令的用户不在docker-users组中需要添加进去。以本文环境为例实际运行用户是whoami输出为desktop-rainder\codexsandboxoffline于是把该用户加入docker-usersAdd-LocalGroupMember-Groupdocker-users-MemberDESKTOP-RAINDER\CodexSandboxOffline如果你是普通本机用户可以按自己的用户名添加例如Add-LocalGroupMember-Groupdocker-users-MemberDESKTOP-RAINDER\Rainder执行后重新打开终端或重启 Docker Desktop让用户组权限生效。3. 修复 WSL2 内核问题Docker Desktop 的 Linux 容器后端依赖 WSL2。如果执行wsl--status提示需要更新 WSL2 内核可以先尝试wsl--update如果这条命令长时间卡住可以使用微软 WSL2 内核更新包Invoke-WebRequest-Urihttps://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi-OutFile.\wsl_update_x64.msi-UseBasicParsing然后静默安装Start-Processmsiexec.exe -ArgumentList/i .\wsl_update_x64.msi /quiet /norestart-Wait -PassThru安装后再次检查wsl--status正常情况下可以看到 WSL 默认版本为 2。4. 重启 Docker Desktop如果 Docker Desktop 一直卡在starting可以先关闭 Docker 相关进程Stop-Process-NameDocker Desktop,com.docker.backend,docker-desktop,docker-sandbox,com.docker.build-Force -ErrorAction SilentlyContinue再关闭 WSL 后端wsl--shutdown重新启动 Docker DesktopStart-Process-FilePathC:\Program Files\Docker\Docker\Docker Desktop.exe等待一会儿再检查docker info如果看到 Server 信息、Storage Driver、Kernel Version 等内容说明 Docker 引擎已经正常。5. 准备 DeerFlow 项目本文使用已经部署好的目录E:\deer-flow进入目录后确认项目结构Get-ChildItemE:\deer-flow关键文件包括Makefile Install.md config.yaml .env frontend\.env docker\docker-compose-dev.yaml scripts\docker.sh scripts\run-with-git-bash.cmdDeerFlow 在 Windows 下会通过 Git Bash 运行脚本因此需要 Git for Windows 可用。6. 运行 DeerFlow Docker 初始化因为当前 Windows 环境没有系统级make所以直接调用项目自带脚本cd E:\deer-flow.\scripts\run-with-git-bash.cmd./scripts/docker.sh init本次输出显示Detected local sandbox mode - no Docker image required. Docker environment is ready. Next step: make docker-start这说明当前config.yaml使用的是 local sandbox 模式不需要额外拉取 sandbox 镜像。7. 启动 DeerFlow Docker 服务继续执行cd E:\deer-flow.\scripts\run-with-git-bash.cmd./scripts/docker.shstart这个过程会构建并启动三个主要服务frontendgatewaynginx最终服务会通过 nginx 暴露在http://localhost:20268. 处理 Docker Hub 拉取镜像超时第一次启动时构建过程可能在拉取基础镜像元数据时报错例如failed to fetch anonymous token Get https://auth.docker.io/token?...: connectex: A connection attempt failed这通常不是 DeerFlow 配置错误而是本机访问 Docker Hub 的网络不稳定。本次解决方式是先手工预拉基础镜像docker pull python:3.12-slim-bookworm docker pull node:22-alpine docker pull docker:clidocker pull ghcr.io/astral-sh/uv:0.7.20这些镜像拉取成功后再重新执行cd E:\deer-flow.\scripts\run-with-git-bash.cmd./scripts/docker.shstart第二次构建可以复用已经拉下来的基础镜像成功率会高很多。9. 验证服务状态查看容器dockerps--formattable {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}正常状态类似NAMES IMAGE STATUS PORTS deer-flow-nginx nginx:alpine Up 0.0.0.0:2026-2026/tcp deer-flow-gateway deer-flow-dev-gateway Up 8001/tcp deer-flow-frontend deer-flow-dev-frontend Up 3000/tcp也可以用 Compose 查看docker compose-p deer-flow-dev-f E:\deer-flow\docker\docker-compose-dev.yamlps最后访问页面Invoke-WebRequest-Urihttp://localhost:2026-UseBasicParsing返回HTTP 200就说明页面已经可访问。浏览器打开http://localhost:202610. 常用运维命令启动cd E:\deer-flow.\scripts\run-with-git-bash.cmd./scripts/docker.shstart停止cd E:\deer-flow.\scripts\run-with-git-bash.cmd./scripts/docker.sh stop查看全部日志cd E:\deer-flow.\scripts\run-with-git-bash.cmd./scripts/docker.sh logs只看前端日志cd E:\deer-flow.\scripts\run-with-git-bash.cmd./scripts/docker.sh logs--frontend只看网关日志cd E:\deer-flow.\scripts\run-with-git-bash.cmd./scripts/docker.sh logs--gateway11. 关于模型 API Key本文没有展示或读取.env中的密钥值。DeerFlow 真正调用模型时需要在.env或系统环境变量中配置对应 provider 的 API Key。config.yaml中可能引用的环境变量包括OPENAI_API_KEY ANTHROPIC_API_KEY DEEPSEEK_API_KEY GEMINI_API_KEY VOLCENGINE_API_KEY TAVILY_API_KEY BRAVE_SEARCH_API_KEY实际使用哪个变量取决于你在config.yaml中选择的模型和工具配置。12. 本次部署结论最终部署结果Docker Desktop 成功运行。WSL2 内核已修复。当前用户已具备 Docker 引擎访问权限。DeerFlow Docker 初始化完成。DeerFlow 前端、网关、nginx 三个容器均已启动。http://localhost:2026返回HTTP 200。如果你在 Windows 上部署 DeerFlow最容易卡住的地方通常不是 DeerFlow 本身而是 Docker Desktop、WSL2 和镜像拉取网络。把这三块处理顺了后面的 DeerFlow 启动流程就比较直接了。