NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações

Backup e restauração

Faça o backup do Nodaro auto-hospedado com um comando, restaure com outro e faça downgrade com segurança. Veja o que o backup guarda e como proteger a chave.

O backup de um Nodaro auto-hospedado é feito com um comando, e a restauração, com outro. O arquivo de backup guarda tudo o que o conjunto de serviços não consegue gerar de novo: o banco de dados, a sua mídia, a chave de criptografia da instância e o seu .env. A restauração também é a única forma de fazer downgrade, porque as migrações do banco de dados só avançam. Voltar a uma versão anterior significa restaurar o backup que você fez antes da atualização.

O que um backup contém

tools/community-backup.sh grava um único arquivo tar.gz:

No arquivo de backupO que é
db.dumpO Postgres, no formato custom do pg_dump: workflows, usuários, tarefas e registros de mídia
minio-data.tarA sua mídia gerada: imagens, vídeos e áudios
encryption-keyA chave da instância, que criptografa as chaves de provedor e os tokens de login das redes sociais. Um banco de dados restaurado sem ela guarda linhas que ninguém consegue ler.
envO seu .env: chaves de provedor e segredos
manifest.jsonA versão do app e o horário do backup, para o script de restauração

O Redis fica de fora de propósito: ele só guarda o estado de curta duração das tarefas.

O arquivo de backup é uma credencial

Ele contém o seu .env e a chave de criptografia. O script restringe o arquivo ao proprietário dele (chmod 600). Mantenha assim e guarde o arquivo de backup como uma senha. No Windows, o chmod não tem efeito real: mantenha o arquivo fora de pastas sincronizadas e de unidades compartilhadas, e restrinja-o com permissões NTFS se outras pessoas usarem o computador.

Fazer um backup

No diretório da instalação, onde fica o docker-compose.community.yml, com o conjunto de serviços rodando:

tools/community-backup.sh
# -> ./backups/nodaro-backup-<date>-v<version>.tar.gz
OpçãoO que faz
tools/community-backup.sh /path/to/backupsGrava o arquivo de backup em outro diretório
COMPOSE_FILE=my-compose.yml tools/community-backup.shUsa um arquivo do Compose com outro nome

O script mostra o que entrou no arquivo de backup. Se a chave de criptografia estiver faltando, ele avisa isso em destaque e sai com um erro, para que uma tarefa agendada perceba. Esse arquivo de backup não consegue restaurar as suas chaves de provedor.

A exportação do banco de dados é sempre consistente. A mídia gravada enquanto o backup roda pode ficar fora do arquivo. Para um instantâneo da mídia com consistência garantida, pare o app primeiro:

docker compose -f docker-compose.community.yml stop nodaro

No Windows, execute os scripts no Git Bash, o shell que o Git for Windows instala. O PowerShell e o bash do WSL quebram os caminhos do contêiner.

Quando fazer backup

Antes de toda atualização de versão major, em que o primeiro número muda, e com a frequência que os seus dados merecem. Uma linha de cron funciona do jeito que está:

0 3 * * * cd /path/to/install && tools/community-backup.sh >> backup.log 2>&1

Restaurar um backup

tools/community-restore.sh backups/nodaro-backup-<date>-v<version>.tar.gz

A restauração substitui o banco de dados e a mídia pelo conteúdo do arquivo de backup, então ela pede que você digite RESTORE antes de mexer em qualquer coisa. Depois, ela:

  1. Para o app e os clientes do banco de dados, auth e rest, porque as conexões abertas deles bloqueariam a restauração.
  2. Restaura o Postgres e verifica se ele funciona, em vez de confiar nos códigos de saída. Algumas mensagens inofensivas da imagem do Supabase são esperadas e aparecem na saída.
  3. Restaura a mídia e verifica se os buckets voltaram e se o MinIO está saudável. Em seguida, restaura a chave de criptografia e verifica o tamanho dela no volume. Por fim, restaura o seu .env, guardando antes à parte qualquer .env existente. Uma verificação que falha interrompe o script antes de o app iniciar: iniciar sem a chave certa criaria uma chave nova e deixaria todas as chaves de provedor restauradas ilegíveis para sempre.
  4. Inicia tudo de novo e espera pela verificação de integridade do próprio app. O script só informa sucesso depois que o app está no ar e, caso contrário, sai com um erro.

Quando ela terminar, abra http://localhost:3000/setup. Todos os cartões devem estar verdes.

Fazer downgrade de versão

Não existe reversão de migrações. Para voltar a uma versão anterior:

  1. Restaure o backup feito antes da atualização, como descrito acima.
  2. Fixe a imagem mais antiga, por exemplo ghcr.io/nodaroai/nodaro-community:v1.25.1, em NODARO_IMAGE ou no docker-compose.community.yml. As tags exatas vX.Y.Z nunca são movidas.
  3. Rode docker compose -f docker-compose.community.yml up -d nodaro.

Veja Atualização para as tags.

Fazer backup de uma implantação gerenciada

Fora do conjunto de serviços do Compose, quatro coisas guardam estado:

