DeerFlow贡献指南：开启你的开发之旅

感谢你对DeerFlow项目的关注与贡献意愿！本文将详细指导你如何设置开发环境，并熟悉DeerFlow的开发工作流程。

一、开发环境设置

DeerFlow提供了两种开发环境选项，其中Docker方案因其一致性和便捷性而被强烈推荐。

1. Docker开发环境（推荐）

Docker提供了一个一致、隔离的环境，所有依赖项（如Node.js、Python、Nginx）都已预配置，无需在本地机器上单独安装。

前置条件：

• Docker Desktop 或 Docker Engine
• pnpm (用于优化缓存)

设置步骤：

1. 配置应用： 首先，复制示例配置文件并设置API密钥。

   # 复制示例配置文件
   cp config.example.yaml config.yaml
   
   # 设置你的API密钥，例如OpenAI API Key
   export OPENAI_API_KEY="your-key-here"
   # 或者直接编辑 config.yaml 文件
   

2. 初始化Docker环境（首次运行）： 执行初始化命令，这将构建Docker镜像、安装前端和后端依赖，并配置pnpm缓存共享。

   make docker-init
   

   此命令将完成以下任务：

   • 构建Docker镜像。
   • 安装前端依赖 (使用 pnpm)。
   • 安装后端依赖 (使用 uv)。
   • 将 pnpm 缓存与宿主机共享，以加快后续构建速度。

3. 启动开发服务： 启动所有开发服务，支持热重载。make docker-start 会读取 config.yaml，并仅在 provisioner/Kubernetes 沙盒模式下启动 provisioner 服务。

   make docker-start
   

   • 前端代码修改会自动重新加载。
   • 后端代码修改会触发自动重启。
   • LangGraph 服务支持热重载。

4. 访问应用：

   • Web界面: `
   • API网关: `
   • LangGraph服务: `

常用Docker命令：

命令	功能描述
make docker-init	构建自定义k3s镜像，启动Docker服务（首次）
make docker-start	启动Docker服务（支持模式感知，端口2026）
make docker-stop	停止Docker开发服务
make docker-logs	查看所有Docker开发日志
make docker-logs-frontend	查看Docker前端服务日志
make docker-logs-gateway	查看Docker网关服务日志

Linux下的Docker权限问题：

如果在Linux系统上运行 make docker-init、make docker-start 或 make docker-stop 时遇到“permission denied”错误，通常是因为当前用户没有访问Docker守护进程套接字的权限。

推荐解决方案： 将当前用户添加到 docker 用户组。

1. 确认 docker 用户组存在：

   getent group docker
   

2. 将当前用户添加到 docker 用户组：

   sudo usermod -aG docker $USER
   

3. 应用新的用户组权限： 最可靠的方法是完全注销当前会话并重新登录。如果只想刷新当前shell会话，可以运行：

   newgrp docker
   

4. 验证Docker访问权限：

   docker ps
   

   如果 docker ps 仍然报告权限错误，请务必完全注销并重新登录后再重试DeerFlow命令。

Docker架构概览：

宿主机 (Host Machine)
  ↓
Docker Compose (deer-flow-dev)
 ├─► nginx (端口 2026) ← 反向代理
 ├─► web (端口 3000) ← 前端服务 (支持热重载)
 ├─► api (端口 8001) ← 网关API (支持热重载)
 ├─► langgraph (端口 2024) ← LangGraph服务 (支持热重载)
 └─► provisioner (可选, 端口 8002) ← 仅在 provisioner/K8s 沙盒模式下启动

Docker开发优势：

• ✅ 跨机器环境一致性
• ✅ 无需本地安装Node.js, Python, Nginx
• ✅ 依赖和服务隔离
• ✅ 易于清理和重置
• ✅ 所有服务均支持热重载
• ✅ 模拟生产环境

2. 本地开发环境

如果你倾向于在本地机器上直接运行服务，可以选择此方案。

前置条件：

运行 make check 检查所有必需工具是否已安装：

• Node.js 22+
• pnpm
• uv (Python包管理器)
• nginx

设置步骤：

1. 配置应用： 与Docker设置相同，复制配置文件并设置API密钥。

   cp config.example.yaml config.yaml
   export OPENAI_API_KEY="your-key-here"
   

2. 安装依赖：

   make install
   

3. 运行开发服务器： 此命令将启动所有服务，包括Nginx。

   make dev
   

4. 访问应用：

   • Web界面: ` 所有API请求都会通过Nginx自动代理。

手动控制服务：

