Backup și restaurare

Acest ghid acoperă cele cinci lucruri pe care oamenii le fac de fapt cu backup-urile: să faci unul, să-l colectezi, să muți un spațiu de lucru, să-l pui la loc și să păstrezi copii în afara mașinii. Pentru forma exactă a fiecărui artefact și a fiecărei operațiuni, vezi referința pentru backup.

Tot ce este aici se află în Setări → Server → Backup și restaurare.

Cerințe preliminare

• Un client complet — aplicația desktop sau cea web. Un telefon asociat nu poate declanșa nimic din toate acestea, prin design.
• Pentru a face, lista, descărca sau șterge un snapshot de instalare: proprietarul instalării.
• Pentru acțiunile pe spațiu de lucru: admin al acelui spațiu de lucru pentru export, proprietar pentru import sau ștergere.
• Pentru descărcări și încărcări: o conexiune directă la server. Releul intermediat transportă cadre RPC, nu transferuri de fișiere, iar controalele de transfer se dezactivează cu o notă când ești pe una.

Snapshot-urile de instalare sunt manuale

Fă backup acum creează în continuare un snapshot al întregii instalări doar la cerere. Pipeline-ul integrat Workspace backup poate în schimb să facă o copie de rezervă a bazei de date a unui spațiu de lucru o dată pe săptămână și să elimine backup-urile acelui spațiu de lucru mai vechi de 30 de zile. Nu copiază global.db, alte spații de lucru sau fișierele de lângă baza de date. Păstrează copiile din afara mașinii separat.

Ce acoperă un backup

Ambele artefacte sunt doar baze de date:

• Un snapshot de instalare este un director cu marcă de timp: manifest.json, global.db și un <workspaceId>/workspace.db pentru fiecare spațiu de lucru.
• Un export de spațiu de lucru este acel singur fișier workspace.db.

Niciunul nu include restul directorului de date: secrets.json (chei de asociere, acreditări de provider, SSO), blobs/ al unui spațiu de lucru (imagini lipite în mesaje), skills/, agents/, chat_credentials/, audio-ul întâlnirilor înregistrate sau imaginile de rig. O parte din asta este de unică folosință, iar o parte nu — tabelul complet este în referință, iar acoperirea lui este scopul secțiunii despre copiile din afara mașinii.

Fă un snapshot al întregii instalări

1. Deschide Setări → Server → Backup și restaurare.
2. La Snapshot-uri de instalare, apasă Fă backup acum.
3. Notificarea indică directorul care a fost scris, pe hostul serverului. Noul snapshot apare în fruntea listei.

Serverul rulează în tot acest timp. Fiecare fișier este scris cu VACUUM INTO, care este consistent față de o bază de date activă, așa că nu există fereastră de mentenanță și nu e nevoie să oprești agenții.

Fiecare rând din listă arată marca de timp, dimensiunea pe disc, câte spații de lucru au fost capturate și dacă snapshot-ul este Complet sau Incomplet. Incomplet înseamnă că manifestul lipsește sau numește fișiere care nu sunt acolo — un backup întrerupt de o cădere sau de un disc plin. Acestea sunt totuși listate intenționat: un snapshot pe care nu îl vezi este unul despre care crezi că îl ai. Un snapshot incomplet nu poate restaura o instalare întreagă, dar fișierele de spațiu de lucru pe care le conține pot fi totuși adoptate unul câte unul.

Un rând poate spune de asemenea n spații de lucru necaptate. Acesta este un spațiu de lucru înregistrat, dar în care nu s-a scris niciodată (nu există încă un fișier), sau unul a cărui copiere a eșuat — verifică jurnalul serverului.

Programează backup-uri de spațiu de lucru și retenția

Deschide Setări → Pipeline-uri → Șabloane pipeline pentru spațiul de lucru și găsește Workspace backup. Programarea lui activată rulează în fiecare duminică la 03:00 UTC: Back up workspace, urmat de Delete backups older than (30 de zile implicit). Al doilea nod rulează doar după ce backup-ul reușește. Poți schimba zilele de retenție la nod sau dezactiva programarea. Dacă serverul este offline la ora programată, programarea se recuperează o dată când revine, în loc să reia fiecare săptămână ratată.

