Restaurar a partir de um backup

Você tem um pacote .tar.gz que salvou antes (ou que alguém da equipe te enviou, ou que acabou de chegar de outro servidor). Este guia mostra como colocá-lo de volta no ar como um serviço em execução — seja no mesmo lugar (sobrescrevendo o original, se ele ainda existir) ou como um clone em um novo domínio.

Procurando a parte de criar backups? Esse é outro artigo: Backups — qual eu devo escolher e como usar. Este aqui começa de "eu já tenho um pacote no meu computador".

Por onde começar a restauração — três pontos de entrada

Mesmo fluxo, três portas. Escolha a que combina com o seu ponto de partida. (Duas delas usam o Menu Ações da barra superior — clique nesse termo para ver onde ele fica.)

As três portas abrem o mesmo modal Restaurar a partir de um backup. A única diferença é o contexto que o Server Manager tem no momento em que você o abre:

• A partir de um painel de serviço, o modal sabe qual receita + carga de trabalho você esperava — se o pacote enviado tiver outro formato (por exemplo, você abriu o painel do WordPress, mas enviou um pacote do Postgres), ele mostra um aviso para você escolher outro arquivo antes que qualquer coisa seja executada.
• Pelo menu Ações, nenhuma expectativa é definida — o que o pacote disser que é, é o que será restaurado.
• A partir de uma transferência recebida, o pacote já está no servidor; o modal oferece um botão Restaurar este pacote com um clique.

Passo a passo

Escolha o ponto de entrada que combina com a sua situação (veja a tabela acima). O modal tem a mesma aparência nos três casos:

Arraste o arquivo .tar.gz para a área de soltar ou clique em qualquer ponto dessa área para abrir o seletor de arquivos. O modal aceita arquivos terminados em .tar.gz ou .tgz.

Clique em Enviar. Uma barra de progresso substitui a área de soltar enquanto o pacote é transmitido para o servidor (envio em partes — até pacotes de vários GB aguentam conexões instáveis).

O que está sendo enviado? Seu computador envia os bytes do .tar.gz para o servidor por um fluxo no estilo SFTP — criptografado pela sessão SSH à qual você está conectado. O arquivo fica em /tmp/helm-restore/<id>/<bundle>.tar.gz e permanece lá até a restauração terminar (depois ele é removido).

Quando o envio termina, o modal fecha e o Faro te cumprimenta no chat com o resumo do manifesto que leu do pacote: o título de origem, o domínio de origem, a receita e o horário do backup. Então ele faz uma pergunta curta:

Você quer restaurar no mesmo lugar (sobrescrevendo o <name> existente, se ele ainda estiver presente) ou clonar para um novo domínio (mantendo o original intacto e criando uma cópia separada)?

Este é o único ponto de decisão. A partir daqui, sua resposta determina o restante das etapas.

4a. Restaurar no mesmo lugar

Escolha esta opção quando:

• A carga de trabalho original sumiu (foi excluída, ou você está em um servidor novo) e você quer trazê-la de volta no mesmo domínio, com os mesmos nomes.
• A original está quebrada / mal configurada e você quer apagá-la e recriá-la a partir do pacote.

O que o Faro faz:

1. Lê docker-compose.yml e .env de dentro do pacote e os recria no caminho de instalação original.
2. Restaura todos os volumes Docker nomeados (dados de banco de dados, arquivos enviados etc.) a partir dos volumes no pacote.
3. Para sites estáticos, copia a árvore de arquivos de volta para /var/www/<domain>/.
4. Reaplica o bloco do Caddyfile para que o domínio original volte a servir o site.
5. Inicia o serviço e executa uma verificação de saúde.

Cada comando pausa para pedir sua aprovação antes de ser executado — o chat mostra as linhas exatas de docker compose up, tar xzf, caddy reload que você está prestes a executar.

4b. Clonar para um novo domínio

Escolha esta opção quando:

• Você quer manter o original em execução enquanto uma cópia sobe em outro domínio (staging, dev, demo, uma segunda empresa…).
• Você está restaurando em um servidor que tem um domínio diferente apontado para ele em relação à origem do pacote.

O Faro faz uma pergunta extra: qual é o novo domínio? (por exemplo, staging.example.com).

O que o Faro faz além das etapas de restauração no mesmo lugar:

