singbox

name

singbox

description

Полный справочник по sing-box в проекте zapret-gui (роутеры Keenetic на Entware / OpenWrt). Использовать при любых задачах о: конфигах sing-box (log/dns/inbounds/outbounds/endpoints/route/services/experimental), CLI (run/check/format/merge/tools/generate/rule-set), типах outbound (vless/vmess/trojan/shadowsocks/hysteria2/tuic/selector/urltest), TLS/Reality/ uTLS/ECH, transport (ws/grpc/httpupgrade/h2/quic), multiplex, прозрачном проксировании (tproxy/redirect/tun), подписках и пуле серверов (server_pool, subscription_*), парсинге vless:// vmess:// ss:// trojan:// hysteria2:// tuic://, миграциях версий 1.11/1.12/1.13/1.14 (geoip/geosite удалены в 1.12, block/dns outbounds + legacy inbound-поля + wireguard outbound удалены в 1.13, новый формат DNS с 1.12 и удаление legacy-DNS в 1.14), отладке и диагностике «sing-box не запускается / конфиг не валиден / прокси не работает». Источник истины — sing-box.sagernet.org + sagernet/sing-box, привязка — наш код core/singbox_*.py, api/singbox.py, web/js/pages/singbox*.js.

sing-box — справочник для zapret-gui

Единый источник истины о том, как sing-box реально работает и как с ним обращаться в zapret-gui. Читать перед тем, как трогать генерацию конфигов, менеджер процессов, прозрачное проксирование, подписки/пул или объяснять пользователю «почему не работает».

Источники истины (в порядке убывания авторитета):

1. sing-box.sagernet.org — официальная документация конфигурации и CLI; sagernet/sing-box (Go-исходники) — окончательная истина по схемам.
2. sing-box check -c <file> — валидатор самого бинаря. Если он молчит — конфиг валиден для ЭТОЙ версии; если ругается — это и есть причина.
3. Наш код — core/singbox_config.py (генерация/валидация JSON), core/singbox_manager.py (run/check/up/down/debug/log), core/singbox_platform.py (пути), core/singbox_transparent.py + core/singbox_transparent_nft.py (firewall tproxy/redirect/tun), core/singbox_subscription.py + core/subscription_importer.py + core/subscription_manager.py (подписки), core/server_pool.py (пул), core/singbox_autostart.py, core/singbox_installer.py, core/singbox_detector.py, api/singbox.py, web/js/pages/singbox*.js.

⚠️ Версии — главный источник «не работает». sing-box ломает обратную совместимость по minor-версиям (см. §9). На роутере может стоять что угодно от 1.8 до 1.13+. Любая фича/поле, генерируемые нами, обязаны быть валидны на ЦЕЛЕВОЙ версии. При сомнении — sing-box version и sing-box check.

---

1. Как sing-box используется в zapret-gui

Модель: один процесс = один конфиг-файл (упрощение против AWG, где туннель = интерфейс). Имя инстанса = имя файла без .json. Внутри одного инстанса — сколько угодно outbound'ов и групп.

Поток:

• Конфиги лежат в platform.config_dir (Keenetic Entware: /opt/etc/sing-box/, Linux: /etc/sing-box/). CRUD — SingboxManager.
• Запуск: sing-box run -c <config> через subprocess.Popen с start_new_session=True, stdout/stderr → лог-файл (platform.log_path), PID → platform.pid_path. Перед стартом — обязательный pre-flight sing-box check -c <config> (если не прошёл — старт не делаем, отдаём stderr пользователю).
• Подписки (subscription_manager): каждая приватная подписка → свой конфиг. Пул (server_pool): много ПУБЛИЧНЫХ источников-«свалок» → дедуп → (опц.) health-тест → cap → один конфиг server-pool с urltest-группой.
• Прозрачное проксирование (singbox_transparent): tproxy / redirect / hybrid / tun — заворачивает трафик LAN в sing-box через iptables/nft.
• Маршрутизация GUI поверх: target_iface = tun0/singbox-tun для TUN.

Базовый генерируемый конфиг (make_minimal_config)

mixed-inbound на 127.0.0.1:1080 → outbound с тегом proxy-out (юзер заменяет на свой), final: direct. Спец-outbound block НЕ добавляем — он удалён в 1.13 (см. §9).

