備份與還原

本指南涵蓋大家實際使用備份時會做的五件事：建立備份、取回副本、搬移工作區、 還原備份，以及把副本保存在機器之外。關於每種產物與每項操作的確切形式，請參閱 備份參考。

本頁所述的一切都位於 設定 → 伺服器 → 備份與還原。

先決條件

• 完整用戶端——桌面或網頁應用程式。已配對的手機依設計無法觸發其中任何一項操作。
• 若要建立、列出、下載或刪除安裝快照：需要該安裝的擁有者。
• 針對個別工作區的操作：匯出需要該工作區的管理員，匯入或刪除則需要擁有者。
• 下載與上傳：需要與伺服器的直接連線。代理中繼傳送的是 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。

在桌面上，你會選擇檔案的存放位置，提示也會指出該位置；在網頁上，檔案會進入 瀏覽器的下載項目。兩種方式都會以位元組回報進度，因為這是僅有的兩種會一路 大到 GB 等級的傳輸。

兩者都會在你按下按鈕的當下產生一份全新的副本、以串流傳送，並在之後刪除 伺服器上的副本——下載並不是「取回先前按匯出所產生的檔案」。

解壓縮快照封存檔會精確重現快照的結構，這正是讓還原它成為單純複製回去的原因。

將工作區搬移到另一個安裝

一個工作區就是一個資料庫檔案，因此移交它就是一次檔案操作。

1. 在來源伺服器上，設定 → 伺服器 → 備份與還原 → 工作區資料，展開該工作區並按下下載。
2. 在目的伺服器上，建立（或選擇）要接收它的工作區。
3. 展開該工作區，並在從此裝置還原下按下選擇檔案並上傳。選擇你下載的 .db。

如果兩部伺服器都是你所在的同一部機器，儲存在伺服器上加上 匯入 → 選擇檔案也能達到相同效果，而且不必來回傳輸；匯入對話方塊中的 路徑是在伺服器主機上解析的。

匯入會取代所有內容

匯入會覆寫目標工作區目前持有的一切，且無法復原。如果目標中有任何你可能想取回 的內容，請先匯出。

有兩件事會被允許並記錄下來，而不是遭到拒絕：匯入記錄的工作區 ID 與目標不同的 檔案（這正是複製工作區，或以新的 ID 還原它的方式），以及匯入來自不同安裝 的檔案。在第二種情況下，該檔案中已配對的裝置與使用者 ID 屬於它來自的安裝， 在這一個安裝上無法解析——工作區本身的資料完好無損，但採用後請重新檢查成員 資格。

聊天機器人權杖位於資料庫旁邊，而不是資料庫內，因此你交給別人的工作區不會 帶有任何有效的憑證。接收端的安裝會重新連接它自己的憑證。

從快照還原單一工作區

1. 在安裝快照下，展開你要的快照。
2. 找到該工作區的列，並按下還原。
3. 確認。該工作區自快照建立後所做的一切都會流失。

這與匯入是同一項操作，只是指向快照中該工作區檔案的副本——這是刻意的，如此 一來就不會有第二種機制以不同方式處理同一個檔案。

某一列可能顯示已不在此伺服器上，且還原為停用狀態：該快照持有的工作區 已不存在於這個安裝。請手動把它帶回來——建立一個工作區，然後在工作區資料 下，從 <snapshot path>/<old workspace id>/workspace.db 匯入到其中。展開的 快照會在自己的可複製欄位中顯示伺服器上的路徑，而該列的標題就是舊的工作區 ID，因此你眼前同時擁有該路徑的兩半。

還原整份安裝

這件事沒有按鈕，也不應該有：它會取代執行中的伺服器正開啟持有的資料庫。

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/（寫入時複製的工作樹，會從你的儲存庫重新佈建）、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 重建，也是唯一能告訴你該備份可以還原、而不只是可以讀取的檢查。

在你設定備份時做一次，之後每當你變更備份的存放位置時再做一次。

疑難排解

徵狀	原因與修正
下載與上傳控制項被停用，並顯示一則關於中繼的說明	你是透過代理中繼連線，而中繼不承載檔案傳輸。請直接連線
「伺服器拒絕了」	角色問題。建立或列出安裝快照需要該安裝的操作員。下載工作區需要管理員，還原工作區需要擁有者，整份快照的 zip 則需要該安裝的操作員
「此伺服器沒有備份介面」	該主機沒有接上備份埠——例如示範伺服器。這些操作是不存在，而不是遭到拒絕
「檔案大於伺服器接受的上限」	上傳上限為 8 GiB。請把檔案放到伺服器主機上，改用匯入 → 選擇檔案
匯入遭拒：不是 Control Center 工作區資料庫	該檔案沒有 workspace_meta 資料列——它不是工作區匯出，或是被截斷了。沒有取代任何內容
某個快照被列為不完整	其資訊清單遺失，或指向不存在的檔案。請建立新的快照；在此期間仍可採用其中個別的工作區檔案
某個快照指出有工作區未擷取	那些工作區從未被寫入，或是其複製失敗。請檢查伺服器日誌
還原後的安裝沒有程式碼託管或 SSO 憑證	快照中不含 secrets.json。請從你保存它的地方還原，或重新連接供應商
還原後的工作區缺少貼上的圖片	Blob 位於資料庫旁邊，而不是資料庫內。請一併複製 <workspaceId>/blobs/ 過去

相關指南

• 執行無介面伺服器：資料目錄從何而來
• 連線至遠端伺服器：直接連線與中繼連線的差異
• 配對裝置：傳輸路由用來簽署的憑證

相關概念與參考

• 備份、匯出與匯入：每一項操作、路由、欄位與限制
• 工作區與隔離：為什麼一個工作區就是一個檔案
• cc_server CLI：資料目錄的結構