主题
快速开始与安装
本章目标:
- 走通从零到
http://localhost:2026跑起来的最短路径,理解make setup → make install → make dev三步链路。- 看懂本地模式与 Docker 模式的差异,以及 5 个启动模式(dev/prod/daemon/docker-start/up)各自的命令、端口与适用场景。
- 弄清
.env与config.yaml的分工:谁存密钥、谁存结构、谁引用谁、谁负责升级。
TL;DR
DeerFlow 用一个根目录 Makefile 统一所有开发命令。新用户推荐先跑 make setup(交互向导,4 步生成 config.yaml 与 .env),再跑 make install 装依赖,最后 make dev 启动。make doctor 可随时体检系统依赖、配置与模型密钥。本地模式需要 Node 22+/pnpm/uv/nginx 四件套,Docker 模式只需 Docker。所有模式最终都通过 nginx 把前端、Gateway API 聚合到 localhost:2026 一个入口。配置分两层:config.yaml 描述结构(模型、工具、sandbox),.env 只存密钥,前者用 $VAR 语法引用后者。
Overview
为什么需要这一整套 setup/doctor/serve 脚本?核心矛盾是:DeerFlow 是一个 harness/app 双层系统,运行时同时需要 Python 后端(Gateway + agent runtime)、Next.js 前端、nginx 反向代理三个进程协同,还要解决"模型密钥从哪来、sandbox 用本地还是容器、依赖怎么装"等一系列开局决策。如果让用户手动逐项配置,出错面极大。
DeerFlow 的解法是把决策前移到一个交互向导(make setup),把校验收敛到一个体检命令(make doctor),把进程编排收敛到一个启动脚本(serve.sh)。配置被刻意拆成两层:结构性配置进 config.yaml(可提交、可 diff、有版本号),敏感密钥进 .env(不提交)。这样 setup 向导写 config.yaml 时只写 api_key: $OPENAI_API_KEY 这种引用占位,真实密钥单独写进 .env,既安全又可复现。
Architecture
所有入口都是 Makefile 里的 target,每个 target 委托给 scripts/ 下的一个脚本。脚本之间职责单一、互不耦合:向导只管写配置,体检只管读校验,启动只管编排进程。
| 命令 | 委托脚本 | 职责 | Source |
|---|---|---|---|
make setup | scripts/setup_wizard.py | 交互式 4 步向导,生成 config.yaml + .env | Makefile:48-49 |
make doctor | scripts/doctor.py | 体检系统依赖/配置/模型/sandbox | Makefile:51-52 |
make config | scripts/configure.py | 纯拷贝模板(已存在则中止) | Makefile:54-55 |
make check | scripts/check.py | 只检查 4 个系统工具是否安装 | Makefile:61-62 |
make dev / start | scripts/serve.sh | 本地编排 Gateway+前端+nginx 三进程 | Makefile:116-123 |
make docker-start | scripts/docker.sh | docker-compose 开发环境(自动识别 sandbox 模式) | Makefile:156-157 |
make up / down | scripts/deploy.sh | 生产 Docker compose 部署 | Makefile:178-183 |
Components / Subsystems
make setup 向导
职责:交互式收集 LLM、搜索、执行模式三类选择,然后写出最小可用配置。
- 入口判定:非交互环境(非 TTY)直接退出并提示手动编辑,见 scripts/setup_wizard.py:17-28。
- 已有
config.yaml时询问是否重新配置,否则保持原样并提示跑make doctor,见 scripts/setup_wizard.py:51-58。 - 共 4 步:Step1 LLM、Step2 搜索/抓取、Step3 执行与安全、Step4 写配置,见 scripts/setup_wizard.py:61-100。
- Step3 让用户在 Local sandbox 与 Container sandbox 间选择,并决定是否启用 bash/写文件工具,见 scripts/wizard/steps/execution.py:25-51。
- 末尾明确给出下一步命令:
make install与make dev,见 scripts/setup_wizard.py:152-156。
config.yaml / .env 写出逻辑
职责:把向导选择落盘,且不破坏用户既有定制。
config.yaml不存在时从.env.example拷贝出.env,见 scripts/setup_wizard.py:103-107。- 模型条目里只写
api_key: $ENV_VAR这种引用形式,真实 key 走.env,见 scripts/wizard/writer.py:181-191。 .env是"原地合并":已有 key 改值,新 key 追加,注释与格式保留,见 scripts/wizard/writer.py:37-63。config_version取自config.example.yaml,用于后续升级检测,见 scripts/wizard/writer.py:255-263。
make doctor 体检
职责:不修改任何东西,只读校验并打印可执行的修复建议。
- 五大分区:System Requirements、Configuration、LLM Provider、Web Capabilities、Sandbox,见 scripts/doctor.py:652-687。
- 系统依赖要求:Python 3.12+、Node 22+、pnpm、uv、nginx,见 scripts/doctor.py:132-207。
- 会先
load_dotenv再校验每个模型的$VAR是否在环境里有值,见 scripts/doctor.py:289-337。 - 退出码:有 fail 返回 1,只有 warn 也算 Ready,见 scripts/doctor.py:706-717。
serve.sh 本地编排
职责:本地模式下按序拉起三个进程并等端口就绪。
- 启动前先
source .env,见 scripts/serve.sh:34-38。 - 找不到任何 config 文件直接报错并提示
make setup,见 scripts/serve.sh:146-154。 - 每次启动自动跑
config-upgrade.sh把新字段合并进config.yaml,见 scripts/serve.sh:156。 - 三进程顺序:Gateway(8001)→ Frontend(3000)→ Nginx(2026),每个都用
wait-for-port.sh等就绪,见 scripts/serve.sh:255-268。
docker.sh 容器编排
职责:Docker 开发环境,启动前从 config.yaml 自动识别 sandbox 模式决定要不要拉 provisioner。
detect_sandbox_mode用 awk 解析config.yaml的sandbox:段,产出 local / aio / provisioner 三种,见 scripts/docker.sh:18-61。- 只有 provisioner 模式才把
provisioner服务加入启动列表,见 scripts/docker.sh:166-179。 config.yaml缺失时自动从示例拷贝,并提示先跑make setup后再make docker-start,见 scripts/docker.sh:190-209。
Data Flow
下面是新用户从零到服务就绪的完整调用链(本地模式)。
启动模式状态机(serve.sh 的参数路由):
速查表
DeerFlow 提供 5 种启动方式,矩阵如下:
| 模式 | 命令 | 脚本/参数 | 热重载 | 后台 | 端口入口 | Source |
|---|---|---|---|---|---|---|
| 本地开发 | make dev | serve.sh --dev | 是 | 否 | localhost:2026 | Makefile:116-118 |
| 本地开发(后台) | make dev-daemon | serve.sh --dev --daemon | 否 | 是 | localhost:2026 | Makefile:126-128 |
| 本地生产 | make start | serve.sh --prod | 否 | 否 | localhost:2026 | Makefile:121-123 |
| 本地生产(后台) | make start-daemon | serve.sh --prod --daemon | 否 | 是 | localhost:2026 | Makefile:131-133 |
| Docker 开发 | make docker-start | docker.sh start | — | 是(容器) | localhost:2026 | Makefile:156-157 |
| Docker 生产 | make up | deploy.sh | — | 是(容器) | localhost:2026 | Makefile:178-179 |
停止对应方式:本地用 make stop(Makefile:136-137),Docker 开发用 make docker-stop,Docker 生产用 make down。
端口与目录矩阵:
| 项 | 值 | 说明 | Source |
|---|---|---|---|
| Gateway | localhost:8001 | REST API + agent runtime | scripts/serve.sh:211 |
| Frontend | localhost:3000 | Next.js 开发服务 | scripts/serve.sh:212 |
| Nginx | localhost:2026 | 统一反向代理入口 | scripts/serve.sh:213 |
| Docker 入口 | localhost:2026 | compose nginx 端口映射 2026:2026 | docker/docker-compose-dev.yaml:67-68 |
| Provisioner | :8002 | 仅 provisioner sandbox 模式启用 | docker/docker-compose-dev.yaml:56 |
| 运行时数据目录 | .deer-flow/ | 默认在 project root 下,可用 DEER_FLOW_HOME 覆盖 | config.example.yaml:8-9 |
Configuration
.env 与 config.yaml 的关系是本章核心:config.yaml 描述"用什么模型、什么工具、什么 sandbox",其中所有字段都支持 $VAR 语法引用环境变量;.env 只负责给这些变量提供真实值。
| 配置项 | 文件 | 作用 | 安全标注 | Source |
|---|---|---|---|---|
config_version | config.yaml | 版本号,落后于 example 时触发升级 | — | config.example.yaml:18 |
models[].api_key | config.yaml | 写 $OPENAI_API_KEY 等占位引用 | 仅占位,不存明文 | config.example.yaml:10 |
sandbox.use | config.yaml | 选 Local / Aio 容器 sandbox provider | — | config.example.yaml:559-560 |
sandbox.allow_host_bash | config.yaml | 默认 false,非安全隔离边界 | ⚠️ 仅在完全可信单机环境开启 | config.example.yaml:561-564 |
OPENAI_API_KEY 等 | .env | 模型/搜索真实密钥 | ⚠️ 不要提交,默认占位值 | .env.example:19-21 |
DEER_FLOW_CONFIG_PATH | 环境变量 | 指定特定 config 文件路径 | — | config.example.yaml:6-7 |
DEER_FLOW_HOME | 环境变量 | 覆盖运行时可写数据目录 | — | config.example.yaml:8-9 |
config 文件解析优先级(serve.sh / config-upgrade.sh 一致):DEER_FLOW_CONFIG_PATH > backend/config.yaml > 根 config.yaml,见 scripts/config-upgrade.sh:14-23 与 scripts/serve.sh:146-154。
Common Pitfalls / Tips
- 非交互环境跑
make setup会直接退出:CI 或管道里没有 TTY 时向导拒绝运行,需手动编辑config.yaml/.env或在终端里跑,见 scripts/setup_wizard.py:23-28。 make config已存在配置会中止:它只是纯拷贝模板,检测到config.yaml/config.yml/configure.yml任一存在就报错退出,要改配置请用make setup,见 scripts/configure.py:29-34。- 本地模式必须装 nginx:
make dev前会跑check.py,Windows 上 nginx 难装,官方建议 Windows 用户走 Docker 模式,见 scripts/check.py:139-143。 - host bash 不是安全隔离边界:
LocalSandboxProvider上启用 bash 会被 doctor 标 warn,需要强隔离时应切到 container sandbox,见 scripts/doctor.py:568-589。 make dev每次都会自动升级配置:启动时跑config-upgrade.sh,落后版本会被合并新字段并备份成config.yaml.bak,见 scripts/serve.sh:156 与 scripts/config-upgrade.sh:137-142。- Docker 模式无需手动选 provisioner:
docker.sh从config.yaml的sandbox:段自动识别,只有配了provisioner_url才会拉起 provisioner 服务,见 scripts/docker.sh:50-61。 - doctor 只有 fail 才返回非零:仅有 warning(如未配搜索)仍判定 Ready,可直接
make dev,见 scripts/doctor.py:709-711。
References
- Makefile — 所有开发命令的统一入口,定义 setup/doctor/dev/up 等 target 到脚本的映射。
- scripts/setup_wizard.py — 4 步交互向导主流程,生成 config.yaml 与 .env 并提示下一步命令。
- scripts/doctor.py — 健康体检,五大分区校验系统依赖、配置、模型密钥、sandbox。
- scripts/serve.sh — 本地三进程编排脚本,处理 dev/prod/daemon/stop/restart 参数路由。
- scripts/docker.sh — Docker 开发环境管理,自动从 config.yaml 识别 sandbox 模式。
- scripts/configure.py — 纯模板拷贝脚本,生成 config.yaml/.env/frontend/.env。
- .env.example — 密钥与可选环境变量模板,展示 .env 该放哪些值。
- config.example.yaml — 完整配置参考,顶部注释说明 $VAR 引用与 config_version 机制。
Related Pages
| 页面 | 关系 |
|---|---|
| ./01-项目概览.md | 上游:本章是项目概览之后的第一步实操,先读概览理解 harness/app 双层定位 |
| ./04-配置系统与AppConfig.md | 深入:本章只讲 .env 与 config.yaml 的上手关系,配置加载与 AppConfig 模型见此页 |
| ./07-沙箱与工具配置.md | 延伸:setup 向导 Step3 的 sandbox 选择,其完整语义在此页展开 |
| ./08-Docker部署与运维.md | 延伸:本章只列 docker-start/up 命令,compose 编排与运维细节见此页 |