企业官网建设流程全解析

1. 先聊明白：DeerFlow 到底是什么，以及我为什么铁了心用 Docker Desktop 部署

如果你最近关注 AI Agent 方向，多半听过 DeerFlow 这个名字。它是字节跳动开源的一个深度研究 Agent 框架，英文全称是 Deep Research Agent，核心目标非常直接：喂给它一个研究型问题，它自己规划任务、拆解子问题、联网搜索、聚合信息，最后产出一份结构化研究报告。和常见的单轮问答不同，它更像一个会自己查资料、做笔记、写综述的研究助理，整个流程可以持续几分钟甚至更久，期间你会看到它在不停地搜索、阅读、整理图谱、组织答案。

我第一次接触这个项目是在同事的推荐下，当时我首先想到的是：这类 Agent 框架通常依赖不是一般的重。LangGraph 编排、多个后端服务、前端界面、数据库、知识图谱组件……如果直接用裸机 Python 环境跑，光是解决依赖冲突就能耗掉一晚上。所以我从始至终就把目标锁定在 Docker 方案上，具体来说就是 Docker Desktop + DeerFlow 官方镜像这套组合拳。这篇内容我就是想把我实际部署的完整过程、踩过的坑、以及配置模型和搜索 API 时最容易让人迷惑的地方一次说清楚。

适合看这篇内容的人有三类：一是打算本地体验 DeerFlow 但没有 Linux 服务器的 Windows 或 macOS 用户；二是熟悉 Python 但不想折腾环境依赖，希望用容器快速起服务的开发者；三是已经在跑 Agent 项目，想对比 Docker 部署和裸机部署差异的从业者。不管你是哪种，只要跟着走一遍，基本都能把 DeerFlow 在本地稳稳跑起来。

2. 部署前把地基打好：Docker Desktop 的安装、虚拟化检测与资源分配

很多人在 DeerFlow 本身没遇到问题，反而卡在 Docker Desktop 起不来，这是我最想先聊透的部分。Docker Desktop 在 Windows 上依赖虚拟化能力，默认走 WSL2 后端，如果你装完之后点击图标报错，提示 virtualization support not detected 或者类似的“虚拟化未开启”，那说明系统底层的虚拟化开关还没打开。

2.1 最容易卡住的“虚拟化没有开启”问题

这个问题的本质是：Windows 上的 Docker 需要宿主机提供 CPU 虚拟化能力，由 BIOS/UEFI 里的 VT-x（Intel）或 SVM（AMD）开关控制。很多品牌机默认把它关了，或者因为系统更新重置了 BIOS 设置。排查方法很简单，打开任务管理器，切到“性能”选项卡，看 CPU 右下角有没有“虚拟化：已启用”。如果显示“已禁用”，就需要重启电脑进入 BIOS，在 Advanced 或 Security 菜单下找到 Intel Virtualization Technology / SVM Mode 之类的选项，设为 Enabled，保存重启。

除了 BIOS 这一层，Windows 功能里还有几个开关要确认：Hyper-V、虚拟机平台、适用于 Linux 的 Windows 子系统。你可以在控制面板的“启用或关闭 Windows 功能”里把它们打开，或者直接用管理员 PowerShell 执行：

dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V-All /all /norestart dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完重启，然后打开微软商店把 WSL2 内核更新到最新。这里我多说一句，如果你之前装过 WSL1 的老版本，建议先跑一下wsl --set-default-version 2，确保 Docker Desktop 使用的发行版跑在 WSL2 上而不是 WSL1，两种版本的性能和兼容性差别很大。

2.2 WSL2 后端的内存限制与磁盘占用

即使 Docker Desktop 能正常启动，DeerFlow 这类多容器项目对资源的需求也不低。我在自己 16GB 内存的 MacBook Pro 上跑过一次，同时起后端、前端和数据库，内存占用基本稳定在 6GB 到 8GB 之间。Windows 用户还要考虑 WSL2 本身会动态占用内存，建议在 Docker Desktop 的 Settings -> Resources 里把内存调成 6GB 以上，如果机器只有 8GB 内存，至少留出 4GB 给 Docker，否则容器一多很容易卡死或者被 OOM Kill。

磁盘方面，WSL2 的虚拟磁盘文件默认放在%LOCALAPPDATA%\Docker\wsl\data\ext4.vhdx，它会随着镜像和容器的增多越来越大，而且不会自动收缩。我用了一段时间后这个文件涨到了 30 多 GB，后来用wsl --shutdown之后跑Optimize-VHD才压回去。所以如果你打算长期用 Docker Desktop 跑 AI 项目，从一开始就给系统盘留足空间，或者干脆把 Docker 的数据目录迁移到大容量分区。

