208 lines
5.3 KiB
Markdown
208 lines
5.3 KiB
Markdown
|
# 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) — 限流指标和告警规则
|