ShadowrocketAPI 概览
Shadowrocket桌面端提供完整的RESTful API接口，专为开发者与运维团队设计，支持节点管理、订阅控制、流量查询、规则更新等核心操作的编程化调用。
Python SDK 现已发布
pip install shadowrocket-sdk 即可使用高级封装接口，支持异步调用与自动重试。详情见文末。
基础信息
Base
http://127.0.0.1:1989/api
仅监听本地，安全无公网暴露
Auth
Bearer Token
设置 → 开发者选项中生成
Format
application/json
统一 JSON 响应格式
Encoding
UTF-8
全中文标签页支持
核心接口速查
GET
/v1/status
获取连接状态与流量统计
POST
/v1/node/switch
切换当前节点
POST
/v1/subscription/refresh
刷新订阅同步
GET
/v1/traffic
查询流量详细数据
GET
/v1/nodes
获取节点列表与延迟
POST
/v1/rules/update
远程更新规则集
实战一：节点健康检查与自动切换
企业内网环境中，保持节点池的健康状态至关重要。以下脚本每10分钟执行一次，自动刷新订阅并切换到延迟最低的节点：
#!/usr/bin/env python3
# shadowrocket_auto_switch.py
# 定时检查节点健康状况并自动切换最优节点
import requests, json, time
from datetime import datetime
API = "http://127.0.0.1:1989/api"
TOKEN = "your_dev_token"
def get_best_node():
"""获取延迟最低的节点"""
resp = requests.get(f"{API}/v1/nodes",
headers={"Authorization": f"Bearer {TOKEN}"})
nodes = resp.json().get("nodes", [])
# 按延迟升序排序，选取最优
viable = [n for n in nodes if n.get("latency", 999) < 500]
if not viable:
return None
return min(viable, key=lambda x: x["latency"])
def auto_switch():
ts = datetime.now().strftime("%Y-%m-%d %H:%M")
# 刷新订阅
requests.post(f"{API}/v1/subscription/refresh",
headers={"Authorization": f"Bearer {TOKEN}"})
best = get_best_node()
if best:
requests.post(f"{API}/v1/node/switch",
json={"node_id": best["id"]},
headers={"Authorization": f"Bearer {TOKEN}"})
print(f"[{ts}] 已切换至 {best['name']} ({best['latency']}ms)")
while True:
auto_switch()
time.sleep(10 * 60) # 每10分钟执行一次
实战二：流量配额告警系统
运维团队可通过API实时监控各节点流量使用情况，超配额时触发告警通知：
#!/usr/bin/env python3
# shadowrocket_quota_monitor.py
# 企业流量配额监控与告警
import requests, logging, json
from datetime import datetime
API = "http://127.0.0.1:1989/api"
TOKEN = "your_token"
QUOTA_GB = 100
WEBHOOK = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s %(levelname)s: %(message)s'
)
def get_usage():
s = requests.get(f"{API}/v1/status",
headers={"Authorization": f"Bearer {TOKEN}"}).json()
total = (s.get("up_bytes",0) + s.get("down_bytes",0)) / (1024**3)
return round(total, 2)
def check_and_alert():
used = get_usage()
if used >= QUOTA_GB:
logging.warning(f"流量超限: {used}GB / {QUOTA_GB}GB")
msg = {
"msgtype": "text",
"text": {
"content": f"⚠️ Shadowrocket节点 {used}GB 流量超限，请及时处理。"
}
}
requests.post(WEBHOOK, json=msg)
else:
logging.info(f"当前使用量: {used}GB / {QUOTA_GB}GB")
if __name__ == "__main__":
check_and_alert()
Python SDK 快速上手
# 安装
pip install shadowrocket-sdk
# 使用示例
from shadowrocket import ShadowrocketClient
client = ShadowrocketClient(
host="127.0.0.1",
port=1989,
token="your_token"
)
# 获取状态
status = client.get_status()
print(f"已连接: {status.connected}")
print(f"当前节点: {status.node}")
print(f"延迟: {status.latency_ms}ms")
# 切换节点
client.switch_node("jp-tokyo-03")
# 刷新订阅
result = client.refresh_subscription()
print(f"已加载 {result.nodes_count} 个节点")
# 异步用法
import asyncio
async def demo():
async with client:
status = await client.async_get_status()
print(status)
asyncio.run(demo())
⚠️ 安全提醒：API Token 在设置页面的「开发者选项」中生成，请勿将其泄露给第三方。API 仅在本地 127.0.0.1 监听，无公网暴露风险，但建议配合系统防火墙使用。
注意事项
- API Token 可随时在设置中重置，重置后旧 Token 立即失效
- 大量节点订阅建议使用异步调用，避免阻塞主线程
- 请注意错误处理，网络异常时应设置合理的重试策略
- v2.5.0 将新增 WebSocket 实时推送接口，支持连接状态变更的即时通知