补充API信息，增加自定义IP数据库文档 (#85)
This commit is contained in:
UUBulb
GitHub
parent
afe81f4d5d
commit
1ff2faaeeb
@ -191,6 +191,7 @@ function getGuideSidebarZhCN() {
|
||||
{ text: '使用 Cloudflare Access 作为 OAuth2 提供方', link: '/guide/q8.html' },
|
||||
{ text: '启用 GPU 监控', link: '/guide/q9.html' },
|
||||
{ text: '启用 OIDC 认证', link: '/guide/q10.html' },
|
||||
{ text: '自定义 IP 地理位置数据库', link: '/guide/q11.html' },
|
||||
]
|
||||
},
|
||||
{
|
||||
@ -264,6 +265,7 @@ function getGuideSidebarEnUS() {
|
||||
{ text: 'Use Cloudflare Access As OAuth2 Provider', link: '/en_US/guide/q8.html' },
|
||||
{ text: 'Enable GPU monitoring', link: '/en_US/guide/q9.html' },
|
||||
{ text: 'Enable OIDC authorization', link: '/en_US/guide/q10.html' },
|
||||
{ text: 'Customize GeoIP database', link: '/en_US/guide/q11.html' },
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
@ -175,6 +175,72 @@ Example response:
|
||||
}
|
||||
```
|
||||
|
||||
### Get ICMP Ping / TCPing monitor value
|
||||
|
||||
This API does not require authentication, except for servers with `HideForGuest` option enabled.
|
||||
|
||||
Request:
|
||||
```
|
||||
GET /api/v1/monitor/{id}
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `id` (required): ServerID, must be an positive integer.
|
||||
|
||||
Example response:
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"result": [
|
||||
{
|
||||
"monitor_id": 1,
|
||||
"server_id": 1,
|
||||
"monitor_name": "Monitor1",
|
||||
"server_name": "Server1",
|
||||
"created_at": [
|
||||
1722142860000,
|
||||
1722142920000
|
||||
],
|
||||
"avg_delay": [
|
||||
68.2275,
|
||||
70.1129
|
||||
]
|
||||
},
|
||||
{
|
||||
"monitor_id": 2,
|
||||
"server_id": 1,
|
||||
"monitor_name": "Monitor2",
|
||||
"server_name": "Server1",
|
||||
"created_at": [
|
||||
1722142860000,
|
||||
1722142920000
|
||||
],
|
||||
"avg_delay": [
|
||||
66.656,
|
||||
68.2153
|
||||
]
|
||||
},
|
||||
{
|
||||
"monitor_id": 3,
|
||||
"server_id": 1,
|
||||
"monitor_name": "Monitor3",
|
||||
"server_name": "Server1",
|
||||
"created_at": [
|
||||
1722142860000,
|
||||
1722142920000
|
||||
],
|
||||
"avg_delay": [
|
||||
61.4525,
|
||||
62.342
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note: `created_at` corresponds with `avg_delay`.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Get All Server Information
|
||||
|
||||
69
docs/en_US/guide/q11.md
Normal file
69
docs/en_US/guide/q11.md
Normal file
@ -0,0 +1,69 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
# Customize GeoIP database
|
||||
|
||||
Dashboard v0.18.3+ uses an embedded GeoIP database to query IP locations. An IPinfo format mmdb database is required to be placed at `pkg/geoip/geoip.db` to compile the Dashboard with working GeoIP queries.
|
||||
|
||||
An IPinfo format mmdb is constructed by those fields:
|
||||
|
||||
- An IP subnet as an entry
|
||||
- `continent`：Continent code
|
||||
- `continent_name`：Continent name
|
||||
- `country`：Country code
|
||||
- `country_name`：Country name
|
||||
|
||||
Dashboard only requires the `country` field, and other fields can be left empty.
|
||||
|
||||
## Editing database
|
||||
|
||||
It is recommended to use `mmdbwriter` and `maxminddb-golang` libraries for editing mmdb databases as of now.
|
||||
|
||||
If your goal is to correct geographic information, it is recommended to modify directly based on the original IPinfo database. For similar operations, you can refer to the [sing-geoip](https://github.com/SagerNet/sing-geoip) project.
|
||||
|
||||
Using the correction of IPinfo data as an example, you need to use the `ReplaceWith` inserter (which is the default value) and write the `mmdbtype.Map` information:
|
||||
|
||||
```go
|
||||
subnet := &net.IPNet{
|
||||
IP: net.ParseIP("114.5.1.4")
|
||||
Mask: net.CIDRMask(32, 32)
|
||||
}
|
||||
countryMap := make(map[mmdbtype.String]mmdbtype.String)
|
||||
|
||||
countryMap[mmdbtype.String("country")] = mmdbtype.String("JP")
|
||||
|
||||
if err := writer.Insert(subnet, mmdbtype.Map(countryMap)); err != nil {
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
A `writer` is an instance of `*mmdbwriter.Tree` and needs to be created using the `mmdbwriter.New` method. The specific operations and the process of inserting other fields are not mentioned here.
|
||||
|
||||
After writing the database information to a file, you can use the `mmdbinspect` CLI tool to test the database information. For example:
|
||||
|
||||
```shell
|
||||
$ mmdbinspect -db ./country.mmdb 114.5.1.4
|
||||
[
|
||||
{
|
||||
"Database": "./country.mmdb",
|
||||
"Records": [
|
||||
{
|
||||
"Network": "114.5.1.4/32",
|
||||
"Record": {
|
||||
"continent": "AS",
|
||||
"continent_name": "Asia",
|
||||
"country": "JP",
|
||||
"country_name": "Japan"
|
||||
}
|
||||
}
|
||||
],
|
||||
"Lookup": "114.5.1.4"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Once the format and information are confirmed to be correct, the database can be used for compiling the Dashboard. Afterwards, you can test if the query API is working correctly using `grpcurl` or similar tools:
|
||||
|
||||
```shell
|
||||
grpcurl -proto ./nezha/proto/nezha.proto -plaintext -H 'client_secret: test' -d '{"ip": "114.5.1.4"}' 127.0.0.1:5555 proto.NezhaService/LookupGeoIP
|
||||
```
|
||||
@ -175,6 +175,72 @@ GET /api/v1/server/details?id=&tag=
|
||||
}
|
||||
```
|
||||
|
||||
### 获取 ICMP Ping / TCPing 数据
|
||||
|
||||
此 API 无需认证。（除限制游客访问的服务器）
|
||||
|
||||
请求：
|
||||
```
|
||||
GET /api/v1/monitor/{id}
|
||||
```
|
||||
|
||||
参数：
|
||||
- `id`（必填）：ServerID，只能是一个正整数。
|
||||
|
||||
返回示例：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"result": [
|
||||
{
|
||||
"monitor_id": 1,
|
||||
"server_id": 1,
|
||||
"monitor_name": "Monitor1",
|
||||
"server_name": "Server1",
|
||||
"created_at": [
|
||||
1722142860000,
|
||||
1722142920000
|
||||
],
|
||||
"avg_delay": [
|
||||
68.2275,
|
||||
70.1129
|
||||
]
|
||||
},
|
||||
{
|
||||
"monitor_id": 2,
|
||||
"server_id": 1,
|
||||
"monitor_name": "Monitor2",
|
||||
"server_name": "Server1",
|
||||
"created_at": [
|
||||
1722142860000,
|
||||
1722142920000
|
||||
],
|
||||
"avg_delay": [
|
||||
66.656,
|
||||
68.2153
|
||||
]
|
||||
},
|
||||
{
|
||||
"monitor_id": 3,
|
||||
"server_id": 1,
|
||||
"monitor_name": "Monitor3",
|
||||
"server_name": "Server1",
|
||||
"created_at": [
|
||||
1722142860000,
|
||||
1722142920000
|
||||
],
|
||||
"avg_delay": [
|
||||
61.4525,
|
||||
62.342
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
注： `created_at` 和 `avg_delay` 为对应关系。
|
||||
|
||||
## 使用案例
|
||||
|
||||
### 获取所有服务器信息
|
||||
|
||||
69
docs/guide/q11.md
Normal file
69
docs/guide/q11.md
Normal file
@ -0,0 +1,69 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
# 自定义 IP 地理位置数据库
|
||||
|
||||
Dashboard v0.18.3+ 采用离线数据库获取 GeoIP 信息，如需编译正确显示地理位置信息的 Dashboard，必须在 `pkg/geoip/geoip.db` 路径下放置符合 IPinfo 格式的 mmdb 数据库。
|
||||
|
||||
IPinfo 格式包含以下字段：
|
||||
|
||||
- 作为条目的 IP 子网
|
||||
- `continent`：大洲代码
|
||||
- `continent_name`：大洲名称
|
||||
- `country`：国家/地区代码
|
||||
- `country_name`：国家/地区名称
|
||||
|
||||
其中 Dashboard 只需要用到 `country` 信息，其它字段可留空。
|
||||
|
||||
## 编辑数据库
|
||||
|
||||
目前推荐使用 MaxMind 官方使用的 `mmdbwriter` 和 `maxminddb-golang` 这两个库进行 mmdb 的编辑操作。
|
||||
|
||||
如果你的主要目的是为了校正地理信息，建议直接在 IPinfo 原版数据库的基础上修改。类似的操作可以参考 [sing-geoip](https://github.com/SagerNet/sing-geoip) 项目。
|
||||
|
||||
这里以校正 IPinfo 数据为例，你需要使用 `ReplaceWith` inserter（此为默认值）并写入 `mmdbtype.Map` 信息：
|
||||
|
||||
```go
|
||||
subnet := &net.IPNet{
|
||||
IP: net.ParseIP("114.5.1.4")
|
||||
Mask: net.CIDRMask(32, 32)
|
||||
}
|
||||
countryMap := make(map[mmdbtype.String]mmdbtype.String)
|
||||
|
||||
countryMap[mmdbtype.String("country")] = mmdbtype.String("JP")
|
||||
|
||||
if err := writer.Insert(subnet, mmdbtype.Map(countryMap)); err != nil {
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
其中 `writer` 为一个 `*mmdbwriter.Tree` 的实例，需要通过 `mmdbwriter.New` 方法创建。具体操作和插入其它字段的过程不再赘述。
|
||||
|
||||
编辑完成并将数据库信息写入到文件后，可以使用 `mmdbinspect` 命令行工具测试数据库信息。例如：
|
||||
|
||||
```shell
|
||||
$ mmdbinspect -db ./country.mmdb 114.5.1.4
|
||||
[
|
||||
{
|
||||
"Database": "./country.mmdb",
|
||||
"Records": [
|
||||
{
|
||||
"Network": "114.5.1.4/32",
|
||||
"Record": {
|
||||
"continent": "AS",
|
||||
"continent_name": "Asia",
|
||||
"country": "JP",
|
||||
"country_name": "Japan"
|
||||
}
|
||||
}
|
||||
],
|
||||
"Lookup": "114.5.1.4"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
确定格式、信息无误后便可用于 Dashboard 编译。之后可通过 `grpcurl` 或类似工具测试查询 API 是否工作正常：
|
||||
|
||||
```shell
|
||||
grpcurl -proto ./nezha/proto/nezha.proto -plaintext -H 'client_secret: test' -d '{"ip": "114.5.1.4"}' 127.0.0.1:5555 proto.NezhaService/LookupGeoIP
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user