鸿蒙Flutter局域网扫描适配：network_tools踩坑与调优

1. 起因：在鸿蒙上做局域网自测，Flutter 工具链给我上了三节课

先把结论放前面：如果你是想在 HarmonyOS 设备上跑一个基于 Flutter 的局域网扫描、端口探测工具，network_tools 这个库能帮你省掉 80% 的造轮子时间，但剩下 20% 的坑，几乎全集中在鸿蒙环境的权限模型和网络栈差异上。

我为什么会碰这个事？最近在整理家里的小型实验室网络，几台开发板、智能家居网关、树莓派混在同一网段，总有些设备在悄悄监听端口。我习惯性地想用一个便携工具把内网资产摸一遍，看看哪些端口裸奔在外——平时我是在一台旧 Android 手机上用 Termux 配合命令行工具做这件事的，但手里刚好有一台鸿蒙开发板闲着，就想着试试"Flutter 写一次、多端跑"的便利性，直接在上面跑一个基于 network_tools 的探测工具，顺便验证一下鸿蒙对第三方 Flutter 生态的兼容程度。

结果，事情远没有想象中顺利。

先说 network_tools 本身。这是一个纯 Dart 实现的网络工具库，核心功能涵盖主机发现（通过 ARP 扫描和 ICMP ping）、端口扫描（TCP connect 扫描）、以及设备信息获取（MAC 地址、厂商识别等）。它在 Android 和 iOS 上表现很稳定，也是我一开始选它而不是自己去调 socket 的原因——纯 Dart 实现意味着理论上它对底层 OS 的依赖最小，这在跨端场景里是巨大的优势。

但鸿蒙不一样。鸿蒙的 Flutter 支持走的是 OpenHarmony 的 Flutter 引擎适配分支，大部分 API 是兼容的，可权限模型和网络栈的细节差异，足以让你的探测引擎在"看起来没问题"的外表下全军覆没。

这篇文章就是这段时间的适配实录。我会把完整的探路过程、踩坑点、以及最终稳定运行的配置方案写清楚，给想在鸿蒙上做局域网安全自测的 Flutter 开发者一些参考。顺便说一句：文中所涉及的所有探测行为，都以你自己拥有的设备、或获得明确授权的网络环境为前提。安全自测和越界攻击之间，差的从来不是工具，而是边界。

2. 从零跑通 network_tools：别急着写业务代码，先确认三件事

2.1 版本选型：不是最新就是最好

先看依赖配置。在 pubspec.yaml 里加依赖，这一步通常大家都觉得没什么可说的。但我在鸿蒙上做适配之后才意识到，版本锁定在这个场景里比在 Android 上重要得多。

我最初直接拉了 network_tools 的最新版本，配合 Flutter 的鸿蒙适配分支来编译。结果直接卡在了依赖解析阶段——倒不是 network_tools 本身的问题，而是它内部依赖的一些底层包（比如用于进程间通信和 Socket 封装的 dart-lang 原生库）在鸿蒙的 Flutter SDK 上会有版本兼容警告。

这里给一句实测结论：如果你打算在鸿蒙上用 Flutter 跑 network_tools，建议优先选择你所用 Flutter 鸿蒙 SDK 版本发布时间点前后、且经过社区验证的 network_tools 版本。别盲目追新，鸿蒙适配分支本身有滞后性，太新的依赖容易撞上尚未补齐的实现。

提示：检查 Flutter 鸿蒙分支支持的 Dart SDK 版本，再反推 network_tools 的版本范围。一条简单的经验是：凡是在 pub.dev 上 marked as "supports null safety" 但发布时间晚于鸿蒙 Flutter SDK 超过三个月的版本，都要谨慎。

2.2 鸿蒙权限：漏掉一个声明，扫描结果悄无声息地缺一块

这是我这轮适配里最大的一个坑。

在 Android 上，做网络扫描需要声明<uses-permission android:name="android.permission.INTERNET"/>，部分场景还需要ACCESS_NETWORK_STATE。代码里 requestPermissions 一把梭，用户点个允许就完事。

鸿蒙不一样。HarmonyOS 的权限体系里，网络访问权限（ohos.permission.INTERNET）是基础，但只有它是不够的。当你的应用要通过 ARP 请求去扫描局域网设备时，需要额外的权限来确定设备的网络状态信息——具体来说还包括：

• ohos.permission.INTERNET：基础网络访问
• ohos.permission.GET_NETWORK_INFO：获取网络连接状态，包括 Wi-Fi 信息
• 部分涉及设备状态读取的场景，还要在 module.json5 里配置相应项

