Yedekleme, dışa ve içe aktarma

Control Center’ın kopyalayabileceği, devredebileceği ya da devralabileceği her şey ve her yapıtın tam biçimi. Gerçekten bir yedek almak için Yedekleme ve geri yükleme sayfasına bakın; kalıcılığın neden bu şekilde bölündüğünü görmek için de Çalışma alanları ve yalıtım.

Yapıtlar

Farklı kapsamlara ve silme politikalarına sahip üç veritabanı kopyası yapıtı vardır.

Yapıt	Yazan	Biçim	Kapsadığı
Kurulum anlık görüntüsü	server.backupNow	Zaman damgalı bir dizin	Kurulumdaki her veritabanı
Çalışma alanı yedeği	Workspace backup pipeline’ı	Tek .db içeren zaman damgalı dizin	Bir çalışma alanının veritabanı
Çalışma alanı dışa aktarımı	workspace.export	Tek bir .db dosyası	Bir çalışma alanının veritabanı

Hepsi SQLite VACUUM INTO ile yazılır; bu, canlı bir WAL veritabanına karşı güvenlidir: bir okuma işlemi alır, parçalanması giderilmiş ve işlemsel olarak tutarlı bir kopya üretir ve sunucunun durdurulmasını hiçbir zaman gerektirmez.

Anlık görüntü düzeni

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

Düzen, canlı veri dizinini tam olarak yansıtır; bir kurulumu geri yüklemeyi bir çeviriye değil, geri kopyalamaya dönüştüren de budur. Dizin adı, : ve . karakterleri - ile değiştirilmiş UTC zaman damgasıdır; böylece Windows’ta dosya sistemi açısından güvenlidir ve düz bir dize olarak kronolojik sıralanır.

Zamanlanmış çalışma alanı yedekleri ayrı bir yerde, <dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db yolunda yaşar. Bir manifest ya da global.db içermezler ve kurulum anlık görüntüsü değildirler. Haftalık pipeline’ın saklama adımı, yalnızca kendi çalışma alanının yapılandırılmış yaşından (varsayılan olarak 30 gün) eski yedeklerini kaldırır; elle oluşturulan kurulum anlık görüntüleri o adım tarafından hiçbir zaman rotasyona tabi tutulmaz. server.listBackups yalnızca kurulum anlık görüntülerini listeler, eksik olanlar dahil.

manifest.json

Alan	Tür	Anlamı
version	int	Manifest biçim sürümü. Şu anda 1
created_at	ISO-8601 UTC	Anlık görüntünün alındığı zaman
global.file	string	Her zaman global.db
global.schema_version	int	Yakalama anındaki GlobalDatabase şema sürümü
global.bytes	int	Yazılan global.db dosyasının boyutu
workspace_schema_version	int	Her çalışma alanı dosyasında ortak olan WorkspaceDatabase şema sürümü
workspaces[]	array	Yakalanan her çalışma alanı için bir girdi
workspaces[].workspace_id	string	Bu dosyanın tuttuğu çalışma alanı
workspaces[].file	string	Anlık görüntü köküne göre yol, <workspaceId>/workspace.db
workspaces[].bytes	int	O dosyanın boyutu
skipped_workspaces[]	array of string	Yedeğin yakalayamadığı çalışma alanları

Bir çalışma alanı, kayıtlı olduğu hâlde hiç yazılmamışsa (yani henüz bir dosya yoksa) ya da VACUUM INTO işlemi başarısız olduysa atlanır. Her iki durumda da anlık görüntü yine tamamlanır ve manifest neyin eksik olduğunu adlandırır.

Tamlık

server.listBackups her anlık görüntü için bir complete bayrağı bildirir. Bu bayrak, manifest yoksa ya da ayrıştırılamıyorsa, global.db eksikse veya manifest diskte olmayan bir çalışma alanı dosyasını adlandırıyorsa false olur.

Eksik bir anlık görüntü yine de listelenir; çünkü bir operatörün göremediği bir anlık görüntü, sahip olduğuna inandığı anlık görüntüdür. Manifest okunamadığında liste, düzenin kendisine geri düşer ve bulduğu <workspaceId>/workspace.db dosyalarını bildirir — anlık görüntü bir bütün olarak bir kurulumu geri yükleyemese de bunlar workspace.import üzerinden tek tek sahiplenilebilir.

Bir yedeğin içermedikleri

Her iki yapıt da yalnızca veritabanlarıdır. Bir çalışma alanı dizini veritabanından fazlasını tutar ve geri kalanın hiçbiri taşınmaz:

Yol	Anlık görüntüde?	Çalışma alanı dışa aktarımında?
global.db	Evet	Hayır
<workspaceId>/workspace.db	Evet	Evet (dosyanın kendisi odur)
<workspaceId>/blobs/	Hayır	Hayır
<workspaceId>/skills/	Hayır	Hayır
<workspaceId>/agents/	Hayır	Hayır
<workspaceId>/chat_credentials/	Hayır	Hayır
<workspaceId>/spaces/<spaceId>/	Hayır	Hayır
<workspaceId>/pr_clones/	Hayır	Hayır
secrets.json	Hayır	Hayır
models/	Hayır	Hayır
meetings/<meetingId>/	Hayır	Hayır
rigs/	Hayır	Hayır

Bunun bir kısmı gözden çıkarılabilir — spaces/ depolar üzerinden yeniden sağlanan kopyala-üzerine-yaz çalışma ağaçlarını tutar, pr_clones/ bir önbellektir, models/ yeniden indirilir, rigs/ makine durumudur. Bir kısmı ise değildir: blobs/ veritabanındaki satırların işaret ettiği yapıştırılmış görselleri tutar, skills/ ve agents/ bir ajanın çalıştığı dosyaları tutar ve secrets.json kurulumdaki her eşleme anahtarını, sağlayıcı kimlik bilgisini ve SSO ayarını tutar. Geri kalanı kapsamak için Yedekleme ve geri yükleme sayfasına bakın.

Sohbet token’ları bilinçli olarak geride kalır

chat_credentials/ dizininin veritabanının içinde değil de yanında durması, başkasına devredilen bir çalışma alanının canlı bot token’ı taşımamasının nedenidir. Sohbet köprüsü referansına bakın.

İşlemler

Kurulum yedekleme RPC’leri ile çalışma alanı dışa/içe aktarma yalnızca fullClient içindir: eşlenmiş bir telefon bunları tetikleyemez. Demo sunucu gibi yedekleme portu bağlanmamış bir sunucuda ise bunların tümü tamamen yoktur — reddedilmezler, yapısal olarak eksiktirler.

İşlem	Tür	Kapsam	Asgari rol	Argümanlar	Döndürdüğü
server.backupNow	mutate	Kurulum	kurulum sahibi	yok	{ok, path}
server.listBackups	read	Kurulum	kurulum sahibi	yok	{backups: [...]}
server.deleteBackup	mutate	Kurulum	kurulum sahibi	name	{ok}
workspace.export	read	Çalışma alanı	admin	yok	{ok, path}
workspace.import	mutate	Çalışma alanı	owner	source_path	{ok, workspace_id}
workspace.delete	mutate	Kurulum*	owner	id	kayıt defteri satırı silinmiş olarak işaretlenir

• workspace.delete kapsamsızdır; çünkü işaretlediği satır genel kayıt defterinde yaşar. İşleyicisi, çağıranın adı geçen çalışma alanındaki üyeliğini denetler ve owner gerektirir.

Her yanıttaki path, sunucu makinesindeki bir yoldur.

Tüm kurulumun anlık görüntüsü her iki hatta da sahip kapısından geçer

