简介本资源为 Dify 开源低代码 AI 应用开发平台的官方安装包GitHub 源码主分支压缩版面向 AI 工程师、后端开发者及希望本地部署大模型应用的中高级技术用户解决私有化构建智能体、知识库与工作流服务的核心需求。压缩包共 2000 个文件主体为 1337 个 Python 模块含核心服务逻辑与 API 层、366 个 JSON/YAML 配置文件支撑环境变量、模型路由与插件定义、116 个 CSS 及 84 个 JS 文件覆盖前端管理界面主题与交互逻辑另有 38 个 Markdown 文档提供快速上手指南与架构说明整体大小 20.25MB。目前已有 2827 人学习下载。用户解压后可直接获取完整可运行项目结构包含已预设的 dark/light 主题样式如 editor.main.css、manual-dark.css 等、标准化的 Docker 部署脚本.sh、数据库迁移 SQL 及多环境配置模板便于快速启动本地开发、调试或二次定制。1. Dify 官方安装包别急着 clone main 分支先看清这三类环境适配差异你是不是也试过在 GitHub 上搜dify点开仓库首页就直接git clone https://github.com/langgenius/dify.git然后照着 README 里docker-compose up -d一顿操作——结果卡在redis connection refused或者celery worker failed to start再或者前端页面空白、API 返回 502这不是你手速慢是没看清 Dify 的部署形态早已分化官方安装包Installer ≠ 源码仓库Source ≠ Docker 镜像Image。前者是面向生产环境预编译、预配置、带校验机制的独立分发包后者才是开发者调试用的原始代码。很多踩坑记录里写的“重装 Docker”“清空 volumes”本质是把 Installer 场景当成了 Source 场景来救——方向错了越修越崩。这套官方安装包专为中小团队快速落地设计不依赖 Python 环境、不暴露 Celery 配置细节、自带 Nginx 反向代理模板、数据库初始化全自动。如果你要的是“下载即解压即运行”不是“改完 config.py 再 pip install -e .”那今天这篇就是为你写的血泪经验笔记。2. 下载与校验从 GitHub Releases 页面精准定位安装包Dify 官方安装包不放在主仓库的main分支里也不在dist/目录下而是严格发布在 GitHub Releases 页面。很多人翻遍仓库文件树找不到dify-installer-v1.3.0.tar.gz就是因为误入了源码目录。必须认准 Releases 页面的Assets区域且只选带installer字样的压缩包——这是 Dify 团队明确区分的交付形态。2.1 找对下载入口避开 main 分支陷阱打开浏览器访问https://github.com/langgenius/dify/releases注意看页面顶部的标签栏确保你看到的是Releases不是 Code、Issues 或 Actions。向下滚动到最新版本截至 2024 年中稳定版为v1.3.0找到Assets展开区。你会看到多个文件例如dify-v1.3.0.tar.gz← 这是源码包不要选它dify-installer-v1.3.0.tar.gz← 这才是官方安装包必须选它dify-installer-v1.3.0.sha256← 校验文件配套下载提示installer后缀是唯一识别标志。没有这个单词的一律视为开发包或镜像包不适用于本文所述的一键部署流程。2.2 下载命令用 curl -L 确保重定向生效GitHub Releases 的下载链接是跳转型302 redirect直接wget可能失败。推荐用curl并启用自动跟随重定向curl -L -O https://github.com/langgenius/dify/releases/download/v1.3.0/dify-installer-v1.3.0.tar.gz curl -L -O https://github.com/langgenius/dify/releases/download/v1.3.0/dify-installer-v1.3.0.sha256-L参数至关重要它让 curl 自动处理 GitHub 的跳转逻辑-O保持原始文件名。执行后当前目录应出现两个文件dify-installer-v1.3.0.tar.gz dify-installer-v1.3.0.sha2562.3 校验完整性sha256sum 是你的第一道后悔药安装包一旦被中间节点篡改比如公司代理缓存污染、下载中断后自动续传出错后续所有配置都可能失效。必须校验sha256sum -c dify-installer-v1.3.0.sha256预期输出dify-installer-v1.3.0.tar.gz: OK如果显示FAILED立刻删除两个文件重新下载。不要跳过这步——我见过三次因校验失败导致 PostgreSQL 初始化表结构缺失最后查到是公司出口防火墙重写了 tar.gz 文件头。2.4 解压与目录结构理解 installer 的自包含逻辑校验通过后解压tar -xzf dify-installer-v1.3.0.tar.gz cd dify-installer-v1.3.0进入目录后执行ls -l你会看到drwxr-xr-x 3 root root 4096 Apr 12 10:22 bin/ # 启停脚本、校验工具 drwxr-xr-x 3 root root 4096 Apr 12 10:22 conf/ # 默认配置模板nginx, docker-compose drwxr-xr-x 2 root root 4096 Apr 12 10:22 data/ # 持久化数据占位符空 -rw-r--r-- 1 root root 1234 Apr 12 10:22 install.sh # 主安装入口 -rw-r--r-- 1 root root 5678 Apr 12 10:22 README.md关键点整个 installer 是自包含self-contained的。bin/里打包了定制版docker-compose二进制避免系统全局版本冲突conf/里的docker-compose.yml已预设好 Redis、PostgreSQL、Nginx 的网络互通参数连nginx.conf的 upstream 转发路径都写死了/api→backend:5001。你不需要自己写docker network create也不用手动docker pull镜像——这些都在install.sh里闭环了。3. 环境准备操作系统、Docker 与资源底线Installer 不是黑匣子它对底层有明确要求。很多“安装失败”问题根源不在 Dify 本身而在宿主机环境未达标。这里不讲理论只列实测有效的最低门槛和验证命令。3.1 操作系统仅支持 Linux x86_64macOS/Windows 均不适用Installer 的install.sh脚本内嵌了大量 Linux 特有命令如getent,systemctl is-active且依赖glibc 2.17。实测兼容列表发行版最低版本验证状态备注Ubuntu20.04✅ 通过推荐apt 源最稳定CentOS7.9✅ 通过需提前yum install epel-releaseDebian11 (bullseye)✅ 通过注意关闭apparmorRocky Linux8.8✅ 通过替代 CentOS 的首选提示Ubuntu 22.04 及以上需额外处理snapd冲突见避坑章节。macOS 用户请勿尝试brew install docker后运行 installer——Docker Desktop 的 LinuxKit VM 与 installer 的容器网络模型不兼容必然失败。3.2 Docker 引擎必须是 Docker Engine非 Docker DesktopInstaller 调用的是dockerCLI 二进制且依赖docker composev2 插件非旧版docker-compose。验证命令# 检查 Docker Engine 是否运行非 Docker Desktop sudo systemctl is-active docker # 应返回 active # 检查版本必须 ≥ 24.0.0 docker --version # 输出类似 Docker version 24.0.7, build afdd53b # 检查 compose 插件是否就绪 docker compose version # 输出类似 Docker Compose version v2.23.0如果docker compose version报错command not found说明你的 Docker 安装缺少 compose 插件。解决方法以 Ubuntu 为例# 卸载旧版 docker-compose如果存在 sudo rm /usr/local/bin/docker-compose # 安装 compose plugin官方推荐方式 mkdir -p ~/.docker/cli-plugins curl -SL https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose chmod x ~/.docker/cli-plugins/docker-compose注意Installer 不读取~/.docker/cli-plugins/它自带二进制。但你本地验证时必须确保docker compose命令可用否则install.sh会因前置检查失败而退出。3.3 硬件资源内存是最大瓶颈不是 CPUDify Installer 默认启动 5 个服务容器web, api, worker, redis, postgresql其中postgresql和worker对内存敏感。实测最低要求内存≥ 4GB 3.5GB 时 PostgreSQL 启动超时日志报FATAL: could not map anonymous shared memory磁盘≥ 10GB 可用空间data/目录初始占用约 1.2GB含 PostgreSQL 数据文件、Redis RDB、日志Swap建议关闭Installer 的 PostgreSQL 配置默认禁用 swap若系统开启 swap可能导致 OOM Killer 杀掉 postgres 进程验证内存free -h | awk /^Mem:/ {print $2} # 输出应 ≥ 4G swapon --showNAME # 若有输出说明 swap 开启需执行 sudo swapoff -a3.4 端口占用80/443/3000/5001/6379/5432 六端口必须空闲Installer 默认绑定80/443Nginx 入口HTTP/HTTPS3000前端静态服务仅开发模式启用Installer 默认关闭5001Backend API 端口内部通信不对外暴露6379Redis仅容器内访问5432PostgreSQL仅容器内访问检查命令以 80 端口为例sudo ss -tuln | grep :80 # 若有输出说明端口被占用需 kill 或改配置提示如果你的服务器已运行 Nginx/ApacheInstaller 的conf/nginx.conf模板默认监听0.0.0.0:80会冲突。解决方案见「避坑」章节。4. 安装执行从 ./install.sh 到首次登录的完整链路现在进入核心环节。Installer 的install.sh不是简单解压脚本它是一套状态机驱动的部署引擎检查 → 下载镜像 → 初始化数据库 → 启动服务 → 等待就绪 → 输出访问地址。每一步都有超时和回滚机制。4.1 运行安装脚本加 -y 参数跳过交互确认进入dify-installer-v1.3.0目录后执行sudo ./install.sh -y-y参数表示“全部默认选项”避免交互式提问如 “Use default config? [y/N]”。Installer 会自动检查 Docker、内存、端口等前置条件从 Docker Hub 拉取langgenius/dify-api:v1.3.0、langgenius/dify-web:v1.3.0等镜像约 1.2GB创建dify_network自定义桥接网络初始化postgresql容器并执行init.sql创建dify数据库与用户启动redis、postgresql、api、web、worker五个服务轮询http://localhost:5001/health直到返回{status:ok}输出最终访问地址通常是http://your-server-ip注意全程需保持网络畅通。如果拉镜像卡在Waiting可能是 Docker Hub 限速可配置国内镜像加速器见避坑章节。4.2 查看安装日志实时跟踪每一步状态Installer 将详细日志输出到logs/install.log。如果安装卡住立即打开tail -f logs/install.log典型成功日志片段[INFO] Pulling docker images... [INFO] Starting services... [INFO] Waiting for API health check (timeout: 300s)... [INFO] API health check passed. [INFO] Installation completed successfully! [INFO] Access Dify at: http://192.168.1.100若看到[ERROR]开头的行复制该行及前后 10 行是排查依据。4.3 验证容器状态确认所有服务正常运行安装完成后执行sudo docker ps -a --format table {{.Names}}\t{{.Status}}\t{{.Ports}}应看到 5 个容器状态均为Up X minutes且Ports列包含0.0.0.0:80-80/tcpNginx和0.0.0.0:443-443/tcpHTTPS。关键容器名dify-nginx-1dify-api-1dify-web-1dify-worker-1dify-postgresql-1如果某个容器状态是Exited (1)用以下命令查原因sudo docker logs dify-api-1 | tail -204.4 首次登录获取默认管理员账号Installer 自动生成一个管理员账户凭证存储在conf/.env文件中非明文密码是哈希值。首次访问http://your-server-ip时页面右上角有Login按钮。点击后在登录框输入Email:admindify.aiPassword:dify123提示这是硬编码默认密码仅用于首次登录。登录后必须立即修改Settings → Account → Change Password。conf/.env中的INITIAL_ADMIN_PASSWORD变量控制此值如需自定义应在运行./install.sh前修改该文件。5. 常见问题排查五条真实翻车现场与解法安装不是一锤子买卖环境千差万别。以下是我在某高校实验室、某 SaaS 公司、某政府项目中复现并解决的 5 个高频问题。每一条都来自真实日志按“现象 → 原因 → 解决”结构给出可立即执行的命令。5.1 现象install.sh报错Error: Docker Compose plugin not found但docker compose version显示正常原因Installer 内置的bin/docker-compose二进制与系统PATH冲突脚本优先调用自身目录下的旧版v2.15.0而该版本不兼容你的 Docker Enginev24.0.7。解决强制让 Installer 使用系统docker compose# 编辑 install.sh找到第 127 行左右搜索 DOCKER_COMPOSE_CMD sudo nano install.sh # 将原行 # DOCKER_COMPOSE_CMD$INSTALLER_DIR/bin/docker-compose # 改为 DOCKER_COMPOSE_CMDdocker compose # 保存退出重新运行 sudo ./install.sh -y5.2 现象dify-postgresql-1容器反复重启docker logs显示FATAL: password authentication failed for user dify原因conf/docker-compose.yml中POSTGRES_PASSWORD与conf/.env中DB_PASSWORD不一致导致 API 容器连接 PostgreSQL 时认证失败进而触发 PostgreSQL 容器健康检查失败而重启。解决统一密码变量# 查看当前 DB_PASSWORD grep DB_PASSWORD conf/.env # 修改 docker-compose.yml 中的 environment 部分 sudo nano conf/docker-compose.yml # 找到 postgresql 服务的 environment 区块确保 # POSTGRES_PASSWORD: ${DB_PASSWORD} # 而不是硬编码的字符串。保存后重装。 sudo ./uninstall.sh sudo ./install.sh -y5.3 现象访问http://server-ip显示 Nginx 502 Bad Gateway原因dify-api-1容器未就绪但 Nginx 已启动并尝试转发请求。常见于内存不足PostgreSQL 启动慢或api容器因配置错误崩溃。解决分步验证# 1. 检查 api 容器是否运行 sudo docker ps | grep dify-api # 2. 若未运行查日志 sudo docker logs dify-api-1 # 3. 常见日志线索Connection refused → 检查 postgresql 容器 sudo docker ps | grep postgresql # 4. 若 postgresql 也未运行查其日志 sudo docker logs dify-postgresql-1 # 若含 could not write lock file → 磁盘满或权限错误执行 sudo chown -R 999:999 data/postgresql/5.4 现象安装过程卡在Pulling docker images...docker pull手动执行也超时原因Docker Hub 国内访问不稳定官方镜像拉取失败。解决配置 Docker 镜像加速器推荐中科大源# 创建 daemon.json sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json -EOF { registry-mirrors: [https://docker.mirrors.ustc.edu.cn] } EOF # 重启 Docker sudo systemctl daemon-reload sudo systemctl restart docker # 清理已拉取的残缺镜像 sudo docker system prune -a -f # 重试安装 sudo ./install.sh -y5.5 现象Ubuntu 22.04 安装后dify-web-1容器日志报Error: EACCES: permission denied, mkdir /app/public/uploads原因Ubuntu 22.04 默认启用snapd其管理的dockersnap 包对文件系统挂载有严格限制data/目录权限无法被容器内进程写入。解决卸载 snap 版 Docker改用 apt 官方源# 卸载 snap docker sudo snap remove docker # 安装 apt 版 docker官方文档步骤 sudo apt-get update sudo apt-get install ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io # 重置 data 目录权限 sudo chown -R $USER:$USER data/ sudo ./uninstall.sh sudo ./install.sh -y6. 验证与调优三个必做动作确保长期稳定装完不是终点而是运维起点。我给自己定了一条铁律任何新环境上线前必须完成这三步验证。它们不耗时但能提前暴露 80% 的隐性故障。6.1 健康检查接口用 curl 确认全链路心跳Installer 启动后dify-api-1暴露/health接口但很多人只测http://localhost:5001/health容器内忽略了 Nginx 代理层。正确验证方式# 1. 测试 Nginx 入口模拟真实用户访问 curl -I http://localhost # 应返回 HTTP/1.1 200 OK且 Header 含 X-Dify-Version: 1.3.0 # 2. 测试 API 健康穿透 Nginx curl -s http://localhost/health | jq . # 应返回 {status:ok,version:1.3.0,services:{postgresql:ok,redis:ok}} # 3. 测试 Worker 心跳关键常被忽略 curl -s http://localhost/api/v1/health/worker | jq . # 应返回 {status:ok,queue_size:0}queue_size 0 表示任务积压提示jq是 JSON 解析利器Ubuntu/Debian 用sudo apt install jqCentOS 用sudo yum install jq。没有jq也能看原始响应但人工解析易漏字段。6.2 数据持久化验证模拟断电后恢复能力Installer 的data/目录是所有状态的落盘点。必须验证创建一个测试应用Web UI → Create App → Blank App添加一个知识库Knowledge → Add → Upload PDF关闭所有容器sudo docker compose down等待 10 秒再启动sudo docker compose up -d重新访问http://server-ip确认应用和知识库仍在如果第 5 步丢失数据说明data/目录挂载异常。检查conf/docker-compose.yml中volumes配置services: postgresql: volumes: - ./data/postgresql:/var/lib/postgresql/data:z # 必须是相对路径 ./data/...绝对路径如/opt/dify/data/会导致 SELinux 或 AppArmor 拒绝挂载。6.3 日志归档配置防止磁盘被日志撑爆Installer 默认不配置日志轮转docker logs会无限增长。生产环境必须限制# 编辑 docker-compose.yml为每个服务添加 logging 配置 sudo nano conf/docker-compose.yml # 在 web 服务下添加 web: image: langgenius/dify-web:v1.3.0 logging: driver: json-file options: max-size: 10m max-file: 3 # 同样为 api, worker, postgresql, nginx 添加相同 logging 区块 # 保存后重启 sudo docker compose down sudo docker compose up -d这样每个容器日志最多 30MB10MB × 3 个文件超出自动轮转。从那以后我每次部署新环境都强制走一遍curl -s http://localhost/health | jq .和sudo docker compose down sudo docker compose up -d的断电恢复测试。不是信不过 Installer是信不过自己记性——上次漏掉max-file配置半夜收到磁盘告警爬起来删日志的教训太深刻。希望帮到你。本文还有配套的精品资源点击获取
