# 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`