Fazer cópia de segurança e restaurar

Este guia aborda as cinco coisas que as pessoas fazem realmente com cópias de segurança: tirar uma, recolhê-la, mover um espaço de trabalho, repor uma e manter cópias fora da máquina. Para a forma exata de cada artefacto e de cada operação, consulte a referência de cópia de segurança.

Está tudo em Definições → Servidor → Backup e restauração.

Pré-requisitos

Um cliente completo — a aplicação para computador ou a aplicação Web. Um telemóvel emparelhado não consegue desencadear nada disto, por conceção.
Para tirar, listar, descarregar ou eliminar um instantâneo da instalação: o proprietário da instalação.
Para ações por espaço de trabalho: admin desse espaço de trabalho para exportar, proprietário para o importar ou eliminar.
Para descarregamentos e envios: uma ligação direta ao servidor. O relay intermediário transporta frames RPC, não transferências de ficheiros, e os controlos de transferência desativam-se com uma nota quando a ligação passa por um relay.

O que abrange uma cópia de segurança

Ambos os artefactos são apenas bases de dados:

Um instantâneo da instalação é uma pasta com 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 ficheiro workspace.db.

Nenhum deles transporta o resto do diretório de dados: secrets.json (chaves de emparelhamento, credenciais de fornecedores, SSO), os blobs/ de um espaço de trabalho (imagens coladas em mensagens), skills/, agents/, chat_credentials/, o á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 é para o que serve a secção sobre cópias fora da máquina.

Tirar um instantâneo da instalação inteira

Abra Definições → Servidor → Backup e restauração.
Em Instantâneos da instalação, prima Fazer backup agora.
A notificação indica o diretório que foi escrito, no anfitrião do servidor. O novo instantâneo aparece no topo da lista.

O servidor continua em execução durante todo o processo. Cada ficheiro é escrito com VACUUM INTO, que é consistente em relação a uma base de dados em utilização, pelo que não há janela de manutenção nem necessidade de parar agentes.

Cada linha da lista mostra a 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á em falta ou que refere ficheiros que não existem — uma cópia de segurança interrompida por uma falha ou por um disco cheio. Continuam a ser listados de propósito: um instantâneo que não vê é um instantâneo que acredita ter. Um instantâneo incompleto não consegue restaurar uma instalação inteira, mas os ficheiros de espaço de trabalho que contém ainda podem ser adotados um a um.

Uma linha pode também indicar n espaços de trabalho não capturados. Trata-se de um espaço de trabalho registado mas nunca escrito (ainda não há ficheiro), ou de um cuja cópia falhou — verifique o registo do servidor.

Agendar cópias de segurança de espaços de trabalho e a retenção

Abra Definições → Pipelines → Modelos de pipeline do espaço de trabalho e localize Workspace backup. A agenda ativada é executada todos os domingos às 03:00 UTC: Back up workspace, seguido de Delete backups older than (30 dias por predefinição). O segundo nó só é executado depois de a cópia de segurança ser bem-sucedida. Pode alterar os dias de retenção no nó ou desativar a agenda. Se o servidor estiver offline à hora agendada, a agenda recupera uma vez quando ele voltar, em vez de repetir todas as semanas falhadas.

As cópias de segurança de espaços de trabalho ficam no servidor em backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. O nó de retenção elimina apenas cópias de segurança antigas deste espaço de trabalho; nunca elimina instantâneos da instalação nem cópias de segurança de outros espaços de trabalho. Estes ficheiros contêm apenas bases de dados. Para retenção fora da máquina, copie-os em separado.

Estas cópias de segurança são distintas da lista Instantâneos da instalação. Para restaurar uma, use Dados do espaço de trabalho → Importar com o caminho workspace.db da cópia de segurança no lado do servidor. A importação substitui a base de dados atual desse espaço de trabalho, por isso exporte-a primeiro se puder precisar de desfazer o restauro.

Eliminar um instantâneo da instalação

Em Instantâneos da instalação, expanda o instantâneo, incluindo um incompleto, e use Excluir instantâneo na zona de perigo. Confirme o nome. Todo o diretório do instantâneo é removido permanentemente do servidor; descarregue-o primeiro se precisar de uma cópia. Um pipeline de cópia de segurança de espaço de trabalho nunca elimina estes instantâneos.

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

Os caminhos mostrados na página estão na máquina que executa o cc_server. Quando essa não é a máquina onde está sentado, use os botões Descarregar:

