Files

T

founder ddf0ddf71e feat(v1): Gecko-обфускация, latest-stable Hysteria на сборке и forward-compatible admin

Сквозная миграция 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 файлов),
документация на русском.

2026-08-27 08:15:02 +05:00

6.2 KiB

Raw Permalink Blame History

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

local builder
install package
vanilla Hysteria2 from upstream
bundled HY2XS admin
Bun/TypeScript install-only orchestrator
systemd + nftables
post-install env
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-результат выглядит так:

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

6.2 KiB Raw Permalink Blame History Unescape Escape