技术小白本地部署DeerFlow 2.0 指南（docker方式+ollama+Qwen3.5）——环境配置、错误排查、硬伤防范、故障排除完整方案(为方便阅读，调整格式重新发布)

📖 前言

作为一个非技术人员，我用了一段时间OpenClaw，它确实在工作中，给予我很多帮助，但是有时总是莫名其妙的出问题，尤其是记忆问题，我按照网上的方法进行了很多改进，但仍然效果不佳。后看到DeerFlow 2.0的系统架构更加合理，它是一个更加强大的 AI 开发平台，所以就尝试在本地部署它，同时调用我本地Qwen3.5模型，以协助我完成更为复杂的长任务。但它的部署过程并不顺利，本周末我自己配了一遍，遇到很多坑，特写下本指南，记录完成从零开始的完整部署过程，以及所有可能出现的错误及解决方法。希望能帮助像我一样的技术小白" 核心提示：Deerflow2.0架构满分，工程成熟度欠佳，对非技术人员不友好。如果您不急于现在用，可以过几个月再学习，纯属个人观点，欢迎批评指正！ 最后说个自己的经验，如果技术小白想部署一些新东西，自己动手的同时可以利用openclaw。比较有效的方法是把新工具的说明书先喂给它，举例说明，比如您看了这篇文章后，也想部署deerflow2.0+本地qwen3.5,您可以把DF相关md文档，以及我这篇文章全文（因为文中除了方法论外，更重要的是记录了多种错误，并分析了原因，给出了解决办法）喂给它，这样你就可以少走很多弯路。

📑 目录

• 5.1 config.yaml 配置详解
• 5.2 docker-compose-windows.yaml 配置详解
• 5.3 nginx.conf 配置详解
• 5.4 extensions_config.json 配置

附录

1. 环境准备与系统要求

1.1 系统基础环境

操作系统要求

• Windows：10/11 Home/Pro/Enterprise
• Docker Desktop：24.0+
• WSL2：必须启用
• CPU 架构：x86_64 / arm64

硬件要求

软件依赖

# 必需软件
– Docker Desktop: 24.0+
– Docker Compose: 2.20+
– Python: 3.10+ (通过 Docker 容器使用)
– Node.js: 18+ (通过 Docker 容器使用)
– Git: 2.30+

# 可选但推荐
– WSL2: 必须（Windows 平台）
– NVIDIA 驱动：550+（使用 GPU 加速）
– curl: 已预装
– PowerShell: 7.0+

1.2 网络环境配置

国内镜像源设置（必需）

Docker 镜像源配置

# 设置 Docker 镜像源为清华
New-Item -Path "$env:LOCALAPPDATA\\Docker\\settings.json" -Force

$settings = Get-Content -Path "$env:LOCALAPPDATA\\Docker\\settings.json" -Raw
$settings | ConvertFrom-Json

# 添加镜像源配置
$settings.mirrors = @{
"https://hub.docker.com" = "https://docker.mirrors.ustc.edu.cn"
}

$settings | ConvertTo-Json -Depth 100 | Set-Content -Path "$env:LOCALAPPDATA\\Docker\\settings.json" -NoNewline

PyPI 镜像源配置

# 设置 pip 清华源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 验证配置
pip config list

# 预期输出
global.index-url=https://pypi.tuna.tsinghua.edu.cn/simple

NPM 镜像源配置

npm config set registry https://registry.npmmirror.com

# 验证配置
npm config get registry

# 预期输出：https://registry.npmmirror.com

1.3 版本验证

# 验证 Docker 版本
docker –version

# 预期输出：Docker version 24.0.0

# 验证 Docker Compose 版本
docker compose version

# 预期输出：Docker Compose version 2.20.0

# 验证 Git 版本
git –version

# 预期输出：git version 2.30.0

# 验证网络连接
curl -I http://google.com

# 预期输出：HTTP/2 200

# 验证端口可用性
Test-NetConnection -ComputerName localhost -Port 2026

1.4 环境检查清单

执行以下命令验证环境：

# 检查 Docker 服务
docker ps

# 检查磁盘空间
df -h | Select-String "overlay2"

# 检查内存
[System.Management.WMI.ManagementObject]::CreateInstanceFromNamespace(
'root\\cimv2', 'Win32_ComputerSystem'
).TotalVisibleMemorySize

# 检查 GPU（NVIDIA）
nvidia-smi

# 检查 WSL2 状态
wsl –list –verbose

检查清单：

• Docker Desktop 已安装并运行
• WSL2 已启用
• 磁盘空间充足（≥256GB）
• 内存充足（≥16GB）
• 网络连接正常
• 国内镜像源已配置
• Docker 版本≥24.0

2. Docker 环境配置

2.1 Docker Desktop 配置

启用 WSL2 后端（Windows 必需）

# 检查当前后端
wsl -l -v

# 设置为 WSL2
wsl –set-default-version 2

# 重启 Docker Desktop
Restart-Service docker-desktop

配置资源限制

# 编辑 Docker 设置
notepad "$env:LOCALAPPDATA\\Docker\\settings.json"

# 添加资源限制配置
{
"features": {
"containerd-overlayfuse-volumes": true
},
"resources": {
"memory": "16gb",
"cpus": "12",
"disk": "200gb"
}
}

2.2 Docker 镜像拉取

拉取 DeerFlow 镜像

# 使用国内镜像源拉取
docker pull –mirror https://docker.mirrors.ustc.edu.cn \\
harveyff/deerflow:v1.0.17

# 验证镜像下载
docker images | Find-String deerflow

# 预期输出
REPOSITORY TAG IMAGE ID SIZE
harveyff/deerflow v1.0.17 abc123... 1.049GB

