API 概览

最近更新时间:2025-12-04 11:35:52

我的收藏

接入流程

vendor 厂家集成云聚通 Linux SDK 步骤如下:
1. 决定是否启用 SDK 内置策略路由管理模块。
2. 配置加速参数(包含:vendor、sn、interfaces、加速模式等)。
3. 配置业务引流策略,决定哪些流量需要加速。
4. 配置基于流的多模式,细分流量走特定模式(可选)。
5. 启动加速进程。
6. 查询各种 SDK 状态信息。
7. 停止加速进程。




SDK 内置策略路由管理

云聚通 SDK 内置策略路由管理模块,该功能可选,请 vendor 厂家根据自身情况决定是否启用,一般情况下建议使用。
SDK 内置策略路由模块简介
云聚通 SDK 内置的策略路由管理模块是基于 WAN 接口源 IP 的策略路由,让指定源 IP 的包从该源 IP 对应的接口发送出去。如果没有这样的策略路由,包将会统一走默认路由发送出去,会导致 SDK 无法从多网卡收发报文。
例如,设备有 ath0 和 rmnet_mhi0.1 两个 WAN 接口,地址分别为 192.168.81.80 和 10.221.7.233,下一跳网关分别为 192.168.81.1 和 10.21.5.17,那么 SDK 会根据接口 IP 地址的变化和默认路由,生成这样的策略路由:
/tmp # ip rule
0: from all lookup 128
1: from all lookup local
79: from 198.18.0.1 lookup 180
79: from all fwmark 0x1/0xf lookup 180
80: from 192.168.81.80 lookup 100
81: from 10.221.7.233 lookup 101
优先级为79的路由表 id 为180的策略是 SDK 默认会添加,不管 SDK 策略路由管理是否开启都会添加。
其中198.18.0.1为 SDK 为 mp_tun0网卡接口所配置的 IP 地址,firewall mark 0x1/0xf 是对需要加速的业务所打的标记。路由表180的默认出口为 mp_tun 口,最终将业务引流到 mp_tun0网卡。SDK 多网协议会对来自 mp_tun0网卡的所有流量进行加速处理。
SDK 策略路由管理会添加优先级为80和81 的两个规则。同时,SDK 策略路由管理会将对应的默认路由加入到 id 为100和101路由表里面,如下:
/tmp # ip route ls table 100
default via 192.168.81.1 dev ath0
unreachable default metric 50000
/tmp # ip route ls table 101
default via 10.21.5.17 dev rmnet_mhi0.1
unreachable default metric 50000
因此,vendor 厂家可以根据自身 OS 的情况决定是否启用 SDK 内置的策略路由模块。如果不启用 SDK 内置的策略路由模块,那么上述工作需要由 vendor 自行实现。
开启 SDK 策略路由管理
curl -X POST 'http://127.0.0.1:9801/api/v2/route/policyRouteManagment' --header 'enable:true'
注意:
本配置会自动持久化保存,无需多次配置。建议在安装 SDK 时执行一次即可,若每次启动 SDK 都重新开关可能会导致路由异常。
关闭 SDK 策略路由管理
curl -X POST 'http://127.0.0.1:9801/api/v2/route/policyRouteManagment' --header 'enable:false'

加速进程控制

配置加速参数

