本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。
部署方法
安装旧版本
使用--branch 标志来安装特定版本：
使用 ZIP 压缩包安装
对于网络受限环境或无法使用 git 的情况：克隆报错「Remote branch null not found」
使用 Docker Compose 部署 Dify 中的克隆命令通过 GitHub API 解析 Dify 最新版本号。该请求失败时（常见原因是 GitHub 对未认证请求的限流），jq 会输出 null，git 随即报 fatal: Remote branch null not found in upstream origin。
改用显式版本号克隆。在 Dify releases 页面查看最新版本号，然后运行：
--branch 直接克隆也可行：main 分支的 Compose 文件固定指向最新发布版镜像，运行的仍是正式版本。但 Compose 文件、环境变量模板等部署文件本身跟随开发进度，可能与发布版有出入。
备份程序
升级前创建备份
升级前务必备份以防止数据丢失：反向代理配置
前端和后端使用不同子域名时登录会话失效
若已将 Web 和 API 拆分到不同子域名并部署在反向代理之后（例如app.example.com 用于 UI，api.example.com 用于后端），认证 Cookie 无法同时到达两个主机。登录看似成功，但下一次请求时会话即丢失。
在 .env 中设置以下两个变量，然后重启 Dify：
COOKIE_DOMAIN：设为前后端共享的顶级域名（例如example.com），前导点可省略。NEXT_PUBLIC_COOKIE_DOMAIN：设为1，启用前端的跨子域名 Cookie。
部署在 Cloudflare 或其他代理之后，所有人的登录邮件都被拦截
所有人同时无法获取登录验证码和密码重置邮件，报错均为：「Too many emails have been sent from this IP address recently. Please try again later.」从 1.18.0 起，只要 Dify 自带的 Nginx 前面还有 Cloudflare、负载均衡器或其他代理，任何部署都可能遇到这个问题。 Dify 从自带的 Nginx 获取每个访问者的 IP 地址。有代理在前时，Nginx 只能看到代理的地址，所有访问者都算在这个地址名下，共用同一份限额。 如果代理绕过自带的 Nginx，直接转发到api 和 web 容器（部分 Cloudflare Tunnel 和 Nginx Proxy Manager 配置就是如此），跳过下面的步骤，改为确认：
- 代理会设置
X-Forwarded-For，否则所有访问者都会显示为代理的地址。 - 只能通过代理访问 API。任何能直连 API 的人都可以任意指定 Dify 看到的地址。
1
确定代理的地址
Nginx 访问日志（
docker compose logs nginx）的每一行都以代理连接时使用的地址开头。即使代理与 Dify 在同一台服务器上，也要以日志中的地址为准，不要想当然地填 127.0.0.1。如果是 Cloudflare 直连 Nginx，跳过此步骤。2
创建 real-ip.conf
根据你的部署情况创建
docker/nginx/conf.d/real-ip.conf。Nginx 本身就会加载该目录下的每个 .conf 文件，升级也不会覆盖你创建的文件。- 负载均衡器或反向代理
- Cloudflare
- 多层代理
适用于会设置
X-Forwarded-For 的代理：3
重新加载 Nginx
docker compose logs nginx 中新增的日志行应改为以访问者自己的地址开头。访问者不再共用被拦截的那个地址，可立即重新请求邮件。