Záloha a obnovení

Zálohy se v praxi používají na pět věcí: pořídit snímek, stáhnout ho, přesunout pracovní prostor, vrátit jeden zpátky a držet kopie mimo stroj. Přesný tvar každého artefaktu a každé operace je v referenci zálohy.

Všechno odsud je v Nastavení → Server → Záloha a obnovení.

Předpoklady

• Plný klient, tedy desktopová nebo webová aplikace. Spárovaný telefon z toho schválně nespustí nic.
• Pořídit, vypsat, stáhnout nebo smazat snímek instalace smí vlastník instalace.
• U akcí jednoho pracovního prostoru: admin toho prostoru pro export, vlastník pro import nebo smazání.
• Stahování a nahrávání chce přímé spojení se serverem. Zprostředkované relé vozí rámce RPC, ne přenos souborů, a ovládací prvky přenosu se samy vypnou a ukážou poznámku, když jsi na něm.

Snímky instalace jsou ruční

Zálohovat teď pořád vytvoří snímek celé instalace jen na vyžádání. Vestavěná pipeline Workspace backup místo toho umí jednou týdně vzít zálohu databáze pracovního prostoru a smazat zálohy toho prostoru starší než 30 dní. Nekopíruje global.db, ostatní pracovní prostory ani soubory vedle databáze. Kopie mimo stroj si drž zvlášť.

Co záloha pokrývá

Oba artefakty jsou jen databáze:

• Snímek instalace je adresář s časovým razítkem: manifest.json, global.db a jeden <workspaceId>/workspace.db na pracovní prostor.
• Export pracovního prostoru je ten jeden soubor workspace.db.

Ani jeden nenese zbytek datového adresáře: secrets.json (klíče párování, přihlašovací údaje poskytovatelů, SSO), blobs/ pracovního prostoru (obrázky vložené do zpráv), skills/, agents/, chat_credentials/, nahraný zvuk schůzek ani obrazy stanic. Část se dá zahodit a část ne. Celá tabulka je v referenci a právě tohle má pokrýt sekce mimo stroj.

Pořiď snímek celé instalace

1. Otevři Nastavení → Server → Záloha a obnovení.
2. Pod Snímky instalace stiskni Zálohovat teď.
3. Toast pojmenuje adresář, který se zapsal, na hostiteli serveru. Nový snímek se objeví nahoře v seznamu.

Server běží po celou dobu. Každý soubor se zapisuje přes VACUUM INTO, což je konzistentní vůči živé databázi, takže okno údržby není a agenty zastavovat nemusíš.

Každý řádek seznamu ukazuje časové razítko, velikost na disku, kolik pracovních prostorů se zachytilo a jestli je snímek Úplný, nebo Neúplný. Neúplný znamená, že manifest chybí nebo jmenuje soubory, které tam nejsou: záloha přerušená pádem nebo plným diskem. V seznamu zůstávají schválně. Snímek, který nevidíš, pokládáš za snímek, který máš. Neúplný snímek celou instalaci neobnoví, ale soubory pracovních prostorů, které v něm jsou, se pořád dají převzít po jednom.

Řádek taky může hlásit n pracovních prostorů nezachyceno. To je pracovní prostor zaregistrovaný, ale ještě nezapsaný (soubor zatím není), nebo takový, jehož kopie selhala. Podívej se do logu serveru.

Naplánuj zálohy pracovního prostoru a uchování

Otevři Nastavení → Pracovní prostor → Šablony pipeline daného pracovního prostoru a najdi Workspace backup. Zapnutý plán běží každou neděli v 03:00 UTC: Back up workspace a po něm Delete backups older than (výchozí 30 dní). Druhý uzel běží až po úspěšné záloze. Počet dní uchování na uzlu změníš, nebo plán vypneš. Když je server v naplánovaný čas offline, plán po návratu dožene jeden běh a neopakuje každý zmeškaný týden.

