Sichern und wiederherstellen

Diese Anleitung deckt die fünf Dinge ab, die du mit Sicherungen tatsächlich tust: eine erstellen, sie abholen, einen Arbeitsbereich verschieben, einen zurückspielen und Kopien außerhalb des Rechners halten. Die genaue Form jedes Artefakts und jeder Operation steht in der Referenz zu Backup, Export und Import.

Alles hier liegt unter Einstellungen → Server → Sicherung und Wiederherstellung.

Voraussetzungen

Ein vollständiger Client, also die Desktop- oder Web-App. Ein gekoppeltes Telefon löst davon nichts aus. Das ist so gewollt.
Eine Momentaufnahme der Installation erstellen, auflisten, herunterladen oder löschen darf der Eigentümer der Installation.
Bei Aktionen an einem Arbeitsbereich: Admin dieses Arbeitsbereichs für den Export, Eigentümer für Import oder Löschen.
Zum Herunterladen und Hochladen: eine direkte Verbindung zum Server. Das vermittelte Relay trägt RPC-Frames, keine Dateiübertragungen, und die Steuerelemente für den Transfer schalten sich mit einem Hinweis ab, wenn du über eines verbunden bist.

Was eine Sicherung umfasst

Beide Artefakte sind nur Datenbanken:

Eine Momentaufnahme der Installation ist ein Verzeichnis mit Zeitstempel: manifest.json, global.db und pro Arbeitsbereich eine <workspaceId>/workspace.db.
Ein Arbeitsbereichs-Export ist genau diese eine Datei workspace.db.

Den Rest des Datenverzeichnisses tragen beide nicht: secrets.json (Kopplungsschlüssel, Anbieter-Zugangsdaten, SSO), die blobs/ eines Arbeitsbereichs (Bilder, die in Nachrichten eingefügt wurden), skills/, agents/, chat_credentials/, aufgezeichnetes Audio von Besprechungen oder Rig-Images. Einiges davon ist entbehrlich, anderes nicht. Die vollständige Tabelle steht in der Referenz, und genau das deckt der Abschnitt außerhalb des Rechners ab.

Eine Momentaufnahme der ganzen Installation erstellen

Öffne Einstellungen → Server → Sicherung und Wiederherstellung.
Unter Momentaufnahmen der Installation drücke Jetzt sichern.
Die Meldung nennt das Verzeichnis, das auf dem Server-Host geschrieben wurde. Die neue Momentaufnahme steht oben in der Liste.

Der Server läuft dabei weiter. Jede Datei wird mit VACUUM INTO geschrieben, konsistent gegen eine laufende Datenbank. Es gibt kein Wartungsfenster, und du musst keine Agenten anhalten.

Jede Zeile zeigt den Zeitstempel, die Größe auf der Platte, wie viele Arbeitsbereiche erfasst wurden und ob die Momentaufnahme Vollständig oder Unvollständig ist. Unvollständig heißt: das Manifest fehlt oder nennt Dateien, die nicht da sind, weil ein Absturz oder eine volle Platte die Sicherung unterbrochen hat. Diese Zeilen bleiben absichtlich sichtbar. Eine Momentaufnahme, die du nicht siehst, ist eine, von der du glaubst, sie zu haben. Eine unvollständige Momentaufnahme kann die ganze Installation nicht wiederherstellen. Die Arbeitsbereichsdateien, die sie enthält, lassen sich weiterhin einzeln übernehmen.

Eine Zeile kann auch n Arbeitsbereiche nicht erfasst sagen. Das ist ein Arbeitsbereich, der registriert, aber noch nie beschrieben wurde (es gibt noch keine Datei), oder einer, dessen Kopie fehlgeschlagen ist. Sieh ins Server-Log.

Arbeitsbereichssicherungen und Aufbewahrung planen

Öffne Einstellungen → Pipelines → Pipeline-Vorlagen für den Arbeitsbereich und suche Workspace backup. Der aktivierte Zeitplan läuft jeden Sonntag um 03:00 UTC: Back up workspace, danach Delete backups older than (standardmäßig 30 Tage). Der zweite Schritt läuft nur, wenn die Sicherung gelungen ist. Die Aufbewahrungstage am Schritt kannst du ändern, oder du schaltest den Zeitplan ab. Ist der Server zur geplanten Zeit offline, holt der Zeitplan beim nächsten Start genau einen Lauf nach, statt jede verpasste Woche nachzuspielen.

