DeerFlow 2.0 部署原理与核心配置文件指南——给科技小白的 AI 工作助手解析
·
目录
第一章：什么是 DeerFlow 2.0？
1.1 用厨房比喻理解 AI 系统
想象一下，您家有一个超级智能厨房机器人，它能够：
- 🤖 自动烹饪各种美食（AI 处理任务）
- 🤖 记住您的饮食习惯（学习用户习惯）
- 🤖 自动清理厨房（管理临时文件）
这个智能厨房机器人的名字就叫 DeerFlow 2.0！
1.2 厨房机器人的组成部分
┌────────────────────────────────────────────────────────┐
│ 您的智能厨房（电脑） │
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌─────────────┐│
│ │ 智能菜谱打印机 │ │ 独立操作台 │ │ 网页显示屏 ││
│ │ (Ollama) │ │ (Docker) │ │ (Web 界面) ││
│ └───────────────┘ └───────────────┘ └─────────────┘│
│ │
│ ┌───────────────┐ │
│ │ AI 厨师 │ │
│ │ (Qwen3.5) │ │
│ └───────────────┘ │
│ │
│ ┌───────────────┐ │
│ │ 自动保鲜柜 │ ← 每次修改菜谱后自动备份 │
│ │ (Git Hooks) │ │
│ └───────────────┘ │
└────────────────────────────────────────────────────────┘
各个部分的作用：
-
智能菜谱打印机（Ollama）
- 作用：存储各种菜谱（AI 模型）
- 比喻：就像打印厨房用书的机器
- 位置：
D:\deer-flow目录中
-
独立操作台（Docker）
- 作用：每个菜谱在独立的干净操作台上制作
- 比喻：就像厨房里的不同操作台，互不干扰
- 优点：一个菜谱的食材洒了，不会弄脏其他操作台
-
AI 厨师（Qwen3.5）
- 作用：根据菜谱做菜（处理 AI 任务）
- 比喻：就像厨房里的 AI 厨师，根据菜谱做菜
- 特点：聪明、听话、会做菜
-
网页显示屏（Web 界面）
- 作用：显示烹饪进度和结果
- 比喻：就像厨房的大屏幕，显示当前在做什么菜
- 位置：访问
http://localhost:2026
-
自动保鲜柜（Git Hooks）
- 作用：每次修改菜谱后自动保存备份
- 比喻：就像厨房的保鲜柜，随时保存当前菜谱版本
- 优点：即使意外打翻了当前菜谱，也能从保鲜柜找回
- 注意：自动保鲜功能需要先运行
install-hooks.ps1安装脚本才会生效哦！
1.3 为什么需要这么多组件？
比喻：就像做饭需要锅、铲子、菜谱
-
没有菜谱打印机（Ollama）
- 问题：不知道用什么食材（AI 模型）
- 结果：厨师（Qwen3.5）不知道做什么菜
-
没有独立操作台（Docker）
- 问题：所有菜混在一起做
- 结果：一个菜做错了，影响其他菜
-
没有网页显示屏（Web 界面）
- 问题：不知道厨房在做什么
- 结果：无法监控烹饪进度
总结：每个组件都有特定作用，缺一不可！
第二章：核心配置文件详解
2.1 什么是配置文件？
比喻：就像房子的"说明书"
- 配置文件告诉厨房机器人：
- ✅ 用什么食材（AI 模型）
- ✅ 怎么烹饪（处理流程）
- ✅ 如何启动各个操作台（容器编排）
- ✅ 如何接待客人（网页路由）
2.2 核心配置文件清单
┌─────────────────────────────────────────────────────────┐
│ 核心配置文件清单（重要程度） │
├─────────────────────────────────────────────────────────┤
│ │
│ 🚨 最高风险文件（一旦损坏，系统无法运行） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 1. config.yaml │ │
│ │ 作用：告诉 AI 厨师用什么菜谱（模型） │ │
│ │ 比喻：菜谱选择表 │ │
│ │ 位置：D:\deer-flow\config.yaml │ │
│ │ 错误表现：无法连接 AI 模型、无响应 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 🚨 2. docker-compose-windows.yaml │
│ 作用：启动所有操作台的开关 │
│ 比喻：厨房启动清单 │
│ 错误表现：所有操作台无法启动 │
│ │
│ 🟠 中风险文件（影响部分功能） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 3. nginx.conf │ │
│ │ 作用：网页显示屏的指引规则 │ │
│ │ 比喻：接待员的指引 │ │
│ │ 位置：D:\deer-flow\docker\nginx\nginx.conf │ │
│ │ 错误表现：网页打不开、404 错误 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 🟠 4. extensions_config.json │
│ 作用：扩展功能开关 │
│ 比喻：厨房扩展工具箱 │
│ 错误表现：扩展功能失效 │
│ │
│ 🟠 5. .env（环境变量） │
│ 作用：认证信息 │
│ 比喻：厨房门禁密码 │
│ 错误表现：无法连接 Feishu 等 │
│ │
│ 🟢 低风险文件（影响辅助功能） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 6. .gitignore │ │
│ │ 作用：告诉自动保鲜柜哪些文件不用备份 │ │
│ │ 比喻：厨房清理清单 │ │
│ │ 错误表现：备份不完整 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
2.3 核心配置文件详细解读
🚨 config.yaml（最高风险）
比喻：菜谱选择表
# 配置文件示例（简化版）
models:
- name: qwen3.5:9b # 菜谱名称
display_name: Qwen 3.5 9B # 菜谱展示名称
use: langchain_openai:ChatOpenAI # 用什么打印机
model: qwen3.5:9b # 实际使用的模型
base_url: http://host.docker.internal:11434/v1 # 打印机地址
作用：
- 告诉 AI 厨师用哪个菜谱（模型）
- 告诉厨师菜谱在哪个打印机里（Ollama 地址）
- 设置厨师做菜的风格（temperature）
损坏后的错误：
- ❌
No models available- 厨师找不到菜谱 - ❌
Connection refused- 打印机不在指定地址 - ❌
Model not found- 菜谱名称不对
如何恢复：
- 找到备份文件：
config.yaml.bak.时间戳 - 复制备份覆盖原文件
- 彻底重建容器（因为 AI 厨师会记老菜谱，需要清空记忆）
🚨 docker-compose-windows.yaml（最高风险）
比喻：厨房启动清单
# 配置文件示例（简化版）
services:
nginx: # 操作台 1
image: nginx:alpine # 用什么操作台
ports:
- "2026:2026" # 显示屏端口
volumes:
- ../config.yaml:/app/config.yaml # 挂载菜谱表（注意相对路径）
gateway: # 操作台 2
image: docker-gateway # 什么网关
ports:
- "8001:8001" # API 端口
langgraph: # 操作台 3
image: docker-langgraph # AI 运行时
ports:
- "2024:2024" # AI 端口
路径小贴士
注意看volumes那行，前面有个../。这是因为启动清单（docker-compose 文件）是放在D:\deer-flow\docker文件夹里的，而菜谱（config.yaml）在上一级目录D:\deer-flow\。这里的..就是“回到上一级文件夹找”的意思。如果您移动了文件位置，这里的路径也得跟着改哦！
作用：
- 启动所有操作台（容器）
- 设置每个操作台的端口
- 挂载配置文件到操作台
损坏后的错误：
- ❌
Cannot find container "nginx"- 操作台找不到 - ❌
Service not found- 启动清单错误 - ❌
Port already in use- 端口被占用
如何恢复：
- 找到备份文件：
docker-compose-windows.yaml.bak.时间戳 - 复制备份覆盖原文件
- 删除所有容器并重新启动
🟠 nginx.conf（中风险）
比喻：接待员的指引规则
# 配置文件示例（简化版）
upstream gateway {
server gateway:8001; # 指向 API 网关
}
location /api/langgraph/ { # 语言接口路径
rewrite ^/api/langgraph/(.*) /$1 break; # 重写规则
proxy_pass http://langgraph; # 转发到 AI 运行时
}
作用：
- 告诉网页显示屏如何接收请求
- 将请求转发到正确的操作台
- 处理 CORS 跨域问题
损坏后的错误：
- ❌
404 Not Found- 路径找不到 - ❌
502 Bad Gateway- 转发失败 - ❌
Connection refused- 目标操作台未启动
如何恢复：
- 找到备份文件：
nginx.conf.bak.时间戳 - 复制备份覆盖原文件
- 重启 nginx 容器
🟠 extensions_config.json（中风险）
比喻：厨房扩展工具箱
{
"enabled": false, // 工具箱是否启用
"agents": {} // 扩展工具列表
}
作用：
- 控制扩展功能是否启用
- 配置 Feishu 等外部工具
- 管理 Agent 工具
损坏后的错误：
- ❌
Feishu connection failed- Feishu 连接失败 - ❌
Agent not found- Agent 工具未找到 - ❌
Extension disabled- 扩展功能未启用
如何恢复：
- 找到备份文件：
extensions_config.json.bak.时间戳 - 复制备份覆盖原文件
- 重启服务
🟠 .env（中风险）
比喻：厨房门禁密码
# 配置文件示例
DEER_FLOW_FEISHU_APP_ID=********** # Feishu 应用 ID
DEER_FLOW_FEISHU_APP_SECRET=*********** # Feishu 密钥
DEER_FLOW_CONFIG_PATH=/app/backend/config.yaml # 配置路径
作用：
- 存储认证信息
- 设置环境变量
- 配置外部服务连接
损坏后的错误：
- ❌
Authentication failed- 认证失败 - ❌
Invalid app_id- 应用 ID 无效 - ❌
Secret mismatch- 密钥不匹配
如何恢复：
- 找到备份文件：
.env.bak.时间戳 - 复制备份覆盖原文件
- 确保文件权限正确（不可读）
🟢 .gitignore（低风险）
比喻：厨房清理清单
# 配置文件示例
.env* # 不要备份认证信息
data/memory.json* # 不要备份内存数据
node_modules/ # 不要备份节点模块
作用：
- 告诉 Git 哪些文件不用备份
- 保护敏感信息不被泄露
- 避免备份无用文件
损坏后的错误：
- ❌ 敏感信息被意外提交到 Git
- ❌ 有用文件被 Git 忽略
- ❌ 备份不完整
如何恢复：
- 找到备份文件：
.gitignore.bak.时间戳 - 复制备份覆盖原文件
- 执行
git add重新跟踪文件
第三章：配置文件损坏后的错误表现
3.1 错误对照表
| 配置文件 | 损坏后的错误现象 | 修复方式 | 风险等级 |
|---|---|---|---|
| config.yaml | ❌ 无法连接 AI 模型 ❌ 页面显示"No models available" ❌ 命令无响应 |
从备份恢复：config.yaml.bak.时间戳并强制重建容器 |
🔴 最高 |
| docker-compose-windows.yaml | ❌ 所有服务无法启动 ❌ Docker 提示"service not found" ❌ 端口冲突 |
从备份恢复 重启 Docker |
🔴 最高 |
| nginx.conf | ❌ 网页打不开 ❌ 显示"404 Not Found" ❌ API 路由失败 |
从备份恢复 重启 nginx |
🟠 中 |
| extensions_config.json | ❌ Feishu 连接失败 ❌ 扩展功能不可用 ❌ Agent 工具未找到 |
从备份恢复 重启服务 |
🟠 中 |
| .env | ❌ 认证失败 ❌ 无法连接 Feishu ❌ 密钥错误 |
从备份恢复 确保权限 |
🟠 中 |
| .gitignore | ❌ 备份不完整 ❌ 敏感信息泄露 ❌ 文件被忽略 |
从备份恢复 检查 Git 状态 |
🟢 低 |
3.2 错误恢复流程图
┌─────────────────────────────────────────────────────────┐
│ 配置文件损坏后的恢复流程 │
├─────────────────────────────────────────────────────────┤
│ │
│ [发现错误现象] │
│ │ │
│ ▼ │
│ [确认损坏的配置文件] │
│ │ │
│ ▼ │
│ [查找备份文件] │
│ │ │
│ ▼ │
│ [备份文件存在吗？] │
│ │ │
│ ├─ 是 ──► [复制备份覆盖原文件] │
│ │ │
│ │ │
│ ▼ │
│ [备份文件不存在？] │
│ │ │
│ ├─ 是 ──► [使用 Git 版本恢复] │
│ │ │
│ │ │
│ ▼ │
│ [使用 Git 恢复] │
│ │ │
│ ▼ │
│ [git checkout 配置文件] │
│ │ │
│ ▼ │
│ [验证恢复成功] │
│ │ │
│ ▼ │
│ [彻底重启服务] │
│ │ │
│ ▼ │
│ [测试功能是否正常] │
│ │ │
│ ▼ │
│ [完成恢复] │
│ │
└─────────────────────────────────────────────────────────┘
3.3 手动恢复步骤（以 config.yaml 为例）
步骤 1：确认错误
# 在 PowerShell 中执行
docker-compose restart
# 查看输出是否有错误
步骤 2：查找备份文件
# 列出所有备份文件
Get-ChildItem "D:\deer-flow\config.yaml.bak*" | Select-Object Name, LastWriteTime
# 预期输出：
# Mode LastWriteTime Length Name
# ---- ------------- ------ ----
# -a---- 2026/4/21 16:30 35601 config.yaml.bak.20260421-1630
步骤 3：复制备份覆盖原文件
# 方法 1：直接复制
Copy-Item "D:\deer-flow\config.yaml.bak.20260421-1630" "D:\deer-flow\config.yaml" -Force
# 方法 2：使用 Git（更推荐）
git checkout config.yaml
步骤 4：彻底重建并验证
这里不能只用
restart哦！
因为 Docker 里的 AI 厨师（容器）有时候会记住旧的菜谱。只重启开关，它脑子里想的还是之前的错误配置。
正确做法是：把厨房清空，重新照着新菜谱表布置一遍！
请在 PowerShell 中依次执行以下“清空重建”命令：
# 1. 进入正确的目录（非常重要！）
cd D:\deer-flow\docker
# 2. 彻底关停并删除所有操作台（清空厨房）
docker-compose down
# 3. 重新启动并强制根据最新菜谱表创建操作台（--force-recreate 就是“必须重建”的意思）
docker-compose up -d --force-recreate
# 4. 访问网页界面验证
start http://localhost:2026
预期：网页正常打开，AI 模型列表显示正常，不再报错。
步骤 5：使用 Git 版本恢复（推荐）
# 使用 Git 恢复到上次提交
git checkout config.yaml
# 查看恢复状态
git status
# 预期输出：
# On branch main
# Changes not staged for commit:
# (use "git add/rm <file>..." to update what will be committed)
# (use "git restore <file>..." to discard changes in working directory)
# modified: config.yaml
# no changes added to commit (use "git add")
3.4 使用 Git Hooks 自动备份
优势：
- ✅ 每次 commit 自动备份
- ✅ 备份文件自动创建
- ✅ 无需手动操作
- ✅ 永久保护配置
温馨提示
想要享受这个“自动保鲜柜”的服务，您需要先运行一次安装命令：.\install-hooks.ps1（在项目根目录下执行）。
如果还没运行过这个脚本，直接 git commit 是不会自动备份的哦。
工作流程：
修改配置文件
↓
git add + commit
↓
pre-commit 钩子触发
├─ 自动暂存所有核心配置文件
└─ 输出：Auto-staged: config.yaml
↓
commit 成功
↓
post-commit 钩子触发
├─ 创建备份文件（文件名.bak.时间戳）
└─ 输出：Backed up: config.yaml → config.yaml.bak.20260421-1630
↓
完成！
第四章：总结
4.1 核心要点回顾
- DeerFlow 2.0 是由多个组件组成的智能厨房机器人
- 核心配置文件决定了系统如何工作
- 自动备份机制保护您的配置不被丢失
- 损坏配置文件后，可从备份或 Git 版本恢复
4.2 给科技小白的建议
-
不要频繁修改核心配置文件
- ✅ 只在需要调整 AI 模型时修改 config.yaml
- ✅ 只在需要调整网页路由时修改 nginx.conf
-
修改配置文件前
- ⚠️ 先查看备份文件是否存在
- ⚠️ 记录当前配置内容（截图或复制）
- ⚠️ 修改后测试功能是否正常
-
遇到问题时
- 🔍 先看错误现象（错误对照表）
- 🔍 查找备份文件
- 🔍 使用 Git 恢复
- 🔍 恢复后记得用
docker-compose up -d --force-recreate彻底重建，不要只重启 - 🔍 最后才考虑重新部署
4.3 快速恢复命令
# 方法 1：从备份文件恢复
Copy-Item "config.yaml.bak.时间戳" "config.yaml"
# 方法 2：使用 Git
git checkout config.yaml
# 方法 3：彻底重建容器（让配置生效）
cd D:\deer-flow\docker
docker-compose down
docker-compose up -d --force-recreate
# 方法 4：查看所有可用版本
git log -- config.yaml
# 方法 5：查看版本历史
git log --oneline -- config.yaml
附录：文件位置速查表
| 文件 | 路径 | 作用 |
|---|---|---|
| config.yaml | D:\deer-flow\config.yaml |
AI 模型配置 |
| docker-compose-windows.yaml | D:\deer-flow\docker\docker-compose-windows.yaml |
容器编排 |
| nginx.conf | D:\deer-flow\docker\nginx\nginx.conf |
网页路由 |
| extensions_config.json | D:\deer-flow\backend\extensions_config.json |
扩展配置 |
| .env | D:\deer-flow\.env |
环境变量 |
| .gitignore | D:\deer-flow\.gitignore |
Git 忽略规则 |
| 备份文件 | *.bak.时间戳 |
自动备份 |
| Git Hooks 安装脚本 | D:\deer-flow\install-hooks.ps1 |
开启自动保鲜柜功能 |
祝您玩的开心！
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
11
0- 0
已为社区贡献2条内容
所有评论(0)