安全加速 SDK 接入常见问题：Real IP、Proxy Protocol 与自定义 Header 怎么处理？

重点摘要

SDK 接入后，客户端不再直连源站，而是先向调度平台取得代理 IP 与端口，再由边缘节点转发至源站。代理地址会动态变动，重连后应重新取得。
源站预设看到的是代理节点 IP。需要真实客户 IP 时，有 Proxy Protocol、TOA 与 API 三种模式，源站支援 Proxy Protocol 时优先选它。
SDK 不新增、不修改、不删除 Header，只原样透传。X-App-Version 之类的自定义栏位由客户端自行加入。
Host Header、源站防火墙策略、心跳与健康检查、HTTPS 证书策略，都应在 POC 阶段由双方共同确认。
验收时先确认对外连线显示代理地址而非源站 IP，再以小比例灰度发布 2 至 3 天后逐步全量上线。

安全加速 SDK 导入过程中，最容易卡住的通常不是初始化函数，而是代理架构带来的细节：源站看到的是节点 IP 还是玩家 IP？能不能用 Real IP Header？可不可以让 SDK 自动加入自定义 Header？断线重建时是否仍沿用原本的代理地址？

如果这些问题没有在 POC 阶段厘清，即使 SDK 已经成功编译进 App，也可能在登入验证、风控、日志分析、IP 封锁或负载均衡环节出现落差。以下依照实际接入流程逐一说明。

源站看到的是节点 IP 还是真实玩家 IP？怎么把真实 IP 传过去？
什么是 Proxy Protocol、TOA、API？我该选哪一种？
SDK 能不能帮我自动加上自定义 Header（如 X-App-Version）？
为什么断线重连后要重新取得代理地址？不能复用吗？

SDK 如何建立安全代理通道？

完成整合后，客户端不再直接连线源站，而是先透过 SDK 取得代理 IP 与端口，再由边缘节点将连线转发至源站。基本流程如下：

客户端使用 AccessKey 与设备识别资讯初始化 SDK。
SDK 向调度平台请求可用的代理 IP 与端口。
客户端使用取得的代理地址建立连线。
边缘节点将原始业务请求转发至控制台设定的源站。

这套模式可以隐藏源站 IP，并依据网络品质、节点健康状态与风险讯号调整路径。也因为代理地址可能动态变动，每次新请求、断线重连或设备锁屏恢复后，都应重新呼叫 getServerIPAndPort，而不是长期保存旧的 IP 与端口。

SDK 代理连线架构：客户端 App 先向调度平台取得代理 IP 与端口（控制面），再直接连线代理地址，由边缘节点转发至企业源站；真实 IP 可透过 Proxy Protocol（建议）、TOA 或 API 传递；全程不依赖 Local DNS 解析，即使 DNS 被劫持仍可取得正确代理地址

接入前，控制台需要设定哪些项目？

客户可于后台自助设定转发规则。正式配置前，建议先盘点需要 SDK 保护的业务域名、端口、协定与源站地址，并将源站与其他未受保护业务隔离。

设定项目	说明
虚拟域名	用于内部识别转发规则，不需要公开 DNS 解析，也不需 ICP 备案，不会成为劫持目标
转发端口	由 SDK 用来区分不同业务，例如 80、443 或游戏服务端口
负载均衡	可选 Round-Robin（轮询），或用 IP Hash 让相同 IP 优先命中相同源站
源站配置	填写实际源站 IP 与服务端口；建议避免源站 IP 透过其他服务直接暴露

是否支援 Real IP Header？先厘清真正需求

SDK 透过代理节点转发连线后，源站预设看到的网络来源可能是代理节点，而不是终端用户的真实 IP。因此，若登入风控、地区判断、日志稽核或封锁策略需要使用真实客户 IP，就必须另外配置 Real IP 的传递方式。

目前支援三种取得真实客户 IP 的模式：

模式	适用情境	实作说明
Proxy Protocol	源站或负载均衡器（如 Nginx、ALB）支援	在连线层（L4）传递原始来源 IP 与端口，源站需解析 PROXY 协定标头。优先建议
TOA（TCP Option Address）	需要操作系统或负载均衡器核心模组支援	透过 TCP 选项栏位携带客户端 IP，源站需搭配对应的核心模组才能读取
API 介面	无法直接支援前两种方式	业务系统透过 API 向平台查询对应连线的真实客户 IP，适合 Legacy 架构或特殊协定

因此，「支援取得真实 IP」不等于「SDK 会任意新增一个 Real IP Header」。实际采用哪一种方式，应依源站服务器、负载均衡器、协定类型与现有日志／风控系统决定。若源站支援 Proxy Protocol，建议优先选择 Proxy Protocol，架构通常较直接。

补充：Nginx 设定范例（Proxy Protocol）

若源站使用 Nginx 且开启 Proxy Protocol，需在 listen 指令加上 proxy_protocol，并以 real_ip_header proxy_protocol 从 PROXY 协定标头取得真实 IP：