Zálohy pracovního prostoru leží na serveru v backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Uzel uchování maže jen staré zálohy tohoto pracovního prostoru. Snímky instalace ani zálohy jiných prostorů nemaže. Jsou to jen databáze. Pro uchování mimo stroj je zkopíruj zvlášť.

Tyhle zálohy jsou oddělené od seznamu Snímky instalace. Obnovíš je přes Data pracovního prostoru → Importovat s cestou k workspace.db na serveru. Import nahradí aktuální databázi toho pracovního prostoru, takže ho nejdřív exportuj, když budeš chtít obnovení vrátit.

Smaž snímek instalace

Pod Snímky instalace rozbal snímek, i neúplný, a v nebezpečné části použij Smazat snímek. Potvrď jeho jméno. Celý adresář snímku se ze serveru trvale smaže. Nejdřív ho stáhni, když kopii potřebuješ. Pipeline zálohy pracovního prostoru tyhle snímky nemaže.

Stáhni kopii na vlastní stroj

Cesty na stránce jsou na stroji, kde běží cc_server. Když to není stroj, u kterého sedíš, použij tlačítka Stáhnout:

• Vedle každého pracovního prostoru pod Data pracovního prostoru → Stáhnout, jeden soubor .db.
• Vedle každého snímku pod Snímky instalace → Stáhnout, celý snímek jako .zip.

Na desktopu vybereš, kam soubor spadne, a toast ho pojmenuje. Na webu jde do stahování prohlížeče. V obou případech se průběh hlásí v bajtech, protože právě tyhle dva přenosy sahají do gigabajtů.

Obě tlačítka v okamžiku stisku vytvoří čerstvou kopii, přenesou ji proudem a kopii na serveru potom smažou. Stažení není „vyzvedni soubor, který dřív udělalo tlačítko exportu“.

Rozbalení archivu snímku zopakuje jeho rozložení přesně, a proto je obnovení zase jen kopie zpátky.

Přesuň pracovní prostor na jinou instalaci

Jeden pracovní prostor je jeden soubor databáze, takže předání je operace se souborem.

1. Na zdrojovém serveru v Nastavení → Server → Záloha a obnovení → Data pracovního prostoru rozbal pracovní prostor a stiskni Stáhnout.
2. Na cílovém serveru založ (nebo vyber) pracovní prostor, který ho přijme.
3. Ten pracovní prostor rozbal a pod Obnovit z tohoto zařízení stiskni Vybrat soubor a nahrát. Vyber stažený .db.

Když jsou oba servery ten stroj, u kterého sedíš, Uložit na server a Importovat → Vybrat soubor udělá totéž bez cesty tam a zpět. Cesty v dialogu importu se řeší na hostiteli serveru.

Import nahradí všechno

Import přepíše všechno, co cílový pracovní prostor právě drží, a nejde vrátit. Cíl nejdřív exportuj, když v něm je něco, co bys chtěl zpátky.

Dvě věci se povolí a zapíšou do logu, místo aby se odmítly: import souboru, jehož zaznamenané id pracovního prostoru se liší od cíle (tak pracovní prostor zduplikuješ nebo ho obnovíš pod novým id), a import souboru z jiné instalace. V tom druhém případě spárovaná zařízení a id uživatelů v souboru patří instalaci, odkud přišel, a na téhle se nevyřeší. Vlastní data pracovního prostoru jsou v pořádku, ale po převzetí znovu zkontroluj členství.

Tokeny chatbota leží vedle databáze, ne v ní, takže pracovní prostor, který někomu předáš, nenese živé přihlašovací údaje. Přijímající instalace si připojí svoje.

Obnov jeden pracovní prostor ze snímku

1. Pod Snímky instalace rozbal snímek, který chceš.
2. Najdi řádek pracovního prostoru a stiskni Obnovit.
3. Potvrď. Všechno, co ten pracovní prostor udělal od pořízení snímku, je pryč.

