企业官网建设流程全解析

DeerFlow 这个项目最近在搞大模型应用的人圈子里出现频率越来越高。简单说，它是一个开源的 AI 工作流与知识库问答平台，核心思路是把大语言模型、RAG 检索增强、多智能体编排串到同一条流水线上，让个人或小团队跑私有知识库问答、自动化 Agent 任务时，不用从零开始搭后端、写向量库、做权限管理。但这类系统依赖的组件很多，Python 环境、数据库、中间件、前端服务串在一起，手动装一遍非常折磨人。用 Docker Desktop 把它们全部容器化，是目前最省心、最不容易污染本机环境的方式。这篇文章我按自己实际部署踩坑的完整过程来写，适合刚接触容器化部署、或者之前只装过 Docker 但从没完整跑通一个组合服务的新手，也适合想快速把 DeerFlow 拉起来做功能验证的老手。

1. 开局先盘环境：硬件、软件与 Docker Desktop 的初始设置

很多人问我，DeerFlow 这种项目是不是一定要用服务器？答案是否定的。开发验证阶段，一台 Windows 或 Mac 电脑配 Docker Desktop 完全够用。关键不是电脑多强，而是你要先把 Docker Desktop 所在的运行环境准备利索，否则后面大概率会在启动 Docker 引擎这一步就卡住，连 DeerFlow 的镜像都还没见到，人已经被报错劝退了。

1.1 DeerFlow 适合跑在什么环境里

DeerFlow 这类“全家桶”项目，依赖的东西比普通单容器应用多。我从部署的角度把它的运行骨架拆开看，基本是三块：

• 数据层，需要 PostgreSQL 存业务数据，Redis 做缓存和队列，可能还要接一个向量数据库来存知识库切片后的 embedding。
• 服务层，包含后端 API、Agent 调度、任务执行这些进程。
• 应用层，就是你在浏览器里看到的管理界面，负责传文件、配置模型、发起问答。

这三块如果全部装在本机，麻烦点在于版本冲突。比如这个依赖要 Python 3.10，那个组件要求 PostgreSQL 14 起步，你本机早就装了 MySQL，环境一乱，排查起来想砸电脑。用 Docker Desktop 之后，每条服务都跑在自己独立的容器里，本机只需要装一个 Docker 引擎，相当于把所有依赖冲突全部隔离在容器内部，这是它最大的价值。

我建议部署 DeerFlow 的电脑至少满足：内存 16GB 起步、磁盘剩余空间 30GB 以上、CPU 支持虚拟化并且已经在 BIOS 里开启。如果你是想跑稍微大一点的本地模型，比如通过 Ollama 接入 DeepSeek 系列模型，内存和磁盘预算还要再往上加。

1.2 Docker Desktop 安装时的三个关键决定

Docker Desktop 安装包本身没什么难度，下一步下一步就行。真正影响 DeerFlow 部署体验的，是安装前你做的三个决定。

第一个决定是 Windows 上选择 WSL2 后端还是 Hyper-V 后端。WSL2 是现在最主流的方式，启动速度快、内存占用相对可控、和 Windows 集成更好。安装 Docker Desktop 之前，建议手动执行一次wsl --update，确保 WSL 内核是最新的。Docker Desktop 会在安装过程中自动帮你创建专用的发行版环境，但如果你之前装过 WSL 并且在里面做开发，最好勾选上“将 WSL 集成到 Docker Desktop 设置中”，避免两边环境互相不认。

第二个决定是资源配置。安装完成后，打开 Docker Desktop 的 Settings → Resources，能看到 CPU、内存、Swap 和磁盘镜像大小几个滑块。这里有个很容易犯的错误：直接全部拉满。其实 Docker Desktop 用的内存是从宿主机分配出去的，你给 Docker 8GB，本机就少 8GB。DeerFlow 全家桶跑起来，Postgres 常驻内存大约 200MB 上下，Redis 一百多 MB，向量库看数据量，两个应用服务加起来 1 到 2GB，整体占用大约 3GB 左右。所以我建议内存至少给 4GB，最好给 6 到 8GB，留出余量给模型推理，但不要无脑拉满。

第三个决定是磁盘镜像位置。Docker Desktop 默认把虚拟磁盘放在 C 盘用户目录下，DeerFlow 的镜像加数据卷很容易长出十几个 GB，C 盘空间吃紧的话电脑会卡到怀疑人生。我实际操作中是把整个 Docker 数据目录迁移到了 D 盘。方法不复杂：在 Docker Desktop 设置里找到 Disk image location，直接改路径，然后点击 Apply & Restart，Docker 会重新创建一个空的虚拟磁盘，旧的镜像需要重新拉取。如果你不想重新拉镜像，也可以手动移动 vhdx 文件，但我不推荐新手这么折腾，直接用官方设置最稳。

1.3 安装完先别急着拉镜像：先验证 Hello World

Docker Desktop 装完先别急着部署 DeerFlow，强烈建议先跑一个 Hello World 容器验证引擎本身可用。打开终端，输入：

docker run hello-world

能正常输出 Hello from Docker! 说明引擎已经在跑。如果这里就报错，那问题基本出在 Docker Desktop 自身，和 DeerFlow 没关系，先把这个解决再往下走。

另外，Docker Desktop 的界面默认是全英文的。社区有汉化包，比如 asxez/dockerdesktop-cn 这个项目，做成 Docker 镜像的形式，可以用来汉化桌面界面。但我个人建议保留英文界面，因为后面遇到问题去搜报错信息时，英文原文更容易命中。界面那点单词，看两三天就熟了。

还有一个细节，Windows 上如果你用 PowerShell 或 Windows Terminal，Docker Desktop 启动后会自动把 docker 命令加进 PATH，正常不需要手动配置。但如果终端提示找不到 docker 命令，先检查 Docker Desktop 是否完全启动，再检查环境变量 PATH 里有没有C:\Program Files\Docker\Docker\resources\bin这条路径。

2. 把 DeerFlow 的容器编排看明白再动手

部署任何 Docker 项目，最忌讳的就是不看编排文件直接docker compose up。DeerFlow 的镜像比较多，服务之间还有依赖关系，你需要先搞清楚每个容器是干什么的、它们之间怎么通信、哪些目录要持久化，这样出了问题你才知道去哪看日志。

2.1 DeerFlow 依赖了哪些基础设施服务

Docker 部署项目的核心思想，是把每个独立进程打包成一个镜像。DeerFlow 这种应用，通常不是单镜像，而是由多个镜像组合起来跑。按我的经验拆一下，大概率包含这几种角色：

• Web 管理端：提供页面服务，你在浏览器访问，本质是一个 Nginx 加前端静态资源的镜像。
• 后端 API：处理知识库上传、切片、模型调用、问答请求，是整条业务逻辑的核心。
• PostgreSQL：存用户、应用配置、知识库元数据、问答记录。
• Redis：做缓存、消息队列，任务调度时扛并发。
• 向量数据库：存文本切片的 embedding 向量，RAG 检索的时候用它做相似度查询。

理解这个结构有什么用？作用是定位问题。比如你在网页上传知识库文档，结果一直停在“处理中”，那你应该去后端 API 容器或向量数据库容器的日志里找线索，而不是在管理界面瞎点。再比如问答很慢，先看 Redis 有没有缓存命中，再看向量检索超时，而不是直接怀疑模型不好。

DeerFlow 官方的 Docker 编排，如果项目仓库里带了 docker-compose.yml，那它会自动把所有服务一次性定义好，你不需要手动一个个启动。如果你拿到的是一个镜像列表而没有编排文件，那就手动建一个 compose 文件，把所有服务串起来。出于方便演示，下面我会用一份常见的多服务编排结构来讲解，实际镜像名请以项目仓库 README 为准。

2.2 镜像选型与版本管理的实战建议

Docker Hub 上的镜像标签通常有 latest 和带具体版本号的。很多新手的习惯是用 latest，图省事。但说实话，DeerFlow 这类还在快速迭代的项目，latest 标签有时候会更新得很频繁，今天能跑，过两周再拉可能就是新版，和你之前创建的数据库结构不兼容，启动直接报错。

