159 lines
8.5 KiB
Markdown
159 lines
8.5 KiB
Markdown
# 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).
|