WinPcap 鸿蒙 PC 适配全记录：从 NPF 原始抓包到 VPN_TUN 与 libpcap 双通路

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_winpcap

一、为什么要适配 WinPcap

WinPcap 是 Windows 网络开发生态中的基础组件。许多抓包工具、协议分析程序、网络诊断软件和实验教程，都围绕 pcap_* 接口、BPF 过滤器以及 pcap 文件格式构建。它的价值不只在于"看到网络包"，更在于形成了一套被大量现有 C/C++ 项目使用的兼容接口。

适配 WinPcap 可以为 HarmonyOS PC 补齐一条基础的网络观测链路：开发者可以在真机上查看 IP 包、使用 BPF 缩小分析范围、保存标准 pcap 文件，也能让部分依赖 WinPcap/libpcap API 的原有代码以较小代价进入 OpenHarmony 环境。同时，这个项目也适合用来检验一个关键问题：当原软件的核心能力与 Windows 内核驱动强绑定时，如何在不混淆权限边界的前提下，仍然做出普通用户可安装、可操作的鸿蒙 PC 版本。

本次适配集成 libpcap 1.10.5，应用名为 OHOS WinPcap，BundleName 为 com.nutpi.ohospcap，目标设备为 HarmonyOS PC 2in1，Native ABI 为 arm64-v8a。

二、先划清边界：NPF 驱动不能原样搬到普通 HAP

Windows 版 WinPcap 依赖 NPF 内核驱动获取物理网卡上的原始帧，其中包含 Win32 HANDLE、驱动 IOCTL、混杂模式和内核缓冲等平台专属语义。HarmonyOS 普通三方 HAP 不具备 CAP_NET_RAW，无法直接使用 AF_PACKET/SOCK_RAW 复制这条链路。如果只把代码编译成 arm64 库，实际运行时仍然会停在权限错误上。

项目因此保留了两条互补通路：

运行场景	抓包方式	可见数据	使用条件
普通鸿蒙 PC HAP	VpnExtensionAbility + TUN	IPv4/IPv6 三层 IP 包	用户授权 VPN 后即可使用
系统签名或 eng 设备	libpcap PF_PACKET	Ethernet、ARP、VLAN 等二层帧	需要 NET_RAW 权限
远程抓包	rpcap:// 实时句柄	由远程端提供的链路层	需要可访问的 rpcap 服务
离线分析	libpcap pcap_open_offline	pcap 文件中的原始链路类型	通过系统文件选择器授权

这样做的目的不是把 TUN 说成 NPF 的完全替代，而是让普通用户有一条真正能跑的 IP 层抓包通路，同时为有更高权限的系统环境保留二层抓包能力。

三、鸿蒙版整体架构

仓库中的 ohos/ 目录同时包含 Native 兼容层和 HAP 应用。Native 侧交叉编译 libpcap、libwpcap 兼容层、rpcapd 与示例程序；HAP 侧使用 ArkUI 提供用户界面，通过 NAPI 调用 libpcap，并由 VPN 扩展能力建立普通应用可用的抓包链路。

EntryAbility / Index.ets
    ├── 实时源选择、BPF 输入、包列表和 pcap 文件选择
    ├── 物理网卡或 rpcap://
    │     └── libpcap NAPI 非阻塞实时句柄
    └── 留空实时源
          └── VpnCaptureAbility
                ├── 创建 IPv4/IPv6 vpn-tun
                ├── 在 DLT_RAW 上执行 BPF
                └── 127.0.0.1:39001 转发二进制帧
                      └── ArkUI 实时展示并写入 vpn_capture.pcap

关键目录如下：

ohos_winpcap/
├── Common/                              # 原 WinPcap 公共头文件
├── Examples/、Examples-pcap/            # 原始示例
├── wpcap/                                # 原 WinPcap/libpcap 代码
└── ohos/
    ├── build.sh                          # OpenHarmony NDK 交叉编译入口
    ├── wpcap-compat/                     # WinPcap 扩展 API 兼容层
    ├── examples/                         # 网卡枚举、抓包、统计等示例
    ├── tools/ohos_capture_check.c        # AF_PACKET/NET_RAW 能力探测
    └── app/
        ├── build-profile.json5           # SDK、产品与签名配置
        └── entry/src/main/
            ├── ets/pages/Index.ets      # 实时展示、文件打开与状态管理
            ├── ets/vpn/                 # VPN/TUN 抓包扩展
            └── cpp/napi_init.cpp       # libpcap 的 NAPI 封装

四、核心适配过程

1. 让应用先成为一个可用的鸿蒙 PC 抓包工具

