HY2XS_flamy/CHANGELOG.md

Изменения HY2XS

Формат основан на Keep a Changelog. Проект использует семантическое версионирование.

Версия относится к самому HY2XS, а не к Hysteria: версия Hysteria выбирается на этапе сборки пакета и фиксируется в его metadata.

Unreleased

Hardening-проход перед релизом 1.0.0. Основная тема — сделать политику «только чистая установка» настоящим системным инвариантом, а не строчкой в документации.

Исправлено

• fatal_pre_apply мог означать «хост уже изменён». install-state.json пишется сразу после успешного preflight, до установки пакетов, но классификация отказа его не учитывала. Падение apt-get update или apt-get install объявлялось как «на сервере ничего не изменено»: откат и обработка состояния пропускались, а маркер оставался на диске и ломал следующую установку по clean-host контракту.

  Ownership-флаги переформулированы с «шаг успешно завершился» на «операция могла начать менять систему» и взводятся перед мутирующим вызовом: apt-get умеет изменить систему и упасть. fatal_pre_apply теперь недостижим ни при одном взведённом флаге, включая запись состояния.

• Экспорт в админке оставлял секреты на диске навсегда. ExportPeer и выгрузка системного конфига шли через os.Create в /var/lib/hy2xs-admin/export/, и файл там не удалялся. При ?includeSecrets=true это означало расшифрованные секреты пиров — фактические учётные данные доступа — в открытом виде, накапливающиеся с каждым нажатием кнопки. Экспорт формируется в памяти; каталога export/ больше нет.

• Generic export/import таблицы config выгружал и позволял подменить криптографические ключи приложения. Выгрузка исключала только сырой Hysteria YAML, а в той же таблице лежат JWT_SECRET, PEER_SECRET_KEY, PEER_SECRET_ENCRYPTION_KEY и HYSTERIA2_TRAFFIC_STATS_SECRET. Импорт их не блокировал: подмена PEER_SECRET_ENCRYPTION_KEY ломает расшифровку секретов уже существующих пиров. Оба маршрута и их UI удалены — production-сценария у них не было, перенос пиров делают peer-import/peer-export.

• Импорт пиров шёл мимо всей валидации. Обычное создание пира проходит через dto.PeerSaveDto, импорт JSON — нет: в базу попадало имя любой длины и с любыми символами, disabled с произвольным числом, отрицательные счётчики. Файл применялся построчно, поэтому ошибка в середине оставляла список пиров наполовину изменённым, а импорт мог перезаписать bootstrap-admin-peer, чей секрет продублирован в /etc/hy2xs/bootstrap-admin.secret. Партия теперь проверяется целиком до первой записи, неизвестные поля отклоняются, bootstrap-пир защищён.

• DNS проверялся на существование A-записи, но не на то, куда она ведёт. После принудительной смены IPv4 провайдером doctor отвечал успехом, хотя клиентская ссылка отправляла людей на чужую машину. Проверялся при этом HY2XS_DOMAIN, тогда как в hysteria2:// уезжает HY2XS_PUBLIC_HOST.

  Добавлен инвариант публичного endpoint: A-записи обязаны принадлежать множеству публичных IPv4, назначенных интерфейсам этого сервера. Проверка живёт в общем preflight, поэтому действует в install, reconfigure и doctor. Адрес определяется локально, без внешних сервисов определения IP. Строгость управляется HY2XS_PUBLIC_ENDPOINT_POLICY (strict по умолчанию).

• Read-only guard PHASE 0 можно было обойти. Guard стоял на writeText, writeTextAtomic, runVisible, runHidden и runRawVisible, но не на универсальном run, через который в коде проходили и наблюдение (ss, systemctl is-active), и настоящие мутации (useradd, install -d, mkdir, cp -a, tar). Универсального раннера больше нет: есть runReadOnly* без guard'а и runMutating* под guard'ом, а выбор — явное решение на месте вызова.

• Go-санитайзер конфига вырезал секреты из URL только у ключей url/addr. Будущее upstream-поле с другим именем (endpoint:) уносило встроенные учётные данные и access_token наружу целиком; URL внутри списков не обрабатывались вовсе. Граница определяется значением, а не именем ключа — как в TS-санитайзере оркестратора; обе реализации покрыты зеркальными тестами.

