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:
+52
-4
@@ -79,11 +79,28 @@ HY2XS admin работает как надстройка над Hysteria YAML/AP
|
||||
- `access_token` в auth-URL и учётные данные, встроенные в URL;
|
||||
- `auth.password`, `auth.userpass`;
|
||||
- учётные данные ACME DNS-провайдера;
|
||||
- любые **неизвестные** поля, имя которых содержит `password`, `secret`, `token` или `credential`.
|
||||
- **неизвестные** поля с секретоподобным именем: `password`, `passwd`,
|
||||
`passphrase`, `secret`, `token`, `credential`, `apiKey` / `api_key`,
|
||||
`privateKey` / `private_key`, `accessKey`, `secretKey`, `authorization`,
|
||||
`cookie`, `bearer`, `signature`.
|
||||
|
||||
Последний пункт — обратная сторона сохранения неизвестных полей: новое upstream-поле с секретом вырезается ещё до того, как HY2XS про него узнает.
|
||||
Последний пункт — обратная сторона сохранения неизвестных полей: новое
|
||||
upstream-поле с секретом вырезается ещё до того, как HY2XS про него узнает.
|
||||
|
||||
Пути к файлам (`tls.cert`, `tls.key`, `ech.keyPath`, `tls.clientCA`) секретами не считаются и остаются читаемыми — они нужны для диагностики.
|
||||
### Как формулируется гарантия
|
||||
|
||||
Точная формулировка:
|
||||
|
||||
> вырезаются известные секреты и неизвестные поля с секретоподобным именем.
|
||||
|
||||
Не «любой будущий секрет будет автоматически удалён». Обобщённый sanitizer
|
||||
работает по именам полей и не может предугадать произвольное имя, которое
|
||||
upstream выберет для нового секрета. Список маркеров синхронизирован с
|
||||
`orchestrator/src/lib/redaction.ts`; при появлении нового поля его нужно
|
||||
добавить в оба места.
|
||||
|
||||
Пути к файлам (`tls.cert`, `tls.key`, `ech.keyPath`, `tls.clientCA`) секретами
|
||||
не считаются и остаются читаемыми — они нужны для диагностики.
|
||||
|
||||
## Модель современной схемы Hysteria
|
||||
|
||||
@@ -118,10 +135,41 @@ HY2XS admin работает как надстройка над Hysteria YAML/AP
|
||||
- Hysteria2 запускается отдельным `hysteria-server.service`;
|
||||
- HY2XS admin работает как operator UI и HTTP auth/traffic layer;
|
||||
- HY2XS admin не запускается от root;
|
||||
- смена версии Hysteria2 через UI отключена в baseline;
|
||||
- смена версии Hysteria2 через UI **отсутствует как API**;
|
||||
- список upstream releases не является частью operator UI baseline;
|
||||
- port hopping не является частью production path.
|
||||
|
||||
### Удалённые операции: почему не заглушки
|
||||
|
||||
Маршруты, которые продукт принципиально не поддерживает, **удалены**, а не
|
||||
оставлены отвечающими «feature disabled»:
|
||||
|
||||
| Удалённый маршрут | Кто владеет операцией |
|
||||
| --- | --- |
|
||||
| `POST /hysteria2ChangeVersion` | install-оркестратор |
|
||||
| `GET /listRelease` | build layer |
|
||||
| `POST /config/updateHysteria2Config` | install-оркестратор |
|
||||
| `POST /config/importHysteria2Config` | install-оркестратор |
|
||||
| `POST /config/restartServer` | systemd |
|
||||
| `POST /config/uploadCertFile` | оператор + оркестратор |
|
||||
| `GET /config/hysteria2AcmePath` | не имел потребителя |
|
||||
|
||||
Причины две.
|
||||
|
||||
Во-первых, API-контракт не должен даже обещать updater, которого у продукта
|
||||
нет: маршрут, всегда возвращающий отказ, вводит в заблуждение.
|
||||
|
||||
Во-вторых, это лишняя attack surface и технический мусор от прежней
|
||||
архитектуры.
|
||||
|
||||
Вместе с маршрутами удалены соответствующие клиентские функции фронтенда,
|
||||
кнопки и строки i18n. Кнопка, которая гарантированно возвращает ошибку, —
|
||||
не «точка расширения на будущее», а дефект UX. Возвращение любого из этих
|
||||
маршрутов ломает acceptance-проверку сборки.
|
||||
|
||||
Конфигурация Hysteria остаётся доступной панели **на чтение и на выгрузку**:
|
||||
`GET /config/getHysteria2Config` и `POST /config/exportHysteria2Config`.
|
||||
|
||||
### Что нельзя делать
|
||||
|
||||
- собирать admin-компонент на target server;
|
||||
|
||||
Reference in New Issue
Block a user