Portabilità dei dati

Libre WebUI può esportare e importare un archivio JSON versionato per utente da Impostazioni → Gestione dati. Serve a spostare i dati personali supportati tra installazioni o a ripristinarli in un account. Non è un backup completo del server.

Archivio versione 3

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

Il backend crea l'esportazione con query autenticate e limitate all'utente. Contiene:

• preferenze, eccetto un riferimento a un profilo vocale riutilizzabile;
• cartelle chat;
• sessioni, messaggi, rami, valutazioni, artefatti e impostazioni per chat;
• Note autonome e stato fissato;
• raccolte di conoscenza;
• contenuto e metadati estratti, associazioni e frammenti.

Gli embedding non vengono esportati perché derivati. Rigenerali dopo l'importazione. L'archivio contiene il testo estratto usato da RAG, non i byte originali, quindi non ricrea il caricamento byte per byte.

Ogni archivio ha una lista exclusions. La versione 3 esclude:

• account, password, sessioni e stato OAuth;
• credenziali e variabili cifrate;
• registrazioni e trascrizioni di voci clonate, dati biometrici;
• personas e memoria;
• immagini, audio e video generati;
• cronologia revisioni e allegati delle note;
• attività Work, esecuzioni, sandbox e volumi Docker/Kubernetes.

Canali, notifiche, calendari e automazioni sono anch'essi stato dell'istanza/team e viaggiano con un backup completo.

Per il recupero completo usa backup del database/directory con lo stesso ENCRYPTION_KEY. Work richiede anche i volumi. Vedi migrazione e backup SQLite e spazi Work.

Integrità e convalida

La versione 3 protegge il payload con SHA-256. La forma libre-json-sort-v1 omette integrity al primo livello, ordina le chiavi, conserva l'ordine degli array e calcola l'hash del JSON compatto UTF-8. Un digest errato viene rifiutato anche con JSON valido.

Rileva corruzione e modifiche accidentali, ma non è firma digitale, non autentica l'autore e non rende l'archivio confidenziale. Proteggilo come copia privata.

Prima del download, l'esportazione esegue gli stessi controlli di schema, dimensioni, ID e conteggi dell'importazione e conferma che il JSON formattato non superi 50 MiB. Restituisce un errore preciso invece di offrire un file non ripristinabile.

Limiti:

• 50 MiB per archivio;
• 100 cartelle;
• 5.000 sessioni;
• 100.000 messaggi;
• 100 Note, titoli fino a 200 e contenuti fino a 200.000 caratteri;
• 5.000 raccolte;
• 5.000 documenti;
• 100.000 frammenti;
• campi generali fino a 2.000.000 caratteri e ID fino a 256, con limiti più stretti dove previsti.

Importazione sicura

Selezionare un file avvia subito il preflight. Le Impostazioni mostrano totali, creazioni/sovrascritture/omissioni previste, rimappature e avvisi prima di abilitare l'importazione. Cambiare politica ricalcola l'anteprima.

Il preflight verifica il digest, migra formati supportati, convalida schema, conteggi, ID, timestamp, limiti e relazioni, e pianifica conflitti senza scrivere. Relazioni mancanti vengono rifiutate, non eliminate. Il backend ripete tutto nell'importazione reale. Tutte le scritture avvengono in una transazione sia SQLite sia PostgreSQL; un errore annulla preferenze, cartelle, sessioni, Note, raccolte, documenti e frammenti insieme.

Politiche:

• Salta duplicati conserva ID esistenti e importa i nuovi; unisce le preferenze.
• Sovrascrivi esistenti sostituisce gli ID corrispondenti e applica le preferenze sui default. Non elimina record assenti.

Entrambe sono idempotenti per ID uguali. Se un ID appartiene a un altro account, viene rimappato deterministicamente con i riferimenti. Libre non legge né sovrascrive risorse altrui. Riferimenti esclusi, come una persona di altra installazione, sono eccezioni dichiarate e il preflight avvisa del distacco.

Il risultato riporta creati, sovrascritti e saltati. Dopo il successo, Libre ricarica preferenze, chat, cartelle e documenti.

Archivi precedenti

Accetta libre-webui-user-data v2 e lo migra a v3. V2 non aveva digest né Note, quindi non può verificarne origine o recuperare Note mai esportate. L'anteprima segnala entrambi.

Accetta anche libre-webui-export 1.0, generato dal browser con preferenze e sole sessioni caricate. documents era sempre vuoto e mancavano cartelle, Note, raccolte e frammenti. Le limitazioni vengono mostrate.

Endpoint HTTP

Tutti richiedono token Bearer o sessione:

Metodo	Endpoint	Scopo
GET	/api/preferences/export	Creare archivio v3
POST	/api/preferences/import/preflight	Convalidare e pianificare senza scrivere
POST	/api/preferences/import	Convalidare e importare transazionalmente

La UI invia l'archivio nel campo multipart/form-data archive e la politica in strategy. Limite 50 MiB. Per migrazioni API più piccole, i POST accettano JSON:

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

strategy è skip o overwrite. Per compatibilità, mergeStrategy: "merge" corrisponde a skip e mergeStrategy: "replace" a overwrite.