Cadangkan dan pulihkan

Panduan ini membahas lima hal yang sebenarnya dilakukan orang dengan cadangan: membuatnya, mengumpulkannya, memindahkan ruang kerja, memulihkannya, dan menyimpan salinannya di luar mesin. Untuk bentuk persis setiap artefak dan operasinya, lihat referensi cadangan.

Semua yang ada di sini berada di Pengaturan → Server → Cadangan & pemulihan.

Prasyarat

• Klien penuh — aplikasi desktop atau web. Ponsel yang dipasangkan tidak bisa memicu satu pun dari tindakan ini, memang begitu desainnya.
• Untuk membuat, menampilkan daftar, mengunduh, atau menghapus snapshot instalasi: pemilik instalasi.
• Untuk tindakan per ruang kerja: admin ruang kerja itu untuk mengekspor, pemilik untuk mengimpor atau menghapusnya.
• Untuk pengunduhan dan pengunggahan: koneksi langsung ke server. Relay dengan perantara membawa frame RPC, bukan transfer file, dan kontrol transfer menonaktifkan dirinya sendiri dengan catatan saat Anda melewatinya.

Snapshot instalasi bersifat manual

Cadangkan sekarang tetap hanya membuat snapshot seluruh instalasi saat diminta. Pipeline bawaan Workspace backup sebagai gantinya bisa membuat cadangan basis data ruang kerja sekali seminggu dan menghapus cadangan ruang kerja itu yang lebih tua dari 30 hari. Pipeline ini tidak menyalin global.db, ruang kerja lain, atau file di samping basis data. Simpan salinan di luar mesin secara terpisah.

Apa yang dicakup cadangan

Kedua artefak itu hanya basis data:

• Snapshot instalasi adalah direktori bertanda waktu: manifest.json, global.db, dan satu <workspaceId>/workspace.db per ruang kerja.
• Ekspor ruang kerja adalah satu file workspace.db itu.

Keduanya tidak membawa sisa direktori data: secrets.json (kunci pemasangan, kredensial penyedia, SSO), blobs/ milik ruang kerja (gambar yang ditempelkan ke pesan), skills/, agents/, chat_credentials/, audio rapat yang direkam, atau gambar rig. Sebagiannya bisa dibuang dan sebagiannya tidak — tabel lengkapnya ada di referensi, dan menutupinya adalah tujuan bagian di luar mesin.

Membuat snapshot seluruh instalasi

1. Buka Pengaturan → Server → Cadangan & pemulihan.
2. Di bawah Snapshot instalasi, tekan Cadangkan sekarang.
3. Notifikasi menampilkan nama direktori yang ditulis, di host server. Snapshot baru muncul di bagian atas daftar.

Server tetap berjalan sepanjang proses. Setiap file ditulis dengan VACUUM INTO, yang konsisten terhadap basis data aktif, jadi tidak ada jendela pemeliharaan dan tidak perlu menghentikan agen.

Setiap baris dalam daftar menampilkan stempel waktu, ukuran di disk, berapa banyak ruang kerja yang terekam, dan apakah snapshot itu Lengkap atau Tidak lengkap. Tidak lengkap berarti manifest-nya hilang atau menyebut file yang tidak ada — cadangan yang terputus karena crash atau disk penuh. Baris seperti itu tetap didaftarkan dengan sengaja: snapshot yang tidak Anda lihat adalah snapshot yang Anda kira Anda miliki. Snapshot yang tidak lengkap tidak bisa memulihkan seluruh instalasi, tetapi file ruang kerja yang dimilikinya masih bisa diadopsi satu per satu.

Sebuah baris juga bisa menyatakan n ruang kerja tidak terekam. Itu adalah ruang kerja yang terdaftar tetapi belum pernah ditulisi (filenya belum ada), atau ruang kerja yang penyalinannya gagal — periksa log server.

Menjadwalkan cadangan ruang kerja dan retensinya

Buka Pengaturan → Pipeline → Template pipeline untuk ruang kerja tersebut dan cari Workspace backup. Jadwalnya yang aktif berjalan setiap Minggu pukul 03:00 UTC: Back up workspace, diikuti Delete backups older than (bawaan 30 hari). Node kedua berjalan hanya setelah cadangan berhasil. Anda bisa mengubah jumlah hari retensi pada node atau menonaktifkan jadwalnya. Jika server offline pada waktu yang dijadwalkan, jadwal itu menyusul sekali saat server kembali, bukan memutar ulang setiap minggu yang terlewat.

