XuqmGroup-Server/xuqm-bugcollect-service/docs/BugCollect-Backpressure.md

BugCollect 摄取防雪崩设计

目标

线上同一故障可能在短时间内由大量设备同时触发。摄取链路必须保护数据库和服务线程， 同时不能让 BugCollect 故障阻断宿主 App。

权威链路

1. SDK 本地按指纹采样和限频，批量上报最多 30 条。
2. 服务端按 appKey 统计固定窗口内的事件数，默认每分钟 6000 条。
3. 多实例部署使用 Redis Lua 原子计数；Redis 不可用时退回进程内窗口，继续保护当前实例。
4. 超限返回 HTTP 429、message=BUGCOLLECT_RATE_LIMITED 和标准 Retry-After 秒数。
5. RN/Android SDK 保留原队列，按 Retry-After 冷却，最长一小时；冷却期间不重复请求。
6. BUGCOLLECT_DISABLED 仍表示租户关闭服务，SDK 清队列并停用。它与临时限流不能混用。

配置

环境变量	默认值	说明
BUGCOLLECT_MAX_EVENTS_PER_MINUTE	6000	单个 appKey 每个窗口允许的事件数，最小 30
BUGCOLLECT_RATE_WINDOW_SECONDS	60	固定窗口长度，最小 10 秒

限流属于平台容量保护，不是租户发布配置。租户平台不向开发者暴露“上传网络建议”或 让租户关闭服务端保护。

验收

• 单批 31 条必须在 Bean Validation 阶段拒绝。
• Redis 可用时，多实例共享同一 appKey 计数。
• Redis 不可用时，单实例超过本地额度仍返回 429。
• 429 必须携带正整数 Retry-After。
• SDK 收到 429 后不得丢队列、立即重试或向宿主业务线程抛未处理异常。
• 服务关闭返回 403 BUGCOLLECT_DISABLED，行为不受限流改动影响。