Резервное копирование и восстановление

Это руководство охватывает пять действий, которые люди на самом деле совершают с резервными копиями: создать копию, забрать её, перенести рабочее пространство, вернуть его обратно и хранить копии за пределами машины. Точная форма каждого артефакта и операции описана в справочнике по резервному копированию.

Всё это находится в разделе Настройки → Сервер → Резервное копирование и восстановление.

Прежде чем начать

• Полноценный клиент — приложение для компьютера или веб-приложение. Сопряжённый телефон не может запустить ничего из этого — так задумано.
• Чтобы создать, просмотреть, скачать или удалить снимок установки, нужен владелец установки.
• Для действий с отдельным рабочим пространством: администратор этого рабочего пространства — для экспорта, владелец — для импорта или удаления.
• Для скачивания и загрузки: прямое подключение к серверу. Брокерский ретранслятор передаёт кадры RPC, а не файлы, и элементы управления передачей отключаются с пояснением, когда вы подключены через него.

Снимки установки создаются вручную

Создать снимок по-прежнему создаёт снимок всей установки только по запросу. Встроенный конвейер Workspace backup может вместо этого раз в неделю снимать резервную копию базы данных рабочего пространства и удалять резервные копии этого рабочего пространства старше 30 дней. Он не копирует global.db, другие рабочие пространства или файлы рядом с базой данных. Копии за пределами машины храните отдельно.

Что охватывает резервная копия

Оба артефакта — только базы данных:

• Снимок установки — это каталог с отметкой времени: manifest.json, global.db и по одному <workspaceId>/workspace.db на каждое рабочее пространство.
• Экспорт рабочего пространства — это тот самый единственный файл workspace.db.

Ни один из них не несёт остального содержимого каталога данных: secrets.json (ключи сопряжения, учётные данные провайдеров, SSO), blobs/ рабочего пространства (изображения, вставленные в сообщения), skills/, agents/, chat_credentials/, записанное аудио встреч или образы rig. Что-то из этого расходуемо, что-то нет — полная таблица есть в справочнике, и именно для этого нужен раздел про копии за пределами машины.

Создайте снимок всей установки

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.

На компьютере вы выбираете, куда попадёт файл, и уведомление называет его; в веб-версии файл уходит в загрузки браузера. В обоих случаях прогресс показывается в байтах, потому что только эти две передачи доходят до гигабайтов.

Обе кнопки создают свежую копию в момент нажатия, передают её потоком и после этого удаляют копию на сервере — скачивание не означает «забрать файл, который кнопка экспорта создала ранее».

Распаковка архива снимка в точности воспроизводит структуру снимка — именно поэтому восстановление из него и есть обратное копирование.

Перенесите рабочее пространство в другую установку

Одно рабочее пространство — это один файл базы данных, поэтому его передача сводится к файловой операции.

1. На исходном сервере откройте Настройки → Сервер → Резервное копирование и восстановление → Данные рабочего пространства, разверните рабочее пространство и нажмите Скачать.
2. На целевом сервере создайте (или выберите) рабочее пространство, которое его примет.
3. Разверните это рабочее пространство и в разделе Восстановить с этого устройства нажмите Выберите файл и загрузите. Выберите скачанный .db.

Если оба сервера — это одна и та же машина, за которой вы сидите, то Сохранить на сервере вместе с Импорт → Выбрать файл делают то же самое без лишнего круга; пути в диалоге импорта разрешаются на хосте сервера.

Импорт заменяет всё

Импорт перезаписывает всё, что сейчас содержит целевое рабочее пространство, и отменить его нельзя. Сначала экспортируйте целевое рабочее пространство, если в нём есть что-то, что вы хотели бы вернуть.

Две вещи разрешаются и записываются в журнал, а не отклоняются: импорт файла, записанный идентификатор рабочего пространства в котором отличается от целевого (так вы дублируете рабочее пространство или восстанавливаете его под новым идентификатором), и импорт файла из другой установки. Во втором случае сопряжённые устройства и идентификаторы пользователей из файла принадлежат установке, откуда он пришёл, и не разрешатся в этой — собственные данные рабочего пространства целы, но после его принятия перепроверьте состав участников.

Токены чат-ботов лежат рядом с базой данных, а не внутри неё, поэтому рабочее пространство, которое вы передаёте кому-то другому, не несёт действующих учётных данных. Принимающая установка подключает свои.

