企业官网建设流程全解析

如果你已经准备自己装一套 Dify 社区版，大概率会经历这样一个过程：先被"功能很强大"打动，然后被部署细节折磨。我上个月刚帮一位朋友从 1.10 升到 1.17.1，中间遇到镜像拉不下来、容器启动顺序混乱、登录后白屏等一系列问题。趁着记忆还热乎，把整套精简部署流程和排查思路整理出来，尤其是 1.17 这个版本的新手友好度相比早期版本已经好了很多，只要按规矩来，基本能一次跑通。

这篇文章不打算讲太深层的源码逻辑，主要面向第一次接触 Dify 的人，覆盖版本选择、前置准备、部署操作、常见报错处理、以及后续跑通一个应用所需的模型接入和知识库配置。我尽量按"实际会踩到的顺序"来写，而不是按官方文档的目录结构来写，因为后者对新手来说太抽象了。

1. 部署前就得看清的三件事：版本选择、硬件底线和镜像来源

1.1 为什么新手上路直接选 1.17，而不是守着旧版本

Dify 社区版从 1.x 开始迭代速度非常快，几乎每隔几周就有一个小版本。很多人有个习惯，觉得"老版本稳定，新版可能有坑"，但在 Dify 这里我的建议恰恰相反：新手直接上 1.17.1，不要从 1.10 或 1.12 开始。

原因有两个。第一，Dify 的数据库结构和插件机制在这几个版本之间变过不少次，你如果先用旧版本把数据建起来，后面升级基本都要做迁移，迁移过程中最容易出现的"字段不存在""外键冲突"对新手来说非常劝退。第二，1.17 在部署层面做了明显的工程化改进，最直观的感受是 api、worker、plugin_daemon 这几个服务之间的启动依赖关系比旧版本合理很多。旧版本经常出现 web 容器已经 started 但 api 还没就绪，导致页面一直 50x；1.17 里加了更严格的健康检查，容器之间会互相等待，整体起来的成功率要高得多。

另外一个容易被忽略的点是镜像 tag 的对应关系。docker-compose.yaml 里的镜像版本必须和源码版本一致。你如果 clone 了最新 main 分支源码，却因为网络原因手动拉了一个旧的 dify-api 镜像，启动时大概率会报字段不匹配或者接口 404。所以最稳妥的方式：用 git tag 固定到一个版本，比如 1.17.1，然后源码、镜像、compose 文件全部以这个 tag 为准。

1.2 硬件配置：官方文档的"最低配置"对新手并不够用

官方写的硬件要求是 2 核 4G 内存可以跑，这句话在纯空载状态下成立，但一旦你开始上传知识库、跑工作流、接本地模型，4G 内存会让整台机器处于崩溃边缘。我自己实际测试过几个配置档位，给你一个参考：

新手最容易低估的是内存。Dify 全家桶一次性会拉起十几个容器，包括 api、worker、web、nginx、postgres、redis、weaviate、sandbox、ssrf_proxy、plugin_daemon。光这些容器常驻内存加起来，在空载状态也要占用 2.5G 到 3G 左右。如果你的机器只有 4G 内存，再叠加系统本身占用，docker stats 里就会看到内存几乎跑满，紧接着出现 OOM，症状就是某个容器突然退出，页面报服务异常。

磁盘同样别按最低要求来。Dify 自己的业务数据不算大，但 Weaviate 作为向量数据库，存储量会随着你上传到知识库的文档数线性增长。假设你往知识库里塞了几百个 PDF，每个文件分段后生成向量数据，几十 G 磁盘很快就会被吃掉。所以无论如何给 Docker 的数据目录预留 100G 以上，磁盘满了以后 postgres 和 weaviate 都会出各种奇怪问题。

1.3 镜像拉取失败：先配置加速器，再考虑离线导入

镜像拉取失败几乎是每个新手的第一个坎。Dify 部署一次要拉十几个镜像，总量大概 3 到 5 个 G，中间任何一层镜像下载失败，docker compose 都会停在那里，不报错也不继续。常见的失败形式有几种：