• purge-v0.sh --keep-hysteria-binary противоречил установщику. Скрипт сохранял /usr/local/bin/hysteria и сообщал «хост чист для установки HY2XS v1», хотя clean-host контракт считает этот бинарник legacy-маркером и следующая установка отказалась бы. Флаг удалён.

• clean-host не замечал часть того, что удаляет purge. /var/lib/hysteria (ACME-состояние и сертификаты Hysteria), /var/log/hy2xs, /usr/local/lib/hy2xs и /usr/local/bin/hy2xs-orchestrator не были маркерами: сервер, где остался только старый runtime-state Hysteria, проходил проверку и получал свежую установку поверх чужого состояния. Оба списка теперь описывают одну границу, и приёмка это проверяет.

• Установщик мог повредить работающий сервер до того, как откажется его трогать. install.sh переписывал /usr/local/lib/hy2xs, раскладывал runtime-пакет и перезаписывал /var/lib/hy2xs/install-state.json, и лишь потом запускал clean-host preflight. При ошибочном запуске поверх старого сервера rollback дополнительно выполнял stop и disable для работающих hysteria-server и hy2xs-admin.

  Установка разделена на две фазы с жёсткой границей: PHASE 0 — read only, PHASE 1 — mutation. Read-only проверка выполняется новой командой hy2xs-orchestrator preflight-install из распакованного архива, а граница держится runtime-guard'ом, а не соглашением.

• Отсутствие HY2XS_CONFIG_SCHEMA_VERSION считалось текущей схемой. До v1 этого поля не существовало, поэтому именно пустое значение — самый вероятный признак конфигурации 0.x. Теперь оно отклоняется как legacy с указанием на чистую установку. Тест, закреплявший прежнее поведение, инвертирован.

• reconfigure и repair работали поверх любого маркера установки. Проверялся только флаг installed, который мог остаться и от 0.x. Маркер получил идентификацию поколения (product, release_line, config_schema_version), и обе команды проверяют её до всего остального.

• Классификация отказа шла по тексту сообщения об ошибке. Ошибка preflight со словом nftables классифицировалась как отказ firewall и приводила к откату чужого ruleset. Теперь классификация опирается на то, что операция реально успела применить. systemctl stop/disable выполняется только для юнитов, развёрнутых текущей операцией, а fatal_pre_apply по определению не выполняет системный откат и не собирает diagnostics-бандл.

• Diagnostics-бандл уносил machine token наружу. Построчное правило редакции auth: подставляло маркер в заголовок mapping'а и оставляло нетронутым вложенный auth.http.url с access_token=<секрет> — тем самым, что открывает и trafficStats API, и auth-endpoint. Редакция YAML переписана структурно; в env-файлах секреты теперь вырезаются и из URL-значений (HY2_AUTH_URL не подходил ни под один маркер имени).

• quic.maxIdleTimeout не проверялся семантической проверкой конфига, хотя присутствовал в production-профиле. Заодно auth.http.url теперь сверяется целиком (host/port/path/token), а не по наличию подстроки access_token=; добавлены проверки auth.http.insecure, полей ACME и отсутствия посторонних секций верхнего уровня.

• Версия админки разъехалась с версией пакета: пакет 1.0.0 сообщал HY2XS admin version v0.0.22. Константа заменена переменной, которую проставляет сборка через ldflags из versions.env.

• Кнопки в панели, которые всегда возвращали ошибку. «Перезапустить панель» и загрузка сертификатов обращались к заглушкам. Маршруты и UI удалены.

Добавлено

• versions.env — единственный источник истины для контракта «продукт / платформа / toolchain»: версия продукта, линия релиза, схема конфигурации, целевая платформа, версии и контрольные суммы Go/Bun/Node/pnpm, политика выбора Hysteria. Прикладные зависимости и конкретная версия Hysteria сюда намеренно не переносятся: у них есть собственные lock-механизмы.

• Шаг сборки verify_versions_contract. Роняет сборку до создания tarball, если разошлись PACKAGE_VERSION, packageManager в двух package.json, схема в package/config/hy2xs.env, константы, скомпилированные в оркестратор, директива go в apps/go.mod, metadata пакета или версия, которую сообщает собранный hy2xs-admin.

