From b190f2758a8dd5ca552f89678bb0202c68c31f6e Mon Sep 17 00:00:00 2001 From: que01 Date: Fri, 23 Oct 2026 12:26:53 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=E5=90=8E=E5=8F=B0?= =?UTF-8?q?=E5=AE=A2=E6=88=B7=E7=AB=AF=E5=BC=82=E5=B8=B8=E4=B8=8A=E6=8A=A5?= =?UTF-8?q?=E9=99=90=E6=B5=81=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../adr/0035-admin-client-error-throttling.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/adr/0035-admin-client-error-throttling.md diff --git a/docs/adr/0035-admin-client-error-throttling.md b/docs/adr/0035-admin-client-error-throttling.md new file mode 100644 index 0000000..66fc4c3 --- /dev/null +++ b/docs/adr/0035-admin-client-error-throttling.md @@ -0,0 +1,43 @@ +# 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. 迁移时保留当前接口与响应形状,仅替换存储实现,并补充并发与过期测试。