Перейти к содержанию

API

Пример запроса

Пример curl curl -H 'Authorization: Bearer ${secret}' http://${controller-api}/configs?force=true -d '{"path": "", "payload": ""}' -X PUT

Этот запрос содержит заголовок 'Authorization: Bearer ${secret}', где:

  • ${secret} - ключ API, заданный в разделе API конфигурационного файла
  • ${controller-api} - адрес прослушивания, заданный в разделе API конфигурационного файла
  • ?force=true - параметр, который требуется для некоторых запросов
  • '{"path": "", "payload": ""}' - данные обновляемого ресурса

Note

Если необходимо передать путь за пределами рабочего каталога mihomo, вручную добавьте его в безопасные пути с помощью переменной среды SAFE_PATHS. Она разбирается по правилам системной переменной PATH: элементы разделяются точкой с запятой в Windows и двоеточием в других системах.

Логи

/logs

Получение логов в реальном времени

  • Метод запроса: GET / WS
  • Необязательный параметр: ?level=log_level, где log_level может быть info, warning, error, debug
  • Необязательный параметр: ?format=structured, при наличии выводит структурированные логи (с полями time, level, message, fields)
  • Поля ответа в стандартном режиме (один объект JSON на строку):
    • type: уровень логирования - info / warning / error / debug
    • payload: текст сообщения журнала
  • Поля ответа в структурированном режиме ?format=structured:
    • time: время в формате HH:MM:SS
    • level: уровень логирования
    • message: текст сообщения журнала
    • fields: массив дополнительных полей

Информация о трафике

/traffic

Получение информации о трафике в реальном времени: up/down измеряются в байтах/с, upTotal/downTotal - в байтах

  • Метод запроса: GET / WS
  • Поля ответа (отправляются раз в секунду):
    • up: текущая скорость исходящего трафика (байт/с)
    • down: текущая скорость входящего трафика (байт/с)
    • upTotal: суммарное количество отправленных байтов
    • downTotal: суммарное количество полученных байтов

Информация о памяти

/memory

Получение информации об использовании памяти в реальном времени, в байтах

  • Метод запроса: GET / WS
  • Поля ответа (отправляются раз в секунду):
    • inuse: текущий объем используемой памяти (байты)
    • oslimit: системное ограничение памяти (байты, всегда 0)

Информация о версии

/version

Получение версии mihomo

  • Метод запроса: GET
  • Поля ответа:
    • meta: является ли сборка версией Meta (true / false)
    • version: строка версии

Кэш

/cache/fakeip/flush

Очистка кэша fakeip

  • Метод запроса: POST
  • Ответ отсутствует (HTTP 204)

/cache/dns/flush

Очистка кэша DNS

  • Метод запроса: POST
  • Ответ отсутствует (HTTP 204)

Рабочая конфигурация

/configs

Получение базовой конфигурации

  • Метод запроса: GET
  • Поля ответа: JSON-объект текущей рабочей конфигурации, включая port, socks-port, mixed-port, mode, log-level, allow-lan, ipv6, tun и другие поля

Перезагрузка базовой конфигурации

  • Метод запроса: PUT
  • Параметр: ?force=true
  • Ответ отсутствует (HTTP 204)

Обновление базовой конфигурации

  • Метод запроса: PATCH
  • Данные: '{"mixed-port": 7890}'
  • Ответ отсутствует (HTTP 204)

/configs/geo

Обновление GEO базы данных

  • Метод запроса: POST
  • Данные: '{"path": "", "payload": ""}'
  • Ответ отсутствует (HTTP 204)

/restart

Перезапуск ядра

  • Метод запроса: POST
  • Данные: '{"path": "", "payload": ""}'
  • Ответ отсутствует (HTTP 204)

Обновления

/upgrade

Обновление ядра

  • Метод запроса: POST
  • Необязательные параметры: ?channel=xxx задаёт канал обновления, ?force=true принудительное обновление
  • Данные: '{"path": "", "payload": ""}'
  • Поля ответа:
    • status: фиксированное значение "ok"

/upgrade/ui

Обновление панели управления, требуется настройка external-ui

  • Метод запроса: POST
  • Поля ответа:
    • status: фиксированное значение "ok"

/upgrade/geo

Обновление GEO базы данных

  • Метод запроса: POST
  • Данные: '{"path": "", "payload": ""}'
  • Ответ отсутствует (HTTP 204)

Группы политик

/group

Получение информации о группах политик

  • Метод запроса: GET
  • Поля ответа:
    • proxies: массив объектов групп политик; формат каждого объекта совпадает с ответом /proxies/proxies_name

/group/group_name

Получение информации о конкретной группе политик

  • Метод запроса: GET
  • Поля ответа: объект группы политик в формате /proxies/proxies_name

/group/group_name/delay

Тестирование узлов/групп политик в указанной группе политик, возвращает новую информацию о задержке и очищает фиксированный выбор автоматической группы политик

  • Метод запроса: GET
  • Параметр: ?url=xxx&timeout=5000
  • Необязательный параметр: ?expected=xxx, ожидаемый код состояния HTTP-ответа, поддерживает диапазоны (например, 200/204, 200-299)
  • Поля ответа: JSON-объект, сопоставляющий имена узлов с задержкой в миллисекундах (uint16), например {"Узел A": 120, "Узел B": 350}

Прокси

/proxies

Получение информации о прокси

  • Метод запроса: GET
  • Поля ответа:
    • proxies: объект, ключами которого являются имена прокси или групп; каждая запись содержит следующие общие поля:
      • name: имя прокси или группы
      • type: тип, например Shadowsocks, VMess, DIRECT, Selector, URLTest, Fallback, LoadBalance
      • udp: поддерживается ли UDP
      • uot: поддерживается ли UDP over TCP
      • xudp: поддерживается ли XUDP
      • tfo: включен ли TCP Fast Open
      • mptcp: включен ли MPTCP
      • smux: включено ли мультиплексирование потоков
      • alive: доступен ли прокси в данный момент
      • history: массив записей истории задержек с полями time и delay (мс)
      • extra: дополнительная история задержек, сгруппированная по URL тестирования
      • interface: имя привязанного сетевого интерфейса
      • routing-mark: значение метки маршрутизации
      • provider-name: имя провайдера, которому принадлежит прокси
      • dialer-proxy: имя нижележащего dialer-прокси
    • Группы политик (Selector, URLTest, Fallback, LoadBalance) дополнительно содержат:
      • now: имя выбранного сейчас узла (отсутствует у LoadBalance)
      • all: массив имен всех узлов и групп
      • testUrl: URL проверки работоспособности
      • hidden: скрыта ли группа в панели управления
      • icon: URL значка
      • emptyFallback: имя резервного узла, используемого при недоступности всех участников
      • expectedStatus: ожидаемый код HTTP-ответа при проверке (отсутствует у Selector)
      • fixed: закрепленный сейчас узел (только для URLTest и Fallback)

/proxies/proxies_name

Получение информации о конкретном прокси

  • Метод запроса: GET
  • Поля ответа: объект прокси или группы с полями одной записи из /proxies; обычные прокси содержат только общие поля, а группы политик также содержат now, all и другие поля группы

Выбор конкретного прокси

  • Метод запроса: PUT
  • Данные: '{"name":"Япония"}'
  • Ответ отсутствует (HTTP 204)

Очистка фиксированного (fixed) выбора прокси/группы политик (кроме типа Selector)

  • Метод запроса: DELETE
  • Ответ отсутствует (HTTP 204)

/proxies/proxies_name/delay

Тестирование указанного прокси и возврат новой информации о задержке

  • Метод запроса: GET
  • Параметр: ?url=xxx&timeout=5000
  • Необязательный параметр: ?expected=xxx, ожидаемый код состояния HTTP-ответа, поддерживает диапазоны (например, 200/204, 200-299)
  • Поля ответа:
    • delay: измеренная задержка в миллисекундах (uint16)

Наборы прокси

/providers/proxies

Получение всей информации о всех наборах прокси

  • Метод запроса: GET
  • Поля ответа:
    • providers: объект, ключами которого являются имена провайдеров; каждая запись содержит метаданные провайдера и список его прокси

/providers/proxies/providers_name

Получение информации о конкретном наборе прокси

  • Метод запроса: GET
  • Поля ответа: объект провайдера прокси, включающий метаданные конфигурации и список proxies

Обновление набора прокси

  • Метод запроса: PUT
  • Ответ отсутствует (HTTP 204)

/providers/proxies/providers_name/healthcheck

Запуск проверки работоспособности конкретного набора прокси

  • Метод запроса: GET
  • Ответ отсутствует (HTTP 204)

/providers/proxies/providers_name/proxies_name

Получение информации об указанном прокси в наборе прокси

  • Метод запроса: GET
  • Поля ответа: объект прокси с теми же полями, что и /proxies/proxies_name

/providers/proxies/providers_name/proxies_name/healthcheck

Тестирование указанного прокси в наборе прокси и возврат новой информации о задержке

  • Метод запроса: GET
  • Параметр: ?url=xxx&timeout=5000
  • Поля ответа:
    • delay: измеренная задержка в миллисекундах (uint16)

Правила

/rules

Получение информации о правилах

  • Метод запроса: GET
  • Поля ответа:
    • rules: массив объектов правил, каждый из которых содержит:
      • index: индекс правила, начиная с 0
      • type: тип правила, например DOMAIN, IP-CIDR, GEOIP
      • payload: содержимое условия правила
      • proxy: имя целевого прокси или группы политик
      • size: количество записей в наборе правил (только для GEOIP / GEOSITE, в остальных случаях -1)
      • extra (необязательно) содержит:
        • disabled: отключено ли правило
        • hitCount: количество совпадений с правилом
        • hitAt: время последнего совпадения
        • missCount: количество несовпадений с правилом
        • missAt: время последнего несовпадения

