游戏盾SDK接入教程_Windows安卓iOS安全加速接入_飞马盾

面对 DDoS、CC 攻击、恶意连接和源站暴露等风险，仅在服务器前增加一个转发地址，往往难以覆盖登录器、游戏客户端和 APP 的真实连接链路。飞马盾游戏盾 SDK 将安全接入能力集成到客户端进程中，由客户端先建立受保护通道，再把业务连接交给 SDK 返回的本地虚拟端点，适合网络游戏、手游、应用登录、电商和金融类 APP 等需要稳定连接与客户端安全加速的业务。

本文介绍飞马盾游戏盾 SDK 的两种接入方式，并给出 Windows、Android 和 iOS 的基础代码。正式开发时请以当前游戏盾下载包内的头文件、包装层和中文教程为准。

一、游戏盾 SDK 接入能解决什么问题

传统接入通常把服务器 IP 和端口直接写在登录器或 APP 中。攻击者分析客户端或抓取连接后，可能持续针对固定入口和源站发起攻击。SDK 接入后的连接关系是：

游戏或 APP -> SDK 返回的本地虚拟端点 -> 安全加速链路 -> 可用高防节点 -> 源站网关 -> 业务服务器

飞马盾会根据当前游戏盾的转发规则和可用节点生成客户端路由。业务程序不需要自己维护高防节点列表，也不应把某个节点 IP 写死在客户端中。节点发生调整时，SDK 可以重新获取路由并恢复连接。

通过这种方式，可以获得以下能力：

Windows、Android、iOS 多端使用同一套游戏盾规则和授权口径；
支持 TCP 与 UDP 业务，实际能力以套餐和转发规则为准；
SDK 密钥、套餐状态、终端权限与路由签名统一校验；
支持本地端口冲突检测和自动换端口；
业务侧只读取当前可用入口，不需要写死高防节点地址；
可配合高防节点、智能调度、链路加密和源站访问控制使用。

需要注意：SDK 是完整防护链路中的客户端接入层。DDoS/CC 清洗、节点承载能力和源站防火墙策略仍需要按业务规模正确配置。

二、选择源码 SDK 接入还是一键封装

飞马盾提供两类接入方式。

1. 源码 SDK 接入

适合能够修改游戏登录器、客户端或 APP 源码的团队。开发者下载对应平台 SDK，把初始化、启动和本地端点读取逻辑加入业务连接模块。这种方式控制最完整，也更适合长期维护、版本升级和异常恢复。

2. 本地一键封装

适合暂时不方便修改源码，或需要快速验证链路的项目。用户可以在游戏盾页面选择 Windows 封装、安卓封装或 iOS 封装，下载本地工具并生成一次性封装码。封装码绑定当前游戏盾，短时间内有效且只能使用一次。

一键封装能否自动接管业务流量，取决于原程序的网络实现、引擎版本和签名条件。正式运营项目仍建议优先采用源码 SDK 接入；Android 和 iOS 应在真机上完成签名、前后台切换、弱网和版本升级测试。

三、接入前的控制台准备

在写代码前，先完成以下配置：

创建或选择一个有效的游戏盾套餐。
添加并启用转发规则。Windows 使用“PC端”或“PC端+移动端”规则；Android、iOS 使用“移动端”或“PC端+移动端”规则。
确认规则的协议、入口端口、源站地址和源站端口与真实业务一致。
确认套餐已分配可用高防节点，源站网关和防火墙允许游戏盾链路回源。
在“SDK开发集成”中点击“获取密钥”，取得套餐编号和 SDK 密钥。
下载 Windows SDK、Android SDK 或 iOS SDK。下载包中的 sdk-settings.json 已绑定当前游戏盾，但不包含 SDK 密钥。

不要混用不同游戏盾下载的 sdk-settings.json，也不要手工替换其中的 App ID、证书指纹或路由公钥。

四、必须遵守的调用顺序

无论使用哪个平台，业务流程都应保持一致：

从应用资源读取 sdk-settings.json。
在运行时取得套餐编号和 SDK 密钥。
初始化 SDK，并按需开启自动换端口。
在后台线程启动 SDK，等待状态变为已就绪。
枚举 SDK 返回的本地虚拟端点。
让游戏或 APP 连接端点返回的 IP、端口和协议。
网络切换、休眠恢复或规则变更后检查状态，必要时重启 SDK 并重新读取端点。
退出业务或结束进程前停止 SDK。