2.3 拉取 DeerFlow 项目并理解目录结构

地基打好之后就开始拉项目。DeerFlow 的官方仓库在 GitHub 上，直接：

git clone https://github.com/bytedance/deer-flow.git cd deer-flow

克隆下来之后别急着跑，先花两分钟把目录结构过一遍。你会看到根目录下有docker-compose.yml、环境变量示例文件env.example、后端代码目录、前端组件目录以及文档目录。这个项目的整体架构是典型的前后端分离：后端负责 Agent 编排和任务执行，前端提供可视化界面，api-gateway 做请求转发，另外还会拉起基础数据服务用来存中间结果和知识图谱数据。

把目录结构看懂的好处是，后面排查问题的时候你知道该去哪个容器的日志里找线索，而不是两眼一抹黑。比如报告生成异常，大概率是后端服务的问题；界面加载不出来，则要先看前端服务和 api-gateway 的日志。这一步花不了几分钟，但能给你后面省下大量时间。

3. 最关键的一步：模型服务与搜索 API 的配置

DeerFlow 本身不是一个能独立工作的应用，它的研究链路里有两个外部依赖缺一不可：大模型推理能力和联网搜索能力。模型负责规划、总结、生成报告，搜索 API 负责在研究的各个阶段召回真实世界的信息。你在部署过程中碰到的绝大多数“能启动但不出活”的问题，十有八九都出在这一环。

3.1 .env 文件里的核心变量

DeerFlow 通过环境变量读取配置，仓库里给了一个env.example，你需要把它复制成.env然后逐项填写。Windows 用户注意，复制之后用编辑器打开，确认换行符是 LF 而不是 CRLF，否则某些配置解析会有奇怪的问题。核心变量大概是下面这些：

# 模型相关 LLM_MODEL=gpt-4o-mini OPENAI_API_KEY=sk-xxxx OPENAI_BASE_URL=https://api.openai.com/v1 # 搜索相关 TAVILY_API_KEY=tvly-xxxx

如果你用的是兼容 OpenAI 协议的其他平台，只需要把OPENAI_BASE_URL改成对应接口地址，OPENAI_API_KEY填那个平台的密钥。模型名则根据平台实际支持的模型去填，比如某些国产模型服务用的是deepseek-chat、qwen-plus这类名字。这里有个容易搞混的概念：OPENAI_API_KEY只是一个约定俗称的变量名，并不强制要求你真有 OpenAI 的账号，它只是一个被模型调用层统一读取的配置项。

搜索 API 这块，DeerFlow 官方文档里提到支持 Tavily 和 Brave Search。我自己的建议是优先选 Tavily，它的结果专门为 RAG 和 Agent 场景优化过，免费额度对个人测试来说足够用一阵子。注册之后在控制台拿到 API Key，填到TAVILY_API_KEY里就行。

3.2 三种大模型接入方式对比

把模型接入方式分成三种理解会比较清楚：云端托管模型、兼容 OpenAI 协议的第三方平台、本地模型服务。

云端托管平台最省事，像 OpenAI 官方或者各大云厂商的模型服务，你只要在控制台创建密钥、把 base_url 和 key 填进.env就行。延迟低、稳定性好，唯一的问题是密钥通常要花钱，而且部分平台在国内网络环境下访问不稳定，这一点你需要根据自己的实际网络情况选择可正常访问的服务。

第三方兼容平台在参数配置上最友好，因为协议一样，DeerFlow 不需要针对它们做额外适配。市面上很多国产模型平台都提供 OpenAI 兼容接口，直接改 base_url 和 model 名称即可。对于国内用户来说，这类方案在日常使用中最省心。

本地模型方案适合隐私要求高或者想省钱的人，用 Ollama 把模型跑在本机，然后在.env里配置：

LLM_MODEL=qwen2.5:7b OPENAI_API_KEY=ollama OPENAI_BASE_URL=http://host.docker.internal:11434/v1

这里有个非常重要的细节：容器里的程序不能直接通过localhost访问宿主机的 Ollama 服务，必须使用host.docker.internal这个特殊域名来指代宿主机。而且 Ollama 需要开启兼容 OpenAI 协议的接口路径/v1，否则 DeerFlow 调用模型时会报 404 或者协议不兼容。本地 7B 级别的模型跑研究任务比较吃力，速度和效果都会明显弱于云端旗舰模型，但用来跑通链路是完全可行的。

3.3 搜索 API 没配好会发生什么

