API 概览

Shadowrocket桌面端提供完整的RESTful API接口,专为开发者设计,支持节点管理、订阅控制、流量查询、规则更新等核心操作的编程化调用。无论是企业内网管理、自动化运维还是第三方集成开发,都能找到合适的接口方案。

基础信息

Base URL
http://127.0.0.1:1989/api
仅监听本地环回地址
Auth
Bearer Token
Authorization Header
Format
application/json
统一响应格式
Encoding
UTF-8
全中文支持

核心接口速查

GET
/v1/status
获取连接状态与流量数据
POST
/v1/node/switch
切换当前节点
POST
/v1/subscription/refresh
刷新订阅同步
GET
/v1/traffic
查询流量统计
GET
/v1/rules
获取规则列表
POST
/v1/rules/update
更新规则集

场景一:订阅自动更新 + 节点健康检查

企业环境中,保持节点池新鲜度至关重要。以下脚本实现每日定时刷新订阅,并自动切换到延迟最低的节点:

#!/usr/bin/env python3 # shadowrocket_auto_maintain.py import requests, json, time, smtplib API = "http://127.0.0.1:1989/api" TOKEN = "your_developer_token" def refresh_and_switch(): # 刷新订阅 r = requests.post(f"{API}/v1/subscription/refresh", headers={"Authorization": f"Bearer {TOKEN}"}) if r.json().get("success"): print(f"[{time.strftime('%H:%M:%S')}] 订阅已刷新") # 获取所有节点 nodes = requests.get(f"{API}/v1/nodes", headers={"Authorization": f"Bearer {TOKEN}"}).json() # 按延迟排序,选取最优节点 best = min(nodes.get("nodes", []), key=lambda x: x.get("latency", 9999)) # 切换 requests.post(f"{API}/v1/node/switch", json={"node_id": best["id"]}, headers={"Authorization": f"Bearer {TOKEN}"}) print(f"已切换至: {best['name']} ({best['latency']}ms)") # 每6小时执行一次 while True: refresh_and_switch() time.sleep(6 * 3600)

场景二:企业流量配额告警

运维团队可通过API实时监控全网节点的流量使用情况,超配额时自动告警:

#!/usr/bin/env python3 # shadowrocket_quota_alert.py import requests, logging from datetime import datetime API = "http://127.0.0.1:1989/api" TOKEN = "your_token" QUOTA_GB = 100 logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') def check_quota(): status = requests.get(f"{API}/v1/status", headers={"Authorization": f"Bearer {TOKEN}"}).json() used = (status.get("up_bytes", 0) + status.get("down_bytes", 0)) / (1024**3) if used >= QUOTA_GB: logging.warning(f"⚠️ 流量配额告警: 已用 {used:.2f}GB / {QUOTA_GB}GB") # 触发企业微信/钉钉/邮件通知 send_alert(f"Shadowrocket节点 {status.get('node')} 流量超限") else: logging.info(f"✓ 当前使用: {used:.2f}GB / {QUOTA_GB}GB") def send_alert(msg): # 企业微信Webhook示例 webhook_url = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY" requests.post(webhook_url, json={"msgtype": "text", "text": {"content": msg}}) if __name__ == "__main__": check_quota()

💡 SDK 提示:Shadowrocket Python SDK 现已发布,pip install shadowrocket-sdk 即可使用高级封装接口,支持异步调用与自动重试。

注意事项