漏掉GET_NETWORK_INFO的表现非常隐蔽：应用能够正常访问公网，TCP socket 也能建立，但扫描得到的活跃主机列表永远是空的，或者只有本机自己。因为在鸿蒙上，获取不到完整的网络接口信息就意味着 ARP 请求发不出去——不是被防火墙拦截，是压根没拿到网卡的有效信息。

排查了一整个下午，最终在 DevEco Studio 的 module.json5 里补全了权限声明，这个问题才解决。

2.3 Flutter 鸿蒙引擎的 Socket 差异：TCP connect 扫描为何会"假超时"

接下来的问题更微妙：权限对了，主机能扫出来，但端口扫描部分的结果非常异常。

我最初跑了一个针对本网段网关的 TCP 端口扫描，范围是 1-1024。在 Android 上大概十几秒出结果，open 端口列表清晰。但在鸿蒙上跑同样的逻辑，结果变成了大面积超时，连 80、443 这类必然开放的端口都显示 filtered。

查了很久，问题出在 Flutter 的鸿蒙分支对Socket.connect超时处理上的差异。具体来说：鸿蒙适配后的 Flutter Socket 实现，在 connect 失败时会走一套不同的错误码映射逻辑，其中一部分"连接被拒绝"的情况会被吞掉，表现为超时而不是立即返回错误状态。

这在扫描引擎里是致命的——超时意味着你要等待完整的超时周期才能确认一个端口状态，扫描 1000 个端口，每个超时 3 秒，单目标就要 50 分钟，完全不可用。

我的解决方案是两步走：

1. 修改 network_tools 中端口扫描的探测策略，把默认的"等待超时确认关闭"调整为"以 TCP 连接建立失败即视为关闭"，也就是主动放弃等待；
2. 在调用层加一层并发控制，把默认的扫描并发数从 50 调到 300——鸿蒙的 socket 并发能力比预期好，这个并发量不会触发文件描述符耗尽，同时可以抵消单连接超时带来的性能损失。

改完之后，同样扫 1-1024 端口，耗时从"无法容忍"降到 20 秒以内，与 Android 上的表现基本持平。

3. 沉浸式全频段扫描引擎搭建：底层探测机制的选型与实测

3.1 主机发现：ARP vs ICMP，鸿蒙上的真实差异

端口扫描的底座是主机发现。只有先找到哪些设备在线，端口扫描才有的放矢。network_tools 提供的主机发现策略主要两种：ARP 扫描和 ICMP ping 扫描。

在传统 Linux/Android 环境下，ARP 扫描是局域网探测的首选——它不依赖目标设备是否响应 ping，只要设备在网络里通信过，ARP 缓存或广播就能把它的 IP 和 MAC 揪出来。但鸿蒙上跑 ARP 扫描有个天然劣势：HarmonyOS 对底层 raw socket 访问的限制比 Android 更严格，Flutter 的 Dart 层无法直接构造 ARP 包，network_tools 库的处理方式是通过系统调用来间接实现。

实测下来，在鸿蒙上 ARP 扫描的覆盖率大约只有 Android 上的七成左右。不是扫描逻辑错了，而是部分低功耗设备（尤其是智能家居类）在鸿蒙的 Wi-Fi 省电策略下不会响应 ARP 请求。

所以我在实际引擎里采用了双通道互补策略：

• 优先跑 ICMP ping 扫描作为第一轮摸底（覆盖面广、速度快，对在线设备响应率足够高）；
• 再针对已发现的在线主机做 ARP 信息补全，拿 MAC 地址和厂商信息；
• 两种结果做合并去重，形成最终的活跃主机清单。

这个组合在鸿蒙上的最终实测成绩是：50 台左右设备的家庭/小型办公网络，单次全量扫描能在 8 秒内完成主机发现，漏报率在 3% 以内——主要漏的是深度休眠的 IoT 设备，这个在 Android 上也会漏，属于物理层限制。

3.2 隐蔽端口探测的并发模型：别用 Future.wait 一把梭

network_tools 的端口扫描接口用起来很简单，把目标 IP 和端口范围传进去就行。但简单调用在鸿蒙上跑不出性能，这是这篇适配实录里最想说的一点。

问题出在 Dart 的并发模型上。network_tools 底层是异步 socket 调用，内部确实做了并发控制，但默认参数在鸿蒙上的表现过于保守。我实测的默认扫描大约只有 30-50 个并发连接，在局域网 5ms 延迟环境下，扫一个常见目标的全端口（1-65535）要将近 8 分钟。

我把扫描模块拆成了可配置的并发线程池模型，核心参数如下：

