Files

T

founder 3a4ce9c751 docs: clean-install-only, versions.env и очистка предыдущего поколения

Новый docs/14-legacy-cleanup.md: как выглядит отказ установщика, полный
список маркеров чужой установки, что сохранить перед очисткой, работа
purge-v0.sh, ручная процедура и отдельно - случай незавершённой
установки текущего поколения, где нужен repair, а не очистка.

Обновлено под фактическое поведение:

- README и package/docs: установка описана как две фазы, PHASE 0 ничего
  не меняет; добавлен troubleshooting по отказу clean-host; версии
  toolchain больше не передаются через окружение;
- 02-build-layer: раздел про versions.env (что в нём есть и чего нет и
  почему), verify_versions_contract, проверка происхождения артефакта
  по upstream hashes.txt;
- 08-orchestrator-spec: двухфазный контракт, read-only guard,
  идентификация поколения в install-state, ownership-aware rollback,
  расширенная семантическая проверка конфига, структурная редакция;
- 04-admin-panel: таблица удалённых маршрутов и почему они удалены, а
  не оставлены заглушками; сужена формулировка гарантии санитайза;
- 11-testing: новые unit-наборы, полный список инвариантов конфига,
  раздел про одну реализацию URI вместо двух, сценарий проверки
  границы установки на живом сервере;
- 12-operations и 13-runbook: диагностика отказов по поколению,
  поведение diagnostics-бандла;
- tools/build/README: контракт версий, обе суммы Bun, hashes.txt.

CHANGELOG: раздел Unreleased с разбором каждого исправленного дефекта.

2026-08-27 12:16:38 +05:00

6.1 KiB

Raw Blame History

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

Главная архитектурная схема

В этой редакции зафиксированы два слоя:

Builder layer — работает на отдельном Debian 13 amd64 build host. Он собирает итоговый пакет, собирает HY2XS admin, компилирует Bun/TypeScript оркестратор в install-артефакт, упаковывает шаблоны, unit-файлы и примеры конфигов.
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.

Базовые правила

Hysteria2 не вендорится и не собирается как часть HY2XS.
HY2XS admin — штатный компонент проекта и поставляется вместе с пакетом.
Оркестратор пишется на Bun + TypeScript.
На target нет npm / pnpm / yarn / bun install / transpile step.
На target нет standalone логики update / rollback / uninstall.
В install/reconfigure есть bounded rollback для failure-сценариев firewall/systemd/config/smoke. Rollback опирается на то, что операция реально успела применить: сервисы, которые она не разворачивала, не останавливаются никогда.
Установка двухфазная: PHASE 0 — read only, PHASE 1 — mutation. До успешного clean-host preflight на сервере не изменяется ни один persistent path. Очистка предыдущей установки — отдельная явная операция оператора, см. 14-legacy-cleanup.md.
Выдача доступа пользователям, Telegram-бот, billing, backend профилей и похожие контуры не входят в этот baseline.

Состав документов

История изменений проекта — в 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 и подготавливает рабочее серверное окружение.

6.1 KiB Raw Blame History Unescape Escape