本地 AI Agent 平台实战：DeerFlow Windows 全栈部署与架构解析

2.3 设计意图解析

1. 网关层 (Gateway, Port 8001)：

   • 作用：作为唯一入口，统一处理鉴权、日志、限流。前端不直接调用 LangGraph，而是通过网关转发。
   • 好处：隐藏后端拓扑，未来若将 LangGraph 迁移到独立服务器，前端无需修改配置。

2. 编排层 (LangGraph, Port 2024)：

   • 作用：维护 Agent 的'记忆'和'状态'。LangGraph 的核心是 State Graph，它知道当前对话进行到哪一步。
   • 好处：支持断点续传、人工介入（Human-in-the-loop）。

3. 沙箱层 (Sandbox)：

   • 作用：隔离文件操作和代码执行。
   • 好处：防止 Agent 误删宿主机的关键文件，保障本地部署安全。

3. 实战演练：一步步实现 (Step-by-Step)

以下操作基于 Windows 11 环境。请确保你拥有管理员权限，以避免某些路径写入失败。

3.1 环境准备：工欲善其事

很多部署失败源于基础环境版本不对。DeerFlow 对版本要求较为严格，尤其是 Node.js 和 Python。

1. 安装 Node.js (v22.18.0+)
Windows 下推荐使用 winget 管理，便于后续升级。

# 在 PowerShell 中执行 winget install OpenJS.NodeJS.LTS # 验证 node --version # 必须输出 v22.18.0 或更高

专家提示：如果你之前安装过旧版 Node，建议先用 控制面板 卸载，避免 PATH 冲突。

2. 安装 pnpm
不要使用 npm 安装 pnpm，直接使用官方脚本更纯净。

npm install -g pnpm pnpm --version # 预期：10.30.3+

3. 安装 uv (Python 包管理器)
这是本项目的亮点。uv 不仅管理包，还能管理 Python 解释器本身。

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

关键步骤：安装完成后，uv 命令可能不会立即生效。这是因为 Windows 的环境变量刷新机制。

• 方案 A：关闭所有 PowerShell 窗口，重新打开。
• 方案 B：在当前窗口强制刷新 PATH（推荐）：

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

验证：

uv --version # 预期：uv 0.10.7+

3.2 项目克隆与配置

1. 克隆代码

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

2. 配置根目录环境变量 (.env)
在项目根目录创建 .env 文件。这是 Agent 连接外部大脑的钥匙。

# .env
# 搜索工具密钥
TAVILY_API_KEY=your-tavily-api-key
JINA_API_KEY=your-jina-api-key
# 模型配置 (以阿里 DashScope 为例，兼容 Anthropic 协议)
ANTHROPIC_AUTH_TOKEN=sk-你的密钥
ANTHROPIC_BASE_URL=https://dashscope.aliyuncs.com/apps/anthropic
API_TIMEOUT_MS=3000000

设计意图：将敏感密钥与代码分离，避免提交到 Git 仓库。API_TIMEOUT_MS 设置较大值是为了防止复杂 Agent 任务超时被杀。

3. 配置核心逻辑 (config.yaml)
这是 Agent 的'大脑皮层'，定义了它能用什么模型、能调用什么工具。

# config.yaml
models:
  - name: qwen3.5-plus
    use: langchain_anthropic:ChatAnthropic
    model: qwen3.5-plus
    api_key: $ANTHROPIC_AUTH_TOKEN
    base_url: $ANTHROPIC_BASE_URL
    supports_vision: true
tools:
  - name: web_search
    use: src.community.tavily.tools:web_search_tool
  - name: bash
    use: src.sandbox.tools:bash_tool

专家提示：use 字段采用了 模块路径：类名 的格式，这是 Python 动态导入的标准写法。如果自定义工具，需遵循此规范。

4. 配置前端环境变量 (frontend/.env)
这是最容易出错的地方！很多用户部署后前端报 404，就是因为忽略了这一步。

# frontend/.env
NEXT_PUBLIC_BACKEND_BASE_URL="http://localhost:8001"
NEXT_PUBLIC_LANGGRAPH_BASE_URL="http://localhost:2024"

原理：Next.js 在构建时会将 NEXT_PUBLIC_ 开头的变量注入到客户端代码中。如果不配置，前端代码不知道去哪里请求后端 API。

5. 修复 Python 依赖缺失
官方文档可能未及时更新依赖列表。根据实战经验，langchain-anthropic 常被遗漏。
编辑 backend/pyproject.toml：

[project]
dependencies = [
 # ... 其他依赖
 "langchain-anthropic>=0.3.0", # 手动添加此行
 # ...
]

3.3 安装依赖与启动服务

1. 后端依赖 (使用 uv)

cd backend
uv sync

观察：uv 会自动创建虚拟环境 (.venv) 并安装依赖。速度极快，通常只需几秒。

2. 前端依赖

cd ../frontend
pnpm install

3. 三窗口启动法
我们需要同时运行三个服务。打开三个独立的 PowerShell 窗口。

• 窗口 1 (编排引擎):

