ionic-enterprise-sdk-migration

Ionic Enterprise SDK 迁移

逐个用开源 Capgo 插件替换 Ionic Enterprise 插件，同时保留登录会话和已存储的数据。

背景：Ionic 已于 2025 年 2 月停止销售其商业产品（包括 Enterprise SDK），并正在逐步停止维护；请在许可证或支持期限结束前规划迁移。

使用时机

在以下情况触发：

• package.json 包含 @ionic-enterprise/auth、@ionic-enterprise/identity-vault 或 @ionic-enterprise/secure-storage。
• 代码导入 AuthConnect、ProviderOptions、Vault、BrowserVault、VaultType、DeviceSecurityType，或 Secure Storage 的 SQLite / KeyValueStorage。
• 用户询问如何替换 Auth Connect、Identity Vault 或 Secure Storage，且不强制用户重新登录。

以下情况不要使用：

• Appflow Live Updates / 构建 -> ionic-appflow-migration。
• 社区版或其他 SQLite 插件 -> sqlite-to-fast-sql。
• 生物识别 UX 或通用安全审查 -> capacitor-security。

当前项目快照

检测到的 Ionic Enterprise 和替换包： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@ionic-enterprise/')||name.startsWith('@capgo/')||name==='@capacitor/preferences'||name==='@capacitor/core')out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

替换映射

Ionic Enterprise	替换方案	涵盖内容	不涵盖（需在应用中重建）
Auth Connect	@capgo/capacitor-social-login（OIDC/OAuth2 身份提供商使用 provider: 'oauth2'；也支持 google、apple、facebook 等）	授权码 + PKCE、令牌刷新（refreshToken）、登出、原生 Apple/Google 登录	令牌存储策略（使用 Native Biometric 或加密 SQL 存储令牌）
Identity Vault	@capgo/capacitor-native-biometric	在 Keychain/Keystore 中保存/读取/删除凭据；accessControl: BIOMETRY_CURRENT_SET 或 BIOMETRY_ANY 可使读取操作必须通过生物识别；在 iOS 上使用带密码回退的 verifyIdentity；biometryChange 监听器	闲置锁定超时、应用转入后台时的隐私屏幕（@capacitor/privacy-screen）、自定义密码保险库、内存保险库
Secure Storage（SQLite）	@capgo/capacitor-fast-sql，搭配 encrypted: true + encryptionKey	加密 SQLite（SQLCipher）、事务、批处理、KeyValueStore	密钥管理——将数据库密钥保存在 Native Biometric 中，而非 JS 常量中
Secure Storage（键值）	@capgo/capacitor-data-storage-sqlite 或 Fast SQL KeyValueStore	简单的加密键值存储

非敏感设置可以存入 @capacitor/preferences。切勿将令牌或机密信息存入其中。

流程

步骤 1：检测并规划

rg -n "@ionic-enterprise/" -g '!node_modules' .

列出每个企业版包、所有调用位置，以及存储的内容（键、数据库名称、保险库配置：type、deviceSecurityType、lockAfterBackgrounded、unlockVaultOnLoad）。如果存在多个插件，每个版本仅迁移一个插件。编辑前先报告计划。

步骤 2：规划数据迁移（两个版本规则）

只有在旧插件仍处于安装状态时，才能读取旧插件数据。对于令牌、保险库值或加密数据库：

1. 发布版本 N：在企业版插件旁安装 Capgo 替换插件。首次启动时，从旧存储中读取数据，写入新存储，设置 migrated 标记，然后清除旧存储。
2. 发布版本 N+1（大多数用户已打开版本 N 后）：移除企业版插件。

如果用户接受所有人都强制重新登录，则单个版本即可；请明确确认这一点。

第 3 步：Auth Connect → Social Login

npm install @capgo/capacitor-social-login
npx cap sync

• 保持客户端 ID、作用域和重定向 URI 不变；发布前，先向 IdP 注册任何新的原生重定向（自定义 scheme 或通用链接）。
• 将每个 Auth Connect 提供商（Azure、Auth0、Okta、Cognito、通用 OIDC）映射到 SocialLogin.initialize({ oauth2: { <providerId>: { ... } } }) 中的一个 oauth2 条目，并配置 clientId/appId、issuerUrl 或 authorizationBaseUrl + accessTokenEndpoint、redirectUrl 和作用域。查看插件的 OAuth2 文档，确认已安装版本所需的确切字段。
• 将 AuthConnect.login/logout/refreshSession/isAccessTokenExpired 替换为 SocialLogin.login({ provider: 'oauth2', options: { providerId } })、logout、refreshToken，并自行检查返回令牌的有效期。
• 在测试租户中对比变更前后的授权请求（作用域、prompt、受众）和令牌响应。

