# 限速器快速上手

URL: https://caijiao.org/pingora/ratelimiter_quickstart
Source: docs/pingora/ratelimiter_quickstart.md
Description: 学习如何在 Pingora 中快速配置限速器（RateLimiter），控制请求速率，防止过载和滥用。

Pingora 提供内置的 **限速器（RateLimiter）** 功能，可以对请求速率进行控制，保护上游服务并提升系统稳定性。

## 配置限速器

在配置文件中启用限速器：

```yaml
ratelimiter:
  enable: true
  requests_per_second: 100
  burst: 20
````

* `enable`：是否启用限速器
* `requests_per_second`：每秒允许的请求数
* `burst`：允许短时间内的请求突发量

## 编程示例

在自定义过滤器中使用限速器：

```rust
use pingora::ratelimiter::RateLimiter;

fn rate_limit_filter(req: &Request, ctx: &mut Context) -> Result<(), Error> {
    let limiter = ctx.get::<RateLimiter>("ratelimiter").unwrap();

    if !limiter.try_acquire() {
        return Err(Error::new("请求过多，请稍后重试", 429));
    }

    Ok(())
}
```

* `try_acquire()`：尝试获取一次请求许可
* 超过速率时返回 429 错误（Too Many Requests）

## 使用场景

1. **保护上游服务**：避免瞬间高并发导致上游压力过大
2. **控制 API 调用频率**：对公共接口进行速率限制
3. **防止滥用**：防止恶意请求或爬虫攻击

## 高级用法

* **按客户端 IP 限速**：为每个 IP 创建独立限速器
* **动态调整速率**：根据系统负载或时间段调整 `requests_per_second`
* **与日志结合**：记录超限请求，便于分析访问模式

---

通过限速器，Pingora 可以轻松实现请求速率控制，保障服务稳定性和公平性，是高并发代理环境下的必要工具。