企业官网建设流程全解析

1. 为什么本地构建 DIFY 镜像又慢又容易失败

先说说我自己的经历。第一次在本地环境跑 DIFY 的时候，按照官方文档拉仓库、执行docker compose up，结果docker compose build --build-arg ...那一步直接卡了半小时，终端里全是fetch http://dl-cdn.alpinelinux.org/...的滚动日志，然后某个依赖源超时，整个构建直接红字退出。第二次换了台配置好点的机器，倒是没超时，但构建速度慢到我去泡了杯咖啡回来，前端镜像还在npm install。

这个问题的根源，其实不在 DIFY 项目本身，而在于它的镜像构建链路实在又长又依赖外部网络。

1.1 DIFY 镜像构建背后的依赖链

先看 DIFY 的源代码结构。主仓库langgenius/dify拉下来之后，里面不是只有一个 Dockerfile，而是一整套多容器编排：

• api服务：Python 后端，基于 Flask，依赖大量 pip 包，Dockerfile 里通常基于python:3.12-slim或类似基础镜像构建，需要跑pip install -r requirements.txt。
• web服务：前端，基于 Next.js（Nuxt.js 那套），依赖 npm/yarn 安装几百 MB 的 node_modules，构建时要执行npm run build，这一步是公认的耗时大户。
• worker服务：和 api 共享一套后端代码，只是启动命令不同，所以构建逻辑几乎一致。
• ssrf_proxy、sandbox、plugin_daemon等辅助服务：有的需要编译二进制，有的需要拉额外的镜像层。

也就是说，“构建 DIFY 镜像”不是构建一个镜像，而是同时构建五六个镜像。每个镜像的基础层都很大，加上中间层的依赖下载和编译过程，网络稍有抖动就会失败。官方文档和社区里最常见的docker compose up -d之所以经常卡在 building 环节，就是这个原因。

1.2 最常见的三类“卡死现场”

我接触过的团队和网友反馈里，构建卡顿/失败基本可以归成三类：

第一类：超时断连。这是最普遍的。Docker 默认网络请求超时时间很短，而国内访问 Docker Hub、GitHub Releases、npm registry、pypi 源这些公共资源时，连接质量不稳定。表现就是日志停在某个Downloading或fetch进度条上，半天不动，然后出现dial tcp: lookup xxx on ...: no such host或者Connection timed out。

第二类：OOM（内存溢出）或被 kill。前端镜像构建时，npm run build会启动多个 worker 进程做打包，内存占用轻松超过 1.5GB，如果宿主机本身内存只有 4GB，Docker 构建容器又没限制资源的话，很可能直接把机器拖到卡死，然后构建进程被操作系统 kill。日志最后一行通常是Killed，没有任何报错指向，非常坑。

第三类：Docker 缓存失效导致每次全量重建。如果你只是改了某个源码文件，但 Dockerfile 里COPY . .发生在依赖安装之前，那每次构建都会重新下载依赖。DIFY 官方仓库更新频繁，很多人git pull之后再docker compose up -d，Docker 检测到源码变更就从头开始构建，实际上很多依赖层根本没必要重装。正确做法是调整 Dockerfile 的层顺序，或者显式控制构建缓存，但大多数普通用户不会去改官方 Dockerfile，只能硬吃全量构建的苦。

不过，这些坑时有发生，但真正能用一套流程稳定复现、可以一键搞定构建的方案并不算多。下面这套Makefile方案就是我经过多次验证后沉淀下来的做法。

2. Makefile 的定位：别整花活，只做编排

很多人听到 “Makefile” 第一反应是：这不是 C/C++ 项目用的老古董吗？跟 Docker 有什么关系？我一开始也有这个疑虑，但实际用下来发现，它其实特别适合做命令行任务的编排工具。

我们最终要达成的目标不是“替代 Docker 或 docker compose”，而是把那些一条条难记、容易漏参数、顺序容易搞错的命令，封装成一个统一的入口。比如：

# 没有 Makefile 的时候，你需要手动敲（还要保证顺序对） git pull origin main docker compose build --build-arg ... api docker compose build --build-arg ... worker docker compose build --build-arg ... web docker compose up -d

有了 Makefile 之后：

make build

