# Restaurando com base em um backup

Restaure uma GitHub Enterprise Server instância usando um instantâneo de backup criado anteriormente.

Você pode restaurar uma GitHub Enterprise Server instância de um backup usando a linha de comando. O serviço de backup dá suporte à restauração da instância completa, incluindo a configuração e os dados do usuário.

> \[!WARNING] Restaurar a partir de um backup **substituirá todos os dados existentes** em sua instância. Essa operação não pode ser desfeita.

## Requisitos de versão do instantâneo

Você só poderá restaurar um instantâneo se ele for, no máximo, de duas versões de funcionalidade anteriores à versão da instância de destino.

Por exemplo:

* Um instantâneo da versão 3.17 pode ser restaurado para um destino executando 3.17.x, 3.18.x ou 3.19.x.
* Não é possível restaurar um instantâneo 3.17 para a 3.20, pois ela está mais de duas versões à frente.

Você também não pode restaurar de uma versão mais recente para uma mais antiga. Por exemplo, tentar restaurar um instantâneo 3.18 para uma instância 3.17 resultará em falha com: `Error: Snapshot can not be restored to an older release of GitHub Enterprise Server.`

## Pré-requisitos

Antes de restaurar um backup:

1. **Habilite o modo de manutenção** na instância de destino. Consulte [Habilitar e programar o modo de manutenção](/pt/enterprise-server@3.21/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode).
2. **Verifique o acesso** ao armazenamento de backup que contém o instantâneo.
3. **Pause os serviços que causam interferência** — se estiver usando alta disponibilidade (HA), verifique se a replicação foi interrompida.
4. **Prepare-se para GitHub Actions** — se estiver habilitado, verifique se a instância de destino está configurada com o armazenamento externo correto. Confira [Restaurando com GitHub Actions habilitadas](/pt/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/restoring-with-github-actions-enabled) para obter detalhes.

## Iniciando a operação de restauração

Para restaurar de um instantâneo:

1. Acesse a instância de destino via SSH como o usuário `admin`.

2. Execute um dos seguintes comandos:

   * Restaure o instantâneo mais recente:

     ```shell
     ghe-restore
     ```

   * Restaure um instantâneo específico. Substitua `<SNAPSHOT_TIMESTAMP>` pelo carimbo de data/hora do instantâneo que você deseja restaurar (por exemplo, `YYYYMMDDTHHMMSS`).

     ```shell
     ghe-restore -s <SNAPSHOT_TIMESTAMP>
     ```

   * (Opcional) Forçar a substituição de dados de configuração, certificados e licença:

     ```shell
     ghe-restore -c          # Latest snapshot
     ghe-restore -s <SNAPSHOT_TIMESTAMP> -c  # Specific snapshot
     ```

3. **Finalizar em Console de Gerenciamento:**

   * Revise todas as configurações (rede, autenticação, TLS etc.).
   * Clique em **Save settings** para aplicá-las e iniciar os serviços.
   * A instância não estará totalmente operacional até que esta etapa seja concluída.

4. **Valide a instância restaurada** para garantir que tudo funciona conforme o esperado.

5. **Se estiver usando HA**, conclua a restauração em uma instância autônoma primeiro. Em seguida, reconfigure a HA.

   * Se encontrar problemas de sincronização (por exemplo, UUIDs obsoletos no `ghe-repl-status`), execute `ghe-repl-teardown`.
   * Para obter ajuda, entre em contato Suporte do GitHub.

6. **Registre novamente os executores auto-hospedados GitHub Actions**, pois a restauração invalida os tokens anteriores.

## Rotação e retenção de instantâneo

Os snapshots são podados automaticamente com base nas suas configurações de retenção.

* Somente os n instantâneos mais recentes são mantidos (conforme configurado).
* Instantâneos mais antigos são excluídos após cada backup bem-sucedido.
* Instantâneos são nomeados usando carimbos de data/hora (`YYYYMMDDTHHMMSS`) para facilitar a referência.
* Links rígidos são usados para armazenar arquivos inalterados com eficiência, preservando a capacidade de restauração completa.

## Solução de problemas de falhas de restauração

Se uma operação de restauração falhar, verifique:

* **Integridade do backup** – verifique se o instantâneo não foi interrompido ou corrompido.
* **Acesso ao armazenamento** – verifique se a instância pode montar e ler o volume de backup.
* **Incompatibilidade de versão** – confirme se a versão do instantâneo é compatível com a instância de destino.
* **Logs** – revisar `/var/log/github-backup/restore-verbose-[timestamp].log` para identificar erros.

Se o Console de Gerenciamento mostrar uma falha genérica, acesse a instância via SSH para acessar os logs detalhados.