Pular para o conteúdo principal

Armazenamento SQLite

Por padrão, o Libre WebUI armazena os dados do aplicativo no SQLite. A camada de armazenamento mantém chats, mensagens, usuários, preferências, documentos, trechos de documentos, personas, credenciais de plugins, memórias e metadados relacionados em um único banco de dados local.

Localização do banco de dados​

As inicializações a partir do código-fonte usam esta ordem de locais:

  1. DATA_DIR, quando definido; valores relativos são resolvidos a partir do diretório do backend.
  2. backend/data, quando não estiver definido.

Para manter a compatibilidade com versões anteriores, um perfil de código-fonte sem essa definição continua usando backend/backend/data quando esse é o único armazenamento persistente existente. Se os dois locais contiverem estado, a inicialização exigirá uma seleção explícita e nunca copiará nem mesclará os dados.

O inicializador distribuído via npm/Homebrew usa ~/.libre-webui por padrão e resolve um DATA_DIR relativo explícito a partir do diretório de trabalho de quem o chamou. Implantações com Docker e Kubernetes fornecem caminhos absolutos do contêiner.

O arquivo SQLite se chama data.sqlite.

Exemplo:

DATA_DIR=/var/lib/libre-webui

O que o SQLite armazena​

  • Usuários e funções
  • Sessões e mensagens
  • Preferências e configurações da interface
  • Documentos e trechos
  • Personas e configurações de personas
  • Memórias de personas e estado de mutação
  • Credenciais de plugins e seus vínculos de roteamento/autenticação, variáveis, ativações por usuário, aprovações de definições graváveis e catálogos de modelos descobertos
  • Configurações do sistema
  • Propriedade de tarefas do Work, roteamento de modelo/provedor, execuções, mensagens, atividade de ferramentas, status e identificadores de recursos do Docker

Valores confidenciais são criptografados na camada do aplicativo quando passam pelos auxiliares de armazenamento criptografado.

O armazenamento do Work é separado​

As conversas e os metadados de tarefas do Work ficam no SQLite, mas os arquivos do Work não. Cada tarefa recebe um volume nomeado dedicado do Docker, montado em /workspace. O contêiner é um estado de execução substituível; o volume nomeado é o sistema de arquivos persistente da tarefa.

Isso significa que um backup somente do banco de dados não é um backup completo do Work. Faça backup dos volumes correspondentes usando o processo de backup de volumes do seu host Docker. O Libre WebUI identifica os volumes gerenciados do Work com ai.libre-webui.managed=true e o ID da tarefa proprietária.

Excluir uma tarefa do Work remove permanentemente seus registros do SQLite e seu volume nomeado gerenciado. Cancelar uma execução, interromper uma prévia ou reiniciar o backend não exclui os arquivos.

Compatibilidade com JSON​

Instalações antigas do Libre WebUI usavam arquivos JSON para alguns dados. As versões atuais usam o SQLite como caminho principal de armazenamento e mantêm o acesso ao armazenamento atrás das camadas de serviço/modelo, para que o restante do aplicativo não precise conhecer o formato de persistência.

Se você estiver atualizando uma instalação antiga, faça backup de todo o diretório de dados antes de iniciar o backend mais recente.

A ativação de plugins legados em .status.json é migrada uma única vez para linhas SQLite por usuário, para contas existentes no momento da atualização, mas somente para definições incluídas no pacote e vinculadas por hash exato. Definições personalizadas e definições de sombra legadas permanecem em quarentena até que um administrador as reimporte, e a aprovação não restaura linhas de ativação antigas. Contas criadas depois começam sem plugins ativos, e as alterações de ativação de cada conta são independentes.

Backup​

Interrompa o backend antes de copiar o banco de dados:

cp -R backend/data backend/data.backup

Para implantações que usam DATA_DIR:

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

Se a instância usa o Work, faça também backup de todos os volumes nomeados gerenciados do Work enquanto o backend estiver interrompido. Mantenha o backup do banco de dados, da chave de criptografia e dos volumes do Work referente ao mesmo ponto no tempo.

Restauração​

Interrompa o backend, substitua o diretório de dados pelo backup e reinicie. Mantenha a mesma ENCRYPTION_KEY; valores criptografados não podem ser descriptografados com outra chave.

Para o Work, restaure os volumes nomeados com os nomes exatos registrados no banco de dados restaurado antes de iniciar o backend. O Libre WebUI consegue recriar o contêiner de uma tarefa, mas não consegue reconstruir arquivos ausentes do workspace a partir do histórico da conversa.

Observações operacionais​

  • O SQLite funciona com WAL habilitado para melhorar as leituras simultâneas.
  • O diretório de dados deve permitir gravação pelo processo do backend.
  • Mantenha DATA_DIR em armazenamento persistente no Docker e no Kubernetes.
  • Faça backup de ENCRYPTION_KEY junto com o banco de dados.
  • Considere separadamente os volumes nomeados do Work ao medir, migrar ou restaurar o armazenamento.

Documentação relacionada​