138 lines
5.6 KiB
Markdown
138 lines
5.6 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
|
|
- standalone rollback subcommands
|
|
- uninstall
|
|
- repair старых неизвестных состояний
|
|
- target-side build
|
|
- target-side git clone нашего UI-форка
|
|
- Telegram-бот / access delivery
|
|
|
|
## Предусловия
|
|
|
|
Оркестратор рассчитан только на:
|
|
- чистый Debian 13
|
|
- 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 13.
|
|
2. Проверяет базовые зависимости и install context.
|
|
3. Создаёт каталоги установки.
|
|
4. Разворачивает bundled HY2XS admin.
|
|
5. Скачивает pinned Hysteria2 binary из package metadata, проверяет SHA256 и выполняет install.
|
|
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.
|
|
- Никакой сложной автомиграции.
|
|
- Ошибки должны быть текстовыми и пригодными для диагностики.
|
|
- Для install/reconfigure допустим bounded rollback при failure-сценариях firewall/systemd/config/smoke.
|
|
|
|
## CLI baseline
|
|
|
|
Команды:
|
|
- `install --package-dir <path> [--config <source-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;
|
|
- версия/URL/SHA256 Hysteria берутся из metadata install package;
|
|
- `reconfigure` не обновляет бинарник Hysteria, только runtime-слой.
|
|
- при `reconfigure --apply`: backup -> staged apply -> smoke -> rollback on fail.
|
|
|
|
## Что не реализовывать
|
|
|
|
- update subcommands
|
|
- rollback subcommands
|
|
- uninstall subcommands
|
|
- reconcile logic
|
|
- выдачу пользовательских ключей или bot workflow
|