Конфигурация mihomo: структура файла config.yaml

Файл config.yaml — это всё, что ядро mihomo знает о вашей сети: какие порты слушать, через какие серверы ходить, как обрабатывать имена доменов и по каким правилам делить трафик. Клиенты с графическим интерфейсом прячут его за кнопками, но под капотом читают именно этот текстовый файл.

Понимание структуры окупается быстро: становится ясно, что именно приходит из подписки, где искать причину ошибки при загрузке профиля и какие поля можно править самому. Разберём синтаксис, основные секции и минимальный рабочий пример, который запускается как есть.

Правила YAML, на которых спотыкаются чаще всего

YAML — формат, чувствительный к оформлению. Четыре правила закрывают почти все ошибки новичков:

• Отступы — только пробелы. Символ табуляции недопустим; редактор должен подставлять пробелы. Вложенность обозначается именно отступом, обычно в два пробела.
• После двоеточия нужен пробел. Запись mode:rule ошибочна, правильно mode: rule.
• Элементы списка начинаются с дефиса и пробела: - MATCH,PROXY.
• Осторожно с копированием из мессенджеров и документов. Оттуда легко принести «умные» кавычки, неразрывные пробелы или переносы строк, которые парсер не понимает.

Ещё две мелочи экономят время. Строка, начинающаяся с #, — комментарий: им удобно временно отключить правило, не удаляя его. А значения, в которых есть двоеточие, решётка или ведущий ноль, лучше брать в кавычки: пароль вида 12:34 без кавычек парсер попробует прочитать не как текст. Имена узлов и групп в кавычки заключают по той же причине — в них часто попадают пробелы и символы оформления.

Основные поля верхнего уровня

Конфигурация состоит из секций верхнего уровня, каждая отвечает за свою область:

В конфигурациях от провайдеров встречается и множество дополнительных полей, но перечисленных достаточно, чтобы ядро запустилось и заработало. Не указанные явно параметры берутся из значений по умолчанию, так что короткий файл — это нормально: отсутствие секции означает «оставить как есть», а не ошибку. Порядок секций верхнего уровня тоже произвольный, хотя привычка держать сетевые настройки сверху, а длинный список правил внизу заметно облегчает чтение.

Два поля заслуживают отдельной осторожности. allow-lan открывает ваш прокси другим устройствам сети — включайте его сознательно и только в доверенной сети. external-controller публикует управляющий API: адрес 127.0.0.1 означает доступ только с этой машины, и на любом устройстве, смотрящем в интернет, менять его на внешний адрес не стоит.

Минимальная рабочая конфигурация

Такой файл можно сохранить как config.yaml и сразу запустить: подставьте данные своего сервера в секцию proxies.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

proxies:
  - name: "server-1"
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-256-gcm
    password: "your-password"

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "server-1"
      - DIRECT

rules:
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

Номер порта здесь приведён для примера — в профилях провайдеров встречаются и другие значения, посмотрите своё поле mixed-port. Значения DIRECT и REJECT писать в секции proxies не нужно: это встроенные адресаты, доступные всегда.

Как связаны proxies, proxy-groups и rules

Три секции образуют цепочку, и понимание её порядка снимает большинство вопросов. Сначала proxies описывает конкретные серверы — это «сырьё». Затем proxy-groups собирает серверы в группы: одна группа переключается вручную, другая сама выбирает узел по задержке. Наконец, rules направляет соединение — и указывает не сервер, а обычно имя группы.

Такой порядок объясняет типичную ошибку: если в правиле указано имя, которого нет ни среди серверов, ни среди групп, ядро откажется загружать конфигурацию целиком. О видах групп читайте в разборе групп прокси, о синтаксисе правил — в статье про правила маршрутизации.

Откуда берётся config.yaml в графическом клиенте

Писать этот файл руками приходится далеко не всем. Когда вы добавляете ссылку подписки, клиент скачивает по ней готовую конфигурацию, сохраняет её как локальный профиль и передаёт ядру. Всё, что вы видите в интерфейсе — списки узлов, группы, правила, — пришло именно оттуда.

Из этого следует практический вывод, о который спотыкаются многие. Правки, внесённые прямо в скачанный профиль, живут до следующего обновления подписки: клиент заменит файл новой версией, и изменения исчезнут. Поэтому постоянные дополнения оформляют средствами клиента — отдельным локальным профилем или механизмом расширения конфигурации, который сохраняется между обновлениями. Названия таких разделов отличаются от версии к версии, но принцип общий: не трогайте загруженный файл, добавляйте своё поверх него.

Проверка конфигурации перед запуском

У ядра есть режим проверки: он разбирает файл и сообщает об ошибке, ничего не запуская.

mihomo -t -f config.yaml

Это первое, что стоит выполнять после любой ручной правки. Сообщение содержит номер строки и характер проблемы, поэтому поиск занимает секунды. Типичных причин отказа немного:

1. Неверный отступ — элемент оказался не в той секции; проверьте выравнивание соседних строк.
2. Повторяющийся ключ — одна и та же секция описана дважды, чаще всего после копирования фрагментов из разных источников.
3. Дублирование имён — два сервера или две группы с одинаковым name.
4. Ссылка на несуществующую группу в правиле или внутри другой группы.

Когда базовая конфигурация запускается, логичный следующий шаг — секция dns: она заметно влияет и на скорость открытия сайтов, и на корректность маршрутизации. Её разбор есть в руководстве по настройке DNS в mihomo.