백업 및 복원

이 가이드에서는 사람들이 백업으로 실제로 하는 다섯 가지 일, 즉 백업 만들기, 백업 수집하기, 워크스페이스 옮기기, 백업 복원하기, 머신 밖에 사본 보관하기를 다룹니다. 모든 아티팩트와 작업의 정확한 형태는 백업 레퍼런스를 참고하세요.

여기서 설명하는 모든 것은 설정 → 서버 → 백업 및 복원에 있습니다.

사전 요구 사항

풀 클라이언트 — 데스크톱 또는 웹 앱입니다. 페어링된 휴대폰은 설계상 이 중 어느 것도 실행할 수 없습니다.
설치 스냅샷을 만들거나 나열, 다운로드, 삭제하려면 설치의 소유자여야 합니다.
워크스페이스별 작업의 경우: 내보내려면 해당 워크스페이스의 관리자, 가져오거나 삭제하려면 소유자여야 합니다.
다운로드와 업로드의 경우: 서버에 직접 연결해야 합니다. 브로커 릴레이는 파일 전송이 아니라 RPC 프레임을 운반하며, 릴레이를 통해 연결하면 전송 컨트롤이 안내 문구와 함께 비활성화됩니다.

백업이 포함하는 범위

두 아티팩트 모두 데이터베이스만 담습니다:

설치 스냅샷은 타임스탬프가 붙은 디렉터리로, manifest.json, global.db, 그리고 워크스페이스마다 하나씩 있는 <workspaceId>/workspace.db로 이루어집니다.
워크스페이스 내보내기는 그 workspace.db 파일 하나입니다.

둘 다 데이터 디렉터리의 나머지는 담지 않습니다. secrets.json(페어링 키, 공급자 자격 증명, SSO), 워크스페이스의 blobs/(메시지에 붙여 넣은 이미지), skills/, agents/, chat_credentials/, 녹음한 회의 오디오, 리그 이미지 등입니다. 그중 일부는 버려도 되는 것이고 일부는 아닙니다. 전체 표는 레퍼런스에 있고, 이를 다루는 방법이 바로 머신 밖 섹션의 목적입니다.

설치 전체의 스냅샷 만들기

설정 → 서버 → 백업 및 복원을 엽니다.
설치 스냅샷에서 지금 백업을 누릅니다.
토스트에 서버 호스트에서 기록된 디렉터리 이름이 표시됩니다. 새 스냅샷은 목록 맨 위에 나타납니다.

스냅샷을 만드는 동안에도 서버는 계속 실행됩니다. 각 파일은 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으로 받습니다.

데스크톱에서는 파일이 저장될 위치를 직접 고르고 토스트에 그 이름이 표시되며, 웹에서는 브라우저의 다운로드 폴더로 들어갑니다. 어느 쪽이든 둘 다 바이트 단위로 진행률을 보고합니다. 이 두 가지가 기가바이트까지 커지는 페이로드이기 때문입니다.

둘 다 버튼을 누르는 순간 새 사본을 만들어 스트리밍하고, 그 뒤에 서버의 사본을 삭제합니다. 다운로드는 “내보내기 버튼이 앞서 만들어 둔 파일을 가져오는 것”이 아닙니다.

스냅샷 아카이브의 압축을 풀면 스냅샷 구조가 그대로 재현되며, 그래서 스냅샷을 복원하는 일은 곧 다시 복사하는 일이 됩니다.

워크스페이스를 다른 설치로 이동하기

워크스페이스 하나는 데이터베이스 파일 하나이므로, 넘겨주는 일은 파일 작업입니다.

원본 서버에서 설정 → 서버 → 백업 및 복원 → 워크스페이스 데이터를 열고, 워크스페이스를 펼친 뒤 다운로드를 누릅니다.
대상 서버에서 이 워크스페이스를 받을 워크스페이스를 만들거나 고릅니다.
그 워크스페이스를 펼치고 이 기기에서 복원 아래에서 파일 선택 후 업로드를 누릅니다. 다운로드한 .db를 고릅니다.

두 서버가 지금 앉아 있는 같은 머신이라면, 서버에 저장과 가져오기 → 파일 선택이 왕복 없이 같은 일을 합니다. 가져오기 대화 상자의 경로는 서버 호스트에서 해석됩니다.

거부되지 않고 허용되며 기록만 되는 경우가 두 가지 있습니다. 기록된 워크스페이스 id가 대상과 다른 파일을 가져오는 경우(이렇게 워크스페이스를 복제하거나 새 id로 복원합니다)와, 다른 설치의 파일을 가져오는 경우입니다. 두 번째 경우 그 파일의 페어링된 기기와 사용자 id는 파일이 온 설치에 속하므로 이 설치에서는 해석되지 않습니다. 워크스페이스 자체의 데이터는 온전하지만, 가져온 뒤에는 멤버십을 다시 확인하세요.

채팅 봇 토큰은 데이터베이스 안이 아니라 옆에 있으므로, 남에게 넘긴 워크스페이스에는 살아 있는 자격 증명이 들어 있지 않습니다. 받는 설치가 자체 토큰을 다시 연결합니다.

스냅샷에서 워크스페이스 하나 복원하기

설치 스냅샷에서 원하는 스냅샷을 펼칩니다.
그 워크스페이스의 행을 찾아 복원을 누릅니다.
확인합니다. 스냅샷을 만든 뒤 그 워크스페이스가 한 모든 일은 사라집니다.

이것은 가져오기와 같은 작업을, 스냅샷 안에 있는 그 워크스페이스 파일의 사본을 향해 실행하는 것입니다. 일부러 그렇게 했습니다. 같은 파일을 다르게 취급할 수 있는 두 번째 메커니즘을 두지 않기 위해서입니다.

행에 이 서버에 더 이상 없습니다라고 표시되고 복원이 비활성화되어 있을 수 있습니다. 스냅샷이 이 설치에 더 이상 없는 워크스페이스를 담고 있는 것입니다. 수동으로 되살리세요. 워크스페이스를 만든 뒤 워크스페이스 데이터 아래에서 <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/ 아래의 녹음한 회의 오디오는 포함할 가치가 있습니다.

앱 밖에서 설치 전체 스냅샷 예약하기

기본 제공 파이프라인은 워크스페이스 하나만 백업합니다. 무인 설치 전체 스냅샷을 위해서는 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가 상한입니다. 파일을 서버 호스트에 두고 대신 가져오기 → 파일 선택을 사용하세요
Import refused: not a Control Center workspace database	그 파일에 `workspace_meta` 행이 없습니다 — 워크스페이스 내보내기가 아니거나 잘렸습니다. 아무것도 교체되지 않았습니다
스냅샷이 미완료로 나열됨	매니페스트가 없거나 없는 파일을 가리킵니다. 새로 하나 만드세요. 그동안에는 그 안의 개별 워크스페이스 파일을 가져올 수 있습니다
스냅샷에 워크스페이스가 캡처되지 않았다고 표시됨	그 워크스페이스는 한 번도 기록된 적이 없거나 복사에 실패했습니다. 서버 로그를 확인하세요
복원한 설치에 코드 호스트나 SSO 자격 증명이 없음	`secrets.json`은 스냅샷에 들어 있지 않습니다. 보관해 둔 곳에서 복원하거나 공급자를 다시 연결하세요
복원한 워크스페이스에 붙여 넣은 이미지가 없음	Blob은 데이터베이스 안이 아니라 옆에 있습니다. `<workspaceId>/blobs/`도 함께 복사하세요