---
title: 将Dify从v1.9.2升级到v1.13.3时的操作流程及注意事项
description: "基础设施 / 自建 AI 平台 # 将 Dify 从 v1.9.2 升级到 v1.13.3 时的操作流程及注意事项 对旧版 `docker-compose.yaml` 做过的自定义调整越多，升级自建 Dify 的难度就越大。 本次我们记录了将运行在 Docker Compose 上的 Dify 从 **v1.9.2** 升级到 **v1.13.3** 的整个过程， 并对敏感信息进行了脱敏以便公开发布。 与其只是简单地更新镜像标签，更稳妥的做法是**以官方 compose 为基础进行替换，然后再恢复各环境的专属配置**。 Dify Docker Compose Weaviate 自建（Self-hosted） 升级 已脱敏公开 **公开说明**…"
url: "https://bestnetllc.co.jp/zh-hans/docs/%e5%b0%86dify%e4%bb%8ev1-9-2%e5%8d%87%e7%ba%a7%e5%88%b0v1-13-3%e6%97%b6%e7%9a%84%e6%93%8d%e4%bd%9c%e6%b5%81%e7%a8%8b%e5%8f%8a%e6%b3%a8%e6%84%8f%e4%ba%8b%e9%a1%b9/"
updated: "2026-06-08"
category: Tech Blog / GPU与LLM基础设施
---

# 将Dify从v1.9.2升级到v1.13.3时的操作流程及注意事项

基础设施 / 自建 AI 平台

# 将 Dify 从 v1.9.2 升级到 v1.13.3 时的操作流程及注意事项

对旧版 `docker-compose.yaml` 做过的自定义调整越多，升级自建 Dify 的难度就越大。 本次我们记录了将运行在 Docker Compose 上的 Dify 从 **v1.9.2** 升级到 **v1.13.3** 的整个过程， 并对敏感信息进行了脱敏以便公开发布。 与其只是简单地更新镜像标签，更稳妥的做法是**以官方 compose 为基础进行替换，然后再恢复各环境的专属配置**。

  Dify Docker Compose Weaviate 自建（Self-hosted） 升级 已脱敏公开   **公开说明**
 本文中的域名、邮箱地址、API 密钥、认证凭据、证书路径、主机名以及部分卷（volume）配置均已进行脱敏或抽象化处理，以防止识别出实际环境。

更新前

## 更新前的配置

- 基于 Dify v1.9.2
- 使用 Docker Compose 运行
- PostgreSQL / Redis / Weaviate
- NGINX 反向代理 + 外部证书目录
- 启用 Sandbox / Plugin Daemon

更新后

## 更新后的配置

- 基于 Dify v1.13.3
- 以官方 compose 为基础重新配置
- 新配置中包含 `db_postgres` / `worker_beat`
- Sandbox 配置已更新为新路径
- 重新应用自定义 TLS / 插件设置

## 为何“仅更新镜像标签”存在风险

当版本跨度较大时，Dify 往往无法仅凭简单的容器镜像更新来完全消化差异。 在实际比对差异后，本次更新有以下几个关键点。

### 服务配置的变化

在新的官方 compose 中，数据库服务名预期为 `db_postgres` 而非 `db`， 并且包含了 `worker_beat` 以及权限初始化处理流程，可见结构上存在差异。

### 周边组件的更新

Plugin Daemon、Sandbox、Weaviate 等 Dify 核心以外的组件同样是本次更新的对象。 若沿用旧的配置文件，很容易导致启动后部分功能出现故障。

### 存在自定义调整

在长期运行的环境中，证书挂载、自定义环境变量、插件配置等自定义设置往往会不断累积。 这些内容不会自动被纳入官方 compose，因此需要手动恢复。

### 配置文件的漂移

长期直接修改旧的 compose 文件，会导致难以分辨哪些是官方设置、哪些是公司自定义设置。 在这种状态下进行批量更新，可能引发难以恢复的故障。

    **本次的决策**
 我们没有继续沿用现有的 compose，而是**以官方 v1.13.3 compose 为基础进行替换，仅恢复必要的差异部分**， 结果证明更新后的可读性和可维护性都有了显著提升。

## 本次更新采用的升级策略

