123 行
5.3 KiB
Markdown
123 行
5.3 KiB
Markdown
|
# SDK 平台 V2 实施与接手说明
|
|||
|
|
|
|||
|
|
> 更新时间：2026-07-26。本文记录当前源码事实与尚未执行的部署动作；不得把本文当作生产环境已发布证明。
|
|||
|
|
|
|||
|
|
## 当前边界
|
|||
|
|
|
|||
|
|
- Config 文件唯一格式为 `XUQM-CONFIG-V2`，V1 不再接受。
|
|||
|
|
- Config 文件由租户服务生成；客户端只验证签名、有效期和包名，不在线检查吊销状态。
|
|||
|
|
- BugCollect 运行时上报失败不得影响宿主业务；服务关闭时固定返回 HTTP 403，消息码为 `BUGCOLLECT_DISABLED`。
|
|||
|
|
- 构建产物上传唯一入口为 `POST /bugcollect/v1/artifacts/upload`。
|
|||
|
|
- 已废弃的 App 离线激活 license 服务已从聚合构建、租户服务、网关和 Web 入口删除；它与签名 SDK 无关。
|
|||
|
|
|
|||
|
|
## Config 文件契约
|
|||
|
|
|
|||
|
|
格式：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
XUQM-CONFIG-V2.<keyId>.<salt>.<iv>.<ciphertext>.<signature>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 内容加密：AES-256-GCM。
|
|||
|
|
- 密钥派生：PBKDF2-HMAC-SHA256，120000 次。
|
|||
|
|
- 完整性与发布方身份：Ed25519 对前五段的 ASCII 原文签名。
|
|||
|
|
- 时间统一使用 UTC `Instant`。
|
|||
|
|
- 重新生成会产生新的 `configId` 和递增 `revision`；旧文件只在后续构建时被拦截，不影响已安装客户端运行。
|
|||
|
|
- 构建校验接口：
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
POST /api/sdk/build/config/validate
|
|||
|
|
Content-Type: application/json
|
|||
|
|
|
|||
|
|
{"content":"...","packageName":"com.example.app"}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
签名密钥只能由运行环境注入：
|
|||
|
|
|
|||
|
|
- `SDK_CONFIG_SIGNING_KEY_ID`
|
|||
|
|
- `SDK_CONFIG_SIGNING_PRIVATE_KEY_BASE64`（PKCS#8 DER Base64）
|
|||
|
|
- `SDK_CONFIG_SIGNING_PUBLIC_KEY_BASE64`（X.509 DER Base64）
|
|||
|
|
|
|||
|
|
公共互操作向量位于 `common/src/test/resources/xuqm-config-v2-vector.json`。私钥不得进入仓库、日志或普通文档。
|
|||
|
|
|
|||
|
|
## SDK 动态配置
|
|||
|
|
|
|||
|
|
`GET /api/sdk/config` 的功能开关按 `appKey + platform + serviceType` 精确读取。版本更新登录要求来自 update-service 的权威字段 `allowAnonymousUpdateCheck`，对外返回 `updateRequiresLogin`。
|
|||
|
|
|
|||
|
|
租户服务访问 update-service 使用 500ms 连接超时、800ms 读取超时和 15s 小 TTL 缓存。依赖不可用时安全返回 `updateRequiresLogin=true`。
|
|||
|
|
|
|||
|
|
## BugCollect 产物契约
|
|||
|
|
|
|||
|
|
构建工具必须携带：
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
Authorization: Bearer <XUQM_API_TOKEN>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Token 复用租户平台 API Key 权威校验，不存在 BugCollect 私有密钥。认证得到的 appKey 必须和上传表单中的 appKey 相同。
|
|||
|
|
该产物端点只接受 Bearer 形式，单独传 `X-API-Key` 必须返回 401；通用业务接口原有的
|
|||
|
|
`X-API-Key` 过滤行为不变。微服务向租户服务校验 Token 时使用受内部令牌保护的
|
|||
|
|
`POST /api/internal/sdk/validate-api-key` JSON 请求体，严禁把 Token 放入 URL、查询参数或日志。
|
|||
|
|
|
|||
|
|
共同字段：
|
|||
|
|
|
|||
|
|
- `artifactType`
|
|||
|
|
- `appKey`
|
|||
|
|
- `platform`
|
|||
|
|
- `appVersion`
|
|||
|
|
- `buildId`
|
|||
|
|
- `file`
|
|||
|
|
|
|||
|
|
`RN_SOURCEMAP` 额外要求 `moduleId`、`moduleVersion`、`bundleHash`，以完整七元组精确匹配，不允许“取最新”回退。source map 不允许内嵌 `sourcesContent`，`sources` 不允许绝对路径、Windows 盘符或 `..` 穿越。
|
|||
|
|
|
|||
|
|
`R8_MAPPING` 仅支持 Android，文件名必须为 `mapping.txt`，并要求 `artifactHash` 与文件 SHA-256 一致。R8 与 RN 产物独立保存和查询。
|
|||
|
|
|
|||
|
|
运行时 `/issues/batch`、`/events/batch` 不使用 CI API Token；它们继续遵循客户端签名与服务开关策略。
|
|||
|
|
|
|||
|
|
## 数据库迁移
|
|||
|
|
|
|||
|
|
- tenant-service：V3 Config V2 元数据、V4 平台专属 App 包名、V5 移除离线 license 服务数据和枚举值。
|
|||
|
|
- xuqm-bugcollect-service：V9 引入精确 bundle 身份和独立产物字段。
|
|||
|
|
|
|||
|
|
执行迁移前必须备份对应数据库。不得修改已在目标环境执行过的历史迁移文件。
|
|||
|
|
|
|||
|
|
## Web 与 Jenkins
|
|||
|
|
|
|||
|
|
- 应用详情页展示 Config 签发元数据，并支持“长期有效”或选择 UTC 到期时间后重新生成。
|
|||
|
|
- 符号化产物页同时展示 RN sourcemap 和 R8 mapping。
|
|||
|
|
- Web 依赖管理统一使用仓库声明的 Yarn 1；不再保留不同步的 `package-lock.json`。
|
|||
|
|
- Server 与 tenant-web Jenkins 默认 `DEPLOY_ENV=development`，development 只验证，不推送、不部署、不提交版本号。
|
|||
|
|
- production 必须经过人工确认，并从 Jenkins Credentials 读取 Git 与 Config 签名凭据。
|
|||
|
|
|
|||
|
|
## 已执行验证
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mvn -Dmaven.repo.local=/private/tmp/xuqm-m2 \
|
|||
|
|
-pl tenant-service,xuqm-bugcollect-service -am test
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
2026-07-26 结果：BUILD SUCCESS。common 共 3 项测试通过，tenant-service 共 3 项测试通过，
|
|||
|
|
xuqm-bugcollect-service 共 7 项测试通过；覆盖 Config 向量、通用 X-API-Key 行为、
|
|||
|
|
受保护的内部 POST 请求体、更新配置失败安全缓存、BugCollect 固定错误、路径校验、
|
|||
|
|
R8 校验，以及产物 API Token 的无 Bearer、仅 X-API-Key、无效 Bearer、有效归属场景。
|
|||
|
|
|
|||
|
|
Server 全聚合 `mvn -DskipTests compile` 结果：BUILD SUCCESS，聚合构建中已不包含 license-service。
|
|||
|
|
|
|||
|
|
Web 验证命令：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
yarn install --frozen-lockfile
|
|||
|
|
yarn build:tenant
|
|||
|
|
yarn build:ops
|
|||
|
|
yarn workspace @xuqm/docs-site build
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
2026-07-26 三项 Web 构建均通过。最终结果以当前任务交接记录为准。
|
|||
|
|
|
|||
|
|
## 尚未执行
|
|||
|
|
|
|||
|
|
- 未提交、未推送。
|
|||
|
|
- 未触发 Jenkins，未部署任何环境。
|
|||
|
|
- 未运行真实 MySQL 迁移。
|
|||
|
|
- Jenkins 中的 Git、Config 签名凭据以及生产主机运行环境变量必须由有权限的维护者配置后，才能进行生产发布。
|