如果你需要单独启动各项服务，可以按以下步骤操作：

• 启动后端服务：

  • 终端1：启动LangGraph服务 (端口 2024)

    cd backend
    make dev
    

  • 终端2：启动网关API (端口 8001)

    cd backend
    make gateway
    

  • 终端3：启动前端服务 (端口 3000)

    cd frontend
    pnpm dev
    

• 启动Nginx：

  make nginx
  # 或者直接运行：
  nginx -c $(pwd)/docker/nginx/nginx.local.conf -g 'daemon off;'
  

Nginx配置职责：

Nginx作为统一入口，负责以下功能：

• 统一入口点： 在端口 2026 提供服务。
• 路由：
  • 将 /api/langgraph/* 请求路由到 LangGraph 服务 (端口 2024)。
  • 将其他 /api/* 请求路由到 网关API (端口 8001)。
  • 将非API请求路由到 前端服务 (端口 3000)。
• CORS处理： 集中处理跨域资源共享。
• SSE/流式支持： 为实时代理响应提供支持。
• 超时优化： 针对长时间运行的操作进行优化。

二、项目结构

DeerFlow的项目目录结构清晰，便于开发者理解和定位代码：

deer-flow/
├── config.example.yaml          # 配置模板文件
├── extensions_config.example.json # MCP和Skills配置模板
├── Makefile                     # 构建和开发命令集
├── scripts/
│   └── docker.sh                # Docker管理脚本
├── docker/
│   ├── docker-compose-dev.yaml  # Docker Compose开发环境配置
│   └── nginx/
│       ├── nginx.conf           # Docker环境的Nginx配置
│       └── nginx.local.conf     # 本地开发环境的Nginx配置
├── backend/                     # 后端应用目录
│   ├── src/
│   │   ├── gateway/             # 网关API (端口 8001)
│   │   ├── agents/              # LangGraph代理 (端口 2024)
│   │   ├── mcp/                 # 模型上下文协议 (Model Context Protocol) 集成
│   │   ├── skills/              # 技能系统
│   │   └── sandbox/             # 沙盒执行环境
│   ├── docs/                    # 后端文档
│   └── Makefile                 # 后端相关命令
├── frontend/                    # 前端应用目录
│   └── Makefile                 # 前端相关命令
└── skills/                      # 代理技能目录
    ├── public/                  # 公共技能
    └── custom/                  # 自定义技能

三、系统架构

DeerFlow的系统架构设计旨在提供高效、可扩展的服务：

浏览器 (Browser)
  ↓
Nginx (端口 2026) ← 统一入口点
 ├─► 前端 (端口 3000) ← / (非API请求)
 ├─► 网关API (端口 8001) ← /api/models, /api/mcp, /api/skills, /api/threads/*/artifacts
 └─► LangGraph 服务 (端口 2024) ← /api/langgraph/* (代理交互)

四、开发工作流程

遵循以下标准流程进行贡献：

1. 创建功能分支：

   git checkout -b feature/your-feature-name
   

2. 进行修改： 在开发环境中进行代码修改，利用热重载功能实时查看效果。
3. 充分测试： 确保你的修改经过彻底测试。
4. 提交更改：

   git add .
   git commit -m "feat: description of your changes"
   

5. 推送并创建拉取请求 (Pull Request)：

   git push origin feature/your-feature-name
   

五、测试与代码规范

1. 测试

• 后端测试：

  cd backend
  uv run pytest
  

• 前端检查：

  cd frontend
  pnpm check
  

2. PR回归测试

每个拉取请求都会自动运行后端回归测试工作流 (.github/workflows/backend-unit-tests.yml)，其中包括：

• tests/test_provisioner_kubeconfig.py
• tests/test_docker_sandbox_mode_detection.py

3. 代码风格

• 后端 (Python): 使用 ruff 进行代码检查和格式化。
• 前端 (TypeScript): 使用 ESLint 和 Prettier 进行代码检查和格式化。

六、获取帮助与文档

• 查阅现有问题： 查看项目的 Issues 页面。
• 阅读文档：
  • 配置指南 - 设置与配置。
  • 架构概述 - 技术架构。
  • MCP设置指南 - 模型上下文协议配置。
• 参与讨论： 在 Discussions 中提出问题。

七、许可协议

通过向DeerFlow贡献代码，你同意你的贡献将遵循MIT许可协议。

---

👉 如果你需要 ChatGPT 代充 / Claude / Claude Code / 镜像 / 中转 API：

• 购买 / 了解更多：ai4.plus
• 备用入口：kk4099.com

---