• 拉取时报dial tcp i/o timeout
• 进度条走到一半就不动了
• 提示某个 tag 不存在
• docker compose 启动时直接说 image not found

前两种在特定网络环境下非常常见，处理思路按优先级排序：

第一步，给 Docker 配置镜像加速器。Linux 下编辑/etc/docker/daemon.json，加入 registry-mirrors 配置，然后重启 Docker 服务。Windows 的 Docker Desktop 用户直接在设置里的 Docker Engine 选项卡中编辑同一个 JSON 即可。示例配置：

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

改完以后重启 Docker，再单独拉一个核心镜像测试：

docker pull langgenius/dify-api:1.17.1

能正常拉下来，说明加速器生效，再执行完整的 docker compose up。

第二步，如果加速器在你的网络环境下还是不稳定，可以换一台网络环境好一些的机器，先执行 docker pull 把镜像拉下来，然后用 save 和 load 的方式打包传输到目标机器：

docker save langgenius/dify-api:1.17.1 -o dify-api.tar scp dify-api.tar user@目标机器IP:/tmp/ ssh user@目标机器IP "docker load -i /tmp/dify-api.tar"

把所有需要的镜像都传过去之后，再执行 docker compose up -d，这样能绕开大部分镜像源不稳定的问题，代价是需要手动操作一遍。

至于第三种"tag 不存在"，基本是你手动指定了不存在的镜像版本，或者源码和镜像版本没对齐。回到代码目录确认 tag：git tag -l，然后根据实际 release 版本去拉对应镜像。

提示：如果你手动 pull 过镜像，注意 compose 文件里 image 字段与你本地镜像的版本必须完全一致。不要随手改 tag，除非你明确知道 compose 里引用的是哪一个名称。

2. 精简部署操作流：从拿到源码到浏览器看到登录页

2.1 源码获取与目录选择

Dify 的部署入口在源码根目录下的 docker 文件夹里。你可以用 git 从 GitHub 克隆，也可以从官方 release 下载源码 zip 包。克隆方式：

git clone https://github.com/langgenius/dify.git cd dify git checkout 1.17.1 cd docker

这里有一个新手常犯的错：只从 release 页面下载 docker 文件夹，觉得 compose 文件都在里面就够了。实际上不是的，Dify 的 compose 配置里引用了 .env.example 和一些相对路径，完整的部署最好基于整个源码包。

下载完源码解压后，Windows 上会看到 dify-main 这样的目录，你需要进入dify-main/docker目录。在资源管理器地址栏输入 cmd 回车，就能直接在当前路径打开命令提示符。接下来复制环境变量文件，Linux 和 mac 用：

cp .env.example .env

Windows cmd 里不太认 cp，用 copy 或者直接在 PowerShell 里用 Copy-Item：

Copy-Item .env.example .env

在正式执行 docker compose 之前，先确认本机 Docker 环境是完好的。检查命令：

docker --version docker compose version

有些 Linux 发行版用了 docker-ce 但不带 compose 插件，会提示找不到 docker compose。Ubuntu 下可以用：

sudo apt-get update sudo apt-get install docker-compose-plugin

检查完 Docker 环境再往后走，避免后面报的错到底是 Docker 没装好还是 Dify 配置问题，混在一起难排查。

2.2 .env 文件里需要改和不需要改的项

.env 是 Dify 部署的配置中心。默认值对于纯体验来说基本够用，但有几个关键项值得你留意：

• SECRET_KEY：Dify 用它做会话加密和敏感数据签名。.env.example 里的默认值虽然能跑，但部署到公网环境或者多人协作时，建议生成一个自己的随机串。生成命令：

openssl rand -base64 42

然后把输出替换到 .env 的SECRET_KEY=后面。

• EXPOSE_NGINX_PORT：默认值是 80。如果服务器 80 端口已经被其他 Web 服务占用，改成 8080 或者你喜欢的其他端口。改完后访问地址变为http://服务器IP:8080。这是新手部署出现"端口被占用"时最直接的解决办法。

• POSTGRES_PASSWORD、REDIS_PASSWORD：本地体验不修改问题不大，生产环境必须改。这两个密码一旦启动过 postgres 容器再改，会比较麻烦，因为数据库数据已经以旧密码初始化了。所以想改的话，要在第一次启动前改好。

