Fazer backup e restaurar

Este guia cobre as cinco coisas que as pessoas realmente fazem com backups: criar um, coletá-lo, mover um espaço de trabalho, restaurar um e manter cópias fora da máquina. Para o formato exato de cada artefato e operação, consulte a referência de backup.

Tudo aqui fica em Configurações → Servidor → Backup e restauração.

Pré-requisitos

• Um cliente completo — o app de desktop ou o da web. Um celular emparelhado não dispara nada disso, por design.
• Para criar, listar, baixar ou excluir um instantâneo da instalação: o owner da instalação.
• Para ações por espaço de trabalho: admin desse espaço de trabalho para exportar, owner para importar ou excluir.
• Para downloads e uploads: uma conexão direta com o servidor. O relay intermediado transporta frames RPC, não transferências de arquivos, e os controles de transferência se desabilitam com uma observação quando você está em um.

Instantâneos da instalação são manuais

Fazer backup agora ainda cria um instantâneo da instalação inteira somente quando você pede. O pipeline embutido Workspace backup pode, em vez disso, fazer um backup do banco de dados de um espaço de trabalho uma vez por semana e remover os backups desse espaço de trabalho com mais de 30 dias. Ele não copia o global.db, outros espaços de trabalho nem arquivos ao lado do banco de dados. Mantenha as cópias fora da máquina separadamente.

O que um backup cobre

Os dois artefatos são somente bancos de dados:

• Um instantâneo da instalação é um diretório com carimbo de data e hora: manifest.json, global.db e um <workspaceId>/workspace.db por espaço de trabalho.
• Uma exportação de espaço de trabalho é esse único arquivo workspace.db.

Nenhum dos dois carrega o resto do diretório de dados: secrets.json (chaves de emparelhamento, credenciais de provedores, SSO), os blobs/ de um espaço de trabalho (imagens coladas em mensagens), skills/, agents/, chat_credentials/, áudio de reuniões gravado ou imagens de rigs. Parte disso é descartável e parte não é — a tabela completa está na referência, e cobrir isso é justamente para o que serve a seção de fora da máquina.

Criar um instantâneo da instalação inteira

1. Abra Configurações → Servidor → Backup e restauração.
2. Em Instantâneos da instalação, clique em Fazer backup agora.
3. O toast informa o diretório que foi gravado, no host do servidor. O novo instantâneo aparece no topo da lista.

O servidor continua em execução o tempo todo. Cada arquivo é gravado com VACUUM INTO, que é consistente em relação a um banco de dados em uso, então não há janela de manutenção nem necessidade de parar agentes.

Cada linha da lista mostra o carimbo de data e hora, o tamanho em disco, quantos espaços de trabalho foram capturados e se o instantâneo está Completo ou Incompleto. Incompleto significa que o manifesto está ausente ou aponta para arquivos que não existem — um backup interrompido por um travamento ou por um disco cheio. Esses continuam listados de propósito: um instantâneo que você não vê é um que você acredita ter. Um instantâneo incompleto não restaura uma instalação inteira, mas os arquivos de espaço de trabalho que ele contém ainda podem ser adotados um a um.

Uma linha também pode dizer n espaços de trabalho não capturados. Trata-se de um espaço de trabalho registrado mas nunca gravado (ainda não há arquivo), ou de um cuja cópia falhou — verifique o log do servidor.

Agendar backups de espaço de trabalho e retenção

Abra Configurações → Pipelines → Modelos de pipeline do espaço de trabalho e encontre Workspace backup. A agenda habilitada dele roda todo domingo às 03:00 UTC: Back up workspace, seguido de Delete backups older than (30 dias por padrão). O segundo nó só roda depois que o backup dá certo. Você pode alterar os dias de retenção no nó ou desabilitar a agenda. Se o servidor estiver offline no horário agendado, a agenda recupera uma vez quando ele voltar, em vez de repetir toda semana perdida.

Os backups de espaço de trabalho ficam no servidor em backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. O nó de retenção exclui apenas backups antigos deste espaço de trabalho; ele nunca exclui instantâneos da instalação nem backups de outros espaços de trabalho. Esses arquivos contêm apenas o banco de dados. Para retenção fora da máquina, copie-os separadamente.

Esses backups são separados da lista Instantâneos da instalação. Para restaurar um, use Dados do espaço de trabalho → Importar com o caminho workspace.db do backup no lado do servidor. A importação substitui o banco de dados atual desse espaço de trabalho, então exporte-o antes se você puder precisar desfazer a restauração.

Excluir um instantâneo da instalação

