メインコンテンツまでスキップ

データの移植

Libre WebUI では、Settings → Data Management から、バージョン管理されたユーザー単位の JSON アーカイブをエクスポート、インポートできます。このアーカイブは、対応する個人データを Libre WebUI のインストール環境間で移動したり、アカウントへ復元したりするためのものです。 サーバー全体のバックアップではありません。

アーカイブバージョン 3​

現在の形式は、次の内容で識別されます。

{
  "format": "libre-webui-user-data",
  "version": 3,
  "integrity": {
    "algorithm": "sha256",
    "canonicalization": "libre-json-sort-v1",
    "digest": "<64 lowercase hexadecimal characters>"
  }
}

バックエンドは、認証済みユーザーをスコープとするデータベースクエリからエクスポートを作成します。 アーカイブには次の内容が含まれます。

  • 選択済みの再利用可能な音声プロファイルへの参照を除く、ユーザー設定
  • チャットフォルダー
  • チャットセッション、メッセージ、分岐、評価、artifact、チャット単位の設定
  • ピン留め状態を含む、独立した Notes
  • ナレッジコレクション
  • 抽出済みのドキュメント内容とメタデータ、セッション/コレクションとの関連付け、テキストチャンク

ドキュメントの埋め込みは派生データなので、エクスポートされません。セマンティック検索が有効な場合は、 インポート後に埋め込みを再生成してください。アーカイブに含まれるのは RAG で使用する抽出済みテキストであり、 アップロードされた元ファイルのバイト列ではありません。そのため、アーカイブから元のアップロードを バイト単位で完全に再現することはできません。

各アーカイブには exclusions リストがあります。バージョン 3 では、次の内容を意図的に除外します。

  • アカウント、パスワード、ログインセッション、OAuth の状態
  • プロバイダーの認証情報と、暗号化されたプラグイン変数
  • 生体データに当たり、同意を考慮した個別の処理が必要な、クローン音声の参照録音と文字起こし
  • Personas と Persona のメモリ
  • 生成された画像、音声、動画ライブラリのファイル
  • ノートのリビジョン履歴と添付ファイル
  • Work のタスク、実行、sandbox、Docker または Kubernetes のボリューム

Channels、Notifications、Calendars、Automations も移植用アーカイブには含まれません。 これらはインスタンス/チーム単位の状態であり、サーバー全体のバックアップに含めて移動します。

サーバー全体を復旧するには、同じ ENCRYPTION_KEY を使用するデータベース/データディレクトリの バックアップを用意してください。Work では、名前付きボリュームの整合性のあるバックアップも必要です。 SQLite の移行とバックアップおよび Work ワークスペースを参照してください。

整合性とエクスポート検証​

バージョン 3 は、SHA-256 整合性ダイジェストでアーカイブのペイロードを保護します。 libre-json-sort-v1 の正規形式は、最上位の integrity フィールドを除外し、すべての JSON オブジェクトの キーを辞書順に並べ、配列の順序を維持し、結果となる空白なしの JSON を UTF-8 としてハッシュします。 インポートでは、JSON として構文的に正しい場合でも、ダイジェストが一致しないバージョン 3 アーカイブを拒否します。

このダイジェストは、偶発的な破損やエクスポート後の変更を検出します。デジタル署名ではないため、 ファイルの作成者を認証するものでも、アーカイブを秘密に保つものでもありません。アーカイブは、 ユーザーの非公開チャットや Notes のほかのコピーと同様に扱ってください。

ダウンロードを提供する前に、エクスポート処理はインポートと同じスキーマ、フィールドサイズ、ID、 アーカイブ件数の検査を実行します。また、Web UI からダウンロードする整形済み JSON が、アップロード上限の 50 MiB 以下であることも確認します。Libre WebUI が復元できないと事前に判断できるファイルを提供する代わりに、 エクスポート処理は正確な検証エラーを返します。

現在のアーカイブおよびアカウントの上限：

  • アップロードまたは生成するアーカイブ 1 件あたり 50 MiB
  • チャットフォルダー 100 件
  • チャットセッション 5,000 件
  • チャットメッセージ 100,000 件
  • Notes 100 件。タイトルは最大 200 文字、内容は最大 200,000 文字
  • ナレッジコレクション 5,000 件
  • ドキュメント 5,000 件
  • ドキュメントチャンク 100,000 件
  • 一般的な個別の内容フィールドは最大 2,000,000 文字、ID は最大 256 文字。 実行時リソースにさらに狭い制限がある場合は、その制限が適用されます

