Sandaran, eksport dan import

Semua yang boleh disalin, diserahkan atau diterima pakai oleh Control Center, dan bentuk tepat setiap artifak. Untuk benar-benar membuat sandaran, lihat Sandarkan dan pulihkan; untuk sebab penyimpanan dipecahkan seperti ini, lihat Ruang kerja dan pengasingan.

Artifak

Terdapat tiga artifak salinan pangkalan data, dengan skop dan polisi pemadaman yang berbeza.

Artifak	Ditulis oleh	Bentuk	Merangkumi
Snapshot pemasangan	server.backupNow	Direktori bercap masa	Setiap pangkalan data pada pemasangan itu
Sandaran ruang kerja	Pipeline Workspace backup	Direktori bercap masa dengan satu .db	Pangkalan data satu ruang kerja
Eksport ruang kerja	workspace.export	Satu fail .db	Pangkalan data satu ruang kerja

Semuanya ditulis dengan SQLite VACUUM INTO, yang selamat terhadap pangkalan data WAL yang aktif: ia mengambil transaksi baca, menghasilkan salinan yang dinyahserpih dan konsisten dari segi transaksi, serta tidak pernah memerlukan pelayan dihentikan.

Susun atur snapshot

<dataDir>/backups/2026-07-28T09-12-33-000Z/
  manifest.json
  global.db
  <workspaceId>/workspace.db      one directory per workspace

Susun atur ini mencerminkan direktori data langsung dengan tepat, dan itulah yang menjadikan pemulihan sesuatu pemasangan sekadar menyalin kembali dan bukannya terjemahan. Nama direktori itu ialah cap masa UTC dengan : dan . digantikan dengan -, jadi ia selamat untuk sistem fail pada Windows dan tersusun mengikut kronologi sebagai rentetan biasa.

Sandaran ruang kerja berjadual berada secara berasingan di <dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Ia tidak merangkumi manifes atau global.db dan bukan snapshot pemasangan. Langkah pengekalan pipeline mingguan hanya membuang sandaran ruang kerjanya sendiri yang lebih lama daripada usia yang dikonfigurasikan (30 hari secara lalai); snapshot pemasangan yang dicipta secara manual tidak pernah termasuk dalam putaran itu. server.listBackups menyenaraikan snapshot pemasangan sahaja, termasuk yang tidak lengkap.

manifest.json

Medan	Jenis	Maksud
version	int	Versi format manifes. Kini 1
created_at	ISO-8601 UTC	Masa snapshot diambil
global.file	string	Sentiasa global.db
global.schema_version	int	Versi skema GlobalDatabase semasa tangkapan
global.bytes	int	Saiz global.db yang ditulis
workspace_schema_version	int	Versi skema WorkspaceDatabase yang dikongsi setiap fail ruang kerja
workspaces[]	array	Satu entri bagi setiap ruang kerja yang ditangkap
workspaces[].workspace_id	string	Ruang kerja yang dipegang oleh fail ini
workspaces[].file	string	Laluan relatif kepada akar snapshot, <workspaceId>/workspace.db
workspaces[].bytes	int	Saiz fail itu
skipped_workspaces[]	array of string	Ruang kerja yang tidak dapat ditangkap oleh sandaran

Sesuatu ruang kerja dilangkau apabila ia didaftarkan tetapi belum pernah ditulis ke dalamnya (jadi failnya belum wujud), atau apabila VACUUM INTO-nya gagal. Sama ada cara, snapshot itu tetap selesai dan manifes menamakan apa yang hilang.

Kelengkapan

server.listBackups melaporkan bendera complete bagi setiap snapshot. Ia palsu apabila manifes tiada atau tidak boleh dihuraikan, apabila global.db hilang, atau apabila manifes menamakan fail ruang kerja yang tiada pada cakera.

