Sandarkan dan pulihkan

Panduan ini merangkumi lima perkara yang sebenarnya dilakukan orang dengan sandaran: mengambilnya, mengumpulnya, memindahkan ruang kerja, memulihkannya semula, dan menyimpan salinan di luar mesin. Untuk bentuk tepat setiap artifak dan operasi, lihat rujukan sandaran.

Semuanya di sini terletak di Tetapan → Pelayan → Sandaran & pulih.

Prasyarat

• Klien penuh — apl desktop atau web. Telefon yang digandingkan tidak boleh mencetuskan mana-mana daripada ini, memang sengaja.
• Untuk mengambil, menyenaraikan, memuat turun atau memadam snapshot pemasangan: pemilik pemasangan itu.
• Untuk tindakan mengikut ruang kerja: pentadbir ruang kerja itu untuk eksport, pemilik untuk mengimport atau memadamnya.
• Untuk muat turun dan muat naik: sambungan terus ke pelayan. Geganti berperantara membawa bingkai RPC, bukan pemindahan fail, dan kawalan pemindahan melumpuhkan dirinya dengan satu nota apabila anda berada padanya.

Snapshot pemasangan dibuat secara manual

Sandarkan sekarang masih hanya mencipta snapshot seluruh pemasangan apabila diminta. Pipeline Workspace backup terbina sebaliknya boleh mengambil sandaran pangkalan data ruang kerja sekali seminggu dan membuang sandaran ruang kerja itu yang lebih lama daripada 30 hari. Ia tidak menyalin global.db, ruang kerja lain, atau fail di sisi pangkalan data. Simpan salinan di luar mesin secara berasingan.

Apa yang dicakup oleh sandaran

Kedua-dua artifak ialah pangkalan data sahaja:

• Snapshot pemasangan ialah direktori bertanda masa: manifest.json, global.db dan satu <workspaceId>/workspace.db bagi setiap ruang kerja.
• Eksport ruang kerja ialah fail workspace.db tunggal itu.

Kedua-duanya tidak membawa seluruh direktori data yang lain: secrets.json (kunci penggandingan, kelayakan penyedia, SSO), blobs/ sesebuah ruang kerja (imej yang ditampal ke dalam mesej), skills/, agents/, chat_credentials/, audio mesyuarat yang dirakam atau imej rig. Sebahagian daripadanya boleh dibuang dan sebahagiannya tidak — jadual penuhnya ada dalam rujukan, dan melindunginya itulah tujuan bahagian luar mesin.

Ambil snapshot seluruh pemasangan

1. Buka Tetapan → Pelayan → Sandaran & pulih.
2. Di bawah Snapshot pemasangan, tekan Sandarkan sekarang.
3. Toast menamakan direktori yang ditulis, pada hos pelayan. Snapshot baharu muncul di bahagian atas senarai.

Pelayan terus berjalan sepanjang masa. Setiap fail ditulis dengan VACUUM INTO, yang konsisten terhadap pangkalan data yang hidup, jadi tiada tetingkap penyelenggaraan dan tiada keperluan untuk menghentikan ejen.

Setiap baris dalam senarai menunjukkan cap masa, saiz pada cakera, berapa banyak ruang kerja yang ditangkap dan sama ada snapshot itu Lengkap atau Tidak lengkap. Tidak lengkap bermaksud manifesnya hilang atau menamakan fail yang tidak ada — sandaran yang tergendala oleh ranap atau cakera penuh. Semuanya masih disenaraikan dengan sengaja: snapshot yang tidak dapat anda lihat ialah snapshot yang anda sangka anda miliki. Snapshot yang tidak lengkap tidak boleh memulihkan seluruh pemasangan, tetapi fail ruang kerja yang dipegangnya masih boleh diterima pakai satu demi satu.

Satu baris juga mungkin menyatakan n ruang kerja tidak ditangkap. Itu ruang kerja yang didaftarkan tetapi tidak pernah ditulis (belum ada fail), atau yang salinannya gagal — semak log pelayan.

Jadualkan sandaran ruang kerja dan pengekalannya

Buka Tetapan → Pipelines → Templat pipeline untuk ruang kerja itu dan cari Workspace backup. Jadualnya yang diaktifkan berjalan setiap Ahad pada 03:00 UTC: Back up workspace, diikuti Delete backups older than (30 hari secara lalai). Nod kedua hanya berjalan selepas sandaran berjaya. Anda boleh menukar hari pengekalan pada nod itu atau melumpuhkan jadualnya. Jika pelayan berada luar talian pada masa yang dijadualkan, jadual itu menyusul sekali apabila ia kembali, bukannya memainkan semula setiap minggu yang terlepas.

