API 概览
下载
聚焦模式
字号
接入流程
云聚通 Linux SDK 集成步骤如下：
1. 决定是否启用 SDK 内置策略路由管理模块（建议启用，配置一次即可）。
2. 配置加速参数（包含：dataKey、interfaces、加速模式等）。
3. 配置业务引流规则，决定哪些流量需要加速。
4. 配置基于流的多模式规则，细分流量走特定模式（可选）。
5. 启动加速进程。
6. 查询各种 SDK 状态信息。
7. 停止加速进程。
说明：
业务引流规则：决定了哪些流量能被加速，一般情况是五元组规则（全量 or 特定）。
多模式规则：决定了进到加速的流量以哪种模式加速，可配置成 bonding / redundant / rtc 模式，对应一些不同的业务场景，如：时延要求高的业务可以配 redundant 模式，音视频类的业务可以用 rtc 或者 bonding 模式。
多模式规则和配置加速参数中模式的关系：
如果没有配置多模规则，则所有业务统一通过配置加速参数中的模式被加速，对某些特定的业务场景可能不是最优选择。
如果配置了多模式规则，则多模式规则的优先级更高。
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 rule0: from all lookup 1281: from all lookup local79: from 198.18.0.1 lookup 18079: from all fwmark 0x1/0xf lookup 18080: from 192.168.81.80 lookup 10081: 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_tun0口，最终将业务引流到 mp_tun0网卡。SDK 多网协议会对来自 mp_tun0网卡的所有流量进行加速处理。
SDK 策略路由管理会添加优先级为80和81的两个规则。同时，SDK 策略路由管理会将对应的默认路由加入到 ID 为100和101的路由表里，如下：
/tmp # ip route ls table 100default via 192.168.81.1 dev ath0unreachable default metric 50000/tmp # ip route ls table 101default via 10.21.5.17 dev rmnet_mhi0.1unreachable 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 二选一。设备厂商提供的设备唯一序列号。 |
registerEnv | integer | 必选。取值：1。 |
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。 |
enableRecreatePathPconn | bool | 是否开启重建 path。 |
注意：
上述配置需要重启加速进程使配置生效。
首次加速之前需要确定一个 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"。 |
| | |
查询加速流量信息
本接口会返回 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 口）上，请确保网卡名中有 "lan" 字样。
3. 如果在没有 lan 口（或 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-3330"。 |
dstPorts | string | 可选：目的端口，支持范围。例如："3303-3330"。 |
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。
注意：
一旦进行细分流走配置操作，必须重启加速进程使配置生效。
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-3330"。 |
dstPorts | string | 可选：目的端口，支持范围。例如："3303-3330"。 |
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 '{"priority":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-3306"。 |
dstPorts | string | 可选：目的端口号，支持范围。例如："3303-3306"。 |
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 '{}'
诊断功能
本功能可选，主要用于产品运维。
日志路径
SDK 日志默认输出路径为：/var/log，包含 mp-sdk.log 和 mp-speeder.log。
如有需要可指定日志输出路径，修改方式为：
手动修改 /usr/local/etc/mp-speeder/log_config.json 文件中的 logDir 字段，格式需和文件中保持一致。
{"logLevel": "info","autoUpload": false,"uploadInterval": 10,"logDir": "/var/log"}
说明：
1、如果指定的 logDir 路径不存在，默认会创建。
2、修改完成之后需重启 SDK。
日志上报
可选将日志上报后台用于问题定位。日志上报有如下两种方式：
手动上报：执行一次命令，将设备本地保存的多网日志上报后台。
自动上报：设置上报间隔并打开开关后，日志将周期性上报后台。可以随时关闭开关以停止上报日志。
注意：
本地日志最多占用 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'
文档反馈