/rules/disable

Отключение правил: ключом служит индекс правила, а значением - признак его отключения. Это временная операция, которая сбрасывается после перезапуска.

  • Метод запроса: PATCH
  • Данные: '{"0": false,"1": true}'
  • Ответ отсутствует (HTTP 204)

Наборы правил

/providers/rules

Получение всей информации о всех наборах правил

  • Метод запроса: GET
  • Поля ответа:
    • providers: объект, ключами которого являются имена провайдеров правил

/providers/rules/providers_name

Обновление набора правил

  • Метод запроса: PUT
  • Ответ отсутствует (HTTP 204)

Соединения

/connections

Получение информации о соединениях

  • Метод запроса: GET / WS
  • Необязательный параметр: ?interval=milliseconds, где milliseconds - интервал обновления, стандартное значение 1000 миллисекунд
  • Поля ответа:
    • downloadTotal: суммарное количество полученных байтов
    • uploadTotal: суммарное количество отправленных байтов
    • memory: текущий объем используемой памяти (байты)
    • connections: массив объектов активных соединений, каждый из которых содержит:
      • id: уникальный идентификатор соединения
      • metadata: метаданные соединения (адреса источника и назначения, протокол, имя процесса и т. д.)
      • upload: количество байтов, отправленных через это соединение
      • download: количество байтов, полученных через это соединение
      • start: время начала соединения
      • chains: массив цепочки прокси
      • providerChains: массив цепочки провайдеров прокси
      • rule: тип совпавшего правила
      • rulePayload: содержимое совпавшего правила

Закрытие всех соединений

  • Метод запроса: DELETE
  • Ответ отсутствует (HTTP 204)

/connections/:id

Закрытие конкретного соединения

  • Метод запроса: DELETE
  • Ответ отсутствует (HTTP 204)

DNS запросы

/dns/query

Получение данных DNS запроса для указанного имени и типа

  • Метод запроса: GET
  • Параметр: ?name=example.com&type=A
  • Поля ответа:
    • Status: код DNS-ответа (Rcode)
    • Question: массив вопросов запроса
    • TC: был ли ответ усечен
    • RD: флаг запроса рекурсии
    • RA: флаг доступности рекурсии
    • AD: флаг аутентифицированных данных
    • CD: флаг отключения проверки
    • Answer (необязательно): массив записей ответа с полями name, type, TTL, data
    • Authority (необязательно): массив авторитетных записей в том же формате, что и Answer
    • Additional (необязательно): массив дополнительных записей в том же формате, что и Answer

Хранилище

/storage/key

Получение значения хранилища по указанному ключу, возвращает null, если не существует

  • Метод запроса: GET
  • Поля ответа: любое сохраненное допустимое значение JSON или null, если ключ не существует

Запись значения хранилища по указанному ключу, данные должны быть корректным JSON, максимум 1 МБ

  • Метод запроса: PUT
  • Данные: '{"foo": "bar"}'
  • Ответ отсутствует (HTTP 204)

Удаление значения хранилища по указанному ключу

  • Метод запроса: DELETE
  • Ответ отсутствует (HTTP 204)

DEBUG

/debug требует, чтобы при запуске ядра уровень логирования был установлен на debug.

/debug/gc

Запуск принудительной сборки мусора

  • Метод запроса: PUT
  • Ответ отсутствует (HTTP 204)

/debug/pprof

Открыв в браузере http://${controller-api}/debug/pprof, можно просмотреть исходную отладочную информацию, где:

  • allocs показывает ситуацию с выделением памяти для каждого вызова функции, включая размер памяти, выделенной в стеке и куче, а также количество выделений памяти. Этот отчет в основном помогает находить проблемы с утечками памяти и частыми запросами на выделение памяти в коде.
  • отчет heap предоставляет подробную информацию об использовании памяти в куче программой, включая размер, количество и адреса выделенных блоков памяти, отсортированных по размеру. Этот отчет в основном используется для поиска мест с высоким использованием памяти, можно просмотреть размеры объектов в отчете heap, чтобы найти места с высоким использованием памяти.

Установите Graphviz, чтобы просматривать графическую отладочную информацию

Просмотр графического отчета Heap
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/heap

Полное изображение

Просмотр графического отчета Allocs
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/allocs

Пример вывода

Отправка отчета

Откройте в браузере http://${controller-api}/debug/pprof/heap?raw=true, чтобы загрузить этот файл, и загрузите его в issues, чтобы сообщить о проблеме, с которой вы столкнулись.