Kopia zapasowa i przywracanie

Ten poradnik obejmuje pięć rzeczy, które faktycznie robi się z kopiami zapasowymi: wykonanie kopii, zgromadzenie jej, przeniesienie obszaru roboczego, przywrócenie kopii oraz trzymanie kopii poza maszyną. Dokładny kształt każdego artefaktu i każdej operacji opisuje dokumentacja referencyjna kopii zapasowej.

Wszystko, co tu opisano, znajduje się w Ustawienia → Serwer → Kopia zapasowa i przywracanie.

Wymagania wstępne

Pełny klient — aplikacja desktopowa lub webowa. Sparowany telefon celowo nie może wywołać żadnej z tych operacji.
Aby wykonać, wyświetlić, pobrać lub usunąć migawkę instalacji: rola właściciela instalacji.
W przypadku działań w obrębie poszczególnych obszarów roboczych: administrator tego obszaru roboczego może eksportować, a właściciel — importować go lub usuwać.
Do pobierania i wysyłania: bezpośrednie połączenie z serwerem. Relay pośredniczący przenosi ramki RPC, a nie transfery plików, więc elementy sterujące transferem wyłączają się z odpowiednią adnotacją, gdy przez niego przechodzisz.

Co obejmuje kopia zapasowa

Oba artefakty to wyłącznie bazy danych:

Migawka instalacji to katalog ze znacznikiem czasu: manifest.json, global.db oraz po jednym pliku <workspaceId>/workspace.db na każdy obszar roboczy.
Eksport obszaru roboczego to właśnie ten pojedynczy plik workspace.db.

Żaden z nich nie przenosi reszty katalogu danych: secrets.json (klucze parowania, poświadczenia dostawców, SSO), katalogu blobs/ obszaru roboczego (obrazy wklejane do wiadomości), skills/, agents/, chat_credentials/, nagranego dźwięku ze spotkań ani obrazów rigów. Część z tego jest zbędna, a część nie — pełna tabela znajduje się w dokumentacji referencyjnej, a objęcie tych danych kopią to zadanie sekcji o kopiach poza maszyną.

Wykonanie migawki całej instalacji

Otwórz Ustawienia → Serwer → Kopia zapasowa i przywracanie.
W sekcji Migawki instalacji naciśnij Wykonaj kopię teraz.
Toast podaje nazwę katalogu, który został zapisany, na hoście serwera. Nowa migawka pojawia się na górze listy.

Serwer działa przez cały czas. Każdy plik jest zapisywany przez VACUUM INTO, co daje spójny obraz działającej bazy danych, więc nie ma okna konserwacyjnego ani potrzeby zatrzymywania agentów.

Każdy wiersz listy pokazuje znacznik czasu, rozmiar na dysku, liczbę przechwyconych obszarów roboczych oraz to, czy migawka jest Kompletna, czy Niekompletna. Niekompletna oznacza, że brakuje manifestu albo wymienia on pliki, których nie ma — kopia przerwana przez awarię lub zapełnienie dysku. Takie migawki są celowo nadal na liście: migawka, której nie widzisz, jest migawką, o której myślisz, że ją masz. Niekompletna migawka nie przywróci całej instalacji, ale zawarte w niej pliki obszarów roboczych można wciąż adoptować pojedynczo.

Wiersz może też zawierać informację Nie uwzględniono n obszarów roboczych. To obszar roboczy zarejestrowany, ale nigdy niezapisany (nie ma jeszcze pliku) albo taki, którego kopiowanie się nie powiodło — sprawdź dziennik serwera.

Planowanie kopii zapasowych obszarów roboczych i retencji

Otwórz Ustawienia → Potoki → Szablony potoków dla danego obszaru roboczego i znajdź Workspace backup. Jego włączony harmonogram działa w każdą niedzielę o 03:00 UTC: Back up workspace, a po nim Delete backups older than (domyślnie 30 dni). Drugi węzeł uruchamia się dopiero po udanej kopii. Liczbę dni retencji możesz zmienić w węźle albo wyłączyć harmonogram. Jeśli serwer jest w zaplanowanym czasie wyłączony, harmonogram nadrobi zaległość raz po powrocie, zamiast odtwarzać każdy pominięty tydzień.

