Dify本地部署实战：Docker Compose安装到API接入全攻略

简介：面向无法稳定访问 GitHub 的开发者，这里提供的是 2025 年 4 月 28 日发布的 dify 原版安装包，来自 GitHub 项目，可在弱网或离线环境下完成安装部署。压缩包内共收录两千个文件，整体大小约二十点二九MB，文件类型丰富：Python 文件有一千四百零四个，承担核心业务逻辑；JSON 配置有三百六十八个，负责各类参数设置；CSS 样式表有一百零三个，用于页面外观；另外还有 Markdown 说明文档、JavaScript 脚本、YAML 配置等辅助内容，基本覆盖了 Web 应用运行所需的前后端资源。核心入口为 dify-main，完整保留了主程序与关键模块，解压后即可获得可运行的项目基础，无需再逐个文件下载或反复访问 GitHub，尤其适合网络受限的同学。目前已有二百五十八人学习下载，也可以作为官方版本备份、项目二次开发或搭建私有化实例的起点，既省时又能避开拉取源码不稳定的问题。无论你是初次接触 dify，还是需要离线部署的运维人员，这份安装包都能降低使用门槛。

1. 先拿包再部署：这份 20250428 原版 Dify 安装包，给 GitHub 拉不下来的人

做 Dify 本地部署，十有八九第一关不是 Docker 不熟，而是 GitHub 上的原版仓库和 Release 资产经常拉不下来。仓库 clone 到一半断连、Release 的 tar.gz 下到 60% 就掉线、页面直接打不开，这些场景这几个月帮同事配环境时反复撞见。这份 2025 年 4 月 28 日打包的 Dify 原版安装包，就是把 GitHub 上对应时刻的原版代码与编排文件完整备份下来，再分发给需要的人——你不用在关键时刻赌网络，直接拿包走后面的部署流程。它适合三类人：想在本地 Docker 里跑起 Dify 的开发者、需要离线或半离线交付的团队、以及想研究 Dify 源码和 docker-compose 编排的同学。后面所有步骤，都围绕这份包展开。

2. 安装包拆解：Dify 社区版的核心模块与 Docker Compose 选型理由

2.1 Dify 到底是什么：一套 LLM 应用开发平台的三层结构

Dify 经常被一句话概括为“开源的 LLM 应用开发平台”，但这个词太笼统。实际拆开看，它解决的是从模型到可用产品之间的那一大段工程问题。你手上有大模型的 API Key，但要做成带知识库、带工作流、带用户权限的应用，需要自己写前端、写编排引擎、写向量库对接逻辑。Dify 把这些通用能力做成了开箱即用的模块，所以它也被很多人直接叫作 Dify 智能体平台——Agent 应用的编排能力是内置的，不需要额外开发。

按技术分层来看，这份原版包里的 Dify 大致有四层能力。第一层是模型接入层，统一管理 OpenAI、DeepSeek、通义等模型供应商，也支持本地 Ollama，所有应用都从这一层拿模型，不需要在每个应用里重复配 Key。第二层是编排层，提供工作流（Workflow）和 Agent 画布，以节点化方式组装逻辑，支持变量赋值、条件分支、迭代循环和外部工具调用。第三层是知识库层，负责文档上传、文本分段、Embedding 入库，给 RAG 流水线用。第四层是 API 与运营层，每个应用发布后都有独立 API 接口，供 Cursor、内部系统等外部调用，同时保留日志、标注、提示词实验等功能。

这套组合对中小团队的实际价值是：不需要从头养一支会写编排引擎的前后端团队，把精力留在业务逻辑上。2025 年 4 月 28 日这个时间点对应的社区版，已经提供了以工作区为单位的成员与资源隔离能力，也就是多租户隔离：一个实例下可以建多个工作区，每个工作区有独立的成员、应用、知识库和 API 密钥。这意味着同一份部署可以同时服务公司里多个业务小组，而不需要为每个小组单独装一套。

2.2 包里有什么：原版 Release 的关键文件清单

拿到这份安装包，第一件事是先看清楚目录结构，它和你在 GitHub 上看到的原版仓库保持一致。默认的 Dify 仓库里，部署相关文件集中在 docker 目录下。下面这份清单是我每次拿到原版包后都会对照检查的：

