限流配置¶
文档版本: 1.0.2
最后更新: 2026-05-21 Git 提交: 61384b4a
作者: Lincoln
JAiRouter 提供多种限流算法,支持全局、服务级别和实例级别的限流配置,以及基于客户端 IP 的独立限流。本文档详细介绍各种限流策略的配置和使用。
模块化配置说明¶
从 v1.0.0 版本开始,JAiRouter 采用模块化配置结构,限流相关配置已移至独立的配置文件中:
- 主配置文件:
application.yml - 全局限流策略:
config/base/model-services-base.yml - 服务级 / 实例级限流配置:
config/router/services.yml(v3.5.3 起model.services只在config/router/services.yml定义一次,见 #643)
全局策略在 config/base/model-services-base.yml,每个服务的限流块与它下面的 instances 列表都在同一份 config/router/services.yml 里。
限流概述¶
支持的算法¶
| 算法 | 特点 | 适用场景 | 突发处理 |
|---|---|---|---|
| Token Bucket | 允许突发流量 | 平稳流量 + 偶发突发 | 优秀 |
| Leaky Bucket | 平滑输出流量 | 需要平稳输出 | 一般 |
| Sliding Window | 精确时间窗口控制 | 精确流量控制 | 一般 |
| Warm Up | 冷启动保护 | 服务启动场景 | 渐进式 |
限流层级¶
graph TB
A[全局限流配置] --> B[服务级限流配置]
B --> C[实例级限流配置]
A --> D[默认算法和参数]
B --> E[服务特定限流]
C --> F[实例独立限流]
G[客户端IP限流] --> B
G --> C
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style G fill:#fff3e0限流层级说明(v2.8.8):请求经过 服务级 → 实例级 两级检查(全局/客户端 IP 限流按配置启用)。服务级超限返回
429 Too Many Requests;实例级超限自动换下一个实例,全部实例被限才返回503。此外规则引擎的 RATE_LIMIT 动作提供按规则 ID 的独立限流(见 routing-rules.md)。退避提示(v3.5.2 起,#624):服务级的
429与实例级全限的503现在都带Retry-After: 1(秒)。这两层由限流器直接判定、不对外暴露剩余量,因此只补退避提示,不返回X-RateLimit-*(配额层仍用X-Quota-*,终端用户层用X-RateLimit-*,三组前缀刻意区分)。
服务级桶是全局共享的(#824)¶
服务级限流器按服务类型取桶:rate-limit.capacity / rate 是该服务的全局上限,同一服务下的所有客户端、所有模型共用同一个令牌桶。默认 client-ip-enable: false,因此一个客户端打满后,其余调用方会一起收到 429(带 Retry-After: 1)。
- 按调用方公平分配:给对应服务设
rate-limit.client-ip-enable: true(每个调用方独立成桶),或在集群 + 无反代场景下把rate-limit.key-dimension设为按 API Key / 租户计数(见 客户端 IP 限流)。 - 启动可见性:只要存在「服务级限流已启用、但未开客户端维度」的服务,启动日志会打印一条
WARN逐一点名,避免把「全局保护」误读成「每人一份配额」。
服务级动态限流配置(v2.8.8)¶
服务级限流支持通过 Web 管理界面 动态配置并热生效(无需重启):
- API:
PUT /api/services/{serviceType}/ratelimit(持久化 + 立即生效)、GET /api/services/{serviceType}/ratelimit(读取当前配置) - 配置格式(canonical):
{
"enabled": true,
"algorithm": "token-bucket",
"capacity": 100,
"rate": 10,
"scope": "service",
"key": ""
}
enabled=false时移除该服务的限流器;启用时capacity/rate必须 > 0,否则返回 400- 配置持久化到配置存储(
model-router-config),重启后自动生效(启动时从合并配置加载);YAML 中未配置限流的服务保持原样 - 服务管理页的编辑对话框已接入该端点(限流配置保存即热生效)
全局限流配置¶
基础配置¶
在 config/router/services.yml 文件中配置全局限流:
# config/router/services.yml
model:
# 全局限流配置
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 1000
rate: 100
scope: "service"
client-ip-enable: true # 启用客户端IP限流
services:
# 聊天服务配置
chat:
load-balance:
type: least-connections
adapter: gpustack # 使用GPUStack适配器
# 服务级别限流配置
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 100
rate: 10
scope: "service"
client-ip-enable: true
高级配置¶
model:
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 1000
rate: 100
scope: "service"
client-ip-enable: true # 启用客户端IP限流
限流算法详解¶
1. Token Bucket(令牌桶算法)¶
算法原理¶
令牌桶算法维护一个固定容量的桶,以固定速率向桶中添加令牌。请求到达时消耗令牌,无令牌时拒绝请求。
graph LR
A[令牌生成器] -->|固定速率| B[令牌桶]
C[请求] --> D{桶中有令牌?}
D -->|是| E[消耗令牌,允许请求]
D -->|否| F[拒绝请求]
B --> D配置示例¶
在 config/router/services.yml 文件中配置令牌桶算法:
model:
services:
chat:
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 100 # 桶容量(最大令牌数)
rate: 10 # 令牌补充速率(每秒)
scope: "service" # 限流范围
client-ip-enable: true # 启用客户端IP限流
JSON 配置¶
JAiRouter 也支持通过动态配置 API 更新限流配置:
{
"services": {
"chat": {
"rateLimit": {
"algorithm": "token-bucket",
"capacity": 100,
"rate": 10,
"clientIpEnable": true
}
}
}
}
参数说明¶
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
capacity | Integer | 桶容量,最大令牌数 | 100 |
rate | Integer | 令牌补充速率(每秒) | 10 |
clientIpEnable | Boolean | 是否启用客户端IP限流 | false |
适用场景¶
- 平稳流量 + 偶发突发:日常流量平稳,偶尔有突发请求
- API 网关:需要允许短时间突发,但控制长期平均速率
- 用户请求限制:允许用户短时间内发送多个请求
配置建议¶
# 高并发场景
rate-limit:
algorithm: "token-bucket"
capacity: 1000 # 大容量支持突发
rate: 100 # 适中的补充速率
# 保护后端场景
rate-limit:
algorithm: "token-bucket"
capacity: 50 # 小容量限制突发
rate: 5 # 低速率保护后端
2. Leaky Bucket(漏桶算法)¶
算法原理¶
漏桶算法维护一个固定容量的桶,请求进入桶中排队,以固定速率从桶底流出处理。
graph TB
A[请求流入] --> B{桶是否满?}
B -->|否| C[请求进入桶]
B -->|是| D[拒绝请求]
C --> E[桶中排队]
E -->|固定速率| F[处理请求]配置示例¶
在 config/router/services.yml 文件中配置漏桶算法:
model:
services:
embedding:
rate-limit:
enabled: true
algorithm: "leaky-bucket"
capacity: 50 # 桶容量
rate: 5 # 漏出速率(每秒)
scope: "service"
client-ip-enable: true
JSON 配置¶
JAiRouter 也支持通过动态配置 API 更新限流配置:
{
"services": {
"embedding": {
"rateLimit": {
"algorithm": "leaky-bucket",
"capacity": 50,
"rate": 5,
"clientIpEnable": true
}
}
}
}
参数说明¶
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
capacity | Integer | 桶容量,最大排队请求数 | 50 |
rate | Integer | 漏出速率(每秒) | 5 |
适用场景¶
- 需要平稳输出:要求后端接收到的请求速率平稳
- 消息队列:需要控制消息处理速率
- 数据库保护:保护数据库免受突发流量冲击
3. Sliding Window(滑动窗口算法)¶
算法原理¶
滑动窗口算法在固定时间窗口内统计请求数量,超过阈值时拒绝请求。
graph LR
A[时间窗口] --> B[统计请求数]
C[新请求] --> D{窗口内请求数 < 阈值?}
D -->|是| E[允许请求]
D -->|否| F[拒绝请求]
B --> D配置示例¶
在 config/router/services.yml 文件中配置滑动窗口算法:
model:
services:
tts:
rate-limit:
enabled: true
algorithm: "sliding-window"
capacity: 100 # 桶容量
rate: 100 # 每秒窗口内最大请求数
scope: "service"
client-ip-enable: true
JSON 配置¶
JAiRouter 也支持通过动态配置 API 更新限流配置:
{
"services": {
"tts": {
"rateLimit": {
"algorithm": "sliding-window",
"capacity": 100,
"rate": 100,
"clientIpEnable": true
}
}
}
}
参数说明¶
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
capacity | Integer | 桶容量 | 100 |
rate | Integer | 每秒窗口内最大请求数 | 10 |
注意:滑动窗口使用固定的 1 秒窗口。
rate控制该窗口内允许的最大请求数。
适用场景¶
- 精确流量控制:需要精确控制时间窗口内的请求数量
- API 配额管理:按时间段分配 API 调用配额
- 防刷接口:防止短时间内大量重复请求
4. Warm Up(预热算法)¶
算法原理¶
预热算法在服务启动时逐渐增加允许的请求速率,避免冷启动时的性能问题。
graph LR
A[服务启动] --> B[低速率]
B --> C[逐渐增加]
C --> D[达到目标速率]
E[预热时间] --> F[当前允许速率]
F --> G[= 目标速率 * (当前时间 / 预热时间)]配置示例¶
在 config/router/services.yml 文件中配置预热算法:
model:
services:
chat:
rate-limit:
enabled: true
algorithm: "warm-up"
capacity: 100 # 最终容量
rate: 10 # 最终速率
warm-up-period: 300 # 预热时间(秒)
scope: "service"
JSON 配置¶
JAiRouter 也支持通过动态配置 API 更新限流配置:
{
"services": {
"chat": {
"rateLimit": {
"algorithm": "warm-up",
"capacity": 100,
"rate": 10,
"warmUpPeriod": 300,
"clientIpEnable": true
}
}
}
}
参数说明¶
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
capacity | Integer | 最终容量 | 100 |
rate | Integer | 最终速率(每秒) | 10 |
warmUpPeriod | Integer | 预热时间(秒) | 600 |
适用场景¶
- 服务冷启动:服务刚启动时需要预热
- 缓存预热:需要时间建立缓存
- 连接池预热:数据库连接池需要时间建立
客户端 IP 限流¶
基础配置¶
在 config/base/model-services-base.yml 中通过 client-ip-enable 启用客户端 IP 限流:
model:
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 1000
rate: 100
scope: "service"
client-ip-enable: true # 按需开启;仓库自带配置默认为 false
实现状态(v3.5.2 起已接线,#623):
client-ip-enable/key-dimension过去「能设、能回显、但主链路不调用」, 现已接进请求主链路(认证之后、服务级限流预扣与缓存读取之前)。仓库自带配置一律为false——集群 + 无 L7 反代 时所有客户端共用一个出口 IP,按 IP 计数会把它们合并成一个桶;这种部署请改用key-dimension: api-key。 注意tenant维度当前等同api-key(系统还没有租户身份),见 roadmap。 需要限制「共用同一个 API Key 的下游用户」时,仍应使用下文「终端用户限流」一节(按 (API Key × 终端用户) 计数)。
服务级别 IP 限流¶
model:
services:
chat:
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 1000 # 服务级别总容量
rate: 100 # 服务级别总速率
client-ip-enable: true # 启用IP限流
实例级别 IP 限流¶
model:
services:
chat:
instances:
- name: "model-1"
base-url: "http://server-1:8080"
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 100
rate: 10
scope: "instance"
client-ip-enable: true
IP 限流监控¶
# 查看限流器状态(包含各IP限流器)
curl "http://localhost:8080/api/rate-limiter/status"
# 查看限流器指标(剩余容量、使用率)
curl "http://localhost:8080/api/rate-limiter/metrics"
终端用户限流(v3.5.2,默认关闭)¶
面向「一个 API Key 被多个终端用户共用」的场景:按 (API Key, 终端用户) 计数,给每个终端用户一份独立的每分钟额度。默认关闭,属于可用性护栏,不是安全边界(原因见本节末尾)。
身份解析顺序¶
- 请求头
X-End-User-Id(header-enabled: true时生效,默认开); - 请求体里的
user字段(Chat Completions、Embeddings、图片生成、图片编辑四类请求体); - Anthropic Messages 的
metadata.user_id。
取到的值先做规范化:只接受 [A-Za-z0-9._:@/-] 组成、长度不超过 64 的标识;不满足时替换为 SHA-256 前 16 位摘要。原始值既不进 Redis 键,也不进日志与错误响应。
配置¶
在 config/router/ratelimit.yml 的 jairouter: 下追加以下块(完整前缀 jairouter.ratelimit.end-user):
ratelimit:
end-user:
enabled: true # 总开关,默认 false
requests-per-minute: 60 # 每 (API Key × 终端用户) 的每分钟额度
header-enabled: true # 是否接受 X-End-User-Id
missing-identity: skip # skip = 不计数直接放行;reject = 直接 429
local-cache-size: 50000 # 本地计数器条目上限(有界,不会无界增长)
fingerprint-length: 16 # 非法标识的摘要长度
执行位置与超限响应¶
判定发生在认证之后、服务级限流预扣与响应缓存读取之前 —— 缓存命中同样受限流约束,限流是硬边界。超限返回 429,并带 Retry-After(到下一整分钟)、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。
多副本¶
默认每副本各自计数,多副本下实际放行量约为配置值 × 副本数。要精确计数需打开 jairouter.ratelimit.distributed.enabled=true(Redis 单脚本原子计数),见多副本部署。
边界与不做的事¶
- 不是安全边界:
X-End-User-Id由调用方自报,API Key 的持有者可以随意切换标识来规避额度。要真正隔离终端用户,仍需一人一 Key。 - 不受它约束的调用方:控制台 JWT 登录态(Playground 等)一律跳过;取不到 API Key 时也跳过。
- 与配额层的区别:配额层(
jairouter.quota.*)按窗口计量(请求数 / token),失败时返回X-Quota-*;本层只按分钟计速率,返回X-RateLimit-*。 - v1 不做每 Key 覆盖:额度是全局一份;按 Key 定制额度留待出现真实需求后再做。
多层限流配置¶
分层限流策略¶
在 config/router/services.yml 文件中配置多层限流:
model:
# 全局限流:保护整个系统
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 10000
rate: 1000
client-ip-enable: true
services:
chat:
# 服务级限流:保护特定服务
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 1000
rate: 100
client-ip-enable: true
instances:
- name: "high-perf-model"
base-url: "http://gpu-server:8080"
# 实例级限流:保护特定实例
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 500
rate: 50
scope: "instance"
限流优先级¶
- 实例级限流:最高优先级,直接保护实例
- 服务级限流:中等优先级,保护服务类型
- 全局限流:最低优先级,保护整个系统
动态限流配置¶
通过配置文件动态调整¶
JAiRouter 也支持通过动态配置 API 更新限流配置:
{
"services": {
"chat": {
"rateLimit": {
"algorithm": "token-bucket",
"capacity": 200,
"rate": 20,
"clientIpEnable": true
},
"instances": [
{
"name": "model-1",
"baseUrl": "http://server-1:8080",
"rateLimit": {
"algorithm": "token-bucket",
"capacity": 100,
"rate": 10
}
}
]
}
}
}
限流参数调优¶
# 监控当前限流效果
curl "http://localhost:8080/api/rate-limiter/summary"
# 根据监控结果调整配置
# 如果拒绝率过高,增加容量或速率
# 如果后端压力大,减少容量或速率
限流监控和告警¶
监控指标¶
🔑 这些运维端点需要管理员凭据:下列 /actuator/** 调用走正常认证链 —— 只有 /actuator/health(含
liveness/readiness子路径)、/actuator/info、/actuator/prometheus允许匿名(供 k8s 探针与 Prometheus 抓取),其余都需要 ADMIN 角色。不带凭据会得到401 AUTH_MISSING。 (修复前即使带了 ADMIN JWT 也会 401:认证链被整段排除,与hasRole("ADMIN")互相抵消,见 issue #340。)取 JWT 与调用示例(本机实测通过):
# 限流事件(允许/拒绝)
curl "http://localhost:8080/actuator/metrics/jairouter_rate_limit_events_total"
# 各限流器剩余容量
curl "http://localhost:8080/actuator/metrics/jairouter_rate_limit_remaining"
# 各限流器使用率
curl "http://localhost:8080/actuator/metrics/jairouter_rate_limit_usage_ratio"
Prometheus 指标¶
# 限流请求速率
rate(jairouter_rate_limit_events_total[5m])
# 限流拒绝率
rate(jairouter_rate_limit_events_total{result="denied"}[5m]) / rate(jairouter_rate_limit_events_total[5m])
# 各限流器剩余容量
jairouter_rate_limit_remaining
# 各限流器使用率
jairouter_rate_limit_usage_ratio
告警规则¶
# Prometheus 告警规则
groups:
- name: jairouter_ratelimit
rules:
- alert: HighRateLimitRejection
expr: rate(jairouter_rate_limit_events_total{result="denied"}[5m]) / rate(jairouter_rate_limit_events_total[5m]) > 0.1
for: 2m
labels:
severity: warning
annotations:
summary: "限流拒绝率过高"
description: "服务 {{ $labels.service }} 的限流拒绝率超过 10%"
性能优化¶
1. 内存优化¶
客户端 IP 限流器缓存使用 Caffeine,自动清理:
- 最多 10,000 个条目
- 30 分钟无访问自动过期(基于访问)
- 自动淘汰并记录统计信息
2. 算法选择优化¶
# 高并发场景:选择性能最好的算法
model:
services:
high-traffic:
rate-limit:
algorithm: "token-bucket" # 性能最好
# 精确控制场景:选择精度最高的算法
model:
services:
precise-control:
rate-limit:
algorithm: "sliding-window" # 精度最高
实际使用案例¶
案例 1:API 网关限流¶
# 多层限流保护
model:
# 全局限流:保护整个网关
rate-limit:
enabled: true
algorithm: "token-bucket"
capacity: 10000
rate: 1000
client-ip-enable: true
services:
# 聊天服务:高频使用
chat:
rate-limit:
algorithm: "token-bucket"
capacity: 5000
rate: 500
client-ip-enable: true
# 图像生成:资源密集
image-generation:
rate-limit:
algorithm: "leaky-bucket"
capacity: 100
rate: 10
client-ip-enable: true
案例 2:防刷保护¶
# 防止恶意刷接口
model:
services:
sensitive-api:
rate-limit:
enabled: true
algorithm: "sliding-window"
capacity: 50 # 桶容量
rate: 50 # 每秒最多 50 次请求
client-ip-enable: true
案例 3:服务预热¶
# 新服务上线预热
model:
services:
new-service:
rate-limit:
enabled: true
algorithm: "warm-up"
capacity: 1000
rate: 100
warm-up-period: 600 # 10分钟预热
故障排查¶
常见问题¶
限流过于严格
内存使用过高
限流不生效
调试命令¶
# 查看限流配置
curl "http://localhost:8080/actuator/configprops" | jq '.model.rate-limit'
# 查看限流指标
curl "http://localhost:8080/actuator/metrics" | grep ratelimit
# 测试限流效果
for i in {1..20}; do
curl -w "%{http_code}\n" "http://localhost:8080/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{"model": "test", "messages": [{"role": "user", "content": "test"}]}'
done
下一步¶
完成限流配置后,您可以继续了解: