代理切换接口 API 文档

接口概述

接口地址: /api/proxy/switch
请求方法: POST
认证方式: （orderId + timestamp + sign）
功能说明: 允许用户切换已分配端口的代理出口，支持设备原配置切换和指定地区两种模式
api接口地址 https://byjsgateway.vpsnb.net

认证参数

请求参数

基础参数（必填）

地区参数（可选）

packet_loss和rtt 越低，出口当不满足要求的时就会自动原地区切换，如果需求是出口ip尽量不变动，这两个参数请不要传。

操作模式

模式1：保持上一次配置出口切换

触发条件: 仅传入 gateway_ip 和 ports 参数

如果上一次配置或者开通的时候没有指定地区，则本次切换依然是随机，如果上一次配置指定了地区，则本地切换只在该地区。

模式2：指定地区切换

触发条件: 传入任意一个地区参数

请求示例

示例1：保持上一次配置出口切换（网关是IP地址）

{
  "orderId": "test_user",
  "timestamp": "1750173159",
  "sign": "abc123def456",
  "gateway_ip": "192.168.1.100",
  "ports": [10010, 10011]
}

示例2：保持上一次配置出口切换（网关是域名）

{
  "orderId": "test_user",
  "timestamp": "1750173159",
  "sign": "abc123def456",
  "gateway_ip": "gateway1.example.com",
  "ports": [10010, 10011]
}

示例3：指定地区切换

{
  "orderId": "test_user",
  "timestamp": "1750173159", 
  "sign": "abc123def456",
  "gateway_ip": "192.168.1.100",
  "ports": [10010],
  "province": "广东",
  "city": "深圳",
  "isp": "电信",
  "packet_loss": 10,
  "rtt": 100
}

响应格式

成功响应

{
  "code": 0,
  "msg": "所有端口切换成功: 共2个端口",
  "data": {
    "gateway": "gateway1.example.com",
    "gateway_ip": "192.168.1.100",
    "total_ports": 2,
    "successful_ports": 2,
    "failed_ports": 0,
    "mode": "device_switch",
    "results": [
      {
        "port": 10010,
        "success": true,
        "message": "代理重新配置成功"
      },
      {
        "port": 10011,
        "success": true,
        "message": "代理重新配置成功"
      }
    ]
  }
}

部分成功响应

{
  "code": 206,
  "msg": "部分端口切换成功: 成功1个，失败1个",
  "data": {
    "gateway_ip": "192.168.1.100",
    "total_ports": 2,
    "successful_ports": 1,
    "failed_ports": 1,
    "mode": "location_config",
    "results": [
      {
        "port": 10010,
        "success": true,
        "message": "端口配置更新成功"
      },
      {
        "port": 10011,
        "success": false,
        "message": "网关API请求失败: HTTP 500"
      }
    ]
  }
}

错误响应

{
  "code": 400,
  "msg": "以下端口无效: 端口 10010 不存在或未分配给当前用户; 端口 10011 已过期"
}

响应字段说明

错误码说明

使用场景

1. 保持上一次配置出口切换: 用户需要更换使用代理的出口【如果上一次配置或者开通的时候没有指定地区，则本次切换依然是随机，如果上一次配置指定了地区，则本地切换只在该地区】
2. 指定地区切换: 用户需要切换代理的地理位置或网络特性时
3. 批量操作: 同时切换多个端口的配置

注意事项

1. 支持批量操作，但建议单次请求不超过10个端口