Yedekleme ve geri yükleme

Bu kılavuz, yedeklerle gerçekte yapılan beş şeyi ele alır: yedek almak, yedeği toplamak, bir çalışma alanını taşımak, bir yedeği geri koymak ve kopyaları makinenin dışında tutmak. Her yapıtın ve işlemin tam biçimi için yedekleme başvurusuna bakın.

Buradaki her şey Ayarlar → Sunucu → Yedekleme ve geri yükleme altında yer alır.

Ön koşullar

• Tam bir istemci — masaüstü ya da web uygulaması. Eşleştirilmiş bir telefon bunların hiçbirini tetikleyemez; bu tasarım gereğidir.
• Kurulum anlık görüntüsü almak, listelemek, indirmek veya silmek için: kurulumun sahibi.
• Çalışma alanı başına işlemler için: dışa aktarmak üzere o çalışma alanının yöneticisi, içe aktarmak veya silmek üzere sahibi.
• İndirmeler ve yüklemeler için: sunucuya doğrudan bir bağlantı. Aracılı relay, RPC çerçeveleri taşır, dosya aktarımı taşımaz; böyle bir bağlantıdayken aktarım denetimleri kendilerini bir notla birlikte devre dışı bırakır.

Kurulum anlık görüntüleri elle alınır

Şimdi yedekle yalnızca istendiğinde tüm kurulumun anlık görüntüsünü oluşturur. Yerleşik Workspace backup işlem hattı ise haftada bir çalışma alanı veritabanı yedeği alabilir ve o çalışma alanının 30 günden eski yedeklerini silebilir. global.db dosyasını, diğer çalışma alanlarını veya veritabanının yanındaki dosyaları kopyalamaz. Makine dışı kopyaları ayrıca tutun.

Yedek neleri kapsar

Her iki yapıt da yalnızca veritabanıdır:

• Kurulum anlık görüntüsü, zaman damgalı bir dizindir: manifest.json, global.db ve her çalışma alanı için bir <workspaceId>/workspace.db.
• Çalışma alanı dışa aktarımı ise tek bir workspace.db dosyasıdır.

İkisi de veri dizininin geri kalanını taşımaz: secrets.json (eşleştirme anahtarları, sağlayıcı kimlik bilgileri, SSO), bir çalışma alanının blobs/ dizini (iletilere yapıştırılan görseller), skills/, agents/, chat_credentials/, kaydedilmiş toplantı sesleri veya rig imajları. Bunların bir kısmı gözden çıkarılabilir, bir kısmı değil — tam tablo başvuruda yer alır ve bunları kapsamak makine dışı bölümünün işidir.

Tüm kurulumun anlık görüntüsünü alın

1. Ayarlar → Sunucu → Yedekleme ve geri yükleme bölümünü açın.
2. Kurulum anlık görüntüleri altında Şimdi yedekle’ye basın.
3. Bildirim, sunucu makinesinde yazılan dizinin adını söyler. Yeni anlık görüntü listenin en üstünde görünür.

Sunucu bu sırada çalışmaya devam eder. Her dosya, canlı bir veritabanına karşı tutarlı olan VACUUM INTO ile yazılır; bu yüzden bakım penceresi yoktur ve ajanları durdurmaya gerek yoktur.

Listedeki her satır zaman damgasını, diskteki boyutu, kaç çalışma alanının yakalandığını ve anlık görüntünün Tamamlandı mı yoksa Eksik mi olduğunu gösterir. Eksik, manifestin bulunmadığı veya olmayan dosyaları adlandırdığı anlamına gelir — bir çökme ya da dolu bir disk yüzünden kesilen bir yedek. Bunlar bilerek listelenir: göremediğiniz bir anlık görüntü, sahip olduğunuzu sandığınız anlık görüntüdür. Eksik bir anlık görüntü tüm kurulumu geri yükleyemez, ancak elinde bulunan çalışma alanı dosyaları yine tek tek devralınabilir.

Bir satırda n çalışma alanı yakalanmadı da yazabilir. Bu, kayıtlı ama hiç yazılmamış bir çalışma alanıdır (henüz dosyası yoktur) ya da kopyası başarısız olmuştur — sunucu günlüğüne bakın.

Çalışma alanı yedeklerini ve saklama süresini zamanlayın

Çalışma alanı için Ayarlar → Pipelines → Pipeline şablonları bölümünü açın ve Workspace backup şablonunu bulun. Etkin zamanlaması her Pazar 03:00 UTC’de çalışır: önce Back up workspace, ardından Delete backups older than (varsayılan olarak 30 gün). İkinci düğüm yalnızca yedekleme başarılı olduktan sonra çalışır. Düğümdeki saklama gün sayısını değiştirebilir ya da zamanlamayı devre dışı bırakabilirsiniz. Sunucu zamanlanan saatte çevrimdışıysa, zamanlama geri geldiğinde kaçırılan her haftayı yeniden oynatmak yerine bir kez yetişir.

Çalışma alanı yedekleri sunucuda backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db altında bulunur. Saklama düğümü yalnızca bu çalışma alanının eski yedeklerini siler; kurulum anlık görüntülerini veya başka çalışma alanlarının yedeklerini asla silmez. Bu dosyalar yalnızca veritabanıdır. Makine dışında saklamak için bunları ayrıca kopyalayın.

Bu yedekler Kurulum anlık görüntüleri listesinden ayrıdır. Birini geri yüklemek için Çalışma alanı verisi → İçe aktar yolunu, yedeğin sunucudaki workspace.db yoluyla kullanın. İçe aktarma, o çalışma alanının mevcut veritabanını değiştirir; geri yüklemeyi geri almanız gerekebilecekse önce onu dışa aktarın.

Kurulum anlık görüntüsünü silme

Kurulum anlık görüntüleri altında, eksik olanlar dahil, anlık görüntüyü genişletin ve tehlike bölümündeki Anlık görüntüyü sil seçeneğini kullanın. Adını doğrulayın. Anlık görüntü dizininin tamamı sunucudan kalıcı olarak kaldırılır; bir kopyaya ihtiyacınız varsa önce indirin. Çalışma alanı yedekleme işlem hattı bu anlık görüntüleri asla silmez.

Kendi makinenizde bir kopya edinin

Sayfada gösterilen yollar cc_server çalıştıran makinededir. Bulunduğunuz makine o değilse İndir düğmelerini kullanın:

• Çalışma alanı verisi altında her çalışma alanının yanındaki İndir, tek bir .db dosyası içindir.
• Kurulum anlık görüntüleri altında her anlık görüntünün yanındaki İndir, anlık görüntünün tamamını bir .zip olarak verir.

Masaüstünde dosyanın nereye ineceğini siz seçersiniz ve bildirim adını söyler; web’de dosya tarayıcının indirmelerine gider. Her iki durumda da ilerleme bayt cinsinden bildirilir, çünkü bunlar gigabaytlara varan iki yüktür.

İkisi de düğmeye bastığınız anda yeni bir kopya oluşturur, onu akış halinde gönderir ve ardından sunucudaki kopyayı siler — indirme, “dışa aktarma düğmesinin daha önce oluşturduğu dosyayı getirmek” değildir.

Bir anlık görüntü arşivini açmak, anlık görüntü düzenini tam olarak yeniden oluşturur; onu geri yüklemeyi düz bir geri kopyalama yapan da budur.

Bir çalışma alanını başka bir kuruluma taşıma

Bir çalışma alanı tek bir veritabanı dosyasıdır; bu yüzden devretmek bir dosya işlemidir.

1. Kaynak sunucuda Ayarlar → Sunucu → Yedekleme ve geri yükleme → Çalışma alanı verisi bölümünde çalışma alanını genişletin ve İndir’e basın.
2. Hedef sunucuda, dosyayı alacak çalışma alanını oluşturun (veya seçin).
3. O çalışma alanını genişletin ve Bu aygıttan geri yükle altında Bir dosya seçin ve yükleyin’e basın. İndirdiğiniz .db dosyasını seçin.

