גיבוי, ייצוא וייבוא

כל מה ש-Control Center יכול להעתיק, למסור או לאמץ, והצורה המדויקת של כל ארטיפקט. כדי ליצור גיבוי בפועל, ראו גיבוי ושחזור; ולהסבר מדוע הנתונים נשמרים באופן מפוצל כזה, ראו סביבות עבודה ובידוד.

ארטיפקטים

ישנם שלושה ארטיפקטים של העתקת מסד נתונים, עם היקפים ומדיניות מחיקה שונים.

ארטיפקט	נכתב על ידי	צורה	מכסה
תמונת מצב של ההתקנה	server.backupNow	תיקייה עם חותמת זמן	כל מסד נתונים בהתקנה
גיבוי של סביבת עבודה	פייפליין Workspace backup	תיקייה עם חותמת זמן ובה קובץ .db אחד	מסד הנתונים של סביבת עבודה אחת
ייצוא של סביבת עבודה	workspace.export	קובץ .db בודד	מסד הנתונים של סביבת עבודה אחת

כולם נכתבים עם VACUUM INTO של SQLite, שהוא בטוח מול מסד נתונים חי במצב WAL: הוא מבצע טרנזקציית קריאה, מפיק עותק מגובב ועקבי מבחינה טרנזקציונית, ולעולם אינו דורש לעצור את השרת.

מבנה תמונת המצב

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

המבנה משקף בדיוק את ספריית הנתונים החיה, וזה מה שהופך שחזור התקנה להעתקה בחזרה ולא לתרגום. שם התיקייה הוא חותמת הזמן של UTC כשהתווים : ו-. הוחלפו ב--, כך שהוא בטוח למערכת הקבצים ב-Windows וממוין כרונולוגית כמחרוזת רגילה.

גיבויים מתוזמנים של סביבות עבודה יושבים בנפרד ב- <dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. הם אינם כוללים מניפסט או global.db ואינם תמונות מצב של ההתקנה. שלב השימור של הפייפליין השבועי מסיר רק גיבויים של סביבת העבודה שלו עצמו הישנים מהגיל שהוגדר לו (30 ימים כברירת מחדל); תמונות מצב של ההתקנה שנוצרו ידנית לעולם אינן נמחקות בשלב הזה. server.listBackups מציג רק תמונות מצב של ההתקנה, כולל חלקיות.

manifest.json

שדה	סוג	משמעות
version	int	גרסת מבנה המניפסט. כעת 1
created_at	ISO-8601 UTC	מתי נוצרה תמונת המצב
global.file	string	תמיד global.db
global.schema_version	int	גרסת הסכימה של GlobalDatabase בעת הלכידה
global.bytes	int	הגודל של global.db שנכתב
workspace_schema_version	int	גרסת הסכימה של WorkspaceDatabase המשותפת לכל קובץ סביבת עבודה
workspaces[]	array	רשומה אחת לכל סביבת עבודה שנלכדה
workspaces[].workspace_id	string	סביבת העבודה שהקובץ הזה מחזיק
workspaces[].file	string	נתיב יחסי לשורש תמונת המצב, <workspaceId>/workspace.db
workspaces[].bytes	int	הגודל של אותו קובץ
skipped_workspaces[]	array of string	סביבות עבודה שהגיבוי לא הצליח ללכוד

סביבת עבודה מדולגת כשהרישום שלה קיים אבל מעולם לא נכתב אליה (ולכן אין עדיין קובץ), או כשה-VACUUM INTO שלה נכשל. כך או כך, תמונת המצב עדיין מושלמת והמניפסט מציין מה חסר.

שלמות

server.listBackups מדווח על דגל complete לכל תמונת מצב. הוא שקרי כשהמניפסט חסר או שאינו ניתן לפענוח, כשחסר global.db, או כשהמניפסט מציין קובץ סביבת עבודה שאינו על הדיסק.

