Files

T

founder b903a09fb1 Позиционирование как самостоятельного продукта и переход на AGPL-3.0-only

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) намеренно не тронут: он требует отдельной
миграции БД и выносится в отдельный этап.

2026-08-15 03:34:18 +05:00

5.6 KiB

Raw Blame History

Install-only orchestrator spec

Цель документа

Зафиксировать ТЗ на оркестратор с учётом двухслойной архитектуры: builder отдельно, target install отдельно.

Технологический стек оркестратора

Оркестратор фиксируется как:

Bun + TypeScript по исходникам
локальная сборка builder layer'ом
поставка на target в виде готового install-артефакта

Это означает:

на target нет npm, pnpm, yarn или bun install
на target нет transpile/build step
shell на target допустим только как thin wrapper entrypoint

Главная роль оркестратора

Оркестратор работает только на target machine и умеет:

выполнить первичную установку (install)
выполнить явную реконфигурацию (reconfigure --dry-run|--apply)
разложить bundled UI
скачать Hysteria2 из official upstream
создать/обновить конфиги
создать unit-файлы
применить staged firewall
создать post-install.env и runtime env-файл

Оркестратор не умеет

upgrade
standalone rollback subcommands
uninstall
repair старых неизвестных состояний
target-side build
target-side git clone исходного кода HY2XS admin
Telegram-бот / access delivery

Предусловия

Оркестратор рассчитан только на:

чистый Debian 13
root/sudo install context
один сервер
одну baseline-схему

Если машина уже «жила своей жизнью», baseline не обещает корректной автоадаптации.

Что приходит на target

На target должен попадать уже готовый package, содержащий:

thin install entrypoint
compiled orchestrator artifact
bundled HY2XS admin
templates
unit files
docs/examples
metadata package version / build id

Логическая модульность

Даже если на target приезжает один собранный артефакт, внутри исходников оркестратор должен быть разложен по шагам:

preflight
deps
filesystem
hysteria
ui
systemd
firewall
env
smoke

Что делает оркестратор по шагам

Проверяет, что ОС — Debian 13.
Проверяет базовые зависимости и install context.
Создаёт каталоги установки.
Разворачивает bundled HY2XS admin.
Скачивает pinned Hysteria2 binary из package metadata, проверяет SHA256 и выполняет install.
Генерирует Hysteria config.
Создаёт systemd unit для Hysteria.
Создаёт systemd unit для HY2XS admin.
Применяет nftables baseline.
Создаёт post-install.env.
Запускает сервисы и выполняет smoke-check.

Модель поставки

Рекомендуемая baseline-модель:

исходники оркестратора хранятся в orchestrator/
builder выполняет локальную сборку через Bun
в install package кладётся готовый артефакт, который запускается thin wrapper'ом

Например:

package/install.sh — проверка контекста и вызов оркестратора
package/orchestrator/hy2xs-orchestrator — собранный артефакт

Логирование и коды возврата

Оркестратор должен:

печатать понятные step-based сообщения
завершаться ненулевым кодом при ошибке
не скрывать первичный источник падения
разделять preflight/config/runtime ошибки хотя бы на уровне текста

Политика ошибок

Любой конфликт неизвестного старого состояния = stop with error.
Никакой сложной автомиграции.
Ошибки должны быть текстовыми и пригодными для диагностики.
Для install/reconfigure допустим bounded rollback при failure-сценариях firewall/systemd/config/smoke.

CLI baseline

Команды:

install --package-dir <path> [--config <source-env>]
reconfigure --package-dir <path> --config /etc/hy2xs/hy2xs.env --dry-run
reconfigure --package-dir <path> --config /etc/hy2xs/hy2xs.env --apply

Инварианты:

только IPv4 bind/listen;
TLS modes: acme | file | self_signed_dev;
trafficStats.secret отдельный от JWT_SECRET;
install flow фиксирует фактически установленную версию Hysteria в snapshot;
версия/URL/SHA256 Hysteria берутся из metadata install package;
reconfigure не обновляет бинарник Hysteria, только runtime-слой.
при reconfigure --apply: backup -> staged apply -> smoke -> rollback on fail.

Что не реализовывать

update subcommands
rollback subcommands
uninstall subcommands
reconcile logic
выдачу пользовательских ключей или bot workflow

5.6 KiB Raw Blame History