拉取其他镜像

# Nginx（反向代理）
docker pull nginx:alpine

# PostgreSQL（持久化）
docker pull postgres:15-alpine

# Redis（任务队列）
docker pull redis:7-alpine

# 验证所有镜像
docker images | Select-String "deerflow|nginx|postgres|redis"

2.3 项目目录准备

# 创建项目目录
$projectPath = "D:\\deer-flow"
if (!(Test-Path $projectPath)) {
New-Item -ItemType Directory -Path $projectPath -Force
}

# 设置目录权限
icacls "$projectPath" /grant:r "Users:(OI)(CI)R"

# 进入项目目录
cd "$projectPath"

3. 项目初始化与克隆

3.1 Git 克隆项目

# 克隆官方仓库
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# 确认版本
git describe –tags

# 预期输出：v1.0.17

# 拉取所有分支
git fetch –all
git pull –all

3.2 项目结构说明

deer-flow/
├── backend/ # 后端代码
│ ├── packages/ # 依赖包
│ ├── skills/ # 技能目录
│ └── .venv/ # Python 虚拟环境
├── frontend/ # 前端代码
│ ├── components/ # 组件
│ └── public/ # 静态资源
├── docker/ # Docker 配置文件
│ ├── nginx/ # Nginx 配置
│ └── docker-compose-windows.yaml # 启动配置
├── skills/ # 技能目录
├── docker-compose-windows.yaml # 主启动配置
└── README.md # 项目说明

3.3 版本确认

# 检查 Git 版本
git describe –tags

# 预期输出：v1.0.17

# 如果版本不符，需要更新
git fetch origin main
git checkout main
git pull origin main

4. Ollama 服务配置

4.1 Ollama 安装

# 下载 Ollama Windows 安装包
# 访问：https://ollama.ai/download

# 或使用 winget 安装
winget install Ollama.Ollama

# 验证安装
ollama –version

# 预期输出：ollama version X.X.X

4.2 启动 Ollama 服务

# 启动服务（后台运行）
ollama serve

# 或使用 Windows 服务（可选）
sc create Ollama binPath= "ollama serve" start= auto

4.3 设置环境变量

# 设置 Ollama 监听所有网络接口
$env:OLLAMA_HOST="0.0.0.0:11434"

# 验证监听端口
netstat -ano | findstr 11434

# 预期输出：TCP 0.0.0.0:11434 0.0.0.0:0 LISTENING

4.4 拉取模型

# 拉取 qwen3.5:9b 模型
ollama pull qwen3.5:9b

# 验证模型
ollama list

# 预期输出
NAME ID SIZE MODIFIED
qwen3.5:9b abc123... 6.6GB 2026-04-19

4.5 Ollama 配置验证

# 验证 API 访问
curl http://localhost:11434/api/tags

# 预期输出
[
{
"name": "qwen3.5:9b",
"model": "qwen3.5:9b",
"modified_at": "2026-04-19T18:00:00Z",
"size": 6677234,
"digest": "sha256:abc123…"
}
]

5. 配置文件详解

5.1 config.yaml 配置详解

完整配置文件

# Configuration for the DeerFlow application
config_version: 7

# Logging
log_level: info

# Token Usage
token_usage:
enabled: false

# Models Configuration
models:
# 本地 Ollama 模型配置
– name: qwen3.5:9b
display_name: Qwen 3.5 9B
use: langchain_ollama:ChatOllama
model: qwen3.5:9b
base_url: http://192.168.3.162:11434/v1
num_predict: 8192
temperature: 0.7
reasoning: true
supports_thinking: true
supports_vision: false
request_timeout: 60
max_retries: 2

# Tool Groups Configuration
tool_groups:
– name: web
– name: file:read
– name: file:write
– name: bash

# Tools Configuration
tools:
# Web 搜索工具
– name: web_search
group: web
use: deerflow.community.ddg_search.tools:web_search_tool
max_results: 5

# Web 抓取工具
– name: web_fetch
group: web
use: deerflow.community.jina_ai.tools:web_fetch_tool
timeout: 10

# 图片搜索工具
– name: image_search
group: web
use: deerflow.community.image_search.tools:image_search_tool
max_results: 5

# 文件操作工具
– name: ls
group: file:read
use: deerflow.sandbox.tools:ls_tool

– name: read_file
group: file:read
use: deerflow.sandbox.tools:read_file_tool

– name: write_file
group: file:write
use: deerflow.sandbox.tools:write_file_tool

– name: str_replace
group: file:write
use: deerflow.sandbox.tools:str_replace_tool

# Bash 执行工具
– name: bash
group: bash
use: deerflow.sandbox.tools:bash_tool

# Tool Search Configuration
tool_search:
enabled: false

# Sandbox Configuration
uploads:
pdf_converter: auto

sandbox:
use: deerflow.sandbox.local:LocalSandboxProvider
allow_host_bash: false
pdf_converter: auto
bash_output_max_chars: 20000
read_file_output_max_chars: 50000
ls_output_max_chars: 20000

# Memory Configuration
memory:
enabled: true
storage_path: memory.json
debounce_seconds: 30
model_name: null
max_facts: 100
fact_confidence_threshold: 0.7
injection_enabled: true
max_injection_tokens: 2000

# Checkpointer Configuration
checkpointer:
type: memory # 生产环境建议改为 postgres

# Title Generation Configuration
title:
enabled: true
max_words: 6
max_chars: 60
model_name: null

# Summarization Configuration
summarization:
enabled: true
model_name: null
trigger:
– type: tokens
value: 15564
keep:
type: messages
value: 10
trim_tokens_to_summarize: 15564

# Custom Agent Management API
agents_api:
enabled: false

