Back-uppen en herstellen

Deze handleiding behandelt de vijf dingen die mensen daadwerkelijk met back-ups doen: er een maken, hem ophalen, een werkruimte verplaatsen, er een terugzetten en kopieën buiten de machine bewaren. Voor de exacte vorm van elk artefact en elke handeling, zie de back-upreferentie.

Alles hier staat onder Instellingen → Server → Back-up en herstel.

Vereisten

Een volledige client — de desktop- of webapp. Een gekoppelde telefoon kan dit allemaal niet starten, en dat is bewust.
Voor het maken, opvragen, downloaden of verwijderen van een momentopname van de installatie: de eigenaar van de installatie.
Voor acties per werkruimte: beheerder van die werkruimte om te exporteren, eigenaar om te importeren of te verwijderen.
Voor downloads en uploads: een rechtstreekse verbinding met de server. De relay die dit bemiddelt, vervoert RPC-frames, geen bestandsoverdrachten, en de overdrachtsknoppen schakelen zichzelf uit met een melding zodra je via een relay verbonden bent.

Wat een back-up omvat

Beide artefacten zijn alleen databases:

Een momentopname van de installatie is een map met tijdstempel: manifest.json, global.db en per werkruimte één <workspaceId>/workspace.db.
Een werkruimte-export is dat ene bestand workspace.db.

Geen van beide bevat de rest van de gegevensmap: secrets.json (koppelingssleutels, inloggegevens van aanbieders, SSO), de blobs/ van een werkruimte (afbeeldingen die in berichten zijn geplakt), skills/, agents/, chat_credentials/, opgenomen vergaderaudio of rig-afbeeldingen. Sommige daarvan kun je missen, andere niet — de volledige tabel staat in de referentie, en dat afdekken is waar de sectie buiten de machine voor dient.

Een momentopname van de hele installatie maken

Open Instellingen → Server → Back-up en herstel.
Druk onder Momentopnamen van de installatie op Nu back-uppen.
De melding noemt de map die is weggeschreven, op de serverhost. De nieuwe momentopname staat bovenaan de lijst.

De server blijft de hele tijd draaien. Elk bestand wordt geschreven met VACUUM INTO, wat consistent is tegen een live database, dus er is geen onderhoudsvenster en je hoeft geen agenten te stoppen.

Elke rij in de lijst toont het tijdstempel, de grootte op schijf, hoeveel werkruimtes er zijn vastgelegd en of de momentopname Volledig of Onvolledig is. Onvolledig betekent dat het manifest ontbreekt of bestanden noemt die er niet zijn — een back-up die is onderbroken door een crash of een volle schijf. Die blijven bewust in de lijst staan: een momentopname die je niet ziet, is er een waarvan je denkt dat je hem hebt. Een onvolledige momentopname kan de hele installatie niet herstellen, maar de werkruimtebestanden die er wel in zitten kun je nog steeds één voor één overnemen.

Een rij kan ook n werkruimtes niet vastgelegd zeggen. Dat is een werkruimte die wel geregistreerd is maar nooit beschreven (er is nog geen bestand), of een waarvan de kopie is mislukt — kijk in het serverlog.

Back-ups van werkruimtes en bewaring plannen

Open Instellingen → Pipelines → Pipelinesjablonen voor de werkruimte en zoek Workspace backup. Het ingeschakelde schema draait elke zondag om 03:00 UTC: Back up workspace, gevolgd door Delete backups older than (standaard 30 dagen). De tweede node draait pas nadat de back-up is gelukt. Je kunt de bewaartermijn in dagen op de node aanpassen of het schema uitschakelen. Is de server op het geplande tijdstip offline, dan haalt het schema het één keer in zodra hij terug is, in plaats van elke gemiste week opnieuw af te spelen.

