开发文档

NetGuard SDK 应接入 Windows、Android 或 iOS 客户端，不应接入服务端应用。请先下载客户端 SDK，再按下面的平台说明完成同步初始化。初始化成功后，客户端连接 SDK 提供的本地地址，后续 App 业务及内嵌 Web 业务流量由 NetGuard 转发。

接入准备

确认客户端平台、最低系统版本以及发布方式；
确认需要转发的 TCP、UDP 或 App 内嵌 Web 业务；
登录管理后台，配置业务源站、协议和端口，并取得 AppId；
允许指定盾机访问源站，并隐藏原有直连地址；
交付版本以项目确认的文件、版本号和校验值为准。

接入流程

下载并加入对应平台 SDK；
在客户端启动阶段同步初始化；
初始化成功后，把业务目标改为分配的本地地址；
验证正常通信、切网、节点切换与无感重连；
上线前限制源站仅接受指定盾机访问。

示例项目

示例仓库提供 Windows、Android、iOS 和 UniApp 的接入示例，可用于了解 SDK 初始化与基础转发流程。示例仓库用于演示，实际项目请以 NetGuard 交付版本和说明为准。

Windows 接入

Windows SDK 提供 Shield.exe 和 Shield.dll，最低支持 Windows 7。Windows 应用可选择零代码启动或动态库同步接入：

零代码接入

将 Shield.exe、Shield.dll 和业务程序放在同一目录，创建 Shield.ini，填写 AppId 与业务主程序路径后运行 Shield.exe：

ini

[Shield]
AppID = YOUR_APP_ID
; 将 YOUR_APP_ID 替换为你自己的 AppId
AppExe = YOUR_APP.exe
; 将 YOUR_APP.exe 替换为你的业务程序路径

AppExe 支持相对路径或绝对路径。此方式适合不希望修改业务代码的 Windows 应用。

动态库接入

/* 建议在独立进程中加载此动态库。
 * 直接加载到业务进程可能导致业务进程崩溃
 * 或无法连接服务器
 */

// 1. 声明 SDK 导出的函数
extern "C" {
    typedef int (__stdcall *InitFunc)(char *, char *);
}

// 2. 在适当时机加载动态库并初始化
HMODULE mod = LoadLibraryA("Shield.dll");
if (!mod)
    return; // 找不到 Shield.dll

InitFunc init = (InitFunc)GetProcAddress(mod, "Init");
if (!init)
    return; // 找不到 Init 函数

// 将 YOUR_APP_ID 替换为你自己的 AppId
int result = init(NULL, "YOUR_APP_ID");
if (result != 0)
    return; // 返回非零值表示初始化失败
// 初始化成功后从这里继续执行

初始化成功后 SDK 服务线程仍在运行，应用应保持动态库已加载直到进程退出。需要与业务进程隔离时，可以使用独立进程运行 SDK；同一 Windows 应用包含多个业务进程时，也应由该独立 SDK 进程提供本地服务。

Android 接入

Android SDK 以 AAR 交付，最低支持 Android 4.4（API 19）。把 AAR 放入主工程的 app/libs：

groovy

android {
    sourceSets.main {
        jniLibs.srcDirs = ['libs']
    }
}

dependencies {
    implementation files('libs/libshield.aar')
}

在应用启动阶段同步初始化：

java

// 将 YOUR_APP_ID 替换为你自己的 AppId
int result = Shield.Init(null, "YOUR_APP_ID");
if (result != 0) {
    // 返回非零值表示初始化失败
}

初始化可能执行网络请求，应由应用根据自身启动流程选择合适的调用线程。

iOS 接入

iOS SDK 提供 Shield.h 和 libshield.a，最低支持 iOS/iPadOS 12，并需要按交付说明链接所需系统框架：

objective-c

// 1. 首先将 libshield.a 加入 iOS 工程，否则编译会失败。

// 2. 引入头文件
#import "Shield.h"

// 3. 在适当时机初始化
Shield *shield = [Shield getInstance];
// 将 YOUR_APP_ID 替换为你自己的 AppId
NSInteger result = [shield Init:nil key:@"YOUR_APP_ID"];
if (result != 0) {
    // 返回非零值表示初始化失败
}

初始化失败

下面列出初始化函数的常见返回值。

返回值	含义
0	初始化成功
1	AppId 为空或为 null
3	无法取得配置或没有设置转发规则
4	无法监听本地地址或端口已被占用
9	保留参数不符合接口要求

不同交付版本可能增加平台错误码，请以随版本提供的头文件和说明为准。

获取客户端 IP

正常情况下，源站只能获取盾机的 IP，无法获取客户端真实 IP。

请在源站下载并安装对应的真实 IP 插件。支持范围、系统版本和部署文件以项目交付说明为准。

如果源站运行在 Windows 上，安装后需要重启应用服务；如果运行在 Linux 上，安装后立即生效。真实 IP 仅支持私有化部署环境。

后续步骤

登录管理后台，正确添加所需的转发规则；
将业务目标地址改为对应应用实例分配的本地地址；
Android 和 iOS 使用 127.0.0.1；
Windows 应用从管理后台获取本地地址；
每个 Windows 应用对应一个 NetGuard 实例，并使用该实例分配的本地地址；
同一 Windows 应用包含多个业务进程时，可由独立 SDK 进程提供本地服务；
NetGuard 不转发到 0–1023 端口。

上线检查

源站防火墙只允许指定盾机连接；
客户端不再包含源站直连地址；
记录 SDK 版本、校验值和回滚版本；
先灰度发布，再扩大客户端范围；
验证业务通信、切网、休眠、前后台恢复和节点切换；
监控源站连接、节点带宽、客户端延迟和初始化错误。

遇到问题时请查看常见问题，并提供平台、SDK 版本、错误码、发生时间和复现步骤。

开发文档 ​

接入准备 ​

接入流程 ​

示例项目 ​

Windows 接入 ​

零代码接入 ​

动态库接入 ​

Android 接入 ​

iOS 接入 ​

初始化失败 ​

获取客户端 IP ​

后续步骤 ​

上线检查 ​