Backup e ripristino

Questa guida copre le cinque cose che si fanno davvero con i backup: crearne uno, raccoglierlo, spostare uno spazio di lavoro, rimetterne uno a posto e tenere copie fuori dalla macchina. Per la forma esatta di ogni artefatto e di ogni operazione, vedi il riferimento sul backup.

Tutto quello che c’è qui vive in Impostazioni → Server → Backup e ripristino.

Prerequisiti

• Un client completo — l’app desktop o web. Un telefono associato non può attivare nulla di tutto questo, per scelta progettuale.
• Per creare, elencare, scaricare o eliminare un’istantanea dell’installazione: il proprietario dell’installazione.
• Per le azioni su un singolo spazio di lavoro: admin di quello spazio di lavoro per esportarlo, proprietario per importarlo o eliminarlo.
• Per i download e gli upload: una connessione diretta al server. Il relay intermediato da un broker trasporta frame RPC, non trasferimenti di file, e i controlli di trasferimento si disattivano da soli con una nota quando sei su uno di questi.

Le istantanee dell’installazione sono manuali

Esegui backup ora crea comunque un’istantanea dell’intera installazione solo su richiesta. La pipeline integrata Workspace backup può invece fare un backup del database di uno spazio di lavoro una volta alla settimana e rimuovere i backup di quello spazio di lavoro più vecchi di 30 giorni. Non copia global.db, altri spazi di lavoro né i file accanto al database. Conserva separatamente le copie fuori dalla macchina.

Cosa copre un backup

Entrambi gli artefatti sono solo database:

• Un’istantanea dell’installazione è una directory con data e ora: manifest.json, global.db e un <workspaceId>/workspace.db per ogni spazio di lavoro.
• Un’esportazione dello spazio di lavoro è quel singolo file workspace.db.

Nessuno dei due porta con sé il resto della directory dei dati: secrets.json (chiavi di associazione, credenziali dei fornitori, SSO), i blobs/ di uno spazio di lavoro (immagini incollate nei messaggi), skills/, agents/, chat_credentials/, l’audio delle riunioni registrate o le immagini dei rig. Una parte è usa e getta e una parte no — la tabella completa è nel riferimento, e coprirla è esattamente lo scopo della sezione fuori dalla macchina.

Scatta un’istantanea dell’intera installazione

1. Apri Impostazioni → Server → Backup e ripristino.
2. Sotto Istantanee dell’installazione, premi Esegui backup ora.
3. L’avviso indica la directory che è stata scritta, sull’host del server. La nuova istantanea compare in cima all’elenco.

Il server resta in esecuzione per tutto il tempo. Ogni file viene scritto con VACUUM INTO, che è coerente anche su un database in uso, quindi non c’è alcuna finestra di manutenzione né bisogno di fermare gli agenti.

Ogni riga dell’elenco mostra la data e l’ora, la dimensione su disco, quanti spazi di lavoro sono stati acquisiti e se l’istantanea è Completa o Incompleta. Incompleta significa che il manifest manca o nomina file che non ci sono — un backup interrotto da un crash o da un disco pieno. Vengono comunque elencate di proposito: un’istantanea che non vedi è un’istantanea che credi di avere. Un’istantanea incompleta non può ripristinare un’intera installazione, ma i file degli spazi di lavoro che contiene si possono ancora adottare uno per uno.

Una riga può anche dire n spazi di lavoro non acquisiti. È uno spazio di lavoro registrato ma in cui non è mai stato scritto nulla (il file non esiste ancora), oppure uno la cui copia non è riuscita — controlla il log del server.

Pianifica i backup degli spazi di lavoro e la conservazione

Apri Impostazioni → Pipeline → Modelli di pipeline per lo spazio di lavoro e cerca Workspace backup. La sua pianificazione attiva viene eseguita ogni domenica alle 03:00 UTC: Back up workspace, seguito da Delete backups older than (30 giorni per impostazione predefinita). Il secondo nodo viene eseguito solo dopo il successo del backup. Puoi cambiare i giorni di conservazione sul nodo o disattivare la pianificazione. Se il server è offline all’ora prevista, la pianificazione recupera una volta sola al suo ritorno, invece di ripetere ogni settimana saltata.

