Перейти к содержанию

Обслуживание

Эксплуатация инстанса — это регулярный цикл: проверить состояние, снять резервную копию, при необходимости обновиться или перезапуститься, а перед крупными изменениями — перенести данные и убедиться, что всё на месте. Ниже — рабочие процедуры для standalone-установки, Docker и Kubernetes.

В раздел входят: сервис инстанса с автозапуском, проверка инстанса, резервное копирование и восстановление, миграции схемы, обновление и откат, перезапуск, удаление, перенос хранилища, экспорт и импорт проекта и ротация мастер-ключа.

Перед изменяющей операцией

Снимите резервную копию и прогоните synth doctor. Восстановление, миграции, обновление и удаление меняют данные необратимо; страховочная копия есть не у всех команд.

Сервис инстанса: работает всегда

Штатный способ держать локальный инстанс поднятым — userspace-сервис systemd (--user). Он стартует вместе с машиной, переживает выход из сессии пользователя и поднимается заново после сбоя.

synth service install          # поставить сервис, включить автозапуск, запустить
synth service status           # unit, автозапуск, PID, состояние health
synth service logs -f          # журнал сервиса
synth service restart          # перезапуск
synth service uninstall        # снять unit (данные инстанса сохраняются)
Что Как сделано
Где живёт unit ~/.config/systemd/user/synth.service (или $XDG_CONFIG_HOME/systemd/user/)
Автозапуск systemctl --user enable — инстанс поднимается после перезагрузки машины
Работа без сессии loginctl enable-linger — сервис не останавливается на выходе из сессии
Перезапуск Unit настроен на graceful restart: процесс завершается с кодом 75, systemd поднимает его заново
Секреты В unit и env-файл не попадают; env-файл создаётся с правами 0600, ключ доступа создаёт сам сервер

Только Linux + systemd

На macOS и Windows команда сообщает о неподдерживаемости и ничего не меняет. Для других сценариев используйте Docker, Kubernetes или запуск вручную.

Полезные флаги synth service install: --port / --host, --home / --data-dir, --config (только значения по умолчанию — в unit не пишутся), --connect (гибридный режим), --no-autostart, --no-start, --no-linger, --force (перезаписать чужой unit), --print-unit и --dry-run (показать unit и план, ничего не записывая).

Чужой unit не перезаписывается

Если unit создан не командой synth service install, команда его не тронет — нужен явный --force. Это относится и к unit, созданному установщиком офлайн-поставки: такой unit ведёт себя по-своему, поэтому сначала посмотрите разницу (synth service install --print-unit), а потом переходите на управляемый сервис. Подробнее — systemd в офлайн-поставке.

Проверка инстанса

Основной инструмент — synth doctor. Он проверяет каталог данных, схему, мастер-ключ, целостность JSON, права на секреты и, для PostgreSQL, соединение с базой. Для машинной обработки добавьте --json.

synth doctor
synth doctor --json
docker compose exec synth synth doctor
kubectl -n synth exec deploy/<backend> -- synth doctor
Код выхода Что значит
0 Все проверки без fail — инстанс здоров
1 Есть хотя бы одна проверка со статусом fail

warn — повод разобраться, но не блокер: например, ожидающие миграции схемы, неверные права на каталог секретов или стухший lock-файл. fail — это недоступный каталог данных, битый мастер-ключ, повреждённые JSON-файлы или данные новее установленной версии.

Дополнительно проверьте, что процесс отвечает:

curl -s localhost:5000/health

Успех — HTTP 200 и status: "healthy". В деградированном режиме хранилища ответ остаётся 200, но status становится degraded. Порт — тот же, что у API: у backend это 5000, у standalone — 4300. Подробности — в разделе Метрики и наблюдаемость.

Резервная копия

synth backup собирает архив каталога данных с манифестом и контрольной суммой. По умолчанию сервис должен быть остановлен — так получается согласованный срез. Снимок с работающего сервиса (--live) валиден по файлам, но не транзакционен: связи между сущностями могут разойтись.

# сервис остановлен
synth backup --out /backups/synth

# с шифрованием внешним ключом оператора
synth backup --out /backups/synth \
  --encrypt --key-file /etc/synth/backup.key
Флаг Что включает
--with-secrets Каталог secrets/; архив сам становится секретом
--with-workspace Рабочие каталоги проектов
--live Снимок с работающего сервиса (нетранзакционный)
--encrypt Шифрование AES-256-GCM; ключ — --key-file или переменная окружения

Без --with-secrets архив не восстановит зашифрованные SSH-ключи и другие секреты. Без --with-workspace рабочие файлы проектов в архив не попадают. Ключ шифрования храните отдельно: архив и ключ вместе — это уже секрет.

PostgreSQL

synth backup снимает только файловый периметр: настройки, секреты, вложения и другие объекты на томе. Данных базы в архиве нет. Полный бэкап БД-режима — две процедуры: дамп или снапшот базы (pg_dump, pg_basebackup, PITR) и архив тома. Порознь ни одна не полна.

