常见问题

本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。

​

部署方法

​

安装旧版本

使用 --branch 标志来安装特定版本：

git clone https://github.com/langgenius/dify.git --branch 0.15.3

其余设置与安装最新版本相同。

​

使用 ZIP 压缩包安装

对于网络受限环境或无法使用 git 的情况：

# 下载最新版本
wget -O dify.zip "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r '.zipball_url')"
unzip dify.zip && rm dify.zip

或者，在另一台设备上下载 ZIP 文件并手动传输。

升级方法：

wget -O dify-latest.zip "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r '.zipball_url')"
unzip dify-latest.zip && rm dify-latest.zip
rsync -a dify-latest/ dify/
rm -rf dify-latest/
cd dify/docker
docker compose pull
docker compose up -d

​

克隆报错「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 页面查看最新版本号，然后运行：

git clone --branch <version> https://github.com/langgenius/dify.git

不加 --branch 直接克隆也可行：main 分支的 Compose 文件固定指向最新发布版镜像，运行的仍是正式版本。但 Compose 文件、环境变量模板等部署文件本身跟随开发进度，可能与发布版有出入。

​

备份程序

​

升级前创建备份

升级前务必备份以防止数据丢失：

cp -r dify "dify.bak.$(date +%Y%m%d%H%M%S)"

这将创建一个带时间戳的备份，便于轻松恢复。

​

反向代理配置

​

前端和后端使用不同子域名时登录会话失效

若已将 Web 和 API 拆分到不同子域名并部署在反向代理之后（例如 app.example.com 用于 UI，api.example.com 用于后端），认证 Cookie 无法同时到达两个主机。登录看似成功，但下一次请求时会话即丢失。

在 .env 中设置以下两个变量，然后重启 Dify：

• COOKIE_DOMAIN：设为前后端共享的顶级域名（例如 example.com），前导点可省略。
• NEXT_PUBLIC_COOKIE_DOMAIN：设为 1，启用前端的跨子域名 Cookie。

docker compose down
docker compose up -d

Cookie 无法跨顶级域名共享，因此前端和后端必须位于同一可注册域名下。详见 环境变量。