Přenositelnost dat

Libre WebUI dokáže exportovat a importovat verzovaný archiv JSON pro uživatele z Nastavení → Správa dat. Archiv slouží k přesunu podporovaných osobních dat mezi instalacemi nebo jejich obnovení do účtu. Nejde o úplnou zálohu serveru.

Archiv verze 3

Aktuální formát identifikuje:

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

Backend vytváří export z ověřených databázových dotazů omezených na uživatele. Obsahuje:

• uživatelské předvolby kromě odkazu na vybraný opakovaně použitelný hlasový profil;
• složky chatu;
• relace, zprávy, větve, hodnocení, artefakty a nastavení jednotlivých chatů;
• samostatné poznámky včetně připnutí;
• znalostní kolekce;
• extrahovaný obsah a metadata dokumentů, vazby relací/kolekcí a textové úseky.

Vkládání dokumentů se neexportují, protože jsou odvozenými daty. Při zapnutém sémantickém načítání je po importu znovu vytvořte. Archiv obsahuje extrahovaný text pro RAG, nikoli původní bajty souboru, a nemůže proto nahrání obnovit bajt po bajtu.

Každý archiv obsahuje seznam exclusions. Verze 3 záměrně vynechává:

• účty, hesla, přihlašovací relace a stav OAuth;
• přihlašovací údaje poskytovatelů a šifrované proměnné pluginů;
• referenční nahrávky a přepisy klonovaných hlasů, které jsou biometrickými daty a vyžadují samostatný souhlas;
• persony a jejich paměť;
• vygenerované obrázky, zvuky a videa;
• historii verzí poznámek a přílohy;
• úkoly, běhy, sandboxy a svazky Docker či Kubernetes Work.

Kanály, oznámení, kalendáře a automatizace jsou také mimo přenosný archiv. Jde o stav instance/týmu a přesouvají se s úplnou zálohou serveru.

Pro úplnou obnovu použijte zálohu databáze/datového adresáře se stejným ENCRYPTION_KEY. Work vyžaduje i konzistentní zálohu pojmenovaných svazků. Viz Migrace a zálohování SQLite a pracovní prostory Work.

Integrita a ověření exportu

Verze 3 chrání payload archivu kontrolním digestem SHA-256. Kanonická forma libre-json-sort-v1 vynechává horní pole integrity, lexikograficky řadí klíče objektů, zachovává pořadí polí a hashuje kompaktní JSON jako UTF-8. Import odmítne archiv s neodpovídajícím digestem i při platné syntaxi JSON.

Digest odhaluje náhodné poškození a změny po exportu. Není digitálním podpisem, neověřuje autora a nezajišťuje důvěrnost. Zacházejte s archivem jako s jinou kopií soukromých chatů a poznámek.

Před stažením export provede stejné kontroly schématu, velikostí polí, ID a počtu jako import. Ověří také, že formátovaný JSON z webového UI nepřesahuje 50 MiB. Místo souboru, který nelze obnovit, vrátí přesnou chybu ověření.

Aktuální limity archivu a účtu:

• 50 MiB na nahraný nebo vytvořený archiv;
• 100 složek chatu;
• 5 000 relací;
• 100 000 zpráv;
• 100 poznámek s názvem do 200 znaků a obsahem do 200 000 znaků;
• 5 000 znalostních kolekcí;
• 5 000 dokumentů;
• 100 000 úseků dokumentů;
• jednotlivá obecná pole do 2 000 000 znaků a ID do 256 znaků, s užšími limity runtime.

Bezpečné chování importu

Výběr souboru spustí okamžitou předběžnou kontrolu backendu. Nastavení zobrazí příchozí součty, odhadované počty vytvoření/přepsání/přeskočení, přemapování ID a migrační varování před povolením konečné akce Importovat. Změna zásady konfliktu vypočítá nový náhled.

Předběžná kontrola ověřuje digest, migruje podporované starší formáty, validuje celé schéma, počty prostředků, jedinečná ID, časová razítka, limity a vztahy a plánuje konflikty a přemapování bez zápisu. Visící vazby složek, kolekcí, rodičů zpráv nebo dokumentů se odmítnou místo tichého zahození. Backend ověření a plán opakuje při skutečném importu. Všechny zápisy probíhají v jedné transakci SQLite nebo PostgreSQL; chyba vrátí předvolby, složky, relace/zprávy, poznámky, kolekce, dokumenty a úseky společně.

K dispozici jsou dvě zásady konfliktu:

• Přeskočit duplicity zachová záznamy se shodnými ID a importuje nové. Předvolby se sloučí s aktuálními.
• Přepsat existující nahradí záznamy se shodnými ID. Předvolby nahradí výchozí hodnoty Libre WebUI. Záznamy chybějící v archivu se nikdy nemažou.

Obě zásady jsou idempotentní pro shodná ID. Pokud ID vlastní jiný účet na cílovém serveru, Libre WebUI jej a všechny odkazy deterministicky přemapuje. Nikdy nepřepisuje ani nečte prostředek jiného uživatele. Odkazy na vynechané nebo nedostupné prostředky, například personu z jiné instalace, jsou dokumentovanou výjimkou: kontrola oznámí odpojení relace před importem.

Výsledek v Nastavení uvádí počty vytvořených, přepsaných a přeskočených složek, relací, poznámek, kolekcí a dokumentů. Po úspěchu Libre znovu načte předvolby, chaty a složky a obnoví dokumenty.

Starší archivy

Import přijímá archivy libre-webui-user-data verze 2 a během ověření je migruje na verzi 3. Verze 2 neměla digest ani poznámky, takže Libre nemůže ověřit původ ani obnovit neexportované poznámky. Náhled uvádí obě omezení.

Import přijímá i dřívější formát libre-webui-export verze 1.0. Formát z prohlížeče obsahoval předvolby a pouze relace načtené v daném prohlížeči. Pole documents bylo vždy prázdné a chyběly složky, poznámky, kolekce i úseky. Libre tato omezení hlásí před importem.

Endpointy HTTP

Všechny endpointy vyžadují bearer token nebo relaci ověřeného uživatele:

Metoda	Endpoint	Účel
GET	/api/preferences/export	Vytvořit archiv v3 aktuálního uživatele
POST	/api/preferences/import/preflight	Ověřit a naplánovat bez zápisu
POST	/api/preferences/import	Ověřit a importovat transakčně

Webové UI posílá archiv jako pole multipart/form-data s názvem archive a zásadu jako strategy. Limit je 50 MiB. U menších migrací řízených API přijímají oba POST endpointy také JSON:

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

strategy je skip nebo overwrite. Pro kompatibilitu se mergeStrategy: "merge" mapuje na skip a mergeStrategy: "replace" na overwrite.