Kopie obszarów roboczych leżą na serwerze pod backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Węzeł retencji usuwa tylko stare kopie tego obszaru roboczego; nigdy nie usuwa migawek instalacji ani kopii innych obszarów roboczych. Te pliki zawierają wyłącznie bazy danych. Aby przechowywać je poza maszyną, kopiuj je niezależnie.

Te kopie są odrębne od listy Migawki instalacji. Aby przywrócić jedną z nich, użyj Dane obszaru roboczego → Importuj, podając ścieżkę workspace.db kopii po stronie serwera. Import zastępuje bieżącą bazę danych tego obszaru roboczego, więc najpierw go wyeksportuj, jeśli przywrócenie może wymagać cofnięcia.

Usuwanie migawki instalacji

W sekcji Migawki instalacji rozwiń migawkę, także niekompletną, i użyj pozycji Usuń migawkę w strefie niebezpieczeństwa. Potwierdź jej nazwę. Cały katalog migawki zostaje trwale usunięty z serwera; jeśli potrzebujesz kopii, najpierw ją pobierz. Potok kopii obszaru roboczego nigdy nie usuwa tych migawek.

Zgromadzenie kopii na własnej maszynie

Ścieżki pokazywane na tej stronie znajdują się na maszynie, na której działa cc_server. Jeśli to nie ta maszyna, przy której siedzisz, skorzystaj z przycisków Pobierz:

Przy każdym obszarze roboczym w sekcji Dane obszaru roboczego → Pobierz, dla jednego pliku .db.
Przy każdej migawce w sekcji Migawki instalacji → Pobierz, dla całej migawki jako pliku .zip.

W aplikacji desktopowej wybierasz miejsce zapisu pliku, a toast podaje jego nazwę; w wersji webowej plik trafia do pobranych w przeglądarce. W obu przypadkach postęp jest raportowany w bajtach, bo to dwa ładunki, które dochodzą do gigabajtów.

Oba tworzą świeżą kopię w momencie naciśnięcia przycisku, przesyłają ją strumieniowo, a następnie usuwają kopię po stronie serwera — pobieranie nie polega na „pobraniu pliku utworzonego wcześniej przez przycisk eksportu”.

Rozpakowanie archiwum migawki odtwarza dokładnie układ migawki, dzięki czemu przywrócenie jej to zwykłe skopiowanie z powrotem.

Przenoszenie obszaru roboczego do innej instalacji

Jeden obszar roboczy to jeden plik bazy danych, więc przekazanie go jest operacją na pliku.

Na serwerze źródłowym otwórz Ustawienia → Serwer → Kopia zapasowa i przywracanie → Dane obszaru roboczego, rozwiń obszar roboczy i naciśnij Pobierz.
Na serwerze docelowym utwórz (lub wybierz) obszar roboczy, który go przejmie.
Rozwiń ten obszar roboczy i w sekcji Przywróć z tego urządzenia naciśnij Wybierz plik i wyślij. Wskaż pobrany plik .db.

Jeśli oba serwery to ta sama maszyna, przy której siedzisz, Zapisz na serwerze plus Importuj → Wybierz plik daje ten sam efekt bez dodatkowego obiegu; ścieżki w oknie importu są rozwiązywane na hoście serwera.

Dwie rzeczy są dozwolone i rejestrowane w dzienniku, a nie odrzucane: import pliku, którego zapisany identyfikator obszaru roboczego różni się od docelowego (tak duplikujesz obszar roboczy albo przywracasz go pod nowym identyfikatorem) oraz import pliku z innej instalacji. W tym drugim przypadku sparowane urządzenia i identyfikatory użytkowników z pliku należą do instalacji, z której pochodzi, i nie zostaną rozwiązane w tej instalacji — dane samego obszaru roboczego są nienaruszone, ale po jego adopcji ponownie sprawdź członkostwo.

Tokeny botów czatu leżą obok bazy danych, a nie w niej, więc obszar roboczy przekazany komuś innemu nie zawiera aktywnych poświadczeń. Przyjmująca instalacja podłącza własne.

Przywracanie jednego obszaru roboczego z migawki

W sekcji Migawki instalacji rozwiń wybraną migawkę.
Znajdź wiersz tego obszaru roboczego i naciśnij Przywróć.
Potwierdź. Wszystko, co ten obszar roboczy zrobił od wykonania migawki, przepada.

