Sao lưu, xuất và nhập

Mọi thứ Control Center có thể sao chép, chuyển giao hoặc nhận, cùng hình dạng chính xác của từng tạo tác. Để thực sự tạo một bản sao lưu, xem Sao lưu và khôi phục; còn vì sao việc lưu trữ bền vững lại được tách theo cách này, xem Không gian làm việc và cô lập.

Tạo tác

Có ba tạo tác sao chép cơ sở dữ liệu, với phạm vi và chính sách xóa khác nhau.

Tạo tác	Được ghi bởi	Hình dạng	Bao gồm
Ảnh chụp bản cài đặt	`server.backupNow`	Một thư mục có dấu thời gian	Mọi cơ sở dữ liệu trong bản cài đặt
Bản sao lưu không gian làm việc	quy trình `Workspace backup`	Thư mục có dấu thời gian chứa một tệp `.db`	Cơ sở dữ liệu của một không gian làm việc
Bản xuất không gian làm việc	`workspace.export`	Một tệp `.db` duy nhất	Cơ sở dữ liệu của một không gian làm việc

Tất cả đều được ghi bằng VACUUM INTO của SQLite, an toàn với một cơ sở dữ liệu WAL đang chạy: nó mở một giao dịch đọc, tạo ra một bản sao đã chống phân mảnh và nhất quán về giao dịch, và không bao giờ đòi hỏi phải dừng máy chủ.

Bố cục ảnh chụp

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

Bố cục phản chiếu chính xác thư mục dữ liệu đang chạy, và đó là điều khiến việc khôi phục một bản cài đặt trở thành sao chép ngược lại chứ không phải một phép dịch. Tên thư mục là dấu thời gian UTC với : và . được thay bằng -, nên nó an toàn với hệ thống tệp trên Windows và sắp xếp theo trình tự thời gian như một chuỗi thuần.

Các bản sao lưu không gian làm việc theo lịch nằm riêng tại <dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Chúng không bao gồm manifest hay global.db và không phải ảnh chụp bản cài đặt. Bước lưu trữ của quy trình hằng tuần chỉ xóa các bản sao lưu của chính không gian làm việc đó cũ hơn tuổi đã cấu hình (mặc định 30 ngày); các ảnh chụp bản cài đặt do người dùng tạo thủ công không bao giờ bị bước đó xoay vòng. server.listBackups chỉ liệt kê ảnh chụp bản cài đặt, kể cả những ảnh chưa hoàn tất.

`manifest.json`

Trường	Kiểu	Ý nghĩa
`version`	số nguyên	Phiên bản định dạng manifest. Hiện tại là `1`
`created_at`	ISO-8601 UTC	Thời điểm ảnh chụp được thực hiện
`global.file`	chuỗi	Luôn là `global.db`
`global.schema_version`	số nguyên	Phiên bản lược đồ `GlobalDatabase` tại thời điểm chụp
`global.bytes`	số nguyên	Kích thước của `global.db` đã ghi
`workspace_schema_version`	số nguyên	Phiên bản lược đồ `WorkspaceDatabase` dùng chung cho mọi tệp không gian làm việc
`workspaces[]`	mảng	Một mục cho mỗi không gian làm việc được chụp
`workspaces[].workspace_id`	chuỗi	Không gian làm việc mà tệp này chứa
`workspaces[].file`	chuỗi	Đường dẫn tương đối so với gốc ảnh chụp, `<workspaceId>/workspace.db`
`workspaces[].bytes`	số nguyên	Kích thước của tệp đó
`skipped_workspaces[]`	mảng chuỗi	Những không gian làm việc mà bản sao lưu không chụp được

Một không gian làm việc bị bỏ qua khi nó đã được đăng ký nhưng chưa từng được ghi vào (nên chưa có tệp), hoặc khi VACUUM INTO của nó thất bại. Dù theo cách nào, ảnh chụp vẫn hoàn tất và manifest ghi rõ những gì còn thiếu.

