پشتیبان‌گیری و بازیابی

این راهنما پنج کاری را پوشش می‌دهد که مردم واقعاً با پشتیبان‌ها انجام می‌دهند: گرفتن یکی، جمع‌کردنش، جابه‌جا کردن یک فضای کاری، برگرداندن یکی، و نگه‌داشتن رونوشت‌ها بیرون از ماشین. برای شکل دقیق هر آرتیفکت و عملیات، مرجع پشتیبان‌گیری را ببینید.

همه‌چیز اینجا زیر تنظیمات → سرور → پشتیبان و بازیابی قرار دارد.

پیش‌نیازها

• یک کلاینت کامل — اپ دسکتاپ یا وب. یک تلفن جفت‌شده به‌طور عامدانه هیچ‌یک از این کارها را نمی‌تواند راه بیندازد.
• برای گرفتن، فهرست کردن، دانلود یا حذف یک اسنپ‌شات نصب: مالک نصب.
• برای کارهای هر فضای کاری: ادمین آن فضای کاری برای برون‌بری، مالک برای درون‌بری یا حذف آن.
• برای دانلود و آپلود: یک اتصال مستقیم به سرور. رلهٔ واسطه فریم‌های RPC را حمل می‌کند، نه انتقال فایل، و کنترل‌های انتقال وقتی روی یکی از آن‌ها هستید خودشان را با یک یادداشت غیرفعال می‌کنند.

اسنپ‌شات‌های نصب دستی‌اند

پشتیبان همین حالا همچنان فقط بنا به درخواست، اسنپ‌شاتی از کل نصب می‌سازد. پایپ‌لاین توکار Workspace backup می‌تواند به‌جای آن هفته‌ای یک‌بار از پایگاه دادهٔ یک فضای کاری پشتیبان بگیرد و پشتیبان‌های آن فضای کاری را که از 30 روز قدیمی‌ترند بردارد. global.db، فضاهای کاری دیگر، یا فایل‌های کنار پایگاه داده را کپی نمی‌کند. رونوشت‌های بیرون از ماشین را جداگانه نگه دارید.

یک پشتیبان چه چیزی را پوشش می‌دهد

هر دو آرتیفکت فقط پایگاه داده هستند:

• یک اسنپ‌شات نصب یک پوشهٔ زمان‌دار است: manifest.json، global.db و یک <workspaceId>/workspace.db به‌ازای هر فضای کاری.
• یک برون‌بری فضای کاری همان تک‌فایل workspace.db است.

هیچ‌یک بقیهٔ پوشهٔ داده را حمل نمی‌کند: secrets.json (کلیدهای جفت‌سازی، اعتبارنامه‌های ارائه‌دهنده، SSO)، blobs/ یک فضای کاری (تصاویر جای‌گذاری‌شده در پیام‌ها)، skills/، agents/، chat_credentials/، صدای ضبط‌شدهٔ جلسه یا تصاویر ریگ. بخشی از آن یک‌بارمصرف است و بخشی نه — جدول کامل در مرجع است، و پوشش دادنش همان چیزی است که بخش بیرون از ماشین برای آن هست.

از کل نصب اسنپ‌شات گرفتن

1. تنظیمات → سرور → پشتیبان و بازیابی را باز کنید.
2. زیر اسنپ‌شات نصب، پشتیبان همین حالا را بزنید.
3. اعلان، پوشه‌ای را که روی میزبان سرور نوشته شده نام می‌برد. اسنپ‌شات جدید در بالای فهرست ظاهر می‌شود.

سرور در تمام این مدت روشن می‌ماند. هر فایل با VACUUM INTO نوشته می‌شود که در برابر یک پایگاه دادهٔ زنده سازگار است، پس نه پنجرهٔ نگهداری‌ای وجود دارد و نه نیازی به متوقف کردن عامل‌ها.

هر ردیف در فهرست، برچسب زمانی، اندازه روی دیسک، شمار فضاهای کاری ثبت‌شده و اینکه اسنپ‌شات کامل است یا ناقص را نشان می‌دهد. ناقص یعنی مانیفست گم است یا فایل‌هایی را نام می‌برد که آنجا نیستند — پشتیبانی که با یک کرش یا پر شدن دیسک نیمه‌کاره مانده. این‌ها به‌عمد همچنان فهرست می‌شوند: اسنپ‌شاتی که نمی‌بینید، همانی است که باور دارید داریدش. یک اسنپ‌شات ناقص نمی‌تواند کل نصب را بازیابی کند، اما فایل‌های فضای کاری که در خود دارد همچنان می‌توانند یکی‌یکی پذیرفته شوند.