• Контрольные суммы toolchain в контракте, включая обе сборки Bun (bun-linux-x64 и bun-linux-x64-baseline): артефакт выбирается по наличию AVX2, поэтому одной суммы архитектурно недостаточно. Передавать суммы через окружение больше не нужно — production-сборка запускается одной командой.

• Проверка происхождения артефакта Hysteria. Ожидаемый SHA-256 берётся из upstream-ассета hashes.txt и сверяется со скачанным бинарником до записи в HY2XS lock. Раньше сумма считалась локально от уже скачанного файла, то есть была trust-on-first-use.

• Полный clean-host контракт. Список маркеров чужой установки расширен с двух до четырнадцати: состояние, runtime-пакет, конфиги, бинарник Hysteria, фрагмент nftables, systemd-юниты, база админки и наследие 0.x. Пути установки и данных берутся из конфигурации, а не захардкожены.

• tools/legacy/purge-v0.sh и docs/14-legacy-cleanup.md — явная очистка сервера от предыдущего поколения. По умолчанию скрипт показывает план и ничего не делает; выполнение требует --apply --yes-i-know. Из установщика он не вызывается никогда: это вернуло бы destructive migration logic в путь свежей установки.

• Явный флаг --allow-partial-state для repair. Прежде согласие на работу поверх незавершённой установки подразумевалось молча.

• HY2XS_PUBLIC_ENDPOINT_POLICY (strict | warn | off, по умолчанию strict) — строгость проверки того, что публичный endpoint ведёт на этот сервер. Ослабление предназначено для топологий вне baseline: NAT, floating IP, anycast. Отсутствие A-записи фатально при любом значении.

• Раздельные API подпроцессов в оркестраторе: runReadOnly / runReadOnlySecret для наблюдения и runMutating* под read-only guard'ом.

• Сверка API namespace на сборке. Путь machine-auth и базовый префикс админского API объявлены по одной константе на компонент, а verify_versions_contract сверяет Go, фронтенд и шаблоны против значений, скомпилированных в оркестратор.

Изменено

• Пространства имён HTTP API. Операторский и auth API переехали с /hui на /api, machine-auth endpoint Hysteria — на /internal/hysteria/auth. Прежний общий префикс был наследием H UI: под ним лежали и machine-to-machine auth, и JWT-защищённый админский API, хотя middleware у них не пересекаются. Момент выбран до первого clean-install релиза: после 1.0.0 эти строки стали бы частью фактического v1 compatibility contract.

• Сетевая идентичность админки принадлежит оркестратору. Ключи H_UI_WEB_PORT, H_UI_WEB_CONTEXT, H_UI_CRT_PATH, H_UI_KEY_PATH удалены из схемы, seed и интерфейса вместе с собственным TLS-слоем панели. Раньше оркестратор передавал порт аргументом, админка записывала его в SQLite и тут же читала обратно, а UI показывал поля в disabled-виде: второй источник истины, из которого ничего нельзя было изменить. Панель всегда монтируется в /.

• HUI_DATA/HUI_LOG → HY2XS_DATA_DIR/HY2XS_LOG_DIR. Мост в systemd-юните, перекладывавший canonical env HY2XS в имена старого H UI, удалён.

• База админки — hy2xs-admin.db вместо h_ui.db; reference-схема — apps/docs/sql/schema.sql вместо h_ui_db.sql. Совместимость сохранять не требуется: v1 ставится только с нуля. Историческое имя h_ui.db остаётся в docs/14-legacy-cleanup.md — там это имя чужого артефакта, который очистка должна найти.

• Индикатор загрузки и legacy-цвета переведены на брендовый токен. NProgress приходил со своим #29d и был единственным элементом интерфейса вне палитры HY2XS; страницы 401/404 и подсветка выбранной строки таблицы несли цвета исходного admin-шаблона. Все они привязаны к --el-color-primary, а не переписаны вторым литералом.

• Приёмка сверяет схему конфигурации с versions.env, а не с числом 2 в тексте проверки.

