Подготовить HY2XS к production-сборке

2026-04-25 23:13:12 +05:00
commit 84a4e94567
277 changed files with 26513 additions and 0 deletions
@@ -0,0 +1,108 @@
+# 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
+- запускаться отдельным 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
+- смена версии Hysteria2 через UI отключена в baseline
+- список upstream releases не является частью operator UI baseline
+
+### Что нельзя делать
+- скачивать H UI с upstream прямо на target как baseline
+- собирать UI на сервере
+- склеивать unit Hysteria и unit H UI в один сервис
+- раздувать оркестратор из-за особенностей UI
+- использовать HY2XS admin как updater бинаря Hysteria2
+
+## Что фиксировать в `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-компонентом