VPN全称为 Virtual Private Network(虚拟专用网络),一般用于外部访问企业内网、多设备远程内网互通等场景。
一、架构
鸿蒙App与VPN开发架构:双进程 + 系统 TUN 模式。
UI 进程 (EntryAbility + ArkUI/native UI)
│ startVpnExtensionAbility(Want: optionsJson + ashmem fd + 通知 fd + attemptId)
▼
系统拉起独立进程 VpnExtensionAbility
│ createVpnConnection(ctx) → connection.create(VpnConfig) → TUN fd
│ protectProcessNet() / protect(fd)
▼
native (Rust/Zig) 读写 TUN fd(AsyncFd 事件驱动)
│ 用户态 TCP/IP 栈 或 VPN 协议主循环
▼
出站代理 socket(必须走物理网,不能回环进 TUN)
二、关键技术
2.1 VPN启动
由主进程(一般情况下为EntryAbility)通过ArkTS方法拉起VPN进程。所有VPN的操作在VPN进行中进行,包括:VPN配置、创建、状态维护和更新等逻辑。
VpnConfig:addresses(必填)、routes、dnsAddresses、mtu、isIPv4Accepted/isIPv6Accepted、isBlocking(默认 false,系统实际强制 O_NONBLOCK)、trustedApplications/blockedApplications(空=全量);RouteInfo.interface 固定 'vpn-tun'。
这部分参考官方Demo或者文档即可,无太多坑点。
2.2 状态同步
由于UI进程和VPN进程分属于不同进程,对于App交互来说只有在UI线程渲染VPN服务的实际状态,VPN进程只负责对应的VPN管理,因此一般情况下必须在两进程之间进行状态同步。但是实际上目前官方无用于两进程之间同步的方法,因此需要使用一些其他方案进行状态同步。
缓存文件
实现方式:
- 主进程在应用私有目录(两个进程均可访问的路径,如
filesDir下的固定文件)维护一个状态文件,将 VPN 状态(starting / connected / failed / cancelled、连接信息、统计等)序列化(如 JSON)写入; - 拉起 VPN 进程时,通过 Want 参数传入该文件路径;
- VPN 进程启动后读取该文件,并在状态变化时持续更新;
- UI 侧周期性或按需读取该文件渲染状态。
注意点:
- 写入必须原子化:先写临时文件再
rename,避免对端读到半截内容; - 文件权限收紧(如 0600),进程退出后清理残留;
- 该方案没有变更通知能力,UI 侧要么轮询读取,要么配合其他通道(如消息/事件)触发读取。
Ashmem
实现方式:
- 主进程创建 ashmem 共享内存并
mmap,约定帧协议:帧头含 magic、版本、generation(单调递增序号)、内容长度、校验和;读写采用双缓冲槽位,payload 先写入、帧头最后提交,对端读到撕裂帧头时重试; - 同时创建一对
AF_UNIX SOCK_DGRAMsocketpair 作为变更通知通道:一方写入状态帧后向对端 socket 发送通知字节,对端阻塞在poll/recv上被唤醒后再去读共享内存; - 拉起 VPN 进程时,把 ashmem fd 与通知 fd 通过 Want 参数以
{type:'FD', value}对象(或want.fds)传入; - VPN 进程收到后先
dup()两份 fd 再mmap使用(fd 归 ArkTS 运行时所有,接收方必须自行复制一份避免所有权冲突),按同一协议读写; - 两侧各自维护一个事件泵:阻塞等待通知 fd,收到事件后同步一次共享状态;停止时通过进程内的取消通道唤醒等待者,而不是关闭跨进程通知 fd。
注意点:
- 帧的序号(revision)要单调递增,不能用时间戳代替(设备时钟精度不足),保证终态帧不会被当作旧帧丢弃;
- 事件通知用 socket 事件驱动,不要用定时轮询。
无论以上哪种方案,都需要在主进程在拉起VPN进程的时候将共享的文件路径或者句柄传递给VPN进程,VPN进程通过文件路径或者句柄来同步状态。
三、隐藏问题
3.1 首次启动导致的状态问题
第一次启动某一个包名的VPN时,系统将弹出授权VPN的弹窗。此阶段易产生状态同步问题。
原因:用户确认授权后,系统会以**新的 Want(只包含 bundleName/abilityName,不含原自定义参数)**重新拉起 VPN 进程(部分系统版本会把原参数包进 myParams 嵌套对象)。原 Want 中携带的配置与状态通道(共享文件路径 / ashmem 句柄、attemptId 等)因此丢失,VPN 进程无法建立状态同步通道,UI 侧一直停留在启动中,直至超时或失败。
处理:
- UI 侧在收到系统受理确认后,重新发送一次完整的原 Want(携带全部参数),让已启动的 VPN 进程通过
onRequest收到完整参数; - VPN 进程对"无参数的空 Want"不直接判定失败,保持空闲等待重发到达后再建立状态通道;
- 读取参数时兼容两种布局:参数直接呈现,或被系统包进
myParams后解包取出; - 将启动过程状态机化:UI 侧发起启动后进入 starting 状态,最终结果只以 VPN 进程通过共享状态通道回传的终态(connected / failed / cancelled)为准,不要以系统接口的返回值直接判定成功与否(系统接口返回只代表"请求已受理");
- 状态流转用事件通知驱动,而不是定时轮询共享状态;
- 对重复或重入的启动请求做去重与幂等处理,保证同一时刻只有一个进行中的启动流程,避免对共享状态反复写入互相覆盖。
3.2 容器环境无效
原因:VPN 建立后,系统按 UID 范围下发 VPN 的 dnsAddresses 并把全部流量路由进 TUN(0.0.0.0/0)。但在部分 Harmony 兼容环境(如:卓易通等容器环境)中,系统解析器仍保留上行 DNS 地址,不切换到 VPN 下发的 dnsAddresses,同时这些 DNS 包已被路由进 TUN——即"保留上行解析器地址、但包进了 TUN",VPN 的 DNS 配置形同虚设。此时协议栈的 TUN 数据路径默认按原目标地址转发 DNS 包(发往上行解析器),与"应使用 VPN 服务端 DNS"的隧道语义冲突,表现为 DNS 解析失败或泄漏。
解决方案(在 TUN 数据面实现 DNS 定向改写,让所有 DNS 查询最终都到达 VPN 服务端下发的 DNS 服务器):
- 识别:在读取到出 TUN 的数据包时,识别 DNS 查询(IPv4 + UDP 且目标端口 53),并判断其目标地址是否与 VPN 下发的 DNS 服务器地址一致;仅对不一致(即容器环境仍发往上行解析器)的包做改写,正常环境的包不做处理。
- 改写请求:将 DNS 查询包的目的 IP(必要时含端口)改写为 VPN 服务端 DNS 地址,并重新计算 IP 头校验和与 UDP 校验和,再交给协议栈转发。
- 记录映射:以"源 IP + 源端口 + 查询 ID"为键记录改写前的原目标地址,供响应还原使用;映射表需要设置过期时间并定期清理,防止泄漏与内存增长。
- 还原响应:收到从服务端 DNS 返回的响应后,按映射把源地址恢复为原解析器地址(同时还原源端口),重新计算校验和后写回 TUN。
- 边界:只对 DNS(端口 53)流量做此处理,不匹配域名、不硬编码客户端网络;映射缺失或超时的响应按丢弃处理。
可以参考AnyConnect-rs 对应的实现处理。
四、实践
- 基于OpenConnect协议的内网连接App,现已上架,源码地址 H-OpenConnect