# 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` | | 上传符号包 | `Authorization: Bearer ` | `CRASH_SYMBOL_TOKEN` | | 查询/下载崩溃报告原始文件 | `Authorization: Bearer ` | `CRASH_ADMIN_TOKEN` | | `CRASH_ADMIN_TOKEN` 为空时查询/下载 | `Authorization: Bearer ` | `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 再试。