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

2026-04-25 23:13:12 +05:00
commit 84a4e94567
277 changed files with 26513 additions and 0 deletions
@@ -0,0 +1,127 @@
+# Architecture baseline
+
+## Цель
+
+Зафиксировать одну непротиворечивую схему без смешивания локальной сборки, серверной установки и внешнего access layer.
+
+## Два слоя системы
+
+### 1. Builder layer
+Запускается **только локально**, на отдельной машине разработчика / оператора.
+
+Функции:
+- хранение исходников проекта
+- хранение и сопровождение **нашего форка HY2XS admin**
+- хранение исходников оркестратора на **Bun + TypeScript**
+- компиляция install-артефакта оркестратора
+- подготовка install package
+- упаковка unit-файлов, шаблонов конфигов и документации
+- контроль версии проекта как целого
+
+Builder layer **не разворачивается на сервере**.
+
+### 2. Runtime / target layer
+Запускается **только на чистом Debian 12**.
+
+Функции:
+- установка системных зависимостей
+- разворачивание файлов пакета
+- скачивание **свежей Hysteria2 из официального upstream**
+- создание server config
+- установка и запуск **встроенного HY2XS admin**
+- создание systemd unit-файлов
+- применение nftables baseline
+- создание `post-install.env`
+
+Target layer **не содержит сборщика** и **не выполняет target-side build**.
+
+## Компоненты baseline
+
+### Серверный транспорт
+- **Hysteria2**
+- QUIC/UDP
+- один фиксированный UDP-порт
+- `Salamander` включён по умолчанию
+- IPv4-only
+- лимит по умолчанию: 50/50 Mbps на клиента
+
+### UI слой
+- **наш форк H UI / HY2XS admin**
+- поставляется внутри проекта
+- устанавливается локально из итогового пакета
+- не скачивается с upstream на сервере
+
+### Orchestrator слой
+- **Bun + TypeScript**
+- собирается локально builder layer'ом
+- попадает на target как готовый install-артефакт
+- не требует `npm/pnpm/yarn/bun install` на сервере
+
+### Server ops слой
+- systemd
+- nftables
+- `post-install.env`
+
+## Принципы
+
+### 1. Ядро, UI и оркестратор ведут себя по-разному
+- Hysteria2: берём свежую upstream-версию при установке
+- HY2XS admin: держим **свой fork** и поставляем его сами
+- Оркестратор: пишем на **Bun + TypeScript**, но собираем **локально**, а не на target
+
+### 2. Builder и target не смешиваются
+Сборка — локально.  
+Установка — на сервере.  
+На сервере не должно быть логики «собери мне UI» или «собери мне TypeScript оркестратор».
+
+### 3. Оркестратор install-only
+Оркестратор умеет только:
+- установить
+- разложить файлы
+- создать базовую конфигурацию
+- подготовить сервер к работе
+
+Он **не** умеет:
+- обновлять уже установленную систему
+- откатывать версии
+- удалять установку
+- чинить неизвестные поломанные старые состояния
+
+### 4. Access layer вынесен за рамки baseline
+Telegram-бот, backend выдачи ключей, remote profile publishing, billing и похожие пользовательские контуры не входят в этот baseline.
+
+## Что входит в baseline
+
+1. local builder
+2. install package
+3. vanilla Hysteria2 from upstream
+4. bundled HY2XS admin
+5. Bun/TypeScript install-only orchestrator
+6. systemd + nftables
+7. post-install env
+8. install-only flow под чистый Debian 12
+
+## Что не входит в baseline
+
+- target-side builder
+- target-side git clone нашего UI
+- target-side `bun install` / transpile / compile
+- Telegram-бот
+- backend выдачи remote profiles
+- update / rollback / uninstall
+- Docker как основной способ поставки
+- multi-node deployment
+- сложный control plane
+
+## Финальный результат
+
+Правильный baseline-результат выглядит так:
+
+1. На локальной машине собирается install package.
+2. В пакет уже встроены наш HY2XS admin и install-артефакт оркестратора.
+3. Пакет переносится на чистый Debian 12.
+4. На сервере запускается только install-only orchestration.
+5. Сервер скачивает свежую Hysteria2 из official upstream.
+6. Сервер разворачивает bundled UI из пакета.
+7. Создаются systemd unit-файлы, firewall baseline и `post-install.env`.
+8. Сервер готов как базовое рабочее окружение HY2XS.