Mihomo

mihomo (Clash.Meta) — справочник для zapret-gui

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

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

1. wiki.metacubex.one — официальная документация конфигурации и CLI; MetaCubeX/mihomo (Go-исходники, docs/config.yaml) — окончательная истина по схеме. mihomo — наследник Clash.Meta, форк-линия от Dreamacro/clash.
2. mihomo -t -f <config> — валидатор самого бинаря. Молчит → конфиг валиден для ЭТОЙ версии; ругается — это и есть причина.
3. Наш код — core/mihomo_manager.py (run/test/up/down/status), core/mihomo_config.py + core/mihomo_routing.py (генерация конфигов маршрутизации), core/mihomo_proxies.py (таблица прокси + Clash API), core/mihomo_platform.py (пути), core/mihomo_installer.py + core/mihomo_detector.py (бинарь/арх), core/mihomo_autostart.py, core/mihomo_watchdog.py, core/clash_yaml.py (конвертер clash→sing-box, §10), api/mihomo.py, web/js/pages/mihomo{,_proxies,_setup}.js. Полный список — §17.

⚠️ Пользовательский YAML мы не переписываем. mihomo_manager хранит конфиг как текст, проверяет минимально (валидный YAML + есть proxies или proxy-providers) и отдаёт всё на откуп mihomo -t. Свои конфиги мы генерируем целиком (mihomo_config, §11.1) — но и их валидирует бинарь. Поэтому истина по ключам — официальная вики и исходники, а не наш парсер: он покрывает подмножество YAML (см. §16.8) и «угадывать» поля по нему нельзя.

---

1. Две роли mihomo в zapret-gui (не путать)

1. Standalone движок. mihomo_manager запускает mihomo -d <config_dir> -f <config.yaml> как отдельный прокси-движок (clash-YAML конфиги, свой inbound/DNS/TUN/правила, RESTful API). Это самостоятельная альтернатива sing-box.
2. Конвертер импорта. core/clash_yaml.py — это НЕ про запуск mihomo, а про разбор clash-YAML подписки и конвертацию proxies → sing-box outbounds (§10). Используется, когда пользователь импортирует clash-ссылку, но гоняет трафик через sing-box.

Когда говорят «mihomo не работает» — сначала пойми, о какой роли речь: упавший процесс mihomo (§11–16) или неконвертированный proxy при импорте в sing-box (§10).

---

2. CLI mihomo (что вызываем)

Таблица — только то, что вызываем мы; полный список шире. В v1.19.31 есть ещё -config (конфиг base64-строкой), -ext-ctl-tls/-ext-ctl-unix/ -ext-ctl-pipe/-ext-ctl-routing-mark, -post-up/-post-down (скрипты), -age-secret-key. Почти все дублируются переменными CLASH_* — сверено с main.go mihomo v1.19.31 (с 1.19.29 не изменился).

Запуск у нас: mihomo -d <config_dir> -f <config.yaml> в новой сессии (start_new_session), stdin=DEVNULL, stdout/stderr → лог-файл, RLIMIT_NOFILE=65536, PID → <run_dir>/mihomo-<name>.pid.

---

3. Верхнеуровневые (general) ключи clash-YAML

Источник: wiki.metacubex.one/en/config/general.

Секции: proxies (§4), proxy-groups (§5), rules+rule-providers (§6), proxy-providers (§9), dns (§7), tun+listeners (§8), sniffer (§8.1), hosts, ntp, experimental.

