zapret-kvn/docs/sing-box/routing-gui.md
loop-uh 686bfeb0eb
Some checks failed
Windows project source guards / test (push) Failing after 17s
Shared always-proxy domain list: one canonical file for both platforms
data/routing/always-proxy-domains.json is a byte-identical copy of android/shared/always-proxy-domains.json
(android/scripts/check-shared-routing-list.sh compares them before an Android release). The template test now
reads the file instead of a hardcoded list, and data/routing is whitelisted in .gitignore so neither file
depends on a forced add. No behaviour change.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-13 18:03:32 -05:00

15 KiB
Raw Permalink Blame History

Маршрутизация: структурный редактор sing-box

Раздел «Маршрутизация» в боковом меню редактирует активный native JSON sing-box (data/configs/sing-box/*.json). Своей модели маршрутизации у приложения нет: формы меняют разобранный JSON на месте и записывают его обратно, страница «JSON» показывает тот же документ.

Страницы

Подпункт Что редактирует
Обзор выбор конфига и шаблона, сравнение со стоком, сброс всего конфига или одного раздела, статус
Правила route.rules (сверху вниз, первое совпадение) и route.final
Наборы правил route.rule_set: local / remote / inline
DNS параметры dns, dns.servers, dns.rules
Исходящие outbounds и endpoints; proxy — слот выбранного сервера, только просмотр
Система inbounds (TUN), остальные route.*, log, experimental, прочие секции
JSON весь документ текстом

Правки живые: «Готово» закрывает подстраницу, «Отменить правки» возвращает объект к состоянию на момент открытия. На диск пишут только «Сохранить»/«Применить» в верхней панели; «Проверить» запускает sing-box check бандл-ядром по редактируемому JSON в фоне (служебные подстановки запуска в эту проверку не входят).

Простое правило и «Проверить сайт»

  • «Добавить правило» → «Сайты, IP, программы (просто)» (ui/singbox/simple_rule_page.py, разбор — singbox_config/simple_rule.py): куда (через VPN / напрямую / блок) и списки по одному в строке в синтаксисе v2rayN. 2ip.ru — domain_suffix (сайт и поддомены), full:/keyword:/regexp:, geosite:/geoip: — существующие наборы, geoip:private — ip_is_private, программа с путём — process_path. Сайты/IP и программы собираются в logical or: в ядре разные виды условий идут через И. Документ не меняется до «Добавить»; правило встаёт сразу после sniff/hijack-dns. «Добавить и применить» идёт тем же путём, что «Применить».
  • Программа «Через VPN» по умолчанию идёт «Кроме российских сайтов»: правило встаёт выше стокового «РФ напрямую», и без исключения VK, Яндекс, банки этой программы уходили в туннель, где с зарубежного адреса часто не открываются (16.10.2026). Исключение — обычное native-правило ядра: logical and из условий пользователя и {"rule_set": [geosite-category-ru, geoip-ru], "domain_suffix": [ru, xn--p1ai, su], "invert": true}; наборы берутся, только если есть в документе. Российское назначение не совпадает с правилом и идёт дальше по списку. Без галочки страница предупреждает, что российские сайты программы тоже пойдут через VPN.
  • Имена, которые блокируются и на российском адресе, идут через VPN всегда (13.11.2026): кеш-серверы YouTube (rrN---sn-….googlevideo.com) стоят и в сетях российских операторов, их адрес «российский», и стоковое «РФ напрямую» по geoip-ru уводило видео мимо VPN в канал, где YouTube блокируется. В каждом шаблоне sing-box и Xray стоит одно обычное native-правило по именам (googlevideo.com, youtube.com, youtu.be, ytimg.com, ggpht.com, youtube-nocookie.com, youtubei.googleapis.com) → proxy, сразу после правила 4pda.to/zapret.moe и выше наборов «РФ напрямую»; в sing-box к нему добавлено DNS-правило proxy-dns. Список один на обе платформы: файл data/routing/always-proxy-domains.json (побайтовая копия android/shared/…, сверка — android/scripts/check-shared-routing-list.sh при выпуске Android). Тест tests/test_always_proxy_domains_templates.py читает файл и держит список, порядок и DNS; чтобы добавить сайт, правят файл (и его копию в Android) и четыре шаблона. Уже сохранённый конфиг, где пользователь правил разделы, шаблон не перезаписывает: такой раздел обновляется вручную.
  • Диагностика маршрута: в runtime_redacted.json — route_decisions (по последним четырём сессиям: процесс, сайт из двух меток имени или IP, правило ядра «… => route(…)» или final, маршрут и число соединений; отдельно — российские сайты, ушедшие в туннель) из того же опроса Clash API /connections, что метрики, и components["sing-box"].route_history — правила route последних восьми запусков.
  • «Проверить сайт» над списком (singbox_config/route_explain.py, application/route_check.py): порядок ядра — сверху вниз до первого совпадения, sniff/resolve/route-options не останавливают, иначе route.final. Запрос — браузер: TCP/443/TLS, программа неизвестна; условия вроде процесса дают «может перехватить», перебор идёт дальше. IP-условия — только в TUN или после resolve. Наборы проверяет само ядро: sing-box rule-set match -f <format> (без -f ядро не читает .srs), наборы по URL — «не узнать». Проверяется редактируемый документ, включая несохранённые правки.

Откуда берутся поля

assets/sing-box-schema/schema.json — JSON Schema, которую генерирует само закреплённое ядро (sing-box schema) из своих Go-структур: python3 scripts/generate_singbox_schema.py после смены пина sing-box в scripts/core-lock.windows-x64.json. Форк не умеет описать несколько своих типов (amnezia-диапазоны endpoints, byte-размеры, providers); генератор ослабляет только их и пишет пути в loose-paths.txt. Тест гарантирует, что их нет в route, dns, inbounds, outbounds, log и experimental; такие поля endpoints редактируются как JSON.

sing-box check по исходному JSON не видит служебных подстановок запуска. Поэтому outbound direct и DNS-сервер bootstrap-dns, на которые запуск ссылается сам, помечены как нужные приложению, а их удаление требует подтверждения.

  • xray_fluent/singbox_config/schema.py — чтение схемы: поля объекта с учётом дискриминатора (type, action), Listable-поля, ссылки на теги (x-tag-reference).
  • xray_fluent/singbox_config/catalog.py — только подписи, закреплённые поля и сводки строк. Поле без подписи всё равно доступно под своим native-ключом.
  • xray_fluent/ui/singbox/form.py — форма показывает заданные, обязательные и закреплённые поля; всё остальное, что знает ядро, — в «Добавить параметр». Смена type/action убирает поля, которые новый вариант не принимает.

Инварианты

  • Открытие страниц и объектов не меняет JSON (пустые секции создаются только при первой настоящей правке).
  • Неизвестные ядру ключи сохраняются и показываются как «неизвестное поле».
  • Одиночное значение Listable-поля остаётся скаляром, пока в нём один элемент.
  • При ошибке JSON разделы только читают и предлагают исправить текст на странице «JSON».
  • Обновление приложения сливает стоковый шаблон посекционно (template_sync.merge_stock_sections): нетронутые разделы следуют за стоком, изменённые остаются вашими. Принудительной синхронизации DNS больше нет. Разделы связаны: если новый стоковый dns ссылается на наборы правил, которых нет в вашем изменённом route, он не применяется (иначе ядро не стартует: «dns rule[N]: rule-set not found»). Конфиг, уже испорченный таким слиянием в 0.8.67–0.8.68, при запуске чинится: убираются только правила DNS с несуществующими наборами, и только если dns совпадает со стоком.
  • Виджеты редактора удаляются только через qt_lifecycle.dispose_later: скрытие сразу, разрушение на следующем такте при выключенном циклическом GC (у ScrollArea/PlainTextEdit/RoundMenu qfluentwidgets есть SmoothScrollDelegate, гонка GC с деструкторами роняет процесс, на Windows — особенно). Меню «Добавить…» строятся по клику и удаляются после закрытия.
  • qfluentwidgets 1.11 не освобождает Python-обёртки удалённых стилизованных виджетов (лямбды на destroyed и qconfig.themeChanged). Глобально это не патчится: освобождённые обёртки попадают под ту же гонку GC во всём приложении. Поэтому редактор бережёт виджеты: строки списков обновляются на месте, невидимые разделы пересобираются только при показе, повторная загрузка того же текста ничего не пересобирает, схема ядра грузится при первой сборке раздела.
  • Смена type/action пересобирает форму на следующем такте: выбор приходит из всплывающего меню самого комбобокса.
  • Незафиксированный ввод (списки и JSON применяются с задержкой) сбрасывается в документ по потере фокуса, «Готово», переключению раздела и перед «Сохранить/Применить/Проверить».

Графика и анимация

  • Строки списков несут значок-плитку (ui/singbox/visuals.py): тон по смыслу — прокси = акцент, напрямую = зелёный (success), блок = error, DNS = info, служебные действия = warning. Цвета берутся из ui/theme.py в момент отрисовки, так что следуют теме и акценту; hex-литералов вне theme.py нет.
  • На странице раздела только заголовок и данные. Пояснения для новичков и живая иллюстрация открываются ссылкой «Как это б#&^ь работает?» в стоковом окне MessageBoxBase поверх приложения (ui/singbox/guide.py: тексты GUIDES, окно удаляется через dispose_later). Иллюстрация (ui/singbox/art.py, QPainter) рисует конфиг пользователя: «Обзор» — карта, где пакеты уходят в прокси, напрямую или в блок пропорционально числу правил (visuals.rule_outcomes); «Правила» — зонд идёт сверху вниз и останавливается на первом совпадении; «DNS» — вращающийся глобус и запрос/ответ; «Исходящие» — хаб с импульсами; «Система» — туннель TUN; «JSON» — набор текста.
  • Анимации работают на motion.FrameGate: кадры (25 fps, у JSON 12 fps) идут только пока виджет виден и в Windows не выключена анимация интерфейса; иначе рисуется неподвижный кадр. Фаза берётся из реального времени.
  • Иконки Fluent рисуются из кэша растров по (иконка, цвет, размер, DPR): FluentIcon.render(fill=…) разбирает SVG на каждом вызове.
  • Микроанимации: вспышка строки при добавлении/дублировании/перемещении, пульсирующая точка несохранённых правок, подстраницы въезжают справа, возврат — слева, разделы появляются снизу (PopUpAniStackedWidget qfluentwidgets; текущая страница переключается сразу, анимируется только положение).