To ta sama operacja co import, wskazująca na kopię pliku tego obszaru roboczego w migawce — celowo, aby nie istniał drugi mechanizm, który mógłby potraktować ten sam plik inaczej.

Wiersz może mówić Nie ma go już na tym serwerze, a pozycja Przywróć jest wyłączona: migawka zawiera obszar roboczy, którego ta instalacja już nie ma. Przywróć go ręcznie — utwórz obszar roboczy, a następnie w sekcji Dane obszaru roboczego zaimportuj do niego plik ze ścieżki <snapshot path>/<old workspace id>/workspace.db. Rozwinięta migawka pokazuje własną Ścieżkę na serwerze w polu do skopiowania, a tytuł wiersza to stary identyfikator obszaru roboczego, więc masz przed sobą obie połówki tej ścieżki.

Przywracanie całej instalacji

Nie ma do tego przycisku i nie powinno go być: zastępuje ono bazy danych, które działający serwer trzyma otwarte.

Zatrzymaj cc_server. Jeśli używasz aplikacji desktopowej z wbudowanym serwerem, zamknij aplikację.

Skopiuj zawartość migawki do katalogu danych. Układ migawki odzwierciedla układ działającej instalacji, więc to zwykłe kopiowanie:

# 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

Usuń wszelkie pliki -wal i -shm leżące obok zastąpionych baz danych. Należą do starych plików, a nieaktualny plik obok przywróconej bazy danych grozi uszkodzeniem.
Uruchom serwer ponownie.

Migawka nie zawiera secrets.json, więc instalacja przywrócona na nowym hoście zachowuje swoje dane, ale nie poświadczenia: sparowane urządzenia, tokeny dostawców i ustawienia SSO trzeba odtworzyć albo przywrócić z miejsca, w którym przechowujesz ten plik. Przywrócenie na ten sam host, na którym secrets.json nigdy nie zginął, zachowuje wszystko.

Kopiowanie kopii zapasowych poza maszynę

Migawka na tym samym dysku co skopiowana baza danych chroni przed nieudanym importem, a nie przed awarią dysku. Nic w Control Center nie wysyła kopii w żadne miejsce, więc ta część należy do ciebie.

Synchronizacja migawek

Migawki są niezmienne po zapisaniu i nazwane znacznikiem czasu, więc każde narzędzie synchronizujące radzi sobie z nimi dobrze. Wyklucz transfer/, który jest warsztatem dla trwających pobierań i wysyłek:

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 odzwierciedla lokalne czyszczenie na zdalnym celu. Usuń go, jeśli chcesz, aby zdalny cel przechowywał migawki dłużej niż host.

Uwzględnianie tego, co pomija migawka

Aby móc odtworzyć instalację, a nie tylko jej dane, skopiuj także te elementy. To zwykłe pliki, które można bezpiecznie kopiować, gdy serwer działa:

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/

Plik secrets.json ma uprawnienia 0600 i zawiera każdy klucz parowania, poświadczenie dostawcy i ustawienie SSO w instalacji. Miejsce, w którym wyląduje, musi być chronione co najmniej tak dobrze jak host serwera — szyfrowane w spoczynku i nie może to być zasobnik, który ktokolwiek inny może odczytać.

Pomiń spaces/ (drzewa robocze copy-on-write, odtwarzane z twoich repozytoriów), pr_clones/ (pamięć podręczna), models/ (pobierane ponownie), media_cache/ oraz rigs/ (stan maszyny i duże rozmiary). Nagrany dźwięk ze spotkań w meetings/ warto uwzględnić, jeśli prowadzisz spotkania.

Planowanie migawki całej instalacji poza aplikacją

Wbudowany potok wykonuje kopię tylko jednego obszaru roboczego. Dla bezobsługowej migawki całej instalacji nie ma podpolecenia CLI, a RPC migawki wymaga sparowanego pełnego klienta będącego właścicielem instalacji. Timer po stronie hosta może użyć VACUUM INTO względem działających baz danych:

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

Uruchamiaj go jako ten sam użytkownik, który jest właścicielem katalogu danych, z cron lub timera systemd, a po zakończeniu zsynchronizuj DEST poza host. VACUUM INTO wymaga SQLite 3.27 lub nowszego.