geo-базы (geoip.dat/geosite.dat/*.mmdb) zapret-gui НЕ ставит (в отличие от sing-box). Они лежат в -d-workdir (= config_dir); mihomo сам качает их при старте (geox-url) либо их кладёт пользователь. На роутере без исходящего доступа правила GEOIP/GEOSITE упадут, если баз нет — см. §16.

---

4. Proxies (типы и поля)

mihomo поддерживает: ss (shadowsocks), ssr, snell, vmess, vless, trojan, anytls, mieru, hysteria, hysteria2, tuic, wireguard, tailscale, ssh, http, socks5, плюс direct/dns. Общие поля: name (уникальное), type, server, port, udp, ip-version, interface-name, routing-mark, tfo, mptcp, dialer-proxy, smux.

Ключевые поля по типам (вики, config/proxies):

• vless: uuid, flow (xtls-rprx-vision), network (tcp/ws/grpc/http), tls, servername, client-fingerprint, reality-opts(public-key,short-id), ws-opts(path,headers.Host), grpc-opts(grpc-service-name).
• vmess: uuid, alterId, cipher(auto), network, tls, servername, ws-opts.
• trojan: password, sni, skip-cert-verify, network, ws-opts.
• ss: cipher, password, udp, опц. plugin/plugin-opts.
• hysteria2: password(или auth), sni, skip-cert-verify, up/down, obfs/obfs-password.
• tuic: uuid, password, sni, alpn, congestion-controller.
• wireguard: private-key, peers/public-key, allowed-ips, reserved, и — важно — amnezia-wg-option (mihomo умеет AmneziaWG-обфускацию прямо в wireguard-outbound; см. skill awg про сами параметры).

---

5. Proxy-groups

Типы: select, url-test, fallback, load-balance, relay. Поля: name, type, proxies, use (имена proxy-providers), url, interval, tolerance, lazy, timeout, max-failed-times, filter, exclude-filter, include-all / include-all-proxies / include-all-providers, disable-udp, hidden, icon. У load-balance — strategy (round-robin/consistent-hashing/sticky-sessions).

---

6. Rules и rule-providers

Формат правила: ТИП,аргумент,цель[,модификатор]. Цель — имя proxy/группы, DIRECT, REJECT, PASS.

Типы (вики, config/rules): DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD, DOMAIN-REGEX, GEOSITE, IP-CIDR, IP-CIDR6, IP-SUFFIX, IP-ASN, GEOIP, SRC-GEOIP, SRC-IP-CIDR, SRC-PORT, DST-PORT, IN-PORT, IN-TYPE, IN-USER, NETWORK (tcp/udp), DSCP, PROCESS-NAME, PROCESS-PATH, RULE-SET, AND/OR/NOT, SUB-RULE, MATCH (последнее, ловит всё). Модификаторы: no-resolve (не резолвить для IP-правил), src (матчить source IP). Примеры: DOMAIN-SUFFIX,google.com,PROXY · IP-CIDR,127.0.0.0/8,DIRECT,no-resolve · GEOIP,CN,DIRECT · MATCH,PROXY.

rule-providers — внешние списки правил: type (http/file/inline), behavior (domain/ipcidr/classical), format (yaml/text/mrs), url, path, interval. Ссылаются из rules через RULE-SET,<name>,<цель>.

---

7. DNS (включая fake-ip)

Ключи (вики, config/dns): enable, listen, ipv6, prefer-h3, enhanced-mode (fake-ip / redir-host), fake-ip-range (дефолт 198.18.0.1/16), fake-ip-filter + fake-ip-filter-mode (blacklist/whitelist/rule), default-nameserver (только IP — ими резолвятся хостнеймы других DNS), nameserver, fallback, fallback-filter (geoip,geoip-code,geosite,ipcidr,domain), nameserver-policy, proxy-server-nameserver (резолв доменов прокси-узлов), direct-nameserver, use-hosts, use-system-hosts, respect-rules.

Схемы nameserver (parseNameServer, v1.19.31): udp://, tcp://, tls://(DoT), http:///https://(DoH), quic://(DoQ), system, dhcp, rcode://, success://, а также резолв через оверлей — ts:///tailscale:// и et:///easytier:// (последний с v1.19.31); после схемы там идёт имя прокси, а не адрес. Суффикс # задаёт параметры сервера (например #proxy — гонять DNS-запрос по правилам/через прокси, &ecs=… — EDNS Client Subnet).

fake-ip — аналог singbox-fakeip: доменам выдаются адреса из fake-ip-range, маршрутизация идёт по ним, по правилам восстанавливается домен. На роутере это самый надёжный доменный роутинг, но требует, чтобы DNS LAN-клиентов доходил до mihomo (TUN dns-hijack или REDIRECT :53).

---

8. TUN / прозрачное проксирование / listeners

tun (вики, config/inbound): enable, stack (system/gvisor/mixed/ mips, дефолт gvisor), device, auto-route (прописать маршруты, чтобы трафик шёл в TUN), auto-redirect (nft-redirect для ПЕРЕсылаемого трафика LAN; только Linux+nftables, вместе с auto-route), auto-detect-interface, dns-hijack (например ["any:53"]; без схемы подразумевается udp://), mtu, strict-route, route-address / route-address-set / route-exclude-address-set (последние два — только nftables при auto-route+auto-redirect), gso/gso-max-size (дефолт 65536), disable-icmp-forwarding, endpoint-independent-nat, udp-timeout (300 c), iproute2-table-index (2022) / iproute2-rule-index (9000), устаревшие inet4-address/inet4-route-address.

🆕 processors-per-channel — с v1.19.31 (RawTun, помечено в коде как непубличное и в документацию апстрима не вынесено). Число обработчиков на канал gvisor, дефолт 1 с прямым комментарием апстрима: «для большинства память важнее пиковой производительности». Для наших роутеров дефолт и нужен — трогать его стоит только если упираемся в CPU при избытке памяти.

🆕 stack: mips — с v1.19.31 (constant/tun.go, реализация — metacubex/mipstack). Отдельный userspace-стек, заявленный как облегчённый; ровно тот случай, ради которого мы вообще держим выбор стека: на слабых MIPS-роутерах (Keenetic) gvisor раздувает буферы и жжёт CPU, а system ловит не весь трафик. Наш UI его пока не предлагает — селектор стека в web/js/pages/mihomo.js (stackSelectHtml) жёстко перечисляет gvisor/system/mixed. Добавлять надо вместе с гейтом по версии: на mihomo < 1.19.31 значение mips конфиг не примет (mihomo -t отдаст ошибку разбора stack).

device по умолчанию — Meta, а не utun. В listener/sing_tun/server.go: var InterfaceName = "Meta", и CalculateInterfaceName() на не-darwin возвращает это имя как есть (префикс utun — исключительно macOS). Значит конфиг с tun: {enable: true} без device создаёт интерфейс Meta. Мы на это опираемся в core/mihomo_config.tun_device_from_text() — правило маршрутизации должно указывать на реальное имя, иначе оно молча ни во что не заворачивает.

listeners (доп. входящие): http, socks, mixed, redir, tproxy, tunnel, tun, а также серверные shadowsocks/vmess/vless/trojan/tuic.

Прозрачный режим через ОС (iptables/nft-правила) у нас завязан на sing-box (core/singbox_transparent*) и Selective routing (core/routing). Для mihomo мы TUN не настраиваем на уровне ОС — движок делает это сам (auto-route/auto-redirect), а секцию tun в конфиге генерируем (core/mihomo_config.make_tun(), флоу «Маршрутизация» на странице mihomo). Дополнительно детектим /dev/net/tun (mihomo_detector).

8.1 sniffer — как движок узнаёт домен

sniffer определяет домен по содержимому соединения (TLS SNI / HTTP Host), когда его неоткуда взять иначе. Ключи и дефолты сверены с config/config.go v1.19.31 (DefaultRawConfig):

⚠️ Когда fake-ip не спасает. Доменные правила (DOMAIN-SUFFIX, GEOSITE) матчатся, только если движок знает домен. При enhanced-mode: fake-ip он его знает — но лишь для клиентов, чей DNS идёт через сам mihomo. Приложение со своим DoH/DoT (браузер с DNS-over-HTTPS, opera-proxy, usque) резолвит мимо движка, и mihomo видит только IP — доменное правило не сработает. Единственное лекарство — sniffer. Именно поэтому core/opera_proxy_chain._attach_mihomo() при подключении opera-proxy в TUN-конфиг включает сниффер: без него защита от петли DOMAIN-SUFFIX,sec-tunnel.com,DIRECT мертва и трафик самого прокси уходит в туннель по кругу.

override-destination при fake-ip ставь в false. Дефолт true подменяет назначение сниффнутым доменом и ломает уже корректную fake-ip-маршрутизацию; для матчинга правил подмена не нужна — домен попадает в метаданные соединения в любом случае.

Без PyYAML _attach_mihomo() делает не всё — и это штатно. Правка rules и sniffer идёт полным round-trip'ом (mihomo_proxies.safe_mutate), а он требует PyYAML: самописный парсер теряет вложенность и скалярные списки, и перезапись повредила бы конфиг. На роутере с python3-light PyYAML обычно нет, поэтому там:

Отказ обязан говорить про opera-proxy, а не отдавать общий текст safe_mutate (тот писался под удаление прокси из таблицы и в ответе на «подключить» уводит пользователя не туда). Оба режима закреплены тестами: TestAttachMihomo (под skipUnless(has_pyyaml())) и TestAttachMihomoWithoutPyYAML (подменяет has_pyyaml и потому гоняется везде).

---

9. proxy-providers (подписки)

Внешние источники прокси: type (http/file/inline), url, path, interval, proxy (через какой прокси качать), header, health-check (enable,url,interval,lazy,expected-status), override (additional-prefix/-suffix, skip-cert-verify, udp, …), filter, exclude-filter, exclude-type, dialer-proxy. Подключаются в группах через use: [<provider>] или include-all-providers.

---

10. Наш конвертер clash-YAML → sing-box (core/clash_yaml.py)

Это отдельная функция (импорт clash-подписки в движок sing-box), не запуск mihomo. Мини-парсер YAML + реестр конвертеров _CLASH_CONVERTERS.

Конвертируются 6 типов (clash-proxy → sing-box outbound):

НЕ конвертируются — узел попадает в skipped с причиной «неподдерживаемый тип» (не теряется молча: список отдаётся вызывающему и показывается в GUI). Но причины у разных типов разные, и это важно:

Список типов сверен с adapter/parser.go mihomo v1.19.31 и каталогами docs/configuration/outbound/ + docs/configuration/endpoint/ sing-box v1.14.1. Апстрим mihomo добавляет протоколы заметно быстрее — при следующей сверке проверять, не появился ли аналог у обоих (так и вышло со snell и openvpn: sing-box 1.14 их принёс). Счёт на v1.19.31 — grep -oE 'case "[a-z0-9]+"' adapter/parser.go | sort -u: 27 веток, из них 3 служебных (direct/dns/reject) → 24 типа прокси, конвертируем 6. (На v1.19.30 было 23 — прибавился easytier.)

Нюанс YAML: short-id: 01 парсится как int 1 — конвертер обрабатывает это best-effort, чтобы не потерять ведущий ноль. proxy-groups/rules при таком импорте не переносятся — берутся только узлы. Тесты: tests/test_clash_yaml.py.

---