• E2E подключается по ссылке из production-кода. Внутри tools/test/e2e-hysteria.sh жила вторая реализация hysteria2:// URI на bash: дрейф любой из двух реализаций оставлял обе группы тестов зелёными. Теперь ссылку выдаёт service.BuildHysteria2ShareURI через apps/tools/share-uri. Единственное расхождение — insecure=1 для самоподписанного сертификата, и оно ограничено тестами с двух сторон.

• Формулировка гарантии санитайза экспорта. Вместо «любой будущий секрет будет удалён» — «известные секреты и неизвестные поля с секретоподобным именем». Список маркеров расширен (apiKey, privateKey, authorization, cookie, bearer, passphrase, signature, …) и синхронизирован между Go-админкой и оркестратором.

Удалено

• Маршруты, операциями которых продукт не владеет: POST /hysteria2ChangeVersion, GET /listRelease, POST /config/updateHysteria2Config, POST /config/importHysteria2Config, POST /config/restartServer, POST /config/uploadCertFile, GET /config/hysteria2AcmePath. Вместе с ними — соответствующие сервисы, клиентские функции фронтенда, кнопки и строки i18n.

  Маршруты удалены, а не оставлены отвечающими «feature disabled»: API-контракт не должен обещать updater, которого у продукта нет, а неиспользуемый маршрут остаётся attack surface.

• POST /config/exportConfig и POST /config/importConfig — generic-выгрузка и загрузка таблицы config вместе с криптографическими ключами приложения. Вместе с ними — кнопки Import/Export в настройках, клиентские функции и строки i18n.

• Персистентный каталог выгрузок /var/lib/hy2xs-admin/export/ и файловый helper util.ExportFile. Артефакт, который покидает сервер, не должен существовать на сервере дольше самого запроса.

• Флаг purge-v0.sh --keep-hysteria-binary.

• Мёртвые строки i18n, оставшиеся от H UI: noHttpsTip, defaultPassTip, hui*, useHysteria2Cert, invalidWebContext, mustBeInteger.

1.0.0 — 2026-08-27

Первый релиз линейки v1.

Обновление с 0.x не поддерживается. Между 0.x и 1.0.0 изменились схема конфигурации, тип обфускации по умолчанию и контракт выбора версии Hysteria. Сервер, установленный из пакета 0.x, нужно поднимать заново: очистка и установка с нуля. Подробности — в разделе «Миграция с 0.x» ниже.

Добавлено

• Разрешение версии Hysteria на этапе сборки. Builder по умолчанию сам определяет последний стабильный upstream-релиз, скачивает артефакт, вычисляет SHA-256 и замораживает version + url + sha256 в metadata пакета. Target-сервер по-прежнему скачивает конкретный неизменяемый артефакт и никогда не обращается к moving latest.
• Compatibility gate в сборке. До создания release-пакета builder рендерит канонический конфиг HY2XS тем же кодом, что и оркестратор, и запускает с ним реальный бинарник Hysteria — для обоих профилей обфускации. Несовместимый upstream ломает сборку, а не сервер оператора.
• Поддержка Gecko-обфускации (Hysteria 2.9.2+) со сквозной интеграцией: оркестратор, шаблон конфига, модель админки, генерация hysteria2:// URI, типы и формы фронтенда.
• Версия схемы конфигурации HY2XS_CONFIG_SCHEMA_VERSION=2. Пакет отказывается работать с конфигурацией неизвестной схемы вместо того, чтобы молча применить чужие значения.
• Современный серверный baseline в генерируемом конфиге: congestion.type: bbr + bbrProfile: standard, bandwidth.disableLossCompensation: false, quic.disableStatelessReset: false, а также maxIdleTimeout, maxIncomingStreams, disablePathMTUDiscovery.
• Модель современной схемы Hysteria в админке: obfs.gecko, ech, congestion, mimic, realm, tls.clientCA, quic.disableStatelessReset, bandwidth.disableLossCompensation, masquerade.proxy.xForwarded. Поля читаются и отображаются, даже если HY2XS не включает их в default-профиль.
• Тесты оркестратора (bun test): разбор env, рендер конфига, семантические инварианты профиля, резолвер upstream-релизов, release rollover.
• E2E-проверка с реальным клиентом Hysteria — tools/test/e2e-hysteria.sh: TLS и obfs handshake, HTTP auth (допуск и отказ), TCP и UDP forwarding, trafficStats, per-peer accounting, переподключение после перезапуска сервера и подключение клиента именно по сгенерированной ссылке.
• CHANGELOG.md в корне репозитория.