就完事了。而且 Makefile 天然支持目标依赖，比如build依赖check-env，up依赖build，它能帮你把执行顺序固化下来，不会因为少跑一步而出错。

2.1 为什么不用纯 shell 脚本

也许有人会说，这些功能我用一个build.sh也能实现。确实能，但 shell 脚本有两个问题：

1. 可读性随逻辑增长迅速下降。判断环境变量、检查上一条命令是否成功、处理不同平台差异……写着写着就变成一堆if [ $? -ne 0 ]，后来人维护成本高。
2. 天然缺少“目标”概念。你想单独重新构建 web 镜像，或者只重启 worker 容器，shell 脚本往往得改代码或加参数。Makefile 里天然就是make build-web、make restart-worker这种细粒度目标，每个目标可以独立执行，也可以互相依赖，非常契合“容器编排”需求。

另外一点很现实：DIFY 的部署环境五花八门，有人用 macOS，有人用 Windows 的 Docker Desktop，有人用 Linux 服务器。Makefile 配合Make这个工具，三个平台都有原生支持（Windows 下可以用 Chocolatey 装 make，或者用 Git Bash 里的 make），写一次到处跑，比 shell 脚本更符合“跨平台复用”的需求。

2.2 这套方案的结构概览

我用一个主 Makefile 加上几个辅助变量的方式，把 DIFY 本地构建的完整流程封装成了以下几个核心目标：

这个结构不是官方文档里的，而是我从实际构建中总结出来的一套“最小可用闭环”：先检查环境，再做网络探测，然后构建，最后启动。每个阶段都有独立的日志输出，哪一步出错一目了然。

3. 一键构建的实际落地：流程与核心命令

下面直接把 Makefile 的核心内容拆出来讲。先说明一下，我基于的 DIFY 版本是 0.6.x 到 1.x 之间常用的docker/docker-compose.yaml结构，新版目录结构有些调整，但核心思路不变。

3.1 先做好“网络状态”自查

为什么要强调网络自查？因为一旦步入构建环节，Docker 就会开始从各个源拉取基础镜像和依赖包。如果网络本身就访问不了某些资源，无论你 Makefile 写得再怎么漂亮，最终还是会失败。浪费大把时间，只为了看红色报错，没有意义。

所以我专门在 Makefile 里设计了一个network-check目标：

NETWORK_CHECK_IMAGES := python:3.12-slim node:20-alpine .PHONY: network-check network-check: @echo ">>> 检查 Docker 网络连通性（拉取小镜像测试）..." @for img in $(NETWORK_CHECK_IMAGES); do \ docker pull $$img || (echo "!!! 无法拉取镜像: $$img"; exit 1); \ done @echo ">>> 网络连通性检查通过，开始准备构建..."

这一步实际干了什么？它会尝试拉取两个小体积的基础镜像：python:3.12-slim和node:20-alpine。这两个镜像是 DIFY 构建过程中一定会用到的基础层。如果这两个都拉不下来，那后面构建 DIFY 镜像大概率也会卡死，不如提前暴露问题。

如果这两步每次都超时，建议检查 Docker 的daemon.json配置，给 docker 配置镜像加速器，比如：

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

这属于正常的基础镜像加速配置，不是绕过什么限制，就是让 Docker 拉镜像时走更快的镜像站点。配置完成后重启 Docker Desktop 或 docker daemon 再跑make network-check，就能确认源是否正常可达。

3.2 Makefile 核心：构建流程编排

我的 Makefile 里最核心的就是build这一节。直接贴出关键部分：

COMPOSE_FILE := docker/docker-compose.yaml DIFY_REPO_URL := https://github.com/langgenius/dify.git BUILD_PLATFORM := linux/amd64 .PHONY: prepare prepare: @if [ ! -d "dify" ]; then \ echo ">>> 克隆 DIFY 仓库..."; \ git clone $(DIFY_REPO_URL); \ else \ echo ">>> 拉取 DIFY 最新代码..."; \ cd dify && git pull origin main; \ fi @echo ">>> 创建必要目录..." @mkdir -p ./volumes/storage ./volumes/db ./volumes/redis .PHONY: build build: network-check prepare @echo ">>> 开始构建镜像，请耐心等待..." cd dify && docker compose -f $(COMPOSE_FILE) build --build-arg BUILDPLATFORM=$(BUILD_PLATFORM) @echo ">>> 镜像构建完成" .PHONY: build-web build-web: network-check prepare @echo ">>> 单独构建 web 镜像..." cd dify && docker compose -f $(COMPOSE_FILE) build web