یک ردیف ممکن است n فضاهای کاری ثبت نشد هم بگوید. آن یک فضای کاری است که ثبت شده اما هرگز چیزی در آن نوشته نشده (هنوز فایلی نیست)، یا یکی که کپی‌اش شکست خورده — لاگ سرور را بررسی کنید.

زمان‌بندی پشتیبان‌گیری از فضاهای کاری و نگه‌داشت

برای فضای کاری، تنظیمات → پایپ‌لاین‌ها → قالب‌های پایپ‌لاین را باز کنید و Workspace backup را پیدا کنید. زمان‌بندی فعال‌ش هر یکشنبه ساعت 03:00 UTC اجرا می‌شود: Back up workspace، و پس از آن Delete backups older than (به‌طور پیش‌فرض 30 روز). گرهٔ دوم فقط پس از موفق شدن پشتیبان اجرا می‌شود. می‌توانید روزهای نگه‌داشت را روی گره عوض کنید یا زمان‌بندی را غیرفعال کنید. اگر سرور در زمان مقرر آفلاین باشد، زمان‌بندی هنگام برگشتن یک‌بار جبران می‌کند، نه اینکه هر هفتهٔ ازدست‌رفته را بازپخش کند.

پشتیبان‌های فضای کاری روی سرور زیر backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db زندگی می‌کنند. گرهٔ نگه‌داشت فقط پشتیبان‌های قدیمی همین فضای کاری را حذف می‌کند؛ هرگز اسنپ‌شات‌های نصب یا پشتیبان‌های فضاهای کاری دیگر را حذف نمی‌کند. این فایل‌ها فقط پایگاه داده‌اند. برای نگه‌داشت بیرون از ماشین، آن‌ها را مستقل کپی کنید.

این پشتیبان‌ها از فهرست اسنپ‌شات نصب جدا هستند. برای بازیابی یکی، از دادهٔ فضای کاری → ورود با مسیر سمت سرور workspace.db آن پشتیبان استفاده کنید. ورود، پایگاه دادهٔ کنونی آن فضای کاری را جایگزین می‌کند، پس اگر ممکن است نیاز به برگرداندن بازیابی داشته باشید، اول آن را برون‌بری کنید.

حذف یک اسنپ‌شات نصب

زیر اسنپ‌شات نصب، اسنپ‌شات را باز کنید — از جمله یک اسنپ‌شات ناقص — و از حذف اسنپ‌شات در بخش خطر استفاده کنید. نامش را تأیید کنید. کل پوشهٔ اسنپ‌شات برای همیشه از سرور حذف می‌شود؛ اگر به یک رونوشت نیاز دارید، اول دانلودش کنید. پایپ‌لاین پشتیبان‌گیری فضای کاری هرگز این اسنپ‌شات‌ها را حذف نمی‌کند.

جمع کردن یک رونوشت روی ماشین خودتان

مسیرهایی که صفحه نشان می‌دهد روی ماشینی هستند که cc_server را اجرا می‌کند. وقتی آن ماشینی نیست که شما کنارش نشسته‌اید، از دکمه‌های دانلود استفاده کنید:

• کنار هر فضای کاری زیر دادهٔ فضای کاری → دانلود، برای یک فایل .db.
• کنار هر اسنپ‌شات زیر اسنپ‌شات نصب → دانلود، برای کل اسنپ‌شات به‌شکل یک .zip.

روی دسکتاپ شما انتخاب می‌کنید فایل کجا فرود بیاید و اعلان نامش را می‌برد؛ روی وب به دانلودهای مرورگر می‌رود. در هر دو حالت، هر دو پیشرفت را با بایت گزارش می‌کنند، چون این‌ها دو باری هستند که به گیگابایت می‌رسند.

هر دو، در همان لحظه‌ای که دکمه را می‌زنید یک نسخهٔ تازه ضرب می‌کنند، آن را استریم می‌کنند، و رونوشت سرور را بعدش پاک می‌کنند — دانلود یعنی «همان فایلی را بگیر که دکمهٔ برون‌بری پیش‌تر ساخت» نیست.

باز کردن یک آرشیو اسنپ‌شات، چیدمان اسنپ‌شات را دقیقاً بازتولید می‌کند، و همین است که بازیابی آن را به یک کپی به عقب تبدیل می‌کند.

جابه‌جا کردن یک فضای کاری به نصبی دیگر

یک فضای کاری یک فایل پایگاه داده است، پس دست‌به‌دست کردنش یک عملیات فایل است.

