更新记录

1.0.0（2026-08-12）

• 建立企业 VPN 安全接入统一合同和 11 状态会话机。
• Android 使用系统 VpnManager，iOS 使用 NetworkExtension 接入 IKEv2。
• 支持用户名密码、预共享密钥、客户端证书三种认证方式。
• 提供能力查询、配置校验、权限准备、连接/断开、状态监听、脱敏日志和私有缓存诊断导出。
• 对系统不提供的会话流量统计和尚未接入的扩展引擎返回真实能力结果。
• 对 Harmony、Web 和小程序提供明确的平台能力结果，不以伪成功代替原生支持。

平台兼容性

uni-app(5.23)

uni-app x(5.23)

lizhao--pro 企业 安全接入

能力与场景

在 uni-app、uni-app x 的 Android 与 iOS App 中接入客户自有 IKEv2/IPsec 服务。插件使用操作系统托管的 引擎，不在应用进程内截获业务数据包；业务层通过统一 UTS API 完成配置预检、系统授权、连接、状态监听、断开、脱敏日志和诊断导出。

适合以下场景：

• 政务、国企、金融、医疗等需要从移动端安全访问内网系统的应用。
• OA、ERP、MES、仓储、巡检和远程运维等专网业务。
• 需要统一 Android/iOS 调用方式，同时保留平台真实状态和错误细节的项目。
• 需要用户名密码、预共享密钥或客户端证书认证的标准 IKEv2 服务。
• 需要在客户现场导出不含账号、密码、密钥和私钥的诊断文件，缩短联调时间的项目。

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

功能特色

• 系统托管隧道：Android 使用 ***Manager + Ikev2***Profile，iOS 使用 NE***Manager + NE***ProtocolIKEv2。
• 三种认证方式：用户名密码、预共享密钥、客户端证书，配置校验会提前拦截互斥项和缺失项。
• 统一 11 状态：从 idle、preparing 到 connected、reconnecting、failed，Android/iOS 使用同一状态合同。
• 抗乱序会话：每次操作使用 sessionId + sequence 关联，旧会话、重复事件和乱序事件不会覆盖当前状态。
• 回调可预测：一次性 API 的 success/fail/complete 各自至多交付一次；持续状态通过 on***Event/off***Event 管理。
• 不伪造能力：系统拿不到单会话流量时，supportsTrafficStats 明确为 false；未接入的引擎和平台返回结构化错误。
• 凭据最小暴露：iOS 密码和 PSK 只进入不可同步的本机 Keychain，并向系统配置传 persistent reference；证书使用 Keychain identity reference。
• 双重脱敏：日志写入前脱敏，诊断组装后再次脱敏；诊断类型从设计上排除 profile 和 credentials。
• 私有诊断文件：导出到 App 私有缓存目录，调用方不能指定任意文件路径。
• 双项目示例：同时提供 uni-app Vue 页面和 uni-app x UVUE 页面，先查能力，再校验配置，最后进入真实连接。

下载与接入

1. 在插件市场当前页面选择“下载插件并导入 HBuilderX”。
2. 从插件根目录导入，不要直接引用 utssdk 内部文件：

import {
  get***CapabilitiesSync,
  validate***ProfileSync,
  prepare***,
  connect***,
  disconnect***,
  on***Event,
  off***Event
} from '@/uni_modules/lizhao-***-pro'

3. Android 项目最低 API 30；iOS 项目需要 Personal *** entitlement 与匹配的 App ID/描述文件。
4. 插件包含 Kotlin、Swift、Manifest、entitlement 和系统 Framework 配置，导入后必须重打并重新安装对应自定义基座。
5. 按下文第一步到第五步逐项接入。不要跳过能力查询、配置校验或系统授权。

完整示例：

• uni-app：uni_modules/lizhao-***-pro/example/uniapp/index.vue
• uni-app x：uni_modules/lizhao-***-pro/example/uniappx/index.uvue

第一步：查询能力

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

import { get***CapabilitiesSync } from '@/uni_modules/lizhao-***-pro'

const capabilities = get***CapabilitiesSync()
const ikev2 = capabilities.engines.find(item => item.engine === 'ikev2')

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

重点字段：

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

第二步：连接前校验配置

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

import {
  validate***ProfileSync,
  ***Profile
} from '@/uni_modules/lizhao-***-pro'

type ***Form = {
  serverAddress: string
  identity: string
  username: string
  password: string
}

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

const profile = buildPasswordProfile(***Form)
const validation = validate***ProfileSync(profile)

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

预共享密钥认证

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

客户端证书认证

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

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

第三步：准备系统权限

import { prepare*** } from '@/uni_modules/lizhao-***-pro'

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

prepare*** 负责检查系统能力和当前授权状态。Android 的真实 profile 授权发生在 connect*** 调用 provision***Profile 时；iOS 的实际权限与配置可用性以保存系统 *** 配置的结果为准。

第四步：监听状态并连接

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

import {
  connect***,
  on***Event,
  off***Event
} from '@/uni_modules/lizhao-***-pro'

let ***ListenerId = on***Event(event => {
  console.log('*** state:', event.status.state)
  if (event.status.lastError != null) {
    console.log(event.status.lastError.errCode, event.status.lastError.errMsg)
  }
})

connect***({
  profile,
  timeoutMs: 30000,
  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 dispose***Listener() {
  if (***ListenerId.length > 0) {
    off***Event(***ListenerId)
    ***ListenerId = ''
  }
}

Android API 33 及以上可读取真实 ***ProfileState；Android API 30–32 在系统接受启动请求后只能可靠报告 connecting。iOS 通过系统状态通知更新 connected/reconnecting/disconnecting/disconnected。业务页面应以状态监听或 get***StatusSync 为准。

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

第五步：状态、断开、日志与诊断

查询当前状态

import { get***StatusSync } from '@/uni_modules/lizhao-***-pro'

const status = get***StatusSync()
console.log(status.state, status.connectedAt)

断开连接

import { disconnect*** } from '@/uni_modules/lizhao-***-pro'

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

读取脱敏日志

import { get***Logs } from '@/uni_modules/lizhao-***-pro'

get***Logs({
  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 { export***Diagnostics } from '@/uni_modules/lizhao-***-pro'

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

诊断文件只包含平台、状态、系统可提供的统计字段和有限日志，不包含完整 profile、credentials、密码、PSK 或私钥。文件位于 App 私有缓存目录，业务方分享或上传前仍应取得用户同意并遵循自身隐私制度。

API

***Profile

Ikev2ProfileOptions

***Credentials

***Status

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

错误码

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

平台支持与限制

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

Android ***Manager 和 iOS NE***Manager 都不提供当前系统 IKEv2 会话的独立字节/数据包统计，所以 supportsTrafficStats 为 false，get***TrafficStatsSync 返回零值与采样时间，不表示真实流量为零。

权限、隐私与自定义基座

Android

• 最低 API 30。
• 声明 android.permission.INTERNET 和可选 android.software.ipsec_tunnels feature。
• 不创建自有 ***Service，不在应用进程读取隧道数据包。
• API 33+ 使用系统 session key 和 ***ProfileState；系统授权页面由 Android 管理。

iOS

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

隐私

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

自定义基座

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

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

作者系列UTS插件

作者系列UTS插件覆盖文件、设备、音视频、数据与业务能力，可按项目需要组合使用。以下均为已核验的公开插件市场页面。