这里的关键设计点：

build依赖network-check和prepare。这意味着你执行make build时，它会自动先跑网络检查和代码准备，不需要你手动分开执行三条命令。Makefile 的依赖机制天然帮我们保证了顺序。

构建时限制平台。我在构建时加了--build-arg BUILDPLATFORM=linux/amd64。在 Apple Silicon（M1/M2/M3）的设备上，如果不指定平台，Docker 可能会尝试构建 arm64 的镜像，这本身没问题，但某些依赖包的在 arm64 平台上的预编译产物可能没有，导致现场编译，现场编译就会特别慢。指定为 amd64 之后再跑，经过 Rosetta 或 Docker 的模拟层，很多时候反而更快、更稳。当然这不是绝对的，如果你的机器本身是 linux/arm64 服务器，就改成linux/arm64。

3.3 构建参数为什么要单独拎出来

我注意到很多人的docker compose build命令后面不加任何参数直接用，这其实踩了一个隐形的坑：DIFY 的官方 compose 文件里，部分服务会用到build.args来传递变量，比如：

services: web: build: context: ../web dockerfile: Dockerfile args: BUILDPLATFORM: ${BUILDPLATFORM:-linux/amd64}

如果你不显式传入BUILDPLATFORM，有些环境会默认成空值，导致 Dockerfile 里的多阶段构建选择错误的基础镜像平台。后面构建出来的镜像运行时可能出现 “exec format error” 或者不兼容的 glibc 报错。所以在 Makefile 里把构建平台参数统一管理起来，也是为了一处修改，处处生效。

3.4 启动编排：build 完之后自动 up

构建完成后，下一步就是启动。我同样封装了一个up目标：

.PHONY: up up: build @echo ">>> 启动 DIFY 全部服务..." cd dify && docker compose -f $(COMPOSE_FILE) up -d @echo ">>> 服务已启动，可通过 http://localhost/install 访问初始化页面"

这里有个细节：up依赖build，但是如果你已经构建过镜像，再跑make up时 Docker 检测到镜像存在且没有变更，会直接跳过构建，不会浪费几分钟去重复执行。这是因为 Docker Compose 本身有缓存机制，构建过的层只要没变化就会缓存命中。所以在 Makefile 里把up依赖build是合理的，不会造成额外开销。

3.5 一次性容器参数配置

有些用户还需要在构建时传入一些额外参数，比如使用国内 pip 镜像源加速：

PIP_INDEX_URL := https://pypi.tuna.tsinghua.edu.cn/simple NPM_REGISTRY := https://registry.npmmirror.com .PHONY: build-with-mirror build-with-mirror: network-check prepare @echo ">>> 使用国内镜像源构建..." cd dify && docker compose -f $(COMPOSE_FILE) build \ --build-arg PIP_INDEX_URL=$(PIP_INDEX_URL) \ --build-arg NPM_REGISTRY=$(NPM_REGISTRY)

前提是 DIFY 的 Dockerfile 里预留了对应 ARG 参数。如果官方 Dockerfile 里没有，你可以自己 patch。具体方法后面讲避坑的时候会提到。

4. 我踩过的坑：断点续传、残留镜像、后端死活起不来

这个部分是我最想写的。因为光看 Dockerfile 和官方文档，你根本不会知道构建过程中还有这么多坑。

4.1 “断点续传”——构建失败后不要急着重新跑

第一次构建 DIFY 的时候，我到web镜像的npm install阶段就失败了。网络超时，node_modules下载到一半断了。当时我的第一反应是重新执行一次构建命令。

但是要注意：Docker 的多阶段构建是有缓存的。如果你只是重跑docker compose build，它会复用已经构建好的api镜像层，只从失败的web阶段重新开始，而不是全部推倒重来。所以“断点续传”在 Docker 里天然存在，关键在于你的 Makefile 不要做多余的事情。

