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 — production installer/runtime-manager для развёртывания Hysteria2 + HY2XS admin на чистом Debian 12 amd64.
HY2XS — production installer/runtime-manager для развёртывания Hysteria2 + HY2XS admin на чистом Debian 13 amd64.
Состав baseline:
- production builder на Debian 12 amd64 создаёт один переносимый архив;
- production builder на Debian 13 amd64 создаёт один переносимый архив;
- install-only оркестратор на Bun + TypeScript поставляется на target как готовый compiled artifact;
- HY2XS admin поставляется в составе пакета как bundled fork;
- 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
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-хоста:
docs/01-architecture-baseline.md
+3 -3
View File
@@ -21,7 +21,7 @@
Builder 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
6. systemd + nftables
7. post-install env
8. install-only flow под чистый Debian 12
8. install-only flow под чистый Debian 13
## Что не входит в baseline
@@ -122,7 +122,7 @@ Telegram-бот, backend выдачи ключей, remote profile publishing, b
1. На локальной машине собирается install package.
2. В пакет уже встроены наш HY2XS admin и install-артефакт оркестратора.
3. Пакет переносится на чистый Debian 12.
3. Пакет переносится на чистый Debian 13.
4. На сервере запускается только install-only orchestration.
5. Сервер скачивает свежую Hysteria2 из official upstream.
6. Сервер разворачивает bundled UI из пакета.
docs/02-build-layer-and-package.md
+5 -5
View File
@@ -19,12 +19,12 @@
## Где работает builder
Production builder работает на отдельном build host:
- Debian 12
- Debian 13
- amd64 / x86_64
- bash
- доступ к интернету для 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.
@@ -104,7 +104,7 @@ project/
## Production builder bootstrap
`tools/build/build.sh` должен быть самодостаточным для Debian 12 amd64:
`tools/build/build.sh` должен быть самодостаточным для Debian 13 amd64:
1. Проверяет ОС и архитектуру.
2. Проверяет структуру репозитория и lock-файлы.
@@ -132,8 +132,8 @@ project/
Система считается правильной, если:
1. builder запускается на Debian 12 amd64 build host, не как target-side build step
2. пакет можно перенести на чистый Debian 12
1. builder запускается на Debian 13 amd64 build host, не как target-side build step
2. пакет можно перенести на чистый Debian 13
3. на сервере нет отдельного build step
4. bundled UI уже находится внутри пакета
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
- сетевой фильтр: nftables
- архитектура 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
- один сервер
- одну baseline-схему
@@ -74,7 +74,7 @@
## Что делает оркестратор по шагам
1. Проверяет, что ОС — Debian 12.
1. Проверяет, что ОС — Debian 13.
2. Проверяет базовые зависимости и install context.
3. Создаёт каталоги установки.
4. Разворачивает bundled HY2XS admin.
docs/11-testing-and-acceptance.md
+4 -4
View File
@@ -7,7 +7,7 @@
## A. Builder layer tests
### Проверяем
1. builder запускается на Debian 12 amd64 build host
1. builder запускается на Debian 13 amd64 build host
2. итоговый пакет собирается без target-side шагов
3. bundled HY2XS admin реально входит в пакет
4. package metadata / build id присутствуют
@@ -19,7 +19,7 @@
## B. Target install tests
### На чистом Debian 12 проверяем
### На чистом Debian 13 проверяем
1. пакет запускается без ручной сборки на сервере
2. Hysteria2 скачивается с official upstream
3. bundled HY2XS admin раскладывается локально из пакета
@@ -58,7 +58,7 @@
## D. Negative tests
1. не Debian 12
1. не Debian 13
2. порт уже занят
3. старое конфликтующее состояние уже существует
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
3. Hysteria2 получена из official upstream
4. UI поставлен из bundled fork
docs/13-production-runbook.md
+1 -1
View File
@@ -2,7 +2,7 @@
## 1. Supported target
- clean Debian 12 amd64
- clean Debian 13 amd64
- single host install profile
- IPv4-only runtime model
docs/README.md
+4 -4
View File
@@ -4,7 +4,7 @@
- серверный транспорт: **ванильная Hysteria2**
- UI: **наш форк H UI / HY2XS admin**, поставляется **вместе с проектом**
- target OS: **только чистый Debian 12**
- target OS: **только чистый Debian 13**
- оркестратор: **install-only**, только первичная установка и базовая настройка
- стек оркестратора: **Bun + TypeScript**
- 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-файлы и примеры конфигов.
2. **Runtime / target layer** — работает **на чистом Debian 12**.
2. **Runtime / target layer** — работает **на чистом Debian 13**.
Здесь нет сборщика. Здесь запускается только итоговый install package / orchestrator, который:
- ставит системные зависимости
- разворачивает **наш встроенный UI**
@@ -72,4 +72,4 @@
Правильная 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-развёртывания.
Итоговый архив создаётся в [`dist`](../../dist) и предназначен для установки на чистый Debian 12 amd64 без сборки на целевом сервере.
Итоговый архив создаётся в [`dist`](../../dist) и предназначен для установки на чистый Debian 13 amd64 без сборки на целевом сервере.
## Поддерживаемая среда сборки
Builder поддерживает только:
- Debian 12;
- Debian 13;
- amd64 / x86_64;
- bash;
- доступ к интернету для установки build-зависимостей и toolchain.
Windows/macOS не являются production build host. На Windows можно править исходники, но финальную сборку нужно выполнять на Debian 12 amd64.
Windows/macOS не являются production build host. На Windows можно править исходники, но финальную сборку нужно выполнять на Debian 13 amd64.
## Что builder делает сам
@@ -77,13 +77,13 @@ Builder ставит управляемый toolchain в [`.toolchain`](../../.t
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.
3. Удалите [`.toolchain`](../../.toolchain) и повторите запуск, если toolchain скачался повреждённым.
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() {
cd "$ROOT_DIR"
require_linux_debian12_amd64
require_linux_debian13_amd64
require_repo_layout
ensure_build_dependencies
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"
}
require_linux_debian12_amd64() {
[ "$(uname -s)" = "Linux" ] || fail "production builder supports only Linux Debian 12 amd64"
require_linux_debian13_amd64() {
[ "$(uname -s)" = "Linux" ] || fail "production builder supports only Linux Debian 13 amd64"
local arch
arch="$(uname -m)"
@@ -36,8 +36,8 @@ require_linux_debian12_amd64() {
[ -f /etc/os-release ] || fail "missing /etc/os-release"
# shellcheck disable=SC1091
. /etc/os-release
[ "${ID:-}" = "debian" ] || fail "production builder supports only Debian 12, got: ${ID:-unknown}"
[ "${VERSION_ID:-}" = "12" ] || fail "production builder supports only Debian 12, got version: ${VERSION_ID:-unknown}"
[ "${ID:-}" = "debian" ] || fail "production builder supports only Debian 13, got: ${ID:-unknown}"
[ "${VERSION_ID:-}" = "13" ] || fail "production builder supports only Debian 13, got version: ${VERSION_ID:-unknown}"
}
apt_install_missing() {
tools/build/lib/package.sh
+3 -1
View File
@@ -81,10 +81,12 @@ write_metadata() {
printf 'name=HY2XS\n'
printf 'version=%s\n' "$version"
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 'target_os=linux\n'
printf 'target_arch=amd64\n'
printf 'target_distro=debian\n'
printf 'target_version=13\n'
printf 'orchestrator_stack=Bun+TypeScript\n'
printf 'go_version=%s\n' "$($GO_BIN version)"
printf 'bun_version=%s\n' "$($BUN_BIN --version)"