feat: 支持多实例客户端异常限流

This commit is contained in:
que01 committed 2026-10-23 12:57:06 +08:00
1 parent 4cd3749806
commit 2fe108d66a
18 files changed
+432 -90

No files matched your search

+26 -19
View File
@@ -1,4 +1,4 @@
# 0035 Admin 客户端异常上报的进程内去重与限流
# 0035 Admin 客户端异常上报的去重与限流
- 状态:已采纳
- 日期:2026-10-23
@@ -10,34 +10,41 @@ Admin 渲染异常上报 `POST /admin/client-errors` 需要防止两类问题:
- 同一次渲染错误在多个组件或重试中重复上报,制造日志噪音。
- 单账号在错误循环中高频上报,拖垮日志与请求处理。
当前生产为单实例 PM2(`deploy/ecosystem.config.cjs`),没有共享缓存或消息队列。引入 Redis 会增加部署依赖,而当前流量与实例数量都不需要。
生产 PM2 当前保持单实例(`deploy/ecosystem.config.cjs`),因此默认不需要额外基础设施。但当 API 扩展为多实例时,进程内窗口会让实际限流值按实例数放大,跨实例去重也会失效。
## Decision
1. 使用进程内 `Map` 完成两件事:
- 去重:`subject + errorId` 在 10 分钟内只记录一次。
- 限流:同一 `subject` 每分钟最多 10 次,超出返回 429。
2. 去重表最多 500 条,按插入顺序淘汰最旧记录;限流窗口每分钟清理。
3. 该状态不持久化,进程重启后清零。
4. 只有通过 `requireBrand` 认证的管理员才能上报,避免匿名刷量。
1. 提供两种 `ClientErrorThrottleStore` 实现,由 `CLIENT_ERROR_THROTTLE_STORE` 选择:
- `memory`(默认):适合当前单实例 PM2,使用进程内 `Map`。
- `postgres`:适合多实例,使用数据库共享去重与限流状态。
2. 两种实现使用一致语义:
- 去重:`subject + errorId` 在 10 分钟内只接受一次。
- 限流:同一 `subject` 每分钟最多接受 10 条不同错误,超出返回 429。
3. Postgres 实现使用两张表:
- `ClientErrorDedupe` 通过 `(subject, errorId)` 唯一约束去重,并用条件 UPSERT 刷新过期记录。
- `ClientErrorThrottleWindow` 按 `subject` 单行保存当前窗口,使用原子 UPSERT 累加计数。
- 去重与限流在同一事务内完成,限流拒绝会回滚去重标记,避免客户端重试同一 `errorId` 时被误判为已记录。
4. 过期去重记录与旧限流窗口每分钟最多清理一次,清理失败只记录警告,不影响诊断上报。
5. 只有通过 `requireBrand` 认证的管理员才能上报,避免匿名刷量。未知的 `CLIENT_ERROR_THROTTLE_STORE` 值必须在启动时失败。
## Alternatives
- 直接引入 Redis:增加部署与可用性依赖,当前单实例没有收益,推迟。
- 只保留进程内实现:多实例下计数与去重不准确,拒绝作为唯一方案。
- 直接引入 Redis:增加部署与可用性依赖;当已经有 Postgres 时,数据库方案成本更低。
- 不做限流:错误循环会持续写日志,并放大客户端重试,拒绝。
- 记录到数据库:异常上报是诊断辅助数据,写入数据库会让故障时的数据库压力更大,拒绝。
- 把错误详情写入数据库:异常上报是诊断辅助数据,故障时不应继续给数据库增加业务写入压力;数据库只保存短期限流状态。
## Consequences
- 单实例下行为确定,无需额外基础设施。
- 多实例部署时每个实例各自计数,实际限流值是 `实例数 × 10/分钟`,去重也只在本实例生效。
- 进程重启会丢失去重窗口,可能重复记录少量错误。
- 默认 `memory` 模式保持现有单实例部署的零额外依赖和低延迟。
- 多实例部署必须显式设置 `CLIENT_ERROR_THROTTLE_STORE=postgres`;只把 PM2 调成 cluster 模式而不切换存储,会重新引入按实例放大的问题。
- Postgres 模式每个接受的上报会增加少量事务写入,但只有已被放行的错误才会进入日志记录路径。
- 进程重启会清空 `memory` 模式的状态;`postgres` 模式在重启后仍能保持窗口。
- `memory` 模式使用滑动窗口;`postgres` 模式按自然分钟切分,边界附近可能出现短时双倍突发。这是诊断上报可接受的取舍。
## Migration plan
1. 当前保持进程内实现,代码注释已说明单实例前提。
2. 出现以下任一条件时迁移到共享存储(Redis 或数据库):
- API 扩展到多实例;
- 单账号错误上报量在正常故障场景下超过 10 次/分钟;
- 需要跨实例聚合错误统计。
3. 迁移时保留当前接口与响应形状,仅替换存储实现,并补充并发与过期测试。
1. 当前单实例 PM2 继续使用默认 `memory` 模式。
2. 扩展 API 实例数前,先执行 `20261023130000_add_client_error_throttle` 迁移,并设置 `CLIENT_ERROR_THROTTLE_STORE=postgres`。
3. 验证多实例下同一 `errorId` 只记录一次,且单账号跨实例超过 10 条/分钟返回 429。
4. 如需 Redis 或消息队列,保留 `ClientErrorThrottleStore` 接口与响应形状,仅替换工厂实现并补充并发与过期测试。
+2
View File
@@ -88,6 +88,8 @@ SEED_ADMIN_PASSWORD=<first-boot-admin-password>
`DATABASE_URL` 使用最小权限数据库账号。`SESSION_SECRET` 不能复用示例值或开发值。`DEFAULT_BRAND_ID` 供未携带 `brandSlug` 的公共请求使用,缺失时 API 返回 503,不会回退到硬编码品牌。
`CLIENT_ERROR_THROTTLE_STORE` 默认为 `memory`,与当前 PM2 单实例模式匹配。扩展到多实例前必须先执行数据库迁移并改为 `postgres`,否则每个实例会各自限流与去重,实际阈值会被实例数量放大。
`CORS_ORIGINS` 默认为空并关闭跨域访问;只有 Admin 或预览应用从其他 origin 调用 API 时,才配置逗号分隔的 HTTPS origin allow-list。
本次部署会为管理员账号引入 `tokenVersion`。既有 admin token 会因缺少当前版本号而失效,管理员需要重新登录;之后修改密码会立即撤销同一账号的旧 token。媒体上传使用 S3 兼容对象存储和预签名直传,生产环境必须配置独立的 `OBJECT_STORAGE_PUBLIC_URL`、最小权限访问密钥和专用 bucket。微信相关变量只在启用对应能力时配置,同样不能提交真实凭据。