更新记录

1.2.2（2026-11-07）

• 优化说明文档，补齐“作者系列 UTS 插件”清单及插件市场链接，便于按能力查找。

1.2.1（2026-11-06）

• 修复示例页面和辅助模块使用相对引入路径的问题，统一通过 @/uni_modules/ 引用插件内文件，复制页面到其他目录时无需另行复制辅助代码。

1.2.0（2026-10-16）

• Android 最低声明扩展到 Android 6 / API 23，覆盖 Android 10；API23–29 使用自带 IKEv2/ESP 与 VpnService，API30+ 继续使用系统 IKEv2。
• 低版本分支保留密码（EAP-MSCHAPv2）、PSK 与 KeyChain 客户端证书三种认证，加入真实 TUN/底层网络保护、完整重连和流量统计；13个公共 API 保持兼容。
• 原生核心按 ARM64/ARMv7 提供 API23 库、可重现构建身份及分立第三方许可/必要源码材料，不改变插件自有代码的发布方式。
• 两宿主示例增加版本生成校验、原生诊断文件采集和手动分段复制；保留真实状态/错误及脱敏。
• 本地源码、资源和原生联编证据单独记录；真实网关互操作、授权、设备及匹配基座仍须验收，不能把此候选当作已发布或真机已通过。

平台兼容性

uni-app(5.23)

uni-app x(5.23)

lizhao-vpn-pro 企业 VPN 安全接入

介绍

在 uni-app / uni-app x 的 Android、iOS App 中接入客户自有 IKEv2/IPsec VPN，统一完成配置校验、系统授权、连接、状态监听、断开与脱敏诊断；服务器、账号、证书和密钥由客户授权管理，插件不提供公共节点。

服务器、账号、证书、密钥和网络策略均由客户自行提供、授权和管理。插件不提供公共节点，不上传配置，不把“启动请求已提交”伪装成“隧道已经连接”。

功能特色

适合哪些场景

下载与导入

1. 从插件市场通过 HBuilderX 导入完整 uni_modules/lizhao-vpn-pro/；API 和类型只从 @/uni_modules/lizhao-vpn-pro 导入。
2. 将对应页面复制到业务目录，在 pages.json 注册后运行。先查询能力、校验配置，再处理系统授权，不跳过任何一步。
3. 首次接入或原生 Kotlin / Swift、Manifest、JNI、entitlement 等变化，须重新联编并安装匹配自定义基座；WGT 不能更新旧基座原生代码。

示例底部提供完整日志、固定快照分段与手动复制。先“导出诊断”可把实际私有 JSON 纳入报告，读取失败会保留错误；复制不申请权限、不重新连接，也不清日志。插件信息由构建数据校验，HX / 包类型未知时写 unknown；coreBuild 只代表实际 Go/JNI 核心，系统引擎不提供。

选择接入方式与导入

普通 JavaScript 页面只导入 API；带类型的示例用于 uni-app x UTS 或 TypeScript，不能直接把类型注解复制进 JavaScript。

import {
  getVpnCapabilitiesSync,
  validateVpnProfileSync,
  prepareVpn,
  connectVpn,
  disconnectVpn,
  onVpnEvent,
  offVpnEvent
} from '@/uni_modules/lizhao-vpn-pro'

从基础到进阶：按业务模块使用

模块零：从业务配置发起一次连接

以下为 uni-app x UTS 调用函数；普通 JavaScript 页面删除类型导入和注解。把表单或受控接口取得的真实 VpnProfile 传入，先注册监听再连接，退出页面时释放监听；释放监听与断开隧道分别处理。

import {
  getVpnCapabilitiesSync, validateVpnProfileSync, prepareVpn, connectVpn,
  onVpnEvent, offVpnEvent, VpnProfile
} from '@/uni_modules/lizhao-vpn-pro'

const listenerId = onVpnEvent((event) => {
  console.log('VPN状态', event.status.state, event.status.statusConfidence)
})

function startEnterpriseVpn(profile: VpnProfile): void {
  const capability = getVpnCapabilitiesSync()
  const ikev2 = capability.engines.find(item => item.engine === 'ikev2')
  if (ikev2 == null || !ikev2.available) {
    console.log('当前引擎不可用，请核对设备与自定义基座')
    return
  }
  const validation = validateVpnProfileSync(profile)
  if (!validation.valid) { console.log(validation.issues); return }
  prepareVpn({
    success: () => {
      connectVpn({
        profile: profile, timeoutMs: 30000,
        success: result => { console.log('请求已受理', result.state) },
        fail: error => { console.log(error.errCode, error.errMsg, error.nativeCode) },
        complete: () => { console.log('本次连接请求回调结束，后续状态看监听') }
      })
    },
    fail: error => { console.log(error.errCode, error.errMsg) }
  })
}

