SQLite ストレージ
Libre WebUI は、デフォルトでアプリケーションデータを SQLite に保存します。ストレージ層は、チャット、メッセージ、ユーザー、設定、ドキュメント、ドキュメントチャンク、ペルソナ、プラグイン資格情報、メモリ、関連メタデータを 1 つのローカルデータベースに保持します。
データベースの場所
ソースから起動する場合は、次の優先順で保存場所が決まります。
DATA_DIRが設定されている場合。相対値はバックエンドディレクトリを基準に解決されます。- 未設定の場合は
backend/data。
後方互換性のため、ソースプロファイルで未設定の場合、永続ストアとして存在する場所が backend/backend/data だけなら、そこを引き続き使用します。両方の場所に状態がある場合、起動には明示的な選択が必要で、自動的にコピーや統合はしません。
パッケージ版の npm/Homebrew ランチャーは、代わりに ~/.libre-webui をデフォルトとし、明示的な相対 DATA_DIR は呼び出し元の作業ディレクトリを基準に解決します。Docker と Kubernetes のデプロイでは、コンテナ内の絶対パスを指定します。
SQLite ファイル名は data.sqlite です。
例:
DATA_DIR=/var/lib/libre-webui
SQLite に保存される内容
- ユーザーとロール
- セッションとメッセージ
- ユーザー設定と UI 設定
- ドキュメントとチャンク
- ペルソナとペルソナ設定
- ペルソナのメモリと変異状態
- プラグイン資格情報と、そのルーティング／認証の関連付け、変数、ユーザーごとの有効化状態、書き込み可能な定義の承認、検出済みモデルカタログ
- システム設定
- Work タスクの所有者、モデル／プロバイダーのルーティング、実行、メッセージ、ツールアクティビティ、状態、Docker リソース ID
機密値は、暗号化ストレージヘルパーを通過するときにアプリケーション層で暗号化されます。
Work のストレージは分割される
Work の会話とタスクメタデータは SQLite に保存されますが、Work のファイルは保存されません。各タスクには、/workspace にマウントされる専用の Docker 名前付きボリュームが割り当てられます。コンテナは交換可能な実行状態で、名前付きボリュームがタスクの永続ファイルシステムです。
したがって、データベースのバックアップだけでは Work の完全なバックアップになりません。Docker ホストのボリュームバックアップ手順を使い、対応する Docker ボリュームもバックアップしてください。Libre WebUI が管理する Work ボリュームには、ai.libre-webui.managed=true と所有するタスク ID のラベルが付きます。
Work タスクを削除すると、その SQLite レコードと管理対象の名前付きボリュームが完全に削除されます。実行のキャンセル、プレビューの停止、バックエンドの再起動ではファイルは削除されません。
JSON との互換性
古い Libre WebUI では、一部のデータに JSON ファイルを使用していました。現在のビルドは SQLite を主要な保存経路とし、ストレージアクセスをサービス／モデル層の背後に置いています。そのため、アプリの他の部分が永続化形式を意識する必要はありません。
古いインストールからアップグレードする場合は、新しいバックエンドを起動する前にデータディレクトリ全体をバックアップしてください。
.status.json の従来のプラグイン有効化状態は、アップグレード時に存在するアカウントについて、ハッシュで固定された同梱定義と完全に一致する場合に限り、ユーザーごとの SQLite 行へ一度だけ移行されます。従来のカスタム定義とシャドー定義は、管理者が再インポートするまで隔離されたままです。承認しても、以前の有効化行は復元されません。後から作成されたアカウントでは、どのプラグインも有効でない状態から始まり、各アカウントの有効化変更は独立しています。
バックアップ
データベースをコピーする前に、バックエンドを停止します。
cp -R backend/data backend/data.backup
DATA_DIR を使用するデプロイでは、次のようにします。
cp -R "$DATA_DIR" "$DATA_DIR.backup"
インスタンスで Work を使用している場合は、バックエンドを停止している間に、管理対象のすべての Work 名前付きボリュームもバックアップします。データベース、暗号化鍵、Work ボリュームのバックアップは、同じ時点のものを揃えて保管してください。
復元
バックエンドを停止し、データディレクトリをバックアップで置き換えてから再起動します。同じ ENCRYPTION_KEY を維持してください。別の鍵では暗号化された値を復号できません。
Work については、バックエンドを起動する前に、復元したデータベースに記録された正確な名前で名前付きボリュームを復元します。Libre WebUI はタスクコンテナを再作成できますが、失われたワークスペースファイルを会話履歴から復元することはできません。
運用上の注意
- SQLite は同時読み取り性能を高めるため、WAL を有効にして動作します。
- データディレクトリは、バックエンドプロセスから書き込み可能でなければなりません。
- Docker と Kubernetes では、
DATA_DIRを永続ストレージに配置してください。 - データベースとともに
ENCRYPTION_KEYもバックアップしてください。 - ストレージの計測、移行、復元では、Work の名前付きボリュームを別に考慮してください。