Documents
Product Categories
HigherShield
Product Categories
HigherShield
HigherShield
Aug 05, 2024 And File...，選擇 Kiwi.framework 文件 Embed 選擇 Do Not Embed
引入頭文件
#import
調用初始化接口
/**
* @breif 初始化接口，不需要重複調用接口。會訪問網絡，不要放在 UI線程中
* @param appkey 控制台獲取的 appkey
* @return 0表示成功，非 0表示失敗，請諮詢 Kiwi開發人員
*/
+(int) Init:(const char *)appkey;
調用代码示例：
// 請替換真實 appkey
const char *appkey = "P8+LRKkfH6m59+x/WBk+8l74OmBMSRdK7rYg+FaS/74=";
int ret = [Kiwi Init:appkey];
NSLog(@"Kiwi Init return %d", ret);調用轉化接口
/**
* @breif 轉化接口，將 rs標識轉換為本地訪問。不會訪問網絡，不會卡頓
* @param name 控制台配置的防護目標 rs標識
* @param ip 轉換後的 ip緩衝區指針
* @param ip_len 轉換後的 ip緩衝區長度
* @param port 轉換後的端口緩衝區指針
* @param port_len 轉換後的端口緩衝區長度
* @return 0表示成功，非 0表示失敗，請諮詢 Kiwi開發人員
*/
+(int) ServerToLocal:(const
char*)name :(char*)ip :(int)ip_len :(char*)port :(int)port_len;
調用程式示例：
char ip[40] = {0};
char port[40] = {0};
// 請替換真實 rs標識
const char *name = "echo";
int ret = [Kiwi ServerToLocal:name :ip :sizeof(ip) :port :sizeof(port)];
NSLog(@"L4 ServerToLocal return %d", ret);
if (ret != 0) {
return;
}
NSString* url = [NSString stringWithFormat:@"http://%s:%s/index.html",
ip, port];
// 訪問 url ...
5.3.3 Windows 接入
添加 SDK 至 Windows 工程
Kiwi 提供的 SDK 為動態庫，包含 Kiwi.dll、Kiwi.h、Kiwi.lib 三部分。
l 將 Kiwi.h 放入工程的頭文件目錄中
l 打開工程->屬性->鏈接器->輸入->附加依賴項，添加 Kiwi.lib，注意 Debug 和 Release 配置都需要設置
l 編譯完成後，將 Kiwi.dll 與工程生成的 exe 放到同一目錄運行
調用程式示例
#include
#include "Kiwi.h"
int main() {
char appkey[] = "Your appkey";
char target[] = "Your target";
char ip[64] = {0};
char port[16] = {0};
int ret = KiwiInit(appkey);
if (ret != 0) {
printf("KiwiInit failed %d\n", ret);
return ret;
}
ret = KiwiServerToLocal(target, ip, sizeof(ip), port, sizeof(port));
if (ret != 0) {
printf("KiwiServerToLocal failed %d\n", ret);
return ret;
}
printf("KiwiServerToLocal success %s %s\n", ip, port);
getchar();
return 0;
}
5.3.4 附錄
kiwi 接口錯誤碼
enum KiwiStatus
{KiwiOK = 0,
KiwiParam = -1,
kiwiAppkey = -2,
KiwiApiRequestFailed = -3,
KiwiNetwork = -4,
KiwiNoSuchRsName = -5,
KiwiConnect = -6,
KiwiNetworkRead = -7,
KiwiNetworkWrite = -8,
KiwiJson = -9,
KiwiJsonNoRoot = -10,
KiwiJsonNoMember = -11,
KiwiJavaRuntime = -12,
KiwiCherryRpcFailed = -13,
KiwiNoRss = -14,
KiwiNoApp = -15,
KiwiUnknow = -999
};
六、最佳實踐
6.1 真實 IP 獲取
四層 tcp 協議真實 IP 獲取（無需修改程式）
l 背景
TCP 代理通常是無法獲取到客戶端的真實 IP 的，但是雲廠商提供了 TOA 方案，這是因為他們的轉
發節點和他們自己的雲服務器之間做了內核級別的兼容，而這個是我們外部廠商無法做到的。所以
海爾盾參考 Cloudflare Spectrum 產品的真實 IP 方案，並對其方案做了兼容，可以直接復用其相
關組件來實現無需修改服務端程式的真實 IP 獲取。
相關文章：mmproxy - Creative Linux routing to preserve client IP addresses in L7 proxies
程式倉庫：go-mmproxy
l 方案概要
適用前提：
僅 linux服務器，內核版本大於 2.6.28
部署前後配置差別：
前：海爾盾 ----- 服務 IP 和端口
後：海爾盾 ----- 海爾盾提供的轉發程序的 IP 和端口（運行在同一台服務器）------服務 IP 和端口l 部署過程
1. 下載，並安裝 go-mmproxy
yum install -y golang
go install github.com/path-network/go-mmproxy@latest
cd go/bin/
cp go-mmproxy / usr/bin/
2. 將 go-mmproxy，配置成為系統服務並啟動
系統配置文件模版：go-mmproxy.service.example ，請根據實際情況進行修改。以原服務端口是
本機 80，通過 mmproxy 程序的 7080 做轉發為例，那麼第 12 行推薦配置如
下 ExecStart=/usr/bin/go-mmproxy -4 127.0.0.1:80 -l 0.0.0.0:7080
完整的服務配置如下：
[Unit]
Description=go-mmproxy
After=network.target
[Service]
Type=simple
LimitNOFILE=65535
ExecStartPost=/sbin/ip rule add from 127.0.0.1/8 iif lo table 123
ExecStartPost=/sbin/ip route add local 0.0.0.0/0 dev lo table 123
ExecStartPost=/sbin/ip -6 rule add from ::1/128 iif lo table 123
ExecStartPost=/sbin/ip -6 route add local ::/0 dev lo table 123
ExecStart=/usr/bin/go-mmproxy -4 127.0.0.1:80 -l 0.0.0.0:7080 # 第 12行
ExecStopPost=/sbin/ip rule del from 127.0.0.1/8 iif lo table 123
ExecStopPost=/sbin/ip route del local 0.0.0.0/0 dev lo table 123
ExecStopPost=/sbin/ip -6 rule del from ::1/128 iif lo table 123
ExecStopPost=/sbin/ip -6 route del local ::/0 dev lo table 123
Restart=on-failure
RestartSec=10s
[Install]
WantedBy=multi-user.target將上述服務配置保存到 /etc/systemd/system/go-mmproxy.service
3. 啟動服務
重新加載 systemd 配置
sudo systemctl daemon-reload;
執行以下命令以啟用服務並設置其在開機時自動啟動
sudo systemctl enable go-mmproxy.service
啟動服務
service go-mmproxy.service start
4. 登錄海爾盾控制台
修改海爾盾對應的防護目標的主線路地址為該服務器的 7080 端口，並將該防護目標的 TOA 設置
為 1
等待配置生效，並驗證是否獲取到真實 IP
備註
以上只是單個端口的部署過程，如果有多個端口需要轉化，則分別運行如下命令
nohup /usr/bin/go-mmproxy -4 127.0.0.1:82 -l 0.0.0.0:7081 &
nohup /usr/bin/go-mmproxy -4 127.0.0.1:82 -l 0.0.0.0:7082 &
確保機器重寫啟動後，相關服務和命令也會自動運行
七層 http 協議真實 IP 獲取
前置條件：防護目標類型使用 HTTP-GO
HTTP 可通過 X-Forward-For 或者 X-Dun-Real-Ip 獲取，無需安裝特殊模塊，參考這裡6.2 跨境加速最優方案
跨境網絡的不穩定性經常構成一項重大挑戰，即便您已經在源站部署了 CN2 線路（阿里雲精品
BGP 跨境線路），仍可能會遭遇各種網絡異常，導致應用程序啟動緩慢或無法正常運行。我們經過
大量實踐得出符合三種不同場景的可靠網絡架構，分別如下：
6.2.1 海爾盾普通 BGP 回源
此架構適合源站網絡質量好或對延時不敏感的業務
6.2.2 海爾盾 cn2 跨境回源加速
CN2 精品線路是一種優化海外回中國大陸流量的公網線路，可以提高大陸用戶國際業務訪問質量。相比普通 BGP 線路，CN2 精品線路在為中國內地終端客戶提供服務時，通過運營商精品公網直連
中國內地，實現中國大陸用戶低時延訪問部署在中國香港地域的 Web 服務
不過此架構也包括如下缺點：
1. 回源鏈路採用公網傳輸，並且是標準協議（如 HTTP/TCP 等），極易被識別，從而導致污染和
攔截。 （普通 BGP 架構同樣存在）
2. 回源鏈路採用 CN2 精品線路，總帶寬能力有限，無法有效應對大規模 DDoS 攻擊。因此，線
路一旦遭受 DDoS 攻擊，您的業務也將受到不小的衝擊。
如何確定存在這樣的問題，需要聯繫盾售後協助分析日誌並確認：
1. 確定客戶端調用盾接口正常
2. 客戶端訪問到盾節點正常，並且 TCP 連接回源正常
3. 但是業務使用不正常（如果開啟了緩存加速，可以嘗試看下 nginx 日誌，是否有大量回源異
常）
4. 盾取消境內節點調度，將流量全部調度到 CN2 香港節點後，業務恢復正常
面對這樣的問題，切換 CN2 節點不是一個好辦法，因為客戶端直接到 CN2 依然會存在類似問題，
我們該如何進行優化並徹底解決呢？
6.2.3 海爾盾 GA 全球加速
境內用戶依然到境內節點，境內節點使用專線跨境到海外源站！
我們建議引入 GA 全球加速產品，這樣可以通過內網傳輸全部流量，徹底解決公網不穩定的問題。值得注意的是：雖然全球加速產品的境內節點需要備案，但盾節點可以通過偽造 Host 回源到 GA，
從而繞過 GA 的備案攔截系統。這就意味著，即使在無備案域名的情況下，您也可以使用 GA 的境
內節點！
部署步驟
海爾盾已經集成了全球加速產品，您可以直接聯繫海爾盾團隊開通！
成功案例
l 某大型直播平台
業務規模：日活躍 1000 萬，峰值在線設備 60 萬！
跨境帶寬：全球加速 2Gbps
部署架構：
海爾盾 ----- 全球加速 ----- Cloudflare（Spectrum 四層轉發產品） ----- AWS 源站（新加坡）
方案特點：穩定跨境加速訪問、源站多隱藏一層，通過 Cloudflare 的優質海外網絡，中轉到 AWS
源站
l 某大型遊戲平台
業務規模：日活躍 10 萬，峰值在線設備 2 萬！
跨境帶寬：全球加速 20Mbps
部署架構：
海爾盾 ----- 全球加速 ----- 阿里雲代理（香港） ----- 未知源站位置
方案特點：穩定跨境加速訪問、跨境阿里雲內部網絡解決，同時隱藏源部署位置信息
七、常見問題 FAQ
7.1 APP 接口域名被污染，盾能否解決？
答：可以解決，盾裡面沒有域名，所以不怕被污染；而且 http 流量是加密傳輸的，只要能接 SDK
就行
7.2 不是原生的安卓，使用-reactive-編寫，能否集成？
答：可以集成，參考“**React Native 引入第三方 Android SDK”參考7.3 調用轉化接口是初始化調用一次就可以了嗎？調用的時候放在什麼位置？
答：初始化成功一次就可以用，不需要重複初始化；調用位置沒有要求，建議盡量早一些（比如開
屏廣告那裡）
7.4 項目的圖片、視頻、聊天等不同服務，一個 appkey 是否可以解決？
答：可以解決，配置不同防護目標即可。
7.5 APP 和網頁（鏈接）都能有防護效果嗎？
答：APP 有防護效果；部分網頁（鏈接）也有防護效果，比如 APP 內的 H5 業務（如充值）；需要
跳轉外部瀏覽器的網頁（鏈接）無防護效果。
7.6 能支持哪些協議進行防護？
答：HTTP 和 TCP。
7.7 代理時 ua 是否會變化？
答：不會變。
7.8 windows 接入 demo？
答：參考《kiwidemo.zip》
7.9 阿里雲-android-切海爾盾
public class AndroidBridge {
public static final int CTYPE = 1;
public static String init(){
- String token = "mst"; // 遊戲內的玩家唯一 ID，如果獲取不 到，可以傳
入一個默認值，定位惡意攻擊者使用
- String groupname = "n.xxx.com"; //遊戲盾防禦分組配置頁面獲取，一個遊
戲一個
//初始化
String appkey = "aaaaappkey"; //控制台獲取
- int ret = YunCeng.initEx(appkey, token); //這個接口只需要調用一
次，重複調用無效
+ int ret = Kiwi.Init(appkey);
if (ret != 0) {
return "初始化失敗，請聯繫管理員";
} else {
//基礎參數，通過 XX遊戲的入口、接入 XX服務器的 XX端口String dip = "mst"; //需要在遊戲盾無限抗防護目標中進行配置，對應的真實
服務器為 121.35.123.21
String dport = "80"; //根據實際需要進行傳入服務器的真實業務端口
+ String name = dip + "_" + dport;
//返回參數
StringBuffer target_ip = new StringBuffer();
StringBuffer target_port = new StringBuffer();
//核心轉化接口調用，此函數為遊戲盾的核心函數
- int ret1 = YunCeng.getProxyTcpByDomain(token, groupname, dip,
dport, target_ip, target_port);
+ int ret1 = Kiwi.ServerToLocal(name, target_ip, target_port);
if (ret1 == 0) {
String fin_g_dip = target_ip.toString(); //遊戲盾轉化後的 IP
String fin_g_dport = target_port.toString(); //遊戲盾轉化後
的 Port
String reqest_url = "http://" + fin_g_dip + ":" +
fin_g_dport;
return reqest_url;
} else {
return "核心接口出錯，請聯繫管理員";
}
}
}
}
7.10 阿里雲-ios-切海爾盾
+ #import
-(id)init{
self = [super init];
const char * appkey ="xxxxx";
- const char * token = "xy";//userIOS
- int ret = YunCeng_InitEx(appkey, token);
+ int ret = [Kiwi Init:appkey];
if(ret==0){
const char * ddomain = "dx";
const char * dport = "80";+ NSString *stringDdomain = [NSString
stringWithUTF8String:ddomain];
+ NSString *stringDport = [NSString stringWithUTF8String:dport];
+ NSString *stringName = [NSString stringWithFormat:@"%@_%@",
stringDdomain, stringDport];
+ const char *name = [stringName UTF8String];
- const char groupname[] = "Qn.ftnormal01aj.com"; //控制台獲取，一個遊
戲一個
char ip[128] = {0};
char port[32] = {0};
//核心調用接口
- int ret1 = [YunCeng getProxyTcpByDomain: token: groupname:
ddomain: dport: ip: 128 : port: 32];
+ int ret1 = [Kiwi
ServerToLocal:name :ip :sizeof(ip) :port :sizeof(port)];
if(ret1==0){
printf("get next ip success. %s, port:%s \n", ip, port);
_name = [[NSString alloc] initWithCString:(const char*)ip
encoding:NSASCIIStringEncoding];
_age = [[NSString alloc] initWithCString:(const char*)port
encoding:NSASCIIStringEncoding];
}
}
return self;
}
7.11 iOS 打包報錯“Found an unexpected Mach-O header code: 0x72613c21”
首先確認 Embed 設置為 Do Not Embed，然後在 Build Phases 裡，將 Embed Frameworks 中
的 framework移除，然後將其添加到 Link Binary With Libraies 中，已經有的話就不用重複添加
了（原因是靜態的 framework 添加到了 Embed Frameworks 裡面了）参考
7.12 如何判斷 SDK 對接已經成功？
打開 App 後，登錄控制台進入應用詳情-日誌查詢-【客戶端】SDK 請求日誌，能查詢到客戶端對應
IP、類型為“初始化”和“心跳”且“返回碼”是“成功”的日誌，說明 SDK 對接已經成功。
7.13 如何判斷防護目標配置正確？
打開 App 後進入防護目標對應的服務，登錄控制台進入應用詳情-日誌查詢-【四層】轉發日誌，能
查詢到客戶端對應 IP、對應防護目標且“請求結果”是“連接成功”的日誌，說明防護目標配置正確且已經生效。
7.14 客戶端出現卡頓或網絡連接超時，如何排查？
1. 首先大退（終止應用）再打開 App，可反覆嘗試幾次；
2. 確認客戶端是否開啟 VPN 或代理？如果有，請關閉後重啟 App（盾對某些VPN 或代理不兼
容）；
3. 如果問題未解決，檢查客戶端網絡是否異常？ 嘗試切換網絡（如 4G --> WIFI 或 WIFI -->
4G）；
4. 如果問題未解決，登錄控制台進入應用詳情-日誌查詢-【客戶端】SDK 請求日誌，確認是否能
查詢到客戶端對應 IP、類型為“初始化”和“心跳”且“返回碼”是“成功”的日誌，如果
能，則說明客戶端已經成功連接盾節點，然後再進行 【步驟 5】；如果不能，說明客戶端未能
成功連接盾節點，可嘗試 【步驟 2】和 【步驟 3】，如果依舊未解決則聯繫海爾盾客服檢查盾
節點是否正常，有必要時更換盾節點；
5. 登錄控制台進入 應用詳情-日誌查詢-【四層】轉發日誌，能查詢到客戶端對應 IP、對應防護目
標且“請求結果”是“連接成功”的日誌，則說明盾節點已正常轉發四層請求；如果對應防護
目標是 HTTP-GO 類型，則嘗試 【步驟 6】
6. 登錄控制台進入應用詳情-日誌查詢-【七層】緩存加速日誌，查詢客戶端對應 IP、對應防護目
標（必須開啟 緩存加速 功能）的日誌，檢查 狀態碼 是否異常？響應時間 是否異常？如果響
應時間很短，則說明盾節點到源站網絡質量很好；如果響應時間很長（大於 5s），則說明盾節
點到源站網絡質量較差，此時可以聯繫海爾盾客服確認是否需要開啟 CN2 回源加速或 GA 加速
進行測試；如果狀態碼是 5xx，則說明源站存在異常，請檢查源站服務器負載（網絡、磁盤、
內存、CPU 等）、源站配置（包括網站配置、域名等）是否正常；
7. 如果問題依舊未解決，請聯繫海爾盾客服，並提供 客戶端 IP、防護目標 ID、現象（截圖或視
頻）等信息。
八、聯繫我們
海爾盾的銷售和服務均由代理商提供，請聯繫您的代理商進行相關問題的處理，代理商將協助您解
決使用中的所有問題。
九、請聯繫
support@highercloud.com.tw
2023 ©HigherCloud">
To view the full page, please visit: HigherShield Product Userguide