Back-ups van werkruimtes staan op de server onder backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. De bewaarnode verwijdert alleen oude back-ups van deze werkruimte; hij verwijdert nooit momentopnamen van de installatie of back-ups van andere werkruimtes. Deze bestanden bevatten alleen de database. Kopieer ze apart als je ze buiten de machine wilt bewaren.

Deze back-ups staan los van de lijst Momentopnamen van de installatie. Gebruik om er een te herstellen Werkruimtegegevens → Importeren met het serverpad van de workspace.db van de back-up. Importeren vervangt de huidige database van die werkruimte, dus exporteer die eerst als je het herstellen misschien ongedaan wilt maken.

Een momentopname van de installatie verwijderen

Klap onder Momentopnamen van de installatie de momentopname uit, ook een onvolledige, en gebruik Momentopname verwijderen in de gevarenzone. Bevestig de naam. De hele map van de momentopname wordt definitief van de server verwijderd; download hem eerst als je een kopie nodig hebt. Een pipeline voor werkruimteback-ups verwijdert deze momentopnamen nooit.

Een kopie op je eigen machine ophalen

De paden die de pagina toont, staan op de machine waarop cc_server draait. Als dat niet de machine is waar je achter zit, gebruik dan de knoppen Downloaden:

Naast elke werkruimte onder Werkruimtegegevens → Downloaden, voor één .db-bestand.
Naast elke momentopname onder Momentopnamen van de installatie → Downloaden, voor de hele momentopname als .zip.

Op de desktop kies je waar het bestand terechtkomt en noemt de melding het pad; op het web gaat het naar de downloads van de browser. In beide gevallen melden ze de voortgang in bytes, want dit zijn de twee payloads die in de gigabytes kunnen lopen.

Beide maken op het moment dat je op de knop drukt een verse kopie, streamen die en verwijderen daarna de kopie op de server — een download is niet “het bestand ophalen dat de exportknop eerder heeft gemaakt”.

Het uitpakken van een archief van een momentopname herstelt de indeling van de momentopname exact, en dat is wat herstellen een kwestie van terugkopiëren maakt.

Een werkruimte naar een andere installatie verplaatsen

Eén werkruimte is één databasebestand, dus het overdragen is een bestandsbewerking.

Op de bronserver: Instellingen → Server → Back-up en herstel → Werkruimtegegevens, klap de werkruimte uit en druk op Downloaden.
Maak op de doelserver de werkruimte aan die hem ontvangt (of kies er een).
Klap die werkruimte uit en druk onder Herstellen vanaf dit apparaat op Bestand kiezen en uploaden. Kies de .db die je hebt gedownload.

Staan beide servers op de machine waar je achter zit, dan doen Op server opslaan plus Importeren → Bestand kiezen hetzelfde zonder de omweg; de paden in het importdialoogvenster worden opgelost op de serverhost.

Twee dingen zijn toegestaan en worden gelogd in plaats van geweigerd: een bestand importeren waarvan het vastgelegde werkruimte-id afwijkt van het doel (zo dupliceer je een werkruimte of herstel je hem onder een nieuw id), en een bestand importeren uit een andere installatie. In het tweede geval horen de gekoppelde apparaten en gebruikers-id’s van het bestand bij de installatie waar het vandaan komt en werken ze hier niet — de eigen gegevens van de werkruimte zijn intact, maar controleer het lidmaatschap opnieuw nadat je hem hebt overgenomen.

Tokens van chatbots staan naast de database, niet erin, dus een werkruimte die je aan iemand anders geeft, bevat geen actieve inloggegevens. De ontvangende installatie verbindt zijn eigen tokens opnieuw.

Eén werkruimte uit een momentopname herstellen

Klap onder Momentopnamen van de installatie de momentopname uit die je wilt.
Zoek de rij van de werkruimte en druk op Herstellen.
Bevestig. Alles wat die werkruimte heeft gedaan sinds de momentopname is gemaakt, gaat verloren.