1. روی سرور مبدأ، تنظیمات → سرور → پشتیبان و بازیابی → دادهٔ فضای کاری، فضای کاری را باز کنید و دانلود را بزنید.
2. روی سرور مقصد، فضای کاری‌ای را که آن را می‌پذیرد بسازید (یا انتخاب کنید).
3. آن فضای کاری را باز کنید، و زیر بازیابی از این دستگاه انتخاب فایل و آپلود را بزنید. همان .db را که دانلود کردید انتخاب کنید.

اگر هر دو سرور همان ماشینی هستند که کنارش نشسته‌اید، ذخیره روی سرور به‌همراه ورود → انتخاب فایل همین کار را بدون رفت‌وبرگشت انجام می‌دهد؛ مسیرهای پنجرهٔ درون‌بری روی میزبان سرور حل می‌شوند.

درون‌بری همه چیز را جایگزین می‌کند

درون‌بری هر چیزی را که فضای کاری هدف هم‌اکنون در خود دارد بازنویسی می‌کند و برگشت‌ناپذیر است. اگر هدف چیزی دارد که ممکن است بخواهید برگردانید، اول آن را برون‌بری کنید.

دو چیز مجاز است و به‌جای رد شدن ثبت می‌شود: درون‌بری فایلی که شناسهٔ فضای کاری ثبت‌شده‌اش با هدف فرق دارد (این همان راهی است که یک فضای کاری را تکثیر می‌کنید یا زیر شناسه‌ای تازه بازیابی می‌کنید)، و درون‌بری فایلی از یک نصب دیگر. در حالت دوم، دستگاه‌های جفت‌شده و شناسه‌های کاربری آن فایل به نصبی تعلق دارند که از آن آمده و روی این نصب حل نمی‌شوند — دادهٔ خود فضای کاری دست‌نخورده است، اما پس از پذیرفتنش عضویت را دوباره بررسی کنید.

توکن‌های ربات گفتگو کنار پایگاه داده زندگی می‌کنند، نه درونش، پس فضای کاری‌ای که به کسی دیگر می‌دهید هیچ اعتبارنامهٔ زنده‌ای حمل نمی‌کند. نصب گیرنده، مال خودش را دوباره وصل می‌کند.

بازیابی یک فضای کاری از یک اسنپ‌شات

1. زیر اسنپ‌شات نصب، اسنپ‌شاتی را که می‌خواهید باز کنید.
2. ردیف آن فضای کاری را پیدا کنید و بازیابی را بزنید.
3. تأیید کنید. هر کاری که آن فضای کاری از زمان گرفتن اسنپ‌شات کرده از دست می‌رود.

این همان عملیاتی است که یک درون‌بری، فقط نشانه‌رفته به رونوشت آن فایل فضای کاری در اسنپ‌شات — عامدانه، تا هیچ سازوکار دومی نباشد که بتواند همان فایل را متفاوت رفتار کند.

یک ردیف ممکن است دیگر روی این سرور نیست بگوید، با بازیابی غیرفعال: اسنپ‌شات فضای کاری‌ای را در خود دارد که این نصب دیگر ندارد. دستی برگردانیدش — یک فضای کاری بسازید، سپس زیر دادهٔ فضای کاری از <snapshot path>/<old workspace id>/workspace.db درون آن درون‌بری کنید. اسنپ‌شات بازشده مسیر روی سرور خودش را در یک فیلد کپی‌شدنی نشان می‌دهد، و عنوان ردیف، شناسهٔ فضای کاری قدیمی است، پس هر دو نیمهٔ آن مسیر را پیش رویتان دارید.

بازیابی کل نصب

دکمه‌ای برای این کار نیست، و نباید هم باشد: پایگاه‌های داده‌ای را که سرور در حال اجرا باز نگه داشته جایگزین می‌کند.

1. cc_server را متوقف کنید. اگر اپ دسکتاپ را با سرور درون‌سازش اجرا می‌کنید، اپ را ببندید.

2. محتوای اسنپ‌شات را روی پوشهٔ داده کپی کنید. چیدمان اسنپ‌شات آینهٔ چیدمان زنده است، پس این یک کپی ساده است:

   # 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. هر فایل -wal و -shm را که کنار پایگاه‌های دادهٔ جایگزین‌شده نشسته‌اند حذف کنید. آن‌ها به فایل‌های قدیمی تعلق دارند و ماندن یک فایل کهنه کنار یک پایگاه دادهٔ بازیابی‌شده خطر خرابی است.

4. سرور را دوباره شروع کنید.

