> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-release-1-17-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/deploy/quick-start/faqs)。

## 部署方法

### 安装旧版本

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

```bash theme={null}
git clone https://github.com/langgenius/dify.git --branch 0.15.3
```

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

### 使用 ZIP 压缩包安装

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

```bash theme={null}
# 下载最新版本
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 文件并手动传输。

**升级方法**：

```bash theme={null}
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](/zh/self-host/deploy/quick-start/docker-compose) 中的克隆命令通过 GitHub API 解析 Dify 最新版本号。该请求失败时（常见原因是 GitHub 对未认证请求的限流），`jq` 会输出 `null`，git 随即报 `fatal: Remote branch null not found in upstream origin`。

改用显式版本号克隆。在 [Dify releases](https://github.com/langgenius/dify/releases) 页面查看最新版本号，然后运行：

```bash theme={null}
git clone --branch <version> https://github.com/langgenius/dify.git
```

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

## 备份程序

### 升级前创建备份

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

```bash theme={null}
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。

```bash theme={null}
docker compose down
docker compose up -d
```

Cookie 无法跨顶级域名共享，因此前端和后端必须位于同一可注册域名下。详见 [环境变量](/zh/self-host/deploy/configuration/environments)。