E5 SingBox Protocols Matrix (Desktop-first)
Дата: 2026-03-08
Статус: active
Владелец: Engineering
Цель: зафиксировать поля подключения до реализации форм протоколов в GUI.
1) Источники (primary)
2) Фрейм реализации
- Target:
sing-box >= 1.12.x (текущий runtime у нас 1.12.12).
- UI-стратегия:
MVP: критичные поля подключения.Advanced: дополнительные tuning-поля.Raw-only: редкие/экзотические поля, остаются в raw JSON режиме.
3) Общие блоки (для большинства outbound)
3.1 Базовые outbound-поля
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.type |
enum/string |
yes |
MVP |
фиксируется выбранным протоколом |
outbound.tag |
string |
yes |
MVP |
стабильный id карточки |
outbound.detour |
string |
no |
Advanced |
цепочка через другой outbound |
3.2 Shared Dial fields (ядро соединения)
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.server |
string |
yes |
MVP |
hostname/IP сервера |
outbound.server_port |
int |
yes |
MVP |
1..65535 |
outbound.network |
enum |
no |
MVP |
`tcp |
outbound.connect_timeout |
duration |
no |
Advanced |
таймаут dial |
outbound.tcp_fast_open |
bool |
no |
Advanced |
TCP Fast Open |
outbound.tcp_multi_path |
bool |
no |
Advanced |
MPTCP (если поддерживается) |
outbound.udp_fragment |
bool |
no |
Advanced |
UDP fragmentation |
outbound.domain_resolver |
string/object |
no |
Advanced |
используется с новым DNS-форматом |
outbound.bind_interface |
string |
no |
Advanced |
привязка к интерфейсу |
outbound.routing_mark |
int |
no |
Advanced |
fwmark для выхода |
3.3 Shared TLS/Reality блок (где применимо)
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.tls.enabled |
bool |
depends |
MVP |
must be true для Reality |
outbound.tls.server_name |
string |
depends |
MVP |
SNI |
outbound.tls.insecure |
bool |
no |
Advanced |
skip verify |
outbound.tls.alpn |
[]string |
no |
Advanced |
ALPN list |
outbound.tls.utls.enabled |
bool |
no |
Advanced |
uTLS toggle |
outbound.tls.utls.fingerprint |
enum/string |
no |
MVP |
для Reality-сценариев обычно обязательно |
outbound.tls.reality.enabled |
bool |
depends |
MVP |
Reality mode |
outbound.tls.reality.public_key |
string |
depends |
MVP |
Reality PBK |
outbound.tls.reality.short_id |
string |
no |
MVP |
Reality SID |
3.4 Shared V2Ray transport блок (где применимо)
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.transport.type |
enum/string |
no |
MVP |
`ws |
outbound.transport.path |
string |
depends |
MVP |
чаще для ws/http/httpupgrade |
outbound.transport.host |
string/[]string |
depends |
Advanced |
Host header/SNI-like values |
outbound.transport.service_name |
string |
depends |
MVP |
обычно для grpc |
outbound.transport.headers |
object |
no |
Advanced |
custom headers |
3.5 Shared Multiplex / UDP-over-TCP (где применимо)
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.multiplex |
object |
no |
Advanced |
pooling/stream mux |
outbound.udp_over_tcp |
object |
no |
Advanced |
туннелирование UDP через TCP |
4) Протокольные матрицы
4.1 VLESS outbound
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.type |
const vless |
yes |
MVP |
|
outbound.server |
string |
yes |
MVP |
|
outbound.server_port |
int |
yes |
MVP |
|
outbound.uuid |
string |
yes |
MVP |
UUID |
outbound.flow |
string |
no |
MVP |
напр. xtls-rprx-vision |
outbound.packet_encoding |
enum/string |
no |
Advanced |
с 1.11 default none |
outbound.network |
enum |
no |
MVP |
|
outbound.tls |
object |
depends |
MVP |
TLS/Reality для production-сценариев |
outbound.transport |
object |
no |
MVP |
V2Ray transport block |
Guardrails:
VLESS-001: если tls.reality.enabled=true -> tls.enabled=true.VLESS-002: если flow=xtls-rprx-vision -> transport должен быть совместим с сервером и TLS включён.
4.2 Trojan outbound
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.type |
const trojan |
yes |
MVP |
|
outbound.server |
string |
yes |
MVP |
|
outbound.server_port |
int |
yes |
MVP |
|
outbound.password |
string |
yes |
MVP |
secret |
outbound.network |
enum |
no |
MVP |
|
outbound.tls |
object |
yes (обычно) |
MVP |
TLS-блок |
outbound.transport |
object |
no |
MVP |
V2Ray transport |
Guardrails:
TRJ-001: пустой password блокирует apply.TRJ-002: без TLS для стандартного trojan-сервера помечать как risky.
4.3 Shadowsocks outbound
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.type |
const shadowsocks |
yes |
MVP |
|
outbound.server |
string |
yes |
MVP |
|
outbound.server_port |
int |
yes |
MVP |
|
outbound.method |
enum/string |
yes |
MVP |
cipher method |
outbound.password |
string |
yes |
MVP |
secret |
outbound.plugin |
string |
no |
Advanced |
SIP003 plugin |
outbound.plugin_opts |
string |
no |
Advanced |
plugin options |
outbound.network |
enum |
no |
Advanced |
|
outbound.udp_over_tcp |
object |
no |
Advanced |
shared UDP-over-TCP fields |
outbound.multiplex |
object |
no |
Advanced |
shared multiplex fields |
Guardrails:
SS-001: method обязателен и валидируется против поддерживаемых cipher.SS-002: если plugin задан, но plugin_opts пуст и plugin его требует -> warning/block.
4.4 WireGuard outbound
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.type |
const wireguard |
yes |
MVP |
|
outbound.server |
string |
depends |
MVP |
при single-peer setup |
outbound.server_port |
int |
depends |
MVP |
|
outbound.system_interface |
bool |
no |
Advanced |
|
outbound.interface_name |
string |
deprecated |
Raw-only |
deprecated с 1.11 |
outbound.local_address |
[]string |
yes |
MVP |
local tunnel address(es) |
outbound.private_key |
string |
yes |
MVP |
secret |
outbound.peer_public_key |
string |
depends |
MVP |
single-peer |
outbound.pre_shared_key |
string |
no |
Advanced |
secret |
outbound.reserved |
[]int |
no |
Advanced |
|
outbound.workers |
int |
no |
Advanced |
|
outbound.mtu |
int |
no |
Advanced |
|
outbound.network |
enum |
no |
Advanced |
|
outbound.peers |
[]object |
depends |
Advanced |
multi-peer schema |
outbound.peer_allowed_ips |
[]string |
no |
Advanced |
|
outbound.packet_encoding |
enum/string |
no |
Advanced |
|
Guardrails:
WG-001: private_key обязателен.WG-002: нужен или peer_public_key (single) или peers[] (multi).
4.5 Hysteria2 outbound
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.type |
const hysteria2 |
yes |
MVP |
|
outbound.server |
string |
yes |
MVP |
|
outbound.server_port |
int |
yes |
MVP |
|
outbound.up_mbps |
int |
no |
MVP |
upload bandwidth hint |
outbound.down_mbps |
int |
no |
MVP |
download bandwidth hint |
outbound.obfs |
string |
no |
Advanced |
obfuscation method |
outbound.obfs_password |
string |
depends |
Advanced |
secret |
outbound.password |
string |
depends |
MVP |
auth password |
outbound.network |
enum |
no |
Advanced |
|
outbound.tls |
object |
yes (обычно) |
MVP |
TLS block |
outbound.brutal_debug |
bool |
no |
Raw-only |
debug option |
Guardrails:
HY2-001: если задан obfs, то obfs_password обязателен.HY2-002: пустой password при password-auth конфиге блокирует apply.
4.6 TUIC outbound
| JSON path |
Type |
Required |
UI level |
Notes |
outbound.type |
const tuic |
yes |
MVP |
|
outbound.server |
string |
yes |
MVP |
|
outbound.server_port |
int |
yes |
MVP |
|
outbound.uuid |
string |
yes |
MVP |
auth uuid |
outbound.password |
string |
yes |
MVP |
secret |
outbound.congestion_control |
enum/string |
no |
Advanced |
algo |
outbound.udp_relay_mode |
enum/string |
no |
Advanced |
relay mode |
outbound.udp_over_stream |
bool |
no |
Advanced |
|
outbound.zero_rtt_handshake |
bool |
no |
Raw-only |
advanced/risky |
outbound.heartbeat |
duration/int |
no |
Raw-only |
keepalive tuning |
outbound.network |
enum |
no |
Advanced |
|
outbound.tls |
object |
yes (обычно) |
MVP |
TLS block |
Guardrails:
TUIC-001: uuid и password обязательны.TUIC-002: zero_rtt_handshake=true помечать warning (опция совместимости/риска).
5) Срез MVP полей для первой версии GUI
VLESS: server, server_port, uuid, flow, tls.server_name, tls.reality.public_key, tls.reality.short_id, tls.utls.fingerprint.Trojan: server, server_port, password, tls.server_name.Shadowsocks: server, server_port, method, password.WireGuard: server, server_port, local_address, private_key, peer_public_key.Hysteria2: server, server_port, password, up_mbps, down_mbps.TUIC: server, server_port, uuid, password, congestion_control.
Все остальные поля:
- либо в секции
Advanced,
- либо в
Raw JSON (без потери функциональности).
6) DoD для этапа "матрица готова"
- Шаблон и матрица лежат в
docs/phase-e.
- Для каждого протокола есть список MVP/Advanced/Raw-only полей.
- Для каждого протокола есть минимум 2 guardrail-правила валидации.
- Есть machine-readable манифест для последующей генерации форм.
