なぜ「image tag だけ更新」では危険なのか #

バージョン差分が大きい場合、Dify は単純なコンテナイメージの更新だけでは吸収できないことがあります。 実際に差分を見比べると、今回の更新では次のようなポイントがありました。

今回のアップグレード方針 #

1. まず docker/volumes を含めてフルバックアップを取得する
2. 公式の v1.13.3 を別ディレクトリに取得して、差分の基準を作る
3. docker-compose.yaml は公式版に置き換える
4. .env と TLS マウントなど、環境依存の設定だけを戻す
5. Sandbox の設定ファイルを新しい前提に合わせる
6. 起動前に docker compose config で構文検証する
7. 起動後は UI だけでなく、Knowledge / Plugin / Code 実行まで確認する

1. まずはバックアップを取る #

いちばん大事なのは、更新前の compose と volumes を戻せる状態にしておくことです。 特に 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 つを見比べると、 今回の更新で何を吸収しなければならないのかが把握しやすくなります。

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

4. 環境依存の設定を戻す #

公式 compose を採用したあと、実運用に必要な設定だけを overlay するイメージで戻します。 今回の環境では、主に次のような項目が重要でした。

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

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 実行が成功する
• Plugin の有効化・実行が成功する
• HTTPS 配信と証明書参照が問題ない

今回のように周辺コンポーネントの差分が大きい更新では、 UI が開くことと実運用で必要な機能がすべて動くことは別問題です。 利用中の主要機能に応じた確認項目を最初から決めておくと、切り戻し判断もしやすくなります。

ハマりどころまとめ #

今回の学び #

長く運用している Dify 環境ほど、アップグレード時に効いてくるのは「バージョン番号」よりも「蓄積した独自差分」です。 今回あらためて感じたのは、公式 compose をなるべく汚さず、環境依存の設定は overlay として管理するほうが、 その後のアップグレードも障害対応も圧倒的に楽になる、ということでした。

もし現行環境が古いバージョンのまま安定稼働しているなら、更新前に次の 3 点だけでも整理しておくとかなり進めやすくなります。

• 公式由来の設定と、自社固有の設定を分けて棚卸しする
• ロールバック可能なバックアップを必ず取る
• 起動確認ではなく、主要機能の確認項目を先に決めておく