版本升级笔记–迁移、兼容性验证、回滚策略实用指南

升级 Dify Enterprise 不仅仅是“更换镜像并重启”那么简单。 数据库迁移、配置文件变更、依赖组件版本一致性、API兼容性 – 由于这些东西同时发生变化，没有提前准备的升级将直接导致生产失败。

官方文档还明确指出“升级步骤可能因版本而异”，有必要检查每个版本的不同步骤。本文为日本公司的运营团队提供了安全执行升级的综合指南。

1. 升级概述

1.1 升级后发生的三件事改变

graph LR
    A[バージョンアップグレード] --> B[イメージ更新]
    A --> C[設定変更]
    A --> D[データマイグレーション]
    B --> B1[API / Worker / Web / Sandbox / Enterprise]
    C --> C1[values.yaml の新規・廃止パラメータ]
    C --> C2[.env の変更点]
    D --> D1[PostgreSQL スキーマ変更]
    D --> D2[Vector DB インデックス再構築]
    D --> D3[オブジェクトストレージの構造変更]

1.2 升级影响范围

影响范围	内容	风险等级
应用层	Dify各组件镜像更新	中等
数据库层	PostgreSQL 架构迁移	高
配置层	更改值.yaml / .env	中等
外部链接	API端点响应格式的更改	高
插件/提供商	插件守护程序和模型提供程序兼容性	中等
许可证	版本和许可证兼容性	低到中

2.升级前准备（Pre-Upgrade）

2.1 仔细阅读发行说明

升级的第一步是仔细阅读目标版本的发行说明。

检查要点：

重大更改：对现有功能的不兼容更改
弃用：弃用的功能和参数
迁移注意事项：数据库迁移的特别注意事项
新配置：添加配置项
已知问题：已知问题

# GitHub の Release ページを確認
# https://github.com/langgenius/dify/releases

# Enterprise 固有の変更は Enterprise Docs を確認
# https://enterprise-docs.dify.ai/en-us/deployment/

2.2 检查配置文件差异

# Docker Compose の場合: .env.example の差分を確認
diff .env.example .env.example.new

# Helm の場合: values.yaml の差分を確認
helm show values dify/dify --version <新バージョン> > values-new.yaml
diff values.yaml values-new.yaml

更改values.yaml中应特别注意的模式：

图案	通讯
添加新参数	检查默认值并在必要时明确设置
更改参数名称	用新名称替换旧名称
弃用参数	从values.yaml中删除（保留它会导致错误）
更改默认值	检查这是否是预期的行为，并在必要时澄清旧值
改变结构	修改 YAML 层次结构以匹配新格式

2.3 进行备份

**升级前切勿跳过备份。 **

# 1. PostgreSQL のフルバックアップ
pg_dump -h <DB_HOST> -U <DB_USER> -d dify_production \
  -F c -f dify_backup_$(date +%Y%m%d_%H%M%S).dump

# 2. オブジェクトストレージのスナップショット
aws s3 sync s3://dify-enterprise-prod s3://dify-enterprise-prod-backup-$(date +%Y%m%d)

# 3. Vector DB (Qdrant) のスナップショット
curl -X POST "http://qdrant-host:6333/collections/dify/snapshots"

# 4. values.yaml の退避
cp values.yaml values.yaml.backup.$(date +%Y%m%d)

# 5. Kubernetes リソースの全体バックアップ（Velero を利用する場合）
velero backup create dify-pre-upgrade-$(date +%Y%m%d) \
  --include-namespaces dify-production \
  --wait

2.4 记录当前环境的状态

将当前版本和设置记录在 helm list、kubectl get pods -o wide 和 helm get values dify 中。

3.暂存环境中的验证（Staging Validation）

3.1 暂存验证流程

graph TD
    A[Release Note 確認] --> B[ステージング環境バックアップ]
    B --> C[ステージングでアップグレード実施]
    C --> D{マイグレーション成功?}
    D -->|Yes| E[機能テスト実施]
    D -->|No| F[ログ確認・原因調査]
    F --> G[修正対応]
    G --> C
    E --> H{全テスト合格?}
    H -->|Yes| I[本番アップグレード計画策定]
    H -->|No| J[問題の切り分け]
    J --> K{回避策あり?}
    K -->|Yes| L[回避策を本番計画に反映]
    K -->|No| M[アップグレード延期]
    L --> I

3.2 分阶段验证清单

项目	确认详情	通过/失败
Pod 启动	所有组件均处于运行状态
数据库迁移	已完成且无错误
管理控制台	登录及基本操作正常
应用运营	现有应用程序运行正常
运行工作流程	现有工作流程按预期工作
代理执行	Agent可以成功调用工具
知识库	搜索工作正常
API调用	外部API调用成功
文件上传	文件上传及处理成功
单点登录	单点登录成功
许可证	许可证信息显示正确
插件	使用中的插件工作正常

4. 执行生产升级

4.1 配置维护时段

推奨スケジュール:
- 曜日: 水曜日または木曜日（週末前に問題発見の余裕を持つ）
- 時間帯: 22:00 - 02:00 JST（利用者が最少の時間帯）
- 所要時間: 2〜4 時間（検証含む）
- 事前通知: 1 週間前にユーザーへ通知

4.2 Helm 升级流程

# 1. メンテナンスモード（任意: Ingress でメンテナンスページを表示）
kubectl apply -f maintenance-ingress.yaml

# 2. 最新の Helm Chart を取得
helm repo update

