日志管理系统

系统说明

公共接口统一使用 JSON body。写入和查询接口都需要 AppID、时间戳、nonce、payload 和 signature；健康检查接口不需要签名。

单条、批量和 WebSocket 写入都会同步落库。公共日志列表接口只返回当前 AppID 对应应用自己的日志，跨项目和跨应用查询请使用管理后台。

健康检查

返回格式

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "ok",
    "service": "log-manager-api",
    "checked_at": "2026-07-01T13:00:00Z",
    "dependencies": {
      "database": "ok",
      "redis": "ok",
      "nats": "connected"
    }
  }
}

日志写入

请求格式

{
  "appid": "lm_zhibao_admin",
  "timestamp": 1782871200,
  "nonce": "unique-random-value",
  "payload": "{\"level\":\"error\",\"message\":\"接口请求失败\",\"module\":\"admin-api\",\"trace_id\":\"trace-001\",\"request_id\":\"req-001\",\"tags\":{\"env\":\"test\"},\"context\":{\"duration_ms\":860}}",
  "signature": "base64-hmac-sha256"
}

payload 字段

• level：日志等级，支持 debug、warning、error、fatal。
• message：日志内容，必填。
• module：业务模块，可选。
• trace_id / request_id：链路追踪字段，可选。
• tags / context：JSON 对象，用于保存扩展标签和上下文。
• occurred_at：日志发生时间，ISO8601 格式；不传时使用服务端接收时间。

成功返回

{
  "code": 0,
  "message": "ok",
  "data": {
    "log_id": "884a6d94-5d8c-46dd-a121-6758f25f699b",
    "received_at": "2026-07-01T13:00:00Z"
  }
}

批量写入

适合服务端本地队列、缓冲区或定时 flush 场景。单次最多写入 100 条日志。

请求格式

{
  "appid": "lm_zhibao_admin",
  "timestamp": 1782871200,
  "nonce": "unique-random-value",
  "payload": "{\"items\":[{\"level\":\"error\",\"message\":\"接口请求失败\"},{\"level\":\"warning\",\"message\":\"队列积压\"}]}",
  "signature": "base64-hmac-sha256"
}

成功返回

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "log_id": "884a6d94-5d8c-46dd-a121-6758f25f699b",
        "received_at": "2026-07-01T13:00:00Z"
      }
    ],
    "count": 1
  }
}

WebSocket 写入

适合服务端到服务端的长连接写入。连接建立后第一条消息必须认证，认证成功后可连续发送单条或批量日志。

认证消息

{
  "type": "auth",
  "appid": "lm_zhibao_admin",
  "timestamp": 1782871200,
  "nonce": "unique-random-value",
  "signature": "base64-hmac-sha256"
}

认证签名 payload 固定为 ws-auth。

单条日志消息

{
  "type": "log",
  "payload": {
    "level": "error",
    "message": "接口请求失败",
    "module": "admin-api"
  }
}

批量日志消息

{
  "type": "logs",
  "items": [
    { "level": "error", "message": "接口请求失败" },
    { "level": "warning", "message": "队列积压" }
  ]
}

日志列表

请求格式

{
  "appid": "lm_zhibao_admin",
  "timestamp": 1782871200,
  "nonce": "unique-random-value",
  "payload": "{\"page\":1,\"page_size\":20,\"level\":\"error\",\"keyword\":\"接口\"}",
  "signature": "base64-hmac-sha256"
}

payload 字段

• page：页码，默认 1。
• page_size：每页条数，默认 20，最大 100。
• level、module、trace_id、request_id：精确筛选字段，可选。
• keyword：按日志内容模糊查询，可选。
• start_time / end_time：按日志发生时间过滤，可选。

返回格式

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [],
    "total": 128,
    "page": 1,
    "page_size": 20,
    "total_pages": 7
  }
}

SDK 接入

仓库内已提供 Rust、Go、TypeScript 和 Dart SDK，统一封装签名、nonce、HTTP 写入、批量写入、列表查询和 WebSocket 认证连接。

• sdks/rust：服务端 Rust 项目使用。
• sdks/go：服务端 Go 项目使用。
• sdks/ts：Vue/TypeScript 项目使用。公开网页不要直接保存生产 AppKey。
• sdks/dart：Flutter/Dart 项目使用。移动端不要直接内置生产 AppKey。

TypeScript 示例

const client = new LogManagerClient({
  baseUrl: 'https://log.yunxuanwl.cn/api/v1',
  appid,
  appkey,
})

await client.writeLog({
  level: 'error',
  message: '接口请求失败',
  module: 'admin-api',
})

Go 示例

client := logmanager.New("https://log.yunxuanwl.cn/api/v1", appid, appkey)
_, err := client.WriteLog(ctx, logmanager.LogPayload{
    Level: "error",
    Message: "接口请求失败",
    Module: "admin-api",
})

生产 AppKey 只应保存在服务端安全配置中。前端、H5、移动端如需上报日志，建议先上报到业务后端，再由业务后端转发到日志 API。

SDK 下载

以下压缩包可直接下载使用。压缩包已排除构建缓存、依赖目录和临时文件；校验文件为 sha256sums.txt。

• Rust SDK
• Go SDK
• TypeScript SDK
• Dart / Flutter SDK
• 全部 SDK 打包
• SHA256 校验文件

MessagePack 优化

JSON 接口保持兼容；高频写入场景可使用 MessagePack 可选端点减少传输体积，WebSocket 也支持二进制 MessagePack 帧。

• POST https://log.yunxuanwl.cn/api/v1/logs/write-msgpack
• POST https://log.yunxuanwl.cn/api/v1/logs/batch-msgpack
• POST https://log.yunxuanwl.cn/api/v1/logs/list-msgpack
• wss://log.yunxuanwl.cn/api/v1/logs/ws：文本帧为 JSON，二进制帧为 MessagePack。

MessagePack 签名原文中的 payload 使用 msgpack:<base64(payload bytes)>，其他字段与 JSON 签名一致。

签名规则

签名原文为：appid + "\n" + timestamp + "\n" + nonce + "\n" + payload。使用应用 AppKey 计算 HMAC-SHA256，再做 Base64 编码。

同一个 appid + nonce 在 5 分钟内只能使用一次；请求时间戳允许误差为 5 分钟。

错误码

{
  "code": 401,
  "message": "签名校验失败"
}

• 400：请求格式错误、payload 非法、日志等级不合法。
• 401：应用不存在、签名错误、时间戳过期、nonce 重复。
• 403：项目或应用被禁用、IP 不在白名单。
• 500：数据库、缓存、消息队列或服务内部错误。

性能测试结果

以下数据为 2026-07-01 通过公网域名 https://log.yunxuanwl.cn 连续请求 20 次的实测结果。

接口                 样本数  平均耗时   最小耗时   最大耗时   p95
健康检查             20      89.31ms   75.74ms   100.02ms  97.21ms
日志写入             20      86.29ms   71.75ms   110.67ms  93.20ms
日志列表             20      94.67ms   82.06ms   107.21ms  105.69ms

测试说明：写入接口每次生成唯一 nonce 并真实落库；列表接口按默认分页查询最近 20 条当前应用日志。

商务合作与产品咨询

如果您希望接入统一日志能力，或就企业日志治理、产品合作与技术支持进行咨询，欢迎联系我们。