founder
672d455467
Hardening-проход перед первой сборкой на Debian. Три из найденного не воспроизводились ни на одном dry-run и проявились бы только на живом сервере. Установка * preflight внутри install вызывался дважды и оба раза проверял clean-host. Ко второму вызову на диске лежал собственный /var/lib/hy2xs/install-state.json, записанный после первого preflight, и опознавался как маркер посторонней установки: КАЖДАЯ чистая установка падала сразу после apt-get с fatal_post_apply и оставляла сервер наполовину настроенным. Чистота хоста — условие входа в операцию, возможности платформы проверяются уже внутри PHASE 1, поэтому checkCleanHost стал отдельным параметром без умолчания. * PHASE 1 начиналась в install.sh: shell сам создавал /usr/local/lib/hy2xs, ставил бинарник, вешал symlink и копировал runtime-пакет, и только потом запускал оркестратор с его собственным preflight. Отказ того preflight объявлялся fatal_pre_apply — «на сервере ничего не изменено» — при уже созданном каталоге оркестратора. Отследить владение мутацией невозможно, пока мутируют двое: install.sh больше не изменяет ничего, раскладку выполняет steps/bootstrap.ts под ownership.bootstrapTouched, пути попали в owned_paths. Как следствие удалено деление clean-host на фазы. * diagnosticsCollect стояла перед rollback обычным await в install и в reconfigure. На заполненном диске она падает сама и отменяла откат целиком. Диагностика — best effort, откат — обязателен. * reconfigure/repair выбирали записываемую фазу отказа регулярным выражением по тексту ошибки. Переведено на ownership-флаги. Секреты * Журнал админки писал RequestURI, то есть путь вместе с query. Hysteria обращается к /internal/hysteria/auth?access_token=<секрет> при каждом подключении пира, поэтому действующий machine token оседал открытым текстом в hy2xs-admin.log, который отдаётся через ExportLog и попадает в diagnostics-бандл. Логируется путь; значения query не пишутся, имена — пишутся. Канала было два: gin.Default() печатает path?query в stdout, оттуда в journald и в тот же бандл, — панель переведена на gin.New() + Recovery(). Журналы внутри бандла и журнал Hysteria из ExportLog теперь проходят санитайз. Сравнение токена — constant time. * Config API позволял прочитать и подменить ключи приложения: getConfig и listConfig принимали произвольный ключ, а проверка записи была denylist'ом из трёх ключей оркестратора. Запрос ?key=PEER_SECRET_ENCRYPTION_KEY отдавал master-key шифрования секретов пиров. Доступ переведён на allowlist, маршрут getConfig удалён целиком — потребителей у него не было ни одного. Пиры * Импорт применялся по одной записи вне транзакции, вопреки собственному контракту. Валидация не знает, что уже лежит в базе: cross-conflict по UNIQUE(name) оставлял часть файла применённой. Применение выполняется одной транзакцией, криптоматериал считается до её открытия. * Файл импорта мог содержать хвостовой JSON-документ, который молча не применялся. После разбора проверяется io.EOF. * Экспорт разделён на «Экспорт настроек» и «Резервная копия» с секретами и подтверждением: обычный экспорт выдаёт пирам новые секреты при импорте, и прежние клиентские ссылки после переноса переставали работать. Сборка * Два stale-грепа в приёмке роняли build.sh в самом конце, внутри verify_archive. Первый искал в smoke.ts исчезнувший литерал URL, второй совпадал с router_test.go, который перечисляет удалённые маршруты, потому что проверяет их отсутствие: добавление регрессионного теста ломало сборку. * verify_archive требовал наличия мутирующей строки в install.sh. Инвариант перевёрнут: их не должно быть ни одной. Очистка * Удалены entity.LegacyAccount, миграции 002/003 и мёртвые хелперы listSQLMigrationFiles и envInt: v1 не мигрирует базу 0.x ни при каком сценарии. Номера оставшихся миграций сохранены. H UI-словарь убран из обычных доков, в docs/14 он остаётся — там это имена объектов для удаления. * Список непубличных IPv4 приведён к IANA Special-Purpose Address Registry: 203.0.113.5 из RFC-примеров считался публичным адресом сервера. Отказ резолвера отделён от отсутствия A-записи. Проверено: bun test 233, go test 71, tsc/vue-tsc, bash -n 11 скриптов, приёмка прогнана против дерева.
92 lines
6.3 KiB
Markdown
92 lines
6.3 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` проверяет и передаёт управление, не изменяя ничего сам.
|
||
Очистка предыдущей установки — отдельная явная операция оператора,
|
||
см. [14-legacy-cleanup.md](14-legacy-cleanup.md).
|
||
8. Выдача доступа пользователям, Telegram-бот, billing, backend профилей и похожие контуры **не входят** в этот baseline.
|
||
|
||
## Состав документов
|
||
|
||
1. [01-architecture-baseline.md](01-architecture-baseline.md)
|
||
2. [02-build-layer-and-package.md](02-build-layer-and-package.md)
|
||
3. [03-server-hysteria2.md](03-server-hysteria2.md)
|
||
4. [04-admin-panel.md](04-admin-panel.md)
|
||
5. [05-client-and-access-scope.md](05-client-and-access-scope.md)
|
||
6. [06-speed-limits-and-congestion.md](06-speed-limits-and-congestion.md)
|
||
7. [07-systemd-and-firewall.md](07-systemd-and-firewall.md)
|
||
8. [08-orchestrator-spec.md](08-orchestrator-spec.md)
|
||
9. [09-post-install-env.md](09-post-install-env.md)
|
||
10. [10-access-layer-out-of-scope.md](10-access-layer-out-of-scope.md)
|
||
11. [11-testing-and-acceptance.md](11-testing-and-acceptance.md)
|
||
12. [12-operations-and-troubleshooting.md](12-operations-and-troubleshooting.md)
|
||
13. [13-production-runbook.md](13-production-runbook.md)
|
||
14. [14-legacy-cleanup.md](14-legacy-cleanup.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 и подготавливает рабочее серверное окружение.**
|