---

2. CLI sing-box (что мы вызываем и что есть ещё)

Глобальные (persistent) флаги — работают со всеми командами:

Флаг	Назначение
-c, --config <file>	путь к конфигу. Повторяемый: -c a.json -c b.json → файлы объединяются (объекты — deep-merge, массивы — конкатенация).
-C, --config-directory <dir>	взять все *.json из каталога (тоже merge).
-D, --directory <dir>	рабочий каталог процесса.
--disable-color	без ANSI-цвета (для логов в файл).

Команды:

Команда	Назначение
run	запустить сервис (наш основной путь).
check	проверить конфиг(и) без запуска (наш pre-flight + validate_via_binary).
format [-w]	отформатировать конфиг (-w — переписать на месте).
merge <output>	склеить несколько -c/-C в один файл (доказывает, что merge поддержан).
tools connect <addr>	проверить досягаемость через конфиг (диагностика).
tools fetch <url>	HTTP-запрос через outbound (диагностика).
tools synctime	синхронизировать время (важно для TLS/Reality!).
generate uuid / rand / reality-keypair / wireguard-keypair / tls-keypair / ech-keypair / vapid-keypair	генерация ключей/идентификаторов.
rule-set compile/decompile/convert/format/match/merge/upgrade	работа с rule-set (бинарные .srs).
geoip / geosite	устаревшие (geoip/geosite удалены в пользу rule-set, §9).
version	версия (всегда снимай при диагностике).

2.1 Режим отладки (наш singbox.debug_log)

core/singbox_manager.py: тумблер singbox.debug_log (API GET/POST /api/singbox/debug, UI — «Режим отладки» в обзоре). Когда включён, при запуске инстанса подмешивается overlay вторым -c:

{"log": {"disabled": false, "level": "debug", "timestamp": true}}

(файл <run_dir>/_zg-debug.json). Тот же набор -c идёт и в pre-flight check. Graceful: если билд не умеет merge (check -c a -c b != 0) — overlay не применяется, инстанс стартует на обычном уровне (старт никогда не ломаем). Overlay НЕ пишется в сам конфиг — выключил тумблер, перезапустил, debug ушёл. Просмотр лога: GET /api/singbox/configs/<name>/log?lines=N → SingboxManager.read_log() (хвост platform.log_path). UI — кнопка «Лог».

---

3. Верхнеуровневые ключи конфига

Ключ	Назначение	Заметки по версиям
log	логирование	см. §3.1
dns	DNS-сервер и правила	формат переписан в 1.12 (§7)
ntp	встроенный NTP-клиент	для TLS, если часы плывут
certificate / certificate_providers	TLS-сертификаты (ACME, Tailscale)	новое
endpoints	WireGuard / Tailscale как endpoint	добавлено в 1.11
inbounds	входящие листенеры	legacy-поля sniff/domain_strategy удалены в 1.13 (§9)
outbounds	исходящие прокси	block/dns удалены в 1.13 (§9)
route	правила маршрутизации + rule-actions	§6
services	доп. сервисы (DERP, resolved, ssm-api)	добавлено в 1.11+
experimental	clash-api / cache-file / v2ray-api	§8

3.1 log

{"log": {"disabled": false, "level": "info", "output": "box.log", "timestamp": true}}

• level: trace | debug | info | warn | error | fatal | panic (по умолч. info).
• output: путь к файлу. ВАЖНО: если задан output, в консоль/stderr лог НЕ пишется. Мы редиректим stderr в файл сами и output НЕ задаём — иначе наш захват лога опустеет. (Debug-overlay тоже без output.)
• timestamp: время в каждой строке (по умолч. true).

---

4. Inbounds (входящие)

Типы: mixed (http+socks одним портом — наш дефолт), socks, http, shadowsocks, vmess, vless, trojan, hysteria, hysteria2, tuic, naive, shadowtls, tun, redirect, tproxy, direct.

Общие поля listen-inbound: type, tag, listen (адрес, ::/0.0.0.0/ 127.0.0.1), listen_port.