在正式部署前，有一个容易误解的点需要先说清楚：这份包解决的是“GitHub 侧的东西拿不到”的问题，也就是源码和编排文件；Docker 镜像本身仍然要从 Docker Hub 拉取，这一层不在包里。如果你所在的网络环境连 Docker Hub 也拉不动，常见做法是让内网一台能正常拉取的机器先 docker save 打包镜像，再传输进去 docker load，离线导入后再走 compose up。很多离线交付的 Dify 项目，最后都是“编排文件 + 镜像 tar 包 + .env 模板”三件套一起给到现场。

2.3 为什么我建议用 Docker Compose，而不是裸机部署

Dify 的依赖不止一个进程。它需要 PostgreSQL 存业务数据、Redis 存缓存和登录状态、一个向量数据库存知识库 embedding、一个 sandbox 服务跑代码节点，再加上 API、Worker、Web 三组应用进程。如果裸机部署，你得先手动装好这些组件，再分别配置环境和启动脚本，中间任何一步版本不匹配都够排查半天。用 Docker Compose 的理由很直接：编排文件是官方原版的，和仓库同步，不用自造轮子；一条 docker compose up -d 就能把全部服务拉起来；日志统一走 docker compose logs 查看；数据都落在 volumes 目录，升级和迁移时只需要搬运目录和重新编排，服务进程本身不保存状态。

选型上的另一个注意点是向量数据库。Dify 社区版的 .env.example 里默认启用了 weaviate，也可以切换到 opensearch 或 qdrant，通过 VECTOR_STORE 变量控制。我一般直接保留默认 weaviate，因为官方对默认链路测试最多，遇到问题时社区里能查到的资料也最多。除非你已经有一套维护得很熟的 OpenSearch，否则不建议在第一次部署时就换向量库。把默认链路先跑通，后面再换也不迟。

3. 从零到跑起来：Docker 部署 Dify 的完整步骤与关键参数

3.1 前置检查：Docker 版本、内存与端口

动手之前先把环境条件过一遍，可以避免后面一半的问题。Dify 官方建议部署机至少有 8GB 内存，我自己的体验是 8GB 起步才能让 API、Worker、向量库同时跑起来不频繁 OOM；4GB 的机器勉强能起服务，但知识库索引一跑就容易翻车。先检查 Docker 和 Compose 是否就位：

docker --version docker compose version

Docker 版本在 20.10 以上基本都能跑；Docker Compose 建议 v2 以上，v1 的 docker-compose 命令和 v2 的 docker compose 语法有差异，下文命令均以 Compose v2 为准。接着检查 80 和 443 端口是否被占用：

ss -lntp | grep -E ':80|:443'

如果 80 端口被 Nginx、Apache 或其他服务占用，后面在 .env 里把 EXPOSE_NGINX_PORT 改掉就行，不一定要先杀掉已有服务。另外用 free -h 看一下可用内存，如果低于 6GB，建议先把 Docker Desktop 或 NAS 设备上的其他容器停掉再继续。你在飞牛 NAS 这类容器环境上部署时也要注意这一点，Compose 默认路径和 NAS 的存储池可能不一致，先确认卷目录落在哪里，免得数据写进系统盘。

3.2 初始化 .env：模板复制与关键参数调整

进入包里的 docker 目录，把环境变量模板复制为正式配置：

cd docker cp .env.example .env

改完先不要直接启动，打开 .env 文件，有三个地方必须仔细看。第一个是 SECRET_KEY，它承担会话加密和数据签名，必须换成你自己的随机串，不能沿用默认值。生成随机串的命令：

openssl rand -base64 42

执行后把输出的一整串字符粘贴到 .env 的 SECRET_KEY= 后面。注意粘贴时不要带换行、不要加引号，否则 api 容器启动时可能报配置格式错误，现象是容器反复重启。

第二个是 EXPOSE_NGINX_PORT，默认是 80。如果部署机 80 端口被占用，改成 8080 或者其他空闲端口，后面访问控制台的地址就变成了 http://部署机IP:8080。第三个是 POSTGRES_PASSWORD，默认值在部署到内网环境时可以先用，但如果这台机器能被公网访问，建议一并改掉。

下表是几个容易出现问题的变量，改完之后对着检查一遍：

提示：SECRET_KEY 的保存和备份很关键。升级或迁移时如果换了 SECRET_KEY，所有已登录会话会失效，涉及加密的数据也可能读不出来。

