HTTP API управления и веб-консоль

[General]
external-http-controller = 127.0.0.1:9090
external-http-secret = your-secret-token
external-http-ui = true
external-http-cors = false

Chute предоставляет встроенный HTTP API управления и веб-консоль, аналогичный панелям Clash и Surge. API предоставляет статус движка, трафик, соединения, DNS, управление политиками и управление конфигурацией через конечные точки REST.

Запись Surge http-api = <секрет>@<хост>:<порт> читается как external-http-controller плюс external-http-secret. Части можно записать и по отдельности: http-api-secret, http-api-ui и http-api-cors читаются как external-http-secret, external-http-ui и external-http-cors, а http-api-web-dashboard — тоже как external-http-ui; конфигурация сохраняется с ключами external-http-*. http-api-tls не поддерживается — контроллер работает по обычному HTTP — и вызывает лишь уведомление.

external-http-controller (По умолчанию: отключено)

external-http-controller = 127.0.0.1:9090

Запросы, которые консоль держит в памяти во время обслуживания, ограничены 4 МБ на macOS и 1 МБ на iOS, tvOS и Android.

Адрес и порт HTTP-контроллера. Для доступа только с этой машины используйте 127.0.0.1. Привязка к любому адресу вне петли (например, 192.168.1.5:9090) требует явно заданного external-http-secret — без него сервер откажется запускаться и запишет в журнал, чего не хватает.

Шаблонный адрес (0.0.0.0, ::, *) в этой проверке считается не-петлевым: он слушает все интерфейсы, то есть противоположность «только локально». Допустимые написания — 0.0.0.0:9090, *:9090 (то же самое) и для IPv6 [::]:9090; голое :::9090 берётся в скобки автоматически, а адрес, который не удаётся разобрать, сообщается как ошибка конфигурации, вместо того чтобы молча оставить контроллер выключенным. Петлевым считается весь диапазон 127.0.0.0/8, а не только 127.0.0.1.

external-http-secret (По умолчанию: сгенерированный токен)

external-http-secret = your-secret-token

