# 【RuoYi-Eggjs】：限流，为 API 保驾护航

## 前言

在 Web 应用开发中，保护 API 免受恶意攻击和过载是一项重要的安全措施。无论是防止暴力破解、恶意刷接口，还是保护服务器免于过载，限流（Rate Limiting）都是必不可少的防护手段。`[ruoyi-eggjs-ratelimiter](https://github.com/undsky/ruoyi-eggjs-ratelimiter)` 就是一个为 Egg.js 量身定制的限流插件，基于强大的 `rate-limiter-flexible` 库，提供开箱即用的请求限流能力。

## 为什么需要限流？

### 🛡️ 防止暴力攻击

登录、注册、找回密码等接口最容易成为暴力破解的目标。通过限流，可以有效限制单个 IP 在短时间内的尝试次数：

```
攻击者 1 分钟内尝试 1000 次登录 ❌ 被限流
正常用户 1 分钟内尝试 3 次登录 ✅ 正常访问
```

### 🚦 保护服务器资源

防止单个用户或恶意脚本占用过多服务器资源，确保所有用户都能获得良好的服务质量。

## 核心特性

### 🎯 基于 IP 的智能限流

插件自动获取客户端真实 IP 地址，并基于 IP 进行限流统计。支持反向代理场景，可正确识别经过 Nginx 等代理的真实 IP。

### 💾 双存储模式

**1. 内存存储（Memory）**
- **优势**：速度快，无需额外服务
- **劣势**：应用重启后限流记录丢失
- **适用**：开发环境、单机部署

**2. Redis 存储（推荐）**
- **优势**：数据持久化，多实例共享限流状态
- **劣势**：需要 Redis 服务
- **适用**：生产环境、集群部署

### 📈 标准响应头

插件严格遵循 HTTP 限流标准，返回标准的响应头：

```
Retry-After: 5.5                    # 多少秒后可以重试
X-RateLimit-Limit: 100              # 时间窗口内的请求限制
X-RateLimit-Remaining: 0            # 剩余可用请求次数
X-RateLimit-Reset: Mon Jan 01...    # 限流重置时间
```

前端可以通过这些响应头实现友好的用户提示和自动重试机制。

### 🔍 自动日志记录

当请求被限流时，插件会自动记录详细日志，包括 IP 地址、用户信息、请求内容等，便于追踪和分析恶意行为。

## 快速上手

### 安装

```bash
npm i ruoyi-eggjs-ratelimiter --save
```

### 配置

**1. 启用插件**

```js
// config/plugin.js
exports.ratelimiter = {
  enable: true,
  package: "ruoyi-eggjs-ratelimiter",
};
```

**2. 基础配置（内存存储）**

适合开发环境或单机部署：

```js
// config/config.default.js
config.ratelimiter = {
  points: 1000,      // 每个时间窗口允许 1000 次请求
  duration: 1000,    // 时间窗口为 1000 毫秒（1 秒）
  redis: null,       // 不使用 Redis
};
```

**3. Redis 配置（生产环境推荐）**

适合生产环境和集群部署：

```js
// config/config.prod.js
config.ratelimiter = {
  points: 100,       // 每分钟允许 100 次请求
  duration: 60,      // 时间窗口为 60 秒
  redis: {
    port: 6379,
    host: '127.0.0.1',
    password: 'your-password',
    db: 0,
  },
};
```

### 配置参数说明

| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| points | Number | 1000 | 时间窗口内允许的最大请求次数 |
| duration | Number | 1000 | 时间窗口大小（内存：毫秒；Redis：秒） |
| redis | Object | null | Redis 配置对象，为 null 时使用内存存储 |

> **注意**：`duration` 的单位根据存储方式不同而不同！使用 Redis 时单位为**秒**，使用内存时单位为**毫秒**。

## 实战场景

### 场景 1：防止登录暴力破解

登录接口是最容易被攻击的目标，限制每分钟的尝试次数可以有效防止暴力破解：

