Portabilité des données

Libre WebUI peut exporter et importer une archive JSON versionnée propre à chaque utilisateur depuis Paramètres → Gestion des données. Cette archive sert à transférer les données personnelles prises en charge entre des installations Libre WebUI ou à les restaurer dans un compte. Elle ne constitue pas une sauvegarde complète du serveur.

Version 3 de l’archive

Le format actuel est identifié par :

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

Le serveur dorsal crée l’exportation à partir de requêtes de base de données authentifiées et limitées à l’utilisateur. Elle contient :

• les préférences de l’utilisateur, à l’exception de la référence d’un profil vocal réutilisable sélectionné ;
• les dossiers de discussions ;
• les sessions de discussion, messages, branches, évaluations, artefacts et paramètres propres à chaque discussion ;
• les Notes autonomes, y compris leur état épinglé ;
• les collections de connaissances ;
• le contenu extrait et les métadonnées des documents, les associations aux sessions et aux collections, ainsi que les fragments de texte.

Les plongements des documents ne sont pas exportés, car ce sont des données dérivées. Régénérez-les après l’importation si la récupération sémantique est activée. L’archive contient le texte extrait utilisé par RAG, et non les octets du fichier importé à l’origine ; elle ne peut donc pas recréer l’importation originale octet pour octet.

Chaque archive comporte une liste exclusions. La version 3 exclut volontairement :

• les comptes, mots de passe, sessions de connexion et états OAuth ;
• les identifiants des fournisseurs et les variables chiffrées des plugins ;
• les enregistrements de référence et transcriptions des voix clonées, qui constituent des données biométriques et exigent une gestion séparée tenant compte du consentement ;
• les personas et leur mémoire ;
• les fichiers de la bibliothèque d’images, de contenus audio et de vidéos générés ;
• l’historique des révisions et les pièces jointes des notes ;
• les tâches Work, leurs exécutions et environnements isolés, ainsi que les volumes Docker ou Kubernetes.

Les canaux, notifications, calendriers et automatisations se trouvent eux aussi en dehors de l’archive portable ; ils constituent l’état de l’instance ou de l’équipe et sont transférés avec une sauvegarde complète du serveur.

Pour une restauration complète du serveur, utilisez une sauvegarde de la base de données et du répertoire de données avec la même valeur ENCRYPTION_KEY. Work exige également une sauvegarde cohérente de ses volumes nommés. Consultez Migration et sauvegarde de SQLite et Espaces de travail Work.

Intégrité et validation de l’exportation

La version 3 protège la charge utile de l’archive par une empreinte d’intégrité SHA-256. La forme canonique libre-json-sort-v1 omet le champ integrity à la racine, trie les clés de chaque objet JSON par ordre lexicographique, préserve l’ordre des tableaux et hache le JSON compact qui en résulte en UTF-8. L’importation rejette toute archive de version 3 dont l’empreinte ne correspond pas, même si son JSON reste syntaxiquement valide.

Cette empreinte détecte les altérations accidentelles et les modifications apportées après l’exportation. Ce n’est pas une signature numérique : elle n’authentifie pas l’auteur du fichier et ne rend pas l’archive confidentielle. Traitez une archive comme toute autre copie des discussions et Notes privées de l’utilisateur.

Avant de proposer un téléchargement, l’exportation effectue les mêmes vérifications de schéma, de taille des champs, d’identifiants et de nombre d’éléments que l’importation. Elle vérifie aussi que le JSON mis en forme téléchargé par l’interface web ne dépasse pas la limite d’importation de 50 MiB. Plutôt que de proposer un fichier dont Libre WebUI sait déjà qu’il ne peut pas être restauré, elle renvoie une erreur de validation précise.

Limites actuelles des archives et des comptes :

• 50 MiB par archive importée ou générée ;
• 100 dossiers de discussions ;
• 5,000 sessions de discussion ;
• 100,000 messages de discussion ;
• 100 Notes, avec un titre de 200 caractères au maximum et un contenu de 200,000 caractères au maximum ;
• 5,000 collections de connaissances ;
• 5,000 documents ;
• 100,000 fragments de documents ;
• champs de contenu général limités à 2,000,000 caractères et identifiants à 256 caractères, avec des limites plus étroites lorsque la ressource d’exécution l’exige.

