Backups e Restauração

O PrimeForge inclui um sistema portátil e criptografado de backup e restauração para os seus sites gerenciados. Cada backup é criptografado com AES-256 no próprio servidor e enviado para um armazenamento compatível com S3 — um servidor MinIO seu ou um provedor externo, como AWS S3 ou Backblaze B2. O objetivo é simples: você deve conseguir recuperar um site depois de uma alteração arriscada, uma falha de disco ou até recriá-lo em outro servidor da sua organização — sem depender de acesso manual por SSH.

Esta página explica como configurar o destino dos backups, como criar, agendar e restaurar backups, como funciona a criptografia de chave dupla e como restaurar um site em um servidor diferente daquele em que ele foi criado.

#Como o backup funciona

Todo backup é feito no próprio servidor onde o site roda: o Agent coleta os componentes escolhidos (banco de dados, storage/, .env, arquivos de configuração etc.), monta um arquivo tar.gz, criptografa esse arquivo e grava o resultado (.tar.gz.enc). O arquivo não criptografado é apagado imediatamente após a criptografia, e um checksum SHA-256 do arquivo cifrado é guardado para verificação de integridade na hora de restaurar. Em seguida o arquivo cifrado é enviado para o armazenamento de backups da organização.

#Criptografia de chave dupla

A criptografia usa um esquema de duas chaves combinadas, para que nem o painel sozinho nem você sozinho consigam abrir o backup:

1. Sua senha — informada por você no momento de criar o backup. Em um backup manual ela nunca é armazenada de forma permanente: fica apenas na cache do painel por, no máximo, 10 minutos enquanto o job de backup roda, e é apagada assim que a criptografia termina. Nunca é gravada em disco, em log, nem incluída no payload da fila. (Backups agendados são a exceção — veja abaixo.)
2. Chave do servidor — 32 bytes aleatórios gerados exclusivamente para aquele backup e guardados de forma criptografada no banco do painel.

As duas são combinadas por uma derivação HKDF-SHA256 para produzir a chave final de 256 bits usada na criptografia:

chave_final = HKDF-SHA256(sua_senha + chave_do_servidor)

Na prática, isso significa que:

• Conhecer apenas a senha não basta para descriptografar — falta a chave do servidor.
• Conhecer apenas a chave do servidor não basta — falta a sua senha.
• Os dois fatores são obrigatórios para qualquer restauração.

Aviso importante sobre a senha. A sua senha de criptografia é a única forma de abrir o backup, e o PrimeForge não a armazena. Se você perdê-la, o backup se torna permanentemente irrecuperável — não existe recuperação, redefinição ou suporte que consiga abrir o arquivo. Guarde a senha em um gerenciador de senhas (1Password, Bitwarden etc.), rotulada com o nome do site e a data do backup.

#Termos de backup

Antes do primeiro backup, cada usuário precisa aceitar os termos e condições de backup: o botão Aceitar termos de backup aparece no cabeçalho de Operações → Backups no lugar de Criar backup. O modal cobre a sua responsabilidade sobre a senha e as chaves de restauração exportadas (o PrimeForge não pode recuperá-las), o uso de disco, a política de "sem garantias" quanto à recuperação e o fato de que os arquivos podem conter dados sensíveis. Marque as duas confirmações e clique em Aceitar — ao aceitar, você confirma que entende que uma senha perdida significa um backup perdido.

#O destino dos backups

Backups são armazenados somente em S3. Enquanto a organização não tem um destino, a página Backups mostra o aviso Configure o destino dos backups e o botão Criar backup fica desabilitado. A configuração fica em Configurações → API e integrações → Armazenamento de backups (Admin ou acima), e oferece duas origens:

• Um dos meus servidores MinIO — escolha um servidor pronto da organização que rode MinIO (como o Servidor Principal do exemplo) e clique em Salvar e provisionar. O PrimeForge abre um túnel WireGuard privado entre o host do painel e esse servidor (o servidor libera para o painel apenas a porta do MinIO), cria o bucket primeforge-backups e uma chave de acesso restrita a ele, e confere que consegue gravar ali antes de salvar. Esse túnel aparece na página Rede do servidor como o peer Painel PrimeForge; ele é aberto e fechado por aqui, não pela página Rede, e é desfeito quando você aponta o armazenamento para outro lugar.
• S3 externo — aponte os backups para AWS S3, Backblaze B2, Cloudflare R2, DigitalOcean Spaces ou qualquer provedor compatível com S3: informe a URL do endpoint, a região, a Access Key, a Secret Key (depois de salva, deixe em branco para manter), o bucket e clique em Salvar configurações S3.

