Sao lưu và khôi phục

Hướng dẫn này bao quát năm việc người ta thực sự làm với bản sao lưu: tạo một bản, thu nó về, chuyển một không gian làm việc, đặt một bản trở lại, và giữ bản sao ngoài máy. Để biết hình dạng chính xác của từng artifact và thao tác, xem tham chiếu sao lưu.

Mọi thứ ở đây nằm tại Cài đặt → Máy chủ → Sao lưu và khôi phục.

Điều kiện tiên quyết

Một máy khách đầy đủ — ứng dụng desktop hoặc web. Một điện thoại đã ghép nối không kích hoạt được bất cứ phần nào trong số này, và đó là chủ đích.
Để tạo, liệt kê, tải xuống hoặc xóa một ảnh chụp cài đặt: owner của bản cài đặt.
Với các thao tác theo từng không gian làm việc: admin của không gian làm việc đó để xuất, owner để nhập hoặc xóa nó.
Với tải xuống và tải lên: một kết nối trực tiếp tới máy chủ. Relay được môi giới chở các khung RPC chứ không chở truyền tệp, và các điều khiển truyền tự vô hiệu hóa kèm một ghi chú khi bạn đang đi qua nó.

Bản sao lưu bao gồm những gì

Cả hai artifact đều chỉ là cơ sở dữ liệu:

Một ảnh chụp cài đặt là một thư mục có dấu thời gian: manifest.json, global.db và một <workspaceId>/workspace.db cho mỗi không gian làm việc.
Một bản xuất không gian làm việc là chính tệp workspace.db đó.

Cả hai đều không mang theo phần còn lại của thư mục dữ liệu: secrets.json (khóa ghép nối, thông tin xác thực nhà cung cấp, SSO), blobs/ của một không gian làm việc (ảnh được dán vào tin nhắn), skills/, agents/, chat_credentials/, âm thanh cuộc họp đã ghi hay ảnh rig. Phần nào trong đó có thể bỏ đi, phần nào thì không — bảng đầy đủ nằm trong tham chiếu, và che phủ nó chính là việc mà phần ngoài máy hướng tới.

Tạo ảnh chụp toàn bộ bản cài đặt

Mở Cài đặt → Máy chủ → Sao lưu và khôi phục.
Dưới Ảnh chụp cài đặt, nhấn Sao lưu ngay.
Thông báo nổi nêu tên thư mục đã được ghi, trên máy chủ. Ảnh chụp mới xuất hiện ở đầu danh sách.

Máy chủ vẫn chạy suốt quá trình. Mỗi tệp được ghi bằng VACUUM INTO, vốn nhất quán ngay cả với một cơ sở dữ liệu đang sống, nên không cần cửa sổ bảo trì và không cần dừng agent.

Mỗi hàng trong danh sách hiển thị dấu thời gian, kích thước trên đĩa, số không gian làm việc đã được chụp và liệu ảnh chụp là Hoàn tất hay Chưa hoàn tất. Chưa hoàn tất nghĩa là manifest bị thiếu hoặc nêu những tệp không tồn tại — một bản sao lưu bị ngắt giữa chừng do sự cố hoặc do đĩa đầy. Những ảnh chụp đó vẫn được liệt kê là có chủ đích: một ảnh chụp bạn không nhìn thấy là một ảnh chụp bạn tưởng mình đang có. Một ảnh chụp chưa hoàn tất không thể khôi phục toàn bộ bản cài đặt, nhưng các tệp không gian làm việc mà nó có vẫn có thể được nhận về từng cái một.

Một hàng cũng có thể ghi n không gian làm việc không được chụp. Đó là một không gian làm việc đã đăng ký nhưng chưa từng được ghi vào (chưa có tệp), hoặc một không gian làm việc mà bản sao của nó thất bại — hãy kiểm tra nhật ký máy chủ.

Lên lịch sao lưu không gian làm việc và lưu giữ

Mở Cài đặt → Pipelines → Mẫu quy trình cho không gian làm việc và tìm Workspace backup. Lịch đã bật của nó chạy vào mỗi Chủ nhật lúc 03:00 UTC: Back up workspace, tiếp theo là Delete backups older than (mặc định 30 ngày). Nút thứ hai chỉ chạy sau khi bản sao lưu thành công. Bạn có thể đổi số ngày lưu giữ trên nút hoặc tắt lịch. Nếu máy chủ ngoại tuyến vào thời điểm đã lên lịch, lịch sẽ chạy bù một lần khi máy chủ trở lại, thay vì phát lại mọi tuần đã lỡ.