```js
// config/config.prod.js
config.ratelimiter = {
  points: 5,         // 每分钟最多 5 次尝试
  duration: 60,      // 60 秒
  redis: {
    host: '127.0.0.1',
    port: 6379,
  },
};
```

**效果**：
- 正常用户输错密码几次后需要等待 1 分钟
- 暴力破解程序在 5 次尝试后被阻止
- 大大降低了账号被破解的风险

### 场景 2：通用 API 限流

对于开放的 API 接口，限制每秒的请求次数可以防止单个客户端占用过多资源：

```js
// config/config.prod.js
config.ratelimiter = {
  points: 10,        // 每秒最多 10 次请求
  duration: 1,       // 1 秒
  redis: {
    host: '127.0.0.1',
    port: 6379,
  },
};
```

**效果**：
- 正常用户每秒 10 次请求足够使用
- 恶意脚本无法快速刷接口
- 服务器负载保持在可控范围

### 场景 3：开发环境宽松限制

开发环境下希望限流不影响调试，可以设置较大的限流值：

```js
// config/config.local.js
config.ratelimiter = {
  points: 1000,      // 每秒 1000 次请求
  duration: 1000,    // 1000 毫秒（1 秒）
  redis: null,       // 使用内存存储，简单快速
};
```

### 场景 4：配合 Nginx 获取真实 IP

在使用 Nginx 等反向代理的情况下，需要正确配置才能获取真实 IP：

**Nginx 配置**：

```nginx
location / {
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_pass http://127.0.0.1:7001;
}
```

**Egg.js 配置**：

```js
// config/config.default.js
config.proxy = true;  // 启用代理模式，信任 X-Forwarded-For
```

这样插件就能通过 `ctx.request.ip` 获取到真实的客户端 IP，而不是 Nginx 的 IP。


## 测试限流

### 使用 curl 测试

快速发送多个请求观察限流效果：

```bash
# 快速发送 10 个请求
for i in {1..10}; do
  curl -i http://localhost:7001/api/test
done
```

### 观察响应变化

**前几次请求**（正常）：
```
HTTP/1.1 200 OK
Content-Type: application/json

{"code":200,"data":{...}}
```

**超限后的请求**：
```
HTTP/1.1 200 OK
Retry-After: 0.5
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: Wed%2C%2027%20Nov%202024%2013%3A30%3A00%20GMT

{"code":429,"message":"Too Many Requests"}
```

### 前端处理示例

```js
// 前端请求拦截器
axios.interceptors.response.use(
  response => {
    if (response.data.code === 429) {
      const retryAfter = response.headers['retry-after'];
      message.error(`请求过于频繁，请在 ${retryAfter} 秒后重试`);
    }
    return response;
  }
);
```

## 常见问题

### Q1: 为什么选择 Redis 还是内存？

| 存储方式 | 速度 | 持久化 | 分布式 | 适用场景 |
|---------|------|-------|--------|---------|
| **内存** | ⚡️ 极快 | ❌ 重启丢失 | ❌ 单机 | 开发环境、单机部署 |
| **Redis** | 🚀 快 | ✅ 持久化 | ✅ 共享 | 生产环境、集群部署 |

**推荐做法**：
- 开发环境使用内存存储，简单快速
- 生产环境使用 Redis，数据可靠、支持集群

### Q2: duration 单位为什么不一致？

这是因为 `rate-limiter-flexible` 库的不同实现对时间单位的要求不同：

- **RateLimiterRedis**：要求 `duration` 为**秒**
- **RateLimiterMemory**：支持 `duration` 为**毫秒**

建议在配置时明确注释单位，避免混淆：

```js
config.ratelimiter = {
  points: 100,
  duration: 60,  // 秒（使用 Redis）
  redis: { ... },
};
```

### Q3: 如何针对不同接口设置不同限流策略？

当前插件作为全局中间件运行，对所有接口使用统一的限流策略。如果需要细粒度控制，可以考虑：

**方案 1**：在特定 Controller 中自定义限流逻辑

