Portabilitatea datelor

Libre WebUI poate exporta și importa o arhivă JSON versionată per utilizator din Setări → Gestionarea datelor. Arhiva este destinată mutării datelor personale acceptate între instalări Libre WebUI sau restaurării lor într-un cont. Nu reprezintă o copie de rezervă completă a serverului.

Arhiva versiunea 3

Formatul curent este identificat prin:

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

Backend-ul creează exportul din interogări autentificate ale bazei de date, limitate la utilizator. Acesta conține:

• preferințele utilizatorului, cu excepția unei referințe selectate la un profil vocal reutilizabil;
• dosare de chat;
• sesiuni de chat, mesaje, ramuri, evaluări, artefacte și setări per chat;
• Notițe independente, inclusiv starea lor de fixare;
• colecții de cunoștințe;
• conținutul și metadatele extrase din documente, asocierile cu sesiuni/colecții și fragmentele de text.

Embedding-urile documentelor nu sunt exportate deoarece sunt date derivate. Regenerați embedding-urile după import când este activată regăsirea semantică. Arhiva conține textul extras folosit de RAG, nu octeții fișierului încărcat inițial, deci nu poate recrea încărcarea originală octet cu octet.

Fiecare arhivă include o listă exclusions. Versiunea 3 exclude intenționat:

• conturi, parole, sesiuni de autentificare și starea OAuth;
• credențiale de furnizor și variabile criptate ale pluginurilor;
• înregistrări de referință și transcrieri ale vocilor clonate, care sunt date biometrice și necesită gestionare separată, bazată pe consimțământ;
• personaje și memoria personajelor;
• fișierele bibliotecii de imagini, audio și video generate;
• istoricul reviziilor și atașamentele notițelor;
• sarcini, execuții și sandbox-uri Work și volume Docker sau Kubernetes.

Canalele, notificările, calendarele și automatizările se află și ele în afara arhivei portabile; sunt stare de instanță/echipă și se transferă printr-o copie de rezervă completă a serverului.

Pentru recuperarea completă a serverului, folosiți o copie de rezervă a bazei de date/directorului de date cu aceeași valoare ENCRYPTION_KEY. Work necesită și o copie de rezervă coerentă a volumelor denumite. Consultați Migrarea și copierea de rezervă SQLite și Spațiile de lucru Work.

Integritate și validarea exportului

Versiunea 3 protejează conținutul arhivei cu un digest de integritate SHA-256. Forma canonică libre-json-sort-v1 omite câmpul de nivel superior integrity, sortează lexicografic cheile fiecărui obiect JSON, păstrează ordinea tablourilor și calculează hash-ul JSON-ului compact rezultat ca UTF-8. Importul respinge o arhivă de versiunea 3 al cărei digest nu corespunde, chiar dacă JSON-ul rămâne valid sintactic.

Digestul detectează coruperea accidentală și schimbările ulterioare exportului. Nu este o semnătură digitală, nu autentifică persoana care a creat fișierul și nu face arhiva confidențială. Tratați arhiva ca pe orice altă copie a chaturilor private și Notițelor utilizatorului.

Înainte de a oferi descărcarea, exportul rulează aceleași verificări pentru schemă, dimensiunea câmpurilor, ID-uri și numărul elementelor din arhivă ca importul. Verifică și dacă JSON-ul formatat lizibil descărcat de interfața web nu depășește limita de încărcare de 50 MiB. Exportul returnează o eroare de validare exactă în loc să ofere un fișier pe care Libre WebUI știe deja că nu îl poate restaura.

Limitele actuale pentru arhivă și cont sunt:

• 50 MiB per arhivă încărcată sau generată;
• 100 de dosare de chat;
• 5,000 de sesiuni de chat;
• 100,000 de mesaje de chat;
• 100 de Notițe, cu titluri de până la 200 de caractere și conținut de până la 200,000 de caractere;
• 5,000 de colecții de cunoștințe;
• 5,000 de documente;
• 100,000 de fragmente de document;
• câmpuri individuale cu conținut general de până la 2,000,000 de caractere și ID-uri de până la 256 de caractere, cu limite mai restrictive acolo unde resursa runtime le impune.