安全なインポート動作​

ファイルを選択すると、バックエンドに対して直ちに事前検証が要求されます。Settings には、最終的な Import 操作を有効にする前に、受信データの合計、作成/上書き/スキップの予測件数、ID の再マッピング、 移行に関する警告が表示されます。競合ポリシーを変更すると、新しいプレビューが計算されて表示されます。

事前検証では、利用可能な場合は整合性ダイジェストを確認し、対応する旧形式を移行して、完全なスキーマ、 リソース件数、一意な ID、タイムスタンプ、内容の範囲、含まれる関係を検証します。また、データを書き込まずに 競合と参照の再マッピングを計画します。参照先のないフォルダー、コレクション、親メッセージ、ドキュメントの 関連付けは、黙って破棄せず拒否します。実際のインポート時には、バックエンドが検証と競合計画を再実行します。 対応する SQLite と PostgreSQL のどちらのバックエンドでも、すべての書き込みは 1 つのデータベーストランザクションで 行われます。エラーが発生すると、設定、フォルダー、セッション/メッセージ、Notes、コレクション、 ドキュメント、チャンクがまとめてロールバックされます。

競合ポリシーは 2 種類あります。

  • 重複をスキップ：ID が一致するレコードを保持し、新しいレコードをインポートします。 設定は、アカウントの現在の設定へマージされます。
  • 既存データを上書き：ID が一致するレコードを置き換えます。設定は Libre WebUI の既定値を基準に 置き換えられます。アーカイブに含まれないレコードが削除されることはありません。

どちらのポリシーも、ID が一致するレコードに対して冪等です。対象サーバー上で別のアカウントがすでに ID を 所有している場合、Libre WebUI はその ID と、含まれるすべての参照を決定論的に再マッピングします。 ほかのユーザーのリソースを上書きしたり、読み取ったりすることはありません。別のインストール環境にある Persona など、除外された、または利用できないリソースへの参照は、文書化された例外として残ります。 事前検証では、インポート前にセッションからその参照が切り離されることを報告します。

Settings に表示される結果には、フォルダー、セッション、Notes、コレクション、ドキュメントについて、 作成、上書き、スキップした件数が含まれます。インポートが成功すると、Libre は設定、チャット、 フォルダーを再読み込みし、ドキュメントを更新します。

旧バージョンのアーカイブ​

インポーターはバージョン 2 の libre-webui-user-data アーカイブを受け付け、検証時にバージョン 3 へ移行します。 バージョン 2 には整合性ダイジェストがなく、Notes も含まれていなかったため、Libre はその作成元を検証できず、 エクスポートされなかった Notes を復元することもできません。事前検証のプレビューには、両方の制限が表示されます。

インポーターは、以前の libre-webui-export バージョン 1.0 形式も受け付けます。このブラウザー生成形式に 含まれていたのは、設定と、そのブラウザーに読み込まれていたセッションだけです。documents 配列は常に空で、 フォルダー、Notes、ナレッジコレクション、ドキュメントチャンクは含まれていませんでした。Libre は、 インポート前にこれらの移行上の制限を報告します。

HTTP エンドポイント​

すべてのエンドポイントで、認証済みユーザーの bearer token または session が必要です。

メソッドエンドポイント用途
GET/api/preferences/export現在のユーザーの v3 アーカイブを作成する
POST/api/preferences/import/preflight書き込まずに検証して計画する
POST/api/preferences/import検証し、トランザクションとしてインポートする

Web UI はアーカイブを archive という名前の multipart/form-data フィールドとして、 競合ポリシーを strategy フィールドとして送信します。アップロード上限は 50 MiB です。 API から実行する小規模な移行では、2 つの POST エンドポイントが JSON も受け付けます。

{
  "data": { "format": "libre-webui-user-data", "version": 3 },
  "strategy": "skip"
}

strategy は skip または overwrite です。以前の設定専用クライアントとの互換性のため、 mergeStrategy: "merge" は skip に、mergeStrategy: "replace" は overwrite に対応します。