• 外部模型 API 的 key 不用提前在这里配，部署完成后在 Dify 页面后台里添加反而更直观，也方便管理多个供应商。

2.3 docker compose up 启动与首次初始化等待

一切准备就绪，在 docker 目录下执行：

docker compose up -d

第一次执行会拉取全部镜像，时间取决于网络和机器性能。完成后再执行：

docker compose ps

看到所有服务状态为 running 或 healthy 就成功了。其中 db、redis、api、worker、nginx、web 这几个核心服务必须健康。如果某些服务显示 unhealthy，不用太着急，因为 api 和 worker 第一次启动时要做数据库初始化，期间健康检查会短暂失败，等一两分钟再观察。

首次启动成功后，浏览器打开：

http://localhost

假设端口没改，看到初始化管理员的页面就说明部署成功了。第一次进入需要设置管理员邮箱和密码，这个账号就是超级管理员，后面可以建团队、开工作空间。整个等待过程建议你不要频繁刷新页面，给容器一点时间把事情干完，反而更快。

3. 启动失败的排查链路：以日志为准，不靠瞎猜

3.1 第一步永远都是 docker compose ps 和 logs

页面提示"服务异常"时，新手的本能反应是不停刷新，但 Dify 这类多容器应用的正确姿势是先看容器状态。执行：

docker compose ps

观察每个容器的状态列，这里有几类典型异常：

确定可疑容器后，查看具体日志：

docker compose logs api

加--tail参数能只看最近的行数，比如：

docker compose logs api --tail 200

日志是排查的第一手资料，containers 的错误基本都会写在这里。比如 api 容器反复出现Connection refused，那基本可以确定是数据库或 Redis 连不上，接下来就去查对应容器状态。

3.2 端口占用与 nginx 起不来

Dify 默认用 nginx 容器对外提供 80 端口。如果宿主机已经有别的 Web 服务占用 80，你会看到 nginx 容器反复退出，日志里出现：

bind 0.0.0.0:80 failed: port is already allocated

解决方案有两个：

1. 修改 .env 里的EXPOSE_NGINX_PORT=8080，然后重新执行docker compose up -d。
2. 停掉占用 80 端口的旧服务。

检查端口占用的命令：

sudo netstat -tlnp | grep :80

拿到占用进程的 PID 之后，再看是什么服务占用，谨慎决定要不要停。

3.3 api 连不上数据库和 Redis：容器内视角与宿主机视角

api 容器如果反复重启，日志里有password authentication failed，那大概率是 postgres 的密码不匹配。有两种可能：一是 .env 里改了 POSTGRES_PASSWORD，但数据库卷是之前用旧密码初始化的；二是 compose 文件里环境变量覆盖了 .env 值，导致 api 连库密码不一致。

先查 db 容器状态：

docker compose logs db --tail 50

如果 db 能起来，只是认证失败，再确认 api 容器里的实际环境变量：

docker compose exec api env | grep DB

把这个输出和 .env 里的值比对，就知道是不是配置被覆盖了。

还有一种更隐蔽的问题：postgres 数据目录权限不对。在某些 Linux 环境下，容器内的 postgres 用户和宿主机挂载目录的属主不一致，导致初始化数据库时报Permission denied。处理方式是调整卷目录属主：

sudo chown -R 999:999 ./volumes/db/data

这里 999 是官方 postgres 容器内 postgres 用户的 uid。改完把容器删掉重新创建：

docker compose up -d --force-recreate db

3.4 内存不足导致容器被 Kill

容器退出码如果是 137 或 139，别去查配置了，大概率是内存溢出。137 对应 SIGKILL，通常是系统 OOM Killer 干的。确认方式：

dmesg | grep -i kill

看到 oom-kill 相关日志，说明物理内存不够了。解决方式两条路：加内存，或者砍掉非必要服务。在 docker-compose.yaml 里暂时注释掉 sandbox、ssrf_proxy、weaviate 等容器，只保留核心服务，可以降低内存占用，但代价是工作流里的部分能力会受影响。如果你后面的确要用工作流和工具，还是老老实实加内存。