最容易出现的接入错误，是 SDK 已经启动，但业务仍然连接原来的源站 IP 或旧端口。正确做法是每次启动或重启后读取 SDK 返回值，不要假设本地端口固定，也不要写死 127.0.0.1:25566 或其他端口。

五、Windows 游戏盾 SDK 接入代码

Windows SDK 提供 x86、x64 DLL、C 头文件、Agent 运行组件以及 C++、.NET、Python 等示例。DLL 位数必须与调用进程一致，runtime 目录和 sdk-settings.json 必须随程序一起发布。

下面是 C/C++ 的基础调用示例：

#include "GameShieldSDK.h"

bool StartGameShield(
    const char* subscriptionId,
    const char* sdkKey,
    GS_Endpoint* selectedEndpoint
) {
    if (GS_Initialize("sdk-settings.json", subscriptionId, sdkKey) != GS_OK) {
        return false;
    }

    // 必须在 GS_Start 前设置。端口被占用时自动选择可用端口。
    GS_SetAutoChangePort(1);
    if (GS_Start() != GS_OK) {
        GS_Stop();
        return false;
    }

    const int32_t count = GS_GetEndpointCount();
    for (int32_t index = 0; index < count; ++index) {
        GS_Endpoint endpoint{};
        endpoint.struct_size = sizeof(endpoint);
        if (GS_GetEndpoint(index, &endpoint) == GS_OK) {
            *selectedEndpoint = endpoint;
            return true;
        }
    }

    GS_Stop();
    return false;
}

业务连接时使用 selectedEndpoint->host、selectedEndpoint->port 和 selectedEndpoint->protocol。如果业务按原始端口查找入口，也可以调用 GS_GetCurrentTCPPort 或 GS_GetCurrentUDPPort 获取自动换端口后的实际值。

GS_Start 会执行网络请求并等待本地入口就绪，不要放在 UI 主线程。返回负数时使用 GS_GetLastError 获取可记录的错误类别，但日志中不得写入 SDK 密钥。

六、Android 游戏盾 SDK 接入代码

Android 下载包包含正式 AAR、Kotlin 包装层、当前游戏盾配置和 Android Studio 示例。把 GameShieldSDK.aar 放入 app/libs/，把 sdk-settings.json 放入 app/src/main/assets/，并加入网络权限。

dependencies {
    implementation(files("libs/GameShieldSDK.aar"))
}

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

推荐在协程的 IO 线程启动：

private var shield: GameShieldClient? = null

suspend fun startProtectedConnection(
    subscriptionId: String,
    sdkKey: String
): GameShieldEndpoint = withContext(Dispatchers.IO) {
    val settings = applicationContext.assets
        .open("sdk-settings.json")
        .bufferedReader()
        .use { it.readText() }

    val client = GameShieldClient.create(
        applicationContext,
        settings,
        subscriptionId,
        sdkKey
    )
    client.setAutoChangePort(true)
    client.start()

    val endpoint = client.endpoints().first()
    shield = client
    endpoint
}

取得 GameShieldEndpoint 后，让原来的 Socket、Unity 网络层或登录模块连接 endpoint.host、endpoint.port 和 endpoint.protocol。应用返回前台后应检查 isReady()；网络被系统挂起或切换后，可调用 restart() 并重新读取全部端点。

七、iOS 游戏盾 SDK 接入代码

iOS 下载包提供 GameShieldSDK.xcframework、Swift 包装层、sdk-settings.json 和 Xcode 示例。将 XCFramework 加入应用 Target，把 sdk-settings.json 加入 Copy Bundle Resources，并确认 Target Membership 正确。当前 SDK 最低支持 iOS 15。

private var shield: GameShieldClient?

enum ProtectedConnectionError: Error {
    case noEndpoint
}

func startProtectedConnection(
    subscriptionId: String,
    sdkKey: String
) async throws -> GameShieldEndpoint {
    let client = try GameShieldClient(
        serialNumber: subscriptionId,
        sdkKey: sdkKey
    )
    try client.setAutoChangePort(true)

    try await Task.detached {
        try client.start()
    }.value

    guard let endpoint = try client.endpoints().first else {
        throw ProtectedConnectionError.noEndpoint
    }
    shield = client
    return endpoint
}