Cadangan ruang kerja berada di server di bawah backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Node retensi hanya menghapus cadangan lama untuk ruang kerja ini; node itu tidak pernah menghapus snapshot instalasi atau cadangan ruang kerja lain. File-file ini hanya berisi basis data. Untuk retensi di luar mesin, salinlah secara terpisah.

Cadangan ini terpisah dari daftar Snapshot instalasi. Untuk memulihkannya, gunakan Data ruang kerja → Impor dengan path workspace.db cadangan di sisi server. Impor menggantikan basis data ruang kerja tersebut saat ini, jadi ekspor dulu jika Anda mungkin perlu membatalkan pemulihan.

Menghapus snapshot instalasi

Di bawah Snapshot instalasi, bentangkan snapshot, termasuk yang tidak lengkap, dan gunakan Hapus snapshot di bagian bahaya. Konfirmasi namanya. Seluruh direktori snapshot dihapus secara permanen dari server; unduh dulu jika Anda memerlukan salinannya. Pipeline cadangan ruang kerja tidak pernah menghapus snapshot ini.

Mengumpulkan salinan di mesin Anda sendiri

Path yang ditampilkan halaman ini berada di mesin yang menjalankan cc_server. Jika mesin itu bukan mesin yang Anda gunakan, gunakan tombol Unduh:

• Di samping setiap ruang kerja di bawah Data ruang kerja → Unduh, untuk satu file .db.
• Di samping setiap snapshot di bawah Snapshot instalasi → Unduh, untuk seluruh snapshot sebagai .zip.

Di desktop Anda memilih lokasi file disimpan dan notifikasi menyebutkannya; di web file masuk ke unduhan browser. Dengan cara apa pun, keduanya melaporkan kemajuan dalam satuan byte, karena inilah dua muatan yang bisa mencapai gigabyte.

Keduanya membuat salinan baru pada saat Anda menekan tombol, mengalirkannya, lalu menghapus salinan di server setelahnya — unduhan bukan “mengambil file yang tadi dibuat tombol ekspor”.

Mengekstrak arsip snapshot mereproduksi tata letak snapshot dengan persis, itulah yang membuat pemulihannya sekadar menyalin kembali.

Memindahkan ruang kerja ke instalasi lain

Satu ruang kerja adalah satu file basis data, jadi menyerahkannya adalah operasi file.

1. Di server sumber, Pengaturan → Server → Cadangan & pemulihan → Data ruang kerja, bentangkan ruang kerja dan tekan Unduh.
2. Di server tujuan, buat (atau pilih) ruang kerja yang akan menerimanya.
3. Bentangkan ruang kerja itu, dan di bawah Pulihkan dari perangkat ini tekan Pilih file lalu unggah. Pilih .db yang Anda unduh.

Jika kedua server adalah mesin yang sama tempat Anda bekerja, Simpan di server plus Impor → Pilih file melakukan hal yang sama tanpa perjalanan bolak-balik; path di dialog impor diselesaikan di host server.

Impor menggantikan semuanya

Mengimpor menimpa semua yang saat ini dimiliki ruang kerja tujuan, dan tindakan ini tidak bisa dibatalkan. Ekspor dulu ruang kerja tujuan jika ada isinya yang mungkin ingin Anda kembalikan.

Ada dua hal yang diizinkan dan dicatat alih-alih ditolak: mengimpor file yang id ruang kerja tercatatnya berbeda dari tujuan (inilah cara Anda menduplikasi ruang kerja atau memulihkannya dengan id baru), dan mengimpor file dari instalasi lain. Pada kasus kedua, perangkat yang dipasangkan dan id pengguna milik file itu berasal dari instalasi asalnya dan tidak akan dikenali di instalasi ini — data ruang kerja itu sendiri tetap utuh, tetapi periksa ulang keanggotaannya setelah mengadopsinya.

Token bot chat berada di samping basis data, bukan di dalamnya, jadi ruang kerja yang Anda serahkan kepada orang lain tidak membawa kredensial aktif. Instalasi penerima menghubungkan kembali tokennya sendiri.

Memulihkan satu ruang kerja dari snapshot

1. Di bawah Snapshot instalasi, bentangkan snapshot yang Anda inginkan.
2. Temukan baris ruang kerja itu dan tekan Pulihkan.
3. Konfirmasi. Semua yang telah dilakukan ruang kerja itu sejak snapshot diambil akan hilang.

