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, — со счётчиками того, что он по этому поводу сделал; на движках AppleselfLoopсообщает о защите от самозацикливания. Ни то, ни другое не содержит адресов.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 не заработают «из коробки».
Эта страница — перевод английской версии. При расхождениях приоритет имеет английская версия.