Mentés, exportálás és importálás

Minden, amit a Control Center másolni, átadni vagy átvenni képes, és az egyes artefaktumok pontos felépítése. Ha ténylegesen biztonsági mentést készítene, lásd a Mentés és visszaállítás oldalt; arról, hogy miért oszlik meg így az adatmegőrzés, a Munkaterületek és elszigetelés oldalon olvashat.

Artefaktumok

Három adatbázist másoló artefaktum létezik, eltérő hatókörrel és törlési szabályzattal.

Artefaktum	Ki írja	Forma	Mit fed le
Telepítési pillanatkép	server.backupNow	Időbélyeggel ellátott könyvtár	A telepítés minden adatbázisa
Munkaterület-mentés	Workspace backup pipeline	Időbélyeggel ellátott könyvtár egyetlen .db fájllal	Egy munkaterület adatbázisa
Munkaterület-export	workspace.export	Egyetlen .db fájl	Egy munkaterület adatbázisa

Mindegyik SQLite VACUUM INTO utasítással íródik, amely egy futó WAL-adatbázissal szemben is biztonságos: olvasási tranzakciót indít, töredezettségmentesített és tranzakcionálisan konzisztens másolatot készít, és soha nem teszi szükségessé a szerver leállítását.

A pillanatkép felépítése

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

A felépítés pontosan tükrözi az élő adatkönyvtárat, és éppen ez teszi egy telepítés visszaállítását visszamásolássá, nem pedig átalakítássá. A könyvtárnév az UTC-időbélyeg, amelyben a : és a . helyére - kerül, így fájlrendszer-biztos Windows alatt, és egyszerű szövegként is kronologikusan rendeződik.

Az ütemezett munkaterület-mentések külön helyen élnek: <dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Nem tartalmaznak manifestet és global.db-t, és nem telepítési pillanatképek. A heti pipeline megőrzési lépése csak a saját munkaterületének a beállított életkornál (alapértelmezésben 30 napnál) régebbi mentéseit törli; a kézzel készített telepítési pillanatképeket ez a lépés soha nem törli. A server.listBackups csak telepítési pillanatképeket listáz, a hiányosakat is beleértve.

manifest.json

Mező	Típus	Jelentés
version	egész szám	A manifest formátumverziója. Jelenleg 1
created_at	ISO-8601 UTC	A pillanatkép készítésének időpontja
global.file	karakterlánc	Mindig global.db
global.schema_version	egész szám	A GlobalDatabase sémaváltozata a rögzítés pillanatában
global.bytes	egész szám	A kiírt global.db mérete
workspace_schema_version	egész szám	A WorkspaceDatabase sémaváltozata, amelyet minden munkaterület-fájl közösen használ
workspaces[]	tömb	Egy bejegyzés minden rögzített munkaterülethez
workspaces[].workspace_id	karakterlánc	Az a munkaterület, amelyet ez a fájl tartalmaz
workspaces[].file	karakterlánc	A pillanatkép gyökeréhez viszonyított útvonal, <workspaceId>/workspace.db
workspaces[].bytes	egész szám	Az adott fájl mérete
skipped_workspaces[]	karakterláncok tömbje	Munkaterületek, amelyeket a mentés nem tudott rögzíteni

Egy munkaterület akkor marad ki, ha regisztrálva van, de soha nem írtak bele (így még nincs fájlja), vagy ha a VACUUM INTO művelete meghiúsult. Mindkét esetben a pillanatkép elkészül, és a manifest megnevezi, mi hiányzik.

Teljesség

A server.listBackups pillanatképenként egy complete jelzőt ad vissza. Ez hamis, ha a manifest hiányzik vagy nem értelmezhető, ha a global.db hiányzik, vagy ha a manifest olyan munkaterület-fájlt nevez meg, amely nincs a lemezen.

Egy hiányos pillanatkép is szerepel a listán, mert az a pillanatkép, amelyet az üzemeltető nem lát, olyan, amelyről azt hiszi, hogy megvan. Ha a manifest olvashatatlan, a listázás magára a felépítésre esik vissza, és minden megtalált <workspaceId>/workspace.db fájlt jelenti — ezek egyenként továbbra is átvehetők a workspace.import művelettel, még ha a pillanatkép egésze nem is tud visszaállítani egy telepítést.

Mit nem tartalmaz egy biztonsági mentés

Mindkét artefaktum kizárólag adatbázis. Egy munkaterület könyvtára többet tartalmaz az adatbázisánál, és a többi semmi nem utazik vele:

Útvonal	Szerepel egy pillanatképben?	Szerepel egy munkaterület-exportban?
global.db	Igen	Nem
<workspaceId>/workspace.db	Igen	Igen (ez maga a fájl)
<workspaceId>/blobs/	Nem	Nem
<workspaceId>/skills/	Nem	Nem
<workspaceId>/agents/	Nem	Nem
<workspaceId>/chat_credentials/	Nem	Nem
<workspaceId>/spaces/<spaceId>/	Nem	Nem
<workspaceId>/pr_clones/	Nem	Nem
secrets.json	Nem	Nem
models/	Nem	Nem
meetings/<meetingId>/	Nem	Nem
rigs/	Nem	Nem