首页没有照搬 WinPcap 时代的示例程序，而是把实时源、开始/停止、pcap 文件、BPF 过滤器和包列表放在同一页中。实时源留空时使用 VPN/TUN，也可输入网卡名称或 rpcap:// 地址。页面右上角直接显示当前加载的 libpcap 版本，方便确认 NAPI 与 Native 库已经成功进入运行时。

以下五张图均来自 HarmonyOS PC 2in1 真机的实际运行界面，设备截图分辨率为 3120×2080，运行应用的 BundleName 为 com.nutpi.ohospcap。

2. 用 VPN/TUN 为普通 HAP 建立实时抓包通路

用户点击"开始抓包"后，应用启动 VpnCaptureAbility，创建同时接受 IPv4 与 IPv6 的 vpn-tun。扩展进程从 TUN fd 中读取原始 IP 包，再通过本机 127.0.0.1:39001 将帧传给 UI 进程。转发头保留 caplen、原始长度和时间戳，界面侧能够在同一条链路中完成实时列表展示与 pcap 记录写入。

为避免本机转发通道被再次导入 TUN，VPN 配置将应用自身加入 blockedApplications。这个细节很重要：如果不排除自己，抓到的包会被回环转发再产生新包，最终形成递归流量。

3. 抓取与保存使用同一份数据

VPN/TUN 提供的是三层 IP 包，因此实时文件使用 DLT_RAW 写入。应用在启动抓包时创建 vpn_capture.pcap，逐包写入标准 pcap 文件头和记录头。停止抓包后，先同步并关闭文件，再通过内置 libpcap 重新打开。这不仅能验证刚刚生成的文件是否可解析，也让实时抓取和离线分析使用同一套包列表交互。

列表中每条记录都显示序号、时间戳、原始长度、抓取长度和前 32 字节 Hex。界面仅保留最近 800 条记录，而 pcap 文件持续写入全部数据，避免长时间抓包时 UI 列表无限增长。

4. BPF 必须在实时与离线两条链路中保持一致

页面中的 BPF 表达式同时作用于实时和离线数据。使用 VPN/TUN 时，过滤器在 DLT_RAW 的 dead handle 上编译，并对从 TUN 读到的每个 IP 包调用 pcap_offline_filter；使用物理网卡或 rpcap 时，则对实时 pcap_t 句柄调用 pcap_compile 和 pcap_setfilter。这样不会因为输入源不同而改变过滤表达式的使用方式。

图中包数据以 60 开头，与 IPv6 首部版本字段一致。这张图验证的不只是输入框有内容，而是 BPF 已经进入 VPN 扩展的逐包处理路径。

5. 离线 pcap 仍然保留原始链路类型

离线文件通过鸿蒙系统文件选择器授权。应用将选中的文件复制到自身可访问的目录后，由 NAPI 调用 pcap_open_offline、pcap_next_ex 和 BPF 接口完成解析。与 TUN 生成的 DLT_RAW 文件不同，外部以太网样本能正确显示为 EN10MB，帧内也保留 Ethernet 头。

这条链路使鸿蒙版不只能分析自己刚刚抓到的数据，也能处理来自其他 pcap 工具的标准文件。

五、适配过程中最棘手的几个问题

难点一：权限模型改变了"抓包"的技术语义

NPF/PF_PACKET 面向物理网卡的二层帧，VPN/TUN 面向系统路由后的三层 IP 包，两者不能用同一套能力描述。本项目在界面、pcap datalink 和功能说明中都保留这个区别：普通 HAP 能完成 IPv4/IPv6 观测，但无法由此宣称已获得 Ethernet 混杂抓包能力。

难点二：跨进程流式数据必须能处理粘包和拆包

VPN 扩展和界面位于不同运行上下文，TCP 又不保留消息边界。项目为每个包增加 16 字节帧头，界面侧使用可累积的接收缓冲区，只在完整帧到达后才进入列表与文件。同时对帧长度设置 65535 上限，避免异常数据导致缓冲区失控。

难点三：BPF 编译依赖正确的 datalink

ip6、tcp port 443 这类表达式虽然文本相同，但 BPF 指令中读取字段的偏移取决于链路层类型。如果把 TUN 包按 Ethernet 帧编译，过滤结果会在无报错的情况下全部错位。因此 VPN 链路固定使用 DLT_RAW，物理网卡和 rpcap 则使用句柄真实返回的 datalink。

难点四：WinPcap 扩展 API 需要按行为重新映射

pcap_sendqueue_*、统计模式、pcap_live_dump 和 pcap_getevent 都带有 Windows 驱动层语义。wpcap-compat 没有用空函数让项目"看起来能链接"，而是将发送队列改为用户态定时发送，将 live dump 改为后台线程写盘，并把 Win32 事件对象改为可供 poll/epoll 使用的 fd。这些映射保留了源码迁移所需的主要能力，同时也明确标注了与 NPF 内核实现的性能差异。