Sandaran ruang kerja terletak pada pelayan di bawah backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Nod pengekalan hanya memadam sandaran lama ruang kerja ini; ia tidak pernah memadam snapshot pemasangan atau sandaran ruang kerja lain. Fail-fail ini mengandungi pangkalan data sahaja. Untuk pengekalan di luar mesin, salinnya secara berasingan.

Sandaran ini berasingan daripada senarai Snapshot pemasangan. Untuk memulihkan satu, gunakan Data ruang kerja → Import dengan laluan workspace.db sandaran itu pada sisi pelayan. Import menggantikan pangkalan data semasa ruang kerja itu, jadi eksportnya dahulu jika anda mungkin perlu membatalkan pemulihan itu.

Padam snapshot pemasangan

Di bawah Snapshot pemasangan, kembangkan snapshot itu, termasuk yang tidak lengkap, dan gunakan Padam snapshot dalam bahagian bahaya. Sahkan namanya. Seluruh direktori snapshot dibuang secara kekal daripada pelayan; muat turun dahulu jika anda memerlukan salinannya. Pipeline sandaran ruang kerja tidak pernah memadam snapshot ini.

Kumpul salinan pada mesin anda sendiri

Laluan yang dipaparkan halaman ini berada pada mesin yang menjalankan cc_server. Apabila mesin itu bukan mesin yang anda sedang duduki, gunakan butang Muat turun:

• Di sebelah setiap ruang kerja di bawah Data ruang kerja → Muat turun, untuk satu fail .db.
• Di sebelah setiap snapshot di bawah Snapshot pemasangan → Muat turun, untuk seluruh snapshot sebagai .zip.

Pada desktop anda memilih tempat fail itu disimpan dan toast menamakannya; pada web ia masuk ke muat turun pelayar. Sama ada cara, kedua-duanya melaporkan kemajuan dalam bait, kerana kedua-duanya ialah muatan yang boleh mencecah gigabait.

Kedua-duanya menjana salinan baharu pada saat anda menekan butang, menstrimkannya, dan memadam salinan pelayan selepas itu — muat turun bukan “mengambil fail yang dibuat oleh butang eksport tadi”.

Membuka arkib snapshot menghasilkan semula susun atur snapshot dengan tepat, dan itulah yang menjadikan pemulihannya satu salinan kembali.

Pindahkan ruang kerja ke pemasangan lain

Satu ruang kerja ialah satu fail pangkalan data, jadi menyerahkannya ialah operasi fail.

1. Pada pelayan sumber, Tetapan → Pelayan → Sandaran & pulih → Data ruang kerja, kembangkan ruang kerja itu dan tekan Muat turun.
2. Pada pelayan destinasi, cipta (atau pilih) ruang kerja yang akan menerimanya.
3. Kembangkan ruang kerja itu, dan di bawah Pulihkan dari peranti ini tekan Pilih fail dan muat naik. Pilih .db yang anda muat turun tadi.

Jika kedua-dua pelayan ialah mesin yang anda sedang duduki, Simpan pada pelayan serta Import → Pilih fail melakukan perkara yang sama tanpa pusingan pergi balik; laluan dalam dialog import diselesaikan pada hos pelayan.

Import menggantikan segala-galanya

Mengimport menimpa segala yang dipegang oleh ruang kerja sasaran sekarang, dan ia tidak boleh dibatalkan. Eksport sasaran itu dahulu jika ia memegang apa-apa yang anda mungkin mahu kembali.

Dua perkara dibenarkan dan direkodkan dalam log dan bukannya ditolak: mengimport fail yang id ruang kerja yang direkodkan di dalamnya berbeza daripada sasaran (inilah cara anda menduplikasi ruang kerja atau memulihkannya di bawah id baharu), dan mengimport fail daripada pemasangan yang berbeza. Dalam kes kedua itu, peranti berganding dan id pengguna fail tersebut kepunyaan pemasangan asalnya dan tidak akan diselesaikan pada pemasangan ini — data ruang kerja itu sendiri utuh, tetapi semak semula keahlian selepas menerimanya.

Token bot sembang terletak di sisi pangkalan data, bukan di dalamnya, jadi ruang kerja yang anda serahkan kepada orang lain tidak membawa kelayakan hidup. Pemasangan penerima menyambung semula kelayakannya sendiri.

Pulihkan satu ruang kerja daripada snapshot

1. Di bawah Snapshot pemasangan, kembangkan snapshot yang anda mahu.
2. Cari baris ruang kerja itu dan tekan Pulihkan.
3. Sahkan. Segala yang dilakukan oleh ruang kerja itu sejak snapshot diambil akan hilang.

