wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M0-05 Traffic Protection & Resilience 基础版 #5

New Issue
Open
opened 2026-05-22 21:00:15 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:15 +08:00
Owner
Copy Link

目标

设计知习后端流量保护与韧性模块，为全系统提供限流、超时控制和基础熔断能力，防止单点过载拖垮整体服务。

本 Issue 只做架构设计，不直接实现代码。

背景说明

知习后端对外暴露 CAPI 和 AAPI 两类接口，对内还有 IAPI 内部接口。AI 调用是高成本操作，登录接口是暴力破解攻击面，文件上传是带宽消耗大户。如果没有任何保护措施，恶意请求或突发流量可能耗尽服务器资源。

Traffic Protection 模块负责在请求进入业务逻辑之前进行流量控制，与 Quota 模块的区别在于：Quota 管"你有没有额度"，Traffic Protection 管"系统现在能不能承受"。

模块职责

  1. 本模块负责：

    • 全局 API 限流（基于 @nestjs/throttler）
    • 登录接口限流（防暴力破解）
    • AI 接口限流（控制成本）
    • 文件上传接口限流
    • 单用户/IP 级别限流
    • 超时控制（全局请求超时、AI 调用超时）
    • 基础降级策略（超时后返回什么）

  2. 本模块不负责：

    • 用户额度管理（走 Quota Module）
    • AI 模型级别的降级路由（走 AI Gateway）
    • 服务器资源监控（走 Server Monitor）
    • 业务逻辑层面的错误处理（走 GlobalExceptionFilter）

基础设施依赖判断

  • MySQL：需判断（限流规则存储）
  • Redis：是（限流计数器、滑动窗口）
  • BullMQ：否
  • Qdrant：否
  • AI Gateway：否（但需要与 AI Gateway 协作定义限流级别）
  • COS：否
  • Content Safety：否

接口设计

  1. Guard / Interceptor（无传统 API 路由）：

    • ThrottlerGuard：基于 @nestjs/throttler 的全局限流守卫
    • RateLimitDecorator：自定义限流装饰器，支持按接口配置
    • TimeoutInterceptor：全局请求超时拦截器

  2. Internal Provider：

    • TrafficService.checkLimit(key)：检查限流状态
    • TrafficService.getStatus()：获取当前流量状态

  3. AAPI：

    • 限流配置管理（哪些接口、什么阈值）
    • 限流事件日志
    • 当前被限流的 IP/用户列表

Domain Event 设计

  • RateLimitExceeded：限流触发事件
  • TrafficAbnormalDetected：异常流量检测

Admin 视图设计

  1. 限流配置页：

    • 接口级别的限流规则配置（阈值、时间窗口）
    • 全局开关（紧急情况下调整限流强度）

  2. 限流事件页：

    • 被限流的请求列表（IP、用户、接口、时间）
    • 限流趋势图（哪些接口被限流最多）

交付检查

  • 路由归属：Guard/Interceptor + AAPI
  • 是否需要 Prisma migration：需判断（限流规则表）
  • 是否需要 MySQL：需判断
  • 是否需要 Redis：是（限流计数器）
  • 是否需要 BullMQ：否
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：否（协作关系）
  • 是否需要 Content Safety：否
  • 是否需要 Cost 记录：否
  • 是否需要 AuditLog：是（限流规则变更）
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：是
  • 是否需要 E2E/集成测试：是

验收标准

  1. 全局 ThrottlerGuard 设计 + 实现
  2. 登录接口限流策略设计
  3. AI 接口限流策略设计
  4. 超时控制机制设计
  5. Redis 限流计数器方案
  6. Admin 限流配置视图设计
  7. 集成测试覆盖限流触发场景

禁止事项

  • 禁止限流规则硬编码（必须可配置）
  • 禁止限流计数器用 MySQL（性能不足，必须走 Redis）
  • 禁止限流影响正常用户体验（需要合理的阈值和提示）
  • 禁止登录限流与业务接口限流共用同一计数器
  • 禁止限流规则变更不记录审计

不建议当前阶段实现

  • 生产级熔断系统（opossum 完整集成）
  • 自动降级策略（先手动配置）
  • 异常流量自动检测和 IP 封禁
  • 全链路细粒度限流（先全局和关键接口）