http {
    # 日志中记录真实客户端 IP
    log_format main '$proxy_protocol_addr - $remote_user [$time_local] "$request"';

    server {
        listen 80 proxy_protocol;
        listen 443 ssl proxy_protocol;

        # 信任的代理来源（正式上线建议限定为 SDK 边缘节点的 IP 范围）
        set_real_ip_from 0.0.0.0/0;
        # 从 PROXY 协定标头取得真实 IP，覆写 $remote_addr
        real_ip_header proxy_protocol;

        access_log /var/log/nginx/access.log main;
    }
}

是否支援自助新增自定义 Header？

目前 SDK 后台不提供新增自定义 Header 的功能。SDK 的处理原则是：将客户端原始请求中的 Header 原样透传至源站，不主动新增、修改或删除 Header。

设计原则上，SDK 专注于安全代理与流量调度，不介入应用层业务逻辑。这可以避免 SDK 与业务 Header 命名冲突，也降低后续维护的耦合度。

如果业务需要 X-App-Version、X-Device-ID、X-Channel 或其他自定义栏位，应由客户端在送出原始请求时自行加入。SDK 会将既有 Header 随请求转发，但不负责产生或改写其内容。

避免混淆：Real IP 传递是代理架构中的来源识别问题；自定义 Header 则是应用程序自行定义的业务资料。两者的责任层与设定方式不同。

接入时还有哪些容易忽略的事项？

源站配置注意事项

HTTP 请求必须保留正确的 Host Header，否则源站虚拟主机可能无法判断目标服务。
SDK 节点会动态调度，不应只用固定节点 IP 白名单限制源站；源站防火墙策略需在 POC 阶段共同设计。
心跳与业务健康检查由应用层实作，SDK 不代替业务判断源站服务状态。

Android 注意事项

需确认 ARM64-v8a、armeabi-v7a、x86 等架构与其他第三方 SDK 相容。
需加入指定的 ProGuard 规则，避免混淆导致 SDK 异常。

iOS 注意事项

以 Framework 方式接入需引入 libz。
锁屏恢复或网络切换后应重新呼叫 getServerIPAndPort 取得代理地址。

HTTPS 与证书

HTTPS 与证书验证策略应在 POC 阶段由双方技术团队确认，确保符合 App 现有安全设计，避免发生 SSL 握手失败。

建议如何进行测试与验收？

使用封包分析工具确认 App 对外连线显示代理地址，而不是直接暴露源站 IP。
在业务系统与日志中确认取得的客户 IP 为真实用户地址，而非代理节点 IP。
测试 Wi-Fi、4G/5G、网络切换、断网重建、锁屏与背景恢复等情境。
检查登入、长连线、API 回应、封包完整性及负载均衡结果。
先进行小比例灰度发布 2 至 3 天，收集异常日志与用户反馈，再逐步全量上线。

结语：先把代理责任厘清楚，接入才会顺利

安全加速 SDK 的核心是建立受保护、可调度的代理通道，而不是取代所有应用层逻辑。Real IP、Header、心跳、证书与源站安全策略，都需要由 SDK、客户端与源站共同完成。

SDK 的核心价值不仅是建立安全代理通道，更在于从终端绕过 DNS 解析，从根源上避免 DNS 劫持对业务连线的影响；调度策略可远端即时下发，无需等待 App 发版即可调整路由。但这些能力能否顺利发挥，取决于接入阶段的架构设计是否完整，而 Real IP、Header 与源站安全策略正是其中最容易忽略的细节。

企业若能在 POC 前先盘点协定、源站架构、Real IP 用途与自定义 Header 需求，就能大幅降低整合后才发现风控、日志或验证流程不相容的机率。

常见问题

源站支援 Proxy Protocol，应该选哪种 Real IP 模式？

建议优先使用 Proxy Protocol。它可在连线层传递原始来源资讯，但仍需确认源站或负载均衡器已正确启用与解析。

可以指定另一个 Header 传递真实 IP 吗？

SDK 可以协助取得真实客户 IP，但标准支援方式为 Proxy Protocol、TOA 或 API。SDK 不会自行新增任意 Header；若应用需要自定义 Header，应由客户端原始请求加入。

SDK 会删除或修改原本的 Header 吗？

不会。SDK 仅将客户端原始请求中的 Header 透传至源站，不新增、不修改，也不删除。

为什么每次连线后要重新呼叫 getServerIPAndPort？

代理地址会依节点健康、网络品质与调度策略动态调整。重新取得地址可以避免持续使用已失效或不再合适的节点。

SDK 是否会自动处理心跳与源站健康判断？

不会。心跳机制与业务层健康检查需由应用程序自行实作；SDK 主要负责安全代理、调度与连线转发。

导入 SDK 后，HTTPS 证书验证会受到影响吗？

SDK 本身不会替换或终止 HTTPS 证书，证书验证逻辑仍由客户端原始程序码处理。但若源站仅允许特定来源 IP 存取，需将 SDK 边缘节点的 IP 范围加入白名单（平台会提供清单）。具体证书策略应在 POC 阶段由双方技术团队共同确认。

如果您正在规划 Android、iOS、PC 或 Flutter 应用接入安全加速 SDK，欢迎联系 ByteShield 团队，我们可协助您检查转发规则、Real IP 方案、源站架构与灰度验收流程。