2ee8cf85d6
* add example for "Automatic Node Registration" * update script url --------- Co-authored-by: uubulb <uub@kuzu.uk>
393 lines
10 KiB
Markdown
393 lines
10 KiB
Markdown
---
|
||
outline: deep
|
||
---
|
||
|
||
# API 接口
|
||
|
||
**哪吒监控支持使用 API 接口查询面板中 Agent 的状态信息**
|
||
|
||
## 创建 Token
|
||
|
||
哪吒面板的 API 接口允许使用 Token 认证与 Cookies 认证。要新建一个 Token，在进入管理面板后，点击右上角的头像，选择 “API Token”，进入 Token 管理页面。点击 “API Token”，自定义备注后，点击 “添加”。
|
||
|
||
如需删除一个 Token，请选择相应的 Token，点击右侧的删除图标。
|
||
|
||
::: warning
|
||
Token 是 API 接口的鉴权凭据，它对你的面板的信息安全非常重要，请不要泄漏你的 Token 给他人。
|
||
:::
|
||
|
||
## 认证方式
|
||
|
||
确保在请求头中包含 `Authorization: Token` 进行身份认证。
|
||
|
||
Token 认证方式：
|
||
```
|
||
Request Headers:
|
||
Authorization: Token
|
||
```
|
||
|
||
## 使用说明
|
||
|
||
::: warning
|
||
下面示例中的负数时间戳为（0000-00-00），目前表示 Dashboard 上线后该 Agent 从未汇报过，但不建议用正负性判断状态。
|
||
:::
|
||
|
||
::: tip
|
||
**请求方式为 `GET`，返回格式为 `JSON`**
|
||
:::
|
||
|
||
### 获取服务器列表
|
||
|
||
请求：
|
||
```
|
||
GET /api/v1/server/list?tag=
|
||
```
|
||
|
||
参数：
|
||
- `tag`（可选）：ServerTag 是服务器的分组，提供此参数则仅查询该分组中的服务器。
|
||
|
||
返回示例：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"result": [
|
||
{
|
||
"id": 1,
|
||
"name": "Server1",
|
||
"tag": "Tag1",
|
||
"last_active": 1653014667,
|
||
"ipv4": "1.1.1.1",
|
||
"ipv6": "",
|
||
"valid_ip": "1.1.1.1"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "Server2",
|
||
"tag": "Tag2",
|
||
"last_active": -62135596800,
|
||
"ipv4": "",
|
||
"ipv6": "",
|
||
"valid_ip": ""
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 获取服务器详情
|
||
|
||
请求：
|
||
```
|
||
GET /api/v1/server/details?id=&tag=
|
||
```
|
||
|
||
参数：
|
||
- `id`（可选）：ServerID，多个 ID 以逗号分隔，提供此参数则查询该 ID 对应的服务器，同时无视 `tag` 参数。
|
||
- `tag`（可选）：ServerTag，提供此参数则仅查询该分组下的服务器。
|
||
|
||
返回示例：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"result": [
|
||
{
|
||
"id": 1,
|
||
"name": "Server1",
|
||
"tag": "Tag1",
|
||
"last_active": 1653015042,
|
||
"ipv4": "1.1.1.1",
|
||
"ipv6": "",
|
||
"valid_ip": "1.1.1.1",
|
||
"host": {
|
||
"Platform": "darwin",
|
||
"PlatformVersion": "12.3.1",
|
||
"CPU": [
|
||
"Apple M1 Pro 1 Physical Core"
|
||
],
|
||
"MemTotal": 17179869184,
|
||
"DiskTotal": 2473496842240,
|
||
"SwapTotal": 0,
|
||
"Arch": "arm64",
|
||
"Virtualization": "",
|
||
"BootTime": 1652683962,
|
||
"CountryCode": "hk",
|
||
"Version": ""
|
||
},
|
||
"status": {
|
||
"CPU": 17.33,
|
||
"MemUsed": 14013841408,
|
||
"SwapUsed": 0,
|
||
"DiskUsed": 2335048912896,
|
||
"NetInTransfer": 2710273234,
|
||
"NetOutTransfer": 695454765,
|
||
"NetInSpeed": 10806,
|
||
"NetOutSpeed": 5303,
|
||
"Uptime": 331080,
|
||
"Load1": 5.23,
|
||
"Load5": 4.87,
|
||
"Load15": 3.99,
|
||
"TcpConnCount": 195,
|
||
"UdpConnCount": 70,
|
||
"ProcessCount": 437
|
||
}
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "Server2",
|
||
"tag": "Tag2",
|
||
"last_active": -62135596800,
|
||
"ipv4": "",
|
||
"ipv6": "",
|
||
"valid_ip": "",
|
||
"host": {
|
||
"Platform": "",
|
||
"PlatformVersion": "",
|
||
"CPU": null,
|
||
"MemTotal": 0,
|
||
"DiskTotal": 0,
|
||
"SwapTotal": 0,
|
||
"Arch": "",
|
||
"Virtualization": "",
|
||
"BootTime": 0,
|
||
"CountryCode": "",
|
||
"Version": ""
|
||
},
|
||
"status": {
|
||
"CPU": 0,
|
||
"MemUsed": 0,
|
||
"SwapUsed": 0,
|
||
"DiskUsed": 0,
|
||
"NetInTransfer": 0,
|
||
"NetOutTransfer": 0,
|
||
"NetInSpeed": 0,
|
||
"NetOutSpeed": 0,
|
||
"Uptime": 0,
|
||
"Load1": 0,
|
||
"Load5": 0,
|
||
"Load15": 0,
|
||
"TcpConnCount": 0,
|
||
"UdpConnCount": 0,
|
||
"ProcessCount": 0
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 获取 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` 为对应关系。
|
||
|
||
### 自动注册节点
|
||
|
||
说明: 用于自动化注册节点的脚本，示例代码详见下文。
|
||
|
||
参考: [https://github.com/naiba/nezha/pull/472](https://github.com/naiba/nezha/pull/472)
|
||
|
||
```http
|
||
POST /api/v1/server/register?simple=1
|
||
```
|
||
|
||
参数:
|
||
|
||
- `simple`:(可选) 指定返回数据的格式。
|
||
- 当设置为 `simple=1`或者`simple=true` 时，返回的数据仅包含 Token 字符串（如 `8GYwaxYuLfU7zl7ndC`）。
|
||
- 其他则返回完整的 JSON 对象：`{"code": 200, "message": "Server created successfully","secret": "8GYwaxYuLfU7zl7ndC"}`
|
||
|
||
请求体 (Payload):
|
||
|
||
你可以设置为空内容(`{}`), 然后nezha面板会使用默认值进行填充
|
||
- `Name`: 默认是节点的IP
|
||
- `Tag`: 默认是 "AutoRegister".
|
||
- `Note`:默认是 "".
|
||
- `HideForGuest`: 默认是 "on".
|
||
|
||
你也可以设置自己的请求参数:
|
||
```json
|
||
{
|
||
"Name": "abcd", // 节点名称
|
||
"Tag": "", // 标签，可选
|
||
"Note": "", // 备注信息，可选
|
||
"HideForGuest": "on" // 是否对访客隐藏
|
||
}
|
||
```
|
||
|
||
## 使用案例
|
||
|
||
### 获取所有服务器信息
|
||
|
||
```python
|
||
import requests
|
||
|
||
url = "http://your-dashboard/api/v1/server/list"
|
||
headers = {
|
||
"Authorization": "your_token"
|
||
}
|
||
|
||
response = requests.get(url, headers=headers)
|
||
data = response.json()
|
||
|
||
for server in data['result']:
|
||
print(f"Server Name: {server['name']}, Last Active: {server['last_active']}, IP: {server['valid_ip']}")
|
||
```
|
||
|
||
### 获取特定服务器详情
|
||
|
||
```python
|
||
import requests
|
||
|
||
server_id = 1 # 替换为你的服务器ID
|
||
url = f"http://your-dashboard/api/v1/server/details?id={server_id}"
|
||
headers = {
|
||
"Authorization": "your_token"
|
||
}
|
||
|
||
response = requests.get(url, headers=headers)
|
||
data = response.json()
|
||
|
||
server = data['result'][0]
|
||
print(f"Server Name: {server['name']}")
|
||
print(f"CPU Usage: {server['status']['CPU']}%")
|
||
print(f"Memory Used: {server['status']['MemUsed']} bytes")
|
||
print(f"Disk Used: {server['status']['DiskUsed']} bytes")
|
||
print(f"Network In Speed: {server['status']['NetInSpeed']} bytes/s")
|
||
print(f"Network Out Speed: {server['status']['NetOutSpeed']} bytes/s")
|
||
```
|
||
|
||
通过以上示例代码，可以轻松获取和处理服务器的状态信息，从而实现自动化监控和管理。
|
||
|
||
### 自动注册节点
|
||
1. 创建文件 `nezha_register.sh`，将以下内容复制到文件中：
|
||
```bash
|
||
#!/bin/bash
|
||
|
||
# Exit if NEZHA_TOKEN is not set
|
||
if [ -z "${NEZHA_TOKEN}" ]; then
|
||
echo "NEZHA_TOKEN is not set. Exiting."
|
||
exit 0
|
||
fi
|
||
|
||
# Set default values if variables are not set
|
||
NEZHA_PROBE_ADDRESS="${NEZHA_PROBE_ADDRESS:-probe.example.com}"
|
||
NEZHA_PROBE_PORT="${NEZHA_PROBE_PORT:-5555}"
|
||
NEZHA_DASHBOARD_URL="${NEZHA_DASHBOARD_URL:-https://nezha.example.com}"
|
||
|
||
NODE_NAME=${NODE_NAME:-$(hostname)}
|
||
|
||
# Send POST request and capture response and HTTP status code
|
||
response=$(curl -s -o response_body.json -w "%{http_code}" -X POST "${NEZHA_DASHBOARD_URL}/api/v1/server/register?simple=true" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: ${NEZHA_TOKEN}" \
|
||
-d "{\"Name\": \"${NODE_NAME}\"}")
|
||
|
||
# Extract HTTP status code and Nezha secret
|
||
HTTP_CODE="$response"
|
||
NEZHA_SECRET=$(cat response_body.json)
|
||
rm -f response_body.json
|
||
|
||
if [ "$HTTP_CODE" != "200" ]; then
|
||
echo "Failed to get Nezha Secret. HTTP status code: $HTTP_CODE"
|
||
exit 1
|
||
fi
|
||
|
||
# Additional check for NEZHA_SECRET to ensure it's not JSON-formatted (indicating failure)
|
||
if [[ "${NEZHA_SECRET:0:1}" == "{" ]]; then
|
||
echo "Failed to get Nezha Secret. Received response: ${NEZHA_SECRET}"
|
||
exit 1
|
||
fi
|
||
|
||
# Download and execute the install script with cleanup
|
||
curl -fsSL https://raw.githubusercontent.com/nezhahq/scripts/main/install.sh -o nezha.sh && \
|
||
chmod +x nezha.sh || { echo "Failed to download or make the script executable"; exit 1; }
|
||
|
||
# Clean up nezha.sh on exit
|
||
trap 'rm -f nezha.sh' EXIT
|
||
|
||
# Run the Nezha agent installation script
|
||
CMD="./nezha.sh install_agent "${NEZHA_PROBE_ADDRESS}" "${NEZHA_PROBE_PORT}" "${NEZHA_SECRET}" --tls"
|
||
|
||
echo "Run commnad : ${CMD}"
|
||
|
||
eval $CMD
|
||
```
|
||
2. 为脚本赋予可执行权限： `chmod +x nezha_register.sh`
|
||
3. 从dashboard获取token, 比如为 `POXbxorKJBM8wPMKX8r2PdMblyXvpggB`
|
||
4. 配置环境变量
|
||
```bash
|
||
export NEZHA_TOKEN="POXbxorKJBM8wPMKX8r2PdMblyXvpggB" # 从面板获取
|
||
export NEZHA_PROBE_ADDRESS="your_probe_address" # 填写探针地址
|
||
export NEZHA_DASHBOARD_URL="https://nezha.example.com" # 修改为你的面板地址
|
||
export NEZHA_PROBE_PORT="5555" # 修改为你的探针端口（如有不同）
|
||
```
|
||
5. 运行注册脚本
|
||
```bash
|
||
./nezha_register.sh
|
||
```
|
||
6. 如果脚本成功运行，你会看到类似以下的日志：
|
||
```bash
|
||
Run command: ./nezha.sh install_agent probe.example.com 5555 YOUR_SECRET --tls
|
||
```
|