Dit is dezelfde handeling als een import, gericht op de kopie van dat werkruimtebestand in de momentopname — bewust, zodat er geen tweede mechanisme is dat hetzelfde bestand anders zou kunnen behandelen.

Een rij kan Staat niet meer op deze server zeggen, met Herstellen uitgeschakeld: de momentopname bevat een werkruimte die deze installatie niet meer heeft. Haal hem handmatig terug — maak een werkruimte aan en importeer daaronder onder Werkruimtegegevens uit <snapshot path>/<old workspace id>/workspace.db. De uitgeklapte momentopname toont zijn eigen Pad op de server in een kopieerveld, en de titel van de rij is het oude werkruimte-id, dus je hebt beide helften van dat pad voor je.

Een hele installatie herstellen

Hiervoor is geen knop, en die hoort er ook niet te zijn: hij vervangt de databases die de draaiende server openhoudt.

Stop cc_server. Als je de desktopapp met de ingebouwde server draait, sluit dan de app af.

Kopieer de inhoud van de momentopname over de gegevensmap. De indeling van de momentopname weerspiegelt de live-indeling, dus dit is een gewone kopie:

# 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

Verwijder alle -wal- en -shm-bestanden naast de databases die je hebt vervangen. Ze horen bij de oude bestanden, en een verouderd bestand naast een herstelde database is een risico op corruptie.
Start de server opnieuw.

De momentopname bevat geen secrets.json, dus een installatie die op een nieuwe host wordt hersteld, behoudt zijn gegevens maar niet zijn inloggegevens: gekoppelde apparaten, tokens van aanbieders en SSO-instellingen moeten opnieuw worden ingesteld, of hersteld vanaf de plek waar je dat bestand hebt bewaard. Herstellen op dezelfde host, waar secrets.json nooit verloren is gegaan, behoudt alles.

Back-ups buiten de machine kopiëren

Een momentopname op dezelfde schijf als de database die hij heeft gekopieerd, beschermt je tegen een slechte import, niet tegen de schijf. Niets in Control Center stuurt ergens een kopie naartoe, dus dit deel is aan jou.

De momentopnamen synchroniseren

Momentopnamen zijn onveranderlijk zodra ze zijn geschreven en hebben een tijdstempel als naam, dus elk synchronisatieprogramma gaat er goed mee om. Sluit transfer/ uit, dat een werkbank is voor lopende downloads en uploads:

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 spiegelt je lokale opruiming naar de externe locatie. Laat het weg als je wilt dat de externe locatie momentopnamen langer bewaart dan de host.

Meenemen wat een momentopname weglaat

Om de installatie te kunnen herbouwen en niet alleen de gegevens, kopieer je deze ook mee. Het zijn gewone bestanden, veilig om te kopiëren terwijl de server draait:

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 staat op 0600 en bevat elke koppelingssleutel, elk inloggegeven van een aanbieder en elke SSO-instelling van de installatie. Waar het ook terechtkomt, moet het minstens zo goed beschermd zijn als de serverhost — versleuteld in rust, en niet in een bucket die anderen kunnen lezen.

Sla spaces/ over (copy-on-write-worktrees, opnieuw ingericht vanuit je repo’s), pr_clones/ (een cache), models/ (opnieuw gedownload), media_cache/ en rigs/ (machinestatus, en groot). Opgenomen vergaderaudio onder meetings/ is het meenemen waard als je vergaderingen bewaart.

Een momentopname van de hele installatie buiten de app plannen

De ingebouwde pipeline maakt maar van één werkruimte een back-up. Voor een onbeheerde momentopname van de hele installatie is er geen CLI-subcommando, en de snapshot-RPC vereist een gekoppelde volledige client die de eigenaar van de installatie is. Een timer op de host kan VACUUM INTO gebruiken op de live databases:

#!/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

Voer het uit als dezelfde gebruiker die eigenaar is van de gegevensmap, vanuit cron of een systemd-timer, en synchroniseer DEST daarna van de host af. VACUUM INTO vereist SQLite 3.27 of nieuwer.

