Android以太网eth0静态IP配置实战：权限、框架与版本适配-北京尧图网络

1. Android 以太网 eth0 静态 IP 到底难在哪Android 以太网 eth0 静态 IP 配置这件事第一次做的人基本都会被卡住界面里翻不到入口、adb敲了一堆命令没反应、代码里setConfiguration直接抛SecurityException。它真正的难点在于 Android 把以太网当成一个“二等公民”来管——Wi-Fi 有完整的公共 API 和用户界面以太网从框架层开始就一直挂在SystemApi和hide后面普通应用连门都摸不到。这篇内容面向三类人做广告机、POS 终端、工控一体机、车机和电视盒子的嵌入式/应用开发者需要在出厂或现场批量把eth0的 IP 固定下来系统定制方向的同学想搞清楚EthernetManager、EthernetTracker、ConnectivityService之间怎么配合以及被“设了不生效”“重启就丢”“能 ping 通 IP 但打不开网页”折磨过的现场实施人员。我会把三条路径全部摊开讲系统签名应用直接调 SystemApi、root 环境下用命令行硬配、以及没有权限时怎么优雅地引导用户自己配。每条路径都给可复现的代码和命令重点讲清楚为什么这么做、不这么做会踩什么坑。安卓版本横跨 7 到 14差异不小我会在每个关键点标注版本边界你按自己手上的系统对号入座。2. 先摸清底层框架一条 IP 配置指令的完整链路2.1 从调用到网卡谁在真正改 IP很多人以为EthernetManager是个只管以太网的小服务其实它只是个薄壳。你调setConfiguration()之后请求先到EthernetServiceImpl它把配置交给EthernetConfigStore持久化再通过EthernetTracker通知底层最后由ConnectivityService拉起来一个EthernetNetworkAgent注册到网络栈里真正下发到内核的ip addr和ip route是netd干的。这条链路上任何一环断了表现都是“命令没报错但 IP 没变”。我见过最典型的案例EthernetTracker根本没接管这块网卡配置存进去了也永远不生效。因为 AOSP 的EthernetTracker只会管理在白名单里声明过的接口这个白名单叫config_ethernet_interfaces在frameworks/base/core/res/res/values/config.xml里老版本用的是config_ethernet_iface_regex正则默认匹配eth\d。所以你拿到一台双网口设备eth1怎么配都没反应先别怀疑代码去确认 overlay 里有没有把eth1加进去。这个点 AOSP 文档基本不提但它是现场排障的第一顺位。2.2 权限门槛为什么你的代码总是抛 SecurityException以太网配置需要的权限是android.permission.MANAGE_ETHERNET_NETWORKS这个权限从 Android 10API 29开始正式对外暴露保护级别是signature——意味着只有用平台签名签过的应用或者放在/system/priv-app下并被privapp-permissions白名单放行的应用才拿得到。我在项目里反复强调一句话反射能绕过 API 可见性绕不过权限检查。你能Class.forName(android.net.EthernetManager)拿到方法并成功invoke但调用进到服务端EthernetServiceImpl里的enforceConnectivityInternalPermission或者MANAGE_ETHERNET_NETWORKS检查一样会把你挡回来抛SecurityException: uid xxx does not have android.permission.MANAGE_ETHERNET_NETWORKS。Android 9 之后还有一层 non-SDK interface 限制android.net.IpConfiguration、IpConfiguration$IpAssignment这些 hide 类在灰名单或黑名单里反射时可能直接抛NoSuchMethodException或收到警告。调试阶段可以临时用adb shell settings put global hidden_api_policy 1放开但这是开发调试用的开关出厂设备上开着它本身就是个隐患别当方案用。2.3 版本差异对照别拿 Android 8 的代码去跑 Android 13以太网的 API 在这几年改动相当剧烈我把关键节点整理成表你按自己的 targetSdk 和实际系统版本对Android 版本API 形态关键变化5.0 - 8.1EthernetManager.setConfiguration(String, IpConfiguration)权限走内部CONNECTIVITY_INTERNAL普通应用完全无法触及9同上non-SDK 限制收紧反射开始受限hidden_api_policy生效10新增MANAGE_ETHERNET_NETWORKS权限模型定型EthernetManager进 SystemApi11EthernetManager迁入 Connectivity 模块模块化后dumpsys ethernet输出格式变化12StaticIpConfiguration.Builder公开构造静态配置不再只能反射13新增EthernetNetworkUpdateRequest与updateConfiguration一次调用可同时改 IP 和网络能力14接口状态查询能力增强多网口场景调试更方便这张表最实用的结论是如果你的设备跑 Android 12 及以上代码尽量往updateConfiguration上靠如果是 Android 10/11setConfiguration还是主力更老的系统只能走定制或者 root。写代码时用Build.VERSION.SDK_INT分支别偷懒只写一套。3. 三条落地路径怎么选界面、命令行、代码3.1 路径一系统设置里手动配最稳但最慢Android 原生从 7.0 开始在设置里有“以太网”入口部分厂商 ROM 会隐藏或删掉插上网线后能看到eth0点进去可以选 DHCP 或静态。这条路径的优点是完全走官方逻辑持久化、DNS、路由、代理全都自动处理好不会出现“IP 对了但 DNS 没设”的半吊子状态。缺点是效率。我做过一个 200 台广告机的项目逐台点设置平均每台 3 分钟还要防止实施人员把掩码填错。后来全部改成脚本批量下发。如果你只是几十台以内、一次性部署手动配反而是最省心的选择尤其在没有系统签名的情况下。现场有个小技巧adb shell am start -a android.settings.ETHERNET_SETTINGS可以直接跳到以太网设置页省得在一堆菜单里翻。这个 action 不是所有 ROM 都实现了包一层try-catch捕获ActivityNotFoundException跳不过去就退回android.settings.WIRELESS_SETTINGS。3.2 路径二adb / 串口命令行批量部署首选adb shell cmd ethernet是 Android 11 之后比较靠谱的入口它背后是EthernetShellCommand。不同版本支持的子命令差异挺大第一件事永远是先执行adb shell cmd ethernet把 help 打出来别背命令。常见的调用形态大致是这样# 先看帮助确认当前系统支持哪些子命令和参数顺序 adb shell cmd ethernet # 典型的静态 IP 设置形式参数顺序以 help 输出为准 adb shell cmd ethernet set-ip eth0 192.168.10.50/24 192.168.10.1 # 单独设置 DNS adb shell cmd ethernet set-dns eth0 192.168.10.1 114.114.114.114这里有个必须注意的细节cmd ethernet走的是 shell uidshell 在多数系统上被授予了MANAGE_ETHERNET_NETWORKS所以能成功但你换成普通应用调同样的逻辑就会被拒。这也是为什么很多人adb测试通过、写进 App 就崩——测试环境和运行环境的权限模型根本不是一回事。命令行还有个好处是能嵌进批处理脚本配合adb devices遍历序列号200 台机器半小时能刷完。我通常会把设备 MAC 和分配的 IP 做成 CSV脚本读一行配一台配完立刻用ping验证失败的重试一次再报错。3.3 路径三应用内代码配置灵活但门槛最高代码配置适合两类场景一是设备出厂首次开机自动下发预置应用系统签名二是运行过程中根据业务动态切换网络比如产线切换不同网段。它的价值在于可控、可日志化、可远程触发但前提是你得拿到系统签名。选型上我给个简单的判断逻辑单机部署少于 50 台、没有系统签名、需求只是固定一个 IP那就手动配或者adb批量配别折腾代码设备量大、需要远程运维、需要和业务联动切换网段那就老老实实做系统签名应用走EthernetManager。路径权限要求适用规模持久化主要风险系统设置手动无小批量自动人为填错、效率低adb 命令行shell 权限中大批量多数版本会存子命令随版本变化应用内代码系统签名或 root大批量、需远程需自行确认权限、反射、版本兼容4. 代码实操把静态 IP 真正写进 eth04.1 参数整理掩码换算和网关校验先做对在写代码之前先把三个参数算清楚这三个地方出错率最高。第一是前缀长度。用户给你的是255.255.255.0这种掩码Android 要的是/24。换算不难但顺序不能乱掩码必须是连续的 1 后跟连续的 0255.255.255.1这种非法掩码要提前拦下来否则底层会抛IllegalArgumentException。掩码前缀可用主机数255.255.255.0/24254255.255.255.128/25126255.255.255.192/2662255.255.255.252/302255.255.0.0/1665534第二是网关必须和 IP 在同一个子网内。部分版本在构造StaticIpConfiguration时会做校验网关跨网段直接抛异常即使不抛配出来的路由也是错的表现就是“设置成功但上不了网”。第三是 DNS 顺序。主 DNS 放第一个备用放第二个别只填一个还填成网关地址就以为万事大吉——很多现场环境网关并不做 DNS 转发这就是“能 ping 通 IP、打不开网页”的根源。4.2 Android 10/11IpConfiguration 的老写法这个版本段用的还是IpConfiguration它本身是 hide 类得靠反射。下面是 Kotlin 版本核心思路是构造StaticIpConfiguration内部类Builder在 Android 12 才有老版本只能用无参构造反射赋值或者用公开的LinkAddress/InetAddressimport android.net.EthernetManager import android.net.IpConfiguration import android.net.LinkAddress import android.net.ProxyInfo import android.net.StaticIpConfiguration import java.net.Inet4Address import java.net.InetAddress fun setStaticIpLegacy( ethManager: EthernetManager, iface: String, ip: String, // 192.168.10.50 prefixLen: Int, // 24 gateway: String, // 192.168.10.1 dns1: String, dns2: String? ) { // 1. 构造 LinkAddress前缀长度在这里生效 val linkAddress LinkAddress(InetAddress.getByName(ip), prefixLen) // 2. 构造 StaticIpConfiguration走反射因为构造器不可见 val sicCls Class.forName(android.net.StaticIpConfiguration) val sic sicCls.getDeclaredConstructor().apply { isAccessible true }.newInstance() val ipAddressField sicCls.getField(ipAddress) ipAddressField.set(sic, linkAddress) val gatewayField sicCls.getField(gateway) gatewayField.set(sic, InetAddress.getByName(gateway)) val dnsField sicCls.getField(dnsServers) Suppress(UNCHECKED_CAST) val dnsList dnsField.get(sic) as ArrayListInetAddress dnsList.add(InetAddress.getByName(dns1)) dns2?.let { dnsList.add(InetAddress.getByName(it)) } // 3. 拿枚举常量。IpAssignment / ProxySettings 也是 hide用 Enum.valueOf 绕 Suppress(UNCHECKED_CAST) val ipAssignCls Class.forName(android.net.IpConfiguration\$IpAssignment) as Classout Enum* val staticEnum java.lang.Enum.valueOf(ipAssignCls as ClassEnum*, STATIC) Suppress(UNCHECKED_CAST) val proxyCls Class.forName(android.net.IpConfiguration\$ProxySettings) as Classout Enum* val noneEnum java.lang.Enum.valueOf(proxyCls as ClassEnum*, NONE) // 4. 组装 IpConfiguration val ipConfigCls Class.forName(android.net.IpConfiguration) val ipConfig ipConfigCls .getConstructor( ipAssignCls, proxyCls, Class.forName(android.net.StaticIpConfiguration), Class.forName(android.net.ProxyInfo) ) .newInstance(staticEnum, noneEnum, sic, null) // 5. 下发 val setConfig EthernetManager::class.java.getMethod( setConfiguration, String::class.java, ipConfigCls ) setConfig.invoke(ethManager, iface, ipConfig) }这段代码里最容易翻车的是第 3 步的枚举。不同 ROM 可能对 hide 类做了裁剪Class.forName直接抛ClassNotFoundException。所以我一般会在应用启动时做一次“能力探测”试着加载android.net.EthernetManager拿到实例试调一个无害的 getter比如isAvailable()全部通过才认为这台设备支持代码配置否则自动切换到“引导用户手动配”的降级路径。这套探测逻辑上线后线上崩溃率从接近百分之几降到了个位数次。4.3 Android 12/13StaticIpConfiguration.Builder 与 updateConfiguration到了 Android 12StaticIpConfiguration.Builder公开了构造静态配置终于不用反射字段了。Android 13 又加了EthernetNetworkUpdateRequest可以一次性把 IP 配置和网络能力NetworkCapabilities一起提上去import android.net.EthernetManager; import android.net.EthernetNetworkUpdateRequest; import android.net.LinkAddress; import android.net.NetworkCapabilities; import android.net.StaticIpConfiguration; import java.net.InetAddress; import java.util.Arrays; public void setStaticIpModern(EthernetManager ethManager, String iface, String ip, int prefixLen, String gateway, String dns1, String dns2) throws Exception { // 1. 静态 IP 配置 StaticIpConfiguration.Builder builder new StaticIpConfiguration.Builder() .setIpAddress(new LinkAddress(InetAddress.getByName(ip), prefixLen)) .setGateway(InetAddress.getByName(gateway)); if (dns2 null || dns2.isEmpty()) { builder.setDnsServers(Arrays.asList(InetAddress.getByName(dns1))); } else { builder.setDnsServers(Arrays.asList( InetAddress.getByName(dns1), InetAddress.getByName(dns2))); } StaticIpConfiguration staticConfig builder.build(); // 2. 网络能力必须带以太网传输类型否则请求会被丢 NetworkCapabilities caps new NetworkCapabilities(); caps.addTransportType(NetworkCapabilities.TRANSPORT_ETHERNET); caps.addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET); // 3. 组装更新请求两个 setter 都必填漏一个 build 直接抛 EthernetNetworkUpdateRequest request new EthernetNetworkUpdateRequest.Builder() .setIpConfiguration(staticConfig) .setNetworkCapabilities(caps) .build(); // 4. 下发 ethManager.updateConfiguration(iface, request); }EthernetNetworkUpdateRequest.Builder有个坑setIpConfiguration和setNetworkCapabilities两个都必须调只设 IP 不设能力build()会抛IllegalArgumentException。我第一次踩的时候一脸问号翻源码才发现build()里对这两个字段做了非空断言。而NetworkCapabilities里如果不加TRANSPORT_ETHERNET即使配置成功网络也不会被ConnectivityService当作以太网网络选中默认网络可能还挂在 Wi-Fi 上。另外这段代码需要RequiresPermission(MANAGE_ETHERNET_NETWORKS)所以必须跑在系统签名应用里。如果你的应用拿不到别浪费时间调直接看下一节。4.4 反射调用的稳定性技巧与混淆注意系统签名应用里我建议优先用SystemApi加SuppressLint(MissingPermission)直接调别一上来就反射——直接调 IDE 能检查方法签名代码可读性也好得多。只有确实被 hide 挡住、编译期拿不到符号时再上反射。反射部分务必做到三点一是所有Class.forName都包try-catch并把异常吞成能力探测的返回值不能让反射异常传到业务层二是方法名、字段名抽成常量集中在一个类里方便将来某个版本改名时一处修改三是开 R8/ProGuard 时把涉及反射的类加keep规则虽然系统类通常不会被混淆但你自己写的封装类会被反射getMethod找不到方法的情况我见过不止一次。提示反射系统隐藏 API 的行为在 Android 9 以后受 non-SDK 接口策略限制灰名单会打日志警告黑名单直接拒绝。上线前一定在真机上跑一遍模拟器上不一定复现真实策略。5. 拿不到系统签名时的替代方案与边界5.1 root 环境下的 ip 命令组合与 DNS 补齐设备已 root或者你做的是有 su 能力的定制系统时可以不碰框架层直接用命令改内核网络配置# 1. 确认网卡存在且链路是 up cat /sys/class/net/eth0/operstate ip link set eth0 up # 2. 清掉旧地址设置新地址 ip addr flush dev eth0 ip addr add 192.168.10.50/24 dev eth0 # 3. 路由默认网关和同网段直连路由 ip route add 192.168.10.0/24 dev eth0 ip route add default via 192.168.10.1 dev eth0 # 4. 关键一步告诉 netd/解析器这个网络的 DNS # netid 先用 ip rule 或者 dumpsys connectivity 查到 cmd netd resolver setnetdns netid 192.168.10.1这里是整条路子最大的坑只改ip addr不改 DNS域名解析一定失败。因为 Android 的 DNS 走的是netd的解析器不看/etc/resolv.conf那个文件在 Android 上基本是摆设。很多人 ping 得通8.8.8.8却打不开网页就是卡在这一步。还有个隐蔽问题框架层的EthernetTracker会周期性检查接口状态一旦发现与你手配的不一致可能把配置覆盖回 DHCP 结果。所以 root 方案的定位应该是“临时救急”或者“配合系统改造彻底关闭框架接管”不能当作长期的量产方案。5.2 无权限时的正确姿势引导而非硬刚普通应用在没有系统权限的情况下最稳妥的做法是引导用户去系统设置里配。别小看这种方式做好体验也能很顺滑try { Intent intent new Intent(android.settings.ETHERNET_SETTINGS); intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); context.startActivity(intent); } catch (ActivityNotFoundException e) { // 部分 ROM 没实现退回网络设置总入口 context.startActivity(new Intent(android.provider.Settings.ACTION_SETTINGS) .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)); }配套要做的是“配置检测”应用启动时读一次ConnectivityManager里以太网网络的LinkProperties把当前 IP、网关、DNS 展示出来和业务期望的网段比对不一致就弹引导。这套逻辑不依赖任何特殊权限LinkProperties是公开 API。我踩过的一个坑是不要试图靠adb shell settings put去改以太网配置Settings.Global里没有对应的静态 IP 键值写了也不会生效只会污染设置数据库。5.3 明确边界哪些事千万不要做有三件事我明确建议别碰。第一别改build.prop或者塞自定义persist.*属性来“预设 IP”。框架层不认这些属性除了让后人维护时困惑没别的作用。第二别直接手改/data/misc/ethernet/下的配置文件。这个文件确实存在是EthernetConfigStore的持久化位置但它的序列化格式随版本变化过直接改坏了会导致以太网服务启动异常严重的话开不了机。第三别在量产版本里长期开着hidden_api_policy。这等于把系统的 SDK 限制整个拆掉稳定性和安全性都没保障。6. 验证与排查从 dumpsys 到 logcat 的一条龙6.1 怎么确认配置真的生效了配置“返回成功”不等于“生效”我见过太多setConfiguration没报错但实际没变的情况。验证要分层做一层一层往下推。第一层框架层认不认adb shell dumpsys ethernet输出里重点看三处接口是否被 tracker 跟踪、IpConfiguration的ipAssignment是不是STATIC、LinkProperties里的地址和网关对不对。第二层内核层有没有adb shell ip addr show eth0 adb shell ip route show table all | grep eth0第三层网络栈有没有注册成可用网络adb shell dumpsys connectivity | grep -i ethernet重点看这个网络的NetworkAgentInfo状态是不是CONNECTED以及它有没有被选为默认网络Default network: ... eth0。如果它是CONNECTED但不是默认网络说明被 Wi-Fi 抢了看下一节。第四层真正能不能通adb shell ping -c 3 192.168.10.1 adb shell ping -c 3 www.example.com第一个 ping 验证链路和路由第二个 ping 验证 DNS。两个都通才算真的配好了。6.2 路由与 DNS 的隐蔽问题Wi-Fi 和以太网同时在线时ConnectivityService按NetworkScore选默认网络。以太网的默认分数通常高于 Wi-Fi但厂商定制可能改过。表现是以太网配了静态 IP 也能 ping 通自己的网关但 App 的请求还是走了 Wi-Fi导致访问内网服务器失败。确认默认网络归属用adb shell dumpsys connectivity看Default network那一行。如果确实被抢可以在系统定制里调NetworkScore或者在应用里用ConnectivityManager.bindProcessToNetwork()显式绑定到以太网网络——后者是应用层能做的不需要系统权限。DNS 的问题更隐蔽。dumpsys connectivity里每个网络都有DnsAddresses去看以太网那个网络的 DNS 是不是你填的那两个。如果显示的是路由器下发的地址说明静态配置里的 DNS 没被采纳多半是构造StaticIpConfiguration时dnsServers列表没塞进去——反射场景下这个字段是ArrayList你得往里add而不是set整个列表set会替换掉内部引用某些版本会失效。6.3 常见故障速查表现象大概率原因排查命令处理方式设置不报错但 IP 没变接口不在config_ethernet_interfaces白名单adb shell dumpsys ethernet修改系统 overlay 并重新编译抛SecurityException缺少MANAGE_ETHERNET_NETWORKSadb shell dumpsys package 包名系统签名或改走引导路径抛IllegalArgumentException前缀长度非法、网关跨网段打印构造参数前置校验掩码连续性和网段能 ping 网关不能解析域名DNS 未下发到 netddumpsys connectivity看DnsAddresses补 DNS或检查列表是否真塞进去了重启后配置丢失未持久化或被 DHCP 覆盖重启前后对比dumpsys ethernet确认走的是setConfiguration而非裸ip命令配了静态 IP 仍走 Wi-Fi默认网络被 Wi-Fi 抢占dumpsys connectivity看默认网络调分数或用bindProcessToNetwork网卡状态为 down网线未插、交换机端口未启用cat /sys/class/net/eth0/carrier先解决物理链路cmd ethernet提示未知命令系统版本不支持该子命令adb shell cmd ethernet换用setConfiguration或升级系统注意carrier文件读出来是1才代表物理链路 upoperstate是up但carrier是0的情况很常见——网线插着但对端没通电这时候配什么 IP 都不会通。7. 踩坑记录与工程化建议7.1 刷新固件后配置回退做量产的时候遇到过一次集体故障几百台设备升级固件后静态 IP 全部变回 DHCP。原因是新固件的 overlay 里改了config_ethernet_interfaces的默认值而EthernetConfigStore在读到配置与白名单不匹配时会重置。后来我们把静态配置的预设逻辑放进了首次开机的BootReceiver每次开机比对一次业务网段不一致就重新下发等于加了一层自愈。这个思路值得借鉴别指望配置一次就永远正确让它具备自我修复能力。代价是开机时多几百毫秒换来的是现场零上门。7.2 批量部署脚本的几个细节批量刷机场景下我把设备按 MAC 排序后分配 IP脚本里加了三重保险下发后立刻ping网关失败重试一次重试仍失败就记录序列号到失败清单全部跑完再统一dumpsys ethernet抓一遍状态做交叉核对。这套流程把一次 200 台的部署从两天压缩到半天且事后能拿出完整的配置证据链。另外提醒一句adb并发不要开太高。我试过 16 路并发结果三分之一设备adbd响应超时反而更慢。8 路左右是比较稳的甜点。7.3 我个人在实际操作中的几点体会第一先确认物理链路再谈配置。我统计过自己排障的记录大概三成的“配置不生效”最后查出来是网线、交换机端口或者 VLAN 划分的问题跟 Android 一点关系没有。第二版本分支要写死在代码里。别用try-catch兜底所有异常然后静默降级那样出了问题日志里什么都没有。按SDK_INT明确分支每个分支打不同的 tag排障时一眼就能定位走的是哪条路。第三能进系统签名就别用反射。反射带来的维护成本远超它省下的那点定制工作量尤其是要跟多个 Android 大版本的时候。第四给现场留一个“恢复 DHCP”的入口。静态 IP 配错了导致设备失联是最难处理的情况有个物理按键或者开机时的一个时间窗口能切回 DHCP能救命。我们后来的设备都保留了这个机制实现方式很简单开机后 5 秒内检测某个组合键命中就调一次setConfiguration把IpAssignment设回DHCP。

Android以太网eth0静态IP配置实战：权限、框架与版本适配

相关推荐

ARMv8汇编本质：ISA语义、微架构约束与ABI契约的三重映射

Linux网络套接字编程基础与实战

2.4G无线键鼠接收器丢失后的对码配对与排障指南

更多资讯

超速检测算法题背后的工业级实时车速判定逻辑

Vue项目集成UEditor富文本编辑器实战指南

C/C++网络库选型指南：从事件循环到通信框架的实战对比

后见之明：如何把踩过的坑变成团队资产？

信息系统管理工程师备考指南：从入门到通关

从零手写AI系统：BPE、反向传播与Transformer实战

今日更新

淘宝商品详情API开发实战与性能优化指南

Unity Package Manager刷新错误排查与解决方案

Java record 规范构造器能否被反序列化或反射绕过

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？