build: закрепить новые инварианты приёмкой и документацией

verify_versions_contract получил сверку API namespace. Путь machine-auth
записывается в /etc/hysteria/config.yaml и в post-install.env, то есть по нему
Hysteria обращается к админке. Пока строка была продублирована в шаблонах,
smoke, тестах, приёмке и e2e, расхождение обнаруживалось только на живом
сервере. Теперь Go-константы, API_BASE фронтенда и оба шаблона сверяются
против значений, скомпилированных в оркестратор.

Приёмка проверяет, что:
  - fatal_pre_apply недостижим после записи install-state;
  - каждый ownership-флаг взводится раньше своего шага;
  - у read-only фазы нет универсального раннера, через который можно
    проскользнуть;
  - инвариант публичного endpoint живёт в preflight и не обращается к внешним
    сервисам определения IP;
  - purge-v0.sh и clean-host описывают одну границу;
  - секреты не попадают в персистентный файл экспорта;
  - импорт пиров валидируется так же строго, как их создание;
  - удалённые exportConfig/importConfig не вернулись.

Захардкоженная схема =2 в приёмке заменена на значение из versions.env: при
переходе на schema 3 пришлось бы помнить ещё и про эту строку.

Документация: контракт раннеров и ownership в 08, инвариант публичного
endpoint в 08/09/12/13 и README, сетевая идентичность панели и удалённые
export/import в 04, сценарии D1 (отказ сразу после PHASE 0) и D2 (устаревший
DNS после смены IPv4) в 11, версии package.json как не-версия продукта в 02.
This commit is contained in:
2026-08-27 20:50:03 +05:00
parent a88268b0cd
commit 086b5d6624
15 changed files with 740 additions and 37 deletions
+19 -1
View File
@@ -104,7 +104,10 @@ HYSTERIA_CHANNEL=stable
| `orchestrator/package.json``packageManager` | `bun@$BUN_VERSION` |
| `apps/frontend/package.json``packageManager` | `pnpm@$PNPM_VERSION` |
| `package/config/hy2xs.env` → схема | `HY2XS_CONFIG_SCHEMA_VERSION` |
| константы, **скомпилированные** в оркестратор | схема, release line, целевая платформа |
| константы, **скомпилированные** в оркестратор | схема, release line, целевая платформа, API namespace |
| `constant.AdminAPIBase` / `constant.HysteriaMachineAuthPath` (Go) | константы оркестратора |
| `API_BASE` фронтенда | `constant.AdminAPIBase` |
| шаблоны Hysteria и `post-install.env` | `HYSTERIA_MACHINE_AUTH_PATH` |
| `apps/go.mod` → директива `go` | `GO_VERSION` |
| `metadata/package.env` | версия, release line, схема, target |
| `hy2xs-admin version` (готовый бинарь) | `v$HY2XS_VERSION` |
@@ -113,6 +116,21 @@ HYSTERIA_CHANNEL=stable
`orchestrator/tools/print-contract.ts`: это доказывает, что в бинарь попало то
же значение.
API namespace попал в этот список не для красоты. Путь machine-auth
записывается в `/etc/hysteria/config.yaml` и в `post-install.env`, то есть по
нему Hysteria обращается к админке. Пока строка была продублирована в шаблонах,
smoke, тестах, приёмке и e2e, расхождение обнаруживалось только на живом
сервере.
### Версии в `package.json` — не версия продукта
`orchestrator/package.json` объявляет `version: 0.1.0`, а
`apps/frontend/package.json``version: 0.0.0`. Это placeholder'ы приватных
пакетов, которые никуда не публикуются; единственная версия продукта живёт в
`versions.env` (`HY2XS_VERSION`) и оттуда доезжает до `metadata/package.env`,
install-state и бинарника админки. Ни одно из этих двух чисел не участвует в
контракте версий и не должно восприниматься как release version.
Версия админки приходит в бинарь через ldflags:
```bash