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) — 限流指标和告警规则
|