founder
8de1719aa4
- исправлен рендер post-install.env: прокинут HYSTERIA_API_SECRET
- добавлен fail-fast при неразрешенных {{...}} в renderTemplate
- HY2XS_FORCE_PASSWORD_CHANGE приведён к production default=false
- docs синхронизированы: sudo bootstrap на deps-стадии
- builder: VERIFY_TOOLCHAIN_CHECKSUMS=true по умолчанию
- acceptance расширен новыми инвариантами
244 lines
8.0 KiB
Markdown
244 lines
8.0 KiB
Markdown
# HY2XS production builder
|
||
|
||
Этот каталог содержит production builder для HY2XS.
|
||
|
||
Builder собирает один переносимый install-archive:
|
||
|
||
```text
|
||
dist/hy2xs-install-<version>.tar.gz
|
||
```
|
||
|
||
Этот архив переносится на production server, распаковывается и устанавливается через [`install.sh`](../../package/install.sh).
|
||
|
||
На production server не должно быть сборки из исходников: без `go build`, без `bun install`, без `pnpm install`, без frontend build и без TypeScript transpilation.
|
||
|
||
## Что где лежит
|
||
|
||
Основные части проекта:
|
||
|
||
- [`tools/build/build.sh`](build.sh) — главный entrypoint сборки.
|
||
- [`tools/build/lib/deps.sh`](lib/deps.sh) — проверка Debian/amd64, установка build dependencies, установка Go/Bun/Node.js/pnpm.
|
||
- [`tools/build/lib/package.sh`](lib/package.sh) — сборка orchestrator, сборка HY2XS admin, создание stage directory и tar.gz архива.
|
||
- [`tools/build/lib/verify.sh`](lib/verify.sh) — проверка структуры репозитория и итогового архива.
|
||
- [`tools/build/hysteria-lock.env`](hysteria-lock.env) — pinned версия, URL и SHA256 upstream Hysteria2 binary.
|
||
- [`orchestrator`](../../orchestrator) — TypeScript/Bun install-only orchestrator.
|
||
- [`apps`](../../apps) — HY2XS admin fork: backend на Go и frontend.
|
||
- [`package`](../../package) — skeleton будущего install package: `install.sh`, templates, systemd units, default config.
|
||
- [`dist`](../../dist) — итоговые архивы. Создаётся builder'ом, в git обычно не хранится.
|
||
- [`.toolchain`](../../.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.3.13`;
|
||
- 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`](../../fix17.txt).
|
||
|
||
По умолчанию:
|
||
|
||
```bash
|
||
BUN_FLAVOR=auto
|
||
```
|
||
|
||
Логика:
|
||
|
||
- если CPU поддерживает AVX2, используется `bun-linux-x64`;
|
||
- если CPU не поддерживает AVX2, используется `bun-linux-x64-baseline`.
|
||
|
||
Можно принудительно задать flavor:
|
||
|
||
```bash
|
||
BUN_FLAVOR=x64 ./tools/build/build.sh
|
||
```
|
||
|
||
или:
|
||
|
||
```bash
|
||
BUN_FLAVOR=x64-baseline ./tools/build/build.sh
|
||
```
|
||
|
||
## Запуск
|
||
|
||
Из корня репозитория:
|
||
|
||
```bash
|
||
./tools/build/build.sh
|
||
```
|
||
|
||
С явной версией и build id:
|
||
|
||
```bash
|
||
PACKAGE_VERSION=0.2.1 \
|
||
BUILD_ID=prod-$(date -u +%Y%m%dT%H%M%SZ) \
|
||
./tools/build/build.sh
|
||
```
|
||
|
||
## Проверка результата
|
||
|
||
Проверка архива:
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
Проверка обязательных файлов:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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`](../../orchestrator/bun.lock) during production builds.
|
||
|
||
Update and commit [`orchestrator/bun.lock`](../../orchestrator/bun.lock) only when:
|
||
|
||
- [`orchestrator/package.json`](../../orchestrator/package.json) changes;
|
||
- `BUN_REQUIRED` changes in [`tools/build/lib/deps.sh`](lib/deps.sh);
|
||
- orchestrator dependencies are intentionally upgraded.
|
||
|
||
Production builder always runs:
|
||
|
||
```bash
|
||
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`](../../apps/frontend/package.json) declares `"packageManager": "pnpm@9.15.9"`;
|
||
- builder uses pinned pnpm `9.15.9` from [`PNPM_REQUIRED`](lib/deps.sh);
|
||
- production frontend install path is always:
|
||
|
||
```bash
|
||
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`
|
||
|
||
По умолчанию `VERIFY_TOOLCHAIN_CHECKSUMS=true` в [`tools/build/lib/deps.sh`](tools/build/lib/deps.sh), поэтому для production-сборки обязательно передавать контрольные суммы:
|
||
|
||
- `GO_ARCHIVE_SHA256=<sha256>`
|
||
- `NODE_ARCHIVE_SHA256=<sha256>`
|
||
- `BUN_ARCHIVE_SHA256=<sha256>`
|
||
|
||
## Frontend memory policy
|
||
|
||
Builder applies a safe default Node.js heap limit for frontend build inside [`bundle_ui()`](lib/package.sh):
|
||
|
||
```bash
|
||
--max-old-space-size=2048
|
||
```
|
||
|
||
Override options:
|
||
|
||
- adjust default value for this policy:
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
NODE_OPTIONS="--max-old-space-size=3072" ./tools/build/build.sh
|
||
```
|
||
|
||
## Диагностика
|
||
|
||
Проверить AVX2:
|
||
|
||
```bash
|
||
grep -m1 '^flags' /proc/cpuinfo | grep -qw avx2 && echo 'CPU has AVX2' || echo 'CPU has NO AVX2; Bun baseline is required'
|
||
```
|
||
|
||
Проверить Bun:
|
||
|
||
```bash
|
||
.toolchain/bun/bin/bun --version
|
||
echo "bun_exit=$?"
|
||
```
|
||
|
||
Если есть `Illegal instruction`, удалите старый Bun и пересоберите:
|
||
|
||
```bash
|
||
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
|
||
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
|
||
```
|