面对 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 构建完成小规模灰度，再逐步扩大用户范围。