Em Instantâneos da instalação, expanda o instantâneo, inclusive um incompleto, e use Excluir instantâneo na zona de perigo. Confirme o nome. O diretório inteiro do instantâneo é removido permanentemente do servidor; baixe-o antes se precisar de uma cópia. Um pipeline de backup de espaço de trabalho nunca exclui esses instantâneos.

Coletar uma cópia na sua própria máquina

Os caminhos mostrados na página ficam na máquina que executa o cc_server. Quando essa não é a máquina em que você está, use os botões Baixar:

• Ao lado de cada espaço de trabalho, em Dados do espaço de trabalho → Baixar, para um arquivo .db.
• Ao lado de cada instantâneo, em Instantâneos da instalação → Baixar, para o instantâneo inteiro como um .zip.

No desktop, você escolhe onde o arquivo vai parar e o toast informa o caminho; na web, ele vai para os downloads do navegador. De qualquer forma, ambos relatam o progresso em bytes, porque essas são as duas cargas que chegam à casa dos gigabytes.

Os dois geram uma cópia nova no momento em que você clica no botão, a transmitem em streaming e excluem a cópia do servidor depois — um download não é “buscar o arquivo que o botão de exportação criou antes”.

Descompactar um arquivo de instantâneo reproduz o layout do instantâneo exatamente, e é isso que faz da restauração uma cópia de volta.

Mover um espaço de trabalho para outra instalação

Um espaço de trabalho é um arquivo de banco de dados, então entregá-lo é uma operação de arquivo.

1. No servidor de origem, Configurações → Servidor → Backup e restauração → Dados do espaço de trabalho, expanda o espaço de trabalho e clique em Baixar.
2. No servidor de destino, crie (ou escolha) o espaço de trabalho que vai recebê-lo.
3. Expanda esse espaço de trabalho e, em Restaurar a partir deste dispositivo, clique em Escolher um arquivo e enviar. Escolha o .db que você baixou.

Se os dois servidores forem a mesma máquina em que você está, Salvar no servidor mais Importar → Escolher arquivo fazem a mesma coisa sem a ida e volta; os caminhos do diálogo de importação são resolvidos no host do servidor.

A importação substitui tudo

Importar sobrescreve tudo o que o espaço de trabalho de destino contém no momento, e não dá para desfazer. Exporte o destino antes se ele tiver algo que você possa querer de volta.

Duas coisas são permitidas e registradas em log em vez de recusadas: importar um arquivo cujo id de espaço de trabalho registrado difere do destino (é assim que você duplica um espaço de trabalho ou o restaura com um id novo) e importar um arquivo de uma instalação diferente. No segundo caso, os dispositivos emparelhados e os ids de usuário do arquivo pertencem à instalação de onde ele veio e não vão resolver nesta — os dados do próprio espaço de trabalho ficam intactos, mas confira a associação de membros depois de adotá-lo.

Os tokens do bot de chat ficam ao lado do banco de dados, não dentro dele, então um espaço de trabalho que você entrega a outra pessoa não carrega credenciais ativas. A instalação que o recebe reconecta as suas próprias.

Restaurar um espaço de trabalho a partir de um instantâneo

1. Em Instantâneos da instalação, expanda o instantâneo que você quer.
2. Encontre a linha do espaço de trabalho e clique em Restaurar.
3. Confirme. Tudo o que esse espaço de trabalho fez desde que o instantâneo foi criado se perde.

É a mesma operação de uma importação, apontada para a cópia do arquivo desse espaço de trabalho dentro do instantâneo — de propósito, para que não exista um segundo mecanismo que pudesse tratar o mesmo arquivo de forma diferente.

Uma linha pode dizer Não está mais neste servidor, com Restaurar desabilitado: o instantâneo contém um espaço de trabalho que esta instalação não tem mais. Traga-o de volta manualmente — crie um espaço de trabalho e, em Dados do espaço de trabalho, importe para ele a partir de <snapshot path>/<old workspace id>/workspace.db. O instantâneo expandido mostra o próprio Caminho no servidor em um campo de cópia, e o título da linha é o id antigo do espaço de trabalho, então você tem as duas metades desse caminho diante de você.

Restaurar uma instalação inteira

Não existe botão para isso, e não deveria existir: ele substituiria os bancos de dados que o servidor em execução mantém abertos.

1. Pare o cc_server. Se você roda o app de desktop com o servidor embutido, saia do app.

