founder
b903a09fb1
HY2XS больше не описывается как форк H UI. Из README, docs, сообщений builder'а и post-install metadata убрана вся fork/H UI терминология. Лицензия: - LICENSE: MIT заменён на полный текст AGPL-3.0-only - README: бейдж и раздел лицензии, подпись Flamy Studio - orchestrator/package.json, apps/frontend/package.json: license - package.sh: LICENSE кладётся в install package, license=AGPL-3.0-only в metadata - verify.sh, acceptance.sh: проверки корневой AGPL и metadata Документация: - 04-admin-panel-h-ui-fork.md -> 04-admin-panel.md, переписан вокруг модели Hysteria2 = external runtime dependency, HY2XS admin = native HY2XS component - docs 01, 02, 03, 08, 09, 11, 12, README: единая терминология HY2XS admin post-install.env: - блок HUI_* заменён на HY2XS_ADMIN_*, HUI_FORK_REF -> HY2XS_ADMIN_SOURCE Внутренний legacy namespace (H_UI_* ключи SQLite, HUI_DATA/HUI_LOG, API /hui, h_ui_db.sql) намеренно не тронут: он требует отдельной миграции БД и выносится в отдельный этап.
110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# Admin panel: HY2XS admin
|
||
|
||
## Цель документа
|
||
|
||
Зафиксировать модель работы с admin-панелью: HY2XS admin является **штатным компонентом HY2XS**, а не внешней зависимостью, которую target server где-то добывает во время установки.
|
||
|
||
## Место компонента в системе
|
||
|
||
Проект состоит из компонентов двух разных типов:
|
||
|
||
- **Hysteria2** — external runtime dependency. Ванильный upstream-бинарник, который оркестратор забирает из официального источника во время установки.
|
||
- **HY2XS admin** — native HY2XS component. Исходный код лежит в репозитории, компонент собирается production builder'ом вместе с остальными артефактами HY2XS.
|
||
|
||
Это противопоставление и есть основная архитектурная граница.
|
||
|
||
## Состав компонента
|
||
|
||
- исходный код admin-компонента хранится в [`apps/`](../apps);
|
||
- backend реализован на Go;
|
||
- frontend реализован на Vue/Vite;
|
||
- frontend-ассеты встраиваются в Go-бинарник;
|
||
- компонент собирается production builder'ом вместе с остальными артефактами HY2XS;
|
||
- готовый бинарник едет в install package как `ui/hy2xs-admin/hy2xs-admin`.
|
||
|
||
## Правила поставки
|
||
|
||
HY2XS admin:
|
||
|
||
- поставляется внутри итогового пакета;
|
||
- имеет свой install dir;
|
||
- имеет свой data dir;
|
||
- запускается отдельным rootless systemd unit (`hy2xs-admin`);
|
||
- не требует target-side build.
|
||
|
||
Target server **не собирает** admin-компонент из исходного кода и **не скачивает** его из внешнего репозитория.
|
||
|
||
## Scope панели
|
||
|
||
Панель нужна для:
|
||
|
||
- operator-facing управления;
|
||
- просмотра статуса;
|
||
- работы с пользователями / трафиком / сущностями доступа;
|
||
- удобной админской рутины.
|
||
|
||
Панель не должна:
|
||
|
||
- определять install lifecycle сервера;
|
||
- превращать систему в сложный control plane;
|
||
- диктовать scope оркестратора.
|
||
|
||
HY2XS admin работает как надстройка над Hysteria YAML/API-слоем. Это нормально: важно только, чтобы источник истины по runtime-состоянию был понятен и не было двух конкурирующих конфигурационных миров без правил синхронизации.
|
||
|
||
## Правила ответственности
|
||
|
||
### Source of truth
|
||
|
||
- runtime transport layer: Hysteria2
|
||
- операторский UI layer: HY2XS admin
|
||
- install lifecycle: оркестратор HY2XS
|
||
- 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.
|
||
|
||
### Что нельзя делать
|
||
|
||
- собирать admin-компонент на target server;
|
||
- скачивать admin-компонент на target из внешнего репозитория;
|
||
- склеивать unit Hysteria2 и unit HY2XS admin в один сервис;
|
||
- раздувать оркестратор из-за особенностей панели;
|
||
- использовать HY2XS admin как updater бинаря Hysteria2;
|
||
- использовать `JWT_SECRET` как `trafficStats.secret` для Hysteria API.
|
||
|
||
## Что фиксировать в `post-install.env`
|
||
|
||
Минимум:
|
||
|
||
- `HY2XS_ADMIN_ENABLED`
|
||
- `HY2XS_ADMIN_SOURCE`
|
||
- `HY2XS_ADMIN_BUILD_ID`
|
||
- `HY2XS_ADMIN_BIND_HOST`
|
||
- `HY2XS_ADMIN_PORT`
|
||
- `HY2XS_ADMIN_INSTALL_DIR`
|
||
- `HY2XS_ADMIN_DATA_DIR`
|
||
- `HY2XS_ADMIN_LOG_DIR`
|
||
|
||
## Инварианты
|
||
|
||
Схема считается корректной, если:
|
||
|
||
1. HY2XS admin приезжает на target уже в составе пакета
|
||
2. target не скачивает и не собирает admin-компонент
|
||
3. HY2XS admin работает отдельным сервисом
|
||
4. HY2XS admin не меняет install-only scope оркестратора
|
||
5. Hysteria2 остаётся внешним vanilla upstream-компонентом
|
||
6. HY2XS admin не выступает updater-менеджером Hysteria2
|
||
7. `trafficStats.secret` не связан с `JWT_SECRET`
|