founder
cb20d8d28f
Отзыв секрета не сходился: `auth_id` при смене секрета оставался прежним, поэтому сессия, установленная по отозванным учётным данным, была неотличима от законной, и цикл учёта не имел признака, по которому её следовало завершить. У состояния есть путь без единой неудачи — Hysteria регистрирует соединение в Traffic Stats API только после возврата backend-auth, поэтому успешный /kick может пройти мимо. Новое поколение credentials получает новый auth_id, kick идёт по старому, пережившая сессия становится orphan. Адрес Traffic Stats API имел два контракта: оркестратор принимал любой IPv4, админка всегда шла на loopback. Валидная по всем гейтам конфигурация выключала лимит устройств, учёт трафика и принудительное отключение разом. Адрес зафиксирован, а расхождение файла с ним админка называет. Состояние службы стало трёхзначным: util.Exec выбрасывал вывод systemctl при ненулевом коде, поэтому «остановлена» и «спросить не удалось» приходили одним значением, а доступность Traffic Stats API выводилась из него же. Журнал Hysteria разбирается в фактическом формате upstream (time — дробное число), страница конфигурации показывает файл вместо дефолтов UI и не возит секреты в браузер, санитайзер выгрузки следует по YAML-якорям. Разбор: docs/acceptance/2026-09-02-v1.0.0-rc4-preflight-findings.md
116 lines
8.1 KiB
Markdown
116 lines
8.1 KiB
Markdown
# HY2XS baseline docs
|
||
|
||
Этот набор документов фиксирует актуальную baseline-модель HY2XS под следующие ограничения:
|
||
|
||
- серверный транспорт: **ванильная Hysteria2**
|
||
- UI: **HY2XS admin**, штатный компонент проекта, поставляется **вместе с пакетом**
|
||
- target OS: **только чистый Debian 13**
|
||
- оркестратор: **install-only**, только первичная установка и базовая настройка
|
||
- стек оркестратора: **Bun + TypeScript**
|
||
- target-side build: **запрещён**
|
||
- standalone update / rollback / uninstall subcommands: **вне scope**
|
||
- сборка и упаковка: **отдельный локальный build layer**
|
||
- post-install state: **`/etc/hysteria/post-install.env`**
|
||
- установка: **только на чистый хост**, миграция с 0.x не поддерживается
|
||
- контракт версий продукта/платформы/toolchain: **корневой `versions.env`**
|
||
- клиентский delivery/access layer: **вне baseline этого пакета docs**
|
||
|
||
## Главная архитектурная схема
|
||
|
||
В этой редакции зафиксированы два слоя:
|
||
|
||
1. **Builder layer** — работает на отдельном **Debian 13 amd64 build host**.
|
||
Он собирает итоговый пакет, собирает **HY2XS admin**, компилирует **Bun/TypeScript оркестратор** в install-артефакт, упаковывает шаблоны, unit-файлы и примеры конфигов.
|
||
|
||
2. **Runtime / target layer** — работает **на чистом Debian 13**.
|
||
Здесь нет сборщика. Здесь запускается только итоговый install package / orchestrator, который:
|
||
- ставит системные зависимости
|
||
- разворачивает **встроенный HY2XS admin**
|
||
- забирает **закреплённую в пакете Hysteria2 из официального upstream** и сверяет её по SHA-256 и версии
|
||
- создаёт конфиги, systemd unit-файлы и `post-install.env`
|
||
- выполняет базовую настройку сервера
|
||
|
||
Версия Hysteria2 выбирается **на builder layer**: последняя стабильная разрешается при сборке и замораживается в metadata пакета. Target layer никогда не обращается к moving `latest`.
|
||
|
||
## Базовые правила
|
||
|
||
1. Hysteria2 не вендорится и не собирается как часть HY2XS.
|
||
2. HY2XS admin — штатный компонент проекта и поставляется вместе с пакетом.
|
||
3. Оркестратор пишется на **Bun + TypeScript**.
|
||
4. На target нет `npm` / `pnpm` / `yarn` / `bun install` / transpile step.
|
||
5. На target нет standalone логики update / rollback / uninstall.
|
||
6. В install/reconfigure есть bounded rollback для failure-сценариев firewall/systemd/config/smoke.
|
||
Rollback опирается на то, что операция реально успела применить: сервисы,
|
||
которые она не разворачивала, не останавливаются никогда.
|
||
7. Установка двухфазная: **PHASE 0 — read only**, **PHASE 1 — mutation**.
|
||
До успешного clean-host preflight на сервере не изменяется ни один
|
||
persistent path. У мутирующей фазы ровно один владелец — оркестратор:
|
||
`install.sh` проверяет и передаёт управление, не изменяя ничего сам.
|
||
Очистка предыдущей установки — отдельная явная операция оператора,
|
||
см. [operations/14-legacy-cleanup.md](operations/14-legacy-cleanup.md).
|
||
8. Выдача доступа пользователям, Telegram-бот, billing, backend профилей и похожие контуры **не входят** в этот baseline.
|
||
|
||
## Состав документов
|
||
|
||
Документы разложены по слою, к которому относятся. Двузначный префикс в имени —
|
||
стабильный идентификатор документа: под ним на него ссылаются CHANGELOG,
|
||
релизные гейты и сообщения оркестратора, поэтому при переносе в каталоги он
|
||
сохранён.
|
||
|
||
### Архитектура и рамки
|
||
|
||
- [architecture/01-architecture-baseline.md](architecture/01-architecture-baseline.md) — baseline-модель двух слоёв
|
||
- [architecture/03-server-hysteria2.md](architecture/03-server-hysteria2.md) — серверный транспорт
|
||
- [architecture/05-client-and-access-scope.md](architecture/05-client-and-access-scope.md) — граница клиента
|
||
- [architecture/06-speed-limits-and-congestion.md](architecture/06-speed-limits-and-congestion.md) — ограничения скорости
|
||
- [architecture/10-access-layer-out-of-scope.md](architecture/10-access-layer-out-of-scope.md) — что вне baseline
|
||
|
||
### Сборка
|
||
|
||
- [build/02-build-layer-and-package.md](build/02-build-layer-and-package.md) — builder layer, состав пакета, требования к сборочной машине
|
||
|
||
### Runtime на target
|
||
|
||
- [runtime/08-orchestrator-spec.md](runtime/08-orchestrator-spec.md) — спецификация оркестратора
|
||
- [runtime/07-systemd-and-firewall.md](runtime/07-systemd-and-firewall.md) — systemd и nftables
|
||
- [runtime/09-post-install-env.md](runtime/09-post-install-env.md) — post-install состояние
|
||
|
||
### Панель
|
||
|
||
- [admin/04-admin-panel.md](admin/04-admin-panel.md) — HY2XS admin
|
||
- [admin/15-ui-contracts.md](admin/15-ui-contracts.md) — контракты панели: иконки, структурированные ошибки, необязательные поля, отсутствие выдуманного состояния, атрибуция
|
||
|
||
### Эксплуатация
|
||
|
||
- [operations/13-production-runbook.md](operations/13-production-runbook.md) — production runbook
|
||
- [operations/12-operations-and-troubleshooting.md](operations/12-operations-and-troubleshooting.md) — операции и разбор отказов
|
||
- [operations/14-legacy-cleanup.md](operations/14-legacy-cleanup.md) — очистка установки предыдущего поколения
|
||
|
||
### Проверки
|
||
|
||
- [testing/](testing/README.md) — набор проверок по слоям (бывший `11-testing-and-acceptance.md`)
|
||
- [acceptance/](acceptance/README.md) — отчёты о фактических прогонах приёмки
|
||
|
||
История изменений проекта — в [CHANGELOG.md](../CHANGELOG.md).
|
||
|
||
## Жёсткие рамки baseline
|
||
|
||
Не делаем:
|
||
- upgrade manager
|
||
- rollback manager
|
||
- uninstall
|
||
- reconcile engine
|
||
- target-side build pipeline
|
||
- Docker baseline
|
||
- multi-node
|
||
- port hopping
|
||
- Telegram-бот
|
||
- backend выдачи remote profiles
|
||
- «умную» миграцию сломанных старых инсталляций
|
||
|
||
## Одной фразой
|
||
|
||
Правильная baseline-модель теперь такая:
|
||
|
||
**Локальный builder разрешает последнюю стабильную Hysteria2, проверяет её на совместимость с конфигом HY2XS и собирает install package с HY2XS admin и Bun/TypeScript оркестратором; серверный install-only orchestrator ставит этот пакет на чистый Debian 13, скачивает ровно закреплённую Hysteria2, разворачивает HY2XS admin, создаёт systemd + nftables + post-install env и подготавливает рабочее серверное окружение.**
|