feat(admin): 增加崩溃报告联调信息展示
This commit is contained in:
@@ -0,0 +1,303 @@
|
||||
# SimCAE 崩溃报告接口联调说明
|
||||
|
||||
本文说明崩溃报告后端接口怎么测试，以及 curl 示例里的 `dev-token` 应该替换成什么。
|
||||
|
||||
## 一、先搞清楚三个 Token
|
||||
|
||||
curl 示例里的：
|
||||
|
||||
```text
|
||||
Authorization: Bearer dev-token
|
||||
```
|
||||
|
||||
这里的 `dev-token` 只是占位符，不是固定值。实际要按接口用途替换成服务端 `.env` / `.env.docker.example` 里的 token。
|
||||
|
||||
| 使用场景 | 请求头里填什么 | 服务端配置字段 |
|
||||
| --- | --- | --- |
|
||||
| 客户端上传崩溃报告 | `Authorization: Bearer <CRASH_REPORT_TOKEN>` | `CRASH_REPORT_TOKEN` |
|
||||
| 上传符号包 | `Authorization: Bearer <CRASH_SYMBOL_TOKEN>` | `CRASH_SYMBOL_TOKEN` |
|
||||
| 查询/下载崩溃报告原始文件 | `Authorization: Bearer <CRASH_ADMIN_TOKEN>` | `CRASH_ADMIN_TOKEN` |
|
||||
| `CRASH_ADMIN_TOKEN` 为空时查询/下载 | `Authorization: Bearer <ADMIN_TOKEN>` | `ADMIN_TOKEN` |
|
||||
|
||||
当前默认配置通常是：
|
||||
|
||||
```env
|
||||
CRASH_REPORT_TOKEN=SimCAECrashReportToken2026
|
||||
CRASH_SYMBOL_TOKEN=SimCAESymbolToken2026
|
||||
CRASH_ADMIN_TOKEN=
|
||||
ADMIN_TOKEN=SimCAEAdminToken2026
|
||||
```
|
||||
|
||||
所以，如果使用默认配置：
|
||||
|
||||
- 上传崩溃报告用 `SimCAECrashReportToken2026`。
|
||||
- 上传符号包用 `SimCAESymbolToken2026`。
|
||||
- 查询/下载崩溃报告时，因为 `CRASH_ADMIN_TOKEN` 为空，所以用 `SimCAEAdminToken2026`。
|
||||
|
||||
管理后台“客户端配置生成”区域下方也会显示“崩溃报告接口联调信息”。这部分只给管理员或测试人员查看，不会复制进客户端 `app_config.json`，也不要手动放进客户端配置文件。
|
||||
|
||||
其中会以类似 `.env` 的形式把 `CRASH_REPORT_TOKEN`、`CRASH_SYMBOL_TOKEN`、`CRASH_ADMIN_TOKEN`、`ADMIN_TOKEN` 单独列出来，并在每个字段前加中文说明。`CRASH_ADMIN_TOKEN` 如果为空，查询和下载崩溃报告时就使用 `ADMIN_TOKEN`。
|
||||
|
||||
## 二、接口地址
|
||||
|
||||
假设服务端地址是：
|
||||
|
||||
```text
|
||||
http://192.168.1.158:8000
|
||||
```
|
||||
|
||||
下面示例里用变量表示：
|
||||
|
||||
```bash
|
||||
SERVER=http://192.168.1.158:8000
|
||||
REPORT_TOKEN=SimCAECrashReportToken2026
|
||||
SYMBOL_TOKEN=SimCAESymbolToken2026
|
||||
ADMIN_TOKEN=SimCAEAdminToken2026
|
||||
```
|
||||
|
||||
如果部署了 HTTPS 或域名，把 `SERVER` 改成实际地址即可。
|
||||
|
||||
## 三、健康检查
|
||||
|
||||
健康检查不需要 token：
|
||||
|
||||
```bash
|
||||
curl "$SERVER/api/v1/health"
|
||||
```
|
||||
|
||||
正常返回类似：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"service": "simcae-crash-server",
|
||||
"version": "1.0.0",
|
||||
"timeUtc": "2026-07-14T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 四、准备测试文件
|
||||
|
||||
创建一个假的 minidump 文件：
|
||||
|
||||
```bash
|
||||
printf "dummy minidump for api test\n" > crash.dmp
|
||||
```
|
||||
|
||||
附件是可选的。需要测试附件时可以准备一个 zip：
|
||||
|
||||
```bash
|
||||
mkdir -p attachments
|
||||
printf "extra log\n" > attachments/runtime.log
|
||||
zip -r attachments.zip attachments
|
||||
```
|
||||
|
||||
如果服务器上没有 `zip`，可以先不传 `attachments` 字段。
|
||||
|
||||
## 五、准备 metadata.json
|
||||
|
||||
`clientReportId` 必须是 UUID，并且请求头 `Idempotency-Key` 必须和它完全一致。
|
||||
|
||||
最小可用示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"clientReportId": "8f6c5ed9-9a2b-4ef1-89a2-8843f2f7d9d1",
|
||||
"crashTimeUtc": "2026-07-14T08:30:00Z",
|
||||
"product": "SIMCAE",
|
||||
"appVersion": "0.10.3",
|
||||
"gitCommit": "unknown",
|
||||
"buildType": "Release",
|
||||
"channel": "stable",
|
||||
"platform": {
|
||||
"os": "Windows",
|
||||
"arch": "x64"
|
||||
},
|
||||
"crash": {
|
||||
"exceptionCode": "0xC0000005",
|
||||
"threadId": 1
|
||||
},
|
||||
"userConsent": {
|
||||
"uploadAllowed": true
|
||||
},
|
||||
"files": []
|
||||
}
|
||||
```
|
||||
|
||||
保存成 `metadata.json`。
|
||||
|
||||
说明：
|
||||
|
||||
- `product` 必须是 `SIMCAE`。
|
||||
- `schemaVersion` 必须是数字 `1`。
|
||||
- `files` 必须是数组，可以先填空数组。
|
||||
- 如果 `files` 里声明了 `minidump` 的 `sha256`，服务端会校验它必须和实际上传的 `crash.dmp` 一致。
|
||||
|
||||
## 六、上传崩溃报告
|
||||
|
||||
不带附件的最小上传：
|
||||
|
||||
```bash
|
||||
curl -X POST "$SERVER/api/v1/crash-reports" \
|
||||
-H "Authorization: Bearer $REPORT_TOKEN" \
|
||||
-H "Idempotency-Key: 8f6c5ed9-9a2b-4ef1-89a2-8843f2f7d9d1" \
|
||||
-H "X-SimCAE-Client: SIMCAE" \
|
||||
-H "X-SimCAE-Version: 0.10.3" \
|
||||
-F "metadata=@metadata.json;type=application/json" \
|
||||
-F "minidump=@crash.dmp;type=application/octet-stream"
|
||||
```
|
||||
|
||||
带附件上传：
|
||||
|
||||
```bash
|
||||
curl -X POST "$SERVER/api/v1/crash-reports" \
|
||||
-H "Authorization: Bearer $REPORT_TOKEN" \
|
||||
-H "Idempotency-Key: 8f6c5ed9-9a2b-4ef1-89a2-8843f2f7d9d1" \
|
||||
-H "X-SimCAE-Client: SIMCAE" \
|
||||
-H "X-SimCAE-Version: 0.10.3" \
|
||||
-F "metadata=@metadata.json;type=application/json" \
|
||||
-F "minidump=@crash.dmp;type=application/octet-stream" \
|
||||
-F "attachments=@attachments.zip;type=application/zip"
|
||||
```
|
||||
|
||||
正常首次上传返回 HTTP 201，类似：
|
||||
|
||||
```json
|
||||
{
|
||||
"reportId": "srv_xxxxxxxxxxxxxxxxxxxxxxxx",
|
||||
"duplicate": false,
|
||||
"status": "stored",
|
||||
"acceptedAtUtc": "2026-07-14T08:31:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
如果用同一个 `clientReportId` 和相同内容重复上传，会返回 HTTP 200，并且：
|
||||
|
||||
```json
|
||||
{
|
||||
"duplicate": true
|
||||
}
|
||||
```
|
||||
|
||||
如果同一个 `clientReportId` 但内容变了，会返回 HTTP 409，表示幂等冲突。
|
||||
|
||||
## 七、查询崩溃报告详情
|
||||
|
||||
把上传返回的 `reportId` 填到下面命令里：
|
||||
|
||||
```bash
|
||||
REPORT_ID=srv_xxxxxxxxxxxxxxxxxxxxxxxx
|
||||
|
||||
curl "$SERVER/api/v1/crash-reports/$REPORT_ID" \
|
||||
-H "Authorization: Bearer $ADMIN_TOKEN"
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- 这里用的是管理查询 token。
|
||||
- 如果 `.env` 里配置了 `CRASH_ADMIN_TOKEN`，就用 `CRASH_ADMIN_TOKEN`。
|
||||
- 如果 `CRASH_ADMIN_TOKEN` 为空，就用 `ADMIN_TOKEN`。
|
||||
|
||||
## 八、下载崩溃报告文件
|
||||
|
||||
可下载文件名：
|
||||
|
||||
```text
|
||||
metadata.json
|
||||
crash.dmp
|
||||
attachments.zip
|
||||
server.json
|
||||
```
|
||||
|
||||
下载 minidump：
|
||||
|
||||
```bash
|
||||
curl "$SERVER/api/v1/crash-reports/$REPORT_ID/files/crash.dmp" \
|
||||
-H "Authorization: Bearer $ADMIN_TOKEN" \
|
||||
-o crash_downloaded.dmp
|
||||
```
|
||||
|
||||
下载 metadata：
|
||||
|
||||
```bash
|
||||
curl "$SERVER/api/v1/crash-reports/$REPORT_ID/files/metadata.json" \
|
||||
-H "Authorization: Bearer $ADMIN_TOKEN" \
|
||||
-o metadata_downloaded.json
|
||||
```
|
||||
|
||||
管理后台也可以查看崩溃报告列表和下载文件。
|
||||
|
||||
## 九、上传符号包
|
||||
|
||||
符号包接口用于上传某个版本/构建对应的 symbols.zip。
|
||||
|
||||
准备 `symbols_metadata.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"product": "SIMCAE",
|
||||
"appVersion": "0.10.3",
|
||||
"gitCommit": "unknown",
|
||||
"buildType": "Release",
|
||||
"platform": "windows-x64",
|
||||
"toolchain": "msvc2019",
|
||||
"createdAtUtc": "2026-07-14T08:00:00Z",
|
||||
"files": []
|
||||
}
|
||||
```
|
||||
|
||||
准备测试符号包：
|
||||
|
||||
```bash
|
||||
mkdir -p symbols
|
||||
printf "dummy symbols\n" > symbols/readme.txt
|
||||
zip -r symbols.zip symbols
|
||||
```
|
||||
|
||||
上传：
|
||||
|
||||
```bash
|
||||
curl -X POST "$SERVER/api/v1/symbols" \
|
||||
-H "Authorization: Bearer $SYMBOL_TOKEN" \
|
||||
-F "metadata=@symbols_metadata.json;type=application/json" \
|
||||
-F "symbols=@symbols.zip;type=application/zip"
|
||||
```
|
||||
|
||||
正常返回类似：
|
||||
|
||||
```json
|
||||
{
|
||||
"symbolUploadId": "sym_xxxxxxxxxxxxxxxxxxxxxxxx",
|
||||
"status": "stored",
|
||||
"duplicate": false,
|
||||
"acceptedAtUtc": "2026-07-14T08:35:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 十、常见错误
|
||||
|
||||
1. HTTP 401 `missing bearer token`
|
||||
没有传 `Authorization: Bearer ...`，或者格式写错。
|
||||
|
||||
2. HTTP 401 `invalid bearer token`
|
||||
token 值不对。检查 `.env` 里的 `CRASH_REPORT_TOKEN`、`CRASH_SYMBOL_TOKEN`、`CRASH_ADMIN_TOKEN`、`ADMIN_TOKEN`。
|
||||
|
||||
3. HTTP 403 `token is not allowed to access this endpoint`
|
||||
token 是对的，但用错接口了。例如拿 `CRASH_REPORT_TOKEN` 去查询/下载报告。
|
||||
|
||||
4. HTTP 400 `Idempotency-Key must equal metadata.clientReportId`
|
||||
请求头 `Idempotency-Key` 必须等于 metadata 里的 `clientReportId`。
|
||||
|
||||
5. HTTP 400 `metadata.product must be SIMCAE`
|
||||
metadata 里的 `product` 必须填 `SIMCAE`。
|
||||
|
||||
6. HTTP 400 `file_hash_mismatch`
|
||||
metadata.files 里声明的 SHA-256 和实际上传文件不一致。联调初期可以先把 `files` 填成空数组。
|
||||
|
||||
7. HTTP 413 `payload_too_large`
|
||||
文件超过 `.env` 里的大小限制，例如 `CRASH_MINIDUMP_MAX_MB`、`CRASH_ATTACHMENTS_MAX_MB`、`CRASH_REQUEST_MAX_MB`。
|
||||
|
||||
8. HTTP 409 `idempotency_conflict`
|
||||
同一个 `clientReportId` 已经上传过，但这次内容不一样。换一个新的 UUID 再试。
|
||||
Reference in New Issue
Block a user