Junto a cada espaço de trabalho, em Dados do espaço de trabalho → Descarregar, para um ficheiro .db.
Junto a cada instantâneo, em Instantâneos da instalação → Descarregar, para o instantâneo inteiro como um .zip.

Na aplicação para computador, escolhe onde o ficheiro fica e a notificação indica-o; na Web, vai para as descargas do navegador. De qualquer forma, ambos comunicam o progresso em bytes, porque estas são as duas cargas que chegam à ordem dos gigabytes.

Ambos criam uma cópia nova no momento em que prime o botão, transmitem-na em fluxo e eliminam depois a cópia do servidor — um descarregamento não é “ir buscar o ficheiro que o botão de exportação criou antes”.

Descompactar um arquivo de instantâneo reproduz exatamente a estrutura do instantâneo, e é isso que faz do restauro uma cópia de volta.

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

Um espaço de trabalho é um ficheiro de base de dados, por isso entregá-lo é uma operação sobre ficheiros.

No servidor de origem, em Definições → Servidor → Backup e restauração → Dados do espaço de trabalho, expanda o espaço de trabalho e prima Descarregar.
No servidor de destino, crie (ou escolha) o espaço de trabalho que o vai receber.
Expanda esse espaço de trabalho e, em Restaurar a partir deste dispositivo, prima Escolher um ficheiro e enviar. Escolha o .db que descarregou.

Se os dois servidores forem a mesma máquina onde está sentado, Guardar no servidor mais Importar → Escolher ficheiro fazem o mesmo sem a ida e volta; os caminhos da caixa de diálogo de importação são resolvidos no anfitrião do servidor.

Duas coisas são permitidas e registadas em vez de recusadas: importar um ficheiro cujo id de espaço de trabalho registado difere do destino (é assim que duplica um espaço de trabalho ou o restaura com um id novo) e importar um ficheiro de uma instalação diferente. Nesse segundo caso, os dispositivos emparelhados e os ids de utilizador do ficheiro pertencem à instalação de onde veio e não serão resolvidos nesta — os dados do próprio espaço de trabalho estão intactos, mas volte a confirmar a associação depois de o adotar.

Os tokens do bot de chat ficam ao lado da base de dados, não dentro dela, por isso um espaço de trabalho que entrega a outra pessoa não transporta credenciais ativas. A instalação que o recebe volta a ligar as suas próprias.

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

Em Instantâneos da instalação, expanda o instantâneo que pretende.
Localize a linha do espaço de trabalho e prima Restaurar.
Confirme. Tudo o que esse espaço de trabalho fez desde que o instantâneo foi tirado perde-se.

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

Uma linha pode indicar Não está mais neste servidor, com Restaurar desativado: o instantâneo contém um espaço de trabalho que esta instalação já não tem. Recupere-o 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 seu próprio Caminho no servidor num campo de cópia, e o título da linha é o id antigo do espaço de trabalho, por isso tem as duas metades desse caminho à frente.

Restaurar uma instalação inteira

Não existe um botão para isto, e não deveria existir: substituiria as bases de dados que o servidor em execução mantém abertas.

Pare o cc_server. Se executa a aplicação para computador com o servidor incorporado, saia da aplicação.

Copie o conteúdo do instantâneo para cima do diretório de dados. A estrutura do instantâneo espelha a do ambiente em execução, por isso é 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

Elimine quaisquer ficheiros -wal e -shm que estejam ao lado das bases de dados que substituiu. Pertencem aos ficheiros antigos, e um ficheiro obsoleto ao lado de uma base de dados restaurada é um risco de corrupção.
Inicie o servidor de novo.

O instantâneo não contém secrets.json, por isso uma instalação restaurada num anfitrião novo mantém os dados mas não as credenciais: os dispositivos emparelhados, os tokens dos fornecedores e as definições de SSO têm de ser restabelecidos, ou restaurados a partir do local onde guardou esse ficheiro. Restaurar no mesmo anfitrião, onde o secrets.json nunca se perdeu, mantém tudo.

Copiar as cópias de segurança para fora da máquina

Um instantâneo no mesmo disco da base de dados que copiou protege-o de uma importação errada, não do disco. Nada no Control Center envia uma cópia para lado nenhum, por isso esta parte é por sua conta.

Sincronizar os instantâneos

Os instantâneos são imutáveis depois de escritos e têm o nome dado pela data e hora, por isso qualquer ferramenta de sincronização lida bem com eles. Exclua transfer/, que é uma bancada de trabalho para descarregamentos e envios em curso:

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 no remoto a limpeza que faz localmente. Remova a opção se quiser que o remoto guarde instantâneos durante mais tempo do que o anfitrião.