Her iki sunucu da bulunduğunuz makineyse, Sunucuya kaydet ve ardından İçe aktar → Dosya seç aynı şeyi gidiş dönüş olmadan yapar; içe aktarma iletişim kutusundaki yollar sunucu makinesinde çözülür.

İçe aktarma her şeyin üzerine yazar

İçe aktarma, hedef çalışma alanının şu anda barındırdığı her şeyin üzerine yazar ve geri alınamaz. Geri isteme ihtimaliniz olan bir şey barındırıyorsa önce hedefi dışa aktarın.

İki şeye izin verilir ve reddedilmek yerine günlüğe yazılır: kayıtlı çalışma alanı kimliği hedeften farklı olan bir dosyayı içe aktarmak (bir çalışma alanını bu şekilde çoğaltır ya da yeni bir kimlik altında geri yüklersiniz) ve farklı bir kurulumdan gelen bir dosyayı içe aktarmak. İkinci durumda dosyanın eşleştirilmiş aygıtları ve kullanıcı kimlikleri geldiği kuruluma aittir ve bu kurulumda çözülmez — çalışma alanının kendi verisi sağlamdır, ancak devraldıktan sonra üyeliği yeniden kontrol edin.

Sohbet botu token’ları veritabanının içinde değil yanında bulunur; bu yüzden başkasına devrettiğiniz çalışma alanı canlı kimlik bilgisi taşımaz. Dosyayı alan kurulum kendi kimlik bilgilerini yeniden bağlar.

Bir çalışma alanını anlık görüntüden geri yükleme

1. Kurulum anlık görüntüleri altında istediğiniz anlık görüntüyü genişletin.
2. Çalışma alanının satırını bulun ve Geri yükle’ye basın.
3. Onaylayın. Anlık görüntü alındığından beri o çalışma alanının yaptığı her şey kaybolur.

Bu, içe aktarmayla aynı işlemdir; yalnızca o çalışma alanının dosyasının anlık görüntüdeki kopyasını hedefler — bilerek böyle, aynı dosyayı farklı ele alabilecek ikinci bir mekanizma olmasın diye.

Bir satırda Artık bu sunucuda yok yazabilir ve Geri yükle devre dışı olabilir: anlık görüntü, bu kurulumun artık sahip olmadığı bir çalışma alanını barındırıyordur. Onu elle geri getirin — bir çalışma alanı oluşturun, ardından Çalışma alanı verisi altında <snapshot path>/<old workspace id>/workspace.db yolundan içine aktarın. Genişletilmiş anlık görüntü kendi Sunucudaki yol değerini kopyalanabilir bir alanda gösterir ve satırın başlığı eski çalışma alanı kimliğidir; böylece o yolun iki yarısı da önünüzde olur.

Tüm kurulumu geri yükleme

Bunun için bir düğme yok ve olmamalı da: çalışan sunucunun açık tuttuğu veritabanlarının yerine geçer.

1. cc_server’ı durdurun. Masaüstü uygulamasını gömülü sunucusuyla çalıştırıyorsanız uygulamadan çıkın.

2. Anlık görüntünün içeriğini veri dizininin üzerine kopyalayın. Anlık görüntü düzeni canlı düzeni yansıtır, dolayısıyla bu düz bir kopyalamadır:

   # 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. Değiştirdiğiniz veritabanlarının yanında duran -wal ve -shm dosyalarını silin. Bunlar eski dosyalara aittir ve geri yüklenen bir veritabanının yanındaki eskimiş bir dosya bozulma riskidir.

4. Sunucuyu yeniden başlatın.