Comportement sûr de l’importation

Lorsque vous sélectionnez un fichier, le serveur dorsal en effectue immédiatement la vérification préalable. Avant d’activer l’action finale Importer, les paramètres affichent les totaux entrants, les nombres prévus de créations, remplacements et éléments ignorés, les réaffectations d’identifiants et les avertissements de migration. Modifier la stratégie de conflits calcule et affiche un nouvel aperçu.

La vérification préalable contrôle l’empreinte d’intégrité lorsqu’elle existe, migre les anciens formats pris en charge, valide l’intégralité du schéma, le nombre de ressources, l’unicité des identifiants, les horodatages, les limites de contenu et les relations incluses, puis planifie les conflits et les réaffectations de références sans écrire de données. Les associations orphelines de dossiers, collections, parents de messages ou documents sont rejetées au lieu d’être supprimées silencieusement. Le serveur dorsal répète la validation et la planification des conflits lors de l’importation effective. Toutes les écritures ont lieu dans une seule transaction de base de données, aussi bien avec SQLite qu’avec PostgreSQL ; une erreur annule ensemble les modifications apportées aux préférences, dossiers, sessions et messages, Notes, collections, documents et fragments.

Deux stratégies de conflits sont proposées :

• Ignorer les doublons conserve les enregistrements dont les identifiants correspondent et importe les nouveaux. Les préférences sont fusionnées avec celles du compte actuel.
• Remplacer les éléments existants remplace les enregistrements dont les identifiants correspondent. Les préférences remplacent les valeurs par défaut de Libre WebUI. Les enregistrements absents de l’archive ne sont jamais supprimés.

Les deux stratégies sont idempotentes pour les enregistrements dont les identifiants correspondent. Si un identifiant appartient déjà à un autre compte sur le serveur cible, Libre WebUI le réaffecte de manière déterministe, ainsi que toutes les références incluses qui le désignent. Il ne remplace ni ne lit jamais la ressource d’une autre personne. Les références à des ressources exclues ou indisponibles, comme un persona d’une autre installation, constituent une exception documentée : la vérification préalable indique que la session sera dissociée avant l’importation.

Le résultat affiché dans les paramètres indique le nombre de dossiers, sessions, Notes, collections et documents créés, remplacés et ignorés. Après une importation réussie, Libre recharge les préférences, discussions et dossiers, puis actualise les documents.

Anciennes archives

L’outil d’importation accepte les archives libre-webui-user-data de version 2 et les migre vers la version 3 pendant la validation. La version 2 ne comportait pas d’empreinte d’intégrité ni de Notes ; Libre ne peut donc ni en vérifier l’origine, ni récupérer des Notes qui n’ont jamais été exportées. L’aperçu de la vérification préalable signale ces deux limites.

L’outil accepte également l’ancien format libre-webui-export de version 1.0. Ce format généré par le navigateur ne contenait que les préférences et les sessions chargées dans ce navigateur. Son tableau documents était toujours vide, et il ne contenait ni dossiers, ni Notes, ni collections de connaissances, ni fragments de documents. Libre signale ces limites de migration avant l’importation.

Points de terminaison HTTP

Tous les points de terminaison nécessitent le jeton Bearer ou la session de l’utilisateur authentifié :

Méthode	Point de terminaison	Rôle
GET	/api/preferences/export	Créer l’archive v3 de l’utilisateur actuel
POST	/api/preferences/import/preflight	Valider et planifier sans écrire
POST	/api/preferences/import	Valider et importer de façon transactionnelle

L’interface web envoie l’archive dans un champ multipart/form-data nommé archive et la stratégie de conflits dans un champ strategy. La limite d’importation est de 50 MiB. Pour les migrations plus petites pilotées par API, les deux points de terminaison POST acceptent également du JSON :

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

strategy vaut skip ou overwrite. Pour assurer la compatibilité avec l’ancien client limité aux préférences, mergeStrategy: "merge" correspond à skip et mergeStrategy: "replace" correspond à overwrite.