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

5.8 KiB

Raw Blame History

Runtime env и post-install snapshot

Цель документа

Зафиксировать двухслойную модель:

editable runtime env: /etc/hy2xs/hy2xs.env
generated deploy snapshot: /etc/hysteria/post-install.env

Зачем нужен файл

После первичной установки оператору нужны:

runtime-файл, который оркестратор читает и валидирует;
snapshot-файл фактического deploy-состояния.

В snapshot видно:

какой пакет был установлен
какой build артефакт использован
какой стек оркестратора применён
какая версия Hysteria реально установилась
какой build HY2XS admin разложен на target
какие базовые параметры сети и портов заданы

Именно для этого создаётся post-install.env.

Чего файл не делает

Этот файл:

не делает оркестратор update-manager'ом
не гарантирует автоматическое применение изменений
не заменяет runtime-конфиги
не превращает target в builder

Минимальный набор переменных

Deploy / package

DEPLOY_TARGET_OS
DEPLOY_TIMESTAMP (last apply timestamp)
PACKAGE_NAME
PACKAGE_BUILD_ID
PACKAGE_VERSION

Orchestrator

ORCH_SOURCE_STACK=bun-typescript
ORCH_BUILD_MODE
ORCH_BUILD_ID
ORCH_ENTRYPOINT

Общие

HY2XS_CONFIG_SCHEMA_VERSION
DEPLOY_DOMAIN
PUBLIC_HOST
PUBLIC_PORT
SSH_PORT
HY2XS_FIREWALL_MODE
HY2XS_FIREWALL_STAGED_APPLY
HY2XS_ADMIN_USER
HY2XS_FORCE_PASSWORD_CHANGE
HY2XS_ALLOW_SELF_SIGNED_DEV

Hysteria

HY2_SOURCE=official-upstream
HY2_VERSION — фактически установленная версия
HY2_RESOLUTION — как версия была выбрана при сборке: latest-stable, pinned или override
HY2_TLS_MODE
HY2_ACME_EMAIL
HY2_TLS_CERT_PATH
HY2_TLS_KEY_PATH
HY2_LISTEN_HOST
HY2_PORT
HY2_AUTH_MODE
HY2_AUTH_URL
HY2_TRAFFIC_STATS_LISTEN
HY2_OBFS_TYPE — gecko или salamander
HY2_OBFS_PASSWORD
HY2_GECKO_MIN_PACKET_SIZE
HY2_GECKO_MAX_PACKET_SIZE
HY2_BANDWIDTH_UP
HY2_BANDWIDTH_DOWN
HY2_DISABLE_LOSS_COMPENSATION
HY2_IGNORE_CLIENT_BANDWIDTH
HY2_CONGESTION_TYPE
HY2_BBR_PROFILE
HY2_DISABLE_STATELESS_RESET
HY2_CONFIG_PATH

HY2XS admin

HY2XS_ADMIN_ENABLED
HY2XS_ADMIN_SOURCE
HY2XS_ADMIN_BUILD_ID
HY2XS_ADMIN_BIND_HOST
HY2XS_ADMIN_PORT
HY2XS_ADMIN_INSTALL_DIR
HY2XS_ADMIN_DATA_DIR
HY2XS_ADMIN_LOG_DIR

Как работать с файлами

Правильная модель:

оркестратор создаёт hy2xs.env и post-install.env при установке;
оператор редактирует только hy2xs.env;
оператор запускает reconfigure --dry-run, затем reconfigure --apply;
оркестратор обновляет runtime и перезаписывает snapshot.

Важно:

HY2XS_ADMIN_INITIAL_PASSWORD используется только для первичного bootstrap seed;
HY2XS_ADMIN_CON_PASS — отдельная runtime-сущность для Hysteria auth/smoke;
bootstrap secret хранится в явном формате KEY=VALUE (ADMIN_USER, ADMIN_INITIAL_PASSWORD, ADMIN_CON_PASS), права 0600;
HY2XS_FORCE_PASSWORD_CHANGE в production baseline установлен в false (forced UX-flow пока не реализован);
после первичного seed перезапуски hy2xs-admin не должны переопределять пароль admin и con_pass.

Immutable-bootstrap контракт

/etc/hy2xs/bootstrap-admin.secret создаётся оркестратором только при первичной установке.
На reconfigure --apply bootstrap secret не пересоздаётся и не ротируется автоматически.
Изменения HY2XS_ADMIN_INITIAL_PASSWORD в runtime env после первичной установки не должны менять фактический пароль admin.
HY2XS_ADMIN_CON_PASS используется как bootstrap-значение при первичной установке; после создания admin account изменение этого значения в /etc/hy2xs/hy2xs.env не пересоздаёт и не обновляет существующий con_pass в SQLite.
Ротация con_pass выполняется через account-management слой UI/БД, а bootstrap snapshot остаётся неизменным.

Что нельзя делать

сваливать туда временный мусор
считать, что edit env автоматически меняет runtime без reconfigure --apply
использовать файл как замену настоящей конфигурации сервисов

Пример

Используйте canonical runtime-файл package/config/hy2xs.env как базовый шаблон значений и переносите его параметры в /etc/hy2xs/hy2xs.env.

5.8 KiB Raw Blame History Unescape Escape