Backup-urile de spațiu de lucru se află pe server sub backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Nodul de retenție șterge doar backup-urile vechi pentru acest spațiu de lucru; nu șterge niciodată snapshot-uri de instalare sau backup-uri pentru alte spații de lucru. Aceste fișiere sunt doar baze de date. Pentru retenție în afara mașinii, copiază-le independent.

Aceste backup-uri sunt separate de lista Snapshot-uri de instalare. Pentru a restaura unul, folosește Date spațiu de lucru → Importă cu calea workspace.db a backup-ului de pe server. Importul înlocuiește baza de date actuală a acelui spațiu de lucru, așa că export-o mai întâi dacă s-ar putea să ai nevoie să anulezi restaurarea.

Șterge un snapshot de instalare

La Snapshot-uri de instalare, extinde snapshot-ul, inclusiv unul incomplet, și folosește Șterge snapshotul în secțiunea de pericol. Confirmă-i numele. Întregul director al snapshot-ului este eliminat definitiv de pe server; descarcă-l mai întâi dacă ai nevoie de o copie. Un pipeline de backup de spațiu de lucru nu șterge niciodată aceste snapshot-uri.

Colectează o copie pe propria mașină

Căile pe care le arată pagina sunt pe mașina care rulează cc_server. Când aceea nu este mașina la care stai, folosește butoanele Descarcă:

• Lângă fiecare spațiu de lucru de la Date spațiu de lucru → Descarcă, pentru un singur fișier .db.
• Lângă fiecare snapshot de la Snapshot-uri de instalare → Descarcă, pentru întregul snapshot ca .zip.

Pe desktop alegi unde ajunge fișierul, iar notificarea îl indică; pe web ajunge în descărcările browserului. În ambele cazuri, amândouă raportează progresul în octeți, pentru că acestea sunt cele două payload-uri care ajung la gigaocteți.

Ambele creează o copie proaspătă în momentul în care apeși butonul, o transmit în flux și șterg copia serverului după aceea — o descărcare nu este „adu fișierul pe care l-a făcut butonul de export mai devreme”.

Dezarhivarea unui snapshot reproduce exact structura snapshot-ului, ceea ce face ca restaurarea lui să fie o simplă copiere la loc.

Mută un spațiu de lucru într-o altă instalare

Un spațiu de lucru este un fișier de bază de date, așa că predarea lui este o operațiune pe fișiere.

1. Pe serverul sursă, Setări → Server → Backup și restaurare → Date spațiu de lucru, extinde spațiul de lucru și apasă Descarcă.
2. Pe serverul destinație, creează (sau alege) spațiul de lucru care îl va primi.
3. Extinde acel spațiu de lucru și, la Restaurează de pe acest dispozitiv, apasă Alege un fișier și încarcă. Alege .db-ul pe care l-ai descărcat.

Dacă ambele servere sunt aceeași mașină la care stai, Salvează pe server plus Importă → Alege fișier fac același lucru fără drumul dus-întors; căile din dialogul de import se rezolvă pe hostul serverului.

Importul înlocuiește tot

Importul suprascrie tot ce conține în prezent spațiul de lucru țintă și nu poate fi anulat. Exportă mai întâi ținta dacă conține ceva ce s-ar putea să vrei înapoi.

Două lucruri sunt permise și înregistrate în jurnal, în loc să fie refuzate: importul unui fișier al cărui id de spațiu de lucru înregistrat diferă de cel al țintei (așa duplici un spațiu de lucru sau îl restaurezi sub un id nou) și importul unui fișier dintr-o altă instalare. În al doilea caz, dispozitivele asociate și id-urile de utilizator ale fișierului aparțin instalării din care provine și nu se vor rezolva pe aceasta — datele proprii ale spațiului de lucru sunt intacte, dar reverifică apartenența după ce îl adopți.

Token-urile botului de chat stau lângă baza de date, nu în ea, așa că un spațiu de lucru pe care îl predai altcuiva nu conține acreditări active. Instalarea primitoare le reconectează pe ale sale.

Restaurează un spațiu de lucru dintr-un snapshot