תמונת מצב חלקית עדיין מוצגת ברשימה, כי תמונת מצב שמפעיל אינו רואה היא תמונה שהוא מאמין שיש לו. כשאין אפשרות לקרוא את המניפסט, הרשימה נופלת חזרה אל המבנה עצמו ומדווחת על כל קובצי <workspaceId>/workspace.db שהיא מוצאת — אלה נשארים ניתנים לאימוץ בנפרד דרך workspace.import, אף שתמונת המצב כולה אינה יכולה לשחזר התקנה.

מה גיבוי אינו כולל

שני הארטיפקטים הם מסדי נתונים בלבד. תיקיית סביבת עבודה מחזיקה יותר ממסד הנתונים שלה, ושום דבר מהשאר אינו נכלל:

נתיב	בתמונת מצב?	בייצוא של סביבת עבודה?
global.db	כן	לא
<workspaceId>/workspace.db	כן	כן (הוא הוא הקובץ)
<workspaceId>/blobs/	לא	לא
<workspaceId>/skills/	לא	לא
<workspaceId>/agents/	לא	לא
<workspaceId>/chat_credentials/	לא	לא
<workspaceId>/spaces/<spaceId>/	לא	לא
<workspaceId>/pr_clones/	לא	לא
secrets.json	לא	לא
models/	לא	לא
meetings/<meetingId>/	לא	לא
rigs/	לא	לא

חלק מזה חד־פעמי — spaces/ מחזיק עצי עבודה בהעתקה בעת כתיבה שמסופקים מחדש מהמאגרים, pr_clones/ הוא מטמון, models/ מורד מחדש, rigs/ הוא מצב מכונה. וחלק מזה אינו חד־פעמי: blobs/ מחזיק תמונות שהודבקו ושורות במסד הנתונים מצביעות אליהן, skills/ ו-agents/ מחזיקים את הקבצים שאיתם סוכן רץ, ו-secrets.json מחזיק כל מפתח שיוך, פרטי גישה של ספק והגדרת SSO בהתקנה. ראו גיבוי ושחזור לכיסוי השאר.

אסימוני צ’אט נשארים מאחור במכוון

העובדה ש-chat_credentials/ יושב לצד מסד הנתונים ולא בתוכו היא הסיבה שסביבת עבודה שנמסרת למישהו אחר אינה נושאת אסימוני בוט חיים. ראו את עזר גשר הצ’אט.

פעולות

קריאות ה-RPC לגיבוי ההתקנה ולייצוא/ייבוא של סביבת עבודה זמינות ל-fullClient בלבד: טלפון משויך אינו יכול להפעיל אותן. כולן נעדרות לחלוטין — לא נדחות, אלא חסרות מבנית — בשרת שבו לא מחובר פורט גיבוי, כמו שרת ההדגמה.

פעולה	סוג	היקף	תפקיד מזערי	ארגומנטים	מחזיר
server.backupNow	שינוי	התקנה	בעלים של ההתקנה	אין	{ok, path}
server.listBackups	קריאה	התקנה	בעלים של ההתקנה	אין	{backups: [...]}
server.deleteBackup	שינוי	התקנה	בעלים של ההתקנה	name	{ok}
workspace.export	קריאה	סביבת עבודה	admin	אין	{ok, path}
workspace.import	שינוי	סביבת עבודה	owner	source_path	{ok, workspace_id}
workspace.delete	שינוי	התקנה*	owner	id	שורת רישום מסומנת כמחוקה

• workspace.delete אינו מוגבל בהיקף כי השורה שהוא מסמן נמצאת ברישום הגלובלי; המטפל שלו בודק את החברות של הקורא בסביבת העבודה הנקובה ומצריך owner.

path בכל תגובה הוא נתיב על מארח השרת.

תמונת מצב של התקנה שלמה מוגנת בבעלים בשני המסלולים

