Подготовить 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.
@@ -0,0 +1,134 @@
+# Build layer and package
+
+## Цель документа
+
+Зафиксировать локальный слой сборки и формат итогового install package.
+
+## Базовое решение
+
+В baseline builder остаётся **shell-first** для packaging-слоя.
+
+То есть:
+- основной packaging pipeline — **sh/bash**
+- оркестратор при этом пишется на **Bun + TypeScript**
+- builder локально компилирует оркестратор в готовый install-артефакт
+- target machine не должна сама собирать или доустанавливать JS/TS toolchain
+
+Причина простая: packaging можно держать простым, а оркестратор — typed и модульным.
+
+## Где работает builder
+
+Production builder работает на отдельном build host:
+- Debian 12
+- amd64 / x86_64
+- bash
+- доступ к интернету для apt и скачивания toolchain
+
+В текущей production-модели сборка выполняется **на Debian 12 amd64**, а не на Windows/macOS dev-машине.
+
+Builder не является частью target install flow: на target server приезжает уже готовый install package, без JS/TS/Go build step.
+
+## Что хранится в репозитории проекта
+
+Минимум:
+- исходники оркестратора на **Bun + TypeScript**
+- shell packaging scripts
+- шаблоны конфигов
+- systemd unit templates
+- docs
+- **наш fork HY2XS admin**
+- шаблоны для `post-install.env`
+- package metadata
+
+## Что делает builder
+
+1. Проверяет структуру проекта.
+2. Собирает / подготавливает HY2XS admin.
+3. Компилирует оркестратор из Bun/TypeScript в install-артефакт.
+4. Копирует артефакты UI в package staging directory.
+5. Кладёт entrypoint, templates, docs и service files.
+6. Формирует итоговый install package.
+7. При необходимости считает manifest/checksum.
+8. Выдаёт один переносимый результат для target machine.
+
+## Что builder не делает
+
+- не ставит Hysteria2 на локальной машине «для продакшена»
+- не превращается в CI/CD платформу
+- не генерирует update pipeline
+- не делает uninstall manifests
+- не готовит миграции между старыми инсталляциями
+
+## Рекомендуемая структура
+
+```text
+project/
+├── tools/
+│   └── build/
+│       ├── build.sh
+│       ├── README.ru.md
+│       └── lib/
+├── orchestrator/
+│   ├── package.json
+│   ├── bun.lock
+│   ├── tsconfig.json
+│   └── src/
+├── package/
+│   ├── install.sh
+│   ├── orchestrator/
+│   ├── templates/
+│   └── systemd/
+├── ui/
+│   └── hy2xs-admin-fork/
+├── docs/
+└── dist/
+```
+
+## Формат итогового пакета
+
+Итоговый пакет должен содержать:
+
+- install-only orchestrator artifact
+- bundled HY2XS admin
+- unit templates
+- config templates
+- docs / examples
+- manifest версии проекта
+
+Итоговый пакет **не должен** содержать:
+- builder scripts
+- исходную локальную build-среду
+- временные каталоги сборки
+- мусор CI
+- target-side dependency install step для оркестратора
+
+## Production builder bootstrap
+
+`tools/build/build.sh` должен быть самодостаточным для Debian 12 amd64:
+
+1. Проверяет ОС и архитектуру.
+2. Проверяет структуру репозитория и lock-файлы.
+3. Доставляет отсутствующие системные build-зависимости через `apt-get`.
+4. Проверяет версии Go, Bun, Node.js и pnpm.
+5. При несовпадении версий скачивает управляемый локальный toolchain в `.toolchain/`.
+6. Собирает только Linux amd64 артефакты.
+7. Записывает версии toolchain в metadata пакета.
+
+## Отношение к Hysteria2
+
+Сам бинарь Hysteria2 **не вендорится** в install package как baseline-правило.
+
+Причина:
+- ядро Hysteria рассматривается как stable upstream component
+- целевая установка должна брать его с official upstream на момент развёртывания
+
+## Инварианты
+
+Система считается правильной, если:
+
+1. builder запускается на Debian 12 amd64 build host, не как target-side build step
+2. пакет можно перенести на чистый Debian 12
+3. на сервере нет отдельного build step
+4. bundled UI уже находится внутри пакета
+5. оркестратор authored as Bun/TypeScript, но на target приходит как готовый install-артефакт
+6. Hysteria2 подтягивается install layer'ом с upstream, а не собирается на target из исходников
@@ -0,0 +1,103 @@
+# Server Hysteria2 baseline
+
+## Цель документа
+
+Зафиксировать правила для серверного слоя Hysteria2 в модели, где UI поставляется вместе с проектом, а Hysteria берётся из official upstream во время установки.
+
+## Роль Hysteria2
+
+Hysteria2 — основной транспортный компонент сервера.  
+Он не форкается и не поставляется как часть UI-форка.
+
+## Source policy
+
+Базовое правило:
+- Hysteria2 скачивается **во время установки**
+- источник — **официальный upstream**
+- install layer не должен подменять собой upstream-дистрибуцию Hysteria2
+
+## Версионная политика
+
+С учётом выбранной модели «берём свежее из upstream» фиксируется такая практика:
+
+- по умолчанию install layer тянет **свежий upstream release / install source**
+- фактически установленная версия обязательно записывается в `post-install.env`
+- документация не обещает жёсткий pin как baseline
+- если оператору нужна строгая фиксация версии, это отдельный режим, а не базовая модель
+
+## Платформа
+
+- ОС: только Debian 12
+- init/system management: systemd
+- сетевой фильтр: nftables
+- архитектура baseline: x86_64/amd64
+
+## Listen и сеть
+
+### Listen
+- только IPv4
+- формат: `0.0.0.0:<PORT>`
+
+### Порт
+- один фиксированный UDP-порт
+- этот порт должен совпадать в:
+  - server config
+  - firewall rules
+  - `post-install.env`
+
+## Обфускация
+
+В baseline включается:
+- `obfs.type: salamander`
+- `obfs.password`
+
+Правила:
+- пароль должен быть сильным
+- пароль должен фиксироваться в конфигурационном контуре
+- значение должно быть доступно оператору через runtime config и `post-install.env`
+
+## TLS
+
+Требования:
+- нормальный домен
+- корректный `server_name` / SNI на клиентах
+- одна понятная TLS policy
+- без смешивания нескольких несовместимых схем по умолчанию
+
+## Auth policy
+
+Для baseline выбирается одна предсказуемая auth-модель.
+
+Правила:
+- install flow должен оставить рабочий auth state
+- bootstrap auth material должен быть либо передан оператором, либо безопасно сгенерирован
+- дальнейшая модель выдачи доступа пользователям не фиксируется в этом пакете docs
+
+## Bandwidth и congestion
+
+Серверная baseline policy:
+- `bandwidth.up = 50 mbps`
+- `bandwidth.down = 50 mbps`
+- `ignoreClientBandwidth = false`
+
+Важно:
+- эти параметры сами по себе не исчерпывают speed policy
+- корректный лимит ожидается только в паре с совместимым клиентским конфигом
+
+## Рекомендуемые пути
+
+- `/etc/hysteria/config.yaml`
+- `/var/lib/hysteria/`
+- `/etc/hysteria/post-install.env`
+
+## Серверные инварианты
+
+После установки должно быть верно:
+
+1. Hysteria2 получена из official upstream
+2. фактическая версия отражена в `post-install.env`
+3. конфиг валиден
+4. сервис стартует через systemd
+5. нужный UDP-порт реально слушается
+6. тестовый совместимый клиент может подключиться
+7. bundled UI работает поверх актуального состояния сервера
@@ -0,0 +1,108 @@
+# Admin panel: bundled H UI fork
+
+## Цель документа
+
+Зафиксировать новую модель работы с UI: панель больше не рассматривается как внешний upstream-зависимый слой для target install, а становится **нашим вендорным компонентом**, поставляемым вместе с проектом.
+
+## Почему меняем подход
+
+Причина архитектурная:
+
+- Hysteria2 ядро считаем достаточно стабильным upstream-компонентом
+- UI считаем более слабым по поддержке и менее надёжным как внешний operational dependency
+- поэтому UI забираем к себе: **fork + vendor + ship with package**
+
+## Что это означает практически
+
+### Было
+- Hysteria — upstream
+- H UI — отдельный upstream
+- оркестратор ставит оба компонента как внешние зависимости
+
+### Стало
+- Hysteria — upstream
+- H UI — **наш fork внутри проекта**
+- итоговый package уже содержит UI
+- на target server не надо скачивать H UI из чужого репозитория
+
+## Правильная модель
+
+- локальный builder хранит и собирает наш fork H UI
+- install package везёт UI на сервер
+- target-side orchestrator только раскладывает UI и создаёт unit
+- H UI продолжает работать как надстройка над Hysteria YAML/API-слоем
+
+## Что считать нормальным
+
+Факт, что H UI — это надстройка над YAML-конфигом Hysteria, считается нормальным.  
+Это не аргумент против использования UI.  
+Важно только, чтобы источник истины по runtime-состоянию был понятен и не было двух конкурирующих конфигурационных миров без правил синхронизации.
+
+## Scope панели
+
+Панель нужна для:
+- operator-facing управления
+- просмотра статуса
+- работы с пользователями / трафиком / сущностями доступа
+- удобной админской рутины
+
+Панель не должна:
+- определять install lifecycle сервера
+- превращать систему в сложный control plane
+- диктовать scope оркестратора
+
+## Правила поставки
+
+Bundled H UI должна:
+- поставляться внутри итогового пакета
+- иметь свой install dir
+- иметь свой data dir
+- запускаться отдельным systemd unit
+- не требовать target-side build
+
+## Правила ответственности
+
+### Source of truth
+- runtime transport layer: Hysteria
+- операторский UI layer: forked H UI
+- install lifecycle: наш orchestrator
+- deploy facts: `post-install.env`
+
+## Production lifecycle Hysteria2
+
+В production package HY2XS admin не скачивает и не обновляет бинарь Hysteria2 самостоятельно.
+
+Правильная модель:
+- Hysteria2 устанавливается install-оркестратором с official upstream
+- Hysteria2 запускается отдельным `hysteria-server.service`
+- HY2XS admin работает как operator UI и HTTP auth/traffic layer
+- смена версии Hysteria2 через UI отключена в baseline
+- список upstream releases не является частью operator UI baseline
+
+### Что нельзя делать
+- скачивать H UI с upstream прямо на target как baseline
+- собирать UI на сервере
+- склеивать unit Hysteria и unit H UI в один сервис
+- раздувать оркестратор из-за особенностей UI
+- использовать HY2XS admin как updater бинаря Hysteria2
+
+## Что фиксировать в `post-install.env`
+
+Минимум:
+- `HUI_ENABLED`
+- `HUI_FORK_REF`
+- `HUI_BUILD_ID`
+- `HUI_BIND_HOST`
+- `HUI_PORT`
+- `HUI_INSTALL_DIR`
+- `HUI_DATA_DIR`
+
+## Инварианты
+
+Схема считается корректной, если:
+
+1. UI приезжает на target уже в составе пакета
+2. target не скачивает UI с внешнего upstream
+3. UI работает отдельным сервисом
+4. UI не меняет install-only scope оркестратора
+5. Hysteria остаётся внешним vanilla upstream-компонентом
@@ -0,0 +1,46 @@
+# Client and access scope
+
+## Цель документа
+
+Зафиксировать, что клиентский delivery/access layer не является частью install baseline.
+
+## Что входит в baseline
+
+В baseline этого пакета docs входит только следующее:
+- установка Hysteria2
+- установка HY2XS admin
+- базовая настройка systemd / firewall / `post-install.env`
+- подготовка рабочего серверного окружения
+
+## Что не входит в baseline
+
+В baseline **не входят**:
+- Telegram-бот
+- backend выдачи профилей
+- remote profile publishing
+- deep links
+- billing / подписки / тарифные планы
+- отдельный user-access API
+
+## Что допускается как вспомогательный слой
+
+Для smoke/manual testing могут существовать:
+- тестовый клиентский конфиг
+- тестовый URI
+- отдельные примеры импортируемых клиентских артефактов
+
+Но это не делает access layer частью install baseline.
+
+## Почему это важно
+
+Если смешать install baseline и delivery layer, документация начинает неверно обещать лишнее:
+- будто оркестратор обязан выдавать ключи пользователям
+- будто сервер после установки автоматически включает пользовательский backend
+- будто Telegram-бот является обязательной частью системы
+
+Это неверно.
+
+## Правильная формулировка
+
+После выполнения install flow система должна быть готова как серверное окружение HY2XS.  
+Как именно оператор потом выдаёт доступ клиентам — отдельный продуктовый контур и отдельная документация.
@@ -0,0 +1,56 @@
+# Speed limits and congestion policy
+
+## Цель документа
+
+Зафиксировать корректную speed policy без неточных упрощений.
+
+## Что нельзя считать правильной схемой
+
+Нельзя описывать baseline так:
+- на сервере включили host BBR
+- выдали какой-то URI
+- автоматически получили строгий лимит 50 Mbps на клиента
+
+Это неверная модель.
+
+## Что зафиксировано в baseline
+
+### На сервере
+- `bandwidth.up = 50 mbps`
+- `bandwidth.down = 50 mbps`
+- `ignoreClientBandwidth = false`
+
+### На клиенте
+Совместимый клиентский конфиг должен задавать соответствующие bandwidth hints:
+- `up_mbps = 50`
+- `down_mbps = 50`
+
+## Практический смысл
+
+Ожидаемый 50/50 Mbps contract считается корректным только тогда, когда сервер и клиентская конфигурация согласованы.
+
+## Что делать с host-level BBR
+
+`net.ipv4.tcp_congestion_control=bbr` можно оставить как общий системный тюнинг, но:
+
+- это не главный механизм speed policy Hysteria2
+- это не замена клиентским bandwidth hints
+- это не центр документации по лимитам
+
+## Что фиксировать в `post-install.env`
+
+Минимум:
+- `HY2_BANDWIDTH_UP_Mbps`
+- `HY2_BANDWIDTH_DOWN_Mbps`
+- `HY2_IGNORE_CLIENT_BANDWIDTH`
+
+## Что нельзя писать в проектных доках
+
+Не писать:
+- «лимит задаётся только на сервере, клиент не важен»
+- «любой URI достаточно для полной speed policy»
+- «host BBR и есть логика Hysteria»
+
+## Правильная baseline-формулировка
+
+Пер-клиентный лимит 50/50 Mbps обеспечивается согласованной серверной и клиентской конфигурацией. Install baseline отвечает за серверную часть этого контракта; конкретный delivery/access слой в этот документ не входит.
@@ -0,0 +1,62 @@
+# systemd and firewall
+
+## Цель документа
+
+Зафиксировать базовый systemd/firewall слой под новую install model.
+
+## systemd: Hysteria2
+
+Базовые требования:
+- отдельный unit `hysteria-server.service`
+- отдельный пользователь `hysteria`
+- автозапуск после reboot
+- restart policy для падений
+
+Базовый ExecStart:
+```bash
+/usr/local/bin/hysteria server -c /etc/hysteria/config.yaml
+```
+
+## systemd: HY2XS admin
+
+Базовые требования:
+- отдельный unit `hy2xs-admin.service`
+- отдельный install dir
+- отдельный data dir
+- отдельный жизненный цикл от Hysteria
+
+Важно:
+- HY2XS admin не должен запускаться как часть unit Hysteria
+- unit-файлы не должны быть склеены
+
+## Базовая firewall-модель
+
+Нужно разрешить:
+- UDP-порт Hysteria2
+- TCP-порт SSH
+- established/related traffic
+
+После staged-проверки можно включать default policy `drop`.
+
+## Порядок применения
+
+1. Добавить allow-правила.
+2. Проверить, что SSH-сессия не теряется.
+3. Проверить listen Hysteria-порта.
+4. Только потом затягивать policy.
+
+## Что не делаем
+
+В baseline не делаем:
+- port hopping
+- сложную динамическую firewall-логику
+- смешение UI-портов и публичного транспортного порта в один firewall-контур без правил
+
+## Инварианты
+
+Система считается корректной, если:
+1. Hysteria и HY2XS admin работают отдельными systemd unit
+2. Hysteria слушает нужный UDP-порт
+3. SSH не ломается после применения firewall
+4. firewall-политика не противоречит listen policy
+5. после reboot оба нужных сервиса стартуют корректно
@@ -0,0 +1,131 @@
+# Install-only orchestrator spec
+
+## Цель документа
+
+Зафиксировать ТЗ на оркестратор с учётом двухслойной архитектуры: builder отдельно, target install отдельно.
+
+## Технологический стек оркестратора
+
+Оркестратор фиксируется как:
+- **Bun + TypeScript** по исходникам
+- локальная сборка builder layer'ом
+- поставка на target в виде **готового install-артефакта**
+
+Это означает:
+- на target нет `npm`, `pnpm`, `yarn` или `bun install`
+- на target нет transpile/build step
+- shell на target допустим только как thin wrapper entrypoint
+
+## Главная роль оркестратора
+
+Оркестратор работает **только на target machine** и умеет только:
+- выполнить первичную установку
+- разложить bundled UI
+- скачать Hysteria2 из official upstream
+- создать базовые конфиги
+- создать unit-файлы
+- применить baseline firewall
+- создать `post-install.env`
+
+## Оркестратор не умеет
+
+- upgrade
+- rollback
+- uninstall
+- repair старых неизвестных состояний
+- target-side build
+- target-side git clone нашего UI-форка
+- Telegram-бот / access delivery
+
+## Предусловия
+
+Оркестратор рассчитан только на:
+- чистый Debian 12
+- root/sudo install context
+- один сервер
+- одну baseline-схему
+
+Если машина уже «жила своей жизнью», baseline не обещает корректной автоадаптации.
+
+## Что приходит на target
+
+На target должен попадать уже готовый package, содержащий:
+- thin install entrypoint
+- compiled orchestrator artifact
+- bundled HY2XS admin
+- templates
+- unit files
+- docs/examples
+- metadata package version / build id
+
+## Логическая модульность
+
+Даже если на target приезжает один собранный артефакт, внутри исходников оркестратор должен быть разложен по шагам:
+- preflight
+- deps
+- filesystem
+- hysteria
+- ui
+- systemd
+- firewall
+- env
+- smoke
+
+## Что делает оркестратор по шагам
+
+1. Проверяет, что ОС — Debian 12.
+2. Проверяет базовые зависимости и install context.
+3. Создаёт каталоги установки.
+4. Разворачивает bundled HY2XS admin.
+5. Скачивает Hysteria2 из official upstream.
+6. Генерирует Hysteria config.
+7. Создаёт systemd unit для Hysteria.
+8. Создаёт systemd unit для HY2XS admin.
+9. Применяет nftables baseline.
+10. Создаёт `post-install.env`.
+11. Запускает сервисы и выполняет smoke-check.
+
+## Модель поставки
+
+Рекомендуемая baseline-модель:
+- исходники оркестратора хранятся в `orchestrator/`
+- builder выполняет локальную сборку через Bun
+- в install package кладётся готовый артефакт, который запускается thin wrapper'ом
+
+Например:
+- `package/install.sh` — проверка контекста и вызов оркестратора
+- `package/orchestrator/hy2xs-orchestrator` — собранный артефакт
+
+## Логирование и коды возврата
+
+Оркестратор должен:
+- печатать понятные step-based сообщения
+- завершаться ненулевым кодом при ошибке
+- не скрывать первичный источник падения
+- разделять preflight/config/runtime ошибки хотя бы на уровне текста
+
+## Политика ошибок
+
+- Любой конфликт неизвестного старого состояния = stop with error.
+- Никакой сложной автомиграции.
+- Ошибки должны быть текстовыми и пригодными для диагностики.
+
+## CLI baseline
+
+Допустимые флаги:
+- `--non-interactive`
+- `--domain`
+- `--port`
+- `--ssh-port`
+- `--skip-firewall`
+- `--skip-start`
+- `--ui-port`
+- `--ui-bind-host`
+
+## Что не реализовывать
+
+- update subcommands
+- rollback subcommands
+- uninstall subcommands
+- reconcile logic
+- выдачу пользовательских ключей или bot workflow
@@ -0,0 +1,92 @@
+# Post-install env
+
+## Цель документа
+
+Зафиксировать `post-install.env` как компактный deploy reference file после первичной установки.
+
+## Зачем нужен файл
+
+После первичной установки оператору нужна одна точка, где видно:
+- какой пакет был установлен
+- какой build артефакт использован
+- какой стек оркестратора применён
+- какая версия Hysteria реально установилась
+- какой fork/build UI разложен на target
+- какие базовые параметры сети и портов заданы
+
+Именно для этого создаётся `post-install.env`.
+
+## Чего файл не делает
+
+Этот файл:
+- не делает оркестратор update-manager'ом
+- не гарантирует автоматическое применение изменений
+- не заменяет runtime-конфиги
+- не превращает target в builder
+
+## Рекомендуемый путь
+
+```bash
+/etc/hysteria/post-install.env
+```
+
+## Минимальный набор переменных
+
+### Deploy / package
+- `DEPLOY_TARGET_OS`
+- `DEPLOY_TIMESTAMP`
+- `PACKAGE_NAME`
+- `PACKAGE_BUILD_ID`
+- `PACKAGE_VERSION`
+
+### Orchestrator
+- `ORCH_SOURCE_STACK=bun-typescript`
+- `ORCH_BUILD_MODE`
+- `ORCH_BUILD_ID`
+- `ORCH_ENTRYPOINT`
+
+### Общие
+- `DEPLOY_DOMAIN`
+- `SSH_PORT`
+
+### Hysteria
+- `HY2_SOURCE=official-upstream`
+- `HY2_VERSION`
+- `HY2_LISTEN_HOST`
+- `HY2_PORT`
+- `HY2_AUTH_MODE`
+- `HY2_AUTH_URL`
+- `HY2_TRAFFIC_STATS_LISTEN`
+- `HY2_OBFS_TYPE`
+- `HY2_OBFS_PASSWORD`
+- `HY2_BANDWIDTH_UP_Mbps`
+- `HY2_BANDWIDTH_DOWN_Mbps`
+- `HY2_IGNORE_CLIENT_BANDWIDTH`
+- `HY2_CONFIG_PATH`
+
+### HY2XS admin
+- `HUI_ENABLED`
+- `HUI_FORK_REF`
+- `HUI_BUILD_ID`
+- `HUI_BIND_HOST`
+- `HUI_PORT`
+- `HUI_INSTALL_DIR`
+- `HUI_DATA_DIR`
+
+## Как работать с файлом
+
+Правильная модель:
+1. оркестратор создаёт файл при первичной установке
+2. оператор использует файл как reference/source-of-truth
+3. при необходимости оператор вручную переносит изменения в реальные рабочие конфиги
+4. затем оператор применяет изменения документированным способом
+
+## Что нельзя делать
+
+- сваливать туда временный мусор
+- считать, что edit env автоматически меняет runtime
+- использовать файл как замену настоящей конфигурации сервисов
+
+## Пример
+
+См. [examples/post-install.env.example](examples/post-install.env.example).
@@ -0,0 +1,41 @@
+# Access layer out of scope
+
+## Цель документа
+
+Явно зафиксировать, что пользовательский access/delivery слой не является частью этого baseline-пакета.
+
+## Что не надо обещать в этих доках
+
+Нельзя описывать систему так, будто install-only оркестратор также отвечает за:
+- Telegram-бота
+- выдачу ключей пользователям
+- backend профилей
+- remote profile publishing
+- deep link delivery
+- billing или управление подписками
+
+Это отдельные контуры.
+
+## Что реально делает baseline
+
+Baseline делает только следующее:
+- устанавливает Hysteria2
+- устанавливает HY2XS admin
+- создаёт runtime-конфиги
+- создаёт systemd units
+- применяет firewall baseline
+- фиксирует deploy facts в `post-install.env`
+
+## Что может существовать рядом, но отдельно
+
+Отдельно от install baseline могут существовать:
+- клиентские инструкции
+- тестовые конфиги
+- access backend
+- бот/панель/CRM/ERP-логика выдачи доступа
+
+Но это требует отдельной документации и отдельного scope.
+
+## Итоговая формулировка
+
+HY2XS baseline в этих документах — это **оркестратор установки и базовой серверной конфигурации**, а не пользовательский delivery platform.
@@ -0,0 +1,66 @@
+# Testing and acceptance
+
+## Цель документа
+
+Зафиксировать checklist для новой двухслойной схемы.
+
+## A. Builder layer tests
+
+### Проверяем
+1. builder запускается на Debian 12 amd64 build host
+2. итоговый пакет собирается без target-side шагов
+3. bundled HY2XS admin реально входит в пакет
+4. package metadata / build id присутствуют
+5. compiled Bun/TypeScript orchestrator artifact присутствует
+6. в пакет не попадает build-мусор
+7. builder сам доставляет отсутствующие build-зависимости
+8. builder проверяет версии Go/Bun/Node.js/pnpm
+9. builder пишет версии toolchain в metadata
+
+## B. Target install tests
+
+### На чистом Debian 12 проверяем
+1. пакет запускается без ручной сборки на сервере
+2. Hysteria2 скачивается с official upstream
+3. bundled HY2XS admin раскладывается локально из пакета
+4. создаются нужные каталоги
+5. создаются systemd unit-файлы
+6. создаётся `post-install.env`
+7. baseline firewall применяется корректно
+8. SSH остаётся доступным
+
+## C. Runtime tests
+
+1. `hysteria-server` active
+2. `hy2xs-admin` active
+3. UDP-порт слушается
+4. HY2XS admin открывается по ожидаемому admin path
+5. тестовый совместимый клиент подключается
+6. идёт реальный трафик
+7. лимит 50/50 Mbps соблюдается при согласованной клиентской конфигурации
+8. reboot не ломает baseline
+9. Hysteria2 управляется systemd unit, а не внутренним updater'ом admin panel
+
+## D. Negative tests
+
+1. не Debian 12
+2. порт уже занят
+3. старое конфликтующее состояние уже существует
+4. домен / SNI заданы некорректно
+5. bundled UI отсутствует в пакете
+6. Hysteria upstream недоступен
+7. firewall применился частично
+8. install flow прерван посередине
+
+## Acceptance criteria
+
+Система принимается, если:
+
+1. production builder на Debian 12 amd64 выдаёт переносимый install package
+2. target server не выполняет build step
+3. Hysteria2 получена из official upstream
+4. UI поставлен из bundled fork
+5. `post-install.env` отражает фактическое deploy-состояние
+6. оркестратор зафиксирован как Bun/TypeScript stack и поставляется как готовый install-артефакт
+7. оркестратор не требует update / rollback / uninstall логики
+8. Telegram/access layer не требуется для прохождения install acceptance
@@ -0,0 +1,94 @@
+# Operations and troubleshooting
+
+## Цель документа
+
+Зафиксировать минимальный operational контур после установки.
+
+## Что должен помнить оператор
+
+### 1. Builder и target — разные миры
+Если нужно изменить состав install package, это делается в локальном builder layer, а не на target server.
+
+### 2. UI приезжает из нашего пакета
+Если проблема в UI, сначала смотреть:
+- какой `HUI_FORK_REF`
+- какой `HUI_BUILD_ID`
+- тот ли пакет вообще стоит на сервере
+
+### 3. Hysteria приходит из upstream
+Если проблема в ядре Hysteria, сначала смотреть:
+- какую фактическую версию оркестратор установил
+- что записано в `HY2_VERSION`
+- не связано ли поведение со свежим upstream release
+
+### 4. Оркестратор — Bun/TypeScript, но target не билдит его
+Если проблема в install flow, сначала смотреть:
+- какой `ORCH_BUILD_ID`
+- какой `ORCH_ENTRYPOINT`
+- не подменён ли install package вручную
+
+## Базовые команды проверки
+
+Проверка сервисов:
+```bash
+systemctl status hysteria-server
+systemctl status hy2xs-admin
+```
+
+Проверка порта:
+```bash
+ss -uln
+```
+
+Проверка firewall:
+```bash
+nft list ruleset
+```
+
+Проверка `post-install.env`:
+```bash
+cat /etc/hysteria/post-install.env
+```
+
+## Типовые проблемы
+
+### Сервер установился, но UI не работает
+Проверить:
+- разложился ли bundled UI
+- корректен ли unit `hy2xs-admin`
+- совпадает ли `HUI_INSTALL_DIR` с реальностью
+- не сломан ли bind host / port
+
+### Hysteria скачалась, но не стартует
+Проверить:
+- валиден ли config
+- совпадают ли listen port и firewall rule
+- домен / SNI / TLS policy
+- реальную установленную версию Hysteria
+
+### Тестовый клиент не подключается
+Проверить:
+- `server_name`
+- порт
+- `obfs.password`
+- auth material
+- что используется совместимый клиентский конфиг
+
+### Скорость не соответствует ожиданиям
+Проверить:
+- `bandwidth.*` на сервере
+- клиентские `up_mbps/down_mbps`
+- нет ли ложного ожидания, что один только host BBR решает speed policy
+
+### Изменили `post-install.env`, но runtime не изменился
+Это ожидаемо.
+
+`post-install.env` — reference file, а не autoreconcile engine.
+
+## Правила эксплуатации
+
+1. Не править сервер как будто на нём есть builder.
+2. Не считать bundled UI источником install-policy.
+3. Не считать `post-install.env` автоматическим механизмом применения изменений.
+4. Не расширять install-only baseline до lifecycle-manager без отдельного проектного решения.
+5. Не смешивать install baseline и access/bot platform в одной документации.
@@ -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 и подготавливает рабочее серверное окружение.**
@@ -0,0 +1,35 @@
+# post-install.env example
+# Baseline reference file for a clean Debian 12 deployment.
+
+DEPLOY_TARGET_OS=debian12
+DEPLOY_TIMESTAMP=2026-04-13T10:00:00Z
+PACKAGE_NAME=hy2xs-install-package
+PACKAGE_BUILD_ID=build-20260413-001
+PACKAGE_VERSION=0.1.0
+
+ORCH_SOURCE_STACK=bun-typescript
+ORCH_BUILD_MODE=bun-compile
+ORCH_BUILD_ID=orch-build-20260413-001
+ORCH_ENTRYPOINT=/usr/local/lib/hy2xs/hy2xs-orchestrator
+
+DEPLOY_DOMAIN=example.com
+SSH_PORT=22
+
+HY2_SOURCE=official-upstream
+HY2_VERSION=v2.8.1
+HY2_LISTEN_HOST=0.0.0.0
+HY2_PORT=443
+HY2_OBFS_TYPE=salamander
+HY2_OBFS_PASSWORD=CHANGE_ME
+HY2_BANDWIDTH_UP_Mbps=50
+HY2_BANDWIDTH_DOWN_Mbps=50
+HY2_IGNORE_CLIENT_BANDWIDTH=false
+HY2_CONFIG_PATH=/etc/hysteria/config.yaml
+
+HUI_ENABLED=true
+HUI_FORK_REF=main
+HUI_BUILD_ID=hy2xs-admin-build-20260413-001
+HUI_BIND_HOST=127.0.0.1
+HUI_PORT=8081
+HUI_INSTALL_DIR=/opt/hy2xs-admin
+HUI_DATA_DIR=/var/lib/hy2xs-admin