cd backend
uv run langgraph dev --no-browser --allow-blocking --host 0.0.0.0 --port 2024

注意：--allow-blocking 允许同步工具执行，本地调试必备。

• 窗口 2 (API 网关):

cd backend
uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001

• 窗口 3 (前端界面):

cd frontend
pnpm run dev

启动成功后，访问 http://localhost:3000。如果看到界面且无报错，恭喜部署成功。

4. 原理深挖：黑盒之下发生了什么

当你在前端点击'发送'按钮后，系统内部发生了什么？理解这一链路有助于你排查复杂问题。

4.1 请求生命周期时序图

4.2 状态管理核心 (LangGraph State)

与传统 HTTP 请求'无状态'不同，Agent 对话是有状态的。LangGraph 在内存（或配置的文件）中维护了一个 State Object。

• 消息累积：每次对话，messages 列表会追加新的 Human 和 AI 消息。
• 持久化：配置中的 memory.json 用于在服務重启后保留部分上下文。
• 截断机制：配置中的 summarization 部分定义了当 Token 超过 15564 时，自动触发摘要任务，压缩历史记忆。这是防止 Context 溢出导致报错的关键机制。

4.3 沙箱隔离原理

配置中的 sandbox: use: src.sandbox.local:LocalSandboxProvider 决定了文件操作的范围。

• 本地模式：直接操作宿主机的指定目录。
• 风险：bash_tool 允许执行系统命令。在生产环境，务必限制其权限或切换到 Docker 沙箱模式，防止 rm -rf 悲剧。

5. 避坑指南：生产环境的血泪教训

在部署过程中，我整理了几个高频'坑点'，这些往往不会出现在官方文档的显眼位置。

坑点 1：uv 命令识别失败

• 现象：输入 uv 提示 "not recognized"。
• 原因：Windows 环境变量刷新延迟，或者安装脚本未正确写入 User Path。
• 解决：
  1. 检查 %USERPROFILE%\.local\bin 是否存在 uv.exe。
  2. 手动将该路径加入系统环境变量。
  3. 必须重启终端，甚至重启电脑以确保生效。

坑点 2：前端 404 连环爆

• 现象：页面能打开，但控制台全是 POST /api/models 404。
• 原因：frontend/.env 未配置或配置错误。Next.js 读取环境变量是在启动时完成的，修改 .env 后必须重启前端服务。
• 解决：
  1. 确认 frontend/.env 存在且内容正确（无多余空格）。
  2. 停止前端服务 (Ctrl+C)。
  3. 重新运行 pnpm run dev。
  4. 浏览器硬刷新 (Ctrl+Shift+R)。

坑点 3：端口占用冲突

• 现象：启动服务时报 Error: Address already in use。
• 原因：上次服务未正常退出，僵尸进程占用了 3000/8001/2024 端口。
• 解决：

# 查找进程
netstat -ano | findstr :8001
# 假设 PID 为 12345
taskkill /PID 12345 /F

建议：养成使用 Ctrl+C 正常停止服务的习惯，避免直接关闭窗口。

坑点 4：YAML 缩进错误

• 现象：后端启动报错 yaml.scanner.ScannerError。
• 原因：config.yaml 中混用了 Tab 和空格，或缩进层级不对。
• 解决：使用 VS Code 打开，开启'显示空白字符'，确保全部使用 2 空格 缩进。YAML 对 Tab 零容忍。

坑点 5：模型导入错误

• 现象：ModuleNotFoundError: No module named 'langchain_anthropic'。
• 原因：pyproject.toml 漏配依赖，或 uv sync 未成功执行。
• 解决：
  1. 确认 pyproject.toml 已添加依赖。
  2. 删除 backend/.venv 文件夹。
  3. 重新运行 uv sync 强制重建环境。

6. 总结与建议

部署 DeerFlow 不仅是一次环境配置，更是对现代 AI 应用架构的一次完整演练。我们验证了 Node.js 与 Python 混合栈的可行性，实践了 LangGraph 的状态编排，并解决了 Windows 下的特定兼容性问题。

核心要点回顾：

• 环境基石：Node 22 + Python 3.12 + uv 是性能与兼容性的最佳平衡。
• 配置关键：前端 .env 的后端地址配置是连通性的命门。
• 依赖管理：uv sync 比 pip 更可靠，注意检查 pyproject.toml 的完整性。
• 服务 orchestration：三个服务（Frontend, Gateway, LangGraph）需独立运行，端口不可冲突。

针对不同团队的建议：

• 个人开发者：直接使用本文的本地部署方案，调试最快，隐私最好。
• 中小企业：建议将后端服务（Gateway + LangGraph）部署到内部 Linux 服务器，前端可本地或托管，通过 HTTPS 通信。
• 大型组织：需改造状态存储模块，接入企业级数据库，并集成 SSO 鉴权，不可直接使用默认配置。

AI Agent 的本地化部署是未来的趋势。掌握这套流程，意味着你拥有了构建私有化智能助理的基础能力。现在，打开你的 PowerShell，开始构建你的第一个本地 Agent 吧。