Schrijf het buiten <dataDir>/backups/. Een zelfgemaakte map daar heeft geen manifest.json, dus de app zou hem als een onvolledige momentopname weergeven en de lijst zou ophouden een eerlijk overzicht te zijn van wat de server zelf heeft gemaakt.

Oude momentopnamen van de hele installatie opruimen

Je kunt afzonderlijke momentopnamen van de installatie in de app verwijderen. Houd voor een bewaarbeleid op de host de map met werkruimteback-ups gescheiden van de momentopnamen van de installatie:

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

Controleer de uitvoer van een run met -print voordat je -exec toevoegt. Bewaar er meer dan één: het falen waartegen je je beschermt, is vaak “de laatste back-up heeft ook het probleem”.

Controleren of een back-up goed is

Een back-up die niemand heeft hersteld, is een hypothese.

Goedkope controle — het bestand opent en de pagina’s zijn intact:

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

Echte controle — neem hem over. Maak een wegwerpwerkruimte aan op een niet-productie-installatie, importeer een werkruimtebestand erin en kijk of de ruimtes, tickets en berichten die je verwacht er zijn. Dat doorloopt hetzelfde pad als een echte herstelactie, inclusief de FTS-herbouw, en het is de enige controle die je vertelt dat de back-up te herstellen is en niet alleen leesbaar.

Doe dit één keer wanneer je back-ups opzet, en opnieuw telkens wanneer je wijzigt waar ze worden bewaard.

Problemen oplossen

Symptoom	Oorzaak en oplossing
Download- en uploadknoppen zijn uitgeschakeld met een melding over een relay	Je bent verbonden via de relay, die geen bestandsoverdrachten vervoert. Verbind rechtstreeks
“De server weigerde”	Rol. Een momentopname van de installatie maken of opvragen vereist de beheerder van de installatie. Een werkruimte downloaden vereist beheerder, er een herstellen vereist eigenaar, een zip van een hele momentopname vereist de beheerder van de installatie
“Deze server heeft geen back-upoppervlak”	Op de host is geen back-uppoort aangesloten — een demoserver. De handelingen ontbreken in plaats van dat ze worden geweigerd
“Het bestand is groter dan de server accepteert”	Uploads zijn beperkt tot 8 GiB. Zet het bestand op de serverhost en gebruik in plaats daarvan Importeren → Bestand kiezen
Import geweigerd: geen werkruimtedatabase van Control Center	Het bestand heeft geen rij `workspace_meta` — het is geen werkruimte-export, of het is afgekapt. Er is niets vervangen
Een momentopname staat als Onvolledig in de lijst	Het manifest ontbreekt of noemt bestanden die er niet zijn. Maak een nieuwe; neem ondertussen afzonderlijke werkruimtebestanden eruit over
Een momentopname meldt dat werkruimtes niet zijn vastgelegd	Die werkruimtes zijn nooit beschreven, of hun kopie is mislukt. Kijk in het serverlog
Een herstelde installatie heeft geen forge- of SSO-inloggegevens	`secrets.json` zit niet in een momentopname. Herstel het vanaf de plek waar je het hebt bewaard, of verbind de aanbieders opnieuw
Een herstelde werkruimte mist geplakte afbeeldingen	Blobs staan naast de database, niet erin. Kopieer `<workspaceId>/blobs/` ook mee

Gerelateerde handleidingen

Een headless server draaien: waar de gegevensmap vandaan komt
Verbinden met een externe server: rechtstreekse verbindingen versus verbindingen via een relay
Een apparaat koppelen: het inloggegeven waarmee de overdrachtsroutes ondertekenen

Gerelateerde concepten en referentie

Backup, export en import: elke handeling, route, veld en limiet
Werkruimtes en isolatie: waarom één werkruimte één bestand is
cc_server CLI: de indeling van de gegevensmap