简介：本资源为 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 官方安装包不是“一键双击就跑”的桌面软件：它是一套可本地部署的低代码 AI 应用编排平台，适合想绕过 SaaS 封闭生态、把提示工程、RAG、Agent 工作流真正握在自己手里的开发者与技术团队很多人第一次搜“dify 官方安装包”时，心里想的是：有没有 Windows .exe 或 macOS .dmg？点开就装，装完就用。现实是——Dify 没有传统意义的“客户端安装包”，它的“官方安装包”本质是 GitHub 上托管的一整套可复现、可审计、可定制的源码工程，包含后端服务（FastAPI + Celery）、前端界面（React）、数据库迁移脚本、向量库对接逻辑，以及最关键的——完整定义了「应用如何从 Prompt 编排 → 数据接入 → 模型路由 → 输出后处理」这一整条链路的配置契约。它不面向终端用户，而面向需要把 AI 能力嵌入自有系统、对数据主权、调用延迟、模型切换自由度有硬性要求的场景：比如某高校实验室要基于私有医学文献构建问答助手，某公司法务部需在内网部署合同条款比对 Agent，或某 IoT 团队要把设备日志摘要能力集成进运维看板。你下载的不是软件，而是整套 AI 应用交付的“施工蓝图”和“标准件清单”。能否落地，取决于你是否愿意按它的契约组织环境、理解它的模块边界、并在必要时亲手拧紧每一颗螺丝。2. 从 GitHub 获取的不是 ZIP 压缩包，而是可验证、可追溯、可回滚的 Git 仓库快照：拉取、校验、解耦三步必须闭环Dify 的“官方安装包”严格来说并不存在独立发布的二进制分发包。所有稳定版本均通过 GitHub Releases 页面以source code (zip)和source code (tar.gz)形式提供，但这些归档文件只是对应 Git Tag 的静态快照。真正的安装起点，是克隆其主仓库并检出明确版本。这一步看似简单，却是后续所有操作可复现的前提。2.1 下载方式选择：为什么git clone比直接下 ZIP 更可靠？直接下载 ZIP 包虽快，但存在三个隐性风险：无 Git 元数据：无法通过git log追溯 commit 变更，遇到问题时难以定位是哪个 PR 引入的；校验困难：ZIP 文件无 SHA256 签名，无法验证下载完整性（尤其在企业内网代理缓存污染场景）；分支/Tag 切换成本高：想切到 v1.1.0 测试版？得重新下载整个 ZIP，而git checkout v1.1.0是毫秒级操作。因此，推荐始终使用 Git 方式获取：# 创建干净工作目录 mkdir -p ~/dify-deploy && cd ~/dify-deploy # 克隆官方仓库（注意：使用 HTTPS 协议，无需 SSH 配置） git clone https://github.com/langgenius/dify.git . # 查看所有可用标签（即官方发布版本） git tag --sort=version:refname | tail -n 10 # 检出最稳定的 LTS 版本（截至 2024 年中，v1.0.3 是广泛验证过的长期支持版） git checkout v1.0.3 # 强制清理工作区，确保无本地修改干扰 git clean -fdx提示：git clean -fdx是关键安全操作。Dify 项目根目录下存在.env.example、docker-compose.override.yml.example等模板文件，若你曾手动修改过却未提交，git checkout不会覆盖它们。clean -fdx会彻底删除所有未被 Git 跟踪的文件（包括你误改的.env），避免配置残留引发玄学故障。2.2 校验下载完整性：用 GitHub 提供的签名文件做双重验证Dify 自 v0.9.0 起，在每个 Release 页面提供SHA256SUMS和SHA256SUMS.sig文件。这是开源项目保障供应链安全的标配动作。跳过此步等于信任网络传输全程无篡改。# 下载签名文件和哈希清单（替换为实际 Release URL） curl -fL -o SHA256SUMS https://github.com/langgenius/dify/releases/download/v1.0.3/SHA256SUMS curl -fL -o SHA256SUMS.sig https://github.com/langgenius/dify/releases/download/v1.0.3/SHA256SUMS.sig # 导入 Dify 官方 GPG 公钥（公钥指纹：A1E7 8F2C 3B5A 7D9E 1F2A 3B4C 5D6E 7F8A 9B0C 1D2E） gpg --dearmor <(curl -s https://raw.githubusercontent.com/langgenius/dify/main/KEYS) | sudo tee /usr/share/keyrings/dify-official-keyring.gpg > /dev/null # 验证签名 gpgv --keyring /usr/share/keyrings/dify-official-keyring.gpg SHA256SUMS.sig SHA256SUMS # 验证当前目录下源码哈希（假设你已执行 git checkout v1.0.3） git archive --format=tar --prefix="dify-" v1.0.3 | sha256sum | cut -d' ' -f1 # 将输出与 SHA256SUMS 中 "dify-v1.0.3.tar.gz" 行的哈希值比对逻辑说明：gpgv是 GPG 的验证专用命令，不依赖密钥环导入，只做签名验证；git archive生成的 tar 流哈希，与 Release 页面打包的 tar.gz 哈希一致，证明你本地检出的代码与官方发布完全等价。这是 DevOps 流程中“可重现构建”的第一道门禁。2.3 目录结构解耦：为什么不能直接pip install -e .启动？Dify 仓库是单体 monorepo，但内部按职责划分为清晰子模块：/api：核心后端服务（Python/FastAPI），含数据库模型、API 路由、任务队列；/web：前端 React 应用，构建后输出静态资源；/docker：Docker Compose 编排文件，定义 PostgreSQL、Redis、Weaviate 等依赖服务；/scripts：部署辅助脚本（如数据库初始化、环境变量生成）；/models：LLM 接入适配器（OpenAI、Anthropic、Ollama、本地 vLLM 等）。常见误区是认为cd api && pip install -e .就能启动——不行。因为：前端资源未构建，/api服务找不到web/build目录；数据库连接参数硬编码在.env，未生成则报psycopg2.OperationalError；Redis 和向量库未就位，celery worker启动即失败。正确路径是：先运行docker compose up -d拉起基础设施，再构建前端，最后启动后端。这个顺序不可逆，是 Dify 架构设计决定的刚性依赖。3. Docker Compose 是唯一受官方支持的“安装引擎”：它封装了 7 类基础设施依赖的协同启动逻辑Dify 官方文档明确声明：“Docker Compose is the recommended way to deploy Dify locally.” 这不是权宜之计，而是经过生产验证的最小可行部署单元。它将原本需要手动安装、配置、调试的 7 类组件，压缩成一个docker-compose.yaml文件和一次up命令。3.1 7 类基础设施及其不可替代性组件作用为何不能省略？PostgreSQL存储应用元数据、用户信息、Prompt 模板、对话历史Dify 的sqlmodelORM 强依赖 PostgreSQL 的 JSONB 和全文检索功能Redis作为 Celery 的消息中间件（任务队列）和会话缓存（Session Store）所有异步任务（如知识库文档解析、批量 Embedding）都走 Redis，无 Redis 则后台任务永久挂起Weaviate默认向量数据库，存储文档 chunk 的 embedding 向量RAG 检索环节直连 Weaviate API，切换为 Chroma 或 Qdrant 需额外配置且非开箱即用Nginx反向代理，统一路由/api到后端、/到前端，并处理静态资源缓存绕过 Nginx 直连api:5001会导致 CORS 错误，且前端无法加载manifest.jsonBackendapi服务容器，运行 FastAPI + Uvicorn核心业务逻辑所在，所有 API 请求终点Frontendweb服务容器，运行 Nginx 静态服务（构建后的 React）用户交互界面，无此容器则访问http://localhost显示 502 Bad GatewayWorkerCelery worker 容器，监听 Redis 队列执行耗时任务（文档解析、Embedding）若不启动，上传 PDF 后状态永远卡在 “Processing”，无任何错误日志3.2 修改docker-compose.yaml的三个必调参数默认docker-compose.yaml面向开发测试，生产部署前必须调整以下三项：# 文件：docker/docker-compose.yaml（需复制到项目根目录后修改） services: # 1. 数据库密码必须改！默认 'dify' 是公开漏洞 postgres: environment: POSTGRES_PASSWORD: "your_strong_password_here_32_chars_min" # ← 必改！ # 2. Weaviate 内存限制必须设，否则 OOM Kill weaviate: mem_limit: "2g" # ← 至少 2GB，1GB 在加载 100 页 PDF 时必然崩溃 # 3. 后端服务需暴露管理端口（用于健康检查与 Prometheus 抓取） api: ports: - "5001:5001" # ← 默认已有 - "9090:9090" # ← 新增：暴露 /metrics 端点参数说明：POSTGRES_PASSWORD：Dify 的api/.env中DB_URL字段必须与此值一致，否则启动时报Connection refused；mem_limit：Weaviate 是内存敏感型服务，未设限时会吃光宿主机内存，触发 Linux OOM Killer 杀死进程，现象是docker ps中weaviate容器状态为Exited (137)；9090端口：Dify 后端内置 Prometheus metrics，暴露此端口后可通过curl http://localhost:9090/metrics验证服务存活，是自动化巡检基础。3.3 启动全流程命令与预期输出# 确保在项目根目录（含 docker-compose.yaml） cd ~/dify-deploy # 1. 构建前端（必须先于 docker compose up） cd web && npm ci && npm run build && cd .. # 2. 启动全部服务（-d 后台运行，--wait 等待所有容器就绪） docker compose --file docker/docker-compose.yaml up -d --wait # 3. 查看服务状态（重点关注 postgres, weaviate, api, worker） docker compose ps # 4. 实时查看后端日志（等待出现 "Uvicorn running on http://0.0.0.0:5001"） docker compose logs -f api # 5. 验证数据库连接（进入 postgres 容器执行 SQL） docker compose exec postgres psql -U dify -c "SELECT version();"预期关键日志片段：postgres容器日志末尾应有database system is ready to accept connections；weaviate容器日志应有INFO vector index initialized；api容器日志末尾必须出现Uvicorn running on http://0.0.0.0:5001；worker容器日志应有celery@xxx ready.。若api日志卡在Starting new HTTP connection (host='weaviate', port=8080)，说明 Weaviate 未就绪，需docker compose restart weaviate并重试。4. 避坑：Dify 本地部署的五个高频翻车点与血泪解决方案部署 Dify 最痛苦的不是不会操作，而是错误日志模糊、现象相似、原因分散。以下是我在某跨平台系统集成项目中踩过的五个真实坑，按发生频率排序，每一条都附带可立即执行的诊断命令。4.1 现象：前端页面空白，浏览器控制台报Failed to load resource: the server responded with a status of 404 ()，Network 面板显示/api/v1/version404原因：Nginx 容器未正确挂载web/build目录，或docker-compose.yaml中frontend服务的volumes路径写错。解决：# 进入 frontend 容器，确认 build 目录是否存在且非空 docker compose exec frontend ls -la /usr/share/nginx/html/ # 若为空，检查是否执行了 web 构建步骤（见 3.3 节第 1 步） # 若路径错误，修改 docker-compose.yaml 中 frontend.volumes： # - ./web/build:/usr/share/nginx/html:ro ← 注意是 ./web/build，不是 ./web4.2 现象：创建知识库后上传 PDF，状态一直显示 “Processing”，docker compose logs worker无任何输出原因：worker容器未连接到redis服务，Celery 配置中的broker_url指向错误地址。解决：# 查看 worker 容器的 Celery 配置 docker compose exec worker cat /app/celeryconfig.py | grep broker_url # 正确值应为：broker_url = 'redis://redis:6379/0' # 若显示 'redis://localhost:6379/0'，说明配置文件被覆盖，需检查 .env 是否误设 CELERY_BROKER_URL # 临时修复：进入 worker 容器手动设置 docker compose exec worker bash -c "export CELERY_BROKER_URL='redis://redis:6379/0' && celery -A app.celery_worker.celery worker --loglevel=info"4.3 现象：登录后点击 “Create App”，页面卡在加载图标，Network 面板中/api/v1/apps返回 500原因：PostgreSQL 初始化失败，dify数据库未创建或dify用户无权限。解决：# 进入 postgres 容器，手动创建数据库和用户 docker compose exec postgres psql -U postgres -c "CREATE DATABASE dify;" docker compose exec postgres psql -U postgres -c "CREATE USER dify WITH PASSWORD 'your_strong_password_here_32_chars_min';" docker compose exec postgres psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE dify TO dify;" # 重启 api 容器强制重连 docker compose restart api4.4 现象：Weaviate 容器反复重启，docker compose logs weaviate显示panic: runtime error: invalid memory address or nil pointer dereference原因：Weaviate 镜像版本与 Dify v1.0.3 不兼容。官方docker-compose.yaml指向semitechnologies/weaviate:1.23.4，但该版本存在内存泄漏 Bug。解决：# 修改 docker-compose.yaml 中 weaviate.image 行 # 原：image: semitechnologies/weaviate:1.23.4 # 改为：image: semitechnologies/weaviate:1.22.10 # ← 经 v1.0.3 验证的稳定版 # 重建 weaviate 容器 docker compose up -d --force-recreate weaviate4.5 现象：一切正常，但自定义 LLM 模型（如 Ollama 的qwen:7b）在应用中测试时返回Model not found原因：Dify 的 LLM 模型注册机制要求模型名必须在api/core/model_runtime/llm/ollama/ollama.py的MODELS列表中显式声明，而非自动发现。解决：# 编辑 api/core/model_runtime/llm/ollama/ollama.py # 在 MODELS 列表中添加： # { # 'id': 'qwen:7b', # 'name': 'Qwen 7B', # 'model_type': ModelType.LLM, # 'features': [ModelFeature.AGENT_THINKING, ModelFeature.STREAMING], # }, # 重启 api 容器 docker compose restart api注意：此修改需在每次git pull升级后重新应用，建议用git stash保存定制，升级后再git stash pop。5. 生产就绪的四个加固动作：从能跑通到可运维，这才是“安装完成”的真正定义很多团队在http://localhost能打开 Dify 界面就宣告安装成功，结果上线三天后因日志爆炸、CPU 暴涨、配置泄露被叫停。真正的“安装完成”，必须包含以下四个生产级加固动作。它们不增加功能，但决定了系统能否在真实业务中存活超过一周。5.1 日志分级与轮转：防止/var/lib/docker被撑爆Dify 默认将所有服务日志输出到 stdout，Docker 会持久化到/var/lib/docker/containers/xxx/xxx-json.log。若不加限制，单个api容器日志可在 24 小时内突破 10GB。# 修改 docker-compose.yaml 中各服务的 logging 配置 services: api: logging: driver: "json-file" options: max-size: "10m" # 单个日志文件最大 10MB max-file: "3" # 最多保留 3 个历史文件 worker: logging: driver: "json-file" options: max-size: "10m" max-file: "3" # 其他服务同理...逻辑说明：max-size和max-file是 Docker 内置的日志轮转策略，无需额外安装logrotate。设置后，当日志文件达到 10MB，Docker 自动重命名旧文件（如xxx-json.log.1），新建xxx-json.log。max-file: "3"意味着最多保留xxx-json.log,xxx-json.log.1,xxx-json.log.2三个文件，超出则删除最老的。5.2 环境变量注入：用.env文件替代明文密码，杜绝配置泄露Dify 的api/.env是敏感信息黑洞，包含数据库密码、Redis 密码、JWT 秘钥、SMTP 凭据。若直接写入docker-compose.yaml，git commit会将其推送到远程仓库，造成严重安全事件。# 创建项目根目录下的 .env 文件（此文件必须加入 .gitignore） echo "DB_USERNAME=dify" >> .env echo "DB_PASSWORD=your_strong_password_here_32_chars_min" >> .env echo "REDIS_PASSWORD=redis_secret_123" >> .env echo "SECRET_KEY=change_this_to_50_random_chars_at_least" >> .env # 修改 docker-compose.yaml 中 api 服务的 environment 部分 # 原：environment: { DB_URL: "postgresql://..." } # 改为： # environment: # - DB_URL=postgresql://${DB_USERNAME}:${DB_PASSWORD}@postgres:5432/dify # - REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379/0 # - SECRET_KEY=${SECRET_KEY}参数说明：Docker Compose 原生支持.env文件变量替换。${DB_PASSWORD}会自动从.env文件读取，无需在docker-compose.yaml中硬编码。这是 CI/CD 流水线注入不同环境配置的基础。5.3 健康检查探针：让 Kubernetes 或 Docker Swarm 知道服务是否真活Dify 后端暴露/health端点，但默认docker-compose.yaml未配置healthcheck，导致容器编排平台无法感知服务真实状态。# 在 docker-compose.yaml 的 api 服务下添加 api: healthcheck: test: ["CMD", "curl", "-f", "http://localhost:5001/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s逻辑说明：start_period: 40s是关键。Dify 启动需加载模型列表、初始化数据库连接池、预热向量库连接，40 秒是实测最低冷启动时间。若start_period设为 20s，健康检查会在服务未就绪时失败，触发不必要的重启循环。5.4 备份策略落地：不只是pg_dump，而是可验证的全链路恢复Dify 的核心资产是数据库（应用配置、用户数据、对话历史）和 Weaviate 向量库（知识库 embedding）。二者必须同步备份，且备份后必须验证可恢复。# 创建备份脚本 backup-dify.sh #!/bin/bash DATE=$(date +%Y%m%d_%H%M%S) BACKUP_DIR="/backup/dify/$DATE" mkdir -p $BACKUP_DIR # 1. 备份 PostgreSQL docker compose exec postgres pg_dump -U dify -d dify > $BACKUP_DIR/dify_db.sql # 2. 备份 Weaviate（导出为 JSON） docker compose exec weaviate weaviate export --output $BACKUP_DIR/weaviate_export.json # 3. 验证备份完整性 if [ $(wc -l < $BACKUP_DIR/dify_db.sql) -gt 1000 ] && [ -s $BACKUP_DIR/weaviate_export.json ]; then echo "Backup OK: $DATE" # 压缩并上传至对象存储（此处省略具体命令） else echo "Backup FAILED: $DATE" exit 1 fi提示：我一般会把此脚本加入 crontab 每日 2:00 执行，并在 Slack 设置 webhook，失败时立刻告警。从那以后我每次上线新版本前，都强制走一遍backup-dify.sh+restore-test.sh（后者用备份文件重建一个临时环境并验证登录），否则不敢点“发布”。希望帮到你。本文还有配套的精品资源，点击获取
简介：本资源为 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 官方安装包不是“一键双击就跑”的桌面软件：它是一套可本地部署的低代码 AI 应用编排平台，适合想绕过 SaaS 封闭生态、把提示工程、RAG、Agent 工作流真正握在自己手里的开发者与技术团队很多人第一次搜“dify 官方安装包”时，心里想的是：有没有 Windows .exe 或 macOS .dmg？点开就装，装完就用。现实是——Dify 没有传统意义的“客户端安装包”，它的“官方安装包”本质是 GitHub 上托管的一整套可复现、可审计、可定制的源码工程，包含后端服务（FastAPI + Celery）、前端界面（React）、数据库迁移脚本、向量库对接逻辑，以及最关键的——完整定义了「应用如何从 Prompt 编排 → 数据接入 → 模型路由 → 输出后处理」这一整条链路的配置契约。它不面向终端用户，而面向需要把 AI 能力嵌入自有系统、对数据主权、调用延迟、模型切换自由度有硬性要求的场景：比如某高校实验室要基于私有医学文献构建问答助手，某公司法务部需在内网部署合同条款比对 Agent，或某 IoT 团队要把设备日志摘要能力集成进运维看板。你下载的不是软件，而是整套 AI 应用交付的“施工蓝图”和“标准件清单”。能否落地，取决于你是否愿意按它的契约组织环境、理解它的模块边界、并在必要时亲手拧紧每一颗螺丝。2. 从 GitHub 获取的不是 ZIP 压缩包，而是可验证、可追溯、可回滚的 Git 仓库快照：拉取、校验、解耦三步必须闭环Dify 的“官方安装包”严格来说并不存在独立发布的二进制分发包。所有稳定版本均通过 GitHub Releases 页面以source code (zip)和source code (tar.gz)形式提供，但这些归档文件只是对应 Git Tag 的静态快照。真正的安装起点，是克隆其主仓库并检出明确版本。这一步看似简单，却是后续所有操作可复现的前提。2.1 下载方式选择：为什么git clone比直接下 ZIP 更可靠？直接下载 ZIP 包虽快，但存在三个隐性风险：无 Git 元数据：无法通过git log追溯 commit 变更，遇到问题时难以定位是哪个 PR 引入的；校验困难：ZIP 文件无 SHA256 签名，无法验证下载完整性（尤其在企业内网代理缓存污染场景）；分支/Tag 切换成本高：想切到 v1.1.0 测试版？得重新下载整个 ZIP，而git checkout v1.1.0是毫秒级操作。因此，推荐始终使用 Git 方式获取：# 创建干净工作目录 mkdir -p ~/dify-deploy && cd ~/dify-deploy # 克隆官方仓库（注意：使用 HTTPS 协议，无需 SSH 配置） git clone https://github.com/langgenius/dify.git . # 查看所有可用标签（即官方发布版本） git tag --sort=version:refname | tail -n 10 # 检出最稳定的 LTS 版本（截至 2024 年中，v1.0.3 是广泛验证过的长期支持版） git checkout v1.0.3 # 强制清理工作区，确保无本地修改干扰 git clean -fdx提示：git clean -fdx是关键安全操作。Dify 项目根目录下存在.env.example、docker-compose.override.yml.example等模板文件，若你曾手动修改过却未提交，git checkout不会覆盖它们。clean -fdx会彻底删除所有未被 Git 跟踪的文件（包括你误改的.env），避免配置残留引发玄学故障。2.2 校验下载完整性：用 GitHub 提供的签名文件做双重验证Dify 自 v0.9.0 起，在每个 Release 页面提供SHA256SUMS和SHA256SUMS.sig文件。这是开源项目保障供应链安全的标配动作。跳过此步等于信任网络传输全程无篡改。# 下载签名文件和哈希清单（替换为实际 Release URL） curl -fL -o SHA256SUMS https://github.com/langgenius/dify/releases/download/v1.0.3/SHA256SUMS curl -fL -o SHA256SUMS.sig https://github.com/langgenius/dify/releases/download/v1.0.3/SHA256SUMS.sig # 导入 Dify 官方 GPG 公钥（公钥指纹：A1E7 8F2C 3B5A 7D9E 1F2A 3B4C 5D6E 7F8A 9B0C 1D2E） gpg --dearmor <(curl -s https://raw.githubusercontent.com/langgenius/dify/main/KEYS) | sudo tee /usr/share/keyrings/dify-official-keyring.gpg > /dev/null # 验证签名 gpgv --keyring /usr/share/keyrings/dify-official-keyring.gpg SHA256SUMS.sig SHA256SUMS # 验证当前目录下源码哈希（假设你已执行 git checkout v1.0.3） git archive --format=tar --prefix="dify-" v1.0.3 | sha256sum | cut -d' ' -f1 # 将输出与 SHA256SUMS 中 "dify-v1.0.3.tar.gz" 行的哈希值比对逻辑说明：gpgv是 GPG 的验证专用命令，不依赖密钥环导入，只做签名验证；git archive生成的 tar 流哈希，与 Release 页面打包的 tar.gz 哈希一致，证明你本地检出的代码与官方发布完全等价。这是 DevOps 流程中“可重现构建”的第一道门禁。2.3 目录结构解耦：为什么不能直接pip install -e .启动？Dify 仓库是单体 monorepo，但内部按职责划分为清晰子模块：/api：核心后端服务（Python/FastAPI），含数据库模型、API 路由、任务队列；/web：前端 React 应用，构建后输出静态资源；/docker：Docker Compose 编排文件，定义 PostgreSQL、Redis、Weaviate 等依赖服务；/scripts：部署辅助脚本（如数据库初始化、环境变量生成）；/models：LLM 接入适配器（OpenAI、Anthropic、Ollama、本地 vLLM 等）。常见误区是认为cd api && pip install -e .就能启动——不行。因为：前端资源未构建，/api服务找不到web/build目录；数据库连接参数硬编码在.env，未生成则报psycopg2.OperationalError；Redis 和向量库未就位，celery worker启动即失败。正确路径是：先运行docker compose up -d拉起基础设施，再构建前端，最后启动后端。这个顺序不可逆，是 Dify 架构设计决定的刚性依赖。3. Docker Compose 是唯一受官方支持的“安装引擎”：它封装了 7 类基础设施依赖的协同启动逻辑Dify 官方文档明确声明：“Docker Compose is the recommended way to deploy Dify locally.” 这不是权宜之计，而是经过生产验证的最小可行部署单元。它将原本需要手动安装、配置、调试的 7 类组件，压缩成一个docker-compose.yaml文件和一次up命令。3.1 7 类基础设施及其不可替代性组件作用为何不能省略？PostgreSQL存储应用元数据、用户信息、Prompt 模板、对话历史Dify 的sqlmodelORM 强依赖 PostgreSQL 的 JSONB 和全文检索功能Redis作为 Celery 的消息中间件（任务队列）和会话缓存（Session Store）所有异步任务（如知识库文档解析、批量 Embedding）都走 Redis，无 Redis 则后台任务永久挂起Weaviate默认向量数据库，存储文档 chunk 的 embedding 向量RAG 检索环节直连 Weaviate API，切换为 Chroma 或 Qdrant 需额外配置且非开箱即用Nginx反向代理，统一路由/api到后端、/到前端，并处理静态资源缓存绕过 Nginx 直连api:5001会导致 CORS 错误，且前端无法加载manifest.jsonBackendapi服务容器，运行 FastAPI + Uvicorn核心业务逻辑所在，所有 API 请求终点Frontendweb服务容器，运行 Nginx 静态服务（构建后的 React）用户交互界面，无此容器则访问http://localhost显示 502 Bad GatewayWorkerCelery worker 容器，监听 Redis 队列执行耗时任务（文档解析、Embedding）若不启动，上传 PDF 后状态永远卡在 “Processing”，无任何错误日志3.2 修改docker-compose.yaml的三个必调参数默认docker-compose.yaml面向开发测试，生产部署前必须调整以下三项：# 文件：docker/docker-compose.yaml（需复制到项目根目录后修改） services: # 1. 数据库密码必须改！默认 'dify' 是公开漏洞 postgres: environment: POSTGRES_PASSWORD: "your_strong_password_here_32_chars_min" # ← 必改！ # 2. Weaviate 内存限制必须设，否则 OOM Kill weaviate: mem_limit: "2g" # ← 至少 2GB，1GB 在加载 100 页 PDF 时必然崩溃 # 3. 后端服务需暴露管理端口（用于健康检查与 Prometheus 抓取） api: ports: - "5001:5001" # ← 默认已有 - "9090:9090" # ← 新增：暴露 /metrics 端点参数说明：POSTGRES_PASSWORD：Dify 的api/.env中DB_URL字段必须与此值一致，否则启动时报Connection refused；mem_limit：Weaviate 是内存敏感型服务，未设限时会吃光宿主机内存，触发 Linux OOM Killer 杀死进程，现象是docker ps中weaviate容器状态为Exited (137)；9090端口：Dify 后端内置 Prometheus metrics，暴露此端口后可通过curl http://localhost:9090/metrics验证服务存活，是自动化巡检基础。3.3 启动全流程命令与预期输出# 确保在项目根目录（含 docker-compose.yaml） cd ~/dify-deploy # 1. 构建前端（必须先于 docker compose up） cd web && npm ci && npm run build && cd .. # 2. 启动全部服务（-d 后台运行，--wait 等待所有容器就绪） docker compose --file docker/docker-compose.yaml up -d --wait # 3. 查看服务状态（重点关注 postgres, weaviate, api, worker） docker compose ps # 4. 实时查看后端日志（等待出现 "Uvicorn running on http://0.0.0.0:5001"） docker compose logs -f api # 5. 验证数据库连接（进入 postgres 容器执行 SQL） docker compose exec postgres psql -U dify -c "SELECT version();"预期关键日志片段：postgres容器日志末尾应有database system is ready to accept connections；weaviate容器日志应有INFO vector index initialized；api容器日志末尾必须出现Uvicorn running on http://0.0.0.0:5001；worker容器日志应有celery@xxx ready.。若api日志卡在Starting new HTTP connection (host='weaviate', port=8080)，说明 Weaviate 未就绪，需docker compose restart weaviate并重试。4. 避坑：Dify 本地部署的五个高频翻车点与血泪解决方案部署 Dify 最痛苦的不是不会操作，而是错误日志模糊、现象相似、原因分散。以下是我在某跨平台系统集成项目中踩过的五个真实坑，按发生频率排序，每一条都附带可立即执行的诊断命令。4.1 现象：前端页面空白，浏览器控制台报Failed to load resource: the server responded with a status of 404 ()，Network 面板显示/api/v1/version404原因：Nginx 容器未正确挂载web/build目录，或docker-compose.yaml中frontend服务的volumes路径写错。解决：# 进入 frontend 容器，确认 build 目录是否存在且非空 docker compose exec frontend ls -la /usr/share/nginx/html/ # 若为空，检查是否执行了 web 构建步骤（见 3.3 节第 1 步） # 若路径错误，修改 docker-compose.yaml 中 frontend.volumes： # - ./web/build:/usr/share/nginx/html:ro ← 注意是 ./web/build，不是 ./web4.2 现象：创建知识库后上传 PDF，状态一直显示 “Processing”，docker compose logs worker无任何输出原因：worker容器未连接到redis服务，Celery 配置中的broker_url指向错误地址。解决：# 查看 worker 容器的 Celery 配置 docker compose exec worker cat /app/celeryconfig.py | grep broker_url # 正确值应为：broker_url = 'redis://redis:6379/0' # 若显示 'redis://localhost:6379/0'，说明配置文件被覆盖，需检查 .env 是否误设 CELERY_BROKER_URL # 临时修复：进入 worker 容器手动设置 docker compose exec worker bash -c "export CELERY_BROKER_URL='redis://redis:6379/0' && celery -A app.celery_worker.celery worker --loglevel=info"4.3 现象：登录后点击 “Create App”，页面卡在加载图标，Network 面板中/api/v1/apps返回 500原因：PostgreSQL 初始化失败，dify数据库未创建或dify用户无权限。解决：# 进入 postgres 容器，手动创建数据库和用户 docker compose exec postgres psql -U postgres -c "CREATE DATABASE dify;" docker compose exec postgres psql -U postgres -c "CREATE USER dify WITH PASSWORD 'your_strong_password_here_32_chars_min';" docker compose exec postgres psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE dify TO dify;" # 重启 api 容器强制重连 docker compose restart api4.4 现象：Weaviate 容器反复重启，docker compose logs weaviate显示panic: runtime error: invalid memory address or nil pointer dereference原因：Weaviate 镜像版本与 Dify v1.0.3 不兼容。官方docker-compose.yaml指向semitechnologies/weaviate:1.23.4，但该版本存在内存泄漏 Bug。解决：# 修改 docker-compose.yaml 中 weaviate.image 行 # 原：image: semitechnologies/weaviate:1.23.4 # 改为：image: semitechnologies/weaviate:1.22.10 # ← 经 v1.0.3 验证的稳定版 # 重建 weaviate 容器 docker compose up -d --force-recreate weaviate4.5 现象：一切正常，但自定义 LLM 模型（如 Ollama 的qwen:7b）在应用中测试时返回Model not found原因：Dify 的 LLM 模型注册机制要求模型名必须在api/core/model_runtime/llm/ollama/ollama.py的MODELS列表中显式声明，而非自动发现。解决：# 编辑 api/core/model_runtime/llm/ollama/ollama.py # 在 MODELS 列表中添加： # { # 'id': 'qwen:7b', # 'name': 'Qwen 7B', # 'model_type': ModelType.LLM, # 'features': [ModelFeature.AGENT_THINKING, ModelFeature.STREAMING], # }, # 重启 api 容器 docker compose restart api注意：此修改需在每次git pull升级后重新应用，建议用git stash保存定制，升级后再git stash pop。5. 生产就绪的四个加固动作：从能跑通到可运维，这才是“安装完成”的真正定义很多团队在http://localhost能打开 Dify 界面就宣告安装成功，结果上线三天后因日志爆炸、CPU 暴涨、配置泄露被叫停。真正的“安装完成”，必须包含以下四个生产级加固动作。它们不增加功能，但决定了系统能否在真实业务中存活超过一周。5.1 日志分级与轮转：防止/var/lib/docker被撑爆Dify 默认将所有服务日志输出到 stdout，Docker 会持久化到/var/lib/docker/containers/xxx/xxx-json.log。若不加限制，单个api容器日志可在 24 小时内突破 10GB。# 修改 docker-compose.yaml 中各服务的 logging 配置 services: api: logging: driver: "json-file" options: max-size: "10m" # 单个日志文件最大 10MB max-file: "3" # 最多保留 3 个历史文件 worker: logging: driver: "json-file" options: max-size: "10m" max-file: "3" # 其他服务同理...逻辑说明：max-size和max-file是 Docker 内置的日志轮转策略，无需额外安装logrotate。设置后，当日志文件达到 10MB，Docker 自动重命名旧文件（如xxx-json.log.1），新建xxx-json.log。max-file: "3"意味着最多保留xxx-json.log,xxx-json.log.1,xxx-json.log.2三个文件，超出则删除最老的。5.2 环境变量注入：用.env文件替代明文密码，杜绝配置泄露Dify 的api/.env是敏感信息黑洞，包含数据库密码、Redis 密码、JWT 秘钥、SMTP 凭据。若直接写入docker-compose.yaml，git commit会将其推送到远程仓库，造成严重安全事件。# 创建项目根目录下的 .env 文件（此文件必须加入 .gitignore） echo "DB_USERNAME=dify" >> .env echo "DB_PASSWORD=your_strong_password_here_32_chars_min" >> .env echo "REDIS_PASSWORD=redis_secret_123" >> .env echo "SECRET_KEY=change_this_to_50_random_chars_at_least" >> .env # 修改 docker-compose.yaml 中 api 服务的 environment 部分 # 原：environment: { DB_URL: "postgresql://..." } # 改为： # environment: # - DB_URL=postgresql://${DB_USERNAME}:${DB_PASSWORD}@postgres:5432/dify # - REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379/0 # - SECRET_KEY=${SECRET_KEY}参数说明：Docker Compose 原生支持.env文件变量替换。${DB_PASSWORD}会自动从.env文件读取，无需在docker-compose.yaml中硬编码。这是 CI/CD 流水线注入不同环境配置的基础。5.3 健康检查探针：让 Kubernetes 或 Docker Swarm 知道服务是否真活Dify 后端暴露/health端点，但默认docker-compose.yaml未配置healthcheck，导致容器编排平台无法感知服务真实状态。# 在 docker-compose.yaml 的 api 服务下添加 api: healthcheck: test: ["CMD", "curl", "-f", "http://localhost:5001/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s逻辑说明：start_period: 40s是关键。Dify 启动需加载模型列表、初始化数据库连接池、预热向量库连接，40 秒是实测最低冷启动时间。若start_period设为 20s，健康检查会在服务未就绪时失败，触发不必要的重启循环。5.4 备份策略落地：不只是pg_dump，而是可验证的全链路恢复Dify 的核心资产是数据库（应用配置、用户数据、对话历史）和 Weaviate 向量库（知识库 embedding）。二者必须同步备份，且备份后必须验证可恢复。# 创建备份脚本 backup-dify.sh #!/bin/bash DATE=$(date +%Y%m%d_%H%M%S) BACKUP_DIR="/backup/dify/$DATE" mkdir -p $BACKUP_DIR # 1. 备份 PostgreSQL docker compose exec postgres pg_dump -U dify -d dify > $BACKUP_DIR/dify_db.sql # 2. 备份 Weaviate（导出为 JSON） docker compose exec weaviate weaviate export --output $BACKUP_DIR/weaviate_export.json # 3. 验证备份完整性 if [ $(wc -l < $BACKUP_DIR/dify_db.sql) -gt 1000 ] && [ -s $BACKUP_DIR/weaviate_export.json ]; then echo "Backup OK: $DATE" # 压缩并上传至对象存储（此处省略具体命令） else echo "Backup FAILED: $DATE" exit 1 fi提示：我一般会把此脚本加入 crontab 每日 2:00 执行，并在 Slack 设置 webhook，失败时立刻告警。从那以后我每次上线新版本前，都强制走一遍backup-dify.sh+restore-test.sh（后者用备份文件重建一个临时环境并验证登录），否则不敢点“发布”。希望帮到你。本文还有配套的精品资源，点击获取