日志服务网络探测各插件所需权限说明

本文档详细说明了网络探测器在 Android、iOS、Windows、Unity 等平台上所需的权限声明，为开发者提供全面的权限配置参考。
Android 权限声明
网络探测插件自身所需权限
权限
说明
android.permission.ACCESS_NETWORK_STATE
获取网络状态信息（如当前网络类型、是否连接等）
android.permission.READ_PHONE_STATE
读取手机状态信息（如设备标识、运营商信息等）
android.permission.INTERNET
访问互联网（执行网络探测请求）
android.permission.CHANGE_NETWORK_STATE
更改网络连接状态
android.permission.WRITE_SETTINGS
写入系统设置
App 层额外声明的权限
权限
说明
android.permission.ACCESS_WIFI_STATE
获取 Wi-Fi 网络状态信息
CLS Producer SDK 所需权限
权限
说明
android.permission.ACCESS_NETWORK_STATE
获取网络状态信息（与探测插件重复）
Android 权限汇总表
完整使用网络探测器功能，总共需要6个权限。
序号
权限
权限类型
说明
特殊要求
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+ 需引导用户到系统设置页面手动授权
AndroidManifest.xml 声明示例
<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>
注意：
READ_PHONE_STATE 和 WRITE_SETTINGS 属于危险权限，在 Android 6.0（API 23）及以上版本需要在运行时动态申请用户授权。
iOS 权限声明
iOS 默认允许应用联网，不需要像 Android 一样显式声明 INTERNET 权限。以下按探测场景分为两套配置。
公网探测版（仅探测互联网域名/IP）
权限/能力清单
键
来源
必需性
说明
NSAppTransportSecurity
Info.plist
视情况
仅当有 HTTP 明文或非标准 TLS 目标时配置；纯 HTTPS 可不配置
Info.plist 示例
仅在需要 ATS 例外时添加。
<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 例外
Info.plist 示例
<key>NSLocalNetworkUsageDescription</key>
<string>用于发现和探测局域网设备的网络连通性与时延。</string>
﻿
<!-- 仅在 Bonjour 场景需要 -->
<key>NSBonjourServices</key>
<array>
    <string>_http._tcp</string>
    <string>_https._tcp</string>
    <!-- 按实际协议补充 -->
</array>
可选：读取 Wi-Fi 信息场景（SSID / BSSID）
如果探测逻辑依赖 Wi-Fi 名称等信息，需补充定位权限。
<key>NSLocationWhenInUseUsageDescription</key>
<string>用于获取当前网络环境信息以辅助网络探测。</string>
注意：
该场景涉及定位授权与系统能力约束，需按实际实现确认。
iOS 权限汇总表
模块
来源文件
键/能力
是否必须
触发弹窗
用途说明
网络探测插件
Info.plist
NSLocalNetworkUsageDescription
是（局域网）
是
局域网探测
网络探测插件
Info.plist
NSBonjourServices
否（Bonjour）
否
局域网服务发现
网络探测插件
Info.plist
NSAppTransportSecurity
视情况
否
HTTP/弱 TLS 兼容
App 层
Info.plist
NSLocationWhenInUseUsageDescription
否
是
Wi-Fi 信息读取辅助
CLS SDK
无额外声明
默认联网能力
是
否
日志上报/连通性请求
Windows 权限声明
Windows 平台不使用清单式权限声明，权限主要取决于运行时用户权限级别和系统配置。
各模块权限需求
探测模块
权限要求
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，无法在普通权限下运行
Unity 权限声明
Unity 网络探测器所需的权限与其实际运行的目标平台相关，Unity 本身不引入额外的独立权限体系。具体说明如下：
Android 平台：Unity 项目构建为 Android 应用时，权限声明与原生 Android 一致，请参考 Android 权限声明。
iOS 平台：Unity 项目构建为 iOS 应用时，权限声明与原生 iOS 一致，请参考 iOS 权限声明。
Windows 平台：Unity 项目构建为 Windows 桌面应用时，权限要求与原生 Windows 一致，请参考 Windows 权限声明。
总结：Unity 网络探测器的权限配置无需单独声明，直接参考目标运行环境对应的平台权限配置即可。
附录：跨平台权限对比总览
探测功能
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
默认联网能力
✅ 普通用户

权限	说明
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 网络状态信息

序号	权限	权限类型	说明	特殊要求
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+ 需引导用户到系统设置页面手动授权

键	来源	必需性	说明
NSAppTransportSecurity	Info.plist	视情况	仅当有 HTTP 明文或非标准 TLS 目标时配置；纯 HTTPS 可不配置

模块	来源文件	键/能力	是否必须	触发弹窗	用途说明
网络探测插件	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	默认联网能力	✅ 普通用户

网络探测各插件所需权限说明

本页目录：

Android 权限声明

网络探测插件自身所需权限

App 层额外声明的权限

CLS Producer SDK 所需权限

Android 权限汇总表

iOS 权限声明

公网探测版（仅探测互联网域名/IP）

权限/能力清单

Info.plist 示例

局域网探测版（扫描/访问同网段设备）

权限/能力清单

Info.plist 示例

可选：读取 Wi-Fi 信息场景（SSID / BSSID）

iOS 权限汇总表

Windows 权限声明

各模块权限需求

其他注意事项

无管理员权限的替代方案

Unity 权限声明

附录：跨平台权限对比总览