如果搜索 API 没有配置或者配额用完了，DeerFlow 并不会直接崩溃，而是会表现出一种很迷惑的状态：任务启动了，日志在滚动，但研究报告一直不往前推进，反复在处理“搜索失败”或返回空结果。我第一次部署时就遇到过这个问题，半天没反应过来，以为是 Agent 的逻辑出bug了，后来一看日志里全是搜索请求超时和 quota exhausted 的报错，才发现是 Tavily 免费额度已经跑光了。

所以配置完之后，建议先用搜索 API 服务商提供的测试工具或直接发一个最简单的请求验证 key 是否有效，再去跑 DeerFlow。这一步验证的成本几乎为零，却能帮你后续排查时少走一大段弯路。

3.4 密钥安全：.env 不要提交进仓库

最后强调一个可能被忽视的点：.env文件里装的是真金白银的密钥，如果项目目录本身是 Git 仓库，一定要确认.gitignore里已经包含了.env。我见过有人把密钥不小心推送到公开仓库之后，几分钟内就被爬虫扫走、账单刷爆的案例。尤其是用了云端付费模型服务的人，这一条真的关乎真金白银，务必养成习惯。

4. Docker Compose 启动全流程：从构建镜像到跑通 Web 界面

配置完成的标志是.env文件内容完整、密钥格式正确。这时候就可以进入真正的部署环节了。我强烈建议你在终端里进到项目根目录，确认docker-compose.yml和.env在同级目录，然后执行构建命令。

4.1 镜像构建阶段会发生什么

docker compose up --build -d

这条命令做了三件事：按 Dockerfile 构建后端镜像，拉取依赖的基础镜像，然后按 compose 文件里的定义把各个服务依次启动。第一次构建是非常典型的重活，需要拉取 Python 基础镜像、安装 PyTorch/CUDA 相关依赖（取决于项目是否启用了 GPU 加速）、安装各种 Python 包，整个过程在普通网络环境下可能要跑十几分钟到半小时。

构建过程中最容易让人困惑的是终端输出很长，滚动得很快。其实你只需要关注最后是不是每个 service 都显示Started或者Healthy即可。如果你发现某个服务反复重启，先别急着整体推倒重来，用docker compose ps看一下哪个服务状态异常，再用docker compose logs <service名>单独看它的日志。很多时候只是数据库比后端晚启动了一两秒，后端依赖检查失败后会自己重启，过一会儿就恢复正常了，这种只要稍等片刻就行。

4.2 镜像仓库拉取慢的处理思路

构建阶段还有一件高频烦心事：基础镜像拉取太慢。这个问题的根源是 Docker Hub 的默认镜像源在某些网络环境下访问速度不稳定。解决思路之一是在 Docker Desktop 的 Docker Engine 配置里添加国内可用的镜像加速地址，格式参考：

{ "registry-mirrors": [ "https://docker.m.daocloud.io" ] }

填完之后点击 Apply & Restart，让配置生效。这个操作非常通用，不仅对 DeerFlow 有效，你后续用 Docker 跑任何项目都会舒服很多。另外，如果你的网络环境拉取 GitHub 仓库或者镜像特别慢，也可以选择网络条件比较好的时段进行构建，多试几次大多能成。

4.3 从日志确认服务就绪

启动完成之后，通过 Docker Desktop 的容器列表或者命令行都能看到服务状态。我习惯用命令行来确认，信息更直接：

docker compose ps

正常情况下，你会看到若干服务处于 running 状态。然后打开日志窗口持续观察一段时间：

docker compose logs -f backend

日志里如果出现类似 Application startup complete 或者相应的框架启动标志，说明后端就绪。这时候打开浏览器访问 Docker Desktop 显示的映射端口，一般入口是http://localhost:8501或者你在 compose 配置里自定义的前端端口，应该能看到 DeerFlow 的交互界面。

我个人的习惯是，日志连续观察至少一分钟，确认服务没有在启动后立即崩掉。因为有些服务启动时一切正常，但由于配置缺失，一旦收到第一个请求才暴露出问题，这种“偶发崩溃”比“启动失败”更隐蔽。

4.4 CLI 入口作为备用方案

Web 界面是大多数人首选的使用方式，但如果界面因为某些原因起不来，DeerFlow 本身还提供了命令行入口。你可以在容器里直接执行 Python 调用，或者用docker compose exec进入后端容器手动触发任务。具体命令格式建议大家以仓库 README 为准，不同版本可能会有调整。

有一个实用技巧是：在跑正式研究任务之前，可以先用 CLI 入口跑一个非常小的测试任务，看整条链路是否贯通。CLI 方式更容易观察分阶段日志，也更容易做最小化问题复现。等 CLI 链路通了，再回 Web 界面操作，这时候就算界面偶发异常，你也能判断问题出在前端还是后端。

5. 用真实任务验证部署：一次深度研究的完整链路