1. La Snapshot-uri de instalare, extinde snapshot-ul dorit.
2. Găsește rândul spațiului de lucru și apasă Restaurează.
3. Confirmă. Tot ce a făcut acel spațiu de lucru de la crearea snapshot-ului este pierdut.

Aceasta este aceeași operațiune ca un import, îndreptată spre copia din snapshot a fișierului acelui spațiu de lucru — în mod deliberat, ca să nu existe un al doilea mecanism care ar putea trata diferit același fișier.

Un rând poate spune Nu mai e pe acest server, cu Restaurează dezactivat: snapshot-ul conține un spațiu de lucru pe care această instalare nu îl mai are. Readu-l manual — creează un spațiu de lucru, apoi, la Date spațiu de lucru, importă în el din <snapshot path>/<old workspace id>/workspace.db. Snapshot-ul extins își arată propria Cale pe server într-un câmp de copiere, iar titlul rândului este id-ul vechiului spațiu de lucru, așa că ai ambele jumătăți ale acelei căi în față.

Restaurează o instalare întreagă

Nu există niciun buton pentru asta și nici nu ar trebui să existe: înlocuiește bazele de date pe care serverul care rulează le ține deschise.

1. Oprește cc_server. Dacă rulezi aplicația desktop cu serverul ei încorporat, închide aplicația.

2. Copiază conținutul snapshot-ului peste directorul de date. Structura snapshot-ului o oglindește pe cea activă, așa că este o simplă copiere:

   # 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. Șterge orice fișiere -wal și -shm care stau lângă bazele de date pe care le-ai înlocuit. Aparțin fișierelor vechi, iar unul rămas în urmă alături de o bază de date restaurată este un risc de corupere.

4. Pornește din nou serverul.

Snapshot-ul nu conține secrets.json, așa că o instalare restaurată pe un host nou își păstrează datele, dar nu și acreditările: dispozitivele asociate, token-urile de provider și setările SSO trebuie re-stabilite sau restaurate din locul unde ai păstrat acel fișier. Restaurarea pe același host, unde secrets.json nu s-a pierdut niciodată, păstrează totul.

Copiază backup-urile în afara mașinii

Un snapshot aflat pe același disc ca baza de date pe care a copiat-o te protejează de un import prost, nu de disc. Nimic din Control Center nu trimite o copie nicăieri, așa că această parte îți revine.

Sincronizează snapshot-urile

Snapshot-urile sunt imuabile după ce au fost scrise și sunt denumite după marca de timp, așa că orice instrument de sincronizare le gestionează bine. Exclude transfer/, care este un atelier pentru descărcările și încărcările în curs:

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 oglindește curățarea locală către remote. Scoate-l dacă vrei ca remote-ul să păstreze snapshot-urile mai mult decât hostul.

Nu sincroniza niciodată direct bazele de date active

Nu îndrepta rsync, aws s3 sync sau un agent de backup la nivel de fișier spre global.db sau <workspaceId>/workspace.db în timp ce serverul rulează. O bază de date SQLite activă are un fișier secundar -wal, iar o copiere fișier cu fișier le surprinde pe cele două în momente diferite — rezultatul este un fișier care deseori se deschide și în care lipsesc în tăcere scrierile recente sau care nu se deschide deloc. Copiază snapshot-ul, care a fost scris într-o tranzacție de citire, sau fă unul cu VACUUM INTO, ca mai jos.

Include ce lasă pe dinafară un snapshot

Ca să poți reconstrui instalarea, nu doar datele ei, copiază-le și pe acestea. Sunt fișiere obișnuite, sigure de copiat în timp ce serverul rulează:

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 are modul 0600 și conține fiecare cheie de asociere, acreditare de provider și setare SSO din instalare. Oriunde ajunge trebuie să fie cel puțin la fel de protejat ca hostul serverului — criptat în repaus și nu un bucket pe care îl poate citi oricine altcineva.

Omite spaces/ (worktree-uri copy-on-write, reprovisionate din repo-urile tale), pr_clones/ (un cache), models/ (descărcate din nou), media_cache/ și rigs/ (stare de mașină și voluminoase). Audio-ul întâlnirilor înregistrate din meetings/ merită inclus dacă păstrezi întâlniri.

Programează un snapshot al întregii instalări în afara aplicației

