Обслуживание¶
Эксплуатация инстанса — это регулярный цикл: проверить состояние, снять резервную копию, при необходимости обновиться или перезапуститься, а перед крупными изменениями — перенести данные и убедиться, что всё на месте. Ниже — рабочие процедуры для 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.
| Код выхода | Что значит |
|---|---|
0 |
Все проверки без fail — инстанс здоров |
1 |
Есть хотя бы одна проверка со статусом fail |
warn — повод разобраться, но не блокер: например, ожидающие миграции схемы,
неверные права на каталог секретов или стухший lock-файл. fail — это
недоступный каталог данных, битый мастер-ключ, повреждённые JSON-файлы или
данные новее установленной версии.
Дополнительно проверьте, что процесс отвечает:
Успех — 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) и архив тома. Порознь ни одна не полна.
Восстановление¶
Восстановление — офлайн-операция: сервис должен быть остановлен, иначе файлы будут перезаписаны под работающим процессом.
--dry-run проверяет манифест, формат, версию схемы и контрольные суммы и
печатает план, ничего не записывая. --yes применяет план. Без --dry-run и без
--yes команда отказывается работать.
Перед записью автоматически создаётся страховочная копия текущих данных в
каталоге backups/. Она же сохраняется при очистке — вместе с workspaces/,
если архив снят без рабочих каталогов. Зашифрованный архив восстанавливается
только через CLI с ключом (--key-file или переменная окружения); через
интерфейс такой архив не принимается.
Порядок для PostgreSQL:
- Остановить сервис.
- Восстановить базу средствами СУБД (
pg_restore, PITR). - Восстановить файловый периметр командой
synth restore— включая объекты вложений и артефактов. - Прогнать
synth doctor.
Оба периметра — база и том — откатывайте к одному моменту времени. Иначе
вложения и артефакты могут ссылаться на объекты, которых в восстановленном
периметре нет. Если схема в архиве старше установленной версии, после
восстановления выполните synth migrate.
Миграции схемы¶
При старте инстанс сам применяет ожидающие миграции, предварительно создавая страховочную копию. Вручную тот же контур выглядит так:
--dry-runпоказывает текущую и ожидаемую версию, список миграций и число записей, которые будут обновлены.--yesприменяет миграции. Без--dry-runи без--yes— отказ.- Повторный прогон безопасен: уже применённые миграции пропускаются.
При storage.backend: postgres миграции нужно применить до запуска новой
версии Synth. Если данные новее установленного пакета, старт и synth migrate
откажутся работать: обновите Synth, а не пытайтесь откатить данные.
Обновление и откат¶
Порядок:
- Снимите резервную копию.
- Проверьте доступную версию и план установки.
- Примените обновление.
- Убедитесь, что версия и состояние корректны.
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 обновление и откат выполняются чартом:
Перед раскаткой проверьте, что база и тома забэкаплены. После обновления
прогоните synth doctor и проверьте /health.
Перезапуск инстанса¶
Перезапуск нужен, когда настройки читаются только при старте: TLS и доверенные CA, прокси, пул PostgreSQL, MCP-клиенты. Команда не переинициализирует процесс «изнутри»: API только инициирует штатное завершение, а поднимает процесс внешний супервизор.
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.
Порядок: preflight-проверка, перешифровка, запись нового мастер-ключа. Если
preflight находит нерасшифровываемое поле, команда прерывается и ничего не
пишет. Без --yes и без --dry-run — отказ.
Перед ротацией остановите сервис и снимите резервную копию. Если эффективный
ключ задан через переменную окружения или config.yaml, обновите его и там:
файл master.key будет перезаписан, но при старте проигнорирован.
Что дальше¶
- Конфигурация — хранилище, PostgreSQL, секреты и параметры запуска.
- CLI — сервис, обновления и реестр MCP из терминала.
- Безопасность — аудит, права и защита секретов.
- Эксплуатация в закрытом контуре — обслуживание офлайн-поставки.
- Метрики и наблюдаемость — здоровье инстанса и алерты.