Je to stejná operace jako import, namířená na kopii souboru toho pracovního prostoru ve snímku. Schválně, aby neexistoval druhý mechanismus, který by se stejným souborem zacházel jinak.

Řádek může říct Na tomto serveru už není a Obnovit je vypnuté: snímek drží pracovní prostor, který tahle instalace už nemá. Vrať ho ručně. Založ pracovní prostor a pod Data pracovního prostoru do něj importuj z <snapshot path>/<old workspace id>/workspace.db. Rozbalený snímek ukazuje vlastní Cesta na serveru v poli ke kopírování a titulek řádku je staré id pracovního prostoru, takže máš obě poloviny té cesty před sebou.

Obnov celou instalaci

Tlačítko na to není a být nemá: nahrazuje to databáze, které má běžící server otevřené.

1. Zastav cc_server. Když desktopovou aplikaci pouštíš s vestavěným serverem, aplikaci ukonči.

2. Zkopíruj obsah snímku přes datový adresář. Rozložení snímku zrcadlí živé, takže je to obyčejná 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

3. Smaž soubory -wal a -shm ležící vedle databází, které jsi nahradil. Patří ke starým souborům a zastaralý soubor vedle obnovené databáze je riziko poškození.

4. Server znovu spusť.

Snímek secrets.json neobsahuje, takže instalace obnovená na čerstvý hostitel si drží data, ale ne přihlašovací údaje: spárovaná zařízení, tokeny poskytovatelů a nastavení SSO se musí znovu navázat, nebo obnovit odtud, kde ten soubor držíš. Obnova na stejný hostitel, kde se secrets.json neztratil, nechá všechno na místě.

Kopíruj zálohy mimo stroj

Snímek na stejném disku jako databáze, kterou zkopíroval, tě chrání před špatným importem, ne před diskem. Control Center nikam kopii sám neposílá, takže tahle část je na tobě.

Synchronizuj snímky

Snímky jsou po zapsání neměnné a pojmenované časovým razítkem, takže je zvládne kterýkoli synchronizační nástroj. Vynech transfer/, což je mezisklad probíhajícího stahování a nahrávání:

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 zrcadlí místní prořezávání na vzdálenou stranu. Vynech ho, když má vzdálená strana držet snímky déle než hostitel.

Živé databáze nikdy nesynchronizuj přímo

Nemiř rsync, aws s3 sync ani zálohovacího agenta na úrovni souborů na global.db nebo <workspaceId>/workspace.db, dokud server běží. Živá databáze SQLite má postranní soubor -wal a kopie soubor po souboru zachytí oba v jiný okamžik. Výsledek je soubor, který se často otevře a tiše mu chybí nedávné zápisy, nebo se neotevře vůbec. Kopíruj snímek, který se zapsal pod čtecí transakcí, nebo ho pořiď přes VACUUM INTO, jak je níž.

Přidej to, co snímek vynechá

Aby šla znovu postavit instalace, a ne jen její data, zkopíruj i tohle. Jsou to obyčejné soubory a kopírovat je za běhu serveru je bezpečné:

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 má práva 0600 a drží každý klíč párování, přihlašovací údaj poskytovatele a nastavení SSO na instalaci. Kam dopadne, musí být chráněné aspoň jako hostitel serveru: šifrované v klidu a ne bucket, do kterého vidí někdo jiný.

Přeskoč spaces/ (worktree copy-on-write, znovu se založí z repozitářů), pr_clones/ (cache), models/ (stáhnou se znovu), media_cache/ a rigs/ (stav stroje, a velké). Nahraný zvuk schůzek pod meetings/ se vyplatí zahrnout, když schůzky držíš.

Naplánuj snímek celé instalace mimo aplikaci

