platform: modularize api/gui, add docs-tests-web foundation, and refresh root config
This commit is contained in:
beckline
158
docs/phase-e/E5_SINGBOX_PROTOCOLS_REQUIREMENTS.md
Normal file
158
docs/phase-e/E5_SINGBOX_PROTOCOLS_REQUIREMENTS.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# E5 Требования: SingBox Protocols (UI tab + Go API)
|
||||
|
||||
Дата: 2026-03-07
|
||||
Статус: planned (requirements fixed)
|
||||
Владелец: Engineering
|
||||
|
||||
## 1) Цель
|
||||
- Зафиксировать требования для реализации протоколов во вкладке `SingBox` без архитектурной "мешанины".
|
||||
- Зафиксировать целевой Go API для `singbox` с поддержкой "всех фишек" через typed-профили и raw-режим.
|
||||
|
||||
## 2) Архитектурные границы (чтобы не смешивать слои)
|
||||
- Слой `Transport Engine`:
|
||||
- lifecycle (`provision/start/stop/restart`), health/metrics, runtime_mode/packaging.
|
||||
- уже реализован в `/api/v1/transport/clients/*`.
|
||||
- Слой `Routing Policy`:
|
||||
- `validate -> confirm -> apply -> rollback`.
|
||||
- уже реализован в `/api/v1/transport/policies/*`.
|
||||
- Слой `Protocol Profile` (новый E5):
|
||||
- описание конфигов `sing-box` (outbounds/rules/dns/tun и т.д.).
|
||||
- не дублирует lifecycle и не дублирует policy.
|
||||
|
||||
Правило:
|
||||
- `Protocol Profile` готовит/валидирует/рендерит `sing-box` config.
|
||||
- `Transport Engine` запускает этот config.
|
||||
- `Routing Policy` решает, какой engine владеет трафиком.
|
||||
|
||||
## 3) Требования к вкладке `SingBox` (GUI)
|
||||
|
||||
### 3.1 Блоки UI (обязательные)
|
||||
- `Profiles list`:
|
||||
- список профилей, тип протокола, версия, последний apply, статус валидации.
|
||||
- `Editor`:
|
||||
- режим `Typed` (форма) и режим `Raw JSON` (полный контроль).
|
||||
- `Validation`:
|
||||
- синтаксис, обязательные поля, совместимость с бинарём/features.
|
||||
- `Apply`:
|
||||
- `Validate` -> `Preview` -> `Apply`.
|
||||
- при рисках/конфликтах — confirm flow.
|
||||
- `Diagnostics`:
|
||||
- last_error, warning, render-diff, health summary.
|
||||
- `Rollback`:
|
||||
- откат к предыдущей рабочей версии профиля.
|
||||
|
||||
### 3.2 Поведение
|
||||
- Нельзя применять профиль без успешной валидации.
|
||||
- `Apply` профиля не должен неявно менять transport-policy ownership.
|
||||
- Секреты в UI маскируются, редактируются только write-only полями.
|
||||
- Все mutating-операции идемпотентны и привязаны к ревизии.
|
||||
|
||||
### 3.3 Desktop layout freeze
|
||||
- Вкладка `SingBox` на desktop фиксируется в 3 секции:
|
||||
- `Connection card (runtime)`,
|
||||
- `Profile settings (per profile)`,
|
||||
- `Global defaults`.
|
||||
- Для profile-параметров используется правило `Use global`/`Override`.
|
||||
- Детальная спецификация: `docs/phase-e/E5_2_SINGBOX_DESKTOP_DASHBOARD_SPEC.md`.
|
||||
|
||||
## 4) Требования к модели профилей (Go)
|
||||
|
||||
### 4.1 Поддерживаемые режимы профиля
|
||||
- `typed`:
|
||||
- структурированная схема под основные протоколы.
|
||||
- `raw`:
|
||||
- полный `sing-box` JSON для "всех фишек", не покрытых формой.
|
||||
|
||||
### 4.2 Минимальный набор протоколов для typed-режима
|
||||
- `vless` (в т.ч. reality/tls варианты),
|
||||
- `trojan`,
|
||||
- `shadowsocks`,
|
||||
- `wireguard`,
|
||||
- `hysteria2`,
|
||||
- `tuic`.
|
||||
|
||||
Примечание:
|
||||
- Для нестандартных/редких фич используется `raw` без потери совместимости.
|
||||
|
||||
### 4.3 Версионирование
|
||||
- `schema_version` для профиля.
|
||||
- `profile_revision` (optimistic lock).
|
||||
- `render_revision` (версия сгенерированного итогового конфига).
|
||||
|
||||
### 4.4 DNS (встроенный resolver sing-box)
|
||||
- Профиль `singbox` должен включать секцию DNS как часть единого конфига (`dns.servers`, `dns.rules`, `strategy`, `final` и связанные поля).
|
||||
- В typed-режиме нужен базовый DNS-набор:
|
||||
- выбор DNS-провайдеров/серверов,
|
||||
- rule-based DNS routing (по доменам/гео/режимам),
|
||||
- переключение стратегий резолва (например, prefer IPv4/IPv6 по профилю).
|
||||
- Для расширенных сценариев (fakeip, cache tuning, нетиповые rules/actions) используется `raw` режим без ограничений формы.
|
||||
- Ограничение границ:
|
||||
- DNS `sing-box` отвечает за резолв внутри transport-профиля,
|
||||
- системный selective routing policy (`/transport/policies/*`) остаётся отдельным слоем и не дублируется в profile editor.
|
||||
|
||||
## 5) Требования к Go API `singbox`
|
||||
|
||||
### 5.1 Новые endpoint-группы (target)
|
||||
- `GET/POST /api/v1/transport/singbox/profiles`
|
||||
- `GET/PATCH/DELETE /api/v1/transport/singbox/profiles/{id}`
|
||||
- `POST /api/v1/transport/singbox/profiles/{id}/validate`
|
||||
- `POST /api/v1/transport/singbox/profiles/{id}/render`
|
||||
- `POST /api/v1/transport/singbox/profiles/{id}/apply`
|
||||
- `POST /api/v1/transport/singbox/profiles/{id}/rollback`
|
||||
- `GET /api/v1/transport/singbox/profiles/{id}/history`
|
||||
- `GET /api/v1/transport/singbox/features`
|
||||
|
||||
### 5.2 Контракт операций
|
||||
- `validate`:
|
||||
- возвращает ошибки схемы, ошибок протокола, неподдерживаемых фич по текущему binary.
|
||||
- `render`:
|
||||
- детерминированно строит финальный `sing-box` config + diff к текущему active.
|
||||
- `apply`:
|
||||
- атомарно: запись конфига -> backend provision -> optional restart/start -> health check.
|
||||
- при fail: автоматический rollback.
|
||||
- `rollback`:
|
||||
- откат к последнему успешному render/apply snapshot.
|
||||
|
||||
### 5.3 Совместимость и безопасность
|
||||
- Не ломать текущий `/api/v1/transport/*` контракт.
|
||||
- Для mutating запросов:
|
||||
- `Idempotency-Key`,
|
||||
- `base_revision`.
|
||||
- Секреты:
|
||||
- отдельное хранение, выдача в API только masked.
|
||||
- запрет на логирование plain-secret в trace/events.
|
||||
|
||||
## 6) "Все фишки" sing-box: как закрываем требование
|
||||
- Typed-форма покрывает частые production-сценарии.
|
||||
- Raw-режим гарантирует доступ к полному синтаксису sing-box.
|
||||
- `GET /transport/singbox/features` отражает реальные возможности текущего binary:
|
||||
- поддерживаемые протоколы,
|
||||
- transport/tls/reality/quic опции,
|
||||
- ограничения версии.
|
||||
|
||||
## 7) Хранение и артефакты
|
||||
- Профили: `/var/lib/selective-vpn/transport/singbox-profiles.json`
|
||||
- История/snapshots: `/var/lib/selective-vpn/transport/singbox-history/*.json`
|
||||
- Rendered configs: `/var/lib/selective-vpn/transport/singbox-rendered/{profile_id}.json`
|
||||
- Secrets store: `/var/lib/selective-vpn/transport/secrets/singbox/{profile_id}.json` (`0600`)
|
||||
|
||||
## 8) SSE-события (обязательные)
|
||||
- `singbox_profile_saved`
|
||||
- `singbox_profile_validated`
|
||||
- `singbox_profile_rendered`
|
||||
- `singbox_profile_applied`
|
||||
- `singbox_profile_rollback`
|
||||
- `singbox_profile_failed`
|
||||
|
||||
## 9) Поэтапная реализация (рекомендуемый порядок)
|
||||
1. `E5.1` Requirements freeze (этот документ).
|
||||
2. `E5.2` Go: state/model + CRUD + versioning + secrets storage.
|
||||
3. `E5.3` Go: validate/render/apply/rollback + SSE events.
|
||||
4. `E5.4` GUI: SingBox profiles tab (`list/editor/validate/preview/apply/rollback`).
|
||||
5. `E5.5` Совместимость web/mobile: reuse того же API-контракта.
|
||||
|
||||
## 10) Критерии готовности E5
|
||||
- Можно создать/редактировать профиль `singbox` без ручного правки файлов на хосте.
|
||||
- `Apply` проходит через validate и имеет rollback safety.
|
||||
- Raw-режим позволяет применить фичи, которых нет в typed-форме.
|
||||
- Наблюдаемость достаточна для диагностики (events + health + last_error + history).
|
||||
Reference in New Issue
Block a user