```js
// app/controller/login.js
async login() {
  // 针对登录接口的特殊限流逻辑
  const limiter = new RateLimiter({ points: 5, duration: 60 });
  await limiter.consume(ctx.request.ip);
  // 业务逻辑
}
```

**方案 2**：扩展插件，支持路由级别的配置（需要修改插件代码）

### Q4: 如何处理代理场景下的 IP 获取？

确保 Nginx 配置正确转发真实 IP：

```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
```

并在 Egg.js 中启用代理模式：

```js
config.proxy = true;
```

## 性能优化建议

### 1. 合理设置限流参数

根据业务场景选择合适的 `points` 和 `duration`：

```js
// 登录接口：严格限制
{ points: 5, duration: 60 }

// 查询接口：适度限制
{ points: 100, duration: 60 }

// 静态资源：宽松限制
{ points: 1000, duration: 60 }
```

### 2. Redis 连接优化

使用连接池，避免频繁创建连接：

```js
config.ratelimiter = {
  redis: {
    host: '127.0.0.1',
    port: 6379,
    // 连接池配置
    maxRetriesPerRequest: 1,
    enableOfflineQueue: false,
  },
};
```

### 3. 监控限流情况

定期查看日志，分析被限流的请求：

```bash
# 查看限流日志
grep "RateLimiter" logs/common-error.log
```

根据日志调整限流策略，平衡安全性和用户体验。

## 总结

`ruoyi-eggjs-ratelimiter` 是一个简单但强大的 Egg.js 限流插件，它的优势在于：

- **开箱即用**：一行配置，全局生效
- **灵活存储**：支持 Redis 和内存两种方式
- **标准化**：遵循 HTTP 限流标准，响应头完整
- **易于调试**：自动记录日志，便于追踪
- **性能优异**：基于成熟的 rate-limiter-flexible 库

无论是保护登录接口免受暴力攻击，还是限制 API 调用频率，这个插件都能轻松胜任。如果你正在使用 Egg.js，强烈建议集成这个插件，为你的 API 加上一道安全防线！

-----

+ 插件地址：[ruoyi-eggjs-ratelimiter](https://github.com/undsky/ruoyi-eggjs-ratelimiter)
+ 项目地址：[RuoYi-Eggjs](https://github.com/undsky/ruoyi-eggjs)
+ 开发文档：[RuoYi-Eggjs 文档](https://www.undsky.com/blog/?category=RuoYi-Eggjs#)

在 Web 应用开发中，保护 API 免受恶意攻击和过载是一项重要的安全措施。无论是防止暴力破解、恶意刷接口，还是保护服务器免于过载，限流（Rate Limiting）都是必不可少的防护手段。[ruoyi-eggjs-ratelimiter](https://github.com/undsky/ruoyi-eggjs-ratelimiter) 就是一个为 Egg.js 量身定制的限流插件，基于强大的 rate-limiter-flexible 库，提供开箱即用的请求限流能力。

【RuoYi-Eggjs】：限流，为 API 保驾护航

在 Web 应用开发中，保护 API 免受恶意攻击和过载是一项重要的安全措施。无论是防止暴力破解、恶意刷接口，还是保护服务器免于过载，限流（Rate Limiting）都是必不可少的防护手段。[ruoyi-eggjs-ratelimiter](https://github.com/undsky/ruoyi-eggjs-ratelimiter) 就是一个为 Egg.js 量身定制的限流插件，基于强大

后端

安全

网络与通信

RuoYi-Eggjs限流插件为Egg.js应用提供强大的API防护能力，支持内存和Redis双存储模式，有效防止暴力破解和服务器过载。基于IP智能限流，遵循HTTP标准响应头，自动记录日志，配置简单灵活。适用于登录保护、API限流等场景，是Egg.js开发者必备的安全防护工具。

中间件

服务器

路由

Redis

腾讯云数据库特惠，新用户首单0.5折起


message-queue-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【RuoYi-Eggjs】：限流，为 API 保驾护航-腾讯云开发者社区-腾讯云

【RuoYi-Eggjs】：限流，为 API 保驾护航

【RuoYi-Eggjs】：限流，为 API 保驾护航

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