O quêComo protegê-lo
Supabase Postgres: workflows, perfis, tarefas e registros de mídiaUse a recuperação para um ponto no tempo (point-in-time recovery) do Supabase, nos planos pagos, ou rode pg_dump regularmente. Este é o backup mais importante.
O bucket de armazenamento: imagens, vídeos e áudios geradosAtive o versionamento do bucket e uma regra de ciclo de vida longa, para que os arquivos apagados possam ser recuperados. Adicione replicação entre regiões para recuperação de desastres, se precisar.
RedisNada para fazer backup. Ele só guarda o estado de curta duração das tarefas. Se você o perder, as execuções em andamento falham, e todo o resto se recupera a partir do Postgres na inicialização seguinte.
A chave de criptografia da instância, NODARO_ENCRYPTION_KEYGuarde-a junto com os backups do Postgres. Sem ela, as linhas restauradas das chaves de provedor, dos tokens de login das redes sociais e das credenciais do nó Saída de webhook não podem ser lidas. Os blocos mostram, então, missing (ausente), e as chaves precisam ser digitadas de novo; nada mais quebra.

Se o Postgres cair durante uma migração ou uma recuperação, a API reinicia em loop até conseguir acessar o banco de dados. Quando o Postgres voltar, reinicie o contêiner do Nodaro.

Restaurar em um novo projeto do Supabase

Uma restauração em um novo projeto do Supabase não mantém os privilégios do banco de dados. Uma função feita só para o servidor pode voltar podendo ser chamada pelos papéis do navegador, anon e authenticated. Uma tabela ou uma coluna que as migrações fecharam pode voltar legível ou gravável. Depois de qualquer restauração, liste as funções SECURITY DEFINER que esses papéis podem executar:

SELECT p.oid::regprocedure AS function,
       has_function_privilege('anon', p.oid, 'EXECUTE') AS anon,
       has_function_privilege('authenticated', p.oid, 'EXECUTE') AS authenticated
  FROM pg_proc p
 WHERE p.pronamespace = 'public'::regnamespace
   AND p.prosecdef
   AND p.prorettype NOT IN ('trigger'::regtype, 'event_trigger'::regtype)
   AND (has_function_privilege('anon', p.oid, 'EXECUTE')
        OR has_function_privilege('authenticated', p.oid, 'EXECUTE'))
 ORDER BY 1;

O resultado deve conter só as funções listadas em browser_callable no arquivo de teste do repositório supabase/tests/server-only-function-privileges.behavior.sql. Feche todas as outras funções, e indique também PUBLIC, porque anon e authenticated herdam o EXECUTE padrão dele:

REVOKE EXECUTE ON FUNCTION public.<name>(<args>) FROM PUBLIC, anon, authenticated;
GRANT EXECUTE ON FUNCTION public.<name>(<args>) TO service_role;

A migração 598 em supabase/migrations/ fecha as funções só do servidor e restaura os privilégios de tabelas e colunas que as migrações até ela definem. É seguro executá-la de novo. Para conferir um banco de dados restaurado com os privilégios esperados, execute o arquivo de teste com psql. Ele desfaz as próprias alterações e para na primeira coisa que estiver aberta:

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f supabase/tests/server-only-function-privileges.behavior.sql

Solução de problemas

  • the db service is not running. Inicie o conjunto de serviços primeiro: docker compose -f docker-compose.community.yml up -d.
  • As chaves de provedor aparecem como missing (ausente) depois de uma restauração. O banco de dados foi restaurado sem a encryption-key correspondente, ou com outra. Restaure a partir de um arquivo de backup que tenha a chave, ou digite as chaves de novo em /setup.
  • A verificação da restauração falhou. O script se recusa a deixar um banco de dados restaurado pela metade em silêncio. Rode a restauração de novo. Se ela falhar repetidamente, o arquivo de backup pode estar truncado: compare o tamanho dele com o do original.
  • could not read the encryption key durante um backup no Windows. Você não está no Git Bash, ou o contêiner do app não está rodando. Rode o backup de novo no Git Bash, com o conjunto de serviços no ar. O arquivo de backup sobre o qual o script avisou não é um backup utilizável.
  • media restore verification FAILED ou encryption key verification FAILED. O script parou de propósito e não iniciou o app. Verifique o volume que ele indica, corrija a causa, normalmente um contêiner parado ou um disco cheio, e rode a restauração de novo. É seguro repetir.

Perguntas frequentes

Como faço o backup de um Nodaro auto-hospedado?

No diretório da instalação, com o conjunto de serviços rodando, execute tools/community-backup.sh. Ele grava um único arquivo de backup em ./backups, com o banco de dados, a mídia, a chave de criptografia da instância e o seu .env.

Como restauro um backup?

Execute tools/community-restore.sh com o caminho do arquivo de backup. A restauração é destrutiva, então ela pede que você digite RESTORE antes. Ela verifica o banco de dados, a mídia e a chave de criptografia antes de iniciar o app de novo.

Por que as minhas chaves de provedor aparecem como missing depois de uma restauração?

O banco de dados foi restaurado sem a chave de criptografia correspondente. Restaure a partir de um arquivo de backup que contenha a chave, ou digite as chaves de novo em /setup. Nada mais quebra.

Preciso fazer backup do Redis?

Não. O Redis só guarda o estado de curta duração das tarefas. Se você o perder, as execuções em andamento falham, e todo o resto se recupera a partir do banco de dados na inicialização seguinte.

Posso rodar os scripts de backup no Windows?

Sim, no Git Bash, o shell que o Git for Windows instala. O PowerShell e o bash do WSL quebram os caminhos do contêiner, e a chave de criptografia fica, então, fora do arquivo de backup.

Última atualização

Nesta página