Snapshot yang tidak lengkap masih disenaraikan, kerana snapshot yang tidak dapat dilihat oleh pengendali ialah snapshot yang mereka percaya mereka miliki. Apabila manifes tidak boleh dibaca, penyenaraian berpatah balik kepada susun atur itu sendiri dan melaporkan mana-mana fail <workspaceId>/workspace.db yang ditemuinya — fail itu kekal boleh diterima pakai satu demi satu melalui workspace.import walaupun snapshot itu secara keseluruhan tidak dapat memulihkan sesuatu pemasangan.

Apa yang tidak terkandung dalam sandaran

Kedua-dua artifak itu ialah pangkalan data sahaja. Direktori ruang kerja memegang lebih daripada pangkalan datanya, dan tiada satu pun daripada selebihnya berpindah:

Laluan	Dalam snapshot?	Dalam eksport ruang kerja?
global.db	Ya	Tidak
<workspaceId>/workspace.db	Ya	Ya (ia ialah fail itu)
<workspaceId>/blobs/	Tidak	Tidak
<workspaceId>/skills/	Tidak	Tidak
<workspaceId>/agents/	Tidak	Tidak
<workspaceId>/chat_credentials/	Tidak	Tidak
<workspaceId>/spaces/<spaceId>/	Tidak	Tidak
<workspaceId>/pr_clones/	Tidak	Tidak
secrets.json	Tidak	Tidak
models/	Tidak	Tidak
meetings/<meetingId>/	Tidak	Tidak
rigs/	Tidak	Tidak

Sebahagian daripadanya boleh dibuang — spaces/ memegang worktree salin-semasa-tulis yang disediakan semula daripada repo, pr_clones/ ialah cache, models/ dimuat turun semula, rigs/ ialah keadaan mesin. Sebahagiannya tidak: blobs/ memegang imej yang ditampal yang ditunjuk oleh baris dalam pangkalan data, skills/ dan agents/ memegang fail yang digunakan oleh ejen untuk berjalan, dan secrets.json memegang setiap kunci penggandingan, kelayakan pembekal dan tetapan SSO pada pemasangan itu. Lihat Sandarkan dan pulihkan untuk merangkumi selebihnya.

Token sembang sengaja ditinggalkan

chat_credentials/ yang berada di sebelah pangkalan data dan bukannya di dalamnya ialah sebab ruang kerja yang diserahkan kepada orang lain tidak membawa token bot yang aktif. Lihat rujukan jambatan sembang.

Operasi

RPC sandaran pemasangan serta eksport/import ruang kerja hanya tersedia untuk fullClient: telefon yang digandingkan tidak boleh mencetuskannya. Semuanya langsung tiada — bukan ditolak, tetapi hilang dari segi struktur — pada pelayan yang tiada port sandaran didawai, seperti pelayan demo.

Operasi	Jenis	Skop	Peranan minimum	Argumen	Pulangan
server.backupNow	ubah	Pemasangan	pemilik pemasangan	tiada	{ok, path}
server.listBackups	baca	Pemasangan	pemilik pemasangan	tiada	{backups: [...]}
server.deleteBackup	ubah	Pemasangan	pemilik pemasangan	name	{ok}
workspace.export	baca	Ruang kerja	admin	tiada	{ok, path}
workspace.import	ubah	Ruang kerja	owner	source_path	{ok, workspace_id}
workspace.delete	ubah	Pemasangan*	owner	id	baris pendaftaran ditandakan dipadam

• workspace.delete tidak berskop kerana baris yang ditandakannya berada dalam daftar global; pengendalinya menyemak keahlian pemanggil dalam ruang kerja yang dinamakan dan mewajibkan owner.

path dalam setiap respons ialah laluan pada hos pelayan.

Snapshot seluruh pemasangan dikawal pemilik pada kedua-dua jalur