2. Copie o conteúdo do instantâneo sobre o diretório de dados. O layout do instantâneo espelha o do ambiente em execução, então é uma cópia simples:

   # macOS default; see the CLI reference for other platforms
   DATA_DIR="$HOME/Library/Application Support/control-center"
   SNAPSHOT="$DATA_DIR/backups/2026-07-28T09-12-33-000Z"
   
   cp "$SNAPSHOT/global.db" "$DATA_DIR/global.db"
   for d in "$SNAPSHOT"/*/; do
     id=$(basename "$d")
     mkdir -p "$DATA_DIR/$id"
     cp "$d/workspace.db" "$DATA_DIR/$id/workspace.db"
   done

3. Exclua quaisquer arquivos -wal e -shm que estejam ao lado dos bancos de dados que você substituiu. Eles pertencem aos arquivos antigos, e um arquivo obsoleto ao lado de um banco de dados restaurado é um risco de corrupção.

4. Inicie o servidor de novo.

O instantâneo não contém secrets.json, então uma instalação restaurada em um host novo mantém os dados, mas não as credenciais: dispositivos emparelhados, tokens de provedores e configurações de SSO precisam ser restabelecidos, ou restaurados de onde você guardou esse arquivo. Restaurar no mesmo host, onde o secrets.json nunca se perdeu, mantém tudo.

Copiar backups para fora da máquina

Um instantâneo no mesmo disco do banco de dados que ele copiou protege você de uma importação ruim, não do disco. Nada no Control Center envia uma cópia para lugar nenhum, então essa parte é com você.

Sincronizar os instantâneos

Instantâneos são imutáveis depois de gravados e nomeados pelo carimbo de data e hora, então qualquer ferramenta de sincronização lida bem com eles. Exclua transfer/, que é uma bancada de trabalho para downloads e uploads em andamento:

DATA_DIR="$HOME/Library/Application Support/control-center"

# To another host over ssh
rsync -a --delete --exclude 'transfer/' \
  "$DATA_DIR/backups/" backup-host:/srv/control-center-backups/

# To object storage
aws s3 sync --exclude 'transfer/*' \
  "$DATA_DIR/backups/" s3://my-bucket/control-center/backups/

# Or with deduplication, encryption and its own retention
restic backup --exclude 'transfer' "$DATA_DIR/backups"

--delete espelha a limpeza local no remoto. Remova essa opção se você quiser que o remoto guarde instantâneos por mais tempo do que o host.

Nunca sincronize os bancos de dados em uso diretamente

Não aponte rsync, aws s3 sync nem um agente de backup em nível de arquivo para global.db ou <workspaceId>/workspace.db enquanto o servidor estiver rodando. Um banco de dados SQLite em uso tem um arquivo secundário -wal, e uma cópia arquivo por arquivo captura os dois em instantes diferentes — o resultado é um arquivo que muitas vezes abre e está silenciosamente sem gravações recentes, ou que não abre de jeito nenhum. Copie o instantâneo, que foi gravado sob uma transação de leitura, ou crie um com VACUUM INTO como abaixo.

Incluir o que um instantâneo deixa de fora

Para conseguir reconstruir a instalação e não apenas os dados dela, copie estes também. São arquivos comuns, seguros de copiar enquanto o servidor está rodando:

rsync -a \
  "$DATA_DIR/secrets.json" \
  backup-host:/srv/control-center-backups/config/

rsync -a --relative \
  "$DATA_DIR"/./*/chat_credentials \
  "$DATA_DIR"/./*/blobs \
  "$DATA_DIR"/./*/skills \
  "$DATA_DIR"/./*/agents \
  backup-host:/srv/control-center-backups/workspace-files/

secrets.json tem permissão 0600 e contém todas as chaves de emparelhamento, credenciais de provedores e configurações de SSO da instalação. Onde quer que ele fique, o local precisa ser pelo menos tão protegido quanto o host do servidor — criptografado em repouso e não um bucket que qualquer outra pessoa possa ler.

Ignore spaces/ (worktrees com copy-on-write, reprovisionados a partir dos seus repos), pr_clones/ (um cache), models/ (baixados de novo), media_cache/ e rigs/ (estado da máquina, e grandes). O áudio de reuniões gravado em meetings/ vale a pena incluir se você guarda as reuniões.

Agendar um instantâneo da instalação inteira fora do app

O pipeline embutido faz backup de apenas um espaço de trabalho. Para um instantâneo da instalação inteira sem supervisão, não há subcomando de CLI, e o RPC de instantâneo exige um cliente completo emparelhado que seja o proprietário da instalação. Um temporizador no host pode usar VACUUM INTO contra os bancos de dados em uso:

#!/usr/bin/env bash
set -euo pipefail

DATA_DIR="${CC_SERVER_DATA_DIR:-$HOME/.local/share/control-center}"
DEST="/srv/control-center-snapshots/$(date -u +%Y-%m-%dT%H-%M-%SZ)"
mkdir -p "$DEST"

sqlite3 "$DATA_DIR/global.db" "VACUUM INTO '$DEST/global.db'"

for db in "$DATA_DIR"/*/workspace.db; do
  id=$(basename "$(dirname "$db")")
  mkdir -p "$DEST/$id"
  sqlite3 "$db" "VACUUM INTO '$DEST/$id/workspace.db'"
