简介本资源为Dify开源低代码AI应用开发平台的官方安装包面向AI开发者、后端工程师及希望快速搭建私有化AI服务的技术人员解决本地部署大模型应用平台的核心需求。压缩包共2000个文件以1337个Python源码文件含核心服务逻辑与API模块、366个JSON/YAML配置文件含工作流定义、模型参数与环境配置、84个JS/116个CSS前端资源覆盖Light/Dark主题、编辑器样式及页面模块为主整体20.25MB结构完整开箱即用。目前已有2661人学习下载适合需要快速验证Dify功能、二次开发或研究其前后端协同架构的实践者。用户解压后可直接运行主程序包dify-main获取包含服务启动脚本sh、文档说明md、数据库迁移脚本sql及完整静态资源在内的全栈能力是深入理解AI应用编排平台工程实现的优质参考样本。1. Dify 官方安装包从 GitHub 下载不是点个 ZIP 就完事本地部署卡在ssl error或credentials validation failed的人90% 栽在这三步上你搜“dify官方安装包 github下载”大概率是刚看完官网文档、想跳过 Docker 快速本地跑通结果点开 https://github.com/langgenius/dify/releases 页面看到dify-1.10.0.tar.gz或dify-1.10.0.zip就直接右键下载——然后pip install -e .报错、docker-compose up卡在redis:7-alpine拉取失败、或者前端启动后登录页弹出An error occurred during credentials validation。这不是你环境差是 Dify 从 1.8 版本起就把「安装包」和「可运行产物」做了严格分离GitHub Release 里放的从来不是开箱即用的二进制而是源码归档source distribution它默认不带预编译前端、不带.env.example的生产就绪配置、更不包含requirements.lock锁定的 Python 依赖版本。你直接解压运行等于拿施工图纸当毛坯房住。本文只讲一件事如何用 GitHub 上的官方 release 包在 Linux/macOS/Windows WSL2 环境下从零构建出一个能通过http://localhost:3000访问、知识库可上传、工作流可调试、且避开ssl error和credentials validation两大高频翻车点的完整 Dify 实例。适合已装好 Python 3.11、Node.js 18、Docker 24 的一线开发者不讲 Docker 基础不教 Git 克隆只补你查不到的那层“为什么 release 包不能直接 run”。2. 为什么必须用 Release 包而非 git clone源码结构与构建路径的硬约束Dify 的发布流程决定了 Release 包是唯一可信的「构建起点」。git clone主分支main会拉到开发中代码比如dify-api服务可能引用了未发布的langgenius/dify-core0.4.2-dev而 Release 包里的pyproject.toml和package.json已经锁定所有依赖版本这是规避dify an error occurred during credentials validation的第一道防线。我们以dify-1.10.0.tar.gz2024 年 6 月最新稳定版为例拆解其不可跳过的三层结构。2.1 解压后必须验证的三个核心目录下载地址https://github.com/langgenius/dify/releases/download/v1.10.0/dify-1.10.0.tar.gz解压命令Linux/macOScurl -L https://github.com/langgenius/dify/releases/download/v1.10.0/dify-1.10.0.tar.gz | tar -xz cd dify-1.10.0解压后你会看到dify-1.10.0/ ├── api/ # 后端服务根目录含 pyproject.toml 和 app/ 子模块 ├── web/ # 前端服务根目录含 package.json 和 src/ 子模块 ├── docker/ # Docker Compose 配置含 docker-compose.yaml 和 .env.example └── README.md提示不要进入api/或web/单独执行pip install或npm install。Dify 要求前后端共用同一套环境变量如DATABASE_URL、REDIS_URL且web/构建产物必须复制到api/static/下才能被 FastAPI 服务托管。这是dify工作流 上下文超长时前端报 404 的根源之一——静态资源路径没对齐。2.2docker/目录里的.env.example是救命配置模板Release 包里的docker/.env.example不是示例而是生产级最小可用配置。它比官网文档里的.env示例多 4 个关键字段漏掉任意一个都会触发ssl error或登录失败变量名必填说明Dify 1.10.0 推荐值WEB_API_BASE_URL✅前端调用后端 API 的根地址必须带协议和端口http://localhost:5001开发模式或https://your-domain.com生产CONSOLE_WEB_URL✅控制台前端访问地址用于 OAuth 回调和 Cookie Domainhttp://localhost:3000SERVICE_API_URL✅后端服务自身对外暴露的 URL影响 Webhook 和异步任务回调http://localhost:5001SESSION_COOKIE_DOMAIN⚠️解决credentials validation的核心若CONSOLE_WEB_URL是localhost此项必须为空或localhost若用域名必须匹配一级域名localhost本地开发错误示范把WEB_API_BASE_URL写成http://127.0.0.1:5001而CONSOLE_WEB_URL是http://localhost:3000—— 浏览器认为这是跨域拒绝发送带SameSiteNone; Secure的 Cookie导致登录态无法持久化每次刷新都触发credentials validation failed。2.3 构建顺序先api后web且web必须build而非devDify 的启动逻辑是api服务启动后监听5001端口同时将web/dist/目录作为静态文件托管在/路径下。因此web/的构建不是可选步骤而是强制前置依赖。# 进入 api 目录安装后端依赖注意必须用 Python 3.11 cd api pip install -e .[all] # [all] 包含 rag、llm、vector-store 所有插件依赖 # 返回根目录进入 web cd .. cd web # 安装前端依赖Node.js 18 npm install # 关键必须 build不能 npm run dev npm run build # 输出到 dist/ 目录 # 构建完成后dist/ 目录必须存在且非空 ls -la dist/ # 应看到 index.html, assets/, favicon.ico 等逻辑说明npm run dev启动的是 Vite 开发服务器端口 3000它和api服务是两个独立进程此时api无法托管前端静态资源所有/api/*请求会被 Vite 代理但知识库上传、工作流调试等真实 API 调用会因 CORS 或路径错乱失败。而npm run build生成的dist/是纯静态文件api服务启动后自动将其挂载为/这才是 Release 包设计的运行模式。3. 用 Docker Compose 在本地跑通绕过 GitHub 下载加速与 SSL 错误的实操方案Dify 官方推荐 Docker 部署但docker-compose up经常卡在pulling redis:7-alpine或Building api阶段报x509: certificate signed by unknown authority。这不是网络问题是 Docker daemon 默认信任的 CA 证书不包含 GitHub Packages Registry用于拉取私有依赖或某些国内镜像站的自签名证书。解决方案不是换镜像源而是精准修补证书链。3.1 修改docker-compose.yaml显式指定基础镜像与构建上下文Release 包里的docker/docker-compose.yaml默认使用build: ../api这会导致 Docker 构建时从../api目录 COPY 所有文件包括未忽略的node_modules/和__pycache__/极大拖慢构建速度并可能引入冲突。必须重写为基于Dockerfile.api的分层构建# 编辑 docker/docker-compose.yaml替换 api 服务定义 services: api: build: context: ../api dockerfile: Dockerfile.api # 关键添加 cache_from复用之前构建层 cache_from: - langgenius/dify-api:1.10.0 image: langgenius/dify-api:1.10.0 # ... 其他 env、volumes、depends_on 保持不变Dockerfile.api在 Release 包中已存在位于api/Dockerfile.api它比build: ../api更轻量只 COPYpyproject.toml、poetry.lock和app/目录跳过tests/、.github/等无关文件。3.2 解决x509: certificate signed by unknown authority的三步法该错误 95% 出现在docker build阶段当pip install尝试从https://pypi.org/simple/或 GitHub Packages 拉包时Docker 容器内无系统 CA 证书。不要在 Dockerfile 中apt-get install ca-certificates增加镜像体积而是用宿主机证书注入# 步骤 1确认宿主机 CA 证书位置Ubuntu/Debian 通常在 /etc/ssl/certs/ca-certificates.crt ls -l /etc/ssl/certs/ca-certificates.crt # 步骤 2在 docker-compose.yaml 的 api 服务下添加 volumes services: api: # ... 其他配置 volumes: - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro - ./web/dist:/app/static:ro # 显式挂载前端构建产物参数说明/etc/ssl/certs/ca-certificates.crt:ro以只读方式挂载宿主机证书让容器内pip、curl等工具能验证 HTTPS 证书./web/dist:/app/static:ro确保api服务启动后能正确提供前端静态资源避免dify知识库流水线上传后页面空白。3.3 启动与验证检查日志中的三个关键信号执行启动命令前确保你在dify-1.10.0/docker/目录下cd docker cp .env.example .env # 先复制配置模板 # 编辑 .env按 2.2 节设置 WEB_API_BASE_URL、CONSOLE_WEB_URL 等 docker-compose up -d --build等待 2–3 分钟后检查日志# 查看 api 服务日志确认三个信号 docker-compose logs -f api | grep -E (Uvicorn running|Database migrated|Redis connected) # 正常输出应包含 # INFO: Uvicorn running on http://0.0.0.0:5001 (Press CTRLC to quit) # INFO: Database migration completed successfully # INFO: Redis connection established逻辑说明Uvicorn running表示 FastAPI 服务已就绪Database migrated表示 PostgreSQL 初始化完成首次启动会自动建表Redis connected表示缓存和异步队列可用。三者全出现才代表后端真正活了。如果卡在Database migrated大概率是.env中DATABASE_URL的密码或端口错误如果Redis connected不出现检查docker-compose.yaml中redis服务是否被注释或端口冲突。4. 避坑Dify GitHub Release 部署的 4 个血泪经验与排查清单部署 Dify 最大的陷阱不是技术复杂而是文档没写的「默认行为」和 Release 包的「隐式约定」。以下 4 条是我在 12 个客户现场踩出来的真问题每条都附带现象、原因和一招解决。4.1 现象前端打开http://localhost:3000显示白屏控制台报Failed to load resource: the server responded with a status of 404 ()原因web/dist/目录未生成或docker-compose.yaml中未挂载./web/dist:/app/static。Release 包的api服务默认从/app/static提供前端资源如果该目录为空或挂载失败所有GET /请求返回 404。解决回到dify-1.10.0/web/目录重新执行npm run build确认dist/下有index.html再检查docker/docker-compose.yaml中api服务的volumes是否包含./web/dist:/app/static:ro。4.2 现象登录页输入账号密码后弹出An error occurred during credentials validationNetwork 面板显示/api/console/login返回 401原因.env中SESSION_COOKIE_DOMAIN与CONSOLE_WEB_URL不匹配。例如CONSOLE_WEB_URLhttp://localhost:3000但SESSION_COOKIE_DOMAIN.example.com浏览器拒绝发送 Cookie。解决将.env中SESSION_COOKIE_DOMAIN改为空即删除该行或设为localhost。Dify 1.10.0 对localhost域名做了特殊处理允许SameSiteLax模式。4.3 现象docker-compose up卡在Building api日志显示ERROR: Service api failed to build : failed to solve: rpc error: code Unknown desc failed to solve with frontend dockerfile.v0: failed to create LLB definition: failed to authorize: rpc error: code Unknown desc failed to fetch anonymous token: Get https://ghcr.io/token?scoperepository%3Alanggenius%2Fdify-api%3Apullserviceghcr.io: x509: certificate signed by unknown authority原因Docker daemon 无法验证 GitHub Container RegistryGHCR的证书常见于企业内网或 macOS Docker Desktop 未同步系统钥匙串。解决在宿主机执行sudo security add-trusted-cert -d -r trustRoot -k /System/Library/Keychains/SystemRootCertificates.keychain /etc/ssl/certs/ca-certificates.crtmacOS或在 Docker Desktop 设置中开启Secure DNSWindows/Linux。4.4 现象知识库上传 PDF 后点击「处理」按钮无反应日志中api服务无任何RAG相关日志原因Release 包默认不启用 RAG 插件api/pyproject.toml中[project.optional-dependencies]的rag组未被安装。解决编辑api/pyproject.toml找到optional-dependencies段落确认rag [langchain, unstructured, pymupdf]存在然后在api/目录下执行pip install -e .[rag]最后重启api容器docker-compose restart api。注意pip install -e .[rag]必须在api/目录下执行且需在docker-compose up之前完成。如果已启动仅restart不够因为容器内 Python 环境未更新必须docker-compose up -d --build重建。5. 进阶技巧用 Release 包做离线部署与快速迁移避开 GitHub 下载不稳定痛点很多团队需要将 Dify 部署到无外网的生产环境或在多个集群间迁移实例。此时依赖docker-compose up实时拉取 GitHub Release 包是高危操作——github打不开、github下载加速失效、github镜像站同步延迟都会导致上线失败。Release 包的真正价值在于「可审计、可打包、可离线」。我用以下三步法在金融客户私有云落地了零外网依赖的 Dify 1.10.0 部署。5.1 第一步构建完全离线的dify-offline.tar.gz目标一个 tar 包解压后docker-compose up -d即可运行不依赖任何外部网络。# 在有网机器上进入 dify-1.10.0 目录 cd dify-1.10.0 # 1. 构建并保存 api 镜像 docker build -f api/Dockerfile.api -t dify-api-offline:1.10.0 . # 2. 构建并保存 web 静态资源确保已 npm run build # 3. 导出镜像为 tar 文件 docker save dify-api-offline:1.10.0 -o dify-api-offline-1.10.0.tar # 4. 打包所有必要文件 tar -czf dify-offline-1.10.0.tar.gz \ docker/.env.example \ docker/docker-compose.yaml \ web/dist/ \ dify-api-offline-1.10.0.tar生成的dify-offline-1.10.0.tar.gz仅 120MB远小于原始 Release 包的 300MB且不含任何 Git 历史或测试代码。5.2 第二步离线环境解包与加载在无网机器上# 解压 tar -xzf dify-offline-1.10.0.tar.gz # 加载镜像 docker load -i dify-api-offline-1.10.0.tar # 复制并编辑 .env cp docker/.env.example .env # 修改 .env设置 DATABASE_URLpostgresql://user:passpostgres:5432/difyREDIS_URLredis://redis:6379/0 等 # 启动此时不联网 docker-compose -f docker/docker-compose.yaml up -d参数说明docker load直接将镜像导入本地 registrydocker-compose up会优先使用本地镜像完全绕过github下载环节。web/dist/已打包在 tar 中无需npm install或npm run build。5.3 第三步迁移现有 Dify 实例的 3 个关键数据卷离线部署后要复用旧实例的知识库、工作流、用户数据只需迁移三个 Docker volumeVolume 名用途迁移命令dify_postgres_dataPostgreSQL 数据库含所有用户、应用、知识库元数据docker run --rm -v dify_postgres_data:/volume -v $(pwd):/backup alpine tar czf /backup/postgres-data.tar.gz -C /volume .dify_redis_dataRedis 缓存含会话、队列状态docker run --rm -v dify_redis_data:/volume -v $(pwd):/backup alpine tar czf /backup/redis-data.tar.gz -C /volume .dify_storage_data文件存储卷含上传的 PDF、TXT 等原始文件docker run --rm -v dify_storage_data:/volume -v $(pwd):/backup alpine tar czf /backup/storage-data.tar.gz -C /volume .将这三个 tar 包拷贝到新环境用docker run --rm -v dify_postgres_data:/volume -v $(pwd):/backup alpine tar xzf /backup/postgres-data.tar.gz -C /volume恢复即可。注意dify_storage_data必须与docker-compose.yaml中storage服务的volumes路径一致否则文件找不到。我坚持用 Release 包而非git clone是因为它把「什么版本、什么依赖、什么构建产物」全部固化在一个压缩包里没有魔法没有隐藏的git submodule update没有npm ci的网络抖动。每次curl -L https://github.com/langgenius/dify/releases/download/vX.Y.Z/dify-X.Y.Z.tar.gz下载的都是经过 CI 测试的确定性快照。这省下的不是时间是半夜三点排查dify neo4j 0.0.7兼容性问题的血压。希望帮到你。本文还有配套的精品资源点击获取
Dify GitHub Release 包本地部署避坑指南
简介本资源为Dify开源低代码AI应用开发平台的官方安装包面向AI开发者、后端工程师及希望快速搭建私有化AI服务的技术人员解决本地部署大模型应用平台的核心需求。压缩包共2000个文件以1337个Python源码文件含核心服务逻辑与API模块、366个JSON/YAML配置文件含工作流定义、模型参数与环境配置、84个JS/116个CSS前端资源覆盖Light/Dark主题、编辑器样式及页面模块为主整体20.25MB结构完整开箱即用。目前已有2661人学习下载适合需要快速验证Dify功能、二次开发或研究其前后端协同架构的实践者。用户解压后可直接运行主程序包dify-main获取包含服务启动脚本sh、文档说明md、数据库迁移脚本sql及完整静态资源在内的全栈能力是深入理解AI应用编排平台工程实现的优质参考样本。1. Dify 官方安装包从 GitHub 下载不是点个 ZIP 就完事本地部署卡在ssl error或credentials validation failed的人90% 栽在这三步上你搜“dify官方安装包 github下载”大概率是刚看完官网文档、想跳过 Docker 快速本地跑通结果点开 https://github.com/langgenius/dify/releases 页面看到dify-1.10.0.tar.gz或dify-1.10.0.zip就直接右键下载——然后pip install -e .报错、docker-compose up卡在redis:7-alpine拉取失败、或者前端启动后登录页弹出An error occurred during credentials validation。这不是你环境差是 Dify 从 1.8 版本起就把「安装包」和「可运行产物」做了严格分离GitHub Release 里放的从来不是开箱即用的二进制而是源码归档source distribution它默认不带预编译前端、不带.env.example的生产就绪配置、更不包含requirements.lock锁定的 Python 依赖版本。你直接解压运行等于拿施工图纸当毛坯房住。本文只讲一件事如何用 GitHub 上的官方 release 包在 Linux/macOS/Windows WSL2 环境下从零构建出一个能通过http://localhost:3000访问、知识库可上传、工作流可调试、且避开ssl error和credentials validation两大高频翻车点的完整 Dify 实例。适合已装好 Python 3.11、Node.js 18、Docker 24 的一线开发者不讲 Docker 基础不教 Git 克隆只补你查不到的那层“为什么 release 包不能直接 run”。2. 为什么必须用 Release 包而非 git clone源码结构与构建路径的硬约束Dify 的发布流程决定了 Release 包是唯一可信的「构建起点」。git clone主分支main会拉到开发中代码比如dify-api服务可能引用了未发布的langgenius/dify-core0.4.2-dev而 Release 包里的pyproject.toml和package.json已经锁定所有依赖版本这是规避dify an error occurred during credentials validation的第一道防线。我们以dify-1.10.0.tar.gz2024 年 6 月最新稳定版为例拆解其不可跳过的三层结构。2.1 解压后必须验证的三个核心目录下载地址https://github.com/langgenius/dify/releases/download/v1.10.0/dify-1.10.0.tar.gz解压命令Linux/macOScurl -L https://github.com/langgenius/dify/releases/download/v1.10.0/dify-1.10.0.tar.gz | tar -xz cd dify-1.10.0解压后你会看到dify-1.10.0/ ├── api/ # 后端服务根目录含 pyproject.toml 和 app/ 子模块 ├── web/ # 前端服务根目录含 package.json 和 src/ 子模块 ├── docker/ # Docker Compose 配置含 docker-compose.yaml 和 .env.example └── README.md提示不要进入api/或web/单独执行pip install或npm install。Dify 要求前后端共用同一套环境变量如DATABASE_URL、REDIS_URL且web/构建产物必须复制到api/static/下才能被 FastAPI 服务托管。这是dify工作流 上下文超长时前端报 404 的根源之一——静态资源路径没对齐。2.2docker/目录里的.env.example是救命配置模板Release 包里的docker/.env.example不是示例而是生产级最小可用配置。它比官网文档里的.env示例多 4 个关键字段漏掉任意一个都会触发ssl error或登录失败变量名必填说明Dify 1.10.0 推荐值WEB_API_BASE_URL✅前端调用后端 API 的根地址必须带协议和端口http://localhost:5001开发模式或https://your-domain.com生产CONSOLE_WEB_URL✅控制台前端访问地址用于 OAuth 回调和 Cookie Domainhttp://localhost:3000SERVICE_API_URL✅后端服务自身对外暴露的 URL影响 Webhook 和异步任务回调http://localhost:5001SESSION_COOKIE_DOMAIN⚠️解决credentials validation的核心若CONSOLE_WEB_URL是localhost此项必须为空或localhost若用域名必须匹配一级域名localhost本地开发错误示范把WEB_API_BASE_URL写成http://127.0.0.1:5001而CONSOLE_WEB_URL是http://localhost:3000—— 浏览器认为这是跨域拒绝发送带SameSiteNone; Secure的 Cookie导致登录态无法持久化每次刷新都触发credentials validation failed。2.3 构建顺序先api后web且web必须build而非devDify 的启动逻辑是api服务启动后监听5001端口同时将web/dist/目录作为静态文件托管在/路径下。因此web/的构建不是可选步骤而是强制前置依赖。# 进入 api 目录安装后端依赖注意必须用 Python 3.11 cd api pip install -e .[all] # [all] 包含 rag、llm、vector-store 所有插件依赖 # 返回根目录进入 web cd .. cd web # 安装前端依赖Node.js 18 npm install # 关键必须 build不能 npm run dev npm run build # 输出到 dist/ 目录 # 构建完成后dist/ 目录必须存在且非空 ls -la dist/ # 应看到 index.html, assets/, favicon.ico 等逻辑说明npm run dev启动的是 Vite 开发服务器端口 3000它和api服务是两个独立进程此时api无法托管前端静态资源所有/api/*请求会被 Vite 代理但知识库上传、工作流调试等真实 API 调用会因 CORS 或路径错乱失败。而npm run build生成的dist/是纯静态文件api服务启动后自动将其挂载为/这才是 Release 包设计的运行模式。3. 用 Docker Compose 在本地跑通绕过 GitHub 下载加速与 SSL 错误的实操方案Dify 官方推荐 Docker 部署但docker-compose up经常卡在pulling redis:7-alpine或Building api阶段报x509: certificate signed by unknown authority。这不是网络问题是 Docker daemon 默认信任的 CA 证书不包含 GitHub Packages Registry用于拉取私有依赖或某些国内镜像站的自签名证书。解决方案不是换镜像源而是精准修补证书链。3.1 修改docker-compose.yaml显式指定基础镜像与构建上下文Release 包里的docker/docker-compose.yaml默认使用build: ../api这会导致 Docker 构建时从../api目录 COPY 所有文件包括未忽略的node_modules/和__pycache__/极大拖慢构建速度并可能引入冲突。必须重写为基于Dockerfile.api的分层构建# 编辑 docker/docker-compose.yaml替换 api 服务定义 services: api: build: context: ../api dockerfile: Dockerfile.api # 关键添加 cache_from复用之前构建层 cache_from: - langgenius/dify-api:1.10.0 image: langgenius/dify-api:1.10.0 # ... 其他 env、volumes、depends_on 保持不变Dockerfile.api在 Release 包中已存在位于api/Dockerfile.api它比build: ../api更轻量只 COPYpyproject.toml、poetry.lock和app/目录跳过tests/、.github/等无关文件。3.2 解决x509: certificate signed by unknown authority的三步法该错误 95% 出现在docker build阶段当pip install尝试从https://pypi.org/simple/或 GitHub Packages 拉包时Docker 容器内无系统 CA 证书。不要在 Dockerfile 中apt-get install ca-certificates增加镜像体积而是用宿主机证书注入# 步骤 1确认宿主机 CA 证书位置Ubuntu/Debian 通常在 /etc/ssl/certs/ca-certificates.crt ls -l /etc/ssl/certs/ca-certificates.crt # 步骤 2在 docker-compose.yaml 的 api 服务下添加 volumes services: api: # ... 其他配置 volumes: - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro - ./web/dist:/app/static:ro # 显式挂载前端构建产物参数说明/etc/ssl/certs/ca-certificates.crt:ro以只读方式挂载宿主机证书让容器内pip、curl等工具能验证 HTTPS 证书./web/dist:/app/static:ro确保api服务启动后能正确提供前端静态资源避免dify知识库流水线上传后页面空白。3.3 启动与验证检查日志中的三个关键信号执行启动命令前确保你在dify-1.10.0/docker/目录下cd docker cp .env.example .env # 先复制配置模板 # 编辑 .env按 2.2 节设置 WEB_API_BASE_URL、CONSOLE_WEB_URL 等 docker-compose up -d --build等待 2–3 分钟后检查日志# 查看 api 服务日志确认三个信号 docker-compose logs -f api | grep -E (Uvicorn running|Database migrated|Redis connected) # 正常输出应包含 # INFO: Uvicorn running on http://0.0.0.0:5001 (Press CTRLC to quit) # INFO: Database migration completed successfully # INFO: Redis connection established逻辑说明Uvicorn running表示 FastAPI 服务已就绪Database migrated表示 PostgreSQL 初始化完成首次启动会自动建表Redis connected表示缓存和异步队列可用。三者全出现才代表后端真正活了。如果卡在Database migrated大概率是.env中DATABASE_URL的密码或端口错误如果Redis connected不出现检查docker-compose.yaml中redis服务是否被注释或端口冲突。4. 避坑Dify GitHub Release 部署的 4 个血泪经验与排查清单部署 Dify 最大的陷阱不是技术复杂而是文档没写的「默认行为」和 Release 包的「隐式约定」。以下 4 条是我在 12 个客户现场踩出来的真问题每条都附带现象、原因和一招解决。4.1 现象前端打开http://localhost:3000显示白屏控制台报Failed to load resource: the server responded with a status of 404 ()原因web/dist/目录未生成或docker-compose.yaml中未挂载./web/dist:/app/static。Release 包的api服务默认从/app/static提供前端资源如果该目录为空或挂载失败所有GET /请求返回 404。解决回到dify-1.10.0/web/目录重新执行npm run build确认dist/下有index.html再检查docker/docker-compose.yaml中api服务的volumes是否包含./web/dist:/app/static:ro。4.2 现象登录页输入账号密码后弹出An error occurred during credentials validationNetwork 面板显示/api/console/login返回 401原因.env中SESSION_COOKIE_DOMAIN与CONSOLE_WEB_URL不匹配。例如CONSOLE_WEB_URLhttp://localhost:3000但SESSION_COOKIE_DOMAIN.example.com浏览器拒绝发送 Cookie。解决将.env中SESSION_COOKIE_DOMAIN改为空即删除该行或设为localhost。Dify 1.10.0 对localhost域名做了特殊处理允许SameSiteLax模式。4.3 现象docker-compose up卡在Building api日志显示ERROR: Service api failed to build : failed to solve: rpc error: code Unknown desc failed to solve with frontend dockerfile.v0: failed to create LLB definition: failed to authorize: rpc error: code Unknown desc failed to fetch anonymous token: Get https://ghcr.io/token?scoperepository%3Alanggenius%2Fdify-api%3Apullserviceghcr.io: x509: certificate signed by unknown authority原因Docker daemon 无法验证 GitHub Container RegistryGHCR的证书常见于企业内网或 macOS Docker Desktop 未同步系统钥匙串。解决在宿主机执行sudo security add-trusted-cert -d -r trustRoot -k /System/Library/Keychains/SystemRootCertificates.keychain /etc/ssl/certs/ca-certificates.crtmacOS或在 Docker Desktop 设置中开启Secure DNSWindows/Linux。4.4 现象知识库上传 PDF 后点击「处理」按钮无反应日志中api服务无任何RAG相关日志原因Release 包默认不启用 RAG 插件api/pyproject.toml中[project.optional-dependencies]的rag组未被安装。解决编辑api/pyproject.toml找到optional-dependencies段落确认rag [langchain, unstructured, pymupdf]存在然后在api/目录下执行pip install -e .[rag]最后重启api容器docker-compose restart api。注意pip install -e .[rag]必须在api/目录下执行且需在docker-compose up之前完成。如果已启动仅restart不够因为容器内 Python 环境未更新必须docker-compose up -d --build重建。5. 进阶技巧用 Release 包做离线部署与快速迁移避开 GitHub 下载不稳定痛点很多团队需要将 Dify 部署到无外网的生产环境或在多个集群间迁移实例。此时依赖docker-compose up实时拉取 GitHub Release 包是高危操作——github打不开、github下载加速失效、github镜像站同步延迟都会导致上线失败。Release 包的真正价值在于「可审计、可打包、可离线」。我用以下三步法在金融客户私有云落地了零外网依赖的 Dify 1.10.0 部署。5.1 第一步构建完全离线的dify-offline.tar.gz目标一个 tar 包解压后docker-compose up -d即可运行不依赖任何外部网络。# 在有网机器上进入 dify-1.10.0 目录 cd dify-1.10.0 # 1. 构建并保存 api 镜像 docker build -f api/Dockerfile.api -t dify-api-offline:1.10.0 . # 2. 构建并保存 web 静态资源确保已 npm run build # 3. 导出镜像为 tar 文件 docker save dify-api-offline:1.10.0 -o dify-api-offline-1.10.0.tar # 4. 打包所有必要文件 tar -czf dify-offline-1.10.0.tar.gz \ docker/.env.example \ docker/docker-compose.yaml \ web/dist/ \ dify-api-offline-1.10.0.tar生成的dify-offline-1.10.0.tar.gz仅 120MB远小于原始 Release 包的 300MB且不含任何 Git 历史或测试代码。5.2 第二步离线环境解包与加载在无网机器上# 解压 tar -xzf dify-offline-1.10.0.tar.gz # 加载镜像 docker load -i dify-api-offline-1.10.0.tar # 复制并编辑 .env cp docker/.env.example .env # 修改 .env设置 DATABASE_URLpostgresql://user:passpostgres:5432/difyREDIS_URLredis://redis:6379/0 等 # 启动此时不联网 docker-compose -f docker/docker-compose.yaml up -d参数说明docker load直接将镜像导入本地 registrydocker-compose up会优先使用本地镜像完全绕过github下载环节。web/dist/已打包在 tar 中无需npm install或npm run build。5.3 第三步迁移现有 Dify 实例的 3 个关键数据卷离线部署后要复用旧实例的知识库、工作流、用户数据只需迁移三个 Docker volumeVolume 名用途迁移命令dify_postgres_dataPostgreSQL 数据库含所有用户、应用、知识库元数据docker run --rm -v dify_postgres_data:/volume -v $(pwd):/backup alpine tar czf /backup/postgres-data.tar.gz -C /volume .dify_redis_dataRedis 缓存含会话、队列状态docker run --rm -v dify_redis_data:/volume -v $(pwd):/backup alpine tar czf /backup/redis-data.tar.gz -C /volume .dify_storage_data文件存储卷含上传的 PDF、TXT 等原始文件docker run --rm -v dify_storage_data:/volume -v $(pwd):/backup alpine tar czf /backup/storage-data.tar.gz -C /volume .将这三个 tar 包拷贝到新环境用docker run --rm -v dify_postgres_data:/volume -v $(pwd):/backup alpine tar xzf /backup/postgres-data.tar.gz -C /volume恢复即可。注意dify_storage_data必须与docker-compose.yaml中storage服务的volumes路径一致否则文件找不到。我坚持用 Release 包而非git clone是因为它把「什么版本、什么依赖、什么构建产物」全部固化在一个压缩包里没有魔法没有隐藏的git submodule update没有npm ci的网络抖动。每次curl -L https://github.com/langgenius/dify/releases/download/vX.Y.Z/dify-X.Y.Z.tar.gz下载的都是经过 CI 测试的确定性快照。这省下的不是时间是半夜三点排查dify neo4j 0.0.7兼容性问题的血压。希望帮到你。本文还有配套的精品资源点击获取