在启动加速进程前,vendor 厂商需要收集必选参数,在启动 SDK 加速时需要作为参数携带。
必选参数:
1. 激活参数二选一:
vendor 和 sn:vendor 是设备厂商型号,sn 是设备厂商提供的序列号。
dataKey:设备 license key。
2. interfaces:设备 WAN 物理接口列表,参与多网聚合的接口。
3. scheduleMode:默认工作模式:bonding、 redundant、rtc。
说明:
云聚通功能激活的两种方式,具体选择哪种 vendor 可根据自身情况决定:
1. vendor+sn:通过设备序列号激活,要求提前在腾讯云控制台创建待激活设备。
2. dataKey:通过 license key 激活,请向腾讯云销售和商务获取。
ScheduleMode 模式说明:
模式
场景
说明
bonding
推流,大带宽
将业务流量分担到多条链路,充分利用所有链路带宽。
效果:大带宽,可靠传输,抗弱网。
redundant
游戏,控制信令
业务报文在所有链路复制发送,接收方挑选最先到达的报文转发。
效果:消耗额外带宽保证最低时延。
rtc
实时音视频
业务流量优先时延最低的链路传输,同时利用其他链路作为补充。
效果:不消耗额外带宽且保证业务流畅不卡顿,抗弱网能力强。
调用如下接口配置加速的各项参数(仅配置参数不启动加速):
curl -X 'POST' 'http://127.0.0.1:9801/api/v2/client/mp-speeder' -H 'accept: */*' -H 'Content-Type: application/json' -d '{
"dataKey":"get this devicekey from tencent and replace it here",
"interfaces": ["usb0","usb1","eth0"],
"registerEnv": -2,
"scheduleMode": "bonding"
}'
本接口传入 Client 实体,定义如下:
name
Type
说明
dataKey
string
必选:vendor+sn 与 dataKey 二选一。设备 dataKey。
vendor
string
必选:vendor+sn 与 dataKey 二选一。设备厂商型号。
sn
string
必选:vendor+sn 与 dataKey 二选一。设备厂商提供的设备唯一序列号。
interfaces
[string]
必选。参与多网聚合的接口列表。支持指定优先级,范围0~255,数值越小,优先级越高,优先级与网卡以冒号间隔。如果不传入优先级,则默认为64。注:redundant 模式下不支持传入优先级。["eth1:100", "eth2"]。
scheduleMode
string
必选。默认加速模式。"bonding", "redundant", "rtc"。
accGateway
string
可选。指定加速网关 IP,多个 IP 使用逗号分隔。如果不指定该参数,SDK 将自动就近接入。否则强制连接指定加速网关,例如:"120.30.39.129"。
gwPort
string
可选。网关端口,默认:"443"。
UUID
string
可选。硬件指纹,如果不指定该参数,SDK 会自动根据硬件生成。
disableCrypto
integer
可选。允许客户在启动加速时,选择是否加密。默认开启流量加密,关闭加密可以降低流量消耗。
0:开启流量加密(默认)。
1:关闭流量加密。
flowStatisticsInterval
integer
可选。链路加速流量统计频率,默认3秒。
maxRttDisableAggregation
integer
可选。链路参与聚合时延阈值,默认460ms。
maxRttThreshold
integer
可选。链路故障检测启动时延,默认460ms。
minSwitchRTT
integer
可选。链路快切敏感度,默认20ms。
maxDelayUntilFailed
integer
可选。链路参与切换时延阈值,默认460ms。
registerEnv
integer
可选。SDK 连接的云加速网关集群环境。(仅测试用)
0:商用环境(默认)。
-2:客户体验环境(POC 测试环境)。
注意:
RegisterEnv 为可选参数,仅在测试时使用。商用设备不需要。
上述配置需要重启加速进程使配置生效。
首次加速之前需要确定一个 mac 地址不会更改的网卡,将网卡名写入/usr/local/etc/mp-speeder/mp_client_ifname.conf文件中。
格式:echo '{"ifName":"eth0"}' > /usr/local/etc/mp-speeder/mp_client_ifname.conf,请务必配置,否则无法加速。

启动加速

调用如下接口将启动加速,之后 SDK 会创建名为mp_tun0的虚拟网卡,业务流量将根据引流策略被引导至该虚拟接口进行加速。(在调用此接口前,请确保加速参数已配置好)。
curl -X 'POST' 'http://127.0.0.1:9801/api/v2/client/mp-speeder/start' -H 'accept: */*' -H 'Content-Type: application/json'

停止加速

停掉多网后,所有流量都不会加速,加速中止,mp_tun0的虚拟网卡接口销毁。
curl -X 'POST' 'http://127.0.0.1:9801/api/v2/client/mp-speeder/stop' -H 'accept: */*' -H 'Content-Type: application/json'

重启加速

重新启动加速进程,并重新加载配置。该接口一般用于修改配置之后使配置生效。
curl -X 'POST' 'http://127.0.0.1:9801/api/v2/client/mp-speeder/restart' -H 'accept: */*' -H 'Content-Type: application/json'

查询加速状态

本接口会返回 Status 实体,包含 SDK 状态信息。
curl -X GET "http://127.0.0.1:9801/api/v2/client/mp-speeder" -H "accept: */*" -H "Content-Type: application/json"
Status 定义:
name
Type
说明
ready
boolean
加速进程是否正常启动。
UUID
string
设备硬件指纹。
dataKey
string
设备 dataKey。
swVersion
string
SDK 软件版本。
accGateway
string
加速网关 IP 地址。
gatewayPort
string
加速网关端口。
interfaces
[string]
参与多网聚合的接口列表。
scheduleMode
string
默认加速模式,"bonding", "redundant", "rtc"。
registerEnv
integer
SDK 连接的云加速网关集群环境。
0:商用环境(默认)。
-2:客户体验环境(POC 测试环境)。

