HY2XS

HY2XS — production installer/runtime-manager для развёртывания Hysteria2 + HY2XS admin на чистом Debian 13 amd64.

Состав baseline:

• production builder на Debian 13 amd64 создаёт один переносимый архив;
• install-only оркестратор на Bun + TypeScript поставляется на target как готовый compiled artifact;
• HY2XS admin поставляется в составе пакета как bundled fork;
• vanilla Hysteria2 устанавливается как pinned binary (version/url/sha256 из metadata install package);
• runtime-конфиг управляется через /etc/hy2xs/hy2xs.env и команду reconfigure.

В baseline намеренно не входят target-side build, standalone rollback/update/uninstall subcommands, Telegram bot delivery, port hopping и generic server-manager функции.

При этом install/reconfigure содержат bounded rollback для failure-сценариев firewall/systemd/config/smoke.

Структура репозитория

• tools/build — production builder и packaging pipeline.
• orchestrator — исходники install-only оркестратора на Bun + TypeScript.
• package — skeleton итогового install package: entrypoint, templates, systemd units, package docs.
• apps — исходники HY2XS admin fork.
• docs — архитектурная документация и acceptance.
• dist — итоговые install archives, создаются builder'ом и не хранятся в git.

Публикация

Целевой репозиторий:

https://git.flamy.studio/prod/HY2XS_flamy.git

Публиковать изменения нужно только после прохождения baseline acceptance, сборки оркестратора и smoke checks итогового пакета.

Установка и конфигурация

На чистом Debian 13 target нужно распаковать архив и запустить от root:

Важно: packaged baseline использует HY2XS_SSH_PORT=2323 по умолчанию. На target-хосте это значение обязательно нужно привести к фактическому рабочему SSH-порту оператора в /etc/hy2xs/hy2xs.env и применить через reconfigure --apply.

Обязательные системные зависимости target-хоста:

apt-get update
apt-get install -y sudo ca-certificates curl iproute2 tar openssl nftables systemd

sudo используется для smoke-проверок прав доступа от имени runtime-пользователей и автоматически устанавливается на шаге deps в install-flow.

Предварительная ручная установка sudo перед ./install.sh не требуется: preflight допускает его отсутствие на clean-host и install deps bootstrap'ит его до smoke-проверок.

./install.sh --non-interactive

Опционально можно передать внешний source-config (не путь runtime-файла на target):

./install.sh --config /root/custom-hy2xs.env --non-interactive

/etc/hy2xs/hy2xs.env создаётся install-слоем автоматически и далее редактируется оператором перед reconfigure.

После установки применяются команды оркестратора:

hy2xs-orchestrator reconfigure --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env --dry-run
hy2xs-orchestrator reconfigure --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env --apply
hy2xs-orchestrator doctor --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env

HY2XS_ADMIN_INITIAL_PASSWORD и HY2XS_ADMIN_CON_PASS — install-only bootstrap-поля. Их изменение в /etc/hy2xs/hy2xs.env после установки не ротирует существующие credentials в SQLite автоматически.

Ключевые инварианты:

• только IPv4 (0.0.0.0:<port> для Hysteria, 127.0.0.1:<ui_port> для UI по умолчанию);
• IPv6 явно out of scope;
• UI запускается не от root (hy2xs-admin);
• секреты и чувствительные конфиги: 0600;
• snapshot deploy-фактов: /etc/hysteria/post-install.env;
• editable runtime layer: /etc/hy2xs/hy2xs.env.