Comportament sigur la import

Selectarea unui fișier cere backend-ului să îl verifice preliminar imediat. Setările afișează totalurile primite, numerele estimate de creare/suprascriere/omitere, remapările ID-urilor și avertismentele de migrare înainte de a activa acțiunea finală Import. Schimbarea politicii de conflicte calculează și afișează o previzualizare nouă.

Verificarea preliminară validează digestul de integritate acolo unde este disponibil, migrează formatele vechi acceptate, verifică schema completă, numărul resurselor, ID-urile unice, marcajele temporale, limitele conținutului și relațiile incluse și planifică conflictele și remaparea referințelor fără a scrie date. Asocierile suspendate de dosare, colecții, părinți ai mesajelor sau documente sunt respinse, nu eliminate în tăcere. Backend-ul repetă validarea și planificarea conflictelor pentru importul efectiv. Toate scrierile au loc într-o singură tranzacție de bază de date pe ambele backend-uri acceptate, SQLite și PostgreSQL; o eroare anulează împreună preferințele, dosarele, sesiunile/mesajele, Notițele, colecțiile, documentele și fragmentele.

Sunt disponibile două politici de conflict:

• Omite duplicatele păstrează înregistrările cu ID-uri identice și importă înregistrările noi. Preferințele sunt îmbinate cu preferințele actuale ale contului.
• Suprascrie elementele existente înlocuiește înregistrările cu ID-uri identice. Preferințele înlocuiesc valorile implicite Libre WebUI. Înregistrările absente din arhivă nu sunt șterse niciodată.

Ambele politici sunt idempotente pentru înregistrările cu ID-uri identice. Dacă un ID aparține deja altui cont de pe serverul țintă, Libre WebUI îl remapează determinist împreună cu fiecare referință inclusă către acesta. Nu suprascrie și nu citește niciodată resursa altui utilizator. Referințele la resurse excluse sau indisponibile, precum un personaj din altă instalare, rămân o excepție documentată: verificarea preliminară raportează că sesiunea va fi detașată înainte de import.

Rezultatul afișat în Setări raportează numărul elementelor create, suprascrise și omise pentru dosare, sesiuni, Notițe, colecții și documente. După un import reușit, Libre reîncarcă preferințele, chaturile și dosarele și actualizează documentele.

Arhive mai vechi

Importatorul acceptă arhive libre-webui-user-data versiunea 2 și le migrează la versiunea 3 în timpul validării. Versiunea 2 nu avea digest de integritate și nu conținea Notițe, astfel încât Libre nu poate verifica originea sau recupera Notițe care nu au fost exportate. Previzualizarea preliminară precizează ambele limitări.

Importatorul acceptă și vechiul format libre-webui-export versiunea 1.0. Formatul generat de browser conținea preferințe și numai sesiunile încărcate în acel browser. Tabloul documents era întotdeauna gol și nu conținea dosare, Notițe, colecții de cunoștințe sau fragmente de documente. Libre raportează aceste limitări de migrare înainte de import.

Endpoint-uri HTTP

Toate endpoint-urile necesită tokenul bearer sau sesiunea utilizatorului autentificat:

Metodă	Endpoint	Scop
GET	/api/preferences/export	Creează arhiva v3 a utilizatorului curent
POST	/api/preferences/import/preflight	Validează și planifică fără scrieri
POST	/api/preferences/import	Validează și importă tranzacțional

Interfața web trimite arhiva ca un câmp multipart/form-data numit archive, iar politica de conflicte ca un câmp strategy. Limita de încărcare este 50 MiB. Pentru migrări mai mici bazate pe API, cele două endpoint-uri POST acceptă și JSON:

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

strategy este skip sau overwrite. Pentru compatibilitate cu vechiul client exclusiv pentru preferințe, mergeStrategy: "merge" corespunde valorii skip, iar mergeStrategy: "replace" corespunde valorii overwrite.