Ennek egy része eldobható — a spaces/ másolás-írás munkakönyvtárakat tartalmaz, amelyek a repókból újra előállnak, a pr_clones/ gyorsítótár, a models/ újra letöltődik, a rigs/ gépállapot. Egy másik része viszont nem az: a blobs/ azokat a beillesztett képeket tartalmazza, amelyekre az adatbázis sorai hivatkoznak, a skills/ és az agents/ azokat a fájlokat, amelyekkel egy ügynök fut, a secrets.json pedig a telepítés minden párosítási kulcsát, szolgáltatói hitelesítő adatát és SSO-beállítását. A többi lefedéséről a Mentés és visszaállítás oldal szól.

A csevegőtokenek szándékosan kimaradnak

Az, hogy a chat_credentials/ az adatbázis mellett van, nem pedig benne, azért van, hogy egy másvalakinek átadott munkaterület ne vigyen magával élő bot-tokeneket. Lásd a csevegőhíd-referenciát.

Műveletek

A telepítési mentés RPC-műveletei, valamint a munkaterület exportálása/importálása kizárólag fullClient-tel érhetők el: egy párosított telefon nem tudja elindítani őket. Ezek egy olyan szerveren, ahol nincs bekötve mentési port — például a demószerveren —, teljesen hiányoznak: nem arról van szó, hogy elutasítanák őket, hanem szerkezetileg nincsenek ott.

Művelet	Fajta	Hatókör	Legkisebb szerepkör	Argumentumok	Visszatérés
server.backupNow	Írás	Telepítés	a telepítés tulajdonosa	nincs	{ok, path}
server.listBackups	Olvasás	Telepítés	a telepítés tulajdonosa	nincs	{backups: [...]}
server.deleteBackup	Írás	Telepítés	a telepítés tulajdonosa	name	{ok}
workspace.export	Olvasás	Munkaterület	admin	nincs	{ok, path}
workspace.import	Írás	Munkaterület	owner	source_path	{ok, workspace_id}
workspace.delete	Írás	Telepítés*	owner	id	a nyilvántartási sor töröltként megjelölve

• A workspace.delete azért hatókör nélküli, mert a sor, amelyet megjelöl, a globális nyilvántartásban él; a kezelője ellenőrzi a hívó tagságát a megnevezett munkaterületben, és owner szerepkört követel.

A path minden válaszban a szervergép egy útvonala.

A teljes telepítésről készült pillanatkép mindkét útvonalon tulajdonosi kapu mögött van

A server.backupNow, a server.listBackups és a server.deleteBackup a telepítés tulajdonosát igényli (ServerAuthority.serverOwner) — ugyanazt a kaput, mint a GET /backup/snapshot. Egy pillanatkép minden munkaterület adatbázisát rögzíti, így önmagában attól, hogy valaki egy munkaterület adminja, még nem kezelheti a többit. A törlés kizárólag a listázott időbélyeg-könyvtárnevet fogadja el, nem tetszőleges szerverútvonalat, és a teljes pillanatképet eltávolítja (a hiányosakat is). A munkaterületenkénti exportálás/importálás továbbra is a munkaterület adminjánál, illetve tulajdonosánál marad, nem a telepítés tulajdonosánál.

A server.listBackups válasza

A legfrissebbel kezdve, könyvtárnév szerint rendezve (ami maga az időbélyeg, így a sorrend akkor is tartja magát, ha egy pillanatkép manifestjét nem sikerült beolvasni).

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

A created_at kimarad, ha a manifestet nem sikerült beolvasni. A legfelső szintű bytes a teljes könyvtár valódi lemezmérete, nem a manifest saját összege — egy pillanatképeket ritkító üzemeltető azt a kérdést teszi fel, hogy mennyibe kerül a könyvtár, nem azt, hogy a mentés mennyit szándékozott írni.

Minden workspaces[].path pontosan az, amit a workspace.import source_path értékként elfogad. Ez szándékos: a „munkaterület visszaállítása ebből a pillanatképből” maga az importálási művelet, így a kettő nem csúszhat el egymástól úgy, hogy ugyanazt a fájlt másképp kezelje.

A workspace.import érvényesítése

Mielőtt bármi lecserélődne, a jelölt fájl csak olvasható módban nyílik meg egy rövid életű nyers SQLite-kapcsolattal, és beolvasásra kerül a workspace_meta sora.

Feltétel	Eredmény
Nem olvasható SQLite-adatbázis, vagy nincs workspace_meta	Elutasítva. Semmi nem változik
A rögzített munkaterület-azonosító ≠ a cél	Engedélyezve, naplózva. Így duplikálódik vagy áll vissza egy munkaterület új azonosító alatt
A rögzített telepítés-azonosító ≠ ez a telepítés	Engedélyezve, naplózva. A párosított eszközei és felhasználóazonosítói ahhoz a telepítéshez tartoznak, és itt nem oldódnak fel
Érvénytelen munkaterület-azonosító, vagy a fájl nem létezik	Elutasítva

