一. 交付件说明
linkboost.dll 动态库(后续简称 SDK):由客户 app 调用,主要实现 API 层。
linkboost.h 头文件:由客户 app 选择调用。
二. 接入流程


vendor 厂家集成云聚通 Windows SDK 步骤如下:
1. 策略路由管理(Windows 暂不关注)。
2. 配置加速参数(包含:dataKey、interfaces、加速模式等)。
3. 配置业务引流策略,决定哪些流量需要加速(socks 模式接入不用关注)。
4. 配置基于流的多模式,细分流量走特定模式(可选)。
5. 启动加速进程。
6. SDK 向 MPGW 发起连接请求。
7. MPGW 反馈连接请求成功。
8. SDK 与 MPGW 进入正常通信阶段。
9. 查询 SDK 状态信息(SDK 向用户同步状态)。
10. 停止加速进程。
11. SDK 断开与 MPGW 的连接。
三. 接口说明
1. SDK 管理接口
初始化 SDK
// InitSDK 初始化SDK// 参数:// - disableLogEncrypt: 是否关闭日志加密,1表示关闭日志加密,0表示开启日志加密// 返回: 0表示初始化成功(可重入),-1表示失败int InitSDK(int disableLogEncrypt);
注意:
1. 请确保客户程序在运行时工作路径下有 config 和 log 目录或者具备创建这两个目录的权限。
2. 请确保 SDK 拥有在 config 目录和 log 目录下的文件读写权限。
启动 SDK
// StartSDK 启动SDK服务// 返回: 0表示启动成功(可重入),-1表示启动失败,-2表示SDK未初始化int StartSDK();
停止 SDK
// StopSDK 停止SDK服务// 返回: 0表示停止成功,-1表示SDK未启动int StopSDK();
查看 SDK 状态
// IsSDKRunning 检查SDK是否正在运行// 返回: 1表示运行中,0表示未运行int IsSDKRunning();
2. 加速相关接口(REST API)
API | 说明 |
/api/v2/client/mp-speeder | 配置加速参数 |
/api/v2/client/mp-speeder/start | 开始加速 |
/api/v2/client/mp-speeder/stop | 停止加速 |
/api/v2/client/mp-speeder/restart | 重启加速 |
/api/v2/client/mp-speeder | 查询加速状态 |
/api/v2/client/flowStatistics | 查询加速流量信息 |
/api/v2/client/multi-mode | 配置流转发策略 |
/api/v2/diagnosis/log | 日志上报 |
/api/v2/client/t2Statistics | 查询下车点测速信息 |
配置加速参数
在启动加速进程前,vendor 厂商需要收集必选参数,在启动 SDK 加速时需要作为参数携带。
必选参数:
1. 激活参数四选一:
a. vendor 和 sn: vendor 是设备厂商型号,sn 是设备厂商提供的序列号。
b. dataKey:设备 license key。
c. appId 和 appSign: app 模式注册,在控制台获取。
d. appId 和 appSign 和 gwId:eo 模式注册,在控制台获取。
scheduleMode:默认工作模式:rtc。
说明:云聚通功能激活的四种方式,具体选择哪种 vendor 可根据自身情况决定:
vendor+sn: 通过设备序列号激活,要求提前在腾讯云控制台创建待激活设备。
dataKey: 通过 license key 激活,请向腾讯云销售&商务获取。
appId+appSign:通过 appId 激活,请在云控制台获取。
appId+appSign+gwId:eo 模式使用,需要同时打开 enableEoSch 开关。
调用如下接口将配置加速的各项参数(仅配置参数不启动加速):
datakey 模式
curl -X POST "http://127.0.0.1:9801/api/v2/client/mp-speeder" ^-H "accept: */*" ^-H "Content-Type: application/json" ^-d "{\\"serviceMode\\":0,\\"dataKey\\":\\"xxxxxxx\\",\\"scheduleMode\\":\\"rtc\\",\\"registerEnv\\":-2,\\"tunInterfaceName\\":\\"mp_tun0\\",\\"t2Probe\\":true}"
appId 模式
curl -X POST "http://127.0.0.1:9801/api/v2/client/mp-speeder" ^-H "accept: */*" ^-H "Content-Type: application/json" ^-d "{\\"serviceMode\\": 0,\\"appId\\":\\"app-0eoo3vpctx\\",\\"appSign\\":\\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZXZpY2VOYW1lIjoiamFja3ktdGVzdC0yMC0xIn0.TleKYrzBL1dyp2i8WTBgs8Y8UvBJQv-n2A2BRMT1xuQ\\",\\"scheduleMode\\":\\"rtc\\"}"
eo 模式
curl -X POST "http://127.0.0.1:9801/api/v2/client/mp-speeder" ^-H "accept: */*" ^-H "Content-Type: application/json" ^-d "{\\"serviceMode\\": 0,\\"gwId\\":\\"mpgw-n96i24ugbd\\",\\"appId\\":\\"zone-359h792djt7h\\",\\"appSign\\":\\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZXZpY2VOYW1lIjoiamFja3ktdGVzdC0yMC0xIn0.RWGNKp_DXqnrg7SJ2yR5UV_MDs3_KWDccBURQfBfiYg\\",\\"scheduleMode\\":\\"rtc\\",\\"enableEoSch\\":true}"
本接口传入 Client 实体,定义如下:
名称 | 类型 | 说明 |
dataKey | string | 必选:上述激活模式三选一,设备 dataKey。 |
vendor | string | 必选:上述激活模式三选一,设备厂商型号。 |
sn | string | 必选:上述激活模式三选一,设备厂商提供的设备唯一序列号。 |
appId | string | 可选:上述激活模式三选一,app 模式+ eo 模式注册下使用,eo 模式下填对应的 zoneId。 |
appSign | string | 可选:上述激活模式三选一,app 模式+ eo 模式注册下使用。 |
enableEoSch | boolean | 可选:eo 模式下需为 true。 |
gwId | string | 可选:eo 模式下使用,填写对应的 gatewayId。 |
lineType | [int] | 可选:eo 模式开启指定线路使用。 0:直连。 1:eo。 2:第三方。 |
enableObfuscated | string | 可选:是否开启 ip 混淆功能。 |
encryptSign | string | 可选:开启 ip 混淆时需要填写,加解密 IP 时使用,需要和客户侧 ip 加密的 sign 一致,推荐使用 appSign,加密算法见附录。 |
scheduleMode | string | 可选:Windows 默认加速模式 "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。 |
t2Probe | boolean | 可选:true:打开 t2 测速 false:关闭 t2 测速。 |
authCode | string | 可选:开启免流。 |
注意:
RegisterEnv 为可选参数,仅在测试时使用。商用设备不需要。
上述配置需要 restart 加速进程使配置生效。
配置 socks5 server
如果需要自定义加速 socks5 server 参数,可通过此接口配置。
curl -X POST "http://127.0.0.1:9801/api/v2/client/socks5" ^-H "accept: application/json" ^-H "Content-Type: application/json" ^-d "{\\"enable\\": true, \\"port\\": 12345, \\"userName\\": \\"xxxxx\\", \\"passWord\\": \\"xxxxx\\"}"
注意:
socks5 server 的监听地址为 "127.0.0.1",不可配置。
名称 | 类型 | 说明 |
enable | bool | 必选:是否自定义 socks5 server。 |
port | int | 必选:socks5 server port。 |
userName | string | 必选:socks5 server username。 |
passWord | string | 必选:socks5 server password。 |
如果需要查询 socks5 server 配置,可通过此接口查询
curl -X GET "http://127.0.0.1:9801/api/v2/client/socks5" ^-H "accept: application/json" ^-H "Content-Type: application/json"
开始加速
调用如下接口将启动加速,之后 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 定义:
名称 | 类型 | 说明 |
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 定义:
名称 | 类型 | 说明 |
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 表示当前链路不可用。 |
查询下车点测速信息
当指定了 T2 加速并且指定了下车点,可通过该 API 查询下车点测速信息。
注意:
仅在手动指定下车点的情况下支持下车点测速。当使用 auto 自动选择下车点时,不支持下车点测速。
curl -X GET "http://127.0.0.1:9801/api/v2/client/t2Statistics" -H "accept: application/json" -H "all: true"
名称 | 类型 | 说明 |
area | string | 下车点名称。 |
rttAccelerated | int | sdk 到下车点时延。 |
rttDirect | int | sdk 直连下车点时延。 |
流转发策略配置
流转发策略主要指定流量应该如何转发。
curl -X POST "http://127.0.0.1:9801/api/v2/client/multi-mode" ^-H "accept: application/json" ^-H "Content-Type: application/json" ^-d "{\\"area\\": \\"hongkong\\",\\"speedMode\\": 35}"
名称 | 类型 | 说明 |
appId | string | 可选:基于指定的 appId 规则进行加速。 |
area | string | auto:自动根据 dip 所属地域自动选取下车点。 Frankfurt :法兰克福。 SiliconValley :美国-硅谷。 SaoPaulo :巴西-圣保罗。 Tokyo :日本。 Bangkok :泰国(东南亚服)。 Singapore :新加坡。 HongKong:中国香港。 Seoul:韩国首尔。 |
speedMode | integer | 0 - "DEFAULT":复用默认加速模式。 1 - "DIRECT":不加速,走系统默认网卡。 2 - "bonding":聚合模式。 3 - "rtc":实时音视频模式。 4 - "redundant":多发选收模式。 25 -(保留配置)。 35 - "T2 rtc":先做 rtc 快切,再做 T2全路径加速。 45 - (保留配置)。 |
移动权益认证接口
移动权益认证。如果需要在加速时免流,则先通过此接口获取。
curl -X POST "http://127.0.0.1:9801/api/v2/client/enableCMCCRightsVerify" ^-H "accept: application/json" ^-H "Content-Type: application/json" ^-d "{\\"token\\": \\"xxxxx\\"}"
请求参数:
名称 | 类型 | 说明 |
token | string | 必选:校验 token。 |
guid | string | 必选:校验 guid,搭配 token 一起使用。 |
salt | string | 必选:盐值,加密使用。 |
响应参数:
名称 | 类型 | 说明 |
status | bool | 必选:token 是否认证成功。 |
authCode | string | 可选:如果校验成功,则返回免流认证码。 |
error | string | 可选:当校验失败时通过 error 返回错误。 |
四. 诊断功能
本章功能可选,主要用于产品运维。
日志上报
可选将日志上报后台用于问题定位。日志上报有两种方式:
1. 手动上报:执行一次命令,将设备本地保存的多网日志上报后台。
2. 自动上报:设置上报间隔并打开开关后,日志将周期性上报后台。可以随时关闭开关以停止上传日志。
注意:
本地日志最多占用50MB 存储空间,上报后本地存储的日志将被删除。
配置日志上报参数
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}"
参数:
名称 | 类型 | 说明 |
logLevel | string | 可选:程序日志级别,默认"info",支持配置 "info", "debug", "warn"。 |
autoUpload | boolean | 可选:自动上传开关,默认 false,为 true 时日志自动上传。 |
uploadInterval | integer | 可选:自动上传间隔,默认10分钟,不开启自动上传时不生效。 |
注意:
修改日志采集参数,需要重启 SDK 生效。
手动上报参数
单次上报日志,推荐使用。
curl -X POST "http://127.0.0.1:9801/api/v2/diagnosis/log"
五. 接入示例
SDK 启动示例
using System;using System.Runtime.InteropServices;using System.Threading;class Program{[DllImport("linkboost.dll", CallingConvention = CallingConvention.Cdecl)]static extern int InitSDK(int disableLogEncrypt);[DllImport("linkboost.dll", CallingConvention = CallingConvention.Cdecl)]static extern int StartSDK();[DllImport("linkboost.dll", CallingConvention = CallingConvention.Cdecl)]static extern int StopSDK();[DllImport("linkboost.dll", CallingConvention = CallingConvention.Cdecl)]static extern int IsSDKRunning();private static bool keepRunning = true;static void Main(){// 注册 Ctrl+C 事件处理Console.CancelKeyPress += (sender, e) =>{e.Cancel = true; // 阻止立即退出keepRunning = false;Console.WriteLine("\\n正在停止程序...");};try{Console.WriteLine("正在初始化 SDK...");// 初始化sdk,不加密日志InitSDK(1);Console.WriteLine("正在启动 SDK...");// 启动sdkStartSDK();Console.WriteLine($"SDK Running: {IsSDKRunning()}");Console.WriteLine("\\nSDK 已启动,程序将持续运行");Console.WriteLine("按 Ctrl+C 可以手动结束程序\\n");// 持续运行,直到按 Ctrl+Cwhile (keepRunning){Thread.Sleep(1000); // 每秒检查一次}}finally{Console.WriteLine("正在停止 SDK...");// 停止sdkStopSDK();Console.WriteLine("SDK 已停止,程序退出");}}}
socks5加速
1. 调用移动权益认证(可选)
对于支持移动权益免流的客户,先调用 /api/v2/client/enableCMCCRightsVerify 获取免流认证码。
参数配置:
token:移动提供的 token。
guid:搭配 token 一起使用。
salt:盐值,加密使用。
说明:
如果成功,记录返回值 authCode,在下面第二步时填入。
如果失败,则可以根据需求给用户提示。
2. 配置加速参数
首先,从腾讯云控制台获取 appId 和 app 密钥,然后参考附录的源代码,计算 appSign。再调用:/api/v2/client/mp-speeder(配置加速参数接口)。
按如下参数配置:
appId:填入从腾讯云控制台获取的应用 id。
appSign:根据 app 密钥计算而来,算法参见附录。
scheduleMode:rtc。
authCode(可选):填入第一步移动权益认证接口返回的 authCode。
interfaces:不需要填。
accGateway 和 gwPort:不填。
UUID:不填。
disableCrypto:不填,保持默认。
其它可选参数都不填。
3. 配置转发规则
调用 /api/v2/client/multi-mode(流转发策略配置接口),指定转发策略。
指定参数:
area:auto,自动选择下车点。
speedMode:选择35。
4. 开启 socks5服务
调用 /api/v2/client/socks5(配置 socks5 server 接口)开启 socks5。
指定参数:
enable:true。
port:客户指定。
userName:客户指定。
passWord:客户指定。
5. 开启加速
调用(开始加速接口)后,SDK 将首先连接就近腾讯云网关。
curl -X POST "http://127.0.0.1:9801/api/v2/client/mp-speeder/start" -H "accept: */*" -H "Content-Type: application/json"
6. 将流量引入 socks5
业务 app 流量引入指定 socks5 端口,流量将按配置好的规则转发。
附录:appSign 计算方法
python
import jwtfrom datetime import datetime, timedeltafrom typing import Tupleclass JWTGenerator:EXPIRE_HOURS = 72 # 过期时间,单位小时SECRET_KEY = "shCrVLKq/Hp6UdtVpw8lBqu6ZDcLwOABf2Az67e/pjI=" # APP密钥@classmethoddef generate_sign(cls, device_name: str) -> Tuple[str, int]:"""生成JWT签名"""now = datetime.utcnow()expire_time = now + timedelta(hours=cls.EXPIRE_HOURS)payload = {"nbf": now,"exp": expire_time,"deviceName": device_name}token = jwt.encode(payload,cls.SECRET_KEY,algorithm="HS256")return token, int(expire_time.timestamp())if __name__ == "__main__":try:sign, expire_ts = JWTGenerator.generate_sign("tencent-test")print(f"Signature: {sign}")print(f"Expire Time: {expire_ts}")except Exception as e:print(f"Error generating token: {str(e)}")
golang
package mainimport ("fmt""github.com/dgrijalva/jwt-go/v4""time")func main() {sign, expireTime, err := GenerateSign("tencent-test")if err != nil {panic(err)}println(sign, expireTime)}// SignClaims JwtCustomClaimstype SignClaims struct {jwt.StandardClaimsDeviceName string `json:"deviceName"`}var (ExpireTime = 72 // 过期时间, 单位小时SecretKey = []byte("shCrVLKq/Hp6UdtVpw8lBqu6ZDcLwOABf2Az67e/pjI=") // APP密钥)// GenerateSign 生成签名func GenerateSign(deviceName string) (string, int64, error) {expireTime := time.Now().Add(time.Duration(ExpireTime) * time.Hour)claims := &SignClaims{StandardClaims: jwt.StandardClaims{NotBefore: jwt.Now(),ExpiresAt: jwt.At(expireTime),},DeviceName: deviceName,}println(fmt.Sprintf("%#v", claims))token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)sign, err := token.SignedString(SecretKey)if err != nil {return "", 0, err}return sign, expireTime.Unix(), nil}
java
package org.example;import io.jsonwebtoken.Jwts;import io.jsonwebtoken.SignatureAlgorithm;import java.security.Key;import java.util.Date;import javax.crypto.spec.SecretKeySpec;/*** generate sign*/public class SignGenerate {private static final long EXPIRE_TIME = 72 * 60 * 60 * 1000; // 过期时间, 单位毫秒private static final String SECRET_KEY = "shCrVLKq/Hp6UdtVpw8lBqu6ZDcLwOABf2Az67e/pjI="; // APP密钥public static void main(String[] args) {String deviceName = "tencent-test";String sign = generateSign(deviceName);System.out.println(sign);}public static String generateSign(String deviceName) {Date now = new Date();Date expireDate = new Date(now.getTime() + EXPIRE_TIME);Key key = new SecretKeySpec(SECRET_KEY.getBytes(), SignatureAlgorithm.HS256.getJcaName());return Jwts.builder().claim("deviceName", deviceName).notBefore(now).expiration(expireDate).signWith(key).compact();}}
附录:encryptSign 计算方法
golang
package mainimport ("crypto/sha256""fmt""golang.org/x/crypto/chacha20""net")func main(ip net.IP, psk []byte) ([]byte, error) {if ip.To4() == nil {return nil, fmt.Errorf("invalid ipv4 address")}key := sha256.Sum256(psk)encryptKey := key[:32]nonce := make([]byte, 12)cipher, err := chacha20.NewUnauthenticatedCipher(encryptKey, nonce)if err != nil {return nil, err}// 原地加密(32bit精确输出)ciphertext := make([]byte, net.IPv4len)cipher.XORKeyStream(ciphertext, ip.To4())return ciphertext, nil}