ByteNoteByteNote
字

字节笔记本

2026年5月18日

Surge HTTP API 完整指南

#开源工具
API中转
¥120

本文介绍 Surge 代理的 HTTP API 能力，包括开关控制、策略切换、DNS 管理等接口，以及本地代理绕过配置方法。

开启 HTTP API

在配置文件 [General] 段添加：

ini
[General]
http-api = yourpassword@127.0.0.1:6171
http-api-tls = false

重启 Surge 生效。

本地代理绕过配置

如果需要让本地流量（如 127.0.0.1）不经过 Surge 代理处理，有三种方式：

方式一：跳过代理（推荐）

Surge → 更多 → 通用 → 跳过代理，添加 127.0.0.1, localhost。这是系统级绕过，比规则更彻底。

方式二：修改配置文件

在 [General] 段添加：

ini
skip-proxy = 127.0.0.1, localhost, 192.168.0.0/16

方式三：添加规则

左侧点规则 → 添加规则：

  • 类型：IP-CIDR
  • 值：127.0.0.0/8
  • 策略：DIRECT

确保这条规则排在其他规则前面（优先级更高）。

API 能力总览

开关控制

GET 获取某功能状态，POST 修改状态。支持系统代理、增强模式、MITM、重写、脚本等主开关。

出站模式

获取或切换出站模式（直连/全局/规则）：

bash
# 切换出站模式
curl -X POST http://127.0.0.1:6171/v1/outbound \
  -H "X-Key: yourpassword" \
  -d '{"mode": "direct"}'

mode 可选值：direct / global / rule

策略与策略组

bash
# 列出策略组
curl http://127.0.0.1:6171/v1/policy_groups \
  -H "X-Key: yourpassword"

# 切换 select 组
curl -X POST http://127.0.0.1:6171/v1/policy_groups/select \
  -H "X-Key: yourpassword" \
  -d '{"group_name":"Proxy","policy":"usa"}'

# 测试策略延迟
curl -X POST http://127.0.0.1:6171/v1/policy_groups/test \
  -H "X-Key: yourpassword" \
  -d '{"policy_names":["usa"],"url":"http://bing.com"}'

请求流量

bash
# 获取最近请求
curl http://127.0.0.1:6171/v1/requests/recent?count=20 \
  -H "X-Key: yourpassword"

DNS 管理

bash
# 刷新 DNS 缓存
curl -X POST http://127.0.0.1:6171/v1/dns/flush \
  -H "X-Key: yourpassword"

# 获取 DNS 缓存
curl http://127.0.0.1:6171/v1/dns \
  -H "X-Key: yourpassword"

# 测试 DNS 延时
curl -X POST http://127.0.0.1:6171/v1/test/dns_delay \
  -H "X-Key: yourpassword"

配置文件

bash
# 获取当前配置
curl http://127.0.0.1:6171/v1/profiles \
  -H "X-Key: yourpassword"

# 检查配置合法性（Mac 4.0.6+）
curl -X POST http://127.0.0.1:6171/v1/profiles/check \
  -H "X-Key: yourpassword"

模块管理

bash
# 获取模块列表
curl http://127.0.0.1:6171/v1/modules \
  -H "X-Key: yourpassword"

# 启用/关闭模块
curl -X POST http://127.0.0.1:6171/v1/modules \
  -H "X-Key: yourpassword" \
  -d '{"name":"module-name","enabled":true}'

脚本

bash
# 获取脚本列表
curl http://127.0.0.1:6171/v1/scripting \
  -H "X-Key: yourpassword"

# 执行脚本
curl -X POST http://127.0.0.1:6171/v1/scripting/evaluate \
  -H "X-Key: yourpassword"

# 触发定时脚本
curl -X POST http://127.0.0.1:6171/v1/scripting/cron/evaluate \
  -H "X-Key: yourpassword"

设备管理

bash
# 获取设备列表
curl http://127.0.0.1:6171/v1/devices \
  -H "X-Key: yourpassword"

# 修改设备属性
curl -X POST http://127.0.0.1:6171/v1/devices \
  -H "X-Key: yourpassword" \
  -d '{"name":"device-name","address":"ip","managed":true}'

杂项

bash
# 获取规则列表
curl http://127.0.0.1:6171/v1/rules \
  -H "X-Key: yourpassword"

# 获取流量统计
curl http://127.0.0.1:6171/v1/traffic \
  -H "X-Key: yourpassword"

# 修改日志等级
curl -X POST http://127.0.0.1:6171/v1/log/level \
  -H "X-Key: yourpassword" \
  -d '{"level":"verbose"}'

# 获取事件中心
curl http://127.0.0.1:6171/v1/events \
  -H "X-Key: yourpassword"

# 停止 Surge 引擎
curl -X POST http://127.0.0.1:6171/v1/stop \
  -H "X-Key: yourpassword"

实用场景

基于 Surge HTTP API，可以实现：

  • Telegram Bot 控制节点切换：通过 Bot 命令切换代理节点
  • 自动测速选节点：定时测试延迟，自动选择最快节点
  • 流量监控面板：实时展示流量使用情况
  • DNS 一键刷新：遇到 DNS 污染时快速清理缓存
开源工具
上一篇

Telegram 机器人群聊配置指南

下一篇

Surge HTTP API 完整指南

分享: