DeerFlow 系列教程第五篇 | 配置与 Docker 部署全指南：从香港首建到内陆迁移

DeerFlow 系列教程第五篇

本篇教程聚焦于配置体系 和 Docker 容器化部署，并覆盖「香港服务器首次构建 → 打快照 → 内陆拉取镜像启动」的完整场景。全文基于国产大模型配置示例编写，适用于在中国大陆网络环境下运行 DeerFlow 的用户。

一、配置体系全解

DeerFlow 的所有核心行为由三个配置文件协同驱动。理解它们之间的关系，是正确部署的第一步。

1.1 三文件协同架构

复制代码

deer-flow/
├── config.yaml                  ← 主配置文件（模型、沙箱、工具、技能、记忆等）
├── .env                         ← 环境变量（API Key 等敏感信息）
├── extensions_config.json       ← 扩展配置（MCP 服务器、技能启用状态）
├── frontend/.env                ← 前端环境变量（后端 URL 配置）
└── config.example.yaml          ← 配置模板（763 行，含详细注释）

文件	作用	敏感信息	版本管理
`config.yaml`	定义模型列表、工具集、沙箱类型、记忆策略等核心行为	可引用 `$ENV_VAR`	不入 Git（.gitignore）
`.env`	存储 API Key、Token 等密钥	是	不入 Git
`extensions_config.json`	MCP 服务器配置、各技能的启用/禁用状态	可能含 Token	不入 Git
`frontend/.env`	前端后端 URL 配置	否	不入 Git

1.2 配置文件生成

运行 make config 时，底层调用 scripts/configure.py，执行以下动作：

检查是否已存在 config.yaml（存在则中止，防止覆盖）
复制 config.example.yaml → config.yaml
复制 .env.example → .env
复制 frontend/.env.example → frontend/.env

bash 复制代码

# 生成配置文件（仅首次）
make config

# 如果后续模板更新了字段，可以增量合并
make config-upgrade

make config-upgrade 底层调用 scripts/config-upgrade.sh，它会将 config.example.yaml 中新增的字段合并到你的 config.yaml 中，同时保留你已有的自定义值。配置文件有一个 config_version 字段用于检测版本：

yaml 复制代码

config_version: 5

1.3 config.yaml 核心结构

yaml 复制代码

config_version: 5                    # 配置版本号
log_level: info                      # 日志级别 (debug/info/warning/error)

token_usage:                         # Token 使用量追踪
  enabled: false

models: [...]                        # 可用模型列表（核心配置）

tool_groups: [...]                   # 工具分组定义
tools: [...]                         # 可用工具列表

tool_search:                         # 延迟工具加载（MCP 工具较多时有用）
  enabled: false

sandbox:                             # 沙箱提供者配置
  use: deerflow.sandbox.local:LocalSandboxProvider

skills:                              # 技能目录配置
  container_path: /mnt/skills

title:                               # 对话标题自动生成
  enabled: true

summarization:                       # 长对话消息摘要
  enabled: true

memory:                              # 长期记忆系统
  enabled: true

checkpointer:                        # 状态持久化
  type: sqlite
  connection_string: checkpoints.db

二、国产大模型配置详解

这是全文最核心的部分。DeerFlow 的模型配置结构为：

yaml 复制代码

models:
  - name: <唯一标识符>             # 模型唯一名称（英文，用于内部引用）
    display_name: <显示名称>       # 前端 UI 展示名称
    use: <Provider 类路径>         # Python 类的全限定路径
    model: <模型标识>              # API 对应的模型 ID
    api_key: $ENV_VAR             # API Key（引用环境变量）
    api_base: <API 地址>           # API Base URL（部分 Provider 使用 base_url）
    timeout: 600.0                 # 请求超时（秒）
    max_retries: 2                 # 最大重试次数
    max_tokens: 8192               # 最大输出 Token 数
    supports_thinking: true        # 是否支持思考模式
    supports_vision: true          # 是否支持视觉（图片输入）
    when_thinking_enabled:         # 思考模式启用时的额外参数
      extra_body:
        thinking:
          type: enabled

2.1 火山引擎豆包（Doubao）

豆包是字节跳动旗下的大模型，通过火山引擎 Ark 平台提供 API。

环境变量配置（.env）：

bash 复制代码

VOLCENGINE_API_KEY=your-volcengine-api-key

模型配置（config.yaml）：

yaml 复制代码

models:
  # 豆包 Seed 1.8 ------ 推荐主力模型，支持思考 + 视觉
  - name: doubao-seed-1.8
    display_name: 豆包 Seed 1.8
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: doubao-seed-1-8-251228
    api_base: https://ark.cn-beijing.volces.com/api/v3
    api_key: $VOLCENGINE_API_KEY
    timeout: 600.0
    max_retries: 2
    supports_thinking: true
    supports_vision: true
    supports_reasoning_effort: true
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled

  # 豆包 Seed 2.0 Code ------ 专注代码生成
  - name: doubao-seed-2.0-code
    display_name: 豆包 Seed 2.0 Code
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: doubao-seed-2-0-code
    api_base: https://ark.cn-beijing.volces.com/api/v3
    api_key: $VOLCENGINE_API_KEY
    timeout: 600.0
    max_retries: 2
    supports_thinking: true
    supports_vision: false
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled

说明：豆包使用 PatchedChatDeepSeek Provider，因为 Ark 平台的 API 格式与 DeepSeek 兼容。api_base 固定为 https://ark.cn-beijing.volces.com/api/v3。

2.2 DeepSeek

DeepSeek 是国内深度求索公司的大模型，API 直连无需翻墙。

环境变量配置（.env）：

bash 复制代码

DEEPSEEK_API_KEY=your-deepseek-api-key

模型配置（config.yaml）：

yaml 复制代码

models:
  # DeepSeek V3（推理模型，支持思考模式）
  - name: deepseek-v3
    display_name: DeepSeek V3
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: deepseek-reasoner
    api_key: $DEEPSEEK_API_KEY
    timeout: 600.0
    max_retries: 2
    max_tokens: 8192
    supports_thinking: true
    supports_vision: false
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled

  # DeepSeek Chat（快速对话，不含推理）
  - name: deepseek-chat
    display_name: DeepSeek Chat
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: deepseek-chat
    api_key: $DEEPSEEK_API_KEY
    timeout: 600.0
    max_retries: 2
    max_tokens: 8192
    supports_thinking: false
    supports_vision: false

2.3 Kimi K2.5（Moonshot）

Kimi 是月之暗面（Moonshot AI）出品的大模型，API 直连无需翻墙。

环境变量配置（.env）：

bash 复制代码

MOONSHOT_API_KEY=your-moonshot-api-key

模型配置（config.yaml）：

yaml 复制代码

models:
  - name: kimi-k2.5
    display_name: Kimi K2.5
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: kimi-k2.5
    api_base: https://api.moonshot.cn/v1
    api_key: $MOONSHOT_API_KEY
    timeout: 600.0
    max_retries: 2
    max_tokens: 32768
    supports_thinking: true
    supports_vision: true
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled

2.4 MiniMax（中国区）

MiniMax 海螺 AI 提供 204K 超长上下文窗口的大模型。

环境变量配置（.env）：

bash 复制代码

MINIMAX_API_KEY=your-minimax-api-key

模型配置（config.yaml）：

yaml 复制代码

models:
  # MiniMax M2.7（中国区用户）
  - name: minimax-m2.7
    display_name: MiniMax M2.7
    use: langchain_openai:ChatOpenAI
    model: MiniMax-M2.7
    api_key: $MINIMAX_API_KEY
    base_url: https://api.minimaxi.com/v1
    request_timeout: 600.0
    max_retries: 2
    max_tokens: 4096
    temperature: 1.0    # MiniMax 要求 temperature 在 (0.0, 1.0] 范围
    supports_vision: true
    supports_thinking: true

  # MiniMax M2.7 Highspeed（快速版）
  - name: minimax-m2.7-highspeed
    display_name: MiniMax M2.7 Highspeed
    use: langchain_openai:ChatOpenAI
    model: MiniMax-M2.7-highspeed
    api_key: $MINIMAX_API_KEY
    base_url: https://api.minimaxi.com/v1
    request_timeout: 600.0
    max_retries: 2
    max_tokens: 4096
    temperature: 1.0
    supports_vision: true
    supports_thinking: true

注意：中国区用户使用 api.minimaxi.com（注意多了一个 i），国际区用户使用 api.minimax.io。

2.5 通义千问 Qwen（通过 vLLM 本地部署）

如果你使用 vLLM 本地部署了 Qwen 模型：

环境变量配置（.env）：

bash 复制代码

VLLM_API_KEY=your-vllm-api-key

模型配置（config.yaml）：

yaml 复制代码

models:
  - name: qwen3-32b-vllm
    display_name: Qwen3 32B (vLLM)
    use: deerflow.models.vllm_provider:VllmChatModel
    model: Qwen/Qwen3-32B
    api_key: $VLLM_API_KEY
    base_url: http://localhost:8000/v1
    request_timeout: 600.0
    max_retries: 2
    max_tokens: 8192
    supports_thinking: true
    supports_vision: false
    when_thinking_enabled:
      extra_body:
        chat_template_kwargs:
          enable_thinking: true

2.6 国产模型推荐组合方案

以下是面向内陆用户的推荐配置组合，全部无需翻墙：

用途	推荐模型	Provider 类	理由
主力模型	豆包 Seed 1.8 / DeepSeek V3	PatchedChatDeepSeek	支持思考模式，综合能力强
快速对话	DeepSeek Chat / MiniMax M2.7 Highspeed	PatchedChatDeepSeek / ChatOpenAI	响应快，成本低
长文本处理	Kimi K2.5	PatchedChatDeepSeek	32K Token 输出，超长上下文
代码生成	豆包 Seed 2.0 Code	PatchedChatDeepSeek	专为代码优化
本地部署	Qwen3 32B (vLLM)	VllmChatModel	完全离线，数据不出境

2.7 Provider 类对照表

Provider 类路径	适用平台	说明
`langchain_openai:ChatOpenAI`	OpenAI 及兼容 API	标准 OpenAI 协议
`deerflow.models.patched_openai:PatchedChatOpenAI`	OpenAI + 思考签名	保留 Gemini 等模型的 thought_signature
`deerflow.models.patched_deepseek:PatchedChatDeepSeek`	DeepSeek / 豆包 / Kimi	支持推理思考模式的适配层
`deerflow.models.vllm_provider:VllmChatModel`	vLLM 本地部署	保留 Qwen 风格推理
`langchain_anthropic:ChatAnthropic`	Anthropic Claude	Claude 专用
`langchain_google_genai:ChatGoogleGenerativeAI`	Google Gemini	Gemini 原生 SDK

2.8 .env 完整示例（国产模型版）

bash 复制代码

# ============================================================
# DeerFlow 环境变量配置（国产模型版）
# ============================================================

# ── 搜索工具 ──
# DuckDuckGo 无需 API Key（默认已启用）
# 如果使用 Tavily 搜索（需要翻墙或代理）:
# TAVILY_API_KEY=tvly-xxxxxxxx

# 如果使用 Jina AI 内容提取:
JINA_API_KEY=jina_xxxxxxxx

# ── 大模型 API Key ──
# 火山引擎豆包
VOLCENGINE_API_KEY=xxxxxxxx

# DeepSeek
DEEPSEEK_API_KEY=sk-xxxxxxxx

# Moonshot (Kimi)
MOONSHOT_API_KEY=sk-xxxxxxxx

# MiniMax
MINIMAX_API_KEY=xxxxxxxx

# vLLM（本地部署时使用）
# VLLM_API_KEY=EMPTY