Ini operasi yang sama dengan impor, diarahkan ke salinan file ruang kerja itu di dalam snapshot — memang sengaja, agar tidak ada mekanisme kedua yang bisa memperlakukan file yang sama secara berbeda.

Sebuah baris bisa menyatakan Sudah tidak ada di server ini, dengan tombol Pulihkan nonaktif: snapshot memuat ruang kerja yang sudah tidak dimiliki instalasi ini. Pulihkan secara manual — buat ruang kerja, lalu di bawah Data ruang kerja impor ke dalamnya dari <snapshot path>/<old workspace id>/workspace.db. Snapshot yang dibentangkan menampilkan Path di server-nya sendiri di kolom salin, dan judul barisnya adalah id ruang kerja lama, jadi kedua bagian path itu ada di depan Anda.

Memulihkan seluruh instalasi

Tidak ada tombol untuk ini, dan memang seharusnya tidak ada: operasi ini menggantikan basis data yang sedang dibuka oleh server yang berjalan.

1. Hentikan cc_server. Jika Anda menjalankan aplikasi desktop dengan server tersematnya, keluar dari aplikasi itu.

2. Salin isi snapshot ke direktori data. Tata letak snapshot mencerminkan yang aktif, jadi ini salinan biasa:

   # 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. Hapus file -wal dan -shm yang berada di samping basis data yang Anda gantikan. File itu milik file lama, dan file usang di samping basis data yang dipulihkan adalah risiko korupsi.

4. Jalankan server lagi.

Snapshot tidak memuat secrets.json, jadi instalasi yang dipulihkan ke host baru mempertahankan datanya tetapi tidak kredensialnya: perangkat yang dipasangkan, token penyedia, dan pengaturan SSO harus disiapkan ulang, atau dipulihkan dari tempat Anda menyimpan file itu. Memulihkan ke host yang sama, tempat secrets.json tidak pernah hilang, mempertahankan semuanya.

Menyalin cadangan ke luar mesin

Snapshot yang berada di disk yang sama dengan basis data yang disalinnya melindungi Anda dari impor yang salah, bukan dari kerusakan disk. Tidak ada apa pun di Control Center yang mengirim salinan ke mana pun, jadi bagian ini tanggung jawab Anda.

Sinkronkan snapshot

Snapshot tidak berubah setelah ditulis dan dinamai menurut stempel waktu, jadi alat sinkronisasi apa pun menanganinya dengan baik. Kecualikan transfer/, yaitu ruang kerja untuk pengunduhan dan pengunggahan yang sedang berlangsung:

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 mencerminkan pemangkasan lokal Anda ke remote. Hilangkan opsi itu jika Anda ingin remote menyimpan snapshot lebih lama daripada host.

Jangan pernah menyinkronkan basis data aktif secara langsung

Jangan arahkan rsync, aws s3 sync, atau agen cadangan tingkat file ke global.db atau <workspaceId>/workspace.db saat server berjalan. Basis data SQLite yang aktif memiliki sidecar -wal, dan salinan file demi file menangkap keduanya pada saat yang berbeda — hasilnya adalah file yang sering kali bisa dibuka tetapi diam-diam kehilangan penulisan terbaru, atau tidak bisa dibuka sama sekali. Salin snapshot, yang ditulis dalam transaksi baca, atau buat snapshot dengan VACUUM INTO seperti di bawah.

Sertakan yang dilewatkan snapshot

Agar bisa membangun ulang instalasi dan bukan hanya datanya, salin juga file-file ini. Ini file biasa, aman disalin saat server berjalan:

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 bermode 0600 dan memuat setiap kunci pemasangan, kredensial penyedia, dan pengaturan SSO di instalasi. Ke mana pun file itu disalin, perlindungannya harus setidaknya sekuat host server — terenkripsi saat disimpan, dan bukan bucket yang bisa dibaca orang lain.

Lewati spaces/ (worktree copy-on-write, disiapkan ulang dari repo Anda), pr_clones/ (cache), models/ (diunduh ulang), media_cache/ dan rigs/ (status mesin, dan berukuran besar). Audio rapat yang direkam di bawah meetings/ layak disertakan jika Anda menyimpan rapat.

Jadwalkan snapshot seluruh instalasi di luar aplikasi

