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

2026-04-25 23:13:12 +05:00
commit 84a4e94567
277 changed files with 26513 additions and 0 deletions
@@ -0,0 +1,75 @@
+# HY2XS baseline docs
+
+Этот набор документов фиксирует актуальную baseline-модель HY2XS под следующие ограничения:
+
+- серверный транспорт: **ванильная Hysteria2**
+- UI: **наш форк H UI / HY2XS admin**, поставляется **вместе с проектом**
+- target OS: **только чистый Debian 12**
+- оркестратор: **install-only**, только первичная установка и базовая настройка
+- стек оркестратора: **Bun + TypeScript**
+- target-side build: **запрещён**
+- update / rollback / uninstall: **вне scope**
+- сборка и упаковка: **отдельный локальный build layer**
+- post-install state: **`/etc/hysteria/post-install.env`**
+- клиентский delivery/access layer: **вне baseline этого пакета docs**
+
+## Главная архитектурная схема
+
+В этой редакции зафиксированы два слоя:
+
+1. **Builder layer** — работает **локально**, на отдельной машине.
+   Он собирает итоговый пакет, подготавливает **наш форк HY2XS admin**, компилирует **Bun/TypeScript оркестратор** в install-артефакт, упаковывает шаблоны, unit-файлы и примеры конфигов.
+
+2. **Runtime / target layer** — работает **на чистом Debian 12**.
+   Здесь нет сборщика. Здесь запускается только итоговый install package / orchestrator, который:
+   - ставит системные зависимости
+   - разворачивает **наш встроенный UI**
+   - забирает **свежую Hysteria2 из официального upstream**
+   - создаёт конфиги, systemd unit-файлы и `post-install.env`
+   - выполняет базовую настройку сервера
+
+## Базовые правила
+
+1. Hysteria2 не форкается и не вендорится в проект.
+2. HY2XS admin форкается к себе и поставляется вместе с пакетом.
+3. Оркестратор пишется на **Bun + TypeScript**.
+4. На target нет `npm` / `pnpm` / `yarn` / `bun install` / transpile step.
+5. На target нет логики update / rollback / uninstall.
+6. Выдача доступа пользователям, Telegram-бот, billing, backend профилей и похожие контуры **не входят** в этот baseline.
+
+## Состав документов
+
+1. [01-architecture-baseline.md](01-architecture-baseline.md)
+2. [02-build-layer-and-package.md](02-build-layer-and-package.md)
+3. [03-server-hysteria2.md](03-server-hysteria2.md)
+4. [04-admin-panel-h-ui-fork.md](04-admin-panel-h-ui-fork.md)
+5. [05-client-and-access-scope.md](05-client-and-access-scope.md)
+6. [06-speed-limits-and-congestion.md](06-speed-limits-and-congestion.md)
+7. [07-systemd-and-firewall.md](07-systemd-and-firewall.md)
+8. [08-orchestrator-spec.md](08-orchestrator-spec.md)
+9. [09-post-install-env.md](09-post-install-env.md)
+10. [10-access-layer-out-of-scope.md](10-access-layer-out-of-scope.md)
+11. [11-testing-and-acceptance.md](11-testing-and-acceptance.md)
+12. [12-operations-and-troubleshooting.md](12-operations-and-troubleshooting.md)
+13. [examples/post-install.env.example](examples/post-install.env.example)
+
+## Жёсткие рамки baseline
+
+Не делаем:
+- upgrade manager
+- rollback manager
+- uninstall
+- reconcile engine
+- target-side build pipeline
+- Docker baseline
+- multi-node
+- port hopping
+- Telegram-бот
+- backend выдачи remote profiles
+- «умную» миграцию сломанных старых инсталляций
+
+## Одной фразой
+
+Правильная baseline-модель теперь такая:
+
+**Локальный builder собирает install package с нашим форком HY2XS admin и Bun/TypeScript оркестратором; серверный install-only orchestrator ставит этот пакет на чистый Debian 12, тянет свежую Hysteria2 из upstream, разворачивает UI, создаёт systemd + nftables + post-install env и подготавливает рабочее серверное окружение.**