# ── 可选：LangSmith 追踪 ──
# LANGSMITH_TRACING=true
# LANGSMITH_ENDPOINT=https://api.smith.langchain.com
# LANGSMITH_API_KEY=lsv2_xxxxxxxx
# LANGSMITH_PROJECT=deerflow

2.9 extensions_config.json 配置

json 复制代码

{
  "mcpServers": {},
  "skills": {}
}

此文件用于管理 MCP 服务器和技能的启用状态。初始部署时保持空配置即可，后续可通过前端设置页面进行配置。

三、Docker 镜像深度解析

在开始部署之前，我们先彻底理解 Docker 构建过程中到底发生了什么，需要下载哪些依赖。这对在受限网络环境下部署至关重要。

3.1 涉及的 Docker 镜像清单

DeerFlow Docker 部署涉及以下镜像：

镜像	来源	大小估算	用途
`python:3.12-slim-bookworm`	Docker Hub	~150 MB	后端基础镜像
`node:22-alpine`	Docker Hub	~130 MB	前端基础镜像
`nginx:alpine`	Docker Hub	~40 MB	反向代理
`ghcr.io/astral-sh/uv:0.7.20`	GitHub Container Registry	~20 MB	Python 包管理器 uv
`docker:cli`	Docker Hub	~60 MB	Docker CLI（DooD 模式）
`enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest`	火山引擎 CR（北京）	~500 MB	沙箱执行环境（可选）

首次构建时总下载量约 1~1.5 GB（含所有基础镜像 + Python/Node.js 依赖包）。

3.2 Backend Dockerfile 逐层解析

后端 Dockerfile（backend/Dockerfile）采用多阶段构建（multi-stage build），分为三个阶段：

复制代码

┌─────────────────────────────────────────────────────────────┐
│  Stage 1: builder（构建阶段）                                │
│                                                             │
│  基础镜像: python:3.12-slim-bookworm                         │
│                                                             │
│  动作 1: [可选] 替换 APT 镜像源                               │
│    → sed 替换 deb.debian.org 为 APT_MIRROR（如 mirrors.aliyun.com）│
│                                                             │
│  动作 2: 安装系统依赖                                         │
│    → apt-get install: curl, build-essential, gnupg, ca-certificates │
│    → 用途: build-essential 编译 Python C 扩展                 │
│                                                             │
│  动作 3: 安装 Node.js 22                                     │
│    → 从 deb.nodesource.com 添加 APT 源                      │
│    → apt-get install nodejs                                  │
│    → 用途: 运行 MCP 服务器的 npx 命令                         │
│                                                             │
│  动作 4: 安装 uv 包管理器                                     │
│    → COPY --from=uv-source /uv /uvx（从 ghcr.io 镜像复制二进制文件）│
│                                                             │
│  动作 5: 复制后端源码 + 安装 Python 依赖                       │
│    → COPY backend ./backend                                  │
│    → cd backend && uv sync（安装 pyproject.toml 中的全部依赖） │
│    → 主要依赖: langchain, langgraph, fastapi, uvicorn 等     │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Stage 2: dev（开发阶段，仅 docker-compose-dev 使用）         │
│                                                             │
│  继承 builder 的全部内容（含编译工具链）                       │
│  额外安装 Docker CLI（从 docker:cli 镜像复制）                │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Stage 3: runtime（生产阶段，docker-compose.yaml 使用）       │
│                                                             │
│  基础镜像: python:3.12-slim-bookworm（全新、干净的镜像层）     │
│                                                             │
│  动作 1: 从 builder 复制 Node.js 运行时                      │
│    → COPY --from=builder /usr/bin/node + /usr/lib/node_modules │
│    → 创建 npm/npx 软链接                                     │
│                                                             │
│  动作 2: 安装 Docker CLI                                     │
│    → COPY --from=docker:cli（DooD 模式需要）                  │
│                                                             │
│  动作 3: 安装 uv                                             │
│    → COPY --from=uv-source /uv /uvx                          │
│                                                             │
│  动作 4: 复制预构建的后端 + virtualenv                        │
│    → COPY --from=builder /app/backend ./backend              │
│    → 包含已安装好的 .venv 目录                                │
│                                                             │
│  最终镜像不含 build-essential，减少约 200 MB                  │
└─────────────────────────────────────────────────────────────┘

3.3 Frontend Dockerfile 逐层解析

前端 Dockerfile（frontend/Dockerfile）同样采用多阶段构建：

复制代码

┌─────────────────────────────────────────────────────────────┐
│  Stage: base（基础阶段）                                      │
│                                                             │
│  基础镜像: node:22-alpine                                    │
│                                                             │
│  动作 1: [可选] 配置 NPM Registry 镜像源                     │
│    → NPM_REGISTRY=https://registry.npmmirror.com            │
│                                                             │
│  动作 2: 启用 corepack + 安装 pnpm@10.26.2                   │
│                                                             │
│  动作 3: 复制前端源码                                         │
│    → COPY frontend ./frontend                                │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Stage: dev（开发目标，docker-compose-dev 使用）               │
│                                                             │
│  动作: pnpm install --frozen-lockfile                        │
│  → 仅安装依赖，不执行构建                                    │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Stage: builder（构建目标）                                    │
│                                                             │
│  动作 1: pnpm install --frozen-lockfile                      │
│  动作 2: pnpm build（Next.js 生产构建）                       │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Stage: prod（生产目标，docker-compose.yaml 使用）            │
│                                                             │
│  基础镜像: node:22-alpine（全新干净层）                       │
│  动作: 从 builder 阶段复制构建产物                            │
│  → COPY --from=builder /app/frontend ./frontend              │
│  → CMD: pnpm start                                          │
└─────────────────────────────────────────────────────────────┘

3.4 构建过程中的网络请求汇总

了解构建阶段的网络请求，有助于判断在内陆环境下可能遇到的阻断点：