难点五：实时抓包不能让界面内存随会话无限增长

抓包程序很容易在几分钟内产生大量记录。鸿蒙版将"文件保留全量数据"和"界面只展示最近数据"分开处理，每次追加新包后裁剪列表，但不截断 pcap 记录。这样既能保持界面流畅，也不会牺牲后续离线分析需要的完整数据。

六、编译、安装与启动

HAP 工程根目录是 ohos/app/，使用 DevEco Studio 时应直接打开该目录，并为 com.nutpi.ohospcap 配置与目标设备匹配的调试签名。当前工程的 Target SDK 和 Compatible SDK 均为 6.0.1(21)。

命令行构建方式如下：

export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
cd ohos/app

/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  assembleHap --mode module \
  -p product=default \
  -p module=entry@default \
  -p buildMode=debug \
  --no-daemon

开发机的 SDK 版本应与工程目标版本匹配。如果升级到启用更严格 ArkTS 检查的新工具链，需要按编译器提示为 UI 构建函数与回调补全显式返回类型，不建议通过关闭严格检查来规避问题。

签名产物通常位于：

ohos/app/entry/build/default/outputs/default/entry-default-signed.hap

连接 HarmonyOS PC 后安装并启动：

hdc list targets
hdc install -r ohos/app/entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.nutpi.ohospcap -m entry

首次启动 VPN/TUN 抓包时需要用户完成系统授权。如果输入 wlan0、eth0 等物理设备，普通签名 HAP 收到 Permission denied 属于预期的权限边界，该路径需要系统签名或 eng 设备提供 NET_RAW。

Native 兼容层可单独交叉编译：

./ohos/fetch-libpcap.sh
./ohos/build.sh arm64-v8a

产物输出到 ohos/out/arm64-v8a/dist/，其中包含 libpcap、libwpcap、rpcapd、能力探测工具和多个抓包示例。

七、当前功能边界

当前版本已经覆盖以下主要能力：

• HarmonyOS PC 2in1 上的 HAP 安装与 ArkUI 界面；
• 基于 VPN/TUN 的 IPv4、IPv6 实时抓包；
• 实时 BPF 编译、过滤和错误反馈；
• 持续抓包、界面最近 800 条限制与标准 pcap 写入；
• 停止抓包后使用 libpcap 重新读取文件；
• 通过系统文件选择器打开外部 pcap，保留 RAW、EN10MB 等链路类型；
• NAPI 侧的网卡枚举、实时非阻塞读取、发包与统计接口；
• libpcap、WinPcap 扩展兼容层、rpcapd 与示例程序的 OpenHarmony Native 构建链。

仍需明确的限制包括：

• VPN/TUN 模式仅提供三层 IP 包，不包含 Ethernet、ARP、VLAN 和 802.11 链路帧；
• 当前 VPN 通路用于观测流量，没有集成完整的用户态 TCP/UDP 转发栈，接管默认路由时可能影响外网访问；
• 物理网卡的混杂模式、TPACKET_V3 与二层发包需要 NET_RAW，不是普通三方 HAP 可自行获取的权限；
• AirPcap、WanPacket、Win9x NPF 驱动等 Windows 硬件或内核绑定能力不在本次迁移范围内；
• 发送队列、统计模式与 live dump 在 OpenHarmony 上采用用户态等价实现，性能与时序精度不与 NPF 内核版本完全相同。

因此，当前版本的准确定位是：对普通鸿蒙 PC 用户，它是一个可以完成双栈 IP 实时观测、BPF 过滤、pcap 保存与离线重读的工具；对系统签名或 eng 环境，则进一步保留 libpcap/WinPcap 的二层实时能力和源码兼容价值。

八、总结

WinPcap 的鸿蒙 PC 适配不是一次简单的库交叉编译。真正的难点在于，需要把 Windows 驱动提供的二层权限、libpcap 的跨平台能力和鸿蒙普通应用的安全模型重新组织起来。

本项目最终采用了分层方案：Native 侧继续提供 libpcap 与 WinPcap 扩展 API 兼容；普通 HAP 利用 VPN/TUN 建立可授权的 IP 层抓包通路；ArkUI 与 NAPI 再把实时展示、BPF、pcap 保存和离线解析串成完整工作流。

这套实践对其他依赖 Windows 驱动或特权 API 的开源项目也具有参考意义：先确认新系统真正能够提供的权限边界，再为普通用户建立可行的替代通路，最后保留有价值的跨平台接口，而不是用"已编译"代替"真正可用"。