第 4 步：Identity Vault → Native Biometric

npm install @capgo/capacitor-native-biometric
npx cap sync

import { NativeBiometric, AccessControl } from '@capgo/capacitor-native-biometric';

await NativeBiometric.setCredentials({
  server: 'com.company.app.session',
  username: userId,
  password: refreshToken,
  accessControl: AccessControl.BIOMETRY_CURRENT_SET,
});

const { password: token } = await NativeBiometric.getSecureCredentials({
  server: 'com.company.app.session',
  reason: 'Unlock your account',
});

• lockAfterBackgrounded -> 在 App resume 时，如果经过的时间超过超时时长，则显示锁屏并再次调用 getSecureCredentials。
• DeviceSecurityType.Both / 密码回退 -> verifyIdentity 支持在 iOS 上回退到设备密码；受保护的凭据读取仍仅支持生物识别。
• BIOMETRY_CURRENT_SET 会在生物识别信息变更时使条目失效（类似 Identity Vault 的严格模式）；BIOMETRY_ANY 在注册信息变更后仍可使用。
• 应用切换器中的隐私屏幕 -> @capacitor/privacy-screen。
• iOS：在 Info.plist 中添加 NSFaceIDUsageDescription。

第 5 步：Secure Storage → Fast SQL 或 Data Storage SQLite

npm install @capgo/capacitor-fast-sql
npx cap sync

import { FastSQL, KeyValueStore } from '@capgo/capacitor-fast-sql';

const db = await FastSQL.connect({ database: 'app', encrypted: true, encryptionKey });
const kv = await KeyValueStore.open({ database: 'kv', encrypted: true, encryptionKey });

• 保留相同的架构；移植查询（executeSql -> db.query / db.run / db.executeBatch / db.transaction）。
• 加密需要 SQLCipher：Android 在 android/app/build.gradle 中添加 implementation 'net.zetetic:sqlcipher-android:<version>'；iOS 使用 CocoaPods 子规范 CapgoCapacitorFastSql/SQLCipher。如果未添加，在 iOS 上使用 encrypted: true 会报错 Encryption is not available in this build。
• Fast SQL 会运行一个本地主机 HTTP 服务：添加 NSAppTransportSecurity -> NSAllowsLocalNetworking（iOS），并在 Android 上配置允许本地主机明文流量的 network_security_config.xml。完整设置请参见 sqlite-to-fast-sql。
• 使用 Native Biometric（第 4 步）保存 encryptionKey，或在服务端派生该密钥；切勿将其硬编码。

第 6 步：清理

npm uninstall @ionic-enterprise/auth @ionic-enterprise/identity-vault @ionic-enterprise/secure-storage
rg -n "@ionic-enterprise" -g '!node_modules' .
npx cap sync

确认不再使用任何企业版软件包后，再从 .npmrc 中移除 Ionic Enterprise 注册表/令牌配置行（否则 CI 安装会失败）。

验证

• 升级测试：安装当前商店版本，登录并存储数据；在其上安装新版本；用户仍保持登录，数据也仍然存在。
• 全新安装：在真实的 iOS 和 Android 设备上，登录、令牌刷新、注销和生物识别解锁均正常工作（模拟器无法完整测试生物识别）。
• 更改设备生物识别信息：BIOMETRY_CURRENT_SET 条目将无法读取，应用会回退到登录。
• 最终发布后，rg -n "@ionic-enterprise" -g '!node_modules' . 不返回任何结果。
• CI 中的 npm ci 无需 Ionic Enterprise 注册表凭据即可成功。

错误处理

问题	修复方法
CI 中 @ionic-enterprise/* 出现 npm error 401 Unauthorized / 404	企业版注册表令牌已过期；完成移除，或保留该令牌直到 N+1 版本发布
更新后用户被注销	数据未迁移；先发布同时使用两个插件的版本 N
切换后出现 redirect_uri_mismatch / IdP 错误	向 IdP 注册新的重定向 URL；保持作用域不变
Encryption is not available in this build	添加 SQLCipher 依赖/子规范，然后重新构建
Fast SQL 调用因网络错误而失败	缺少 ATS 本地网络配置 / Android 本地主机明文流量配置
注册信息变更后生物识别读取失败	使用 BIOMETRY_CURRENT_SET 时属于预期行为；重新验证身份并再次保存