简介：这是Dify官方安装包，来自GitHub平台的zip压缩文件，面向需要部署或扩展Dify应用的开发者、运维人员，可用于搭建AI应用开发环境。压缩包共2000个文件，大小20.25MB，以Python源码（1337个py）、JSON配置（366个json）、前端样式与脚本（116个css、84个js）为主，另含Markdown文档、Shell部署脚本、YAML配置等，覆盖后端逻辑、界面资源、环境配置与使用说明，包体结构完整。已有2758人学习或下载。解压后即可获得Dify主程序及相关依赖文件，适合需要快速获取完整源码进行本地化安装、二次开发或功能定制的技术人员，可省去逐文件收集的麻烦，便于直接对照文档完成部署与调试。
1. Dify官方安装包：为什么推荐直接从GitHub社区版装
装Dify看起来是个「docker compose up -d」就能完事的小事，可真到了生产或个人服务器上，最常翻车的不是Dify本身，而是你从哪儿拿安装包、拿到的是不是官方release结构、以及docker目录下的文件跟你的环境对不对得上。网上不少教程让你去拉别人的一键脚本或改过的镜像，结果装到一半容器起不来，数据目录乱成一团，最后只能删了重来——这种血泪经验我见得太多。
与其赌那些来路不明的包，不如直接走GitHub官方仓库拿社区版安装包。Dify作为开源项目，官方在GitHub发布的release压缩包和docker部署目录是自洽的：拿到手、改端口、配.env、启动，一条链路走完就能在本地跑起一套完整的大模型应用开发平台。这篇笔记就按我实际装过的路径来写，从选版本到验证跑通，每一步都给你能直接抄的命令和参数取舍。
2. 安装前的环境准备：先把系统、Docker版本和目录定下来
2.1 系统选型：哪类Linux发行版踩坑最少
Dify官方部署用Docker Compose这套思路，所以操作系统的选择本质上是在选「Docker运行得最顺」的系统。我在Ubuntu 22.04 LTS、Debian 12、CentOS 7上都试过，先说结论：Ubuntu 22.04是坑最少的，遇到问题能搜到的资料也最多。
CentOS 7虽然也能跑，但有个历史遗留问题——系统自带的yum源里docker-ce版本偏旧，如果你用默认源装出来的Docker是19.x，跑Dify这套compose编排时会出现容器网络模式不兼容的情况。你的破旧Docker与dify的api、worker容器之间容易出现网络隔离异常，表现为前端页面能开、API请求却一直超时。CentOS 7上我一般会把Docker升级到20.10以上再继续。
内存方面，Dify社区版官方给出的最低配置是CPU 2核、内存4GB。这不是玩笑——光docker目录下那一堆容器（nginx、postgres、redis、weaviate、api、worker、web、sandbox）加起来，空闲状态下就要占掉2GB左右内存。如果你机器是2GB的小内存VPS，建议直接把weaviate这个向量数据库容器停掉，后面我会说怎么停。
# Ubuntu 22.04 / Debian 12 检查基础环境 uname -a cat /etc/os-release free -h nproc先确认系统架构和资源余量，x86_64架构最稳妥，如果拿到的是ARM机器（比如苹果芯片的云主机），后续镜像拉取会自动走arm64版本，Dify官方镜像对ARM支持是完整的，但个别第三方扩展容器可能有坑。内存至少保证剩余3GB以上再往下走。
2.2 Docker与Compose版本要求：低了真的跑不动
Dify的docker编排用到了Compose V2的特性和多个depends_on条件判断，所以Docker引擎最低要20.10.7，Compose V2最好用2.20以上的版本。这不是官方文档上的建议值，是我实际遇到的硬性门槛——Compose版本过低时，compose.yaml里的depends_on条件判断会被忽略，导致api容器在postgres还没就绪时就开始连数据库，疯狂报错重启。
# 安装新版Docker与Compose插件（Debian/Ubuntu系） curl -fsSL https://get.docker.com | sh systemctl enable --now docker docker --version docker compose version安装脚本来自Docker官方，它会自动配置apt源并装上最新稳定版Docker。这一步时间比较久，卡在网络上是正常现象，只要apt源能连上就行。装完之后务必用上面两条命令确认版本号：Docker版本大于20.10.7，docker compose version输出里带v2.字样。
如果你之前装过旧版docker-compose（Python那个单文件版），建议直接卸载掉，Dify新版目录已经不提供docker-compose.yml这种旧格式的完整适配了，继续用docker-compose命令去跑会出现文件找不到的报错。新版统一用docker compose（带空格）。
2.3 目录规划：源码、数据、日志分开存
很多人在家目录里直接解压release包，跑起来之后一堆volumes数据目录散落在home下，升级时不知道该备份什么，迁移时更是一脸懵。我习惯把Dify的部署目录固定在/opt/dify，数据目录让它默认生成在/opt/dify/docker/volumes，日志通过docker compose logs统一看。
# 固定部署根目录 mkdir -p /opt/dify cd /opt/dify这个目录一旦定下来，之后升级、迁移、备份都围绕它做。官方release包解压之后，站在/opt/dify/dify-1.x.x/这个目录里就能看到docker/子目录，里面装的是compose编排文件、.env.example模板以及各种依赖配置。建议把release包里的docker目录整个软链出来，或者干脆记住你解压到了哪个绝对路径，因为后续每次执行docker compose命令都要在这个目录下进行，路径对不上是新手最容易迷糊的地方。
3. 从GitHub拉取官方安装包：release包、clone与解压细节
3.1 release压缩包和git clone，到底选哪个
Dify官网的部署引导和GitHub release页面都提供了下载入口，但这里的「官方安装包」有很多人理解错了。真正的官方安装包就是GitHub仓库langgenius/dify下每次发版时打出的源码归档压缩包，不是Docker镜像包——镜像是在你执行docker compose up -d时现场从Docker Hub拉取的。
所以选release包还是git clone，取决于你想怎么升级。如果追求稳定、部署目录干净，下载release的tar.gz压缩包最合适；如果你打算长期跟版本、随时git pull拉最新，那就直接clone整个仓库。我自己的做法是拉release包，因为Dify发版频率不高，每次换版本直接下载新压缩包比维护一个git仓库更直观。
3.2 下载与解压：校验文件名和版本号
# 在 /opt/dify 下下载release包 wget https://github.com/langgenius/dify/archive/refs/tags/1.15.3.tar.gz tar -xzf 1.15.3.tar.gz cd dify-1.15.3/docker ls -la这里以某个release版本号为例，具体版本以你打开GitHub releases页面时看到的最新tag为准。下载之前先看release页面里这个tag对应的代码是否包含docker目录——极早期的版本没有独立docker编排目录，不过现在的基本每个正式版都有。解压后进入docker目录，你会看到.env.example、docker-compose.yaml、docker-compose-base.yaml、nginx子目录等文件，这些就是安装包的核心内容。
注意，如果你的服务器访问GitHub慢，wget可能断掉，加-c参数断点续传。文件较大时我习惯先下载到本地机器再scp上去，但这就是个人网络情况的取舍了。
3.3 改默认端口：80端口被占用的应对
docker-compose.yaml里nginx容器的端口映射默认是80:80，意味着安装完Dify会直接占用宿主机80端口。如果机器上已经跑了nginx或者别的web服务，这个冲突会让Dify启动时直接报port is already allocated，你还没看到界面就先栽个跟头。
# 打开 docker-compose.yaml，找到nginx服务下的ports段 vim docker-compose.yaml # 将 "80:80" 改为 "8080:80" # 保存后启动，访问 http://服务器IP:8080改的时候注意冒号左侧是宿主机端口，右侧是容器内端口。容器内端口80是nginx自己监听的，不要动；需要改的是左侧的宿主机映射。改完之后，Dify的Web入口就变成了8080，API地址也一并走这个端口。如果你后面要用独立的域名+SSL，这一步可以之后再通过nginx反代把443转到8080来处理。
4. 配置.env与启动：顺序对了，成功率翻倍
4.1 先看清docker目录下的文件分工
解压之后的docker目录里，有几个文件你必须分清楚：.env.example是环境变量模板，docker-compose.yaml是主编排文件，docker-compose-base.yaml是基础镜像与依赖服务的定义，nginx/目录下是反向代理的站点配置模板。
.env.example和docker-compose.yaml的关系是：compose文件里的${VARIABLE}占位符，运行时从.env里读取。所以你必须先复制.env.example为.env，再改里面的参数，然后才能启动。跳过这一步直接docker compose up -d，compose会拿不到必填变量，启动直接失败。
4.2 这些环境变量按需改，别一上来全动
# 进入docker目录 cd /opt/dify/dify-1.15.3/docker cp .env.example .env # 编辑.env，重点是下面几个 vim .env.env文件里变量非常多，我一般只动几个关键的：SECRET_KEY、POSTGRES_PASSWORD这种安全性参数生成随机长串；EXPOSE_NGINX_PORT改成刚才在compose里设置的宿主机端口；NGINX_PORT保持80不要动；INIT_PASSWORD可以设置一个初始管理员密码。
设置SECRET_KEY和数据库密码时，生产环境不要用dify这种弱口令。生成随机密码的常用做法：
openssl rand -hex 16把输出填进.env对应位置。还有几个跟功能相关的开关：ENABLE_WEAVIATE控制是否启用weaviate向量数据库，不需要知识库检索功能的小项目可以设成false；ENABLE_OPEN_AI_API控制是否开放OpenAI风格API端点，仅内部使用可关掉。
4.3 docker compose up -d：启动过程的正确打开方式
# 在 /opt/dify/dify-1.15.3/docker 目录下执行 docker compose up -d # 观察所有容器状态 docker compose ps启动命令本身只有一行，但执行后发生的事情值得你盯着看：compose会按依赖顺序先拉取postgres、redis、weaviate等基础镜像，再启动api、worker、web。第一次拉镜像的时间取决于网络,几个大镜像加起来好几个GB,建议用docker compose pull提前把镜像拉好，再进行up -d，这样你能清楚看到是哪一步在卡。
每次执行up -d后，用docker compose ps看状态栏。正常的标志是：api、worker、web、nginx、postgres、redis、ssrf_proxy、sandbox这些容器都显示Up且健康状况为healthy。如果某个容器反复重启，立刻docker compose logs <容器名>看日志，不要瞎等。
5. 卡住的坑：Dify部署失败的常见问题排查
5.1 现象：nginx容器起不来，报port is already allocated
这个是最常见的启动失败原因。你机器上80端口已经被其他服务占了，Dify的nginx容器自然抢不到端口。
解决方法很简单：回到3.3节说的端口映射修改，把宿主机端口改掉，同时同步修改.env里的EXPOSE_NGINX_PORT。两个地方必须一致，否则容器能起来但端口映射对不上，访问还是不成功。我犯过一次错就是只改了compose没改.env，结果容器起来了，页面却一直打不开。
5.2 现象：api容器启动后一直CrashLoopBackOff
看docker compose logs api，十有八九是数据库连接失败。原因通常是api容器比postgres容器先就绪，连接被拒。新版Dify通过depends_on做了等待，但如果你用的是旧版docker compose或compose版本过低，这个等待机制不生效。
解决思路分两步：先升级docker compose版本到2.20以上；如果版本没问题，手动重启api容器让它重新连数据库：
docker compose restart api如果还不行，看日志里有没有password authentication failed，那就是.env里POSTGRES_PASSWORD和api容器读到的密码不一致——改了.env之后没有重启所有容器，旧容器还在用内存里的旧变量。
5.3 现象：worker容器反复重启，日志里是Failed to init worker
worker容器的作用是异步处理任务，它启动时会连Redis和数据库。如果Redis没起来或者密码不对，worker就无限重启。排查看Redis容器状态：
docker compose logs redis常见原因是.env里REDIS_PASSWORD设置了强密码，但redis容器初始化时没读到。遇到这种情况，我一般直接把redis密码相关的配置恢复默认空密码，内网环境没必要给redis加密码，反而给自己添堵。改完.env后要重新创建容器才能生效：
docker compose up -d --force-recreate5.4 现象：升级Dify版本后,数据库迁移失败
从旧版本升级到新release包，启动时api容器会自动执行数据库迁移。迁移失败的表现是api容器日志里有一堆migration相关的红色报错，页面打开是502或白屏。
遇到这个情况，最稳妥的办法是降级回原来的版本,然后把数据库备份恢复,再重新走升级流程。我在一次大版本升级时跳过了一个中间版本，数据库结构跳变导致迁移器直接放弃。从那以后我升级都遵循「逐版本升级」原则，不跨大版本跳。另外升级前务必备份docker/volumes里的postgres数据目录，这是最后的后悔药。
# 备份数据库 volumes（升级前必做） tar -czf dify-db-backup.tar.gz /opt/dify/dify-1.x.x/docker/volumes/pgdata6. 装完怎么验证跑通：从容器状态到第一个AI应用
6.1 一套快速的健康检查流程
容器全部Up不代表Dify可用。我习惯按这个顺序验证：先看所有容器健康状态，再测端口连通性，最后在浏览器里走完整初始化流程。
# 1. 检查容器健康状态 docker compose ps # 2. 检查端口HTTP响应 curl -I http://服务器IP:8080 # 3. 查看关键容器日志里是否有ERROR docker compose logs api | grep -i errorcurl返回200说明nginx和web服务已经通了。首次访问时Dify会显示初始化页面，让你创建管理员账号——这一步是验证能否写入数据库的关键，如果到这里没报错，说明postgres、api全链路正常。我还会顺手测一下注册登录和创建应用两个流程，因为有的安装web容器起来了但api连不上，登录时才会暴露502。
6.2 创建一个最简对话应用
初始化完成后，点「创建应用」选「聊天助手」，模型选一个你配置好的API供应商（比如OpenAI兼容接口），随便发一句消息。这一步能跑通，意味着api容器到模型供应商的请求链路、sandbox执行环境、日志持久化全部是正常的。如果消息发出去一直转圈，优先看docker compose logs api里的出站请求报错，多半是模型API Key没配置正确。
6.3 从一次升级翻车中学到的部署习惯
之前有一次升级，我图省事没看release notes，直接按网上教程docker compose down后拉新包启动，结果数据库迁移失败，折腾了半小时才救回来。从那以后我每次部署或升级Dify都强制走一遍固定流程：先备份pgdata目录、再确认当前版本号、下载对应新release包、比对.env里新增的配置项、最后才启动。这套流程看起来多花五分钟，但比出问题再想办法省的不是一时半会。
Dify社区版作为开源项目，版本迭代很快，你现在装的可能不是最新版，但只要紧跟着GitHub官方release页更新，把安装包来源控制住，这套环境基本不会变成黑匣子。希望这篇笔记帮你少走一段弯路，装完能用、用着能续。
本文还有配套的精品资源，点击获取