Arbeitsbereichssicherungen liegen auf dem Server unter backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Der Aufbewahrungsschritt löscht nur alte Sicherungen dieses Arbeitsbereichs. Momentaufnahmen der Installation und Sicherungen anderer Arbeitsbereiche fasst er nicht an. Diese Dateien sind nur die Datenbank. Für die Aufbewahrung außerhalb des Rechners kopierst du sie selbst.

Diese Sicherungen stehen getrennt von der Liste Momentaufnahmen der Installation. Zum Wiederherstellen nimmst du Arbeitsbereichsdaten → Importieren und den serverseitigen Pfad der workspace.db. Der Import ersetzt die aktuelle Datenbank dieses Arbeitsbereichs. Exportiere sie vorher, wenn du die Wiederherstellung rückgängig machen können willst.

Eine Momentaufnahme der Installation löschen

Klappe unter Momentaufnahmen der Installation die Momentaufnahme auf, auch eine unvollständige, und nimm Momentaufnahme löschen im Gefahrenbereich. Bestätige den Namen. Das ganze Verzeichnis der Momentaufnahme wird dauerhaft vom Server entfernt. Lade es vorher herunter, wenn du eine Kopie brauchst. Eine Pipeline Workspace backup löscht diese Momentaufnahmen nie.

Eine Kopie auf den eigenen Rechner holen

Die Pfade auf der Seite liegen auf dem Rechner, auf dem cc_server läuft. Wenn das nicht der Rechner ist, an dem du sitzt, nimm die Schaltflächen Herunterladen:

Neben jedem Arbeitsbereich unter Arbeitsbereichsdaten → Herunterladen, für eine .db-Datei.
Neben jeder Momentaufnahme unter Momentaufnahmen der Installation → Herunterladen, für die ganze Momentaufnahme als .zip.

Auf dem Desktop wählst du, wo die Datei landet, und die Meldung nennt den Pfad. Im Web geht sie in die Downloads des Browsers. Beides meldet den Fortschritt in Bytes, weil das die beiden Nutzlasten sind, die in den Gigabyte-Bereich laufen.

Beide erzeugen im Moment des Klicks eine frische Kopie, streamen sie und löschen die Kopie auf dem Server danach. Ein Download holt nicht die Datei, die ein früherer Export angelegt hat.

Ein entpacktes Archiv der Momentaufnahme stellt ihr Layout genau wieder her. Deshalb ist das Wiederherstellen ein Zurückkopieren.

Einen Arbeitsbereich auf eine andere Installation verschieben

Ein Arbeitsbereich ist eine Datenbankdatei, die Übergabe also eine Dateioperation.

Auf dem Quellserver: Einstellungen → Server → Sicherung und Wiederherstellung → Arbeitsbereichsdaten, den Arbeitsbereich aufklappen und Herunterladen drücken.
Auf dem Zielserver den Arbeitsbereich anlegen oder auswählen, der die Datei aufnehmen soll.
Diesen Arbeitsbereich aufklappen und unter Von diesem Gerät wiederherstellen Datei auswählen und hochladen drücken. Wähle die heruntergeladene .db.

Sitzen beide Server auf dem Rechner, an dem du gerade bist, tun Auf dem Server speichern plus Importieren → Datei auswählen dasselbe ohne den Umweg. Die Pfade im Import-Dialog werden auf dem Server-Host aufgelöst.

Zwei Dinge werden erlaubt und protokolliert, nicht abgelehnt: eine Datei importieren, deren aufgezeichnete Arbeitsbereichs-ID vom Ziel abweicht (so duplizierst du einen Arbeitsbereich oder stellst ihn unter einer neuen ID wieder her), und eine Datei aus einer anderen Installation importieren. Im zweiten Fall gehören die gekoppelten Geräte und die Benutzer-IDs in der Datei zur Installation, von der sie stammt, und lösen sich hier nicht auf. Die eigenen Daten des Arbeitsbereichs sind intakt. Die Mitgliedschaft prüfst du nach dem Übernehmen.

Chatbot-Token liegen neben der Datenbank, nicht darin. Ein Arbeitsbereich, den du jemand anderem gibst, trägt keine lebenden Zugangsdaten. Die empfangende Installation verbindet ihre eigenen neu.

Einen Arbeitsbereich aus einer Momentaufnahme wiederherstellen

