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 с разбором каждого исправленного дефекта.
This commit is contained in:
2026-08-27 12:16:38 +05:00
parent 42db78c6a0
commit 3a4ce9c751
12 changed files with 1117 additions and 99 deletions
+10 -1
View File
@@ -11,6 +11,8 @@
- 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**
## Главная архитектурная схема
@@ -38,7 +40,13 @@
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.
7. Выдача доступа пользователям, Telegram-бот, billing, backend профилей и похожие контуры **не входят** в этот baseline.
Rollback опирается на то, что операция реально успела применить: сервисы,
которые она не разворачивала, не останавливаются никогда.
7. Установка двухфазная: **PHASE 0 — read only**, **PHASE 1 — mutation**.
До успешного clean-host preflight на сервере не изменяется ни один
persistent path. Очистка предыдущей установки — отдельная явная операция
оператора, см. [14-legacy-cleanup.md](14-legacy-cleanup.md).
8. Выдача доступа пользователям, Telegram-бот, billing, backend профилей и похожие контуры **не входят** в этот baseline.
## Состав документов
@@ -55,6 +63,7 @@
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).