ZSFrp 文档
API

节点 API

接口一览

接口一览

方法路径认证说明
GET/api/v1/nodes否公开节点列表
GET/api/v1/nodes/recommend是按协议推荐节点
GET/api/v1/nodes/:id/latency-test否延迟测试

节点列表

GET /api/v1/nodes

返回对外展示节点，通常包含：

字段（示例）说明
id创建隧道时使用
name显示名称
domain连接域名
region地区
online是否在线
maintenance是否维护中
supportedTunnelTypes如 tcp,udp,http
latencyMs延迟（若有）
load负载（若有）

不含 frps token 等敏感信息。

curl -s https://你的域名/api/v1/nodes

📷 图片占位 /images/docs/api/nodes-list.png
建议内容：控制台节点列表与 API 字段对应。

推荐节点

GET /api/v1/nodes/recommend?protocol=tcp
Authorization: Bearer zsfrp_pat_xxx
参数说明
protocol默认 tcp，可选 udp、http 等

按套餐、负载、协议支持等推荐。无可用节点时 data.node 可能为 null 并带 message。

延迟测试

GET /api/v1/nodes/1/latency-test

响应示例：

{
  "code": 0,
  "data": {
    "nodeId": 1,
    "latencyMs": 28,
    "message": "ok"
  }
}

latencyMs 为 -1 表示连接失败。

此为 服务端到节点 的 RTT，与你本机到节点的体验可能略有差异，但仍可作相对参考。

选型流程

  1. 公开列表了解地区与支持协议
  2. 对候选节点做 latency-test
  3. 或直接用 recommend（需 PAT）
  4. 创建隧道

与隧道 API 配合

# 1. 推荐
curl -H "Authorization: Bearer $TOKEN" 
  "$API/api/v1/nodes/recommend?protocol=tcp"

# 2. 建议端口
curl -H "Authorization: Bearer $TOKEN" 
  "$API/api/v1/tunnels/suggest-remote-port?nodeId=1"

# 3. 创建
curl -X POST -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"name":"t1","nodeId":1,"type":"tcp","localAddr":"127.0.0.1:8080"}' 
  "$API/api/v1/tunnels"

限流

公开接口可能有频率限制，脚本请加间隔；收到 429 时退避重试。

维护与切换

节点 维护中 时不应继续使用，请：

  • 控制台编辑隧道 换节点
  • 或使用 克隆 到 healthy 节点

相关文档

隧道 API

基础路径：/api/v1/tunnels

On this page

接口一览节点列表推荐节点延迟测试选型流程与隧道 API 配合限流维护与切换相关文档