系统日志 API

本节介绍了用于管理和检索系统事件日志的 API 接口。这些接口需要管理员权限。

管理员接口 (需要登录鉴权)

获取日志列表

获取分页的系统日志列表。

接口地址: GET /api/admin/logs

查询参数:

  • page (可选): 需要获取的页码。默认值为 1。
  • pageSize (可选): 每页显示的日志数量。默认值为 50。
  • search (可选): 按请求编号、错误信息或路径搜索日志的 message 与 details,最多 200 字符;分页与总数按筛选结果计算。page 最小为 1,pageSize 限制为 1–100。

响应示例:

{
  "logs": [
    {
      "id": 1,
      "level": "error",
      "message": "Payment gateway timeout",
      "details": "{\"error\": \"Connection refused\", \"gateway\": \"stripe\"}",
      "source": "payment",
      "createdAt": "2024-01-01T12:00:00.000Z"
    }
  ],
  "total": 150,
  "page": 1,
  "pageSize": 50
}

定位 HTTP 5xx 与运行时异常

每个请求会获得服务端生成的 x-request-id 响应头。错误 JSON 同时包含 requestId;当 data 为对象时也带上编号,并保留原有业务错误字段。5xx 的 message 附带 [requestId],现有 API 报错提示即可显示编号。生产环境的未处理异常和 fatal 错误仍使用脱敏提示。HTML 500/503 页面展示可复制的请求编号、路径和构建版本,开发环境额外展示错误栈。

进入后台 → 日志 → 系统日志搜索编号,或请求 GET /api/admin/logs?search=<requestId>。HTTP 5xx 的来源为 http-error,没有 HTTP 上下文的异常来源为 runtime-error。详情包含 UTC 时间、构建编号、方法、路径、状态、耗时、可获取的用户编号、错误栈与有深度限制的原因链;详情弹窗将栈和各层原因分行展示。复用已有日志表和管理员权限,无需数据库迁移。

同一记录也输出到服务端控制台([api-error]),Node 部署另写入 ${APAY_DATA_DIR:-.data}/logs/api-errors.jsonl,超过 5 MiB 时滚动保留近期记录。文件写入是异步的,磁盘繁忙时不会卡住其他请求。页面 404(非 /api 路径,多为爬虫探测)不记录,API 的 404 仍然记录。先写控制台/文件,再写数据库,因此数据库故障本身仍有证据。Edge 部署使用平台控制台日志,不依赖本地文件。记录不读取请求体、Cookie、请求头或 query;错误文本中的 URL 凭据和 query、SQL 参数行及常见凭据赋值会脱敏,其余诊断内容仍仅供管理员查看。

服务端构建保留源码映射,打包部署时须保留服务端 .map 文件。Node 使用 node --enable-source-maps .output/server/index.mjs 启动,或在 NODE_OPTIONS 追加 --enable-source-maps,才能覆盖错误插件初始化之前已加载的模块;插件内的启用逻辑为后续加载模块提供兜底。Node 源码映射说明。客户端源码映射仍关闭。日志写入失败不改变原请求结果;回滚只需回退代码,不涉及数据迁移或业务重试。插件初始化前的导入/启动失败、业务代码内部吞掉的异常仍需查进程/平台日志。仅发生在浏览器内的异常会在开发控制台可见,目前不会上传到服务端。

删除指定日志

通过日志 ID 永久删除一条日志记录。

接口地址: DELETE /api/admin/logs/:id

响应示例:

{
  "success": true
}

清空所有日志

永久删除所有系统日志。

接口地址: DELETE /api/admin/logs/clear

响应示例:

{
  "success": true,
  "message": "All logs cleared successfully"
}