I backup degli spazi di lavoro vivono sul server in backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Il nodo di conservazione elimina solo i backup vecchi di questo spazio di lavoro; non elimina mai le istantanee dell’installazione né i backup di altri spazi di lavoro. Questi file contengono solo database. Per una conservazione fuori dalla macchina, copiali in modo indipendente.

Questi backup sono separati dall’elenco Istantanee dell’installazione. Per ripristinarne uno, usa Dati dello spazio di lavoro → Importa con il percorso workspace.db lato server del backup. L’importazione sostituisce il database attuale di quello spazio di lavoro, quindi esportalo prima se potresti aver bisogno di annullare il ripristino.

Elimina un’istantanea dell’installazione

Sotto Istantanee dell’installazione, espandi l’istantanea, anche una incompleta, e usa Elimina istantanea nella zona pericolosa. Conferma il suo nome. L’intera directory dell’istantanea viene rimossa definitivamente dal server; scaricala prima se ti serve una copia. Una pipeline di backup degli spazi di lavoro non elimina mai queste istantanee.

Raccogli una copia sulla tua macchina

I percorsi che la pagina mostra sono sulla macchina che esegue cc_server. Quando non è la macchina su cui sei seduto, usa i pulsanti Scarica:

• Accanto a ogni spazio di lavoro, sotto Dati dello spazio di lavoro → Scarica, per un singolo file .db.
• Accanto a ogni istantanea, sotto Istantanee dell’installazione → Scarica, per l’intera istantanea come .zip.

Su desktop scegli dove finisce il file e l’avviso lo indica; sul web finisce nei download del browser. In entrambi i casi il progresso è riportato in byte, perché questi sono i due payload che arrivano a gigabyte.

Entrambi generano una copia nuova nel momento in cui premi il pulsante, la trasmettono in streaming e poi eliminano la copia del server — un download non è «recuperare il file che il pulsante di esportazione aveva creato prima».

Estrarre un archivio di istantanea riproduce esattamente la struttura dell’istantanea, ed è ciò che rende il suo ripristino una semplice copia di ritorno.

Sposta uno spazio di lavoro su un’altra installazione

Uno spazio di lavoro è un solo file di database, quindi passarlo a qualcun altro è un’operazione su file.

1. Sul server di origine, Impostazioni → Server → Backup e ripristino → Dati dello spazio di lavoro, espandi lo spazio di lavoro e premi Scarica.
2. Sul server di destinazione, crea (o scegli) lo spazio di lavoro che lo riceverà.
3. Espandi quello spazio di lavoro e, sotto Ripristina da questo dispositivo, premi Scegli un file e caricalo. Scegli il .db che hai scaricato.

Se entrambi i server sono la macchina su cui sei seduto, Salva sul server più Importa → Scegli un file fanno la stessa cosa senza il viaggio di andata e ritorno; i percorsi della finestra di importazione vengono risolti sull’host del server.

L’importazione sostituisce tutto

Importare sovrascrive tutto ciò che lo spazio di lavoro di destinazione contiene attualmente, e non si può annullare. Esporta prima la destinazione se contiene qualcosa che potresti voler riavere.

Due cose sono consentite e registrate invece che rifiutate: importare un file il cui id di spazio di lavoro registrato differisce da quello di destinazione (è così che duplichi uno spazio di lavoro o lo ripristini sotto un nuovo id), e importare un file da un’installazione diversa. In questo secondo caso i dispositivi associati e gli id utente del file appartengono all’installazione da cui proviene e non si risolveranno su questa — i dati dello spazio di lavoro sono intatti, ma ricontrolla l’appartenenza dopo averlo adottato.

I token dei bot di chat vivono accanto al database, non al suo interno, quindi uno spazio di lavoro che passi a qualcun altro non porta con sé credenziali attive. L’installazione che lo riceve ricollega le proprie.

Ripristina un solo spazio di lavoro da un’istantanea

