Резервне копіювання та відновлення

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

Усе описане тут міститься в розділі Налаштування → Сервер → Резервні копії та відновлення.

Передумови

• Повноцінний клієнт — настільний застосунок або вебзастосунок. Спарений телефон не може запустити нічого з цього — так задумано.
• Щоб зробити, переглянути, завантажити чи видалити знімок інсталяції, потрібно бути власником інсталяції.
• Для дій з окремим робочим простором: адмін цього робочого простору для експорту, власник — для імпорту чи видалення.
• Для завантажень і вивантажень: пряме з’єднання із сервером. Ретранслятор-посередник передає кадри 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/ (робочі дерева з копіюванням під час запису, які створюються заново з ваших репозиторіїв), 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, і це єдина перевірка, яка каже, що копію можна відновити, а не лише прочитати.

Зробіть це один раз, коли налаштовуєте резервні копії, і ще раз щоразу, коли змінюєте місце їхнього зберігання.

Усунення проблем

Симптом	Причина та виправлення
Елементи керування завантаженням і вивантаженням вимкнено із приміткою про ретранслятор	Ви підключені через ретранслятор-посередник, який не передає файли. Підключіться напряму
«Сервер відмовив»	Роль. Щоб зробити чи переглянути знімок інсталяції, потрібен operator інсталяції. Щоб завантажити робочий простір, потрібен адмін, щоб відновити — власник, а для ZIP-архіву цілого знімка — operator інсталяції
«На цьому сервері немає поверхні резервного копіювання»	На хості не під’єднано порт резервного копіювання — це демонстраційний сервер. Операції відсутні, а не відхилені
«Файл більший, ніж приймає сервер»	Вивантаження обмежене 8 GiB. Покладіть файл на хост сервера й скористайтеся Імпортувати → Вибрати файл
Імпорт відхилено: це не база даних робочого простору Control Center	У файлі немає рядка workspace_meta — це не експорт робочого простору або файл обрізано. Нічого не було замінено
Знімок позначено як Неповний	Його маніфест відсутній або вказує на відсутні файли. Зробіть новий знімок; тим часом приймайте з нього окремі файли робочих просторів
Знімок каже, що частину робочих просторів не захоплено	До цих робочих просторів ніколи не записували, або їхню копію не вдалося зробити. Перевірте журнал сервера
У відновленій інсталяції немає облікових даних хостингу коду чи SSO	secrets.json не входить до знімка. Відновіть його з місця, де ви його зберігали, або під’єднайте провайдерів заново
У відновленому робочому просторі бракує вставлених зображень	Блоби лежать поряд із базою даних, а не в ній. Скопіюйте також <workspaceId>/blobs/

Пов’язані посібники

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

Пов’язані поняття та довідка

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