バックアップと復元

このガイドでは、バックアップに関して実際によく行われる 5 つの作業、つまり取得、回収、ワークスペースの移動、復元、マシン外へのコピー保持を扱います。各アーティファクトと各操作の正確な形については、バックアップのリファレンスを参照してください。

ここで説明する内容はすべて 設定 → サーバー → バックアップと復元 にあります。

前提条件

フルクライアント（デスクトップまたは Web アプリ）が必要です。ペアリングされたスマートフォンでは、これらはいずれも設計上実行できません。
インストール全体のスナップショットの取得、一覧表示、ダウンロード、削除には、インストールのオーナーである必要があります。
ワークスペース単位の操作では、エクスポートにはそのワークスペースの管理者、インポートまたは削除にはオーナーが必要です。
ダウンロードとアップロードには、サーバーへの直接接続が必要です。ブローカー経由のリレーが運ぶのは RPC フレームであり、ファイル転送ではありません。リレー経由の場合、転送コントロールは注記とともに無効になります。

バックアップに含まれる範囲

どちらのアーティファクトもデータベースのみです。

インストール全体のスナップショットはタイムスタンプ付きのディレクトリで、manifest.json、global.db、およびワークスペースごとの <workspaceId>/workspace.db から成ります。
ワークスペースのエクスポートは、その単一の workspace.db ファイルです。

どちらもデータディレクトリの残りの部分は含みません。secrets.json（ペアリングキー、プロバイダーの認証情報、SSO）、ワークスペースの blobs/（メッセージに貼り付けられた画像）、skills/、agents/、chat_credentials/、録画したミーティングの音声、リグ画像などです。その一部は捨ててよいものですが、そうでないものもあります。完全な表はリファレンスにあり、これらをカバーするのがマシン外のセクションの目的です。

インストール全体のスナップショットを取得する

設定 → サーバー → バックアップと復元を開きます。
インストール全体のスナップショットで、今すぐバックアップを押します。
トーストに、サーバーホスト上で書き込まれたディレクトリ名が表示されます。新しいスナップショットは一覧の先頭に表示されます。

サーバーはその間も動き続けます。各ファイルは VACUUM INTO で書き込まれ、これは稼働中のデータベースに対しても整合性が保たれるため、メンテナンスウィンドウは不要で、エージェントを停止する必要もありません。

一覧の各行には、タイムスタンプ、ディスク上のサイズ、取得されたワークスペースの数、およびスナップショットが完了か不完全かが表示されます。不完全とは、マニフェストが存在しないか、存在しないファイルを指定している場合です。クラッシュやディスク容量不足で中断されたバックアップです。これらも意図的に一覧に残されます。見えないスナップショットは、持っていると思い込んでしまうスナップショットだからです。不完全なスナップショットではインストール全体を復元できませんが、そこに含まれるワークスペースファイルは 1 つずつ採用できます。

行に n ワークスペースを取得せずと表示されることもあります。これは、登録されているものの一度も書き込まれていないワークスペース（ファイルがまだ存在しない）、またはコピーに失敗したワークスペースです。サーバーログを確認してください。

ワークスペースのバックアップと保持をスケジュールする

そのワークスペースの 設定 → パイプライン → パイプラインテンプレートを開き、 Workspace backup を見つけます。有効になっているスケジュールは毎週日曜日の 03:00 UTC に実行され、Back up workspace の後に Delete backups older than （既定では 30 日）が続きます。2 つ目のノードはバックアップが成功した後にのみ実行されます。保持日数はノードで変更でき、スケジュールを無効にすることもできます。予定時刻にサーバーがオフラインだった場合、スケジュールは復帰時に 1 回だけ追いつき、逃した週をすべて再生することはありません。

ワークスペースのバックアップはサーバー上の backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db にあります。保持ノードが削除するのはこのワークスペースの古いバックアップだけで、インストール全体のスナップショットや他のワークスペースのバックアップを削除することはありません。これらのファイルにはデータベースしか含まれません。マシン外で保持するには、これらを別途コピーしてください。

