HY2XS_flamy/docs

HY2XS baseline docs

Этот набор документов фиксирует актуальную baseline-модель HY2XS под следующие ограничения:

• серверный транспорт: ванильная Hysteria2
• UI: HY2XS admin, штатный компонент проекта, поставляется вместе с пакетом
• target OS: только чистый Debian 13
• оркестратор: install-only, только первичная установка и базовая настройка
• стек оркестратора: Bun + TypeScript
• target-side build: запрещён
• standalone update / rollback / uninstall subcommands: вне scope
• сборка и упаковка: отдельный локальный build layer
• post-install state: /etc/hysteria/post-install.env
• установка: только на чистый хост, миграция с 0.x не поддерживается
• контракт версий продукта/платформы/toolchain: корневой versions.env
• клиентский delivery/access layer: вне baseline этого пакета docs

Главная архитектурная схема

В этой редакции зафиксированы два слоя:

1. Builder layer — работает на отдельном Debian 13 amd64 build host. Он собирает итоговый пакет, собирает HY2XS admin, компилирует Bun/TypeScript оркестратор в install-артефакт, упаковывает шаблоны, unit-файлы и примеры конфигов.

2. Runtime / target layer — работает на чистом Debian 13. Здесь нет сборщика. Здесь запускается только итоговый install package / orchestrator, который:

   • ставит системные зависимости
   • разворачивает встроенный HY2XS admin
   • забирает закреплённую в пакете Hysteria2 из официального upstream и сверяет её по SHA-256 и версии
   • создаёт конфиги, systemd unit-файлы и post-install.env
   • выполняет базовую настройку сервера

Версия Hysteria2 выбирается на builder layer: последняя стабильная разрешается при сборке и замораживается в metadata пакета. Target layer никогда не обращается к moving latest.

Базовые правила

1. Hysteria2 не вендорится и не собирается как часть HY2XS.
2. HY2XS admin — штатный компонент проекта и поставляется вместе с пакетом.
3. Оркестратор пишется на Bun + TypeScript.
4. На target нет npm / pnpm / yarn / bun install / transpile step.
5. На target нет standalone логики update / rollback / uninstall.
6. В install/reconfigure есть bounded rollback для failure-сценариев firewall/systemd/config/smoke. Rollback опирается на то, что операция реально успела применить: сервисы, которые она не разворачивала, не останавливаются никогда.
7. Установка двухфазная: PHASE 0 — read only, PHASE 1 — mutation. До успешного clean-host preflight на сервере не изменяется ни один persistent path. У мутирующей фазы ровно один владелец — оркестратор: install.sh проверяет и передаёт управление, не изменяя ничего сам. Очистка предыдущей установки — отдельная явная операция оператора, см. operations/14-legacy-cleanup.md.
8. Выдача доступа пользователям, Telegram-бот, billing, backend профилей и похожие контуры не входят в этот baseline.

Состав документов

Документы разложены по слою, к которому относятся. Двузначный префикс в имени — стабильный идентификатор документа: под ним на него ссылаются CHANGELOG, релизные гейты и сообщения оркестратора, поэтому при переносе в каталоги он сохранён.

Архитектура и рамки

• architecture/01-architecture-baseline.md — baseline-модель двух слоёв
• architecture/03-server-hysteria2.md — серверный транспорт
• architecture/05-client-and-access-scope.md — граница клиента
• architecture/06-speed-limits-and-congestion.md — ограничения скорости
• architecture/10-access-layer-out-of-scope.md — что вне baseline

Сборка

• build/02-build-layer-and-package.md — builder layer, состав пакета, требования к сборочной машине

Runtime на target

• runtime/08-orchestrator-spec.md — спецификация оркестратора
• runtime/07-systemd-and-firewall.md — systemd и nftables
• runtime/09-post-install-env.md — post-install состояние

Панель

• admin/04-admin-panel.md — HY2XS admin
• admin/15-ui-contracts.md — контракты панели: иконки, структурированные ошибки, необязательные поля, отсутствие выдуманного состояния, атрибуция

Эксплуатация

• operations/13-production-runbook.md — production runbook
• operations/12-operations-and-troubleshooting.md — операции и разбор отказов
• operations/14-legacy-cleanup.md — очистка установки предыдущего поколения

Проверки

• testing/ — набор проверок по слоям (бывший 11-testing-and-acceptance.md)
• acceptance/ — отчёты о фактических прогонах приёмки

История изменений проекта — в CHANGELOG.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 разрешает последнюю стабильную Hysteria2, проверяет её на совместимость с конфигом HY2XS и собирает install package с HY2XS admin и Bun/TypeScript оркестратором; серверный install-only orchestrator ставит этот пакет на чистый Debian 13, скачивает ровно закреплённую Hysteria2, разворачивает HY2XS admin, создаёт systemd + nftables + post-install env и подготавливает рабочее серверное окружение.