# 3. アップグレード前の最終確認
helm diff upgrade dify dify/dify \
  -n dify-production \
  -f base-values.yaml \
  -f production-values.yaml \
  --version <新バージョン>

# 4. アップグレード実行
helm upgrade dify dify/dify \
  -n dify-production \
  -f base-values.yaml \
  -f production-values.yaml \
  --version <新バージョン> \
  --wait \
  --timeout 15m

# 5. Pod の起動状況を確認
kubectl get pods -n dify-production -w

# 6. マイグレーション完了を確認
kubectl logs -n dify-production deployment/dify-api --tail=100 | grep -i migration

# 7. 動作確認（ヘルスチェック）
curl -s https://api.dify.example.co.jp/health | jq .

# 8. メンテナンスモード解除
kubectl apply -f production-ingress.yaml

4.3 使用 Docker Compose 升级

Docker Compose环境下，按照以下顺序执行：docker compose down → git checkout <新タグ> → .env 差异确认/反映 → docker compose pull && docker compose up -d → 迁移日志确认。

5. 优先风险领域

5.1 数据库迁移

数据库架构更改是风险最高的领域。

リスクパターン:
1. 大規模テーブルへのカラム追加 → ロック時間の延長
2. インデックスの再構築 → 一時的なクエリ遅延
3. データ変換を伴うマイグレーション → 実行時間の予測困難
4. 複数マイグレーションの連鎖 → 中間での失敗時の復旧が複雑

对策：

使用与生产环境相同的数据量测量临时环境中的迁移时间
在执行迁移之前始终进行数据库备份
对于大规模迁移，确保更长的维护窗口

5.2 API 兼容性

如果外部系统使用Dify API，请注意以下更改。

更改类型	影响	行动
更改端点	API调用失败	更新链接系统的 URL
更改请求参数	拒绝请求	修改合作伙伴系统请求结构
更改响应格式	解析处理错误	修正联动系统的响应处理
认证方式变更	身份验证错误	兼容新的认证方式
更改速率限制	节流	调整通话频率

升级后，为聊天完成 API (/v1/chat-messages) 和工作流程执行 API (/v1/workflows/run) 准备操作检查脚本，并在临时环境和生产环境中执行它们。

5.3 插件/提供商兼容性

確認すべき項目:
- Plugin Daemon のバージョン要件
- 利用中のモデルプロバイダ（OpenAI, Anthropic, Azure OpenAI 等）の互換性
- カスタムツールの動作
- Vector DB（Qdrant, Weaviate, Milvus 等）のクライアントバージョン

6. 回滚策略

6.1 回滚决策标准

情况	判断	原因
Pod 无法启动	立即回滚	全面停止服务
数据库迁移失败	立即回滚	数据不一致风险
关键功能不起作用	30分钟内决定	违反 SLA 的风险
轻微的 UI 问题	无需回滚	等待下个版本修复
性能恶化	根据情况确定	先查明原因

6.2 使用 Helm 回滚

# Helm のリリース履歴を確認
helm history dify -n dify-production

# 直前のリビジョンにロールバック
helm rollback dify <前のリビジョン番号> -n dify-production --wait

# ロールバック後の確認
kubectl get pods -n dify-production
curl -s https://api.dify.example.co.jp/health | jq .

6.3 数据库回滚

仅使用 Helm 无法完成数据库迁移后的回滚。

# 1. Dify の全 Pod を停止
kubectl scale deployment --all --replicas=0 -n dify-production

# 2. PostgreSQL をバックアップから復元
pg_restore -h <DB_HOST> -U <DB_USER> -d dify_production \
  --clean --if-exists \
  -F c dify_backup_YYYYMMDD_HHMMSS.dump

# 3. 旧バージョンにロールバック
helm rollback dify <前のリビジョン番号> -n dify-production --wait

# 4. Pod の起動を確認
kubectl get pods -n dify-production -w

# 5. 動作確認
curl -s https://api.dify.example.co.jp/health | jq .

6.4 无法回滚的情况

如果迁移涉及数据转换或者外部链接目标已更改为新的 API，则回滚将很困难。在这种情况下，解决方案是使用“向前修复”——在新版本中修复问题，而不是恢复到以前的版本。

7. 支持版本跳转

作为一般规则，一次升级一个步骤 (v3.5.0 → v3.6.0 → v3.7.0)。如果必须跳过它，请查看中间版本的所有发行说明，并在临时环境中使用生产数据进行完整的演练。

8.升级后后续

升级后一周，重点监控API响应时间、错误率、Pod重启次数、DB连接数、内存使用情况。

8.1 升级后检查清单

所有 Pod 均稳定处于 Running 状态
数据库迁移已成功完成
现有应用程序运行正常
工作流程/代理按预期运行
知识库搜索工作正常。
外部API链接工作正常。
许可证被正确识别
SSO登录工作正常
文件上传工作正常。
管理控制台正常显示。
错误日志中没有异常模式。
性能指标在可接受的范围内
Ledger（版本信息）已更新
向用户发送升级完成通知

9. 总结

Dify Enterprise 升级包含四个阶段：计划→验证→执行→验证。五个最重要的原则是：

请务必阅读发行说明：步骤可能因版本而异
进行备份：三件套：数据库、对象存储和配置文件
一定要通过分期验证：在接近实际数据的环境中进行演练
提前准备回滚过程：记录恢复数据库快照的步骤。
增强升级后监控：密切监控指标和日志一周

“先升级再考虑”是你最应该避免的做法。安全升级意味着在运行之前清除所有迁移、兼容性检查和回滚路径。

Keyboard shortcuts

MKC — Dify Japan 内容体系