147 行
7.0 KiB
Markdown
147 行
7.0 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 构建均通过。最终结果以当前任务交接记录为准。
|
||
|
||
## 尚未执行
|
||
|
||
- 未运行真实 MySQL 迁移。
|
||
- 本批 Server 变更仅执行 development 验证，未构建或部署生产镜像。
|
||
|
||
## 2026-07-27 Jenkins SCM 凭据收口
|
||
|
||
- Server 流水线的显式 checkout 已改用 Gitea SSH URL 和 Jenkins
|
||
`jenkins-ssh-key`，不再引用未配置的 `XUQM_GIT_CREDENTIALS`，也不允许在 URL
|
||
中嵌入用户名、密码或访问令牌。生产版本回写的 pull/push 同样放入
|
||
`sshagent(jenkins-ssh-key)`，不依赖 checkout 步骤的临时认证环境。
|
||
- 该修改尚未通过下一次 Server Jenkins 构建验证；触发部署前应先执行一次只构建不
|
||
部署的流水线或确认 checkout 阶段成功。
|
||
- 首次仓库流水线验证 `xuqmgroup-tenant-service #95` 已证明 SSH checkout 成功，
|
||
但 Windows 节点没有全局 `mvn`。仓库已引入 Apache Maven Wrapper 3.3.4
|
||
`only-script`，固定 Maven 3.9.16 及官方发行包 SHA-256；Jenkins 统一调用
|
||
`mvnw.cmd -B test`，不再依赖节点手工安装 Maven。
|
||
- 本地已使用 Wrapper 完成全部 10 个 Maven 模块的 `./mvnw -B test`，构建成功。
|
||
同时修正 `UpdatePublishConfigClientContextTest`：测试上下文显式使用 Spring Boot
|
||
转换服务和 `RestTemplateBuilder` 的正式构造参数，避免把测试容器缺失的默认
|
||
Bean/类型转换能力误判为生产构造器故障。
|
||
- `xuqmgroup-tenant-service #96` 已在 Windows Jenkins 使用 Wrapper 完成 10 模块测试，
|
||
但同时确认 Declarative Pipeline 的 stage `input` 默认早于 `when` 执行，导致
|
||
development 构建仍等待生产确认。`Confirm Production` 已增加
|
||
`beforeInput true`。
|
||
- `xuqmgroup-tenant-service #97` 已通过：development 模式完成全部 10 模块测试后
|
||
直接成功结束，未出现生产确认、镜像构建、部署或版本提交 stage。
|
||
- `xuqmgroup-tenant-service #98` 已通过：在删除数据库重置流程最后一处
|
||
`app_licenses` 保留规则后，再次完成全部 10 模块测试；production 相关 stage
|
||
全部按条件跳过。
|
