HY2XS_flamy/docs/04-admin-panel-h-ui-fork.md

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