function disposeVpnPage(): void { offVpnEvent(listenerId) }

系统授权由插件在连接过程中衔接。连接回调的 connecting 只表示请求被接受，界面应以真实状态事件或 waitVpnState 判断连接结果。

模块一：查询能力

先根据真实能力决定是否显示连接按钮：

import { getVpnCapabilitiesSync } from '@/uni_modules/lizhao-vpn-pro'

const capabilities = getVpnCapabilitiesSync()
const ikev2 = capabilities.engines.find(item => item.engine === 'ikev2')

if (ikev2 == null || !ikev2.available) {
  console.log(ikev2?.reason ?? '当前平台不支持企业 VPN')
}

重点字段：

• platform：android、ios 或当前不支持的平台名。
• engines[].available：引擎是否真实可用。
• supportsTrafficStats：系统是否提供当前隧道的独立流量统计。
• supportsDiagnostics：是否可以导出脱敏诊断文件。

模块二：连接前校验配置

配置值应来自客户运行时表单、安全配置中心或受控业务接口，不要把真实地址和凭据写入源码。

import {
  validateVpnProfileSync,
  VpnProfile
} from '@/uni_modules/lizhao-vpn-pro'

type VpnForm = {
  serverAddress: string
  identity: string
  username: string
  password: string
}

function buildPasswordProfile(form: VpnForm): VpnProfile {
  return {
    id: 'company-ikev2',
    name: '企业内网',
    engine: 'ikev2',
    ikev2: {
      serverAddress: form.serverAddress,
      identity: form.identity,
      authentication: 'password'
    },
    credentials: {
      username: form.username,
      password: form.password
    }
  }
}

// vpnForm 为业务表单实际提供的 VpnForm，不能填入示例账号；取得后调用：
const profile = buildPasswordProfile(vpnForm)
const validation = validateVpnProfileSync(profile)

if (!validation.valid) {
  validation.issues.forEach(item => {
    console.log(`${item.field}: ${item.message}`)
  })
}

预共享密钥认证

前置：业务运行时提供 vpnForm.serverAddress、identity 和 preSharedKey；这是另一种认证配置，不与密码认证同时传。

const profile: VpnProfile = {
  id: 'company-psk',
  name: '企业专网',
  engine: 'ikev2',
  ikev2: {
    serverAddress: vpnForm.serverAddress,
    identity: vpnForm.identity,
    authentication: 'pre-shared-key'
  },
  credentials: {
    preSharedKey: vpnForm.preSharedKey
  }
}

客户端证书认证

前置：业务提供 vpnForm.serverAddress、identity 与已经安全导入的 certificateAlias；不要把私钥放入源码。

const profile: VpnProfile = {
  id: 'company-certificate',
  name: '证书专网',
  engine: 'ikev2',
  ikev2: {
    serverAddress: vpnForm.serverAddress,
    identity: vpnForm.identity,
    authentication: 'certificate',
    certificateAlias: vpnForm.certificateAlias
  }
}

certificateAlias 必须指向已经由宿主应用或系统流程安全导入的客户端证书身份。插件不会从 README 路径、公共目录或网络地址自动读取私钥。

模块三：准备系统权限

import { prepareVpn } from '@/uni_modules/lizhao-vpn-pro'

prepareVpn({
  success(result) {
    if (result.authorized) {
      console.log('系统 VPN 能力已准备')
    } else {
      console.log('首次连接时还需要完成系统授权')
    }
  },
  fail(error) {
    console.log(error.errCode, error.errMsg, error.suggestion)
  },
  complete() {}
})

prepareVpn 负责检查系统能力和当前授权状态。Android 6–10 使用 VpnService.prepare 授权，Android 11+ 的 profile 授权发生在 connectVpn 调用 provisionVpnProfile 时；iOS 的实际权限与配置可用性以保存系统 VPN 配置的结果为准。

模块四：监听状态并连接

先注册监听，再发起连接。页面卸载时必须释放监听。

import {
  connectVpn,
  onVpnEvent,
  offVpnEvent
} from '@/uni_modules/lizhao-vpn-pro'

let vpnListenerId = onVpnEvent(event => {
  console.log('VPN state:', event.status.state)
  if (event.status.lastError != null) {
    console.log(event.status.lastError.errCode, event.status.lastError.errMsg)
  }
})

