RESTful API 与面板对接

控制接口默认监听在本地的 9090 端口，走 HTTP 协议，返回 JSON 数据。 面板做的所有事情 —— 切换节点、查看连接、改配置 —— 本质上都是调用这些端点。

开启控制接口

复制external-controller: 127.0.0.1:9090
external-ui: ui          # 将面板文件放在 ./ui 目录即可自动托管
external-ui-name: metacubexd
secret: "your-strong-password"

鉴权与安全

复制# 带鉴权的请求方式
curl -H "Authorization: Bearer your-strong-password" \
  http://127.0.0.1:9090/version

# 也支持放在查询参数里（不推荐，会出现在日志中）
curl "http://127.0.0.1:9090/version?token=your-strong-password"

如果确实需要远程访问，正确做法是通过反向代理加上 HTTPS 与额外的身份验证，而不是直接把端口映射出去。

常用端点速查

方法	路径	用途
GET	/version	获取内核版本
GET	/configs	读取当前运行配置
PATCH	/configs	修改运行参数，如切换模式
PUT	/configs	重载配置文件
GET	/proxies	列出全部节点与代理组
PUT	/proxies/{name}	切换指定代理组的选中节点
GET	/proxies/{name}/delay	测试节点延迟
GET	/connections	查看当前活动连接
DELETE	/connections	关闭全部连接
GET	/traffic	流式返回实时上下行速率
GET	/logs	流式返回运行日志

实用调用示例

复制# 切换模式为全局
curl -X PATCH http://127.0.0.1:9090/configs \
  -H "Authorization: Bearer your-password" \
  -H "Content-Type: application/json" \
  -d '{"mode":"global"}'

# 在「节点选择」组中选中「东京-01」
curl -X PUT "http://127.0.0.1:9090/proxies/🚀%20节点选择" \
  -H "Authorization: Bearer your-password" \
  -H "Content-Type: application/json" \
  -d '{"name":"东京-01"}'

# 批量测试延迟
curl -H "Authorization: Bearer your-password" \
  "http://127.0.0.1:9090/group/🚀%20节点选择/delay?url=http://www.gstatic.com/generate_204"

接入第三方面板

常见做法有三种，按便捷程度排序：

1. 本地托管 —— 把面板静态文件放到内核的 external-ui 目录，访问 http://127.0.0.1:9090/ui 即可，无需额外服务；
2. Docker 部署 —— 单独跑一个面板容器，通过 API 地址连接内核；
3. 在线面板 —— 直接访问面板站点并填写接口地址，注意这会把地址与密码交给第三方页面。

复制# 面板连接信息填写示例
API 地址:  http://127.0.0.1:9090
密钥:      your-strong-password

# 若内核运行在路由器上
API 地址:  http://192.168.1.1:9090

自动化场景

• 检测到某个节点超时后自动切换到备用组；
• 根据当前网络环境（公司 / 家庭）自动切换代理模式；
• 定时拉取订阅并触发重载，配合日志做健康巡检；
• 把 /traffic 的数据接入监控系统，绘制流量曲线。

/traffic 与 /logs 是流式接口，会一直保持连接不断推送数据。写脚本时记得设置读取超时与断线重连。

---

不同内核对 API 的支持略有差异，可参考 Clash 与 Mihomo 内核差异对比。