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

4 min read

基础设施 / 自建 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 为基础进行替换，仅恢复必要的差异部分，结果证明更新后的可读性和可维护性都有了显著提升。

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

首先对包括 docker/volumes 在内的内容进行完整备份
在单独的目录中获取官方 v1.13.3，以此作为差异比对基准
将 docker-compose.yaml 替换为官方版本
仅恢复 .env 以及 TLS 挂载等环境专属设置
将 Sandbox 配置文件更新为符合新版本的前提假设
启动前使用 docker compose config 校验语法
启动后不仅要检查 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 为基础重新构建”是更稳妥的做法，也能让日后回顾时的配置更加清晰易懂。

Updated on 2026年6月9日

What are your feelings

Happy
常规
Sad

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

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

更新前的配置 #

更新后的配置 #

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

服务配置的变化 #

周边组件的更新 #

存在自定义调整 #

配置文件的漂移 #

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

1. 首先进行备份 #

2. 获取官方 v1.13.3 #

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

4. 恢复环境专属设置 #

务必核实的项目 #

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

5. 恢复 NGINX 证书挂载 #

6. 更新 Sandbox 配置 #

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

8. 更新后验证清单 #

常见陷阱汇总 #

DB_HOST 不一致 #

遗漏 worker_beat #

忘记恢复 TLS 挂载 #

沿用旧的 Sandbox 配置 #

本次更新的经验总结 #

Share This Article :

服务

AI 解决方案

资源

`DB_HOST` 不一致 #

遗漏 `worker_beat` #