HTTP 控制 API 和 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 提供内嵌的 HTTP 控制 API 和 Web 控制台,类似于 Clash 和 Surge 面板。API 通过 REST 端点暴露引擎状态、流量、连接、DNS、策略控制和配置管理。

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

控制台服务期间常驻的请求上限为 macOS 4 MB,iOS、tvOS 与 Android 1 MB。

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

用于 API 鉴权的 Bearer 令牌。请求必须包含请求头 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/* 路径。Web 控制台的页面和静态资源(/、/assets/…,Chute Android 上还有 /ui)不需要令牌(external-http-ui = false 时它们根本不存在——页面返回 404)。

未写这一项时,Chute 会生成一个令牌,而不是不加鉴权地提供服务。生成的令牌以仅属主可读的权限写入 Chute 共享目录下的 control-token 文件——不在配置旁边:iOS 与 tvOS 上是 App Group 容器,Android 上是应用的私有数据目录——重启后继续沿用,各端应用会展示给你——见打开 Web 控制台。控制 API 可以交出连接数据库,而其中的记录带有本次运行见过的每一条 URL、请求头和进程名,所以「默认开放」不是一个合理的默认值。

如果确实要不加鉴权地提供服务,请在配置里明说:

external-http-secret = none

该写法仅在回环绑定时被接受。在非回环地址上,none 和「不写」都不够:控制服务器会拒绝启动,并说明它需要什么。

升级提示:如果你此前依赖「不写 external-http-secret 即不鉴权」,本机脚本会开始收到 401。要么从应用里读出生成的令牌,要么写上 external-http-secret = none,明确保留旧行为。

external-http-ui(默认:true)

external-http-ui = true

启用后,Chute 在控制器地址提供内嵌的 Web 控制台。Web 控制台提供概览、连接管理、DNS 检查、流量监控、策略控制和配置编辑。设置为 false 则仅启用 API 而禁用 UI。

打开 Web 控制台

控制台就在控制服务器的地址上,各端应用都能把地址和令牌交给你——包括自动生成的那一个,否则你没有别的办法读到它:

  • Chute Mac:菜单栏 → 打开 Web 控制台,以及复制 Web 控制台令牌。连接详情窗口里还有请求与历史,同样会打开控制台——打开的是首页,不是那条连接。
  • Chute iOS:控制面板 → Web 控制台那一行 → 打开、复制地址或复制访问令牌。
  • Chute tvOS:控制面板另有一行Web 控制台地址,显示主机与端口。选中它时,若监听器能被其他设备访问,就显示二维码——登录令牌只藏在二维码里,不显示在屏幕上;若控制器绑定在回环地址,则显示一段说明,因为回环上的控制台没法从手机打开。
  • Chute Android:控制面板 → Web 控制台地址 → 打开或复制地址,另有一行生成的访问令牌,点按即复制。令牌是你自己配置的 secret 时,这两行都不会出现——这种 secret 永远不会被显示。

这些入口给出的地址把令牌带在查询参数里。页面加载时会消费掉它并从地址栏移除,所以打开链接就是一次完整登录,没人需要手抄 32 个十六进制字符。


external-http-cors(默认:false)

external-http-cors = true

在 API 响应中启用 CORS(跨域资源共享)头。当 Web 控制台或第三方工具需要从不同源访问 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,标了 hidden=true 的组为 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,即当前所有打开着的连接的 id:之前某次应答里有、而这里没有的连接已经关闭。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 MiB 时返回 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 MB)。成功后引擎会重新加载——若尚未运行则直接启动。
  • 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 请求体,有 10 秒上限,且只回答一次。url-test/:policy 对未定义的策略名直接报错,而不是去测 REJECT。
  • GET /api/scripts 以 {name, type} 列出已启用的 generic 脚本;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 失败关闭——并在 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 MB。

PUT 端点也接受 PATCH。为第三方面板提供了 Clash 兼容的别名路径:/version、/traffic、/connections、/configs、/proxies、/rules——路径可达,但响应使用 Chute 自己的信封和字段名而非 Clash 的 schema(/version 返回 {"name", "run_id", "egress_probe"},其中 egress_probe 在 Apple 引擎上是 network_address,在 Android 引擎上是 egress_ip),因此 Clash 面板无法开箱即用。

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

本页为英文版的翻译。如内容有出入,以英文版为准。

results matching ""

    No results matching ""