founder
ddf0ddf71e
Сквозная миграция HY2XS на современную Hysteria (2.12.2) и переход на v1. Build: - версия Hysteria резолвится на этапе сборки из HyNetworks/hysteria и замораживается в metadata пакета (version + immutable url + sha256); - compatibility gate: реальный бинарник должен принять канонический конфиг HY2XS для gecko и salamander до создания пакета; - сборка прогоняет тесты оркестратора и админки. Конфигурационный контракт: - HY2XS_CONFIG_SCHEMA_VERSION=2, чужая схема отклоняется fail-fast; - obfs стал настоящим union gecko|salamander, gecko — default; - obfs-блок рендерится оркестратором целиком, два подтипа одновременно структурно невозможны; - современный baseline: congestion bbr/standard, disableLossCompensation=false, disableStatelessReset=false, полный quic-блок. Исправления: - share URI для gecko: генератор был завязан на Obfs.Salamander.Password и выдавал нерабочую ссылку при любой другой обфускации; - SNI брался только из ACME-блока и уходил пустым при HY2XS_TLS_MODE=file; - экспорт конфига выносил trafficStats.secret, access_token и obfs-пароль; - экспорт терял неизвестные upstream-поля при round-trip через типизированную модель; - renderRuntimeEnv печатал тип обфускации литералом, расходясь с конфигом; - namedotcom удалён из ACME-реестра (нет в Hysteria с 2.11.0). Тесты: - 95 тестов оркестратора: env, рендер, семантика профиля, резолвер, rollover; - тесты URI и экспорта в Go; - tools/test/e2e-hysteria.sh с реальным клиентом Hysteria. UX: - подсказки и примеры в форме создания пира. Прочее: CHANGELOG.md, .gitattributes (LF для target-side файлов), документация на русском.
139 lines
6.2 KiB
Markdown
139 lines
6.2 KiB
Markdown
# 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-порт
|
||
- `Gecko` включён по умолчанию, `Salamander` доступен как режим совместимости
|
||
- IPv4-only
|
||
- лимит по умолчанию: 50/50 Mbps на клиента
|
||
- fallback congestion controller: BBR (профиль `standard`)
|
||
|
||
### 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: разрабатываем **внутри проекта** и поставляем его сами
|
||
- Оркестратор: пишем на **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
|