以我实际经验，4G 内存的机器跑 Dify 全家桶是极限，想在旁边再跑一个 Ollama 服务做本地模型，基本必 OOM。本地模型方案建议 8G 起步，16G 比较舒服。

3.5 页面白屏、登录异常，但容器都健康

容器状态全 healthy，页面却白屏或者一直转圈，这种情况在升级场景里比较多见，全新部署偶尔也会遇到。

首先排除浏览器缓存。Dify 的前端是打包的静态资源，升级前后资源哈希会变，旧缓存容易导致白屏。开一个无痕窗口试一次，如果无痕模式正常，清理浏览器缓存即可。

无痕也不行的，继续查 nginx 日志：

docker compose logs nginx --tail 100

关注有没有upstream timed out或者connection refused之类的关键词。nginx 正常的话，再看 web 容器日志。web 容器是纯前端静态服务，一般不会有问题，除非你自己动过 compose 文件里的端口映射或者环境变量。默认情况下 web 监听 3000，nginx 反代配置写死在里面，没有十足把握不要在 compose 文件里乱改这些值。

4. 部署完成后先把模型接进来，再谈知识库和工作流

4.1 用云端 API 还是本地模型：就差一个 URL 的事

容器都正常运行了，接下来要做的是把大模型接进 Dify。没有模型，后面的对话、知识库、工作流全都跑不起来。入口在页面右上角头像 → 设置 → 模型供应商。

如果你是云端模型，比如 DeepSeek、OpenAI、通义千问，配置很简单：API Key 填进去，模型名称填对，测试通过即可用。以 DeepSeek 为例，模型名填deepseek-chat，Key 填你在平台申请到的 sk- 开头字符串。

如果你用 Ollama 跑本地模型，配置里面有一个特别容易踩的坑。Dify 的容器和你宿主机上的 Ollama 不在同一个网络命名空间，容器内部的localhost:11434指的是容器自己，不是宿主机。所以 Ollama 的 Base URL 不能填 localhost，要填宿主机 IP。如果 Dify 容器用的是默认 bridge 网络，宿主机在容器内部的地址通常是172.17.0.1。更稳妥的方式是直接填宿主机局域网 IP。

http://172.17.0.1:11434

填完后点测试，能连通就说明模型配置成功。

4.2 知识库流水线的三个关键配置：分段、索引、召回

模型接进来后，大部分人第二件事是上传文档建知识库。创建知识库的时候有三处配置直接决定效果，新手往往没太在意，到后面发现问题再回头改，成本就高了。

第一是分段设置。文档上传后会被切成文本块，再向量化。这个切块动作很关键：分太短，单块文本缺乏上下文，检索出来可能答非所问；分太长，噪声太多，检索精度下降。官方默认的分段方式在多数场景下表现中庸，新手可以先默认跑通流程，后续觉得效果不好再改成按标题分或者自定义分隔符。

第二是索引方式。高质量模式会走向量化索引，语义检索效果好，但每次处理文档要消耗模型 token。经济模式是关键词索引，不消耗模型 token，但检索效果上限低。想体验完整能力就用高质量模式，想省钱测试就先小范围试。

第三是召回设置。在应用里关联知识库之后，召回策略可以选择向量检索、全文检索、混合检索。混合检索在大多数业务场景下效果明显好于单一模式，代价是多了一点点检索耗时。如果你当前用的向量化模型不太行，混合检索能兜底。

4.3 用官方模板工作流验证全链路

部署完、模型接上、知识库建好，最后一步是完整跑通一个应用，否则你无法确认整个部署链路真的没问题。在"工作室"里点击创建空白应用，或者从模板市场导入一个模板工作流。

导入了模板之后，做的第一件事是把工作流里的模型节点切换到你自己配置好的模型。很多测试失败都是因为模板里写了某个模型名称，在你的环境里并不存在。

测试过程中如果节点报错，不用慌。Dify 的工作流节点支持查看每一步的输入输出，双击节点或点击节点详情，能看到实际传入的数据和返回的结果。跟着日志里的错误信息走，绝大多数问题就三类：模型未配置、prompt 里变量名拼错、知识库没有正确关联到节点。

