Aller au contenu principal

Stockage SQLite

Par défaut, Libre WebUI stocke les données de l’application dans SQLite. La couche de stockage conserve les chats, les messages, les utilisateurs, les préférences, les documents, les fragments de documents, les personas, les identifiants des plugins, les souvenirs et les métadonnées associées dans une seule base de données locale.

Emplacement de la base de données​

Les lancements depuis le code source utilisent l’ordre suivant :

  1. DATA_DIR lorsqu’il est défini ; les valeurs relatives sont résolues depuis le répertoire du backend.
  2. backend/data lorsqu’il ne l’est pas.

Par souci de rétrocompatibilité, un profil source où cette variable n’est pas définie continue d’utiliser backend/backend/data lorsqu’il s’agit du seul stockage durable existant. Si les deux emplacements contiennent un état, le démarrage exige un choix explicite et ne les copie ni ne les fusionne jamais.

Le lanceur npm/Homebrew empaqueté utilise plutôt ~/.libre-webui par défaut et résout un DATA_DIR relatif explicite depuis le répertoire de travail de l’appelant. Les déploiements Docker et Kubernetes fournissent des chemins de conteneur absolus.

Le fichier SQLite se nomme data.sqlite.

Exemple :

DATA_DIR=/var/lib/libre-webui

Contenu stocké par SQLite​

  • Utilisateurs et rôles
  • Sessions et messages
  • Préférences et réglages de l’interface
  • Documents et fragments
  • Personas et réglages des personas
  • Souvenirs des personas et état de mutation
  • Identifiants des plugins et associations de routage ou d’authentification, variables, activations par utilisateur, approbations des définitions modifiables et catalogues de modèles découverts
  • Réglages système
  • Propriété des tâches Work, routage des modèles et fournisseurs, exécutions, messages, activité des outils, état et identifiants de ressources Docker

Les valeurs sensibles sont chiffrées au niveau de l’application lorsqu’elles passent par les fonctions d’assistance du stockage chiffré.

Le stockage de Work est réparti​

Les conversations Work et les métadonnées des tâches résident dans SQLite, mais pas les fichiers Work. Chaque tâche reçoit un volume nommé Docker dédié, monté sur /workspace. Le conteneur est un état d’exécution remplaçable ; le volume nommé est le système de fichiers durable de la tâche.

Une sauvegarde de la base de données seule ne constitue donc pas une sauvegarde Work complète. Sauvegardez les volumes Docker correspondants selon la procédure de sauvegarde des volumes de votre hôte Docker. Libre WebUI attribue aux volumes Work gérés l’étiquette ai.libre-webui.managed=true et l’identifiant de leur tâche.

La suppression d’une tâche Work supprime définitivement ses enregistrements SQLite et son volume nommé géré. L’annulation d’une exécution, l’arrêt d’un aperçu ou le redémarrage du backend ne supprime pas ses fichiers.

Compatibilité JSON​

Les anciennes installations de Libre WebUI utilisaient des fichiers JSON pour certaines données. Les versions actuelles utilisent SQLite comme chemin de stockage principal et encapsulent l’accès au stockage derrière des couches de services et de modèles, afin que le reste de l’application n’ait pas à connaître le format de persistance.

Si vous mettez à niveau une ancienne installation, sauvegardez l’intégralité du répertoire de données avant de démarrer le nouveau backend.

L’activation des plugins héritée de .status.json est migrée une seule fois vers des lignes SQLite propres à chaque utilisateur pour les comptes qui existent au moment de la mise à niveau, mais seulement pour les définitions intégrées dont le hachage correspond exactement. Les définitions personnalisées et fantômes héritées restent en quarantaine jusqu’à ce qu’un administrateur les réimporte, et leur approbation ne restaure pas les anciennes lignes d’activation. Les comptes créés ensuite ne commencent avec aucun plugin actif, et les modifications d’activation de chaque compte sont indépendantes.

Sauvegarde​

Arrêtez le backend avant de copier la base de données :

cp -R backend/data backend/data.backup

Pour les déploiements qui utilisent DATA_DIR :

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

Si l’instance utilise Work, sauvegardez également tous les volumes nommés Work gérés pendant que le backend est arrêté. Conservez une sauvegarde de la base de données, de la clé de chiffrement et des volumes Work provenant du même instant.

Restauration​

Arrêtez le backend, remplacez le répertoire de données par votre sauvegarde, puis redémarrez. Conservez le même ENCRYPTION_KEY ; une autre clé ne pourra pas déchiffrer les valeurs chiffrées.

Pour Work, restaurez les volumes nommés sous les noms exacts enregistrés dans la base restaurée avant de démarrer le backend. Libre WebUI peut recréer le conteneur d’une tâche, mais pas reconstituer les fichiers absents de l’espace de travail à partir de l’historique de la conversation.

Remarques d’exploitation​

  • SQLite fonctionne avec WAL activé pour améliorer les lectures simultanées.
  • Le processus du backend doit pouvoir écrire dans le répertoire de données.
  • Conservez DATA_DIR sur un stockage persistant avec Docker et Kubernetes.
  • Sauvegardez ENCRYPTION_KEY avec la base de données.
  • Tenez compte séparément des volumes nommés Work lors de la mesure, de la migration ou de la restauration du stockage.

Documentation connexe​