本指南面向 Linux SDK 接入方,提供从安装、配置到启动加速的完整步骤,包含 Shell 与 Go 两种调用示例。SDK 默认在本机
127.0.0.1:9801 提供 HTTP API。1. 概述
Linux SDK 通过本机 HTTP 接口对外提供加速能力。客户只需按顺序调用几个 API,即可完成策略路由配置、加速参数下发、业务引流配置和加速启动。
说明:
使用模式说明:本指南是首次接入的标准化流程。在生产环境中,所有配置项(策略路由、加速参数、网卡、业务引流等)都只需配置一次即可,配置会被持久化保存。如果配置无变化,后续日常运维只需调用启动加速和停止加速两个接口即可,无需重复执行配置步骤。
前置条件:
操作系统:Linux(amd64 / aarch64 / armv7l)。
运行权限:
root(涉及策略路由、iptables、tun 设备)。准备好从腾讯云控制台获取的
dataKey(设备密钥)。2. 安装
SDK 以自解压 BIN 包形式发布,命名格式为:
MP_SDK_V1.0R002_<commit>_<arch>.BIN
安装命令为:
chmod +x MP_SDK_V1.0R002_xxxx_x86_64.BIN./MP_SDK_V1.0R002_cc80499b31dd_x86_64.BIN
注意:
如果 BIN 包安装失败:部分操作系统环境(如低版本 glibc、定制内核等)可能无法直接执行 BIN 包,此时可使用 tar 包方式手动安装。
安装后关键路径:
路径 | 说明 |
/usr/local/bin/mp-sdk/mp-sdk | SDK 主程序(HTTP 服务) |
/usr/local/bin/mp-speeder/mp-speeder | 加速进程 |
/usr/local/etc/mp-speeder/mp_client_ifname.conf | 网卡配置文件 |
/usr/local/etc/mp-speeder/data/mp_client.json | 加速参数配置文件 |
验证安装命令:
# 检查 SDK 进程是否运行ps -ef | grep mp-sdk | grep -v grep
配置网卡(一次性操作):安装完成后需要写入一次网卡配置,用于生成本机认证参数。建议选取一个 MAC 地址不会变化的网卡(例如
eth0)。echo '{"ifName":"eth0"}' > /usr/local/etc/mp-speeder/mp_client_ifname.conf
3. 使用流程
3.1 调用流程图


调用方与 SDK 之间的交互时序如下:
1. 调用方首先进行一次性的策略路由管理配置;
2. 随后依次向 SDK 配置加速参数;
3. 业务引流策略;
4. 可选的特定流量走特定模式配置;
5. 完成所有参数配置后,调用方向 SDK 发起启动加速进程的指令;
6. SDK 运行期间可将状态信息反馈给调用方(虚线表示异步/回调返回);
7. 当业务结束时,调用方再向 SDK 发送停止加速进程的指令,完成整个生命周期的管理。
3.2 接口清单
步骤 | 作用 | 方法 | 路径 |
1 | 开启策略路由 | POST | /api/v2/route/policyRouteManagement |
2 | 配置加速参数 | POST | /api/v2/client/mp-speeder |
3 | 添加业务引流 | POST | /api/v2/route/businessRoute |
4 | 添加多模规则(可选) | POST | /api/v2/client/multi-mode |
5 | 启动加速 | POST | /api/v2/client/mp-speeder/start |
6 | 查询加速状态 | GET | /api/v2/client/mp-speeder |
7 | 停止加速 | POST | /api/v2/client/mp-speeder/stop |
8 | 重启加速 | POST | /api/v2/client/mp-speeder/restart |
3.3 核心概念
加速链路涉及三个关键概念,分别对应流量的“入”和“出”两个方向:
业务引流(入):决定哪些流量进入加速程序。一般通过 iptables 实现,未命中引流规则的流量走原有路径,不受加速影响。对应步骤 3。
默认模式(出·兜底):所有进入加速程序的流量默认走转发模式,在步骤 2「配置加速参数」的
scheduleMode 字段设置(bonding / redundant / rtc)。对应步骤 2。多模规则(出·特殊,可选):为特殊五元组指定与默认模式不同的转发模式,优先级高于默认模式,不配置时所有流量都走默认模式。
典型场景:默认走
bonding 聚合,对可靠性要求高的关键业务走 redundant 双发。