Anlık görüntüde secrets.json yoktur; bu yüzden yeni bir makineye geri yüklenen kurulum verisini korur ama kimlik bilgilerini korumaz: eşleştirilmiş aygıtlar, sağlayıcı token’ları ve SSO ayarları yeniden kurulmalı ya da o dosyayı sakladığınız yerden geri yüklenmelidir. secrets.json dosyasının hiç kaybolmadığı aynı makineye geri yükleme her şeyi korur.

Yedekleri makinenin dışına kopyalama

Kopyaladığı veritabanıyla aynı diskte duran bir anlık görüntü sizi hatalı bir içe aktarmadan korur, diskten korumaz. Control Center’da hiçbir şey bir kopyayı başka bir yere göndermez; bu kısım size kalır.

Anlık görüntüleri eşitleme

Anlık görüntüler yazıldıktan sonra değişmez ve zaman damgasıyla adlandırılır; bu yüzden herhangi bir eşitleme aracı onlarla iyi baş eder. Devam eden indirme ve yüklemeler için bir tezgah olan transfer/ dizinini hariç tutun:

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, yereldeki budamanızı uzak tarafa yansıtır. Uzak tarafın anlık görüntüleri makineden daha uzun süre tutmasını istiyorsanız bunu kaldırın.

Canlı veritabanlarını asla doğrudan eşitlemeyin

Sunucu çalışırken rsync’i, aws s3 sync’i veya dosya düzeyinde bir yedekleme aracını global.db ya da <workspaceId>/workspace.db üzerine yöneltmeyin. Canlı bir SQLite veritabanının bir -wal eşlik dosyası vardır ve dosya dosya kopyalama ikisini farklı anlarda yakalar — sonuç, çoğu zaman açılan ama son yazmaları sessizce eksik olan ya da hiç açılmayan bir dosyadır. Bir okuma işlemi altında yazılan anlık görüntüyü kopyalayın veya aşağıdaki gibi VACUUM INTO ile bir tane alın.

Anlık görüntünün dışarıda bıraktıklarını dahil edin

Kurulumu yalnızca verisiyle değil bütünüyle yeniden kurabilmek için bunları da kopyalayın. Bunlar sıradan dosyalardır; sunucu çalışırken kopyalanmaları güvenlidir:

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 dosyasının izinleri 0600’dür ve kurulumdaki her eşleştirme anahtarını, sağlayıcı kimlik bilgisini ve SSO ayarını barındırır. Gittiği yer en az sunucu makinesi kadar korunmalıdır — durağan halde şifreli olmalı ve başkalarının okuyabileceği bir bucket olmamalıdır.

spaces/ (copy-on-write çalışma ağaçları, depolarınızdan yeniden oluşturulur), pr_clones/ (bir önbellek), models/ (yeniden indirilir), media_cache/ ve rigs/ (makine durumu ve büyük) dizinlerini atlayın. Toplantı tutuyorsanız meetings/ altındaki kayıtlı toplantı seslerini dahil etmeye değer.

Uygulama dışında tüm kurulumun anlık görüntüsünü zamanlayın

Yerleşik işlem hattı yalnızca bir çalışma alanını yedekler. Gözetimsiz bir tüm kurulum anlık görüntüsü için bir CLI alt komutu yoktur ve anlık görüntü RPC’si, kurulumun sahibi olan eşleştirilmiş bir tam istemci gerektirir. Makine tarafındaki bir zamanlayıcı, canlı veritabanlarına karşı VACUUM INTO kullanabilir:

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

Bunu veri dizininin sahibi olan kullanıcıyla, cron’dan ya da bir systemd zamanlayıcısından çalıştırın ve ardından DEST dizinini makinenin dışına eşitleyin. VACUUM INTO için SQLite 3.27 veya daha yeni bir sürüm gerekir.

Bunu <dataDir>/backups/ dizininin dışına yazın. Orada elle oluşturulmuş bir dizinde manifest.json bulunmaz; uygulama onu eksik bir anlık görüntü olarak listeler ve liste, sunucunun kendisinin ürettiklerinin dürüst kaydı olmaktan çıkar.

Eski tüm kurulum anlık görüntülerini budama

