ByteDance/DeerFlow 项目详情

DeerFlow（Deep Exploration and Efficient Research Flow）是字节跳动开源的社区驱动型深度研究框架，核心将大语言模型与网页搜索、爬虫、Python 代码执行等工具融合，主打自动化深度研究、多智能体协作，同时已上线火山引擎 FaaS 应用中心，支持线上体验和一键部署，项目遵循MIT 开源协议，目前在 GitHub 收获16.6k Star、2.1k Fork，有 60 位贡献者参与开发。

DeerFlow 本地部署方法（2026-03）

DeerFlow 提供Docker 一键部署（推荐）、本地开发部署两种主流方式，覆盖快速体验与二次开发场景。以下为官方标准流程与实操步骤，适配 Linux/macOS/Windows（WSL2）环境。

一、前置准备

1. 系统与硬件要求

• 系统：Linux（Ubuntu 22.04 推荐）、macOS、Windows（WSL2 环境）
• 硬件：≥10GB 磁盘空间、稳定网络、8GB+ 内存（推荐 16GB+）
• 核心依赖：Docker + Docker Compose（容器化部署首选）、Git

2. 依赖安装（仅本地开发模式需要）

二、方式一：Docker 一键部署（推荐，最快 5 分钟）

适合快速体验、无需本地开发，全程容器化隔离，环境一致性强。

1. 克隆仓库

bash》：

git clone https://github.com/bytedance/deer-flow.gitcd deer-flow

2. 生成配置文件

执行命令自动生成 .env、config.yaml 等基础配置：

bash》：

make config

3. 初始化沙箱镜像（仅首次 / 更新时执行）

拉取运行所需的沙箱容器镜像，首次执行耗时较长（约 1-5 分钟，取决于网络）：

bash：

make docker-init

4. 启动服务

bash》：

make docker-start

5. 访问与验证

• 访问地址：http://localhost:2026
• 验证：页面正常加载、无报错即为部署成功

6. 停止服务

bash》：

make docker-down

三、方式二：本地开发部署（适合二次开发 / 调试）

适合需要修改源码、热重载调试的场景，依赖本地环境完整。

1. 环境检查

bash》：

make check

根据提示补全缺失依赖（Node.js、pnpm、uv、Python 等）。

2. 安装前后端依赖

bash》：

make install

3. 配置 API 密钥（关键步骤）

编辑配置文件，填入大模型 / 搜索服务密钥：

1.编辑模型配置：vim config.yaml

YAML》：

• models:
• - name: gpt-4o
• display_name: GPT-4o
• use: langchain_openai:ChatOpenAI
• model: gpt-4o
• api_key: $OPENAI_API_KEY # 从环境变量读取
• max_tokens: 4096
• temperature: 0.7

2.编辑环境变量：vim .env

env》：

OPENAI_API_KEY=你的OpenAI密钥

TAVILY_API_KEY=你的搜索密钥（可选）

4. 启动开发服务（热重载）

bash》：

make dev

支持前端 / 后端代码修改自动重载，无需重启服务。

5. 访问与验证

• 主界面：http://localhost:2026
• 后端接口：http://localhost:2024（LangGraph）、http://localhost:8001（Gateway）

四、生产环境部署（进阶）

若用于正式使用，可采用生产级容器化部署：

bash》：

# 构建镜像并启动所有服务make up# 停止服务make down# 查看日志make logs

五、核心配置说明

1. 模型配置：config.yaml 支持多模型切换，可配置 OpenAI、Anthropic、DeepSeek 等，通过 api_key 或环境变量注入密钥。
2. 沙箱模式：

本地执行：直接在主机运行代码（风险高，不推荐生产）

Docker 执行：容器隔离（推荐，安全可控）

3. 环境变量：敏感密钥建议通过 .env 或系统环境变量配置，避免硬编码。

六、常见问题排查

1. Docker 镜像拉取失败：更换国内镜像源、检查网络代理。
2. 端口占用：修改 .env 中的端口配置（如 PORT=2026 改为其他未占用端口）。
3. 依赖安装失败：执行 make clean 清理缓存后重新执行 make install。
4. Windows 兼容性：必须使用 WSL2（Ubuntu 22.04/24.04），原生 CMD/PowerShell 不支持部分命令。

七、快速访问

• 官方仓库：bytedance/deer-flow
• 配置文档：CONFIGURATION.md

结合前面的 DeerFlow 本地部署方法，下面补充Windows WSL2 专属安装步骤、国内镜像源加速配置，同时适配 Docker、依赖安装、网络加速等核心场景，解决国内网络环境下的部署难题，全程基于 WSL2（Ubuntu 22.04 发行版，推荐）操作：

