Saltar al contenido principal

Almacenamiento SQLite

Libre WebUI almacena los datos de la aplicación en SQLite de forma predeterminada. La capa de almacenamiento conserva chats, mensajes, usuarios, preferencias, documentos, fragmentos de documentos, personas, credenciales de plugins, recuerdos y metadatos relacionados en una única base de datos local.

Ubicación de la base de datos​

Los inicios desde el código fuente usan este orden de ubicaciones:

  1. DATA_DIR cuando está definido; los valores relativos se resuelven desde el directorio del backend.
  2. backend/data cuando no lo está.

Por compatibilidad con versiones anteriores, un perfil de código fuente sin esa variable sigue usando backend/backend/data cuando es el único almacén duradero existente. Si ambas ubicaciones contienen estado, el inicio exige una selección explícita y nunca las copia ni combina.

El lanzador empaquetado de npm/Homebrew usa ~/.libre-webui de forma predeterminada y resuelve un DATA_DIR relativo explícito desde el directorio de trabajo del invocador. Los despliegues de Docker y Kubernetes proporcionan rutas absolutas dentro del contenedor.

El archivo SQLite se llama data.sqlite.

Ejemplo:

DATA_DIR=/var/lib/libre-webui

Qué almacena SQLite​

  • Usuarios y roles
  • Sesiones y mensajes
  • Preferencias y configuración de la interfaz
  • Documentos y fragmentos
  • Personas y configuración de personas
  • Recuerdos de personas y estado de mutación
  • Credenciales de plugins y sus enlaces de enrutamiento o autenticación, variables, activaciones por usuario, aprobaciones de definiciones modificables y catálogos de modelos descubiertos
  • Configuración del sistema
  • Propiedad de tareas de Work, enrutamiento de modelos y proveedores, ejecuciones, mensajes, actividad de herramientas, estado e identificadores de recursos Docker

Los valores confidenciales se cifran en la capa de aplicación cuando pasan por los asistentes de almacenamiento cifrado.

El almacenamiento de Work está dividido​

Las conversaciones de Work y los metadatos de las tareas viven en SQLite, pero los archivos de Work no. Cada tarea recibe un volumen con nombre de Docker dedicado, montado en /workspace. El contenedor es un estado de ejecución sustituible; el volumen con nombre es el sistema de archivos duradero de la tarea.

Esto significa que una copia de la base de datos por sí sola no es una copia de Work completa. Copia los volúmenes Docker correspondientes mediante el proceso de copia de volúmenes de tu host Docker. Libre WebUI etiqueta los volúmenes de Work que gestiona con ai.libre-webui.managed=true y el ID de su tarea propietaria.

Eliminar una tarea de Work borra permanentemente sus registros SQLite y el volumen con nombre gestionado. Cancelar una ejecución, detener una vista previa o reiniciar el backend no elimina sus archivos.

Compatibilidad con JSON​

Las instalaciones antiguas de Libre WebUI usaban archivos JSON para algunos datos. Las compilaciones actuales usan SQLite como ruta principal de almacenamiento y mantienen el acceso tras capas de servicios y modelos, para que el resto de la aplicación no necesite conocer el formato de persistencia.

Si actualizas una instalación antigua, haz una copia de todo el directorio de datos antes de iniciar el backend nuevo.

La activación heredada de plugins en .status.json se migra una sola vez a filas SQLite por usuario para las cuentas que existan durante la actualización, pero solo para definiciones integradas que coincidan exactamente con el hash fijado. Las definiciones personalizadas y ocultas heredadas permanecen en cuarentena hasta que un administrador las vuelva a importar, y su aprobación no restaura las filas de activación antiguas. Las cuentas posteriores empiezan sin plugins activos y los cambios de activación de cada cuenta son independientes.

Copia de seguridad​

Detén el backend antes de copiar la base de datos:

cp -R backend/data backend/data.backup

Para despliegues que usan DATA_DIR:

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

Si la instancia usa Work, copia también todos los volúmenes con nombre de Work gestionados mientras el backend esté detenido. Conserva las copias de la base de datos, la clave de cifrado y los volúmenes de Work correspondientes al mismo momento.

Restauración​

Detén el backend, sustituye el directorio de datos por tu copia y reinicia. Conserva el mismo ENCRYPTION_KEY; los valores cifrados no se pueden descifrar con otra clave.

Para Work, restaura los volúmenes con nombre bajo los nombres exactos registrados en la base restaurada antes de iniciar el backend. Libre WebUI puede volver a crear el contenedor de una tarea, pero no reconstruir archivos ausentes de la conversación.

Notas operativas​

  • SQLite funciona con WAL activado para mejorar las lecturas simultáneas.
  • El proceso del backend debe poder escribir en el directorio de datos.
  • Mantén DATA_DIR en almacenamiento persistente con Docker y Kubernetes.
  • Copia ENCRYPTION_KEY junto con la base de datos.
  • Contabiliza por separado los volúmenes con nombre de Work al medir, migrar o restaurar el almacenamiento.

Documentación relacionada​