Pipeline-ul integrat face backup doar pentru un singur spațiu de lucru. Pentru un snapshot al întregii instalări nesupravegheat, nu există subcomandă CLI, iar RPC-ul de snapshot necesită un client complet asociat care este proprietarul instalării. Un timer de pe host poate folosi VACUUM INTO pe bazele de date active:

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

Rulează-l ca același utilizator care deține directorul de date, din cron sau dintr-un timer systemd, și sincronizează DEST în afara hostului după aceea. VACUUM INTO necesită SQLite 3.27 sau mai nou.

Scrie-l în afara <dataDir>/backups/. Un director făcut manual acolo nu are manifest.json, așa că aplicația l-ar lista ca pe un snapshot incomplet, iar lista ar înceta să mai fie o evidență onestă a ceea ce a produs serverul însuși.

Curăță snapshot-urile vechi ale întregii instalări

Poți șterge snapshot-uri de instalare individuale din aplicație. Pentru o politică de retenție pe host, ține directorul de backup al spațiilor de lucru separat de snapshot-urile de instalare:

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

Verifică rezultatul unei rulări cu -print înainte de a adăuga -exec. Păstrează mai mult de unul: defecțiunea de care te protejezi este adesea „și ultimul backup are problema”.

Verifică dacă un backup este bun

Un backup pe care nu l-a restaurat nimeni este o ipoteză.

Verificare ieftină — fișierul se deschide și paginile lui sunt intacte:

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

Verificarea reală — adoptă-l. Creează un spațiu de lucru de probă pe o instalare care nu este de producție, importă în el un fișier de spațiu de lucru și uită-te dacă spațiile, tichetele și mesajele pe care le aștepți sunt acolo. Aceasta exercită aceeași cale pe care o parcurge o restaurare reală, inclusiv reconstruirea FTS, și este singura verificare care îți spune că backup-ul este restaurabil, nu doar citibil.

Fă asta o dată când configurezi backup-urile și din nou ori de câte ori schimbi locul unde sunt stocate.

Depanare

Simptom	Cauză și soluție
Controalele de descărcare și încărcare sunt dezactivate cu o notă despre un releu	Ești conectat prin releul intermediat, care nu transportă fișiere. Conectează-te direct
„Serverul a refuzat”	Rol. Crearea sau listarea unui snapshot de instalare necesită operatorul instalării. Descărcarea unui spațiu de lucru necesită admin, restaurarea unuia necesită proprietar, un zip cu snapshot complet necesită operatorul instalării
„Acest server nu are o suprafață de backup”	Hostul nu are conectat niciun port de backup — un server demo. Operațiunile lipsesc, în loc să fie refuzate
„Fișierul e mai mare decât acceptă serverul”	Încărcările sunt limitate la 8 GiB. Pune fișierul pe hostul serverului și folosește în schimb Importă → Alege fișier
Import refused: not a Control Center workspace database	Fișierul nu are niciun rând workspace_meta — nu este un export de spațiu de lucru sau este trunchiat. Nu s-a înlocuit nimic
Un snapshot este listat Incomplet	Manifestul lui lipsește sau numește fișiere absente. Fă unul nou; între timp, adoptă din el fișierele individuale de spațiu de lucru
Un snapshot spune că nu au fost capturate spații de lucru	În acele spații de lucru nu s-a scris niciodată sau copierea lor a eșuat. Verifică jurnalul serverului
O instalare restaurată nu are acreditări de forge sau SSO	secrets.json nu este într-un snapshot. Restaurează-l de unde l-ai păstrat sau reconectează providerii
Unui spațiu de lucru restaurat îi lipsesc imaginile lipite	Blob-urile stau lângă baza de date, nu în ea. Copiază și <workspaceId>/blobs/

Ghiduri conexe

• Rulează un server headless: de unde vine directorul de date
• Conectează-te la un server remote: conexiuni directe versus prin releu
• Asociază un dispozitiv: acreditarea cu care semnează rutele de transfer

Concepte și referință conexe

• Backup, export și import: fiecare operațiune, rută, câmp și limită
• Spații de lucru și izolare: de ce un spațiu de lucru este un singur fișier
• cc_server CLI: structura directorului de date