3.3 启动、初始化和首次登录

仍然在 docker 目录下执行启动命令：

docker compose up -d

第一次执行会从 Docker Hub 拉取 api、worker、web、nginx、postgres、redis、weaviate、sandbox 等镜像。这里有两个分支情况：如果拉取正常，耐心等镜像下载完成；如果拉取超时或失败，就让内网另一台能正常拉取的机器执行 docker save 把镜像打包，再传输到目标机器执行 docker load，镜像就位后重新 docker compose up -d。常见的离线导入写法：

docker save -o dify_images.tar 完整镜像名1 完整镜像名2 ... docker load -i dify_images.tar

启动完成后先看服务状态：

docker compose ps

正常情况下所有服务都应该是 Up 状态。接着看 api 服务是否完成了数据库迁移：

docker compose logs -f api | grep -i "migration\|ready"

看到数据库初始化完成、api 服务进入就绪状态后，浏览器访问 http://部署机IP:对应的EXPOSE_NGINX_PORT，第一次打开会进入管理员账号初始化页面，设置邮箱和密码后登录。如果页面提示 Page not found 或者 403，先确认端口映射和访问路径，这部分在第 5 章专门展开。

4. 接入模型与工作流：从界面配置到 API 调用一条线

4.1 配置模型供应商：OpenAI 兼容接口的参数细节

部署跑通之后，第一步是让应用能拿到大模型的回复。Dify 控制台右上角头像菜单里的“设置 → 模型供应商”，是集中管理模型 Key 的地方。这里支持的供应商很多，但绝大多数团队实际用的是 OpenAI 官方接口或各种 OpenAI 兼容服务。以 OpenAI 兼容服务为例，需要填写的几个字段分别是：模型供应商选择 OpenAI 或兼容服务，API Key 填服务商生成的密钥，Base URL 默认是 OpenAI 官方地址，如果你用的是兼容服务，改成对方提供的端点，注意不要带 /v1 后面的路径，模型名称填服务商实际支持的模型名，比如 gpt-4o-mini 或 deepseek-chat。

填完点击保存，Dify 会立刻做一次凭据校验。如果提示 an error occurred during credentials validation，先用这条命令验证 Key 本身是否有效：

curl -s https://api.openai.com/v1/models \ -H "Authorization: Bearer 你的KEY"

如果 curl 直接返回了模型列表，说明 Key 正常，问题大概率出在 Base URL 填错、模型名不在 Dify 预设列表里，或者 Dify 容器访问不到服务商端点。如果 curl 也报 401 或 403，说明 Key 本身权限就不对，去服务商后台重新生成即可。还有一个常见翻车点：模型服务跑在宿主机本地端口上，Dify 容器里的 localhost 指向的是容器自己，永远连不到宿主机，这种情况要把服务地址改成宿主机在容器网络中的网关地址。先验证 Key，再查网络，按这个顺序能省很多时间。

4.2 搭建知识库流水线：分段、检索与变量赋值

模型就位后，我建议第一个练习做一个带知识库检索的工作流，它能把 Dify 的核心能力都过一遍。先创建知识库：控制台左侧菜单点击知识库，创建知识库后上传一份 PDF 或 Markdown 文档。分段设置里有两个关键参数：分段长度和分段重叠长度。Dify 默认分段长度是 500 token、重叠 50 token，做一般资料库可以直接用默认值；如果文档里代码块或长表格多，把分段长度拉到 800、重叠改成 100，避免在一个分段中间被切断。索引方式选高质量会走向量索引，经济模式适合批量导入草稿。

创建完成后先测试检索，看返回片段是否贴合问题。检索相关的两个参数在知识库设置里：TopK 控制返回片段数量，默认 3 通常够用；Score 阈值用来过滤低相关片段，一般从 0.2 开始试，命中率低就往下调。接下来建一个最简工作流：开始节点 → 知识检索节点 → LLM 节点 → 结束节点。在知识检索节点里选择刚才的知识库，在 LLM 节点里把检索结果通过变量赋值引用进来。Dify 的模板变量写法如下：