Nas duas origens você define também:

• Prefixo de caminho — a pasta dentro do bucket (padrão primeforge-backups/).
• Manter cópia local após upload para o S3 (ligado por padrão) — o arquivo criptografado também fica no servidor do site, para restaurar e baixar sem buscar no S3. Desligado, a cópia local é apagada assim que o envio termina.

Se o envio para o armazenamento falhar, o backup é marcado como Falhou, com o motivo na lista — ele nunca é dado como concluído sem ter chegado ao destino. Se você trocar o destino depois, os backups antigos continuam no bucket anterior: a lista os marca como Armazenamento alterado, e eles só voltam a ser restaurados ou baixados se você apontar o armazenamento de volta para lá.

#Criando um backup

1. Acesse Operações → Backups no menu do topo (ou use Mais → Criar Backup no cabeçalho de qualquer site no ar).
2. Clique em Criar backup.
3. Selecione o site — só aparecem sites já provisionados em servidores prontos.
4. Informe uma senha de criptografia (mínimo de 8 caracteres) e confirme.
5. Escolha quais componentes incluir (veja a tabela abaixo).
6. Confirme.

O job roda em segundo plano e o status (Pendente, Em execução, Pronto, Falhou) é atualizado na lista de backups. No topo da página, cartões mostram o total de backups, o espaço ocupado e o destino configurado. Cada linha mostra o site, o status, o armazenamento, os componentes, o tamanho, quem criou e quando.

#Componentes do backup

Você escolhe exatamente o que entra em cada backup. Os padrões cobrem o essencial para recuperar um site funcional:

O componente Origens dos serviços é o que viabiliza a restauração entre servidores (veja mais abaixo): ele registra, no momento do backup, se o banco, o Redis, o S3 e o Reverb estavam no próprio servidor (interno) ou em outro servidor da malha (externo).

#Backups agendados

Em Operações → Backups → Agendamentos (o botão Agendamentos no cabeçalho da lista) você cria uma rotina por site com Novo agendamento: diário, semanal (dia da semana) ou mensal (dia 1–28), no horário e fuso horário que escolher, com os componentes de sempre. O painel roda o backup sozinho — mesma criptografia, mesmo destino do backup manual — e mantém só as últimas N cópias daquele agendamento (Manter as últimas, de 1 a 60): as mais antigas são apagadas do servidor e do armazenamento assim que uma nova termina.

Para rodar sem você, a senha de criptografia fica guardada criptografada no painel (com a chave da aplicação). Essa é a diferença para o backup manual, que nunca persiste a senha. Na hora de restaurar um backup agendado, ligue Usar a senha do agendamento e o painel descriptografa com ela sem que ela passe pelo navegador; para restaurar em outra conta, você ainda precisa digitá-la.

A lista de agendamentos mostra, para cada um, quando roda, a próxima rodada, o resultado da última, quantas cópias mantém e se está ativo. Cada agendamento pode ser Editado (inclusive trocando a senha), Pausado/Ativado, Rodado agora ou Excluído — excluir para a rotina; os backups já feitos continuam na lista, marcados como Agendado. Uma rodada é pulada, com aviso no sino, quando o site não está no ar, o armazenamento de backups não está configurado ou a rodada anterior ainda não terminou. Falhas de backup agendado chegam ao sino e aos webhooks (backup.failed); sucessos são opcionais (backup.succeeded).

#Restaurando um backup

#Pré-requisitos

Antes de restaurar, confirme que:

• O site de destino existe e tem o modo de banco e os serviços corretos habilitados.
• O servidor de destino oferece os serviços necessários (PostgreSQL, Redis etc.) compatíveis com as origens de serviço do backup.
• Você tem em mãos a senha de criptografia usada quando o backup foi criado (ou o backup veio de um agendamento).

#Processo de restauração

1. Na lista de Backups, localize um backup com status Pronto.
2. Clique em Restaurar.
3. Informe a senha de criptografia — ou ligue Usar a senha do agendamento, se o backup veio de um agendamento.
4. Escolha o destino da restauração: Mesmo site (sobrescrever atual) ou Servidor diferente (criar novo site).
5. Confirme.