Zapisuj go poza <dataDir>/backups/. Wykonany ręcznie katalog w tym miejscu nie ma manifest.json, więc aplikacja wymieniłaby go jako niekompletną migawkę, a lista przestałaby być rzetelnym zapisem tego, co wyprodukował sam serwer.

Usuwanie starych migawek całej instalacji

Pojedyncze migawki instalacji możesz usuwać w aplikacji. Aby prowadzić politykę retencji po stronie hosta, trzymaj katalog kopii obszarów roboczych osobno od migawek instalacji:

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

Zanim dodasz -exec, sprawdź wynik uruchomienia z -print. Trzymaj więcej niż jedną kopię: awaria, przed którą się chronisz, to często „ostatnia kopia też ma ten problem”.

Sprawdzanie, czy kopia zapasowa jest dobra

Kopia zapasowa, której nikt nie przywrócił, to hipoteza.

Tania kontrola — plik się otwiera, a jego strony są nienaruszone:

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

Prawdziwa kontrola — zaadoptuj ją. Utwórz tymczasowy obszar roboczy na instalacji nieprodukcyjnej, zaimportuj do niego plik obszaru roboczego i sprawdź, czy są w nim przestrzenie, zgłoszenia i wiadomości, których oczekujesz. To przechodzi tę samą ścieżkę co prawdziwe przywracanie, wraz z odbudową FTS, i to jedyna kontrola, która mówi, że kopię da się przywrócić, a nie tylko odczytać.

Zrób to raz przy konfigurowaniu kopii zapasowych i ponownie za każdym razem, gdy zmienisz miejsce ich przechowywania.

Rozwiązywanie problemów

Objaw	Przyczyna i rozwiązanie
Elementy sterujące pobieraniem i wysyłaniem są wyłączone, z adnotacją o relay	Połączenie przechodzi przez relay pośredniczący, który nie przenosi transferów plików. Połącz się bezpośrednio
„Serwer odmówił”	Rola. Wykonanie lub wyświetlenie migawki instalacji wymaga operatora instalacji. Pobranie obszaru roboczego wymaga roli administratora, przywrócenie go — roli właściciela, a archiwum całej migawki — operatora instalacji
„Ten serwer nie ma powierzchni kopii zapasowych”	Na hoście nie podłączono portu kopii zapasowych — to serwer demonstracyjny. Operacje są nieobecne, a nie odrzucane
„Plik jest większy, niż serwer akceptuje”	Wysyłanie jest ograniczone do 8 GiB. Umieść plik na hoście serwera i użyj zamiast tego Importuj → Wybierz plik
Import odrzucony: to nie jest baza danych obszaru roboczego Control Center	Plik nie ma wiersza `workspace_meta` — to nie eksport obszaru roboczego albo jest obcięty. Nic nie zostało zastąpione
Migawka jest oznaczona jako Niekompletna	Brakuje jej manifestu albo wymienia nieistniejące pliki. Wykonaj nową; w międzyczasie adoptuj z niej pojedyncze pliki obszarów roboczych
Migawka informuje, że nie uwzględniono obszarów roboczych	Te obszary robocze nigdy nie były zapisywane albo ich kopiowanie się nie powiodło. Sprawdź dziennik serwera
Przywrócona instalacja nie ma poświadczeń hosta kodu ani SSO	`secrets.json` nie wchodzi w skład migawki. Przywróć go z miejsca, w którym go przechowujesz, albo podłącz dostawców ponownie
W przywróconym obszarze roboczym brakuje wklejonych obrazów	Bloby leżą obok bazy danych, a nie w niej. Skopiuj także `<workspaceId>/blobs/`

Powiązane poradniki

Uruchom serwer headless: skąd pochodzi katalog danych
Połącz się ze zdalnym serwerem: połączenia bezpośrednie a połączenia przez relay
Sparuj urządzenie: poświadczenie, którym podpisują się trasy transferu

Powiązane koncepcje i dokumentacja referencyjna

Kopia zapasowa, eksport i import: każda operacja, trasa, pole i limit
Obszary robocze i izolacja: dlaczego jeden obszar roboczy to jeden plik
cc_server CLI: układ katalogu danych