请求目标	阶段	内容	内陆可达性
`registry-1.docker.io`	拉取基础镜像	python:3.12, node:22-alpine, nginx:alpine	需配置镜像加速器
`ghcr.io`	拉取 uv 镜像	astral-sh/uv:0.7.20	可能受阻，需 UV_IMAGE 参数
`deb.debian.org`	apt-get	系统包（curl, build-essential 等）	可替换为 APT_MIRROR
`deb.nodesource.com`	apt-get	Node.js 22 APT 源	可能受阻
`pypi.org`	uv sync	Python 包	可替换为 UV_INDEX_URL
`registry.npmjs.org`	pnpm install	Node.js 包	可替换为 NPM_REGISTRY

四、最小 Linux 运行环境配置

4.1 服务器硬件要求

场景	CPU	内存	磁盘	说明
最低可运行	2 vCPU	4 GB RAM	20 GB SSD	仅能运行，响应可能较慢
推荐配置	4 vCPU	8 GB RAM	40 GB SSD	日常使用，流畅运行
生产环境	8 vCPU	16 GB RAM	60 GB SSD	多用户并发，含沙箱容器

磁盘空间说明：Docker 镜像约 3-5 GB，构建缓存约 2-3 GB，运行时数据根据使用量增长。

4.2 操作系统要求

推荐 Ubuntu 22.04 LTS 或 Debian 12 (Bookworm)。以下为最小安装步骤：

bash 复制代码

# 1. 系统更新
sudo apt update && sudo apt upgrade -y

# 2. 安装基础工具
sudo apt install -y \
    curl \
    wget \
    git \
    make \
    ca-certificates \
    gnupg \
    lsb-release

# 3. 安装 Docker Engine
curl -fsSL https://get.docker.com | sh

# 4. 将当前用户加入 docker 组（避免每次 sudo）
sudo usermod -aG docker $USER
# 重新登录或执行: newgrp docker

# 5. 安装 Docker Compose 插件（现代 Docker 已内置）
docker compose version
# 如果没有，安装插件：
# sudo apt install docker-compose-plugin

# 6. 验证 Docker 环境
docker run --rm hello-world

4.3 Docker 守护进程配置（国内镜像加速）

bash 复制代码

# 创建 Docker 配置目录
sudo mkdir -p /etc/docker

# 写入镜像加速器配置
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://docker.mirrors.ustc.edu.cn"
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}
EOF

# 重启 Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

4.4 防火墙端口开放

bash 复制代码

# DeerFlow 默认访问端口
sudo ufw allow 2026/tcp    # Nginx 反向代理入口

# 如果需要直接访问内部服务（调试用途）
# sudo ufw allow 3000/tcp  # Frontend
# sudo ufw allow 8001/tcp  # Gateway API
# sudo ufw allow 2024/tcp  # LangGraph Server

五、Make 命令完全解读

DeerFlow 的 Makefile 是日常操作的统一入口。以下逐一解读每条命令背后的动作链。

5.1 配置类命令

命令	触发动作	说明
`make config`	`python3 ./scripts/configure.py`	从 example 文件复制生成 config.yaml、.env、frontend/.env。如果 config.yaml 已存在则中止
`make config-upgrade`	`./scripts/config-upgrade.sh`	将 config.example.yaml 的新字段增量合并到已有的 config.yaml

5.2 检查和安装类命令

命令	触发动作	说明
`make check`	`python3 ./scripts/check.py`	检查 Node.js 22+、pnpm、uv、nginx 四个依赖是否已安装
`make install`	`cd backend && uv sync` + `cd frontend && pnpm install`	安装后端 Python 依赖 + 前端 Node.js 依赖
`make setup-sandbox`	`docker pull <sandbox_image>`	预拉取沙箱容器镜像（AIO 模式使用）

5.3 本地运行类命令

命令	触发的脚本和参数	启动的进程	说明
`make dev`	`scripts/serve.sh --dev`	LangGraph + Gateway + Frontend + Nginx（4 进程）	开发模式，热更新
`make dev-pro`	`scripts/serve.sh --dev --gateway`	Gateway + Frontend + Nginx（3 进程）	开发 + Gateway 模式
`make start`	`scripts/serve.sh --prod`	同 dev 但无热更新，前端预构建	生产模式
`make start-pro`	`scripts/serve.sh --prod --gateway`	同 dev-pro 但无热更新	生产 + Gateway
`make dev-daemon`	`scripts/serve.sh --dev --daemon`	同 dev 但后台运行	后台开发模式
`make stop`	`scripts/serve.sh --stop`	杀掉所有相关进程 + 清理沙箱容器	停止所有服务
`make clean`	`make stop` + 删除 `.deer-flow`、`.langgraph_api`、日志	停止服务并清理临时文件	完全清理

scripts/serve.sh 的完整动作链（以 make dev 为例）：

复制代码

make dev
  → scripts/check.py（检查依赖）
  → scripts/serve.sh --dev
      1. 加载 .env 文件中的环境变量
      2. 停止所有已运行的服务
      3. 检查 config.yaml 是否存在
      4. 运行 scripts/config-upgrade.sh（增量合并配置）
      5. 安装依赖: cd backend && uv sync + cd frontend && pnpm install
      6. 同步前端 .env.local（Gateway 模式下设置 LANGGRAPH_BASE_URL）
      7. 启动 LangGraph Server: uv run langgraph dev --port 2024
      8. 启动 Gateway: uv run uvicorn app.gateway.app:app --port 8001
      9. 启动 Frontend: pnpm run dev（端口 3000）
      10. 启动 Nginx: nginx -c nginx.local.conf（端口 2026）
      11. 等待所有端口就绪

5.4 Docker 开发类命令

命令	触发的脚本	说明
`make docker-init`	`scripts/docker.sh init`	拉取沙箱 Docker 镜像
`make docker-start`	`scripts/docker.sh start`	构建并启动开发 Docker 环境（docker-compose-dev.yaml）
`make docker-start-pro`	`scripts/docker.sh start --gateway`	Gateway 模式启动开发 Docker
`make docker-stop`	`scripts/docker.sh stop`	停止开发 Docker 容器
`make docker-logs`	`scripts/docker.sh logs`	查看开发 Docker 日志

