简介Dify官方安装包是一份从GitHub获取的开源软件/插件压缩包面向需要部署Dify服务、搭建AI应用或进行二次开发的开发者和运维人员可帮助快速获得官方发布版本省去自行打包的环节。资源共包含2000个文件以Python脚本、JSON配置、CSS样式和JavaScript脚本为主体其中Python脚本与JSON配置负责核心逻辑和项目设置CSS与JavaScript支撑前端交互界面另有Markdown文档、YAML配置及Shell脚本用于部署和环境初始化压缩包整体约20.25MB。压缩包以dify-main为主体涵盖主程序模块、静态资源与配置模板解压后按官方文档操作即可完成安装。目前已有2634人学习下载适合希望通过源码研究Dify架构、扩展功能或快速部署上线的人员。获取后可直接获得一套结构完整的项目主体既可用于本地环境调试也可作为二次开发的起点节省从零搭建和收集依赖的时间。1. Dify 官方安装包一个靠 Docker Compose 跑起来的开源 LLM 平台如果你正在找 Dify 官方安装包先泼一盆冷水这个项目没有 Windows 安装程序也没有单独的 exe 可执行文件。所谓官方安装包本质是 GitHub 上开源仓库打包好的源码加一组 Docker Compose 编排文件你的任务是把它们下载到本地用 Docker 把后端、前端、数据库、向量库一整套服务拉起来。我上个月刚在 Windows 和 Linux 上各部署了一遍社区版先后踩了 SSL 证书、凭据校验失败、Unstructured 解析三个坑这篇就把从 GitHub 下载安装包到本地部署、初始化配置和排错的过程完整过一遍。适合谁看想私有化部署 LLM 应用平台、做内部知识库问答、以及打算二次开发的团队和个人。你只需要知道 Docker 的基本概念剩下的按步骤走就能落地。2. 从 GitHub 拿 Dify 安装包仓库结构、Release 下载与 docker 目录定位2.1 官方仓库里哪几个目录跟安装有关打开 GitHub 上的 langgenius/dify 仓库第一眼会看到 api、web、docker 三个大目录很多第一次下载的人会愣住到底该下哪个其实真正跟部署强相关的不是 api 也不是 web而是 docker 这个目录。它里面放着 docker-compose.yaml、.env.example 和一整套子服务的编排定义。路径作用docker/docker-compose.yaml编排入口定义 api、worker、web、db、redis、sandbox、向量库等所有容器docker/.env.example全部可变参数的模板部署时要复制成 .envapi/后端 Flask 服务源码二次开发才需要深入web/前端 Next.js 源码二次开发才需要深入README.md官方安装入口所有部署方式都从这里跳转先讲清楚为什么 Dify 不是一个单体应用api 负责业务接口worker 跑异步任务sandbox 隔离执行用户自定义代码ssrf_proxy 防服务端请求伪造默认向量库是 Milvus文件解析走 Unstructured前端再单列一个 web。这么多进程塞进一个 exe 根本不现实所以官方选择用 Docker Compose 把整条链路编排起来。社区版官方给的三条部署路线——Docker Compose、本地源码启动、Kubernetes Helm——绝大多数人走 Docker Compose因为本地源码启动要自己装 Python、Node 环境和一堆系统依赖Helm 是给集群用的单机或小团队用 Compose 是最省事、官方维护也最勤的一条路。2.2 Release 源码包、git clone 与容器镜像的关系GitHub 每个 Release 页面都能下载 Source code 的 zip 或 tar.gz这就是很多人挂在嘴边的“官方安装包”。它和 git clone 的区别我用一张表说清楚方式优点缺点适合场景Release 源码包干净、一次性 HTTP 下载、不带 .git 历史更新版本要重新下只想部署、不想碰源码git clone checkout tag切版本方便、改源码可追踪仓库体积大、网络要求高二次开发、想长期跟进社区版这里要提前打个预防针你下载的“安装包”管的是编排和配置真正的容器镜像是 docker compose up 时从 Docker Hub 拉取的 langgenius/dify-api、langgenius/dify-web 等官方镜像。所以完整流程其实是两步——先拿到 compose 编排文件再让 Docker 把镜像拉下来。还有一点关于 GitHub 访问的实话直连慢的时候不要急着找第三方镜像方案Release 包的 zip 是一次性 HTTP 下载通常比 git clone 稳得多真拉不动就让网络畅通的同事下好传给你或者在一台云服务器上拉好再走内网分发。GitHub 没有官方国内镜像第三方镜像站的同步时效和文件完整性都不可控生产环境别依赖它们。2.3 下载之后三件事换目录、复制 .env、校验 compose 语法拿到安装包后的操作路径我习惯把 Dify 放到 /opt/dify 下mkdir -p /opt/dify cd /opt/dify # 方案 Agit clone 后切到 release 页面显示的 tag git clone https://github.com/langgenius/dify.git . git checkout release 页面显示的 tag # 方案 Brelease 源码包解压后把内容提到目录根 # unzip dify-*.zip mv dify-*/* . cd docker cp .env.example .env docker compose config --quiet三个动作各有目的git checkout 到指定 tag保证你部署的是 Release 对应版本而不是 master 上的开发态cp .env.example .env 不是可选项compose 文件里到处是 ${EXPOSE_NGINX_PORT} 这类变量引用没有 .env 它只能 fallback 默认值之后端口、密码从哪来你完全不知道最后 docker compose config --quiet 是很好的自检语法错误或变量引用问题它会直接报错不用等到 up 的时候再去翻日志。还有个容易忽视的细节解压后先看一眼 docker 目录里 .env.example 和 docker-compose.yaml 是否完整如果缺少文件要么是下载中断要么是解压工具抽风重新下载一遍比硬着头皮往上叠快得多。到这一步你已经有了可用的安装包剩下的核心问题是参数怎么设、服务怎么起、起了之后怎么配这正是下面几章要解决的。3. Windows/Linux 本地部署.env 参数、docker compose 启动与首次登录3.1 环境准备Docker、内存与端口规划先把硬条件摆出来Dify 全家桶正常跑起来建议内存 8GB 以上。我在一台 4GB 的云主机上试过Milvus 反复内存不足日志里全是 mmap 失败最后只能先关掉知识库功能才把服务救起来。CPU 2 核起步磁盘 20GB 以上因为镜像加数据卷占得不少。Windows 上部署Docker Desktop 必须开 WSL2 后端安装时勾选 Use WSL 2 based engine。我踩过的一个坑是 WSL 默认内存上限只有宿主机的一半部署完发现 web 和 api 都起来了但 Milvus 偶尔被系统杀掉。解决办法是在用户目录下的 .wslconfig 里手动分配[wsl2] memory8GB processors4改完执行 wsl --shutdown 再重启 Docker Desktop 才生效。Linux 上反而简单Ubuntu 22.04 装 Docker Engine 和 compose 插件就行sudo apt update sudo apt install docker.io docker-compose-v2 -y sudo usermod -aG docker $USER # 重新登录后验证 docker compose version端口规划是最容易被忽略的一步。compose 默认把 80 和 443 映射到宿主机很多机器上 80 已经被系统自带 nginx 或其他服务占了结果 web 容器反复重启。我一般直接在 .env 里改掉cd /opt/dify/docker sed -i s/^EXPOSE_NGINX_PORT.*/EXPOSE_NGINX_PORT8080/ .env sed -i s/^EXPOSE_NGINX_SSL_PORT.*/EXPOSE_NGINX_SSL_PORT8443/ .envEXPOSE_NGINX_PORT 是宿主机访问入口改完访问 http://localhost:8080 或 http://服务器IP:8080。SSL 的坑后面第 5 章单独展开这里先把 HTTP 链路跑通再说。3.2 .env 里的必改参数与不能动的东西打开 .env先找这几项关键参数参数作用我的建议SECRET_KEY会话签名密钥必须改用 openssl rand -base64 42 生成随机串EXPOSE_NGINX_PORT / EXPOSE_NGINX_SSL_PORT宿主机映射端口按端口占用情况改POSTGRES_PASSWORD、DB_PASSWORD数据库密码改成强密码注意 compose 引用一致VECTOR_STORE向量库类型默认 milvus内存小再考虑换轻量方案UNSTRUCTURED_API_URL文档解析服务地址默认 http://unstructured:8000先不要动生成密钥并写入openssl rand -base64 42 # 把输出的字符串填到 .env 的 SECRET_KEY 后面SECRET_KEY 不改的后果是会话签名可预测登录态存在安全隐患内网也一样。这里有个很容易翻车的点DB_HOST、REDIS_HOST、MILVUS_HOST 这类配置默认是容器名 db、redis、milvus它们走的是 compose 内部网络不是 127.0.0.1。别按直觉把 DB_HOST 改成 localhostapi 容器反而连不上数据库——因为它不在宿主机的网络命名空间里。注意compose 内部的服务名是固定的.env 里能改的是密码、端口、存储路径不要改 host 那几项除非你明确知道自己在做什么。3.3 启动、看日志与首次登录准备工作做完启动就一条命令cd /opt/dify/docker docker compose up -d docker compose ps第一次 up 会从 Docker Hub 拉不少镜像api、web、milvus、unstructured 都是大件耗时取决于网络。拉完后重点看 api 容器的状态正常应该是 healthydocker compose ps # 期望 api 的 STATUS 为 healthyweb 为 running docker compose logs -f apiapi 一直 unhealthy先看日志里的数据库连接错误十有八九是 .env 里数据库密码改了一半或者端口参数写错。web 起不来优先看 nginx 容器日志多半是端口被占。健康之后浏览器访问 http://localhost:8080/install服务器部署访问 http://服务器IP:8080/install这一步是初始化管理员邮箱和密码相当于 Dify 的“装系统”环节。首次登录后别急着传文档先把模型供应商配上否则知识库和聊天助手都是空转。如果你卡在登录页一直转圈检查 web 容器日志常见是前端访问后端的地址没配对外部入口确认 .env 里 CONSOLE_API_URL、APP_API_URL 这类前端直连地址和你实际访问的域名或 IP 一致。另外提前记住一个坑改完 .env 直接 docker compose up -d 不会自动重建容器配置不生效是常态必须 down 再 up后面排错章还会讲。4. 初始化配置模型接入、知识库流水线与变量聚合器实战4.1 模型供应商OpenAI 兼容接口与 Ollama 的 Base URL 坑Dify 的模型接入在“设置 → 模型供应商”本质上是一个插件式的模型适配层DeepSeek、通义、Moonshot 这类国内模型大多提供了 OpenAI 兼容接口所以选 OpenAI-API 兼容供应商填三个东西API Key、Base URL、模型名。一半的人第一次会在 Base URL 上翻车DeepSeek 兼容地址要写 https://api.deepseek.com/v1只写域名不带 /v1 的话SDK 拼接路径会错点保存时校验直接失败。填完点保存Dify 会先做一次凭据校验credentials validation校验失败大概率是 Key 或 Base URL 的问题不一定是服务商挂了。完全离线的团队模型侧用 Ollama 跑本地模型提前把模型拉好Dify 这边就只需要面对局域网或本机。Ollama 供应商的填法有讲究字段Windows / Mac 值Linux 值Base URLhttp://host.docker.internal:11434/v1http://172.17.0.1:11434/v1模型名与 ollama list 一致例如 qwen2.5:7b与 ollama list 一致为什么不能写 localhostDify 的 api 跑在容器里容器内的 localhost 指向容器自己不是宿主机。Windows 和 Mac 的 Docker Desktop 提供了 host.docker.internal 这个宿主机别名Linux 没有所以要用 Docker 网桥网关 172.17.0.1。填进 Dify 之前先在宿主机验证一遍curl http://localhost:11434/v1/models -H Authorization: Bearer ollama宿主机能列出模型再填到 Dify问题范围一下就缩小了。如果 curl 都不通先检查 Ollama 是否真的在监听 11434而不是去 Dify 里反复折磨校验按钮。4.2 知识库流水线从上传文档到检索测试的完整走法Dify 的知识库是一条完整流水线上传文档、分段、清洗、索引、检索测试。我在实际项目里常用的参数组合环节参数我的设置分段长度chunk size500 token分段重叠overlap50 token分隔符分段依据按 Markdown 标题分段索引方式高质量 / 经济高质量向量检索召回条数top-k4相似度阈值过滤低分片段0.4分段长度决定单条知识的粒度500 token 对问答场景比较均衡重叠 50 是为了避免语义在切分处被切断。索引方式选高质量会调用你配的 embedding 模型把每段编码成向量存进 Milvus检索时算相似度选经济只做关键字匹配省资源但效果差很多。第一次跑通建议选高质量知识库问答的差距非常明显。上传 docx 或 PDF 时会触发文件解析服务也就是 Unstructured如果报 unstructured api url is not configured直接看第 5 章。解析完成后进入分段和索引索引跑完在“召回测试”页面输入一句测试问题能看到命中的片段和相似度分数——这一步能直接验证 embedding 模型和向量库是否真的在工作。知识库建好后挂到聊天助手或工作流的知识检索节点注意别把整个检索结果原样塞给 LLM我一般把 top-k 限制到 4 条提示词里只引用结果的文本字段上下文体积可控。4.3 变量聚合器把多个来源的变量拼成一个再喂给 LLM变量聚合器是工作流里最容易被忽略但很实用的节点。它的作用是把多个变量按顺序拼接成一个新变量典型场景把用户当前问题、知识库检索结果、上一轮回答摘要拼成一段带结构的上下文再给 LLM而不是让 LLM 节点直接面对一堆杂乱变量。在界面上操作路径是工作流编辑器中添加“变量聚合器”节点。在变量列表里添加要合并的变量来源选 sys.query、知识检索输出、上一个节点输出。设置分隔符我常用 \n\n 或 \n---\n。设置输出变量名比如 aggregated_content。在 LLM 节点的提示词里引用 {{#aggregated_content#}}。对应的节点配置可以用下面这段 JSON 理解界面操作的可视化结果不同版本字段名可能略有差异{ type: variable-aggregator, variables: [ { variable_selector: [sys, query] }, { variable_selector: [knowledge_retrieval, result] } ], separator: \n\n, output_variable: aggregated_content }参数说明variables 里的顺序就是拼接顺序separator 决定拼接后的分隔符直接影响 token 用量output_variable 命名要避开系统保留字段。这个节点最大的价值是控制上下文格式避免把一堆无结构文本堆在提示词里。如果你发现工作流开始报上下文超长回变量聚合器检查是不是把整段原文都拼进去了。5. Dify 部署避坑清单SSL 错误、凭据校验失败与上下文超长排查5.1 凭据校验失败an error occurred during credentials validation现象添加模型供应商时点保存页面直接弹 an error occurred during credentials validationKey 看着没问题但就是过不去。原因按概率排序一是 API Key 复制时带了不可见空格或换行二是 Base URL 少了 /v1 或多了尾斜杠三是服务器出网受限模型 API 域名不在白名单四是 Ollama 方式下模型名和 ollama list 的结果不一致。其中第一种最常见也最隐蔽界面完全看不出来。解决先在宿主机用 curl 模拟一遍请求curl https://api.deepseek.com/v1/models -H Authorization: Bearer sk-xxx宿主机通了再检查 Dify 里填的值Base URL 末尾别带斜杠。还不行就去翻 api 容器日志cd /opt/dify/docker docker compose logs -f api日志里能看到是 401 还是超时。我遇到过一次很玄学的情况curl 验证身份没问题Dify 一直 401最后把 Key 重新手打一遍才解决就是复制进去带了不可见字符。所以遇到这个错第一反应不是怀疑服务商而是先重新手动输入一遍 Key。5.2 Unstructured API 未配置doc file processing 报错现象知识库里上传 docx 或 PDF处理状态一直停在解析阶段日志里报 unstructured api url is not configured for doc file processing。原因Dify 1.x 把文档解析独立成 Unstructured 服务.env 里 UNSTRUCTURED_API_URL 没指向它或者 compose 里这个服务压根没起来。有些人从旧版本迁移过来或者手工精简过 docker-compose.yaml最容易漏掉这个子服务。解决先确认 compose 里有没有这个服务再把它拉起来cd /opt/dify/docker grep -n unstructured docker-compose.yaml docker compose up -d unstructured docker compose exec unstructured curl http://localhost:8000/health确认 .env 里是 UNSTRUCTURED_API_URLhttp://unstructured:8000这个地址是 compose 内部网络的服务名不是 localhost。改完 .env 记得 down 再 up然后重新上传文档解析服务正常的话文档状态会在几秒内从“解析中”变到“分段完成”。注意UNSTRUCTURED_API_URL 指向的是容器服务名 unstructured不是宿主机 IP端口也不要乱改除非你同时改了 compose 里该服务的内部端口定义。5.3 SSL 错误HTTPS 证书怎么配都不对现象浏览器访问提示证书无效API 客户端调用时报 SSL 相关错误还有的人配了 HTTPS 之后整个页面打不开。原因Dify 的 nginx 默认监听 443但如果你没提供证书或者证书的 CN/SAN 跟你实际访问的 IP 不一致浏览器必然报错。另一个隐蔽原因是宿主机系统时间不准容器内校验证书时直接失败这种问题在长期不重启的云主机上偶尔出现。解决内网小团队我真心建议先用 HTTP把 HTTPS 的诉求放一放。实在要上 HTTPS把证书和私钥放到 docker/nginx/ssl 目录在 .env 里配置证书路径并重启 nginx 容器。访问地址必须是证书上的域名用 IP 访问自带证书错误这不是 Dify 的 bug。宿主机时间用 ntpdate 校准后再重启容器证书校验的玄学问题大多能消失。如果你同时改了 EXPOSE_NGINX_SSL_PORT 但没给证书nginx 容器会反复重启先用 docker compose logs nginx 确认是 bind 失败还是证书加载失败。5.4 工作流上下文超长现象工作流跑到 LLM 节点时报上下文超长、context length exceeded或者模型接口直接返回 400。原因变量聚合器或知识检索把大量原文拼进了提示词。常见操作是知识检索 top-k 设了 10、每段 500 token四段就是 2000 token 起再叠加多轮对话历史和系统提示词轻松超过小模型的 4K 窗口。这不是模型的锅是输入侧没收敛。解决先压缩输入而不是去调模型供应商的 max tokens。我的做法是知识检索节点 top-k 降到 4相似度阈值提到 0.4 过滤低分片段变量聚合器只拼必需字段别把整段历史对话塞进去最后实在需要长文本再换长上下文模型。判断是不是输入超长看 api 日志里 400 响应的错误体会明确写 max context length 之类的字段定位很快。5.5 升级、迁移与“多租户”传言现象docker compose pull 拉完新镜像后直接 up -d结果登录不上或页面报版本不匹配迁移服务器后数据全空或者 postgres 容器起不来。原因升级不是简单换镜像官方升级流程包含数据库迁移跳过那一步 api 和 web 版本就对不上。迁移只拷了代码没拷 docker/volumes 下的数据卷或者拷了但权限变了postgres 容器直接拒绝启动。数据文件权限不对时容器日志里会明确报 permission denied。解决升级前备份 .env 和 docker/volumes 整个目录按官方 upgrade 文档执行迁移步骤没有迁移脚本的版本就 pull 镜像后 down 再 up别手动去动数据库表结构。迁移后如果数据目录权限不对按容器日志提示调整目录属主不要盲目 chmod 777。另外看到有人在问社区版 1.10 多租户这里说清楚社区版里能看到的“工作空间/成员”是团队协作隔离不是企业版那种多租户。要给多个独立客户交付隔离环境别指望社区版原生支持要么自己基于 API 做层隔离要么上企业版。6. 验证闭环从空白应用到二次开发入口的检查习惯部署完别急着上复杂功能先花两分钟建一个最小应用验证全链路。操作路径应用 → 创建空白应用 → 聊天助手 → 提示词里只写一行“你是助手请直接回答 {{#sys.query#}}” → 关联一个已验证可用的模型 → 发布 → 对话框发一句测试文本。这一步通过说明 web、api、模型供应商、数据库整条链路是通的之后再接知识库或工作流出问题就能把排查范围锁定到具体节点而不是整套环境。我见过同事先建知识库、再搭复杂工作流、最后才配模型结果模型没配通所有调试都在空转。正确顺序永远是环境起来 → 模型通 → 建最小应用 → 再叠加功能。这也是为什么我把“验证闭环”放在最后的理由——它看起来不起眼实际是部署质量最有效的标尺。二次开发也是一样的逻辑。打算改 Dify 源码的话从一开始就选 git clone 而不是 Release 包官方 compose 里 api 和 web 默认用远程构建好的镜像但支持切到本地构建源码模式具体开关当前版本的 docker-compose.yaml 注释里有写改完要重新 build 镜像。调试时盯着 api 容器的日志后端代码改了容器不重建就不生效别在旧容器上白调cd /opt/dify/docker docker compose logs -f api最后说个我自己交过的学费这次部署最大的一个坑是改完 .env 端口后没 down 重建浏览器怎么刷都是旧端口还以为是防火墙拦截前后折腾了半小时。从那以后我养成了一个习惯凡是动了 .env 或 compose 文件一律 docker compose down 再 docker compose up -d然后用 docker compose ps 确认所有服务状态正常绝不省这一步。希望帮到你。本文还有配套的精品资源点击获取