我建议的做法是：第一次部署时，去项目仓库的 releases 页面看最近一个稳定版本的发布说明，里面通常会写清楚对应的镜像标签，以及需要配套的数据库版本。把版本号记下来，在 compose 文件里写死。以后要做升级，再主动替换版本号并做好数据备份，而不是被动接受 latest 的变化。

镜像拉取环节有一个常见情况：Docker Hub 在大陆网络环境下拉取大镜像速度不稳定，多试几次或者配置一个可用的镜像源都能解决。配置位置在 Docker Desktop Settings → Docker Engine，把 registry-mirrors 配好，然后重启 Docker。这里不推荐一次性拉起 DeerFlow 所有镜像，比如你要拉五六个镜像，可以先把 compose 文件写好，然后让 compose 自动按依赖顺序拉取，比一个个docker pull更省心。

2.3 环境变量里的门道：模型接入与数据库连接

DeerFlow 这类平台一般会提供 .env.example 文件来让你配置运行参数。环境变量听起来简单，但里面有个特别容易踩的坑：容器内部地址和宿主机地址不是一回事。比如你在本机用 Ollama 跑了一个 DeepSeek 模型，DeerFlow 后端想去调用它，不能填localhost:11434，因为在 Docker 容器内部，localhost 指向的是容器自己。这时要填http://host.docker.internal:11434，这是 Docker Desktop 提供的特殊域名，能指向宿主机。

同样道理，compose 文件里多个容器之间通信，直接使用服务名即可。比如后端 API 要连 PostgreSQL，连接地址写postgres而不是localhost，Docker 内部 DNS 会自动解析到对应容器。

我自己部署时遇到最多的问题就在这。很多新手配置完 .env，看着界面还是报“模型连接失败”，排查半天发现是地址写错了。所以环境变量这份配置，一定要先理清两个网络平面：宿主机网络和容器网络。

环境变量里还有几个关键项需要特别注意：管理员账号密码、密钥、数据目录挂载路径。密码如果改了，数据库里对应记录也要一致，否则页面能打开但登录接口报错，这个很难排查。建议第一次先保持和示例文件一致，跑通了再改。

3. 完整实操：Compose 文件编写到界面跑通

前面铺垫了这么多，下面进入实际部署流程。我按自己部署时的完整步骤写，不省略细节，尽量让你照着做就能跑通。

3.1 项目目录与 .env 文件的准备

先建一个项目目录，比如 D:\projects\deerflow，后续所有配置都放这里，保持干净。目录下建一个.env文件，内容大体长这样：

# DeerFlow 基础配置示例，实际内容以官方为准 DEERFLOW_VERSION=latest POSTGRES_USER=deerflow POSTGRES_PASSWORD=change_this_password POSTGRES_DB=deerflow DATABASE_URL=postgresql://deerflow:change_this_password@postgres:5432/deerflow REDIS_URL=redis://redis:6379/0 VECTOR_DB_URL=http://vector-db:8080 # 模型配置，接入 Ollama 本地模型时使用宿主机地址 OLLAMA_BASE_URL=http://host.docker.internal:11434 OLLAMA_MODEL=deepseek-r1:7b

注意看 DATABASE_URL 里我用的是postgres这个主机名，而不是 localhost，这就是前面提到的容器间通信用服务名。如果你是照着官方文档改，大概率会看到类似的写法，别觉得奇怪，也别改成 127.0.0.1，除非你想试一次“容器启动成功但连不上数据库”的报错。

3.2 compose 文件逐段解读

接下来在项目目录下创建 docker-compose.yml。第一版可以先参考这个结构：

services: postgres: image: postgres:14 environment: POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: ${POSTGRES_DB} volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"] interval: 10s timeout: 5s retries: 5 restart: unless-stopped redis: image: redis:7-alpine command: redis-server --appendonly yes volumes: - redisdata:/data restart: unless-stopped vector-db: image: your-vector-db-image:latest environment: PERSISTENT_DIR: /data volumes: - vectordata:/data restart: unless-stopped backend: image: deerflow-backend:${DEERFLOW_VERSION} env_file: .env depends_on: postgres: condition: service_healthy redis: condition: service_started ports: - "8000:8000" restart: unless-stopped frontend: image: deerflow-frontend:${DEERFLOW_VERSION} depends_on: - backend ports: - "8088:80" restart: unless-stopped volumes: pgdata: redisdata: vectordata:

这段配置里有三个关键点值得展开。

第一个是depends_on配合健康检查。Postgres 启动到“能接受连接”是需要几秒钟的，如果后端容器同步启动，数据库还没就绪，后端连库失败就会直接崩溃退出。用depends_on: condition: service_healthy让 compose 等数据库健康检查通过后才启动后端，可以从根上避免这个问题。Redis 不需要等太久，所以只用了service_started。

第二个是数据卷。Postgres、Redis、向量数据库的数据都要写进 volume，不然容器一删数据全没。数据卷的名字写在 volumes 段里，当你需要备份或者换机器迁移时，只要把卷数据一起带走就行。很多新手跑 MongoDB、Postgres 容器时没挂卷，重启一次服务数据全丢，这是最惨痛的基础教训。

第三个是端口映射。我习惯把前端对外端口映射成 8088，后端映射成 8000，如果这两个端口已经被本机其他程序占用，就换成 8089、8001 之类的。改完端口映射后，浏览器访问的也是新端口，别到时候页面打不开还以为是 DeerFlow 没启动。

3.3 启动、看日志、初始化数据库

配置文件准备好后，在项目目录下执行：

docker compose up -d

第一次执行会先拉镜像，几个大镜像加在一起可能有好几个 GB，需要耐心等。拉镜像完成后，-d参数让所有服务在后台运行。接着执行：

docker compose ps

看到多个服务的 STATUS 是 Up 或 healthy，就说明容器层面没问题了。如果某个服务一直显示 Restarting，或者状态是 Exit code 1，马上看日志：

docker compose logs -f backend

重点看最后几十行，最常见的几个报错我会在下一章详细展开。首次启动时，数据库迁移通常由后端容器自动完成，它会创建表结构和初始数据，这一步如果日志里出现 migration 相关字样，等它跑完再看状态，不要中途 Ctrl+C 中断。

初始化完成后，浏览器打开http://localhost:8088，应该能看到 DeerFlow 的登录页或欢迎页。首次登录可能需要用 .env 里配置的管理员账号，没有的话就用界面提示的初始化方式创建。

3.4 接入本地 DeepSeek 模型与首次问答

DeerFlow 本身不带大模型，它需要你把模型接口配置好。两种常见方式：

第一种，用 Ollama 跑本地模型。你提前装好 Ollama，执行ollama pull deepseek-r1:7b，让模型跑在本机上。然后在 DeerFlow 后台配置模型时，Base URL 填http://host.docker.internal:11434，模型名填你在 Ollama 里拉取的名字。配置完先做一个连通性测试，成功后再传知识库文档。这里有个易错点：DeepSeek 这类模型在 Ollama 里的名字和你在 DeerFlow 配置里填的名字必须完全一致，大小写都要一致。

第二种，用 DeepSeek 开放平台的 API。把 API Key 填进 DeerFlow 的模型设置页面，Base URL 填官方提供的接口地址，模型名选择对应型号。上传知识库文档后，系统会调模型生成向量，这一步会花点时间。处理完成后你可以在问答页面提问“这个文档里讲了什么”，如果回答引用了文档内容，说明整条 RAG 流水线已经跑通了。

第一次问答如果返回空白或者报错，不要急着重新部署，先去后端容器日志确认是模型接口问题还是向量检索问题。模型接口问题，日志里会明确写明请求失败、超时或鉴权失败；向量检索问题，则会看到查询相关报错。这一步定位准确了，后面排查效率会高很多。

4. Docker Desktop 部署常见问题与排查

写这篇教程的时候，我特意把部署过程中遇到的坑按频率排了个序。DeerFlow 本身部署不算难，难的是你电脑环境千奇百怪，Docker Desktop 又叠加了一层虚拟化复杂度。下面这四类问题，覆盖了九成以上新手的翻车点。

4.1 启动即报错：virtualization support not detected

这个报错是 Docker Desktop 启动失败时最经典的一个，完整信息里通常可以看到 “virtualization support not detected” 或者 “failed to start because virtualization support wasn't detected”。说白了就是 Docker 引擎依赖的虚拟化能力没有就绪，按顺序检查三件事。

