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

44 lines
2.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. 迁移时保留当前接口与响应形状,仅替换存储实现,并补充并发与过期测试。