Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: plugin doc #242

Merged
merged 2 commits into from
Jun 25, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: AI 内容审核
title: AI 内容安全
keywords: [ higress, ai]
description: AI 内容审核插件配置参考
description: AI 内容安全插件配置参考
---

## 功能说明
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: AI 限流
title: AI Token 限流
keywords: [higress, ai, rate-limit]
description: AI 限流插件配置参考
description: AI Token 限流插件配置参考
---

## 功能说明
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,6 @@ description: Basic 认证插件配置参考
## 功能说明
`basic-auth` 插件实现了基于 HTTP Basic Auth 标准进行认证鉴权的功能。

## 运行属性

- 插件执行阶段:`认证阶段`
- 插件执行优先级:`320`

## 配置字段

### 全局配置
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,6 @@ description: JWT 认证插件配置参考

`jwt-auth` 插件实现了基于 JWT(JSON Web Tokens) 进行认证鉴权的功能,支持从 HTTP 请求的 URL 参数、请求头、Cookie 字段解析 JWT,同时验证该 Token 是否有权限访问。

## 运行属性

- 插件执行阶段:`认证阶段`
- 插件执行优先级:`340`

## 配置字段

### 全局配置
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,7 @@ description: Bot Detect 插件配置参考

`bot-detect` 插件可以用于识别并阻止互联网爬虫对站点资源的爬取。

## 运行属性

- 插件执行阶段:`鉴权阶段`
- 插件执行优先级:`310`

### 配置字段
## 配置字段

| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,6 @@ description: WAF 防护插件配置参考

开源版 WAF 插件,支持基于 OWASP ModSecurity Core Rule Set (CRS) 的 WAF 规则配置。

## 运行属性

- 插件执行阶段:`授权阶段`
- 插件执行优先级:`330`

## 配置字段

| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,23 +61,23 @@ description: 基于 Key 集群限流插件配置参考
```yaml
rule_name: default_rule
rule_items:
- limit_by_param: apikey
limit_keys:
- key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
query_per_minute: 10
- key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
query_per_hour: 100
- limit_by_per_param: apikey
limit_keys:
# 正则表达式,匹配以 a 开头的所有字符串,每个 apikey 对应的请求 10qds
- key: "regexp:^a.*"
query_per_second: 10
# 正则表达式,匹配以 b 开头的所有字符串,每个 apikey 对应的请求 100qd
- key: "regexp:^b.*"
query_per_minute: 100
# 兜底用,匹配所有请求,每个 apikey 对应的请求 1000qdh
- key: "*"
query_per_hour: 1000
- limit_by_param: apikey
limit_keys:
- key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
query_per_minute: 10
- key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
query_per_hour: 100
- limit_by_per_param: apikey
limit_keys:
# 正则表达式,匹配以 a 开头的所有字符串,每个 apikey 对应的请求 10qds
- key: "regexp:^a.*"
query_per_second: 10
# 正则表达式,匹配以 b 开头的所有字符串,每个 apikey 对应的请求 100qd
- key: "regexp:^b.*"
query_per_minute: 100
# 兜底用,匹配所有请求,每个 apikey 对应的请求 1000qdh
- key: "*"
query_per_hour: 1000
redis:
service_name: redis.static
show_limit_quota_header: true
Expand All @@ -88,23 +88,23 @@ show_limit_quota_header: true
```yaml
rule_name: default_rule
rule_items:
- limit_by_header: x-ca-key
limit_keys:
- key: 102234
query_per_minute: 10
- key: 308239
query_per_hour: 10
- limit_by_per_header: x-ca-key
limit_keys:
# 正则表达式,匹配以 a 开头的所有字符串,每个 apikey 对应的请求 10qds
- key: "regexp:^a.*"
query_per_second: 10
# 正则表达式,匹配以b开头的所有字符串,每个 apikey 对应的请求 100qd
- key: "regexp:^b.*"
query_per_minute: 100
# 兜底用,匹配所有请求,每个 apikey 对应的请求 1000qdh
- key: "*"
query_per_hour: 1000
- limit_by_header: x-ca-key
limit_keys:
- key: 102234
query_per_minute: 10
- key: 308239
query_per_hour: 10
- limit_by_per_header: x-ca-key
limit_keys:
# 正则表达式,匹配以 a 开头的所有字符串,每个 apikey 对应的请求 10qds
- key: "regexp:^a.*"
query_per_second: 10
# 正则表达式,匹配以b开头的所有字符串,每个 apikey 对应的请求 100qd
- key: "regexp:^b.*"
query_per_minute: 100
# 兜底用,匹配所有请求,每个 apikey 对应的请求 1000qdh
- key: "*"
query_per_hour: 1000
redis:
service_name: redis.static
show_limit_quota_header: true
Expand All @@ -115,17 +115,17 @@ show_limit_quota_header: true
```yaml
rule_name: default_rule
rule_items:
- limit_by_per_ip: from-header-x-forwarded-for
limit_keys:
# 精确 ip
- key: 1.1.1.1
query_per_day: 10
# ip 段,符合这个 ip 段的 ip,每个 ip 100qpd
- key: 1.1.1.0/24
query_per_day: 100
# 兜底用,即默认每个 ip 1000 qpd
- key: 0.0.0.0/0
query_per_day: 1000
- limit_by_per_ip: from-header-x-forwarded-for
limit_keys:
# 精确 IP
- key: 1.1.1.1
query_per_day: 10
# IP 段,符合这个 IP 段的 IP,每个 IP 100qpd
- key: 1.1.1.0/24
query_per_day: 100
# 兜底用,即默认每个 IP 1000 qpd
- key: 0.0.0.0/0
query_per_day: 1000
redis:
service_name: redis.static
show_limit_quota_header: true
Expand All @@ -136,23 +136,23 @@ show_limit_quota_header: true
```yaml
rule_name: default_rule
rule_items:
- limit_by_consumer: ''
limit_keys:
- key: consumer1
query_per_second: 10
- key: consumer2
query_per_hour: 100
- limit_by_per_consumer: ''
limit_keys:
# 正则表达式,匹配以 a 开头的所有字符串,每个 consumer 对应的请求 10qds
- key: "regexp:^a.*"
query_per_second: 10
# 正则表达式,匹配以 b 开头的所有字符串,每个 consumer 对应的请求 100qd
- key: "regexp:^b.*"
query_per_minute: 100
# 兜底用,匹配所有请求,每个 consumer 对应的请求 1000qdh
- key: "*"
query_per_hour: 1000
- limit_by_consumer: ''
limit_keys:
- key: consumer1
query_per_second: 10
- key: consumer2
query_per_hour: 100
- limit_by_per_consumer: ''
limit_keys:
# 正则表达式,匹配以 a 开头的所有字符串,每个 consumer 对应的请求 10qds
- key: "regexp:^a.*"
query_per_second: 10
# 正则表达式,匹配以 b 开头的所有字符串,每个 consumer 对应的请求 100qd
- key: "regexp:^b.*"
query_per_minute: 100
# 兜底用,匹配所有请求,每个 consumer 对应的请求 1000qdh
- key: "*"
query_per_hour: 1000
redis:
service_name: redis.static
show_limit_quota_header: true
Expand All @@ -163,26 +163,26 @@ show_limit_quota_header: true
```yaml
rule_name: default_rule
rule_items:
- limit_by_cookie: key1
limit_keys:
- key: value1
query_per_minute: 10
- key: value2
query_per_hour: 100
- limit_by_per_cookie: key1
limit_keys:
# 正则表达式,匹配以 a 开头的所有字符串,每个 cookie 中的 value 对应的请求 10qds
- key: "regexp:^a.*"
query_per_second: 10
# 正则表达式,匹配以 b 开头的所有字符串,每个 cookie 中的 value 对应的请求 100qd
- key: "regexp:^b.*"
query_per_minute: 100
# 兜底用,匹配所有请求,每个 cookie 中的 value 对应的请求 1000qdh
- key: "*"
query_per_hour: 1000
- limit_by_cookie: key1
limit_keys:
- key: value1
query_per_minute: 10
- key: value2
query_per_hour: 100
- limit_by_per_cookie: key1
limit_keys:
# 正则表达式,匹配以 a 开头的所有字符串,每个 cookie 中的 value 对应的请求 10qds
- key: "regexp:^a.*"
query_per_second: 10
# 正则表达式,匹配以 b 开头的所有字符串,每个 cookie 中的 value 对应的请求 100qd
- key: "regexp:^b.*"
query_per_minute: 100
# 兜底用,匹配所有请求,每个 cookie 中的 value 对应的请求 1000qdh
- key: "*"
query_per_hour: 1000
rejected_code: 200
rejected_msg: '{"code":-1,"msg":"Too many requests"}'
redis:
service_name: redis.static
show_limit_quota_header: true
```
```
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,7 @@ description: IP 限制插件配置参考

## 功能说明

`ip-restriction` 插件可以通过将 IP 地址列入白名单或黑名单来限制对服务或路由的访问.支持对单个 IP 地址、多个 IP 地址和类似
10.10.10.0/24 的 CIDR 范围的限制。
`ip-restriction` 插件可以通过将 IP 地址列入白名单或黑名单来限制对服务或路由的访问。支持对单个 IP 地址、多个 IP 地址和类似 10.10.10.0/24 的 CIDR 范围的限制。

## 配置说明

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,6 @@ description: Key 限流插件配置参考

`key-rate-limit` 插件实现了基于特定键值实现限流,键值来源可以是 URL 参数、HTTP 请求头。

## 运行属性

- 插件执行阶段:`默认阶段`
- 插件执行优先级:`10`


## 配置字段

| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -72,26 +72,27 @@ curl http://exmaple.com -d 'hello world'
### 对特定路由或域名开启

```yaml
# 使用 _rules_ 字段进行细粒度规则配置
_rules_:
# 规则一:按路由名称匹配生效
- _match_route_:
- route-a
- route-b
# 使用 matchRules 字段进行细粒度规则配置
matchRules:
# 规则一:按 Ingress 名称匹配生效
- ingress:
- default/foo
- default/bar
block_bodies:
- "hello world"
# 规则二:按域名匹配生效
- _match_domain_:
- domain:
- "*.example.com"
- test.com
block_urls:
- "swagger.html"
block_bodies:
- "hello world"
```
此例 `_match_route_` 中指定的 `route-a` 和 `route-b` 即在创建网关路由时填写的路由名称,当匹配到这两个路由时,将使用此段配置;
此例 `_match_domain_` 中指定的 `*.example.com` 和 `test.com` 用于匹配请求的域名,当发现域名匹配时,将使用此段配置;
配置的匹配生效顺序,将按照 `_rules_` 下规则的排列顺序,匹配第一个规则后生效对应配置,后续规则将被忽略。

此例 `ingress` 中指定的 `default/foo` 和 `default/bar` 对应 default 命名空间下名为 foo 和 bar 的 Ingress,当匹配到这两个 Ingress 时,将使用此段配置;
此例 `domain` 中指定的 `*.example.com` 和 `test.com` 用于匹配请求的域名,当发现域名匹配时,将使用此段配置;
配置的匹配生效顺序,将按照 `matchRules` 下规则的排列顺序,匹配第一个规则后生效对应配置,后续规则将被忽略。

## 请求 Body 大小限制

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ description: 请求/响应转换插件配置参考

## 配置字段

| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| :----: | :----: | :----: | :----: | -------- |
| reqRules | string | 选填,reqRules和respRules至少填一个 | - | 请求转换器配置,指定转换操作类型以及请求头、请求查询参数、请求体的转换规则 |
| respRules | string | 选填,reqRules和respRules至少填一个 | - | 响应转换器配置,指定转换操作类型以及响应头、响应体的转换规则 |
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| :----: | :----: |:-----------------------------:| :----: | -------- |
| reqRules | string | 选填,reqRules 和 respRules 至少填一个 | - | 请求转换器配置,指定转换操作类型以及请求头、请求查询参数、请求体的转换规则 |
| respRules | string | 选填,reqRules 和 respRules 至少填一个 | - | 响应转换器配置,指定转换操作类型以及响应头、响应体的转换规则 |

`reqRules` 和 `respRules` 中每一项的配置字段说明如下:

Expand Down Expand Up @@ -536,7 +536,7 @@ reqRules:
curl localhost -d '{"userId":12, "userName":"johnlanni"}' -H 'content-type:application/json'
```

