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 расширен новыми инвариантами
81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
# HY2XS
|
|
|
|
HY2XS — production installer/runtime-manager для развёртывания Hysteria2 + HY2XS admin на чистом Debian 13 amd64.
|
|
|
|
Состав baseline:
|
|
|
|
- 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);
|
|
- runtime-конфиг управляется через `/etc/hy2xs/hy2xs.env` и команду `reconfigure`.
|
|
|
|
В baseline намеренно не входят target-side build, standalone rollback/update/uninstall subcommands, Telegram bot delivery, port hopping и generic server-manager функции.
|
|
|
|
При этом install/reconfigure содержат bounded rollback для failure-сценариев firewall/systemd/config/smoke.
|
|
|
|
## Структура репозитория
|
|
|
|
- [`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.
|
|
- [`dist`](dist) — итоговые install archives, создаются builder'ом и не хранятся в git.
|
|
|
|
## Публикация
|
|
|
|
Целевой репозиторий:
|
|
|
|
```text
|
|
https://git.ext.flamy.studio/flamy_dev/HY2XS_flamy.git
|
|
```
|
|
|
|
Публиковать изменения нужно только после прохождения baseline acceptance, сборки оркестратора и smoke checks итогового пакета.
|
|
|
|
## Установка и конфигурация
|
|
|
|
На чистом Debian 13 target нужно распаковать архив и запустить от root:
|
|
|
|
Обязательные системные зависимости target-хоста:
|
|
|
|
```sh
|
|
apt-get update
|
|
apt-get install -y sudo ca-certificates curl iproute2 tar openssl nftables systemd
|
|
```
|
|
|
|
`sudo` используется для smoke-проверок прав доступа от имени runtime-пользователей и автоматически устанавливается на шаге deps в install-flow.
|
|
|
|
Предварительная ручная установка `sudo` перед `./install.sh` не требуется: preflight допускает его отсутствие на clean-host и install deps bootstrap'ит его до smoke-проверок.
|
|
|
|
```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 /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env --dry-run
|
|
hy2xs-orchestrator reconfigure --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env --apply
|
|
hy2xs-orchestrator doctor --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env
|
|
```
|
|
|
|
`HY2XS_ADMIN_INITIAL_PASSWORD` и `HY2XS_ADMIN_CON_PASS` — install-only bootstrap-поля. Их изменение в `/etc/hy2xs/hy2xs.env` после установки не ротирует существующие credentials в SQLite автоматически.
|
|
|
|
Ключевые инварианты:
|
|
|
|
- только 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`.
|