我见过有人的脚本里写了docker system prune -a来清理“确保干净构建”，结果把整个构建缓存全清了，每次都从零开始，网络稍微抖一下就失败。这完全是赔了夫人又折兵。我们在 Makefile 的clean目标里可以清理悬空镜像，但构建前一定不要清缓存，反而要尽量让 Docker 命中缓存。

不过这里有一个反向的坑：如果你拉取了 DIFY 最新代码，源码变了，但依赖没变，Docker 是如何判断是否需要重装依赖的呢？它看的是 Dockerfile 指令层面是否变化。如果你在用COPY . .把整个源码目录 COPY 进镜像的指令放在RUN pip install之前，那源码一变，后面所有层都会失效，包括依赖安装层，就会重新下载。DIFY 的 Dockerfile 官方写法通常是先只拷贝requirements.txt，再安装依赖，之后再拷贝完整代码，这是正确的缓存友好写法。所以我们要做的不是改 DIFY 的 Dockerfile，而是别去画蛇添足。

4.2 “残留镜像”导致磁盘爆满

构建了几次之后，你可能会发现磁盘空间急剧减少。原因有两部分：

一是 Docker 的多阶段构建会产生大量中间镜像层，这些层如果不被任何镜像引用，就成了悬空镜像（dangling images）。长时间不清理，几百 MB 到几个 GB 的空间就白白丢了。

二是 DIFY 本身就是个重量级项目，所有镜像真正运行起来之后，体积很容易超过 5GB。如果构建过程中有失败重试，磁盘上会堆积更多临时文件。

我的clean目标是这样写的：

.PHONY: clean clean: @echo ">>> 清理悬空镜像..." docker image prune -f @echo ">>> 清理未使用的构建缓存..." docker builder prune -f @echo ">>> 清理完成"

注意我用了docker builder prune，这是专门清理 BuildKit 缓存（/var/lib/docker下的构建缓存）的命令，有时候能释放好几 GB 空间。但是要确认你的 Docker 构建模式是 BuildKit（Docker Desktop 和环境变量 DOCKER_BUILDKIT=1 是默认开启的）。如果你是新版 Docker，直接用没问题。

这里有个小提示：docker image prune -f只清理无标签且无容器使用的镜像，不会误删正在运行的 DIFY 镜像，所以可以放心用。

4.3 后端服务死活起不来的排查链路

有一次我构建完所有镜像，docker compose up -d也成功执行了，但http://localhost/install一直打不开，docker compose ps显示api容器状态是exited (1)。这个问题的排查链路值得完整写出来，因为你以后大概率也会遇到。

第一步，看日志：

cd dify && docker compose logs api --tail 200

如果日志里出现ModuleNotFoundError: No module named 'xxx'，说明 Python 依赖没装全，构建时用的 requirements 和运行时不匹配，或者镜像时区/基础镜像传递参数有问题。

如果日志里出现connection refused，说明 api 连不上数据库或 Redis 容器。DIFY 的 compose 文件里定义了依赖关系，理论上会自动先启动 db 和 redis，但如果你上次启动失败残留了旧容器，可能导致端口冲突。

第二步，检查端口占用：

docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

看是否有多个 db 容器同时占用同一个端口。这种情况很常见：你执行docker compose down时没有加-v，数据卷保留着，但容器端口可能已经换过了；重跑 up 时新容器和残留的容器产生了端口冲突。

第三步，如果确认端口没问题，检查环境变量.

一种加快排查的方式是进入容器手动执行启动命令：

docker exec -it dify-api-1 bash python -c "from flask import Flask; print('ok')"

如果这步报错，就说明镜像内的 Python 环境不对，可能是构建时用错了基础镜像。这种时候不要慌，DIFY 官方在api镜像里有时会区分celery容器和api容器，它们共享同一套代码但启动模块不同。我之前就踩过坑：构建时候只构建了worker，忘了构建api，然后worker容器用的是旧镜像，导致代码不同步。所以一定记得make build是把所有服务都构建。

4.4 镜像平台不匹配：exec format error

另一个很容易遇到的高频报错是standard_init_linux.go:211: exec user process caused: exec format error。这个报错一般出现在你想在树莓派或 ARM 服务器上跑 amd64 的镜像。反过来，在 Apple Silicon Mac 上构建时如果没指定平台，构建出来的镜像在某些 Linux 云服务器上跑也会出现类似问题。