Восстановление

Восстановление — офлайн-операция: сервис должен быть остановлен, иначе файлы будут перезаписаны под работающим процессом.

synth restore /backups/synth/<archive> --dry-run
synth restore /backups/synth/<archive> --yes

--dry-run проверяет манифест, формат, версию схемы и контрольные суммы и печатает план, ничего не записывая. --yes применяет план. Без --dry-run и без --yes команда отказывается работать.

Перед записью автоматически создаётся страховочная копия текущих данных в каталоге backups/. Она же сохраняется при очистке — вместе с workspaces/, если архив снят без рабочих каталогов. Зашифрованный архив восстанавливается только через CLI с ключом (--key-file или переменная окружения); через интерфейс такой архив не принимается.

Порядок для PostgreSQL:

  1. Остановить сервис.
  2. Восстановить базу средствами СУБД (pg_restore, PITR).
  3. Восстановить файловый периметр командой synth restore — включая объекты вложений и артефактов.
  4. Прогнать synth doctor.

Оба периметра — база и том — откатывайте к одному моменту времени. Иначе вложения и артефакты могут ссылаться на объекты, которых в восстановленном периметре нет. Если схема в архиве старше установленной версии, после восстановления выполните synth migrate.

Миграции схемы

При старте инстанс сам применяет ожидающие миграции, предварительно создавая страховочную копию. Вручную тот же контур выглядит так:

synth migrate --dry-run
synth migrate --yes
  • --dry-run показывает текущую и ожидаемую версию, список миграций и число записей, которые будут обновлены.
  • --yes применяет миграции. Без --dry-run и без --yes — отказ.
  • Повторный прогон безопасен: уже применённые миграции пропускаются.

При storage.backend: postgres миграции нужно применить до запуска новой версии Synth. Если данные новее установленного пакета, старт и synth migrate откажутся работать: обновите Synth, а не пытайтесь откатить данные.

Обновление и откат

Порядок:

  1. Снимите резервную копию.
  2. Проверьте доступную версию и план установки.
  3. Примените обновление.
  4. Убедитесь, что версия и состояние корректны.
synth update --check                  # что доступно (ничего не ставится)
synth update --dry-run                # план установки
synth update --apply                  # установить найденную версию
synth update --to 0.13.10 --apply     # конкретная версия — и откат тоже
synth --version
synth doctor

synth update без флагов только показывает текущую и целевую версию. --apply устанавливает последнюю версию канала, --to <version> --apply — конкретную, в том числе более старую для отката.

Каналы обновлений

Канал Что в нём Как задан
auto Канал выводится из установленной версии: сборка с пометкой -beta. остаётся на бета-канале, обычная — на стабильном По умолчанию
stable Обычные релизы --channel stable или конфигурация
beta Предрелизные сборки из внутреннего реестра --channel beta или конфигурация
synth update --channel beta --check   # что доступно в бетах
synth update --channel beta --apply   # поставить бету
synth update --channel stable --apply # вернуться на стабильную линию
  • Возврат на стабильный канал — понижение версии, поэтому он требует подтверждения.
  • Автопроверка по умолчанию выключена: инстанс не ходит в реестры без явного согласия владельца (важно для закрытого контура). Включить её можно в интерфейсе (Настройки → Панель управления → Обновления) или в конфигурации — раздел updates.
  • Свой реестр. --registry <url> переопределяет реестр канала: так обновляются инстансы за прокси или в закрытом контуре. Для чтения внутреннего реестра токен не нужен.
  • После установки — перезапуск. Если инстанс работает как сервис, новый пакет подхватится после synth service restart.

Понижение версии не откатывает данные

Откат пакета и откат данных — разные операции. Данные возвращаются только из резервной копии, снятой до обновления. Схема, созданная новой версией, назад не мигрирует.

В Kubernetes обновление и откат выполняются чартом:

helm upgrade synth synth/synth -f my-values.yaml -n synth
helm rollback synth <revision> -n synth

Перед раскаткой проверьте, что база и тома забэкаплены. После обновления прогоните synth doctor и проверьте /health.

Перезапуск инстанса

Перезапуск нужен, когда настройки читаются только при старте: TLS и доверенные CA, прокси, пул PostgreSQL, MCP-клиенты. Команда не переинициализирует процесс «изнутри»: API только инициирует штатное завершение, а поднимает процесс внешний супервизор.

GET  /api/v2/maintenance/restart
POST /api/v2/maintenance/restart
{"confirm": true}

POST отвечает 202 и {status: "restarting", restartId, mode, startedAt}, после чего процесс завершается с кодом 75 (временный отказ). Режим задаётся переменной SYNTH_RESTART_MODE или флагом synth serve --restart-mode (флаг приоритетнее):