1. Sotto Istantanee dell’installazione, espandi l’istantanea che vuoi.
2. Trova la riga dello spazio di lavoro e premi Ripristina.
3. Conferma. Tutto ciò che quello spazio di lavoro ha fatto da quando è stata scattata l’istantanea va perso.

È la stessa operazione di un’importazione, puntata sulla copia che l’istantanea contiene del file di quello spazio di lavoro — di proposito, così non c’è un secondo meccanismo che possa trattare lo stesso file in modo diverso.

Una riga può dire Non è più su questo server, con Ripristina disattivato: l’istantanea contiene uno spazio di lavoro che questa installazione non ha più. Riportalo indietro a mano — crea uno spazio di lavoro, poi sotto Dati dello spazio di lavoro importa al suo interno da <snapshot path>/<old workspace id>/workspace.db. L’istantanea espansa mostra il suo Percorso sul server in un campo copiabile, e il titolo della riga è il vecchio id dello spazio di lavoro, quindi hai entrambe le metà di quel percorso davanti a te.

Ripristina un’intera installazione

Non esiste un pulsante per farlo, e non dovrebbe esistere: sostituisce i database che il server in esecuzione tiene aperti.

1. Ferma cc_server. Se usi l’app desktop con il suo server incorporato, chiudi l’app.

2. Copia il contenuto dell’istantanea sopra la directory dei dati. La struttura dell’istantanea rispecchia quella attiva, quindi è una semplice copia:

   # 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. Elimina i file -wal e -shm che si trovano accanto ai database che hai sostituito. Appartengono ai vecchi file, e un file rimasto lì accanto a un database ripristinato è un rischio di corruzione.

4. Avvia di nuovo il server.

L’istantanea non contiene secrets.json, quindi un’installazione ripristinata su un host nuovo conserva i suoi dati ma non le sue credenziali: dispositivi associati, token dei fornitori e impostazioni SSO vanno ristabiliti, oppure ripristinati da dove hai conservato quel file. Ripristinare sullo stesso host, dove secrets.json non è mai andato perso, conserva tutto.

Copia i backup fuori dalla macchina

Un’istantanea sullo stesso disco del database che ha copiato ti protegge da un’importazione sbagliata, non dal disco. Niente in Control Center spedisce una copia da nessuna parte, quindi questa parte tocca a te.

Sincronizza le istantanee

Le istantanee sono immutabili una volta scritte e nominate per data e ora, quindi qualsiasi strumento di sincronizzazione le gestisce bene. Escludi transfer/, che è un banco di lavoro per download e upload in corso:

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 rispecchia sul remoto la tua pulizia locale. Toglilo se vuoi che il remoto conservi le istantanee più a lungo dell’host.

Non sincronizzare mai direttamente i database in uso

Non puntare rsync, aws s3 sync o un agente di backup a livello di file su global.db o <workspaceId>/workspace.db mentre il server è in esecuzione. Un database SQLite in uso ha un file -wal collaterale, e una copia file per file cattura i due in istanti diversi — il risultato è un file che spesso si apre ma perde silenziosamente le scritture recenti, oppure che non si apre affatto. Copia l’istantanea, che è stata scritta all’interno di una transazione di lettura, oppure creane una con VACUUM INTO come qui sotto.

Includi ciò che un’istantanea lascia fuori

Per poter ricostruire l’installazione e non solo i suoi dati, copia anche questi. Sono file normali, sicuri da copiare mentre il server è in esecuzione:

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 è 0600 e contiene ogni chiave di associazione, credenziale di fornitore e impostazione SSO dell’installazione. Ovunque finisca deve essere almeno altrettanto protetto dell’host del server — cifrato a riposo, e non un bucket che chiunque altro possa leggere.

Salta spaces/ (worktree copy-on-write, riprovisionati dai tuoi repo), pr_clones/ (una cache), models/ (riscaricati), media_cache/ e rigs/ (stato della macchina, e grandi). L’audio delle riunioni registrate sotto meetings/ vale la pena di includerlo se conservi le riunioni.

Pianifica un’istantanea dell’intera installazione fuori dall’app