これらのバックアップはインストール全体のスナップショットの一覧とは別です。復元するには、 ワークスペースデータ → インポートでバックアップのサーバー側 workspace.db パスを指定します。インポートはそのワークスペースの現在のデータベースを置き換えるため、復元を元に戻す必要があるかもしれない場合は先にエクスポートしておいてください。

インストール全体のスナップショットを削除する

インストール全体のスナップショットでスナップショット（不完全なものも含む）を展開し、危険セクションのスナップショットを削除を使います。名前を確認します。スナップショットのディレクトリ全体がサーバーから完全に削除されます。コピーが必要な場合は先にダウンロードしてください。ワークスペースのバックアップパイプラインがこれらのスナップショットを削除することはありません。

手元のマシンにコピーを回収する

このページに表示されるパスは、cc_server を実行しているマシン上のものです。それが自分が操作しているマシンでない場合は、ダウンロードボタンを使います。

ワークスペースデータの各ワークスペースの横にある ダウンロード。1 つの .db ファイル用です。
インストール全体のスナップショットの各スナップショットの横にある ダウンロード。スナップショット全体を .zip として取得します。

デスクトップではファイルの保存先を選択し、トーストにその場所が表示されます。Web ではブラウザーのダウンロード先に保存されます。どちらの場合も、進捗はバイト単位で報告されます。これはギガバイト規模になりうる 2 つのペイロードだからです。

どちらも、ボタンを押した時点で新しいコピーを作成してストリーミングし、その後サーバー側のコピーを削除します。ダウンロードは「エクスポートボタンが以前に作成したファイルを取りに行く」ことではありません。

スナップショットのアーカイブを展開すると、スナップショットのレイアウトがそのまま再現されます。だからこそ、その復元はコピーを戻すだけの操作になります。

ワークスペースを別のインストールへ移動する

1 つのワークスペースは 1 つのデータベースファイルなので、その受け渡しはファイル操作です。

ソースサーバーで 設定 → サーバー → バックアップと復元 → ワークスペースデータを開き、ワークスペースを展開してダウンロードを押します。
移動先サーバーで、受け取るワークスペースを作成（または選択）します。
そのワークスペースを展開し、このデバイスから復元の下にあるファイルを選んでアップロードを押します。ダウンロードした .db を選択します。

両方のサーバーが自分が操作している同じマシンであれば、サーバーに保存と インポート → ファイルを選択で、往復なしに同じことができます。インポートダイアログのパスはサーバーホスト上で解決されます。

拒否されずに許可され、ログに記録されるケースが 2 つあります。記録されたワークスペース ID が対象と異なるファイルをインポートする場合（これがワークスペースを複製したり、新しい ID で復元したりする方法です）と、別のインストールのファイルをインポートする場合です。後者の場合、そのファイルのペアリング済みデバイスとユーザー ID は元のインストールに属しており、こちらでは解決されません。ワークスペース自身のデータは無傷ですが、採用後にメンバーシップを再確認してください。

チャットボットのトークンはデータベースの中ではなく隣にあります。そのため、他人に渡すワークスペースに有効な認証情報は含まれません。受け取ったインストールが自身のトークンを再接続します。

スナップショットから 1 つのワークスペースを復元する

インストール全体のスナップショットで、目的のスナップショットを展開します。
そのワークスペースの行を見つけて復元を押します。
確認します。スナップショット取得後にそのワークスペースが行ったことはすべて失われます。

これはインポートと同じ操作を、スナップショット内のそのワークスペースのファイルのコピーに対して行うものです。意図的にそうしてあり、同じファイルを別の扱いにする第 2 の仕組みが存在しないようにしています。