Tính đầy đủ

server.listBackups báo cáo một cờ complete cho mỗi ảnh chụp. Cờ này là false khi manifest vắng mặt hoặc không phân tích được, khi global.db bị thiếu, hoặc khi manifest nêu tên một tệp không gian làm việc không có trên đĩa.

Một ảnh chụp chưa hoàn tất vẫn được liệt kê, bởi vì một ảnh chụp mà người vận hành không thấy là một ảnh chụp họ tin rằng mình đang có. Khi manifest không đọc được, danh sách lùi về chính bố cục thư mục và báo cáo bất kỳ tệp <workspaceId>/workspace.db nào nó tìm thấy — những tệp đó vẫn có thể được nhận riêng lẻ qua workspace.import dù toàn bộ ảnh chụp không thể khôi phục một bản cài đặt.

Ảnh chụp không chứa những gì

Cả hai tạo tác đều chỉ là cơ sở dữ liệu. Một thư mục không gian làm việc chứa nhiều hơn cơ sở dữ liệu của nó, và không phần nào khác đi kèm:

Đường dẫn	Có trong ảnh chụp?	Có trong bản xuất không gian làm việc?
`global.db`	Có	Không
`<workspaceId>/workspace.db`	Có	Có (nó chính là tệp đó)
`<workspaceId>/blobs/`	Không	Không
`<workspaceId>/skills/`	Không	Không
`<workspaceId>/agents/`	Không	Không
`<workspaceId>/chat_credentials/`	Không	Không
`<workspaceId>/spaces/<spaceId>/`	Không	Không
`<workspaceId>/pr_clones/`	Không	Không
`secrets.json`	Không	Không
`models/`	Không	Không
`meetings/<meetingId>/`	Không	Không
`rigs/`	Không	Không

Một phần trong đó có thể bỏ đi — spaces/ chứa các worktree copy-on-write được cấp phát lại từ các kho lưu trữ, pr_clones/ là một bộ nhớ đệm, models/ tải lại được, rigs/ là trạng thái máy. Một phần thì không: blobs/ chứa ảnh được dán mà các hàng trong cơ sở dữ liệu trỏ tới, skills/ và agents/ chứa các tệp mà agent chạy cùng, và secrets.json chứa mọi khóa ghép nối, thông tin xác thực nhà cung cấp và cài đặt SSO trên bản cài đặt. Xem Sao lưu và khôi phục để bao quát phần còn lại.

Các thao tác

Các RPC sao lưu của bản cài đặt và thao tác xuất/nhập không gian làm việc chỉ dành cho fullClient: một điện thoại đã ghép nối không thể kích hoạt chúng. Tất cả đều vắng mặt hoàn toàn — không phải bị từ chối, mà thiếu hụt về mặt cấu trúc — trên một máy chủ không nối cổng sao lưu, chẳng hạn máy chủ demo.

Thao tác	Loại	Phạm vi	Vai trò tối thiểu	Đối số	Trả về
`server.backupNow`	thay đổi	Bản cài đặt	chủ sở hữu bản cài đặt	không có	`{ok, path}`
`server.listBackups`	đọc	Bản cài đặt	chủ sở hữu bản cài đặt	không có	`{backups: [...]}`
`server.deleteBackup`	thay đổi	Bản cài đặt	chủ sở hữu bản cài đặt	`name`	`{ok}`
`workspace.export`	đọc	Không gian làm việc	`admin`	không có	`{ok, path}`
`workspace.import`	thay đổi	Không gian làm việc	`owner`	`source_path`	`{ok, workspace_id}`
`workspace.delete`	thay đổi	Bản cài đặt*	`owner`	`id`	hàng sổ đăng ký được đánh dấu đã xóa

workspace.delete không thuộc phạm vi nào vì hàng mà nó đánh dấu nằm trong sổ đăng ký toàn cục; trình xử lý của nó kiểm tra tư cách thành viên của bên gọi trong không gian làm việc được nêu tên và yêu cầu owner.

