Nezha

https://nezha.wiki
Admin
An open-source, lightweight server monitoring and operations management tool supporting multiple...
Tokens:32,563
Snippets:372
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Enable and Start Nezha Agent Service on OpenWrt

Source: https://nezha.wiki/guide/agent.html

Enable the Nezha Agent service to start on boot and then start the service manually. Verify its running status.

```bash
/etc/init.d/nezha-service enable
/etc/init.d/nezha-service start
```

--------------------------------

### Install Nezha Agent as a Service on Windows

Source: https://nezha.wiki/guide/agent.html

Install the Nezha Agent to run as a background service. This ensures the agent starts automatically.

```powershell
nezha-agent.exe service install
```

--------------------------------

### Install Dependencies

Source: https://nezha.wiki/case/case8.html

Install project dependencies using npm.

```bash
npm install
```

--------------------------------

### Install Necessary Tools on OpenWrt

Source: https://nezha.wiki/guide/agent.html

Update package lists and install wget and unzip on OpenWrt. These are required for downloading and extracting the agent.

```bash
opkg update
opkg install wget unzip
```

--------------------------------

### Download URL Response Example

Source: https://nezha.wiki/guide/mcp.html

This is an example of the JSON response received when requesting a download URL. It includes the URL, HTTP method, and expiration time.

```json
{
  "url": "https://nezha.example.com/mcp/download/<token>",
  "method": "GET",
  "expires_at": "2026-05-31T19:30:00+02:00"
}
```

--------------------------------

### Compile and Install ROCm SMI Library

Source: https://nezha.wiki/guide/q9.html

Compile and install the rocm_smi_lib after cloning the repository. This process involves creating a build directory, configuring with CMake, and making the installation.

```bash
cd rocm_smi_lib
mkdir -p build
cd build
cmake ..
make -j $(nproc)
# 安装库文件和头文件，默认安装到 /opt/rocm
sudo make install
```

--------------------------------

### MCP Client Configuration Example

Source: https://nezha.wiki/guide/mcp.html

Example configuration for an MCP client supporting Streamable HTTP and custom headers. Ensure to use API Tokens, not web login JWTs.

```json
{
  "mcpServers": {
    "nezha": {
      "url": "https://nezha.example.com/mcp",
      "headers": {
        "Authorization": "Bearer nzp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

--------------------------------

### Run Nezha Agent on OpenWrt

Source: https://nezha.wiki/guide/agent.html

Grant execute permissions to the agent binary and start the agent with the specified configuration file. Verify the connection afterwards.

```bash
chmod +x /etc/nezha/nezha-agent
/etc/nezha/nezha-agent -c /etc/nezha/config.yml
```

--------------------------------

### Install Nezha Agent with Specific UUID

Source: https://nezha.wiki/guide/agent.html

Install Nezha Agent using a script, specifying the server address, TLS settings, client secret, and a unique server UUID.

```bash
curl -L https://raw.githubusercontent.com/nezhahq/scripts/main/agent/install.sh -o agent.sh && chmod +x agent.sh && env NZ_SERVER=dashboard.example.com:8008 NZ_TLS=false NZ_CLIENT_SECRET=EXAMPLE NZ_UUID=your_server_uuid ./agent.sh
```

--------------------------------

### MCP Initialize Request

Source: https://nezha.wiki/guide/mcp.html

Example JSON-RPC request to initialize an MCP session. This establishes the protocol version, capabilities, and client information.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}
```

--------------------------------

### Install ROCm SMI for AMD GPUs on Fedora/RHEL

Source: https://nezha.wiki/guide/q9.html

Install the ROCm SMI library for AMD GPU monitoring on Fedora or RHEL 8+ systems using dnf.

```bash
# Fedora / RHEL 8+
dnf install rocm-smi
```

--------------------------------

### Server酱 Advanced Notification Body Example

Source: https://nezha.wiki/guide/notifications.html

Example of a FORM request body for Server酱, including server name, notification content, load averages, and a link to the dashboard.

```json
{
  "title": "#SERVER.NAME#",
  "desp": "**#NEZHA#\n\n平均负载: \"#SERVER.LOAD1#\",\"#SERVER.LOAD5#\",\"#SERVER.LOAD15#\"\n\n## [点击访问面板](https://你的面板域名)\n\n![logo](https://raw.githubusercontent.com/naiba/nezha/master/resource/static/brand.svg)"
}
```

