Эксплуатация¶

Раздел описывает повседневные операции в закрытом контуре: запуск и остановку, логи, резервное копирование, обновление, откат и удаление. Все команды выполняются на хосте Synth или внутри контейнера — внешние сервисы не нужны.

synth update в офлайне не работает

Команда обращается к npm-реестру. В закрытом контуре обновление выполняется заменой бандла и миграцией схемы. Не используйте synth update и synth update --apply как способ обновления.

Запуск и остановка¶

Платформа	Запуск	Остановка
Linux, systemd system	`sudo systemctl start synth`	`sudo systemctl stop synth`
Linux, systemd user	`systemctl --user start synth`	`systemctl --user stop synth`
macOS, LaunchAgent	`launchctl kickstart -k gui/$(id -u)/ru.itphx.synth`	`launchctl bootout gui/$(id -u)/ru.itphx.synth`
Windows	`bin\synth.cmd serve --home <home>`	`Ctrl+C` в консоли или остановить задачу
Docker Compose	`docker compose up -d`	`docker compose stop`
Kubernetes	`kubectl -n synth rollout restart deploy/<deployment>`	`kubectl -n synth scale deploy/<deployment> --replicas=0`

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

curl -fsS http://127.0.0.1:4300/health
curl -fsS http://127.0.0.1:4300/ready
synth doctor
synth doctor --json

/health подтверждает, что процесс жив; /ready — готовность. synth doctor проверяет данные, ключи и провайдеров и возвращает ненулевой код при проблеме.

Логи¶

Способ установки	Где смотреть
systemd system	`sudo journalctl -u synth -f`
systemd user	`journalctl --user -u synth -f`
macOS LaunchAgent	`~/Library/Logs/Synth/synth.out.log`, `synth.err.log`
Windows	`%LOCALAPPDATA%\Synth\logs\synth.out.log`, `synth.err.log`
Docker Compose	`docker compose logs -f synth`
Kubernetes	`kubectl -n synth logs deploy/<backend> -f`

Для диагностики полезно начать с synth doctor --json и последних строк лога. Не публикуйте логи с ключами и токенами.

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

synth backup создаёт архив каталога данных с манифестом. Остановите сервис для согласованного снимка; --live снимает с работающего сервиса, но срез нетранзакционный. Каталог назначения должен быть доступен на запись пользователю сервиса.

# остановить сервис, затем (system-установка — от пользователя synth):
sudo install -d -m 0750 -o synth -g synth /var/backups/synth
sudo -u synth synth backup --out /var/backups/synth

С шифрованием:

synth backup --out /var/backups/synth \
  --encrypt --key-file /etc/synth/backup.key

Ключ — 32 байта в base64 или hex; альтернатива — SYNTH_BACKUP_KEY_FILE или SYNTH_BACKUP_KEY. Храните ключ отдельно от архива.

Флаг	Что делает
`--with-secrets`	Включает `secrets/`; архив сам становится секретом
`--with-workspace`	Включает рабочие каталоги `workspaces/`
`--live`	Снимок с работающего сервиса (нетранзакционный)
`--encrypt`	AES-256-GCM; ключ из `--key-file`/env

По умолчанию секреты и workspace не входят. Если нужен полный перенос, проверьте, что архив хранится в защищённом месте.

Docker¶

docker compose exec synth synth backup --out /tmp
docker compose cp synth:/tmp/<archive> ./backups/

<archive> — имя, которое напечатает команда. Для шифрования передайте ключ внутрь контейнера безопасным способом (Secret/volume), а не в истории shell.

Kubernetes¶

kubectl -n synth exec deploy/<backend> -- synth backup --out /tmp
kubectl -n synth cp <backend-pod>:/tmp/<archive> ./backups/

Для больших каталогов данных используйте backup на уровне PVC/хранилища, предварительно остановив backend.

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

Восстановление возвращает данные к снимку. По умолчанию создаётся страховочная копия текущих данных; --no-safety-copy отключает её (откат станет невозможен).

synth restore /var/backups/synth/<archive> --dry-run
sudo systemctl stop synth
sudo -u synth synth restore /var/backups/synth/<archive> --yes
sudo systemctl start synth

Для зашифрованного архива добавьте --key-file /etc/synth/backup.key. Выполняйте восстановление от того же пользователя, что и сервис, чтобы не сломать владельца файлов (для пользовательской установки sudo не нужен).

Docker (сервис остановлен, архив на хосте):

docker compose stop synth
docker compose run --rm --no-deps \
  -v "$PWD/backups:/backups:ro" \
  --entrypoint synth synth \
  restore /backups/<archive> --yes
docker compose start synth

Обновление¶

Порядок для portable-бандла:

Сделайте backup и проверьте его --dry-run-восстановлением.
Остановите сервис.
Распакуйте новый бандл в отдельный каталог, не поверх работающей установки.
Проверьте SHA256 нового архива.
Запустите установщик из нового бандла: он разложит версию в <prefix>/<version> и переключит symlink current (unit уже указывает на current, править его не нужно):

sudo ./install.sh --system --no-start --no-autostart   # system
# или для пользовательской установки:
./install.sh --no-start --no-autostart

Примените миграции от пользователя сервиса:

sudo -u synth /opt/synth/current/bin/synth migrate --dry-run
sudo -u synth /opt/synth/current/bin/synth migrate --yes

--yes обязателен: без него и без --dry-run команда отказывается работать. 7. Запустите сервис и проверьте /health, /ready, synth doctor и короткий чат с моделью.

sudo systemctl start synth
curl -fsS http://127.0.0.1:4300/health
/opt/synth/current/bin/synth doctor

Тот же порядок для macOS (выгрузить/загрузить LaunchAgent) и Windows (остановить процесс, заменить каталог, запустить synth.cmd).

Контейнеры и Helm¶

# загрузить новые образы
docker load -i synth-<version>-amd64.tar.gz
docker load -i synth-backend-<version>-amd64.tar.gz
docker load -i synth-ui-<version>-amd64.tar.gz

# Compose: обновить тег в compose.yaml и перезапустить
docker compose up -d

# Helm: обновить values и выполнить
helm upgrade synth ./synth-<version>.tgz -n synth -f values.yaml

Перед helm upgrade сделайте backup. Миграции схемы в контейнере выполняйте осознанно (synth migrate --dry-run, затем --yes), так как откат схемы может быть необратим.

Docker Compose (сервис остановлен):

docker compose run --rm --no-deps --entrypoint synth synth migrate --dry-run
docker compose run --rm --no-deps --entrypoint synth synth migrate --yes

В Kubernetes миграции применяются при старте backend (для PostgreSQL — драйвером хранения). Для ручного контроля остановите backend (kubectl -n synth scale deploy/<backend> --replicas=0) и выполните миграцию в одноразовом pod/Job с тем же PVC, затем верните replicas.

Откат¶

Если новая версия не запускается:

Остановите сервис.
Верните предыдущий каталог бандла (или предыдущий тег образа/чарта).
Если миграция уже применена и схема несовместима — восстановите backup:

sudo -u synth synth restore /var/backups/synth/<archive> --yes

Запустите сервис и проверьте synth doctor.

Helm:

helm history synth -n synth
helm rollback synth <revision> -n synth

helm rollback откатывает манифесты, но не данные. Если схема данных уже изменена, нужен restore backup. Поэтому backup перед обновлением обязателен.

Удаление¶

synth uninstall --dry-run
synth uninstall --yes          # удаляет установку, данные сохраняются
synth uninstall --purge --yes  # удаляет и данные (необратимо)

Для PostgreSQL: --purge-db вместе с --purge --yes удаляет схему БД (DROP SCHEMA). Без --yes и без --dry-run команда отказывается работать.

Платформа	Дополнительно
Linux systemd	`sudo systemctl disable --now synth` перед удалением unit
Linux user	`systemctl --user disable --now synth`
macOS	`launchctl bootout gui/$(id -u)/ru.itphx.synth`
Windows	`Unregister-ScheduledTask -TaskName "Synth" -Confirm:$false`
Docker	`docker compose down` (том сохраняется), `down -v` — удаляет данные
Helm	`helm uninstall synth -n synth`; PVC удаляется, если не `keepOnUninstall`

Регламентные проверки¶

Ежедневно: /health, свободное место, ошибки в логах.
Еженедельно: synth doctor, тестовое восстановление backup в отдельный каталог.
Перед изменением: backup, synth migrate --dry-run, план отката.
После изменения: synth doctor, чат с моделью, проверка прав и входа.