Incluir o que um instantâneo deixa de fora

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

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/

O secrets.json tem as permissões 0600 e contém todas as chaves de emparelhamento, credenciais de fornecedores e definições de SSO da instalação. Onde quer que fique, tem de estar pelo menos tão protegido como o anfitrião do servidor — cifrado em repouso e não um bucket que qualquer outra pessoa consiga ler.

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

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

O pipeline incorporado só faz cópia de segurança de um espaço de trabalho. Para um instantâneo da instalação inteira sem supervisão, não existe qualquer subcomando de CLI, e o RPC de instantâneo exige um cliente completo emparelhado que seja o proprietário da instalação. Um temporizador do lado do anfitrião pode usar VACUUM INTO contra as bases de dados em utilização:

#!/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 utilizador que é proprietário do diretório de dados, a partir do cron ou de um temporizador do systemd, e sincronize depois o DEST para fora do anfitrião. O VACUUM INTO requer o SQLite 3.27 ou mais recente.

Escreva-o fora de <dataDir>/backups/. Um diretório criado à mão nesse local não tem manifest.json, por isso a aplicação iria listá-lo como um instantâneo incompleto e a lista deixaria de ser um registo honesto daquilo que o próprio servidor produziu.

Limpar instantâneos antigos da instalação inteira

Pode eliminar instantâneos da instalação individuais na aplicação. Para uma política de retenção do lado do anfitrião, mantenha o diretório de cópias de segurança de espaços 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 {} +

Verifique a saída de uma execução com -print antes de adicionar -exec. Mantenha mais do que um: a falha contra a qual se está a proteger é muitas vezes “a última cópia de segurança também tem o problema”.

Verificar se uma cópia de segurança está boa

Uma cópia de segurança que ninguém restaurou é uma hipótese.

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

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

Verificação real — adote-o. Crie um espaço de trabalho descartável numa instalação que não seja de produção, importe para ele um ficheiro de espaço de trabalho e veja se os espaços, os tickets e as mensagens que espera estão lá. Isto exercita o mesmo caminho que um restauro real percorre, incluindo a reconstrução do FTS, e é a única verificação que lhe diz que a cópia de segurança é restaurável e não apenas legível.

Faça isto uma vez quando configurar as cópias de segurança e de novo sempre que mudar o local onde são guardadas.

Resolução de problemas

Sintoma	Causa e solução
Os controlos de descarregamento e envio estão desativados com uma nota sobre um relay	Está ligado através do relay intermediário, que não transporta transferências de ficheiros. Ligue-se diretamente
“O servidor recusou”	Papel. Tirar ou listar um instantâneo da instalação exige o operador da instalação. Descarregar um espaço de trabalho exige o papel admin, restaurar um exige o proprietário 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 anfitrião não tem nenhuma porta de cópia de segurança ligada — é um servidor de demonstração. As operações estão ausentes em vez de serem recusadas
“O ficheiro é maior do que o servidor aceita”	Os envios estão limitados a 8 GiB. Coloque o ficheiro no anfitrião do servidor e use antes Importar → Escolher ficheiro
Import refused: not a Control Center workspace database	O ficheiro não tem uma linha `workspace_meta` — não é uma exportação de espaço de trabalho, ou está truncado. Nada foi substituído
Um instantâneo aparece listado como Incompleto	O manifesto está em falta ou refere ficheiros que não existem. Tire um novo; entretanto, adote a partir dele os ficheiros de espaço de trabalho individuais
Um instantâneo diz que há espaços de trabalho não capturados	Esses espaços de trabalho nunca foram escritos, ou a cópia deles falhou. Verifique o registo do servidor
Uma instalação restaurada não tem credenciais de forge nem de SSO	O `secrets.json` não está num instantâneo. Restaure-o do local onde o guardou ou volte a ligar os fornecedores
Faltam imagens coladas a um espaço de trabalho restaurado	Os blobs ficam ao lado da base de dados, não dentro dela. Copie também `<workspaceId>/blobs/`

Guias relacionados

Executar um servidor headless: de onde vem o diretório de dados
Ligar a um servidor remoto: ligações diretas em comparação com ligações por relay
Emparelhar um dispositivo: a credencial com que as rotas de transferência são assinadas

Conceitos e referência relacionados

Cópia de segurança, exportação e importação: todas as operações, rotas, campos e limites
Espaços de trabalho e isolamento: porque é que um espaço de trabalho é um ficheiro
CLI do cc_server: a estrutura do diretório de dados