行にこのサーバーにはもう存在しませんと表示され、復元が無効になっていることがあります。スナップショットが、このインストールにもはや存在しないワークスペースを保持しているのです。手作業で戻します。ワークスペースを作成し、次にワークスペースデータで <snapshot path>/<old workspace id>/workspace.db からそのワークスペースへインポートします。展開したスナップショットには、自身のサーバー上のパスがコピー用フィールドに表示され、行のタイトルが古いワークスペース ID なので、そのパスの前半と後半の両方が目の前にそろうことになります。

インストール全体を復元する

これ用のボタンはありませんし、あるべきでもありません。稼働中のサーバーが開いているデータベースを置き換える操作だからです。

cc_server を停止します。 組み込みサーバー付きのデスクトップアプリを実行している場合は、アプリを終了します。

スナップショットの内容をデータディレクトリにコピーします。スナップショットのレイアウトは稼働中のものと同じなので、単純なコピーです。

# 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

置き換えたデータベースの隣にある -wal および -shm ファイルを削除します。これらは古いファイルのもので、復元したデータベースの隣に古いものが残っていると破損のリスクがあります。
サーバーを再起動します。

スナップショットには 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 -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/ にある録画したミーティング音声は、ミーティングを保存しているなら含める価値があります。

アプリの外でインストール全体のスナップショットをスケジュールする

組み込みのパイプラインがバックアップするのは 1 つのワークスペースだけです。無人で インストール全体のスナップショットを取得するための 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 での実行結果を確認してください。1 つだけでなく複数を保持してください。備えたい障害は多くの場合「最後のバックアップにも同じ問題がある」だからです。

バックアップが良好か確認する

誰も復元したことのないバックアップは、仮説にすぎません。

手軽な確認 — ファイルが開き、ページが無傷であること。

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

本格的な確認 — 実際に採用してみます。非本番のインストールに使い捨てのワークスペースを作成し、そこにワークスペースファイルをインポートして、期待するスペース、チケット、メッセージがあるかを確認します。これは FTS の再構築を含め、実際の復元と同じ経路を通り、バックアップが単に読めるだけでなく復元可能であることを教えてくれる唯一の確認です。

バックアップを設定したときに一度、保管場所を変更するたびに再度行ってください。

トラブルシューティング

症状	原因と対処
ダウンロードとアップロードのコントロールが、リレーに関する注記とともに無効になっている	ブローカー経由のリレーを通じて接続しており、これはファイル転送を運びません。直接接続してください
「サーバーに拒否されました」	ロールの問題です。インストール全体のスナップショットの取得または一覧表示にはインストールのオペレーターが必要です。ワークスペースのダウンロードには管理者、復元にはオーナー、スナップショット全体の zip にはインストールのオペレーターが必要です
「このサーバーにはバックアップの仕組みがありません」	ホストにバックアップポートが接続されていません — デモサーバーです。操作は拒否されるのではなく存在しません
「ファイルがサーバーの受け入れ可能なサイズを超えています」	アップロードは 8 GiB が上限です。ファイルをサーバーホストに置き、代わりにインポート → ファイルを選択を使ってください
Import refused: not a Control Center workspace database	そのファイルには `workspace_meta` の行がありません — ワークスペースのエクスポートではないか、切り詰められています。何も置き換えられていません
スナップショットが不完全として一覧に表示される	マニフェストが存在しないか、存在しないファイルを指定しています。新しいものを取得してください。それまでの間は、そこから個々のワークスペースファイルを採用できます
スナップショットにワークスペースを取得していないと表示される	それらのワークスペースは一度も書き込まれていないか、コピーに失敗しています。サーバーログを確認してください
復元したインストールにコードホストまたは SSO の認証情報がない	`secrets.json` はスナップショットに含まれません。保管しておいた場所から復元するか、プロバイダーを再接続してください
復元したワークスペースに貼り付けた画像がない	Blob はデータベースの中ではなく隣にあります。`<workspaceId>/blobs/` も併せてコピーしてください