企业官网建设流程全解析

DeerFlow 部署与落地指南：从克隆仓库到对外服务的 3 条路径

【免费下载链接】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 运行框架：子智能体、沙箱、记忆、技能与消息网关协作，承接从几分钟到几小时的研究、编码和创作任务。这篇文章就是DeerFlow 部署指南，主线只有一条：你拿到仓库后，怎么最快把它跑起来、并稳定地对外提供服务。

先选档位：三种规模，三种部署方式

拿到项目后别急着敲命令。先对照下面这张表定位自己，后文每个档位都按「环境准备 → 最小可运行配置 → 启动与验证 → 常见坑」四步展开，只读你那一档就够了。

档位对应的机器规模，官方给了明确基线：本地体验 4 核 8G 起步；Docker 开发 4 核 8G + 25G 磁盘；对外服务 8 核 16G 起步、推荐 16 核 32G。2 核 4G 基本不够用——沙箱容器和并发研究会先把内存吃满。

快速体验：本地开发环境怎么搭建

环境准备

本地模式要求 Node 22+、pnpm、uv、nginx 和 Python 3.12，版本要求与检查命令一一对应：

克隆仓库后先跑自检：

git clone https://gitcode.com/GitGitHub_Trending/de/deer-flow cd deer-flow make check

为什么先跑make check：它会逐项打印 OK/FAIL，缺 nginx 或 Node 版本不够时直接给出安装提示，比启动到一半报错好排查得多。预期输出是结尾一行「OK All dependencies are installed!」。

最小可运行配置

配置不用手写。跑交互式向导，跟着选模型提供商、填 API key、挑沙箱模式即可：

make setup

它会生成最小可用的config.yaml，并把密钥写入根目录.env，全程约两分钟。想手动精调的话改用make config复制完整模板，逐项字段更多，见仓库根目录的config.example.yaml。

启动与验证

make install # 装后端 + 前端依赖，只需一次 make dev # 开发模式启动，带热重载

浏览器打开http://localhost:2026：能看到登录页说明前端和网关都活了；登录后发起一个任务，答案以流式文本返回，任务产物落在会话的/mnt/user-data/outputs目录。💡 不想每次手动装依赖的话，make install之后改代码make dev会自动热重载，不用重启。

本地模式常见坑

• config.yaml不存在直接启动：make dev会在自检阶段拒绝启动，先跑make setup。
• pnpm 反复报版本错误：项目通过 corepack 锁定版本，用corepack enable或直接依赖make check的自动拉起，别手动装别的 pnpm 版本。
• 模型 key 没填导致任务中途失败：界面能打开不等于能跑任务，跑make doctor能直接指出哪个环境变量是空的。

团队自用：Docker 容器化部署

内网给团队用，推荐 Docker 方式：环境一致、不污染个人电脑，重启机器不用重装。

环境准备

只需 Docker Engine（或 Docker Desktop）和Compose v2.24+，确认方式：

docker compose version

为什么卡这个版本：旧版 Compose 解析不了docker/docker-compose-dev.yaml里的可选env_file语法，会直接报 unknown flag。

最小可运行配置

配置文件和本地模式完全一致——仓库根目录的config.yaml+.env。区别只在沙箱：make docker-start会读取config.yaml里的sandbox配置自动决定要不要额外启动 provisioner 服务，你不需要手工编排容器。

启动与验证

make docker-init # 拉取沙箱镜像，仅首次 make docker-start # 启动全部服务 make docker-logs # 看日志

预期看到 gateway、frontend、nginx 等容器全部 up，然后访问http://localhost:2026。验证方法和本地模式相同：登录 + 跑通一个任务。停服务用make docker-stop。

Docker 模式常见坑

• Linux 下报 permission denied 访问 docker.sock：把你的用户加进docker组后重新登录，这是文档里被问得最多的问题。
• 构建镜像慢：受限网络下设置UV_INDEX_URL和NPM_REGISTRY指向国内镜像源再跑make docker-init。
• 改了config.yaml没生效：大部分配置下次访问即生效，但 checkpoint 存储类参数是进程启动时冻结的，必须重启容器。

