Portabilidad de datos

Libre WebUI puede exportar e importar un archivo JSON versionado por usuario desde Ajustes → Gestión de datos. Está pensado para trasladar datos personales compatibles entre instalaciones o restaurarlos en una cuenta. No es una copia de seguridad completa del servidor.

Versión 3 del archivo

El formato actual se identifica mediante:

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

El backend crea la exportación mediante consultas autenticadas y limitadas al usuario. Contiene:

• preferencias del usuario, excepto la referencia de un perfil de voz reutilizable seleccionado;
• carpetas de chat;
• sesiones, mensajes, ramas, valoraciones, artefactos y ajustes por chat;
• Notes independientes, incluido su estado fijado;
• colecciones de conocimiento;
• contenido y metadatos extraídos de documentos, asociaciones de sesiones/colecciones y fragmentos de texto.

Los embeddings no se exportan porque son datos derivados. Regénéralos tras importar si está activa la recuperación semántica. El archivo contiene el texto extraído que utiliza RAG, no los bytes del archivo subido, por lo que no puede recrearlo byte por byte.

Cada archivo incluye una lista exclusions. La versión 3 excluye deliberadamente:

• cuentas, contraseñas, sesiones y estado de OAuth;
• credenciales de proveedores y variables cifradas de plugins;
• grabaciones y transcripciones de voces clonadas, que son datos biométricos y requieren un tratamiento aparte basado en el consentimiento;
• personas y memoria de personas;
• archivos de la biblioteca de imágenes, audio y vídeo generados;
• historial de revisiones y adjuntos de notas;
• tareas, ejecuciones y entornos de Work y volúmenes Docker o Kubernetes.

Los canales, notificaciones, calendarios y automatizaciones también quedan fuera; son estado de instancia/equipo y viajan con una copia completa del servidor.

Para una recuperación completa, utiliza una copia de la base de datos/directorio de datos con el mismo ENCRYPTION_KEY. Work también necesita una copia coherente de sus volúmenes con nombre. Consulta Migración y copia de SQLite y Espacios de Work.

Integridad y validación de la exportación

La versión 3 protege la carga con un resumen SHA-256. La forma canónica libre-json-sort-v1 omite el campo integrity superior, ordena lexicográficamente las claves de cada objeto JSON, conserva el orden de las matrices y calcula el hash del JSON compacto en UTF-8. La importación rechaza un archivo v3 cuyo resumen no coincida aunque el JSON sea válido.

El resumen detecta corrupción accidental y cambios posteriores. No es una firma digital, no autentica al creador ni hace confidencial el archivo. Trátalo como cualquier copia de chats y Notes privados.

Antes de ofrecer la descarga, la exportación ejecuta las mismas comprobaciones de esquema, tamaños, ID y recuentos que la importación. También comprueba que el JSON formateado no supere el límite de 50 MiB. Devuelve un error preciso en lugar de ofrecer un archivo que Libre WebUI ya sabe que no podrá restaurar.

Límites actuales:

• 50 MiB por archivo subido o generado;
• 100 carpetas de chat;
• 5,000 sesiones;
• 100,000 mensajes;
• 100 Notes, con títulos de hasta 200 caracteres y contenido de hasta 200,000;
• 5,000 colecciones de conocimiento;
• 5,000 documentos;
• 100,000 fragmentos;
• campos de contenido general de hasta 2,000,000 caracteres e ID de hasta 256, con límites menores donde el recurso los imponga.

Importación segura

Al seleccionar un archivo, el backend lo comprueba inmediatamente. Antes de habilitar la acción final, Ajustes muestra totales entrantes, recuentos previstos de creación/sobrescritura/omisión, reasignaciones de ID y avisos de migración. Cambiar la política de conflictos calcula una vista previa nueva.

La comprobación valida el resumen cuando existe, migra formatos antiguos compatibles, comprueba el esquema completo, recuentos, ID únicos, marcas temporales, límites y relaciones, y planifica conflictos y reasignaciones sin escribir. Rechaza asociaciones huérfanas de carpetas, colecciones, mensajes o documentos en vez de descartarlas. El backend repite la validación y planificación para la importación real. Todas las escrituras se realizan en una transacción tanto en SQLite como PostgreSQL; un error revierte preferencias, carpetas, sesiones/mensajes, Notes, colecciones, documentos y fragmentos juntos.

Hay dos políticas:

• Omitir duplicados conserva los registros con ID coincidentes e importa los nuevos. Las preferencias se combinan con las actuales.
• Sobrescribir existentes sustituye los registros con ID coincidentes. Las preferencias sustituyen los valores predeterminados de Libre WebUI. Nunca se borran registros ausentes del archivo.

Ambas son idempotentes para ID coincidentes. Si un ID ya pertenece a otra cuenta, Libre WebUI lo reasigna de forma determinista junto con todas sus referencias. Nunca sobrescribe ni lee recursos ajenos. Las referencias a recursos excluidos o no disponibles, como una persona de otra instalación, son una excepción documentada: la comprobación informa de que la sesión se desvinculará antes de importar.

El resultado muestra recuentos creados, sobrescritos y omitidos de carpetas, sesiones, Notes, colecciones y documentos. Tras importar correctamente, Libre recarga preferencias, chats y carpetas y actualiza los documentos.

Archivos anteriores

El importador acepta archivos libre-webui-user-data versión 2 y los migra a v3 durante la validación. La v2 no tenía resumen ni Notes, por lo que Libre no puede verificar su origen ni recuperar notas que nunca se exportaron. La vista previa indica ambas limitaciones.

También acepta el antiguo formato libre-webui-export versión 1.0. Ese formato del navegador contenía preferencias y solo las sesiones cargadas allí. Su matriz documents siempre estaba vacía y no contenía carpetas, Notes, colecciones ni fragmentos. Libre informa de estas limitaciones antes de importar.

Endpoints HTTP

Todos los endpoints requieren el token Bearer o la sesión del usuario autenticado:

Método	Endpoint	Finalidad
GET	/api/preferences/export	Crear el archivo v3 del usuario actual
POST	/api/preferences/import/preflight	Validar y planificar sin escrituras
POST	/api/preferences/import	Validar e importar en una transacción

La interfaz envía el archivo como campo multipart/form-data llamado archive y la política como strategy. El límite es 50 MiB. Para migraciones pequeñas por API, los dos endpoints POST aceptan JSON:

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

strategy es skip u overwrite. Para mantener la compatibilidad con el cliente anterior, mergeStrategy: "merge" equivale a skip y mergeStrategy: "replace" a overwrite.