查询加速流量信息

本接口会返回 Statistics 实体,包含基于网卡的累计加速流量消耗和加速通道实时速率,统计信息以10秒为间隔定期刷新。
curl -X 'GET' 'http://127.0.0.1:9801/api/v2/client/flowStatistics' -H 'accept: application/json' -H 'all: true'
Statistics 定义:
name
Type
说明
interface
string
链路网卡名称。
state
integer
当前链路工作状态:
-2:链路不可用。
60:链路被临时禁用。
100:链路正常。
totalReceivedBytes
integer
接收方向的累计加速流量,单位 Bytes。
totalSendBytes
integer
发送方向的累计加速流量,单位 Bytes。
receivedRate
float
当前网卡加速通道的接收速率,单位 bit/s。
sendRate
float
当前网卡加速通道的发送速率,单位 bit/s。
loss
float
当前网卡加速通道的丢包率。丢包率以小数形式表示,例如0.1表示丢包率为10%, 1表示丢包率为100%。
rtt
integer
当前网卡加速通道的 rtt,单位 ms。
注:-1 表示当前链路不可用。

业务引流

业务引流主要作用是将感兴趣的流量引导进 mp_tun 虚拟接口,以便进行加速。其原理是对配置的五元组流量打标记,做策略路由,通过 mp_tun 口把流量导向 SDK 处理。引过来的流量将采用默认加速模式(在“必选参数”中配置)。
注意:
一旦进行业务引流配置操作,必须重启加速进程使配置生效。
curl -X 'POST' 'http://127.0.0.1:9801/api/v2/client/mp-speeder/restart' -H 'accept: */*' -H 'Content-Type: application/json'

添加全量引流规则

拦截本机下挂设备访问互联网的全量 TCP/UDP 流量,这些流量会被引流进入 SDK。
注意:
1. 全量引流规则只适用于本机下挂设备,不支持本机自身流量。如需加速本机流量,请配置特定引流规则,源 IP 填0.0.0.0。
2. 全量引流会配置在lan口上,请确保网卡名中有 "lan" 字样。
3. 如果在没有lan口的情况下配置了全量引流,可能会导致 SSH 流量被引入,进而导致无法远程连接设备。
curl -X 'POST' 'http://127.0.0.1:9801/api/v2/route/businessRoute' -H 'accept: */*' -H 'all: true'

添加特定引流规则

对特定的业务五元组进行配置加速,需要设置 -H 'all: false'。
curl -X 'POST' \\
'http://127.0.0.1:9801/api/v2/route/businessRoute' \\
-H 'accept: */*' \\
-H 'all: false' \\
-H 'Content-Type: application/json' \\
-d '[
{
"dstIP": "9.134.246.109",
"protocol": "tcp"
}
]'
这个例子里面只对 124.220.191.156 为目的 IP 的 TCP 流量进行加速。
本接口携带 businessRoute 实体,参数说明:
name
Type
说明
srcIP
string
可选:源 IP 地址,支持掩码。例如:"192.168.3.3/30"。
dstIP
string
可选:目的 IP 地址,支持掩码。例如:"192.168.3.3/30"。
protocol
string
可选:"TCP", "UDP"。
srcPorts
string
可选:源端口,支持范围。例如:"3303-3230"。
dstPorts
string
可选:目的端口,支持范围。例如:"3303-3230"。
isBlack
bool
可选:是否黑名单,默认 false。

删除全量引流规则

删除所有加速引流路由,删除后相当于流量不会加速了,虽然加速进程还在。
curl -X DELETE 'http://127.0.0.1:9801/api/v2/route/businessRoute' --header 'all: true'

删除特定引流规则

删除特定加速引流路由,删除后则对应规则的流量不会再被加速。
curl -X 'DELETE' \\
'http://127.0.0.1:9801/api/v2/route/businessRoute' \\
-H 'accept: */*' \\
-H 'all: false' \\
-H 'Content-Type: application/json' \\
-d '[
{
"dstIP": "124.220.191.156",
"protocol": "tcp"
}
]'

查询引流规则

本接口将获取所有引流规则,具体 businessRoute 定义参见上节描述。
curl -X 'GET' 'http://127.0.0.1:9801/api/v2/route/businessRoute'

