最近在折腾AI工作流编排的时候我盯上了一个叫deer-flow的开源项目。老实说市面上的工作流引擎我基本都摸过一轮要么太重要么对开发者不够友好部署起来能折腾掉半天。deer-flow 给我的第一感觉就是“轻”但轻并不代表弱它的定位非常精准本地优先、开发者友好、可视化和代码双模驱动的 Agent 工作流编排引擎。这篇文章我打算把这几周的实际使用心得完整记录下来从项目定位、核心架构拆解到具体部署和建流实操再到我踩过的坑和排查思路一次性聊透。不管你是刚开始接触工作流编排的新手还是已经在用 n8n、Dify 这类工具想换个更轻量方案的开发者这篇都能给你一些参考。1. 项目概述与整体设计思路1.1 为什么需要 deer-flow 这类工具先聊一个可能很多人都困惑的问题有了 n8n、Dify、Coze 这些成熟产品为什么还要折腾 deer-flow我的理解是工具链的分化本质上是需求的分化。像 Coze 这种平台型产品什么都给你配好了拖拖拽拽就能出一个聊天机器人但你永远受制于平台的规则想深度定制自己的逻辑就非常痛苦。n8n 功能很全但节点重、模板多跑起来内存占用不小而且它更偏传统业务流程自动化对 AI Agent 的原生支持虽然一直在补总感觉差一口气。deer-flow 走的是另一条路线它把“工作流”和“Agent”这两件事揉在了一起但揉得很克制。核心引擎非常轻量跑一个 Docker 容器内存占用在几百兆以内启动秒级完成。同时它给了开发者两种操作界面一个可视化画布适合快速搭原型、看全局一套 YAML 格式的流程描述文件适合放进 Git 里做版本管理跟代码一起走 CI/CD。这个设计我太喜欢了因为在真实项目里工作流的版本管理往往比工作流本身更让人头疼。另外它在设计上默认了本地优先。数据不出内网模型可以配本地部署的 Ollama 或者 vLLM 服务也可以接各种云厂商的 API。对于有数据合规要求的场景这一点能直接劝退一批人从云端平台迁过来。1.2 核心特征与适用场景我用了一段时间后把 deer-flow 的核心特征归纳成下面这几点轻量级运行时单容器即可运行依赖很少内存占用低适合部署在低配服务器甚至开发机上。可视化和代码双模画布拖拽 YAML 源码编辑同步更新两种方式随时切换。Agent 原生支持可以把大模型调用作为一等公民节点来编排而不是靠 HTTP 请求硬凑。自定义节点扩展支持用 Python 或 TypeScript 写自定义节点加载即用。执行历史可回溯每次运行都有完整日志和中间产物记录排查问题很方便。适用场景我最推荐三类企业内部的数据处理流水线、个人知识库自动整理工具、以及需要对接大模型能力的业务流程自动化。如果你只是想快速搭一个带界面的聊天机器人其实没必要上 deer-flow但凡是涉及“多步骤处理、有分支判断、要接外部工具”的 AI 自动化任务它的优势就会非常明显。1.3 架构解构deer-flow 是怎么工作的从架构层面看deer-flow 可以分为四个核心层级触发层负责接收外部事件包括 Webhook、定时任务、手动触发、消息队列消息等相当于工作流的“入口”。引擎层核心编排引擎负责解析 DAG有向无环图调度节点执行顺序处理数据流转和分支逻辑。这一层是纯代码实现的所以执行效率很高。执行层具体的节点执行器包括 LLM 调用节点、代码执行节点、HTTP 请求节点、条件判断节点等。集成层提供对外集成能力包括 REST API、Webhook 输出、数据库连接器等。这个分层的好处是每一层都可以独立扩展。比如你把引擎层跑在一个高性能服务器上节点执行器可以分布式部署到其他机器上通过内部消息队列通信。对于大部分中小项目单机部署就完全够用了。2. 核心细节解析与实操要点2.1 节点类型详解deer-flow 的节点类型设计得比较克制但每个都有明确的用途。我用过一圈之后把常用节点分成了四类第一类是触发器节点。它有定时触发器cron 表达式、Webhook 触发器、手动触发器和事件触发器。定时触发器适合做周期性的数据抓取、报表生成Webhook 触发器适合接外部系统的回调通知比如 GitHub push 事件或者支付回调。第二类是逻辑处理节点。条件判断if/else、合并分支、循环遍历、延迟等待、错误处理等等。这些节点是工作流的骨架决定了流程会往哪个方向走。deer-flow 的条件判断节点比较直观可以直接在画布上配置“字段值满足什么条件就走哪条边”不用写代码。第三类是 AI 能力节点。这是 deer-flow 区别于传统工作流引擎的核心部分。包括 LLM 调用节点可以选任意兼容 OpenAI 协议的服务、Prompt 模板节点、向量化节点Embedding、知识库检索节点。LLM 调用节点里可以直接配置模型名称、temperature、max_tokens 等参数也可以在输入框中引用上游节点的输出字段。第四类是工具和集成节点。HTTP 请求节点支持 GET/POST/PUT/DELETE 及自定义 Header、代码执行节点Python/TypeScript 沙箱、数据库查询节点。HTTP 节点可以拼接动态 URL也可以把上游节点的 JSON 输出直接作为请求体传递给下游系统。2.2 配置管理与数据传递机制deer-flow 的工作流描述文件用的是 YAML 格式整体结构很清爽。一个工作流的基本结构包含工作流元信息、变量定义、节点列表和连线关系。YAML 手写起来也没有想象中那么复杂下面是一个极简的示例id: demo_workflow name: 演示工作流 description: 一个简单的 LLM 调用示例 trigger: type: webhook path: /demo variables: - name: user_question type: string required: true nodes: - id: node_prompt type: prompt_template template: | 请回答下面这个问题要求使用简洁的语言。 问题{{ user_question }} - id: node_llm type: llm provider: openai-compatible model: gpt-4o-mini prompt: ${node_prompt.output} config: temperature: 0.7 max_tokens: 1024 - id: node_output type: http_response status_code: 200 data: ${node_llm.output} edges: - from: node_prompt to: node_llm - from: node_llm to: node_output这里有一个很重要的概念是edge连线它定义了节点之间的依赖关系。deer-flow 的 DAG 调度器会按照连线方向自动推导执行顺序如果某个节点没有依赖可以并行执行。变量引用通过${node_id.output}的模板语法完成这相当于把数据流和控制器解耦了非常直观。2.3 可视化画布操作要点虽然 YAML 已经够好用但我日常建流还是习惯先在画布上拖一遍看流程全貌然后导出 YAML 做精细调整。画布操作上有几个小技巧值得分享画布右上角有个“导出 YAML”按钮搭好流程之后导出把 YAML 提交到 Git 仓库形成版本基线。后续任何改动都要过 Git 审查这比我之前用的某些平台纯黑盒的操作方式要踏实得多。连线时注意数据流向。画布上每条连线都可以在属性面板里配置“条件标签”相当于给边加了一个守卫条件。这样就不用在中间塞一个巨大的条件判断节点去拆分支了画布看起来更简洁。比如 LLM 节点输出的success字段为 false 时走错误分支连线上直接写condition: ${node_llm.output.success} ! true就行。我习惯把公共的子流程封装成“子工作流”节点。在 deer-flow 里一个工作流可以作为另一个工作流的子步骤被调用父工作流只需要传参与接收结果。这个机制非常适合抽取公共逻辑我通常会把“调用 LLM 并解析 JSON 结果”这种反复出现的操作封装成子工作流。3. 实操过程与核心环节实现3.1 环境准备与快速部署deer-flow 官方推荐用 Docker 部署一条命令就能拉起来docker run -d --name deer-flow \ -p 8080:8080 \ -v ./deerflow-data:/app/data \ -e DEER_FLOW_MODEdev \ deer-flow/deer-flow:latest这里做了几个关键配置-p 8080:8080把容器的 8080 端口映射到宿主机这是 Web 控制台的端口-v挂载了数据目录所有工作流定义、执行日志和内置 SQLite 数据库都会存在宿主机上升级容器版本不用怕丢数据DEER_FLOW_MODEdev开启开发模式后面调试方便可以热加载节点代码。如果你需要更完整的配置我建议直接使用 Docker Compose 方式version: 3 services: deer-flow: image: deer-flow/deer-flow:latest container_name: deer-flow ports: - 8080:8080 volumes: - ./deerflow-data:/app/data - ./custom-nodes:/app/custom-nodes environment: - DEER_FLOW_MODEdev - TZAsia/Shanghai restart: unless-stopped这里多挂载了一个./custom-nodes目录用来放自定义节点。启动完成后浏览器打开http://localhost:8080就能看到控制台了。第一次登录会让你创建一个管理员账号创建完默认进入空白的项目首页。3.2 第一个工作流Webhook 接收 → LLM 处理 → 返回结果我拿一个最常见的场景来演示外部系统通过 Webhook 发来一个问题deer-flow 调用大模型生成回答然后把结果返回给调用方。先在控制台左侧菜单点“新建工作流”命名webhook-to-llm。工作流创建后会自动生成一个 Webhook 触发器节点点击节点右侧属性面板会看到这个工作流专属的 Webhook 地址。我直接复制这个地址先用 curl 测试一下连通性curl -X POST https://your-domain/api/webhook/demo_workflow \ -H Content-Type: application/json \ -d {user_question:介绍下什么是 DAG}返回会是一个默认响应说明 Webhook 已经通到引擎了。然后我分别从左侧面板拖入一个“Prompt 模板”节点、一个“LLM 调用”节点和一个“HTTP 响应”节点。三者连线顺序是 Webhook → Prompt 模板 → LLM 调用 → HTTP 响应。在 Prompt 模板节点里输入模板内容并把变量引用接到 Webhook 请求体的user_question字段上$(trigger.body.user_question)这样请求进来时deer-flow 会自动把 HTTP 请求的 JSON body 填充到变量里。LLM 节点里选择 OpenAI 兼容协议填 base URL 和 API Key模型可以填gpt-4o-mini。如果用的是本地 Ollama也可以填http://host.docker.internal:11434/v1加模型名qwen2.5:7b之类。点击右上角的“运行测试”按钮填入一个模拟请求体能看到每一步节点的执行时间、输入输出摘要。这一步调试起来非常直观哪一步慢、哪一步报错都一目了然。3.3 定时触发场景每天抓取数据并推送给模型分析建一个每天自动运行的定时工作流。新建工作流daily-report这次触发器选“定时触发”配置 cron 表达式0 8 * * *意思是每天早上 8 点执行。然后是 HTTP 请求节点从内部系统拉取前一天的运营数据。HTTP 节点配置如下method: GET url: https://internal-api.example.com/stats?date$(YESTERDAY) headers: Authorization: Bearer $(env.API_TOKEN)这里的$(env.API_TOKEN)引用的是环境变量可以在工作流的变量配置里设置。拿到数据之后接一个 Prompt 模板节点让模型按指定格式生成日报摘要最后接“Webhook 发送”节点把结果 POST 到企业微信/钉钉/飞书的机器人地址上。定时任务跑起来之后我在控制台的“执行历史”页面可以看到每天的执行记录。如果某天数据源刚好返回空列表模型生成的日报就会是“暂无数据”这种问题我一般通过在 HTTP 请求之后加一个条件判断节点来规避如果返回内容为空就改走一个“跳过生成直接发送默认文本”的分支。3.4 自定义节点开发一个 Python 节点示例内置节点不够用时就得自己写扩展了。deer-flow 的自定义节点开发起来门槛很低我去custom-nodes目录下新建一个 Python 文件内容如下from deer_flow import BaseNode, Field class UuidGenerateNode(BaseNode): name uuid_generate display_name UUID 生成器 description 生成一个随机 UUID方便做消息关联 inputs { prefix: Field(str, defaultmsg, description前缀) } outputs { uuid: Field(str, description生成的 UUID), full_id: Field(str, description带前缀的完整 ID) } def run(self, node_inputs, context): import uuid prefix node_inputs.get(prefix, msg) uid str(uuid.uuid4()) return { uuid: uid, full_id: f{prefix}-{uid} }把文件保存到挂载目录后刷新控制台左侧面板就能看到“UUID 生成器”这个节点了。如果没出现多半是控制台没感知到文件变化我一般直接重启容器简单粗暴有效docker restart deer-flow自定义节点能访问context对象里面包含当前工作流的执行 ID、触发时间、所有上游节点输出等全局信息在写复杂逻辑时很有用。比如想在节点里记录日志直接调用内置 logger 就行日志会滚动到执行历史里方便排查。4. 常见问题与排查技巧实录4.1 典型问题速查表用了一段时间后我把遇到的典型问题汇总成了一张表方便以后对照排查现象可能原因解决方式Webhook 请求超时LLM 节点配置的 API 地址不可达检查模型服务连通性curl 测试一次节点执行成功但没有输出变量引用路径写错核对${node_id.output}中的 node_id定时任务没触发cron 时区不对检查容器内 TZ 环境变量和 cron 表达式导入 YAML 报错连线指向不存在的节点 ID比对 YAML 里的 id 和 edges 引用自定义节点不显示文件未挂载或被语法错误阻断重启容器查看容器日志数据量大的流程很慢出现了不必要的串行依赖检查连线把独立的节点拆成并行分支4.2 现场踩坑记录变量引用与类型转换最坑的一次是写 HTTP 请求节点时上游 LLM 返回的 JSON 字段在模板中总是取不到值。折腾了半天最后发现是output字段本身是字符串LLM 返回的 JSON 被当成纯文本塞进去了要在下游解析 JSON 才能用字段内容。deer-flow 的 LLM 节点默认把完整响应作为一个 JSON 字符串放在output字段里。如果你需要结构化数据不能直接$(node_llm.output.field_name)而是要先接一个“代码执行”节点解析import json data json.loads(node_output) result { status: data.get(status, unknown), summary: data.get(summary, ) }处理好之后返回给下游的才是干净的结构化数据。这种“JSON in, JSON out”的习惯在编排复杂任务时非常重要尽量避免让数据在节点之间以非结构化的形态流转。4.3 性能调优与依赖管理deer-flow 的单机性能上限取决于节点类型。纯逻辑节点和 HTTP 调用节点速度很快瓶颈主要在大模型调用上。我实测下来只要不是几十个节点的大型图单机默认配置完全够用。用得久了有几个调优心得并行别浪费。工作流中互相没有依赖关系的节点deer-flow 会并行执行。我建流的时候会刻意调整节点切成多个独立分支特别是“同时查三个数据源”这种场景串行要等三倍时间并行一次就拿到全部结果。控制日志级别。开发模式下每个节点都会打印输入输出摘要方便是方便但跑长期定时任务时日志文件会快速增长。我一般生产环境把DEER_FLOW_MODE设为prod日志只保留 error 级别。模型参数要控制住。如果有多个节点调用同一个模型尽量在模型服务端做限流和排队不然 API 配额很容易被打爆排查起来还特麻烦。5. 进阶玩法与扩展场景5.1 用子工作流搭建复用模块项目做大以后工作流数量会迅速增长。这时候我会把公共逻辑抽成子工作流然后在主流程里调用。比如公司内部所有流程都要走一个“身份校验 权限判断”的公共模块就可以抽成一个auth-check子工作流其他流程里引用它即可。子工作流的调用节点长得跟普通节点类似但属性面板里可以选择“子工作流”并指定要调用哪个已发布的工作流版本。输入参数和输出参数都能映射。这个机制能大幅降低重复节点堆叠带来的维护成本改动一次公共逻辑所以依赖它的流程全部生效。5.2 多 Agent 协作场景deer-flow 虽然不是一个完整的 Agent 框架但它的图编排能力完全可以支撑简单的多 Agent 协作。我搭过一版“主管-专员”模式的流程主管节点先接收用户任务做任务拆解把拆解后的子任务分别派发给几个专员 Agent 节点每个专员负责一类能力如搜索资料、写代码、做总结全部完成后汇总到主管节点做最终整合。这种实现方式本质上就是利用工作流的图结构天然支持的这种 fork-join 模式。开发时把每个专员都做成子工作流方便单独测试和替换。比如搜资料专员内部用的是某搜索 API如果 API 涨价要换只需要改动这个子工作流内部实现不影响主流程编排。5.3 将 deer-flow 嵌入现有系统API 集成模式最后一个很常见的诉求是如何把工作流能力嵌入到公司现有系统里而不是每次都在控制台手动操作。deer-flow 提供了完整的 REST API可以创建、更新、运行工作流也能查询执行状态。我在实践中通常是业务系统后端收到用户请求后调用 deer-flow 的“运行工作流”API 把任务交给引擎异步执行然后轮询查询执行结果。通过 Webhook 把流程结果推回给业务系统避免业务系统阻塞等待。整体调用链路很干净deer-flow 在这里的角色更像一个“AI 中间层”把各种模型和工具能力编排成一套标准化的接口服务。6. 一些题外话与个人心得聊完技术最后说点我个人在使用了这段日子之后更真实的感受。deer-flow 并不完美。它目前的生态还在早期官方文档有些地方写得比较简略社区模板也不算丰富离 n8n 那种庞大的集成库还有距离。但它的定位很准踩中了“想自由编排 AI 工作流又不想被云平台绑死”这块需求。对我来说工具链最终的考验永远不是功能多不多而是在真实业务里跑得稳不稳、能不能塞进现有的研发流程里。deer-flow 的数据文件是纯文本 YAML能进 Git能 review能回滚这一条就已经赢了很多同类工具。如果你在犹豫要不要上手我的建议是先跑一个最小的 Webhook 场景就 10 分钟的事。等你能画出第一条链路把真实业务里最繁琐的那个流程塞进去剩下的很多想法自然会浮现出来。 
长河君 · 2026/9/11 11:36:57 · 阅读 1.2k deer-flow：轻量级AI Agent工作流编排引擎部署与实战指南
最近在折腾AI工作流编排的时候我盯上了一个叫deer-flow的开源项目。老实说市面上的工作流引擎我基本都摸过一轮要么太重要么对开发者不够友好部署起来能折腾掉半天。deer-flow 给我的第一感觉就是“轻”但轻并不代表弱它的定位非常精准本地优先、开发者友好、可视化和代码双模驱动的 Agent 工作流编排引擎。这篇文章我打算把这几周的实际使用心得完整记录下来从项目定位、核心架构拆解到具体部署和建流实操再到我踩过的坑和排查思路一次性聊透。不管你是刚开始接触工作流编排的新手还是已经在用 n8n、Dify 这类工具想换个更轻量方案的开发者这篇都能给你一些参考。1. 项目概述与整体设计思路1.1 为什么需要 deer-flow 这类工具先聊一个可能很多人都困惑的问题有了 n8n、Dify、Coze 这些成熟产品为什么还要折腾 deer-flow我的理解是工具链的分化本质上是需求的分化。像 Coze 这种平台型产品什么都给你配好了拖拖拽拽就能出一个聊天机器人但你永远受制于平台的规则想深度定制自己的逻辑就非常痛苦。n8n 功能很全但节点重、模板多跑起来内存占用不小而且它更偏传统业务流程自动化对 AI Agent 的原生支持虽然一直在补总感觉差一口气。deer-flow 走的是另一条路线它把“工作流”和“Agent”这两件事揉在了一起但揉得很克制。核心引擎非常轻量跑一个 Docker 容器内存占用在几百兆以内启动秒级完成。同时它给了开发者两种操作界面一个可视化画布适合快速搭原型、看全局一套 YAML 格式的流程描述文件适合放进 Git 里做版本管理跟代码一起走 CI/CD。这个设计我太喜欢了因为在真实项目里工作流的版本管理往往比工作流本身更让人头疼。另外它在设计上默认了本地优先。数据不出内网模型可以配本地部署的 Ollama 或者 vLLM 服务也可以接各种云厂商的 API。对于有数据合规要求的场景这一点能直接劝退一批人从云端平台迁过来。1.2 核心特征与适用场景我用了一段时间后把 deer-flow 的核心特征归纳成下面这几点轻量级运行时单容器即可运行依赖很少内存占用低适合部署在低配服务器甚至开发机上。可视化和代码双模画布拖拽 YAML 源码编辑同步更新两种方式随时切换。Agent 原生支持可以把大模型调用作为一等公民节点来编排而不是靠 HTTP 请求硬凑。自定义节点扩展支持用 Python 或 TypeScript 写自定义节点加载即用。执行历史可回溯每次运行都有完整日志和中间产物记录排查问题很方便。适用场景我最推荐三类企业内部的数据处理流水线、个人知识库自动整理工具、以及需要对接大模型能力的业务流程自动化。如果你只是想快速搭一个带界面的聊天机器人其实没必要上 deer-flow但凡是涉及“多步骤处理、有分支判断、要接外部工具”的 AI 自动化任务它的优势就会非常明显。1.3 架构解构deer-flow 是怎么工作的从架构层面看deer-flow 可以分为四个核心层级触发层负责接收外部事件包括 Webhook、定时任务、手动触发、消息队列消息等相当于工作流的“入口”。引擎层核心编排引擎负责解析 DAG有向无环图调度节点执行顺序处理数据流转和分支逻辑。这一层是纯代码实现的所以执行效率很高。执行层具体的节点执行器包括 LLM 调用节点、代码执行节点、HTTP 请求节点、条件判断节点等。集成层提供对外集成能力包括 REST API、Webhook 输出、数据库连接器等。这个分层的好处是每一层都可以独立扩展。比如你把引擎层跑在一个高性能服务器上节点执行器可以分布式部署到其他机器上通过内部消息队列通信。对于大部分中小项目单机部署就完全够用了。2. 核心细节解析与实操要点2.1 节点类型详解deer-flow 的节点类型设计得比较克制但每个都有明确的用途。我用过一圈之后把常用节点分成了四类第一类是触发器节点。它有定时触发器cron 表达式、Webhook 触发器、手动触发器和事件触发器。定时触发器适合做周期性的数据抓取、报表生成Webhook 触发器适合接外部系统的回调通知比如 GitHub push 事件或者支付回调。第二类是逻辑处理节点。条件判断if/else、合并分支、循环遍历、延迟等待、错误处理等等。这些节点是工作流的骨架决定了流程会往哪个方向走。deer-flow 的条件判断节点比较直观可以直接在画布上配置“字段值满足什么条件就走哪条边”不用写代码。第三类是 AI 能力节点。这是 deer-flow 区别于传统工作流引擎的核心部分。包括 LLM 调用节点可以选任意兼容 OpenAI 协议的服务、Prompt 模板节点、向量化节点Embedding、知识库检索节点。LLM 调用节点里可以直接配置模型名称、temperature、max_tokens 等参数也可以在输入框中引用上游节点的输出字段。第四类是工具和集成节点。HTTP 请求节点支持 GET/POST/PUT/DELETE 及自定义 Header、代码执行节点Python/TypeScript 沙箱、数据库查询节点。HTTP 节点可以拼接动态 URL也可以把上游节点的 JSON 输出直接作为请求体传递给下游系统。2.2 配置管理与数据传递机制deer-flow 的工作流描述文件用的是 YAML 格式整体结构很清爽。一个工作流的基本结构包含工作流元信息、变量定义、节点列表和连线关系。YAML 手写起来也没有想象中那么复杂下面是一个极简的示例id: demo_workflow name: 演示工作流 description: 一个简单的 LLM 调用示例 trigger: type: webhook path: /demo variables: - name: user_question type: string required: true nodes: - id: node_prompt type: prompt_template template: | 请回答下面这个问题要求使用简洁的语言。 问题{{ user_question }} - id: node_llm type: llm provider: openai-compatible model: gpt-4o-mini prompt: ${node_prompt.output} config: temperature: 0.7 max_tokens: 1024 - id: node_output type: http_response status_code: 200 data: ${node_llm.output} edges: - from: node_prompt to: node_llm - from: node_llm to: node_output这里有一个很重要的概念是edge连线它定义了节点之间的依赖关系。deer-flow 的 DAG 调度器会按照连线方向自动推导执行顺序如果某个节点没有依赖可以并行执行。变量引用通过${node_id.output}的模板语法完成这相当于把数据流和控制器解耦了非常直观。2.3 可视化画布操作要点虽然 YAML 已经够好用但我日常建流还是习惯先在画布上拖一遍看流程全貌然后导出 YAML 做精细调整。画布操作上有几个小技巧值得分享画布右上角有个“导出 YAML”按钮搭好流程之后导出把 YAML 提交到 Git 仓库形成版本基线。后续任何改动都要过 Git 审查这比我之前用的某些平台纯黑盒的操作方式要踏实得多。连线时注意数据流向。画布上每条连线都可以在属性面板里配置“条件标签”相当于给边加了一个守卫条件。这样就不用在中间塞一个巨大的条件判断节点去拆分支了画布看起来更简洁。比如 LLM 节点输出的success字段为 false 时走错误分支连线上直接写condition: ${node_llm.output.success} ! true就行。我习惯把公共的子流程封装成“子工作流”节点。在 deer-flow 里一个工作流可以作为另一个工作流的子步骤被调用父工作流只需要传参与接收结果。这个机制非常适合抽取公共逻辑我通常会把“调用 LLM 并解析 JSON 结果”这种反复出现的操作封装成子工作流。3. 实操过程与核心环节实现3.1 环境准备与快速部署deer-flow 官方推荐用 Docker 部署一条命令就能拉起来docker run -d --name deer-flow \ -p 8080:8080 \ -v ./deerflow-data:/app/data \ -e DEER_FLOW_MODEdev \ deer-flow/deer-flow:latest这里做了几个关键配置-p 8080:8080把容器的 8080 端口映射到宿主机这是 Web 控制台的端口-v挂载了数据目录所有工作流定义、执行日志和内置 SQLite 数据库都会存在宿主机上升级容器版本不用怕丢数据DEER_FLOW_MODEdev开启开发模式后面调试方便可以热加载节点代码。如果你需要更完整的配置我建议直接使用 Docker Compose 方式version: 3 services: deer-flow: image: deer-flow/deer-flow:latest container_name: deer-flow ports: - 8080:8080 volumes: - ./deerflow-data:/app/data - ./custom-nodes:/app/custom-nodes environment: - DEER_FLOW_MODEdev - TZAsia/Shanghai restart: unless-stopped这里多挂载了一个./custom-nodes目录用来放自定义节点。启动完成后浏览器打开http://localhost:8080就能看到控制台了。第一次登录会让你创建一个管理员账号创建完默认进入空白的项目首页。3.2 第一个工作流Webhook 接收 → LLM 处理 → 返回结果我拿一个最常见的场景来演示外部系统通过 Webhook 发来一个问题deer-flow 调用大模型生成回答然后把结果返回给调用方。先在控制台左侧菜单点“新建工作流”命名webhook-to-llm。工作流创建后会自动生成一个 Webhook 触发器节点点击节点右侧属性面板会看到这个工作流专属的 Webhook 地址。我直接复制这个地址先用 curl 测试一下连通性curl -X POST https://your-domain/api/webhook/demo_workflow \ -H Content-Type: application/json \ -d {user_question:介绍下什么是 DAG}返回会是一个默认响应说明 Webhook 已经通到引擎了。然后我分别从左侧面板拖入一个“Prompt 模板”节点、一个“LLM 调用”节点和一个“HTTP 响应”节点。三者连线顺序是 Webhook → Prompt 模板 → LLM 调用 → HTTP 响应。在 Prompt 模板节点里输入模板内容并把变量引用接到 Webhook 请求体的user_question字段上$(trigger.body.user_question)这样请求进来时deer-flow 会自动把 HTTP 请求的 JSON body 填充到变量里。LLM 节点里选择 OpenAI 兼容协议填 base URL 和 API Key模型可以填gpt-4o-mini。如果用的是本地 Ollama也可以填http://host.docker.internal:11434/v1加模型名qwen2.5:7b之类。点击右上角的“运行测试”按钮填入一个模拟请求体能看到每一步节点的执行时间、输入输出摘要。这一步调试起来非常直观哪一步慢、哪一步报错都一目了然。3.3 定时触发场景每天抓取数据并推送给模型分析建一个每天自动运行的定时工作流。新建工作流daily-report这次触发器选“定时触发”配置 cron 表达式0 8 * * *意思是每天早上 8 点执行。然后是 HTTP 请求节点从内部系统拉取前一天的运营数据。HTTP 节点配置如下method: GET url: https://internal-api.example.com/stats?date$(YESTERDAY) headers: Authorization: Bearer $(env.API_TOKEN)这里的$(env.API_TOKEN)引用的是环境变量可以在工作流的变量配置里设置。拿到数据之后接一个 Prompt 模板节点让模型按指定格式生成日报摘要最后接“Webhook 发送”节点把结果 POST 到企业微信/钉钉/飞书的机器人地址上。定时任务跑起来之后我在控制台的“执行历史”页面可以看到每天的执行记录。如果某天数据源刚好返回空列表模型生成的日报就会是“暂无数据”这种问题我一般通过在 HTTP 请求之后加一个条件判断节点来规避如果返回内容为空就改走一个“跳过生成直接发送默认文本”的分支。3.4 自定义节点开发一个 Python 节点示例内置节点不够用时就得自己写扩展了。deer-flow 的自定义节点开发起来门槛很低我去custom-nodes目录下新建一个 Python 文件内容如下from deer_flow import BaseNode, Field class UuidGenerateNode(BaseNode): name uuid_generate display_name UUID 生成器 description 生成一个随机 UUID方便做消息关联 inputs { prefix: Field(str, defaultmsg, description前缀) } outputs { uuid: Field(str, description生成的 UUID), full_id: Field(str, description带前缀的完整 ID) } def run(self, node_inputs, context): import uuid prefix node_inputs.get(prefix, msg) uid str(uuid.uuid4()) return { uuid: uid, full_id: f{prefix}-{uid} }把文件保存到挂载目录后刷新控制台左侧面板就能看到“UUID 生成器”这个节点了。如果没出现多半是控制台没感知到文件变化我一般直接重启容器简单粗暴有效docker restart deer-flow自定义节点能访问context对象里面包含当前工作流的执行 ID、触发时间、所有上游节点输出等全局信息在写复杂逻辑时很有用。比如想在节点里记录日志直接调用内置 logger 就行日志会滚动到执行历史里方便排查。4. 常见问题与排查技巧实录4.1 典型问题速查表用了一段时间后我把遇到的典型问题汇总成了一张表方便以后对照排查现象可能原因解决方式Webhook 请求超时LLM 节点配置的 API 地址不可达检查模型服务连通性curl 测试一次节点执行成功但没有输出变量引用路径写错核对${node_id.output}中的 node_id定时任务没触发cron 时区不对检查容器内 TZ 环境变量和 cron 表达式导入 YAML 报错连线指向不存在的节点 ID比对 YAML 里的 id 和 edges 引用自定义节点不显示文件未挂载或被语法错误阻断重启容器查看容器日志数据量大的流程很慢出现了不必要的串行依赖检查连线把独立的节点拆成并行分支4.2 现场踩坑记录变量引用与类型转换最坑的一次是写 HTTP 请求节点时上游 LLM 返回的 JSON 字段在模板中总是取不到值。折腾了半天最后发现是output字段本身是字符串LLM 返回的 JSON 被当成纯文本塞进去了要在下游解析 JSON 才能用字段内容。deer-flow 的 LLM 节点默认把完整响应作为一个 JSON 字符串放在output字段里。如果你需要结构化数据不能直接$(node_llm.output.field_name)而是要先接一个“代码执行”节点解析import json data json.loads(node_output) result { status: data.get(status, unknown), summary: data.get(summary, ) }处理好之后返回给下游的才是干净的结构化数据。这种“JSON in, JSON out”的习惯在编排复杂任务时非常重要尽量避免让数据在节点之间以非结构化的形态流转。4.3 性能调优与依赖管理deer-flow 的单机性能上限取决于节点类型。纯逻辑节点和 HTTP 调用节点速度很快瓶颈主要在大模型调用上。我实测下来只要不是几十个节点的大型图单机默认配置完全够用。用得久了有几个调优心得并行别浪费。工作流中互相没有依赖关系的节点deer-flow 会并行执行。我建流的时候会刻意调整节点切成多个独立分支特别是“同时查三个数据源”这种场景串行要等三倍时间并行一次就拿到全部结果。控制日志级别。开发模式下每个节点都会打印输入输出摘要方便是方便但跑长期定时任务时日志文件会快速增长。我一般生产环境把DEER_FLOW_MODE设为prod日志只保留 error 级别。模型参数要控制住。如果有多个节点调用同一个模型尽量在模型服务端做限流和排队不然 API 配额很容易被打爆排查起来还特麻烦。5. 进阶玩法与扩展场景5.1 用子工作流搭建复用模块项目做大以后工作流数量会迅速增长。这时候我会把公共逻辑抽成子工作流然后在主流程里调用。比如公司内部所有流程都要走一个“身份校验 权限判断”的公共模块就可以抽成一个auth-check子工作流其他流程里引用它即可。子工作流的调用节点长得跟普通节点类似但属性面板里可以选择“子工作流”并指定要调用哪个已发布的工作流版本。输入参数和输出参数都能映射。这个机制能大幅降低重复节点堆叠带来的维护成本改动一次公共逻辑所以依赖它的流程全部生效。5.2 多 Agent 协作场景deer-flow 虽然不是一个完整的 Agent 框架但它的图编排能力完全可以支撑简单的多 Agent 协作。我搭过一版“主管-专员”模式的流程主管节点先接收用户任务做任务拆解把拆解后的子任务分别派发给几个专员 Agent 节点每个专员负责一类能力如搜索资料、写代码、做总结全部完成后汇总到主管节点做最终整合。这种实现方式本质上就是利用工作流的图结构天然支持的这种 fork-join 模式。开发时把每个专员都做成子工作流方便单独测试和替换。比如搜资料专员内部用的是某搜索 API如果 API 涨价要换只需要改动这个子工作流内部实现不影响主流程编排。5.3 将 deer-flow 嵌入现有系统API 集成模式最后一个很常见的诉求是如何把工作流能力嵌入到公司现有系统里而不是每次都在控制台手动操作。deer-flow 提供了完整的 REST API可以创建、更新、运行工作流也能查询执行状态。我在实践中通常是业务系统后端收到用户请求后调用 deer-flow 的“运行工作流”API 把任务交给引擎异步执行然后轮询查询执行结果。通过 Webhook 把流程结果推回给业务系统避免业务系统阻塞等待。整体调用链路很干净deer-flow 在这里的角色更像一个“AI 中间层”把各种模型和工具能力编排成一套标准化的接口服务。6. 一些题外话与个人心得聊完技术最后说点我个人在使用了这段日子之后更真实的感受。deer-flow 并不完美。它目前的生态还在早期官方文档有些地方写得比较简略社区模板也不算丰富离 n8n 那种庞大的集成库还有距离。但它的定位很准踩中了“想自由编排 AI 工作流又不想被云平台绑死”这块需求。对我来说工具链最终的考验永远不是功能多不多而是在真实业务里跑得稳不稳、能不能塞进现有的研发流程里。deer-flow 的数据文件是纯文本 YAML能进 Git能 review能回滚这一条就已经赢了很多同类工具。如果你在犹豫要不要上手我的建议是先跑一个最小的 Webhook 场景就 10 分钟的事。等你能画出第一条链路把真实业务里最繁琐的那个流程塞进去剩下的很多想法自然会浮现出来。