Um backup GitLab que não se consegue restaurar é apenas um ficheiro grande

A maioria das instâncias GitLab self-hosted tem um job de backup noturno, e a maioria das pessoas que o configurou nunca fez um restore a partir dele. Isso é um problema, porque o arquivo que o GitLab produz é deliberadamente incompleto. Restaure-o num servidor novo sem os ficheiros que ele deixa de fora, e os repositórios regressam enquanto as variáveis de CI, as definições de dois fatores e os registos de runners se transformam em dados ilegíveis. Eis o que contém um backup GitLab completo, como o mover sem enfraquecer a sua segurança e como provar que funciona.

O que a tarefa de backup inclui, e o que deixa de fora

Numa instalação por pacote (Omnibus), a tarefa de backup é:

sudo gitlab-backup create STRATEGY=copy

Escreve um único arquivo tar no diretório de backups, normalmente /var/opt/gitlab/backups. Esse arquivo contém a base de dados, os repositórios Git, uploads, objetos LFS, artefactos dos jobs de CI, pages, packages e, se estiver ativado, o container registry. STRATEGY=copy copia os dados antes de os arquivar, o que evita erros quando ficheiros mudam durante um backup longo numa instância com muita atividade.

O que não contém, de propósito:

• /etc/gitlab/gitlab-secrets.json, as chaves usadas para encriptar colunas sensíveis na base de dados.
• /etc/gitlab/gitlab.rb, a sua configuração.
• Certificados e chaves TLS em /etc/gitlab/ssl, se os guardar aí.
• As chaves de host SSH em /etc/ssh, que os clientes dos seus programadores já registaram.

O GitLab deixa-os de fora para que um único arquivo roubado não contenha ao mesmo tempo os dados encriptados e a chave que os desencripta. É um raciocínio sólido, e passa para si a tarefa de os guardar em backup separadamente.

Porque é que o ficheiro de secrets importa tanto

Variáveis de CI/CD, tokens de registo de runners, seeds de autenticação de dois fatores, palavras-passe de integrações e várias outras definições são encriptadas na base de dados com chaves de gitlab-secrets.json. Restaure a base de dados sem o ficheiro de secrets correspondente e o GitLab arranca, os repositórios estão lá, e depois os pipelines falham, os utilizadores com autenticação de dois fatores não conseguem iniciar sessão e os runners precisam de ser registados de novo.

Guarde o diretório de configuração como um artefacto próprio:

sudo gitlab-ctl backup-etc --backup-path /var/opt/gitlab/config-backups

Isto produz um tar de /etc/gitlab, incluindo o ficheiro de secrets. Guarde-o num local diferente do arquivo de dados, com acesso mais restrito, e mantenha os pares correspondentes juntos na sua política de retenção. Um arquivo de dados de segunda-feira e um ficheiro de secrets de quinta-feira podem não concordar um com o outro se algo tiver sido rodado entretanto.

Em instalações em container os comandos são os mesmos, executados dentro do container, e /etc/gitlab é o volume que lhe tiver mapeado. Certifique-se de que esse volume faz parte do que guarda em backup. É fácil guardar apenas o volume de dados.

Obtenha o backup por pull, não o empurre

O padrão habitual é um cron job no servidor GitLab que copia o arquivo para um host de backup. Isso significa que o servidor GitLab guarda credenciais que podem escrever nos seus backups. Se o GitLab for comprometido, fica comprometido também o caminho para chegar aos backups e os apagar.

Inverta a direção. O host de backup liga-se ao GitLab e vai buscar os ficheiros. O GitLab não guarda credenciais para o host de backup e não tem caminho de rede até ele. Do lado do GitLab, limite o que a chave do host de backup pode fazer com um forced command no authorized_keys:

command="/usr/local/bin/backup-send",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA... backup-puller

onde backup-send é um pequeno script que não faz nada além de enviar o arquivo de dados mais recente e o arquivo de configuração correspondente. No host de backup, o job vai buscar ambos, verifica os tamanhos e os checksums, e alerta se algum estiver em falta ou for mais antigo do que o esperado.

Depois imponha a direção na firewall: o host de backup pode abrir ligações para o GitLab, nada na rede do GitLab pode abrir ligações para o host de backup.

Regras de restore que vale a pena conhecer antes de precisar delas

Um backup GitLab só restaura na mesma versão e edição do GitLab que o criou. Escreva a versão no nome do arquivo ou num ficheiro ao lado no momento do backup:

sudo gitlab-rake gitlab:env:info > gitlab-env-$(date +%F).txt

Se perder o servidor e o único instalador que conseguir encontrar for mais recente, vai primeiro instalar a versão antiga, restaurar, e depois atualizar ao longo do caminho suportado. Saber isso de antemão transforma uma noite longa num procedimento planeado.

O restore propriamente dito, numa instalação nova da versão correspondente:

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# put gitlab-secrets.json and gitlab.rb back into /etc/gitlab first
sudo gitlab-ctl reconfigure
sudo gitlab-backup restore BACKUP=<archive-id>
sudo gitlab-ctl restart
sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-rake gitlab:doctor:secrets

O último comando é o que conta. gitlab:doctor:secrets percorre as colunas encriptadas e reporta as que não consegue desencriptar. Se reportar falhas, o seu ficheiro de secrets e o seu arquivo de dados não pertencem um ao outro.

Prove-o com regularidade

Um restore que não testou é uma esperança. Torne-o rotina:

1. Construa uma VM descartável numa rede isolada, sem rota para a produção.
2. Instale a versão do GitLab registada com o backup.
3. Restaure o par mais recente de configuração e dados.
4. Corra gitlab:check e gitlab:doctor:secrets.
5. Clone um repositório conhecido, compare o hash do último commit com a produção e abra a página de variáveis de CI de um projeto.
6. Registe o resultado e o tempo que demorou, e depois destrua a VM.

Cronometre-o também. A duração do restore é o seu tempo de recuperação real, e numa instância grande costuma ser mais longo do que as pessoas imaginam.

Uma segunda cópia do código, independente

O backup completo protege a aplicação inteira. Para os repositórios em si, um simples mirror dá-lhe uma segunda cópia que não depende de todo das ferramentas do GitLab:

git clone --mirror git@gitlab.example.com:group/project.git
git -C project.git remote update --prune

Corra isto do lado do backup para os repositórios que não se pode dar ao luxo de perder. Não restaura issues nem merge requests, mas significa que o histórico do seu código sobrevive até a um arquivo de backup que não consegue ler.

A versão curta

• gitlab-backup create é metade de um backup. gitlab-ctl backup-etc é a outra metade.
• Mantenha secrets e dados em pares correspondentes, guardados em separado, com acesso mais restrito aos secrets.
• O lado do backup faz pull. O GitLab não tem caminho para os seus próprios backups.
• Registe a versão do GitLab com cada arquivo.
• Restaure com regularidade, e corra gitlab:doctor:secrets de cada vez.

É assim que protegemos as instâncias GitLab que operamos para clientes nos nossos próprios datacenters. Se quiser que o seu caminho de restore seja verificado, teremos todo o gosto em ajudar.

Fale com um engenheiro

related line: Relacionados: Source control gerido em GitLab · Managed Nextcloud para documentos de escritório

footer line: Publicado em 22 de outubro de 2026. Todas as notas de campo