Tek tek kurulum anlık görüntülerini uygulamada silebilirsiniz. Makine tarafında bir saklama ilkesi için çalışma alanı yedek dizinini kurulum anlık görüntülerinden ayrı tutun:

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

-exec eklemeden önce bir -print çalıştırmasının çıktısını kontrol edin. Birden fazla yedek tutun: korunmaya çalıştığınız arıza çoğu zaman “son yedekte de aynı sorun var”dır.

Yedeğin sağlam olduğunu kontrol etme

Kimsenin geri yüklemediği bir yedek bir varsayımdır.

Ucuz kontrol — dosya açılıyor ve sayfaları sağlam:

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

Gerçek kontrol — onu devralın. Üretim dışı bir kurulumda geçici bir çalışma alanı oluşturun, içine bir çalışma alanı dosyası aktarın ve beklediğiniz alanların, biletlerin ve iletilerin orada olup olmadığına bakın. Bu, FTS yeniden oluşturma dahil, gerçek bir geri yüklemenin izlediği yolun aynısını çalıştırır ve yedeğin yalnızca okunabilir değil geri yüklenebilir olduğunu söyleyen tek kontroldür.

Bunu yedekleri kurduğunuzda bir kez, saklandıkları yeri her değiştirdiğinizde de yeniden yapın.

Sorun giderme

Belirti	Neden ve çözüm
İndirme ve yükleme denetimleri, relay’le ilgili bir notla devre dışı	Aracılı relay üzerinden bağlısınız ve bu relay dosya aktarımı taşımaz. Doğrudan bağlanın
“Sunucu reddetti”	Rol. Kurulum anlık görüntüsü almak veya listelemek kurulumun operatörünü gerektirir. Bir çalışma alanını indirmek yönetici rolünü, geri yüklemek sahip rolünü, tüm bir anlık görüntü zip’i kurulumun operatörünü gerektirir
“Bu sunucuda yedekleme yüzeyi yok”	Makinede yedekleme portu bağlı değil — bir demo sunucusu. İşlemler reddedilmek yerine yoktur
“Dosya, sunucunun kabul ettiğinden büyük”	Yüklemeler 8 GiB ile sınırlıdır. Dosyayı sunucu makinesine koyun ve bunun yerine İçe aktar → Dosya seç kullanın
Import refused: not a Control Center workspace database	Dosyada workspace_meta satırı yok — bu bir çalışma alanı dışa aktarımı değil veya dosya kesilmiş. Hiçbir şey değiştirilmedi
Bir anlık görüntü Eksik olarak listelenir	Manifesti eksik ya da olmayan dosyaları adlandırıyor. Yeni bir tane alın; bu arada ondan tek tek çalışma alanı dosyalarını devralın
Bir anlık görüntü, bazı çalışma alanlarının yakalanmadığını söyler	O çalışma alanlarına hiç yazılmamıştır veya kopyaları başarısız olmuştur. Sunucu günlüğüne bakın
Geri yüklenen bir kurulumda forge veya SSO kimlik bilgisi yok	secrets.json bir anlık görüntüde yer almaz. Onu sakladığınız yerden geri yükleyin veya sağlayıcıları yeniden bağlayın
Geri yüklenen bir çalışma alanında yapıştırılan görseller eksik	Blob’lar veritabanının içinde değil yanında bulunur. <workspaceId>/blobs/ dizinini de kopyalayın

İlgili kılavuzlar

• Headless bir sunucu çalıştırma: veri dizininin nereden geldiği
• Uzak bir sunucuya bağlanma: doğrudan ve relay üzerinden bağlantılar
• Bir cihaz eşleştirme: aktarım rotalarının imzaladığı kimlik bilgisi

İlgili kavramlar ve başvuru

• Yedekleme, dışa ve içe aktarma: her işlem, rota, alan ve sınır
• Çalışma alanları ve yalıtım: bir çalışma alanı neden tek bir dosyadır
• cc_server CLI: veri dizini düzeni