Режим Поведение
disabled По умолчанию. supported: false, POST → 409 RESTART_UNSUPPORTED
process Выход с кодом 75; процесс поднимает супервизор (systemd, Docker, Kubernetes)
supervisor То же, но для локального dev-запуска со встроенным супервизором

В интерфейсе перезапуск доступен в Настройки → «Обслуживание» → «Перезапуск». Если режим выключен, кнопки нет и показана причина.

Если инстанс поставлен как сервис (synth service install), режим process уже настроен в unit — перезапуск из интерфейса поднимает процесс сам. Вручную то же самое делает synth service restart.

Что прерывается

Активные ответы модели, выполняющиеся инструменты и ходы агента, HTTP-запросы и подписки WS/SSE на этом процессе обрываются. Очередь сообщений и состояние сессий сохраняются, но незавершённый ход нужно повторить. Фоновая работа не возобновляется: запущенные процессы помечаются прерванными, незавершённые вопросы отменяются. Терминальные записи и логи остаются доступны.

Ожидания подтверждений переживают перезапуск

Запрос подтверждения прав не пропадает: после перезапуска полоса подтверждения восстанавливается с пометкой, что инстанс был перезапущен, а ответ «разрешить» действует в рамках одобренного — для доступа к каталогу вне рабочего каталога это грант каталогом, а для изменения или удаления данных, защищённого пути и смены рабочего каталога постоянное правило не выдаётся и вопрос повторится. Подробнее — Режимы и права.

После возврата startedAt в /health меняется — по нему интерфейс и скрипты отличают новый процесс от старого. В multi-replica окружении эндпоинт перезапускает только тот pod, который обработал запрос. Чтобы перезапустить всё развёртывание, используйте kubectl rollout restart deployment/<name>.

Удаление инстанса

По умолчанию synth uninstall ничего не удаляет: команда показывает сводку каталога данных — размер, число сессий и проектов, наличие секретов и мастер- ключа, версию схемы.

synth uninstall
synth uninstall --dry-run
synth uninstall --purge --yes
synth uninstall --purge --purge-db --yes

--purge удаляет каталог данных рекурсивно. Без --yes команда отказывается. При storage.backend: postgres данные базы по умолчанию сохраняются; для их удаления нужен явный --purge-db, причём только вместе с --purge и --yes. Схема базы удаляется через DROP SCHEMA … CASCADE — это необратимо.

Удаление необратимо

Вместе с каталогом данных удаляются мастер-ключ и страховочные копии. Зашифрованные SSH-ключи после этого восстановить нельзя. Если данные нужны, сначала снимите резервную копию и проверьте её восстановление.

В Helm судьба томов зависит от значения persistence.keepOnUninstall. По умолчанию чарт удаляет PVC вместе с релизом. Если данные должны пережить helm uninstall, выставьте keepOnUninstall: true заранее — аннотация на живом PVC после установки не поможет.

Перенос хранилища

Смена физического backend'а — отдельная идемпотентная операция:

synth storage migrate --to postgres --dry-run
synth storage migrate --to postgres --yes

synth storage migrate --to file --target-data-dir /var/synth/data-files --yes

Сначала выполните --dry-run: команда печатает счётчики переносимых записей. Затем повторите с --yes. Перед переносом снимите резервную копию обоих периметров. Подробности о полях и предусловиях — в разделе Конфигурация.

Экспорт и импорт проекта

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

synth project export <projectId> --out /backups
synth project export <projectId> --with-workspace --out /backups

synth project import /backups/<archive> --dry-run
synth project import /backups/<archive> --yes
synth project import /backups/<archive> --name "Новый проект" --with-workspace --yes
Флаг Назначение
--with-workspace Включить или восстановить рабочий каталог проекта
--with-secrets Оставить карту обфускации секретов; только ADMIN и LEAD
--dry-run Проверить архив и показать план без записи
--yes Применить импорт
--name Имя нового проекта
--merge-into Импортировать сессии в существующий проект

По умолчанию в архиве нет секретов: карта обфускации вырезается. Архив, собранный с --with-secrets, сам является секретом — храните его соответственно и передавайте только по защищённому каналу. Импорт без --dry-run и --yes отказывается работать.

Ротация мастер-ключа

Мастер-ключ шифрует секреты в хранилище, например SSH-ключи агентов. Ротация перешифровывает существующие секреты со старого ключа на новый и обновляет master.key.

synth secrets rotate --dry-run
synth secrets rotate --yes

Порядок: preflight-проверка, перешифровка, запись нового мастер-ключа. Если preflight находит нерасшифровываемое поле, команда прерывается и ничего не пишет. Без --yes и без --dry-run — отказ.

Перед ротацией остановите сервис и снимите резервную копию. Если эффективный ключ задан через переменную окружения или config.yaml, обновите его и там: файл master.key будет перезаписан, но при старте проигнорирован.

Что дальше