Portabilidade de dados

O Libre WebUI exporta e importa um arquivo JSON versionado por usuário em Configurações → Gerenciamento de dados. Ele serve para mover dados pessoais compatíveis entre instalações ou restaurá-los em uma conta. Não é um backup completo do servidor.

Arquivo versão 3

O formato atual é identificado por:

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

O backend cria a exportação com consultas autenticadas e limitadas ao usuário. Ela contém:

• preferências, exceto a referência a um perfil de voz reutilizável selecionado;
• pastas de chat;
• sessões, mensagens, ramificações, avaliações, artefatos e configurações por chat;
• notas independentes e seu estado fixado;
• coleções de conhecimento;
• conteúdo e metadados extraídos de documentos, associações e segmentos de texto.

Embeddings não são exportados por serem derivados. Regenere-os após importar quando a busca semântica estiver ativa. O arquivo contém o texto extraído usado por RAG, não os bytes originais, portanto não recria o upload byte a byte.

Cada arquivo contém uma lista exclusions. A versão 3 exclui:

• contas, senhas, sessões e estado OAuth;
• credenciais de provedores e variáveis criptografadas;
• gravações e transcrições de vozes clonadas, que são biométricas;
• personas e suas memórias;
• arquivos gerados de imagem, áudio e vídeo;
• histórico de revisões e anexos de notas;
• tarefas Work, execuções, sandboxes e volumes Docker/Kubernetes.

Canais, notificações, calendários e automações também ficam fora por serem estado da instância/equipe e viajam em um backup completo.

Para recuperação total, use backup do banco/diretório com o mesmo ENCRYPTION_KEY. Work também exige backup consistente de seus volumes nomeados. Consulte Migração e backup do SQLite e espaços Work.

Integridade e validação da exportação

A versão 3 protege o payload com um resumo SHA-256. A forma libre-json-sort-v1 omite o campo superior integrity, ordena lexicograficamente as chaves de todos os objetos, preserva a ordem dos arrays e calcula o hash do JSON compacto em UTF-8. A importação rejeita um arquivo cujo resumo não coincida, mesmo se o JSON for válido.

O resumo detecta corrupção acidental e alterações. Não é assinatura digital, não autentica quem criou o arquivo e não oferece confidencialidade. Trate-o como uma cópia privada de chats e notas.

Antes do download, a exportação executa as mesmas verificações de esquema, tamanho, IDs e contagens da importação e confirma que o JSON formatado não supera 50 MiB. Em vez de oferecer algo que já sabe não poder restaurar, retorna um erro preciso.

Limites atuais:

• 50 MiB por arquivo enviado ou gerado;
• 100 pastas;
• 5.000 sessões;
• 100.000 mensagens;
• 100 notas, títulos de até 200 caracteres e conteúdo de até 200.000;
• 5.000 coleções;
• 5.000 documentos;
• 100.000 segmentos;
• campos gerais até 2.000.000 de caracteres e IDs até 256, com limites menores quando o recurso tiver.

Importação segura

Selecionar um arquivo solicita uma pré-análise imediata. As configurações mostram totais, previsões de criação/sobrescrita/omissão, remapeamentos e avisos antes de ativar a importação. Alterar a política recalcula a prévia.

A pré-análise verifica o resumo, migra formatos antigos compatíveis, valida esquema completo, contagens, IDs únicos, horários, limites e relações, e planeja conflitos e referências sem gravar. Relações pendentes são rejeitadas em vez de descartadas. O backend repete tudo na importação real. Todas as gravações ocorrem em uma transação tanto no SQLite quanto no PostgreSQL; qualquer erro reverte preferências, pastas, sessões/mensagens, notas, coleções, documentos e segmentos juntos.

Duas políticas estão disponíveis:

• Ignorar duplicados mantém registros com IDs iguais e importa novos. Preferências são mescladas.
• Sobrescrever existentes substitui IDs iguais. Preferências substituem os padrões do Libre WebUI. Registros ausentes nunca são excluídos.

Ambas são idempotentes para IDs iguais. Se outra conta já possuir um ID, o Libre WebUI o remapeia deterministicamente com todas as referências. Nunca lê nem sobrescreve recursos de outro usuário. Referências excluídas ou indisponíveis, como personas de outra instalação, são exceções documentadas; a prévia avisa que a sessão será desvinculada.

O resultado informa quantidades criadas, sobrescritas e ignoradas. Após sucesso, o Libre recarrega preferências, chats e pastas e atualiza documentos.

Arquivos antigos

O importador aceita libre-webui-user-data versão 2 e migra para a 3 durante a validação. A versão 2 não tinha resumo nem notas, então não é possível verificar sua origem nem recuperar notas nunca exportadas. A prévia informa ambas as limitações.

Também aceita o antigo libre-webui-export versão 1.0, gerado no navegador com preferências e apenas sessões carregadas. Seu array documents era sempre vazio e não continha pastas, notas, coleções nem segmentos. Essas limitações são informadas antes.

Endpoints HTTP

Todos exigem token Bearer ou sessão do usuário:

Método	Endpoint	Finalidade
GET	/api/preferences/export	Criar arquivo v3 do usuário
POST	/api/preferences/import/preflight	Validar e planejar sem gravar
POST	/api/preferences/import	Validar e importar em transação

A interface envia o arquivo no campo multipart/form-data chamado archive e a política no campo strategy. O limite é 50 MiB. Para migrações menores pela API, os dois endpoints POST também aceitam JSON:

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

strategy é skip ou overwrite. Para compatibilidade com o cliente antigo, mergeStrategy: "merge" corresponde a skip e mergeStrategy: "replace" a overwrite.