founder
330a63b050
Верхнеуровневый откат стал неотменяемым в прошлом проходе, и на этом фоне
проявилось, что его substrate этой надёжности не соответствует: откат
гарантированно запускался, но отдельные его шаги могли молча не выполнить
восстановление, отчитаться успехом и уничтожить резервную копию.
1. Данные для отката уничтожались ДО фиксации успеха (commit ordering).
cancelFirewallRollback снимала таймер автоотката И удаляла резервные копии
firewall, а вызывалась до долговечной записи phase=installed. Отказ этой
записи (ENOSPC/EIO/read-only ФС) приводил в обработчик ошибки, обязательный
откат честно запускался и сообщал "no HY2XS rollback markers found":
откатывать было нечем. Причём отказ записи маркера — ровно тот сценарий,
который прошлый проход специально сделал безопасным.
Разделено на disarmFirewallRollback (снять таймер, копии оставить) и
cleanupFirewallRollback (удалить копии). Порядок в install и reconfigure:
smoke_ok -> disarm -> durable installed -> cleanup best-effort.
2. Резервные копии снимались без доказательства.
И firewall, и reconfigure копировали как `cp ... || true`: отказ
игнорировался, операция шла менять систему без копии, на которую
рассчитывает откат. У firewall маркер prepared («данные для отката
существуют») выставлялся вообще ДО копирования. Копирование строгое, факт
создания проверяется, маркер ставится после.
3. Копии reconfigure смешивались между операциями.
Общий набор *.bak в /etc/hy2xs/backups не был привязан к проходу. Если у
операции B копирование падало, B всё равно менял систему, а его откат
восстанавливал файлы операции A — сервер возвращался в более старое
состояние и это выглядело успешным откатом. Копия стала операционной:
/etc/hy2xs/backups/<op-id>/ с манифестом, где отсутствие файла записано
явно ("present": false), а не выведено из неудачи cp. Разбор строгий,
включая проверку opId.
4. Ошибка восстановления скрывалась, и после неё копии удалялись.
rollbackFirewallNow выполняла cp и nft -f с `|| true`, затем безусловно
удаляла /run/hy2xs/rollback/<op>. Худшая комбинация: неудача не видна,
стадия успешна, данные для ручной починки уничтожены. Теперь копии
удаляются только после подтверждённого успеха, иначе сохраняются с
сообщением manual recovery data preserved at ...
5. Команды отката глушили собственный код возврата.
До стадийного раннера `|| true` был единственной защитой от обрыва цепочки;
после его появления стал маскировкой — стадия не могла сообщить, что
ничего не сделала. Убран; rollbackCurrentState разбита на семь независимых
стадий.
6. Долговечность записи каталога маркера.
writeTextAtomic синхронизирует файл и его каталог, но при первой установке
/var/lib/hy2xs создаётся тут же, и запись "hy2xs" в /var/lib оставалась
несинхронизированной. ensureDir сообщает о фактическом создании и
синхронизирует родителя только тогда.
Отдельно про doctor. Утверждение аудита, что doctor вызывает
UpdatePeerLastConnectionAt через успешную machine-auth, кодом не
подтверждается: проба с действующим паролем ограничена `context.mode ===
"install"`, а doctor работает в режиме reconfigure. Инвариант, однако, ничем не
охранялся — добавлены тест и приёмка. Документация уточнена: guard действует
внутри процесса, а границу «что doctor шлёт по сети» держит состав проб;
единственный остающийся след — записи в журнале админки, и это сказано прямо.
Тесты: backup-integrity.test.ts (манифест, строгий разбор, копия до мутации,
сохранение копий при неудачном восстановлении), commit-ordering.test.ts
(disarm/cleanup разделены, порядок фиксации в обеих командах). Три теста,
закреплявших прежний инвариант «каждая команда отката несёт || true»,
переписаны на обратный: команды обязаны сообщать о своих отказах.
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. У мутирующей фазы ровно один владелец — оркестратор:
install.shпроверяет и передаёт управление, не изменяя ничего сам. Очистка предыдущей установки — отдельная явная операция оператора, см. 14-legacy-cleanup.md. - Выдача доступа пользователям, Telegram-бот, billing, backend профилей и похожие контуры не входят в этот baseline.
Состав документов
- 01-architecture-baseline.md
- 02-build-layer-and-package.md
- 03-server-hysteria2.md
- 04-admin-panel.md
- 05-client-and-access-scope.md
- 06-speed-limits-and-congestion.md
- 07-systemd-and-firewall.md
- 08-orchestrator-spec.md
- 09-post-install-env.md
- 10-access-layer-out-of-scope.md
- 11-testing-and-acceptance.md
- 12-operations-and-troubleshooting.md
- 13-production-runbook.md
- 14-legacy-cleanup.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 и подготавливает рабочее серверное окружение.