scripts/docker.sh start 的完整动作链：

复制代码

make docker-start
  → scripts/docker.sh start
      1. 检测 config.yaml 中的沙箱模式（local/aio/provisioner）
      2. 确保 config.yaml 存在（不存在则从 example 复制）
      3. 确保 extensions_config.json 存在
      4. 设置 Nginx 路由变量（Gateway 模式下重定向到 Gateway）
      5. 执行: docker compose -p deer-flow-dev -f docker-compose-dev.yaml up --build -d
      6. 启动的服务: nginx + frontend + gateway + langgraph（+ provisioner 如果 K8s 模式）

5.5 Docker 生产类命令

命令	触发的脚本	说明
`make up`	`scripts/deploy.sh`	构建并启动生产 Docker（docker-compose.yaml）
`make up-pro`	`scripts/deploy.sh --gateway`	Gateway 模式生产 Docker
`make down`	`scripts/deploy.sh down`	停止并移除生产 Docker 容器

scripts/deploy.sh 的完整动作链：

复制代码

make up
  → scripts/deploy.sh
      1. 设置 DEER_FLOW_HOME（默认 backend/.deer-flow）
      2. 设置 DEER_FLOW_REPO_ROOT
      3. 确保 config.yaml 存在
      4. 确保 extensions_config.json 存在
      5. 生成 BETTER_AUTH_SECRET（首次生成后持久化到 .deer-flow/.better-auth-secret）
      6. 检测沙箱模式
      7. 确定启动的服务集合:
         - standard: frontend + gateway + langgraph + nginx
         - gateway:  frontend + gateway + nginx
         - 如果 provisioner 模式: 追加 provisioner
      8. 检查 Docker Socket（AIO/Provisioner 模式需要）
      9. 执行: docker compose -p deer-flow -f docker-compose.yaml up --build -d

六、香港服务器首次部署（Docker 方式）

6.1 部署场景说明

这个方案的核心思路：

复制代码

┌────────────────────┐         ┌────────────────────┐
│   香港服务器         │         │   内陆服务器         │
│                    │         │                    │
│  1. 克隆代码       │         │  4. 加载镜像快照     │
│  2. 构建 Docker    │  ────→  │  5. 启动容器        │
│  3. 导出镜像快照    │  传输   │  6. 修改配置         │
│                    │         │                    │
└────────────────────┘         └────────────────────┘

香港服务器: 网络畅通，可直接拉取所有依赖
内陆服务器: 使用预构建的镜像，无需再次下载依赖

6.2 Step 1：克隆项目

bash 复制代码

# 在香港服务器上
cd /opt
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

6.3 Step 2：生成配置文件

bash 复制代码

make config

此命令生成以下文件：

config.yaml（从 config.example.yaml 复制）
.env（从 .env.example 复制）
frontend/.env（从 frontend/.env.example 复制）

6.4 Step 3：编辑配置（国产模型示例）

编辑 .env：

bash 复制代码

vi .env

填入你的 API Key：

bash 复制代码

# 选择你使用的模型平台，填入对应 Key
DEEPSEEK_API_KEY=sk-xxxxxxxx
# VOLCENGINE_API_KEY=xxxxxxxx
# MOONSHOT_API_KEY=sk-xxxxxxxx

编辑 config.yaml，取消注释并配置你选用的国产模型。以 DeepSeek 为例：

yaml 复制代码

models:
  - name: deepseek-v3
    display_name: DeepSeek V3
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: deepseek-reasoner
    api_key: $DEEPSEEK_API_KEY
    timeout: 600.0
    max_retries: 2
    max_tokens: 8192
    supports_thinking: true
    supports_vision: false
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled

  - name: deepseek-chat
    display_name: DeepSeek Chat
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: deepseek-chat
    api_key: $DEEPSEEK_API_KEY
    timeout: 600.0
    max_retries: 2
    max_tokens: 8192
    supports_thinking: false
    supports_vision: false

6.5 Step 4：构建 Docker 镜像

bash 复制代码

# 生产模式构建 + 启动
make up

此命令的完整动作链已在「第五章」中解读。首次执行时，Docker 将：

拉取基础镜像（python:3.12-slim-bookworm, node:22-alpine, nginx:alpine 等）
在 builder 阶段安装系统依赖和 Python 包
在前端阶段安装 Node.js 包并执行 Next.js 构建
生成最终的生产镜像

首次构建耗时约 10-20 分钟（取决于网络速度）。

6.6 Step 5：验证服务运行

bash 复制代码

# 查看容器状态
docker compose -p deer-flow -f docker/docker-compose.yaml ps

# 期望输出：
# deer-flow-nginx       running   0.0.0.0:2026->2026/tcp
# deer-flow-frontend    running
# deer-flow-gateway     running
# deer-flow-langgraph   running

访问 http://<香港服务器IP>:2026，确认：

前端页面正常加载
发送一条测试消息，验证 Agent 能正常回复

查看日志排查问题：

bash 复制代码

# 查看所有服务日志
docker compose -p deer-flow -f docker/docker-compose.yaml logs -f

# 只看某个服务
docker compose -p deer-flow -f docker/docker-compose.yaml logs -f gateway
docker compose -p deer-flow -f docker/docker-compose.yaml logs -f langgraph

6.7 Step 6：导出 Docker 镜像快照

确认服务正常运行后，停止容器并导出镜像：

bash 复制代码

# 停止服务
make down

# 查看已构建的镜像
docker images | grep deer-flow
# 输出示例：
# deer-flow-frontend    latest    abc123    2 hours ago    500MB
# deer-flow-gateway     latest    def456    2 hours ago    1.2GB
# deer-flow-langgraph   latest    def456    2 hours ago    1.2GB
# （gateway 和 langgraph 使用相同的 backend 镜像）