Ini ialah operasi yang sama seperti import, ditujukan kepada salinan fail ruang kerja itu dalam snapshot — memang sengaja, supaya tiada mekanisme kedua yang boleh melayan fail yang sama secara berbeza.

Satu baris mungkin menyatakan Tidak lagi pada pelayan ini, dengan Pulihkan dilumpuhkan: snapshot itu memegang ruang kerja yang tidak lagi dimiliki pemasangan ini. Bawanya kembali secara manual — cipta ruang kerja, kemudian di bawah Data ruang kerja import ke dalamnya daripada <snapshot path>/<old workspace id>/workspace.db. Snapshot yang dikembangkan menunjukkan Laluan pada pelayan sendiri dalam medan salinan, dan tajuk baris itu ialah id ruang kerja lama, jadi kedua-dua bahagian laluan itu ada di hadapan anda.

Pulihkan seluruh pemasangan

Tiada butang untuk ini, dan memang sepatutnya tiada: ia menggantikan pangkalan data yang sedang dipegang terbuka oleh pelayan yang berjalan.

1. Hentikan cc_server. Jika anda menjalankan apl desktop dengan pelayan terbenamnya, keluar daripada apl itu.

2. Salin kandungan snapshot ke atas direktori data. Susun atur snapshot mencerminkan yang hidup, jadi ini penyalinan biasa sahaja:

   # 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. Padam mana-mana fail -wal dan -shm yang terletak di sisi pangkalan data yang anda gantikan. Fail itu kepunyaan fail lama, dan yang basi di sisi pangkalan data yang dipulihkan ialah risiko kerosakan.

4. Mulakan semula pelayan.

Snapshot tidak memegang secrets.json, jadi pemasangan yang dipulihkan ke hos baharu mengekalkan datanya tetapi bukan kelayakannya: peranti berganding, token penyedia dan tetapan SSO perlu diwujudkan semula, atau dipulihkan dari tempat anda menyimpan fail itu. Memulihkan ke hos yang sama, tempat secrets.json tidak pernah hilang, mengekalkan segala-galanya.

Salin sandaran keluar daripada mesin

Snapshot pada cakera yang sama dengan pangkalan data yang disalinnya melindungi anda daripada import yang buruk, bukan daripada cakera itu. Tiada apa-apa dalam Control Center menghantar salinannya ke mana-mana, jadi bahagian ini tanggungjawab anda.

Segerakkan snapshot

Snapshot tidak boleh diubah selepas ditulis dan dinamakan mengikut cap masa, jadi mana-mana alat segerak mengendalikannya dengan baik. Kecualikan transfer/, iaitu meja kerja untuk muat turun dan muat naik yang sedang berjalan:

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 tempatan anda ke jauh. Buangkan bendera itu jika anda mahu jauh menyimpan snapshot lebih lama daripada hos.

Jangan segerakkan pangkalan data hidup secara terus

Jangan halakan rsync, aws s3 sync atau ejen sandaran peringkat fail pada global.db atau <workspaceId>/workspace.db semasa pelayan berjalan. Pangkalan data SQLite yang hidup mempunyai fail sampingan -wal, dan salinan fail demi fail menangkap kedua-duanya pada detik yang berbeza — hasilnya ialah fail yang selalunya boleh dibuka tetapi secara senyap kehilangan tulisan terbaharu, atau tidak boleh dibuka sama sekali. Salin snapshot, yang ditulis di bawah transaksi baca, atau ambil satu dengan VACUUM INTO seperti di bawah.

Sertakan apa yang ditinggalkan oleh snapshot

Untuk dapat membina semula pemasangan dan bukan sekadar datanya, salin ini juga. Semuanya fail biasa, selamat disalin semasa pelayan 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 berkeizinan 0600 dan memegang setiap kunci penggandingan, kelayakan penyedia dan tetapan SSO pada pemasangan itu. Di mana pun ia diletakkan, tempat itu mesti dilindungi sekurang-kurangnya seperti hos pelayan — disulitkan semasa rehat, dan bukan baldi yang boleh dibaca oleh orang lain.

Langkau spaces/ (worktree salin-semasa-tulis, disediakan semula daripada repo anda), pr_clones/ (cache), models/ (dimuat turun semula), media_cache/ dan rigs/ (keadaan mesin, dan besar). Audio mesyuarat yang dirakam di bawah meetings/ berbaloi disertakan jika anda menyimpan mesyuarat.

Jadualkan snapshot seluruh pemasangan di luar apl

