DeerFlow从零跑通只需15分钟：深度研究Agent完整部署实战

DeerFlow从零跑通只需15分钟：深度研究Agent完整部署实战

【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow

DeerFlow 是一个开源的深度研究 Agent（SuperAgent harness）：你给它一个研究任务，它会自己拆解计划、调度子 Agent、检索网页、写代码、跑沙箱，最后交出一份带图表的报告。基于 LangGraph 构建，技能、记忆、沙箱开箱即用。这篇指南带你完成 DeerFlow 从零安装、本地启动到长期运行的完整部署。三条路线：本地试玩、容器化、上生产，照着做就能跑起来。

上面这张图就是 Agent 在研究任务中自动生成的分析图表，跑通后你可以直观感受它的产出深度。

前置自检与项目安装：5个工具搞定

先装齐5个工具

DeerFlow 的运行时依赖不多，但一个都不能少：

• Python 3.12 及以上
• Node.js 22 及以上
• uv（Python 依赖管理器，速度快）
• pnpm（前端依赖管理器）
• nginx（本地开发的统一入口）

逐个确认版本：

python3 --version node --version uv --version pnpm --version

缺哪个装哪个即可。装完不用自己核对，克隆后跑make check，项目会替你把所有前置项查一遍，缺什么直接列出来。

克隆仓库，跑一遍设置向导

git clone https://gitcode.com/GitHub_Trending/de/deer-flow cd deer-flow make setup

make setup是个交互式向导，大约 2 分钟。它带你选 LLM 提供商、填 API 密钥、决定要不要网页搜索、选沙箱模式。结束时它替你生成config.yaml，并把密钥写进.env——整个配置就这两个文件。

想自己动手也行：跑make config生成模板，再照着仓库里的config.example.yaml改。完整字段（多模型、子 Agent 上限、追踪等）都以那份示例文件为准，这里不展开。

三种启动方式：本地开发、Docker、生产构建

路线A：本地开发，最透明

make install # 一次性装齐前后端依赖 make dev # 带热更新启动全部服务

启动后浏览器打开http://localhost:2026。内部其实跑了三个服务：前端 3000、Gateway 8001、nginx 入口 2026。你只需要记住 2026 这个统一入口，其他不用管。

路线B：Docker 开发，最省心

有 Docker 就优先走这条，官方默认推荐。两条命令：

make docker-init # 拉取沙箱镜像，只需一次 make docker-start # 启动全部服务

docker-start会自动读config.yaml判断该用哪种沙箱模式。看日志用make docker-logs。如果机器访问默认依赖源慢，在 init 之前把UV_INDEX_URL和NPM_REGISTRY指到可用镜像即可。

路线C：生产构建，给长期运行的机器

make up # 构建镜像并启动生产环境 make down # 停止并移除容器

make up会等 Gateway 的/health变绿才宣告成功；窗口期内起不来就直接报错退出，并打印容器状态和最近的 Gateway 日志。不会出现"看起来启动了，其实半残"的情况。

验证启动：30秒确认一切正常

打开页面，发一条真实任务

访问http://localhost:2026，登录，发一个你熟悉的研究任务。第一次运行会慢一些，因为沙箱在初始化；第二次起就快了。看它是不是真的在检索、在写代码、在出报告。

一条命令戳健康端点

curl -s http://localhost:8001/health

返回 JSON 就说明 Gateway 活着。2026 是 nginx 统一入口，8001 是 Gateway API 本体，两个都能通才算完全健康。

让 doctor 做全面体检

make doctor

它会检查配置、密钥、前置依赖，有问题会直接给出可执行的修复提示，而不是甩一段报错。之后如果要提交 issue，先跑make support-bundle，它会打包一份脱敏的诊断文件，维护者一眼就能看懂。

启动报错排查：三个高频坑

密钥没配或配错

症状：页面能打开，但发任务没反应，日志里出现认证类错误。先确认config.yaml的models段至少有一条模型配置，且api_key指向的环境变量（比如$OPENAI_API_KEY）里确实有值。密钥这类敏感值向导只会写进.env，不会替你填假值。

Linux 上 docker.sock 拒绝连接

报错里带着permission denied ... docker.sock，基本就是当前用户没有 Docker 权限。把用户加进 docker 组，重新登录后重试：

sudo usermod -aG docker $USER

端口被占用

本地服务的端口是固定的：3000、8001、2026。根目录.env里的PORT只影响 Docker 对外发布的入口，改它救不了本地模式。2026 被占就先释放占用进程，或者调整 nginx 配置，别在无关变量上浪费时间。

生产加固：长期运行前做三件事

数据别留在内存里

持久化部署把database.backend设为sqlite或postgres。这一个配置同时管检查点、LangGraph Store 和应用数据，三处共用。另外建议顺手开启token_budget，给单次运行设 token 硬上限，防止一个失控任务烧穿 API 账单。

多副本前先配齐依赖

Gateway 默认单 worker（GATEWAY_WORKERS=1）。想水平扩展，需要 Postgres、Redis 流桥（stream_bridge.type: redis）和租约心跳三者齐活——进程内的内存事件存储没法跨进程保证任务唯一投递。资源上建议 8 vCPU / 16 GB 起步，CPU 或内存长期打满时，先降并发再谈扩容。

把安全边界守住

公共部署里，Gateway 的管理员权限约等于代码执行权限，别裸奔暴露到公网。外层套 HTTPS，开启登录鉴权，代理场景下注意让外层代理清洗转发头。

下一步：启动后先做这几件事

1. 先跑一个你熟悉领域的研究任务，检查产出报告，确认整条链路通
2. 有本地模型的话，把config.yaml的模型换成 vLLM 指向的本地端点，体验零成本调用
3. 想深入技能（skills）、子 Agent、MCP、IM 通道、链路追踪这些能力，去读仓库根目录的README.md和backend/docs/ARCHITECTURE.md

这份指南只负责把你带到"跑通"这一步。往后的定制空间，全在上面的完整文档里。

【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow