135 lines
5.3 KiB
Markdown
135 lines
5.3 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** и умеет:
|
||
- выполнить первичную установку (`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. Скачивает installer Hysteria2 в temp-файл и выполняет install с policy `latest|vX.Y.Z`.
|
||
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`;
|
||
- install flow фиксирует фактически установленную версию Hysteria в snapshot;
|
||
- при `reconfigure --apply`: backup -> staged apply -> smoke -> rollback on fail.
|
||
|
||
## Что не реализовывать
|
||
|
||
- update subcommands
|
||
- rollback subcommands
|
||
- uninstall subcommands
|
||
- reconcile logic
|
||
- выдачу пользовательских ключей или bot workflow
|