На 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:

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

Важное про 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.2.1 \
BUILD_ID=prod-$(date -u +%Y%m%dT%H%M%SZ) \
./tools/build/build.sh

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

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

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

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

tar -tzf dist/hy2xs-install-0.2.1.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.2.1.tar.gz hy2xs-install/metadata/package.env

When to update orchestrator/bun.lock

Do not regenerate orchestrator/bun.lock during production builds.

Update and commit orchestrator/bun.lock only when:

orchestrator/package.json changes;
BUN_REQUIRED changes in tools/build/lib/deps.sh;
orchestrator dependencies are intentionally upgraded.

Production builder always runs:

bun install --frozen-lockfile

If this command fails, fix and commit the lockfile in source control. Do not remove --frozen-lockfile.

Frontend lockfile discipline

Do not regenerate frontend lock data during routine production builds.

For frontend package management:

apps/frontend/package.json declares "packageManager": "pnpm@9.15.9";
builder uses pinned pnpm 9.15.9 from PNPM_REQUIRED;
production frontend install path is always:

pnpm install --frozen-lockfile

If frozen install fails, update dependencies intentionally in source control and commit lockfile changes. Do not remove --frozen-lockfile from build flow.

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

PACKAGE_VERSION=0.2.1
BUILD_ID=prod-$(date -u +%Y%m%dT%H%M%SZ)
BUN_FLAVOR=auto|x64|x64-baseline
FRONTEND_NODE_OLD_SPACE_SIZE=2048 (default memory limit for frontend build step)
TOOLCHAIN_DIR=/custom/path/.toolchain
VERIFY_TOOLCHAIN_CHECKSUMS=true

Frontend memory policy

Builder applies a safe default Node.js heap limit for frontend build inside bundle_ui():

--max-old-space-size=2048

Override options:

adjust default value for this policy:

FRONTEND_NODE_OLD_SPACE_SIZE=3072 ./tools/build/build.sh

or provide full custom Node options (if --max-old-space-size is already set there, builder will not append another one):

NODE_OPTIONS="--max-old-space-size=3072" ./tools/build/build.sh

Диагностика

Проверить 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.2.1 ./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

README.md Unescape Escape

HY2XS production builder