server.backupNow, server.listBackups, dan server.deleteBackup memerlukan pemilik pemasangan (ServerAuthority.serverOwner), pintu yang sama seperti GET /backup/snapshot. Sesuatu snapshot menangkap pangkalan data setiap ruang kerja, jadi menjadi pentadbir bagi satu ruang kerja tidak cukup untuk menguruskan yang lain. Pemadaman hanya menerima nama direktori cap masa yang tersenarai, bukan laluan pelayan sewenang-wenangnya, dan membuang keseluruhan snapshot (termasuk snapshot yang tidak lengkap). Eksport/import setiap ruang kerja kekal pada pentadbir/pemilik ruang kerja, bukan pemilik pemasangan.

Respons server.listBackups

Terbaharu dahulu, disusun mengikut nama direktori (yang merupakan cap masa, jadi susunan itu kekal walaupun bagi snapshot yang manifesnya tidak dapat dibaca).

{
  "backups": [
    {
      "path": "/…/backups/2026-07-28T09-12-33-000Z",
      "name": "2026-07-28T09-12-33-000Z",
      "created_at": "2026-07-28T09:12:33.000Z",
      "bytes": 481203712,
      "complete": true,
      "workspaces": [
        {
          "workspace_id": "w_9f2c…",
          "path": "/…/backups/2026-07-28T09-12-33-000Z/w_9f2c…/workspace.db",
          "bytes": 190840832
        }
      ],
      "skipped_workspace_ids": []
    }
  ]
}

created_at ditinggalkan apabila manifes tidak dapat dibaca. bytes pada peringkat atas ialah saiz sebenar pada cakera bagi keseluruhan direktori, bukan jumlah daripada manifes itu sendiri — soalan yang ditanya oleh pengendali yang memangkas snapshot ialah berapa kos direktori itu, bukan apa yang dimaksudkan untuk ditulis oleh sandaran.

Setiap workspaces[].path ialah tepat apa yang diambil oleh workspace.import sebagai source_path. Itu memang disengajakan: “memulihkan ruang kerja ini daripada snapshot ini” ialah operasi import, jadi kedua-duanya tidak boleh terpesong menjadi layanan yang berbeza terhadap fail yang sama.

Pengesahan workspace.import

Sebelum apa-apa diganti, fail calon dibuka dalam mod baca sahaja dengan sambungan SQLite mentah yang berumur pendek dan baris workspace_meta-nya dibaca.

Keadaan	Hasil
Bukan pangkalan data SQLite yang boleh dibaca, atau tiada workspace_meta	Ditolak. Tiada apa-apa disentuh
Id ruang kerja yang direkodkan ≠ sasaran	Dibenarkan, direkodkan dalam log. Beginilah ruang kerja diduplikasi atau dipulihkan dengan id baharu
Id pemasangan yang direkodkan ≠ pemasangan ini	Dibenarkan, direkodkan dalam log. Peranti berganding dan id penggunanya milik pemasangan itu dan tidak akan diselesaikan di sini
Id ruang kerja tidak sah, atau fail tidak wujud	Ditolak

Setelah diterima, pangkalan data ruang kerja sasaran ditutup dan digugurkan daripada pengurus sebelum fail disalin menimpanya (sambungan drift yang terbuka memegang fail itu dan -wal-nya), kemudian dibuka semula supaya beforeOpen memasang semula pencetus FTS dan penyegerakan, dan indeks FTS dibina semula — jadual kandungan fail yang diimport diisi tetapi indeksnya mungkin sudah basi.

Laluan pemindahan

Setiap operasi di atas bercakap dalam laluan sisi pelayan, yang merupakan jawapan lengkap hanya apabila pelayan itu mesin anda sendiri. Ketiga-tiga laluan ini membawa bait, pada jalur bertandatangan PSK yang sama yang digunakan oleh proksi media dan stor blob. Pemanggil menandatangani rentetan sasaran dengan kunci pra-kongsi perantinya dan menghantar tandatangan itu sebagai s.

