Backup e restauração

As atualizações de esquema do banco de dados só avançam — não existe caminho de downgrade. Um backup feito com vision backup é a sua única forma de reverter, o que o torna parte da rotina de atualização, e não um extra opcional.

Fazendo um backup

sudo vision backup --output /root/

Não há tempo de inatividade: o banco de dados é capturado com VACUUM INTO do SQLite, que tira uma cópia consistente de um ponto no tempo enquanto o serviço continua gravando, e a cópia já passou por checkpoint — o arquivo de backup nunca contém arquivos auxiliares WAL/SHM, então a classe de corrupção “restaurou um WAL antigo sobre um banco de dados novo” não pode acontecer. O banco de dados de origem passa primeiro por uma verificação de integridade; o backup de um banco de dados danificado é recusado, em vez de sobrescrever o seu último arquivo de backup válido.

O que há no arquivo

vision-backup-<host>-<timestamp>.tar.gz
└── vision-backup-<host>-<timestamp>/
    ├── manifest.json         what's inside, schema version, encryption key ids
    ├── vision.db             consistent database snapshot
    ├── config.yaml
    ├── vision.env            secrets — omit with --no-secrets
    ├── license.txt           license serial — omitted with --no-secrets
    ├── maps/…                 floor-plan images — omit with --no-maps
    └── systemd/vision.service  reference only; restore never writes it

Incluído por padrão:

• vision.env (segredos). A chave de criptografia que protege todas as colunas criptografadas — credenciais de câmeras e do Alta, segredos de armazenamento e SMTP, chaves de assinatura de webhooks — existe somente neste arquivo. Um arquivo de backup sem ela não consegue descriptografar o banco de dados ao qual está associado, por isso os segredos são incluídos por padrão; o arquivo de backup é gravado com modo 0600.
• license.txt. O serial da licença, quando o host possui um (Licenciamento). O restore o coloca de volta como vision:vision 0600. Sem ele, o host restaurado inicia bloqueado até ser ativado novamente.
• maps/. Os fundos de planta baixa são os únicos arquivos enviados por operadores que ficam fora do banco de dados, e as linhas do banco de dados que os referenciam seguem no mesmo arquivo — deixar as imagens de fora faria uma restauração “bem-sucedida” produzir silenciosamente mapas sem fundo.

Excluído, com o motivo registrado no manifesto:

• Clipes e capturas de tela — gerenciados por retenção e regeneráveis; incluí-los faria os backups de rotina ocuparem vários gigabytes.
• Gravações HLS — ficam no armazenamento do próprio servidor Alta, nunca no host do Vision.
• O binário — sua versão é registrada no manifesto, mas um backup é uma reversão de dados, não uma reversão de código.

Trate o arquivo de backup como o arquivo env

O arquivo de backup é tão sensível quanto toda a sua instalação — mantenha-o com modo 0600 e nunca o coloque em uma unidade compartilhada, em armazenamento de objetos, nem em um chat ou ticket sem criptografia. --no-secrets produz um arquivo compartilhável, mas o banco de dados dentro dele fica então impossível de descriptografar, a menos que você possua separadamente a chave correspondente. --output - (gravar na saída padrão, para enviar por pipe a outro host) exige --no-secrets.

Use --force para substituir um arquivo de saída existente. --recover-wal abre o banco de dados com leitura e escrita primeiro para recuperar um WAL obsoleto; execute sudo vision doctor e use-o somente quando o comando recomendar. Para instalações não padrão, passe --config PATH ou --db PATH.

Restaurando

sudo vision restore /root/vision-backup-<host>-<timestamp>.tar.gz

A sequência é deliberadamente cuidadosa:

1. Tudo é verificado antes que qualquer coisa no disco mude — o manifesto, o checksum de cada arquivo e o conteúdo do arquivo compactado são conferidos antes de qualquer gravação. Trate um arquivo vindo de outra pessoa como qualquer arquivo não confiável.
2. Verificação de esquema. Um arquivo de uma versão mais nova é recusado de imediato — atualize o binário primeiro. Um arquivo mais antigo é restaurado com um aviso: o serviço fará a migração para a versão atual na próxima inicialização, o que é irreversível.
3. Verificação de chave. Se o arquivo não tiver vision.env, os ids de chave de criptografia registrados nele devem corresponder a uma chave que você possui no momento, ou a restauração é recusada (--force-key-mismatch ignora essa verificação).
4. Recusa enquanto o serviço está em execução. Passe --stop-service para que ele pare o serviço por você — a restauração nunca o inicia novamente depois, para que os problemas apareçam antes do serviço.
5. Confirmação digitada. Você deve digitar restore <this hostname> para prosseguir — um comando de runbook colado na máquina errada falha em vez de ser executado.
6. Primeiro é feito um backup de segurança do estado atual. Se isso falhar, nada mais acontece.
7. Os arquivos são substituídos, os arquivos auxiliares WAL obsoletos são removidos e o esquema do banco de dados restaurado é verificado — qualquer falha nesta etapa reverte tudo.

Depois, coloque o serviço de volta no ar por conta própria:

sudo vision doctor
sudo vision start
sudo vision status

O vision doctor lembra você de excluir o arquivo de segurança pre-restore-* quando você estiver satisfeito com a restauração.

Para um runbook não interativo, passe --yes explicitamente:

sudo vision restore /root/vision-backup.tar.gz --stop-service --yes

O teste de restauração

Um backup que ninguém restaurou não é um backup. Execute isto trimestralmente:

sudo vision restore <latest-archive> --dry-run

--dry-run executa a verificação completa — manifesto, checksums, esquema e compatibilidade de chaves — e imprime o que faria sem gravar nada. Isso comprova que o arquivo está íntegro e pode ser restaurado na máquina que realmente precisaria dele.

Restauração entre hosts

Restaurar em um hardware diferente é suportado — o comando avisa quando o arquivo vem de outro host e, como a confirmação digitada sempre nomeia o host em que você está atualmente, uma linha de runbook copiada para a máquina errada ainda falha com segurança. Depois de uma restauração entre hosts, revise http.allowed_origins na configuração restaurada antes de iniciar — ela ainda pode citar o host antigo.

O license.txt do arquivo de backup é o dispositivo do host antigo. Se o host antigo ainda estiver em execução, ambos passam a usar uma só licença: remova o dispositivo antigo no seu perfil Cesbo (licença → Manage device) ou ative o novo host como substituto dele (Licenciamento).

Agendamento

Uma linha de cron é suficiente; o comando não precisa de coordenação com o serviço em execução:

15 3 * * * root /usr/local/bin/vision backup --output /var/backups/vision/ >>/var/log/vision-backup.log 2>&1

Faça você mesmo a rotação dos arquivos antigos, por exemplo:

find /var/backups/vision -name 'vision-backup-*.tar.gz' -mtime +30 -delete

Cada arquivo de backup contém a sua chave de criptografia por padrão — aplique ao armazenamento dos seus backups os mesmos controles de acesso que você aplica a /etc/vision/vision.env.