3.3 KiB
3.3 KiB
0035 Admin 客户端异常上报的去重与限流
- 状态:已采纳
- 日期:2026-10-23
Context
Admin 渲染异常上报 POST /admin/client-errors 需要防止两类问题:
- 同一次渲染错误在多个组件或重试中重复上报,制造日志噪音。
- 单账号在错误循环中高频上报,拖垮日志与请求处理。
生产 PM2 当前保持单实例(deploy/ecosystem.config.cjs),因此默认不需要额外基础设施。但当 API 扩展为多实例时,进程内窗口会让实际限流值按实例数放大,跨实例去重也会失效。
Decision
- 提供两种
ClientErrorThrottleStore实现,由CLIENT_ERROR_THROTTLE_STORE选择:memory(默认):适合当前单实例 PM2,使用进程内Map。postgres:适合多实例,使用数据库共享去重与限流状态。
- 两种实现使用一致语义:
- 去重:
subject + errorId在 10 分钟内只接受一次。 - 限流:同一
subject每分钟最多接受 10 条不同错误,超出返回 429。
- 去重:
- Postgres 实现使用两张表:
ClientErrorDedupe通过(subject, errorId)唯一约束去重,并用条件 UPSERT 刷新过期记录。ClientErrorThrottleWindow按subject单行保存当前窗口,使用原子 UPSERT 累加计数。- 去重与限流在同一事务内完成,限流拒绝会回滚去重标记,避免客户端重试同一
errorId时被误判为已记录。
- 过期去重记录与旧限流窗口每分钟最多清理一次,清理失败只记录警告,不影响诊断上报。
- 只有通过
requireBrand认证的管理员才能上报,避免匿名刷量。未知的CLIENT_ERROR_THROTTLE_STORE值必须在启动时失败。
Alternatives
- 只保留进程内实现:多实例下计数与去重不准确,拒绝作为唯一方案。
- 直接引入 Redis:增加部署与可用性依赖;当已经有 Postgres 时,数据库方案成本更低。
- 不做限流:错误循环会持续写日志,并放大客户端重试,拒绝。
- 把错误详情写入数据库:异常上报是诊断辅助数据,故障时不应继续给数据库增加业务写入压力;数据库只保存短期限流状态。
Consequences
- 默认
memory模式保持现有单实例部署的零额外依赖和低延迟。 - 多实例部署必须显式设置
CLIENT_ERROR_THROTTLE_STORE=postgres;只把 PM2 调成 cluster 模式而不切换存储,会重新引入按实例放大的问题。 - Postgres 模式每个接受的上报会增加少量事务写入,但只有已被放行的错误才会进入日志记录路径。
- 进程重启会清空
memory模式的状态;postgres模式在重启后仍能保持窗口。 memory模式使用滑动窗口;postgres模式按自然分钟切分,边界附近可能出现短时双倍突发。这是诊断上报可接受的取舍。
Migration plan
- 当前单实例 PM2 继续使用默认
memory模式。 - 扩展 API 实例数前,先执行
20261023130000_add_client_error_throttle迁移,并设置CLIENT_ERROR_THROTTLE_STORE=postgres。 - 验证多实例下同一
errorId只记录一次,且单账号跨实例超过 10 条/分钟返回 429。 - 如需 Redis 或消息队列,保留
ClientErrorThrottleStore接口与响应形状,仅替换工厂实现并补充并发与过期测试。