Files
persionalBrand/docs/adr/0035-admin-client-error-throttling.md
T

2.0 KiB
Raw Blame History

0035 Admin 客户端异常上报的进程内去重与限流

  • 状态:已采纳
  • 日期:2026-10-23

Context

Admin 渲染异常上报 POST /admin/client-errors 需要防止两类问题:

  • 同一次渲染错误在多个组件或重试中重复上报,制造日志噪音。
  • 单账号在错误循环中高频上报,拖垮日志与请求处理。

当前生产为单实例 PM2(deploy/ecosystem.config.cjs),没有共享缓存或消息队列。引入 Redis 会增加部署依赖,而当前流量与实例数量都不需要。

Decision

  1. 使用进程内 Map 完成两件事:
    • 去重:subject + errorId 在 10 分钟内只记录一次。
    • 限流:同一 subject 每分钟最多 10 次,超出返回 429。
  2. 去重表最多 500 条,按插入顺序淘汰最旧记录;限流窗口每分钟清理。
  3. 该状态不持久化,进程重启后清零。
  4. 只有通过 requireBrand 认证的管理员才能上报,避免匿名刷量。

Alternatives

  • 直接引入 Redis:增加部署与可用性依赖,当前单实例没有收益,推迟。
  • 不做限流:错误循环会持续写日志,并放大客户端重试,拒绝。
  • 记录到数据库:异常上报是诊断辅助数据,写入数据库会让故障时的数据库压力更大,拒绝。

Consequences

  • 单实例下行为确定,无需额外基础设施。
  • 多实例部署时每个实例各自计数,实际限流值是 实例数 × 10/分钟,去重也只在本实例生效。
  • 进程重启会丢失去重窗口,可能重复记录少量错误。

Migration plan

  1. 当前保持进程内实现,代码注释已说明单实例前提。
  2. 出现以下任一条件时迁移到共享存储(Redis 或数据库):
    • API 扩展到多实例;
    • 单账号错误上报量在正常故障场景下超过 10 次/分钟;
    • 需要跨实例聚合错误统计。
  3. 迁移时保留当前接口与响应形状,仅替换存储实现,并补充并发与过期测试。