# 方案 A：逐个导出（推荐，更灵活）
docker save deer-flow-frontend:latest | gzip > deer-flow-frontend.tar.gz
docker save deer-flow-gateway:latest | gzip > deer-flow-gateway.tar.gz
docker save deer-flow-langgraph:latest | gzip > deer-flow-langgraph.tar.gz

# 同时导出 nginx:alpine（因为内陆可能拉不到）
docker save nginx:alpine | gzip > nginx-alpine.tar.gz

# 方案 B：一次性导出所有相关镜像
docker save \
    deer-flow-frontend:latest \
    deer-flow-gateway:latest \
    deer-flow-langgraph:latest \
    nginx:alpine \
    | gzip > deer-flow-all-images.tar.gz

# 查看导出文件大小
ls -lh *.tar.gz

6.8 Step 7：打包项目配置

除了 Docker 镜像，还需要传输项目配置文件：

bash 复制代码

# 创建配置打包目录
mkdir -p /tmp/deer-flow-transfer

# 复制必要文件（不含 node_modules 和 .venv）
cp -r config.yaml .env frontend/.env extensions_config.json \
      docker/ skills/ Makefile scripts/ \
      docker-compose*.yaml \
      /tmp/deer-flow-transfer/ 2>/dev/null || true

# 实际上更简单的方式：直接传输整个项目目录（排除大文件）
tar czf deer-flow-project.tar.gz \
    --exclude='.git' \
    --exclude='node_modules' \
    --exclude='.venv' \
    --exclude='.next' \
    --exclude='backend/.deer-flow' \
    --exclude='*.tar.gz' \
    .

6.9 Step 8：传输到内陆服务器

bash 复制代码

# 使用 scp 传输（或其他方式如 rsync, 对象存储等）
scp deer-flow-all-images.tar.gz user@inland-server:/opt/
scp deer-flow-project.tar.gz user@inland-server:/opt/

七、内陆服务器部署（从镜像快照启动）

7.1 准备工作

确保内陆服务器已安装 Docker（参见「第四章：最小 Linux 运行环境配置」）。

7.2 加载 Docker 镜像

bash 复制代码

cd /opt

# 加载镜像（方案 A：逐个加载）
gunzip -c deer-flow-frontend.tar.gz | docker load
gunzip -c deer-flow-gateway.tar.gz | docker load
gunzip -c deer-flow-langgraph.tar.gz | docker load
gunzip -c nginx-alpine.tar.gz | docker load

# 加载镜像（方案 B：一次性加载）
gunzip -c deer-flow-all-images.tar.gz | docker load

# 验证镜像已加载
docker images | grep -E "deer-flow|nginx"

7.3 解压项目文件

bash 复制代码

mkdir -p /opt/deer-flow
cd /opt/deer-flow
tar xzf /opt/deer-flow-project.tar.gz

7.4 调整配置（如需更改模型）

如果需要切换模型或更新 API Key：

bash 复制代码

# 编辑环境变量
vi .env

# 编辑模型配置
vi config.yaml

7.5 启动服务

由于镜像已预构建，我们跳过构建步骤直接启动：

bash 复制代码

# 方法 1：使用 deploy.sh 的 start 子命令（跳过构建）
./scripts/deploy.sh start

# 方法 2：直接使用 docker compose
# 先设置必要的环境变量
export DEER_FLOW_HOME="$(pwd)/backend/.deer-flow"
export DEER_FLOW_CONFIG_PATH="$(pwd)/config.yaml"
export DEER_FLOW_EXTENSIONS_CONFIG_PATH="$(pwd)/extensions_config.json"
export DEER_FLOW_DOCKER_SOCKET="/var/run/docker.sock"
export DEER_FLOW_REPO_ROOT="$(pwd)"
export BETTER_AUTH_SECRET=$(python3 -c 'import secrets; print(secrets.token_hex(32))')

mkdir -p "$DEER_FLOW_HOME"

docker compose -p deer-flow -f docker/docker-compose.yaml up -d \
    --no-build \
    frontend gateway langgraph nginx

--no-build 参数告诉 Docker Compose 不重新构建镜像，直接使用本地已有的镜像启动。

7.6 验证服务

bash 复制代码

# 查看容器状态
docker compose -p deer-flow -f docker/docker-compose.yaml ps

# 查看日志
docker compose -p deer-flow -f docker/docker-compose.yaml logs -f

# 访问测试
curl -s http://localhost:2026/health

访问 http://<内陆服务器IP>:2026，发送测试消息验证。

八、docker-compose.yaml 深度解读

8.1 服务拓扑

生产环境的 docker/docker-compose.yaml 定义了以下服务：

复制代码

                    ┌─────────────────────┐
                    │  nginx:alpine       │
                    │  端口: 2026         │
                    │  容器: deer-flow-nginx│
                    └────┬───┬───┬────────┘
                         │   │   │
            ┌────────────┘   │   └────────────┐
            ▼                ▼                ▼
  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
  │  frontend    │  │  gateway     │  │  langgraph   │
  │  端口: 3000  │  │  端口: 8001  │  │  端口: 2024  │
  │  Next.js     │  │  FastAPI     │  │  LangGraph   │
  │  prod 目标   │  │  4 workers   │  │  dev 模式    │
  └──────────────┘  └──────────────┘  └──────────────┘
                                            │
                                     ┌──────────────┐
                                     │ provisioner  │
                                     │ 端口: 8002   │
                                     │ (可选, K8s)  │
                                     └──────────────┘

8.2 各服务关键配置

nginx 服务：

镜像：nginx:alpine（预构建，无需自定义构建）
端口映射：${PORT:-2026}:2026（可通过 PORT 环境变量自定义）
通过 envsubst 在启动时将环境变量注入 nginx.conf
LANGGRAPH_UPSTREAM 和 LANGGRAPH_REWRITE 控制 Standard/Gateway 模式路由

frontend 服务：