اسنپ‌شات هیچ secrets.json ندارد، پس نصبی که روی میزبانی تازه بازیابی شود داده‌اش را نگه می‌دارد اما اعتبارنامه‌هایش را نه: دستگاه‌های جفت‌شده، توکن‌های ارائه‌دهنده و تنظیمات SSO باید از نو برقرار شوند، یا از همان‌جایی که آن فایل را نگه داشتید بازیابی شوند. بازیابی روی همان میزبان، جایی که secrets.json هرگز از دست نرفته، همه‌چیز را نگه می‌دارد.

کپی کردن پشتیبان‌ها بیرون از ماشین

یک اسنپ‌شات روی همان دیسکی که پایگاه دادهٔ کپی‌شده‌اش هست، شما را از یک درون‌بری بد محافظت می‌کند، نه از خود دیسک. هیچ‌چیز در Control Center رونوشتی جایی نمی‌فرستد، پس این بخش کار خودتان است.

همگام‌سازی اسنپ‌شات‌ها

اسنپ‌شات‌ها پس از نوشته شدن تغییرناپذیرند و با برچسب زمانی نام‌گذاری می‌شوند، پس هر ابزار همگام‌سازی خوب از عهده‌شان برمی‌آید. transfer/ را کنار بگذارید، که کارگاهی برای دانلود و آپلودهای در جریان است:

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 هرس محلی شما را به مقصد آینه می‌کند. اگر می‌خواهید مقصد اسنپ‌شات‌ها را بیشتر از میزبان نگه دارد، برش دارید.

هرگز پایگاه‌های دادهٔ زنده را مستقیم همگام نکنید

تا وقتی سرور در حال اجراست، rsync، aws s3 sync یا یک عامل پشتیبان‌گیری فایل‌محور را به global.db یا <workspaceId>/workspace.db نشانه نگیرید. یک پایگاه دادهٔ زندهٔ SQLite یک فایل جانبی -wal دارد، و یک کپی فایل‌به‌فایل آن دو را در دو لحظهٔ متفاوت ثبت می‌کند — نتیجه فایلی است که اغلب باز می‌شود و بی‌صدا نوشتن‌های اخیر را ندارد، یا اصلاً باز نمی‌شود. از اسنپ‌شات کپی کنید، که زیر یک تراکنش خواندن نوشته شده است، یا یکی با VACUUM INTO مطابق زیر بگیرید.

گنجاندن آنچه یک اسنپ‌شات جا می‌گذارد

برای اینکه بتوانید نصب را بازسازی کنید نه فقط داده‌اش را، این‌ها را هم کپی کنید. فایل‌های معمولی‌اند و کپی کردنشان وقتی سرور در حال اجراست ایمن است:

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 با مجوز 0600 است و هر کلید جفت‌سازی، اعتبارنامهٔ ارائه‌دهنده و تنظیم SSO روی نصب را در خود دارد. هر جا فرود بیاید باید دست‌کم به‌اندازهٔ میزبان سرور محافظت شود — رمزنگاری‌شده در حالت سکون، و نه سطلی که کس دیگری بتواند بخواند.

spaces/ (worktreeهای copy-on-write، که از مخزن‌های شما از نو تأمین می‌شوند)، pr_clones/ (یک کش)، models/ (از نو دانلود می‌شوند)، media_cache/ و rigs/ (وضعیت ماشین، و بزرگ) را کنار بگذارید. صدای ضبط‌شدهٔ جلسه زیر meetings/ اگر جلسه نگه می‌دارید ارزش گنجاندن دارد.

زمان‌بندی اسنپ‌شات کل نصب بیرون از اپ

پایپ‌لاین توکار فقط از یک فضای کاری پشتیبان می‌گیرد. برای یک اسنپ‌شات کل نصب بی‌سرپرست، هیچ زیرفرمان CLI وجود ندارد، و RPC اسنپ‌شات به یک کلاینت کامل جفت‌شده نیاز دارد که مالک نصب باشد. یک زمان‌سنج سمت میزبان می‌تواند VACUUM INTO را روی پایگاه‌های دادهٔ زنده به کار ببرد:

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

آن را با همان کاربری اجرا کنید که مالک پوشهٔ داده است، از cron یا یک زمان‌سنج systemd، و بعدش DEST را از میزبان بیرون همگام کنید. VACUUM INTO به SQLite نسخهٔ 3.27 یا تازه‌تر نیاز دارد.

آن را بیرون از <dataDir>/backups/ بنویسید. یک پوشهٔ دست‌ساز آنجا هیچ manifest.json ندارد، پس اپ آن را به‌عنوان یک اسنپ‌شات ناقص فهرست می‌کند و فهرست دیگر رکورد صادقانه‌ای از آنچه خود سرور تولید کرده نخواهد بود.

هرس اسنپ‌شات‌های قدیمی کل نصب