server.backupNow, server.listBackups ve server.deleteBackup, GET /backup/snapshot ile aynı kapıdan, yani kurulum sahibi (ServerAuthority.serverOwner) koşulundan geçer. Bir anlık görüntü her çalışma alanının veritabanını yakalar; dolayısıyla bir çalışma alanının yöneticisi olmak diğerlerini yönetmeye yetmez. Silme, rastgele bir sunucu yolunu değil, yalnızca listede görünen zaman damgalı dizin adını kabul eder ve anlık görüntünün tamamını (eksik olanlar dahil) kaldırır. Çalışma alanı başına dışa/içe aktarma, kurulum sahibinde değil, çalışma alanı yöneticisi/sahibinde kalır.

server.listBackups yanıtı

En yeniden en eskiye doğru, dizin adına göre sıralanır (bu da zaman damgası olduğundan, sıralama manifesti okunamayan bir anlık görüntü için bile geçerli kalır).

{
  "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": []
    }
  ]
}

Manifest okunamadığında created_at atlanır. En üst düzeydeki bytes, manifestin kendi toplamı değil, dizinin tamamının diskteki gerçek boyutudur — anlık görüntüleri budayan bir operatörün sorduğu soru, dizinin ne kadar yer kapladığıdır; yedeğin ne yazmayı amaçladığı değil.

Her workspaces[].path, workspace.import işleminin source_path olarak aldığı şeyin tam kendisidir. Bu bilinçlidir: “bu çalışma alanını bu anlık görüntüden geri yükle” içe aktarma işleminin ta kendisidir; böylece ikisi aynı dosyaya yönelik farklı davranışlara sapamaz.

workspace.import doğrulaması

Herhangi bir şeyin yerine yenisi konmadan önce, aday dosya kısa ömürlü ham bir SQLite bağlantısıyla salt okunur olarak açılır ve workspace_meta satırı okunur.

Koşul	Sonuç
Okunabilir bir SQLite veritabanı değil ya da workspace_meta yok	Reddedilir. Hiçbir şeye dokunulmaz
Kayıtlı çalışma alanı kimliği ≠ hedef	İzin verilir, günlüğe yazılır. Bir çalışma alanı yeni bir kimlik altında böyle çoğaltılır ya da geri yüklenir
Kayıtlı kurulum kimliği ≠ bu kurulum	İzin verilir, günlüğe yazılır. Eşlenmiş cihazları ve kullanıcı kimlikleri o kuruluma aittir ve burada çözümlenmez
Geçersiz çalışma alanı kimliği ya da dosya yok	Reddedilir

Kabul edildiğinde, hedef çalışma alanının veritabanı kapatılır ve dosya üzerine kopyalanmadan önce yöneticiden düşürülür (açık bir drift bağlantısı dosyayı ve -wal dosyasını tutar); ardından beforeOpen FTS ve senkronizasyon tetikleyicilerini yeniden kursun diye yeniden açılır ve FTS dizinleri yeniden oluşturulur — içe aktarılan bir dosyanın içerik tabloları doludur ama dizini eskimiş olabilir.

Aktarım rotaları

Yukarıdaki her işlem sunucu tarafındaki yollarla konuşur; bu da yalnızca sunucu kendi makinenizse eksiksiz bir yanıttır. Aşağıdaki üç rota, medya proxy’sinin ve blob deposunun zaten kullandığı aynı PSK imzalı hat üzerinden baytları taşır. Çağıran, hedef dizeyi cihazının ön paylaşımlı anahtarıyla imzalar ve imzayı s olarak geçirir.

Rota	Yöntem	Sorgu	İmzalanan hedef	Gerektirdiği
/backup/workspace	GET	w, d, s	backup-workspace:<workspaceId>	Çalışma alanı yöneticisi
/backup/snapshot	GET	n, d, s	backup-snapshot:<name>	Kurulum sahibi
/backup/restore	POST	w, d, s	backup-restore:<workspaceId>	Çalışma alanı sahibi

w bir çalışma alanı kimliği, n bir anlık görüntü dizini adı, d çağıran cihazın kimliği, s ise imzadır. n, yedekleme köküne eklenmek yerine yedekleme listesine karşı çözümlenir; böylece rota, listenin göstermeyeceği bir dizine yöneltilemez.

Durum	Neden
400	Gerekli bir sorgu parametresi eksik ya da bir yükleme gövdesi boş
403	Bilinmeyen ya da iptal edilmiş cihaz, hatalı imza veya çağıranda gerekli rolün olmaması
404	Bu makinede yedekleme portu yok ya da adı geçen anlık görüntü/çalışma alanı dosyası mevcut değil
405	/backup/restore rotasının POST dışında bir yöntemle çağrılması
413	Yükleme gövdesinin, bildirilen content-length’e göre ya da gerçekte okunan baytlara göre 8 GiB’ı aşması
500	Dışa aktarma ya da arşivleme sunucu tarafında başarısız oldu

Her iki indirme de Cache-Control: no-store ve Accept-Ranges: none ile yanıt verir. Her istek yeni bir kopya üretir ve akıtıldıktan sonra onu siler; dolayısıyla önbelleğe alınmış ya da kaldığı yerden devam eden bir yanıt, iki farklı dışa aktarımın baytlarını geçerli görünen ama geçerli olmayan tek bir dosyada birleştirirdi.

/backup/snapshot, <name>.zip döndürür; girdiler anlık görüntü köküne göre göreli olduğundan arşivi açmak manifest.json + global.db + <workspaceId>/workspace.db yapısını yeniden üretir. Girdiler sıralı olarak yazılır; böylece aynı anlık görüntünün iki arşivi aynı arşivdir.

/backup/restore, gövdeyi arabelleğe almak yerine doğrudan bir hazırlama dosyasına akıtır, okuma öncesinde ve sırasında boyutunu sınırlar ve hazırlanan dosyayı bir ret dahil her çıkış yolunda siler.

Aktarılan bir bağlantının HTTP kaynağı yoktur

Aracılı aktarım hattı dosya transferlerini değil, RPC çerçevelerini taşır. Sunucu tarafı yollarla konuşan her şey onun üzerinden çalışmaya devam eder; üç aktarım rotası doğrudan bir bağlantı gerektirir ve arayüz, indirmenin ortasında başarısız olmak yerine onları nedenini söyleyen bir notla devre dışı bırakır.

Yollar ve sınırlar

Öğe	Değer
Anlık görüntüler	<dataDir>/backups/<timestamp>/
Zamanlanmış çalışma alanı yedekleri	<dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db
Çalışma alanı dışa aktarımları	<dataDir>/backups/exports/<workspaceId>-<timestamp>.db
Aktarım hazırlama	<dataDir>/backups/transfer/ — bir çalışma tezgâhı; onu yazan rota tarafından süpürülür
Anlık görüntü arşiv adı	<snapshot directory name>.zip
Yükleme üst sınırı	POST /backup/restore başına 8 GiB
Saklama	Kurulum anlık görüntüleri: elle silme. Çalışma alanı yedekleri: haftalık pipeline, varsayılan 30 gün

exports/, transfer/ ve workspace-backups/ dizinleri kurulum anlık görüntüsü değildir ve server.listBackups dışında tutulur. Zamanlanmış saklama yalnızca son dizin için geçerlidir; bir kurulum anlık görüntüsünü silmek, kurulum sahibinin açık eylemini gerektirir.

Ayrıca bakınız

• Yedekleme ve geri yükleme — bu işlemlerin ait olduğu tarifler
• Çalışma alanları ve yalıtım — bir çalışma alanı neden tek bir dosyadır
• cc_server CLI — bu yolların içinde bulunduğu veri dizini
• Rota haritası — arayüzün yaşadığı yer
• Mimari — yolların izlediği istemci/sunucu bölünmesi