--------------------------------

### Install sudo on Ubuntu

Source: https://nezha.wiki/guide/agentq.html

Run this command on Ubuntu systems if the 'sudo: command not found' error occurs during script execution.

```shell
apt install sudo
```

--------------------------------

### Install Nezha Agent

Source: https://nezha.wiki/case/case5.html

This command installs the Nezha agent using a curl script. It requires the Nezha panel domain, port, and a TLS key.

```bash
curl -L https://raw.githubusercontent.com/nezhahq/scripts/main/install.sh -o nezha.sh && chmod +x nezha.sh && sudo ./nezha.sh install_agent nezha.seales.nom.za 443 eAxO9IF519fKFODlW0 --tls
```

--------------------------------

### Install ROCm SMI for AMD GPUs on Debian/Ubuntu

Source: https://nezha.wiki/guide/q9.html

Install the ROCm SMI library for AMD GPU monitoring on Debian or Ubuntu systems using apt.

```bash
# Debian / Ubuntu
apt install rocm-smi
```

--------------------------------

### Webhook Request Headers Example

Source: https://nezha.wiki/guide/ddns.html

Example of how to format authorization headers for a webhook request. The 'pass' value needs to be Base64 encoded.

```json
{
  "Authorization": "Basic pass"
}
```

--------------------------------

### Bark Notification Body Example

Source: https://nezha.wiki/guide/notifications.html

Example of a POST request body for Bark notifications. It uses placeholders for server name and notification content.

```json
{
  "title": "#SERVER.NAME#",
  "device_key": "xxxxxxxxx",
  "body": "#NEZHA#",
  "icon": "https://xxxxxxxx/nz.png"
}
```

--------------------------------

### Reload Systemd and Start Nezha Agent Service

Source: https://nezha.wiki/guide/agent.html

After creating the service file, reload the systemd daemon to recognize the new service and then start the Nezha Agent. This command ensures the agent runs automatically on boot.

```bash
sudo systemctl daemon-reload
sudo systemctl start nezha-agent
sudo systemctl enable nezha-agent
```

--------------------------------

### Slack Notification Body Example

Source: https://nezha.wiki/guide/notifications.html

Example of a JSON body for Slack notifications, using the #NEZHA# placeholder for the alert message.

```json
{
  "text": "#NEZHA#"
}
```

--------------------------------

### wxpusher Notification Body Example

Source: https://nezha.wiki/guide/notifications.html

Example of a JSON body for wxpusher notifications, using placeholders for app token, topic IDs, content, and user IDs.

```json
{
  "appToken": "你的appToken",
  "topicIds": [],
  "content": "#NEZHA#",
  "contentType": "1",
  "uids": ["你的uid"]
}
```

--------------------------------

### Install ROCm SMI for AMD GPUs on Arch Linux

Source: https://nezha.wiki/guide/q9.html

Install the necessary ROCm SMI library for AMD GPU monitoring on Arch Linux using pacman.

```bash
# Arch Linux
pacman -Sy rocm-smi-lib
```

--------------------------------

### PAT Permissions Scope Example

Source: https://nezha.wiki/guide/api.html

PATs use a specific permission scope format: `nezha:{resource}:{verb}`. This example shows how to grant read access to servers and server groups.

```string
nezha:inventory:read
```

--------------------------------

### MCP Call meta.whoami Tool

Source: https://nezha.wiki/guide/mcp.html

Example JSON-RPC request to call the 'meta.whoami' tool, which returns information about the current token. Requires any valid API Token.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "meta.whoami",
    "arguments": {}
  }
}
```

--------------------------------

### MCP Call server.get Tool

Source: https://nezha.wiki/guide/mcp.html

Example JSON-RPC request to call the 'server.get' tool to retrieve details for a specific server. Requires the 'nezha:server:read' scope.

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "server.get",
    "arguments": {
      "server_id": 1
    }
  }
}
```

--------------------------------

### TSDB Configuration Example

Source: https://nezha.wiki/configuration/dashboard.html

This snippet shows how to configure the Time-Series Database (TSDB) for storing service monitoring history and server metrics. Ensure `data_path` is set to enable TSDB.