这个配置下，全端口扫描同一目标从 8 分钟缩短到 90 秒左右，同时没有触发任何文件描述符溢出或内存异常。如果你也要这么调，记得关注你的应用在鸿蒙上的ulimit -n限制，大部分设备默认是 1024，300 并发连接加上运行时自身的连接占用，基本是安全的。

3.3 引擎架构上的一个小巧思：按"端口热区"分阶段扫描

在实际使用中，我发现全端口扫描虽然完整，但不是每次都需要。做局域网自查时，真正有价值的通常是几个热区端口——Web 管理口、SSH 口、数据库口、远程控制软件监听口。

我基于 network_tools 封装了一层按端口热区扫描的策略：

• 第一梯队（最常用）：80, 443, 22, 23, 3389, 5900, 8000, 8080, 8443——Web 与远程管理类
• 第二梯队（服务类）：21, 25, 110, 143, 3306, 5432, 6379, 27017——数据库与邮件服务
• 第三梯队（IoT 常见）：1883, 8883, 5683, 8083, 8086, 9000——物联网协议
• 第四梯队（其余）：按需补充

日常巡检只扫前三个梯队，总共 20 个端口，配合 300 并发，单目标一秒完成，整个网段 50 台设备不到 10 秒出结果。发现问题后，再对特定目标单独做全端口深扫。这个"先快扫、再深扫"的节奏，比无脑全端口扫描实用得多，尤其在鸿蒙这种省电策略激进的平台上，减少扫描时长就是在减少设备休眠导致的误判。

4. 零信任视角下的本地网络分析：数据落地与异常识别

4.1 为什么"看见了在线设备"不等于"理解了网络风险"

端口扫描只是手段，不是目的。把扫描结果变成可操作的安全判断，才算是真正完成了一次"本地防线探测"。

我做这事的思路是：把每次扫描的结果持久化下来，形成资产基线，然后做偏移检测。这是零信任模型里最基础也最有效的一环——不默认任何设备的行为是可信的，只认数和基线。

具体实现上，我用 network_tools 返回的设备列表和端口开放情况，串成一个 JSON 结构存到本地 Sqflite 数据库里。每次扫描完成后，和上一次的基线数据做对比，重点看三个维度的异常：

1. 新设备入网——之前没见过 MAC 地址的新主机
2. 新端口开放——同一设备上，之前没出现过某端口监听
3. 高价值端口暴露——22、3389、3306 这类端口出现在之前不开放的设备上

在鸿蒙适配过程中，这个基线模块反而没遇到太多问题。Sqflite 在 OpenHarmony 上的支持已经比较完善，唯一需要注意的是路径处理，鸿蒙的应用沙箱路径和 Android 的getDatabasesPath()返回值结构略有不同，需要做一次路径归一化处理。

4.2 厂商识别的妙用：从 MAC 前缀到设备类型推断

network_tools 自带的厂商识别功能（通过 MAC 地址前三位匹配 OUI 数据库）在鸿蒙上表现稳定。这对局域网资产分析的价值，其实很多使用者没有充分利用。

举个例子，我家里有十来个 IP 在线的设备，看 IP 和主机名很难判断各是什么——因为不少 IoT 设备的主机名，厂商懒得改，看起来都是一串无意义的字母数字。但配合 MAC 的 OUI 厂商识别，设备类型马上清晰了：ESP32 系列的开发板、某品牌的智能插座、树莓派基金会认证适配器、某稞路由器……每个设备大概是什么类型，心里有底之后，"某端口开放"这件事才有了判断上下文。

同样的 8080 端口，在一台树莓派上可能是正常的开发服务，在一台智能插座上就大概率是可疑的信号。这就是为何我坚持认为，资产盘点类工具不能只给一张端口列表，必须带上设备指纹信息。恰恰这一点，network_tools 默认就支持，只是需要你自己把这部分数据接进分析逻辑里。

4.3 把扫描引擎接到通知告警里：全自动巡检链路

做到这一层，已经把 network_tools 的大多数能力都用起来了。但我还加了一步：把扫描任务做成定时巡检。

在鸿蒙上，最简单的实现方式是通过 WorkScheduler 扩展能力（对应 Android 的 WorkManager）来调度周期任务。我做的是每天凌晨 3 点自动跑一轮快扫，扫完做基线对比，如果有异常就把结果推到另一个消息通道——微信群机器人或者邮件都行。

这套全自动链路跑了两周，真实抓到过一次异常：一台老旧 Android 盒子在系统更新后自动开启了 5555 端口的 adb 调试服务，而这个端口在基线上从来没有出现过。如果不是定时巡检自动发现了偏移，这个暴露面可能会一直存在。