Các bản sao lưu không gian làm việc nằm trên máy chủ tại backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Nút lưu giữ chỉ xóa các bản sao lưu cũ của không gian làm việc này; nó không bao giờ xóa ảnh chụp cài đặt hay bản sao lưu của các không gian làm việc khác. Những tệp này chỉ chứa cơ sở dữ liệu. Để lưu giữ ngoài máy, hãy sao chép chúng một cách độc lập.

Những bản sao lưu này tách biệt với danh sách Ảnh chụp cài đặt. Để khôi phục một bản, dùng Dữ liệu không gian làm việc → Nhập với đường dẫn workspace.db phía máy chủ của bản sao lưu đó. Nhập sẽ thay thế cơ sở dữ liệu hiện tại của không gian làm việc đó, nên hãy xuất nó trước nếu bạn có thể cần hoàn tác lần khôi phục.

Xóa một ảnh chụp cài đặt

Dưới Ảnh chụp cài đặt, mở rộng ảnh chụp, kể cả ảnh chụp chưa hoàn tất, và dùng Xóa ảnh chụp trong vùng nguy hiểm. Xác nhận tên của nó. Toàn bộ thư mục ảnh chụp bị xóa vĩnh viễn khỏi máy chủ; hãy tải nó xuống trước nếu bạn cần một bản sao. Quy trình sao lưu không gian làm việc không bao giờ xóa những ảnh chụp này.

Thu một bản sao về máy của bạn

Những đường dẫn mà trang này hiển thị nằm trên máy đang chạy cc_server. Khi đó không phải máy bạn đang ngồi, hãy dùng các nút Tải xuống:

Bên cạnh mỗi không gian làm việc dưới Dữ liệu không gian làm việc → Tải xuống, để lấy một tệp .db.
Bên cạnh mỗi ảnh chụp dưới Ảnh chụp cài đặt → Tải xuống, để lấy toàn bộ ảnh chụp dưới dạng .zip.

Trên desktop, bạn chọn nơi tệp hạ cánh và thông báo nổi nêu tên nó; trên web, tệp đi vào thư mục tải xuống của trình duyệt. Dù theo cách nào, cả hai đều báo tiến độ theo byte, bởi đây là hai payload có thể lên tới hàng gigabyte.

Cả hai đều tạo một bản sao mới ngay lúc bạn nhấn nút, truyền phát nó, rồi xóa bản sao trên máy chủ sau đó — tải xuống không phải là “lấy tệp mà nút xuất đã tạo trước đó”.

Giải nén một tệp lưu trữ ảnh chụp tái tạo chính xác bố cục của ảnh chụp, và đó là điều khiến việc khôi phục nó chỉ còn là một thao tác sao chép trở lại.

Chuyển một không gian làm việc sang bản cài đặt khác

Một không gian làm việc là một tệp cơ sở dữ liệu, nên chuyển giao nó là một thao tác tệp.

Trên máy chủ nguồn, Cài đặt → Máy chủ → Sao lưu và khôi phục → Dữ liệu không gian làm việc, mở rộng không gian làm việc và nhấn Tải xuống.
Trên máy chủ đích, tạo (hoặc chọn) không gian làm việc sẽ nhận nó.
Mở rộng không gian làm việc đó, và dưới Khôi phục từ thiết bị này nhấn Chọn tệp và tải lên. Chọn tệp .db bạn đã tải xuống.

Nếu cả hai máy chủ đều là máy bạn đang ngồi, Lưu trên máy chủ cộng với Nhập → Chọn tệp làm đúng việc đó mà không cần đi vòng; các đường dẫn trong hộp thoại nhập được phân giải trên máy chủ.

Hai trường hợp được cho phép và ghi nhật ký thay vì bị từ chối: nhập một tệp có id không gian làm việc được ghi khác với đích (đây là cách bạn nhân bản một không gian làm việc hoặc khôi phục nó dưới một id mới), và nhập một tệp từ một bản cài đặt khác. Trong trường hợp thứ hai, các thiết bị đã ghép nối và id người dùng của tệp thuộc về bản cài đặt gốc và sẽ không phân giải được trên bản cài đặt này — dữ liệu của chính không gian làm việc vẫn nguyên vẹn, nhưng hãy kiểm tra lại tư cách thành viên sau khi nhận nó.

Token của bot chat nằm bên cạnh cơ sở dữ liệu chứ không nằm trong đó, nên một không gian làm việc bạn trao cho người khác không mang theo thông tin xác thực nào đang sống. Bản cài đặt nhận sẽ tự kết nối lại thông tin xác thực của chính nó.

Khôi phục một không gian làm việc từ ảnh chụp

Dưới Ảnh chụp cài đặt, mở rộng ảnh chụp bạn muốn.
Tìm hàng của không gian làm việc và nhấn Khôi phục.
Xác nhận. Mọi việc không gian làm việc đó đã làm kể từ khi ảnh chụp được tạo sẽ mất.

