Skip to Content
WASPWASP

部署指南

本指南涵盖 DeerFlow 应用所有支持的部署方式：本地开发、Docker Compose 以及使用 Kubernetes 管理沙箱的生产环境。

本地开发部署

本地工作流是运行 DeerFlow 最快的方式，所有服务作为原生进程在你的机器上运行。

make dev

启动的服务：

服务端口描述
Gateway API8001FastAPI 后端 + 嵌入式 Agent 运行时
前端3000Next.js 界面
nginx2026统一反向代理

访问地址：http://localhost:2026 

Docker Compose 部署

Docker Compose 在容器中运行所有服务。适用于更接近生产的本地设置或团队环境。

前置条件

  • Docker（macOS 上的 Docker Desktop 或 OrbStack）
  • 在仓库根目录中已配置的 config.yaml

开发 Compose

# 设置 deer-flow 仓库根目录的绝对路径
export DEER_FLOW_ROOT=/path/to/deer-flow
 
docker compose -f docker/docker-compose-dev.yaml up --build

访问地址：http://localhost:2026 

环境变量

在仓库根目录创建 .env 文件用于存放密钥和运行时配置：

# .env（项目根目录 — Gateway、API Key、认证）
OPENAI_API_KEY=sk-...
AUTH_FRONTEND_BASE_URL=https://your-domain.com
AUTH_JWT_SECRET=...   # 可选；未设置时写入 .deer-flow

将 frontend/.env.example 复制为 frontend/.env 配置界面品牌名（NEXT_PUBLIC_APP_NAME 等）。

docker-compose*.yaml 为 gateway 加载 ../.env，为 frontend 加载 ../frontend/.env。

数据持久化

线程数据存储在 backend/.deer-flow/threads/。在 Docker 部署中，此目录会绑定挂载到 gateway 容器中。

为避免容器重建时数据丢失：

  1. 将 DEER_FLOW_ROOT 设置为仓库根目录的绝对路径。
  2. 验证 threads/ 和 skills/ 目录挂载正确。

对于生产环境，使用命名卷或持久化卷声明（PVC）代替主机绑定挂载。

生产部署注意事项

沙箱模式选择

沙箱使用场景
LocalSandboxProvider单用户、受信任的本地工作流
AioSandboxProvider（Docker）多用户、中等隔离需求
AioSandboxProvider + K8s Provisioner生产环境、强隔离、多用户

对于有多个并发用户的任何部署，使用基于容器的沙箱，防止用户之间的执行环境相互干扰。

K8s Provisioner 配置

配置 Provisioner

在你的 .env 或 compose 覆盖文件中设置必需的环境变量：

K8S_NAMESPACE=deer-flow
SANDBOX_IMAGE=enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
DEER_FLOW_ROOT=/absolute/path/to/deer-flow

配置沙箱提供者

# config.yaml
sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8002

配置数据持久化

对于生产环境，使用 PVC 代替 hostPath 卷：

# 在 .env 或 compose 环境中
USERDATA_PVC_NAME=deer-flow-userdata-pvc
SKILLS_PVC_NAME=deer-flow-skills-pvc

当设置 USERDATA_PVC_NAME 时，Provisioner 自动使用子路径（threads/{thread_id}/user-data），每个线程在 PVC 中获得自己的目录。

nginx 配置

nginx 将流量路由到前端或 Gateway。/api/langgraph/* 会被重写到 Gateway 的 LangGraph-compatible /api/* 路由，因此不需要单独的 LangGraph upstream。

认证配置

会话由 Gateway（JWT Cookie）管理。生产环境在项目根目录 .env 中设置：

  1. AUTH_FRONTEND_BASE_URL — 对外访问地址（如 https://your-domain.com）
  2. AUTH_JWT_SECRET — JWT 签名密钥（可选；未设置时写入 .deer-flow）
  3. OAuth / 魔法链接：AUTH_*_CLIENT_*、RESEND_API_KEY、RESEND_FROM
# 生成密钥
openssl rand -base64 32

资源建议

服务最低配置推荐配置
Gateway + Agent 运行时2 vCPU、4 GB RAM4 vCPU、8 GB RAM
前端0.5 vCPU、512 MB1 vCPU、1 GB
沙箱容器（每会话）1 vCPU、1 GB2 vCPU、2 GB

部署后验证

启动后验证部署：

# 检查 Gateway 健康状态
curl http://localhost:8001/health
 
# 通过 nginx 列出配置的模型（验证完整代理链）
curl http://localhost:2026/api/models

正常工作的部署会从每个端点返回 200 响应。/api/models 调用会返回你 config.yaml 中的模型列表。

配置运维与排障
为什么选择 WASP