HY2XS_flamy/docs/03-server-hysteria2.md

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
• бинарник Hysteria2 устанавливается только на этапе install
• версия, URL и SHA256 фиксируются в metadata install package
• reconfigure не обновляет и не откатывает бинарник Hysteria2

Платформа

• ОС: только Debian 13
• 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

Требования:

• production default: acme
• поддерживаемые режимы: acme | file | self_signed_dev
• self_signed_dev только для dev/lab и только при явном HY2XS_ALLOW_SELF_SIGNED_DEV=true
• корректный server_name / SNI на клиентах
• одна понятная TLS policy
• без смешивания нескольких несовместимых схем по умолчанию

Инварианты:

• acme -> только acme block в конфиге;
• acme block обязан содержать type: http|tls из runtime env (HY2XS_ACME_TYPE);
• HY2XS_ACME_TYPE=dns в production-профиле запрещён до отдельной реализации;
• HY2XS_HYSTERIA_AUTH_MODE зафиксирован в http и валидируется fail-fast;
• HY2XS_HYSTERIA_OBFS_TYPE зафиксирован в salamander и валидируется fail-fast;
• блок masquerade в baseline не задаётся (допустимо, но приводит к 404 Not Found на обычный HTTP трафик);
• file -> только tls.cert/tls.key block;
• self_signed_dev -> только dev сценарии.

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/hy2xs/hy2xs.env
• /etc/hysteria/post-install.env

Серверные инварианты

После установки должно быть верно:

1. Hysteria2 получена из official upstream
2. фактическая версия отражена в post-install.env
3. конфиг валиден
4. сервис стартует через systemd
5. нужный UDP-порт реально слушается
6. тестовый совместимый клиент может подключиться
7. bundled UI работает поверх актуального состояния сервера
8. trafficStats.secret отдельный от JWT_SECRET
9. IPv6 listen не используется
10. публичные клиентские endpoint/URL берутся из HY2XS_PUBLIC_HOST + HY2XS_PUBLIC_PORT, а не из listen/request-host