细分流走特定模式

本功能可选,主要用于有针对性的特定流走不同模式的需求。
典型案例:假设某机器人场景,对于控制信令希望走 redundant 模式以确保超低时延,而对于机载摄像头则采用 RTC 模式以确保视频流畅的同时不会消耗双倍流量。因此,就需要利用本功能,配置匹配规则,根据 IP 五元组精确识别控制流和视频流,然后分别对两条流设置不同的运行模式。
配置匹配规则后,流量将:
1. 首先按照 IP 五元组进行匹配,如果命中则按配置好的规则走特定加速模式;
2. 如果系统中没有配置任何规则,或者没有匹配上任何规则,则流量将采用默认加速模式。默认加速模式在“加速必选参数”中配置;
3. 多模式规则支持优先级,数字越低优先级越高。默认优先级255。
注意:
一旦进行细分流走配置操作,必须重启 restart 加速进程使配置生效。
curl -X 'POST' 'http://127.0.0.1:9801/api/v2/client/mp-speeder/restart' -H 'accept: */*' -H 'Content-Type: application/json'

添加多模式规则

multi-mode 的 body 携带 SpeedModeRule 参数:
curl -X 'POST' \\
'http://127.0.0.1:9801/api/v2/client/multi-mode' \\
-H 'accept: application/json' \\
-H 'Content-Type: application/json' \\
-d '{
"dstIP": "124.220.191.156/32",
"protocol": "UDP",
"speedMode": 3
}'
SpeedModeRule 实体参数说明:
name
Type
说明
priority
integer
可选:1-255,数字越低优先级越高。默认优先级255。
srcIP
string
可选:源IP地址,支持掩码。例如:"192.168.3.3/30"。
dstIP
string
可选:目的 IP 地址,支持掩码。例如:"192.168.3.3/30"。
protocol
string
可选:"TCP"、 "UDP"、 "ANY"。
srcPorts
string
可选:源端口,支持范围。例如:"3303-3230"。
dstPorts
string
可选:目的端口,支持范围。例如:"3303-3230"。
speedMode
integer
必选:
● 0 - "DEFAULT":复用默认加速模式。
● 1 - "DIRECT":不加速,走系统默认网卡。
● 2 - "bonding":聚合模式。
● 3 - "rtc":实时音视频模式。
● 4 - "redundant":多发选收模式。

删除多模式规则

1. 删除单条规则。
curl -X 'DELETE' \\
'http://127.0.0.1:9801/api/v2/client/multi-mode' \\
-H 'accept: application/json' \\
-H 'all: false' \\
-H 'Content-Type: application/json' \\
-d '{
"pritority":0,
"dstIP": "124.220.191.156/32",
"protocol": "UDP"
}'
参数如下:
name
Type
说明
priority
integer
可选:1-255,数字越低优先级越高。默认优先级255。
srcIP
string
可选:源IP地址,支持掩码。例如:"192.168.3.3/30"。
dstIP
string
可选:目的 IP 地址,支持掩码。例如:"192.168.3.3/30"。
protocol
string
可选:"TCP"、"UDP"、"ANY"。
srcPorts
string
可选:源端口,支持范围。例如:"3303-3230"。
dstPorts
string
可选:目的端口,支持范围。例如:"3303-3230"。
2. 删除所有规则。
curl -X 'DELETE' \\
'http://127.0.0.1:9801/api/v2/client/multi-mode' \\
-H 'accept: application/json' \\
-H 'all: true' \\
-H 'Content-Type: application/json' \\
-d '{}'

查询多模式规则

本接口会返回 SpeedModeRule 实体,具体返回参数参见上节 SpeedModeRule 定义。
header 中携带 -H 'all: true' 代表查询所有多模规则。
curl -X 'GET' \\
'http://127.0.0.1:9801/api/v2/client/multi-mode' \\
-H 'accept: application/json' \\
-H 'Content-Type: application/json' \\
-H 'all: true' \\
-d '{}'

诊断功能

本功能可选,主要用于产品运维。

日志上报

