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 и умеет:

• выполнить первичную установку (install)
• выполнить явную реконфигурацию (reconfigure --dry-run|--apply)
• разложить bundled UI
• скачать Hysteria2 из official upstream
• создать/обновить конфиги
• создать unit-файлы
• применить staged firewall
• создать post-install.env и runtime 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

Команды:

• install --package-dir <path> [--config /etc/hy2xs/hy2xs.env]
• reconfigure --package-dir <path> --config /etc/hy2xs/hy2xs.env --dry-run
• reconfigure --package-dir <path> --config /etc/hy2xs/hy2xs.env --apply

Инварианты:

• только IPv4 bind/listen;
• TLS modes: acme | file | self_signed_dev;
• trafficStats.secret отдельный от JWT_SECRET;
• при reconfigure --apply: backup -> staged apply -> smoke -> rollback on fail.

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

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