Files

T

founder 086b5d6624 build: закрепить новые инварианты приёмкой и документацией

verify_versions_contract получил сверку API namespace. Путь machine-auth
записывается в /etc/hysteria/config.yaml и в post-install.env, то есть по нему
Hysteria обращается к админке. Пока строка была продублирована в шаблонах,
smoke, тестах, приёмке и e2e, расхождение обнаруживалось только на живом
сервере. Теперь Go-константы, API_BASE фронтенда и оба шаблона сверяются
против значений, скомпилированных в оркестратор.

Приёмка проверяет, что:
  - fatal_pre_apply недостижим после записи install-state;
  - каждый ownership-флаг взводится раньше своего шага;
  - у read-only фазы нет универсального раннера, через который можно
    проскользнуть;
  - инвариант публичного endpoint живёт в preflight и не обращается к внешним
    сервисам определения IP;
  - purge-v0.sh и clean-host описывают одну границу;
  - секреты не попадают в персистентный файл экспорта;
  - импорт пиров валидируется так же строго, как их создание;
  - удалённые exportConfig/importConfig не вернулись.

Захардкоженная схема =2 в приёмке заменена на значение из versions.env: при
переходе на schema 3 пришлось бы помнить ещё и про эту строку.

Документация: контракт раннеров и ownership в 08, инвариант публичного
endpoint в 08/09/12/13 и README, сетевая идентичность панели и удалённые
export/import в 04, сценарии D1 (отказ сразу после PHASE 0) и D2 (устаревший
DNS после смены IPv4) в 11, версии package.json как не-версия продукта в 02.

2026-08-27 20:50:03 +05:00

7.1 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.

Политики проверок DNS

В /etc/hy2xs/hy2xs.env есть две независимые политики, обе по умолчанию strict:

Переменная	Что проверяет
`HY2XS_DNS_AAAA_POLICY`	наличие AAAA-записи при IPv4-only профиле
`HY2XS_PUBLIC_ENDPOINT_POLICY`	что A-записи публичного endpoint ведут на публичные IPv4 этого сервера

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

Обе политики применяются в install, reconfigure и doctor, потому что живут в общем preflight.

Сетевая идентичность админки

HY2XS_UI_PORT, HY2XS_UI_BIND_HOST, HY2XS_DATA_DIR и HY2XS_LOG_DIR — единственный источник истины для этих величин. Админка читает их из окружения юнита и не хранит собственных копий в SQLite.

Важно:

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.

7.1 KiB Raw Blame History Unescape Escape