Pipeline bawaan hanya mencadangkan satu ruang kerja. Untuk snapshot seluruh instalasi tanpa pengawasan, tidak ada subperintah CLI, dan snapshot RPC memerlukan klien penuh yang dipasangkan yang merupakan pemilik instalasi. Timer di sisi host bisa memakai VACUUM INTO terhadap basis data aktif:

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

Jalankan sebagai pengguna yang sama yang memiliki direktori data, dari cron atau timer systemd, lalu sinkronkan DEST ke luar host setelahnya. VACUUM INTO memerlukan SQLite 3.27 atau yang lebih baru.

Tulis di luar <dataDir>/backups/. Direktori buatan tangan di sana tidak memiliki manifest.json, jadi aplikasi akan mendaftarkannya sebagai snapshot yang tidak lengkap dan daftar itu berhenti menjadi catatan jujur tentang apa yang dihasilkan server sendiri.

Pangkas snapshot seluruh instalasi yang lama

Anda bisa menghapus snapshot instalasi satu per satu di aplikasi. Untuk kebijakan retensi di sisi host, pisahkan direktori cadangan ruang kerja dari snapshot instalasi:

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

Periksa keluaran dari sekali jalan -print sebelum menambahkan -exec. Simpan lebih dari satu: kegagalan yang Anda lindungi sering kali adalah “cadangan terakhir juga bermasalah”.

Memeriksa bahwa cadangan itu baik

Cadangan yang belum pernah dipulihkan hanyalah dugaan.

Pemeriksaan murah — file bisa dibuka dan halamannya utuh:

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

Pemeriksaan sungguhan — adopsi file itu. Buat ruang kerja sementara di instalasi non-produksi, impor file ruang kerja ke dalamnya, dan lihat apakah space, tiket, serta pesan yang Anda harapkan ada di sana. Itu menjalankan jalur yang sama dengan pemulihan sungguhan, termasuk pembangunan ulang FTS, dan hanya pemeriksaan itulah yang memberi tahu Anda bahwa cadangan itu bisa dipulihkan dan bukan sekadar bisa dibaca.

Lakukan sekali saat Anda menyiapkan cadangan, dan lagi setiap kali Anda mengubah lokasi penyimpanannya.

Pemecahan masalah

Gejala	Penyebab dan perbaikan
Kontrol unduh dan unggah dinonaktifkan dengan catatan tentang relay	Anda terhubung melalui relay dengan perantara, yang tidak membawa transfer file. Hubungkan secara langsung
“Server menolak”	Peran. Membuat atau menampilkan daftar snapshot instalasi memerlukan operator instalasi. Mengunduh ruang kerja memerlukan admin, memulihkannya memerlukan pemilik, zip seluruh snapshot memerlukan operator instalasi
“Server ini tidak punya permukaan cadangan”	Host tidak memiliki port cadangan yang terpasang — server demo. Operasinya tidak ada alih-alih ditolak
“File lebih besar dari yang diterima server”	Unggahan dibatasi 8 GiB. Letakkan file di host server dan gunakan Impor → Pilih file sebagai gantinya
Impor ditolak: bukan basis data ruang kerja Control Center	File tidak memiliki baris workspace_meta — itu bukan ekspor ruang kerja, atau terpotong. Tidak ada yang digantikan
Snapshot terdaftar sebagai Tidak lengkap	Manifest-nya hilang atau menyebut file yang tidak ada. Buat snapshot baru; sementara itu adopsi file ruang kerja satu per satu darinya
Snapshot menyatakan ada ruang kerja yang tidak terekam	Ruang kerja itu belum pernah ditulisi, atau penyalinannya gagal. Periksa log server
Instalasi yang dipulihkan tidak memiliki kredensial forge atau SSO	secrets.json tidak ada di dalam snapshot. Pulihkan dari tempat Anda menyimpannya, atau hubungkan kembali penyedianya
Ruang kerja yang dipulihkan kehilangan gambar yang ditempelkan	Blob berada di samping basis data, bukan di dalamnya. Salin juga <workspaceId>/blobs/

Panduan terkait

• Jalankan server headless: dari mana direktori data berasal
• Hubungkan ke server jarak jauh: koneksi langsung versus melalui relay
• Pasangkan perangkat: kredensial yang dipakai rute transfer untuk menandatangani

Konsep dan referensi terkait

• Cadangan, ekspor, dan impor: setiap operasi, rute, bidang, dan batas
• Ruang kerja dan isolasi: mengapa satu ruang kerja adalah satu file
• cc_server CLI: tata letak direktori data