docs: add plugin docs (#38)

Signed-off-by: yutao04 <[email protected]> Signed-off-by: yutao04 <[email protected]>
hango-io · Oct 19, 2022 · 6ea6972 · 6ea6972
1 parent 830841b
commit 6ea6972
Show file tree

Hide file tree

Showing 5 changed files with 198 additions and 0 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -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)
 
 ## 问题定位
 

diff --git a/docs/plugin/header-restriction.md b/docs/plugin/header-restriction.md
@@ -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)
diff --git a/docs/plugin/ip-restriction.md b/docs/plugin/ip-restriction.md
@@ -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)
diff --git a/docs/plugin/local-limiting.md b/docs/plugin/local-limiting.md
@@ -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)
diff --git a/docs/plugin/referer-restriction.md b/docs/plugin/referer-restriction.md
@@ -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)