Klappe unter Momentaufnahmen der Installation die Momentaufnahme auf, die du willst.
Suche die Zeile des Arbeitsbereichs und drücke Wiederherstellen.
Bestätige. Alles, was dieser Arbeitsbereich seit der Momentaufnahme getan hat, ist weg.

Das ist dieselbe Operation wie ein Import, gerichtet auf die Kopie dieser Arbeitsbereichsdatei in der Momentaufnahme. Absichtlich, damit es keinen zweiten Mechanismus gibt, der dieselbe Datei anders behandeln könnte.

Eine Zeile kann Nicht mehr auf diesem Server sagen, mit deaktiviertem Wiederherstellen: die Momentaufnahme enthält einen Arbeitsbereich, den diese Installation nicht mehr hat. Hol ihn von Hand zurück. Lege einen Arbeitsbereich an und importiere unter Arbeitsbereichsdaten aus <snapshot path>/<old workspace id>/workspace.db. Die aufgeklappte Momentaufnahme zeigt ihren Pfad auf dem Server in einem Kopierfeld, und der Titel der Zeile ist die alte Arbeitsbereichs-ID. Beide Hälften des Pfads liegen damit vor dir.

Eine ganze Installation wiederherstellen

Dafür gibt es keine Schaltfläche, und das soll so bleiben: sie würde die Datenbanken ersetzen, die der laufende Server offen hält.

Halte cc_server an. Läuft die Desktop-App mit eingebettetem Server, beende die App.

Kopiere den Inhalt der Momentaufnahme über das Datenverzeichnis. Das Layout der Momentaufnahme spiegelt das laufende, es ist also ein schlichtes Kopieren:

# 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

Lösche alle -wal- und -shm-Dateien, die neben den ersetzten Datenbanken liegen. Sie gehören zu den alten Dateien, und eine veraltete Datei neben einer wiederhergestellten Datenbank ist ein Korruptionsrisiko.
Starte den Server wieder.

Die Momentaufnahme enthält kein secrets.json. Eine Installation, die du auf einen frischen Host zurückspielst, behält ihre Daten, nicht ihre Zugangsdaten: gekoppelte Geräte, Anbieter-Token und SSO-Einstellungen musst du neu einrichten oder aus der Datei wiederherstellen, die du dafür aufbewahrt hast. Spielst du auf denselben Host zurück, auf dem secrets.json nie verloren ging, bleibt alles erhalten.

Sicherungen vom Rechner kopieren

Eine Momentaufnahme auf derselben Platte wie die Datenbank, die sie kopiert hat, schützt dich vor einem schlechten Import, nicht vor der Platte. Control Center schickt von sich aus nirgends eine Kopie hin. Dieser Teil liegt bei dir.

Die Momentaufnahmen synchronisieren

Momentaufnahmen sind nach dem Schreiben unveränderlich und nach Zeitstempel benannt, deshalb kommt jedes Synchronisierungsprogramm gut mit ihnen klar. Lass transfer/ aus. Das ist die Werkbank für laufende Downloads und 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 dein lokales Ausdünnen auf die Gegenseite. Lass es weg, wenn die Gegenseite Momentaufnahmen länger behalten soll als der Host.

Was eine Momentaufnahme auslässt, mitnehmen

Um die Installation neu aufbauen zu können, und nicht nur ihre Daten, kopiere auch diese Dateien. Es sind gewöhnliche Dateien, die du kopieren kannst, während der Server läuft:

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 ist 0600 und enthält jeden Kopplungsschlüssel, alle Anbieter-Zugangsdaten und alle SSO-Einstellungen der Installation. Wo die Datei landet, muss mindestens so geschützt sein wie der Server-Host: im Ruhezustand verschlüsselt, und kein Bucket, den jemand anderes lesen kann.

Lass spaces/ aus (Copy-on-Write-Worktrees, die aus deinen Repos neu bereitgestellt werden), pr_clones/ (ein Cache), models/ (werden neu heruntergeladen), media_cache/ und rigs/ (Maschinenzustand, und groß). Aufgezeichnetes Audio von Besprechungen unter meetings/ lohnt sich, wenn du Besprechungen behältst.

Eine Momentaufnahme der ganzen Installation außerhalb der App planen