Đây là cùng thao tác như một lần nhập, trỏ vào bản sao trong ảnh chụp của tệp không gian làm việc đó — là có chủ đích, để không tồn tại cơ chế thứ hai có thể xử lý cùng một tệp theo cách khác.

Một hàng có thể ghi Không còn trên máy chủ này, với Khôi phục bị vô hiệu hóa: ảnh chụp chứa một không gian làm việc mà bản cài đặt này không còn nữa. Hãy đưa nó trở lại bằng tay — tạo một không gian làm việc, rồi dưới Dữ liệu không gian làm việc nhập vào nó từ <snapshot path>/<old workspace id>/workspace.db. Ảnh chụp đã mở rộng hiển thị Đường dẫn trên máy chủ của chính nó trong một trường sao chép, và tiêu đề của hàng là id không gian làm việc cũ, nên bạn có cả hai nửa của đường dẫn đó ngay trước mắt.

Khôi phục toàn bộ bản cài đặt

Không có nút cho việc này, và cũng không nên có: nó thay thế những cơ sở dữ liệu mà máy chủ đang chạy giữ mở.

Dừng cc_server. Nếu bạn chạy ứng dụng desktop với máy chủ nhúng của nó, hãy thoát ứng dụng.

Sao chép nội dung của ảnh chụp đè lên thư mục dữ liệu. Bố cục ảnh chụp phản chiếu bố cục đang chạy, nên đây chỉ là một thao tác sao chép đơn thuần:

# 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

Xóa mọi tệp -wal và -shm nằm cạnh những cơ sở dữ liệu bạn đã thay thế. Chúng thuộc về các tệp cũ, và một tệp cũ sót lại bên cạnh cơ sở dữ liệu đã khôi phục là một rủi ro hỏng dữ liệu.
Khởi động lại máy chủ.

Ảnh chụp không chứa secrets.json, nên một bản cài đặt được khôi phục lên một máy chủ hoàn toàn mới giữ được dữ liệu nhưng không giữ được thông tin xác thực: các thiết bị đã ghép nối, token nhà cung cấp và cài đặt SSO phải được thiết lập lại, hoặc khôi phục từ nơi bạn đã cất tệp đó. Khôi phục lên cùng máy chủ, nơi secrets.json chưa từng bị mất, giữ được mọi thứ.

Sao chép bản sao lưu ra khỏi máy

Một ảnh chụp nằm trên cùng đĩa với cơ sở dữ liệu mà nó đã sao chép bảo vệ bạn khỏi một lần nhập hỏng, chứ không khỏi hỏng đĩa. Không có gì trong Control Center tự gửi bản sao đi đâu cả, nên phần này là việc của bạn.

Đồng bộ các ảnh chụp

Ảnh chụp là bất biến sau khi được ghi và được đặt tên theo dấu thời gian, nên mọi công cụ đồng bộ đều xử lý chúng tốt. Hãy loại trừ transfer/, vốn là nơi làm việc cho các tải xuống và tải lên đang diễn ra:

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 phản chiếu việc dọn dẹp cục bộ của bạn lên remote. Bỏ nó đi nếu bạn muốn remote giữ ảnh chụp lâu hơn máy chủ.

Bổ sung những gì ảnh chụp bỏ sót

Để có thể dựng lại cả bản cài đặt chứ không chỉ dữ liệu của nó, hãy sao chép cả những thứ này. Chúng là những tệp thông thường, sao chép an toàn trong khi máy chủ đang chạy:

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 có quyền 0600 và 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. Nơi nó hạ cánh phải được bảo vệ ít nhất ngang với máy chủ — mã hóa khi lưu trữ, và không phải một bucket mà người khác đọc được.

Bỏ qua spaces/ (các worktree copy-on-write, được cấp phát lại từ kho mã của bạn), pr_clones/ (một bộ đệm), models/ (tải lại được), media_cache/ và rigs/ (trạng thái máy, và dung lượng lớn). Âm thanh cuộc họp đã ghi trong meetings/ đáng để đưa vào nếu bạn có lưu cuộc họp.

Lên lịch ảnh chụp toàn bộ cài đặt ngoài ứng dụng

Quy trình tích hợp chỉ sao lưu một không gian làm việc. Với một ảnh chụp toàn bộ cài đặt không cần người trực, không có lệnh con CLI nào, và RPC ảnh chụp yêu cầu một máy khách đầy đủ đã ghép nối và chính là chủ sở hữu bản cài đặt. Một bộ hẹn giờ phía máy chủ có thể dùng VACUUM INTO trên các cơ sở dữ liệu đang sống:

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