构建目标：prod（包含 Next.js 生产构建产物）
环境变量：DEER_FLOW_INTERNAL_GATEWAY_BASE_URL=http://gateway:8001（容器间通信）
BETTER_AUTH_SECRET：用于 Next.js 认证会话安全

gateway 服务：

启动命令：uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --workers 4
挂载卷：
- config.yaml → /app/backend/config.yaml（只读）
- extensions_config.json → /app/backend/extensions_config.json（只读）
- skills/ → /app/skills/（只读）
- .deer-flow/ → /app/backend/.deer-flow/（读写，运行时数据）
- Docker Socket → /var/run/docker.sock（DooD 模式，启动沙箱容器）

langgraph 服务：

启动命令：uv run langgraph dev --no-browser --no-reload --host 0.0.0.0 --port 2024
使用与 gateway 相同的后端镜像（由 backend/Dockerfile 构建）
挂载卷与 gateway 基本相同

8.3 网络与通信

所有服务在同一个 Docker bridge 网络 deer-flow 中，通过容器名相互访问：

复制代码

nginx     → frontend:3000
nginx     → gateway:8001
nginx     → langgraph:2024
gateway   → langgraph:2024（IM 频道场景）
gateway   → host.docker.internal（DooD 沙箱容器通信）
langgraph → host.docker.internal（DooD 沙箱容器通信）

extra_hosts: host.docker.internal:host-gateway 使容器内可通过 host.docker.internal 访问宿主机网络，这是 DooD（Docker-outside-of-Docker）模式的关键。

8.4 关键环境变量说明

变量	默认值	说明
`PORT`	`2026`	Nginx 对外暴露端口
`DEER_FLOW_HOME`	`$REPO_ROOT/backend/.deer-flow`	运行时数据存储目录
`DEER_FLOW_CONFIG_PATH`	`$REPO_ROOT/config.yaml`	config.yaml 路径
`DEER_FLOW_DOCKER_SOCKET`	`/var/run/docker.sock`	Docker Socket 路径
`GATEWAY_WORKERS`	`4`	Gateway uvicorn worker 数量
`LANGGRAPH_JOBS_PER_WORKER`	`10`	LangGraph 每 worker 并发任务数
`LANGGRAPH_ALLOW_BLOCKING`	`0`	是否允许阻塞调用
`APT_MIRROR`	（空）	Debian APT 镜像源
`UV_IMAGE`	`ghcr.io/astral-sh/uv:0.7.20`	uv 安装来源镜像
`UV_INDEX_URL`	`https://pypi.org/simple`	Python 包索引 URL
`NPM_REGISTRY`	（空）	NPM 包注册中心 URL

九、内陆网络环境的构建优化

如果你需要在内陆服务器上直接构建（而非使用香港预构建镜像），以下是镜像源配置方案：

9.1 构建参数总表

在 make up 或 docker compose build 时，通过环境变量传入国内镜像源：

bash 复制代码

# 方式 1：导出环境变量后构建
export APT_MIRROR=mirrors.aliyun.com
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export NPM_REGISTRY=https://registry.npmmirror.com

# uv 镜像（如果 ghcr.io 不可达，需要手动拉取或使用本地镜像）
# 方案 A: 提前在可达网络拉取并 docker save/load
# 方案 B: 构建一个本地的 uv 镜像并修改 UV_IMAGE
export UV_IMAGE=ghcr.io/astral-sh/uv:0.7.20

make up

# 方式 2：在 docker compose 命令中指定
APT_MIRROR=mirrors.aliyun.com \
UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
NPM_REGISTRY=https://registry.npmmirror.com \
make up

9.2 各镜像源说明

APT 镜像源（Debian 系统包）：

阿里云：mirrors.aliyun.com
清华 TUNA：mirrors.tuna.tsinghua.edu.cn
中科大 USTC：mirrors.ustc.edu.cn

Python 包索引（PyPI）：

清华 TUNA：https://pypi.tuna.tsinghua.edu.cn/simple
阿里云：https://mirrors.aliyun.com/pypi/simple/
豆瓣：https://pypi.douban.com/simple

NPM 注册中心：

淘宝 NPM 镜像：https://registry.npmmirror.com

9.3 Node.js 源的问题

Backend Dockerfile 中从 deb.nodesource.com 安装 Node.js，这在内陆可能受阻。解决方案：

推荐方案：在香港构建镜像后传输（本教程的主方案）
备选方案：修改 Dockerfile，使用 nvm 或预编译二进制安装 Node.js

十、运维操作手册

10.1 日常管理命令

bash 复制代码

# 查看服务状态
docker compose -p deer-flow -f docker/docker-compose.yaml ps

# 查看日志（实时跟踪）
docker compose -p deer-flow -f docker/docker-compose.yaml logs -f

# 只看某个服务的日志
docker compose -p deer-flow -f docker/docker-compose.yaml logs -f gateway
docker compose -p deer-flow -f docker/docker-compose.yaml logs -f langgraph
docker compose -p deer-flow -f docker/docker-compose.yaml logs -f frontend

# 重启某个服务
docker compose -p deer-flow -f docker/docker-compose.yaml restart gateway

# 停止所有服务
make down

# 重新启动（不重新构建）
./scripts/deploy.sh start

# 重新构建并启动
make up

10.2 配置更新流程

bash 复制代码

# 1. 编辑配置
vi config.yaml
vi .env

# 2. 重启 gateway 和 langgraph（它们挂载了 config.yaml）
docker compose -p deer-flow -f docker/docker-compose.yaml restart gateway langgraph

# 如果修改了前端相关配置，也需重启 frontend
docker compose -p deer-flow -f docker/docker-compose.yaml restart frontend

10.3 健康检查

bash 复制代码

# Gateway 健康检查
curl http://localhost:2026/health

# 查看可用模型列表（验证模型配置）
curl http://localhost:2026/api/models

# 查看技能列表
curl http://localhost:2026/api/skills

10.4 清理操作

bash 复制代码

