Подготовить HY2XS к production-сборке

2026-04-25 23:13:12 +05:00
commit 84a4e94567
277 changed files with 26513 additions and 0 deletions
@@ -0,0 +1,131 @@
+# 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