注意：如果是低功耗设备（比如蓝牙 Mesh 网关），夜间会进入睡眠状态，自动巡检的扫描结果容易误报"设备离线"。建议巡检时间避开深度睡眠时段，或者对已知低功耗设备做单独的豁免名单处理。

5. 适配实录里的关键经验：鸿蒙 Flutter 生态还差什么

5.1 社区适配 vs 官方支持的界限

这次整轮适配下来，最深的感受是：network_tools 在鸿蒙上能跑到"可用的状态"，但它确实还处于"社区适配"而非"官方支持"的层次。

我要的重点差异，集中在以下两点：

第一，异常处理路径不完整。鸿蒙 Flutter 引擎对部分系统调用的返回错误，仍然是以"吞掉异常"或者"转成通用错误"的形式反馈给上层 Dart 代码。在 Android 上，你拿到SocketException可以准确判断是连接拒绝、网络不可达还是超时；在鸿蒙上，三者经常混在一起。这也直接导致了我在端口扫描策略上做的调整——不做错误码的精确匹配，而是用超时+重试机制兜底。

第二，插件生态有断层。network_tools 本身是纯 Dart 实现，不需要原生插件，跑鸿蒙相对容易。但如果你要做的工具需要依赖 fl_device_info 之类获取系统信息的插件，这些插件绝大多数还没有适配鸿蒙的 ohos 平台目录，需要你自己去 fork 一份改原生代码。纯 Dart 库在鸿蒙上基本能跑，带原生通道的插件就看运气。

5.2 性能数字对比：用真实数据衡量"能不能用"

不是所有项目都需要全端口扫描。衡量鸿蒙适配质量是否达标,我建议你拿这样一组基准数据参考：

这组数据说明：在鸿蒙上基于 Flutter 的局域网探测引擎，做维护型巡检、资产盘点、基线对比是完全可行的，整体性能比 Android 慢 30% 左右，但没到不可用的程度。如果你是做安全工具的开发者，这个代价大概率是可以接受的——前提是你像我一样，愿意花时间在权限声明和并发参数上调校。

如果你期望的是"Android 上怎么跑，鸿蒙上就原样怎么跑、性能一致"，我劝你直接降低预期——至少在现阶段，鸿蒙 Flutter 生态还在补齐期，适合愿意动手调细节的开发者，不适合拿现成代码复制粘贴就期望完美运行的场景。

5.3 给后面接手的人一份避坑清单

总结我这轮适配里所有的坑，整理成一份可以直接照做的清单：

1. module.json5 权限必须补全：INTERNET和GET_NETWORK_INFO一个都不能少，漏掉后者的表现是"能上网但扫不到网段主机"；
2. 端口扫描超时建议手动调低：默认 3 秒在鸿蒙上会放大错误码模糊带来的假超时问题，调到 800ms 到 1 秒之间，配合高并发更适用；
3. ARP 扫描不能作为唯一主机发现手段：在鸿蒙上覆盖率偏低，用 ICMP 先扫、ARP 再补全的方式更可靠；
4. Sqflite 数据库路径需要适配：鸿蒙沙箱路径结构不同，要做路径归一化，否则首次启动会报数据库打开失败；
5. Dart 层的Socket.connect错误捕获要靠超时机制兜底：不要依赖错误码做精确分支，鸿蒙的异常映射还没完全对齐；
6. 定时巡检注意避开低功耗设备的深度睡眠窗口：否则容易积累大量"设备离线"的误报数据，让基线失去参考价值。

6. 结语：这不只是端口嗅探，更是对"零信任"的本地实践

我在多次适配测试中反复打磨这套引擎，最终的收获远不止"在鸿蒙上跑通了 Flutter 网络库"这么简单。实际上，当网络资产的编排、扫描、基线对比、异常发现这条链路完整跑起来之后，你对本地网络的掌控感会和之前完全不同——你不再是盯着路由器后台的 DHCP 列表去猜哪台设备是谁，而是拥有了一张时刻更新的、带端口信息和厂商指纹的资产地图。

最后再分享一个小技巧：如果你只需要临时快速扫一轮网段，不关心端口信息，可以把 network_tools 的主机发现结果直接以 CSV 格式导出，在鸿蒙上用自带的表格工具打开。MAC 地址 + 厂商的清单里，往往能一眼发现那些 .0 和 .255 之外的"幽灵设备"——这类设备在 DHCP 列表里常常被折叠隐藏，但在 ARP 结果里无所遁形。

霍，从工程适配到安全实践，这条路越走越深。有在鸿蒙上做相近尝试的同行，可以按这份实录先搭一个最小验证环境，省下来的排查时间足够你把业务逻辑写出好大一段了。