Восстановите одно рабочее пространство из снимка

1. В разделе Снимки установки разверните нужный снимок.
2. Найдите строку рабочего пространства и нажмите Восстановить.
3. Подтвердите. Всё, что рабочее пространство сделало с момента создания снимка, будет потеряно.

Это та же операция, что и импорт, только нацеленная на копию файла этого рабочего пространства внутри снимка — намеренно, чтобы не было второго механизма, который мог бы обработать тот же файл иначе.

Строка может гласить Больше нет на этом сервере, а Восстановить будет отключена: снимок содержит рабочее пространство, которого в этой установке больше нет. Верните его вручную — создайте рабочее пространство, а затем в разделе Данные рабочего пространства импортируйте в него из <snapshot path>/<old workspace id>/workspace.db. Развёрнутый снимок показывает собственный Путь на сервере в поле для копирования, а заголовок строки — это старый идентификатор рабочего пространства, так что обе половины этого пути у вас перед глазами.

Восстановите всю установку

Кнопки для этого нет, и быть не должно: это заменяет базы данных, которые держит открытыми работающий сервер.

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/ (worktree с копированием при записи, заново создаваемые из ваших репозиториев), 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 {} +

Проверьте вывод прогона с -print, прежде чем добавлять -exec. Храните больше одного снимка: сбой, от которого вы защищаетесь, часто звучит как «у последней резервной копии та же проблема».

Проверьте, что резервная копия пригодна

Резервная копия, которую никто не восстанавливал, — это гипотеза.

Дешёвая проверка — файл открывается, а его страницы целы:

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

Настоящая проверка — принять её. Создайте черновое рабочее пространство в нерабочей установке, импортируйте в него файл рабочего пространства и посмотрите, на месте ли пространства, тикеты и сообщения, которые вы ожидаете. Это задействует тот же путь, что и настоящее восстановление, включая перестройку FTS, и это единственная проверка, которая говорит, что резервную копию можно восстановить, а не просто прочитать.

Сделайте это один раз при настройке резервного копирования и ещё раз всякий раз, когда меняете место их хранения.

Устранение неполадок

Симптом	Причина и решение
Элементы управления скачиванием и загрузкой отключены с пояснением про ретранслятор	Вы подключены через брокерский ретранслятор, который не передаёт файлы. Подключитесь напрямую
«Сервер отказал»	Роль. Для создания или просмотра снимка установки нужен оператор установки. Для скачивания рабочего пространства нужна роль администратора, для восстановления — владельца, а для zip всего снимка — оператор установки
«У этого сервера нет интерфейса резервного копирования»	На хосте не подключён порт резервного копирования — это демо-сервер. Операции отсутствуют, а не отклоняются
«Файл больше, чем принимает сервер»	Загрузки ограничены 8 GiB. Положите файл на хост сервера и вместо этого используйте Импорт → Выбрать файл
Импорт отклонён: это не база данных рабочего пространства Control Center	В файле нет строки workspace_meta — это не экспорт рабочего пространства или он обрезан. Ничего не было заменено
Снимок помечен как Неполный	Его манифест отсутствует или называет отсутствующие файлы. Создайте новый снимок, а пока перенимайте из него отдельные файлы рабочих пространств
Снимок сообщает, что рабочие пространства не попали в него	В эти рабочие пространства никогда не писали, или их копирование не удалось. Проверьте журнал сервера
В восстановленной установке нет учётных данных хоста кода или SSO	secrets.json не входит в снимок. Восстановите его из того места, где вы его хранили, или подключите провайдеров заново
В восстановленном рабочем пространстве нет вставленных изображений	Двоичные объекты лежат рядом с базой данных, а не внутри неё. Скопируйте также <workspaceId>/blobs/

Связанные руководства

• Запустить headless-сервер: откуда берётся каталог данных
• Подключиться к удалённому серверу: прямые и ретранслируемые подключения
• Привязать устройство: учётные данные, которыми подписываются маршруты передачи

Связанные понятия и справка

• Резервное копирование, экспорт и импорт: каждая операция, маршрут, поле и ограничение
• Рабочие пространства и изоляция: почему одно рабочее пространство — это один файл
• CLI cc_server: структура каталога данных