八、前置：Windows WSL2 环境初始化

1. 开启 WSL2 并安装 Ubuntu

1. 以管理员身份打开 Windows PowerShell，执行命令启用 WSL 功能：

powershell》：

wsl --install

2.执行完成后，重启电脑；重启后系统会自动弹出 Ubuntu 初始化界面，设置用户名和密码（自定义，记住密码，后续 sudo 需要）。

3.若已安装 WSL，可手动指定安装 Ubuntu 22.04：

powershell》：

powershell wsl --list --onlinewsl --install -d Ubuntu-22.04

2. 优化 WSL2 配置（提升性能与兼容性）

1. 在 Windows 文件资源管理器中，打开路径：C:\Users\你的Windows用户名\
2. 新建文件，命名为 .wslconfig（无后缀名），写入以下配置，优化 WSL2 资源占用：

在配置文件中，以下是针对 WSL2 的相关设置：

[wsl2]# 为 WSL 分配的内存大小，可依据自身计算机的实际情况进行灵活调整，建议分配的内存不少于 8GBmemory = 8GB# 为 WSL 分配的 CPU 核心数量processors = 4# 启用本地端口转发功能，此设置有助于便捷地访问 WSL 服务localhostForwarding = true

这些设置能够优化 WSL2 的运行环境，使其更贴合您的使用需求。

3.保存后，在 PowerShell 中执行 wsl --shutdown 关闭 WSL，再重新打开 Ubuntu 终端生效。

3. 进入 WSL2 Ubuntu 环境

在开始菜单打开「Ubuntu 22.04 LTS」，进入 Linux 终端，后续所有操作均在此终端执行。

九、Windows WSL2 专属：依赖安装（国内加速版）

1. 系统软件源替换为国内镜像（Ubuntu 22.04）

默认源在国内访问缓慢，替换为阿里云 / 清华镜像，加速 apt 安装：

1. 备份原软件源：

在 Bash 环境中，若需对系统软件源列表文件进行备份操作，可借助超级用户权限执行如下指令：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

此命令的作用在于将 /etc/apt/sources.list 文件复制一份，并以 .bak 为后缀名进行保存，从而实现对原始文件的备份，以防后续操作出现意外状况时可恢复至初始状态。

2.编辑源文件：

于 Bash 环境之中，若要对系统的软件源列表文件进行编辑，可运用 nano 文本编辑器来达成。具体操作是借助超级用户权限执行如下指令：

sudo nano /etc/apt/sources.list

该指令会以超级用户身份调用 nano 编辑器打开 /etc/apt/sources.list 文件，方便用户对软件源的配置信息进行查看、修改与管理，以适配不同的软件获取需求。

3.清空文件内容，粘贴阿里云 Ubuntu 22.04 镜像源：

# 主软件源，涵盖主要、受限、通用和多元软件包deb http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse# 安全更新软件源，提供系统安全相关的软件包更新deb http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse# 常规更新软件源，包含系统的常规软件更新deb http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse# 预发布软件源，提供尚未正式发布的软件包deb http://mirrors.aliyun.com/ubuntu/ jammy-proposed main restricted universe multiverse# 回溯软件源，可获取旧版本软件包deb http://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse# 主软件源的源码，用于获取软件的源代码deb-src http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse# 安全更新软件源的源码deb-src http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse# 常规更新软件源的源码deb-src http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse# 预发布软件源的源码deb-src http://mirrors.aliyun.com/ubuntu/ jammy-proposed main restricted universe multiverse# 回溯软件源的源码deb-src http://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse

4.保存退出：按 Ctrl+O 保存，Ctrl+X 退出。

5.更新软件列表：

bash》：

sudo apt update && sudo apt upgrade -y

2. 安装基础依赖

bash》：

sudo apt install -y git make curl wget gcc g++ python3.10 python3.10-venv python3-pip

十、Windows WSL2 专属：Docker 安装与国内镜像加速

Docker 是 DeerFlow 部署的核心依赖，WSL2 下需安装 Docker Desktop（Windows 版）并配置 WSL2 集成，同时配置国内镜像源。

1. 安装 Docker Desktop（Windows）

1. 下载地址：Docker Desktop 官方下载
2. 安装时勾选 Use WSL 2 instead of Hyper-V（默认已勾选，WSL2 环境必备），完成安装后重启电脑。
3. 打开 Docker Desktop，进入设置（Settings）→ Resources → WSL Integration，启用 Ubuntu-22.04 的集成，点击 Apply & Restart。

2. 验证 WSL2 与 Docker 连通

在 Ubuntu 终端执行：

bash》：

docker --version# 输出版本信息则连通成功

3. 配置 Docker 国内镜像源（加速拉取镜像）

方式 1：Docker Desktop 图形界面配置（推荐）

1. 打开 Docker Desktop → 进入 Settings → Docker Engine
2. 在配置文件中，添加国内镜像源，修改后如下：

json》：

{    // 配置 Docker 镜像源，可加速镜像拉取过程    "registry-mirrors": [        "https://docker.mirrors.ustc.edu.cn",        "https://hub-mirror.c.163.com",        "https://mirror.baidubce.com"    ],    // 不安全的镜像仓库列表，当前为空    "insecure-registries": [],    // 是否开启调试模式，此处设置为不开启    "debug": false,    // 是否启用实验性功能，此处设置为不启用    "experimental": false}

3.点击 Apply & Restart，Docker 会自动重启生效。

方式 2：命令行配置（备用）

若无法使用图形界面，在 Ubuntu 终端编辑 Docker 配置：

bash》：

sudo mkdir -p /etc/dockersudo nano /etc/docker/daemon.json

粘贴上述镜像源配置，保存后执行：

bash》：

sudo systemctl daemon-reloadsudo systemctl restart docker

4. 验证镜像加速

bash》：

docker info# 输出中包含 "Registry Mirrors" 且显示配置的国内地址，即为生效

十一、Windows WSL2 专属：DeerFlow 部署（Docker 一键部署，国内加速）

基于你之前的部署需求，结合 WSL2 和国内镜像加速，完整流程如下：

1. 克隆 DeerFlow 仓库

bash：》

git clone https://github.com/bytedance/deer-flow.gitcd deer-flow

2. 生成配置文件

bash》：

make config

3. 初始化沙箱镜像（国内加速版）

由于配置了 Docker 国内镜像，拉取镜像速度会大幅提升：

bash》：

make docker-init

4. 启动 DeerFlow 服务

bash》：

make docker-start

5. 访问服务

在 Windows 浏览器中访问：http://localhost:2026

原理：Docker Desktop 已配置 WSL2 端口转发，Windows 本地可直接访问 WSL2 内的服务端口。

6. 常用管理命令

bash》：

# 停止服务make docker-down# 查看Docker容器日志docker compose logs -f

十二、Windows WSL2 专属：本地开发部署（二次开发，国内加速）

若需要二次开发，补充 Node.js、pnpm、Python 依赖的国内加速配置：

1. Node.js 安装（国内镜像）

bash》：

# 使用淘宝镜像安装Node.js 22.xcurl -fsSL https://npmmirror.com/mirrors/node/setup_22.x | sudo -E bash -sudo apt install -y nodejs# 验证版本node -v && npm -v

2. pnpm 安装（淘宝镜像）

bash》：

npm install -g pnpm --registry=https://registry.npmmirror.com# 配置pnpm默认镜像pnpm config set registry https://registry.npmmirror.com

3. Python 包镜像加速（pip）

临时使用：

bash》：

pip install 包名 -i https://pypi.tuna.tsinghua.edu.cn/simple

永久配置：

bash》：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

4. 安装依赖并启动开发服务

bash》：

# 安装依赖（加速）make install# 启动开发热重载服务make dev

十三、WSL2 专属常见问题排查

1. Docker 无法启动

检查 Docker Desktop 的 WSL2 集成是否启用，执行 wsl --list --verbose 确认 WSL 版本为 2。

2.端口占用（2026/2024 端口）

修改 .env 文件中的端口配置，例如：

bash》：

sed -i 's/PORT=2026/PORT=2027/g' .env

访问时使用 http://localhost:2027。

3.Git 克隆速度慢

配置 Git 国内镜像：

bash》：

git config --global url."https://ghproxy.com/https://github.com".insteadOf https://github.com

git config --global url."https://ghproxy.com/https://github.com".insteadOf https://github.com

4.WSL2 磁盘空间不足

将 DeerFlow 仓库放在 WSL2 的用户目录（/home/你的用户名/），避免访问 Windows 磁盘（速度慢、权限问题）。

十四、核心加速配置汇总（一键复制）

1. Docker 镜像源：阿里云、中科大、网易镜像
2. apt 源：阿里云 Ubuntu 镜像
3. npm/pnpm：淘宝镜像
4. pip：清华源
5. Git：ghproxy 代理加速

按照以上步骤，你可以在 Windows WSL2 环境下，以国内加速的方式完成 DeerFlow 的本地部署，大幅解决网络慢、依赖安装失败、镜像拉取卡顿等问题。