# Backup e restauração

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

Source: https://nodaro.ai/pt-BR/docs/self-hosting/backups

O **backup** de um Nodaro self-hosted é feito com um comando, e a **restauração**, com outro. O arquivo de backup guarda tudo o que a stack 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 backup | O que é |
| --- | --- |
| `db.dump` | O Postgres, no formato custom do pg_dump: workflows, usuários, jobs e registros de mídia |
| `minio-data.tar` | A sua mídia gerada: imagens, vídeos e áudios |
| `encryption-key` | A 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.** |
| `env` | O seu `.env`: chaves de provedor e segredos |
| `manifest.json` | A 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 dos jobs.

**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 a stack **rodando**:

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

| Opção | O que faz |
| --- | --- |
| `tools/community-backup.sh /path/to/backups` | Grava o arquivo de backup em outro diretório |
| `COMPOSE_FILE=my-compose.yml tools/community-backup.sh` | Usa 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 um job agendado perceba. Esse arquivo de backup não consegue restaurar as suas chaves de provedor.

O dump do banco de dados é sempre consistente. A mídia gravada enquanto o backup roda pode ficar fora do arquivo. Para um snapshot da mídia com consistência garantida, pare o app primeiro:

```bash
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á:

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

## Restaurar um backup
```bash
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](https://nodaro.ai/docs/self-hosting/updating) para as tags.

## Fazer backup de uma implantação gerenciada
Fora da stack do Compose, quatro coisas guardam estado:

| O quê | Como protegê-lo |
| --- | --- |
| **Supabase Postgres**: workflows, perfis, jobs e registros de mídia | Use 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 gerados | Ative 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. |
| **Redis** | Nada para fazer backup. Ele só guarda o estado de curta duração dos jobs. 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_KEY` | Guarde-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** (Webhook Output) 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.

## Solução de problemas
- **`the db service is not running`.** Inicie a stack 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 a stack 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.

## Frequently asked questions

### Como faço o backup de um Nodaro self-hosted?

No diretório da instalação, com a stack 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 dos jobs. 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.