DeerFlow 2.0 本地部署教程与排错指南

适用场景

DeerFlow 是一套基于 LangGraph 的「深度研究」Agent 框架：给它一个题目，它会自动拆解子问题、调用搜索引擎、抓取网页正文、多轮反思，最后产出一份带引用的研究型报告。把整套东西放在自己机器上跑，适合三类人：想研究 Agent 编排流程的 AI 开发者、需要在内网处理敏感资料不便走公有云 SaaS 的团队、以及想拿它当脚手架改成自己业务 Agent 的工程师。本文覆盖从零环境准备到跑通一个真实研究任务的全过程，并重点讲国内网络下容易踩的坑。

环境与前置条件

先对照下表，缺什么补什么。所有版本号以官方文档当前版本为准，不要照搬本文示例中的数字。

关于显存：DeerFlow 本身不加载模型权重，默认走 API 调用，机器可以是纯 CPU。只有当你打算用 Ollama、vLLM 之类自建推理时，才需要考虑显存——7B 级别量化模型大致 8GB 显存起步，32B 级别通常要 24GB 以上，具体取决于量化方式与上下文长度，跑之前先确认。

分步骤部署

步骤一：检查系统与基础工具

先确认手上有什么，避免装到一半才发现缺件。

```bash

uname -a

python3 --version

node --version

git --version

make --version

```

Python 版本低于要求时，不要动系统自带的 Python，用 pyenv 或 uv 管理的独立版本，避免污染系统环境。

步骤二：安装 uv

uv 同时管 Python 版本和虚拟环境，装它比手动折腾 venv 省事。

```bash

curl -LsSf https://astral.sh/uv/install.sh | sh

source $HOME/.local/bin/env

uv --version

```

安装脚本地址以 uv 官方文档当前版本为准。如果这条命令卡住，改用 pip install -U uv 也可以。装完后 uv --version 能打印出版本号即为成功。

步骤三：安装 Node.js 与 pnpm

推荐用 nvm 或 fnm 管理 Node，方便后面切版本。

```bash

node -v

npm i -g pnpm

pnpm -v

```

国内网络下把 npm 源换掉，能省下大量等待时间：

```bash

npm config set registry https://registry.npmmirror.com

pnpm config set registry https://registry.npmmirror.com

```

步骤四：获取源码

```bash

git clone <项目仓库地址> deer-flow

cd deer-flow

```

仓库地址以官方项目页为准。国内直连 GitHub 慢的时候，可以用镜像加速地址、配置代理，或者直接在网页上下载 zip 包再解压，效果一样。

步骤五：安装后端依赖

```bash

uv sync

```

这一步会创建 .venv 目录并安装全部 Python 依赖。看到命令无报错退出、目录下出现 .venv 即为成功。

如果 PyPI 下载慢，配置 pip 镜像：

```ini

~/.config/pip/pip.conf

[global]

index-url = https://pypi.tuna.tsinghua.edu.cn/simple

trusted-host = pypi.tuna.tsinghua.edu.cn

```

uv 也支持通过命令行参数或环境变量指定索引源，具体参数名以 uv 文档为准。少数依赖需要本地编译，若报缺头文件，Linux 下补上 build-essential 与 python3-dev 即可。

步骤六：配置环境变量

配置文件通常在仓库根目录，形如 .env.example，先复制一份再改。具体文件名与字段名以仓库当前版本为准。

```bash

cp .env.example .env

```

用编辑器打开 .env，至少要填三类内容：模型接口的 base_url、api_key、模型名；搜索服务的 API Key；以及可选的日志级别、服务端口。不要把 .env 提交到任何 Git 仓库。

步骤七：配置模型

项目一般通过 conf.yaml 之类的配置文件描述模型，区分基础模型和推理模型两个角色：基础模型负责常规对话与总结，推理模型负责规划与反思，可以用同一个接口的不同模型。字段名以仓库示例文件为准，结构大致如下：

```yaml

BASIC_MODEL:

base_url: ${BASIC_MODEL_BASE_URL}

api_key: ${BASIC_MODEL_API_KEY}

model: ${BASIC_MODEL_NAME}

temperature: 0.7

```

这里的变量从 .env 读取，所以两边名字要完全对上。国内用户把 base_url 指向可直连的 OpenAI 兼容服务即可，注意有些服务要求地址带 /v1 后缀，有些不要，填错会直接 404。

步骤八：安装并构建前端

```bash

cd web

pnpm install

pnpm build

cd ..

```

只是本地体验的话，也可以跳过 build 直接跑开发模式。构建阶段内存占用较高，小内存机器可以加上：

```bash

NODE_OPTIONS=--max-old-space-size=4096 pnpm build

```

步骤九：启动服务

项目通常提供 Makefile 或 npm script 作为统一入口，以仓库 README 为准：

```bash

make dev

```

也可以分开启动，方便看日志：

```bash

uv run python server.py # 后端

cd web && pnpm dev # 前端

```

默认端口一般是后端 8000、前端 3000，实际以配置文件为准。启动成功的标志是后端打印出监听地址、前端打印出 Local 地址且无红色报错。

国内网络注意事项

• Python 依赖走清华或中科大镜像，npm 依赖走 npmmirror，这两个动作能解决大部分「安装卡住」的问题。
• GitHub 克隆慢时优先考虑下载 zip 包，比反复重试 git clone 稳定。
• 模型接口优先选国内可直连的 OpenAI 兼容服务。如果必须走海外接口，给 shell 配上代理并确认对 Python 进程生效：

```bash

export HTTP_PROXY=http://127.0.0.1:7890

export HTTPS_PROXY=http://127.0.0.1:7890

```

