HY2XS_flamy/tools/build/README.md

HY2XS production builder

Этот каталог содержит production builder для HY2XS.

Builder собирает один переносимый install-archive:

dist/hy2xs-install-<version>.tar.gz

Этот архив переносится на production server, распаковывается и устанавливается через install.sh.

На production server не должно быть сборки из исходников: без go build, без bun install, без pnpm install, без frontend build и без TypeScript transpilation.

Что где лежит

Основные части проекта:

• tools/build/build.sh — главный entrypoint сборки.
• tools/build/lib/deps.sh — проверка Debian/amd64, установка build dependencies, установка Go/Bun/Node.js/pnpm.
• tools/build/lib/package.sh — сборка orchestrator, сборка HY2XS admin, создание stage directory и tar.gz архива.
• tools/build/lib/verify.sh — проверка структуры репозитория и итогового архива.
• tools/build/hysteria-lock.env — pinned версия, URL и SHA256 upstream Hysteria2 binary.
• orchestrator — TypeScript/Bun install-only orchestrator.
• apps — HY2XS admin fork: backend на Go и frontend.
• package — skeleton будущего install package: install.sh, templates, systemd units, default config.
• dist — итоговые архивы. Создаётся builder'ом, в git обычно не хранится.
• .toolchain — локальный toolchain builder'а. Создаётся автоматически, в git не хранится.

Требования к build machine

Production build поддерживается только на:

• Debian 13;
• amd64 / x86_64;
• root или пользователь с sudo;
• доступ в интернет.

Нужен outbound HTTPS/DNS до:

• Debian apt repositories;
• go.dev;
• github.com;
• nodejs.org;
• npm registry.

Windows и macOS можно использовать для редактирования исходников, но финальную production-сборку надо делать на Debian 13 amd64.

Что builder делает сам

При запуске builder:

1. Проверяет, что host — Debian 13 amd64.
2. Проверяет структуру репозитория.
3. Устанавливает недостающие системные build dependencies через apt-get.
4. Проверяет или скачивает локальные версии:
   • Go 1.21.13;
   • Bun 1.1.45;
   • Node.js 20.19.0;
   • pnpm 9.15.9.
5. Собирает install-only orchestrator в standalone binary.
6. Собирает frontend HY2XS admin.
7. Собирает backend HY2XS admin в Linux amd64 binary.
8. Копирует package skeleton.
9. Записывает metadata и checksums.
10. Создаёт dist/hy2xs-install-<version>.tar.gz.
11. Проверяет, что архив содержит обязательные файлы.

Важное про Bun и старые CPU

Bun имеет два Linux x64 artifact'а:

• bun-linux-x64 — обычный build;
• bun-linux-x64-baseline — build для CPU без AVX2.

Если CPU не поддерживает AVX2, обычный Bun может падать с Illegal instruction.

Builder автоматически проверяет /proc/cpuinfo.

По умолчанию:

BUN_FLAVOR=auto

Логика:

• если CPU поддерживает AVX2, используется bun-linux-x64;
• если CPU не поддерживает AVX2, используется bun-linux-x64-baseline.

Можно принудительно задать flavor:

BUN_FLAVOR=x64 ./tools/build/build.sh

или:

BUN_FLAVOR=x64-baseline ./tools/build/build.sh

Запуск

Из корня репозитория:

./tools/build/build.sh

С явной версией и build id:

PACKAGE_VERSION=0.1.6 \
BUILD_ID=prod-$(date -u +%Y%m%dT%H%M%SZ) \
./tools/build/build.sh

Проверка результата

Проверка архива:

ls -lh dist/hy2xs-install-0.1.6.tar.gz
sha256sum dist/hy2xs-install-0.1.6.tar.gz | tee dist/hy2xs-install-0.1.6.tar.gz.sha256

Проверка обязательных файлов:

tar -tzf dist/hy2xs-install-0.1.6.tar.gz | grep -E '^(hy2xs-install/install.sh|hy2xs-install/orchestrator/hy2xs-orchestrator|hy2xs-install/ui/hy2xs-admin/hy2xs-admin|hy2xs-install/metadata/checksums.txt)$'

Проверка metadata:

tar -xOzf dist/hy2xs-install-0.1.6.tar.gz hy2xs-install/metadata/package.env

Полезные переменные

• PACKAGE_VERSION=0.1.6
• BUILD_ID=prod-$(date -u +%Y%m%dT%H%M%SZ)
• BUN_FLAVOR=auto|x64|x64-baseline
• TOOLCHAIN_DIR=/custom/path/.toolchain
• VERIFY_TOOLCHAIN_CHECKSUMS=true

Диагностика

Проверить AVX2:

grep -m1 '^flags' /proc/cpuinfo | grep -qw avx2 && echo 'CPU has AVX2' || echo 'CPU has NO AVX2; Bun baseline is required'

Проверить Bun:

.toolchain/bun/bin/bun --version
echo "bun_exit=$?"

Если есть Illegal instruction, удалите старый Bun и пересоберите:

rm -rf .toolchain/bun .toolchain/bun-tmp
rm -f .toolchain/downloads/bun-linux-x64-*.zip
rm -f .toolchain/downloads/bun-linux-x64-baseline-*.zip
PACKAGE_VERSION=0.1.6 ./tools/build/build.sh

Проверить shell syntax:

bash -n tools/build/build.sh
bash -n tools/build/lib/common.sh
bash -n tools/build/lib/deps.sh
bash -n tools/build/lib/package.sh
bash -n tools/build/lib/verify.sh