# 停止并删除容器
make down

# 清理沙箱容器（如果使用了 AIO 模式）
./scripts/cleanup-containers.sh deer-flow-sandbox

# 清理 Docker 未使用的镜像和缓存
docker system prune -f

# 清理运行时数据（谨慎：会删除对话历史）
rm -rf backend/.deer-flow

十一、常见问题排查

11.1 Docker 权限问题（Linux）

bash 复制代码

# 症状：Got permission denied while trying to connect to the Docker daemon socket
# 解决：
sudo usermod -aG docker $USER
newgrp docker
# 或重新登录 SSH

11.2 端口冲突

bash 复制代码

# 检查端口占用
ss -tlnp | grep -E "2026|3000|8001|2024"

# 修改 DeerFlow 端口
export PORT=8080
make up
# 访问 http://localhost:8080

11.3 镜像加载后标签不匹配

如果从香港导出的镜像标签与 docker-compose.yaml 中期望的不一致：

bash 复制代码

# 查看已加载的镜像
docker images

# 如果需要重新打标签
docker tag <image_id> deer-flow-gateway:latest
docker tag <image_id> deer-flow-frontend:latest
docker tag <image_id> deer-flow-langgraph:latest

11.4 Gateway 启动失败

bash 复制代码

# 查看详细日志
docker compose -p deer-flow -f docker/docker-compose.yaml logs gateway

# 常见原因：
# 1. config.yaml 语法错误 → 用 python3 -c "import yaml; yaml.safe_load(open('config.yaml'))" 检查
# 2. .env 中的 API Key 未设置 → 检查 .env 文件
# 3. 配置版本不匹配 → 运行 make config-upgrade

11.5 LangGraph 启动慢

LangGraph 首次启动时会编译 Agent 图，可能需要 30-60 秒。如果持续无法启动：

bash 复制代码

# 查看日志
docker compose -p deer-flow -f docker/docker-compose.yaml logs -f langgraph

# 检查 .langgraph_api 目录是否有权限问题
ls -la backend/.langgraph_api/

总结

本篇覆盖了 DeerFlow 部署的完整链路：

配置体系 --- 三文件协同（config.yaml + .env + extensions_config.json），理解每个配置项的作用
国产模型配置 --- 豆包、DeepSeek、Kimi、MiniMax、Qwen 五大国产模型的详细配置示例和推荐组合
Docker 镜像解析 --- 多阶段构建的每一步动作、涉及的网络请求和镜像依赖
最小运行环境 --- Ubuntu 22.04 + Docker Engine + 4 vCPU / 8 GB RAM 的最小配置
Make 命令解读 --- 每条 make 命令背后触发的完整动作链
香港首建到内陆迁移 --- docker save/load 的镜像传输方案
运维手册 --- 日常管理、配置更新、健康检查和故障排查

关键决策点：

首次部署选香港/海外服务器构建，利用畅通网络下载所有依赖
导出镜像快照传输到内陆，避免内陆网络环境的各种限制
使用国产大模型 API，DeepSeek 和豆包等均可直接在内陆网络环境访问

下篇预告

下一篇我们将进入 DeerFlow 的实际使用，展示从创建对话到获取 Agent 回复的完整工作流，包括文件上传、工具调用观察和制品管理等核心交互体验。

DeerFlow 系列教程 第五篇 | 配置与 Docker 部署全指南：从香港首建到内陆迁移

一、配置体系全解

1.1 三文件协同架构

1.2 配置文件生成

1.3 config.yaml 核心结构

二、国产大模型配置详解

2.1 火山引擎豆包（Doubao）

2.2 DeepSeek

2.3 Kimi K2.5（Moonshot）

2.4 MiniMax（中国区）

2.5 通义千问 Qwen（通过 vLLM 本地部署）

2.6 国产模型推荐组合方案

2.7 Provider 类对照表

2.8 .env 完整示例（国产模型版）

2.9 extensions_config.json 配置

三、Docker 镜像深度解析

3.1 涉及的 Docker 镜像清单

3.2 Backend Dockerfile 逐层解析

3.3 Frontend Dockerfile 逐层解析

3.4 构建过程中的网络请求汇总

四、最小 Linux 运行环境配置

4.1 服务器硬件要求

4.2 操作系统要求

4.3 Docker 守护进程配置（国内镜像加速）

4.4 防火墙端口开放

五、Make 命令完全解读

5.1 配置类命令

5.2 检查和安装类命令

5.3 本地运行类命令

5.4 Docker 开发类命令

5.5 Docker 生产类命令

六、香港服务器首次部署（Docker 方式）

6.1 部署场景说明

6.2 Step 1：克隆项目

6.3 Step 2：生成配置文件

6.4 Step 3：编辑配置（国产模型示例）

6.5 Step 4：构建 Docker 镜像

6.6 Step 5：验证服务运行

6.7 Step 6：导出 Docker 镜像快照

6.8 Step 7：打包项目配置

6.9 Step 8：传输到内陆服务器

七、内陆服务器部署（从镜像快照启动）

7.1 准备工作

7.2 加载 Docker 镜像

7.3 解压项目文件

7.4 调整配置（如需更改模型）

7.5 启动服务

7.6 验证服务

八、docker-compose.yaml 深度解读

8.1 服务拓扑

8.2 各服务关键配置

8.3 网络与通信

8.4 关键环境变量说明

九、内陆网络环境的构建优化

9.1 构建参数总表

9.2 各镜像源说明

9.3 Node.js 源的问题

十、运维操作手册

10.1 日常管理命令

10.2 配置更新流程

10.3 健康检查

10.4 清理操作

十一、常见问题排查

11.1 Docker 权限问题（Linux）

11.2 端口冲突

11.3 镜像加载后标签不匹配

11.4 Gateway 启动失败

11.5 LangGraph 启动慢

总结

下篇预告

DeerFlow 系列教程第五篇 | 配置与 Docker 部署全指南：从香港首建到内陆迁移