connectVpn({
  profile,
  timeoutMs: 45000,
  success(result) {
    // connecting 表示系统已接受启动请求，不等于隧道已经建立。
    console.log('连接操作状态:', result.state)
  },
  fail(error) {
    if (error.errCode === 9300003) {
      console.log('请在系统页面完成授权，App 回到前台后重试连接')
      return
    }
    console.log(error.errCode, error.errMsg, error.nativeCode)
  },
  complete() {}
})

function disposeVpnListener() {
  if (vpnListenerId.length > 0) {
    offVpnEvent(vpnListenerId)
    vpnListenerId = ''
  }
}

Android API23–29 需要协商成功、Child SA、系统 TUN 与同代际健康检查全部就绪后才报告 connected；API33 及以上可读取真实 VpnProfileState；Android API 30–32 在系统接受启动请求后只能可靠报告 connecting。iOS 通过系统状态通知更新 connected/reconnecting/disconnecting/disconnected。connectVpn 的 timeoutMs 只限制权限衔接、配置下发和原生启动操作，不把“启动请求已接受”解释成“隧道已经连接”。

等待可信终态

需要在登录、内网资源加载等业务流程中等待真实终态时，使用 waitVpnState，不必在页面自行编写轮询：

import { waitVpnState } from '@/uni_modules/lizhao-vpn-pro'

waitVpnState({
  states: ['connected', 'failed'],
  timeoutMs: 60000,
  success(status) {
    console.log(status.state, status.statusSource, status.statusConfidence)
  },
  fail(error) {
    // 9300019 表示指定时间内没有到达目标状态，不代表插件伪造失败状态。
    console.log(error.errCode, error.suggestion)
  },
  complete() {}
})

statusSource 用于区分系统查询、原生事件、操作推导或平台不可查询；statusConfidence 用于区分确认状态、估计状态和未知状态。Android API 30–32 的 connecting 为 operation/estimated，不能当成真实 connected。

当前系统与用户态 IKEv2 均不提供应用内动态挑战，因此 respondVpnChallenge 当前返回明确不支持错误。该 API 为后续可产生 OTP、短信或口令挑战的扩展引擎保留，不影响现有调用合同。

模块五：状态、断开、日志与诊断

查询当前状态

import { getVpnStatusSync } from '@/uni_modules/lizhao-vpn-pro'

const status = getVpnStatusSync()
console.log(status.state, status.connectedAt)

断开连接

import { disconnectVpn } from '@/uni_modules/lizhao-vpn-pro'

disconnectVpn({
  success(result) {
    console.log('断开操作状态:', result.state)
  },
  fail(error) {
    console.log(error.errCode, error.suggestion)
  },
  complete() {}
})

读取脱敏日志

import { getVpnLogs } from '@/uni_modules/lizhao-vpn-pro'

getVpnLogs({
  limit: 100,
  success(result) {
    result.entries.forEach(entry => {
      console.log(entry.timestamp, entry.level, entry.message)
    })
  },
  fail(error) {
    console.log(error.errCode, error.errMsg)
  },
  complete() {}
})

导出诊断文件

import { exportVpnDiagnostics } from '@/uni_modules/lizhao-vpn-pro'

exportVpnDiagnostics({
  includeLogs: true,
  success(result) {
    console.log('脱敏诊断文件:', result.filePath)
  },
  fail(error) {
    console.log(error.errCode, error.suggestion)
  },
  complete() {}
})

诊断文件只包含平台、状态、引擎可提供的统计字段和有限日志；Android 6–10 还包含 androidNative 中的真实引擎、核心构建标记、线程/队列与错误摘要，不包含完整 profile、credentials、密码、PSK 或私钥。文件位于 App 私有缓存目录，业务方分享或上传前仍应取得用户同意并遵循自身隐私制度。

API 用途速查

VpnProfile

Ikev2ProfileOptions

VpnCredentials

VpnStatus

状态全集：idle、preparing、permission-required、ready、connecting、auth-required、connected、reconnecting、disconnecting、disconnected、failed。

错误码说明

失败对象还包含 stage、recoverable、nativeCode 和 suggestion。errSubject 固定为 lizhao-vpn-pro。

注意事项

平台支持与限制

公共合同中保留 *** 引擎标识，但当前发布内容没有经过双端原生产物、许可证、包体和真实连接 PoC，因此能力查询固定返回不可用。业务代码不得绕过 capabilities 强行调用。

Android API23–29 用户态引擎的 supportsTrafficStats 为 true（前提是对应 ABI 库加载成功）；统计来自当前隧道收发并在完整重连间累加，不是全机流量。Android API30+ VpnManager 和 iOS NEVPNManager 都不提供当前系统 IKEv2 会话的独立字节/数据包统计，所以 supportsTrafficStats 为 false，getVpnTrafficStatsSync 返回零值与采样时间，不表示真实流量为零。

