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.

Sign up for GitHub

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

docs: add plugin docs #38

Merged
merged 1 commit into from
Oct 19, 2022
Merged

docs: add plugin docs #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,13 @@

* [插件界面配置引导](plugin/plugin-configuring-guide.md)
* [percent-limit](plugin/percent-limit.md)
* [local-limiting](plugin/local-limiting.md)
* [static-downgrade](plugin/static-downgrade.md)
* [response-header-rewrite](plugin/response-header-rewrite.md)
* [ua-restriction](plugin/ua-restriction.md)
* [header-restriction](plugin/header-restriction.md)
* [referer-restriction](plugin/referer-restriction.md)
* [ip-restriction](plugin/ip-restriction.md)

## 问题定位

Expand Down
48 changes: 48 additions & 0 deletions docs/plugin/header-restriction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Header黑白名单

## 描述

`header-restriction`插件可以针对来携带不同请求头的请求进行黑名单或白名单限制

## 属性

| 名称 | 类型 | 必选项 | 范围 | 描述 |
|-------------------|---------|-----|---------------------------------------------------|------------------------------|
| kind | string | 是 | header-restriction | 插件类型（值固定） |
| type | integer | 是 | [0, 1] | Header黑白名单策略<br/>0:黑名单；1:白名单 |
| list[].header | string | 是 | length <= 200 | Header名 |
| list[].match_type | string | 是 | exact_match<br/>prefix_match<br/>safe_regex_match | Header黑白名单策略 |
| list[].value | string | 是 | length <= 200 | Header值 |

## 前置条件

以下curl命令中存在变量，使用前需要替换为真实环境数据，变量以`{{}}`符号包裹，例如`{{ 网关ID }}`需要根据网关的实际ID进行替换；创建插件命令中`PluginConfiguration`（插件配置）需要根据实际需要进行配置

## 创建

```shell
curl -XPOST -v -H "Content-Type:application/json" -d '{
"BindingObjectId": {{ 路由ID }},
"BindingObjectType": "routeRule",
"GwId": {{ 网关ID }},
"PluginConfiguration": "{\"type\":\"0\",\"list\":[{\"header\":\"blackHeader\",\"match_type\":\"exact_match\",\"value\":[\"blackHeaderValue\"]}],\"kind\":\"header-restriction\"}",
"PluginType": "header-restriction"
}' http://{{ hango-portal ip:port }}/gdashboard?Action=BindingPlugin&Version=2019-09-01
```

## 测试

```shell
## 修改如下请求的Header参数，与插件配置的一致，测试Header黑白名单效果
curl -v "http://{{ 网关IP }}/{{ 路由path }}" -H "host:{{ 网关关联域名 }}" -H "blackHeader:blackHeaderValue"
```

## 删除

```shell
curl -v -H "Content-Type:application/json" http://{{ hango-portal ip:port }}/gdashboard?PluginBindingInfoId={{ 插件ID }}&Action=UnbindingPlugin&Version=2019-09-01
```

## 界面配置方法

[插件界面配置方法引导](plugin-configuring-guide.md)
47 changes: 47 additions & 0 deletions docs/plugin/ip-restriction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# IP黑白名单

## 描述

`ip-restriction`插件可以针对来源于不同User-Agent（用户代理）的请求进行黑名单或白名单限制

## 属性

| 名称 | 类型 | 必选项 | 范围 | 描述 |
|------|----------|-----|----------------|--------------------------|
| kind | string | 是 | ip-restriction | 插件类型（值固定） |
| type | integer | 是 | [0, 1] | IP黑白名单策略<br/>0:黑名单；1:白名单 |
| list | []string | 是 | IP格式 | IP值 |


## 前置条件

以下curl命令中存在变量，使用前需要替换为真实环境数据，变量以`{{}}`符号包裹，例如`{{ 网关ID }}`需要根据网关的实际ID进行替换；创建插件命令中`PluginConfiguration`（插件配置）需要根据实际需要进行配置

## 创建

```shell
curl -XPOST -v -H "Content-Type:application/json" -d '{
"BindingObjectId": {{ 路由ID }},
"BindingObjectType": "routeRule",
"GwId": {{ 网关ID }},
"PluginConfiguration": "{\"type\":\"0\",\"list\":[\"192.168.2.101\",\"192.168.2.102\"],\"kind\":\"ip-restriction\"}",
"PluginType": "ip-restriction"
}' http://{{ hango-portal ip:port }}/gdashboard?Action=BindingPlugin&Version=2019-09-01
```

## 测试

```shell
## 基于如下请求，基于不同IP（携带请求头X-Forwarded-For）来源请求网关测试IP黑白名单插件
curl -v "http://{{ 网关IP }}/{{ 路由path }}" -H "host:{{ 网关关联域名 }}"
```

## 删除

```shell
curl -v -H "Content-Type:application/json" http://{{ hango-portal ip:port }}/gdashboard?PluginBindingInfoId={{ 插件ID }}&Action=UnbindingPlugin&Version=2019-09-01
```

## 界面配置方法

[插件界面配置方法引导](plugin-configuring-guide.md)
51 changes: 51 additions & 0 deletions docs/plugin/local-limiting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# 本地限流

