权限 | 说明 |
android.permission.ACCESS_NETWORK_STATE | 获取网络状态信息（如当前网络类型、是否连接等） |
android.permission.READ_PHONE_STATE | 读取手机状态信息（如设备标识、运营商信息等） |
android.permission.INTERNET | 访问互联网（执行网络探测请求） |
android.permission.CHANGE_NETWORK_STATE | 更改网络连接状态 |
android.permission.WRITE_SETTINGS | 写入系统设置 |
权限 | 说明 |
android.permission.ACCESS_WIFI_STATE | 获取 Wi-Fi 网络状态信息 |
权限 | 说明 |
android.permission.ACCESS_NETWORK_STATE | 获取网络状态信息（与探测插件重复） |
序号 | 权限 | 权限类型 | 说明 | 特殊要求 |
1 | INTERNET | 普通权限 | 核心权限，用于执行网络探测（Ping、Traceroute 等）和上报数据 | 无 |
2 | ACCESS_NETWORK_STATE | 普通权限 | 获取当前网络连接状态和类型 | 无 |
3 | ACCESS_WIFI_STATE | 普通权限 | 获取 WiFi 连接信息 | 无 |
4 | READ_PHONE_STATE | 危险权限 | 读取设备和运营商信息 | Android 6.0+ 需要运行时动态申请 |
5 | CHANGE_NETWORK_STATE | 普通权限 | 更改网络连接状态 | 无 |
6 | WRITE_SETTINGS | 危险权限 | 写入系统设置 | Android 6.0+ 需引导用户到系统设置页面手动授权 |
<manifest xmlns:android="http://schemas.android.com/apk/res/android"><!-- 核心网络权限 --><uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /><uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /><!-- 设备信息读取（危险权限，需运行时申请） --><uses-permission android:name="android.permission.READ_PHONE_STATE" /><!-- 网络状态变更 --><uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /><!-- 系统设置写入（危险权限，需引导用户手动授权） --><uses-permission android:name="android.permission.WRITE_SETTINGS" /></manifest>
键 | 来源 | 必需性 | 说明 |
NSAppTransportSecurity | Info.plist | 视情况 | 仅当有 HTTP 明文或非标准 TLS 目标时配置；纯 HTTPS 可不配置 |
<key>NSAppTransportSecurity</key><dict><!-- 全局放开不推荐，建议按域名细粒度配置 --><key>NSAllowsArbitraryLoads</key><false/><key>NSExceptionDomains</key><dict><key>example.com</key><dict><key>NSIncludesSubdomains</key><true/><key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key><true/><key>NSTemporaryExceptionMinimumTLSVersion</key><string>TLSv1.0</string></dict></dict></dict>
键 | 来源 | 必需性 | 说明 |
NSLocalNetworkUsageDescription | Info.plist | 必需 | iOS 14+ 本地网络访问用途说明，触发系统弹窗 |
NSBonjourServices | Info.plist | 仅 Bonjour 发现时必需 | 声明要使用的 Bonjour 服务类型 |
NSAppTransportSecurity | Info.plist | 视情况 | 若走 HTTP 或弱 TLS，仍需 ATS 例外 |
<key>NSLocalNetworkUsageDescription</key><string>用于发现和探测局域网设备的网络连通性与时延。</string><!-- 仅在 Bonjour 场景需要 --><key>NSBonjourServices</key><array><string>_http._tcp</string><string>_https._tcp</string><!-- 按实际协议补充 --></array>
<key>NSLocationWhenInUseUsageDescription</key><string>用于获取当前网络环境信息以辅助网络探测。</string>
模块 | 来源文件 | 键/能力 | 是否必须 | 触发弹窗 | 用途说明 |
网络探测插件 | Info.plist | NSLocalNetworkUsageDescription | 是（局域网） | 是 | 局域网探测 |
网络探测插件 | Info.plist | NSBonjourServices | 否（Bonjour） | 否 | 局域网服务发现 |
网络探测插件 | Info.plist | NSAppTransportSecurity | 视情况 | 否 | HTTP/弱 TLS 兼容 |
App 层 | Info.plist | NSLocationWhenInUseUsageDescription | 否 | 是 | Wi-Fi 信息读取辅助 |
CLS SDK | 无额外声明 | 默认联网能力 | 是 | 否 | 日志上报/连通性请求 |
探测模块 | 权限要求 | Socket 类型 | 说明 |
Ping（ICMP） | ⚠️ 需要管理员权限 | SOCK_RAW | 创建 RAW Socket 需要管理员权限 |
TCPPing | ✅ 普通用户即可 | SOCK_STREAM | 使用标准 TCP 连接 |
HTTP 检测 | ✅ 普通用户即可 | 标准 HTTP 连接 | 无特殊权限要求 |
DNS 检测 | ✅ 普通用户即可 | UDP 标准连接 | 无特殊权限要求 |
MTR（ICMP） | ⚠️ 需要管理员权限 | SOCK_RAW | 创建 RAW Socket 需要管理员权限 |
MTR（TCP/UDP） | ⚠️ 需要管理员权限 | SOCK_RAW + SIO_RCVALL | 需要 RAW IP Socket 和 SIO_RCVALL 权限 |
功能 | 权限要求 | 说明 |
创建 RAW Socket | 管理员权限 | socket(AF_INET, SOCK_RAW, IPPROTO_ICMP) |
创建 RAW IP Socket | 管理员权限 | socket(AF_INET, SOCK_RAW, IPPROTO_IP) |
启用 SIO_RCVALL | 管理员权限 | 用于接收所有 IP 包（包括 ICMP Time Exceeded） |
场景 | 错误码 | 说明 |
Ping 创建 RAW Socket 失败 | PERMISSION_DENIED = -4 | 返回权限拒绝错误码 |
MTR 启用 SIO_RCVALL 失败 | error=10013（WSAEACCES） | 日志显示：[mtr] FAILED: SIO_RCVALL failed, error=10013 |
注意事项 | 说明 |
防火墙设置 | 某些防火墙（尤其是第三方防火墙）可能会阻止 RAW Socket，即使有管理员权限也需要手动配置放行规则 |
SQLite 存储 | 需要确保数据库文件所在目录有写权限，注意 Windows 下的 UAC 权限问题 |
DLL 部署 | 需要确保 cls_network_detect.dll、cls_log_sdk.dll、sqlite3.dll 位于可搜索路径，且程序架构一致（建议统一 x64） |
替代方案 | 说明 |
使用 TCPPing 替代 Ping | TCPPing 使用普通的 SOCK_STREAM 连接，不需要管理员权限 |
使用 HTTP 检测 | 标准 HTTP 连接，普通用户即可执行 |
使用 DNS 检测 | UDP 标准连接，普通用户即可执行 |
放弃 MTR 路由追踪 | MTR 功能强依赖 RAW Socket，无法在普通权限下运行 |
探测功能 | Android | iOS | Windows |
Ping（ICMP） | INTERNET | 默认联网能力 | ⚠️ 管理员权限 |
TCPPing | INTERNET | 默认联网能力 | ✅ 普通用户 |
HTTP 检测 | INTERNET | ATS 配置（视情况） | ✅ 普通用户 |
DNS 检测 | INTERNET | 默认联网能力 | ✅ 普通用户 |
MTR 路由追踪 | INTERNET | 默认联网能力 | ⚠️ 管理员权限 |
局域网探测 | ACCESS_NETWORK_STATE | NSLocalNetworkUsageDescription | ✅ 普通用户（需防火墙放行） |
网络状态获取 | ACCESS_NETWORK_STATE / ACCESS_WIFI_STATE | 无需额外权限 | 无需额外权限 |
数据上报（CLS） | INTERNET / ACCESS_NETWORK_STATE | 默认联网能力 | ✅ 普通用户 |
文档反馈