业务连接应使用 endpoint.virtualIp、endpoint.virtualPort 和 endpoint.protocol。普通 iOS 应用进入后台后可能被系统暂停，回到前台时应检查 isReady，异常时调用 restart() 并重新获取端点。

直接 IPA 接入还涉及应用签名、Provisioning Profile、Bundle 权限和原程序网络实现。一键封装适合验证，但拥有 Xcode 工程时，源码接入更稳定、更容易持续升级。

八、SDK 密钥与客户端发布安全

套餐编号用于标识当前游戏盾，SDK 密钥用于客户端授权。生产环境应遵守以下要求：

不要把 SDK 密钥写入源码、EXE 资源、APK/IPA 明文资源、命令行或日志；
推荐由受保护的登录会话或业务后台在运行时下发密钥；
sdk-settings.json 可以随应用发布，但不能加入 SDK 密钥；
不要关闭证书、指纹或路由签名校验；
重新生成 SDK 密钥后，旧密钥会失效，需要同步更新客户端的安全下发流程；
Windows 客户端和安装包建议使用可信代码签名证书，移动端使用正式应用签名流程。

九、常见问题排查

SDK 显示已启动，但游戏无法连接

检查业务是否真正改为连接 SDK 返回的本地虚拟端点。继续连接源站、旧入口或写死的本地端口，都不会进入当前 SDK 链路。

为什么控制台改了端口，客户端没有立即变化

客户端运行期间会保留当前入口。规则变化后调用重启接口，并重新读取端点；不要继续使用旧对象中缓存的地址和端口。

为什么本地端口与控制台端口不一致

启用自动换端口后，如果原端口被占用，SDK 会选择可用端口。这是正常行为，应以端点接口或当前端口查询接口返回值为准。

Android 或 iOS 启动后几秒失效

检查 SDK 客户端对象是否被局部变量释放、应用生命周期是否调用了停止方法，以及系统是否限制后台网络。客户端对象应由应用级或业务会话级组件持有。

凭据被拒绝或没有可用端点

检查套餐是否有效、SDK 密钥是否被重新生成、是否存在适用于当前平台的启用规则，以及当前游戏盾是否已分配在线节点。

怎样判断已经真正走游戏盾

确认 SDK 状态为已就绪且活动通道大于零，业务连接目标是 SDK 返回的本地入口，并在控制台观察对应游戏盾的在线终端和连接记录。不要仅凭客户端窗口是否显示“启动成功”判断。

十、上线前检查清单

分别验证登录、选服、进服、断线重连和正常退出；
验证 TCP、UDP 以及一个服务器使用多个业务端口的场景；
验证端口被占用后自动换端口是否正确；
验证 Wi-Fi/蜂窝网络切换、断网恢复、休眠和前后台切换；
验证规则新增、修改后重启 SDK 能重新取得全部入口；
验证节点下线时客户端能够重新调度，而不是写死旧节点；
检查发布包、日志和崩溃平台中不存在 SDK 密钥；
使用正式签名和 Release 构建完成小规模灰度，再逐步扩大用户范围。

十一、为什么选择飞马盾游戏盾 SDK

自建游戏盾并不只是准备几台高防服务器。真正投入运营还需要解决客户端接入、TCP/UDP 转发、节点健康检查、智能调度、链路身份校验、套餐授权、设备管理、日志诊断、网关部署和版本升级等问题。每一项独立开发并不困难，但把它们组合成可长期维护、可交付给客户的系统，需要持续的工程投入。

飞马盾把游戏盾 SDK、Windows/Android/iOS 本地封装、高防节点接入、源站网关、转发规则、终端授权和分销运营能力整合在同一套系统中。用户可以使用自有高防服务器或符合条件的 NAT 节点扩展资源池，减少从零开发控制平台和客户端组件的成本，更快搭建自己的高防游戏盾业务。

如果你正在寻找游戏盾 SDK、APP 安全加速、客户端防护、高防游戏盾、DDoS/CC 防护或游戏盾系统授权方案，可以先使用一个测试游戏盾完成真实业务接入，再根据在线规模逐步增加节点和授权容量。

游戏盾 SDK 怎么接入？Windows、Android、iOS 完整接入教程