API概览-dll

最近更新时间:2026-05-25 10:45:32

我的收藏

一. 交付件说明

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...");
// 启动sdk
StartSDK();

Console.WriteLine($"SDK Running: {IsSDKRunning()}");
Console.WriteLine("\\nSDK 已启动,程序将持续运行");
Console.WriteLine("按 Ctrl+C 可以手动结束程序\\n");

// 持续运行,直到按 Ctrl+C
while (keepRunning)
{
Thread.Sleep(1000); // 每秒检查一次
}
}
finally
{
Console.WriteLine("正在停止 SDK...");
// 停止sdk
StopSDK();
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 jwt
from datetime import datetime, timedelta
from typing import Tuple


class JWTGenerator:
EXPIRE_HOURS = 72 # 过期时间,单位小时
SECRET_KEY = "shCrVLKq/Hp6UdtVpw8lBqu6ZDcLwOABf2Az67e/pjI=" # APP密钥

@classmethod
def 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 main

import (
"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 JwtCustomClaims
type SignClaims struct {
jwt.StandardClaims
DeviceName 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 main

import (
"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
}