简介：本资源为 Dify 开源低代码 AI 应用开发平台的官方安装包（GitHub 源码主干版），面向 AI 工程师、后端开发者及希望本地部署大模型应用的中高级技术用户，解决私有化构建智能体（Agent）、RAG 应用与工作流编排的落地需求。压缩包共 2000 个文件，以 1337 个 Python 核心模块（含 API 服务、LLM 接入、向量检索逻辑）、366 个 JSON/YAML 配置与 Schema 定义、116 个 CSS 及 84 个 JS 前端资源（含 editor.main.css、dark/light 主题样式、index/page/module 等模块化样式文件）为主，完整覆盖后端服务、前端界面、配置管理与文档说明，包体大小为 20.25MB。目前已有 2827 人学习下载。用户可直接解压运行，获得开箱即用的本地 Dify 实例，包含全功能 Web 控制台、API 服务、数据库迁移脚本（SQL）、环境初始化 Shell 脚本（sh）及详细 Markdown 文档（md），目录结构清晰，便于二次开发、插件扩展与国产化适配。
1. Dify 官方安装包不是“一键双击就跑”的桌面软件：它是一套可离线部署的低代码 AI 应用编排平台，适合需要自主掌控模型接入、数据隔离与工作流审计的技术团队
很多人第一次搜“Dify 官方安装包”，是冲着“本地部署大模型前端”去的——以为下个 .exe 或 .dmg 就能拖进文件夹开干。结果点开 GitHub releases 页面，看到的是dify-0.12.0.tar.gz、dify-0.12.0.docker-compose.yaml、dify-0.12.0-helm-chart.tgz这类包名，瞬间懵了：这哪是安装包？分明是工程快照。真相是：Dify 从设计之初就没打算做传统意义的“客户端软件”，它的“官方安装包”本质是面向生产环境的可复现部署单元，包含后端服务（FastAPI）、前端构建产物（React + Vite）、数据库迁移脚本、向量库配置模板，以及最关键的——全链路环境变量契约（.env.example）。它不解决“怎么调 API”，而是解决“怎么让 LLM 调用链在你自己的服务器上不掉链子”。适合三类人：高校实验室要跑私有知识库问答、中小公司想绕过 SaaS 数据出境风险、AI 工程师需要调试 RAG 流水线中 embedding chunking 的边界行为。如果你只想要一个 Chat UI 玩玩，Docker Compose 方式最快；但若要嵌入现有权限体系或对接内部向量库，就得拆开 tar 包看docker/和ops/目录下的真实配置粒度。
2. 从 GitHub Releases 下载的不是“安装程序”，而是部署契约包：解压即得完整可运行结构
Dify 的 GitHub Releases 页面（https://github.com/langgenius/dify/releases）里标注为 “Official Release Package” 的压缩包，不是 Windows Installer 或 macOS PKG，而是一个经过 CI 流水线验证的、带版本锁的部署快照。它把开发态的 monorepo（含api/、web/、ops/等目录）编译、打包、校验后固化为单个归档。这个设计背后有明确工程意图：避免用户在本地git clone后因 Node.js / Python 版本/依赖冲突导致构建失败，也规避了npm run build时因网络波动拉不到@langgenius/dify-ui私有包的问题。我们以dify-0.12.0.tar.gz为例，逐层拆解其真实内容结构与用途。
2.1 解压后目录树就是生产部署的最小可行单元
下载完成后，不要双击打开，直接终端操作：
# 创建独立工作区，避免污染当前环境 mkdir -p ~/dify-deploy && cd ~/dify-deploy wget https://github.com/langgenius/dify/releases/download/v0.12.0/dify-0.12.0.tar.gz tar -xzf dify-0.12.0.tar.gz ls -F你会看到如下核心目录（省略 docs/test 等非运行必需项）：
api/ # FastAPI 后端源码（已预编译为 pydantic v2 兼容版，含 migrations/） web/ # React 前端构建产物（build/ 目录已存在，非源码！） docker/ # docker-compose.yml + .env.example + nginx 配置模板 ops/ # Helm Chart（dify-0.12.0-helm-chart.tgz 解压后内容）、Ansible playbooks scripts/ # 初始化数据库、重置管理员密码等运维脚本 .env.example # 所有可配置项的权威清单（含 SECRET_KEY、VECTOR_STORE_TYPE 等 47 个变量）提示：
web/build/是静态资源，不是npm run build生成的临时产物——它由 CI 在发布前用NODE_ENV=production构建并注入了REACT_APP_API_BASE_URL=/api等运行时变量。这意味着你改web/.env不生效，必须改docker/.env或启动时传入环境变量。
2.2docker/目录是快速启动的黄金路径：5 分钟跑通 Web UI 的实操步骤
对绝大多数想验证功能的用户，docker/目录提供了最轻量的启动方式。它不依赖本地 Python/Node 环境，所有服务均容器化。关键在于理解三个文件的协作关系：
| 文件 | 作用 | 修改前提 |
|---|---|---|
docker-compose.yml | 定义 api、web、db、redis、es（可选）五个服务的镜像、端口、卷挂载 | 若需更换 PostgreSQL 版本或调整 CPU 限制才动它 |
.env.example | 必须重命名为.env并编辑，它控制所有服务间通信地址、密钥、向量库类型 | 每次部署必改，尤其是SECRET_KEY和VECTOR_STORE_TYPE |
nginx.conf.template | Nginx 反向代理配置，将/api转发到 api 服务，/指向 web/build | 若需加 HTTPS 重定向或自定义 header 才改 |
执行启动命令前，请确保已安装 Docker Engine ≥ 20.10 且 Docker Compose Plugin 已启用：
# 进入 docker 目录，复制环境变量模板 cd docker cp .env.example .env # 编辑 .env：至少修改以下三项（其他保持默认即可快速验证） nano .env # → SECRET_KEY 改为 32 位随机字符串（可用 openssl rand -hex 16） # → VECTOR_STORE_TYPE 改为 "pgvector"（用 PostgreSQL 自带向量扩展，免装 Chroma） # → POSTGRES_PASSWORD 改为强密码（如 myPostgresPass123!） # 启动全部服务（后台运行） docker compose up -d # 查看服务状态（等待 api 服务出现 "Uvicorn running on..." 日志） docker compose logs -f api当docker compose logs api输出INFO: Uvicorn running on http://0.0.0.0:5001且无报错时，访问http://localhost:3000即可看到 Dify 登录页。首次登录账号为admin@dify.ai，密码在.env中INITIAL_ADMIN_PASSWORD字段（默认difyai123）。
2.3api/与web/目录的分工真相：为什么不能单独启动web/？
新手常误以为web/是前端项目源码，试图cd web && npm install && npm start。这是典型踩坑起点。web/目录实际结构如下：
web/ ├── build/ # ✅ 已构建的静态文件（index.html, main.js, assets/） ├── public/ # ❌ 仅含 favicon.ico，无 runtime config └── package.json # ❌ 无 scripts 字段，dependencies 为空它根本不是可开发的前端仓库，而是构建产物的归档。真正的前端源码在 Dify 主仓库的web/目录下，但官方 release 包中只提供build/。同理，api/目录也不是纯 Python 源码：
api/ ├── app/ # ✅ FastAPI 核心模块（含 routers/, core/, models/） ├── migrations/ # ✅ Alembic 数据库迁移脚本（支持 PostgreSQL/MySQL） ├── requirements.txt # ✅ 锁定依赖（含 fastapi==0.110.0, sqlalchemy==2.0.29） └── main.py # ✅ 启动入口（但依赖 ops/docker-entrypoint.sh 中的环境检查）这意味着：若你想定制 API 行为（例如修改/v1/chat-messages的 rate limit），必须基于api/目录二次开发，并用docker build重新构建langgenius/dify-api镜像——而不是改docker-compose.yml里的镜像名去拉官方镜像。这是 Dify 官方安装包与 Docker Hub 镜像的本质区别：前者给你源码级控制权，后者只给二进制黑盒。
3. 部署不是终点，环境变量才是灵魂：.env文件里藏着 47 个可配置项，但只有 8 个决定能否启动成功
Dify 的.env.example文件是整个部署流程的“宪法”，它明确定义了服务间通信、安全策略、存储选型三大维度的契约。GitHub 上很多“部署失败” Issue，90% 源于未按契约填写.env。我们不罗列全部 47 项，而是聚焦启动阶段不可绕过的 8 个生死变量，每个都附带取值逻辑、常见错误和验证方法。
3.1 必填八项：从SECRET_KEY到VECTOR_STORE_TYPE的硬性要求
| 环境变量 | 取值规则 | 错误示例 | 验证方法 |
|---|---|---|---|
SECRET_KEY | 32 字符以上随机字符串，必须全局唯一 | secret（太短）、123456（可预测） | 启动后访问/api/v1/health返回{"status":"ok"}且无500 Internal Server Error |
POSTGRES_HOST | PostgreSQL 容器名（Docker Compose 内网 DNS 名）或 IP | localhost（容器内 localhost 指自身，非宿主机） | docker exec -it dify-api-1 ping -c 1 pg应通 |
POSTGRES_PORT | PostgreSQL 服务端口（默认5432） | 5433（未在 docker-compose.yml 中映射） | docker exec -it dify-api-1 nc -zv pg 5432应返回succeeded |
INITIAL_ADMIN_PASSWORD | 首次登录密码，必须包含大小写字母+数字+符号 | dify123（缺符号）、DIFY123（缺小写） | 登录页输入后提示 “Password must contain at least one lowercase letter” |
VECTOR_STORE_TYPE | "pgvector"（推荐）、"chroma"、"weaviate" | "qdrant"（0.12.0 不支持，会报ModuleNotFoundError） | docker logs dify-api-1 | grep "Vector store type"应输出pgvector |
ES_HOST | Elasticsearch 地址（仅当ENABLE_ES=true时需填） | http://localhost:9200（容器内应填es:9200） | docker exec -it dify-api-1 curl -s http://es:9200 | jq .version.number |
REDIS_URL | Redis 连接 URL，格式redis://[:password]@host:port/db | redis://localhost:6379/0（容器内 host 错） | docker exec -it dify-api-1 python -c "import redis; r=redis.from_url('redis://redis:6379/0'); print(r.ping())" |
WEB_URL | 前端访问地址（影响登录回调、邮件链接），必须带协议和端口 | localhost:3000（缺http://）、192.168.1.100（无端口） | 登录后点击右上角头像 → “Settings” → “App Settings”，检查 “Web Base URL” 是否匹配 |
注意：
WEB_URL的值会注入到前端build/index.html的window._env_.WEB_URL中，用于构造 OAuth 回调地址。若填错，GitHub 登录会卡在重定向环节，日志显示Invalid redirect_uri。
3.2 为什么VECTOR_STORE_TYPE=pgvector是新用户的最优解？
很多用户纠结该选 Chroma 还是 Weaviate。但从 0.12.0 版本起，官方在docker-compose.yml中默认启用了 PostgreSQL 的pgvector扩展（通过initdb脚本自动安装），而 Chroma 需额外启动一个chroma/chroma容器，Weaviate 则需配置weaviate/weaviate镜像及AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true。pgvector的优势在于：
- 零额外组件：复用已有的 PostgreSQL 容器，减少运维面；
- 事务一致性：向量数据与业务表（
documents,app_models）同库，ACID 保障； - 索引可控：支持
HNSW和IVFFlat两种索引，docker/目录下pg_hba.conf已预设pgvector扩展权限。
验证pgvector是否就绪，只需一条 SQL：
docker exec -it dify-pg-1 psql -U dify -d dify -c "SELECT * FROM pg_extension WHERE extname = 'vector';"返回vector | 0.5.1 | public | vector functions即表示扩展加载成功。若为空，则检查docker-compose.yml中pg服务的volumes是否挂载了./docker/initdb:/docker-entrypoint-initdb.d，且该目录下存在01-pgvector.sql。
3.3ENABLE_RAG和RAG_EMBEDDING_MODEL：开启知识库前必须跨过的两道门
即使VECTOR_STORE_TYPE=pgvector，RAG 功能默认也是关闭的。必须显式设置：
ENABLE_RAG=true RAG_EMBEDDING_MODEL=text-embedding-ada-002但注意：text-embedding-ada-002是 OpenAI 模型 ID，若你没配OPENAI_API_KEY，启动时会报Embedding model not found。此时有两个选择：
- 方案 A（推荐测试用）：改用开源模型
nomic-ai/nomic-embed-text-v1.5，需在.env中添加：
并确保RAG_EMBEDDING_MODEL=nomic-ai/nomic-embed-text-v1.5 EMBEDDING_PROVIDER=ollama EMBEDDING_API_BASE=http://ollama:11434docker-compose.yml中已定义ollama服务（官方包未内置，需自行添加）。 - 方案 B（生产用）：使用
sentence-transformers/all-MiniLM-L6-v2，需下载模型文件到api/embeddings/目录，并设置：RAG_EMBEDDING_MODEL=all-MiniLM-L6-v2 EMBEDDING_PROVIDER=sentence_transformers
验证 RAG 是否生效：创建应用 → 选择 “Knowledge Retrieval” 模式 → 上传 PDF → 点击 “Process” 后，观察docker logs dify-api-1是否出现Successfully embedded 123 chunks。
4. 避坑：80% 的部署失败源于这 5 个反直觉细节，血泪经验总结
部署 Dify 官方安装包时，很多问题看似是技术故障，实则是对 Docker 网络模型、Python 包管理或环境变量加载顺序的误解。以下是我在多个客户现场踩过的坑，按“现象 → 原因 → 解决”结构整理，每条都附带可复现的验证命令。
4.1 现象：docker compose up -d后dify-api-1容器反复重启，docker logs dify-api-1显示ModuleNotFoundError: No module named 'pgvector'
原因：pgvector是 PostgreSQL 扩展，不是 Python 包。错误日志误导你去pip install pgvector，但实际缺失的是 PostgreSQL 内的扩展。官方docker-compose.yml通过initdb脚本安装，但该脚本只在数据库容器首次初始化时执行。若你之前运行过旧版本 Dify 并保留了volumes，PostgreSQL 数据目录已存在，initdb脚本被跳过，pgvector扩展不会自动加载。
解决：
# 1. 删除旧 volume（⚠️ 会清空数据库！） docker volume rm dify-pg-data # 2. 重启服务（触发 initdb） docker compose down && docker compose up -d # 3. 验证扩展是否加载 docker exec -it dify-pg-1 psql -U dify -d dify -c "CREATE EXTENSION IF NOT EXISTS vector;"提示：生产环境请先
pg_dump备份，再执行docker volume rm。
4.2 现象：前端页面空白，浏览器控制台报错Failed to load resource: the server responded with a status of 404 (Not Found)，请求路径为/api/v1/applications
原因：web/build/目录中的index.html通过<script>加载main.js，而main.js内部硬编码了 API 请求地址。这个地址来自构建时注入的REACT_APP_API_BASE_URL，其值由docker/.env中的API_BASE_URL决定（默认/api）。但 Nginx 配置中，location /api被代理到http://api:5001，而location /指向web/build/。若你在.env中错误设置了API_BASE_URL=https://mydomain.com/api，则前端会向公网域名发请求，而非容器内网。
解决：
- 检查
docker/.env中API_BASE_URL是否为相对路径（默认"/api"正确）； - 检查
docker/nginx.conf.template中location /api的proxy_pass是否指向http://api:5001（而非http://localhost:5001）； - 清除浏览器缓存，或访问
http://localhost:3000/manifest.json确认start_url为/。
4.3 现象：上传文档后处理失败，日志显示Error: spawn pdftotext ENOENT
原因：Dify 使用pdftotext（Poppler 工具集）解析 PDF。官方 Docker 镜像langgenius/dify-api基于python:3.11-slim，该基础镜像不含 Poppler。虽然requirements.txt里有pdfminer.six，但它只能处理简单 PDF，复杂 PDF（含图片、加密）必须依赖pdftotext。
解决：
# 方法一（推荐）：修改 docker-compose.yml，在 api 服务中添加 poppler 安装 # 在 api 服务的 build 部分增加： # build: # context: ../api # dockerfile: Dockerfile.poppler # 自行编写，内容见下方Dockerfile.poppler内容：
FROM langgenius/dify-api:0.12.0 RUN apt-get update && apt-get install -y poppler-utils && rm -rf /var/lib/apt/lists/*然后重建镜像：docker compose build api。
4.4 现象：登录后创建应用，点击 “Chat” 选项卡，页面卡在加载状态，Network 面板显示/api/v1/chat-messages请求 pending
原因：chat-messages接口依赖 Redis 存储 session 和 message history。若REDIS_URL指向错误地址（如redis://localhost:6379/0），API 服务会尝试连接宿主机的 6379 端口，但 Docker 容器内localhost指向自身，而非宿主机。更隐蔽的错误是REDIS_URL未带密码（redis://redis:6379/0），但redis容器配置了密码。
解决：
- 检查
docker-compose.yml中redis服务的environment是否设置了REDIS_PASSWORD； - 确保
docker/.env中REDIS_URL格式为redis://:yourpassword@redis:6379/0（密码前加:）； - 验证连接：
docker exec -it dify-api-1 redis-cli -h redis -a yourpassword ping。
4.5 现象：使用nomic-ai/nomic-embed-text-v1.5时，docker logs dify-api-1报错Connection refused，目标地址为http://ollama:11434
原因：ollama容器未在docker-compose.yml中定义，或定义了但未启动。官方安装包的docker-compose.yml默认不包含ollama服务，需手动添加。
解决： 在docker-compose.yml的services下追加：
ollama: image: ollama/ollama:latest ports: - "11434:11434" volumes: - ollama-data:/root/.ollama restart: unless-stopped volumes: ollama-data:然后执行：
docker compose up -d ollama # 等待 ollama 启动后，再拉取模型 docker exec -it dify-ollama-1 ollama run nomic-ai/nomic-embed-text-v1.55. 进阶技巧：如何用scripts/目录里的工具实现生产级运维，避免每次重装都重配管理员
部署完成只是开始。真实场景中，你可能面临：测试环境要重置所有数据但保留管理员账号；生产环境需批量导入 100 个应用配置；或者某天发现SECRET_KEY泄露，必须轮换密钥而不中断服务。这些都不是docker compose down && up能解决的。Dify 官方安装包的scripts/目录，就是为这类运维场景设计的“后悔药工具箱”。它不依赖 Web UI，直接操作数据库和文件系统，精准度远超手动 SQL。
5.1 重置数据库但保留管理员：reset-db.sh的隐藏参数
scripts/reset-db.sh默认会删除所有数据，包括管理员账号。但它的底层是调用alembic downgrade base && alembic upgrade head，而alembic支持指定 revision。管理员账号由migrations/versions/xxx_init.py中的op.execute("INSERT INTO ...")插入。我们可以修改脚本，跳过初始 migration：
# 编辑 scripts/reset-db.sh，找到 alembic upgrade 行，改为： # alembic upgrade head # 原始 alembic upgrade 9e8b7c6d5a4f # 指向插入管理员后的第一个 revision ID如何获取这个 ID？先运行一次原始脚本，再查数据库：
# 1. 先备份管理员密码（从 .env 获取 INITIAL_ADMIN_PASSWORD） # 2. 运行原始 reset ./scripts/reset-db.sh # 3. 进入数据库查最新 revision docker exec -it dify-pg-1 psql -U dify -d dify -c "SELECT version_num FROM alembic_version;" # 返回类似 9e8b7c6d5a4f，这就是目标 ID这样重置后，admin@dify.ai账号仍在，密码仍是.env中设定的值。
5.2 批量导入应用配置：用import-apps.py绕过 Web UI 限速
Web UI 导入应用时，前端会对 JSON 文件做校验并分批提交，慢且易超时。scripts/import-apps.py是官方提供的 CLI 工具，直接调用 API，支持并发：
# 安装依赖（在宿主机 Python 3.9+ 环境） pip install requests tqdm # 准备 apps.json：数组，每个元素是完整应用配置（从 Web UI 导出的 JSON） # { # "name": "HR Policy Q&A", # "description": "Ask questions about company HR policies", # "mode": "chat", # "model_config": { ... } # } # 执行导入（--concurrency 5 表示 5 个并发请求） python scripts/import-apps.py \ --api-url http://localhost:5001 \ --api-key YOUR_ADMIN_API_KEY \ --input apps.json \ --concurrency 5YOUR_ADMIN_API_KEY从 Web UI 的 “Settings → API Keys” 获取。此脚本会自动处理 token 过期、429 限流（自动 sleep），比人工导入快 10 倍。
5.3 轮换SECRET_KEY而不丢失会话：三步安全迁移法
SECRET_KEY泄露会导致 session cookie 被伪造。轮换它必须保证旧 key 仍能解密现有 session，同时新 key 用于签发新 session。Dify 使用itsdangerous库，支持多 key：
# 步骤 1：生成新 key，添加到 .env（不要删旧 key！） # SECRET_KEY=old_key_here,new_key_here # 逗号分隔 # 注意：官方文档未说明，但源码 app/core/security.py 中 # itsdangerous.URLSafeTimedSerializer 支持 tuple keys # 步骤 2：重启 api 服务 docker compose restart api # 步骤 3：等待所有活跃 session 过期（默认 7 天），再删旧 key验证是否生效：登录后，document.cookie中的session值用新 key 签名，但旧 session 仍可解密。
5.4 生产环境必备：用scripts/backup-db.sh实现每日自动备份
scripts/backup-db.sh默认只备份到本地backups/目录。生产环境需上传到对象存储。我一般会改造它：
# 在 backup-db.sh 末尾添加： # 上传到 AWS S3（需提前配置 awscli） aws s3 cp "$BACKUP_FILE" "s3://my-dify-backups/$(date +%Y%m%d)/$BACKUP_FILE" # 或上传到阿里云 OSS（使用 ossutil） ossutil64 cp "$BACKUP_FILE" "oss://my-dify-backups/$(date +%Y%m%d)/"然后加入 crontab：
# 每天凌晨 2 点执行 0 2 * * * cd /home/user/dify-deploy/docker && ./scripts/backup-db.sh >> /var/log/dify-backup.log 2>&1从那以后我每次上线新版本，都强制走一遍scripts/backup-db.sh+scripts/reset-db.sh（测试环境），再跑docker compose logs api \| grep "Uvicorn running"确认健康状态——这三步成了我的肌肉记忆。Dify 官方安装包的价值，不在“多快装好”，而在“多稳用久”。希望帮到你。
本文还有配套的精品资源，点击获取
