补充API信息，增加自定义IP数据库文档 (#85)

2024-07-29 08:37:34 +02:00
parent afe81f4d5d
commit 1ff2faaeeb
5 changed files with 272 additions and 0 deletions
@@ -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` 为对应关系。
+
 ## 使用案例

 ### 获取所有服务器信息
@@ -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
+```