バージョンアップグレード注意事項 – マイグレーション・互換性検証・ロールバック戦略の実践ガイド

Dify Enterprise のアップグレードは「イメージを差し替えて再起動する」だけの作業ではない。データベースマイグレーション、設定ファイルの変更、依存コンポーネントのバージョン整合性、API の互換性 – これらが同時に変化するため、事前準備なしのアップグレードは本番障害に直結する。

公式ドキュメントでも “upgrade steps may vary between releases” と明記されており、バージョンごとに異なる手順の確認が必須事項として位置づけられている。本記事では、日本企業の運用チームが安全にアップグレードを実施するための包括的なガイドラインを提供する。

1. アップグレードの全体像

1.1 アップグレードで変化する 3 つの要素

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 アップグレードの影響範囲

2. アップグレード前の準備（Pre-Upgrade）

2.1 Release Note の精読

アップグレードの最初のステップは、対象バージョンの Release Note を隅々まで読むことである。

確認すべきポイント:

• Breaking Changes: 既存機能の非互換変更
• Deprecations: 廃止予定の機能やパラメータ
• Migration Notes: データベースマイグレーションの特記事項
• New Configuration: 追加された設定項目
• Known Issues: 既知の不具合

# 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 の変更パターン:

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 ステージング検証チェックリスト

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. 複数マイグレーションの連鎖 → 中間での失敗時の復旧が複雑

対策:

• ステージング環境で本番と同等のデータ量でマイグレーション時間を計測する
• マイグレーション実行前に必ず DB バックアップを取得する
• 大規模マイグレーションの場合はメンテナンスウィンドウを長めに確保する

5.2 API 互換性

外部システムが Dify API を利用している場合、以下の変更に注意する。

アップグレード後に Chat Completion API (/v1/chat-messages) と Workflow 実行 API (/v1/workflows/run) の動作確認スクリプトを用意し、ステージング・本番の両環境で実行する。

5.3 プラグイン・Provider の互換性

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

6. ロールバック戦略

6.1 ロールバック判断基準

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 データベースのロールバック

DB マイグレーションが実行された後のロールバックは、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 に変更済みの場合はロールバックが困難になる。このような場合は「前方修正（Forward Fix）」– 旧バージョンに戻すのではなく新バージョン上で問題を修正する – で対応する。

7. バージョンスキップへの対応

原則として一段階ずつアップグレードする（v3.5.0 → v3.6.0 → v3.7.0）。やむを得ずスキップする場合は、中間バージョンの Release Note をすべて確認し、ステージング環境で本番データを使った完全なリハーサルを実施する。

8. アップグレード後のフォローアップ

アップグレード後 1 週間は、API レスポンスタイム・エラー率・Pod 再起動回数・DB コネクション数・メモリ使用率を重点的に監視する。

8.1 アップグレード後チェックリスト

• 全 Pod が Running 状態で安定している
• DB マイグレーションが正常に完了している
• 既存アプリケーションが正常に動作している
• Workflow / Agent が期待どおり実行される
• ナレッジベースの検索が正常に動作している
• 外部 API 連携が正常に機能している
• License が正しく認識されている
• SSO ログインが正常に機能している
• ファイルアップロードが正常に動作している
• 管理コンソールが正常に表示されている
• エラーログに異常なパターンが出ていない
• パフォーマンスメトリクスが許容範囲内
• 台帳（バージョン情報）を更新済み
• ユーザーへのアップグレード完了通知を送信済み

9. まとめ

Dify Enterprise のアップグレードは「計画 → 検証 → 実行 → 確認」の 4 フェーズで構成される。最も重要な原則は以下の 5 つである。

1. Release Note を必ず読む: バージョンごとに手順が異なる可能性がある
2. バックアップを絶対に取る: DB・オブジェクトストレージ・設定ファイルの 3 点セット
3. ステージングで必ず検証する: 本番データに近い環境でリハーサルを実施する
4. ロールバック手順を事前に用意する: DB スナップショットの復元手順まで含めて文書化する
5. アップグレード後の監視を強化する: 1 週間はメトリクスとログを注意深く監視する

「先にアップグレードしてから考える」は最も避けるべきアプローチである。安全なアップグレードとは、実行する前にマイグレーション・互換性検証・ロールバックパスをすべて明確にしておくことである。