prod/HY2XS_flamy
5
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Полная миграция baseline на Debian 13: build-layer, metadata и документация

Browse Source
This commit is contained in:
Crimson
2026-05-05 05:39:59 +05:00
parent 52f1e5d909
commit 9368846405
12 changed files with 37 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+4 -4
View File
@@ -1,10 +1,10 @@
# HY2XS # HY2XS
HY2XS — production installer/runtime-manager для развёртывания Hysteria2 + HY2XS admin на чистом Debian 12 amd64. HY2XS — production installer/runtime-manager для развёртывания Hysteria2 + HY2XS admin на чистом Debian 13 amd64.
Состав baseline: Состав baseline:
- production builder на Debian 12 amd64 создаёт один переносимый архив; - production builder на Debian 13 amd64 создаёт один переносимый архив;
- install-only оркестратор на Bun + TypeScript поставляется на target как готовый compiled artifact; - install-only оркестратор на Bun + TypeScript поставляется на target как готовый compiled artifact;
- HY2XS admin поставляется в составе пакета как bundled fork; - HY2XS admin поставляется в составе пакета как bundled fork;
- vanilla Hysteria2 устанавливается как pinned binary (version/url/sha256 из metadata install package); - vanilla Hysteria2 устанавливается как pinned binary (version/url/sha256 из metadata install package);
@@ -25,7 +25,7 @@ HY2XS — production installer/runtime-manager для развёртывания
## Сборка ## Сборка
Production-сборка выполняется только на Debian 12 amd64: Production-сборка выполняется только на Debian 13 amd64:
```sh ```sh
PACKAGE_VERSION=0.1.0 ./tools/build/build.sh PACKAGE_VERSION=0.1.0 ./tools/build/build.sh
@@ -55,7 +55,7 @@ https://git.ext.flamy.studio/flamy_dev/HY2XS_flamy.git
## Установка и конфигурация ## Установка и конфигурация
На чистом Debian 12 target нужно распаковать архив и запустить от root: На чистом Debian 13 target нужно распаковать архив и запустить от root:
Обязательные системные зависимости target-хоста: Обязательные системные зависимости target-хоста:
docs/01-architecture-baseline.md
+3 -3
View File
@@ -21,7 +21,7 @@
Builder layer **не разворачивается на сервере**. Builder layer **не разворачивается на сервере**.
### 2. Runtime / target layer ### 2. Runtime / target layer
Запускается **только на чистом Debian 12**. Запускается **только на чистом Debian 13**.
Функции: Функции:
- установка системных зависимостей - установка системных зависимостей
@@ -100,7 +100,7 @@ Telegram-бот, backend выдачи ключей, remote profile publishing, b
5. Bun/TypeScript install-only orchestrator 5. Bun/TypeScript install-only orchestrator
6. systemd + nftables 6. systemd + nftables
7. post-install env 7. post-install env
8. install-only flow под чистый Debian 12 8. install-only flow под чистый Debian 13
## Что не входит в baseline ## Что не входит в baseline
@@ -122,7 +122,7 @@ Telegram-бот, backend выдачи ключей, remote profile publishing, b
1. На локальной машине собирается install package. 1. На локальной машине собирается install package.
2. В пакет уже встроены наш HY2XS admin и install-артефакт оркестратора. 2. В пакет уже встроены наш HY2XS admin и install-артефакт оркестратора.
3. Пакет переносится на чистый Debian 12. 3. Пакет переносится на чистый Debian 13.
4. На сервере запускается только install-only orchestration. 4. На сервере запускается только install-only orchestration.
5. Сервер скачивает свежую Hysteria2 из official upstream. 5. Сервер скачивает свежую Hysteria2 из official upstream.
6. Сервер разворачивает bundled UI из пакета. 6. Сервер разворачивает bundled UI из пакета.
docs/02-build-layer-and-package.md
+5 -5
View File
@@ -19,12 +19,12 @@
## Где работает builder ## Где работает builder
Production builder работает на отдельном build host: Production builder работает на отдельном build host:
- Debian 12 - Debian 13
- amd64 / x86_64 - amd64 / x86_64
- bash - bash
- доступ к интернету для apt и скачивания toolchain - доступ к интернету для apt и скачивания toolchain
В текущей production-модели сборка выполняется **на Debian 12 amd64**, а не на Windows/macOS dev-машине. В текущей production-модели сборка выполняется **на Debian 13 amd64**, а не на Windows/macOS dev-машине.
Builder не является частью target install flow: на target server приезжает уже готовый install package, без JS/TS/Go build step. Builder не является частью target install flow: на target server приезжает уже готовый install package, без JS/TS/Go build step.
@@ -104,7 +104,7 @@ project/
## Production builder bootstrap ## Production builder bootstrap
`tools/build/build.sh` должен быть самодостаточным для Debian 12 amd64: `tools/build/build.sh` должен быть самодостаточным для Debian 13 amd64:
1. Проверяет ОС и архитектуру. 1. Проверяет ОС и архитектуру.
2. Проверяет структуру репозитория и lock-файлы. 2. Проверяет структуру репозитория и lock-файлы.
@@ -132,8 +132,8 @@ project/
Система считается правильной, если: Система считается правильной, если:
1. builder запускается на Debian 12 amd64 build host, не как target-side build step 1. builder запускается на Debian 13 amd64 build host, не как target-side build step
2. пакет можно перенести на чистый Debian 12 2. пакет можно перенести на чистый Debian 13
3. на сервере нет отдельного build step 3. на сервере нет отдельного build step
4. bundled UI уже находится внутри пакета 4. bundled UI уже находится внутри пакета
5. оркестратор authored as Bun/TypeScript, но на target приходит как готовый install-артефакт 5. оркестратор authored as Bun/TypeScript, но на target приходит как готовый install-артефакт
docs/03-server-hysteria2.md
+1 -1
View File
@@ -28,7 +28,7 @@ Hysteria2 — основной транспортный компонент се
## Платформа ## Платформа
- ОС: только Debian 12 - ОС: только Debian 13
- init/system management: systemd - init/system management: systemd
- сетевой фильтр: nftables - сетевой фильтр: nftables
- архитектура baseline: x86_64/amd64 - архитектура baseline: x86_64/amd64
docs/08-orchestrator-spec.md
+2 -2
View File
@@ -41,7 +41,7 @@
## Предусловия ## Предусловия
Оркестратор рассчитан только на: Оркестратор рассчитан только на:
- чистый Debian 12 - чистый Debian 13
- root/sudo install context - root/sudo install context
- один сервер - один сервер
- одну baseline-схему - одну baseline-схему
@@ -74,7 +74,7 @@
## Что делает оркестратор по шагам ## Что делает оркестратор по шагам
1. Проверяет, что ОС — Debian 12. 1. Проверяет, что ОС — Debian 13.
2. Проверяет базовые зависимости и install context. 2. Проверяет базовые зависимости и install context.
3. Создаёт каталоги установки. 3. Создаёт каталоги установки.
4. Разворачивает bundled HY2XS admin. 4. Разворачивает bundled HY2XS admin.
docs/11-testing-and-acceptance.md
+4 -4
View File
@@ -7,7 +7,7 @@
## A. Builder layer tests ## A. Builder layer tests
### Проверяем ### Проверяем
1. builder запускается на Debian 12 amd64 build host 1. builder запускается на Debian 13 amd64 build host
2. итоговый пакет собирается без target-side шагов 2. итоговый пакет собирается без target-side шагов
3. bundled HY2XS admin реально входит в пакет 3. bundled HY2XS admin реально входит в пакет
4. package metadata / build id присутствуют 4. package metadata / build id присутствуют
@@ -19,7 +19,7 @@
## B. Target install tests ## B. Target install tests
### На чистом Debian 12 проверяем ### На чистом Debian 13 проверяем
1. пакет запускается без ручной сборки на сервере 1. пакет запускается без ручной сборки на сервере
2. Hysteria2 скачивается с official upstream 2. Hysteria2 скачивается с official upstream
3. bundled HY2XS admin раскладывается локально из пакета 3. bundled HY2XS admin раскладывается локально из пакета
@@ -58,7 +58,7 @@
## D. Negative tests ## D. Negative tests
1. не Debian 12 1. не Debian 13
2. порт уже занят 2. порт уже занят
3. старое конфликтующее состояние уже существует 3. старое конфликтующее состояние уже существует
4. домен / SNI заданы некорректно 4. домен / SNI заданы некорректно
@@ -73,7 +73,7 @@
Система принимается, если: Система принимается, если:
1. production builder на Debian 12 amd64 выдаёт переносимый install package 1. production builder на Debian 13 amd64 выдаёт переносимый install package
2. target server не выполняет build step 2. target server не выполняет build step
3. Hysteria2 получена из official upstream 3. Hysteria2 получена из official upstream
4. UI поставлен из bundled fork 4. UI поставлен из bundled fork
docs/13-production-runbook.md
+1 -1
View File
@@ -2,7 +2,7 @@
## 1. Supported target ## 1. Supported target
- clean Debian 12 amd64 - clean Debian 13 amd64
- single host install profile - single host install profile
- IPv4-only runtime model - IPv4-only runtime model
docs/README.md
+4 -4
View File
@@ -4,7 +4,7 @@
- серверный транспорт: **ванильная Hysteria2** - серверный транспорт: **ванильная Hysteria2**
- UI: **наш форк H UI / HY2XS admin**, поставляется **вместе с проектом** - UI: **наш форк H UI / HY2XS admin**, поставляется **вместе с проектом**
- target OS: **только чистый Debian 12** - target OS: **только чистый Debian 13**
- оркестратор: **install-only**, только первичная установка и базовая настройка - оркестратор: **install-only**, только первичная установка и базовая настройка
- стек оркестратора: **Bun + TypeScript** - стек оркестратора: **Bun + TypeScript**
- target-side build: **запрещён** - target-side build: **запрещён**
@@ -17,10 +17,10 @@
В этой редакции зафиксированы два слоя: В этой редакции зафиксированы два слоя:
1. **Builder layer** — работает на отдельном **Debian 12 amd64 build host**. 1. **Builder layer** — работает на отдельном **Debian 13 amd64 build host**.
Он собирает итоговый пакет, подготавливает **наш форк HY2XS admin**, компилирует **Bun/TypeScript оркестратор** в install-артефакт, упаковывает шаблоны, unit-файлы и примеры конфигов. Он собирает итоговый пакет, подготавливает **наш форк HY2XS admin**, компилирует **Bun/TypeScript оркестратор** в install-артефакт, упаковывает шаблоны, unit-файлы и примеры конфигов.
2. **Runtime / target layer** — работает **на чистом Debian 12**. 2. **Runtime / target layer** — работает **на чистом Debian 13**.
Здесь нет сборщика. Здесь запускается только итоговый install package / orchestrator, который: Здесь нет сборщика. Здесь запускается только итоговый install package / orchestrator, который:
- ставит системные зависимости - ставит системные зависимости
- разворачивает **наш встроенный UI** - разворачивает **наш встроенный UI**
@@ -72,4 +72,4 @@
Правильная baseline-модель теперь такая: Правильная baseline-модель теперь такая:
**Локальный builder собирает install package с нашим форком HY2XS admin и Bun/TypeScript оркестратором; серверный install-only orchestrator ставит этот пакет на чистый Debian 12, тянет свежую Hysteria2 из upstream, разворачивает UI, создаёт systemd + nftables + post-install env и подготавливает рабочее серверное окружение.** **Локальный builder собирает install package с нашим форком HY2XS admin и Bun/TypeScript оркестратором; серверный install-only orchestrator ставит этот пакет на чистый Debian 13, тянет свежую Hysteria2 из upstream, разворачивает UI, создаёт systemd + nftables + post-install env и подготавливает рабочее серверное окружение.**
tools/build/README.md
+5 -5
View File
@@ -4,18 +4,18 @@
[`build.sh`](build.sh) собирает переносимый установочный пакет HY2XS для production-развёртывания. [`build.sh`](build.sh) собирает переносимый установочный пакет HY2XS для production-развёртывания.
Итоговый архив создаётся в [`dist`](../../dist) и предназначен для установки на чистый Debian 12 amd64 без сборки на целевом сервере. Итоговый архив создаётся в [`dist`](../../dist) и предназначен для установки на чистый Debian 13 amd64 без сборки на целевом сервере.
## Поддерживаемая среда сборки ## Поддерживаемая среда сборки
Builder поддерживает только: Builder поддерживает только:
- Debian 12; - Debian 13;
- amd64 / x86_64; - amd64 / x86_64;
- bash; - bash;
- доступ к интернету для установки build-зависимостей и toolchain. - доступ к интернету для установки build-зависимостей и toolchain.
Windows/macOS не являются production build host. На Windows можно править исходники, но финальную сборку нужно выполнять на Debian 12 amd64. Windows/macOS не являются production build host. На Windows можно править исходники, но финальную сборку нужно выполнять на Debian 13 amd64.
## Что builder делает сам ## Что builder делает сам
@@ -77,13 +77,13 @@ Builder ставит управляемый toolchain в [`.toolchain`](../../.t
dist/hy2xs-install-<version>.tar.gz dist/hy2xs-install-<version>.tar.gz
``` ```
Его нужно перенести на target Debian 12 amd64, распаковать и запустить [`install.sh`](../../package/install.sh) от root. Его нужно перенести на target Debian 13 amd64, распаковать и запустить [`install.sh`](../../package/install.sh) от root.
## Диагностика ## Диагностика
Если сборка падает: Если сборка падает:
1. Проверьте, что host — Debian 12 amd64. 1. Проверьте, что host — Debian 13 amd64.
2. Проверьте доступ к `go.dev`, `github.com`, `nodejs.org`, npm registry и apt repositories. 2. Проверьте доступ к `go.dev`, `github.com`, `nodejs.org`, npm registry и apt repositories.
3. Удалите [`.toolchain`](../../.toolchain) и повторите запуск, если toolchain скачался повреждённым. 3. Удалите [`.toolchain`](../../.toolchain) и повторите запуск, если toolchain скачался повреждённым.
4. Проверьте lock-файлы [`bun.lock`](../../orchestrator/bun.lock), [`pnpm-lock.yaml`](../../apps/frontend/pnpm-lock.yaml), [`go.sum`](../../apps/go.sum). 4. Проверьте lock-файлы [`bun.lock`](../../orchestrator/bun.lock), [`pnpm-lock.yaml`](../../apps/frontend/pnpm-lock.yaml), [`go.sum`](../../apps/go.sum).
tools/build/build.sh
+1 -1
View File
@@ -16,7 +16,7 @@ BUILD_DIR="$ROOT_DIR/tools/build"
main() { main() {
cd "$ROOT_DIR" cd "$ROOT_DIR"
require_linux_debian12_amd64 require_linux_debian13_amd64
require_repo_layout require_repo_layout
ensure_build_dependencies ensure_build_dependencies
ensure_toolchain ensure_toolchain
tools/build/lib/deps.sh
+4 -4
View File
@@ -26,8 +26,8 @@ verify_archive_sha256() {
[ "$actual" = "$expected" ] || fail "$label sha256 mismatch: expected $expected, got $actual" [ "$actual" = "$expected" ] || fail "$label sha256 mismatch: expected $expected, got $actual"
} }
require_linux_debian12_amd64() { require_linux_debian13_amd64() {
[ "$(uname -s)" = "Linux" ] || fail "production builder supports only Linux Debian 12 amd64" [ "$(uname -s)" = "Linux" ] || fail "production builder supports only Linux Debian 13 amd64"
local arch local arch
arch="$(uname -m)" arch="$(uname -m)"
@@ -36,8 +36,8 @@ require_linux_debian12_amd64() {
[ -f /etc/os-release ] || fail "missing /etc/os-release" [ -f /etc/os-release ] || fail "missing /etc/os-release"
# shellcheck disable=SC1091 # shellcheck disable=SC1091
. /etc/os-release . /etc/os-release
[ "${ID:-}" = "debian" ] || fail "production builder supports only Debian 12, got: ${ID:-unknown}" [ "${ID:-}" = "debian" ] || fail "production builder supports only Debian 13, got: ${ID:-unknown}"
[ "${VERSION_ID:-}" = "12" ] || fail "production builder supports only Debian 12, got version: ${VERSION_ID:-unknown}" [ "${VERSION_ID:-}" = "13" ] || fail "production builder supports only Debian 13, got version: ${VERSION_ID:-unknown}"
} }
apt_install_missing() { apt_install_missing() {
tools/build/lib/package.sh
+3 -1
View File
@@ -81,10 +81,12 @@ write_metadata() {
printf 'name=HY2XS\n' printf 'name=HY2XS\n'
printf 'version=%s\n' "$version" printf 'version=%s\n' "$version"
printf 'build_id=%s\n' "$build_id" printf 'build_id=%s\n' "$build_id"
printf 'build_host_os=debian12\n' printf 'build_host_os=debian13\n'
printf 'build_host_arch=amd64\n' printf 'build_host_arch=amd64\n'
printf 'target_os=linux\n' printf 'target_os=linux\n'
printf 'target_arch=amd64\n' printf 'target_arch=amd64\n'
printf 'target_distro=debian\n'
printf 'target_version=13\n'
printf 'orchestrator_stack=Bun+TypeScript\n' printf 'orchestrator_stack=Bun+TypeScript\n'
printf 'go_version=%s\n' "$($GO_BIN version)" printf 'go_version=%s\n' "$($GO_BIN version)"
printf 'bun_version=%s\n' "$($BUN_BIN --version)" printf 'bun_version=%s\n' "$($BUN_BIN --version)"