jiazhizhong/higress
1
0
Fork 0
mirror of https://github.com/alibaba/higress.git synced 2026-06-09 04:37:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

update plugins doc (#1305)

Browse Source
This commit is contained in:
澄潭
2024-09-12 21:48:40 +08:00
committed by GitHub
parent 0f9113ed82
commit c7c4ae1da2
80 changed files with 7373 additions and 2368 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
plugins/wasm-go/extensions/geo-ip/README.md
View File

@@ -1,8 +1,20 @@
# 功能说明
---
title: IP 地理位置
keywords: [higress,geo ip]
description: IP 地理位置插件配置参考
---
## 功能说明
`geo-ip`本插件实现了通过用户ip查询出地理位置信息，然后通过请求属性和新添加的请求头把地理位置信息传递给后续插件。
# 配置字段
## 运行属性
插件执行阶段：`认证阶段`
插件执行优先级：`440`
## 配置字段
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| ip_protocol | string | 否 | ipv4 | 可选值：1. ipv4：只对ipv4用户请求查找地理位置信息，传递给后续插件。而ipv6用户的请求会跳过该插件，继续由后续插件处理。 2. ipv6：(未来实现后)只对ipv6用户查找地理位置信息，传递给后续插件。而ipv4用户的请求会跳过该插件，继续由后续插件处理。（目前是跳过插件，请求由后续插件处理。）
@@ -10,7 +22,7 @@
| ip_header_name | string | 否 | x-forwarded-for | 当`ip_source_type`为`header`时，指定自定义IP来源头 |
# 配置示例
## 配置示例
```yaml
ip_protocol: ipv4
@@ -18,7 +30,7 @@ ip_source_type: header
ip_header_name: X-Real-Ip
```
# 生成geoCidr.txt的说明
## 生成geoCidr.txt的说明
在generateCidr目录里包含的ip.merge.txt文件是github上ip2region项目的全世界的ip网段库。 ipRange2Cidr.go 是把ip网段转换成多个cidr的程序。转换出的cidr 和地理位置信息存在 /data/geoCidr.txt文件里。geo-ip插件会在Higress启动读配置阶段读取geoCidr.txt文件并且解析到radixtree数据结构的内存里，以便以后查询用户ip对应的地理位置信息。转换程序运行命令如下：
@@ -26,13 +38,5 @@ ip_header_name: X-Real-Ip
go run generateCidr/ipRange2Cidr.go
```
# property 的使用方式
## property 的使用方式
在geo-ip插件里调用proxywasm.SetProperty() 分别把country、city、province、isp设置进请求属性里，以便后续插件可以调用proxywasm.GetProperty()获取该请求的用户ip对应的地理信息。
# ip网段转换成cidr列表的单元测试
在 generateCidr 目录里的 ipRange2Cidr_test.go 是ip网段转换成cidr 列表的单元测试程序。在 generateCidr 目录里运行命令 go test 。通过的情况显示如下：
``bash
PASS
ok higress/plugins/wasm-go/extensions/geo-ip/generateCidr 0.018s
```

34
plugins/wasm-go/extensions/geo-ip/README_EN.md Normal file
View File

@@ -0,0 +1,34 @@
---
title: IP Geolocation
keywords: [higress,geo ip]
description: IP Geolocation Plugin Configuration Reference
---
## Function Description
The `geo-ip` plugin allows querying geographical location information based on the user's IP address, and then passes this geographical information to subsequent plugins through request attributes and newly added request headers.
## Runtime Properties
Plugin Execution Phase: `Authentication Phase`
Plugin Execution Priority: `440`
## Configuration Fields
| Name | Data Type | Requirement | Default Value | Description |
| -------- | ----------- | ----------- | ------------------ | ------------ |
| ip_protocol | string | No | ipv4 | Optional values: 1. ipv4: Only queries geographical location information for ipv4 user requests, passing it to subsequent plugins. Requests from ipv6 users will skip this plugin and be processed by later plugins. 2. ipv6: (To be implemented in the future) Only queries geographical location information for ipv6 users, passing it to subsequent plugins. Requests from ipv4 users will skip this plugin and be processed by later plugins. (Currently skips the plugin; requests are handled by subsequent plugins.) |
| ip_source_type | string | No | origin-source | Optional values: 1. Peer socket IP: `origin-source`; 2. Retrieved via header: `header` |
| ip_header_name | string | No | x-forwarded-for | When `ip_source_type` is `header`, specify the custom IP source header. |
## Configuration Example
```yaml
ip_protocol: ipv4
ip_source_type: header
ip_header_name: X-Real-Ip
```
## Explanation for Generating geoCidr.txt
The ip.merge.txt file included in the generateCidr directory is the global IP segment database from the ip2region project on GitHub. The ipRange2Cidr.go program converts IP segments into multiple CIDRs. The converted CIDRs and geographical location information are stored in the /data/geoCidr.txt file. The geo-ip plugin will read the geoCidr.txt file during the configuration stage when Higress starts and parse it into the radixtree data structure in memory for future queries of geographical location information corresponding to user IP addresses. The command to run the conversion program is as follows:
```bash
go run generateCidr/ipRange2Cidr.go
```
## Usage of Properties
In the geo-ip plugin, call proxywasm.SetProperty() to set country, city, province, and isp into request attributes so that subsequent plugins can use proxywasm.GetProperty() to obtain the geographical information corresponding to the user's IP for that request.