HY2XS_flamy/tools/build/README.ru.md

HY2XS production builder

Назначение

tools/build/build.sh собирает один переносимый install package HY2XS для production-развёртывания.

Итоговый артефакт создаётся в dist/hy2xs-install-<version>.tar.gz и предназначен для установки на чистый Debian 12 amd64 без target-side сборки.

Поддерживаемая среда сборки

Builder поддерживает только:

• Debian 12;
• amd64 / x86_64;
• bash;
• доступ к интернету для установки build-зависимостей и toolchain.

Windows/macOS не являются production build host. На Windows можно править исходники, но финальную сборку нужно выполнять на Debian 12 amd64.

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

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

1. Проверяет ОС и архитектуру build host.
2. Проверяет структуру репозитория.
3. Доставляет отсутствующие системные build-зависимости через apt-get.
4. Проверяет и при необходимости скачивает локальный toolchain:
   • Go 1.21.13;
   • Bun 1.1.45;
   • Node.js 20.19.0;
   • pnpm 9.15.9.
5. Собирает install-only orchestrator под Linux amd64.
6. Собирает bundled HY2XS admin под Linux amd64.
7. Формирует metadata и checksums.
8. Создаёт архив install package.
9. Проверяет состав итогового архива.

Запуск

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

./tools/build/build.sh

С явной версией пакета:

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

С явным build id:

PACKAGE_VERSION=0.1.0 BUILD_ID=prod-20260425-001 ./tools/build/build.sh

Локальный toolchain

Builder ставит управляемый toolchain в .toolchain/ и не требует ручной установки Go/Bun/Node/pnpm в систему.

Если нужная версия уже установлена глобально, builder может использовать её. Если версия не совпадает, будет скачана локальная версия.

Важные ограничения

• Builder не ставит HY2XS на сервер.
• Builder не выполняет target install.
• Builder не собирает ничего на target machine.
• Builder не вендорит Hysteria2 binary в пакет: Hysteria2 скачивается install layer'ом с official upstream.
• Итоговый package не должен содержать build scripts, .toolchain или временные каталоги.

Результат

После успешной сборки появится архив:

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

Его нужно перенести на target Debian 12 amd64, распаковать и запустить install.sh от root.

Диагностика

Если сборка падает:

1. Проверьте, что host — Debian 12 amd64.
2. Проверьте доступ к go.dev, github.com, nodejs.org, npm registry и apt repositories.
3. Удалите .toolchain/ и повторите запуск, если toolchain скачался повреждённым.
4. Проверьте lock-файлы orchestrator/bun.lock, apps/frontend/pnpm-lock.yaml, apps/go.sum.