1. 首先对包括 `docker/volumes` 在内的内容进行完整备份
2. 在单独的目录中获取官方 v1.13.3，以此作为差异比对基准
3. 将 `docker-compose.yaml` 替换为官方版本
4. 仅恢复 `.env` 以及 TLS 挂载等环境专属设置
5. 将 Sandbox 配置文件更新为符合新版本的前提假设
6. 启动前使用 `docker compose config` 校验语法
7. 启动后不仅要检查 UI，还要验证 Knowledge / Plugin / 代码执行功能

## 1. 首先进行备份

最重要的是要**确保可以回退到更新前的 compose 与卷（volume）状态**。 尤其是 Weaviate 或 PostgreSQL，更新后确实存在希望回滚的场景。

```
cd /srv/dify/docker
TS=$(date +%Y%m%d%H%M%S)

cp -a docker-compose.yaml "docker-compose.yaml.${TS}.bak"
cp -a .env ".env.${TS}.bak"
[ -f volumes/sandbox/conf/config.yaml ] && 
  cp -a volumes/sandbox/conf/config.yaml "volumes/sandbox/conf/config.yaml.${TS}.bak"

tar -czf "/root/dify-volumes-${TS}.tgz" volumes
```

此处展示的路径为公开发布用的示例。在实际生产环境中，请根据您自身环境的目录结构进行调整。

## 2. 获取官方 v1.13.3

并非直接修改现有目录，而是将其获取到单独的目录中以便比对。 此阶段的关键点在于不要覆盖现有的环境文件。

```
cd /tmp
rm -rf dify-1.13.3
git clone --branch 1.13.3 https://github.com/langgenius/dify.git dify-1.13.3
```

获取完成后，至少比对以下三个文件，可以更容易理解本次更新需要吸收哪些变化： `docker-compose.yaml`、`.env.example`，以及 `volumes/sandbox/conf/config.yaml.example`。

## 3. 将 Compose 替换为官方版本

本次我们没有继续修改现有的 compose，而是直接采用官方 v1.13.3 作为基础。 这样一来，今后的升级也更容易追踪“与官方之间的差异”。

```
cp /tmp/dify-1.13.3/docker/docker-compose.yaml /srv/dify/docker/docker-compose.yaml
cp /tmp/dify-1.13.3/docker/.env.example /srv/dify/docker/.env.example.1.13.3
cp /tmp/dify-1.13.3/docker/volumes/sandbox/conf/config.yaml.example 
   /srv/dify/docker/volumes/sandbox/conf/config.yaml.example.1.13.3
```

   **重要提示**
 关键点在于**替换 compose 后不要立即启动**。 请先恢复 `.env`、证书挂载、Sandbox 设置等环境专属数值，再进行启动。

## 4. 恢复环境专属设置

在采用官方 compose 之后，以叠加（overlay）的方式仅恢复生产环境运行所需的设置。 在我们的环境中，以下几项尤为重要。

### 务必核实的项目

- `DB_HOST` 是否设置为 `db_postgres`
- Weaviate 的 API 密钥与 gRPC 端点
- NGINX 的服务器名与证书路径
- 公开 URL 与内部文件 URL
- Plugin Daemon 相关的超时设置

### 公开发布时需脱敏的项目

- 域名
- 邮箱地址
- API 密钥／密钥（secret）
- 实际的证书文件名
- 内部卷配置与主机名

```
DB_TYPE=postgresql
DB_HOST=db_postgres
DB_PORT=5432

VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_GRPC_ENDPOINT=grpc://weaviate:50051
WEAVIATE_API_KEY=<YOUR_WEAVIATE_API_KEY>

NGINX_SERVER_NAME=<YOUR_DOMAIN>
NGINX_HTTPS_ENABLED=true
NGINX_SSL_CERT_FILENAME=live/<YOUR_DOMAIN>/fullchain.pem
NGINX_SSL_CERT_KEY_FILENAME=live/<YOUR_DOMAIN>/privkey.pem

FILES_URL=https://<YOUR_DOMAIN>
INTERNAL_FILES_URL=http://api:5001
PLUGIN_MAX_EXECUTION_TIMEOUT=1800
```

关键在于**不要照搬所有旧的环境变量，而应以新的官方 `.env.example` 为基准，仅重新配置所需的项目**。 特别是 `DB_HOST` 以及与 Weaviate 相关的设置，如果沿用旧 compose 的内容，很容易在启动后引发错误。

