Skip to Content

CodeCraft

Star on GitHub

部署指南

浏览器入口统一经 nginx → backend-go（REST/SSE + 认证）；Python worker 仅处理 POST /internal/runtasks，不对外暴露给浏览器。

本地全进程开发

make dev
服务端口说明
backend-go18080Go 控制面（对外 API）
worker8001Python RunTask（内网，经 Go 调度）
前端3000Next.js
nginx2026统一入口

访问：http://localhost:2026 

Docker 开发栈

容器内：frontend、worker、nginx（按 config.yaml 沙箱模式可选 provisioner）。backend-go 在宿主机运行（compose 通过 host.docker.internal:18080 访问）。

前置

  • Docker
  • 仓库根目录已配置 config.yaml
  • .env 中至少设置 DEER_FLOW_WORKER_SECRET（openssl rand -hex 32）；宿主机启动 Go 所需的数据库/Redis 等与全本地 make dev 一致（见 backend-go/README.md）

启动

export DEER_FLOW_ROOT=/absolute/path/to/deer-flow   # provisioner 模式需要
make docker-start
# 另开终端：在仓库根目录启动 backend-go（例如 backend-go 目录下 make run）

等价命令：docker compose -p deer-flow-dev -f docker/docker-compose-dev.yaml up --build（在 docker/ 目录下需自行带上 -p 与 DEER_FLOW_ROOT）。

访问：http://localhost:2026 

停止：make docker-stop

Docker 生产

使用仓库根目录 docker/docker-compose.yaml，推荐：

./scripts/deploy.sh          # 构建并后台启动
# ./scripts/deploy.sh build  # 仅构建
# ./scripts/deploy.sh start  # 已有镜像时启动
# ./scripts/deploy.sh down   # 停止并删除容器

或 make up / make down。deploy.sh 会在 backend/.deer-flow/ 下持久化生成/读取 BETTER_AUTH_SECRET、DEER_FLOW_WORKER_SECRET、AUTH_JWT_SECRET（若环境变量未设置）。

环境变量

仓库根目录 .env（docker-compose*.yaml 通过 env_file 加载）。常用示例：

OPENAI_API_KEY=sk-...
DEER_FLOW_ROOT=/absolute/path/to/deer-flow
BETTER_AUTH_SECRET=your-secret-min-32-chars
BETTER_AUTH_URL=https://your-domain.com
AUTH_JWT_SECRET=...           # 未用 deploy.sh 时需自行设置（建议 openssl rand -hex 32）
DEER_FLOW_WORKER_SECRET=...   # 同上

生产环境必须设置强随机 BETTER_AUTH_SECRET；勿依赖前端构建中的已知默认值。

数据持久化

运行时数据默认在 DEER_FLOW_HOME（默认 backend/.deer-flow）：线程、认证状态等。生产请用命名卷或 PVC，避免仅依赖临时主机路径。

生产注意

沙箱

沙箱场景
LocalSandboxProvider单用户、受信环境
AioSandboxProvider（Docker）多用户、进程隔离
AioSandboxProvider + K8s Provisioner强隔离、多用户

K8s Provisioner

环境变量

K8S_NAMESPACE=deer-flow
SANDBOX_IMAGE=deerflow-arduino-sandbox:latest
# 或改为仓库中的 all-in-one 镜像
DEER_FLOW_ROOT=/absolute/path/to/deer-flow

config.yaml

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

PVC（可选）

USERDATA_PVC_NAME=deer-flow-userdata-pvc
SKILLS_PVC_NAME=deer-flow-skills-pvc

设置 USERDATA_PVC_NAME 时，Provisioner 按线程使用子路径 threads/{thread_id}/user-data。

nginx

路由定义在 docker/nginx/nginx.conf：对外仅反代 frontend 与 backend-go；worker 不参与浏览器路径。

认证（Better Auth）

  1. BETTER_AUTH_SECRET：强随机，≥32 字符
  2. BETTER_AUTH_URL：公网访问根 URL
openssl rand -base64 32

资源建议

组件最低推荐
backend-go1 vCPU / 512MB2 vCPU / 1GB
worker（Agent）2 vCPU / 4GB4 vCPU / 8GB
前端0.5 vCPU / 512MB1 vCPU / 1GB
沙箱（每会话）1 vCPU / 1GB2 vCPU / 2GB

部署后检查

curl -sf http://localhost:2026/health
curl -sf http://localhost:2026/api/models

全本地调试时可额外：curl -sf http://localhost:8001/health（worker，仅本机）。

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