HY2XS_flamy/docs

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 — работает на отдельном Debian 12 amd64 build host. Он собирает итоговый пакет, подготавливает наш форк 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
2. 02-build-layer-and-package.md
3. 03-server-hysteria2.md
4. 04-admin-panel-h-ui-fork.md
5. 05-client-and-access-scope.md
6. 06-speed-limits-and-congestion.md
7. 07-systemd-and-firewall.md
8. 08-orchestrator-spec.md
9. 09-post-install-env.md
10. 10-access-layer-out-of-scope.md
11. 11-testing-and-acceptance.md
12. 12-operations-and-troubleshooting.md

Жёсткие рамки 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 и подготавливает рабочее серверное окружение.