204 行
6.7 KiB
Markdown
204 行
6.7 KiB
Markdown
# 配置文件规范
|
||
|
||
> 最后更新：2026-06-15
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
XuqmGroup SDK 使用加密配置文件完成自动初始化，对齐 Android SDK 的 ContentProvider 模式。
|
||
|
||
**核心流程**：
|
||
|
||
1. 宿主把加密配置文件放到标准位置
|
||
2. SDK 在 common bundle 加载时自动读取、解密、初始化
|
||
3. 宿主代码零初始化调用
|
||
|
||
---
|
||
|
||
## 配置文件格式
|
||
|
||
### 加密格式
|
||
|
||
```
|
||
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 结构
|
||
|
||
```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`）：
|
||
|
||
```javascript
|
||
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`
|
||
|
||
```typescript
|
||
export const ENCRYPTED_CONFIG = "XUQM-CONFIG-V1.{salt}.{iv}.{ciphertext}";
|
||
```
|
||
|
||
**Metro alias**（`metro.config.js`）：
|
||
|
||
```javascript
|
||
const alias = {
|
||
"@xuqm/autoinit-config": path.resolve(
|
||
projectRoot,
|
||
"src/assets/xuqm/config.xuqmconfig",
|
||
),
|
||
};
|
||
```
|
||
|
||
**Babel alias**（`babel.config.js`）：
|
||
|
||
```javascript
|
||
'@xuqm/autoinit-config': './src/assets/xuqm/config.xuqmconfig'
|
||
```
|
||
|
||
**TypeScript path**（`tsconfig.json`）：
|
||
|
||
```json
|
||
"@xuqm/autoinit-config": ["src/assets/xuqm/config.xuqmconfig"]
|
||
```
|
||
|
||
### Android（原生）
|
||
|
||
配置文件位置：`src/main/assets/config/*.xuqmconfig`（推荐）或 `assets/xuqm/*.xuqmconfig`
|
||
|
||
从平台下载 `.xuqmconfig` 文件（例如 `识校宝.xuqmconfig`），放入上述任一目录。文件名不限，扩展名为 `.xuqmconfig` 即可。Android SDK 通过 ContentProvider 自动扫描并读取，无需额外配置。
|
||
|
||
### iOS（原生）
|
||
|
||
配置文件位置：`{app}/xuqm/*.xuqmconfig`
|
||
|
||
从平台下载 `.xuqmconfig` 文件，放入 App Bundle 的 `xuqm/` 目录。文件名不限，扩展名为 `.xuqmconfig` 即可。SDK 启动时自动扫描并读取。
|
||
|
||
---
|
||
|
||
## 自动初始化流程
|
||
|
||
```
|
||
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 启动
|
||
|
||
---
|
||
|
||
## 降级机制
|
||
|
||
如果自动初始化失败，宿主可以手动调用：
|
||
|
||
```typescript
|
||
import { XuqmSDK } from "@xuqm/rn-common";
|
||
|
||
// 使用默认 URL 初始化
|
||
XuqmSDK.init({ appKey: "yiwangxin", debug: __DEV__ });
|
||
```
|
||
|
||
---
|
||
|
||
## 安全注意事项
|
||
|
||
1. **不要提交解密后的明文配置**到版本控制
|
||
2. **不要在日志中打印**配置文件内容或解密后的数据
|
||
3. 配置文件的 `appKey` 用于 API 调用，**不要硬编码**在业务代码中
|
||
4. `serverUrl` 字段会覆盖所有服务端点，确保指向正确的环境
|
||
|
||
---
|
||
|
||
## 与 Android SDK 的对齐
|
||
|
||
| 环节 | Android SDK | RNSDK |
|
||
| ------------ | ---------------------------------- | --------------------------------------------- |
|
||
| 配置文件位置 | `assets/config/*.xuqmconfig` | `src/assets/config/*.xuqmconfig` |
|
||
| 自动初始化 | ContentProvider.onCreate() | common 包 import 时 autoInit |
|
||
| 解密 | ConfigFileCrypto (Java) | configCrypto (JS + react-native-quick-crypto) |
|
||
| 失败处理 | runCatching + Log.w | try/catch + 静默跳过 |
|
||
| 服务端点覆盖 | configurePrivateServer() | initializeFromLicense(serverUrl) |
|