## 目标 设计知习后端流量保护与韧性模块，为全系统提供限流、超时控制和基础熔断能力，防止单点过载拖垮整体服务。 本 Issue 只做架构设计，不直接实现代码。 ## 背景说明 知习后端对外暴露 CAPI 和 AAPI 两类接口，对内还有 IAPI 内部接口。AI 调用是高成本操作，登录接口是暴力破解攻击面，文件上传是带宽消耗大户。如果没有任何保护措施，恶意请求或突发流量可能耗尽服务器资源。 Traffic Protection 模块负责在请求进入业务逻辑之前进行流量控制，与 Quota 模块的区别在于：Quota 管"你有没有额度"，Traffic Protection 管"系统现在能不能承受"。 ## 模块职责 1. 本模块负责： - 全局 API 限流（基于 @nestjs/throttler） - 登录接口限流（防暴力破解） - AI 接口限流（控制成本） - 文件上传接口限流 - 单用户/IP 级别限流 - 超时控制（全局请求超时、AI 调用超时） - 基础降级策略（超时后返回什么） 2. 本模块不负责： - 用户额度管理（走 Quota Module） - AI 模型级别的降级路由（走 AI Gateway） - 服务器资源监控（走 Server Monitor） - 业务逻辑层面的错误处理（走 GlobalExceptionFilter） ## 基础设施依赖判断 - MySQL：需判断（限流规则存储） - Redis：是（限流计数器、滑动窗口） - BullMQ：否 - Qdrant：否 - AI Gateway：否（但需要与 AI Gateway 协作定义限流级别） - COS：否 - Content Safety：否 ## 接口设计 1. Guard / Interceptor（无传统 API 路由）： - ThrottlerGuard：基于 @nestjs/throttler 的全局限流守卫 - RateLimitDecorator：自定义限流装饰器，支持按接口配置 - TimeoutInterceptor：全局请求超时拦截器 2. Internal Provider： - TrafficService.checkLimit(key)：检查限流状态 - TrafficService.getStatus()：获取当前流量状态 3. AAPI： - 限流配置管理（哪些接口、什么阈值） - 限流事件日志 - 当前被限流的 IP/用户列表 ## Domain Event 设计 - RateLimitExceeded：限流触发事件 - TrafficAbnormalDetected：异常流量检测 ## Admin 视图设计 1. 限流配置页： - 接口级别的限流规则配置（阈值、时间窗口） - 全局开关（紧急情况下调整限流强度） 2. 限流事件页： - 被限流的请求列表（IP、用户、接口、时间） - 限流趋势图（哪些接口被限流最多） ## 交付检查 - [ ] 路由归属：Guard/Interceptor + AAPI - [ ] 是否需要 Prisma migration：需判断（限流规则表） - [ ] 是否需要 MySQL：需判断 - [ ] 是否需要 Redis：是（限流计数器） - [ ] 是否需要 BullMQ：否 - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：否（协作关系） - [ ] 是否需要 Content Safety：否 - [ ] 是否需要 Cost 记录：否 - [ ] 是否需要 AuditLog：是（限流规则变更） - [ ] 是否需要 Domain Event：是 - [ ] 是否需要 Admin 视图：是 - [ ] 是否需要 E2E/集成测试：是 ## 验收标准 1. 全局 ThrottlerGuard 设计 + 实现 2. 登录接口限流策略设计 3. AI 接口限流策略设计 4. 超时控制机制设计 5. Redis 限流计数器方案 6. Admin 限流配置视图设计 7. 集成测试覆盖限流触发场景 ## 禁止事项 - 禁止限流规则硬编码（必须可配置） - 禁止限流计数器用 MySQL（性能不足，必须走 Redis） - 禁止限流影响正常用户体验（需要合理的阈值和提示） - 禁止登录限流与业务接口限流共用同一计数器 - 禁止限流规则变更不记录审计 ## 不建议当前阶段实现 - 生产级熔断系统（opossum 完整集成） - 自动降级策略（先手动配置） - 异常流量自动检测和 IP 封禁 - 全链路细粒度限流（先全局和关键接口）
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:15 +08:00
wangdl self-assigned this 2026-05-22 21:00:15 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#5
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?