HY2XS_flamy/docs/01-architecture-baseline.md

Architecture baseline

Цель

Зафиксировать одну непротиворечивую схему без смешивания локальной сборки, серверной установки и внешнего access layer.

Два слоя системы

1. Builder layer

Запускается только локально, на отдельной машине разработчика / оператора.

Функции:

• хранение исходников проекта
• хранение и сопровождение нашего форка HY2XS admin
• хранение исходников оркестратора на Bun + TypeScript
• компиляция install-артефакта оркестратора
• подготовка install package
• упаковка unit-файлов, шаблонов конфигов и документации
• контроль версии проекта как целого

Builder layer не разворачивается на сервере.

2. Runtime / target layer

Запускается только на чистом Debian 13.

Функции:

• установка системных зависимостей
• разворачивание файлов пакета
• скачивание свежей 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/reconfigure-only

Оркестратор умеет только:

• установить
• применить явную реконфигурацию из runtime env
• разложить файлы
• создать базовую конфигурацию
• подготовить сервер к работе

Он не умеет:

• обновлять уже установленную систему
• откатывать версии
• удалять установку
• чинить неизвестные поломанные старые состояния

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 13

Что не входит в baseline

• target-side builder
• target-side git clone нашего UI
• target-side bun install / transpile / compile
• Telegram-бот
• backend выдачи remote profiles
• standalone update / rollback / uninstall subcommands

При этом в install/reconfigure допускается bounded rollback для failure-сценариев firewall/systemd/config/smoke.

• Docker как основной способ поставки
• multi-node deployment
• сложный control plane

Финальный результат

Правильный baseline-результат выглядит так:

1. На локальной машине собирается install package.
2. В пакет уже встроены наш HY2XS admin и install-артефакт оркестратора.
3. Пакет переносится на чистый Debian 13.
4. На сервере запускается только install-only orchestration.
5. Сервер скачивает свежую Hysteria2 из official upstream.
6. Сервер разворачивает bundled UI из пакета.
7. Создаются systemd unit-файлы, firewall baseline и post-install.env.
8. Сервер готов как базовое рабочее окружение HY2XS.

Runtime policy

• editable слой: /etc/hy2xs/hy2xs.env (0600)
• snapshot слой: /etc/hysteria/post-install.env (0600)
• изменения runtime применяются только через явный reconfigure --dry-run/--apply
• IPv6 out of scope: все bind/listen только IPv4