快速接入

最近更新时间:2026-05-28 17:14:00

我的收藏
本指南面向 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 下载 页面进行下载。
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 关键字段speedMode0=默认 / 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 -u

SDK="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"
echo

echo "[2/6] 配置加速参数"
curl -s -X POST "$SDK/client/mp-speeder" \\
-H "Content-Type: application/json" \\
-d "{
\\"dataKey\\": \\"$DATA_KEY\\",
\\"interfaces\\": $ACC_IFS,
\\"scheduleMode\\": \\"bonding\\"
}"
echo

echo "[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"
echo

echo "[6/6] 查询加速状态(最多等待 30 秒)"
for i in $(seq 1 30); do
ready=$(curl -s "$SDK/client/mp-speeder" | grep -o '"ready":[^,}]*' | awk -F: '{print $2}' | tr -d ' ')
if [ "$ready" = "true" ]; then
echo "加速已就绪"
exit 0
fi
sleep 1
done
echo "加速未在 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 main

import (
"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.Reader
if 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"}
// =====================

// 检查用户是否忘记修改 dataKey
if 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 = 30
for i := 1; i <= maxWait; i++ {
body, err := call("GET", "/client/mp-speeder", nil, nil)
if err == nil {
var s status
if 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 怎么办?
A1:请参考 FAQ 文档联系我们 排查。
Q2:业务流量没有走加速?
A2:确认步骤 4 的引流规则与业务实际五元组匹配,用 iptables -t mangle -nvL 观察对应规则的命中计数是否增长。
Q3:怎样修改加速参数(如换 dataKey、换网卡)?
A3:直接重新调用步骤 2 的接口,再调用步骤 6 启动接口即可。
Q4:SDK 服务异常重启后需要重新配置吗?
A4:不需要。配置已持久化到 /usr/local/etc/mp-speeder/,SDK 启动后会自动加载。