vault backup: 2026-06-03 10:22:41

2026-06-03 10:22:41 +08:00
parent 6f8363fd3c
commit 2e207dc8fb
16 changed files with 0 additions and 0 deletions
@@ -0,0 +1,207 @@
+# 09 — 限流
+
+> **一句话概括**：Redis Lua 原子令牌桶 + 双层限流 + Fail-Open 降级，保护系统免受过载。
+
+---
+
+```mermaid
+flowchart LR
+    A["🌐 Request"] --> B["🌍 Global<br/>Limiter"]
+    B -->|pass| C["👤 User<br/>Limiter"]
+    B -->|deny| F["❌ 429"]
+    B -->|redis-fail| C
+    C -->|pass| D["✅ Handler"]
+    C -->|deny| F
+    C -->|redis-fail| D
+
+    style A fill:#e3f2fd,stroke:#1976d2
+    style B fill:#fff3e0,stroke:#f57c00
+    style C fill:#e8f5e9,stroke:#388e3c
+    style D fill:#c8e6c9,stroke:#2e7d32
+    style F fill:#ffcdd2,stroke:#c62828
+```
+
+---
+
+## ⚙️ 令牌桶算法
+
+Gen2D 使用 **Redis + Lua 脚本** 实现分布式令牌桶限流，保证原子性和一致性。
+
+### Lua 脚本核心逻辑
+
+```lua
+-- KEYS[1] = 限流 key
+-- ARGV[1] = rate（每秒令牌数）
+-- ARGV[2] = burst（桶容量）
+-- ARGV[3] = now（当前时间戳，毫秒）
+-- ARGV[4] = expiration（key 过期时间）
+
+-- 1. 获取当前桶状态
+local data = redis.call('HMGET', key, 'tokens', 'ts')
+
+-- 2. 首次访问，初始化满桶
+if tokens == nil then
+    tokens = burst
+    last_ts = now
+end
+
+-- 3. 计算时间差，补充令牌
+local delta = now - last_ts
+if delta > 0 and rate > 0 then
+    local refill = (delta * rate) / 1000
+    tokens = math.min(burst, tokens + refill)
+end
+
+-- 4. 判断是否允许
+if tokens >= 1 then
+    tokens = tokens - 1
+    allowed = 1
+else
+    retry_after = math.ceil((deficit * 1000) / rate)
+end
+
+-- 5. 更新 Redis
+redis.call('HSET', key, 'tokens', tokens, 'ts', last_ts)
+redis.call('PEXPIRE', key, expiration)
+
+return {allowed, tokens, retry_after}
+```
+
+### 固定窗口变体
+
+当 `Rate = 0` 时，令牌桶退化为固定窗口模式：
+
+- 桶初始化为满（Burst 个令牌）
+- 用完后不补充（`rate = 0` 时跳过 refill）
+- 等待 key 过期后重置（`Expiration` 控制窗口大小）
+
+> 💡 **适用场景**：24 小时维度的配额控制，如"每天 30 次提示词优化"。
+
+---
+
+## 🔀 双层限流配置
+
+Gen2D 对核心接口实施**全局限流 + 用户限流**双重保护：
+
+| 接口 | 全局限流 | 用户限流 | 窗口 |
+|------|---------|---------|------|
+| `/api/v1/prompt/optimize` | 1000 次/24h | 30 次/24h | 25h 过期 |
+| `/api/v1/generate` | 500 次/24h | 15 次/24h | 25h 过期 |
+
+### 执行顺序
+
+```mermaid
+flowchart TB
+    A["请求进入"] --> B["全局限流检查"]
+    B -->|通过| C["用户限流检查"]
+    B -->|拒绝| D["429 Too Many Requests"]
+    C -->|通过| E["执行 Handler"]
+    C -->|拒绝| D
+
+    style B fill:#fff3e0,stroke:#f57c00
+    style C fill:#e8f5e9,stroke:#388e3c
+    style D fill:#ffcdd2,stroke:#c62828
+    style E fill:#c8e6c9,stroke:#2e7d32
+```
+
+**全局限流在前**：先检查系统总体配额，避免单个用户耗尽全局配额。
+
+### 配置参数
+
+```go
+type Config struct {
+    Rate       int           // 每秒令牌数；0 = 固定窗口
+    Burst      int           // 桶容量（窗口内总量上限）
+    KeyPrefix  string        // Redis key 前缀
+    Expiration time.Duration // key 过期时间
+}
+```
+
+| 配置项 | Prompt User | Prompt Global | Generate User | Generate Global |
+|--------|:-----------:|:-------------:|:-------------:|:---------------:|
+| Rate | 0 | 0 | 0 | 0 |
+| Burst | 30 | 1000 | 15 | 500 |
+| KeyPrefix | `ratelimit:prompt:user:` | `ratelimit:prompt:global:` | `ratelimit:generate:user:` | `ratelimit:generate:global:` |
+| Expiration | 25h | 25h | 25h | 25h |
+
+---
+
+## 🛡️ Fail-Open 降级
+
+当 Redis 不可用时限流器自动降级为 **Fail-Open** 模式：
+
+```go
+func (l *TokenBucketLimiter) Allow(ctx context.Context, key string) (bool, int, time.Duration) {
+    result, err := l.script.Run(ctx, l.client, ...).Int64Slice()
+    if err != nil {
+        // Redis 不可用时 fail-open，放行请求
+        return true, l.config.Burst, 0
+    }
+    // ...
+}
+```
+
+**设计权衡**：
+
+| 策略 | 优点 | 缺点 |
+|------|------|------|
+| **Fail-Open** ✅ | 保证可用性，用户体验不受影响 | 可能短暂失去限流保护 |
+| Fail-Close | 严格限流保护 | Redis 故障导致全站不可用 |
+
+> 🛡️ **选择 Fail-Open**：在"偶尔超限"和"完全不可用"之间，优先保证服务可用性。
+
+---
+
+## 📡 中间件响应
+
+限流中间件返回标准化的 HTTP 响应：
+
+### 允许通过
+
+```http
+HTTP/1.1 200 OK
+X-RateLimit-Remaining: 12
+```
+
+### 被限流
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 3600
+X-RateLimit-Remaining: 0
+
+{
+  "code": 429,
+  "message": "请求过于频繁，请稍后再试"
+}
+```
+
+| Header | 说明 |
+|--------|------|
+| `X-RateLimit-Remaining` | 剩余令牌数 |
+| `Retry-After` | 建议重试等待秒数 |
+
+---
+
+## 📊 指标采集
+
+限流中间件自动采集 Prometheus 指标：
+
+```go
+metrics.RateLimitRequestsTotal.WithLabelValues(scope, endpoint, result).Inc()
+metrics.RateLimitRemainingTokens.WithLabelValues(scope, endpoint).Set(float64(remaining))
+```
+
+- `scope`：`user` / `global`
+- `endpoint`：`prompt` / `generate`
+- `result`：`allowed` / `denied`
+
+配合告警规则 `RateLimitHighDenialRate`（拒绝率 > 5%），及时发现异常流量。
+
+---
+
+## 🔗 关联文档
+
+- [← 返回索引](00-index.md)
+- [10 — 中间件链](10-middleware-chain.md) — 限流中间件在链中的位置
+- [07 — 可观测性](07-observability.md) — 限流指标和告警规则