Passa al contenuto principale

Archiviazione SQLite

Per impostazione predefinita, Libre WebUI archivia i dati dell'applicazione in SQLite. Il livello di archiviazione conserva chat, messaggi, utenti, preferenze, documenti, segmenti di documenti, persona, credenziali dei plugin, ricordi e metadati correlati in un unico database locale.

Posizione del database​

Gli avvii dal codice sorgente usano le posizioni nel seguente ordine:

  1. DATA_DIR, se impostata; i valori relativi vengono risolti a partire dalla directory del backend.
  2. backend/data, se non è impostata.

Per compatibilità con le versioni precedenti, un profilo sorgente senza impostazione continua a usare backend/backend/data quando questa è l'unica archiviazione permanente esistente. Se entrambe le posizioni contengono uno stato, all'avvio è necessario selezionare esplicitamente quale usare e non vengono mai copiati né uniti dati.

Il launcher incluso nei pacchetti npm/Homebrew usa invece ~/.libre-webui per impostazione predefinita e risolve un valore DATA_DIR relativo esplicito a partire dalla directory di lavoro del chiamante. I deployment Docker e Kubernetes forniscono percorsi assoluti nel container.

Il file SQLite si chiama data.sqlite.

Esempio:

DATA_DIR=/var/lib/libre-webui

Dati archiviati da SQLite​

  • Utenti e ruoli
  • Sessioni e messaggi
  • Preferenze e impostazioni dell'interfaccia
  • Documenti e segmenti
  • Persona e relative impostazioni
  • Ricordi delle persona e stato delle modifiche
  • Credenziali dei plugin e rispettivi collegamenti di routing/autenticazione, variabili, attivazioni per utente, approvazioni delle definizioni scrivibili e cataloghi di modelli rilevati
  • Impostazioni di sistema
  • Proprietà delle attività Work, routing di modello/provider, esecuzioni, messaggi, attività degli strumenti, stato e identificatori delle risorse Docker

I valori sensibili vengono crittografati a livello dell'applicazione quando passano attraverso gli helper per l'archiviazione crittografata.

L'archiviazione di Work è suddivisa​

La conversazione e i metadati delle attività Work risiedono in SQLite, ma i file di Work no. Ogni attività riceve un volume Docker denominato dedicato, montato in /workspace. Il container costituisce uno stato di esecuzione sostituibile; il volume denominato è il file system permanente dell'attività.

Ciò significa che il solo backup del database non è un backup completo di Work. Esegui il backup dei volumi Docker corrispondenti seguendo la procedura dell'host Docker per i backup dei volumi. Libre WebUI assegna ai volumi Work gestiti l'etichetta ai.libre-webui.managed=true e l'ID dell'attività proprietaria.

L'eliminazione di un'attività Work rimuove definitivamente i relativi record SQLite e il volume denominato gestito. Annullare un'esecuzione, arrestare un'anteprima o riavviare il backend non elimina i file dell'attività.

Compatibilità con JSON​

Le installazioni meno recenti di Libre WebUI usavano file JSON per alcuni dati. Le build attuali usano SQLite come percorso di archiviazione principale e mantengono l'accesso ai dati dietro livelli di servizio/modello, così il resto dell'applicazione non deve conoscere il formato di persistenza.

Se stai aggiornando una vecchia installazione, esegui il backup dell'intera directory dei dati prima di avviare la versione più recente.

L'attivazione dei plugin precedente in .status.json viene migrata una sola volta in righe SQLite per utente per gli account esistenti al momento dell'aggiornamento, ma soltanto per definizioni incluse nel pacchetto ancorate a un hash esatto. Le definizioni personalizzate e shadow precedenti restano in quarantena finché un amministratore non le importa di nuovo e l'approvazione non ripristina le vecchie righe di attivazione. Gli account creati in seguito iniziano senza plugin attivi e le modifiche alle attivazioni di ciascun account sono indipendenti.

Backup​

Arresta il backend prima di copiare il database:

cp -R backend/data backend/data.backup

Per i deployment che usano DATA_DIR:

cp -R "$DATA_DIR" "$DATA_DIR.backup"

Se l'istanza usa Work, esegui anche il backup di ogni volume Work denominato gestito mentre il backend è arrestato. Conserva insieme il database, la chiave di crittografia e il backup dei volumi Work corrispondenti allo stesso momento.

Ripristino​

Arresta il backend, sostituisci la directory dei dati con il backup e riavvialo. Mantieni la stessa ENCRYPTION_KEY: i valori crittografati non possono essere decifrati con una chiave diversa.

Per Work, ripristina i volumi denominati con i nomi esatti registrati nel database ripristinato prima di avviare il backend. Libre WebUI può ricreare il container di un'attività, ma non può ricostruire i file mancanti nello spazio di lavoro dalla cronologia della conversazione.

Note operative​

  • SQLite viene eseguito con WAL abilitato per migliorare le letture simultanee.
  • La directory dei dati deve essere scrivibile dal processo del backend.
  • In Docker e Kubernetes, conserva DATA_DIR su un'archiviazione permanente.
  • Esegui il backup di ENCRYPTION_KEY insieme al database.
  • Considera separatamente i volumi denominati di Work quando misuri, migri o ripristini l'archiviazione.

Documentazione correlata​