跑通一个模板工作流，说明从 Docker 容器到模型调用、到知识库检索的整条链路都是通的，到此才算真正完成了部署。

5. 长期维护与版本升级的实战经验

5.1 备份永远比升级更优先

数据安全这块要放在最前面。Dify 的业务数据主要存在 postgres 里，向量数据在 weaviate 里，缓存和会话在 redis 里。备份时不需要把整个容器打包，备份 volumes 目录即可。

官方 compose 默认把数据放在当前目录的 volumes 下，最简单的方式是直接备份这个目录。想对 postgres 单独做逻辑备份，也可以这样：

docker compose exec db pg_dump -U postgres dify > dify_backup.sql

恢复：

docker compose exec -T db psql -U postgres -d dify < dify_backup.sql

备份前最好先停掉业务容器，避免数据写入不一致。我习惯的操作顺序是：

docker compose stop api worker web nginx docker compose exec db pg_dump -U postgres dify > dify_$(date +%Y%m%d).sql docker compose start

5.2 从旧版本升级到 1.17.1：保留 .env、替换代码、观察迁移

升级的核心是：保留 .env 配置和 volumes 数据，替换代码和镜像。

cd dify git pull git checkout 1.17.1 cd docker docker compose down

如果你的部署是从 release zip 来的，没有 git 仓库，下载新版本的 zip 解压后，把旧版本的 .env 和 volumes 目录拷贝到新版对应位置。

官方每次发布都会在 .env.example 里增加新配置项。升级时不要直接cp .env.example .env覆盖，那样会丢掉 SECRET_KEY 和数据库密码，导致老数据连不上。正确做法是把 .env.example 里的新增项合并进旧 .env，旧 .env 里已有的配置一项都不要动。Linux 下可以用 diff 命令对比两个文件，手动确认新增内容。

合并完配置后：

docker compose pull docker compose up -d

升级后 api 容器会自动执行数据库迁移。这一步要看日志确认有没有成功：

docker compose logs api --tail 200

迁移过程中页面可能暂时无法正常访问，这是正常的。等日志里不再出现 migration 相关的输出，再刷新页面测试主流程。

我升级过程中遇到过迁移后 redis 里缓存了旧数据导致页面异常的情况，清理一下 redis 缓存就好了：

docker compose exec redis redis-cli FLUSHALL

这个命令会把所有会话踢下线，执行前和团队同步好时间点。

5.3 容器日志无限增长和资源占用失控

Dify 跑一段时间后，最容易被忽略的问题是容器日志无限增长。默认情况下 docker 的 json-file 驱动不会自动轮转日志，遇到某个服务频繁打印错误，几天就能吃掉几个 G 磁盘。在 docker-compose.yaml 里给服务加上日志限制是很好的习惯：

logging: driver: json-file options: max-size: "50m" max-file: "5"

这样单个服务日志最多保留 250M 左右，磁盘不会被日志打满。quiet 期间你可能不会注意到日志，直到磁盘满了 postgres 突然写不进去数据，那时候才是真麻烦。

再看资源占用。运行时间长了，如果发现 Dify 响应变慢，先跑一下：

docker stats --no-stream

观察哪个容器在长时间吃 CPU 或内存。我遇到比较多的是 weaviate，在知识库大量写入的时候内存会持续攀升。如果长时间不释放，可以给它设置资源上限：

services: weaviate: mem_limit: 2g

同理 redis 和 postgres 也建议加上资源限制，避免单个服务吃掉宿主机所有资源。要注意：修改 docker-compose.yaml 后，执行docker compose up -d重新创建容器才能生效，只 restart 是没用的。

我在几次部署和升级中的经验是，Dify 这类多容器应用，部署过程本身并不难，难的是出了问题以后还在靠页面刷新和猜来排查。先看容器状态，再看日志，最后才动配置，这套顺序适用于绝大多数问题。真心希望这篇精简部署和排查指南能让你少走几个弯路，一次把 Dify 跑起来。