端口换成自己代理的实际端口。注意 systemd 托管的服务不会继承你终端的代理变量，要在 unit 文件里单独写。

• 搜索环节容易被忽略：Tavily 这类海外搜索服务在部分网络下不稳定，出现「研究跑完但没有引用来源」的情况，多半是搜索请求没成功。可以考虑自建 SearXNG 作为搜索后端，配置方式以官方文档为准。
• 前端构建时若长时间停在某个资源下载，检查页面模板里是否引用了外部 CDN 的字体或样式，内网环境下需要替换为本地资源。

验证部署是否成功

按下面四层依次验证，从底往上排错最快。

第一层：后端活着

```bash

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8000/docs

```

返回 200（或文档页面实际的 3xx 跳转）说明 HTTP 服务已起来。路由路径以项目实际定义为准。

第二层：模型通了

```bash

uv run python -c "

import os

from openai import OpenAI

client = OpenAI(base_url=os.environ['BASIC_MODEL_BASE_URL'], api_key=os.environ['BASIC_MODEL_API_KEY'])

resp = client.chat.completions.create(

model=os.environ['BASIC_MODEL_NAME'],

messages=[{'role': 'user', 'content': '用一个词回答：你好'}]

)

print(resp.choices[0].message.content)

"

```

能打印出模型回复，说明 base_url、key、模型名三者都正确。这一步失败就别往下走了。

第三层：前端能打开

浏览器访问 http://localhost:3000，看到对话输入框且浏览器控制台没有连续报错。

第四层：端到端跑一个任务

在界面里输入一个具体题目，例如「调研 Rust 在嵌入式领域的应用现状，输出 500 字以内的报告，附来源链接」。预期表现是：后端日志依次出现规划、搜索、抓取、总结等阶段，几分钟内返回一份带引用的 Markdown 报告。如果报告没有任何引用链接，回到上一节检查搜索服务。

常见报错与解决

报错一：ModuleNotFoundError: No module named '<项目包名>'

原因：没在虚拟环境里执行命令，或者 uv sync 没跑完。

解决：

```bash

cd deer-flow

uv sync

uv run python -c "import <项目包名>; print('<项目包名>', 'ok')"

```

包名以 pyproject.toml 里的定义为准。养成用 uv run 前缀执行命令的习惯，可以省掉激活虚拟环境这一步。

报错二：ERR_PNPM_NO_MATCHING_VERSION 或 pnpm install 长时间卡在 resolving

原因：npm 源响应慢，或者本地缓存损坏。

解决：

```bash

pnpm config set registry https://registry.npmmirror.com

pnpm store prune

rm -rf node_modules

pnpm install

```

报错三：openai.AuthenticationError: Error code: 401

原因：.env 没被加载、key 写错、或者 base_url 指向了错误的区域端点。

解决：

```bash

grep -i "api_key\|base_url" .env

uv run python -c "import os; print(os.environ.get('BASIC_MODEL_API_KEY', '未读取到'))"

```

如果打印「未读取到」，说明启动目录不对或者 .env 文件名不对，确认是在项目根目录启动，并且文件名与示例文件去掉 .example 后完全一致。

报错四：APIConnectionError 或 Connection timed out

原因：网络不通、base_url 地址缺 /v1、代理没生效。

解决：

```bash

curl -I "$BASIC_MODEL_BASE_URL"

export HTTPS_PROXY=http://127.0.0.1:7890

export HTTP_PROXY=http://127.0.0.1:7890

```

先确认 curl 能连通，再重启服务。

报错五：Error: listen EADDRINUSE: address already in use :::3000

原因：端口被别的进程占用，常见于上一次没关干净。

解决：

```bash

lsof -i :3000

kill -9 <PID>

```

或者在前端配置里把端口改成 3001 之类的空闲端口。

报错六：前端页面能打开，但发起对话就报 CORS 或 404

原因：前端调用的后端地址与实际后端地址不一致，多为环境变量没改就 build 了。

解决：修改前端目录下的环境变量文件，把 API 地址指向真实后端，然后重新 pnpm build 并重启。

报错七：构建阶段被 OOM Killer 杀掉

原因：内存不足。

解决：

```bash

NODE_OPTIONS=--max-old-space-size=4096 pnpm build

```

仍失败就临时加 swap，或者把构建挪到内存更大的机器上，把产物拷回来。

后续维护

备份：需要备份的核心是 .env、conf.yaml（或同类配置文件），以及会话与报告数据目录。若使用 SQLite，直接定期复制数据库文件；若使用 Postgres，用 pg_dump 做逻辑备份。这些文件包含密钥，权限设成 600，备份包也要加密存放。

升级：升级前先备份配置，然后拉取新代码、重装依赖、重启：

```bash

git fetch && git pull

uv sync

cd web && pnpm install && pnpm build && cd ..

```

配置字段在新版本里可能改名或新增，升级后对照新的示例文件检查一遍，别直接覆盖，改动逐项合并。

日志：开发阶段直接看终端输出即可；长期运行建议用 systemd 或 supervisor 托管进程，把标准输出重定向到文件，并配置 logrotate 做轮转，避免单文件涨到几个 GB。重点关注 401（key 失效）、429（触发限流）、超时三类记录。

监控：最少盯四项——进程存活（systemd 配 Restart=always）、磁盘剩余空间、内存占用、外部 API 错误率。另外记录几次真实任务的耗时作为基线，某天明显变慢通常意味着上游接口降速或搜索服务异常。

成本与稳定性：深度研究类任务会反复调用模型和搜索接口，建议限制单次任务的最大轮数与递归深度（配置项名称以官方文档为准），给搜索结果加缓存，避免一个跑飞的题目把额度吃光。密钥建议定期轮换，改完重启服务生效。