Pipeline terbina hanya menyandarkan satu ruang kerja. Untuk snapshot seluruh pemasangan yang berjalan tanpa pengawasan, tiada subperintah CLI, dan RPC snapshot memerlukan klien penuh berganding yang merupakan pemilik pemasangan. Pemasa di sisi hos boleh menggunakan VACUUM INTO terhadap pangkalan data hidup:

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

Jalankannya sebagai pengguna yang sama yang memiliki direktori data, daripada cron atau pemasa systemd, dan segerakkan DEST keluar daripada hos selepas itu. VACUUM INTO memerlukan SQLite 3.27 atau lebih baharu.

Tulisnya di luar <dataDir>/backups/. Direktori yang dibuat dengan tangan di situ tiada manifest.json, jadi apl akan menyenaraikannya sebagai snapshot yang tidak lengkap dan senarai itu tidak lagi menjadi rekod jujur tentang apa yang dihasilkan oleh pelayan sendiri.

Pangkas snapshot seluruh pemasangan yang lama

Anda boleh memadam snapshot pemasangan secara individu dalam apl. Untuk polisi pengekalan di sisi hos, pastikan direktori sandaran ruang kerja berasingan daripada snapshot pemasangan:

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

Semak output larian -print sebelum menambah -exec. Simpan lebih daripada satu: kegagalan yang anda lindungi itu selalunya “sandaran terakhir juga mempunyai masalah itu”.

Semak bahawa sandaran itu baik

Sandaran yang tidak pernah dipulihkan oleh sesiapa hanyalah hipotesis.

Semakan murah — fail itu boleh dibuka dan halamannya utuh:

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

Semakan sebenar — terima pakainya. Cipta ruang kerja sementara pada pemasangan bukan pengeluaran, import fail ruang kerja ke dalamnya, dan lihat sama ada ruang, tiket dan mesej yang anda jangkakan ada di situ. Itu melatih laluan yang sama seperti pemulihan sebenar, termasuk pembinaan semula FTS, dan itulah satu-satunya semakan yang memberitahu anda bahawa sandaran itu boleh dipulihkan dan bukan sekadar boleh dibaca.

Lakukan ini sekali semasa anda menyediakan sandaran, dan sekali lagi setiap kali anda menukar tempat penyimpanannya.

Penyelesaian masalah

Gejala	Punca dan pembaikan
Kawalan muat turun dan muat naik dilumpuhkan dengan nota tentang geganti	Anda bersambung melalui geganti berperantara, yang tidak membawa pemindahan fail. Sambung terus
“Pelayan menolak”	Peranan. Mengambil atau menyenaraikan snapshot pemasangan memerlukan operator pemasangan. Memuat turun ruang kerja memerlukan pentadbir, memulihkannya memerlukan pemilik, dan zip seluruh snapshot memerlukan operator pemasangan
“Pelayan ini tiada permukaan sandaran”	Hos itu tiada port sandaran yang dipasang — pelayan demo. Operasi itu tidak wujud dan bukannya ditolak
“Fail itu lebih besar daripada yang diterima oleh pelayan”	Muat naik dihadkan pada 8 GiB. Letakkan fail itu pada hos pelayan dan gunakan Import → Pilih fail sebagai gantinya
Import ditolak: bukan pangkalan data ruang kerja Control Center	Fail itu tiada baris workspace_meta — ia bukan eksport ruang kerja, atau ia terpotong. Tiada apa yang digantikan
Sesuatu snapshot disenaraikan sebagai Tidak lengkap	Manifesnya hilang atau menamakan fail yang tiada. Ambil snapshot baharu; sementara itu terima pakai fail ruang kerja individu daripadanya
Sesuatu snapshot menyatakan ruang kerja tidak ditangkap	Ruang kerja itu tidak pernah ditulis, atau salinannya gagal. Semak log pelayan
Pemasangan yang dipulihkan tiada kelayakan forge atau SSO	secrets.json tiada dalam snapshot. Pulihkannya dari tempat anda menyimpannya, atau sambung semula penyedia itu
Ruang kerja yang dipulihkan kehilangan imej yang ditampal	Blob terletak di sisi pangkalan data, bukan di dalamnya. Salin <workspaceId>/blobs/ juga

Panduan berkaitan

• Jalankan pelayan tanpa kepala: dari mana direktori data datang
• Sambung ke pelayan jauh: sambungan terus berbanding sambungan melalui geganti
• Gandingkan peranti: kelayakan yang ditandatangani oleh laluan pemindahan

Konsep dan rujukan berkaitan

• Sandaran, eksport dan import: setiap operasi, laluan, medan dan had
• Ruang kerja dan pengasingan: mengapa satu ruang kerja ialah satu fail
• cc_server CLI: susun atur direktori data