1. Escolhe um nome novo para o projeto compose (para que os contêineres do clone não colidam com os do original), por exemplo, mysite-com → staging-example-com.
2. Reescreve a entrada do Caddyfile para usar o novo domínio.
3. Gera novos segredos em .env (nova senha do banco, novas chaves do app) — o clone não compartilha credenciais com o original.
4. Para WordPress, executa wp search-replace <old-domain> <new-domain> dentro do contêiner clonado para que links em posts/metadados de mídia apontem para o novo domínio.
5. Para apps web, atualiza quaisquer variáveis de ambiente *_URL / *_HOST que apontem para o domínio antigo.
6. Solicita um novo certificado TLS para o novo domínio (Let's Encrypt via Caddy, automático).

O original continua rodando sem alterações.

Clonando um banco de dados? Bancos de dados não têm domínio. Em vez disso, o Faro pede um sufixo curto (como staging ou qa) e o usa para derivar um nome único de projeto compose, nome de contêiner e porta de escuta, para que os dois bancos rodem lado a lado sem conflito.

Quando as etapas terminam, o Faro mostra a URL final (clone) ou o domínio agora restaurado (no mesmo lugar). Abra no navegador; se não carregar de imediato, aguarde 30–60 segundos para o Let's Encrypt emitir o certificado e tente novamente.

O pacote original é removido automaticamente de /tmp/helm-restore/ assim que a restauração termina com sucesso.

Incompatibilidade do formato da receita

Se você abriu o modal de restauração a partir de um painel de serviço (por exemplo, o painel do WordPress para mysite.com) e enviou um pacote de uma receita diferente (por exemplo, um pacote do Postgres), o modal não segue em frente sem avisar — ele mostra um alerta:

Você tem duas opções:

• Escolher outro arquivo — quase sempre é o que você quer (você pegou o pacote errado).
• Usar este pacote mesmo assim — o pacote conduz a restauração, então isso vai configurar um serviço novo da receita que estiver no pacote, e NÃO modificar o serviço cujo painel você abriu. Escolha esta opção apenas se você entende isso e é o que deseja.

A verificação de incompatibilidade só acontece quando o modal foi aberto a partir de um painel de serviço com uma receita esperada. O caminho Ações → Restaurar pula essa verificação completamente (não há expectativa para comparar).

Restauração automática após mover de servidor para servidor

Se você usou aba Backup → Mover para outro servidor em outro servidor e ele transferiu um pacote para cá, o modal de restauração abre automaticamente com esse pacote destacado no topo:

Clique em Restaurar este pacote e, a partir daí, o restante do fluxo é idêntico a uma restauração nova (o Faro pergunta restaurar no mesmo lugar vs. clonar, você aprova comandos etc.). O pacote já está no servidor, então não há etapa de envio.

Você também pode clicar em Usar outro pacote… para dispensar o pré-carregamento e abrir o seletor de arquivos normal — útil se você transferiu o pacote errado e quer começar de novo.

Perguntas comuns

Onde o original fica durante um clone? Intacto. O clone usa nomes de contêiner diferentes, volumes diferentes, portas diferentes (para bancos de dados) e segredos diferentes. Você pode excluir o clone depois sem afetar o original.

Posso restaurar um pacote em outra distribuição Linux? Sim. O pacote é apenas Docker compose + volumes nomeados + (para sites estáticos) uma árvore de arquivos. O Server Manager cuida da instalação do Docker específica de cada distribuição no destino, se ele estiver ausente. A exceção são pacotes de apps web nativos (sem contêiner) — eles dependem do gerenciador de pacotes e do systemd da distribuição de origem, e o artigo de restauração vai avisar se não conseguir traduzir a instalação.

O pacote é enorme — o envio pode expirar? Não. O envio é feito em partes (~4 MB por parte) e o servidor junta tudo. Pacotes de vários GB funcionam; se sua conexão cair no meio do envio, o modal permite cancelar e começar de novo, em vez de reiniciar do zero a cada parte.

E se eu cancelar no meio da restauração? Cancelar durante o envio exclui o arquivo parcial e você volta para a área de soltar. Cancelar durante as etapas do chat (entre aprovações) deixa no lugar o que o Faro já tiver feito — alguns contêineres podem existir, alguns volumes podem existir. Você pode executar a restauração novamente a partir do mesmo pacote ou pedir ao Faro para limpar o estado parcial primeiro; se algo parecer estranho, pergunte no chat e o Faro vai diagnosticar.

Posso restaurar o mesmo pacote várias vezes em clones diferentes? Sim. Abra o modal novamente, envie o mesmo pacote e escolha clonar a cada vez com um novo domínio diferente. O pacote continua válido para sempre (é apenas um tarball).

Onde restaurações com falha deixam arquivos? /tmp/helm-restore/<id>/ no servidor de destino. O Ações da tela inicial mostra diretórios helm-restore órfãos na visão de limpeza, caso algum tenha ficado para trás. É seguro excluir.

O que NÃO está no escopo aqui

• Arquivos **.helm-backup/** (desfazer por arquivo na aba Arquivos) → veja a seção "Recuperar um único arquivo" do artigo Backups.
• Dumps brutos de banco **.sql.gz** (carregáveis em qualquer Postgres/MySQL) → veja a seção "Fazer backup apenas do banco de dados" do artigo Backups.
• Restaurar entre receitas diferentes (por exemplo, um pacote de WordPress como site estático) — os pacotes são específicos por receita. Escolha um pacote que corresponda ao que você quer colocar no ar.

Referência

O que a restauração precisa no servidor de destino:

• O servidor Linux acessível por SSH ao qual você está conectado no Server Manager.
• Espaço em disco para extrair o pacote (aproximadamente 2× o tamanho do pacote, por pouco tempo, durante a extração).
• Docker instalado (o Server Manager instala automaticamente se estiver ausente em um destino novo).

Caminhos em disco durante a restauração:

• Pacote enviado (temporário) → /tmp/helm-restore/<id>/<name>.tar.gz
• Origem extraída → /tmp/helm-restore/<id>/extracted/
• Instalação final — o mesmo caminho que o original usava (por exemplo, /opt/wordpress-mysite-com/, /var/www/mysite.example.com/, …)

A árvore de decisão em resumo: