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-secret pour dire « pas d'authentification », vos scripts locaux commenceront à recevoir 401. Lisez le jeton généré dans l'application, ou écrivez external-http-secret = none pour 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/features indique chaque interrupteur tel qu'il est réglé — record_traffic, mitm, mitm_h2, mitm_auto_quic_block, rewrite — ainsi que licensed. effective indique ce qui tourne réellement, pour cinq éléments seulement : record_traffic, mitm, rewrite, scripts et lan_proxy. Dans l'édition gratuite, les cinq sont faux, si bien qu'un interrupteur peut apparaître activé alors que son entrée effective est fausse. inactive est un objet qui nomme ce que la configuration en cours demande mais qui ne tourne pas dans cette édition : les compteurs scripts, scriptRules, dnsScripts, rewrites et mapLocals, et les drapeaux mitm, bodyCapture, lanProxy et exitNode (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/connections accepte limit (entier positif, valeur par défaut et maximale 1000) et cursor (ne renvoie que les connexions dont l'id est supérieur au curseur). Le data de la réponse contient connections, total, page_size, has_more, server_time et — lorsque d'autres pages existent — next_cursor. since (en secondes, le server_time d'une réponse antérieure) ne renvoie que les connexions qui ont changé après ce moment, et ajoute active_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. Un since postérieur à server_time est traité comme 0, si bien que toutes les connexions sont renvoyées.
  • GET /api/connections/history accepte limit (par défaut 100, maximum 1000) et cursor/before (synonymes ; les passer tous les deux est rejeté).
  • GET /api/connections/:id/request et .../response renvoient {"connection_id": <id>, "data": "<base64>"}. Les captures supérieures à 2 Mio renvoient 413. Sans Chute Pro, les deux renvoient 403, avec request data is not available ou response data is not available, y compris pour des corps enregistrés lors d'une exécution antérieure sous licence.
  • GET /api/config renvoie 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/config qui porte encore <redacted> où que ce soit est refusée avec 400 et un message qui nomme la première ligne concernée. Soumettez plutôt la configuration d'origine.
  • GET et PUT /api/config sont aussi accessibles sous /api/configs, ainsi que sous l'alias Clash /configs.
  • PUT /api/config accepte 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/:group prend la sélection dans la première des clés de corps policy, 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écial GLOBAL définit la politique globale sélectionnée.
  • Dans GET /api/policies, chaque politique, groupe et membre de groupe porte endpoint, la politique à laquelle il mène actuellement — suivie à travers les groupes, et à travers la politique intégrée PROXY jusqu'à la politique sélectionnée pour le mode global — et endpoint_ping, la latence de cette politique. Le ping propre d'un groupe vaut 0, il n'est pas mesuré : c'est donc endpoint_ping qu'il faut lire pour un groupe ou pour PROXY.
  • PUT /api/mode exige un nombre JSON : {"mode": 0} — 0 règles, 1 direct, 2 proxy.
  • PUT /api/features/mitm et PUT /api/features/record-traffic prennent {"enabled": true}.
  • GET /api/logs accepte since (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} — timestamp et wall_time portent 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/health indique 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, unclean ou suspected_memory — voir Dépannage). addressFamily indique comment Chute juge la sortie IPv6 — ipv6 vaut healthy, confirming ou degraded — avec le décompte de ce qu'il a fait en conséquence ; sur les moteurs Apple, selfLoop rend compte de la protection contre l'auto-bouclage. Aucun des deux ne contient d'adresse.
  • GET /api/events sert l'anneau en mémoire ; ?persisted=1 lit à la place l'historique enregistré de cette exécution et répond available: false si l'enregistrement est désactivé.
  • Sans section [Tailscale], GET /api/tailscale répond state: "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/:policy rejette un nom de politique inexistant plutôt que de mesurer REJECT.
  • GET /api/scripts liste les scripts génériques activés sous la forme {name, type} ; POST /api/scripts/run prend name dans le corps ou dans la chaîne de requête, est borné comme les sondes de diagnostic, et répond {name, timedOut, result} — timedOut distingue un script qui n'a jamais appelé $done d'un script allé au bout. Un nom qui n'est pas un script générique activé donne un 404. Sans Chute Pro, il répond 403, script is not available.
  • POST /api/rules/match répond à la question où irait une requête, sans ouvrir de connexion. Il accepte host (ou une url dont il tire l'hôte et le port ; une règle URL-REGEX est testée sur cette url exactement telle qu'elle est écrite, même si, dans le trafic réel, elle ne voit que des requêtes http:// en clair), port (443 par défaut), et en option ip, 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ègle matched (sa ligne, son type, la politique qu'elle nomme et la resolved_policy vers laquelle un groupe pointe actuellement), la policy, need_resolve, ainsi que les rule_count et match_generation sur 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 —, passes contient une entrée par passe ; sans ip, seule la passe avant résolution existe, et la réponse le dit dans note. Ajoutez explain=true pour 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/validate analyse 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 comprend valid, error_count, advisory_count, rule_count, policy_count et une liste errors de {line, severity, content, error} — severity distingue une ligne refusée d'une ligne acceptée avec réserve, et content est 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 avant PUT /api/config, qui redémarre l'exécution que vous êtes en train de déboguer.
  • GET /api/loglevel indique le level courant, le nslog_level, les sections écrites dans le fichier, et les available_levels / available_sections que vous pouvez définir. PUT (ou PATCH) accepte level, sections, ou les deux : sections est un tableau de noms de sections ou la chaîne "all", et un tableau vide est refusé — pour arrêter la journalisation, utilisez level avec none. Changer le niveau ainsi ne redémarre pas l'exécution, et c'est bien l'intérêt : loglevel = verbose dans le fichier exige un rechargement, et un rechargement perd précisément ce que vous cherchiez à voir.
  • GET /api/rules renvoie aussi rewrite_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 dans rewrite_hit_dropped_rules. rules liste 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 enfin FINAL ; rule_regions indique l'origine de chaque ligne, indice pour indice (front, user, module, configuration).
  • /api/rules/user contient 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é. GET les liste ; PUT les remplace et POST en 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 ; DELETE les supprime toutes. Une écriture se fait en tout ou rien : une ligne qui ne s'analyse pas, ou un FINAL, est refusée avec 400 et 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 vers REJECT — et nommée dans warnings. close_rerouted, true par défaut, ferme les connexions que les règles modifiées routent ailleurs, et seulement celles-là ; false laisse toutes les connexions ouvertes — avec DELETE, passez-le sous la forme ?close_rerouted=false. Chaque méthode répond avec les rules actuelles. Les règles sont conservées lors d'un rechargement et disparaissent quand le moteur s'arrête. PATCH n'est pas accepté sur ce chemin.
  • POST /api/rewrites/:family prend {"rule": "<configuration line>"} — exactement le texte que vous écririez dans le fichier. Une ligne qui ne s'analyse pas est refusée avec 400 au lieu d'être stockée comme une règle qui ne pourra jamais correspondre. :family vaut url-rewrite, header-rewrite, body-rewrite ou mock. 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=har renvoie un document HAR 1.2 et POST /api/diagnostics/bundle un zip — ce sont des fichiers, donc contrairement à tous les autres points d'accès ils ne sont pas enveloppés dans {"ok": ..., "data": ...}. export accepte source (current par défaut, ou history), limit (100 par défaut, 300 au maximum), ids, et bodies=1 pour inclure les charges utiles capturées. Chaque entrée porte un objet _kl avec 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/connections et GET /api/connections/history porte chainPath, le chemin de cet appareil jusqu'à la sortie, comme Airport/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 de GET /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 PUT acceptent également PATCH. 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 (/version renvoie {"name", "run_id", "egress_probe"}, où egress_probe vaut network_address sur les moteurs Apple et egress_ip sur Android) ; les tableaux de bord Clash ne fonctionneront donc pas tels quels.

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

Cette page est une traduction de la version anglaise. En cas de divergence, la version anglaise fait foi.

results matching ""

    No results matching ""