API de contrôle HTTP et console web
[General]
external-http-controller = 127.0.0.1:9090
external-http-secret = your-secret-token
external-http-ui = true
external-http-cors = false
Chute fournit une API de contrôle HTTP intégrée et une console web, comparables aux tableaux de bord de Clash et de Surge. L'API expose l'état du moteur, le trafic, les connexions, le DNS, les contrôles de politique et la gestion de configuration via des points de terminaison REST.
La forme Surge http-api = <secret>@<host>:<port> est lue comme external-http-controller plus external-http-secret. Un profil peut aussi écrire les parties séparément : http-api-secret, http-api-ui et http-api-cors sont lues comme external-http-secret, external-http-ui et external-http-cors, et http-api-web-dashboard également comme external-http-ui ; la configuration est enregistrée avec les clés external-http-*. http-api-tls n'est pas pris en charge — le contrôleur parle HTTP en clair — et ne produit qu'un avis.
external-http-controller (par défaut : désactivé)
external-http-controller = 127.0.0.1:9090
Les requêtes que la console garde résidentes pendant le service sont plafonnées à 4 Mo sous macOS et 1 Mo sous iOS, tvOS et Android.
Adresse et port du serveur de contrôle HTTP. Utilisez 127.0.0.1 pour un accès purement local. Se lier à une adresse hors boucle locale (par exemple 192.168.1.5:9090) exige un external-http-secret explicite : sans lui, le serveur refuse de démarrer et journalise ce qui manque.
Une adresse joker (0.0.0.0, ::, *) compte comme hors boucle locale pour cette vérification, car elle écoute sur toutes les interfaces — l'inverse d'un accès local. Les graphies acceptées sont 0.0.0.0:9090, *:9090 (la même chose) et, pour IPv6, [::]:9090 — un :::9090 nu reçoit ses crochets automatiquement ; une adresse impossible à analyser est signalée comme erreur de configuration au lieu de laisser silencieusement le contrôleur éteint. L'ensemble de 127.0.0.0/8 compte comme boucle locale, pas seulement 127.0.0.1.
external-http-secret (par défaut : un jeton généré)
external-http-secret = your-secret-token
Le jeton Bearer utilisé pour l'authentification de l'API. Les requêtes doivent contenir l'en-tête Authorization: Bearer <secret> — le jeton n'est accepté que dans cet en-tête, jamais en paramètre d'URL, et la comparaison se fait en temps constant. Un échec d'authentification renvoie 401 avec {"ok": false, "error": {"code": "unauthorized", "message": "missing or invalid token"}}. Toutes les routes de données sont protégées : les chemins /api/*, les alias compatibles Clash et les routes plus anciennes que seul Chute Android sert encore (/status, /policies, /dns, /records, etc.), qui n'acceptent elles aussi le jeton que dans cet en-tête. Le tableau de bord distant de Chute Android lui-même n'utilise plus que les chemins /api/*. La page et les fichiers statiques de la console web (/, /assets/…, et sur Chute Android aussi /ui) n'ont pas besoin de jeton (avec external-http-ui = false ils disparaissent tout à fait — la page renvoie 404).
Lorsque la clé est absente, Chute génère un jeton au lieu de servir sans authentification. Le jeton généré est écrit dans un fichier control-token du dossier de partage de Chute — pas à côté de la configuration : le conteneur du groupe d'apps sur iOS et tvOS, le répertoire de données privé de l'app sur Android —, lisible par son seul propriétaire, réutilisé d'un redémarrage à l'autre, et les applications vous le montrent — voir Ouvrir la console web. L'API de contrôle peut livrer la base des connexions, dont les enregistrements portent chaque URL, chaque en-tête et chaque nom de processus vus pendant l'exécution ; un contrôleur ouvert n'est pas une valeur par défaut raisonnable.
Si vous voulez malgré tout servir sans authentification, dites-le explicitement dans la configuration :
external-http-secret = none
Cela n'est accepté que pour une liaison en boucle locale. Hors boucle locale, ni none ni l'absence de clé ne suffisent : le serveur de contrôle refuse de démarrer et indique ce qu'il attend.
Mise à niveau : si vous comptiez sur l'absence de
external-http-secretpour dire « pas d'authentification », vos scripts locaux commenceront à recevoir401. Lisez le jeton généré dans l'application, ou écrivezexternal-http-secret = nonepour conserver délibérément l'ancien comportement.
external-http-ui (par défaut : true)
external-http-ui = true
Lorsque cette option est activée, Chute sert une console web intégrée à l'adresse du contrôleur. La console web propose une vue d'ensemble, la gestion des connexions, l'inspection DNS, la surveillance du trafic, les contrôles de politique et l'édition de configuration. Définissez false pour conserver l'API activée tout en désactivant l'interface.
Ouvrir la console web
La console est servie à l'adresse du serveur de contrôle, et chaque application peut vous donner l'adresse et le jeton — y compris celui qui est généré, que vous n'auriez sinon aucun moyen de lire :
- Chute Mac : barre des menus → Ouvrir la console web, et Copier le jeton de la console web. La fenêtre de détail d'une connexion propose aussi Requêtes et historique, qui ouvre la console — sa page d'accueil, pas cette connexion.
- Chute iOS : panneau de configuration → ligne Console web → Ouvrir, Copier l'adresse ou Copier le jeton d'accès.
- Chute tvOS : le panneau de configuration a une ligne distincte Adresse de la console web, qui affiche l'hôte et le port. La sélectionner montre un QR code lorsque l'écouteur est joignable depuis d'autres appareils — le jeton de connexion voyage dans le code, pas à l'écran — et, lorsque le contrôleur est lié à la boucle locale, une explication à la place, car une console en boucle locale ne peut pas s'ouvrir depuis un téléphone.
- Chute Android : panneau de configuration → Adresse de la console web → Ouvrir ou Copier l'adresse, et une ligne Jeton d'accès généré qui copie d'un appui. Aucune des deux lignes n'apparaît lorsque le jeton est un secret que vous avez configuré vous-même, lequel n'est jamais affiché.
L'adresse ainsi produite porte le jeton en paramètre d'URL. La page le consomme au chargement et le retire de la barre d'adresse, si bien qu'ouvrir le lien constitue une connexion complète et que personne n'a à recopier 32 caractères hexadécimaux.
external-http-cors (par défaut : false)
external-http-cors = true
Active les en-têtes CORS (partage de ressources entre origines) sur les réponses de l'API. Utile lorsque la console web ou des outils tiers doivent accéder à l'API depuis une autre origine.
Points de terminaison de l'API :
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/api/status |
État d'exécution, ports, temps de fonctionnement |
GET |
/api/traffic |
Compteurs de trafic globaux et par politique |
GET |
/api/connections |
Connexions actives actuelles |
DELETE |
/api/connections/:id |
Fermer une connexion |
GET |
/api/connections/history |
Enregistrements de connexions historiques |
GET |
/api/connections/processes |
Statistiques de connexion par processus |
GET |
/api/connections/:id/request |
Données de requête capturées pour une connexion |
GET |
/api/connections/:id/response |
Données de réponse capturées pour une connexion |
GET |
/api/dns |
Enregistrements du cache DNS |
DELETE |
/api/dns/cache |
Purger le cache DNS |
DELETE |
/api/dns/records/:domain |
Supprimer un enregistrement DNS |
GET |
/api/config |
Configuration actuelle |
PUT |
/api/config |
Recharger la configuration |
POST |
/api/config/validate |
Analyse une configuration et signale ses erreurs, sans la charger |
GET |
/api/policies |
Groupes de politiques et sélection actuelle ; chaque entrée porte hidden, qui vaut true pour un groupe marqué hidden=true |
PUT |
/api/policies/:group |
Changer la sélection d'un groupe de politiques |
PUT |
/api/mode |
Définir le mode de sortie |
GET |
/api/features |
États des interrupteurs de fonctionnalités |
PUT |
/api/features/mitm |
Activer/désactiver le MitM |
PUT |
/api/features/record-traffic |
Activer/désactiver l'enregistrement du trafic |
GET |
/api/rules |
La table des règles que parcourt le moteur de correspondance, l'origine de chaque règle et les règles de réécriture déclenchées |
POST |
/api/rules/match |
Où une requête serait routée, sans l'émettre |
GET |
/api/rules/user |
Règles ajoutées à l'exécution, évaluées avant les modules et la configuration |
PUT |
/api/rules/user |
Remplacer les règles d'exécution |
POST |
/api/rules/user |
Ajouter des règles après les règles d'exécution |
DELETE |
/api/rules/user |
Supprimer toutes les règles d'exécution |
GET |
/api/logs |
Entrées de journal récentes |
GET |
/api/loglevel |
Niveau de journal courant, et les sections écrites |
PUT |
/api/loglevel |
Changer le niveau de journal ou les sections sans redémarrer |
GET |
/api/health |
Santé du moteur : refus, générations, empreinte mémoire, sortie précédente |
GET |
/api/events |
Moments notables de cette exécution |
GET |
/api/tailscale |
État courant du moteur Tailscale |
GET |
/api/scripts |
Les scripts génériques exécutables à la demande |
POST |
/api/scripts/run |
Exécuter un script générique par son nom |
POST |
/api/diagnostics/ping |
Sonde d'accessibilité ICMP ou TCP |
POST |
/api/diagnostics/dns-query |
Résoudre un domaine via le résolveur en cours |
POST |
/api/diagnostics/egress-probe |
Vérifier l'adresse : celles de l'appareil sur les moteurs Apple ; sur Android, l'adresse publique de l'appareil sur son réseau physique, et non la sortie d'un proxy |
POST |
/api/diagnostics/internet-test |
Le test Internet direct : récupérer internet-test-url sans proxy |
POST |
/api/diagnostics/url-test/:policy |
Lancer le test de latence d'une politique |
POST |
/api/diagnostics/bundle |
Construire une archive de diagnostic expurgée |
GET |
/api/connections/export |
Exporter les connexions en HAR 1.2 |
GET |
/api/rewrites |
Toutes les familles de réécriture/réponse simulée et la liste des hôtes MitM |
GET |
/api/rewrites/:family |
Les règles d'une famille |
POST |
/api/rewrites/:family |
Ajouter une règle |
DELETE |
/api/rewrites/:family/:id |
Supprimer une règle |
DELETE |
/api/rewrites/:family |
Vider une famille |
GET |
/api/mitm/hosts |
Hôtes actuellement déchiffrés |
POST |
/api/mitm/hosts |
Ajouter un hôte |
DELETE |
/api/mitm/hosts/:host |
Supprimer un hôte |
DELETE |
/api/mitm/hosts |
Vider la liste |
GET |
/api/rules/providers |
Les fournisseurs de règles et les jeux de règles, avec l'état de chacun — y compris la raison pour laquelle l'un d'eux n'a pas été chargé |
Notes sur les points de terminaison :
GET /api/featuresindique chaque interrupteur tel qu'il est réglé —record_traffic,mitm,mitm_h2,mitm_auto_quic_block,rewrite— ainsi quelicensed.effectiveindique ce qui tourne réellement, pour cinq éléments seulement :record_traffic,mitm,rewrite,scriptsetlan_proxy. Dans l'édition gratuite, les cinq sont faux, si bien qu'un interrupteur peut apparaître activé alors que son entréeeffectiveest fausse.inactiveest un objet qui nomme ce que la configuration en cours demande mais qui ne tourne pas dans cette édition : les compteursscripts,scriptRules,dnsScripts,rewritesetmapLocals, et les drapeauxmitm,bodyCapture,lanProxyetexitNode(l'annonce Tailscale, que seul Chute Mac pratique). Avec une licence, ou tant que le moteur est arrêté, chaque compteur vaut 0 et chaque drapeau est faux.GET /api/connectionsacceptelimit(entier positif, valeur par défaut et maximale 1000) etcursor(ne renvoie que les connexions dont l'idest supérieur au curseur). Ledatade la réponse contientconnections,total,page_size,has_more,server_timeet — lorsque d'autres pages existent —next_cursor.since(en secondes, leserver_timed'une réponse antérieure) ne renvoie que les connexions qui ont changé après ce moment, et ajouteactive_ids, les identifiants de toutes les connexions ouvertes à présent : une connexion présente dans une réponse antérieure et absente de cette liste a été fermée. Unsincepostérieur àserver_timeest traité comme0, si bien que toutes les connexions sont renvoyées.GET /api/connections/historyacceptelimit(par défaut 100, maximum 1000) etcursor/before(synonymes ; les passer tous les deux est rejeté).GET /api/connections/:id/requestet.../responserenvoient{"connection_id": <id>, "data": "<base64>"}. Les captures supérieures à 2 Mio renvoient413. Sans Chute Pro, les deux renvoient403, avecrequest data is not availableouresponse data is not available, y compris pour des corps enregistrés lors d'une exécution antérieure sous licence.GET /api/configrenvoie la configuration en cours telle qu'elle est écrite, identifiants compris —http-auth,external-http-secret,ca-p12,ca-passphrase, clés WireGuard et le mot de passe de chaque proxy —, si bien qu'accéder à l'API de contrôle, c'est accéder à tous ces identifiants. Seul un ensemble de diagnostic remplace les identifiants par<redacted>, et cette copie ne peut pas être rechargée : une configuration envoyée àPUT /api/configqui porte encore<redacted>où que ce soit est refusée avec400et un message qui nomme la première ligne concernée. Soumettez plutôt la configuration d'origine.GETetPUT /api/configsont aussi accessibles sous/api/configs, ainsi que sous l'alias Clash/configs.PUT /api/configaccepte soit du JSON{"configuration": "<full text>"}, soit le texte brut de configuration comme corps de requête (limite de 1 Mo). En cas de succès, le moteur se recharge — ou démarre, s'il ne tournait pas.PUT /api/policies/:groupprend la sélection dans la première des clés de corpspolicy,name,selected,select; la valeur peut être un nom de politique ou un index numérique sous forme de chaîne. Le nom de groupe spécialGLOBALdéfinit la politique globale sélectionnée.- Dans
GET /api/policies, chaque politique, groupe et membre de groupe porteendpoint, la politique à laquelle il mène actuellement — suivie à travers les groupes, et à travers la politique intégréePROXYjusqu'à la politique sélectionnée pour le mode global — etendpoint_ping, la latence de cette politique. Lepingpropre d'un groupe vaut0, il n'est pas mesuré : c'est doncendpoint_pingqu'il faut lire pour un groupe ou pourPROXY. PUT /api/modeexige un nombre JSON :{"mode": 0}—0règles,1direct,2proxy.PUT /api/features/mitmetPUT /api/features/record-trafficprennent{"enabled": true}.GET /api/logsacceptesince(secondes Unix) ; le tampon en mémoire conserve les 1000 entrées les plus récentes, chacune sous la forme{timestamp, wall_time, level, section, message}—timestampetwall_timeportent la même valeur en secondes Unix, avancée d'un cran quand l'horloge ne progresse pas, afin que les entrées restent strictement ordonnées.GET /api/healthindique ce que le moteur retient et pourquoi il a refusé quelque chose en dernier, ainsi que la façon dont l'exécution précédente s'est terminée (clean,uncleanoususpected_memory— voir Dépannage).addressFamilyindique comment Chute juge la sortie IPv6 —ipv6vauthealthy,confirmingoudegraded— avec le décompte de ce qu'il a fait en conséquence ; sur les moteurs Apple,selfLooprend compte de la protection contre l'auto-bouclage. Aucun des deux ne contient d'adresse.GET /api/eventssert l'anneau en mémoire ;?persisted=1lit à la place l'historique enregistré de cette exécution et répondavailable: falsesi l'enregistrement est désactivé.- Sans section
[Tailscale],GET /api/tailscalerépondstate: "idle"— c'est une réponse normale, pas une erreur. - Les sondes
POST /api/diagnostics/*prennent leurs arguments dans la chaîne de requête ou dans un corps JSON, sont limitées à dix secondes et répondent exactement une fois.url-test/:policyrejette un nom de politique inexistant plutôt que de mesurerREJECT. GET /api/scriptsliste les scripts génériques activés sous la forme{name, type};POST /api/scripts/runprendnamedans le corps ou dans la chaîne de requête, est borné comme les sondes de diagnostic, et répond{name, timedOut, result}—timedOutdistingue un script qui n'a jamais appelé$doned'un script allé au bout. Un nom qui n'est pas un script générique activé donne un404. Sans Chute Pro, il répond403,script is not available.POST /api/rules/matchrépond à la question où irait une requête, sans ouvrir de connexion. Il acceptehost(ou uneurldont il tire l'hôte et le port ; une règleURL-REGEXest testée sur cetteurlexactement telle qu'elle est écrite, même si, dans le trafic réel, elle ne voit que des requêteshttp://en clair),port(443 par défaut), et en optionip,protocol,process,process_path,src_ip,src_port,in_port,in_type,in_user,in_name,network,ssid,bssid,from_tun,user_agent— un champ inconnu est refusé avec la liste des champs acceptés, plutôt qu'ignoré. La réponse porte la règlematched(sa ligne, son type, la politique qu'elle nomme et laresolved_policyvers laquelle un groupe pointe actuellement), lapolicy,need_resolve, ainsi que lesrule_countetmatch_generationsur lesquels le calcul a été fait. Comme un domaine est mis en correspondance deux fois — une fois sur le nom, une seconde fois une fois l'adresse connue —,passescontient une entrée par passe ; sansip, seule la passe avant résolution existe, et la réponse le dit dansnote. Ajoutezexplain=truepour obtenir les règles candidates qui auraient pu correspondre aussi, jusqu'à 50, avec le nombre de jeux de règles non dépliés.POST /api/config/validateanalyse une configuration puis la jette : le moteur en cours n'en adopte rien. Envoyez-la sous la forme{"configuration": "<full text>"}ou en texte brut. La réponse comprendvalid,error_count,advisory_count,rule_count,policy_countet une listeerrorsde{line, severity, content, error}—severitydistingue une ligne refusée d'une ligne acceptée avec réserve, etcontentest la ligne fautive telle qu'elle est écrite — identifiants compris, car une mauvaise ligne[Proxy]l'est souvent justement dans le champ qui contient son mot de passe —, tronquée à 4096 caractères. Servez-vous-en avantPUT /api/config, qui redémarre l'exécution que vous êtes en train de déboguer.GET /api/loglevelindique lelevelcourant, lenslog_level, lessectionsécrites dans le fichier, et lesavailable_levels/available_sectionsque vous pouvez définir.PUT(ouPATCH) acceptelevel,sections, ou les deux :sectionsest un tableau de noms de sections ou la chaîne"all", et un tableau vide est refusé — pour arrêter la journalisation, utilisezlevelavecnone. Changer le niveau ainsi ne redémarre pas l'exécution, et c'est bien l'intérêt :loglevel = verbosedans le fichier exige un rechargement, et un rechargement perd précisément ce que vous cherchiez à voir.GET /api/rulesrenvoie aussirewrite_hits: chaque règle de réécriture ou de réponse simulée qui a agi pendant cette exécution, avec son compteur. Une règle absente de cette liste n'a jamais correspondu — c'est l'explication habituelle d'une réécriture qui semble ne rien faire. Le tableau suit jusqu'à 512 règles distinctes et signale tout ce qui dépasse dansrewrite_hit_dropped_rules.rulesliste dans l'ordre chaque règle que parcourt le moteur : les règles Tailscale automatiques, puis les règles ajoutées via/api/rules/user, puis les règles des modules, puis la section[Rule]de la configuration, et enfinFINAL;rule_regionsindique l'origine de chaque ligne, indice pour indice (front,user,module,configuration)./api/rules/usercontient des règles ajoutées pendant que le moteur tourne, sans rechargement et sans toucher au fichier de configuration. Elles sont évaluées après les règles Tailscale automatiques et avant les règles des modules et la section[Rule]de la configuration, dans l'ordre donné.GETles liste ;PUTles remplace etPOSTen ajoute après celles qui s'y trouvent, tous deux acceptant{"rules": ["<rule line>", ...]}ou un seul{"rule": "<rule line>"}, écrits comme dans le fichier ;DELETEles supprime toutes. Une écriture se fait en tout ou rien : une ligne qui ne s'analyse pas, ou unFINAL, est refusée avec400et les règles restent telles qu'elles étaient. Une règle dont la politique n'est pas définie par la configuration en cours est acceptée — elle échoue en mode fail-closed versREJECT— et nommée danswarnings.close_rerouted,truepar défaut, ferme les connexions que les règles modifiées routent ailleurs, et seulement celles-là ;falselaisse toutes les connexions ouvertes — avecDELETE, passez-le sous la forme?close_rerouted=false. Chaque méthode répond avec lesrulesactuelles. Les règles sont conservées lors d'un rechargement et disparaissent quand le moteur s'arrête.PATCHn'est pas accepté sur ce chemin.POST /api/rewrites/:familyprend{"rule": "<configuration line>"}— exactement le texte que vous écririez dans le fichier. Une ligne qui ne s'analyse pas est refusée avec400au lieu d'être stockée comme une règle qui ne pourra jamais correspondre.:familyvauturl-rewrite,header-rewrite,body-rewriteoumock. Les règles ajoutées ainsi vivent dans le moteur en cours d'exécution et ne sont pas réécrites dans le fichier de configuration.GET /api/connections/export?format=harrenvoie un document HAR 1.2 etPOST /api/diagnostics/bundleun zip — ce sont des fichiers, donc contrairement à tous les autres points d'accès ils ne sont pas enveloppés dans{"ok": ..., "data": ...}.exportacceptesource(currentpar défaut, ouhistory),limit(100 par défaut, 300 au maximum),ids, etbodies=1pour inclure les charges utiles capturées. Chaque entrée porte un objet_klavec ce dont HAR n'a pas de champ : la politique choisie, la règle correspondante et les réécritures qui ont agi.- L'enregistrement d'une connexion chaînée dans
GET /api/connectionsetGET /api/connections/historyportechainPath, le chemin de cet appareil jusqu'à la sortie, commeAirport/HK-01 → Landing; il est vide pour une connexion qui n'a utilisé qu'une politique, et l'export HAR le porte sous_kl.chain. Dans les compteurs par politique deGET /api/traffic, un amont compte aussi les octets qu'il a transportés pour des connexions chaînées ; les totaux globaux ne les comptent qu'une fois.
Exemple — lire l'état, puis changer un groupe de politiques :
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":[...], ...}}
Exemple — demander où irait une requête, avant de l'émettre :
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", ...}, ...}}
Restreindre le journal à un sous-système pendant la reproduction, sans redémarrer l'exécution :
curl -X PUT -H "Authorization: Bearer your-secret-token" \
-d '{"level": "verbose", "sections": ["MitM", "DNS"]}' \
http://127.0.0.1:9090/api/loglevel
Remarque : cette fonctionnalité est désactivée par défaut. Chaque réponse utilise l'enveloppe
{"ok": true, "data": {...}}en cas de succès et{"ok": false, "error": {"code": "...", "message": "..."}}en cas d'erreur ; les corps de requête sont limités à 1 Mo.Les points de terminaison
PUTacceptent égalementPATCH. Des chemins d'alias compatibles Clash sont disponibles pour les tableaux de bord tiers :/version,/traffic,/connections,/configs,/proxies,/rules— ces chemins sont accessibles, mais les réponses utilisent l'enveloppe et les noms de champ de Chute plutôt que le schéma de Clash (/versionrenvoie{"name", "run_id", "egress_probe"}, oùegress_probevautnetwork_addresssur les moteurs Apple etegress_ipsur Android) ; les tableaux de bord Clash ne fonctionneront donc pas tels quels.
Cette page est une traduction de la version anglaise. En cas de divergence, la version anglaise fait foi.