path trong mọi phản hồi là một đường dẫn trên máy chủ.

server.backupNow, server.listBackups và server.deleteBackup yêu cầu chủ sở hữu bản cài đặt (ServerAuthority.serverOwner), cùng cổng như GET /backup/snapshot. Một ảnh chụp nắm mọi cơ sở dữ liệu của không gian làm việc, nên chỉ là quản trị viên của một không gian làm việc thì chưa đủ để quản lý những cái khác. Thao tác xóa chỉ chấp nhận tên thư mục dấu thời gian có trong danh sách, không phải một đường dẫn máy chủ tùy ý, và xóa toàn bộ ảnh chụp (kể cả ảnh chụp chưa hoàn tất). Xuất/nhập theo từng không gian làm việc vẫn ở mức quản trị viên/chủ sở hữu không gian làm việc, không phải chủ sở hữu bản cài đặt.

Phản hồi của `server.listBackups`

Mới nhất trước, sắp xếp theo tên thư mục (chính là dấu thời gian, nên thứ tự vẫn đúng kể cả với một ảnh chụp có manifest không đọc được).

{
  "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 bị lược bỏ khi manifest không đọc được. bytes ở cấp cao nhất là kích thước thật trên đĩa của toàn bộ thư mục, không phải tổng do manifest tự cộng — câu hỏi mà một người vận hành đang dọn bớt ảnh chụp đặt ra là thư mục đó tốn bao nhiêu, chứ không phải bản sao lưu định ghi những gì.

Mỗi workspaces[].path đúng là thứ mà workspace.import nhận làm source_path. Đó là chủ ý: “khôi phục không gian làm việc này từ ảnh chụp này” chính là thao tác nhập, nên hai thứ không thể trôi dạt thành những cách xử lý khác nhau cho cùng một tệp.

Kiểm tra hợp lệ của `workspace.import`

Trước khi bất cứ thứ gì bị thay thế, tệp ứng viên được mở ở chế độ chỉ đọc bằng một kết nối SQLite thô tồn tại ngắn, và hàng workspace_meta của nó được đọc.

Điều kiện	Kết quả
Không phải cơ sở dữ liệu SQLite đọc được, hoặc không có `workspace_meta`	Bị từ chối. Không có gì bị chạm tới
Id không gian làm việc được ghi ≠ đích	Được phép, có ghi nhật ký. Đây là cách một không gian làm việc được nhân bản hoặc khôi phục dưới một id mới
Id bản cài đặt được ghi ≠ bản cài đặt này	Được phép, có ghi nhật ký. Các thiết bị đã ghép nối và id người dùng của nó thuộc về bản cài đặt đó và sẽ không phân giải được ở đây
Id không gian làm việc không hợp lệ, hoặc tệp không tồn tại	Bị từ chối

Khi được chấp nhận, cơ sở dữ liệu của không gian làm việc đích được đóng và loại khỏi bộ quản lý trước khi tệp được sao chép đè lên nó (một kết nối drift đang mở sẽ giữ tệp và -wal của nó), rồi được mở lại để beforeOpen cài đặt lại các trigger FTS và đồng bộ, và các chỉ mục FTS được dựng lại — bảng nội dung của một tệp được nhập thì đã được điền nhưng chỉ mục của nó có thể đã cũ.

Các tuyến truyền tải

Mọi thao tác ở trên đều nói bằng đường dẫn phía máy chủ, và đó là câu trả lời đầy đủ chỉ khi máy chủ chính là máy của bạn. Ba tuyến này mang các byte, trên cùng làn có chữ ký PSK mà proxy phương tiện và kho ảnh đang dùng. Bên gọi ký một chuỗi đích bằng khóa chia sẻ trước của thiết bị và truyền chữ ký dưới dạng s.

Tuyến	Phương thức	Truy vấn	Đích được ký	Yêu cầu
`/backup/workspace`	GET	`w`, `d`, `s`	`backup-workspace:<workspaceId>`	quản trị viên không gian làm việc
`/backup/snapshot`	GET	`n`, `d`, `s`	`backup-snapshot:<name>`	chủ sở hữu bản cài đặt
`/backup/restore`	POST	`w`, `d`, `s`	`backup-restore:<workspaceId>`	chủ sở hữu không gian làm việc

w là id không gian làm việc, n là tên thư mục ảnh chụp, d là id thiết bị đang gọi, s là chữ ký. n được phân giải dựa trên danh sách sao lưu thay vì được nối thẳng vào gốc thư mục sao lưu, nên tuyến không thể bị nhắm vào một thư mục mà danh sách sẽ không hiển thị.

Trạng thái	Nguyên nhân
`400`	Thiếu một tham số truy vấn bắt buộc, hoặc phần thân tải lên rỗng
`403`	Thiết bị không xác định hoặc đã bị thu hồi, chữ ký sai, hoặc bên gọi thiếu vai trò
`404`	Máy chủ này không có cổng sao lưu, hoặc ảnh chụp/tệp không gian làm việc được nêu tên không tồn tại
`405`	`/backup/restore` được gọi với phương thức khác `POST`
`413`	Phần thân tải lên vượt 8 GiB, theo content-length được khai báo hoặc theo số byte thực sự đọc được
`500`	Thao tác xuất hoặc lưu trữ thất bại phía máy chủ

Cả hai thao tác tải xuống đều trả về Cache-Control: no-store cùng Accept-Ranges: none. Mỗi yêu cầu tạo ra một bản sao mới và xóa nó sau khi truyền xong, nên một phản hồi được đệm hoặc tiếp tục sẽ nối các byte từ hai lần xuất khác nhau thành một tệp trông có vẻ hợp lệ mà lại không hợp lệ.

/backup/snapshot trả về <name>.zip, với các mục tương đối so với gốc ảnh chụp để khi giải nén tái tạo được manifest.json + global.db + <workspaceId>/workspace.db. Các mục được ghi theo thứ tự sắp xếp, nên hai tệp lưu trữ của cùng một ảnh chụp là cùng một tệp.

/backup/restore truyền thẳng phần thân xuống một tệp tạm thay vì đệm nó, đặt giới hạn trước và trong khi đọc, và xóa tệp tạm trên mọi lối ra kể cả khi bị từ chối.

Đường dẫn và giới hạn

Thứ	Giá trị
Ảnh chụp	`<dataDir>/backups/<timestamp>/`
Bản sao lưu không gian làm việc theo lịch	`<dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db`
Bản xuất không gian làm việc	`<dataDir>/backups/exports/<workspaceId>-<timestamp>.db`
Trung chuyển truyền tải	`<dataDir>/backups/transfer/` — một bàn làm việc, được dọn bởi chính tuyến ghi vào nó
Tên tệp lưu trữ ảnh chụp	`<snapshot directory name>.zip`
Giới hạn tải lên	8 GiB cho mỗi `POST /backup/restore`
Lưu trữ	Ảnh chụp bản cài đặt: xóa thủ công. Bản sao lưu không gian làm việc: quy trình hằng tuần, mặc định 30 ngày

Các thư mục exports/, transfer/ và workspace-backups/ không phải ảnh chụp bản cài đặt và bị loại khỏi server.listBackups. Chỉ thư mục cuối cùng có lưu trữ theo lịch; việc xóa một ảnh chụp bản cài đặt đòi hỏi hành động rõ ràng của chủ sở hữu bản cài đặt.

Xem thêm

Sao lưu và khôi phục — các công thức mà những thao tác này thuộc về
Không gian làm việc và cô lập — vì sao một không gian làm việc là một tệp
CLI cc_server — thư mục dữ liệu mà những đường dẫn này nằm trong
Bản đồ tuyến — nơi giao diện người dùng nằm
Kiến trúc — sự phân tách máy khách/máy chủ mà các đường dẫn tuân theo