Изменено

• Обфускация по умолчанию для новых установок — Gecko. Salamander остаётся полностью поддержанным режимом совместимости и выбирается через HY2XS_HYSTERIA_OBFS_TYPE=salamander.
• Gecko использует upstream-defaults 512/1200 и не выносит размеры пакетов в env: официальная URI-схема не умеет их передавать, поэтому нестандартные значения сделали бы клиентскую ссылку неполной.
• Тип обфускации больше не собирается внутри статического YAML. Оркестратор формирует проверенный obfs-блок целиком, поэтому комбинация вида type: gecko рядом с блоком salamander структурно невозможна.
• Экспорт конфига Hysteria работает от исходного YAML, а не от типизированной модели: поля, о которых HY2XS ещё не знает, переживают выгрузку.
• Smoke-проверки разбирают YAML и сверяют его с production-профилем, вместо поиска подстрок.
• Канонический upstream-репозиторий — HyNetworks/hysteria (вместо устаревших ссылок на apernet).
• Реестр ACME DNS-провайдеров во фронтенде приведён к актуальному upstream: добавлены namecheap, njalla, porkbun.
• Дефолты формы Hysteria во фронтенде отражают baseline HY2XS (50/50 Mbps, Let's Encrypt, каталог ACME), а не пример из upstream-доки.
• Сборка запускает тесты оркестратора и админки до упаковки.

Исправлено

• hysteria2:// для Gecko. Генератор ссылок был завязан на Obfs.Salamander.Password, поэтому при любой другой обфускации выдавал формально корректную, но неработающую ссылку без параметров obfs.
• SNI в клиентской ссылке при файловых сертификатах. SNI брался только из ACME-блока, поэтому при HY2XS_TLS_MODE=file уходил пустым. Теперь источник — ACME-домен, затем HY2XS_DOMAIN, затем HY2XS_PUBLIC_HOST; IP-адрес в качестве SNI не используется.
• Утечка секретов в экспорте конфига. Выгружаемый оператору YAML содержал trafficStats.secret, access_token в auth-URL и пароль обфускации. Секреты вырезаются, включая поля, о которых HY2XS ещё не знает.
• Расхождение runtime-конфига с разобранным. renderRuntimeEnv печатал тип обфускации и режим auth литералами, игнорируя фактическую конфигурацию, — из-за чего запись /etc/hy2xs/hy2xs.env могла разойтись с тем, что реально применено.
• Смешение веток obfs в UI. Форма склеивала дефолт с ответом API и показывала блок обфускации, которого нет в конфиге сервера.
• namedotcom в списке ACME DNS-провайдеров. Провайдер удалён из Hysteria в 2.11.0; конфигурация с ним больше не запускается.
• Отсутствие подсказок в форме создания пира. У полей «Пир», «Комментарий» и «Секрет» не было ни примеров, ни пояснений: оператор не мог понять без документации, что секрет необязателен и генерируется автоматически.

Безопасность

• Переход на Hysteria 2.12.2 закрывает исправления, вышедшие после 2.8.2, включая обход UDP ACL, возможный OOM через sniff и обход ACL через домены с завершающей точкой (2.9.2).
• Экспорт конфига больше не выносит секреты за пределы сервера.

Миграция с 0.x

Автоматическая миграция не предусмотрена и не планируется.

Порядок перехода:

1. Выпишите с работающего сервера список пиров и их секреты.
2. Очистите сервер: tools/legacy/purge-v0.sh или ручная процедура из docs/14-legacy-cleanup.md.
3. Разверните 1.0.0 на чистом Debian 13 из release-пакета.
4. Заведите пиров заново и раздайте новые клиентские ссылки.

Установщик 1.0.0 обнаружит остатки предыдущей установки на шаге PHASE 0, откажется работать и не изменит на сервере ничего.

Клиентские ссылки 0.x в любом случае перестанут работать: смена обфускации — это изменение wire-совместимости.