mirror of
https://github.com/alibaba/higress.git
synced 2026-05-04 10:27:27 +08:00
update plugins doc (#1305)
This commit is contained in:
澄潭
GitHub
@@ -1,11 +1,18 @@
|
||||
<p>
|
||||
<a href="README_EN.md"> English </a> | 中文
|
||||
</p>
|
||||
---
|
||||
title: 基于 Key 的本地限流
|
||||
keywords: [higress,key rate limit]
|
||||
description: Key 本地限流插件配置参考
|
||||
---
|
||||
|
||||
# 功能说明
|
||||
## 功能说明
|
||||
`key-rate-limit`插件实现了基于特定键值实现限流，键值来源可以是 URL 参数、HTTP 请求头
|
||||
|
||||
# 配置字段
|
||||
## 运行属性
|
||||
|
||||
插件执行阶段：`默认阶段`
|
||||
插件执行优先级：`10`
|
||||
|
||||
## 配置字段
|
||||
|
||||
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
|
||||
| -------- | -------- | -------- | -------- | -------- |
|
||||
@@ -23,9 +30,9 @@
|
||||
| query_per_hour | number | 选填，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项 | - | 允许每小时请求次数 |
|
||||
| query_per_day | number | 选填，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项 | - | 允许每天请求次数 |
|
||||
|
||||
# 配置示例
|
||||
## 配置示例
|
||||
|
||||
## 识别请求参数 apikey，进行区别限流
|
||||
### 识别请求参数 apikey，进行区别限流
|
||||
```yaml
|
||||
limit_by_param: apikey
|
||||
limit_keys:
|
||||
@@ -35,7 +42,7 @@ limit_keys:
|
||||
query_per_minute: 100
|
||||
```
|
||||
|
||||
## 识别请求头 x-ca-key，进行区别限流
|
||||
### 识别请求头 x-ca-key，进行区别限流
|
||||
```yaml
|
||||
limit_by_header: x-ca-key
|
||||
limit_keys:
|
||||
@@ -45,29 +52,3 @@ limit_keys:
|
||||
query_per_hour: 10
|
||||
|
||||
```
|
||||
|
||||
## 对特定路由或域名开启
|
||||
```yaml
|
||||
# 使用 _rules_ 字段进行细粒度规则配置
|
||||
_rules_:
|
||||
# 规则一：按路由名称匹配生效
|
||||
- _match_route_:
|
||||
- route-a
|
||||
- route-b
|
||||
limit_by_header: x-ca-key
|
||||
limit_keys:
|
||||
- key: 102234
|
||||
query_per_second: 10
|
||||
# 规则二：按域名匹配生效
|
||||
- _match_domain_:
|
||||
- "*.example.com"
|
||||
- test.com
|
||||
limit_by_header: x-ca-key
|
||||
limit_keys:
|
||||
- key: 102234
|
||||
query_per_second: 100
|
||||
|
||||
```
|
||||
此例 `_match_route_` 中指定的 `route-a` 和 `route-b` 即在创建网关路由时填写的路由名称，当匹配到这两个路由时，将使用此段配置；
|
||||
此例 `_match_domain_` 中指定的 `*.example.com` 和 `test.com` 用于匹配请求的域名，当发现域名匹配时，将使用此段配置；
|
||||
配置的匹配生效顺序，将按照 `_rules_` 下规则的排列顺序，匹配第一个规则后生效对应配置，后续规则将被忽略。
|
||||
|
||||
@@ -1,31 +1,36 @@
|
||||
<p>
|
||||
English | <a href="README.md">中文</a>
|
||||
</p>
|
||||
---
|
||||
title: Key-based Local Rate Limiting
|
||||
keywords: [higress,key rate limit]
|
||||
description: Configuration reference for Key local rate limiting plugin
|
||||
---
|
||||
|
||||
# Description
|
||||
`key-rate-limit` plugin implements a rate-limiting function based on specific key-values. The key-values may come from URL parameters or HTTP headers.
|
||||
## Functional Description
|
||||
The `key-rate-limit` plugin implements rate limiting based on specific key values, which can originate from URL parameters or HTTP request headers.
|
||||
|
||||
# Configuration Fields
|
||||
## Running Properties
|
||||
Plugin execution phase: `default phase`
|
||||
Plugin execution priority: `10`
|
||||
|
||||
| Name | Type | Requirement | Default Value | Description |
|
||||
| -------- | -------- | -------- | -------- | -------- |
|
||||
| limit_by_header | string | Optional. Choose one from following: `limit_by_header`, `limit_by_param`. | - | The name of HTTP header used to obtain key-value used in rate-limiting. |
|
||||
| limit_by_param | string | Optional. Choose one from following: `limit_by_header`, `limit_by_param`. | - | The name of URL parameter used to obtain key-value used in rate-limiting. |
|
||||
| limit_keys | array of object | Required | - | Rate-limiting thresholds when matching specific key-values |
|
||||
## Configuration Fields
|
||||
|
||||
Field descriptions of `limit_keys` items:
|
||||
| Name | Data Type | Required | Default Value | Description |
|
||||
|-----------------|-----------------|---------------------------------------------------------------|---------------|----------------------------------------------------------------------------------------|
|
||||
| limit_by_header | string | Optional, choose one from `limit_by_header`, `limit_by_param` | - | Configuration for the source of the rate limiting key value (HTTP request header name) |
|
||||
| limit_by_param | string | Optional, choose one from `limit_by_header`, `limit_by_param` | - | Configuration for the source of the rate limiting key value (URL parameter name) |
|
||||
| limit_keys | array of object | Required | - | Configuration for the rate limiting frequency based on matched key values |
|
||||
|
||||
| Name | Type | Requirement | Default Value | Description |
|
||||
| -------- | -------- | -------- | -------- | -------- |
|
||||
| key | string | Required | - | Value to match of the specific key |
|
||||
| query_per_second | number | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. | - | Number of requests allowed per second |
|
||||
| query_per_minute | number | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. | - | Number of requests allowed per minute |
|
||||
| query_per_hour | number | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. | - | Number of requests allowed per hour |
|
||||
| query_per_day | number | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. | - | Number of requests allowed per day |
|
||||
Explanation of each configuration field in `limit_keys`
|
||||
|
||||
# Configuration Samples
|
||||
| Name | Data Type | Required | Default Value | Description |
|
||||
|------------------|-----------|-----------------------------------------------------------------------------------------------------|---------------|---------------------------------------|
|
||||
| key | string | Required | - | Matched key value |
|
||||
| query_per_second | number | Optional, choose one from `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day` | - | Allowed number of requests per second |
|
||||
| query_per_minute | number | Optional, choose one from `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day` | - | Allowed number of requests per minute |
|
||||
| query_per_hour | number | Optional, choose one from `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day` | - | Allowed number of requests per hour |
|
||||
| query_per_day | number | Optional, choose one from `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day` | - | Allowed number of requests per day |
|
||||
|
||||
## Use query parameter `apikey` for rate-limiting
|
||||
## Configuration Examples
|
||||
### Identify request parameter apikey for differentiated rate limiting
|
||||
```yaml
|
||||
limit_by_param: apikey
|
||||
limit_keys:
|
||||
@@ -35,7 +40,7 @@ limit_keys:
|
||||
query_per_minute: 100
|
||||
```
|
||||
|
||||
## Use HTTP header parameter `x-ca-key` for rate-limiting
|
||||
### Identify request header x-ca-key for differentiated rate limiting
|
||||
```yaml
|
||||
limit_by_header: x-ca-key
|
||||
limit_keys:
|
||||
@@ -44,28 +49,3 @@ limit_keys:
|
||||
- key: 308239
|
||||
query_per_hour: 10
|
||||
```
|
||||
|
||||
## Enable rate-limiting for specific routes or domains
|
||||
```yaml
|
||||
# Use _rules_ field for fine-grained rule configurations
|
||||
_rules_:
|
||||
# Rule 1: Match by route name
|
||||
- _match_route_:
|
||||
- route-a
|
||||
- route-b
|
||||
limit_by_header: x-ca-key
|
||||
limit_keys:
|
||||
- key: 102234
|
||||
query_per_second: 10
|
||||
# Rule 2: Match by domain
|
||||
- _match_domain_:
|
||||
- "*.example.com"
|
||||
- test.com
|
||||
limit_by_header: x-ca-key
|
||||
limit_keys:
|
||||
- key: 102234
|
||||
query_per_second: 100
|
||||
```
|
||||
In the rule sample of `_match_route_`, `route-a` and `route-b` are the route names provided when creating a new gateway route. When the current route names matches the configuration, the rule following shall be applied.
|
||||
In the rule sample of `_match_domain_`, `*.example.com` and `test.com` are the domain names used for request matching. When the current domain name matches the configuration, the rule following shall be applied.
|
||||
All rules shall be checked following the order of items in the `_rules_` field, The first matched rule will be applied. All remained will be ignored.
|
||||
Reference in New Issue
Block a user