对外服务：生产 Docker 部署

给外部用户访问，用生产模式：镜像预先构建好、运行时不装依赖，启动速度稳定。

环境准备

与团队自用相同（Docker + Compose v2.24+），外加一台 Linux 服务器。规模建议按官方基线：8 核 16G 起步、40G 空闲磁盘；如果同时自托管 LLM，资源要另算。

最小可运行配置

生产部署只有三个增量配置：

# .env 示例，只列关键项 PORT=2026 # 对外端口 BIND_HOST=0.0.0.0 # 默认 127.0.0.1 仅本机可达，对外必须改 # BETTER_AUTH_SECRET # 首次 make up 自动生成并持久化，一般不用手动填

config.yaml里额外建议把database.backend设为sqlite或postgres——会话、检查点、应用数据都走这个库，持久化部署不能留在内存里。其余字段保持向导生成的默认值即可，更多选项见官方文档。

启动与验证

make up # 构建镜像 + 启动 make down # 停止并清理

make up会阻塞等待 Gateway 的/health端点就绪后才返回成功；超时则打印容器状态和最近的 Gateway 日志并以非零码退出，失败原因当场可见。成功时输出的预期信息：

DeerFlow is running! Application: http://localhost:2026 API Gateway: http://localhost:2026/api/*

⚠️ 如果改了BIND_HOST暴露到网络，先在浏览器里完成管理员账号创建，再放开外部访问——deploy 脚本检测到非回环绑定时会打印这条提醒，别跳过。

生产部署常见坑

• 多 worker 直接改GATEWAY_WORKERS：Gateway 在进程内持有运行任务，默认必须保持单 worker。要多副本需 Postgres + Redis 流桥 + 心跳与 db 事件存储一起配齐，单独加 worker 会出现任务投递错乱。
• 公网裸奔：默认 nginx 是同源的，不做 CORS、不终止 TLS。对外必须前置你自己的 TLS 终结和认证层。
• 沙箱模式选错：DooD（挂宿主机 Docker socket）等于给容器 root 级宿主机权限，生产环境应改用 provisioner 模式，让沙箱在独立 Pod/容器里跑。

进阶加固：安全、持久化与运维

以上三档共用的加固项集中在这里说一次，按需取用。

网络与密钥：端口默认绑 127.0.0.1，暴露前必须前置 TLS 与认证；所有密钥只放.env，config.yaml里用$VAR引用，密钥文件权限保持 600。IM 渠道（Telegram、Slack、飞书等）都支持allowed_users白名单，开放渠道先收紧再放开。

数据与备份：运行时数据集中在DEER_FLOW_HOME（默认backend/.deer-flow）：会话数据库、认证密钥、运行日志都在里面。备份策略很直接——整个目录加数据库文件一起归档即可，deploy.sh生成的两个密钥文件也在这里，丢了登录态会全部失效。

可观测与排障：日志用make docker-logs或docker compose logs --tail 100 gateway；出问题时跑make support-bundle，它生成脱敏后的诊断摘要和证据包，报障或自查都不用手动翻日志。

扩缩容信号：CPU 或内存长期贴顶时，先降并发运行数，再升一档配置；确需多副本时按上一条的 worker 前置条件配齐 Postgres/Redis，不要只改 worker 数。

上线前检查清单

全部勾选再放行流量，缺任何一项都可能让用户第一次访问就撞上问题：

• make doctor通过，config.yaml至少配置了一个可用模型
• .env中所有被引用的环境变量都有真实值
• BIND_HOST已按暴露范围设置，且 TLS/认证前置层就绪
• 管理员账号已在首个访问时创建
• database.backend指向持久化后端，DEER_FLOW_HOME已纳入备份
• 沙箱模式确认：生产不用 DooD，改用 provisioner
• 端口与防火墙规则核对，只开必要端口
• 日志命令（make docker-logs）验证能正常输出

配置字段与部署细节的完整参考，建议直接读仓库内的 backend/docs/CONFIGURATION.md 和 backend/docs/SETUP.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