第一件事，进 BIOS 确认 CPU 虚拟化开关已经打开。Intel 的选项叫 Intel Virtualization Technology，AMD 的叫 SVM Mode。有些电脑默认关闭，开机时按 Del 或 F2 进 BIOS，找到对应选项改成 Enabled，保存重启。这一步不做，Windows 里怎么设置都没用。

第二件事，确认 Windows 功能里开启了 WSL2 和虚拟机平台。通过“启用或关闭 Windows 功能”勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”，然后重启。如果之前没开过 WSL，在管理员 PowerShell 里执行wsl --install，装好之后wsl --status查看默认版本，确保是 WSL2。

第三件事，检查 Hyper-V 是否被其他软件干扰。有些电脑装了第三方虚拟机软件或者沙箱工具，会抢占虚拟化资源。Docker Desktop 安装时如果检测到 Hyper-V 冲突，会干脆不启动。这种情况可以先把冲突软件退掉、禁用 Hyper-V 再重试，或者反过来直接用 WSL2 后端绕开 Hyper-V 依赖。

4.2 页面打不开与容器反复重启怎么看日志

页面打不开，通常不是 DeerFlow 问题，而是端口映射没对。先执行docker compose ps看端口情况：如果 localhost:8088 空白但容器是 Up 状态，大概率是端口映射写成了容器内部端口没暴露出来，检查 compose 文件的 ports 部分。如果页面提示 502 Bad Gateway，说明前端容器起来了但后端容器没起来，用docker compose logs -f backend查后端。

容器反复重启，观察 Restarting 状态，日志里会留下原因。我遇到最多的原因是数据库连接失败，后端启动时连不上 Postgres。这就要回看 .env 里 DATABASE_URL 的主机名、账号、密码三者是否和 postgres 容器环境变量一致。另外，Postgres 容器如果设置了 healthcheck，第一次初始化时可能要花 10 到 30 秒，如果后端容器没设置依赖健康状态，就会启动太早，连接失败后退出。你可以手动重启后端容器：

docker compose restart backend

等数据库完全就绪后再启动，通常就能恢复。如果数据库数据卷之前初始化过但损坏，最干净的办法是删掉这个数据卷重建，但注意这会清空所有数据：

docker compose down docker volume rm deerflow_pgdata docker compose up -d

4.3 磁盘膨胀、内存溢出那点事

Docker Desktop 跑久了，最让人头疼的是 C 盘空间神秘消失。镜像一层一层缓存、容器日志文件越写越大、Postgres 数据卷持续增长，磁盘很快就告急。我建议定期看这几个地方：

• 镜像和构建缓存：docker system df能看到各类资源占用。
• 悬空镜像：docker image prune -a清理没用的镜像。
• 日志文件：容器长期不清理，日志可能膨胀到好几 GB。

Docker Desktop 还提供了一个很实用的功能：Settings → Resources → Disk image location 旁边的 “Browse disk image” 可以查看虚拟磁盘被什么占用了，清理数据卷的时候配合使用，就不会误删数据。

内存溢出的情况，一般会看到容器 OOM Killed 的日志，或者在 Docker Desktop 的事件记录里看到内存不足提示。处理办法是到 Settings → Resources 里把内存调大一些，同时减少同时运行的大模型进程数量。如果本地模型推理把内存吃满了，DeerFlow 容器被杀死，就算镜像没问题也是白搭。

4.4 问题速查表

下表是我从自己部署经验和群聊记录里整理出来的高频问题，适合收藏备查。

再补一个很实用的小技巧：每个服务日志文件的大小可以通过 Docker 配置限制，在 docker-compose 文件的对应服务下面加logging: options: max-size: "50m"，这样单个容器的日志最多占 50MB，超过就自动滚动。这个配置我建议加上，它能避免好多次“磁盘怎么又满了”的尴尬。

个人建议，这套部署流程不要在第一次部署时就追求花哨优化，先把基础环境跑通、把界面点起来、把一次问答走通，然后再逐步调整参数。Docker Desktop 的好处是环境和你的本机天然隔离，玩坏了大不了docker compose down重来，这个容错空间就是容器化部署给我们最大的便利。