DeerFlow 部署实战：本地跑通到生产上线的完整路径，4 个高频坑一次讲清
【免费下载链接】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 是一个开源的长时程 SuperAgent 运行框架：它靠沙箱、记忆、技能和子智能体，让一个 Agent 独立处理从几分钟到几小时的复杂任务——查资料、写代码、出报告一条龙。这份指南不堆概念，而是按你的真实决策路径走：30 秒在本地跑通 → 一分钟内看懂架构 → 三种部署姿势怎么选 → 真正影响体验的参数 → 卡住时照着排 → 上生产前的勾选项。适合有基本命令行经验、想尽快把 DeerFlow 部署起来用起来的人，看完直接能动手。🚀
30 秒跑通：最小可运行环境
先跑通，再谈别的。最短路径就是 4 条命令，全部在项目根目录执行：
- 克隆代码（国内网络建议用 GitCode 镜像源）
git clone https://gitcode.com/GitHub_Trending/de/deer-flow cd deer-flow- 交互式配置向导：选模型提供商、填 API key、定沙箱策略，约 2 分钟，自动生成
config.yaml并把密钥写入.env
make setup- 检查前置工具（Node 22+、pnpm、uv、nginx）并安装前后端依赖
make check make install- 启动开发模式（带热更新，前端 + 网关 + 反向代理一次拉起）
make dev怎么确认成功了：浏览器打开http://localhost:2026，能看到登录页并注册一个账号，随后发起一次对话、Agent 开始逐步执行——就算跑通了。
跑起来之后，你可以随便丢一个研究任务试试，比如让它分析一份 CSV 并出图：
它到底在干什么：架构 60 秒拆解
先建立整体图感：你只和 2026 端口打交道，后面发生的事全在这张图里。
nginx：你的统一前台
它像餐厅的门卫：不管你要的是页面还是接口，进门都是 2026 一个号码，它负责把流量分给前端或网关。同域设计意味着浏览器不用处理跨域，这也是它默认不输出 CORS 头的原因。
Gateway：又当 API 又当大脑
它像一个既能接电话又能亲自干活的调度中心：FastAPI 处理所有/api/*请求，真正的 Agent 运行时也跑在这个进程里——任务状态、运行管理都住在这里，所以它不能随便随便重启（后文生产清单里会提）。
Agent 运行时：任务真正发生的地方
说白了就是「带班组长」：它拿着你的指令，派活给子智能体、查记忆、装技能、开沙箱，把一个长任务拆成一步步执行。你界面上看到的每一个进度事件，都从这里流出来。
沙箱 Sandbox：Agent 的独立工作间
它像一间一次性的实验室：Agent 在里面跑 bash、装依赖、写文件，宿主机是安全的。默认用LocalSandboxProvider（不隔离，适合单人本机），容器化模式用 AIO Sandbox——共享环境务必换成后者，这条是安全底线。
Redis：事件流的接力站
像广播站：当网关有多 worker 或你断线重连时，SSE 事件流靠它跨进程投递和按Last-Event-ID补发。单人本地部署它也在跑，但平时你感觉不到它。
部署选型：3 种姿势对应 3 种场景
选型前先对号入座：机器至少 4 核 8G，长开服务器建议 8 核 16G。
| 方案 | 适合谁 | 优势 | 注意点 |
|---|---|---|---|
本地裸跑make dev | 个人开发、想改代码 | 热更新最快，改配置即生效 | 需 Node 22+/pnpm/uv/nginx 齐全；Windows 要用 Git Bash |
Docker 开发make docker-start | 环境不想被污染、多人同机 | 沙箱镜像预拉取，配置驱动自动识别模式 | 需要 Compose v2.24+；Linux 可能遇 socket 权限问题 |
Docker 生产make up | 常驻服务、给别人用 | 一条命令构建启动，自带健康检查把关 | 入口默认只绑回环，公网暴露前必须加 TLS/认证 |
本地裸跑——最短反馈环，两条命令起步：
make check # ← 缺什么工具它直接告诉你 make dev # ← 前台启动，Ctrl+C 停止最常踩的坑：make check报缺 nginx 或 pnpm，装完再跑一次即可，不用改任何配置。
Docker 开发——适合想体验沙箱隔离但还不想上生产的：
make docker-init # ← 拉取沙箱镜像，只需一次 make docker-start # ← 自动按 config.yaml 识别沙箱模式这步最容易卡住：Linux 上如果报permission denied ... docker.sock，把当前用户加进 docker 组重新登录就行；另外 Compose 版本低于 v2.24 会解析不了 compose 文件的env_file语法，先docker compose version确认。
Docker 生产——DeerFlow 部署到长期在线服务器的标准姿势：
make up # ← 构建镜像并启动全部服务，等 /health 通过才报成功 make down # ← 停止并移除容器必改的一项：.env里BIND_HOST默认是127.0.0.1，因为 Agent 能执行命令，默认部署模型就是「本地可信环境」。只有在你自己的 TLS/认证前置就绪后才改成0.0.0.0，端口则用PORT调整。
配置调优：真正影响体验的几个参数
别急着改这里——先确认任务跑顺了，再按下面三级往下调。全部在 config.example.yaml 里都有注释，向导生成的config.yaml只包含必要项，要加字段就对着模板抄。
必配：模型是唯一的硬前提
向导已帮你写好。核心就两点：models列表里每个条目对应一个可切换的模型，api_key用$OPENAI_API_KEY这种写法从.env取，密钥永远不落盘在 yaml 里。换模型只需加一个条目，界面里即时可切。
推荐：token_budget — 每次任务的 token 总闸门，防账单失控
| 项 | 默认值 | 推荐值 | 为什么 |
|---|---|---|---|
enabled | false | 长期跑共享环境改true | 长时程任务一次能吃掉几十万 token，闸门比事后看账单有效 |
max_tokens | 200000 | 按你的单价倒推 | 这是单次运行的 input+output 总上限 |
warn_threshold | 0.8 | 保持 | 到 80% 时 Agent 先收到提醒，通常能自己收口 |
推荐：max_recursion_limit — 运行递归步数的天花板，防死循环烧钱
默认1000，普通任务用 100（服务端默认）就够，这个字段只是防客户端传天文数字的硬顶。除非你跑极深的子智能体嵌套，别动它。
进阶：database.backend — 任务状态的落盘方式，决定重启丢不丢东西
默认sqlite单文件就够个人用；多人共享或要审计历史就换postgres（对应.env里的DATABASE_URL）。注意checkpoint_channel_mode和snapshot_frequency在进程首次构建 Agent 时就被冻结，改了要重启进程才生效。
进阶：memory 与 sandbox 容量 — 长期记忆的深度和并发沙箱数
memory.backend_config.max_facts默认100条事实，想要 Agent 更「记得住」可调大但提取会更多 LLM 调用；sandbox.replicas（容器沙箱模式）默认3个并发容器，多人同时跑任务就调大，它和机器内存直接挂钩。
排障速查：90% 的卡壳出在这 5 个地方
排障前先记住两条万能命令：
make doctor # ← 检查配置与环境，直接给修复建议 make support-bundle # ← 生成脱敏诊断包，卡得深时贴给社区症状：Docker 命令报 docker.sock permission denied → Linux 当前用户没权限连 daemon → 加组重登
sudo usermod -aG docker $USER # ← 然后注销重新登录 docker info # ← 能看到 Server 段即恢复症状：make up 一直等不到 healthy 就退出 → 网关容器没起来，多半是构建或依赖问题 → 看日志定位
make down docker compose -f docker/docker-compose.yaml logs --tail=100 gateway退出时脚本本身会打印容器状态和最近的网关日志，先读那段再动手。
症状：本地 2026 或 8001 端口被占用 → 有旧进程没停干净 → 先停服务再查占用
make stop lsof -i :2026 -i :8001 # ← 列出占用进程，确认后 kill症状：模型调用直接报错或一直转圈 →.env里 key 没配或模型名与提供商不匹配 → 逐层验证
make doctor # ← 会点名缺哪个 key grep -c "your-" .env # ← 结果应为 0，还有占位符就是没填症状：多人共用时 Agent 执行命令影响宿主机 → 沙箱还停在 LocalSandboxProvider（无隔离边界）→ 换容器沙箱 🔴
🔴 这一条是唯一要标红的：共享环境下allow_host_bash保持false，把sandbox.use换成 AIO SandboxProvider 并make setup-sandbox预拉镜像。本地单人跑则维持默认即可，别为「感觉更隔离」乱改挂载。
上生产前必须勾掉的 6 项
BIND_HOST保持回环默认（验证：grep BIND_HOST .env）BETTER_AUTH_SECRET已设为随机强值（验证：grep BETTER_AUTH_SECRET .env）- 生产关闭 Swagger/OpenAPI 文档（
GATEWAY_ENABLE_DOCS=false） - 状态落盘：
database.backend为 sqlite 或 postgres - 服务自愈：容器均带
restart: unless-stopped（docker/docker-compose.yaml） - 入口走 HTTPS 并留日志（
docker compose logs -f gateway）
安全细节展开看 SECURITY.md：Agent 能执行命令，公网暴露前先过一遍那里的建议。
到这里，你的 DeerFlow 部署已经能应对从个人试用到小团队共享的完整场景了。下一步建议两条腿走：想深入行为细节，翻 backend/docs/ 里的 CONFIGURATION 和 ARCHITECTURE 两篇；想让它更懂你的业务，去 skills/ 里加一个自定义技能试跑。先让make dev稳定跑上一周，再碰生产那 6 项——顺序反了容易白折腾。⚡
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
