311 lines
8.2 KiB
Markdown
311 lines
8.2 KiB
Markdown
# SimCAE 崩溃报告接口联调指南
|
||
|
||
本文说明崩溃报告后端接口怎么测试，以及 curl 示例里的 `dev-token` 应该替换成什么。
|
||
|
||
最快结论：
|
||
|
||
- 上传崩溃报告时，`dev-token` 替换成 `CRASH_REPORT_TOKEN` 的值。
|
||
- 上传符号包时，`dev-token` 替换成 `CRASH_SYMBOL_TOKEN` 的值。
|
||
- 查询或下载崩溃报告时，优先用 `CRASH_ADMIN_TOKEN`；如果它为空，就用 `ADMIN_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 再试。
|