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 即可使用高级封装接口,支持异步调用与自动重试。
注意事项
- API Token 在设置 → 开发者选项中生成,请勿泄露给第三方
- API 仅监听 127.0.0.1,无公网暴露风险
- 大量节点订阅建议使用异步请求,避免阻塞
- v2.5.0 将新增 WebSocket 实时推送接口
Shadowrocket