本地 AI Agent 平台 DeerFlow Windows 部署与架构解析
介绍在 Windows 环境下本地部署 DeerFlow AI Agent 平台的完整流程。涵盖前后端分离架构设计(Next.js + FastAPI + LangGraph),环境配置(Node.js 22, Python uv),以及依赖管理和服务启动步骤。同时深入解析状态管理机制、沙箱隔离原理,并提供端口冲突、环境变量配置等常见问题的解决方案,适合希望构建私有化智能助理的开发者参考。

介绍在 Windows 环境下本地部署 DeerFlow AI Agent 平台的完整流程。涵盖前后端分离架构设计(Next.js + FastAPI + LangGraph),环境配置(Node.js 22, Python uv),以及依赖管理和服务启动步骤。同时深入解析状态管理机制、沙箱隔离原理,并提供端口冲突、环境变量配置等常见问题的解决方案,适合希望构建私有化智能助理的开发者参考。


在大模型应用爆发的今天,大多数开发者习惯了调用云端 API 快速构建 Demo。但当项目从'玩具'走向'生产',尤其是涉及企业敏感数据、复杂任务编排或需要极致低延迟的场景时,云端 SaaS 方案的局限性就暴露无遗。
你是否遇到过以下场景:
这就是为什么我们需要 DeerFlow 这样的本地化 AI Agent 编排平台。它不仅仅是一个'可部署的项目',更是一套完整的 Agent 操作系统。
然而,在 Windows 环境下部署这样一个 polyglot(多语言混合)架构并非易事。Node.js 22 的新特性、Python uv 包管理器的引入、LangGraph 的状态机机制,以及前端与后端服务的通信链路,每一个环节都可能成为'拦路虎'。
本文基于 DeerFlow 的 Windows 部署实践,拆解其背后的架构设计逻辑,分享在混合技术栈下的环境治理经验,并深入探讨 LangGraph 在本地运行时的状态管理原理。无论你是想快速搭建私有化 Agent 平台,还是想学习现代 AI 应用的全栈架构,这篇文章都将提供可落地的解决方案。
在动手敲命令之前,我们必须先看清'全景图'。DeerFlow 的本地架构采用了经典的 前后端分离 + 服务网格化 设计。这种设计并非过度工程,而是为了解耦 AI 推理、业务逻辑与用户交互。

为什么是这套组合拳?我们来看技术选型对比:
组件 | 选型方案 | 替代方案 | 选型理由 (Why) | 潜在风险 (When Not) |
前端框架 | Next.js 16 (Turbopack) | Vite + React | 服务端渲染能力更强,适合 SEO 及复杂状态管理;Turbopack 构建速度极快。 | 若仅需纯静态后台,Next.js 略显厚重。 |
包管理 (JS) | pnpm | npm/yarn | 硬链接机制节省磁盘空间,依赖安装速度极快,避免依赖地狱。 | 旧项目若锁定 yarn.lock 需迁移。 |
包管理 (Py) | uv | pip/poetry | 关键选型。Rust 编写,速度比 pip 快 10-100 倍,自动管理 Python 版本。 | 团队若未普及 uv 需额外安装步骤。 |
Agent 编排 | LangGraph | LangChain Chains | 支持循环、状态持久化、多 Agent 协作,更适合复杂任务流。 | 简单线性任务用 LangChain Chains 更轻量。 |
API 网关 | FastAPI | Flask/Django | 原生异步支持,性能极高,自动生成 Swagger 文档。 | 同步阻塞任务多时优势不明显。 |
操作系统 | Windows 10/11 | Linux/Mac | 企业办公主流环境,兼容性挑战大但需求最迫切。 | 生产环境建议迁移至 Linux 容器。 |
以下操作基于 Windows 11 环境。请确保你拥有管理员权限,以避免某些路径写入失败。
很多部署失败源于基础环境版本不对。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 的环境变量刷新机制。
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
验证:
uv --version # 预期:uv 0.10.7+
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 # 关键:指定 LangChain 适配器 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 # 谨慎开启 bash 工具
专家提示: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", # 手动添加此行
# ...
]
1. 后端依赖 (使用 uv)
cd backend uv sync
观察:uv 会自动创建虚拟环境 (.venv) 并安装依赖。速度极快,通常只需几秒。
2. 前端依赖
cd ../frontend pnpm install
3. 三窗口启动法
我们需要同时运行三个服务。打开三个独立的 PowerShell 窗口。
cd backend uv run langgraph dev --no-browser --allow-blocking --host 0.0.0.0 --port 2024
注意:--allow-blocking 允许同步工具执行,本地调试必备。
cd backend uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001
cd frontend pnpm run dev
启动成功后,访问 http://localhost:3000。如果看到界面且无报错,部署成功。
当你在前端点击'发送'按钮后,系统内部发生了什么?理解这一链路有助于你排查复杂问题。

与传统 HTTP 请求'无状态'不同,Agent 对话是有状态的。LangGraph 在内存(或配置的文件)中维护了一个 State Object。
messages 列表会追加新的 Human 和 AI 消息。memory.json 用于在服務重启后保留部分上下文。summarization 部分定义了当 Token 超过 15564 时,自动触发摘要任务,压缩历史记忆。这是防止 Context 溢出导致报错的关键机制。配置中的 sandbox: use: src.sandbox.local:LocalSandboxProvider 决定了文件操作的范围。
bash_tool 允许执行系统命令。在生产环境,务必限制其权限或切换到 Docker 沙箱模式,防止 rm -rf 悲剧。在部署过程中,我整理了几个高频'坑点',这些往往不会出现在官方文档的显眼位置。
uv 提示 "not recognized"。%USERPROFILE%\.local\bin 是否存在 uv.exe。POST /api/models 404。frontend/.env 未配置或配置错误。Next.js 读取环境变量是在启动时完成的,修改 .env 后必须重启前端服务。frontend/.env 存在且内容正确(无多余空格)。pnpm run dev。Error: Address already in use。# 查找进程 netstat -ano | findstr :8001 # 假设 PID 为 12345 taskkill /PID 12345 /F
建议:养成使用 Ctrl+C 正常停止服务的习惯,避免直接关闭窗口。
yaml.scanner.ScannerError。config.yaml 中混用了 Tab 和空格,或缩进层级不对。ModuleNotFoundError: No module named 'langchain_anthropic'。pyproject.toml 漏配依赖,或 uv sync 未成功执行。pyproject.toml 已添加依赖。backend/.venv 文件夹。uv sync 强制重建环境。部署 DeerFlow 不仅是一次环境配置,更是对现代 AI 应用架构的一次完整演练。我们验证了 Node.js 与 Python 混合栈的可行性,实践了 LangGraph 的状态编排,并解决了 Windows 下的特定兼容性问题。
核心要点回顾:
.env 的后端地址配置是连通性的命门。uv sync 比 pip 更可靠,注意检查 pyproject.toml 的完整性。针对不同团队的建议:
AI Agent 的本地化部署是未来的趋势。掌握这套流程,意味着你拥有了构建私有化智能助理的基础能力。开始构建你的第一个本地 Agent。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online