Die eingebaute Pipeline sichert nur einen Arbeitsbereich. Für eine unbeaufsichtigte Momentaufnahme der ganzen Installation gibt es kein CLI-Unterkommando, und der RPC für Momentaufnahmen verlangt einen gekoppelten vollständigen Client, der Eigentümer der Installation ist. Ein Timer auf dem Host kann VACUUM INTO gegen die laufenden Datenbanken verwenden:

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

Führe das als denselben Benutzer aus, dem das Datenverzeichnis gehört, aus cron oder einem systemd-Timer, und synchronisiere DEST danach vom Host weg. VACUUM INTO braucht SQLite 3.27 oder neuer.

Schreibe das außerhalb von <dataDir>/backups/. Ein von Hand angelegtes Verzeichnis dort hat kein manifest.json. Die App würde es als unvollständige Momentaufnahme listen, und die Liste wäre kein ehrliches Protokoll mehr dessen, was der Server selbst erzeugt hat.

Alte Momentaufnahmen der ganzen Installation ausdünnen

Einzelne Momentaufnahmen der Installation kannst du in der App löschen. Für eine Aufbewahrung auf dem Host halte das Verzeichnis der Arbeitsbereichssicherungen von den Momentaufnahmen der Installation getrennt:

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

Prüfe die Ausgabe eines Laufs mit -print, bevor du -exec ergänzt. Behalte mehr als eine: der Fehler, gegen den du dich absicherst, steckt oft schon in der letzten Sicherung.

Prüfen, ob eine Sicherung brauchbar ist

Eine Sicherung, die niemand wiederhergestellt hat, ist eine Hypothese.

Wenig Aufwand: die Datei öffnet sich, und ihre Seiten sind intakt:

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

Die echte Prüfung: übernimm sie. Lege auf einer Installation, die nicht produktiv ist, einen Wegwerf-Arbeitsbereich an, importiere eine Arbeitsbereichsdatei hinein und sieh nach, ob die Bereiche, Tickets und Nachrichten da sind, die du erwartest. Das geht denselben Weg wie eine echte Wiederherstellung, einschließlich des FTS-Neuaufbaus, und es ist die einzige Prüfung, die dir sagt, dass die Sicherung wiederherstellbar ist und nicht nur lesbar.

Mach das einmal, wenn du Sicherungen einrichtest, und wieder, sobald du änderst, wo sie liegen.

Fehlersuche

Anzeichen	Ursache und Abhilfe
Herunterladen und Hochladen sind deaktiviert, mit einem Hinweis auf ein Relay	Du bist über das vermittelte Relay verbunden, das keine Dateien überträgt. Verbinde dich direkt
„Der Server hat abgelehnt“	Rolle. Eine Momentaufnahme der Installation zu erstellen oder aufzulisten braucht den Betreiber der Installation. Einen Arbeitsbereich herunterzuladen braucht Admin, ihn wiederherzustellen Eigentümer, ein Zip der ganzen Momentaufnahme den Betreiber der Installation
„Dieser Server bietet keine Sicherungsschnittstelle“	Auf dem Host ist kein Backup-Port verdrahtet, ein Demo-Server. Die Operationen fehlen, sie werden nicht abgelehnt
„Die Datei ist größer, als der Server annimmt“	Uploads sind auf 8 GiB begrenzt. Lege die Datei auf den Server-Host und nimm Importieren → Datei auswählen
Import abgelehnt: keine Arbeitsbereichsdatenbank von Control Center	Die Datei hat keine Zeile `workspace_meta`. Sie ist kein Arbeitsbereichs-Export, oder sie ist abgeschnitten. Nichts wurde ersetzt
Eine Momentaufnahme steht als Unvollständig in der Liste	Das Manifest fehlt oder nennt Dateien, die nicht da sind. Erstelle eine neue und übernimm in der Zwischenzeit einzelne Arbeitsbereichsdateien daraus
Eine Momentaufnahme meldet, Arbeitsbereiche seien nicht erfasst worden	Diese Arbeitsbereiche wurden noch nie beschrieben, oder ihre Kopie ist fehlgeschlagen. Sieh ins Server-Log
Eine wiederhergestellte Installation hat keine Forge- oder SSO-Zugangsdaten	`secrets.json` liegt nicht in einer Momentaufnahme. Stelle sie von dort wieder her, wo du sie aufbewahrt hast, oder verbinde die Anbieter neu
Einem wiederhergestellten Arbeitsbereich fehlen eingefügte Bilder	Blobs liegen neben der Datenbank, nicht darin. Kopiere `<workspaceId>/blobs/` mit