```yaml
tsdb:
  data_path: "data/tsdb"
  retention_days: 30
  max_memory_mb: 256
```

--------------------------------

### MCP Call server.list Tool

Source: https://nezha.wiki/guide/mcp.html

Example JSON-RPC request to call the 'server.list' tool to list visible online servers. Requires the 'nezha:inventory:read' scope.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "server.list",
    "arguments": {
      "online_only": true
    }
  }
}
```

--------------------------------

### Manage Nezha Agent Service on OpenWrt

Source: https://nezha.wiki/guide/agent.html

Commands to manually start, stop, and restart the Nezha Agent service on OpenWrt.

```bash
/etc/init.d/nezha-service start
/etc/init.d/nezha-service stop
/etc/init.d/nezha-service restart
```

--------------------------------

### Install sudo on CentOS

Source: https://nezha.wiki/guide/agentq.html

Run this command on CentOS systems if the 'sudo: command not found' error occurs during script execution.

```shell
yum install sudo
```

--------------------------------

### Server Metrics History Response Example

Source: https://nezha.wiki/guide/api.html

Example JSON response for the server metrics history endpoint. Includes server details, the requested metric, and data points with timestamps and values.

```json
{
  "success": true,
  "data": {
    "server_id": 1,
    "server_name": "Server 1",
    "metric": "cpu",
    "data_points": [
      {
        "ts": 1760000000000,
        "value": 12.34
      }
    ]
  }
}
```

--------------------------------

### Get Server Architecture

Source: https://nezha.wiki/guide/agent.html

Use this command to determine the CPU architecture of your Synology NAS. This is crucial for downloading the correct Nezha Agent binary.

```bash
uname -m
```

--------------------------------

### Service Monitoring History Response Example

Source: https://nezha.wiki/guide/api.html

Example JSON response for the service monitoring history endpoint. Includes service details and data points with timestamps, delay, and status.

```json
{
  "success": true,
  "data": {
    "service_id": 1,
    "service_name": "HTTPS",
    "servers": [
      {
        "server_id": 1,
        "server_name": "Server 1",
        "stats": {
          "avg_delay": 68.2,
          "up_percent": 99.9,
          "total_up": 1440,
          "total_down": 1,
          "data_points": [
            {
              "ts": 1760000000000,
              "delay": 68.2,
              "status": 1
            }
          ]
        }
      }
    ]
  }
}
```

--------------------------------

### Get System Settings

Source: https://nezha.wiki/guide/api.html

Retrieve basic system information such as site name, language, and OAuth2 provider. Unauthenticated access returns only publicly readable configurations.

```http
GET /api/v1/setting
```

--------------------------------

### Uninstall Agent and Remove Configurations

Source: https://nezha.wiki/guide/agentq.html

Use this command to clear all Agent configuration files and associated services if multiple instances have been installed.

```bash
./agent.sh uninstall
```

--------------------------------

### GET /api/v1/setting

Source: https://nezha.wiki/guide/api.html

Retrieves system settings such as site name, language, frontend templates, OAuth2 providers, and TSDB status. Unauthenticated users can only access publicly available configurations.

```APIDOC
## GET /api/v1/setting

### Description
Retrieves system settings including site name, language, frontend templates, OAuth2 providers, and TSDB status. Unauthenticated users can only access publicly available configurations.

### Method
GET

### Endpoint
/api/v1/setting

### Parameters

### Request Example

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the system settings.

#### Response Example
```json
{
  "success": true,
  "data": {}
}
```
```

--------------------------------

### Nezha Agent OpenWrt Service Script Content

Source: https://nezha.wiki/guide/agent.html

Content for the Nezha Agent service script. This script defines how to start, stop, and restart the agent service using procd.

```bash
#!/bin/sh /etc/rc.common

START=99
USE_PROCD=1

start_service() {
    procd_open_instance
    procd_set_param command /etc/nezha/nezha-agent -c /etc/nezha/config.yml
    procd_set_param respawn
    procd_close_instance
}

stop_service() {
    killall nezha-agent
}

restart() {
    stop
    sleep 2
    start
}
```

--------------------------------

### Common Scopes and Route Mappings

Source: https://nezha.wiki/guide/api.html

This section details common scopes required for various API routes and provides examples of scope usage for different scenarios.

```APIDOC
## Common Scopes and Route Mappings