O PrimeForge então: verifica o checksum SHA-256 do arquivo criptografado, descriptografa o backup usando a sua senha combinada com a chave do servidor, para os processos do site (as unidades systemd do site), substitui o banco de dados, o storage/, o ambiente e os arquivos de configuração, e reinicia esses processos. Se a restauração falhar — uma senha digitada errado, por exemplo —, o backup continua Pronto e a lista mostra o motivo da última tentativa, para você tentar de novo.

Cada linha pronta também oferece Baixar (o arquivo cifrado) e Exportar chave — a chave de restauração daquele backup, necessária para restaurá-lo em outra conta do PrimeForge. Copie e guarde com o mesmo cuidado da senha.

#Restauração entre servidores (cross-server)

Escolha Servidor diferente (criar novo site) e o servidor de destino para recriar o site em outro servidor da sua organização — útil para mover um site de um servidor para outro, ou para recuperar um site em um servidor novo depois de uma falha.

Aqui é onde o componente Origens dos serviços entra em ação. Como o backup registra se cada serviço era interno ou externo, o painel valida o destino antes de começar:

• Se nenhum servidor da organização oferecer um serviço interno obrigatório (por exemplo, não há PostgreSQL disponível), o painel bloqueia a restauração antes de prosseguir e avisa o que falta.
• Nesse caso, provisione os serviços ausentes no servidor de destino e tente novamente.
• As referências a serviços cross-server (host de DB / Redis / S3 / Reverb) são preservadas a partir dos metadados do backup, de modo que o site recriado se reconecta aos mesmos hosts.

Isso significa que um site do Servidor de Sites que usa o PostgreSQL e o Redis do Servidor Principal pela malha WireGuard — como o todo.secnote.com.br do exemplo — pode ser restaurado corretamente, contanto que o painel encontre esses serviços na organização.

#Site excluído e restauração a partir de arquivo

• Recriar e restaurar — quando o site de um backup foi excluído, a linha do backup troca Restaurar por Recriar e restaurar: o PrimeForge recria o site a partir dos metadados do backup (no servidor original ou, se ele não existir mais, em um servidor que você escolhe), faz o scaffolding e o deploy, e então restaura banco, arquivos e configuração.
• Restaurar de arquivo — no menu Mais do cabeçalho da página Backups: envie um arquivo .tar.gz.enc, informe a senha de criptografia, cole a chave de restauração exportada da conta original e escolha o servidor de destino. É o caminho para trazer um backup de outra conta ou de um arquivo que você guardou fora do PrimeForge.
• Esquecer este registro — quando o armazenamento de um backup deixou de existir de vez, remove o registro do painel sem apagar nada do bucket.

#Retenção e limpeza

O PrimeForge roda uma rotina diária de limpeza que apaga os arquivos de backup com mais de 30 dias — no armazenamento S3 e a cópia local no servidor do site. Backups de um agendamento seguem, além disso, o Manter as últimas daquele agendamento.

Na limpeza diária, os registros no banco (metadados, checksums, datas) são preservados depois que o arquivo é removido, então o histórico de backups continua visível no painel. Já a retenção de um agendamento remove também o registro, assim que as duas cópias (a local e a do S3) foram apagadas. Se um bucket estiver inacessível na hora da limpeza, o arquivo fica para a próxima rodada em vez de o painel perder o endereço dele.

#Boas práticas

• Teste as suas restaurações. Um backup que você nunca restaurou não é um backup de verdade. Periodicamente, restaure um backup de produção em um site de teste (no mesmo servidor ou em outro) e confirme que a aplicação funciona.
• Guarde os backups fora do servidor do site. Um MinIO em outro servidor, ou um S3 externo, sobrevive à perda do disco da aplicação.
• Mantenha várias gerações. Não dependa de um único backup. Use um agendamento diário com uma retenção de vários dias para sites críticos, e faça um backup manual antes de cada alteração arriscada.
• Documente as senhas e as chaves de restauração. Use um gerenciador de senhas e rotule cada senha com o nome do site e a data. Uma senha perdida é um backup perdido.

#Próximos passos

• Deploys e Rollback — como o pipeline de deploy e as releases atômicas protegem o site durante mudanças.
• Sites — configuração de serviços (banco, Redis, S3) que definem o que entra em cada backup.
• Boas Práticas de Segurança — como o PrimeForge criptografa dados em trânsito e em repouso.