HY2XS_flamy/docs/08-orchestrator-spec.md

Install-only orchestrator spec

Цель документа

Зафиксировать ТЗ на оркестратор с учётом двухслойной архитектуры: builder отдельно, target install отдельно.

Технологический стек оркестратора

Оркестратор фиксируется как:

• Bun + TypeScript по исходникам
• локальная сборка builder layer'ом
• поставка на target в виде готового install-артефакта

Это означает:

• на target нет npm, pnpm, yarn или bun install
• на target нет transpile/build step
• shell на target допустим только как thin wrapper entrypoint

Главная роль оркестратора

Оркестратор работает только на target machine и умеет только:

• выполнить первичную установку
• разложить bundled UI
• скачать Hysteria2 из official upstream
• создать базовые конфиги
• создать unit-файлы
• применить baseline firewall
• создать post-install.env

Оркестратор не умеет

• upgrade
• rollback
• uninstall
• repair старых неизвестных состояний
• target-side build
• target-side git clone нашего UI-форка
• Telegram-бот / access delivery

Предусловия

Оркестратор рассчитан только на:

• чистый Debian 12
• root/sudo install context
• один сервер
• одну baseline-схему

Если машина уже «жила своей жизнью», baseline не обещает корректной автоадаптации.

Что приходит на target

На target должен попадать уже готовый package, содержащий:

• thin install entrypoint
• compiled orchestrator artifact
• bundled HY2XS admin
• templates
• unit files
• docs/examples
• metadata package version / build id

Логическая модульность

Даже если на target приезжает один собранный артефакт, внутри исходников оркестратор должен быть разложен по шагам:

• preflight
• deps
• filesystem
• hysteria
• ui
• systemd
• firewall
• env
• smoke

Что делает оркестратор по шагам

1. Проверяет, что ОС — Debian 12.
2. Проверяет базовые зависимости и install context.
3. Создаёт каталоги установки.
4. Разворачивает bundled HY2XS admin.
5. Скачивает Hysteria2 из official upstream.
6. Генерирует Hysteria config.
7. Создаёт systemd unit для Hysteria.
8. Создаёт systemd unit для HY2XS admin.
9. Применяет nftables baseline.
10. Создаёт post-install.env.
11. Запускает сервисы и выполняет smoke-check.

Модель поставки

Рекомендуемая baseline-модель:

• исходники оркестратора хранятся в orchestrator/
• builder выполняет локальную сборку через Bun
• в install package кладётся готовый артефакт, который запускается thin wrapper'ом

Например:

• package/install.sh — проверка контекста и вызов оркестратора
• package/orchestrator/hy2xs-orchestrator — собранный артефакт

Логирование и коды возврата

Оркестратор должен:

• печатать понятные step-based сообщения
• завершаться ненулевым кодом при ошибке
• не скрывать первичный источник падения
• разделять preflight/config/runtime ошибки хотя бы на уровне текста

Политика ошибок

• Любой конфликт неизвестного старого состояния = stop with error.
• Никакой сложной автомиграции.
• Ошибки должны быть текстовыми и пригодными для диагностики.

CLI baseline

Допустимые флаги:

• --non-interactive
• --domain
• --port
• --ssh-port
• --skip-firewall
• --skip-start
• --ui-port
• --ui-bind-host

Что не реализовывать

• update subcommands
• rollback subcommands
• uninstall subcommands
• reconcile logic
• выдачу пользовательских ключей или bot workflow