done

Execute-o como o mesmo usuário dono do diretório de dados, pelo cron ou por um temporizador do systemd, e sincronize o DEST para fora do host depois. O VACUUM INTO precisa do SQLite 3.27 ou mais recente.

Grave-o fora de <dataDir>/backups/. Um diretório feito à mão ali não tem manifest.json, então o app o listaria como um instantâneo incompleto e a lista deixaria de ser um registro honesto do que o próprio servidor produziu.

Limpar instantâneos antigos da instalação inteira

Você pode excluir instantâneos da instalação individualmente no app. Para uma política de retenção no host, mantenha o diretório de backups de espaço de trabalho separado dos instantâneos da instalação:

find "$DATA_DIR/backups" -mindepth 1 -maxdepth 1 -type d \
  ! -name exports ! -name transfer ! -name workspace-backups \
  -mtime +30 -exec rm -rf {} +

Confira a saída de uma execução com -print antes de adicionar -exec. Mantenha mais de um: a falha contra a qual você está se protegendo muitas vezes é “o último backup também tem o problema”.

Verificar se um backup está bom

Um backup que ninguém restaurou é uma hipótese.

Verificação barata — o arquivo abre e suas páginas estão intactas:

sqlite3 "$SNAPSHOT/global.db" 'PRAGMA integrity_check;'   # expects: ok

Verificação de verdade — adote-o. Crie um espaço de trabalho descartável em uma instalação que não seja de produção, importe um arquivo de espaço de trabalho para ele e veja se os espaços, tickets e mensagens que você espera estão lá. Isso exercita o mesmo caminho que uma restauração real percorre, incluindo a recriação do FTS, e é a única verificação que diz que o backup é restaurável, e não apenas legível.

Faça isso uma vez quando configurar os backups, e de novo sempre que mudar onde eles são guardados.

Solução de problemas

Sintoma	Causa e correção
Os controles de download e upload ficam desabilitados com uma observação sobre um relay	Você está conectado pelo relay intermediado, que não transporta arquivos. Conecte-se diretamente
“O servidor recusou”	Papel. Criar ou listar um instantâneo da instalação exige o operador da instalação. Baixar um espaço de trabalho exige admin, restaurar um exige owner, e um zip de instantâneo inteiro exige o operador da instalação
“Este servidor não expõe nenhuma superfície de backup”	O host não tem uma porta de backup configurada — um servidor de demonstração. As operações ficam ausentes em vez de serem recusadas
“O arquivo é maior do que o servidor aceita”	Os uploads têm limite de 8 GiB. Coloque o arquivo no host do servidor e use Importar → Escolher arquivo
Importação recusada: não é um banco de dados de espaço de trabalho do Control Center	O arquivo não tem uma linha workspace_meta — ele não é uma exportação de espaço de trabalho, ou está truncado. Nada foi substituído
Um instantâneo aparece como Incompleto	O manifesto dele está ausente ou aponta para arquivos que não existem. Crie um novo; adote os arquivos de espaço de trabalho individuais dele enquanto isso
Um instantâneo diz que espaços de trabalho não foram capturados	Esses espaços de trabalho nunca foram gravados, ou a cópia deles falhou. Verifique o log do servidor
Uma instalação restaurada não tem credenciais de forge nem de SSO	O secrets.json não está em um instantâneo. Restaure-o de onde você o guardou, ou reconecte os provedores
Um espaço de trabalho restaurado está sem imagens coladas	Os blobs ficam ao lado do banco de dados, não dentro dele. Copie <workspaceId>/blobs/ também

Guias relacionados

• Executar um servidor headless: de onde vem o diretório de dados
• Conectar a um servidor remoto: conexões diretas versus por relay
• Emparelhar um dispositivo: a credencial com que as rotas de transferência são assinadas

Conceitos e referência relacionados

• Backup, exportação e importação: cada operação, rota, campo e limite
• Espaços de trabalho e isolamento: por que um espaço de trabalho é um arquivo
• CLI do cc_server: o layout do diretório de dados