115 lines
5.2 KiB
Markdown
115 lines
5.2 KiB
Markdown
# Admin panel: bundled H UI fork
|
||
|
||
## Цель документа
|
||
|
||
Зафиксировать новую модель работы с UI: панель больше не рассматривается как внешний upstream-зависимый слой для target install, а становится **нашим вендорным компонентом**, поставляемым вместе с проектом.
|
||
|
||
## Почему меняем подход
|
||
|
||
Причина архитектурная:
|
||
|
||
- Hysteria2 ядро считаем достаточно стабильным upstream-компонентом
|
||
- UI считаем более слабым по поддержке и менее надёжным как внешний operational dependency
|
||
- поэтому UI забираем к себе: **fork + vendor + ship with package**
|
||
|
||
## Что это означает практически
|
||
|
||
### Было
|
||
- Hysteria — upstream
|
||
- H UI — отдельный upstream
|
||
- оркестратор ставит оба компонента как внешние зависимости
|
||
|
||
### Стало
|
||
- Hysteria — upstream
|
||
- H UI — **наш fork внутри проекта**
|
||
- итоговый package уже содержит UI
|
||
- на target server не надо скачивать H UI из чужого репозитория
|
||
|
||
## Правильная модель
|
||
|
||
- локальный builder хранит и собирает наш fork H UI
|
||
- install package везёт UI на сервер
|
||
- target-side orchestrator только раскладывает UI и создаёт unit
|
||
- H UI продолжает работать как надстройка над Hysteria YAML/API-слоем
|
||
|
||
## Что считать нормальным
|
||
|
||
Факт, что H UI — это надстройка над YAML-конфигом Hysteria, считается нормальным.
|
||
Это не аргумент против использования UI.
|
||
Важно только, чтобы источник истины по runtime-состоянию был понятен и не было двух конкурирующих конфигурационных миров без правил синхронизации.
|
||
|
||
## Scope панели
|
||
|
||
Панель нужна для:
|
||
- operator-facing управления
|
||
- просмотра статуса
|
||
- работы с пользователями / трафиком / сущностями доступа
|
||
- удобной админской рутины
|
||
|
||
Панель не должна:
|
||
- определять install lifecycle сервера
|
||
- превращать систему в сложный control plane
|
||
- диктовать scope оркестратора
|
||
|
||
## Правила поставки
|
||
|
||
Bundled H UI должна:
|
||
- поставляться внутри итогового пакета
|
||
- иметь свой install dir
|
||
- иметь свой data dir
|
||
- иметь rootless systemd unit (`hy2xs-admin`)
|
||
- запускаться отдельным systemd unit
|
||
- не требовать target-side build
|
||
|
||
## Правила ответственности
|
||
|
||
### Source of truth
|
||
- runtime transport layer: Hysteria
|
||
- операторский UI layer: forked H UI
|
||
- install lifecycle: наш orchestrator
|
||
- deploy facts: `post-install.env`
|
||
|
||
## Production lifecycle Hysteria2
|
||
|
||
В production package HY2XS admin не скачивает и не обновляет бинарь Hysteria2 самостоятельно.
|
||
|
||
Правильная модель:
|
||
- Hysteria2 устанавливается install-оркестратором с official upstream
|
||
- Hysteria2 запускается отдельным `hysteria-server.service`
|
||
- HY2XS admin работает как operator UI и HTTP auth/traffic layer
|
||
- HY2XS admin не запускается от root
|
||
- смена версии Hysteria2 через UI отключена в baseline
|
||
- список upstream releases не является частью operator UI baseline
|
||
- port hopping не является частью production path
|
||
|
||
### Что нельзя делать
|
||
- скачивать H UI с upstream прямо на target как baseline
|
||
- собирать UI на сервере
|
||
- склеивать unit Hysteria и unit H UI в один сервис
|
||
- раздувать оркестратор из-за особенностей UI
|
||
- использовать HY2XS admin как updater бинаря Hysteria2
|
||
- использовать `JWT_SECRET` как `trafficStats.secret` для Hysteria API
|
||
|
||
## Что фиксировать в `post-install.env`
|
||
|
||
Минимум:
|
||
- `HUI_ENABLED`
|
||
- `HUI_FORK_REF`
|
||
- `HUI_BUILD_ID`
|
||
- `HUI_BIND_HOST`
|
||
- `HUI_PORT`
|
||
- `HUI_INSTALL_DIR`
|
||
- `HUI_DATA_DIR`
|
||
|
||
## Инварианты
|
||
|
||
Схема считается корректной, если:
|
||
|
||
1. UI приезжает на target уже в составе пакета
|
||
2. target не скачивает UI с внешнего upstream
|
||
3. UI работает отдельным сервисом
|
||
4. UI не меняет install-only scope оркестратора
|
||
5. Hysteria остаётся внешним vanilla upstream-компонентом
|
||
6. UI не выступает updater-менеджером Hysteria2
|
||
7. `trafficStats.secret` не связан с `JWT_SECRET`
|