Подготовить HY2XS к production-сборке

2026-04-25 23:13:12 +05:00
commit 84a4e94567
277 changed files with 26513 additions and 0 deletions
@@ -0,0 +1,89 @@
+# 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. Проверяет состав итогового архива.
+
+## Запуск
+
+Из корня репозитория:
+
+```bash
+./tools/build/build.sh
+```
+
+С явной версией пакета:
+
+```bash
+PACKAGE_VERSION=0.1.0 ./tools/build/build.sh
+```
+
+С явным build id:
+
+```bash
+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` или временные каталоги.
+
+## Результат
+
+После успешной сборки появится архив:
+
+```bash
+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`.