Windows下使用 Docker部署DeerFlow

Windows 下使用 Docker 部署 DeerFlow：一次完整实战记录

本文记录一次在 Windows 环境中通过 Docker 部署 DeerFlow 的完整过程。重点不只是“命令怎么敲”，也包括实际部署中遇到的几个典型问题：Docker Desktop 无法启动、WSL2 内核缺失、当前用户没有 Docker 权限、Docker Hub 拉取镜像超时等。

本文环境：

• 系统：Windows
• Docker：Docker Desktop
• DeerFlow 项目目录：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-Group'docker-users'

如果当前执行命令的用户不在docker-users组中，需要添加进去。以本文环境为例，实际运行用户是：

whoami

输出为：

desktop-rainder\codexsandboxoffline

于是把该用户加入docker-users：

Add-LocalGroupMember-Group'docker-users'-Member'DESKTOP-RAINDER\CodexSandboxOffline'

如果你是普通本机用户，可以按自己的用户名添加，例如：

Add-LocalGroupMember-Group'docker-users'-Member'DESKTOP-RAINDER\Rainder'

执行后重新打开终端，或重启 Docker Desktop，让用户组权限生效。

3. 修复 WSL2 内核问题

Docker Desktop 的 Linux 容器后端依赖 WSL2。如果执行：

wsl--status

提示需要更新 WSL2 内核，可以先尝试：

wsl--update

如果这条命令长时间卡住，可以使用微软 WSL2 内核更新包：

Invoke-WebRequest`-Uri'https://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`-Name'Docker Desktop','com.docker.backend','docker-desktop','docker-sandbox','com.docker.build'`-Force `-ErrorAction SilentlyContinue

再关闭 WSL 后端：

wsl--shutdown

重新启动 Docker Desktop：

Start-Process-FilePath'C:\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.cmd

DeerFlow 在 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

这个过程会构建并启动三个主要服务：

• frontend
• gateway
• nginx

最终服务会通过 nginx 暴露在：

http://localhost:2026

8. 处理 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--format"table {{.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-Uri'http://localhost:2026'-UseBasicParsing

返回HTTP 200就说明页面已经可访问。

浏览器打开：

http://localhost:2026

10. 常用运维命令

启动：

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--gateway

11. 关于模型 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 启动流程就比较直接了。