Hãy chạy nó bằng chính người dùng sở hữu thư mục dữ liệu, từ cron hoặc một bộ hẹn giờ systemd, rồi đồng bộ DEST ra khỏi máy chủ sau đó. VACUUM INTO cần SQLite 3.27 trở lên.

Hãy ghi nó ra bên ngoài <dataDir>/backups/. Một thư mục do bạn tự tạo ở đó không có manifest.json, nên ứng dụng sẽ liệt kê nó như một ảnh chụp chưa hoàn tất và danh sách sẽ không còn là bản ghi trung thực về những gì chính máy chủ đã tạo.

Dọn các ảnh chụp toàn bộ cài đặt cũ

Bạn có thể xóa từng ảnh chụp cài đặt trong ứng dụng. Với một chính sách lưu giữ phía máy chủ, hãy giữ thư mục sao lưu không gian làm việc tách biệt khỏi các ảnh chụp cài đặt:

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

Hãy kiểm tra đầu ra của một lần chạy -print trước khi thêm -exec. Giữ nhiều hơn một bản: thất bại mà bạn đang phòng ngừa thường là “bản sao lưu cuối cùng cũng dính vấn đề”.

Kiểm tra một bản sao lưu có tốt không

Một bản sao lưu chưa từng được ai khôi phục chỉ là một giả thuyết.

Cách kiểm tra rẻ — tệp mở được và các trang của nó nguyên vẹn:

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

Cách kiểm tra thật — nhận nó về. Tạo một không gian làm việc tạm trên một bản cài đặt không phải production, nhập một tệp không gian làm việc vào đó, rồi xem các space, phiếu và tin nhắn bạn mong đợi có ở đó không. Thao tác này chạy đúng con đường mà một lần khôi phục thật đi qua, kể cả việc dựng lại FTS, và đây là cách kiểm tra duy nhất cho bạn biết bản sao lưu khôi phục được chứ không chỉ đọc được.

Hãy làm việc này một lần khi bạn thiết lập sao lưu, và lặp lại mỗi khi bạn thay đổi nơi lưu chúng.

Khắc phục sự cố

Triệu chứng	Nguyên nhân và cách khắc phục
Điều khiển tải xuống và tải lên bị vô hiệu hóa kèm ghi chú về relay	Bạn đang kết nối qua relay được môi giới, vốn không chở truyền tệp. Hãy kết nối trực tiếp
“Máy chủ từ chối”	Vai trò. Tạo hoặc liệt kê một ảnh chụp cài đặt cần operator của bản cài đặt. Tải xuống một không gian làm việc cần admin, khôi phục một không gian làm việc cần owner, một tệp zip toàn bộ ảnh chụp cần operator của bản cài đặt
“Máy chủ này không có bề mặt sao lưu”	Máy chủ không có cổng sao lưu nào được nối — một máy chủ demo. Các thao tác vắng mặt thay vì bị từ chối
“Tệp lớn hơn mức máy chủ chấp nhận”	Tải lên bị giới hạn ở 8 GiB. Hãy đặt tệp lên máy chủ và dùng Nhập → Chọn tệp thay thế
Nhập bị từ chối: không phải cơ sở dữ liệu không gian làm việc của Control Center	Tệp không có hàng `workspace_meta` — nó không phải một bản xuất không gian làm việc, hoặc nó bị cắt cụt. Không có gì bị thay thế
Một ảnh chụp được liệt kê là Chưa hoàn tất	Manifest của nó bị thiếu hoặc nêu những tệp không tồn tại. Hãy tạo một ảnh chụp mới; trong lúc chờ, hãy nhận từng tệp không gian làm việc từ nó
Một ảnh chụp báo có không gian làm việc không được chụp	Những không gian làm việc đó chưa từng được ghi vào, hoặc bản sao của chúng thất bại. Hãy kiểm tra nhật ký máy chủ
Một bản cài đặt đã khôi phục không có thông tin xác thực forge hay SSO	`secrets.json` không nằm trong ảnh chụp. Hãy khôi phục nó từ nơi bạn đã cất, hoặc kết nối lại các nhà cung cấp
Một không gian làm việc đã khôi phục bị thiếu ảnh đã dán	Blob nằm bên cạnh cơ sở dữ liệu chứ không nằm trong đó. Hãy sao chép cả `<workspaceId>/blobs/` sang

Hướng dẫn liên quan

Chạy máy chủ không giao diện: thư mục dữ liệu đến từ đâu
Kết nối máy chủ từ xa: kết nối trực tiếp so với kết nối qua relay
Ghép nối thiết bị: thông tin xác thực mà các tuyến truyền dùng để ký

Khái niệm và tham chiếu liên quan

Sao lưu, xuất và nhập: mọi thao tác, tuyến, trường và giới hạn
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
cc_server CLI: bố cục thư mục dữ liệu