Vestavěná pipeline zálohuje jen jeden pracovní prostor. Pro bezobslužný snímek celé instalace není podpříkaz CLI a RPC snímku chce spárovaný plný klient, který je vlastník instalace. Časovač na hostiteli může proti živým databázím použít VACUUM INTO:

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

Spusť ho jako stejný uživatel, který vlastní datový adresář, z cronu nebo časovače systemd, a DEST potom synchronizuj mimo hostitele. VACUUM INTO potřebuje SQLite 3.27 nebo novější.

Piš ho mimo <dataDir>/backups/. Ručně udělaný adresář tam nemá manifest.json, takže by ho aplikace vypsala jako neúplný snímek a seznam by přestal být poctivý záznam toho, co vyrobil sám server.

Promaž staré snímky celé instalace

Jednotlivé snímky instalace smažeš v aplikaci. Pro politiku uchování na hostiteli drž adresář záloh pracovního prostoru odděleně od snímků instalace:

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

Nejdřív zkontroluj výstup běhu s -print, než přidáš -exec. Nech víc než jeden: selhání, proti kterému se chráníš, je často „poslední záloha má ten problém taky“.

Ověř, že záloha je v pořádku

Záloha, kterou nikdo neobnovil, je hypotéza.

Levná kontrola: soubor se otevře a jeho stránky jsou celé:

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

Skutečná kontrola: převezmi ji. Na neprodukční instalaci založ zkušební pracovní prostor, importuj do něj soubor pracovního prostoru a podívej se, jestli tam jsou prostory, tickety a zprávy, které čekáš. Tím projdeš stejnou cestou jako skutečné obnovení, včetně přestavění FTS, a je to jediná kontrola, která řekne, že záloha jde obnovit, a ne jen přečíst.

Udělej to jednou, když zálohy nastavuješ, a znovu pokaždé, když změníš, kde se ukládají.

Řešení problémů

Příznak	Příčina a oprava
Ovládací prvky stahování a nahrávání jsou vypnuté a je u nich poznámka o relé	Jsi připojený přes zprostředkované relé, které nepřenáší soubory. Připoj se přímo
„Server odmítl“	Role. Pořízení nebo výpis snímku instalace potřebuje operátora instalace. Stažení pracovního prostoru potřebuje admina, obnovení vlastníka a zip celého snímku operátora instalace
„Tento server nemá povrch záloh“	Hostitel nemá připojený port záloh. Je to demo server. Operace chybí, neodmítají se
„Soubor je větší, než server přijímá“	Nahrávání je omezené na 8 GiB. Dej soubor na hostitele serveru a použij Importovat → Vybrat soubor
Import odmítnut: není to databáze pracovního prostoru Control Center	Soubor nemá řádek workspace_meta. Není to export pracovního prostoru, nebo je useknutý. Nic se nenahradilo
Snímek je uvedený jako Neúplný	Manifest chybí, nebo jmenuje chybějící soubory. Pořiď nový a mezitím z něj převezmi jednotlivé soubory pracovních prostorů
Snímek hlásí, že se pracovní prostory nezachytily	Ty pracovní prostory se ještě nikdy nezapsaly, nebo jejich kopie selhala. Podívej se do logu serveru
Obnovená instalace nemá přihlašovací údaje forge ani SSO	secrets.json ve snímku není. Obnov ho odtud, kde ho držíš, nebo poskytovatele znovu připoj
Obnovenému pracovnímu prostoru chybí vložené obrázky	Bloby leží vedle databáze, ne v ní. Zkopíruj taky <workspaceId>/blobs/

Související návody

• Spusťte headless server: odkud se bere datový adresář
• Připojte se ke vzdálenému serveru: přímé spojení a spojení přes relé
• Spárujte zařízení: přihlašovací údaj, kterým se podepisují trasy přenosu

Související koncepty a reference

• Záloha, export a import: každá operace, trasa, pole a limit
• Pracovní prostory a izolace: proč je jeden pracovní prostor jeden soubor
• CLI cc_server: rozložení datového adresáře