### Description
Defines the permissions (scopes) required for various API operations and provides recommended scope combinations for common use cases.

### Scope Definitions
- `nezha:inventory:read`: Read server list, groups, and status.
- `nezha:inventory:delete`: Delete servers and groups.
- `nezha:server:read`: Read server details, metrics, status, and file content.
- `nezha:server:write`: Modify server settings, push config, force update, migrate, write files.
- `nezha:server:delete`: Delete files on a server.
- `nezha:server:exec`: Open online terminal, execute commands.
- `nezha:service:read/write/delete`: Manage service monitoring.
- `nezha:alertrule:read/write/delete`: Manage alert rules.
- `nezha:cron:read/write/delete/exec`: Manage scheduled tasks.
- `nezha:ddns:read/write/delete`: Manage DDNS configurations.
- `nezha:nat:read/write/delete`: Manage NAT rules.
- `nezha:notification:read/write/delete`: Manage notification methods.
- `nezha:notification-group:read/write/delete`: Manage notification groups.
- `nezha:transfer:read/write/delete`: Manage server migration records.
- `nezha:<resource>:*`: All actions for a specific resource (e.g., `nezha:server:*`).
- `nezha:admin:*`: Admin interfaces (users, WAF, settings, etc.). Only available for admin tokens.
- `nezha:*`: All permissions. Only available for admin tokens.

### Route to Scope Mapping
- `GET /api/v1/server`, `GET /api/v1/ws/server`, `GET /api/v1/server-group`: `nezha:inventory:read`
- `POST /api/v1/batch-delete/server`, `POST /api/v1/batch-delete/server-group`: `nezha:inventory:delete`
- `PATCH /api/v1/server/{id}`, `GET /api/v1/server/config/{id}`, `POST /api/v1/server/config`, `POST /api/v1/batch-move/server`, `POST /api/v1/force-update/server`: `nezha:server:write`
- `POST /api/v1/file`, `GET /api/v1/ws/file/{id}`: Requires `nezha:server:read`, `nezha:server:write`, `nezha:server:delete`
- `GET /api/v1/transfer`, `GET /api/v1/ws/transfer`: `nezha:transfer:read`
- `POST /api/v1/transfer/{id}/cancel`, `POST /api/v1/transfer/{id}/retry`: `nezha:transfer:write`
- `GET/POST/PATCH/DELETE` for resource management: Corresponding `read`, `write`, `delete` scope.
- `/api/v1/user`, `/api/v1/waf`, `/api/v1/online-user`, `PATCH /api/v1/setting`, `POST /api/v1/maintenance`: `nezha:admin:*` or `nezha:*` (Admin only).

### Recommended Scope Combinations
- **External dashboard read-only server list**: `nezha:inventory:read`
- **External dashboard read server details and metrics**: `nezha:inventory:read`, `nezha:server:read`
- **MCP client query servers and read small files**: `nezha:inventory:read`, `nezha:server:read`
- **MCP client execute maintenance commands**: `nezha:inventory:read`, `nezha:server:read`, `nezha:server:exec` (with Server ID whitelist)
- **MCP client write or upload files**: `nezha:server:read`, `nezha:server:write` (with Server ID whitelist)
- **CI/CD trigger specific scheduled tasks**: `nezha:cron:read`, `nezha:cron:exec`
- **Operations script manage service monitoring**: `nezha:service:read`, `nezha:service:write` (add `nezha:service:delete` if needed)
- **Admin automated maintenance**: `nezha:admin:*` (Admin Token only)

