HY2XS_flamy/README.md

HY2XS

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

Состав baseline:

• production builder на Debian 12 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, rollback/uninstall orchestration, Telegram bot delivery, port hopping и generic server-manager функции.

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

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

Сборка

Production-сборка выполняется только на Debian 12 amd64:

PACKAGE_VERSION=0.1.0 ./tools/build/build.sh

Builder сам проверяет ОС, архитектуру, структуру проекта, lock-файлы, версии Go/Bun/Node.js/pnpm и при необходимости скачивает локальный toolchain.

Ожидаемый результат:

dist/hy2xs-install-0.1.0.tar.gz

На target server не должно быть bun install, pnpm install, TypeScript transpilation, frontend build или Go build.

Подробности сборки: tools/build/README.md.

Публикация

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

https://git.ext.flamy.studio/flamy_dev/HY2XS_flamy.git

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

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

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

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

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

sudo является обязательной зависимостью target-хоста. Он используется не для интерактивной установки, а для smoke-проверок прав доступа от имени runtime-пользователей.

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