可选将日志上报后台用于问题定位。日志上报有如下两种方式:
手动上报:执行一次命令,将设备本地保存的多网日志上报后台。
自动上报:设置上报间隔并打开开关后,日志将周期性上报后台。可以随时关闭开关以停止上传日志。
注意:
本地日志最多占用 50MB 存储空间,上报后本地存储的日志将被删除。
修改日志采集参数,需要重启 SDK 才能生效。
1. 配置日志上报参数。
curl -X POST 'http://127.0.0.1:9801/api/v2/diagnosis/log' -H 'accept: application/json' -H 'Content-Type: application/json' -d '{
"logLevel": "debug",
"upload": false,
"uploadInterval": 10
}'
参数说明:
name
Type
说明
logLevel
string
可选:程序日志级别,默认"info",支持配置 "info", "debug", "warn"。
autoUpload
boolean
可选:自动上传开关,默认 false,为 true 时日志自动上传。
uploadInterval
integer
可选:自动上传间隔,默认10分钟,不开启自动上传时不生效。
2. 手动上报日志
单次上报日志,推荐使用。
curl -X POST 'http://127.0.0.1:9801/api/v2/diagnosis/log'

测速逃生回调

添加回调接口

curl -X POST
'http://127.0.0.1:9801/api/v2/client/setCallback'
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d '{
"callback_url": "http://127.0.0.1:9801/api/v2/client/callBackMock"
}'
回调消息体
{
"acc_mode": "1",
"mandatory": true,
"code": 2,
"reason": "Acc RTT 496.634µs over Master 447.855µs * 1 in 5m0s"
}
字段说明:
字段
类型
含义
acc_mode
string
加速模式。
acc_mode返回值:
1:聚合模式;
2:双发模式;
3:快切模式。
mandatory
bool
通知 SDK 是否需要主动关闭加速,false 时表示通知事件仅作为建议。
code
int
关闭加速的异常码。
code返回值:
-6:ACC 链路持续丢包异常;
-7:ACC 链路最大时延异常,ACC 链路时延连续大于指定时延并且主链路正常;
-8:ACC 链路平均时延在时间窗口内超过主链路平均时延;
-9:ACC 链路平均时延超过设置的阈值;
-100:可能存在链路异常,仅针对聚合模式;
2:加速无效果,建议关闭加速。
reason
string
关闭加速的具体原因 。
注意:
配置完成之后需要重启才能加速生效。

测速配置

此功能需手动配置测速配置文件,文件位置:/usr/local/etc/mp-speeder/metric.json,可使用默认配置,也可自定义。
根据所需要的加速模式进行对应配置,这里以聚合模式举例:

"bonding":{
"probeCfg": {
"fastProbeInterval": 200,
"normalProbeInterval": 1000,
"minTimeForSelectProbePoint": 3000
},
"checkCfg": {
"quicDetectTime": 10000,
"primaryDetectTime":60000,
"secondaryDetectTime":300000,
"iQRAlpha": 0.75,
"minDetectCount": 4,
"maxDetectRTT": 400,
"detectTimeout": 1000
},
"enableAcc": {
"lossRate": 5,
"quicRTT": 100,
"avgRTT": 110,
"jitterRTT": 20,
"mdevRTT": 20,
"maxRTT": 300,
"disableQuicWndDetect": true,
"disableAvgRTTDetect": false,
"disableJitterDetect": false,
"disableLossDetect": false
},
"disableAcc": {
"lossCount": 4,
"maxRTTCount": 4,
"avgRTT": 130,
"toleranceRate": 1.1,
"minAvgRTT": 66,
"SecondaryToleranceRate":1.0,
"SecondaryJitterRate":0.8,
// 逃生:连续 ${lossCount} 个丢包并且主链路没有连续丢包
"EnableLossDetect": true,
// 逃生:连续 ${maxRTTCount} 个rtt大于 ${checkCfg.maxDetectRTT} 并且主链路正常
"EnableMaxRTTDetect": false,
// 逃生:${checkCfg.primaryDetectTime} 时间窗口内acc链路的avgRTT大于 ${disableAcc.avgRTT}
"EnablePrimaryAvgRTTDetect": false,
// 逃生:${checkCfg.primaryDetectTime} 时间窗口内acc链路的avgRTT大于主链路avgRTT
"EnablePrimaryDetect": false,
// 建议关闭:${checkCfg.secondaryDetectTime} 时间窗口内acc链路的avgRTT大于主链路avgRTT
"EnableSecondaryDetect": false,
// 建议关闭:${checkCfg.primaryDetectTime} 时间窗口内所有辅链路全丢包
"EnableSlaveLossDetect": false
}
}

注意:
配置完成之后需要重启才能加速生效。

查看回调接口

curl -X 'GET'
'http://127.0.0.1:9801/api/v2/client/getCallback'
-H 'accept: application/json'
-H 'Content-Type: application/json'