server.backupNow, server.listBackups ו-server.deleteBackup דורשים את הבעלים של ההתקנה (ServerAuthority.serverOwner), אותו שער בדיוק כמו GET /backup/snapshot. תמונת מצב לוכדת את מסד הנתונים של כל סביבת עבודה, ולכן היותכם מנהלים של סביבת עבודה אחת אינו מספיק כדי לנהל את האחרות. המחיקה מקבלת רק את שם תיקיית חותמת הזמן מהרשימה, ולא נתיב שרירותי בשרת, ומסירה את תמונת המצב כולה (כולל תמונות מצב חלקיות). ייצוא/ייבוא ברמת סביבת עבודה נשארים אצל מנהל/בעלים של סביבת העבודה, ולא אצל בעלים של ההתקנה.

התגובה של server.listBackups

החדשה ביותר תחילה, ממוין לפי שם התיקייה (שהוא חותמת הזמן, ולכן הסדר תקף גם לתמונת מצב שאי אפשר היה לקרוא את המניפסט שלה).

{
  "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 מושמט כשאי אפשר היה לקרוא את המניפסט. bytes ברמה העליונה הוא הגודל האמיתי בדיסק של התיקייה כולה, ולא הסכום של המניפסט עצמו — השאלה שמפעיל שמנקה תמונות מצב שואל היא כמה התיקייה עולה, ולא מה הגיבוי התכוון לכתוב.

כל workspaces[].path הוא בדיוק מה ש-workspace.import מקבל בתור source_path. זה מכוון: “שחזרו את סביבת העבודה הזו מתמונת המצב הזו” הוא פעולת הייבוא, ולכן השניים אינם יכולים להיפרד לטיפולים שונים באותו קובץ.

האימות של workspace.import

לפני שמשהו מוחלף, הקובץ המועמד נפתח לקריאה בלבד עם חיבור SQLite גולמי קצר־מועד ונקראת שורת ה-workspace_meta שלו.

תנאי	תוצאה
לא מסד נתונים קריא של SQLite, או שאין workspace_meta	נדחה. לא נוגעים בדבר
מזהה סביבת העבודה הרשום ≠ היעד	מותר, נרשם ביומן. כך משכפלים סביבת עבודה או משחזרים אותה תחת מזהה חדש
מזהה ההתקנה הרשום ≠ ההתקנה הזו	מותר, נרשם ביומן. המכשירים המשויכים ומזהי המשתמשים שלו שייכים לאותה התקנה ולא יפתרו כאן
מזהה סביבת עבודה שגוי, או שהקובץ אינו קיים	נדחה

עם הקבלה, מסד הנתונים של סביבת העבודה היעד נסגר ומוסר מהמנהל לפני שהקובץ מועתק עליו (חיבור drift פתוח מחזיק את הקובץ ואת ה--wal שלו), ואז נפתח מחדש כדי ש-beforeOpen יתקין מחדש את טריגרי ה-FTS והסנכרון, ואינדקסי ה-FTS נבנים מחדש — טבלאות התוכן של קובץ מיובא מאוכלסות, אבל האינדקס שלו עשוי להיות מיושן.

נתיבי העברה

כל פעולה שלמעלה מדברת בנתיבים בצד השרת, וזו תשובה מלאה רק כשהשרת הוא המכונה שלכם. שלושת אלה מעבירים את הבתים, על אותו מסלול חתום ב-PSK שבו משתמשים פרוקסי המדיה ומאגר ה-blobs. הקורא חותם על מחרוזת יעד עם מפתח הצימוד של המכשיר שלו ומעביר את החתימה בתור s.

נתיב	מתודה	שאילתה	יעד חתום	דורש
/backup/workspace	GET	w, d, s	backup-workspace:<workspaceId>	מנהל של סביבת עבודה
/backup/snapshot	GET	n, d, s	backup-snapshot:<name>	בעלים של ההתקנה
/backup/restore	POST	w, d, s	backup-restore:<workspaceId>	בעלים של סביבת עבודה

w הוא מזהה סביבת עבודה, n הוא שם תיקייה של תמונת מצב, d הוא מזהה המכשיר הקורא, ו-s הוא החתימה. n נפתר מול רשימת הגיבויים ולא מצורף לשורש הגיבויים, ולכן לא ניתן לכוון את הנתיב לתיקייה שהרשימה לא הייתה מציגה.

סטטוס	סיבה
400	פרמטר שאילתה נדרש חסר, או שגוף ההעלאה ריק
403	מכשיר לא מוכר או מבוטל, חתימה שגויה, או שלקורא חסר התפקיד
404	אין פורט גיבוי במארח הזה, או שתמונת המצב/קובץ סביבת העבודה הנקוב אינו קיים
405	/backup/restore נקרא עם כל דבר מלבד POST
413	גוף ההעלאה עולה על 8 GiB, לפי content-length המוצהר או לפי הבתים שנקראו בפועל
500	הייצוא או הארכיון נכשלו בצד השרת

שתי ההורדות מגיבות ב-Cache-Control: no-store עם Accept-Ranges: none. כל בקשה מנפיקה עותק חדש ומוחקת אותו לאחר הזרמתו, ולכן תגובה שנשמרה במטמון או שחודשה הייתה מלחימה בתים משני ייצואים שונים לקובץ אחד שנראה תקין ואינו כזה.

/backup/snapshot מחזיר <name>.zip, עם רשומות יחסיות לשורש תמונת המצב כך שפריסה משחזרת manifest.json + global.db + <workspaceId>/workspace.db. הרשומות נכתבות בסדר ממוין, ולכן שני ארכיונים של אותה תמונת מצב הם אותו ארכיון.

/backup/restore מזרים את הגוף ישירות לקובץ ביניים במקום לאגור אותו בזיכרון, מגביל אותו לפני הקריאה ובמהלכה, ומוחק את קובץ הביניים בכל נתיב יציאה, כולל דחייה.

לחיבור דרך ממסר אין מקור HTTP

הממסר המתווך מעביר מסגרות RPC ולא העברות קבצים. כל מה שמדבר בנתיבים בצד השרת ממשיך לעבוד דרכו; שלושת נתיבי ההעברה דורשים חיבור ישיר, וה-UI משבית אותם עם הערה במקום להיכשל באמצע ההורדה.

נתיבים ומגבלות

דבר	ערך
תמונות מצב	<dataDir>/backups/<timestamp>/
גיבויים מתוזמנים של סביבות עבודה	<dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db
ייצואים של סביבות עבודה	<dataDir>/backups/exports/<workspaceId>-<timestamp>.db
אחסון ביניים להעברות	<dataDir>/backups/transfer/ — שולחן עבודה, שמנוקה על ידי הנתיב שכותב אליו
שם הארכיון של תמונת מצב	<snapshot directory name>.zip
תקרת ההעלאה	8 GiB לכל POST /backup/restore
שימור	תמונות מצב של ההתקנה: מחיקה ידנית. גיבויים של סביבות עבודה: פייפליין שבועי, ברירת מחדל של 30 ימים

התיקיות exports/, transfer/ ו-workspace-backups/ אינן תמונות מצב של ההתקנה והן מוחרגות מ-server.listBackups. רק לתיקייה האחרונה יש שימור מתוזמן; מחיקת תמונת מצב של ההתקנה דורשת פעולה מפורשת של בעלי ההתקנה.

ראו גם

• גיבוי ושחזור — המתכונים שהפעולות האלה שייכות להם
• סביבות עבודה ובידוד — למה סביבת עבודה אחת היא קובץ אחד
• cc_server CLI — ספריית הנתונים שהנתיבים האלה יושבים בה
• מפת נתיבים — היכן שה-UI נמצא
• ארכיטקטורה — פיצול הלקוח/שרת שהנתיבים הולכים לפיו