Backup e recuperacao

O self-hosting so tem valor se a recuperacao for realmente possivel. O QuoteNode deve por isso ser operado com uma estrategia de backup testada.

O que deve ser salvaguardado

Cada backup deve capturar tres componentes:

1. Dump da base de dados - exportacao PostgreSQL em formato custom (pg_dump --format=custom)
2. Armazenamento de ficheiros - uploads, logotipos e PDF gerados, tipicamente como files.tar.gz
3. Manifesto de integridade - ficheiro checksums.sha256 com hashes dos artefactos de backup

Esta combinacao permite verificar rapidamente se um backup foi corrompido ou adulterado.

Backup online

O modo mais comum faz um dump consistente da base de dados e arquiva o file storage sem parar a aplicacao. Para a maioria das equipas, este e o modelo recomendado.

Como funciona:

• pg_dump cria um snapshot transacional consistente sem bloquear tabelas
• o armazenamento de ficheiros e arquivado em paralelo
• os artefactos sao verificados por checksum e podem ser cifrados antes de armazenamento

Limitacoes:

• transacoes ainda nao commitadas no instante do dump nao entram no snapshot
• para a maioria das organizacoes, isto e o comportamento correto e suficiente

Backup offline

Antes de upgrades sensiveis ou migracoes maiores, podes optar por:

1. parar os contentores aplicacionais
2. correr pg_dump diretamente sobre o PostgreSQL
3. arquivar os volumes de ficheiros
4. voltar a arrancar a stack

Este metodo elimina transacoes em voo, mas exige uma pequena janela de manutencao.

Agendamento

Os backups podem ser executados por um worker dedicado:

• com cron configuravel
• com trigger manual por admin
• com protecao contra concorrencia

Na arquitetura padrao, o backup-worker corre o backend em modo dedicado de backup.

Janela e timeout

Cada backup deve respeitar um timeout operacional razoavel. Para bases maiores, esse limite pode ser aumentado, mas o objetivo e evitar jobs presos indefinidamente.

Trigger manual

Os administradores podem lancar um backup manual a partir do painel administrativo ou por API quando precisam de uma copia imediata antes de uma alteracao de risco.

Protecao contra concorrencia

O worker deve impedir que dois backups concorram ao mesmo tempo, usando locks operacionais ou o padrao SKIP LOCKED.

Armazenamento local e remoto

Armazenamento local

Por defeito, os backups ficam em BACKUP_LOCAL_DIR, normalmente montado num volume Docker persistente. Isto chega para desenvolvimento e para pequenas instalacoes.

Para producao, um backup apenas no mesmo disco da base de dados nao e protecao suficiente contra falha de hardware.

Armazenamento remoto via rclone

Quando BACKUP_RCLONE_REMOTE esta configurado, o QuoteNode envia uma copia para um destino remoto apos a criacao local. Isto permite trabalhar com:

• S3 compativel
• Google Cloud Storage
• Azure Blob Storage
• SFTP
• WebDAV

Se o upload remoto falhar, a copia local deve permanecer preservada.

Politica de retention

O QuoteNode pode limpar backups locais antigos apos cada execucao bem-sucedida, mantendo apenas a janela definida de historico. Para copias remotas, a retention deve ser definida no provider de armazenamento.

Cifragem

Quando necessario, os backups podem ser cifrados com GPG:

• define BACKUP_GPG_RECIPIENT
• cifra dump e arquivo de ficheiros antes de armazenamento
• os ficheiros passam a ter extensao .gpg
• a restauracao exige a chave privada correspondente

Quando cifrar

A cifragem e especialmente importante quando os backups saem da tua infraestrutura principal e passam a viver em cloud ou em storage gerido por terceiros.

O que acontece sem a chave privada

Sem a chave privada correta, o backup pode continuar integro mas torna-se inutilizavel para restore. O processo de backup deve incluir tambem a estrategia de custodia da chave GPG.

Metadados e auditoria

Cada backup deve ter registo de:

• estado
• hora de inicio e fim
• origem do trigger
• tamanho
• destino
• checksum
• erro, se aplicavel

Os ultimos backups devem ser visiveis no painel administrativo e via API para facilitar supervisao operacional.

Download de backups

Os administradores podem descarregar arquivos de backup a partir do painel quando o backup local foi concluido com sucesso.

Quando usar o download direto

Esta opcao e util para:

• guardar uma copia offline
• preparar uma migracao
• validar restores fora do ambiente principal

Limitacao para storage remoto

Quando o backup existe apenas em storage remoto, o download deve ser feito diretamente no provider remoto e nao pela aplicacao.

Restauracao

Uma restauracao tipica envolve:

1. parar a stack
2. restaurar a base de dados
3. repor ficheiros e PDF
4. voltar a subir os contentores
5. verificar checksums e funcionamento

Restauracao parcial

Como o dump esta em formato custom, tambem e possivel restaurar apenas tabelas ou subconjuntos usando pg_restore com flags especificas.

Restauracao de backups cifrados

gpg --decrypt backup.dump.gpg > backup.dump
gpg --decrypt files.tar.gz.gpg > files.tar.gz

Depois segue-se o procedimento normal de restore.

Timeout de backup

Cada operacao de backup deve ter um timeout maximo. Se nao terminar a tempo, o job e marcado como falhado para evitar que a fila fique bloqueada.

Estrategia de teste

Backups so teem valor real quando o procedimento de restore e treinado. Por isso, a equipa deve definir uma cadencia minima para testes de recuperacao em ambiente isolado.

Disaster recovery

Em caso de perda total do servidor, a recuperacao depende de:

• backup valido
• copia segura do .env
• mesma chave DB_ENCRYPTION_KEY
• procedimento de restore testado

Reconstrucao a partir do zero

Num servidor novo com Docker instalado:

1. recria docker-compose.yml
2. restaura o .env original
3. copia o ficheiro de backup para o host
4. corre o script de restore ou executa manualmente pg_restore e extracao de ficheiros
5. valida login, propostas, uploads e PDF

Sem a mesma DB_ENCRYPTION_KEY, os dados cifrados nao voltam a ser legiveis.

Dry run de restauracao

Sempre que possivel, faz um restore de teste num ambiente isolado. Um backup nunca testado nao deve ser considerado suficiente para disaster recovery.

Estrategia recomendada

• backups diarios
• pelo menos uma copia remota
• cifragem quando os dados saem da infraestrutura
• testes regulares de restauracao
• monitorizacao dos logs de backup
• pelo menos sete dias de historico de backups