می‌توانید اسنپ‌شات‌های نصب را یکی‌یکی در اپ حذف کنید. برای یک سیاست نگه‌داشت سمت میزبان، پوشهٔ پشتیبان فضای کاری را از اسنپ‌شات‌های نصب جدا نگه دارید:

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

پیش از افزودن -exec، خروجی یک اجرای -print را بررسی کنید. بیش از یکی نگه دارید: خرابی‌ای که در برابر آن محافظت می‌کنید اغلب «آخرین پشتیبان هم همان مشکل را دارد» است.

بررسی خوب بودن یک پشتیبان

پشتیبانی که هیچ‌کس بازیابی‌اش نکرده، یک فرضیه است.

بررسی ارزان — فایل باز می‌شود و صفحه‌هایش سالماند:

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

بررسی واقعی — بپذیریدش. روی یک نصب غیرتولیدی یک فضای کاری آزمایشی بسازید، یک فایل فضای کاری درون آن درون‌بری کنید، و ببینید آیا فضاها، تیکت‌ها و پیام‌هایی که انتظار دارید آنجا هستند. این همان مسیری را می‌آزماید که یک بازیابی واقعی می‌پیماید، از جمله بازسازی FTS، و تنها بررسی‌ای است که به شما می‌گوید پشتیبان قابل بازیابی است نه فقط خواندنی.

این کار را یک‌بار وقتی پشتیبان‌ها را راه می‌اندازید انجام دهید، و هر بار که جایی را که ذخیره می‌شوند عوض می‌کنید باز هم.

عیب‌یابی

نشانه	علت و راه‌حل
کنترل‌های دانلود و آپلود با یادداشتی دربارهٔ رله غیرفعال‌اند	شما از رلهٔ واسطه وصل شده‌اید، که انتقال فایل ندارد. مستقیم وصل شوید
«سرور رد کرد»	نقش. گرفتن یا فهرست کردن اسنپ‌شات نصب به اپراتور نصب نیاز دارد. دانلود یک فضای کاری به ادمین نیاز دارد، بازیابی یکی به مالک، و زیپ کل اسنپ‌شات به اپراتور نصب
«این سرور سطح پشتیبانی ندارد»	میزبان هیچ دروازهٔ پشتیبان‌گیری سیم‌کشی‌شده‌ای ندارد — یک سرور دمو. عملیات‌ها به‌جای رد شدن، غایب‌اند
«فایل بزرگ‌تر از پذیرش سرور است»	آپلودها روی 8 GiB سقف دارند. فایل را روی میزبان سرور بگذارید و به‌جایش از ورود → انتخاب فایل استفاده کنید
درون‌بری رد شد: پایگاه دادهٔ فضای کاری Control Center نیست	فایل هیچ سطر workspace_meta ندارد — برون‌بری یک فضای کاری نیست، یا بریده شده است. هیچ‌چیز جایگزین نشد
یک اسنپ‌شات ناقص فهرست شده است	مانیفستش گم است یا فایل‌های غایب را نام می‌برد. یکی تازه بگیرید؛ در این فاصله فایل‌های تک‌تک فضاهای کاری را از آن بپذیرید
یک اسنپ‌شات می‌گوید فضاهای کاری ثبت نشدند	آن فضاهای کاری هرگز چیزی در آن‌ها نوشته نشده، یا کپی‌شان شکست خورده. لاگ سرور را بررسی کنید
یک نصب بازیابی‌شده اعتبارنامهٔ میزبان کد یا SSO ندارد	secrets.json در اسنپ‌شات نیست. از همان‌جایی که نگهش داشتید بازیابی‌اش کنید، یا ارائه‌دهنده‌ها را دوباره وصل کنید
یک فضای کاری بازیابی‌شده تصاویر جای‌گذاری‌شده را ندارد	بلاب‌ها کنار پایگاه داده زندگی می‌کنند، نه درونش. <workspaceId>/blobs/ را هم کپی کنید

راهنماهای مرتبط

• اجرای سرور بدون رابط: پوشهٔ داده از کجا می‌آید
• اتصال به سرور راه دور: اتصال‌های مستقیم در برابر رله‌شده
• جفت‌کردن دستگاه: اعتبارنامه‌ای که مسیرهای انتقال با آن امضا می‌کنند

مفاهیم و مرجع مرتبط

• پشتیبان‌گیری، برون‌بری و درون‌بری: هر عملیات، مسیر، فیلد و محدودیت
• فضاهای کاری و ایزوله‌سازی: چرا یک فضای کاری یک فایل است
• cc_server CLI: چیدمان پوشهٔ داده