## 描述

`local-limiting`插件可以实现基于网关实例级别的多维度流量

## 属性

| 名称 | 类型 | 必选项 | 范围 | 描述 |
|--------------------------------------|---------|-----|---------------------------------------------------|----------------|
| kind | string | 是 | local-limiting | 插件类型（值固定） |
| limit_by_list[].headers[].headerKey | string | 否 | length <= 200 | 限流匹配Header名 |
| limit_by_list[].headers[].match_type | string | 是 | exact_match<br/>prefix_match<br/>safe_regex_match | 限流请求Header匹配方式 |
| limit_by_list[].headers[].value | string | 是 | length <= 200 | 限流匹配Header值 |
| limit_by_list[].day | integer | 是 | \> 0 | 天维度允许通过的请求数量 |
| limit_by_list[].hour | integer | 是 | \> 0 | 时维度允许通过的请求数量 |
| limit_by_list[].minute | integer | 是 | \> 0 | 分维度允许通过的请求数量 |
| limit_by_list[].second | integer | 是 | \> 0 | 秒维度允许通过的请求数量 |

## 前置条件

以下curl命令中存在变量，使用前需要替换为真实环境数据，变量以`{{}}`符号包裹，例如`{{ 网关ID }}`需要根据网关的实际ID进行替换；创建插件命令中`PluginConfiguration`（插件配置）需要根据实际需要进行配置

## 创建

```shell
curl -XPOST -v -H "Content-Type:application/json" -d '{
"BindingObjectId": {{ 路由ID }},
"BindingObjectType": "routeRule",
"GwId": {{ 网关ID }},
"PluginConfiguration": "{\"limit_by_list\":[{\"headers\":[{\"headerKey\":\"limitHeader\",\"match_type\":\"exact_match\",\"value\":\"limitHeaderValue\"}],\"day\":4321,\"hour\":321,\"minute\":21,\"second\":1}],\"kind\":\"local-limiting\",\"name\":\"local-limiting\"}",
"PluginType": "local-limiting"
}' http://{{ hango-portal ip:port }}/gdashboard?Action=BindingPlugin&Version=2019-09-01
```

## 测试

```shell
## 如下命令展示了用命令调用3次请求的案例，可修改for中的请求次数，进行限流次数测试；可以为请求添加header进行限流请头求匹配测试
for((i=0;i<3;i++));do curl -v "http://{{ 网关IP }}/{{ 路由path }}" -H "host:{{ 网关关联域名 }}" -H "blackHeader:blackHeaderValue";done
```

## 删除

```shell
curl -v -H "Content-Type:application/json" http://{{ hango-portal ip:port }}/gdashboard?PluginBindingInfoId={{ 插件ID }}&Action=UnbindingPlugin&Version=2019-09-01
```

## 界面配置方法

[插件界面配置方法引导](plugin-configuring-guide.md)
48 changes: 48 additions & 0 deletions docs/plugin/referer-restriction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Referer黑白名单

## 描述

`referer-restriction`插件可以基于请头头Referer来针对来源的请求进行黑名单或白名单限制

## 属性

| 名称 | 类型 | 必选项 | 范围 | 描述 |
|-------------------|---------|-----|---------------------------------------------------|--------------------------|
| kind | string | 是 | referer-restriction | 插件类型（值固定） |
| type | integer | 是 | [0, 1] | Referer黑白名单策略<br/>0:黑名单；1:白名单 |
| list[].match_type | string | 是 | exact_match<br/>prefix_match<br/>safe_regex_match | Referer黑白名单策略 |
| list[].value | string | 是 | length <= 200 | Referer值 |


## 前置条件

以下curl命令中存在变量，使用前需要替换为真实环境数据，变量以`{{}}`符号包裹，例如`{{ 网关ID }}`需要根据网关的实际ID进行替换；创建插件命令中`PluginConfiguration`（插件配置）需要根据实际需要进行配置

## 创建

```shell
curl -XPOST -v -H "Content-Type:application/json" -d '{
"BindingObjectId": {{ 路由ID }},
"BindingObjectType": "routeRule",
"GwId": {{ 网关ID }},
"PluginConfiguration": "{\"type\":\"0\",\"list\":[{\"match_type\":\"exact_match\",\"value\":[\"deny\"]}],\"kind\":\"referer-restriction\"}",
"PluginType": "referer-restriction"
}' http://{{ hango-portal ip:port }}/gdashboard?Action=BindingPlugin&Version=2019-09-01
```

## 测试

```shell
## 修改如下请求的Referer参数，与插件配置的Referer值一致，测试黑白名单效果
curl -v "http://{{ 网关IP }}/{{ 路由path }}" -H "host:{{ 网关关联域名 }}" -H "Referer:xxx"
```

## 删除

```shell
curl -v -H "Content-Type:application/json" http://{{ hango-portal ip:port }}/gdashboard?PluginBindingInfoId={{ 插件ID }}&Action=UnbindingPlugin&Version=2019-09-01
```

## 界面配置方法

[插件界面配置方法引导](plugin-configuring-guide.md)