Elfogadás esetén a cél-munkaterület adatbázisa bezárul, és a kezelő elengedi, mielőtt a fájl rákerül (egy nyitott drift-kapcsolat fogva tartja a fájlt és annak -wal állományát), majd újra megnyílik, hogy a beforeOpen újratelepítse az FTS- és szinkronizációs triggereket, és az FTS-indexek újraépüljenek — egy importált fájl tartalomtáblái feltöltöttek, de az indexe elavult lehet.

Átviteli útvonalak

A fenti műveletek mindegyike szerveroldali útvonalakkal dolgozik, ami csak akkor teljes válasz, ha a szerver a saját gépe. Az alábbi három viszi át a bájtokat, ugyanazon a PSK-val aláírt sávon, amelyet a médiaproxy és a blobtár használ. A hívó az eszköze előzetesen megosztott kulcsával írja alá a célkarakterláncot, és az aláírást s néven adja át.

Útvonal	Metódus	Lekérdezés	Aláírt cél	Szükséges
/backup/workspace	GET	w, d, s	backup-workspace:<workspaceId>	Munkaterület admin
/backup/snapshot	GET	n, d, s	backup-snapshot:<name>	Telepítés tulajdonosa
/backup/restore	POST	w, d, s	backup-restore:<workspaceId>	Munkaterület tulajdonosa

A w egy munkaterület-azonosító, az n egy pillanatkép-könyvtárnév, a d a hívó eszköz azonosítója, az s pedig az aláírás. Az n a mentéslistázás alapján oldódik fel, nem a mentések gyökérkönyvtárához fűzve, így az útvonal nem irányítható olyan könyvtárra, amelyet a listázás nem mutatott volna.

Állapot	Ok
400	Hiányzik egy kötelező lekérdezési paraméter, vagy üres a feltöltés törzse
403	Ismeretlen vagy visszavont eszköz, hibás aláírás, vagy a hívónak nincs meg a szerepköre
404	Nincs mentési port ezen a gazdagépen, vagy a megnevezett pillanatkép- vagy munkaterület-fájl nem létezik
405	A /backup/restore hívása POST-on kívül bármi mással
413	A feltöltés törzse meghaladja a 8 GiB-ot, akár a megadott content-length, akár a ténylegesen beolvasott bájtok szerint
500	Az exportálás vagy az archiválás szerveroldalon meghiúsult

Mindkét letöltés Cache-Control: no-store, illetve Accept-Ranges: none fejléccel válaszol. Minden kérés egy friss másolatot készít, és a streamelés után törli, így egy gyorsítótárazott vagy folytatott válasz két különböző exportálás bájtjait fűzné össze egyetlen, érvényesnek látszó, de nem az fájlba.

A /backup/snapshot <name>.zip fájlt ad vissza, a bejegyzések a pillanatkép gyökeréhez képes relatívak, így a kicsomagolás a manifest.json + global.db + <workspaceId>/workspace.db szerkezetet állítja elő. A bejegyzések rendezett sorrendben íródnak, így ugyanannak a pillanatképnek a két archívuma ugyanaz az archívum.

A /backup/restore a törzset egyenesen egy előkészítő fájlba streameli, ahelyett hogy pufferelné, a beolvasás előtt és közben is korlátot szab neki, és minden kivezető úton törli az előkészített fájlt, az elutasítást is beleértve.

Egy továbbított kapcsolatnak nincs HTTP-eredete

A brókerezett továbbító RPC-kereteket szállít, nem fájlátvitelt. Minden, ami szerveroldali útvonalakkal dolgozik, továbbra is működik rajta; a három átviteli útvonal közvetlen kapcsolatot igényel, ezért a felhasználói felület letiltja őket egy megjegyzéssel, ahelyett hogy a letöltés közepén hibázna.

Útvonalak és korlátok

Dolog	Érték
Pillanatképek	<dataDir>/backups/<timestamp>/
Ütemezett munkaterület-mentések	<dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db
Munkaterület-exportok	<dataDir>/backups/exports/<workspaceId>-<timestamp>.db
Átviteli előkészítés	<dataDir>/backups/transfer/ — egy munkapad, amelyet az őt író útvonal söpör ki
A pillanatkép-archívum neve	<snapshot directory name>.zip
Feltöltési felső korlát	8 GiB POST /backup/restore-onként
Megőrzés	Telepítési pillanatképek: kézi törlés. Munkaterület-mentések: heti pipeline, alapértelmezésben 30 nap

Az exports/, a transfer/ és a workspace-backups/ könyvtár nem telepítési pillanatkép, és ki van zárva a server.listBackups listájából. Csak az utolsó könyvtárnak van ütemezett megőrzése; egy telepítési pillanatkép törléséhez a telepítés tulajdonosának kifejezett művelete kell.

Lásd még

• Mentés és visszaállítás — azok a receptek, amelyekhez ezek a műveletek tartoznak
• Munkaterületek és elszigetelés — miért jelent egy munkaterület egyetlen fájlt
• cc_server CLI — az az adatkönyvtár, amelyben ezek az útvonalak vannak
• Útvonaltérkép — hol él a felhasználói felület
• Architektúra — az az ügyfél/szerver felosztás, amelyet az útvonalak követnek