nikelaluo/update-server

Fork 0

Files

T

nikelaluo d7c7eeefc7 docs: 优化服务端文档入口和部署说明

2026-07-14 09:27:34 +00:00

8.2 KiB

Raw Permalink Blame History

SimCAE 崩溃报告接口联调指南

本文说明崩溃报告后端接口怎么测试，以及 curl 示例里的 dev-token 应该替换成什么。

最快结论：

上传崩溃报告时，dev-token 替换成 CRASH_REPORT_TOKEN 的值。
上传符号包时，dev-token 替换成 CRASH_SYMBOL_TOKEN 的值。
查询或下载崩溃报告时，优先用 CRASH_ADMIN_TOKEN；如果它为空，就用 ADMIN_TOKEN。
管理后台“客户端配置生成”区域下方会显示这些联调信息，方便复制。

一、先搞清楚三个 Token

curl 示例里的：

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`

当前默认配置通常是：

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。

二、接口地址

假设服务端地址是：

http://192.168.1.158:8000

下面示例里用变量表示：

SERVER=http://192.168.1.158:8000
REPORT_TOKEN=SimCAECrashReportToken2026
SYMBOL_TOKEN=SimCAESymbolToken2026
ADMIN_TOKEN=SimCAEAdminToken2026

如果部署了 HTTPS 或域名，把 SERVER 改成实际地址即可。

三、健康检查

健康检查不需要 token：

curl "$SERVER/api/v1/health"

正常返回类似：

{
  "status": "ok",
  "service": "simcae-crash-server",
  "version": "1.0.0",
  "timeUtc": "2026-07-14T00:00:00Z"
}

四、准备测试文件

创建一个假的 minidump 文件：

printf "dummy minidump for api test\n" > crash.dmp

附件是可选的。需要测试附件时可以准备一个 zip：

mkdir -p attachments
printf "extra log\n" > attachments/runtime.log
zip -r attachments.zip attachments

如果服务器上没有 zip，可以先不传 attachments 字段。

五、准备 metadata.json

clientReportId 必须是 UUID，并且请求头 Idempotency-Key 必须和它完全一致。

最小可用示例：

{
  "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 一致。

六、上传崩溃报告

不带附件的最小上传：

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"

带附件上传：

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，类似：

{
  "reportId": "srv_xxxxxxxxxxxxxxxxxxxxxxxx",
  "duplicate": false,
  "status": "stored",
  "acceptedAtUtc": "2026-07-14T08:31:00Z"
}

如果用同一个 clientReportId 和相同内容重复上传，会返回 HTTP 200，并且：

{
  "duplicate": true
}

如果同一个 clientReportId 但内容变了，会返回 HTTP 409，表示幂等冲突。

七、查询崩溃报告详情

把上传返回的 reportId 填到下面命令里：

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。

八、下载崩溃报告文件

可下载文件名：

metadata.json
crash.dmp
attachments.zip
server.json

下载 minidump：

curl "$SERVER/api/v1/crash-reports/$REPORT_ID/files/crash.dmp" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -o crash_downloaded.dmp

下载 metadata：

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：

{
  "schemaVersion": 1,
  "product": "SIMCAE",
  "appVersion": "0.10.3",
  "gitCommit": "unknown",
  "buildType": "Release",
  "platform": "windows-x64",
  "toolchain": "msvc2019",
  "createdAtUtc": "2026-07-14T08:00:00Z",
  "files": []
}

准备测试符号包：

mkdir -p symbols
printf "dummy symbols\n" > symbols/readme.txt
zip -r symbols.zip symbols

上传：

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"