解决办法就是我在 Makefile 里加的那个BUILDPLATFORM变量。如果你的部署目标是 x86 服务器，就固定linux/amd64；如果是 ARM 设备，就改成linux/arm64。关键是要显式声明，不要让它自动猜，自动猜的跨平台构建需要开 QEMU 模拟，速度慢且容易出问题。

4.5 旧版 DIFY 无法访问 ollama 知识库

这个坑虽然不是 Makefile 直接导致的，但构建完新镜像后经常会遇到。DIFY 连接 Ollama 本地模型时，API 地址要写http://host.docker.internal:11434而不是http://localhost:11434，因为 DIFY 容器内部访问localhost是容器自己，到不了宿主机。如果你在配置 Ollama 时一直连不上，检查 docker-compose 里 api 容器的extra_hosts配置，需要加一行：

extra_hosts: - "host.docker.internal:host-gateway"

新版本 Docker 默认支持host-gateway，但老版本需要用localhost映射或者手动配置。这个配置可以直接加在 Makefile 管理的 compose 文件 override 文件里，不必改动原版 compose。

5. 让这套流程更好用的三个补充习惯

5.1 用.env管理变量，而不是硬编码

上面的 Makefile 里，我直接写了PIP_INDEX_URL、NPM_REGISTRY这些变量名，实际项目中不要在 Makefile 里硬编码具体URL值，而是用.env文件来管理。Make 会自动加载项目根目录下的.env文件（需要你在 Makefile 里加一句include .env或者通过$(shell ...)方式手动 parse，新版本 GNU Make 支持直接-include .env）。

这样做的价值在哪？举个例子：你在本地构建可以走docker.m.daocloud.io加速镜像，但在公司内网环境，这个镜像源可能被防火墙挡了，需要走公司内部的 Harbor 仓库。通过统一管理.env文件，你不需要改 Makefile 一行代码，只换.env内容就能适配新环境。

5.2 构建日志落盘，方便回溯

构建失败时，终端日志滚得太快，根本看不过来。我建议在 Makefile 的build目标里加一段日志落盘逻辑：

BUILD_LOG := ./logs/build_$(shell date +%Y%m%d_%H%M%S).log .PHONY: build build: network-check prepare @mkdir -p ./logs @echo ">>> 构建日志将写入 $(BUILD_LOG)" cd dify && docker compose -f $(COMPOSE_FILE) build 2>&1 | tee ../$(BUILD_LOG)

用的是简单粗暴的tee，把构建输出同时打到终端和日志文件。这样即使失败，你也可以在日志文件里搜索ERROR、failed、timed out等关键词，而不是地盯着终端翻页。而且logs/目录下的日志按时间命名，复盘的时候非常有用。

5.3 构建完了别急着开浏览器

镜像构建完成、服务启动后，第一次访问 DIFY 初始化页面之前，一定要把数据库初始化完成，否则会出现页面能打开但部分功能异常的情况。DIFY 正常启动顺序是：db 容器先起来，然后 api 容器执行迁移脚本，最后 nginx 容器（或 web 容器）才能正常反代。

如果你用make up启动后立刻访问页面，很可能会提示“数据库连接失败”。等 30 秒到 1 分钟，等 api 容器跑完数据库迁移再刷新，一般就好了。我习惯在make up之后加一个轮询等待：

.PHONY: up up: build @echo ">>> 启动 DIFY 全部服务..." cd dify && docker compose -f $(COMPOSE_FILE) up -d @echo ">>> 等待数据库初始化..." @sleep 20 @echo ">>> 打开 http://localhost/install 完成初始化"

sleep 20虽然粗暴，但绝大多数情况下足够 api 容器完成数据库迁移了。如果你机器性能差，可以自己改成 30 或 40。

从最初的构建连番失败，到现在一台新机器上make build && make up一条命令直接跑通，整个过程最关键的一点就是：把容易出错、容易遗漏的步骤固化为脚本和配置，别让“人脑记忆”参与其中。Makefile 就是这样一个轻量又可靠的固化工具。后面如果再遇到 DIFY 版本升级、镜像构建策略调整，你只需要改 Makefile 里的几个变量，就能继续稳定使用。如果你也在本地构建 DIFY 镜像，希望这套方案和避坑经验能帮你少走几个来回。