# Skill Self-Evolution Configuration
skill_evolution:
enabled: false
moderation_model_name: null

关键配置项说明

5.2 docker-compose-windows.yaml 配置详解

完整配置文件

# DeerFlow Docker Compose Configuration
# 适用于 Windows/Docker Desktop

services:
# Nginx 反向代理
nginx:
image: nginx:alpine
container_name: deer–flow–nginx
ports:
– "2026:2026"
volumes:
– ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf.template:ro
environment:
– LANGGRAPH_UPSTREAM=langgraph:2024
– LANGGRAPH_REWRITE=/
command: >
sh -c "envsubst '\\$\\$LANGGRAPH_UPSTREAM \\$\\$LANGGRAPH_REWRITE'
< /etc/nginx/nginx.conf.template > /etc/nginx/nginx.conf
&& nginx -g 'daemon off;'"
depends_on:
– frontend
– gateway
networks:
– deer–flow
restart: unless–stopped

# Frontend 前端服务
frontend:
build:
context: ../
dockerfile: frontend/Dockerfile
target: prod
args:
PNPM_STORE_PATH: /root/.local/share/pnpm/store
NPM_REGISTRY: ""
container_name: deer–flow–frontend
environment:
– BETTER_AUTH_SECRET=deerflow–secret–key–2026
– DEER_FLOW_INTERNAL_GATEWAY_BASE_URL=http://gateway:8001
– DEER_FLOW_INTERNAL_LANGGRAPH_BASE_URL=http://langgraph:2024
networks:
– deer–flow
restart: unless–stopped

# Gateway API 网关
gateway:
build:
context: ../
dockerfile: backend/Dockerfile
args:
APT_MIRROR: ""
UV_IMAGE: ghcr.io/astral–sh/uv:0.7.20
UV_INDEX_URL: https://pypi.org/simple
container_name: deer–flow–gateway
command: sh –c "cd backend && PYTHONPATH=. uv run uvicorn app.gateway.app:app ––host 0.0.0.0 ––port 8001 ––workers 4"
volumes:
– ./docker/config.yaml:/app/backend/config.yaml:ro
– ../backend/extensions_config.json:/app/backend/extensions_config.json:ro
– ../skills:/app/skills:ro
– /root/.deer–flow:/app/backend/.deer–flow
– /var/run/docker.sock:/var/run/docker.sock
working_dir: /app
environment:
– CI=true
– DEER_FLOW_HOME=/app/backend/.deer–flow
– DEER_FLOW_CONFIG_PATH=/app/backend/config.yaml
– DEER_FLOW_HOST_BASE_DIR=/app/backend/.deer–flow
– DEER_FLOW_SANDBOX_HOST=host.docker.internal
extra_hosts:
– "host.docker.internal:host-gateway"
networks:
– deer–flow
restart: unless–stopped

# LangGraph AI 运行时
langgraph:
build:
context: ../
dockerfile: backend/Dockerfile
args:
APT_MIRROR: ""
UV_IMAGE: ghcr.io/astral–sh/uv:0.7.20
UV_INDEX_URL: https://pypi.org/simple
container_name: deer–flow–langgraph
command: sh –c 'cd /app/backend && args="––no–browser ––no–reload ––host 0.0.0.0 ––port 2024 ––n–jobs–per–worker 10" && uv run langgraph dev $$args'
volumes:
– ./docker/config.yaml:/app/backend/config.yaml:ro
– ../backend/extensions_config.json:/app/backend/extensions_config.json:ro
– /root/.deer–flow:/app/backend/.deer–flow
– ../skills:/app/skills:ro
– /var/run/docker.sock:/var/run/docker.sock
working_dir: /app
environment:
– CI=true
– DEER_FLOW_HOME=/app/backend/.deer–flow
– DEER_FLOW_CONFIG_PATH=/app/backend/config.yaml
– DEER_FLOW_HOST_BASE_DIR=/app/backend/.deer–flow
– DEER_FLOW_SANDBOX_HOST=host.docker.internal
networks:
– deer–flow
restart: unless–stopped

networks:
deer-flow:
driver: bridge

volumes:
# 生产环境添加
# postgres_data:

服务说明

5.3 nginx.conf 配置详解

完整配置文件

events {
worker_connections 1024;
}