一句话总结:业务引流是入,模式是出;默认模式是兜底,多模规则是特殊。
3.4 详细说明
步骤 1:开启策略路由
让 SDK 接管多网卡的策略路由管理,通过 Header
enable: true 开启(false 关闭)。注意:
强烈建议在首次接入时调用一次开启即可,配置会持久化,后续无需重复开启。
步骤 2:配置加速参数
下发
dataKey、参与加速的网卡、调度模式等参数,参数会持久化到 /usr/local/etc/mp-speeder/data/mp_client.json。其中 scheduleMode 即默认模式。Body 关键字段如下:
字段 | 类型 | 必填 | 说明 |
dataKey | string | 是 | 控制台获取的设备密钥 |
interfaces | [string] | 是 | 参与加速的网卡列表,如 ["eth0","eth1"] |
scheduleMode | string | 否 | 默认模式: bonding / redundant / rtc,默认 bonding;作为兜底转发模式 |
步骤 3:添加业务引流
声明哪些五元组流量需要被加速,对应 3.3 核心概念 中的业务引流(入)。未命中引流规则的流量走原有路径,不进入加速程序。
字段 | 示例 | 说明 |
srcIP | 192.168.1.0/24 | 源地址段,可省 |
dstIP | 10.0.0.0/24 | 目的地址段 |
protocol | TCP / UDP | 协议 |
srcPorts | 0-65535 | 源端口范围,可省 |
dstPorts | 443 或 8000-9000 | 目的端口 |
步骤 4:添加多模规则(可选)
对应多模规则(特殊)。仅针对已进入加速程序的流量生效,为特定五元组指定与默认模式不同的转发模式,优先级高于默认模式;如不需要可跳过此步,所有流量均走默认模式。
Body 关键字段:
speedMode(0=默认 / 1=直连 / 2=bonding / 3=rtc / 4=redundant),其他五元组字段同上。步骤 5:启动加速
启动加速进程。
步骤 6:查询加速状态
轮询此接口直到返回字段
ready == true,表示加速通道已建立。若加速长时间(如1分钟)未就绪,请参考官网 FAQ 文档或联系项目人员排查。
日常启停
首次接入完成后,配置已经持久化。后续如果配置无变化,日常只需调用以下接口即可:
启动加速:
POST /api/v2/client/mp-speeder/start停止加速:
POST /api/v2/client/mp-speeder/stop重启加速:
POST /api/v2/client/mp-speeder/restart注意:
配置变更(如更换
dataKey、调整网卡、修改业务引流规则等)后,需要调用重启加速接口使新配置生效。4. 完整示例
以下示例严格按上面的 6 步顺序执行,可直接运行。
注意:
BIN 包安装完成后会自动拉起加速进程。因此在调用配置接口后需要使新配置生效,有以下两种方式:
1. 在调用所有配置接口之前,先调用一次停止加速(
POST /api/v2/client/mp-speeder/stop),然后正常执行配置步骤,最后调用启动加速;2. 正常执行配置步骤,最后不调用启动加速(start),而是调用重启加速接口(
POST /api/v2/client/mp-speeder/restart)使新配置生效。以下示例采用方式 2,直接在最后调用重启加速。
4.1 Shell 示例
将以下脚本保存为
quick_start.sh,按需修改 DATA_KEY 等变量后执行:#!/bin/bash# Linux SDK 一键接入示例set -uSDK="http://127.0.0.1:9801/api/v2"# ==== 按实际情况修改以下变量 ====DATA_KEY="PUT_YOUR_DATA_KEY_HERE"ACC_IFS='["eth0","eth1"]' # 参与加速的网卡列表SRC_CIDR="0.0.0.0/0"DST_CIDR="10.0.0.0/24"DST_PORTS="443"PROTO="TCP"# =============================# 检查用户是否忘记修改 DATA_KEY[ "$DATA_KEY" = "PUT_YOUR_DATA_KEY_HERE" ] && { echo "请先修改 DATA_KEY 变量为实际的 dataKey"; exit 1; }echo "[1/6] 开启策略路由"curl -s -X POST "$SDK/route/policyRouteManagment" -H "enable: true"echoecho "[2/6] 配置加速参数"curl -s -X POST "$SDK/client/mp-speeder" \\-H "Content-Type: application/json" \\-d "{\\"dataKey\\": \\"$DATA_KEY\\",\\"interfaces\\": $ACC_IFS,\\"scheduleMode\\": \\"bonding\\"}"echoecho "[3/6] 添加业务引流"curl -s -X POST "$SDK/route/businessRoute" \\-H "all: false" \\-H "Content-Type: application/json" \\-d "[{\\"srcIP\\": \\"$SRC_CIDR\\",\\"dstIP\\": \\"$DST_CIDR\\",\\"protocol\\": \\"$PROTO\\",\\"dstPorts\\": \\"$DST_PORTS\\"}]"echo# 步骤 4(可选,需要按特定模式调度时再使用)# curl -s -X POST "$SDK/client/multi-mode" \\# -H "Content-Type: application/json" \\# -d '{"dstIP":"10.0.0.0/24","protocol":"TCP","dstPorts":"443","speedMode":2,"priority":100}'echo "[5/6] 重启加速(使新配置生效)"curl -s -X POST "$SDK/client/mp-speeder/restart"echoecho "[6/6] 查询加速状态(最多等待 30 秒)"for i in $(seq 1 30); doready=$(curl -s "$SDK/client/mp-speeder" | grep -o '"ready":[^,}]*' | awk -F: '{print $2}' | tr -d ' ')if [ "$ready" = "true" ]; thenecho "加速已就绪"exit 0fisleep 1doneecho "加速未在 30 秒内就绪"exit 1
停止加速:
curl -s -X POST "http://127.0.0.1:9801/api/v2/client/mp-speeder/stop"
4.2 Go 示例
将以下代码保存为
main.go,使用 go run main.go 执行(仅依赖标准库):package mainimport ("bytes""encoding/json""fmt""io""log""net/http""os""time")const sdkBase = "http://127.0.0.1:9801/api/v2"// 通用 HTTP 调用func call(method, path string, headers map[string]string, body interface{}) ([]byte, error) {var reqBody io.Readerif body != nil {bs, _ := json.Marshal(body)reqBody = bytes.NewReader(bs)}req, err := http.NewRequest(method, sdkBase+path, reqBody)if err != nil {return nil, err}if body != nil {req.Header.Set("Content-Type", "application/json")}for k, v := range headers {req.Header.Set(k, v)}resp, err := http.DefaultClient.Do(req)if err != nil {return nil, err}defer resp.Body.Close()respBody, _ := io.ReadAll(resp.Body)if resp.StatusCode >= 400 {return respBody, fmt.Errorf("status=%d body=%s", resp.StatusCode, string(respBody))}return respBody, nil}func main() {// 简化日志格式:仅保留时间,不带文件名前缀log.SetFlags(log.LstdFlags)// ==== 按实际情况修改 ====dataKey := "PUT_YOUR_DATA_KEY_HERE"accIfs := []string{"eth1"}// =====================// 检查用户是否忘记修改 dataKeyif dataKey == "PUT_YOUR_DATA_KEY_HERE" {log.Fatal("请先修改 dataKey 变量为实际的 dataKey")}// 1. 开启策略路由log.Println("[1/6] 开启策略路由 ...")_, err := call("POST", "/route/policyRouteManagment",map[string]string{"enable": "true"}, nil)if err != nil {log.Fatalf("开启策略路由失败: %v", err)}// 2. 配置加速参数log.Println("[2/6] 配置加速参数 ...")accCfg := map[string]interface{}{"dataKey": dataKey,"interfaces": accIfs,"scheduleMode": "bonding",}_, err = call("POST", "/client/mp-speeder", nil, accCfg)if err != nil {log.Fatalf("配置加速参数失败: %v", err)}// 3. 添加业务引流log.Println("[3/6] 添加业务引流 ...")routes := []map[string]string{{"srcIP": "0.0.0.0/0","dstIP": "10.0.0.0/24","protocol": "TCP","dstPorts": "443",},}_, err = call("POST", "/route/businessRoute",map[string]string{"all": "false"}, routes)if err != nil {log.Fatalf("添加业务引流失败: %v", err)}// 4. (可选)添加多模规则// modeRule := map[string]interface{}{// "dstIP": "10.0.0.0/24",// "protocol": "TCP",// "dstPorts": "443",// "speedMode": 2,// "priority": 100,// }// call("POST", "/client/multi-mode", nil, modeRule)// 5. 重启加速(使新配置生效)log.Println("[5/6] 重启加速 ...")_, err = call("POST", "/client/mp-speeder/restart", nil, nil)if err != nil {log.Fatalf("重启加速失败: %v", err)}// 6. 轮询加速状态log.Println("[6/6] 等待加速就绪(最多 30 秒)...")type status struct {Ready bool `json:"ready"`}const maxWait = 30for i := 1; i <= maxWait; i++ {body, err := call("GET", "/client/mp-speeder", nil, nil)if err == nil {var s statusif json.Unmarshal(body, &s) == nil && s.Ready {log.Printf("加速已就绪(耗时 %ds)", i)return}}time.Sleep(time.Second)}log.Println("加速未在 30 秒内就绪")os.Exit(1)}
停止加速(独立调用):
call("POST", "/client/mp-speeder/stop", nil, nil)
5. 测试验证
5.1 经过加速通道访问
curl --interface mp_tun0 https://www.qq.com
正常返回 HTML 即表示加速通道可达。
5.2 验证业务引流是否命中
iptables -t mangle -nvL
查看与你配置的业务引流规则相关的链(pkts/bytes 计数会持续增长),即说明业务流量已经被引到加速通道。
6. 常见问题
Q1:调用启动后
ready 一直为 false 怎么办?Q2:业务流量没有走加速?
A2:确认步骤 4 的引流规则与业务实际五元组匹配,用
iptables -t mangle -nvL 观察对应规则的命中计数是否增长。Q3:怎样修改加速参数(如换 dataKey、换网卡)?
A3:直接重新调用步骤 2 的接口,再调用步骤 6 启动接口即可。
Q4:SDK 服务异常重启后需要重新配置吗?
A4:不需要。配置已持久化到
/usr/local/etc/mp-speeder/,SDK 启动后会自动加载。