很多人部署完之后，在界面里输入了一个问题，点了运行，然后就盯着屏幕等着。如果过了几分钟没反应就开始焦虑，甚至认为部署失败了。其实 DeerFlow 的深度研究模式本来就是长时任务，和普通问答的秒级响应完全不同。学会判断“任务进行中”和“任务卡死”，是使用这个工具的基本功。

5.1 一个合适的试跑任务长什么样

验证部署是否成功，我建议选一个中等复杂度的题目，比如“盘点 2025 年目前主流的开源 Agent 框架，对比它们的架构特点和适用场景”。这个问题有明确的调研边界，搜索 API 容易命中高质量信息，又不至于像“什么是人工智能”那样宽泛。任务提交后，DeerFlow 会先做意图理解和任务规划，然后进入多轮搜索和信息聚合阶段，最后生成报告。

如果你用的是 Deep Research 模式，整个过程会比较长，数分钟到十几分钟都正常。期间界面或日志里会看到 Agent 反复规划、搜索、阅读、整理的过程。千万别在这个阶段频繁刷新页面或者重启容器，给它一点时间。

5.2 各个阶段的日志分别意味着什么

我从日志里总结过几个标志性的阶段信息，分享出来供你对号入座：

第一阶段是规划，日志里会出现任务拆解、子问题列表之类的信息，说明 Agent 正在把大问题分解成可执行的小步骤。第二阶段是搜索与阅读，会出现搜索关键词、召回结果数量、正在处理的 URL 等信息，这是整个链路里耗时最长的部分。第三阶段是图谱与记忆，项目会用知识图谱组件把提取出的实体和关系组织起来，日志里可能会有图构建或关系存储相关的记录。最后是报告生成，Agent 把所有信息汇总并交给大模型生成结构化长文。

如果你发现日志长时间停在同一阶段不动，也不要急着判定失败。先看看是不是搜索 API 在反复重试。我遇到过最典型的情况是搜索服务返回了 500 错误，Agent 按预设逻辑重试了三次，每次间隔几秒，看起来像卡住了，实际上它只是在等待重试结果。这种场景下耐心观察两到三分钟再下结论也不迟。

5.3 常见报错与排查思路

为了让你少走弯路，我把实际部署和试跑中最高频的几个问题整理成了一张表，每个都附上了定位思路：

这张表覆盖了我踩过的大多数坑，但 Docker 的生态决定了总会遇到一些新问题。真碰上了，最实用的排查思路永远是：先docker compose ps看状态，再docker compose logs看细节，最后根据日志里的异常堆栈反查配置。

6. 部署完之后，我给你的几点实在建议

DeerFlow 跑通只是第一步，真正发挥它的价值还需要做好后续的使用规划。这里分享几条我在实际使用中沉淀下来的经验。

第一，数据持久化别忽略。DeerFlow 的研究历史、中间状态、知识图谱数据都存在容器挂载的数据卷或者数据库里。如果你不清除容器和镜像，正常情况下数据不会丢。但如果你习惯用docker compose down -v来清理环境，这个命令会把数据卷一起删掉，之前跑过的所有研究记录都会消失。所以我建议不到万不得已不要加-v，日常停止用docker compose down就够了。

第二，日志文件要定期观察。长时间运行的 Agent 任务会产生大量日志，尤其是一个研究报告包含几十轮搜索的情况下，日志里全是网页正文片段。这些日志会占据 Docker 的数据目录，时间长了会给 WSL2 的虚拟磁盘文件带来不必要的膨胀。如果发现系统磁盘空间吃紧，先看 Docker 的数据目录，把不用的镜像 prune 掉，必要时重建容器。

第三，升级版本是有章法的。DeerFlow 迭代很快，社区经常会更新模型适配和 Agent 策略。想升级的时候，git pull拉取最新代码，然后重新执行docker compose up --build -d即可。升级前我强烈建议先把当前跑通的.env文件备份一份，因为新版本可能存在配置项变化，对比着旧文件改新文件效率最高。

第四，模型选型会直接影响使用体验。同一个小型 7B 模型跑深度研究任务，和旗舰级别大模型跑同一个任务，最终报告的信息密度、逻辑严谨度完全是两个量级。建议日常测试用轻量模型，正式产出用能力强的大模型，性价比最高。

最后再分享一个我的个人体会。从第一次在 Docker Desktop 里把 DeerFlow 跑通，到真正用它完成一份像样的研究报告，这中间最大的差别不在于部署技巧，而在于你会不会提研究任务。给 Agent 的问题越具体、边界越清晰，它产出的报告越有价值。工具和能力都就位之后，剩下的就是多喂好问题、多打磨任务描述，这也是 Deep Research 类 Agent 最有意思的地方。