Bearer-токен для аутентификации API. Запросы должны содержать заголовок Authorization: Bearer <secret> — токен принимается только в этом заголовке, никогда как параметр запроса, и сравнивается за постоянное время. При неудачной аутентификации возвращается 401 с {"ok": false, "error": {"code": "unauthorized", "message": "missing or invalid token"}}. Защищены все маршруты данных: пути /api/*, Clash-совместимые псевдонимы и более старые маршруты, которые по-прежнему предоставляет только Chute Android (/status, /policies, /dns, /records и подобные), — они тоже принимают токен только в этом заголовке. Собственная удалённая панель Chute Android теперь пользуется только путями /api/*. Странице и статическим файлам веб-консоли (/, /assets/…, а на Chute Android также /ui) токен не нужен (при external-http-ui = false их нет вовсе — страница отвечает 404).

Если ключ отсутствует, Chute генерирует токен, а не отдаёт API без аутентификации. Сгенерированный токен записывается в файл control-token в общей папке Chute — не рядом с конфигурацией: в контейнер группы приложений на iOS и tvOS, в закрытый каталог данных приложения на Android — с правами только для владельца, переиспользуется после перезапуска, и приложения показывают его — см. Открытие веб-консоли. Управляющий API может выдать базу соединений, записи которой содержат каждый URL, заголовок и имя процесса, встреченные за этот запуск; открытый контроллер — неразумное значение по умолчанию.

Если всё же нужно отдавать API без аутентификации, скажите это в конфигурации явно:

external-http-secret = none

Это принимается только при привязке к петле. Вне петли не хватит ни none, ни отсутствия ключа: контроллер откажется запускаться и скажет, что ему нужно.

При обновлении: если вы полагались на то, что отсутствие external-http-secret означает «без аутентификации», локальные скрипты начнут получать 401. Либо прочитайте сгенерированный токен в приложении, либо напишите external-http-secret = none, чтобы намеренно сохранить прежнее поведение.

external-http-ui (По умолчанию: true)

external-http-ui = true

Если включено, Chute предоставляет встроенную веб-консоль по адресу контроллера. Веб-консоль предоставляет обзор, управление соединениями, проверку DNS, мониторинг трафика, управление политиками и редактирование конфигурации. Установите false, чтобы сохранить API включённым, отключив интерфейс.

Открытие веб-консоли

Консоль отдаётся по адресу контроллера, и каждое приложение может передать вам адрес и токен — включая сгенерированный, прочитать который иначе негде:

  • Chute Mac: строка меню → Открыть веб-консоль и Копировать токен веб-консоли. В окне сведений о соединении также есть Запросы и история, открывающая консоль — её главную страницу, а не это соединение.
  • Chute iOS: панель управления → строка Веб-консоль → Открыть, Копировать адрес или Копировать токен доступа.
  • Chute tvOS: в панели управления есть отдельная строка Адрес веб-консоли, показывающая хост и порт. При её выборе показывается QR-код, если слушатель доступен с других устройств — токен входа спрятан внутри кода, а не на экране, — а если контроллер привязан к петлевому адресу, вместо него выводится объяснение: петлевую консоль с телефона не открыть.
  • Chute Android: панель управления → Адрес веб-консоли → Открыть или Копировать адрес, а строка Сгенерированный токен доступа копирует токен по нажатию. Ни одна из этих строк не появляется, если токен — заданный вами секрет: его никогда не показывают.

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


external-http-cors (По умолчанию: false)

external-http-cors = true

Включает заголовки CORS (Cross-Origin Resource Sharing) в ответах API. Полезно, когда веб-консоль или сторонние инструменты должны получать доступ к API из другого источника.

Конечные точки API:

Метод Конечная точка Описание
GET /api/status Статус выполнения, порты, время работы
GET /api/traffic Глобальные счётчики трафика и счётчики по каждой политике
GET /api/connections Текущие активные соединения
DELETE /api/connections/:id Закрыть соединение
GET /api/connections/history История записей соединений
GET /api/connections/processes Статистика соединений по процессам
GET /api/connections/:id/request Захваченные данные запроса для соединения
GET /api/connections/:id/response Захваченные данные ответа для соединения
GET /api/dns Записи кэша DNS
DELETE /api/dns/cache Очистить кэш DNS
DELETE /api/dns/records/:domain Удалить одну DNS-запись
GET /api/config Текущая конфигурация
PUT /api/config Перезагрузить конфигурацию
POST /api/config/validate Разобрать конфигурацию и сообщить об ошибках, не загружая её
GET /api/policies Группы политик и текущий выбор; каждый элемент несёт hidden, равный true для группы с hidden=true
PUT /api/policies/:group Изменить выбор группы политик
PUT /api/mode Установить режим исходящих соединений
GET /api/features Состояния переключателей функций
PUT /api/features/mitm Переключить MitM
PUT /api/features/record-traffic Переключить запись трафика
GET /api/rules Таблица правил, которую проходит сопоставитель, происхождение каждого правила и сработавшие правила перезаписи
POST /api/rules/match Куда был бы смаршрутизирован запрос, не отправляя его
GET /api/rules/user Правила, добавленные во время работы, которые сопоставляются раньше модулей и конфигурации
PUT /api/rules/user Заменить правила, добавленные во время работы
POST /api/rules/user Добавить правила после правил, добавленных во время работы
DELETE /api/rules/user Удалить все правила, добавленные во время работы
GET /api/logs Последние записи журнала
GET /api/loglevel Текущий уровень журнала и записываемые разделы
PUT /api/loglevel Сменить уровень журнала или разделы без перезапуска
GET /api/health Состояние движка: отказы, поколения, потребление памяти, предыдущее завершение
GET /api/events Заметные события этого запуска
GET /api/tailscale Текущее состояние движка Tailscale
GET /api/scripts Скрипты generic, которые можно запустить по требованию
POST /api/scripts/run Запустить один скрипт generic по имени
POST /api/diagnostics/ping Проверка доступности по ICMP или TCP
POST /api/diagnostics/dns-query Разрешить домен через работающий резолвер
POST /api/diagnostics/egress-probe Проверить адрес: на движках Apple — собственные адреса устройства; на Android — публичный адрес устройства в его физической сети, а не выход прокси
POST /api/diagnostics/internet-test Прямая проверка Интернета: загрузить internet-test-url без прокси
POST /api/diagnostics/url-test/:policy Запустить тест задержки политики
POST /api/diagnostics/bundle Собрать очищенный диагностический архив
GET /api/connections/export Экспорт соединений в HAR 1.2
GET /api/rewrites Все семейства перезаписи/имитации ответов и список хостов MitM
GET /api/rewrites/:family Правила одного семейства
POST /api/rewrites/:family Добавить правило
DELETE /api/rewrites/:family/:id Удалить правило
DELETE /api/rewrites/:family Очистить семейство
GET /api/mitm/hosts Хосты, которые сейчас расшифровываются
POST /api/mitm/hosts Добавить хост
DELETE /api/mitm/hosts/:host Удалить хост
DELETE /api/mitm/hosts Очистить список
GET /api/rules/providers Провайдеры правил и наборы правил со статусом каждого — включая причину, по которой один из них не загрузился

Примечания к конечным точкам:

  • GET /api/features сообщает каждый переключатель так, как он выставлен, — record_traffic, mitm, mitm_h2, mitm_auto_quic_block, rewrite — и licensed. effective говорит, что действительно работает, и только для пяти пунктов: record_traffic, mitm, rewrite, scripts и lan_proxy. В бесплатной версии все пять равны false, поэтому переключатель может показывать включённое состояние, тогда как его запись в effective равна false. inactive — объект, называющий то, что запрашивает работающая конфигурация, но что не работает в этой версии: счётчики scripts, scriptRules, dnsScripts, rewrites и mapLocals и флаги mitm, bodyCapture, lanProxy и exitNode (анонсирование Tailscale, которое выполняет только Chute Mac). С лицензией или пока движок остановлен все счётчики равны 0, а все флаги — false.
  • GET /api/connections принимает limit (положительное целое, по умолчанию и максимум 1000) и cursor (возвращает только соединения с id больше курсора). Поле data ответа содержит connections, total, page_size, has_more, server_time и — когда есть ещё страницы — next_cursor. since (секунды, server_time из более раннего ответа) возвращает только соединения, изменившиеся после этого момента, и добавляет active_ids — идентификаторы всех открытых сейчас соединений: соединение, которое было в более раннем ответе и которого среди них нет, закрылось. since позже server_time считается равным 0, так что возвращаются все соединения.
  • GET /api/connections/history принимает limit (по умолчанию 100, максимум 1000) и cursor/before (синонимы; передача обоих отклоняется).
  • GET /api/connections/:id/request и .../response возвращают {"connection_id": <id>, "data": "<base64>"}. Захваты больше 2 МиБ возвращают 413. Без Chute Pro оба возвращают 403 с request data is not available или response data is not available — в том числе для тел, записанных во время более раннего запуска с лицензией.
  • GET /api/config возвращает работающую конфигурацию в том виде, в каком она написана, вместе с учётными данными — http-auth, external-http-secret, ca-p12, ca-passphrase, ключами WireGuard и паролем каждого прокси, — так что доступ к API управления означает доступ ко всем ним. Учётные данные заменяет на <redacted> только диагностический пакет, и эту копию нельзя загрузить обратно: конфигурация, отправленная в PUT /api/config, в которой где-либо ещё стоит <redacted>, отклоняется с 400 и сообщением, где названа первая такая строка. Отправляйте вместо неё исходную конфигурацию.
  • GET и PUT /api/config доступны также как /api/configs и как псевдоним Clash /configs.
  • PUT /api/config принимает либо JSON {"configuration": "<full text>"}, либо сырой текст конфигурации в теле запроса (лимит 1 МБ). При успехе движок перезагружается — или запускается, если он не работал.
  • PUT /api/policies/:group берёт выбор из первого из ключей тела policy, name, selected, select; значением может быть имя политики или числовой индекс в виде строки. Специальное имя группы GLOBAL устанавливает глобально выбранную политику.
  • В GET /api/policies каждая политика, группа и участник группы несут endpoint — политику, к которой они ведут сейчас (через группы и через встроенный PROXY до политики, выбранной для глобального режима), — и endpoint_ping, задержку этой политики. Собственный ping группы равен 0 — он не измеряется, — так что для группы или для PROXY смотреть нужно на endpoint_ping.
  • PUT /api/mode требует число JSON: {"mode": 0} — 0 правила, 1 напрямую, 2 прокси.
  • PUT /api/features/mitm и PUT /api/features/record-traffic принимают {"enabled": true}.
  • GET /api/logs принимает since (секунды Unix); буфер в памяти хранит последние 1000 записей, каждая — {timestamp, wall_time, level, section, message}: timestamp и wall_time несут одно и то же значение в секундах Unix, сдвигаемое вперёд, когда часы не идут, чтобы записи оставались строго упорядоченными.
  • GET /api/health сообщает, что движок сейчас удерживает и почему в последний раз что-то отклонил, а также как завершился предыдущий запуск (clean, unclean или suspected_memory — см. Устранение неполадок). addressFamily показывает, как Chute оценивает выход в IPv6 — ipv6 равно healthy, confirming или degraded, — со счётчиками того, что он по этому поводу сделал; на движках Apple selfLoop сообщает о защите от самозацикливания. Ни то, ни другое не содержит адресов.
  • GET /api/events отдаёт кольцевой буфер в памяти; ?persisted=1 читает сохранённую историю этого запуска и отвечает available: false, если запись выключена.
  • Без раздела [Tailscale] GET /api/tailscale отвечает state: "idle" — это нормальный ответ, а не ошибка.
  • Проверки POST /api/diagnostics/* берут аргументы из строки запроса или JSON-тела, ограничены десятью секундами и отвечают ровно один раз. url-test/:policy отклоняет имя несуществующей политики, а не измеряет REJECT.
  • GET /api/scripts перечисляет включённые скрипты generic как {name, type}; POST /api/scripts/run берёт name из тела или строки запроса, ограничен так же, как диагностические проверки, и отвечает {name, timedOut, result} — timedOut отличает скрипт, который так и не вызвал $done, от отработавшего до конца. Имя, не принадлежащее включённому скрипту generic, даёт 404. Без Chute Pro он отвечает 403, script is not available.
  • POST /api/rules/match отвечает, куда пошёл бы запрос, не открывая соединения. Он принимает host (или url, из которого берутся хост и порт; правило URL-REGEX проверяется по этому url точно в том виде, в каком он написан, хотя в реальном трафике такое правило видит только обычные запросы http://), port (по умолчанию 443), а также необязательные ip, protocol, process, process_path, src_ip, src_port, in_port, in_type, in_user, in_name, network, ssid, bssid, from_tun, user_agent — незнакомое поле не игнорируется, а отклоняется вместе со списком допустимых. В ответе есть правило matched (его строка, тип, названная им политика и resolved_policy, на которую в данный момент указывает группа), policy, need_resolve, а также rule_count и match_generation, относительно которых считался ответ. Поскольку домен сопоставляется дважды — сначала по имени, затем ещё раз, когда известен адрес, — в passes по одной записи на проход; без ip существует только проход до разрешения имени, и ответ говорит об этом в note. Добавьте explain=true, чтобы получить правила-кандидаты, которые тоже могли совпасть, до 50 штук, вместе с числом нераскрытых наборов правил.
  • POST /api/config/validate разбирает конфигурацию и выбрасывает её: работающий движок не принимает из неё ничего. Отправьте её как {"configuration": "<full text>"} или сырым текстом. В ответе — valid, error_count, advisory_count, rule_count, policy_count и список errors из {line, severity, content, error}; severity отделяет отвергнутую строку от принятой с оговоркой, а content — это проблемная строка в том виде, в каком она написана, вместе с учётными данными (ведь плохая строка [Proxy] часто плоха именно в том поле, где хранится её пароль), обрезанная до 4096 символов. Пользуйтесь этим перед PUT /api/config, который перезапускает тот самый запуск, который вы отлаживаете.
  • GET /api/loglevel сообщает текущий level, nslog_level, записываемые в файл sections, а также available_levels / available_sections, которые можно задать. PUT (или PATCH) принимает level, sections либо и то и другое: sections — это массив имён разделов или строка "all", а пустой массив отклоняется; чтобы прекратить запись, используйте level со значением none. Смена уровня таким способом не перезапускает работающий процесс, и в этом весь смысл: loglevel = verbose в файле требует перезагрузки, а перезагрузка теряет как раз то, что вы пытались увидеть.
  • GET /api/rules дополнительно сообщает rewrite_hits — каждое правило перезаписи или имитации ответов, сработавшее за этот запуск, со счётчиком. Правило, которого там нет, ни разу не совпало — это обычное объяснение перезаписи, которая как будто ничего не делает. Таблица отслеживает до 512 различных правил, а всё сверх этого сообщает в rewrite_hit_dropped_rules. rules перечисляет по порядку все правила, которые проходит сопоставитель: автоматические правила Tailscale, затем правила, добавленные через /api/rules/user, затем правила модулей, затем раздел [Rule] конфигурации и в конце FINAL; rule_regions указывает происхождение каждой строки с тем же индексом (front, user, module, configuration).
  • /api/rules/user хранит правила, добавленные во время работы движка, без перезагрузки и без изменения файла конфигурации. Они сопоставляются после автоматических правил Tailscale и раньше правил модулей и раздела [Rule] конфигурации, в заданном порядке. GET перечисляет их; PUT заменяет их, а POST добавляет после имеющихся — оба принимают {"rules": ["<rule line>", ...]} или одиночный {"rule": "<rule line>"}, записанные так же, как в файле; DELETE удаляет их все. Запись выполняется целиком или никак: строка, которая не разбирается, или FINAL отклоняются с 400, и правила остаются прежними. Правило, политика которого не определена в работающей конфигурации, принимается — оно отказывает соединениям через REJECT (fail-closed) — и называется в warnings. close_rerouted, по умолчанию true, закрывает соединения, которые изменённые правила направляют в другое место, и только их; false оставляет все соединения открытыми — для DELETE передайте его как ?close_rerouted=false. Каждый метод отвечает текущими rules. Правила сохраняются при перезагрузке и исчезают, когда движок останавливается. PATCH на этом пути не принимается.
  • POST /api/rewrites/:family принимает {"rule": "<configuration line>"} — тот же текст, что вы написали бы в файле. Строка, которая не разбирается, отклоняется с 400, а не сохраняется как правило, которое никогда не совпадёт. :family — одно из url-rewrite, header-rewrite, body-rewrite, mock. Добавленные так правила живут только в работающем движке и не записываются обратно в файл конфигурации.
  • GET /api/connections/export?format=har возвращает документ HAR 1.2, а POST /api/diagnostics/bundle — zip. Оба являются файлами, поэтому, в отличие от остальных точек, не заворачиваются в {"ok": ..., "data": ...}. export принимает source (current по умолчанию или history), limit (по умолчанию 100, максимум 300), ids и bodies=1 для включения захваченных тел. Каждая запись несёт объект _kl с тем, для чего в HAR нет полей: выбранная политика, совпавшее правило и сработавшие перезаписи.
  • Запись соединения в цепочке в GET /api/connections и GET /api/connections/history содержит chainPath — путь от этого устройства до выхода, например Airport/HK-01 → Landing; для соединения через одну политику он пуст, а экспорт HAR несёт его как _kl.chain. В счётчиках по политикам в GET /api/traffic вышестоящий узел тоже учитывает байты, которые он передал для соединений в цепочке; общие итоги учитывают их один раз.

Пример — прочитать статус, затем переключить группу политик:

curl -H "Authorization: Bearer your-secret-token" http://127.0.0.1:9090/api/status
{"ok":true,"data":{"running":true,"outbound_mode":0,"mitm":false, ...}}

curl -X PUT -H "Authorization: Bearer your-secret-token" \
     -d '{"policy": "ProxyB"}' http://127.0.0.1:9090/api/policies/MainGroup
{"ok":true,"data":{"outbound_mode":0,"selectable_groups":[...], ...}}

Пример — спросить, куда пойдёт запрос, прежде чем его отправлять:

curl -X POST -H "Authorization: Bearer your-secret-token" \
     -d '{"url": "https://api.example.com/v1/orders", "explain": true}' \
     http://127.0.0.1:9090/api/rules/match
{"ok":true,"data":{"policy":"MainGroup","matched":{"rule":"DOMAIN-SUFFIX,example.com,MainGroup", ...}, ...}}

Сузить журнал до одной подсистемы во время воспроизведения, не перезапуская процесс:

curl -X PUT -H "Authorization: Bearer your-secret-token" \
     -d '{"level": "verbose", "sections": ["MitM", "DNS"]}' \
     http://127.0.0.1:9090/api/loglevel

Примечание: Эта функция отключена по умолчанию. Каждый ответ использует конверт {"ok": true, "data": {...}} при успехе и {"ok": false, "error": {"code": "...", "message": "..."}} при ошибках; тела запросов ограничены 1 МБ.

Конечные точки PUT также принимают PATCH. Для сторонних панелей доступны Clash-совместимые псевдонимы путей: /version, /traffic, /connections, /configs, /proxies, /rules — пути доступны, но ответы используют конверт и имена полей Chute, а не схему Clash (/version возвращает {"name", "run_id", "egress_probe"}, где egress_probe — network_address на движках Apple и egress_ip на Android), поэтому панели Clash не заработают «из коробки».

S. Smart Rabbit LLC © All Rights Reserved            updated 2026-11-19 16:07:28

Эта страница — перевод английской версии. При расхождениях приоритет имеет английская версия.

results matching ""

    No results matching ""