90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# HY2XS production builder
|
||
|
||
## Назначение
|
||
|
||
[`build.sh`](build.sh) собирает переносимый установочный пакет HY2XS для production-развёртывания.
|
||
|
||
Итоговый архив создаётся в [`dist`](../../dist) и предназначен для установки на чистый Debian 12 amd64 без сборки на целевом сервере.
|
||
|
||
## Поддерживаемая среда сборки
|
||
|
||
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`](../../.toolchain) и не требует ручной установки Go/Bun/Node/pnpm в систему.
|
||
|
||
Если нужная версия уже установлена глобально, builder может использовать её. Если версия не совпадает, будет скачана локальная версия.
|
||
|
||
## Важные ограничения
|
||
|
||
- Builder не ставит HY2XS на сервер.
|
||
- Builder не выполняет target install.
|
||
- Builder не собирает ничего на target machine.
|
||
- Builder не вендорит бинарь Hysteria2 в пакет: Hysteria2 скачивается install layer'ом с official upstream.
|
||
- Итоговый пакет не должен содержать build scripts, `.toolchain` или временные каталоги.
|
||
|
||
## Результат
|
||
|
||
После успешной сборки появится архив:
|
||
|
||
```bash
|
||
dist/hy2xs-install-<version>.tar.gz
|
||
```
|
||
|
||
Его нужно перенести на target Debian 12 amd64, распаковать и запустить [`install.sh`](../../package/install.sh) от root.
|
||
|
||
## Диагностика
|
||
|
||
Если сборка падает:
|
||
|
||
1. Проверьте, что host — Debian 12 amd64.
|
||
2. Проверьте доступ к `go.dev`, `github.com`, `nodejs.org`, npm registry и apt repositories.
|
||
3. Удалите [`.toolchain`](../../.toolchain) и повторите запуск, если toolchain скачался повреждённым.
|
||
4. Проверьте lock-файлы [`bun.lock`](../../orchestrator/bun.lock), [`pnpm-lock.yaml`](../../apps/frontend/pnpm-lock.yaml), [`go.sum`](../../apps/go.sum).
|