简介面向无法稳定访问 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 目录下。下面这份清单是我每次拿到原版包后都会对照检查的路径/文件作用部署时是否需要改docker/docker-compose.yamlCompose 编排主文件定义 api、worker、web、nginx、db、redis、sandbox、weaviate 等服务端口冲突时需要改端口映射docker/.env.example环境变量模板包含数据库、向量库、存储等全部可调参数必须复制为 .env 并调整docker/volumes数据卷挂载目录对应 postgres、redis、weaviate、sandbox 等持久化数据建议保留默认备份时直接打包api/ 与 web/后端 API 服务与前端控制台的源码目录用于自定义构建镜像第一次部署不直接动README 与文档部署、配置、常见问题的说明可留作参考在正式部署前有一个容易误解的点需要先说清楚这份包解决的是“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、向量库同时跑起来不频繁 OOM4GB 的机器勉强能起服务但知识库索引一跑就容易翻车。先检查 Docker 和 Compose 是否就位docker --version docker compose versionDocker 版本在 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默认值在部署到内网环境时可以先用但如果这台机器能被公网访问建议一并改掉。下表是几个容易出现问题的变量改完之后对着检查一遍变量名默认值说明EXPOSE_NGINX_PORT80对外暴露的 HTTP 端口冲突时改这里VECTOR_STOREweaviate可选 weaviate / opensearch / qdrantSECRET_KEY空必改用 openssl rand -base64 42 生成POSTGRES_PASSWORDdifyai123456生产环境建议修改提示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 接口返回 403API 调用返回 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 和旧文件做 diffdiff 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 顺利跑起来。本文还有配套的精品资源点击获取 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 目录下。下面这份清单是我每次拿到原版包后都会对照检查的路径/文件作用部署时是否需要改docker/docker-compose.yamlCompose 编排主文件定义 api、worker、web、nginx、db、redis、sandbox、weaviate 等服务端口冲突时需要改端口映射docker/.env.example环境变量模板包含数据库、向量库、存储等全部可调参数必须复制为 .env 并调整docker/volumes数据卷挂载目录对应 postgres、redis、weaviate、sandbox 等持久化数据建议保留默认备份时直接打包api/ 与 web/后端 API 服务与前端控制台的源码目录用于自定义构建镜像第一次部署不直接动README 与文档部署、配置、常见问题的说明可留作参考在正式部署前有一个容易误解的点需要先说清楚这份包解决的是“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、向量库同时跑起来不频繁 OOM4GB 的机器勉强能起服务但知识库索引一跑就容易翻车。先检查 Docker 和 Compose 是否就位docker --version docker compose versionDocker 版本在 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默认值在部署到内网环境时可以先用但如果这台机器能被公网访问建议一并改掉。下表是几个容易出现问题的变量改完之后对着检查一遍变量名默认值说明EXPOSE_NGINX_PORT80对外暴露的 HTTP 端口冲突时改这里VECTOR_STOREweaviate可选 weaviate / opensearch / qdrantSECRET_KEY空必改用 openssl rand -base64 42 生成POSTGRES_PASSWORDdifyai123456生产环境建议修改提示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 接口返回 403API 调用返回 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 和旧文件做 diffdiff 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 顺利跑起来。本文还有配套的精品资源点击获取