### Important Notes
- Scopes only narrow down existing user permissions; they cannot grant elevated privileges.
- Using a `Server IDs` whitelist is recommended for tokens used with single or few servers.
- Old `mcp:*` scopes are deprecated and will be mapped to `nezha:*` scopes or rejected.
```

--------------------------------

### SSH Access via Cloudflared

Source: https://nezha.wiki/case/case5.html

Example command for SSH access using cloudflared, specifying the hostname and client ID. The password is often derived from GH_CLIENTSECRET.

```bash
<file path>/cloudflared access ssh --hostname nezha.seales.nom.za/<GH_CLIENTID>
```

--------------------------------

### Execute Command with Environment Setup

Source: https://nezha.wiki/guide/tasks.html

When a command is not found, it might be due to an incorrect PATH environment variable. This snippet shows how to prepend 'source ~/.bashrc' to ensure the environment is loaded before executing your command on Linux.

```bash
source ~/.bashrc && your_command
```

--------------------------------

### Caddy Reverse Proxy Configuration

Source: https://nezha.wiki/guide/q3.html

Example Caddy configuration for reverse proxying Nezha Dashboard traffic, including gRPC and standard web requests. Adjust CDN headers and proxy targets as needed.

```caddy
dashboard.example.com {
    @grpcProto {
        path /proto.NezhaService/*
    }

    reverse_proxy @grpcProto {
        header_up Host {host}
        header_up nz-realip {http.CF-Connecting-IP} # 替换为你的 CDN 提供的私有 header，此处为 CloudFlare 默认
        # header_up nz-realip {remote_host} # 如果你使用caddy作为最外层，就把上面一行注释掉，启用此行
        transport http {
            versions h2c
            read_buffer 4096
        }
        to localhost:8008
    }

    reverse_proxy {
        header_up Host {host}
        header_up Origin https://{host}
        header_up nz-realip {http.CF-Connecting-IP} # 替换为你的 CDN 提供的私有 header，此处为 CloudFlare 默认
        # header_up nz-realip {remote_host} # 如果你使用caddy作为最外层，就把上面一行注释掉，启用此行
        transport http {
            read_buffer 16384
        }
        to localhost:8008
    }
}
```

--------------------------------

### GET /api/v1/server

Source: https://nezha.wiki/guide/api.html

Fetches a list of servers that the current user has permission to manage. Administrators can see all servers, while regular users only see their own. For real-time status, use the WebSocket interface.

```APIDOC
## GET /api/v1/server

### Description
Fetches a list of servers that the current user has permission to manage. Administrators can see all servers, while regular users only see their own. For real-time status, use the WebSocket interface.

### Method
GET

### Endpoint
/api/v1/server

### Parameters
#### Query Parameters
- **Authorization** (string) - Bearer JWT_TOKEN

### Request Example
```http
GET /api/v1/server
Authorization: Bearer JWT_TOKEN
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the list of servers.

#### Response Example
```json
{
  "success": true,
  "data": []
}
```
```

--------------------------------

### Get Service Monitoring Overview

Source: https://nezha.wiki/guide/api.html

Retrieves the current status and periodic traffic statistics for services. Authenticated users see data they have access to; guests are limited by 'force_auth' and hidden configurations.

```http
GET /api/v1/service
```

--------------------------------

### Get Real-time Server Status Stream

Source: https://nezha.wiki/guide/api.html

Establishes a WebSocket connection to receive a data stream for real-time server online status and resource utilization. Guests can connect if 'force_auth' is not enabled, but hidden servers will be excluded.

```http
GET /api/v1/ws/server
Authorization: Bearer JWT_TOKEN
```

--------------------------------

### Create Nezha Agent Directory and Unzip

Source: https://nezha.wiki/guide/agent.html

Create a directory for the Nezha Agent and unzip the downloaded agent binary into it. This prepares the agent files for execution.

```bash
mkdir -p /opt/nezha
unzip nezha-agent.zip -d /opt/nezha
```

--------------------------------

### Create Nezha Agent Service Script on OpenWrt

Source: https://nezha.wiki/guide/agent.html

Create a service script in /etc/init.d/nezha-service to manage the Nezha Agent as a system service. Customize paths as needed.

```bash
vi /etc/init.d/nezha-service
```

--------------------------------

### Create Nezha Agent Configuration File on OpenWrt

Source: https://nezha.wiki/guide/agent.html

Create and edit the configuration file for the Nezha Agent. Populate it with your server details, client secret, and UUID.

```bash
touch /etc/nezha/config.yml
vi /etc/nezha/config.yml
```

--------------------------------

### Download Nezha Agent for OpenWrt

Source: https://nezha.wiki/guide/agent.html

Download the Nezha Agent zip file compatible with your OpenWrt system architecture. Replace <arch> with your system's architecture (e.g., amd64, arm).

```bash
wget -O nezha-agent.zip https://github.com/nezhahq/agent/releases/latest/download/nezha-agent_linux_<arch>.zip
```

--------------------------------

### Download Nezha Agent for amd64

Source: https://nezha.wiki/guide/agent.html

Download the Nezha Agent binary for amd64 architecture using wget. This command saves the zip file to the current directory.

```bash
wget -O nezha-agent.zip https://github.com/nezhahq/agent/releases/latest/download/nezha-agent_linux_amd64.zip
```

--------------------------------

### Run Nezha Agent on Windows

Source: https://nezha.wiki/guide/agent.html

Execute the Nezha Agent with a configuration file. Ensure you have administrator privileges.

```powershell
nezha-agent.exe -c config.yml
```

--------------------------------

### Extract Nezha Agent on OpenWrt

Source: https://nezha.wiki/guide/agent.html

Create the agent directory and extract the downloaded zip file into it. Ensure the path is correct for subsequent operations.

```bash
mkdir -p /etc/nezha
unzip nezha-agent.zip -d /etc/nezha
```

--------------------------------

### Generate Swagger File from Source

Source: https://nezha.wiki/guide/api.html

If developing from source, you can generate the Swagger file by running a script in the repository root.

```shell
./script/bootstrap.sh
```

--------------------------------

### Login to get JWT Token

Source: https://nezha.wiki/guide/api.html

Obtain a JWT token by providing username and password. This token is used for subsequent authenticated requests.

```APIDOC
## POST /api/v1/login

### Description
Authenticates a user and returns a JWT token for session management.

### Method
POST

### Endpoint
/api/v1/login

### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "username": "admin",
  "password": "your-password"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the login was successful.
- **data** (object) - Contains the authentication token and its expiration.
  - **token** (string) - The JWT token.
  - **expire** (string) - The expiration date and time of the token.

#### Response Example
```json
{
  "success": true,
  "data": {
    "token": "JWT_TOKEN",
    "expire": "2026-05-18T12:00:00+02:00"
  }
}
```
```

--------------------------------

### Clone ROCm SMI Library Repository

Source: https://nezha.wiki/guide/q9.html

Clone the rocm_smi_lib repository from GitHub to manually compile and install the library if pre-packaged versions are unavailable.

```bash
git clone https://github.com/ROCm/rocm_smi_lib
```

--------------------------------

### Write File Content

Source: https://nezha.wiki/guide/mcp.html

Use `fs.write` to write content to a file. Supports creating directories if they don't exist and specifying file permissions. Requires `nezha:server:write` permission. Consider using `if_match_sha256` for optimistic locking.

```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "fs.write",
    "arguments": {
      "server_id": 1,
      "path": "/tmp/nezha-note.txt",
      "content": "hello from nezha mcp\n",
      "encoding": "utf8",
      "mode": "0644",
      "create_dirs": true
    }
  }
}
```

--------------------------------

### DDNS Update Log Entries

Source: https://nezha.wiki/guide/ddns.html

Example log entries showing the status of DDNS updates. These logs indicate whether the update attempt was successful or is in progress.

```shell
dashboard_1  | 2024/03/16 23:16:25 NEZHA>> 正在尝试更新域名(ddns.example.com)DDNS(1/3)
dashboard_1  | 2024/03/16 23:16:28 NEZHA>> 尝试更新域名(ddns.example.com)DDNS成功
```

--------------------------------

### Matrix Notification - Get Access Token

Source: https://nezha.wiki/guide/notifications.html

Use this cURL command to obtain your Matrix access token. Replace placeholders with your Matrix server details and credentials.

```bash
curl -XPOST -d '{"type": "m.login.password", "identifier": {"user": "$YOUR_MATRIX_USERNAME", "type": "m.id.user"}, "password": "$YOUR_MATRIX_PASSWD"}' "https://$YOUR_HOME_SERVER/_matrix/client/r0/login"
```

--------------------------------

### Download Nezha Agent for Windows

Source: https://nezha.wiki/guide/agent.html

Download the Nezha Agent binary specifically for Windows operating systems. This is typically a zip file containing the executable and configuration files.

```plaintext
nezha-agent_windows_amd64.zip
```

--------------------------------

### Grant Execute Permissions to Nezha Agent

Source: https://nezha.wiki/guide/agent.html

Make the Nezha Agent binary executable. This step is necessary before you can run the agent.

```bash
chmod +x /opt/nezha/nezha-agent
```

--------------------------------

### GET /api/v1/service/{id}/history

Source: https://nezha.wiki/guide/api.html

Retrieves historical data for a specific service monitoring instance. Supports different periods (`1d`, `7d`, `30d`) with varying data granularities.

```APIDOC
## GET /api/v1/service/{id}/history

### Description
Retrieves historical data for a specific service monitoring instance. Supports different periods (`1d`, `7d`, `30d`) with varying data granularities.

### Method
GET

### Endpoint
/api/v1/service/{id}/history

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the service monitoring instance.

#### Query Parameters
- **period** (string) - Optional - The query period. Options: `1d`, `7d`, `30d`. Defaults to `1d`.

### Request Example
```http
GET /api/v1/service/1/history?period=1d
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains historical data for the service monitoring.
  - **service_id** (integer) - The ID of the service.
  - **service_name** (string) - The name of the service.
  - **servers** (array) - List of servers associated with the service.
    - **server_id** (integer) - The ID of the server.
    - **server_name** (string) - The name of the server.
    - **stats** (object) - Statistics for the server.
      - **avg_delay** (number) - Average delay.
      - **up_percent** (number) - Percentage of uptime.
      - **total_up** (integer) - Total uptime duration.
      - **total_down** (integer) - Total downtime duration.
      - **data_points** (array) - Time-series data points.
        - **ts** (integer) - Timestamp.
        - **delay** (number) - Delay value.
        - **status** (integer) - Status code.

#### Response Example
```json
{
  "success": true,
  "data": {
    "service_id": 1,
    "service_name": "HTTPS",
    "servers": [
      {
        "server_id": 1,
        "server_name": "Server 1",
        "stats": {
          "avg_delay": 68.2,
          "up_percent": 99.9,
          "total_up": 1440,
          "total_down": 1,
          "data_points": [
            {
              "ts": 1760000000000,
              "delay": 68.2,
              "status": 1
            }
          ]
        }
      }
    ]
  }
}
```
```

--------------------------------

### GET /api/v1/service

Source: https://nezha.wiki/guide/api.html

Returns the current status and periodic traffic statistics for service monitoring. Authenticated users see data they have permission for; guests are limited by `force_auth` and hidden configurations.

```APIDOC
## GET /api/v1/service

### Description
Returns the current status and periodic traffic statistics for service monitoring. Authenticated users see data they have permission for; guests are limited by `force_auth` and hidden configurations.

### Method
GET

### Endpoint
/api/v1/service

### Parameters

### Request Example

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains service monitoring overview and traffic statistics.

#### Response Example
```json
{
  "success": true,
  "data": {}
}
```
```

--------------------------------

### Host Deployment Script for Argo-Nezha

Source: https://nezha.wiki/case/case5.html

This bash script can be used to deploy Argo-Nezha directly on the host machine. It fetches the script from a GitHub raw URL.

```bash
bash <(wget -qO- https://raw.githubusercontent.com/fscarmen2/Argo-Nezha-Service-Container/main/dashboard.sh)
```

--------------------------------

### GET /api/v1/ws/server

Source: https://nezha.wiki/guide/api.html

Provides a WebSocket data stream for real-time updates on server online status and resource utilization. Accessible to guests if `force_auth` is not enabled, but hidden servers will not be included.

```APIDOC
## GET /api/v1/ws/server

### Description
Provides a WebSocket data stream for real-time updates on server online status and resource utilization. Accessible to guests if `force_auth` is not enabled, but hidden servers will not be included.

### Method
GET

### Endpoint
/api/v1/ws/server

### Parameters
#### Query Parameters
- **Authorization** (string) - Bearer JWT_TOKEN

### Request Example
```http
GET /api/v1/ws/server
Authorization: Bearer JWT_TOKEN
```

### Response
(WebSocket stream data)
```

--------------------------------

### View Agent Runtime Logs

Source: https://nezha.wiki/guide/q2.html

Enable debug mode in the agent configuration and use systemctl and journalctl to view the agent's status and logs for error messages.

```bash
systemctl status 'nezha-agent*'
journalctl -u 'nezha-agent*' -e --no-pager
```

--------------------------------

### Restart Docker Service

Source: https://nezha.wiki/guide/dashboardq.html

If the panel installation, restart, or update fails with iptables errors, try restarting the Docker service. This can resolve issues related to Docker's network configurations.

```shell
systemctl status docker
systemctl restart docker
systemctl status docker
```

--------------------------------

### Check Nezha Agent Process on OpenWrt

Source: https://nezha.wiki/guide/agent.html

Use the ps command to verify if the nezha-agent process is running on your OpenWrt system.

```bash
ps | grep nezha-agent
```

--------------------------------

### List Directory Contents

Source: https://nezha.wiki/guide/mcp.html

Use the `fs.list` method to retrieve the contents of a directory on the remote server. Requires `nezha:server:read` permission. Hidden files can be optionally shown.

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "fs.list",
    "arguments": {
      "server_id": 1,
      "path": "/var/log",
      "show_hidden": false
    }
  }
}
```

--------------------------------

### GET /api/v1/service/{id}/server

Source: https://nezha.wiki/guide/api.html

Returns a list of servers associated with a specific service monitoring instance. Useful for displaying node-level status for a given monitoring item in custom frontends.

```APIDOC
## GET /api/v1/service/{id}/server

### Description
Returns a list of servers associated with a specific service monitoring instance. Useful for displaying node-level status for a given monitoring item in custom frontends.

### Method
GET

### Endpoint
/api/v1/service/{id}/server

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the service monitoring instance.

### Request Example

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the list of servers associated with the service.

#### Response Example
```json
{
  "success": true,
  "data": []
}
```
```

--------------------------------

### GET /api/v1/server/{id}/metrics

Source: https://nezha.wiki/guide/api.html

Retrieves historical metrics for a specific server. Supports various metrics like CPU, memory, disk, and network, with configurable periods and data granularities.

```APIDOC
## GET /api/v1/server/{id}/metrics

### Description
Retrieves historical metrics for a specific server. Supports various metrics like CPU, memory, disk, and network, with configurable periods and data granularities.

### Method
GET

### Endpoint
/api/v1/server/{id}/metrics

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the server.

#### Query Parameters
- **metric** (string) - Required - The name of the metric to retrieve (e.g., `cpu`, `memory`, `disk`, `net_in_speed`).
- **period** (string) - Optional - The query period. Options: `1d`, `7d`, `30d`. Defaults to `1d`.

### Request Example
```http
GET /api/v1/server/1/metrics?metric=cpu&period=1d
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the historical metric data for the server.
  - **server_id** (integer) - The ID of the server.
  - **server_name** (string) - The name of the server.
  - **metric** (string) - The name of the metric retrieved.
  - **data_points** (array) - Time-series data points.
    - **ts** (integer) - Timestamp.
    - **value** (number) - The metric value.

#### Response Example
```json
{
  "success": true,
  "data": {
    "server_id": 1,
    "server_name": "Server 1",
    "metric": "cpu",
    "data_points": [
      {
        "ts": 1760000000000,
        "value": 12.34
      }
    ]
  }
}
```
```

--------------------------------

### Get Servers Under a Service

Source: https://nezha.wiki/guide/api.html

Retrieves a list of servers associated with a specific service monitoring instance. Useful for displaying the status of nodes within a particular monitoring item on a custom frontend.

```http
GET /api/v1/service/{id}/server
```

--------------------------------

### Enable GPU Monitoring in Agent Configuration

Source: https://nezha.wiki/guide/q9.html

Enable the 'gpu' parameter in the agent's configuration file to activate GPU monitoring. Restart the agent service for changes to take effect.

```yaml
gpu: true
```

--------------------------------

### Get Server List

Source: https://nezha.wiki/guide/api.html

Retrieve a list of servers that the current user has permission to manage. Administrators see all servers, while regular users see only their own. For real-time status, use the WebSocket endpoint.

```http
GET /api/v1/server
Authorization: Bearer JWT_TOKEN
```

--------------------------------

### Get Server Metrics History

Source: https://nezha.wiki/guide/api.html

Retrieves historical metrics for a specific server. The 'metric' parameter is required, and 'period' controls the data granularity. This endpoint relies on TSDB; without it, 'data_points' will be empty.

```http
GET /api/v1/server/{id}/metrics?metric=cpu&period=1d
```
Tokens:
Raw