Laluan	Kaedah	Pertanyaan	Sasaran bertandatangan	Memerlukan
/backup/workspace	GET	w, d, s	backup-workspace:<workspaceId>	Pentadbir ruang kerja
/backup/snapshot	GET	n, d, s	backup-snapshot:<name>	Pemilik pemasangan
/backup/restore	POST	w, d, s	backup-restore:<workspaceId>	Pemilik ruang kerja

w ialah id ruang kerja, n nama direktori snapshot, d id peranti pemanggil, s tandatangannya. n diselesaikan terhadap penyenaraian sandaran dan bukannya dicantumkan pada akar sandaran, jadi laluan itu tidak boleh dihalakan ke direktori yang tidak akan ditunjukkan oleh penyenaraian.

Status	Punca
400	Parameter pertanyaan yang diperlukan hilang, atau badan muat naik kosong
403	Peranti tidak dikenali atau dibatalkan, tandatangan tidak sah, atau pemanggil tiada peranan itu
404	Tiada port sandaran pada hos ini, atau snapshot/fail ruang kerja yang dinamakan tidak wujud
405	/backup/restore dipanggil dengan apa-apa selain POST
413	Badan muat naik melebihi 8 GiB, sama ada mengikut content-length yang diisytiharkan atau bait yang benar-benar dibaca
500	Eksport atau arkib gagal di sisi pelayan

Kedua-dua muat turun membalas Cache-Control: no-store dengan Accept-Ranges: none. Setiap permintaan menempa salinan baharu dan memadamkannya selepas dialirkan, jadi respons yang dicache atau disambung semula akan menyambung bait daripada dua eksport berbeza menjadi satu fail yang kelihatan sah tetapi sebenarnya tidak.

/backup/snapshot memulangkan <name>.zip, dengan entri relatif kepada akar snapshot supaya membuka bungkusan menghasilkan semula manifest.json + global.db + <workspaceId>/workspace.db. Entri ditulis dalam susunan terisih, jadi dua arkib bagi snapshot yang sama ialah arkib yang sama.

/backup/restore mengalirkan badan terus ke fail pementasan dan bukan menyangganya, membatasinya sebelum dan semasa pembacaan, dan memadam fail yang dipentaskan pada setiap laluan keluar termasuk penolakan.

Sambungan yang direlai tiada origin HTTP

Relai yang diperantarakan membawa bingkai RPC, bukan pemindahan fail. Segala yang bercakap dalam laluan sisi pelayan terus berfungsi melaluinya; ketiga-tiga laluan pemindahan memerlukan sambungan langsung, dan UI menyahdayakannya dengan nota dan bukannya gagal di pertengahan muat turun.

Laluan dan had

Perkara	Nilai
Snapshot	<dataDir>/backups/<timestamp>/
Sandaran ruang kerja berjadual	<dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db
Eksport ruang kerja	<dataDir>/backups/exports/<workspaceId>-<timestamp>.db
Pementasan pemindahan	<dataDir>/backups/transfer/ — meja kerja, disapu oleh laluan yang menulisnya
Nama arkib snapshot	<snapshot directory name>.zip
Had muat naik	8 GiB per POST /backup/restore
Pengekalan	Snapshot pemasangan: pemadaman manual. Sandaran ruang kerja: pipeline mingguan, lalai 30 hari

Direktori exports/, transfer/, dan workspace-backups/ bukan snapshot pemasangan dan dikecualikan daripada server.listBackups. Hanya direktori terakhir yang mempunyai pengekalan berjadual; memadam snapshot pemasangan memerlukan tindakan eksplisit pemilik pemasangan.

Lihat juga

• Sandarkan dan pulihkan — resipi tempat operasi ini berada
• Ruang kerja dan pengasingan — mengapa satu ruang kerja ialah satu fail
• CLI cc_server — direktori data tempat laluan ini berada
• Peta laluan — tempat UI berada
• Seni bina — pemisahan klien/pelayan yang diikuti laluan ini