From a5ad75d90a0e7093d1f7530b721fc3b3327ad1f2 Mon Sep 17 00:00:00 2001 From: Duda Nogueira Date: Wed, 12 Aug 2026 19:22:22 -0300 Subject: [PATCH 1/3] docs: add weaviate server upgrade path guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The existing v4 migration guide stops at server 1.27, but Dify now bundles 1.39 (langgenius/dify#38214). Existing deployments cannot jump that gap in one step: Weaviate does not test or support skipping minor versions. Adds a sibling page with the one-minor-at-a-time ladder and the two operational details that decide whether vectors survive it — graceful shutdown, which a hard kill silently costs you in HNSW recall, and the post-restart index-mount race. Cross-links both directions with the v4 page. en, zh and ja, with nav mirrored across all three sections. --- docs.json | 9 +- .../weaviate-server-migration-path.mdx | 167 +++++++++++++++++ .../troubleshooting/weaviate-v4-migration.mdx | 4 + .../weaviate-server-migration-path.mdx | 169 ++++++++++++++++++ .../troubleshooting/weaviate-v4-migration.mdx | 4 + .../weaviate-server-migration-path.mdx | 169 ++++++++++++++++++ .../troubleshooting/weaviate-v4-migration.mdx | 4 + 7 files changed, 523 insertions(+), 3 deletions(-) create mode 100644 en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx create mode 100644 ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx create mode 100644 zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx diff --git a/docs.json b/docs.json index 9e944edcf..ccc06c78e 100644 --- a/docs.json +++ b/docs.json @@ -736,7 +736,8 @@ "en/self-host/deploy/troubleshooting/docker-issues", "en/self-host/deploy/troubleshooting/integrations", "en/self-host/deploy/troubleshooting/storage-and-migration", - "en/self-host/deploy/troubleshooting/weaviate-v4-migration" + "en/self-host/deploy/troubleshooting/weaviate-v4-migration", + "en/self-host/deploy/troubleshooting/weaviate-server-migration-path" ], "icon": "wrench" } @@ -2128,7 +2129,8 @@ "zh/self-host/deploy/troubleshooting/docker-issues", "zh/self-host/deploy/troubleshooting/integrations", "zh/self-host/deploy/troubleshooting/storage-and-migration", - "zh/self-host/deploy/troubleshooting/weaviate-v4-migration" + "zh/self-host/deploy/troubleshooting/weaviate-v4-migration", + "zh/self-host/deploy/troubleshooting/weaviate-server-migration-path" ], "icon": "wrench" } @@ -3520,7 +3522,8 @@ "ja/self-host/deploy/troubleshooting/docker-issues", "ja/self-host/deploy/troubleshooting/integrations", "ja/self-host/deploy/troubleshooting/storage-and-migration", - "ja/self-host/deploy/troubleshooting/weaviate-v4-migration" + "ja/self-host/deploy/troubleshooting/weaviate-v4-migration", + "ja/self-host/deploy/troubleshooting/weaviate-server-migration-path" ], "icon": "wrench" } diff --git a/en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx b/en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx new file mode 100644 index 000000000..b5034b5c1 --- /dev/null +++ b/en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx @@ -0,0 +1,167 @@ +--- +title: Weaviate Server Upgrade Path +description: How to move a self-hosted Weaviate server across minor versions without losing vector data +--- + +Dify's bundled Weaviate image moved from `1.27.0` to `1.39.0`. Deploy Dify fresh and you get the new version, so nothing here applies to you. + +If you already run Weaviate on an existing data volume, you cannot jump straight to the new image. Weaviate neither tests nor supports skipping minor versions, and any release may carry an on-disk migration that expects the previous version to have run at least once. + +The supported path is to step through every minor release in order, landing on the latest patch of each. Below is that ladder, along with the two operational details that decide whether your vectors survive it. + + + Back up your Weaviate volume before you start. An upgrade that goes wrong partway through a twelve-step ladder is only recoverable if you have a snapshot to return to. + + +## Check Your Current Version + +```bash +curl -s -H "Authorization: Bearer " \ + http://localhost:8080/v1/meta | python3 -c "import sys, json; print(json.load(sys.stdin)['version'])" +``` + +If this already reports `1.39.x`, you are done. Anything lower tells you where to start on the ladder. + +## Back Up Your Data + +For a Docker deployment, the simplest backup is an offline copy of the volume. Stop Weaviate first so the copy is consistent: + +```bash +cd docker +docker compose stop weaviate +sudo cp -r ./volumes/weaviate ./volumes/weaviate_backup_$(date +%Y%m%d) +``` + +In production, prefer Weaviate's [backup module](https://docs.weaviate.io/deploy/configuration/backups) writing to S3, GCS, or Azure. It produces a restorable snapshot rather than a raw directory copy, and it can run against a live instance. The local filesystem backend is for development only. + +## Upgrade One Minor at a Time + +Move through every minor release in order, always landing on that minor's latest patch. The versions below were current at the time of writing; check for newer patches before you start, and prefer them. + +| Step | Image tag | +|:-----|:----------| +| 0 (current) | `cr.weaviate.io/semitechnologies/weaviate:1.27.x` | +| 1 | `cr.weaviate.io/semitechnologies/weaviate:1.27.27` | +| 2 | `cr.weaviate.io/semitechnologies/weaviate:1.28.16` | +| 3 | `cr.weaviate.io/semitechnologies/weaviate:1.29.11` | +| 4 | `cr.weaviate.io/semitechnologies/weaviate:1.30.23` | +| 5 | `cr.weaviate.io/semitechnologies/weaviate:1.31.22` | +| 6 | `cr.weaviate.io/semitechnologies/weaviate:1.32.27` | +| 7 | `cr.weaviate.io/semitechnologies/weaviate:1.33.18` | +| 8 | `cr.weaviate.io/semitechnologies/weaviate:1.34.20` | +| 9 | `cr.weaviate.io/semitechnologies/weaviate:1.35.23` | +| 10 | `cr.weaviate.io/semitechnologies/weaviate:1.36.23` | +| 11 | `cr.weaviate.io/semitechnologies/weaviate:1.37.14` | +| 12 | `cr.weaviate.io/semitechnologies/weaviate:1.38.9` | +| 13 | `cr.weaviate.io/semitechnologies/weaviate:1.39.0` | + +Stepping one minor at a time also limits your blast radius. When a rung misbehaves, you roll back a single version and know exactly which release caused it, instead of bisecting a twelve-version jump. + + + Staying close to the newest release keeps you in the fix window. Weaviate backports bug and security fixes to the latest patch of the newest minor and roughly the three minors before it, so a deployment more than about three minors behind stops receiving them. Revisit periodically after this migration and move to the current patch. + + +## Upgrade with Docker Compose + +Dify pins the Weaviate image in `docker/docker-compose.yaml`, `docker/docker-compose.middleware.yaml`, and `docker/docker-compose-template.yaml`. Edit the file you deploy with, then repeat the loop below for each rung. + + + + Change the `weaviate` service to the next minor's latest patch, for example `image: cr.weaviate.io/semitechnologies/weaviate:1.28.16`. + + + ```bash + cd docker + docker compose stop weaviate + ``` + + Never use `docker kill` or `docker rm -f` here. See [Stop Weaviate Gracefully](#stop-weaviate-gracefully) for what a hard kill costs you. + + + ```bash + docker compose up -d weaviate + ``` + + + Confirm the reported version, then check that data and search both work, as described in [Verify Each Step](#verify-each-step). Only then continue to the next rung. + + + +If you run Weaviate through `docker-compose.middleware.yaml` while developing from source, the same loop applies with the file named explicitly: + +```bash +cd docker +docker compose -f docker-compose.middleware.yaml stop weaviate +docker compose -f docker-compose.middleware.yaml --profile weaviate up -d weaviate +``` + +## Stop Weaviate Gracefully + +This is the single detail most likely to cost you data, and it is easy to get wrong. + +Weaviate holds its HNSW vector index in memory and flushes it to disk on a clean shutdown. When the container is hard-killed—`docker kill`, `docker rm -f`, an out-of-memory kill, or a stop that exceeds Docker's grace period—the vector index commit log on disk can be left incomplete. + +The failure that follows is quiet, which is what makes it dangerous. Your objects survive intact: the count is correct and fetching an object by ID returns its exact vector. But the HNSW graph is truncated, so vector search silently recalls only a subset of them until the index rebuilds. In testing, a hard kill between versions left a ten-object collection returning three results from `near_vector` while the object count still read ten. + +Use `docker compose stop` or `docker compose down`, both of which send SIGTERM, and give the process enough time to finish flushing. Large indexes need a longer grace period than Docker's default: + +```bash +docker compose stop -t 120 weaviate +``` + +If you suspect a hard kill already happened, verify recall as described below rather than assuming the data is gone—the objects are still there, and the index recovers once rebuilt. + +## Wait for the Index to Mount After Each Restart + +On newer versions, `/v1/meta` answers a moment before per-collection indexes finish mounting. A query fired in that window fails with `tried to browse non-existing index for Vector_index__Node`. + +This is transient and needs no action beyond patience. Wait a few seconds after each restart before relying on search. If you script health checks, poll until a trivial query succeeds instead of trusting `/v1/meta` alone. + +## Verify Each Step + +Confirm that data survived and that search works. A server that boots is not evidence of a healthy index. + +```bash +KEY="" + +# Reported server version +curl -s -H "Authorization: Bearer $KEY" http://localhost:8080/v1/meta \ + | python3 -c "import sys, json; print('version', json.load(sys.stdin)['version'])" + +# Collections are present +curl -s -H "Authorization: Bearer $KEY" http://localhost:8080/v1/schema \ + | python3 -c "import sys, json; print([c['class'] for c in json.load(sys.stdin)['classes']])" + +# Object count for one collection +curl -s -H "Authorization: Bearer $KEY" \ + "http://localhost:8080/v1/objects?class=&limit=1" \ + | python3 -c "import sys, json; print('totalResults', json.load(sys.stdin).get('totalResults'))" +``` + +Then open a knowledge base in Dify and run a test retrieval. Getting chunks back confirms the vector index survived, which the object count alone does not tell you. + +## Roll Back a Failed Step + +Restore the backup and return the image tag to the last rung that worked: + +```bash +cd docker +docker compose stop weaviate +sudo rm -rf ./volumes/weaviate +sudo cp -r ./volumes/weaviate_backup_YYYYMMDD ./volumes/weaviate +docker compose up -d weaviate +``` + + + Rolling the image tag back without restoring the data is not safe. Once a newer version has written to the volume, an older binary may not read it. + + +## What Does Not Change + +Your collections keep their existing layout, so no re-indexing is required and your knowledge bases keep working as they are. Dify stores each dataset as a `Vector_index__Node` collection with a self-provided named vector `default` using cosine distance, and that structure is identical before and after the upgrade. + +The Python `weaviate-client` also needs no attention. Version `4.22.0`, which current Dify ships, works against every server version on the ladder, so you can upgrade the server independently. + + + Upgrading from Weaviate 1.19 or older, or moving from client v3 to v4? Start with the [Weaviate v4 migration guide](/en/self-host/deploy/troubleshooting/weaviate-v4-migration), which covers the schema migration up to 1.27, then return here. + diff --git a/en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx b/en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx index 213a88ab1..70a8ae03e 100644 --- a/en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx +++ b/en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx @@ -4,6 +4,10 @@ title: Weaviate Migration Guide upgrading to Client v4 and Server 1.27+ > This guide explains how to migrate from Weaviate client v3 to v4.17.0 and upgrade your Weaviate server from version 1.19.0 to 1.27.0 or higher. This migration is required for Dify versions that include the weaviate-client v4 upgrade. + + Already on 1.27 and moving to a newer server? Current Dify bundles Weaviate 1.39, and getting there means stepping through the minor releases in order. See the [Weaviate server upgrade path](/en/self-host/deploy/troubleshooting/weaviate-server-migration-path) for the ladder. + + ## Overview Starting with **Dify v1.9.2**, the weaviate-client has been upgraded from v3 to v4.17.0. This upgrade brings significant performance improvements and better stability, but requires **Weaviate server version 1.27.0 or higher**. diff --git a/ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx b/ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx new file mode 100644 index 000000000..830ab80a7 --- /dev/null +++ b/ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx @@ -0,0 +1,169 @@ +--- +title: Weaviate サーバーのアップグレード経路 +description: セルフホスト Weaviate サーバーをベクトルデータを失わずにマイナーバージョン間で移行する方法 +--- + +> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/deploy/troubleshooting/weaviate-server-migration-path) を参照してください。 + +Dify に同梱される Weaviate イメージは `1.27.0` から `1.39.0` に更新されました。新規に Dify をデプロイする場合は新しいバージョンが使われるため、このページの内容は不要です。 + +既存のデータボリュームで Weaviate を運用している場合、新しいイメージへ直接移行することはできません。Weaviate はマイナーバージョンの飛び越しをテストも保証もしていません。各リリースにはディスク上のデータ移行が含まれることがあり、その移行は直前のバージョンが一度は起動していることを前提とします。 + +サポートされる手順は、マイナーリリースを順に 1 つずつ進め、それぞれの最新パッチで止めることです。以下にその手順一覧と、ベクトルが無事に残るかどうかを左右する 2 つの運用上の注意点を示します。 + + + 開始前に Weaviate のデータボリュームをバックアップしてください。10 段階を超える手順の途中で問題が起きた場合、スナップショットがなければ復旧できません。 + + +## 現在のバージョンの確認 + +```bash +curl -s -H "Authorization: Bearer " \ + http://localhost:8080/v1/meta | python3 -c "import sys, json; print(json.load(sys.stdin)['version'])" +``` + +すでに `1.39.x` が表示される場合、作業は不要です。それより低い場合は、その値が手順の開始地点になります。 + +## データのバックアップ + +Docker デプロイでは、ボリュームをオフラインでコピーする方法が最も簡単です。整合性を保つため、先に Weaviate を停止します。 + +```bash +cd docker +docker compose stop weaviate +sudo cp -r ./volumes/weaviate ./volumes/weaviate_backup_$(date +%Y%m%d) +``` + +本番環境では、S3、GCS、Azure に書き出す Weaviate の [バックアップモジュール](https://docs.weaviate.io/deploy/configuration/backups) を推奨します。ディレクトリの単純なコピーではなく復元可能なスナップショットが得られ、稼働中のインスタンスに対しても実行できます。ローカルファイルシステムのバックエンドは開発用途に限られます。 + +## マイナーバージョンごとのアップグレード + +すべてのマイナーリリースを順に進め、毎回そのマイナーの最新パッチで止めます。以下のバージョンは執筆時点のものです。開始前に新しいパッチが出ていないか確認し、あればそちらを使ってください。 + +| 手順 | イメージタグ | +|:-----|:-------------| +| 0（現在） | `cr.weaviate.io/semitechnologies/weaviate:1.27.x` | +| 1 | `cr.weaviate.io/semitechnologies/weaviate:1.27.27` | +| 2 | `cr.weaviate.io/semitechnologies/weaviate:1.28.16` | +| 3 | `cr.weaviate.io/semitechnologies/weaviate:1.29.11` | +| 4 | `cr.weaviate.io/semitechnologies/weaviate:1.30.23` | +| 5 | `cr.weaviate.io/semitechnologies/weaviate:1.31.22` | +| 6 | `cr.weaviate.io/semitechnologies/weaviate:1.32.27` | +| 7 | `cr.weaviate.io/semitechnologies/weaviate:1.33.18` | +| 8 | `cr.weaviate.io/semitechnologies/weaviate:1.34.20` | +| 9 | `cr.weaviate.io/semitechnologies/weaviate:1.35.23` | +| 10 | `cr.weaviate.io/semitechnologies/weaviate:1.36.23` | +| 11 | `cr.weaviate.io/semitechnologies/weaviate:1.37.14` | +| 12 | `cr.weaviate.io/semitechnologies/weaviate:1.38.9` | +| 13 | `cr.weaviate.io/semitechnologies/weaviate:1.39.0` | + +1 つずつ進めることで影響範囲も限定できます。ある段階で問題が起きても、戻すのは 1 バージョンだけで済み、原因となったリリースもすぐ特定できます。10 以上のバージョンをまたいだ切り分けは不要です。 + + + 最新に近い状態を保つことが修正を受け取り続ける条件です。Weaviate は不具合修正とセキュリティ修正を、最新マイナーとその直前 3 マイナー程度の最新パッチにのみバックポートします。3 マイナー以上遅れた環境はこれらの修正を受け取れなくなります。今回の移行後も定期的に確認し、その時点の最新パッチへ更新してください。 + + +## Docker Compose でのアップグレード + +Dify は `docker/docker-compose.yaml`、`docker/docker-compose.middleware.yaml`、`docker/docker-compose-template.yaml` の 3 か所で Weaviate のイメージを固定しています。実際にデプロイに使うファイルを編集し、各段階で次の手順を繰り返します。 + + + + `weaviate` サービスを次のマイナーの最新パッチに変更します。例：`image: cr.weaviate.io/semitechnologies/weaviate:1.28.16` + + + ```bash + cd docker + docker compose stop weaviate + ``` + + ここで `docker kill` や `docker rm -f` を使わないでください。強制終了の代償については [Weaviate の正常な停止](#weaviate-の正常な停止) を参照してください。 + + + ```bash + docker compose up -d weaviate + ``` + + + 報告されたバージョンを確認し、[各段階での確認](#各段階での確認) に従ってデータと検索が正常か調べます。問題がなければ次の段階へ進みます。 + + + +ソースからの開発時に `docker-compose.middleware.yaml` で Weaviate を動かしている場合も、ファイルを明示すれば同じ手順です。 + +```bash +cd docker +docker compose -f docker-compose.middleware.yaml stop weaviate +docker compose -f docker-compose.middleware.yaml --profile weaviate up -d weaviate +``` + +## Weaviate の正常な停止 + +データ損失につながりやすく、間違えやすいのがこの点です。 + +Weaviate は HNSW ベクトルインデックスをメモリ上に保持し、正常終了時にディスクへ書き出します。コンテナが強制終了された場合（`docker kill`、`docker rm -f`、メモリ不足による強制終了、Docker の猶予時間を超えた停止）、ディスク上のベクトルインデックスのコミットログが不完全なまま残ることがあります。 + +その後に起きる不具合は表面化しにくく、そこが危険です。オブジェクト自体は無傷で、件数も正しく、ID による取得では完全なベクトルが返ります。しかし HNSW グラフは途中で切れているため、インデックスが再構築されるまでベクトル検索は一部しか返しません。実際の検証では、バージョン間での強制終了により、10 件のコレクションが `near_vector` で 3 件しか返さない状態になりました。オブジェクト件数は 10 のままです。 + +`docker compose stop` または `docker compose down` を使ってください。どちらも SIGTERM を送ります。書き出しが終わるまでの時間も確保します。インデックスが大きい場合、Docker の既定値より長い猶予時間が必要です。 + +```bash +docker compose stop -t 120 weaviate +``` + +すでに強制終了が起きた疑いがある場合は、データが失われたと決めつけず、以下の手順で再現率を確認してください。オブジェクトは残っており、インデックスの再構築後に復旧します。 + +## 再起動後のインデックスのマウント待ち + +新しいバージョンでは、コレクションごとのインデックスのマウントが終わる前に `/v1/meta` が応答します。この間にクエリを実行すると `tried to browse non-existing index for Vector_index__Node` というエラーで失敗します。 + +これは一時的な状態で、少し待つ以外の対応は不要です。再起動のたびに数秒待ってから検索を利用してください。ヘルスチェックをスクリプト化する場合は、`/v1/meta` だけを見るのではなく、簡単なクエリが成功するまでポーリングします。 + +## 各段階での確認 + +データが残っていることと、検索が動くことの両方を確認します。サーバーが起動しても、インデックスが健全である証拠にはなりません。 + +```bash +KEY="" + +# 報告されたサーバーバージョン +curl -s -H "Authorization: Bearer $KEY" http://localhost:8080/v1/meta \ + | python3 -c "import sys, json; print('version', json.load(sys.stdin)['version'])" + +# コレクションの存在 +curl -s -H "Authorization: Bearer $KEY" http://localhost:8080/v1/schema \ + | python3 -c "import sys, json; print([c['class'] for c in json.load(sys.stdin)['classes']])" + +# 単一コレクションのオブジェクト数 +curl -s -H "Authorization: Bearer $KEY" \ + "http://localhost:8080/v1/objects?class=&limit=1" \ + | python3 -c "import sys, json; print('totalResults', json.load(sys.stdin).get('totalResults'))" +``` + +続いて Dify でナレッジベースを開き、テスト検索を実行します。チャンクが返ってくればベクトルインデックスが残っていると判断できます。オブジェクト数だけでは、そこまでは分かりません。 + +## 失敗した段階のロールバック + +バックアップを復元し、イメージタグを最後に正常だった段階へ戻します。 + +```bash +cd docker +docker compose stop weaviate +sudo rm -rf ./volumes/weaviate +sudo cp -r ./volumes/weaviate_backup_YYYYMMDD ./volumes/weaviate +docker compose up -d weaviate +``` + + + データを復元せずにイメージタグだけを戻すのは安全ではありません。新しいバージョンが一度そのボリュームに書き込むと、古いバイナリでは読めなくなる場合があります。 + + +## 変更されない部分 + +コレクションの構成は変わらないため、再インデックスは不要で、ナレッジベースもそのまま使えます。Dify は各データセットを `Vector_index__Node` コレクションとして保存し、コサイン距離の名前付きベクトル `default` を自前で指定します。この構造はアップグレードの前後で同一です。 + +Python の `weaviate-client` についても対応は不要です。現行の Dify が同梱する `4.22.0` は一覧のすべてのサーバーバージョンで動作するため、サーバーだけを個別にアップグレードできます。 + + + Weaviate 1.19 以前からのアップグレード、またはクライアント v3 から v4 への移行を行う場合は、先に [Weaviate v4 移行ガイド](/ja/self-host/deploy/troubleshooting/weaviate-v4-migration) を参照してください。1.27 までのスキーマ移行を扱っています。その後このページに戻ってください。 + diff --git a/ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx b/ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx index 2a92f295c..e6bf48f6d 100644 --- a/ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx +++ b/ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx @@ -6,6 +6,10 @@ title: Weaviate 移行ガイド：クライアント v4 とサーバー 1.27+ > このガイドでは、Weaviate クライアント v3 から v4.17.0 への移行と、Weaviate サーバーをバージョン 1.19.0 から 1.27.0 以降にアップグレードする方法について説明します。この移行は、weaviate-client v4 アップグレードを含む Dify バージョンに必要です。 + + すでに 1.27 を使っていて、より新しいサーバーへ移行する場合、現行の Dify は Weaviate 1.39 を同梱しており、マイナーリリースを順に進める必要があります。手順の一覧は [Weaviate サーバーのアップグレード経路](/ja/self-host/deploy/troubleshooting/weaviate-server-migration-path) を参照してください。 + + ## 概要 **Dify v1.9.2** 以降、weaviate-client が v3 から v4.17.0 にアップグレードされました。このアップグレードにより、パフォーマンスが大幅に向上し、安定性が向上しますが、**Weaviate サーバーバージョン 1.27.0 以降**が必要です。 diff --git a/zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx b/zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx new file mode 100644 index 000000000..8faff8395 --- /dev/null +++ b/zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx @@ -0,0 +1,169 @@ +--- +title: Weaviate 服务器升级路径 +description: 如何跨小版本升级自托管 Weaviate 服务器而不丢失向量数据 +--- + +> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/deploy/troubleshooting/weaviate-server-migration-path)。 + +Dify 内置的 Weaviate 镜像已从 `1.27.0` 升级到 `1.39.0`。全新部署 Dify 会直接获得新版本，无需关注本文。 + +如果已在现有数据卷上运行 Weaviate，则不能直接跳到新镜像。Weaviate 既未测试也不支持跨小版本升级，任何一个版本都可能包含磁盘数据迁移，而这类迁移要求上一个版本至少运行过一次。 + +受支持的升级方式是按顺序逐个小版本推进，每次都升到该小版本的最新补丁版本。下面给出完整阶梯，以及决定向量能否存活的两个运维细节。 + + + 开始前先备份 Weaviate 数据卷。十几级阶梯中途出问题时，只有手上有快照才能恢复。 + + +## 检查当前版本 + +```bash +curl -s -H "Authorization: Bearer " \ + http://localhost:8080/v1/meta | python3 -c "import sys, json; print(json.load(sys.stdin)['version'])" +``` + +若返回结果已是 `1.39.x`，说明无需升级。低于该版本，则以返回值作为阶梯起点。 + +## 备份数据 + +Docker 部署最简单的备份方式是离线复制数据卷。先停止 Weaviate，确保副本一致： + +```bash +cd docker +docker compose stop weaviate +sudo cp -r ./volumes/weaviate ./volumes/weaviate_backup_$(date +%Y%m%d) +``` + +生产环境建议使用 Weaviate 的 [备份模块](https://docs.weaviate.io/deploy/configuration/backups) 写入 S3、GCS 或 Azure。它生成的是可还原的快照，而非原始目录副本，且可对运行中的实例执行。本地文件系统后端仅适用于开发环境。 + +## 逐个小版本升级 + +按顺序走完每个小版本，每次都停在该小版本的最新补丁版本上。下表版本号为撰写时的最新值，开始前先确认是否有更新的补丁，有则优先使用。 + +| 步骤 | 镜像标签 | +|:-----|:---------| +| 0（当前） | `cr.weaviate.io/semitechnologies/weaviate:1.27.x` | +| 1 | `cr.weaviate.io/semitechnologies/weaviate:1.27.27` | +| 2 | `cr.weaviate.io/semitechnologies/weaviate:1.28.16` | +| 3 | `cr.weaviate.io/semitechnologies/weaviate:1.29.11` | +| 4 | `cr.weaviate.io/semitechnologies/weaviate:1.30.23` | +| 5 | `cr.weaviate.io/semitechnologies/weaviate:1.31.22` | +| 6 | `cr.weaviate.io/semitechnologies/weaviate:1.32.27` | +| 7 | `cr.weaviate.io/semitechnologies/weaviate:1.33.18` | +| 8 | `cr.weaviate.io/semitechnologies/weaviate:1.34.20` | +| 9 | `cr.weaviate.io/semitechnologies/weaviate:1.35.23` | +| 10 | `cr.weaviate.io/semitechnologies/weaviate:1.36.23` | +| 11 | `cr.weaviate.io/semitechnologies/weaviate:1.37.14` | +| 12 | `cr.weaviate.io/semitechnologies/weaviate:1.38.9` | +| 13 | `cr.weaviate.io/semitechnologies/weaviate:1.39.0` | + +逐级升级还能缩小影响范围。某一级出问题时，只需回退一个版本，并且能立刻确定是哪个版本引入的问题，不必在十几个版本的跨度里二分排查。 + + + 紧跟最新版本才能持续拿到修复。Weaviate 只把缺陷和安全修复回合到最新小版本及其之前约三个小版本的最新补丁上，落后超过三个小版本的部署将不再收到这些修复。本次迁移完成后也要定期回看，及时升到当前补丁版本。 + + +## 使用 Docker Compose 升级 + +Dify 在 `docker/docker-compose.yaml`、`docker/docker-compose.middleware.yaml` 和 `docker/docker-compose-template.yaml` 三处固定 Weaviate 镜像版本。修改实际部署所用的文件，然后对每一级重复下面的循环。 + + + + 把 `weaviate` 服务改成下一个小版本的最新补丁，例如 `image: cr.weaviate.io/semitechnologies/weaviate:1.28.16`。 + + + ```bash + cd docker + docker compose stop weaviate + ``` + + 切勿在此使用 `docker kill` 或 `docker rm -f`。强杀的代价详见 [优雅停止 Weaviate](#优雅停止-weaviate)。 + + + ```bash + docker compose up -d weaviate + ``` + + + 先确认上报的版本号，再按 [每一步都要验证](#每一步都要验证) 检查数据与检索是否正常，确认无误后才进入下一级。 + + + +如果开发时通过 `docker-compose.middleware.yaml` 运行 Weaviate，同样的循环只需显式指定文件： + +```bash +cd docker +docker compose -f docker-compose.middleware.yaml stop weaviate +docker compose -f docker-compose.middleware.yaml --profile weaviate up -d weaviate +``` + +## 优雅停止 Weaviate + +这是最容易丢数据、也最容易做错的一个细节。 + +Weaviate 把 HNSW 向量索引放在内存中，正常关闭时才会刷写到磁盘。容器被强制杀死时（`docker kill`、`docker rm -f`、内存溢出被杀，或停止超过 Docker 的宽限期），磁盘上的向量索引提交日志可能残缺不全。 + +随之而来的故障非常隐蔽，这正是它危险的地方。对象本身完好无损：数量正确，按 ID 取回对象也能拿到完整向量。但 HNSW 图是截断的，向量检索会悄悄只召回其中一部分，直到索引重建完成。实测中，版本之间的一次强杀让一个含 10 个对象的集合在 `near_vector` 检索时只返回 3 条，而对象计数仍显示 10。 + +使用 `docker compose stop` 或 `docker compose down`，两者都发送 SIGTERM，并留出足够时间完成刷写。索引较大时，需要比 Docker 默认值更长的宽限期： + +```bash +docker compose stop -t 120 weaviate +``` + +若怀疑已经发生过强杀，按下文验证召回情况，不必假定数据已丢失：对象仍然在，索引重建后即可恢复。 + +## 重启后等待索引挂载 + +在较新版本上，`/v1/meta` 会在各集合索引挂载完成前就先行响应。在这个窗口内发起查询会失败，报错为 `tried to browse non-existing index for Vector_index__Node`。 + +这是暂时现象，除了稍等片刻无需其他处理。每次重启后等待几秒再依赖检索功能。如果要编写健康检查脚本，应轮询到一个简单查询成功为止，而不是只看 `/v1/meta`。 + +## 每一步都要验证 + +既要确认数据还在，也要确认检索可用。服务能启动并不代表索引是健康的。 + +```bash +KEY="" + +# 上报的服务器版本 +curl -s -H "Authorization: Bearer $KEY" http://localhost:8080/v1/meta \ + | python3 -c "import sys, json; print('version', json.load(sys.stdin)['version'])" + +# 集合是否存在 +curl -s -H "Authorization: Bearer $KEY" http://localhost:8080/v1/schema \ + | python3 -c "import sys, json; print([c['class'] for c in json.load(sys.stdin)['classes']])" + +# 单个集合的对象数量 +curl -s -H "Authorization: Bearer $KEY" \ + "http://localhost:8080/v1/objects?class=&limit=1" \ + | python3 -c "import sys, json; print('totalResults', json.load(sys.stdin).get('totalResults'))" +``` + +随后在 Dify 中打开一个知识库，执行一次测试检索。能召回分段才说明向量索引存活，仅凭对象计数看不出这一点。 + +## 回滚失败的升级 + +还原备份，并把镜像标签退回到最后一个正常的级别： + +```bash +cd docker +docker compose stop weaviate +sudo rm -rf ./volumes/weaviate +sudo cp -r ./volumes/weaviate_backup_YYYYMMDD ./volumes/weaviate +docker compose up -d weaviate +``` + + + 只回退镜像标签而不还原数据并不安全。新版本一旦写过该数据卷，旧版本程序可能就读不了了。 + + +## 保持不变的部分 + +集合结构保持原样，因此无需重建索引，知识库照常可用。Dify 把每个数据集存为 `Vector_index__Node` 集合，使用自带命名向量 `default` 和余弦距离，升级前后完全一致。 + +Python `weaviate-client` 同样无需处理。当前 Dify 附带的 `4.22.0` 可与阶梯上的所有服务器版本配合工作，因此服务器可以单独升级。 + + + 如果是从 Weaviate 1.19 或更早版本升级，或要从客户端 v3 迁移到 v4，先参考 [Weaviate v4 迁移指南](/zh/self-host/deploy/troubleshooting/weaviate-v4-migration)，它覆盖到 1.27 为止的 schema 迁移，之后再回到本文。 + diff --git a/zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx b/zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx index d7fc65cff..473b0c2af 100644 --- a/zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx +++ b/zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx @@ -6,6 +6,10 @@ title: Weaviate 迁移指南：升级到客户端 v4 和服务器 1.27+ > 本指南说明如何从 Weaviate 客户端 v3 迁移到 v4.17.0，并将 Weaviate 服务器从 1.19.0 版本升级到 1.27.0 或更高版本。此迁移适用于包含 weaviate-client v4 升级的 Dify 版本。 + + 已在 1.27 上，想升到更新的服务器版本？当前 Dify 内置 Weaviate 1.39，升级过程需要按顺序逐个小版本推进。完整阶梯详见 [Weaviate 服务器升级路径](/zh/self-host/deploy/troubleshooting/weaviate-server-migration-path)。 + + ## 概述 从 **Dify v1.9.2** 开始，weaviate-client 已从 v3 升级到 v4.17.0。此升级带来了显著的性能改进和更好的稳定性，但需要 **Weaviate 服务器版本 1.27.0 或更高版本**。 From 2810263d3d78cb9e51c809bb96dcd52633332775 Mon Sep 17 00:00:00 2001 From: Duda Nogueira Date: Wed, 12 Aug 2026 19:29:15 -0300 Subject: [PATCH 2/3] fix: correct weaviate client versions in the compatibility matrix The matrix listed v4.17.0 for every release from 1.9.2 onward and capped server coverage at "tested up to 1.33.1". Both are stale: the client moved to 4.20.4 in 1.13.1 and 4.20.5 in 1.14.0, and the server bound was a moving target that went out of date rather than a real limit. Splits the client rows at their actual boundaries, replaces the tested-up-to note with the reason the server column has no upper bound, and points readers at the server upgrade path for external instances. Also replaces the hardcoded `pip install weaviate-client==4.17.0` fix with `uv sync`, so source installs get whatever version their checkout pins instead of being pinned to a version Dify stopped shipping. --- .../troubleshooting/weaviate-v4-migration.mdx | 16 +++++++++------- .../troubleshooting/weaviate-v4-migration.mdx | 10 ++++++---- .../troubleshooting/weaviate-v4-migration.mdx | 10 ++++++---- 3 files changed, 21 insertions(+), 15 deletions(-) diff --git a/en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx b/en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx index 70a8ae03e..bdfb7a962 100644 --- a/en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx +++ b/en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx @@ -50,15 +50,18 @@ The weaviate-client v4 introduces several breaking changes: ## Version Compatibility Matrix -| Dify Version | Weaviate-client Version | Compatible Weaviate Server Versions | -| ------------ | ----------------------- | ----------------------------------- | -| ≤ 1.9.1 | v3.x | 1.19.0 - 1.26.x | -| ≥ 1.9.2 | v4.17.0 | 1.27.0+ (tested up to 1.33.1) | +| Dify Version | Weaviate-client Version | Compatible Weaviate Server Versions | +| -------------- | ----------------------- | ----------------------------------- | +| ≤ 1.9.1 | v3.x | 1.19.0 - 1.26.x | +| 1.9.2 - 1.13.0 | v4.17.0 | 1.27.0 or higher | +| 1.13.1 - 1.16.x | v4.20.x | 1.27.0 or higher | This migration applies to any Dify version using weaviate-client v4.17.0 or higher. +The server column has no upper bound because Dify pins the client and the bundled server together. If you point Dify at an external Weaviate instead, keep it at 1.27 or higher, and upgrade it one minor at a time using the [Weaviate server upgrade path](/en/self-host/deploy/troubleshooting/weaviate-server-migration-path). + Weaviate server version 1.19.0 was released over a year ago and is now outdated. Upgrading to 1.27.0+ provides access to numerous improvements in performance, stability, and features. @@ -629,9 +632,8 @@ docker compose pull docker compose down docker compose up -d -# For source installations -pip uninstall weaviate-client -pip install weaviate-client==4.17.0 +# For source installations, install the version your Dify checkout pins +uv sync --project api --group vdb-weaviate ``` ### Issue: Connection Refused on gRPC Port (50051) diff --git a/ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx b/ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx index e6bf48f6d..b59932428 100644 --- a/ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx +++ b/ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx @@ -55,12 +55,15 @@ weaviate-client v4 では、いくつかの破壊的変更が導入されてい | Dify バージョン | Weaviate-client バージョン | 互換性のある Weaviate サーバーバージョン | | ------------ | ----------------------- | ----------------------------------- | | ≤ 1.9.1 | v3.x | 1.19.0 - 1.26.x | -| ≥ 1.9.2 | v4.17.0 | 1.27.0+（1.33.1 までテスト済み） | +| 1.9.2 - 1.13.0 | v4.17.0 | 1.27.0 以降 | +| 1.13.1 - 1.16.x | v4.20.x | 1.27.0 以降 | この移行は、weaviate-client v4.17.0 以降を使用するすべての Dify バージョンに適用されます。 +サーバー列に上限がないのは、Dify がクライアントと同梱サーバーのバージョンをまとめて固定しているためです。外部の Weaviate に接続する場合は 1.27.0 以降を維持し、[Weaviate サーバーのアップグレード経路](/ja/self-host/deploy/troubleshooting/weaviate-server-migration-path) に従ってマイナーバージョンごとにアップグレードしてください。 + Weaviate サーバーバージョン 1.19.0 は 1 年以上前にリリースされ、現在は古くなっています。1.27.0+ にアップグレードすると、パフォーマンス、安定性、機能の数多くの改善にアクセスできます。 @@ -630,9 +633,8 @@ docker compose pull docker compose down docker compose up -d -# ソースインストールの場合 -pip uninstall weaviate-client -pip install weaviate-client==4.17.0 +# ソースインストールの場合、Dify のコードが固定しているバージョンをインストールします +uv sync --project api --group vdb-weaviate ``` ### 問題：gRPC ポート (50051) で接続拒否 diff --git a/zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx b/zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx index 473b0c2af..4e5c96979 100644 --- a/zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx +++ b/zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx @@ -55,12 +55,15 @@ weaviate-client v4 引入了几个破坏性变更： | Dify 版本 | Weaviate-client 版本 | 兼容的 Weaviate 服务器版本 | | ------------ | ----------------------- | ----------------------------------- | | ≤ 1.9.1 | v3.x | 1.19.0 - 1.26.x | -| ≥ 1.9.2 | v4.17.0 | 1.27.0+（已测试至 1.33.1） | +| 1.9.2 - 1.13.0 | v4.17.0 | 1.27.0 或更高版本 | +| 1.13.1 - 1.16.x | v4.20.x | 1.27.0 或更高版本 | 此迁移适用于任何使用 weaviate-client v4.17.0 或更高版本的 Dify 版本。 +服务器一列没有上限，因为 Dify 会把客户端和内置服务器版本一起固定。如果让 Dify 连接外部 Weaviate，需保持在 1.27.0 或更高版本，并按 [Weaviate 服务器升级路径](/zh/self-host/deploy/troubleshooting/weaviate-server-migration-path) 逐个小版本升级。 + Weaviate 服务器版本 1.19.0 在一年多前发布，现已过时。升级到 1.27.0+ 可访问性能、稳定性和功能方面的众多改进。 @@ -630,9 +633,8 @@ docker compose pull docker compose down docker compose up -d -# 对于源码安装 -pip uninstall weaviate-client -pip install weaviate-client==4.17.0 +# 对于源码安装，安装当前 Dify 代码固定的版本 +uv sync --project api --group vdb-weaviate ``` ### 问题：gRPC 端口 (50051) 连接被拒绝 From 1490b52ca876d61b50f491e37a1920dc0f3084ed Mon Sep 17 00:00:00 2001 From: Duda Nogueira Date: Wed, 12 Aug 2026 19:32:52 -0300 Subject: [PATCH 3/3] fix: drop hard-coded step counts and correct a zh phrasing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review feedback on #940: - The warning said "twelve-step ladder" and the blast-radius note said "twelve-version jump" while the table lists thirteen rungs. Both counts are now phrased so they stay correct if the ladder changes. - zh used 回合到 for backporting, which does not read as Chinese. Rewritten as 合入. Applied to ja as well, where the same counts appeared as 10 段階 and 10 以上のバージョン. --- .../troubleshooting/weaviate-server-migration-path.mdx | 4 ++-- .../troubleshooting/weaviate-server-migration-path.mdx | 4 ++-- .../troubleshooting/weaviate-server-migration-path.mdx | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx b/en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx index b5034b5c1..a34cdf4dd 100644 --- a/en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx +++ b/en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx @@ -10,7 +10,7 @@ If you already run Weaviate on an existing data volume, you cannot jump straight The supported path is to step through every minor release in order, landing on the latest patch of each. Below is that ladder, along with the two operational details that decide whether your vectors survive it. - Back up your Weaviate volume before you start. An upgrade that goes wrong partway through a twelve-step ladder is only recoverable if you have a snapshot to return to. + Back up your Weaviate volume before you start. An upgrade that goes wrong partway through the ladder is only recoverable if you have a snapshot to return to. ## Check Your Current Version @@ -55,7 +55,7 @@ Move through every minor release in order, always landing on that minor's latest | 12 | `cr.weaviate.io/semitechnologies/weaviate:1.38.9` | | 13 | `cr.weaviate.io/semitechnologies/weaviate:1.39.0` | -Stepping one minor at a time also limits your blast radius. When a rung misbehaves, you roll back a single version and know exactly which release caused it, instead of bisecting a twelve-version jump. +Stepping one minor at a time also limits your blast radius. When a rung misbehaves, you roll back a single version and know exactly which release caused it, instead of bisecting a jump that crossed every minor at once. Staying close to the newest release keeps you in the fix window. Weaviate backports bug and security fixes to the latest patch of the newest minor and roughly the three minors before it, so a deployment more than about three minors behind stops receiving them. Revisit periodically after this migration and move to the current patch. diff --git a/ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx b/ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx index 830ab80a7..bb1b906eb 100644 --- a/ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx +++ b/ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx @@ -12,7 +12,7 @@ Dify に同梱される Weaviate イメージは `1.27.0` から `1.39.0` に更 サポートされる手順は、マイナーリリースを順に 1 つずつ進め、それぞれの最新パッチで止めることです。以下にその手順一覧と、ベクトルが無事に残るかどうかを左右する 2 つの運用上の注意点を示します。 - 開始前に Weaviate のデータボリュームをバックアップしてください。10 段階を超える手順の途中で問題が起きた場合、スナップショットがなければ復旧できません。 + 開始前に Weaviate のデータボリュームをバックアップしてください。手順の途中で問題が起きた場合、スナップショットがなければ復旧できません。 ## 現在のバージョンの確認 @@ -57,7 +57,7 @@ sudo cp -r ./volumes/weaviate ./volumes/weaviate_backup_$(date +%Y%m%d) | 12 | `cr.weaviate.io/semitechnologies/weaviate:1.38.9` | | 13 | `cr.weaviate.io/semitechnologies/weaviate:1.39.0` | -1 つずつ進めることで影響範囲も限定できます。ある段階で問題が起きても、戻すのは 1 バージョンだけで済み、原因となったリリースもすぐ特定できます。10 以上のバージョンをまたいだ切り分けは不要です。 +1 つずつ進めることで影響範囲も限定できます。ある段階で問題が起きても、戻すのは 1 バージョンだけで済み、原因となったリリースもすぐ特定できます。すべてのマイナーを一度にまたいだ切り分けは不要です。 最新に近い状態を保つことが修正を受け取り続ける条件です。Weaviate は不具合修正とセキュリティ修正を、最新マイナーとその直前 3 マイナー程度の最新パッチにのみバックポートします。3 マイナー以上遅れた環境はこれらの修正を受け取れなくなります。今回の移行後も定期的に確認し、その時点の最新パッチへ更新してください。 diff --git a/zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx b/zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx index 8faff8395..91147a8d8 100644 --- a/zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx +++ b/zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx @@ -12,7 +12,7 @@ Dify 内置的 Weaviate 镜像已从 `1.27.0` 升级到 `1.39.0`。全新部署 受支持的升级方式是按顺序逐个小版本推进，每次都升到该小版本的最新补丁版本。下面给出完整阶梯，以及决定向量能否存活的两个运维细节。 - 开始前先备份 Weaviate 数据卷。十几级阶梯中途出问题时，只有手上有快照才能恢复。 + 开始前先备份 Weaviate 数据卷。阶梯中途出问题时，只有手上有快照才能恢复。 ## 检查当前版本 @@ -57,10 +57,10 @@ sudo cp -r ./volumes/weaviate ./volumes/weaviate_backup_$(date +%Y%m%d) | 12 | `cr.weaviate.io/semitechnologies/weaviate:1.38.9` | | 13 | `cr.weaviate.io/semitechnologies/weaviate:1.39.0` | -逐级升级还能缩小影响范围。某一级出问题时，只需回退一个版本，并且能立刻确定是哪个版本引入的问题，不必在十几个版本的跨度里二分排查。 +逐级升级还能缩小影响范围。某一级出问题时，只需回退一个版本，并且能立刻确定是哪个版本引入的问题，不必在一次跨越所有小版本的升级里二分排查。 - 紧跟最新版本才能持续拿到修复。Weaviate 只把缺陷和安全修复回合到最新小版本及其之前约三个小版本的最新补丁上，落后超过三个小版本的部署将不再收到这些修复。本次迁移完成后也要定期回看，及时升到当前补丁版本。 + 紧跟最新版本才能持续拿到修复。Weaviate 只会把缺陷和安全修复合入最新小版本及其之前约三个小版本的最新补丁，落后超过三个小版本的部署将不再收到这些修复。本次迁移完成后也要定期回看，及时升到当前补丁版本。 ## 使用 Docker Compose 升级