1.11→1.13 (КРИТИЧНО): legacy-поля inbound sniff, sniff_override_destination, sniff_timeout, domain_strategy, udp_disable_domain_unmapping объявлены deprecated в 1.11 и удалены в 1.13. Замена — route rule-actions sniff / resolve (§6). Наш код это уже делает: make_sniff_rule() ставит {"action":"sniff"}, inbound'ы «чистые». Issue #149 был ровно про это.

TUN-inbound (make_tun_inbound)

type:tun, interface_name (singbox-tun), address (172.18.0.1/30+v6), mtu, stack (system/gvisor/mixed), auto_route, strict_route. Требует поддержку TUN в ядре (platform.tun_available()). Не нужен TPROXY — забирает TCP+UDP.

---

5. Outbounds (исходящие) и endpoints

5.1 Прокси-типы (наши билдеры в singbox_config.py)

• vless (make_vless_outbound): uuid, опц. flow:"xtls-rprx-vision", tls, transport, multiplex.
• vmess (make_vmess_outbound): uuid, security(auto), alter_id.
• trojan (make_trojan_outbound): password, обычно с tls.
• shadowsocks (make_shadowsocks_outbound): method, password.
• hysteria2 (make_hysteria2_outbound): password, up_mbps/down_mbps, obfs(salamander), всегда TLS (часто tls.insecure).
• tuic (make_tuic_outbound): uuid, password, congestion_control(bbr), UDP-over-QUIC.
• direct, и группы ниже.

Общие поля: type, tag, server, server_port. direct — валидный тип (прямой выход), НЕ deprecated.

5.2 Группы

