132 lines
4.7 KiB
Markdown
132 lines
4.7 KiB
Markdown
# 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
|