权限、隐私与自定义基座

Android

• 最低 Android 6 / API23。其他插件及宿主运行时若要求更高版本，最终应用最低版本取全部依赖的最大值；当前综合示例含 API26 插件，验证 API23 应使用仅接入本插件的最小宿主，不能只改综合工程声明。
• API23–29 使用自有 VpnService，数据包在本应用进程的 Go IKEv2/ESP 核心和系统 TUN 间转发，不记录客户数据包正文。当前提供 ARM64/ARMv7；不提供 x86/x86_64 用户态库，缺少匹配库时能力查询返回不可用。
• Manifest 包含 INTERNET、ACCESS_NETWORK_STATE、FOREGROUND_SERVICE、FOREGROUND_SERVICE_SYSTEM_EXEMPTED，Service 由 BIND_VPN_SERVICE 保护；声明可选 android.software.ipsec_tunnels feature。API26+ 低版本分支保持前台通知，不需要额外存储权限。
• 用户态分支不从磁盘恢复凭据，不声明 Always-on；撤销、断开和网络变化会关闭旧资源。网络切换采用完整重连，不承诺 MOBIKE 无缝切换。
• 证书认证使用已授予本应用访问权的 Android KeyChain identity；私钥留在系统，不导出到 Go。服务端证书与身份必须通过平台信任校验；当前公共接口不支持直接传入自定义 CA 文件。
• 客户网关需支持标准 IKEv2、相应认证和双方共同提案；协议、证书链及三认证互通仍须对客户测试网关验收。
• API 33+ 使用系统 session key 和 VpnProfileState；系统授权页面由 Android 管理。

iOS

• 最低部署目标 iOS 12。
• 使用 NetworkExtension 与 Security Framework。
• 宿主 App ID、描述文件和签名必须包含 Personal VPN entitlement。
• 密码和 PSK 写入 kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly Keychain 项，不进入 UserDefaults、日志或诊断文件。

隐私

• 插件不提供服务器、不收集账号、不上传诊断文件。
• 原始 profile、credentials、密码、PSK、私钥和 Bearer 内容不进入诊断结构。
• 日志和诊断分别执行脱敏；业务层仍不得主动打印传入配置。
• 诊断文件位于 App 私有缓存，何时分享、上传或删除由宿主业务决定。

第三方许可与闭源分发

插件自有代码沿用现有发布方式。用户态核心来源及固定提交见 uni_modules/lizhao-vpn-pro/native/android/UPSTREAM.json；MIT/BSD/Apache 等许可分别保留，少量 MPL2 组件需要随包保留对应源码材料。uni_modules/lizhao-vpn-pro/native/android/THIRD-PARTY-NOTICES.md、uni_modules/lizhao-vpn-pro/native/android/third-party-licenses/ 和 uni_modules/lizhao-vpn-pro/native/android/third-party-sources/ 为分发材料，不能统一改成私有许可或加密后删去第三方源码；此路线未引入 strongSwan GPL 引擎。

自定义基座

插件包含 Android Kotlin/Manifest/JNI 与两套 ARM .so，以及 iOS Swift/entitlement/Privacy Manifest。首次导入或升级这些原生文件后，Android、iOS 都必须使用当前 HBuilderX 重新原生联编，重打并安装对应自定义基座。

若 HBuilderX 仍提示“需 Android 11.0 以上设备运行”，先核对当前选择的自定义基座。旧基座的 Manifest 最低版本仍是 API30，必须用当前源码重打并重新选择新基座；appResource/WGT 不能改变旧 APK 的最低系统版本，也不能给旧基座加入本次 JNI/Go/Service。

Android 6–10 分支目前完成本地离线、资源生成和原生联编验证；没有真实网关、系统授权及设备验收证据，仍属待验收候选。

appResource 编译成功只证明 UTS 与生成入口可生成，不能替代 Android/iOS 原生签名、系统授权和真实 VPN 服务器连接。正式上线前至少验证：首次授权、授权后重试、三种认证、连接失败、断网重连、主动断开、App 前后台、诊断导出和卸载后系统配置行为。

• 使用本应用获授权的服务器和认证信息，真实配置不写入源码或日志。
• 连接请求成功不代表隧道已连接；根据真实状态事件与 waitVpnState 决定何时访问内网业务。
• 释放页面监听与断开隧道是两种操作，由业务分别控制。

作者系列 UTS 插件

以下为作者已发布的 UTS 插件，可按能力方向查找。