XuqmGroup a9f320db63 docs: 更新 README + 配置文件规范 + 架构总览（BugCollect/withXuqmConfig）

Co-Authored-By: Claude <noreply@anthropic.com>

2026-06-18 15:34:48 +08:00

6.3 KiB

原始文件 Blame 文件历史

配置文件规范

最后更新：2026-06-15

概述

XuqmGroup SDK 使用加密配置文件完成自动初始化，对齐 Android SDK 的 ContentProvider 模式。

核心流程：

宿主把加密配置文件放到标准位置
SDK 在 common bundle 加载时自动读取、解密、初始化
宿主代码零初始化调用

配置文件格式

加密格式

XUQM-CONFIG-V1.{base64urlSalt}.{base64urlIV}.{base64urlCiphertext}

部分	说明
`XUQM-CONFIG-V1`	固定 magic header
`base64urlSalt`	PBKDF2 盐值（16 字节，base64url 编码）
`base64urlIV`	AES-GCM 初始向量（12 字节，base64url 编码）
`base64urlCiphertext`	AES-256-GCM 密文 + 16 字节 auth tag

加密参数

参数	值
算法	AES-256-GCM
密钥派生	PBKDF2-HMAC-SHA256
迭代次数	120,000
密钥长度	256 位
Auth Tag	128 位（16 字节）

解密后 JSON 结构

{
  "appKey": "yiwangxin",
  "appName": "医网信",
  "companyName": "BJCA",
  "baseUrl": "https://www.51trust.com",
  "serverUrl": "https://www.51trust.com",
  "packageName": "cn.org.bjca.wcert.ywq",
  "iosBundleId": "com.bjca.ywq",
  "issuedAt": "2026-01-01T00:00:00Z",
  "expiresAt": "2028-01-01T00:00:00Z"
}

字段	必填	说明
`appKey`	✅	应用唯一标识
`appName`	❌	应用名称
`companyName`	❌	公司名称
`baseUrl`	❌	API 服务地址（覆盖默认值）
`serverUrl`	❌	私有部署地址（覆盖所有服务端点）
`packageName`	❌	Android 包名（用于校验）
`iosBundleId`	❌	iOS Bundle ID
`issuedAt`	❌	签发时间
`expiresAt`	❌	过期时间

宿主集成方式

React Native（Metro bundler）

推荐方式：withXuqmConfig Metro 插件

将平台下载的 .xuqmconfig 加密文件直接放入 src/assets/config/（推荐）或 src/assets/xuqm/，然后用 withXuqmConfig 包裹 Metro 配置：

文件位置：src/assets/config/config.xuqmconfig（原始加密文件，无需改名或创建 .ts 包装）

Metro 配置（metro.config.js）：

const { getDefaultConfig } = require('@react-native/metro-config');
const { withXuqmConfig } = require('@xuqm/rn-common/metro');
const baseConfig = getDefaultConfig(__dirname);
module.exports = withXuqmConfig(baseConfig);

withXuqmConfig 会自动扫描 src/assets/config/ 和 src/assets/xuqm/ 目录，优先查找 config.xuqmconfig 或 config.xuqm，否则取第一个 .xuqmconfig 文件。找到后生成虚拟模块并注入 Metro 解析链，SDK import 时自动读取并初始化。

兼容方式：手动 alias

如果无法使用 Metro 插件，也可以手动配置 alias。由于 Metro 只能 bundle JS/TS 模块，配置文件使用 .ts 扩展名。

文件位置：src/assets/xuqm/config.xuqmconfig.ts

export const ENCRYPTED_CONFIG = "XUQM-CONFIG-V1.{salt}.{iv}.{ciphertext}";

Metro alias（metro.config.js）：

const alias = {
  "@xuqm/autoinit-config": path.resolve(
    projectRoot,
    "src/assets/xuqm/config.xuqmconfig",
  ),
};

Babel alias（babel.config.js）：

'@xuqm/autoinit-config': './src/assets/xuqm/config.xuqmconfig'

TypeScript path（tsconfig.json）：

"@xuqm/autoinit-config": ["src/assets/xuqm/config.xuqmconfig"]

Android（原生）

配置文件位置：src/main/assets/xuqm/config.xuqm

Android SDK 通过 ContentProvider 自动读取，无需额外配置。

iOS（原生）

配置文件位置：{app}/xuqm/config.xuqm

自动初始化流程

common bundle 加载
  → import '@xuqm/rn-common'
    → packages/common/src/index.ts
      → import './autoInit'  （副作用）
        → tryAutoInit()
          → require('@xuqm/autoinit-config')
            → Metro 解析 alias → 宿主 config.xuqmconfig.ts
          → XuqmSDK.initWithConfigFile(encrypted)
            → configCrypto.decryptConfigFile(encrypted)
              → PBKDF2 派生密钥
              → AES-256-GCM 解密
            → initializeFromLicense(decrypted)
              → configureHttp(baseUrl || serverUrl)
              → markInitialized()

失败处理

对齐 Android SDK 的 runCatching + Log.w 行为：

配置文件不存在 → 静默跳过
解密失败 → 静默跳过
SDK 保持未初始化状态
awaitInitialization() 会超时
不崩溃、不阻塞 app 启动

降级机制

如果自动初始化失败，宿主可以手动调用：

import { XuqmSDK } from "@xuqm/rn-common";

// 使用默认 URL 初始化
XuqmSDK.init({ appKey: "yiwangxin", debug: __DEV__ });

安全注意事项

不要提交解密后的明文配置到版本控制
不要在日志中打印配置文件内容或解密后的数据
配置文件的 appKey 用于 API 调用，不要硬编码在业务代码中
serverUrl 字段会覆盖所有服务端点，确保指向正确的环境

与 Android SDK 的对齐

环节	Android SDK	RNSDK
配置文件位置	`assets/xuqm/config.xuqm`	`src/assets/xuqm/config.xuqmconfig.ts`
自动初始化	ContentProvider.onCreate()	common 包 import 时 autoInit
解密	ConfigFileCrypto (Java)	configCrypto (JS + react-native-quick-crypto)
失败处理	runCatching + Log.w	try/catch + 静默跳过
服务端点覆盖	configurePrivateServer()	initializeFromLicense(serverUrl)

6.3 KiB 原始文件 Blame 文件历史 Unescape Escape