• selector (make_selector_outbound): ручной выбор; outbounds:[tags], default(тег), interrupt_exist_connections.
• urltest (make_urltest_outbound): авто по latency; url (https://www.gstatic.com/generate_204 / cloudflare), interval, tolerance, idle_timeout. Наш пул заворачивает все ключи в urltest.

5.3 Endpoints (1.11+)

endpoints (отдельно от outbounds): wireguard, tailscale. WireGuard как endpoint заменил старый type:wireguard outbound (он deprecated в 1.11 и удалён в 1.13.0 — на 1.13+ {"type":"wireguard"} в outbounds не парсится, нужен endpoints). Это встроенный WG sing-box; про AmneziaWG-туннели — skill awg.

5.4 TLS / Transport / Multiplex (вложенные объекты)

• tls: enabled, server_name(SNI), insecure, alpn, utls({enabled, fingerprint:"chrome"} — маскировка ClientHello), reality({enabled, public_key, short_id}), ech.
• transport: type ∈ ws (path,headers), grpc(service_name), httpupgrade, http(h2), quic.
• multiplex: {enabled, protocol:"smux|yamux|h2mux", max_streams, padding, brutal:{...}}.

---

6. Route и rule-actions (1.11+ модель)

route: rules:[...], final(тег по умолчанию), auto_detect_interface, default_mark, rule_set:[...].

Каждое правило = матчеры + action. Матчеры: inbound, protocol, domain/domain_suffix/domain_keyword/domain_regex, ip_cidr, source_ip_cidr, port/port_range, network(tcp/udp), clash_mode, rule_set, и т.д.

⚠️ geoip/geosite как матчеры route-правил УДАЛЕНЫ в 1.12.0 (deprecated с 1.8). На 1.12+ конфиг с {"geosite":...}/{"geoip":...} в route.rules не парсится — замена — rule_set (бинарные .srs) либо ip_cidr/domain_suffix.

Actions (это и есть «новая модель» 1.11+):

action	смысл	ключевые параметры
route (default)	направить в outbound	outbound
route-options	оверрайды без финализации	override_address/port, TLS-fragment
reject	оборвать соединение	method: default (RST/ICMP-unreach) / drop (тихо) / reply (ICMP echo). Заменяет удалённый block-outbound.
hijack-dns	завернуть DNS в DNS-модуль sing-box	Заменяет удалённый dns-outbound. (make_hijack_dns_rule)
sniff	определить L7-протокол (для domain-правил)	sniffer:[...], timeout(300ms). Заменяет inbound sniff. (make_sniff_rule)
resolve	резолв домена в IP до маршрутизации	server(тег), strategy(prefer_ipv4/prefer_ipv6/ipv4_only/ipv6_only), disable_cache, rewrite_ttl, client_subnet
bypass	обойти sing-box на уровне ядра (auto-redirect, только Linux)	—

Типовой порядок правил при sniffing: сначала {"action":"sniff"}, затем {"protocol":"dns","action":"hijack-dns"}, затем доменные/ip правила с outbound, в конце final.

---

7. DNS (формат переписан в 1.12)

• До 1.12 (legacy): dns.servers[].address ("tls://1.1.1.1", "https://...", "local", "fakeip"), detour, address_resolver, strategy.
• С 1.12 (типизированный): dns.servers[].type ∈ udp | tcp | tls | https | quic | h3 | local | hosts | dhcp | fakeip | tailscale | resolved, плюс type:legacy для старого address-формата. Структура: servers[], rules[], final, strategy, independent_cache, client_subnet. ⚠️ legacy address-формат (и type:legacy) УДАЛЁН в 1.14.0 — на 1.14+ конфиг с dns.servers[].address не запустится, только typed-серверы.

При генерации DNS-секции учитывай целевую версию: на 1.12+ предпочитай типизированные серверы; legacy-address всё ещё валиден как type:legacy, но это путь к будущим поломкам. DNS-перехват у нас делается route-action hijack-dns, а не спец-outbound dns (тот удалён, §9).

⚠️ Реальность нашего кода: базовый unified/OS-routing путь НЕ эмитит секцию dns (hijack-dns — только в transparent-режиме с dns_port>0). НО есть отдельный FakeIP-режим (build_fakeip_config / core/singbox_fakeip), который генерирует полноценную dns-секцию с FakeIP

• hijack-dns — см. §13.

---

8. experimental

• clash_api (make_clash_api): {external_controller, secret, external_ui} — даёт API для трафик-статистики/переключения (наш /api/singbox/traffic, enable-clash-api).
• cache_file: {enabled, path, store_fakeip} — кэш fakeip/urltest между рестартами.
• v2ray_api: устаревает в пользу clash_api.

---

9. Миграции версий — таблица «что удалено» (ГЛАВНОЕ при «не работает»)

Сверено с офиц. sing-box.sagernet.org/deprecated + /migration (deprecated ≠ removed — важно различать версию объявления и версию удаления):

Версия	Что произошло	Замена	Наш статус
1.8	deprecated: geoip, geosite	rule_set (бинарные .srs)	ipset/hostlist + rule-set при импорте
1.11	deprecated: спец-outbounds block/dns; inbound-поля sniff*/domain_strategy; outbound wireguard	rule-actions reject/hijack-dns/sniff/resolve; endpoints для WG	block убран из make_minimal_config; sniff/dns-hijack через route
1.12	УДАЛЕНЫ geoip/geosite (как route-матчеры); формат dns переписан на типизированные серверы (legacy-address пока принимается)	rule_set; type:udp/tcp/tls/…	geo — через ipset/rule-set; DNS см. §7
1.13	УДАЛЕНЫ block/dns outbounds, legacy inbound-поля (sniff*/domain_strategy), старый outbound type:wireguard	как deprecated в 1.11	issue #149 — генератор чистый; validate() держит block/dns в «известных типах» только для ЧТЕНИЯ старых чужих конфигов
1.14 (latest — 1.14.0-alpha)	УДАЛЁН legacy-формат dns (address-серверы / type:legacy); deprecated: inline tls.acme, address-filter поля DNS-правил (→ action evaluate), independent_cache (убрано), store_rdrc→store_dns	typed DNS-серверы (§7)	на 1.14+ dns.servers[].address не запустится — генерить только typed

Симптомы по версиям: на 1.12+ — падение на {"geosite":…}/{"geoip":…} в route или на legacy-DNS уже на 1.14; на 1.13 — FATAL ... legacy inbound fields ... removed in sing-box 1.13.0 (legacy sniff) либо падение на {"type":"block"|"dns"|"wireguard"}. Лечится переходом на rule-actions/ rule_set/endpoints/typed-DNS. Наш генератор уже чистый; импортированные/ручные конфиги пользователя — нет, поэтому существует pre-flight check и режим отладки.

---

10. Прозрачное проксирование (singbox_transparent*)

Режимы (make_transparent_inbounds, firewall в singbox_transparent.py / _nft.py):

• redirect — nat REDIRECT (TCP). TPROXY НЕ нужен, работает почти везде. Минус: UDP/QUIC уходит напрямую.
• tproxy — mangle TPROXY (TCP+UDP). Требует ядро/модуль xt_TPROXY/nf_tproxy + iptables-mod-tproxy.
• hybrid — redirect для TCP + tproxy для UDP.
• tun — TUN-инбаунд, забирает TCP+UDP без TPROXY.

issue #149/#151 (Keenetic mips): TPROXY часто ОТСУТСТВУЕТ (modprobe not found, iptables-mod-* = Unknown package). Тогда tproxy/hybrid не поднимутся в принципе. GUI зондирует цель TPROXY заранее, помечает tproxy/hybrid как недоступные, рекомендует redirect (TCP) или TUN (TCP+UDP). Правила обязаны строиться с явной таблицей (-t mangle/-t nat) — иначе уходят в filter и падают с «No chain/target/match by that name».

---

11. Подписки и парсинг ссылок

subscription_importer / singbox_subscription парсят форматы:

• URI-ключи: vless://, vmess:// (base64-JSON), ss:// (base64 method:pass), trojan://, hysteria2:///hy2://, tuic://.
• base64-список (строки URI в base64), clash YAML, sing-box JSON. format:"auto" определяет тип сам. Дедуп по (type, server, port, cred) в server_pool.dedup_outbounds, уникализация тегов.

Пул источников (server_pool.BUILTIN_PRESETS): публичные «свалки» ключей. Инвариант «не затирать при пустом» — last-good кэш на источник. Битая ссылка (404) → 0 ключей → берётся прошлый успешный набор. Проверяй URL пресетов: файлы в публичных репо переименовываются/переезжают (igareck → BLACK_*; kort0881 → *_for_mirror.txt), configs.txt/vless.txt в корне могут давать 404.

---

12. Диагностика «почему не работает» (чек-лист)

1. sing-box version — какая версия? (определяет, что валидно.)
2. sing-box check -c <config> — первый и главный шаг. Текст ошибки = причина (legacy-поля, удалённые типы, опечатки).
3. Режим отладки (§2.1) → log.level=debug → смотреть read_log/кнопку «Лог»: видно dial/handshake/TLS-ошибки, отказ сервера, неверный SNI/uuid.
4. Часы: TLS/Reality рушатся при расхождении времени → tools synctime.
5. Транспорт/TLS совпадает с сервером? ws-path, SNI, flow, reality public_key/short_id, insecure для self-signed/hysteria2.
6. TPROXY недоступен (§10) → redirect/TUN.
7. DNS: на 1.12+ legacy-формат — частая причина; hijack-dns через route.
8. Лишний/удалённый ключ (block/dns outbound, inbound sniff) на 1.13.

---

13. Наша selective-routing модель и DNS (и чем отличаемся от podkop)

Как мы заворачиваем выбранные ресурсы в sing-box-TUN (единый слой, core/unified; см. applier._apply_tunnel + geo_engine):

• домены / CIDR правит НЕ sing-box, а ОС-роутинг (core/routing: dnsmasq + ipset/nftset + ip rule) — листовые домены резолвятся в ipset, их IP маршрутизируются в TUN-интерфейс; sing-box просто форвардит всё, что вошло в TUN, в прокси-outbound (route.final). DNS-leak частично закрывает core/routing/doh_resolver.py (преднаполнение set'а через DoH).
• geosite / geoip — нативные концепции движка, ОС их не выразит → geo_engine._inject_singbox добавляет их как sing-box route-правила (domain_suffix/geosite/geoip → proxy, build_geo_route_rule).
• set_tun_inbound() добавляет {"action":"sniff"} (доменные правила ВНУТРИ движка матчатся по SNI), но hijack_dns=False и секцию dns не генерирует. auto_route=false по умолчанию (трафик в TUN загоняет Selective routing через ip rule/ipset, а не сам sing-box).

podkop устроен наоборот — DNS-центрично: dnsmasq → sing-box DNS с FakeIP; домены из списков получают fake-IP, диапазон fake-IP роутится в TUN, sing-box по fake-IP восстанавливает домен и проксирует. Маршрутизация управляется DNS/FakeIP внутри движка. podkop — только OpenWrt 24.10+ (fw4/nftset + переписываемый dnsmasq). Списки доменов у обоих из одного источника — itdoginfo/allow-domains (наш core/list_updater.py).

Почему у нас иначе: мультиплатформенность (Keenetic/Entware с NDM-dnsmasq и iptables, OpenWrt, Linux). На Keenetic нельзя свободно переписать резолвер на sing-box-fakeip, поэтому базовый путь — ОС-роутинг по ipset.

Известные ограничения нашего пути (которых нет у fakeip):

• DNS клиента для проксируемого домена может уйти мимо и зарезолвиться в IP вне нашего ipset (geo-split CDN) → соединение не завернётся / лёгкий DNS-leak; doh_resolver смягчает, но best-effort.
• QUIC/ECH (шифрованный ClientHello) ломает SNI-sniff → доменные правила ВНУТРИ движка не сработают (fakeip сработал бы).
• Режим «весь трафик» (auto_route=true) без секции dns → системный резолвер может течь.

FakeIP-режим (РЕАЛИЗОВАН) — podkop-уровень надёжности доменного роутинга, мультиплатформенно:

• singbox_config.build_fakeip_config() — собирает self-contained конфиг: TUN(auto_route+strict_route[+auto_redirect на nft]) + dns с FakeIP + {action:sniff} + {protocol:dns,action:hijack-dns} + domain/cidr-правила → proxy-out; experimental.cache_file.store_fakeip. ip_is_private→direct.
• make_fakeip_dns() — DNS-секция в двух форматах: legacy (address:fakeip
  • top-level dns.fakeip; валиден 1.8–1.13) и typed (type:fakeip; 1.12+).
• core/singbox_fakeip.py — оркестратор: резолвит прокси из ссылки (uri_to_outbound) или из конфига; домены берёт из hostlist'ов пользователя + формы; подбирает формат DNS под версию и проверяет sing-box check-ом ДО сохранения (SingboxManager.check_text), legacy↔typed fallback; route_all отключает FakeIP (весь трафик в прокси).
• API: GET /api/singbox/fakeip/options, POST /api/singbox/fakeip/build.
• UI: карточка «Умный доменный роутинг (FakeIP)» на дашборде sing-box (web/js/pages/singbox.js): ссылка/конфиг прокси, чекбоксы списков, доп. домены/подсети, прямой DNS, режим «весь трафик».

DNS-перехват LAN-клиентов (FakeIP работает, только если их DNS доходит до движка):

• nft (OpenWrt): auto_redirect TUN сам забирает forwarded :53 → ничего не нужно.
• iptables (Keenetic): конфиг несёт dns-in direct-inbound на dns_port (1153), а SingboxManager на старте ставит REDIRECT udp/tcp :53 → dns_port и на остановке снимает (живёт ровно пока конфиг запущен — иначе LAN остался бы без DNS). Сделано через singbox_transparent mode="dns-only" (только DNS-hijack, без traffic-redirect; своя цепочка SBT_REDIR_PRE в nat PREROUTING — локальный DNS роутера/движка в OUTPUT не трогается → без петли). Состояние сохраняется как singbox.transparent={mode:dns-only,...}, поэтому переживает перезагрузку через штатный --apply-singbox-transparent. Сигнал «этому конфигу нужен перехват» — наличие inbound'а tag=dns-in (_config_dns_in_port). Конфликт-гард: если активно прозрачное проксирование (redirect/tproxy) — dns-only не ставится (общие цепочки).
• Управление — чекбокс «Перехватывать DNS LAN-клиентов» в карточке FakeIP (capture_dns, по умолчанию вкл); build_and_save возвращает dns_capture ∈ {auto_redirect, iptables-redirect, manual}.

---

14. Layout (где что)

• Бинарь: singbox_detector.detect_binary() (Entware: /opt/sbin/sing-box).
• Конфиги: platform.config_dir (/opt/etc/sing-box/ | /etc/sing-box/).
• PID/лог/overlay: platform.run_dir (/opt/var/run/sing-box/ | /var/run/sing-box/): singbox-<name>.pid, <name>.log, _zg-debug.json.
• last-good кэш пула: .server_pool_cache.json рядом с settings.json.
• Автозапуск: singbox_autostart (init-скрипт платформы).