## 5. 恢复 NGINX 证书挂载

在替换为官方 compose 之后，TLS 挂载配置可能会偏离您所在环境的原有假设。 本次我们是在现有的宿主机目录中管理证书，因此仅针对 NGINX 服务重新调整了挂载配置。

```
services:
  nginx:
    volumes:
      - ./nginx/ssl:/etc/ssl
      - /path/to/external/letsencrypt:/etc/letsencrypt
```

如果您的配置是完全在 Certbot 容器内部处理证书，官方挂载配置或许原样即可使用。 但如果是通过外部路径管理证书，替换后最好重新检查一遍。

## 6. 更新 Sandbox 配置

一个常被忽视的地方是 Sandbox 配置。 版本变化时，Python / Node.js 的路径前提可能发生变化， 而现有的 `config.yaml` 文件并不会自动更新。

```
app:
  port: 8194
  debug: true
  key: dify-sandbox

python_path: /opt/python/bin/python3
nodejs_path: /usr/local/bin/node
```

   **提示**
 沿用旧的 `config.yaml`，往往会出现 UI 可以正常启动、但唯独代码执行功能失败的情况。 更新之后，建议单独对 Sandbox 进行验证。

## 7. 启动前进行语法检查，启动后检查日志

替换 compose 之后，首先运行语法检查。 然后再拉取镜像并启动各项服务。

```
docker compose --profile weaviate --profile postgresql config > /tmp/dify.check.yaml

docker compose --profile weaviate --profile postgresql pull
docker compose --profile weaviate --profile postgresql up -d --remove-orphans

docker compose ps
docker compose logs --tail=120 api worker worker_beat plugin_daemon sandbox weaviate nginx
```

在更新工作中，切忌仅凭“能够启动”就断定成功。 来自 `api`、`worker`、`worker_beat`、`plugin_daemon`、`sandbox` 的日志，对于及早发现功能故障尤其有用。

## 8. 更新后验证清单

- 管理控制台可以正常登录
- 现有应用的对话响应正常返回
- Knowledge 检索与重新索引成功
- Code 节点与 Sandbox 执行成功
- 插件激活与执行成功
- HTTPS 访问与证书引用均无异常

在本次这种周边组件差异较大的更新中， **UI 能否打开**与**生产环境所需的全部功能是否正常运作**是两个独立的问题。 提前根据自身使用情况确定关键验证项目，能让回滚决策更容易做出。

## 常见陷阱汇总

### `DB_HOST` 不一致

如果没有与新的官方 compose 保持一致，API 与 Plugin Daemon 将无法连接数据库并崩溃。 `db` 与 `db_postgres` 之间的不一致，正是一个特别容易被忽视的地方。

### 遗漏 `worker_beat`

如果只关注主 API 和 worker，可能会遗漏定期任务方面的问题。 更新后，最好也一并检查这些辅助服务。

### 忘记恢复 TLS 挂载

将 compose 替换为官方版本时，证书路径可能超出您所在环境的原有假设。 这会导致 HTTP 正常，但 HTTPS 失败。

### 沿用旧的 Sandbox 配置

由于管理控制台能够正常打开，这一点很容易被忽视，但它会直接导致代码执行功能失败。 分别对 UI 和 Sandbox 进行验证是关键所在。

## 本次更新的经验总结

Dify 环境运行的时间越长，升级时“累积下来的自定义差异”对比“版本号”所带来的影响就越大。 本次我们再次确认的一点是，**尽量减少对官方 compose 的修改、将环境专属设置作为叠加层来管理**， 会让后续的升级和故障应对都变得大幅简化。

如果您当前的环境正稳定运行在旧版本上，在更新前先整理好以下三点，整个过程会顺畅得多。

- 盘点并区分官方来源的设置与公司自定义的设置
- 务必进行可回滚的备份
- 在启动验证之前，先确定关键功能的验证项目

  **结论**
 对于 Dify 的重大版本更新而言，**相较于“扩展旧的 compose”，“以新的官方 compose 为基础重新构建”**是更稳妥的做法， 也能让日后回顾时的配置更加清晰易懂。

本文中的命令与配置值已为公开发布进行了抽象化处理。 应用到您自己的环境时，请务必根据贵公司的域名、存储、证书、认证凭据及卷配置进行相应调整。