Build docker and publish / build (20.15.1) (push) Successful in 7m15s

Details

重构设备解绑逻辑，简化事务处理流程并移除冗余代码。将错误上报接口的详细说明从主文档拆分到单独文件，提高文档可维护性。

- 合并设备查询与认证记录查询操作
- 简化匿名用户创建流程
- 移除冗余的错误日志记录
- 将错误上报接口文档拆分到单独文件

2025-12-03 01:45:06 -08:00

4.2 KiB

Raw Blame History

客户端错误上报接口文档

接口概览

路径：POST /v1/common/log/message/report
说明：APP/PC/Web 客户端错误与异常信息上报，服务端入库 log_message 表，并提供管理端查询。
认证：无需登录；若走设备安全通道需使用 Login-Type: device 与 AES 加密。
中间件：DeviceMiddleware（当请求头 Login-Type=device 时启用加解密）。

请求

Headers：
- Content-Type: application/json
- 可选：Login-Type: device（启用设备加密通道）
Body（JSON）：
- platform string 必填，客户端平台，如 android/ios/windows/mac/web
- appVersion string 可选，应用版本，如 2.4.1
- osName string 可选，系统名称，如 Android/iOS/Windows/macOS
- osVersion string 可选，系统版本，如 14
- deviceId string 可选，设备唯一标识
- sessionId string 可选，会话标识
- level uint8 可选，日志等级：1=fatal、2=error、3=warn、4=info（默认 3）
- errorCode string 可选，业务或系统错误码
- message string 必填，错误简述（服务器将超过约 64KB 的内容截断）
- stack string 可选，堆栈信息（服务器将超过约 1MB 的内容截断）
- context object 可选，扩展上下文（如接口路径、参数、网络状态等）
- occurredAt int64 可选，客户端发生时间，毫秒时间戳
服务器侧自动填充：
- client_ip、user_agent、locale 由请求解析
- user_id 仅在鉴权后由服务端注入（本接口默认匿名）

加密通道（设备）

当使用设备安全通道时（Login-Type: device），请求体需要将原始 JSON 加密为：
- data string：AES 加密后的密文
- time string：IV/nonce（与密文配套）
服务端会自动解密为明文 JSON，再进行字段校验与入库。

响应

成功：

{
  "code": 0,
  "msg": "OK",
  "data": { "id": 123 }
}

常见错误：
- {"code":401,"msg":"TooManyRequests"} 触发速率限制（设备ID或IP维度）
- {"code":400,"msg":"InvalidParams"} 参数校验失败（缺少必填或类型不符）
- {"code":10001,"msg":"DatabaseQueryError"} 数据库操作异常

速率限制

默认按 deviceId 或 client_ip 每分钟最多约 120 条，超限即返回 TooManyRequests。

去重策略

服务端计算 digest = sha256(message|stack|errorCode|appVersion|platform) 并尝试唯一入库，重复日志可能返回已存在记录的 id。

示例

明文上报（推荐测试使用）：

curl -X POST http://localhost:8080/v1/common/log/message/report \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "android",
    "appVersion": "2.4.1",
    "osName": "Android",
    "osVersion": "14",
    "deviceId": "and-9a7f3e2c-01",
    "sessionId": "sess-73f8a2a4",
    "level": 2,
    "errorCode": "ORDER_RENEWAL_TIMEOUT",
    "message": "订单续费接口超时：/v1/public/order/renewal",
    "stack": "TimeoutException: request exceeded 8000ms\\n at HttpClient.post(HttpClient.kt:214)\\n at RenewalRepository.submit(RenewalRepository.kt:87)",
    "context": {
      "api": "/v1/public/order/renewal",
      "method": "POST",
      "endpoint": "https://api.example.com/v1/public/order/renewal",
      "httpStatus": 504,
      "responseTimeMs": 8123,
      "retryCount": 2,
      "network": { "type": "cellular", "carrier": "China Mobile" }
    },
    "occurredAt": 1733200005123
  }'

设备加密上报（示意）：

# 将原始JSON通过AES加密得到密文data与随机IV time
curl -X POST http://localhost:8080/v1/common/log/message/report \
  -H 'Content-Type: application/json' \
  -H 'Login-Type: device' \
  -d '{"data":"<aes_cipher>","time":"<iv_nonce>"}'

管理端查询（用于联调验证）

列表：GET /v1/admin/log/message/error/list（需 Authorization）
详情：GET /v1/admin/log/message/error/detail?id=...

备注

字段尽量避免携带敏感信息（密码、密钥、完整令牌等）；如需调试请截断或脱敏后上报。
建议在 APP/PC 端统一封装上报模块，包含：字段收集、级别过滤、采样策略、离线缓存与重试、速率限制配合。

4.2 KiB Raw Blame History Unescape Escape

客户端错误上报接口文档

接口概览

请求

加密通道（设备）

响应

速率限制

去重策略

示例

管理端查询（用于联调验证）

备注

4.2 KiB

Raw Blame History