La pipeline integrata esegue il backup di un solo spazio di lavoro. Per un’istantanea dell’intera installazione senza supervisione non esiste un sottocomando CLI, e l’RPC dell’istantanea richiede un client completo associato che sia il proprietario dell’installazione. Un timer lato host può usare VACUUM INTO sui database in 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

Eseguilo come lo stesso utente che possiede la directory dei dati, da cron o da un timer systemd, e poi sincronizza DEST fuori dall’host. VACUUM INTO richiede SQLite 3.27 o successivo.

Scrivilo fuori da <dataDir>/backups/. Una directory creata a mano lì dentro non ha manifest.json, quindi l’app la elencherebbe come un’istantanea incompleta e l’elenco smetterebbe di essere un registro onesto di ciò che il server ha prodotto da sé.

Elimina le vecchie istantanee dell’intera installazione

Puoi eliminare le singole istantanee dell’installazione nell’app. Per una politica di conservazione lato host, tieni la directory dei backup degli spazi di lavoro separata dalle istantanee dell’installazione:

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

Controlla l’output di un’esecuzione con -print prima di aggiungere -exec. Conservane più di una: il guasto da cui ti proteggi è spesso «anche l’ultimo backup ha lo stesso problema».

Verifica che un backup sia buono

Un backup che nessuno ha ripristinato è un’ipotesi.

Verifica rapida — il file si apre e le sue pagine sono intatte:

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

Verifica reale — adottalo. Crea uno spazio di lavoro di prova su un’installazione non di produzione, importa al suo interno un file di spazio di lavoro e guarda se gli spazi, i ticket e i messaggi che ti aspetti ci sono. Questo esercita lo stesso percorso di un ripristino reale, compresa la ricostruzione FTS, ed è l’unica verifica che ti dice che il backup è ripristinabile e non solo leggibile.

Fallo una volta quando imposti i backup, e di nuovo ogni volta che cambi dove sono conservati.

Risoluzione dei problemi

Sintomo	Causa e soluzione
I controlli di download e upload sono disattivati con una nota su un relay	Sei connesso attraverso il relay intermediato da un broker, che non trasporta alcun trasferimento di file. Collegati direttamente
«Il server ha rifiutato»	Ruolo. Creare o elencare un’istantanea dell’installazione richiede l’operatore dell’installazione. Scaricare uno spazio di lavoro richiede admin, ripristinarne uno richiede proprietario, e uno zip con l’intera istantanea richiede l’operatore dell’installazione
«Questo server non espone alcuna superficie di backup»	L’host non ha alcuna porta di backup cablata — un server demo. Le operazioni sono assenti invece che rifiutate
«Il file supera la dimensione accettata dal server»	Gli upload sono limitati a 8 GiB. Metti il file sull’host del server e usa invece Importa → Scegli un file
Import refused: not a Control Center workspace database	Il file non ha alcuna riga workspace_meta — non è un’esportazione di spazio di lavoro, oppure è troncato. Non è stato sostituito nulla
Un’istantanea è elencata come Incompleta	Il suo manifest manca o nomina file assenti. Creane una nuova; nel frattempo adotta da essa i singoli file degli spazi di lavoro
Un’istantanea dice che alcuni spazi di lavoro non sono stati acquisiti	Quegli spazi di lavoro non hanno mai ricevuto scritture, oppure la loro copia non è riuscita. Controlla il log del server
A un’installazione ripristinata mancano le credenziali della forge o dell’SSO	secrets.json non è dentro un’istantanea. Ripristinalo da dove l’hai conservato, oppure ricollega i fornitori
A uno spazio di lavoro ripristinato mancano le immagini incollate	I blob vivono accanto al database, non al suo interno. Copia anche <workspaceId>/blobs/

Guide correlate

• Esegui un server headless: da dove viene la directory dei dati
• Connettiti a un server remoto: connessioni dirette o via relay
• Associa un dispositivo: la credenziale con cui firmano le route di trasferimento

Concetti e riferimenti correlati

• Backup, esportazione e importazione: ogni operazione, route, campo e limite
• Spazi di lavoro e isolamento: perché uno spazio di lavoro è un solo file
• cc_server CLI: la struttura della directory dei dati