将从 json 中提取出 `userId` 字段的值,设置到 `x-user-id` 中,后端服务收到的请求头将增加:`x-usr-id: 12`。
将从 JSON 中提取出 `userId` 字段的值,设置到 `x-user-id` 中,后端服务收到的请求头将增加:`x-usr-id: 12`。

因为在插件新增这个 Header 后,网关将重新计算路由,所以可以实现网关路由配置根据这个请求头来匹配路由到特定的目标服务。

Expand All @@ -553,9 +553,9 @@ curl localhost -d 'userId=12&userName=johnlanni'

### JSON Path 支持

可以根据 [GJSON Path 语法](https://github.com/tidwall/gjson/blob/master/SYNTAX.md),从复杂的 json 中提取出字段。
可以根据 [GJSON Path 语法](https://github.com/tidwall/gjson/blob/master/SYNTAX.md),从复杂的 JSON 中提取出字段。

比较常用的操作举例,对于以下 json:
比较常用的操作举例,对于以下 JSON:

```json
{
Expand Down Expand Up @@ -584,7 +584,7 @@ friends.1 {"first": "Roger", "last": "Craig", "age": 68}
friends.1.first "Roger"
```

现在如果想从上面这个 json 格式的 body 中提取出 friends 中第二项的 first 字段,来设置到 Header `x-first-name` 中,同时抽取 last 字段,来设置到 Header `x-last-name` 中,则可以使用这份插件配置:
现在如果想从上面这个 JSON 格式的 body 中提取出 friends 中第二项的 first 字段,来设置到 Header `x-first-name` 中,同时抽取 last 字段,来设置到 Header `x-last-name` 中,则可以使用这份插件配置:

```yaml
reqRules:
Expand Down
2 changes: 1 addition & 1 deletion sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ const sidebars = {
{
type: 'category',
label: 'Authentication Plugins',
items: ['plugins/authentication/basic-auth', 'plugins/authentication/key-auth', 'plugins/authentication/oidc', 'plugins/authentication/jwt-auth', 'plugins/authentication/hmac-auth', 'plugins/authentication/simple-jwt-auth']
items: ['plugins/authentication/basic-auth', 'plugins/authentication/key-auth', 'plugins/authentication/oidc', 'plugins/authentication/jwt-auth', 'plugins/authentication/hmac-auth']
},
{
"type": "category",
Expand Down
Loading