你是内部知识库助手，请只依据下面提供的资料回答问题。 如果资料里没有相关信息，直接说"资料里没有"，不要编造。 资料内容： {{#context#}} 用户问题： {{#sys.query#}}

这里的 {{#context#}} 是知识检索节点输出的上下文变量，{{#sys.query#}} 是用户输入的系统变量，两个都是系统预设的变量名，在 LLM 节点可以直接引用。如果你在工作流里自己加了一个文本节点，要把它的值传给下游 LLM 节点，则需要在文本节点里定义一个输出变量，再在 LLM 节点映射该变量的值。理解“节点输出变量、下游节点引用”这条链路，是 Dify 工作流里变量赋值的基本功。

4.3 发布 API 并接入 Cursor 或自己的系统

工作流调试无误后，从应用编辑页右上角点发布，然后进入“访问 API”页面生成一枚 API 密钥。Dify 提供的 API 是标准 REST 接口，最常用的是 chat-messages 接口：

curl -X POST http://部署机IP:端口/v1/chat-messages \ -H "Authorization: Bearer app-你的API密钥" \ -H "Content-Type: application/json" \ -d '{ "inputs": {}, "query": "什么是Dify", "response_mode": "blocking", "conversation_id": "", "user": "demo-user" }'

参数含义：inputs 对应工作流开始节点的自定义输入变量，没有就传空对象；query 是用户问题；response_mode 选 blocking 是同步等待完整回复，选 streaming 是流式返回；user 是业务侧的用户标识，Dify 会用它在日志里区分不同用户。返回体里的 answer 字段就是最终回复。把这段 curl 换成你熟悉的 JS 或 Python 请求，就是一个最小的二次开发接入。

Cursor 连接 Dify 知识库这个需求也很常见。本质上是把 Dify 的 /v1 接口适配成 Cursor 能识别的模型端点，通常需要在中间写一个薄适配层，把客户端发来的 OpenAI 格式请求转发到 Dify 的 /chat-messages，再返回给客户端。团队内部写一个几十行的转换服务就能跑通，没有必要改成 Dify 源码。记住每个应用的 API 密钥是独立的，拿应用 A 的 Key 去调应用 B 的接口会得到 403，这个细节在第 5 章展开。

5. 部署排查：登录锁定、凭据校验、SSL 与 403 的踩坑记录

这一章写的是我在实际部署和帮同事处理问题时，遇到频率最高的四类故障。每条都按“现象 → 原因 → 解决”来写，方便你直接对照排查。

5.1 现象：登录时提示 too many incorrect password attempts. please try again later.

刚部署完第一次登录，或者连续试错几次密码之后，Dify 会提示密码错误尝试次数过多、请稍后再试。这其实是 Dify 的登录保护机制：它把失败次数记录在 Redis 里，短时间连续失败会临时锁住账号或来源 IP。解决方法是先等锁定期过完，再用正确密码登录；如果等不及，可以直接清掉 Redis 里的登录计数。在 docker 目录下执行：

docker compose exec redis redis-cli KEYS "login:*"

记下返回的 key 名，然后逐个删除：

docker compose exec redis redis-cli DEL 登录相关的key名

我还会顺手检查服务器时间。宿主机和容器的时间偏差过大时，锁定的过期时间判断会出错，表现为明明等了很久还是提示锁定。这个和登录锁定看似无关，但排查起来往往比清空 Redis 更根治。

5.2 现象：配置模型供应商时提示 an error occurred during credentials validation

这个错误字面意思是“凭据验证期间发生错误”，涵盖的情况很多，按概率排序大致是：Base URL 填错、API Key 无效、模型名不受支持、网络到服务商端点不通。我的排查顺序是固定的：先用这一条 curl 直接测试 Key 和服务商端点，排除 Key 问题：

curl -s https://api.openai.com/v1/models \ -H "Authorization: Bearer 你的KEY"

如果 curl 能拿到模型列表，说明 Key 正常，再去确认 Base URL 是否填入了多余的 /v1 路径；如果 curl 也报 401 或 403，直接去服务商后台重新生成 Key。网络层还有一个隐蔽问题：模型服务跑在宿主机某个本地端口上，而 Dify 容器里的 localhost 指向容器自己，永远连不到宿主机。这种场景需要把地址改成 Docker 网关地址，或者让模型服务监听在容器网络可达的地址上。所以看到这个报错，先别急着怀疑版本，Provider 的连通性和 Key 权限占八成以上。

5.3 现象：打开页面提示 SSL 错误、Page not found 或 404

浏览器访问控制台时，有时会看到 SSL 相关错误，有时是 404 或 Page not found，这两类问题都出在入口层。Dify 默认用容器里的 Nginx 做入口，证书和端口都由 .env 控制。如果你直接通过 http://IP:端口 访问，而 .env 里却开了 SSL 相关开关，就会看到证书不匹配的警告；如果证书没有配置但你又用 https 访问，同样报错。

正确做法是：第一次部署一律先用 http + EXPOSE_NGINX_PORT 访问，确认控制台能打开后再考虑配证书。需要 https 时，把证书文件挂载到 Nginx 容器内，并在 .env 里开启对应开关。遇到 404 时先检查端口映射：

docker compose ps

确认 Nginx 服务映射的宿主机端口和你访问的端口一致。一个很低级但常见的问题，是 .env 里把 EXPOSE_NGINX_PORT 改成了 8080，访问时却还在用 80，结果页面要么 404、要么直接提示 Page not found。路径和端口都核对一遍，这类问题基本一分钟能定位。

5.4 现象：调用 /v1 接口返回 403

API 调用返回 403，绝大多数不是服务故障，而是权限或密钥问题。先确认请求头里有没有带 Authorization: Bearer app-xxxx，且这个 Key 确实属于当前正在访问的应用。Dify 的 API 密钥按应用隔离，把应用 A 的 Key 拿去调应用 B 的 API，必然 403。从控制台复制接口示例时，也要注意 Key 是否串到别的应用上去了。

另一个隐蔽点是 IP 白名单。如果在应用 API 设置里开了 IP 限制，而你的出口 IP 不在白名单内，同样返回 403。我在服务器上排查时，会先用一个最简单的请求做对照测试：

curl -i http://部署机IP:端口/v1/chat-messages \ -H "Authorization: Bearer app-正确的密钥" \ -H "Content-Type: application/json" \ -d '{"inputs":{},"query":"ping","response_mode":"blocking","user":"test"}'

看返回的 HTTP 状态码。如果是 200 但业务报错，问题在下游模型或工作流；如果是 403，就逐项核对 Key 归属、应用发布状态和 IP 白名单。这里还有一个容易忽略的规则：应用处于未发布或已停用状态时，API 也会返回 403。检查一下应用编辑页是否显示已发布，再去纠结网络层。

6. 备份与升级：把这份 20250428 原版包用得更久的两个习惯

6.1 备份：数据卷和 .env 一起打包

Dify 的所有业务数据都在 docker/volumes 目录对应的数据卷里，数据库在 postgres 卷、缓存会话在 redis 卷、知识库向量在 weaviate 卷。备份时不需要停服务，但最好挑业务低峰期，直接打包目录和配置文件：

tar czvf dify_backup_$(date +%Y%m%d).tar.gz \ docker/volumes \ docker/.env \ docker/docker-compose.yaml

恢复时先 docker compose down，再把备份里对应目录解压回去，最后 docker compose up -d。需要特别强调：.env 里的 SECRET_KEY 如果变了，恢复后所有会话会失效，已加密的数据也可能读不出来。所以 .env 和 volumes 必须一起备份、一起恢复，这是一个容易翻车的依赖关系。

6.2 升级：先备份、再 diff、后启动

后续在 GitHub 上看到新版本，或者拿到更新的安装包时，不建议直接把新编排文件覆盖到旧目录里启动。编排文件可能新增了环境变量、服务或数据卷定义，直接覆盖容易把旧配置弄丢。我一般这样升级：先备份旧 volumes 和 .env；把新版 docker-compose.yaml 和旧文件做 diff：

diff docker-compose.yaml docker-compose.new.yaml

把新增的变量合并进旧的 .env，保留原来的 SECRET_KEY 和数据库密码，再执行：

docker compose pull docker compose up -d

如果升级后 api 或 worker 起不来，先看迁移日志，确认数据库迁移是否完成，再决定是否回滚。从那以后，我每次动编排文件前都强制走一遍“备份 volumes + diff 配置 + 保留 SECRET_KEY”这三步，宁可多花十分钟，也不在升级失败后再找后悔药。希望这份 20250428 原版包和上面的踩坑记录，能帮你把 Dify 顺利跑起来。

本文还有配套的精品资源，点击获取