http {
# 基本设置
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 65;
types_hash_max_size 2048;

# 日志
access_log /dev/stdout;
error_log /dev/stderr;

# Docker 内部 DNS
resolver 127.0.0.11 valid=10s ipv6=off;

# 上游服务配置
upstream gateway {
server gateway:8001;
}

upstream langgraph {
server langgraph:2024;
}

upstream frontend {
server frontend:3000;
}

# ── Main server (path-based routing) ──
server {
listen 2026 default_server;
listen [::]:2026 default_server;
server_name _;

# Hide CORS headers from upstream to prevent duplicates
proxy_hide_header 'Access-Control-Allow-Origin';
proxy_hide_header 'Access-Control-Allow-Methods';
proxy_hide_header 'Access-Control-Allow-Headers';
proxy_hide_header 'Access-Control-Allow-Credentials';

# CORS headers for all responses (nginx handles CORS centrally)
add_header 'Access-Control-Allow-Origin' '*' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, PATCH, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' '*' always;

# Handle OPTIONS requests (CORS preflight)
if ($request_method = 'OPTIONS') {
return 204;
}

# LangGraph API routes
# In standard mode: /api/langgraph/* → langgraph:2024 (rewrite to /*)
location /api/langgraph/ {
rewrite ^/api/langgraph/(.*) /$1 break;
proxy_pass http://langgraph;
proxy_http_version 1.1;

# Headers
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection '';

# SSE/Streaming support
proxy_buffering off;
proxy_cache off;
proxy_set_header X-Accel-Buffering no;

# Timeouts for long-running requests
proxy_connect_timeout 600s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;

# Chunked transfer encoding
chunked_transfer_encoding on;
}

# Custom API: Models endpoint
location /api/models {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# Custom API: Memory endpoint
location /api/memory {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# Custom API: MCP configuration endpoint
location /api/mcp {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# Custom API: Skills configuration endpoint
location /api/skills {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# Custom API: Agents endpoint
location /api/agents {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# Custom API: Uploads endpoint
location ~ ^/api/threads/[^/]+/uploads {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

# Large file upload support
client_max_body_size 100M;
proxy_request_buffering off;
}

# Custom API: Other endpoints under /api/threads
location ~ ^/api/threads {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# API Documentation: Swagger UI
location /docs {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# API Documentation: ReDoc
location /redoc {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# API Documentation: OpenAPI Schema
location /openapi.json {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# Health check endpoint (gateway)
location /health {
proxy_pass http://gateway;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

# All other requests go to frontend
location / {
proxy_pass http://frontend;
proxy_http_version 1.1;

# Headers
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_cache_bypass $http_upgrade;

# Timeouts
proxy_connect_timeout 600s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;
}
}
}

配置说明

• rewrite ^/api/langgraph/(.*) /$1 break;：将 /api/langgraph/threads 重写到 /threads
• proxy_pass：转发请求到上游服务
• proxy_set_header：设置代理头

5.4 extensions_config.json 配置

{
"enabled": false,
"agents": {}
}

注意：此文件必须为纯 UTF-8 编码，无 BOM。

6. Docker Compose 启动

6.1 启动所有服务

cd D:\\deer-flow\\docker

# 启动所有服务
docker-compose -f docker-compose-windows.yaml up -d

# 检查容器状态
docker-compose ps

# 预期输出
NAME IMAGE COMMAND SERVICE STATUS PORTS
deer-flow-frontend docker-frontend Up 2 minutes 3000/tcp
deer-flow-gateway docker-gateway Up 2 minutes 2024/tcp,8001/tcp
deer-flow-nginx nginx:alpine Up 2 minutes 0.0.0.0:2026->2026/tcp
deer-flow-langgraph docker-langgraph Up 2 minutes 2024/tcp,8001/tcp

6.2 验证服务状态

# 查看所有容器
docker ps | Select-String "deer-flow"

# 查看各服务日志
docker logs deer-flow-nginx –tail 30
docker logs deer-flow-gateway –tail 30
docker logs deer-flow-langgraph –tail 30

# 验证模型连接
curl.exe -s http://localhost:2026/api/models

# 预期输出
[
{
"id": "qwen3.5:9b",
"name": "Qwen 3.5 9B",
"description": "Qwen 3.5 9B Local Model"
}
]

6.3 访问 Web 界面

# 打开浏览器
start http://localhost:2026

# 预期：显示 DeerFlow 欢迎界面

6.4 创建测试对话

# 创建线程
curl.exe -s -X POST http://localhost:2026/api/langgraph/threads \\
-H "Content-Type: application/json" \\
-d '{}'

# 预期输出
{
"thread_id": "threads:uuid-12345",
"created_at": "2026-04-19T18:00:00Z"
}

6.5 启动验证清单

• 所有容器显示"Up"状态
• 模型连接验证通过（curl /api/models）
• Web 界面可访问（http://localhost:2026）
• 创建线程成功
• 浏览器界面显示正常

7. 四大硬伤防范方案

7.1 硬伤一：无 Rate Limiting（API 限流）

问题描述

• DeerFlow 没有内置限流器
• API 滥用会导致服务崩溃

解决方案：Nginx 层限流

编辑 nginx.conf，在 http 块添加：

http {
# 定义限流区域
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

server {
listen 2026;

# 应用到所有 API 路径
location /api/ {
limit_req zone=api_limit burst=20 nodelay;
limit_req_status 429;

# 其他配置…
}
}
}

重启 Nginx

docker-compose restart nginx

测试限流

# 发送 30 个快速请求
for i in {1..30}; do
curl http://localhost:2026/api/models &
done | grep "429"

# 预期：部分请求返回 429 Too Many Requests

7.2 硬伤二：崩溃即失忆（长任务无恢复机制）

问题描述

• 默认使用 InMemoryStore
• 容器重启数据全丢

解决方案：PostgreSQL 持久化

编辑 docker-compose-windows.yaml：

services:
# 添加 PostgreSQL 服务
postgres:
image: postgres:15–alpine
container_name: deer–flow–postgres
environment:
POSTGRES_USER: deerflow
POSTGRES_PASSWORD: deerflow123
POSTGRES_DB: deerflow
volumes:
– postgres_data:/var/lib/postgresql/data
networks:
– deer–flow
restart: unless–stopped

langgraph:
# … 原有配置
environment:
– LANGGRAPH_STORE=postgres
– LANGGRAPH_POSTGRES_URL=postgresql://deerflow:deerflow123@postgres:5432/deerflow
depends_on:
– postgres

volumes:
postgres_data:

验证持久化

# 启动 PostgreSQL
docker-compose up -d postgres

# 等待 10 秒让数据库初始化
Start-Sleep -Seconds 10

# 重启 langgraph（会自动建表）
docker-compose restart langgraph

# 检查日志确认存储类型
docker logs deer-flow-langgraph | Select-String "PostgresStore"

# 测试：创建对话 → 重启容器 → 刷新页面
docker-compose restart langgraph
# 刷新浏览器，对话应该还在

7.3 硬伤三：并发受限（LLM 任务排队）

问题描述

• 默认 n-jobs-per-worker=10 只是内存队列
• 容器重启任务全丢

解决方案：增加并发数

编辑 docker-compose-windows.yaml：

langgraph:
# … 原有配置
environment:
– LANGGRAPH_N_JOBS_PER_WORKER=20 # 提高并发数

或者使用 Gateway Mode：

cd D:\\deer-flow\\docker
docker-compose -f docker-compose-windows.yaml down
docker-compose -f docker-compose-windows.yaml –profile gateway up -d

7.4 硬伤四：文档薄弱（高级配置靠读源码）

问题描述

• 官方文档不全
• 高级配置需要读源码

解决方案：源码速查

# 查看所有可配置项
docker exec deer-flow-gateway cat /app/backend/packages/harness/deerflow/config.py

关键配置项说明

# runtime 配置
runtime:
max_workers: 10 # 并发工作线程
queue_maxsize: 100 # 任务队列大小
checkpoint_interval: 30 # 检查点间隔（秒）
task_timeout: 300 # 任务超时（秒）
retry_attempts: 3 # 失败重试次数

# models 配置
models:
default: qwen3.5:9b
timeout: 60 # LLM 调用超时
max_retries: 2 # LLM 调用重试

# sandbox 配置
sandbox:
enabled: true
timeout: 120 # 沙箱执行超时
memory_limit: 512m # 沙箱内存限制

8. 故障排查流程

8.1 错误码速查表

8.2 关键调试命令

# 查看容器状态
docker-compose ps

# 查看 LangGraph 日志（实时跟踪）
docker logs deer-flow-langgraph -f
docker logs deer-flow-langgraph –tail 50

# 查看 Gateway 日志
docker logs deer-flow-gateway –tail 30

# 测试 API 端点
curl.exe -s http://localhost:2026/api/models
curl.exe -s -X POST http://localhost:2026/api/langgraph/threads -H "Content-Type: application/json" -d '{}'

# 检查依赖
docker exec deer-flow-langgraph sh -c 'cd /app/backend && .venv/bin/python -c "import langchain_ollama; print(langchain_ollama.version)"'

# 验证持久化
docker exec deer-flow-langgraph sh -c 'cd /app/backend && .venv/bin/python -c "from langgraph.store import get_store; store = get_store(); print(type(store))"'

# 重启服务
docker-compose restart langgraph
docker-compose restart nginx

# 停止所有服务
docker-compose down

# 启动所有服务
docker-compose up -d

8.3 浏览器开发者工具调试

8.4 故障排查流程

出现错误
↓
查看错误码
↓
查看容器日志
↓
定位错误原因
↓
应用解决方案
↓
验证修复
↓
成功？
├── 是 → 完成
└── 否 → 回到查看容器日志

9. 生产级优化建议

9.1 监控与告警

Prometheus + Grafana 配置

# docker-compose 添加监控服务
prometheus:
image: prom/prometheus
volumes:
– ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
command:
– '–config.file=/etc/prometheus/prometheus.yml'
– '–storage.tsdb.path=/prometheus'
ports:
– "9090:9090"

grafana:
image: grafana/grafana
ports:
– "3001:3000"
volumes:
– ./monitoring/dashboards:/etc/grafana/provisioning/dashboards

监控指标

9.2 备份策略

#!/bin/bash
# backup.sh – 每天备份

# 备份数据库
docker exec deer-flow-postgres pg_dump deerflow > /backup/deerflow-db-$(date +%Y%m%d).sql

# 备份配置文件
tar -czf /backup/deerflow-config-$(date +%Y%m%d).tar.gz \\
config.yaml docker-compose-windows.yaml nginx.conf

# 备份聊天记录
docker exec deer-flow-gateway tar -czf /backup/deerflow-threads-$(date +%Y%m%d).tar.gz \\
/app/backend/.deer-flow/threads

9.3 故障恢复流程

# 快速恢复步骤
docker-compose down
docker-compose up -d postgres
Start-Sleep -Seconds 10
docker-compose up -d langgraph
docker-compose up -d nginx frontend gateway

附录

附录 A：完整配置文件

A.1 docker-compose-windows.yaml（生产版）

[完整配置文件内容见第 5.2 节]

A.2 nginx.conf（生产版）

[完整配置文件内容见第 5.3 节]

A.3 config.yaml（生产版）

[完整配置文件内容见第 5.1 节]

附录 B：常见错误及解决办法

❌ 错误 1：WSL2 未启用导致的错误

症状：

Error: Failed to start Docker
Error: Cannot access '/var/run/docker.sock'

原因：WSL2 未启用，Docker 使用默认后端。

解决方法：

# 检查 WSL 版本
wsl –list –verbose

# 设置为 WSL2
wsl –set-default-version 2

# 重启 Docker Desktop
Restart-Service docker-desktop

# 验证
docker ps

❌ 错误 2：Docker 资源不足导致的错误

症状：

Error: Cannot allocate memory
Error: Not enough memory for container

原因：Docker 资源限制未配置。

解决方法：

# 编辑 Docker 设置
notepad "$env:LOCALAPPDATA\\Docker\\settings.json"

# 添加资源限制配置
{
"features": {
"containerd-overlayfuse-volumes": true
},
"resources": {
"memory": "16gb",
"cpus": "12",
"disk": "200gb"
}
}

# 重启 Docker Desktop
Restart-Service docker-desktop

❌ 错误 3：国内网络无法连接 Docker Hub

症状：

Error: Cannot access docker.io
Error: Connection timed out after 10000ms

原因：国内用户无法访问 Docker Hub 官方源。

解决方法：

# 设置 Docker 镜像源
New-Item -Path "$env:LOCALAPPDATA\\Docker\\settings.json" -Force

$settings = Get-Content -Path "$env:LOCALAPPDATA\\Docker\\settings.json" -Raw
$settings | ConvertFrom-Json

# 添加镜像源配置
$settings.mirrors = @{
"https://hub.docker.com" = "https://docker.mirrors.ustc.edu.cn"
}

$settings | ConvertTo-Json -Depth 100 | Set-Content -Path "$env:LOCALAPPDATA\\Docker\\settings.json" -NoNewline

# 重启 Docker Desktop
Restart-Service docker-desktop

验证：

# 测试镜像源
docker pull nginx:alpine

# 预期：快速拉取

❌ 错误 4：Docker 版本过低

症状：

Error: This version of Docker Desktop is not supported for WSL2
Error: Please update to version 24.0 or higher

原因：Docker Desktop 版本低于 24.0。

解决方法：

# 检查版本
docker –version

# 更新 Docker Desktop
# 从 Microsoft Store 更新，或使用 winget
winget upgrade docker-desktop

# 重启 Docker Desktop
Restart-Service docker-desktop

❌ 错误 5：WSL2 后端配置错误

症状：

Error: Cannot access /var/run/docker.sock
Error: WSL2 backend not available

原因：WSL2 未设置为默认版本。

解决方法：

# 检查当前后端
wsl -l -v

# 设置为 WSL2
wsl –set-default-version 2

# 重启 Docker Desktop
Restart-Service docker-desktop

# 验证
docker ps

❌ 错误 6：Docker 资源限制错误

症状：

Error: Cannot allocate memory
Error: Cannot create container

原因：Docker 资源限制未配置。

解决方法：

# 编辑 Docker 设置
notepad "$env:LOCALAPPDATA\\Docker\\settings.json"

# 添加资源限制配置
{
"features": {
"containerd-overlayfuse-volumes": true
},
"resources": {
"memory": "16gb",
"cpus": "12",
"disk": "200gb"
}
}

# 重启 Docker Desktop
Restart-Service docker-desktop

❌ 错误 7：镜像拉取超时

症状：

Error: Get https://hub.docker.com/v2/repositories/library/nginx/manifests/latest: net/http: request canceled
Error: context deadline exceeded

原因：国内网络无法访问 Docker Hub。

解决方法：

# 使用国内镜像源
docker pull –mirror https://docker.mirrors.ustc.edu.cn \\
harveyff/deerflow:v1.0.17

# 或者使用其他镜像源
docker pull –mirror https://mirror.buaa.edu.cn/nginx \\
nginx:alpine

❌ 错误 8：镜像下载失败

症状：

Error: Get "https://registry-1.docker.io/v2/deerflow/…"
Error: EOF

原因：DNS 解析失败或连接超时。

解决方法：

# 配置 DNS
notepad C:\\Windows\\System32\\drivers\\etc\\hosts

# 添加 Docker 镜像源
192.168.1.1 docker.mirrors.ustc.edu.cn

# 清除 Docker 镜像缓存
docker system prune -a

# 重试拉取
docker pull harveyff/deerflow:v1.0.17

❌ 错误 9：镜像验证失败

症状：

Error: Error: image already exists
Error: Invalid image name

原因：镜像名称错误或缓存问题。

解决方法：

# 查看已下载镜像
docker images | Find-String deerflow

# 清除特定镜像
docker rmi harveyff/deerflow:v1.0.17

# 重新拉取
docker pull harveyff/deerflow:v1.0.17

# 验证镜像
docker images

❌ 错误 10：权限不足

症状：

Error: Access denied
Error: Permission denied

原因：目录权限未设置。

解决方法：

# 创建项目目录
$projectPath = "D:\\deer-flow"
if (!(Test-Path $projectPath)) {
New-Item -ItemType Directory -Path $projectPath -Force
}

# 设置目录权限
icacls "$projectPath" /grant:r "Users:(OI)(CI)R"

# 进入项目目录
cd "$projectPath"

❌ 错误 11：Git 克隆失败

症状：

Error: fatal: could not read Username for 'https://github.com': terminal prompts disabled
Error: permission denied (publickey)

原因：Git 未配置凭证或 SSH 密钥。

解决方法：

# 配置 Git 凭证
git config –global credential.helper wincred

# 或者使用 HTTPS 凭证
git config –global http.postBuffer 524288000

# 克隆项目
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

❌ 错误 12：Git 分支版本错误

症状：

Error: branch 'main' not found
Error: HEAD is not at a commit

原因：项目版本不匹配。

解决方法：

# 拉取所有分支
git fetch –all
git pull –all

# 查看分支
git branch -a

# 切换到正确的分支
git checkout main
git pull origin main

# 确认版本
git describe –tags

# 预期输出：v1.0.17

❌ 错误 13：目录结构错误

症状：

Error: directory not found
Error: No such file or directory

原因：项目目录结构未正确创建。

解决方法：

# 查看项目结构
tree /F

# 或者使用命令
Get-ChildItem -Path . -Recurse | Select-Object FullName

# 验证关键目录
Test-Path "backend"
Test-Path "frontend"
Test-Path "docker"
Test-Path "docker-compose-windows.yaml"

❌ 错误 14：Ollama 安装失败

症状：

Error: Package ol
Error: Cannot download Ollama

原因：安装包下载失败或版本不匹配。

解决方法：

# 使用 winget 安装
winget install Ollama.Ollama

# 或者下载安装包
# 访问：https://ollama.ai/download

# 验证安装
ollama –version

❌ 错误 15：Ollama 服务无法启动

症状：

Error: ollama serve failed
Error: Cannot start Ollama service

原因：端口被占用或内存不足。

解决方法：

# 检查端口占用
netstat -ano | findstr 11434

# 如果端口被占用，终止占用进程
Stop-Process -Id <PID>

# 启动 Ollama 服务
ollama serve

# 或使用 Windows 服务
sc create Ollama binPath= "ollama serve" start= auto

❌ 错误 16：环境变量设置失败

症状：

Error: Cannot set environment variable
Error: Variable not found

原因：环境变量路径错误或权限不足。

解决方法：

# 设置环境变量
$env:OLLAMA_HOST="0.0.0.0:11434"

# 验证监听端口
netstat -ano | findstr 11434

# 预期输出：TCP 0.0.0.0:11434 0.0.0.0:0 LISTENING

❌ 错误 17：模型拉取失败

症状：

Error: Error downloading qwen3.5:9b
Error: Connection timed out

原因：国内网络无法访问 Ollama 镜像源。

解决方法：

# 设置 Ollama 镜像源
ollama pull qwen3.5:9b –mirror https://ollama.m.daoguan.com

# 或者使用国内镜像源
ollama pull qwen3.5:9b –mirror https://ollama.ai

# 验证模型
ollama list

❌ 错误 18：配置文件编码错误（UTF-8 BOM）

症状：

Error: Unexpected UTF-8 BOM (decode using utf-8-sig)
Error: Invalid UTF-8 sequence

原因：文件包含 UTF-8 BOM 字符。

解决方法：

# 删除原文件
Remove-Item "D:\\deer-flow\\config.yaml" -Force

# 使用纯 UTF-8 编码创建文件
$bytes = [System.Text.Encoding]::UTF8.GetBytes(
@'
# Configuration for the DeerFlow application
config_version: 7
# … 配置内容
'@
)

[System.IO.File]::WriteAllBytes("D:\\deer-flow\\config.yaml", $bytes)

# 验证编码
Get-Content "D:\\deer-flow\\config.yaml" -Encoding UTF8

❌ 错误 19：配置文件路径错误

症状：

Error: File not found: config.yaml
Error: Cannot open file

原因：配置文件路径未正确设置。

解决方法：

# 复制配置到正确位置
Copy-Item "D:\\deer-flow\\docker\\config.yaml" -Destination "D:\\deer-flow\\config.yaml"

# 或者使用环境变量
$env:DEER_FLOW_CONFIG_PATH="D:\\deer-flow\\config.yaml"

❌ 错误 20：配置文件语法错误

症状：

Error: Invalid YAML syntax
Error: Unexpected character

原因：YAML 缩进错误或注释格式错误。

解决方法：

# 使用 YAML 验证工具
docker exec deer-flow-gateway cat /app/backend/packages/harness/deerflow/config.py

# 或者使用在线 YAML 验证器
# 访问：https://yaml-validator.com

# 手动检查缩进
# 确保所有缩进使用 2 个空格

❌ 错误 21：Docker Compose 语法错误

症状：

Error: Invalid compose file format
Error: Unknown service name

原因：YAML 缩进错误或拼写错误。

解决方法：

# 检查 YAML 缩进
notepad "D:\\deer-flow\\docker\\docker-compose-windows.yaml"

# 或者使用 YAML 验证工具
docker-compose -f docker-compose-windows.yaml config

# 验证服务名称
docker-compose ps

❌ 错误 22：端口冲突错误

症状：

Error: Port 2026 is already in use
Error: Cannot bind to port

原因：端口 2026 被占用。

解决方法：

# 检查端口占用
netstat -ano | findstr 2026

# 终止占用进程
Stop-Process -Id <PID>

# 或者修改端口配置
# 编辑 docker-compose-windows.yaml
# 将 ports: – "2026:2026" 改为 – "2027:2026"

❌ 错误 23：nginx 配置路径错误

症状：

Error: File not found: nginx.conf
Error: Cannot open file

原因：nginx 配置文件路径错误。

解决方法：

# 检查配置文件路径
Get-ChildItem -Path "D:\\deer-flow\\docker\\nginx" -Filter *.conf

# 复制配置到正确位置
Copy-Item "D:\\deer-flow\\docker\\nginx\\nginx.conf" -Destination "D:\\deer-flow\\docker\\nginx\\nginx.conf.template"

# 验证文件存在
Test-Path "D:\\deer-flow\\docker\\nginx\\nginx.conf.template"

❌ 错误 24：nginx 配置语法错误

症状：

Error: nginx: [emerg] invalid number of workers
Error: syntax error in configuration

原因：nginx 配置语法错误。

解决方法：

# 测试 nginx 配置
docker exec deer-flow-nginx nginx -t

# 查看错误日志
docker logs deer-flow-nginx –tail 30

# 手动检查配置
docker exec deer-flow-nginx cat /etc/nginx/nginx.conf

❌ 错误 25：JSON 格式错误

症状：

Error: Invalid JSON
Error: Unexpected token

原因：JSON 格式错误或包含 BOM。

解决方法：

# 删除原文件
Remove-Item "D:\\deer-flow\\backend\\extensions_config.json" -Force

# 使用纯 UTF-8 编码创建文件
$bytes = [System.Text.Encoding]::UTF8.GetBytes(
'{"enabled": false,"agents":{}}'
)

[System.IO.File]::WriteAllBytes("D:\\deer-flow\\backend\\extensions_config.json", $bytes)

# 验证 JSON
docker exec deer-flow-gateway cat /app/backend/extensions_config.json

❌ 错误 26：docker-compose 启动失败

症状：

Error: ERROR: Cannot start service
Error: Service not found

原因：Docker Compose 语法错误或依赖服务未启动。

解决方法：

# 进入项目目录
cd D:\\deer-flow\\docker

# 查看 Docker Compose 配置
docker-compose -f docker-compose-windows.yaml config

# 启动所有服务
docker-compose -f docker-compose-windows.yaml up -d

# 检查容器状态
docker-compose ps

❌ 错误 27：容器启动失败

症状：

Error: Container exited with code 1
Error: Container crashed

原因：容器启动脚本错误或缺少依赖。

解决方法：

# 查看容器日志
docker logs deer-flow-langgraph –tail 50

# 查看构建日志
docker-compose logs -f

# 验证镜像
docker images | Select-String "deerflow"

❌ 错误 28：服务依赖失败

症状：

Error: nginx is not ready
Error: gateway failed to start

原因：服务依赖顺序错误或端口冲突。

解决方法：

# 单独启动服务
docker-compose up -d nginx

# 验证服务状态
docker-compose ps

# 或者重建镜像
docker-compose build
docker-compose up -d

❌ 错误 29：模型连接失败

症状：

Error: Cannot connect to Ollama
Error: HTTP connection failed

原因：Ollama 服务未启动或地址配置错误。

解决方法：

# 检查 Ollama 服务
ollama list

# 验证 API 访问
curl http://localhost:11434/api/tags

# 检查配置
docker exec deer-flow-gateway cat /app/backend/config.yaml | Select-String "base_url"

# 或者修改配置
# 编辑 config.yaml
# base_url: http://192.168.3.162:11434

❌ 错误 30：Web 界面无法访问

症状：

Error: Cannot connect to localhost:2026
Error: Connection refused

原因：Nginx 未启动或端口配置错误。

解决方法：

# 检查 Nginx 服务
docker ps | Select-String "deer-flow-nginx"

# 查看 Nginx 日志
docker logs deer-flow-nginx –tail 30

# 测试 Nginx 配置
docker exec deer-flow-nginx nginx -t

# 重启 Nginx
docker-compose restart nginx

# 验证连接
curl http://localhost:2026/api/models

❌ 错误 31：API 限流不足

症状：

Error: Too many requests
Error: Rate limit exceeded

原因：Nginx 限流配置不足。

解决方法：

# 编辑 nginx.conf
notepad "D:\\deer-flow\\docker\\nginx\\nginx.conf"

# 添加限流配置
http {
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

location /api/ {
limit_req zone=api_limit burst=20 nodelay;
limit_req_status 429;
}
}

# 重启 Nginx
docker-compose restart nginx

❌ 错误 32：数据持久化失败

症状：

Error: InMemoryStore used
Error: Data lost on restart

原因：未配置 PostgreSQL 或配置错误。

解决方法：

# 编辑 docker-compose-windows.yaml
notepad "D:\\deer-flow\\docker\\docker-compose-windows.yaml"

# 添加 PostgreSQL 服务
postgres:
image: postgres:15-alpine
container_name: deer-flow-postgres
environment:
POSTGRES_USER: deerflow
POSTGRES_PASSWORD: deerflow123
POSTGRES_DB: deerflow
volumes:
– postgres_data:/var/lib/postgresql/data
networks:
– deer-flow

# 添加环境变量到 langgraph
langgraph:
environment:
– LANGGRAPH_STORE=postgres
– LANGGRAPH_POSTGRES_URL=postgresql://deerflow:deerflow123@postgres:5432/deerflow

# 添加依赖
langgraph:
depends_on:
– postgres

# 添加 volumes
volumes:
postgres_data:

# 启动 PostgreSQL
docker-compose up -d postgres

# 等待 10 秒让数据库初始化
Start-Sleep -Seconds 10

# 重启 langgraph
docker-compose restart langgraph

# 验证持久化
docker logs deer-flow-langgraph | Select-String "PostgresStore"

❌ 错误 33：并发数不足

症状：

Error: Task queue full
Error: Cannot process request

原因：并发数配置不足。

解决方法：

# 编辑 docker-compose-windows.yaml
notepad "D:\\deer-flow\\docker\\docker-compose-windows.yaml"

# 添加环境变量
langgraph:
environment:
– LANGGRAPH_N_JOBS_PER_WORKER=20

❌ 错误 34：配置参数不明确

症状：

Error: Unknown config parameter
Error: Invalid config value

原因：配置参数含义不明确。

解决方法：

# 查看所有可配置项
docker exec deer-flow-gateway cat /app/backend/packages/harness/deerflow/config.py

# 或者查看官方文档
# GitHub: https://github.com/bytedance/deer-flow

❌ 错误 35：日志查看失败

症状：

Error: Cannot access container logs
Error: Permission denied

原因：容器权限问题。

解决方法：

# 查看容器状态
docker ps

# 查看日志
docker logs deer-flow-langgraph –tail 50

# 或者进入容器查看日志
docker exec -it deer-flow-langgraph sh
tail -f /var/log/containers/*.log

❌ 错误 36：监控服务无法启动

症状：

Error: Cannot start Prometheus
Error: Port already in use

原因：端口冲突。

解决方法：

# 检查端口占用
netstat -ano | findstr 9090

# 终止占用进程
Stop-Process -Id <PID>

# 或者修改端口配置
# 编辑 docker-compose
# 将 ports: – "9090:9090" 改为 – "9091:9090"

10. 结语

本指南覆盖了：

• ✅ 环境准备与系统要求
• ✅ Docker 环境配置
• ✅ 项目初始化与克隆
• ✅ Ollama 服务配置
• ✅ 配置文件详解
• ✅ Docker Compose 启动
• ✅ 四大硬伤防范方案
• ✅ 故障排查流程
• ✅ 生产级优化建议
• ✅ 完整配置文件
• ✅ 常见错误及解决办法

祝部署顺利！🦌✨