elmprodvpn/docs/phase-b/B5_SINGBOX_TEMPLATE_MIGRATION_ROLLBACK_RUNBOOK.md

B5 SingBox Template Migration And Rollback Runbook

Цель

Операционный runbook для миграции legacy singbox-<id>.service к template-модели singbox@<id>.service и для аварийного отката при инциденте деплоя.

Контекст текущей модели

• Целевой runtime: singbox@.service + per-instance drop-in singbox@<id>.service.d/10-selective-vpn.conf.
• One-shot миграция legacy unit выполняется автоматически в pre-action (start/restart) для kind=singbox.
• Safety guard: legacy unit обрабатывается только при ownership marker Environment=SVPN_TRANSPORT_ID=<client_id>.

Preflight перед деплоем

1. Проверить runtime-зависимости:
   • scripts/check_runtime_dependencies.sh
2. Проверить strict-режим (опционально для CI/релиза):
   • scripts/check_runtime_dependencies.sh --strict
3. Проверить наличие template unit:
   • systemctl list-unit-files 'singbox@.service' --no-legend

Управление миграцией

• Отключить авто-миграцию для профиля:
  • config.singbox_legacy_unit_migrate=false
• Включить dry-run без изменений unit-файлов:
  • config.singbox_legacy_unit_migrate_dry_run=true
• Поведение dry-run:
  • backend пишет trace/stdout о планируемом legacy -> template переходе,
  • stop/disable/remove не выполняются.

Нормальный migrate-путь

1. Обновить API-бинарь и перезапустить selective-vpn-api.service.
2. На start/restart конкретного SingBox-клиента backend:
   • валидирует ownership legacy unit,
   • выполняет stop + disable + remove legacy unit,
   • выполняет daemon-reload + reset-failed для legacy unit,
   • запускает template instance singbox@<id>.service.
3. Проверить:
   • systemctl status 'singbox@<id>.service'
   • systemctl list-unit-files 'singbox-*' --no-legend (legacy не должен появляться как managed unit)

Аварийный rollback (template -> legacy)

Важно: текущий прод-код нормализует SingBox clients к config.unit=singbox@.service, поэтому rollback делается на уровне release rollback (предыдущий API build + восстановление unit/state).

1. Зафиксировать инцидент и остановить изменения policy:
   • временно не выполнять start/restart/switch через GUI/API.
2. Откатить API до предыдущего релиза (где legacy path поддерживался штатно).
3. Восстановить transport-clients state из backup/снапшота релиза (если в инциденте state был изменён).
4. Восстановить legacy unit-файлы singbox-*.service из backup среды (если удалены).
5. Выполнить:
   • systemctl daemon-reload
   • systemctl reset-failed
6. Поднять нужные legacy unit и проверить egress/health.

Проверка после rollback

• systemctl is-active selective-vpn-api.service
• systemctl is-active 'singbox-<id>.service' (для rollback-релиза)
• API smoke:
  • curl -fsS http://127.0.0.1:8080/healthz
  • curl -fsS http://127.0.0.1:8080/api/v1/transport/clients

Примечание

• Legacy sing-box.service остаётся только как compat-артефакт окружения.
• Production path для новых профилей: только singbox@.service.