Backups e Restauração

O sh0 faz backup de servidores de banco de dados e volumes em arquivos compactados, sob demanda ou por agendamento, guarda-os no servidor ou envia-os a um armazenamento externo, e os restaura no lugar.

Conteúdo de um backup

Cada backup é um único arquivo compactado com gzip. O conteúdo depende da origem:

O arquivo leva o ID do backup: <id>.gz, ou <id>.gz.enc quando criptografado. Não existem arquivos .dump, .archive ou .rdb. Os backups locais ficam na pasta backups/ do diretório de dados do sh0 (/var/lib/sh0/backups/ em uma instalação Linux padrão):

$ cd /var/lib/sh0/backups
$ ls -l 4efb5ef8-b61c-4b1f-b6dd-b546c1a01bb8.gz 9b5222c8-4c09-4805-8d96-4d80df2168c8.gz.enc | awk '{print $5, $9}'
1314 4efb5ef8-b61c-4b1f-b6dd-b546c1a01bb8.gz
1343 9b5222c8-4c09-4805-8d96-4d80df2168c8.gz.enc

$ zcat 4efb5ef8-b61c-4b1f-b6dd-b546c1a01bb8.gz | grep -m3 '^-- '
-- PostgreSQL database cluster dump
-- Drop databases (except postgres and template1)
-- Drop roles

Backups manuais

• Pelo servidor de banco de dados: a aba Visão geral tem um cartão Backup com Fazer backup agora. O backup cobre o servidor inteiro, local e sem criptografia.
• Pela página Backups da barra lateral: Iniciar backup pergunta O que deseja copiar?, o Destino, se deve Criptografar e, para um servidor de banco de dados, um banco ou todos.

Pela API, source_type é database_server, volume ou database. A chamada responde 202 e o backup roda em segundo plano; leia-o de novo para saber o arquivo:

$ curl -s -X POST https://panel.example.com/api/v1/backups/trigger \
    -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
    -d '{"source_type":"database_server","source_id":"3afde175-12d6-4614-94ca-e504737a7cc4","destination":"local","encrypt":false}' \
    -o /dev/null -w "%{http_code}\n"
202

$ curl -s https://panel.example.com/api/v1/backups/4efb5ef8-b61c-4b1f-b6dd-b546c1a01bb8 \
    -H "Authorization: Bearer $SH0_TOKEN"
{"data":{"created_at":"2026-10-02 02:46:04","created_by":"50159570-e8ad-46a8-8065-e6c9096edde6","database_name":null,"destination":"local","encrypted":false,"file_path":"/var/lib/sh0/backups/4efb5ef8-b61c-4b1f-b6dd-b546c1a01bb8.gz","file_size":1314,"id":"4efb5ef8-b61c-4b1f-b6dd-b546c1a01bb8","path":null,"project_id":null,"restore_error":null,"restore_status":"completed","restored_at":"2026-10-02 02:46:31","schedule_id":null,"source_id":"3afde175-12d6-4614-94ca-e504737a7cc4","source_type":"database_server","status":"completed"}}

Backups agendados

Na página Backups, Criar agendamento pede a origem, uma expressão cron de cinco campos, o Destino e a retenção. Os agendamentos são avaliados em UTC. Executar agora dispara um backup agendado imediatamente.

$ curl -s -X POST https://panel.example.com/api/v1/backup-schedules \
    -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
    -d '{"source_type":"database_server","source_id":"3afde175-12d6-4614-94ca-e504737a7cc4","cron":"0 3 * * *"}'
{"data":{"cron":"0 3 * * *","destination":"local","enabled":true,"id":"ed140ca5-1c47-4388-897d-52726489d3fa","last_run":null,"next_run":"2026-10-02 03:00:00","path":null,"retention":7,"service_id":null,"source_id":"3afde175-12d6-4614-94ca-e504737a7cc4","source_type":"database_server"}}

$ curl -s -X POST https://panel.example.com/api/v1/backup-schedules/ed140ca5-1c47-4388-897d-52726489d3fa/run \
    -H "Authorization: Bearer $SH0_TOKEN"
{"data":{"schedule_id":"ed140ca5-1c47-4388-897d-52726489d3fa","status":"started"}}

Retenção

A retenção é uma quantidade de backups, não de dias. O padrão é 7; 0 mantém tudo. Após cada execução agendada bem-sucedida, o sh0 exclui os backups mais antigos daquele agendamento além do limite, registros e arquivos. Backups manuais nunca são removidos.

Destinos de armazenamento

O destino padrão é local. Provedores externos são adicionados em Configurações → Armazenamento (o link Adicionar armazenamento externo da página Backups leva até lá). Os tipos disponíveis são:

• Compatível com S3: AWS S3, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, Wasabi, MinIO, Hetzner Object Storage ou qualquer endpoint S3
• SFTP, com senha ou chave SSH
• FTP, com TLS opcional
• Dropbox e Google Drive
• Caminho local: outro diretório do servidor, por exemplo um disco montado

Na API, destination aceita local, o nome de um provedor ou external:<id-do-provedor>. Qualquer outro valor é recusado com 422 em vez de ser salvo localmente sem aviso.

Criptografia

Um backup criptografado (.gz.enc) é selado com AES-256-GCM usando a chave mestra da instância, armazenada em master.key e master.passphrase no diretório de dados do sh0. Somente uma instância com essa chave pode restaurá-lo: guarde uma cópia dos dois arquivos fora do servidor.

Restaurar um backup

No Histórico da página Backups, Restaurar reaplica um backup no recurso de origem, depois que você digita o nome para confirmar. Os dados atuais são substituídos e o sh0 não faz um backup antes. A chamada de API é POST /api/v1/backups/:id/restore; ela responde 202 e o restore_status do backup passa a completed ou failed.

Restaurar de fonte externa restaura um arquivo que está em um provedor de armazenamento configurado, por exemplo um backup feito por outra instância do sh0.

Baixar e excluir

Baixar no histórico, ou GET /api/v1/backups/:id/download, devolve o arquivo como armazenado (application/gzip, ou binário se criptografado). Excluir um backup remove o registro e o arquivo.