86 lines
3.9 KiB
Markdown
86 lines
3.9 KiB
Markdown
# HY2XS
|
||
|
||
HY2XS — production installer/runtime-manager для развёртывания Hysteria2 + HY2XS admin на чистом Debian 12 amd64.
|
||
|
||
Состав baseline:
|
||
|
||
- production builder на Debian 12 amd64 создаёт один переносимый архив;
|
||
- install-only оркестратор на Bun + TypeScript поставляется на target как готовый compiled artifact;
|
||
- HY2XS admin поставляется в составе пакета как bundled fork;
|
||
- vanilla Hysteria2 скачивается с official upstream во время установки;
|
||
- runtime-конфиг управляется через `/etc/hy2xs/hy2xs.env` и команду `reconfigure`.
|
||
|
||
В baseline намеренно не входят target-side build, rollback/uninstall orchestration, Telegram bot delivery, port hopping и generic server-manager функции.
|
||
|
||
## Структура репозитория
|
||
|
||
- [`tools/build`](tools/build) — production builder и packaging pipeline.
|
||
- [`orchestrator`](orchestrator) — исходники install-only оркестратора на Bun + TypeScript.
|
||
- [`package`](package) — skeleton итогового install package: entrypoint, templates, systemd units, package docs.
|
||
- [`apps`](apps) — исходники HY2XS admin fork.
|
||
- [`docs`](docs) — архитектурная документация и acceptance.
|
||
- [`hy2xs_implementation_plan-no_git`](hy2xs_implementation_plan-no_git) — roadmap и task breakdown.
|
||
- [`dist`](dist) — итоговые install archives, создаются builder'ом и не хранятся в git.
|
||
|
||
## Сборка
|
||
|
||
Production-сборка выполняется только на Debian 12 amd64:
|
||
|
||
```sh
|
||
PACKAGE_VERSION=0.1.0 ./tools/build/build.sh
|
||
```
|
||
|
||
Builder сам проверяет ОС, архитектуру, структуру проекта, lock-файлы, версии Go/Bun/Node.js/pnpm и при необходимости скачивает локальный toolchain.
|
||
|
||
Ожидаемый результат:
|
||
|
||
```text
|
||
dist/hy2xs-install-0.1.0.tar.gz
|
||
```
|
||
|
||
На target server не должно быть `bun install`, `pnpm install`, TypeScript transpilation, frontend build или Go build.
|
||
|
||
Подробности сборки: [`tools/build/README.md`](tools/build/README.md).
|
||
|
||
## Публикация
|
||
|
||
Целевой репозиторий:
|
||
|
||
```text
|
||
https://git.ext.flamy.studio/flamy_dev/HY2XS_flamy.git
|
||
```
|
||
|
||
Публиковать изменения нужно только после прохождения baseline acceptance, сборки оркестратора и smoke checks итогового пакета.
|
||
|
||
## Установка и конфигурация
|
||
|
||
На чистом Debian 12 target нужно распаковать архив и запустить от root:
|
||
|
||
```sh
|
||
./install.sh --non-interactive
|
||
```
|
||
|
||
Опционально можно передать внешний source-config (не путь runtime-файла на target):
|
||
|
||
```sh
|
||
./install.sh --config /root/custom-hy2xs.env --non-interactive
|
||
```
|
||
|
||
`/etc/hy2xs/hy2xs.env` создаётся install-слоем автоматически и далее редактируется оператором перед `reconfigure`.
|
||
|
||
После установки применяются команды оркестратора:
|
||
|
||
```sh
|
||
hy2xs-orchestrator reconfigure --package-dir /opt/hy2xs-package --config /etc/hy2xs/hy2xs.env --dry-run
|
||
hy2xs-orchestrator reconfigure --package-dir /opt/hy2xs-package --config /etc/hy2xs/hy2xs.env --apply
|
||
```
|
||
|
||
Ключевые инварианты:
|
||
|
||
- только IPv4 (`0.0.0.0:<port>` для Hysteria, `127.0.0.1:<ui_port>` для UI по умолчанию);
|
||
- IPv6 явно out of scope;
|
||
- UI запускается не от root (`hy2xs-admin`);
|
||
- секреты и чувствительные конфиги: `0600`;
|
||
- snapshot deploy-фактов: `/etc/hysteria/post-install.env`;
|
||
- editable runtime layer: `/etc/hy2xs/hy2xs.env`.
|