## 1. Project Overview & Quickstart (nezhahq/nezha)

\>> Telegram Channel: [哪吒监控（中文通知频道）](https://t.me/nezhanews)
\>> Telegram Group: [Nezha Monitoring Global (English Only)](https://t.me/nezhamonitoring_global), [哪吒监控（中文群组）](https://t.me/nezhamonitoring)

\>> [Use Cases | 我们的用户](https://www.google.com/search?q=%22%E5%93%AA%E5%90%92%E7%9B%91%E6%8E%A7+Nezha+Monitoring%22) (Google) 


## User Guide

- [English](https://nezhahq.github.io/en_US/index.html)
- [中文文档](https://nezhahq.github.io/index.html)

## Contributing

### Translation

<a href="https://hosted.weblate.org/engage/nezha/">

</a>

Is Nezha not in your language, or the translation is incorrect or incomplete? Get involved in the translations on [Hosted Weblate](https://hosted.weblate.org/engage/nezha/).

## Screenshots

| 用户前台 [@hamster1963](https://github.com/hamster1963) | 管理后台 [@nezhahq](https://github.com/nezhahq) |
|---|---|
|   |   |
| [hamster1963/nezha-dash](https://github.com/hamster1963/nezha-dash)  | [nezhahq/admin-frontend](https://github.com/nezhahq/admin-frontend)  |

add your theme to [service/singleton/frontend-templates.yaml](service/singleton/frontend-templates.yaml)

## Contributors

[](https://github.com/naiba)
[](https://github.com/uubulb)
[](https://github.com/AkkiaS7)
[](https://github.com/matchch)
[](https://github.com/nap0o)
[](https://github.com/dysf888)
[](https://github.com/xykt)
[](https://github.com/weblate)
[](https://github.com/MikoyChinese)
[](https://github.com/JackieSung4ev)
[](https://github.com/cantoblanco)
[](https://github.com/lemoeo)
[](https://github.com/spiritLHLS)
[](https://github.com/liuyanxi975)
[](https://github.com/CosmosZ-code)
[](https://github.com/lvgj-stack)
[](https://github.com/hhhkkk520)
[](https://github.com/Mmx233)
[](https://github.com/rootmelo92118)
[](https://github.com/Moraxyc)
[](https://github.com/hamster1963)
[](https://github.com/1ridic)
[](https://github.com/zhucaidan)
[](https://github.com/iilemon)
[](https://github.com/lyj0309)
[](https://github.com/fscarmen)
[](https://github.com/ch8o)
[](https://github.com/MemoryShadow)
[](https://github.com/HsukqiLee)
[](https://github.com/DarcJC)
[](https://github.com/Creling)
[](https://github.com/coreff)
[](https://github.com/wellcoming)
[](https://github.com/adminsama)
[](https://github.com/acgpiano)
[](https://github.com/eya46)
[](https://github.com/guoyongchang)
[](https://github.com/hiDandelion)
[](https://github.com/honeok)
[](https://github.com/yuanweize)
[](https://github.com/igophper)
[](https://github.com/lvyaoting)
[](https://github.com/quanljh)
[](https://github.com/unclezs)
[](https://github.com/ysicing)
[](https://github.com/yanhao98)
[](https://github.com/arkylin)
[](https://github.com/yumusb)
[](https://github.com/colour93)
[](https://github.com/wwng2333)
[](https://github.com/Es-dese)
[](https://github.com/GreenTeodoro839)
[](https://github.com/techotaku)
[](https://github.com/KorenKrita)
[](https://github.com/funnyzak)
[](https://github.com/MartijnLindeman)
[](https://github.com/silver-ymz)
[](https://github.com/dreamingsleeping)
[](https://github.com/NikoCat233)
[](https://github.com/Septrum101)
[](https://github.com/IamTaoChen)
[](https://github.com/nickfox-taterli)
[](https://github.com/TomyJan)
[](https://github.com/hmsjy2017)
[](https://github.com/ace-consultoria)
[](https://github.com/77-QiQi)
[](https://github.com/railzen)
[](https://github.com/Mubelotix)
[](https://github.com/zhdsmy)

## Special Thanks
- [IPInfo](https://ipinfo.io/) for providing an accurate GeoIP Database.

## Star History

[](https://star-history.dera.page/#nezhahq/nezha&Timeline)

## 2. Official Technical Reference & Guides (nezhahq/nezhahq.github.io)

## File: README.md

# Nezha Monitoring V2 Documentation

Official Chinese and English documentation for [Nezha Monitoring V2](https://nezha.wiki/), an open-source, self-hosted server monitoring and operations platform.

The documentation covers:

- Dashboard and Agent installation
- Multi-server metrics and availability
- HTTP, Ping, TCP, and TLS certificate checks
- Alerts and notification providers
- Terminal, files, tasks, DDNS, NAT, REST API, and MCP
- Architecture, security, version compatibility, and troubleshooting

## Official projects

- [Nezha Dashboard](https://github.com/nezhahq/nezha)
- [Nezha Agent](https://github.com/nezhahq/agent)
- [Chinese documentation](https://nezha.wiki/)
- [English documentation](https://nezha.wiki/en_US/)

## Local development

```shell
npm ci
npm run dev
```

Build and audit generated SEO metadata:

```shell
npm test
```

When adding or changing documentation, keep the Chinese and English pages synchronized.

---

## File: docs/guide/agent.md

---
outline: deep
---

# 安装 Agent

**哪吒监控的被控端服务被称为 Agent，本文档将介绍如何在被控端服务器上安装 Agent，并与 Dashboard 连接。**  
::: tip  
Agent 二进制文件仓库地址为：<https://github.com/nezhahq/agent/releases>  
:::

## 一键安装 Agent

哪吒监控支持在 Windows、macOS 和 Linux 上一键安装 Agent。遵循本文档的步骤，你可以轻松地在服务器上部署它。

### 准备工作

在安装前，需要提前在管理面板中设置通信域名，该域名不建议接入 CDN。本文档以示例通信域名 “data.example.com” 为例。

1. 在后台管理面板点击头像，进入“系统设置”页。
2. 在“Agent 对接地址【域名/IP:端口】”项中填入通信域名和端口 “data.example.com:8008”。
3. 点击“确认”保存设置。

### 一键安装步骤

1. 在 `服务器` 页面中，点击 `安装命令` 并选择对应操作系统，安装命令将自动复制到你的剪贴板。
2. 在被控端服务器中运行安装命令，等待安装完成后返回到 `服务器` 页面查看是否上线。
3. 如果安装成功，页面中将自动弹出新的服务器，你可以点击编辑按钮为其设置名称。

### 平台特有说明

#### Windows 特殊说明

1. 在 Windows 服务器中，运行 PowerShell。
2. 在 PowerShell 中粘贴并运行安装命令。
3. 如遇到「执行策略变更」确认提示，输入 `Y` 并回车。

## 其他方式安装 Agent

---

### 在群晖系统中安装 Agent（DSM 7）


  点击展开/收起

由于群晖（Synology NAS）设备的系统基于特定版本的 Linux，其 shell 环境和软件包管理与标准 Linux 系统有所不同，因此不支持一键安装脚本。需要手动安装 Agent，具体步骤如下：

---

#### 1. 准备工作

1. **确保拥有管理员权限**

   - 登录群晖的管理界面，或通过 SSH 使用管理员账户登录设备。

2. **安装必要的依赖**  
   确定群晖设备已安装 `wget`、`unzip` 或 `curl`

:::tip

也可以提前下载并解压好 Nezha Agent 的二进制文件，通过群晖的 DSM File Station 手动上传，免去安装依赖的步骤。

:::

---

#### 2. 下载 Nezha Agent

1. **确定群晖的 CPU 架构**  
   使用以下命令获取设备的架构信息：

   ```bash
   uname -m
   ```

   常见架构对应关系：

   - `x86_64` 对应 `amd64`
   - `armv7l` 或 `aarch64` 对应 `arm`

2. **下载适配的 Nezha Agent 二进制文件**  
   根据设备架构选择正确的下载链接。例如，对于 `amd64` 架构：

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

3. **解压文件**  
   将下载的压缩包解压到指定目录，例如 `/opt/nezha`：

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

4. **赋予运行权限**
   ```bash
   chmod +x /opt/nezha/nezha-agent
   ```

---

#### 3. 创建配置文件

1. **创建并编辑配置文件**  
   在 `/opt/nezha` 目录下创建 `config.yml` 文件，并添加以下内容：
   ```yaml
   client_secret: your_agent_secret
   debug: false
   disable_auto_update: false
   disable_command_execute: false
   disable_force_update: false
   disable_nat: false
   disable_send_query: false
   gpu: false
   insecure_tls: false
   ip_report_period: 1800
   report_delay: 3
   server: data.example.com:8008
   skip_connection_count: false
   skip_procs_count: false
   temperature: false
   tls: false
   use_atomgit_to_upgrade: false
   use_gitee_to_upgrade: false
   use_ipv6_country_code: false
   uuid: your_uuid
   ```
   - **字段说明**：
     - `server`：替换为 Dashboard 地址和端口，如 `data.example.com:8008` `1.1.1.1:8008` `"[2606:4700:4700::1111]:8008"`。
     - `client_secret`：替换为 Dashboard 中对应用户的连接密钥。当前前台没有单独的连接密钥复制入口，建议直接使用服务器页面生成的安装命令，或从命令中的 `NZ_CLIENT_SECRET` 提取。
     - `uuid`：为该 Agent 生成一个唯一标识符，不要与同一个 Dashboard 中其他的 Agent 重复，可使用 `uuidgen` 命令生成：
       ```bash
       uuidgen
       ```
   - **保存文件**：将文件保存至 `/opt/nezha/config.yml`。

---

#### 4. 创建 systemctl 服务文件

1. **创建服务文件**  
   在 `/etc/systemd/system/` 目录下创建 `nezha-agent.service` 文件：

   ```bash
   sudo nano /etc/systemd/system/nezha-agent.service
   ```

2. **添加以下内容**：

   ```ini
   [Unit]
   Description=Nezha Agent
   After=network.target

   [Service]
   Type=simple
   User=root
   Group=root
   ExecStart=/opt/nezha/nezha-agent -c /opt/nezha/config.yml
   Restart=always
   RestartSec=5

   [Install]
   WantedBy=multi-user.target
   ```

3. **保存文件并重新加载服务配置**：
   ```bash
   sudo systemctl daemon-reload
   ```

---

#### 5. 启动 Agent

1. **启动服务**  
   使用以下命令启动 Agent：

   ```bash
   sudo systemctl start nezha-agent
   ```

2. **设置开机自启动**

   ```bash
   sudo systemctl enable nezha-agent
   ```

3. **查看服务状态**  
   确保 Agent 已成功启动：
   ```bash
   sudo systemctl status nezha-agent
   ```

---

#### 6. 验证 Agent 连接

1. 登录 Dashboard，检查是否有新设备上线。
2. 如果服务运行正常且日志中无报错，则安装完成。



---

### 在 Windows 系统中手动安装 Agent


  点击展开/收起

Windows 系统除了一键脚本，也可以下载对应的二进制文件并手动配置，以下是详细步骤：

---

#### 1. 准备工作

1. **确保管理员权限**  
   使用管理员账户登录 Windows 系统。

2. **安装必要工具**
   - 确保有解压工具（如 `7-Zip` 或 `WinRAR`）。

---

#### 2. 下载 Nezha Agent

1. **确认系统架构**

   - Windows 系统一般为 `amd64` 架构，可直接下载对应的二进制文件。

2. **下载 Nezha Agent 文件**

   - 访问 [Nezha Agent Releases](https://github.com/nezhahq/agent/releases)，下载适用于 `Windows` 的版本，例如：
     ```plaintext
     nezha-agent_windows_amd64.zip
     ```

3. **解压文件**
   - 将下载的压缩包解压到指定目录，例如：`C:\nezha`。

---

#### 3. 创建配置文件

1. **创建并编辑配置文件**  
   在解压目录中创建 `config.yml` 文件，内容如下：

   ```yaml
   client_secret: your_agent_secret
   debug: false
   disable_auto_update: false
   disable_command_execute: false
   disable_force_update: false
   disable_nat: false
   disable_send_query: false
   gpu: false
   insecure_tls: false
   ip_report_period: 1800
   report_delay: 3
   server: data.example.com:8008
   skip_connection_count: false
   skip_procs_count: false
   temperature: false
   tls: false
   use_atomgit_to_upgrade: false
   use_gitee_to_upgrade: false
   use_ipv6_country_code: false
   uuid: your_uuid
   ```

   - **字段说明**：
     - `server`：替换为您的 Dashboard 地址和端口，例如 `data.example.com:8008` `1.1.1.1:8008` `"[2606:4700:4700::1111]:8008"`。
     - `client_secret`：替换为 Dashboard 中对应用户的连接密钥。当前前台没有单独的连接密钥复制入口，建议直接使用服务器页面生成的安装命令，或从命令中的 `NZ_CLIENT_SECRET` 提取。
     - `uuid`：可以通过在线工具生成。

2. **保存文件**  
   将文件保存为 `config.yml`，存放在 Agent 的目录中。

---

#### 4. 运行 Agent

1. **以管理员权限运行 Agent**  
   打开命令提示符，进入 Agent 的目录并运行以下命令：

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

2. **验证连接**
   - 登录 Dashboard，查看是否有新设备上线。
   - 如果日志中没有报错信息，说明安装成功。

---

#### 5. 设置为服务运行

1. **安装为服务**

   - 进入 Agent 的目录，在命令提示符中运行：
     ```powershell
     nezha-agent.exe service install
     ```

2. **启动服务**

   - 安装成功后，Agent 会自动以服务形式启动，重启系统时也会自动运行。

3. **卸载服务**
   - 如需卸载服务，运行以下命令：
     ```powershell
     nezha-agent.exe service uninstall
     ```



---

### 在 OpenWrt 系统中安装 Agent


  点击展开/收起

OpenWrt 是轻量级 Linux 系统，需通过手动下载和配置安装 Nezha Agent。

---

#### 1. 准备工作

1. **确保管理员权限**

   - 通过 SSH 登录到 OpenWrt，使用 `root` 账户操作。

2. **安装必要工具**
   - 更新软件包列表并安装必要工具：
     ```bash
     opkg update
     opkg install wget unzip
     ```

---

#### 2. 下载 Nezha Agent

1. **确定系统架构**  
   使用以下命令获取架构信息：

   ```bash
   uname -m
   ```

   常见架构对应关系：

   - `x86_64` 对应 `nezha-agent_linux_amd64.zip`
   - `arm` 或 `aarch64` 对应 `nezha-agent_linux_arm.zip`

2. **下载适配的 Nezha Agent**

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

3. **解压文件**  
   解压文件至 `/etc/nezha` 目录：
   ```bash
   mkdir -p /etc/nezha
   unzip nezha-agent.zip -d /etc/nezha
   ```

---

#### 3. 创建配置文件

1. **创建配置文件**  
   创建并编辑 `/etc/nezha/config.yml` 文件并填入以下内容：

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

   ```yaml
   client_secret: your_agent_secret
   debug: false
   disable_auto_update: false
   disable_command_execute: false
   disable_force_update: false
   disable_nat: false
   disable_send_query: false
   gpu: false
   insecure_tls: false
   ip_report_period: 1800
   report_delay: 3
   server: data.example.com:8008
   skip_connection_count: false
   skip_procs_count: false
   temperature: false
   tls: false
   use_atomgit_to_upgrade: false
   use_gitee_to_upgrade: false
   use_ipv6_country_code: false
   uuid: your_uuid
   ```

   - **字段说明**：
     - `server`：替换为您的 Dashboard 地址和端口，例如 `data.example.com:8008` `1.1.1.1:8008` `"[2606:4700:4700::1111]:8008"`。
     - `client_secret`：替换为 Dashboard 中对应用户的连接密钥。当前前台没有单独的连接密钥复制入口，建议直接使用服务器页面生成的安装命令，或从命令中的 `NZ_CLIENT_SECRET` 提取。
     - `uuid`：可以通过在线工具生成。

2. **保存配置文件**  
   确保配置文件路径正确：`/etc/nezha/config.yml`。

---

#### 4. 运行 Agent

1. **赋予执行权限并启动 Agent**

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

2. **验证 Agent 连接**
   - 登录 Dashboard 检查是否有新设备上线。
   - 确认 Agent 运行状态正常。

---

#### 5. 设置为开机自启动

在 OpenWrt 上，可以通过创建服务脚本的方式实现 Nezha Agent 开机自启动。

---

1. **创建服务脚本**  
   在 `/etc/init.d/nezha-service` 中创建一个服务脚本：

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

2. **添加以下内容**  
   将以下内容复制到文件中，并根据需求修改 `nezha-agent` 的路径和配置文件路径：

   ```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
   }
   ```

3. **赋予执行权限**  
   保存文件后，赋予脚本执行权限：

   ```bash
   chmod +x /etc/init.d/nezha-service
   ```

4. **启用服务**  
   运行以下命令启用并启动服务：

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

5. **验证启动状态**  
   使用以下命令检查服务是否正常运行：
   ```bash
   ps | grep nezha-agent
   ```

---

#### 注意事项

- **配置文件路径**：确保脚本中配置文件的路径（如 `/etc/nezha/config.yml`）正确。
- **服务管理**：可以使用以下命令管理服务：
  - 手动启动服务：
    ```bash
    /etc/init.d/nezha-service start
    ```
  - 停止服务：
    ```bash
    /etc/init.d/nezha-service stop
    ```
  - 重启服务：
    ```bash
    /etc/init.d/nezha-service restart
    ```
- **日志排查**：如 Agent 无法正常启动，可通过 `logread` 检查相关日志。


---

## 卸载 Agent

卸载 Agent 包括停止服务、卸载服务，以及删除相关文件。以下是 Ubuntu 系统的卸载步骤：

1. 停止并卸载服务：

   ```bash
   cd /opt/nezha/agent/
   ./nezha-agent service uninstall
   ```

2. 删除 Agent 文件夹：
   ```bash
   rm -rf /opt/nezha/agent/
   ```

如果安装了多个服务并想要全部卸载，可以使用 Agent 安装脚本的卸载功能：

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

---

## 重新安装并指定 Agent 的 UUID

添加参数 UUID 让新的 Agent 连接后会继承原有的服务器记录和配置。

### 操作步骤

1. **复制服务器的 UUID**  
   进入 Dashboard，找到目标服务器并获取其对应的 UUID。

2. **生成安装命令并添加 UUID**  
   在生成的安装命令中，添加 `NZ_UUID=服务器的UUID` 参数。这样可以确保 Agent 正确绑定到指定的服务器记录。

3. **确认是否卸载旧 Agent**  
   如果服务器上已有 Agent，请确保卸载旧的 Agent，避免重复注册或冲突。

### 示例安装命令

以下是一个带有 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
```

将 `your_server_uuid` 替换为目标服务器的实际 UUID。

`NZ_CLIENT_SECRET` 需要使用目标用户的连接密钥，不是 Dashboard 配置文件中的全局 `agent_secret_key`。当前前台没有单独的连接密钥复制入口，优先以服务器页面生成的安装命令为准；管理员需要批量处理时，可通过管理接口读取对应用户的 `agent_secret`。

## 下一步

- 需要调整采集、更新或执行能力时查看 [Agent 配置](/configuration/agent.html)。
- 配置[服务监控](/guide/services.html)和[通知](/guide/notifications.html)。
- 上线授权终端或任务前阅读[安全与隐私](/guide/security.html)。
- Agent 无法上线时按[启动/上线自检流程](/guide/q2.html)排查。

---

## File: docs/guide/agentq.md

---
outline: deep
---

# Agent 常见问题

---

## Dashboard 搭建在只有 IPv6 的服务器上 / 使用 IPv6 地址， Agent 该怎么使用 IPv6 连接面板？

解决办法：
1. 修改`server`字段，例如 `"[2606:4700:4700::1111]:8008"`
2. 为 Dashboard 使用的域名添加 IPv6 解析（DNS AAAA 记录）

---

## 后台显示的 IP 和 Agent 实际 IP 不一致？

如果后台显示的 IP 和 Agent 的实际 IP 不一致，请参考 [Dashboard 相关 - 为什么管理面板中显示的 IP 和 Agent 实际 IP 不一致？](/guide/dashboardq.html#为什么管理面板中显示的-ip-和-agent-实际-ip-不一致)。
该问题的详细解决方法已在相关文档中说明，此处不再赘述。

---

## 一键脚本安装时出错

### 1. `curl: Failed to connect to raw.githubusercontent.com......`

此问题多发生在中国大陆的服务器上，原因是 Github 的连接不稳定。解决方法：
1. **多次尝试**：直接多尝试几次运行一键脚本。
2. **手动安装**：按照 [手动安装 Agent](/guide/agent.html#其他方式安装-agent) 的指南完成安装。
3. **使用加速服务**：可使用第三方 Github 加速服务或镜像。找到加速地址后，在一键安装脚本中进行替换。

---

### 2. `sudo: command not found`

如果提示 `sudo: command not found`，说明目标服务器未安装 `sudo` 工具。解决方法：
1. **手动安装 sudo**：
   - 对于 Ubuntu 系统，可以运行以下命令：
     ```shell
     apt install sudo
     ```
   - 对于 CentOS 系统，可以运行以下命令：
     ```shell
     yum install sudo
     ```
2. **检查安装成功**：安装完成后，再次运行一键脚本进行安装。

---

## Agent 安装目录出现多个配置文件，系统被安装了多个 Agent 服务

为重复运行 Agent 安装脚本所致。Agent 支持根据不同的配置文件安装多个系统服务，故脚本不会覆盖安装而是会安装新的配置到系统服务。

可以使用 Agent 脚本的卸载功能清除所有配置文件和对应的服务：

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

---

## Agent 有 Docker 镜像吗？

**Agent 目前没有推出 Docker 镜像。**  
Agent 的设计思路和 Dashboard 相反：Dashboard 的目标是尽量减少对宿主机的干扰，而 Agent 则需要深度与宿主机集成以执行监控服务和命令任务。  

虽然将 Agent 放入容器中可以继续执行监控任务，但 WebShell 等功能将无法正常运行，因此官方不提供 Docker 镜像支持。

---

## File: docs/guide/api.md

---
outline: deep
---

# API 接口

哪吒监控 V2 Dashboard 当前主要使用 `/api/v1` 路径；这里的 `v1` 是 API 路由版本，并不表示产品仍是 V1。接口返回 JSON，适合自定义前端、机器人、自动化脚本和内部运维工具使用。

如果需要完整、随源码同步的接口列表，建议优先使用 Dashboard 内置 Swagger 文档；本页保留常用接口和调用规则，方便快速上手。

---

## 获取完整 API 文档

Dashboard 在调试模式下会挂载 Swagger UI：

1. 编辑 Dashboard 配置文件，开启调试模式：

   ```yaml
   debug: true
   ```

2. 重启 Dashboard。

3. 查看 Dashboard 日志中的提示，默认地址类似：

   ```text
   http://localhost:8008/swagger/index.html
   ```

如果你是从源码开发，也可以在仓库根目录生成 Swagger 文件：

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

生成结果位于 `cmd/dashboard/docs`。

::: warning
`debug: true` 会额外暴露调试信息和 Swagger UI，不建议在公网生产环境长期开启。需要线上排查时，建议临时开启，完成后关闭并重启 Dashboard。
:::

---

## 认证方式

### 登录获取 Token

请求：

```http
POST /api/v1/login
Content-Type: application/json
```

请求体：

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

成功后返回：

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

后续需要登录的接口，在请求头中携带：

```http
Authorization: Bearer JWT_TOKEN
```

### Personal Access Token (PAT)

JWT 主要用于浏览器和管理前端的登录态；自动化脚本、CI、LLM 工具和 MCP 客户端建议使用 Personal Access Token（PAT）。PAT 请求头格式为：

```http
Authorization: Bearer nzp_<secret>
```

可以在管理前端的 **系统设置 → API Tokens** 中创建和吊销 PAT。创建 PAT 时需要填写：

- `name`：Token 名称，最长 128 个字符。
- `scopes`：权限列表，至少 1 项，最多 32 项。
- `server_ids`：可选的服务器 ID 白名单，最多 1000 项；留空表示不在用户原有服务器权限之外再加限制。
- `expires_in_days`：可选的过期天数，留空或 `0` 表示永不过期，最大值为 `3650`。

创建成功后，明文 Token 只会在响应中返回一次，请立即复制并妥善保存。之后列表接口只会返回脱敏后的 Token 元信息，例如权限、服务器白名单、过期时间、最后使用时间和最后使用 IP。

::: warning
`/api/v1/api-tokens` 这组 Token 管理接口只能使用登录 JWT 调用，不能用 PAT 自己创建、更改或删除 PAT。
:::

### PAT 权限范围

PAT 使用 `nezha:{resource}:{verb}` 命名权限范围。JWT 登录请求不走 PAT scope 校验；PAT 请求必须携带对应接口所需的 scope。

资源名包括：

- `server`
- `service`
- `alertrule`
- `cron`
- `ddns`
- `nat`
- `notification`
- `notification-group`
- `transfer`
- `admin`

动作名包括：

- `read`
- `write`
- `delete`
- `exec`

常见示例：

- `nezha:inventory:read`：列出服务器与服务器分组（`server.list`、`GET /api/v1/server`、`GET /api/v1/server-group`）。
- `nezha:inventory:delete`：删除服务器与服务器分组（`batch-delete/server`、`batch-delete/server-group`）。
- `nezha:server:read`：查看单台服务器、读取其指标与文件，以及服务器相关服务监控。
- `nezha:server:exec`：创建在线终端或调用 MCP 的远程执行工具。
- `nezha:cron:exec`：手动触发计划任务。
- `nezha:transfer:write`：取消或重试服务器转移任务。
- `nezha:admin:*`：用户、WAF、在线用户、系统设置和维护等管理员资源。

通配 scope：

- `nezha:<resource>:*`：允许某个资源下的所有动作，例如 `nezha:server:*`。
- `nezha:admin:*`：允许管理员资源，只有管理员可以签发。
- `nezha:*`：完整权限，只有管理员可以签发。

### PAT 禁用接口

以下接口属于个人账户自我管理流程，会显式拒绝 PAT，必须使用登录 JWT 调用：

- `POST /api/v1/refresh-token`
- `GET /api/v1/profile`
- `POST /api/v1/profile`
- `POST /api/v1/oauth2/{provider}/unbind`
- `GET /api/v1/api-tokens`
- `POST /api/v1/api-tokens`
- `DELETE /api/v1/api-tokens/{id}`

### 游客可访问接口

部分只读接口支持游客访问，但会受到站点配置和服务器隐藏设置限制：

- 开启 `force_auth` 后，游客不能访问服务器和服务监控数据。
- 如果服务器启用了“对游客隐藏”，游客不能访问该服务器的数据。
- 服务历史和服务器指标接口中，游客只能查询 `1d` 周期数据。

### API Token (PAT)

API Token 是同一套 `/api/v1` REST API 的另一种认证方式，也可以称为 PAT（Personal Access Token）。它和登录接口返回的 JWT 共用 `Authorization: Bearer ...` 请求头，也共用下方的接口返回格式和路由；区别是 JWT 面向浏览器登录会话，API Token 面向脚本、自动化工具和 MCP 客户端。

明文 Token 统一以 `nzp_` 开头。Dashboard 只保存哈希，明文只会在创建成功后显示一次；关闭弹窗后无法再次查看，需要重新创建。

登录管理前端，进入 **设置 > API Tokens**，点击 **Create API Token** 创建。创建时需要填写：

| 字段 | 说明 |
| --- | --- |
| 名称 | 便于识别用途，例如 `homepage-readonly`、`mcp-maintenance`。最长 128 个字符。 |
| Scopes | Token 可以调用哪些资源和动作。至少选择一个。 |
| Server IDs | 可选的服务器 ID 白名单，使用英文逗号分隔，例如 `1,2,3`。留空表示不额外限制服务器，但仍受用户自身权限限制。 |
| Expires in days | 可选过期天数。默认前端填入 `90`；留空或填 `0` 表示永不过期。最大 3650 天。 |

普通用户可以创建、查看和吊销自己的 Token。管理员同样通过该页面管理自己的 Token，并且只有管理员可以签发 `nezha:admin:*` 或 `nezha:*` 这类管理员 scope。

REST API 调用方式与 JWT 相同：

```http
Authorization: Bearer nzp_xxxxxxxxxxxxxxxxxxxx
```

API Token 使用 `nezha:{resource}:{verb}` scope 控制权限，且只会收窄当前用户原本拥有的权限；即使 Token 带有某个 scope，仍然不能越过用户本身的服务器、管理员或资源归属限制。创建 Token 时还可以填写服务器 ID 白名单，空白表示不额外限制服务器。

常见错误：

| 状态码 | 含义 |
| --- | --- |
| `401 Unauthorized` | Token 无效、已过期、所属用户不存在，或 `Authorization` 头格式错误。 |
| `403 Forbidden` | Token 有效，但缺少当前接口需要的 scope，服务器不在白名单内，用户没有该服务器权限，或接口明确禁止 API Token 调用。 |

常用 scope：

| Scope | 说明 |
| --- | --- |
| `nezha:inventory:read` | 读取服务器清单、服务器分组和实时服务器状态流 |
| `nezha:inventory:delete` | 删除服务器和服务器分组 |
| `nezha:server:read` | 读取已知服务器详情、指标、服务状态和文件列表/文件内容 |
| `nezha:server:write` | 修改服务器、下发配置、强制更新、迁移服务器和写入文件 |
| `nezha:server:delete` | 删除服务器上的文件 |
| `nezha:server:exec` | 打开在线终端、执行命令 |
| `nezha:service:read/write/delete` | 读取、创建/修改、删除服务监控 |
| `nezha:alertrule:read/write/delete` | 读取、创建/修改、删除警报规则 |
| `nezha:cron:read/write/delete/exec` | 读取、创建/修改、删除、手动触发计划任务 |
| `nezha:ddns:read/write/delete` | 读取、创建/修改、删除 DDNS 配置 |
| `nezha:nat:read/write/delete` | 读取、创建/修改、删除 NAT 规则 |
| `nezha:notification:read/write/delete` | 读取、创建/修改、删除通知方式 |
| `nezha:notification-group:read/write/delete` | 读取、创建/修改、删除通知组 |
| `nezha:transfer:read/write/delete` | 读取、取消/重试、删除服务器迁移记录 |
| `nezha:<resource>:*` | 某个资源的全部动作，例如 `nezha:server:*` |
| `nezha:admin:*` | 用户、WAF、设置、在线用户等管理员接口，仅管理员可用 |
| `nezha:*` | 全部权限，仅管理员可用 |

`inventory` 与 `server` 是两个不同的资源域：前者管“能看到和删除哪些机器清单”，后者管“对已知服务器执行运行态操作”。因此只给 `nezha:server:exec` 的 Token 可以执行指定服务器命令，但不能枚举服务器列表；需要列表时还要授予 `nezha:inventory:read`。

REST 路由常见 scope 对照：

| 路由 | API Token 所需 scope |
| --- | --- |
| `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}` | 同时需要 `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` 各资源管理接口 | 对应资源的 `read`、`write`、`delete` scope |
| `/api/v1/user`、`/api/v1/waf`、`/api/v1/online-user`、`PATCH /api/v1/setting`、`POST /api/v1/maintenance` | `nezha:admin:*` 或 `nezha:*`，且调用用户必须是管理员 |

常见授权组合：

| 场景 | 建议 scope |
| --- | --- |
| 外部看板只读展示服务器清单 | `nezha:inventory:read` |
| 外部看板读取服务器详情和指标 | `nezha:inventory:read`、`nezha:server:read` |
| MCP 客户端查询服务器和读取小文件 | `nezha:inventory:read`、`nezha:server:read` |
| MCP 客户端执行维护命令 | `nezha:inventory:read`、`nezha:server:read`、`nezha:server:exec`，并设置服务器 ID 白名单 |
| MCP 客户端写入或上传文件 | `nezha:server:read`、`nezha:server:write`，并设置服务器 ID 白名单 |
| CI/CD 只触发指定计划任务 | `nezha:cron:read`、`nezha:cron:exec` |
| 运维脚本管理服务监控 | `nezha:service:read`、`nezha:service:write`，需要删除时再加 `nezha:service:delete` |
| 管理员自动化维护设置 | `nezha:admin:*`，仅管理员 Token 可用 |

如果 Token 用于单台或少量服务器，建议始终填写 `Server IDs` 白名单。这样即使 scope 较宽，也只能作用于指定服务器。

旧版 `mcp:*` scope 不再作为运行时权限使用。创建 Token 时，`mcp:server:read`、`mcp:server:exec`、`mcp:fs:read` 会被兼容重写为对应的 `nezha:*` scope；`mcp:fs:write`、`mcp:fs:delete`、`mcp:*` 会被拒绝。启动迁移会清理数据库中残留的危险旧 scope，清理后没有任何 scope 的 Token 会被删除。

::: warning
API Token 不能调用账号自管理接口，例如 `/api/v1/profile`、`/api/v1/refresh-token`、`/api/v1/oauth2/{provider}/unbind` 和 `/api/v1/api-tokens`。这些接口只能使用网页登录产生的 JWT。
:::

在 **设置 > API Tokens** 列表中点击 **Revoke** 可以吊销 Token。吊销后，新请求会立即失败；使用该 Token 的长连接会被取消，包括服务器实时状态流、迁移流、在线终端、文件管理连接，以及正在执行的 MCP `tools/call`、文件上传/下载传输和临时传输 URL。

---

## MCP 接入

Dashboard 提供独立的 MCP 入口：

```http
POST /mcp
Authorization: Bearer nzp_<secret>
```

MCP 不在 `/api/v1` 下，并且只接受 PAT，不接受 JWT。启用前需要在 Dashboard 配置或管理前端中打开 [`enable_mcp`](/configuration/dashboard.html#enable-mcp)。关闭后，Dashboard 会拒绝新的 MCP 调用，并中断相关的 MCP 传输任务。

为兼容 Streamable HTTP 客户端，`GET /mcp` 和 `DELETE /mcp` 会明确返回 method-not-allowed；实际调用应使用 `POST /mcp`。文件传输类工具会使用 `GET /mcp/download/:token` 和 `POST /mcp/upload/:token` 作为临时传输地址。

MCP 入口带有 Origin 防护，用于降低浏览器跨站调用和 DNS rebinding 风险。仍然建议只给 MCP 客户端签发最小权限 PAT，并在不使用 MCP 时关闭 `enable_mcp`。

### MCP 工具权限

| 工具 | 所需 scope |
| --- | --- |
| `meta.whoami` | 任意有效 PAT |
| `server.list` | `nezha:inventory:read` |
| `server.get` | `nezha:server:read` |
| `server.exec` | `nezha:server:exec` |
| `fs.list` / `fs.read` / `fs.download_url` | `nezha:server:read` |
| `fs.write` / `fs.upload_url` | `nezha:server:write` |
| `fs.delete` | `nezha:server:delete` |

## 返回格式

普通接口返回：

```json
{
  "success": true,
  "data": {}
}
```

失败时通常返回：

```json
{
  "success": false,
  "error": "error message"
}
```

带分页的列表接口返回：

```json
{
  "success": true,
  "data": {
    "value": [],
    "pagination": {
      "offset": 0,
      "limit": 10,
      "total": 100
    }
  }
}
```

---

## 常用接口

### 获取系统设置

请求：

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

说明：

- 可用于读取站点名称、语言、前端模板、OAuth2 提供方、TSDB 是否启用等基础信息。
- 未登录访问时只返回允许游客读取的配置。

### 获取服务器列表

请求：

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

说明：

- 返回当前用户有权限管理的服务器列表。
- 管理员可见所有服务器，普通用户只能看到自己名下的服务器。
- 如需实时状态流，请使用 `GET /api/v1/ws/server` WebSocket 接口。

### 获取服务器实时状态流

请求：

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

说明：

- 返回 WebSocket 数据流，用于实时刷新服务器在线状态和资源占用。
- 如果站点未开启 `force_auth`，游客也可以连接，但隐藏服务器不会出现在游客数据中。

### 获取服务监控概览

请求：

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

说明：

- 返回服务监控当前状态和周期流量统计。
- 登录用户可以看到自己有权限查看的数据；游客访问会受到 `force_auth` 和隐藏配置限制。

### 获取服务监控历史

请求：

```http
GET /api/v1/service/{id}/history?period=1d
```

参数：

- `id`：服务监控 ID。
- `period`：查询周期，可选 `1d`、`7d`、`30d`，默认 `1d`。

`1d` 周期使用 30 秒粒度，适合展示最近 24 小时的细粒度曲线；`7d` 和 `30d` 周期会使用更粗的聚合粒度，以减少查询和传输开销。

返回示例：

```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
            }
          ]
        }
      }
    ]
  }
}
```

::: tip
如果 Dashboard 未启用 TSDB，服务监控历史会从数据库读取；启用 TSDB 后会从 TSDB 查询。
:::

### 获取服务器指标历史

请求：

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

参数：

- `id`：服务器 ID。
- `metric`：指标名称，必填。
- `period`：查询周期，可选 `1d`、`7d`、`30d`，默认 `1d`。

`1d` 周期使用 30 秒粒度，适合展示最近 24 小时的细粒度曲线；`7d` 和 `30d` 周期会使用更粗的聚合粒度，以减少查询和传输开销。

支持的 `metric`：

- `cpu`
- `memory`
- `swap`
- `disk`
- `net_in_speed`
- `net_out_speed`
- `net_in_transfer`
- `net_out_transfer`
- `load1`
- `load5`
- `load15`
- `tcp_conn`
- `udp_conn`
- `process_count`
- `temperature`
- `uptime`
- `gpu`

返回示例：

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

::: warning
该接口依赖 TSDB。未启用 TSDB 时，接口仍会返回成功，但 `data_points` 为空。TSDB 配置详见 [管理面板配置](/configuration/dashboard.html#tsdb)。
:::

### 获取服务下的服务器

请求：

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

说明：

- 返回某个服务监控关联的服务器列表。
- 常用于自定义前端展示某个监控项的节点维度状态。

### 获取服务器下的服务监控

请求：

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

说明：

- 返回某台服务器关联的服务监控列表。
- 常用于服务器详情页展示该服务器参与的 HTTP、TCP、Ping 等监控项。

---

## 管理类接口

管理类接口均需要登录。使用 JWT 时按用户角色和资源归属判断权限；使用 PAT 时，还会额外校验所需 scope。常见路径和 PAT scope 如下，字段和请求体请以 Swagger 文档为准。

| 功能 | 常见路径 | PAT scope |
| --- | --- | --- |
| 用户和个人资料 | `/api/v1/profile`、`/api/v1/user`、`/api/v1/batch-delete/user` | 个人资料接口禁止 PAT；用户管理需要 `nezha:admin:*` |
| 服务器台账 | `GET /api/v1/server`、`/api/v1/batch-delete/server`、`GET /api/v1/server-group`、`/api/v1/batch-delete/server-group` | `nezha:inventory:read` / `delete` |
| 服务器 | `/api/v1/server/config`、`/api/v1/batch-move/server`、`/api/v1/force-update/server`、`PATCH /api/v1/server/{id}` | `nezha:server:read` / `write` |
| 服务器分组 | `POST /api/v1/server-group`、`PATCH /api/v1/server-group/{id}` | `nezha:server:write` |
| 服务器转移 | `/api/v1/transfer`、`/api/v1/transfer/{id}/cancel`、`/api/v1/transfer/{id}/retry`、`/api/v1/ws/transfer` | `nezha:transfer:read` / `write` |
| 通知方式 | `/api/v1/notification`、`/api/v1/batch-delete/notification` | `nezha:notification:read` / `write` / `delete` |
| 通知组 | `/api/v1/notification-group`、`/api/v1/batch-delete/notification-group` | `nezha:notification-group:read` / `write` / `delete` |
| 警报规则 | `/api/v1/alert-rule`、`/api/v1/batch-delete/alert-rule` | `nezha:alertrule:read` / `write` / `delete` |
| 服务监控 | `/api/v1/service/list`、`/api/v1/service`、`/api/v1/batch-delete/service` | `nezha:service:read` / `write` / `delete` |
| 定时任务 | `/api/v1/cron`、`/api/v1/cron/{id}/manual`、`/api/v1/batch-delete/cron` | `nezha:cron:read` / `write` / `exec` / `delete` |
| DDNS | `/api/v1/ddns`、`/api/v1/ddns/providers`、`/api/v1/batch-delete/ddns` | `nezha:ddns:read` / `write` / `delete` |
| NAT | `/api/v1/nat`、`/api/v1/batch-delete/nat` | `nezha:nat:read` / `write` / `delete` |
| 在线终端 | `/api/v1/terminal`、`/api/v1/ws/terminal/{id}` | `nezha:server:exec` |
| 文件管理 | `/api/v1/file`、`/api/v1/ws/file/{id}` | 同时需要 `nezha:server:read`、`nezha:server:write`、`nezha:server:delete` |
| WAF 和在线用户 | `/api/v1/waf`、`/api/v1/batch-delete/waf`、`/api/v1/online-user`、`/api/v1/online-user/batch-block` | `nezha:admin:*` |
| 系统设置和维护 | `PATCH /api/v1/setting`、`POST /api/v1/maintenance` | `nezha:admin:*` |

直接写管理类自动化脚本前，建议先在测试环境验证，避免批量修改服务器、通知、任务或用户配置。

通知方式和 DDNS 的读取接口会对敏感字段脱敏：通知方式不会返回已保存的 `url`、`request_header`、`request_body`，DDNS 不会返回已保存的 `access_secret`、`webhook_headers`。更新这些对象时，省略相应字段或传入空值会保留数据库中的原值，不会将其清空。自动化脚本不应把读取到的空值当作真实配置再覆盖回去；如需清空这些敏感字段，请删除并重新创建对象。

---

## MCP 入口

Dashboard 内置一个面向自动化客户端和 LLM 工具调用的 MCP (Model Context Protocol) HTTP 入口：

完整的客户端配置、工具参数示例和文件传输说明，见 [MCP 使用指南](/guide/mcp.html)。

```http
POST /mcp
Authorization: Bearer nzp_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
```

使用前需要在 Dashboard 配置或管理前端中启用 `enable_mcp`。该入口只接受 API Token，不接受 JWT；`GET /mcp` 和 `DELETE /mcp` 会返回 405。

当前实现支持 Streamable HTTP 的 POST 请求/响应，不提供 SSE 会话。JSON-RPC 请求体最大为 8 MiB，每个 Token 默认限制约为每秒 10 次、每分钟 120 次请求。常用 JSON-RPC 方法：

- `initialize`
- `tools/list`
- `tools/call`
- `notifications/initialized`
- `ping`

`tools/list` 会返回每个工具的 `inputSchema` 和 `outputSchema`。`tools/call` 成功时，结构化结果放在 `structuredContent`，并在 `content[0].text` 中提供同一结果的 JSON 文本；工具报错时只返回 `isError: true` 和文本错误信息，避免严格 MCP 客户端用成功输出 schema 校验错误对象。

已注册的 MCP 工具和所需 scope：

| 工具 | 所需 scope |
| --- | --- |
| `meta.whoami` | 任意有效 API Token |
| `server.list` | `nezha:inventory:read` |
| `server.get` | `nezha:server:read` |
| `server.exec` | `nezha:server:exec` |
| `fs.list`、`fs.read`、`fs.download_url` | `nezha:server:read` |
| `fs.write`、`fs.upload_url` | `nezha:server:write` |
| `fs.delete` | `nezha:server:delete` |

需要调用 Agent 的 MCP 工具要求目标 Agent 版本不低于 `v2.1.0`。`server.exec` 是非交互一次性命令，不分配 PTY，默认超时 30 秒，`timeout_seconds` 硬上限 300 秒；需要管道、重定向等 shell 语法时，请显式使用 `cmd: "sh"` 和 `args: ["-c", "..."]`。

文件工具分为两类：

- `fs.read` / `fs.write` 适合小文件或分段读取写入。`fs.read` 默认最多返回约 1 MiB，可使用 `offset`、`length` 和 `encoding: "utf8" | "base64"`。
- `fs.download_url` / `fs.upload_url` 会签发一次性临时 URL，通过 `GET /mcp/download/{token}` 或 `POST /mcp/upload/{token}` 走 Dashboard 到 Agent 的 IOStream 传输，单文件硬上限 100 MiB，`ttl_seconds` 范围为 30 到 600 秒。上传时必须发送 `Content-Length`，可在 URL 查询参数追加 `sha256=<64位十六进制>` 做端到端校验；`fs.upload_url` 还支持 `mode`、`create_dirs`、`if_match_sha256`。
- 同一目标服务器最多同时承载 40 条活跃 IOStream。MCP 文件传输会与在线终端、文件管理和内网穿透共同计入该上限；达到上限时应结束不用的流后重试。

MCP 调用同时受 API Token 的服务器 ID 白名单和用户原本权限限制。临时上传/下载 URL 在使用时还会重新校验 Token、scope、服务器白名单和服务器归属；Token 被撤销或关闭 `enable_mcp` 时，Dashboard 会撤销 MCP 传输流、清理临时 URL 并取消正在执行的 MCP RPC。

---

## 使用案例

### 获取服务器列表

```python
import requests

base_url = "https://nezha.example.com"
token = "JWT_TOKEN_OR_NZP_API_TOKEN"

response = requests.get(
    f"{base_url}/api/v1/server",
    headers={"Authorization": f"Bearer {token}"},
    timeout=10,
)
response.raise_for_status()

payload = response.json()
if not payload.get("success"):
    raise RuntimeError(payload.get("error", "unknown error"))

for server in payload["data"]:
    print(server["id"], server["name"])
```

### 查询 24 小时 CPU 历史

```python
import requests

base_url = "https://nezha.example.com"
server_id = 1

response = requests.get(
    f"{base_url}/api/v1/server/{server_id}/metrics",
    params={"metric": "cpu", "period": "1d"},
    timeout=10,
)
response.raise_for_status()

payload = response.json()
if not payload.get("success"):
    raise RuntimeError(payload.get("error", "unknown error"))

for point in payload["data"]["data_points"]:
    print(point["ts"], point["value"])
```

## 相关文档

- [版本与兼容性](/guide/version-compatibility.html)：区分产品 V2、组件 Release 与 `/api/v1`。
- [安全与隐私](/guide/security.html)：PAT 最小 scope、到期、存储与 MCP 风险。
- [架构与数据流](/guide/architecture.html)：API、WebSocket、gRPC、任务与 IOStream 的关系。

---

## File: docs/guide/architecture.md

---
title: 哪吒监控 V2 架构与数据流
outline: deep
---

# 哪吒监控 V2 架构与数据流

哪吒监控 V2 使用“一个 Dashboard 管理多个 Agent”的集中式拓扑。Dashboard 是控制面和展示入口，Agent 是部署在被监控节点上的数据采集与任务执行端。理解这条边界有助于正确设计域名、反向代理、权限、备份和故障排查。

## 逻辑拓扑

```text
浏览器 / API 客户端
          |
          | HTTPS / WebSocket
          v
+------------------------+        通知提供商 / DNS API
| Dashboard              |---------------------> 外部集成
| - 用户与管理前端       |
| - REST API / MCP       |
| - 告警与任务调度       |
| - 实时状态与权限控制   |
+-----------+------------+
            |        |
            |        +------> SQLite（配置、用户和业务数据）
            |        +------> 可选 TSDB（指标与服务监控历史）
            |
            | gRPC（可由 HTTPS 反向代理承载）
            v
     +------+------+------+
     | Agent | Agent | ... |
     +-------+-------+-----+
        |       |
        +-------> 本机指标、网络检查、授权任务
```

这是逻辑关系，不要求每个组件位于同一网络。关键条件是浏览器能够访问 Dashboard，且每个 Agent 能够访问 Dashboard 的 Agent 对接地址。

## Dashboard 是什么角色？

Dashboard 承担以下职责：

- 验证用户、API Token 和 Agent 连接身份。
- 接收 Agent 上报的主机信息、实时状态和任务结果。
- 维护服务器、分组、用户、服务、通知、任务、DDNS 和系统配置。
- 向用户前端、管理前端、REST API 和可选 MCP 入口提供数据。
- 评估服务状态与告警条件，并调用已配置的通知方式。
- 将终端、文件、任务、NAT 等授权请求转交到目标 Agent。

因此，Dashboard 不只是只读图表。启用远程运维能力后，它属于高权限控制面，应限制管理入口、使用 TLS、保护密钥并保持更新。

## Agent 是什么角色？

Agent 运行在每台被监控设备上，主要负责：

- 读取操作系统可提供的主机和网络状态。
- 使用连接密钥与自身 UUID 接入 Dashboard。
- 按 `report_delay` 等配置报告状态。
- 执行被分配的 HTTP、Ping 或 TCP 服务检查。
- 在没有被禁用且调用者有权限时执行终端、文件、任务、更新或 NAT 相关操作。

不需要远程操作的节点应使用 Agent 的 `disable_command_execute`、`disable_force_update`、`disable_nat` 等配置缩小能力范围。完整字段见 [Agent 配置](/configuration/agent.html)。

## 连接与反向代理

V2 的 Web 访问和 Agent 通信可以共用 Dashboard 监听端口，默认是 `8008`。实际部署通常有两种方式：

1. **直接访问 Dashboard 端口**：浏览器和 Agent 连接 `host:8008`。
2. **通过反向代理提供 HTTPS**：代理将普通 HTTP、WebSocket 和 gRPC 请求转发到 Dashboard。

反向代理必须正确支持 gRPC 和 WebSocket。当前 Agent/Dashboard 兼容 `Authorization` 和 `Grpc-Metadata-Authorization` 两种 gRPC 认证头；完整 Nginx、Caddy 和 CDN 注意事项见 [Dashboard 反向代理配置](/guide/q3.html)及 [WebSocket 排障](/guide/q4.html)。

如果公开访问域名和 Agent 通信域名不同，应分别设置 `dashboard_host` 和 `install_host`。它们还参与 OAuth2 回调 Host 与 NAT 保留域名判断，详见 [Dashboard 配置](/configuration/dashboard.html#dashboard-host)。

## 状态数据如何流动？

### 主机状态

Agent 将主机信息和状态流发送给 Dashboard。Dashboard 在内存中维护实时状态供页面和 API 查询；启用 TSDB 后，服务器历史指标会写入本地 TSDB。没有启用 TSDB 时，实时状态仍可使用，但服务器历史指标不可用，前端会锁定相应历史周期。

### 服务监控

Dashboard 根据服务的覆盖范围和特定服务器配置，将检查任务分配给 Agent。Agent 从自身网络位置访问 HTTP、ICMP 或 TCP 目标并返回结果。这样可以比较不同线路或地域到同一目标的可用性与延迟。

未启用 TSDB 时，服务监控历史从 SQLite 读取；启用 TSDB 后改为从 TSDB 查询。启用步骤和迁移限制见[如何启用 TSDB](/guide/q15.html)。

### 远程操作

浏览器或 API 发起终端、文件、任务等请求后，Dashboard 先验证用户或 Token 权限，再通过 Agent 的任务或 IOStream 通道转发。终端、文件管理、NAT 和 MCP 文件传输会使用有限的 IOStream 配额；需要时应关闭闲置会话。

## 数据存在哪里？

- **SQLite**：Dashboard 默认使用本地 SQLite 文件保存用户、配置和业务数据。
- **内存**：当前在线状态和运行时对象会在 Dashboard 内存中维护，进程重启后由 Agent 重新连接并报告。
- **可选 TSDB**：配置 `tsdb.data_path` 后启用内置时序存储，用于服务器指标和服务监控历史。
- **外部服务**：只有在配置相应通知、OAuth2 或 DDNS 提供商时，Dashboard 才会向这些服务发送请求；发送内容取决于具体模板和配置。

备份时不能只保存容器定义。安装脚本部署通常需要备份 `/opt/nezha`，并在迁移前停止 Dashboard 以获得一致数据，见[备份与恢复](/guide/q5.html)。

## 常见架构选择

### 单域名部署

同一 HTTPS 域名同时服务浏览器和 Agent，配置最简单。反向代理必须同时正确处理 WebSocket 和 gRPC。

### 访问域名与通信域名分离

公开访问域名可接入 CDN，Agent 通信域名直接回源或使用明确支持 gRPC 的代理。该方式能绕开部分 CDN 对长连接或 gRPC 的限制，但需要正确设置两个 Host。

### 私有 Dashboard

通过 VPN、私有网络或访问控制层限制 Dashboard，适合不需要公开状态页的场景。必须确保所有 Agent 和管理员客户端仍能到达所需入口。

## 上线前检查

- [安装 Dashboard](/guide/dashboard.html)并替换默认密码。
- 为公开入口启用 HTTPS，正确配置真实 IP 请求头和可信 Host。
- 只向必要用户开放终端、文件、任务、NAT、API 与 MCP 权限。
- 为 Agent 关闭不需要的执行能力。
- 备份 SQLite、配置和 TSDB 目录，并验证恢复过程。
- 阅读[安全与隐私](/guide/security.html)和[版本与兼容性](/guide/version-compatibility.html)。

---

## File: docs/guide/comparison.md

---
title: 哪吒监控 V2 与其他监控工具怎么选？
outline: deep
---

# 哪吒监控 V2 与其他监控工具怎么选？

**哪吒监控 V2 适合希望在一套自托管 Web 界面中同时完成多服务器状态、网络服务探测、告警和常用远程运维的人。** 如果需求更集中在公开状态页、秒级深度可观测性、可编程指标查询或企业网络与资产监控，Uptime Kuma、Netdata、Prometheus/Grafana 或 Zabbix 可能更贴近主要目标。

这些工具并非只能互相替代。例如，可以用哪吒管理 VPS 和远程操作，同时用 Prometheus/Grafana 观察应用指标，或用 Uptime Kuma 提供独立公开状态页。

## 一页对比

| 工具 | 官方定位与主要关注点 | 典型架构 | 更适合优先评估的场景 |
| --- | --- | --- | --- |
| [哪吒监控 V2](https://github.com/nezhahq/nezha) | 自托管服务器监控与运维：主机状态、HTTP/Ping/TCP 检查、告警、终端、文件、任务、DDNS、API | 中央 Dashboard + 每节点 Agent | VPS、多地域服务器、家庭实验室和小型团队，需要简洁状态视图与运维闭环 |
| [Uptime Kuma](https://github.com/louislam/uptime-kuma) | 易用的自托管可用性监控，覆盖 HTTP(S)、TCP、Ping、DNS、Push、WebSocket、Docker 等目标，并提供多状态页和多种通知 | 中央服务主动检查目标，也支持 Push 等监控类型 | 网站与端口可用性、证书、通知和公开状态页是核心需求 |
| [Netdata](https://learn.netdata.cloud/docs/welcome-to-netdata/) | 分布式实时可观测性，采集系统和应用指标与日志，提供自动仪表板、告警和异常检测 | 每节点 Agent，可选 Parent 聚合与 Netdata Cloud 控制面 | 需要高粒度实时指标、自动发现、深入主机/应用排障或日志关联 |
| [Prometheus + Grafana](https://prometheus.io/docs/introduction/overview/) | Prometheus 采集和存储带标签的时序指标并用 PromQL 查询；Grafana 查询、可视化和告警多种指标、日志与追踪数据源 | Prometheus、exporter、服务发现、Alertmanager 与 Grafana 等可组合组件 | 云原生、微服务、自定义应用指标、复杂查询和可组合可观测性平台 |
| [Zabbix](https://www.zabbix.com/documentation/current/en/manual/introduction/about) | 企业级分布式开源监控，覆盖服务器、网络、虚拟机、应用、服务、数据库和网站，支持轮询、接收、模板、告警与可视化 | Server + 数据库 + Web 前端，可加入 Proxy 和 Agent | 需要广泛协议、模板、网络设备、自动发现、代理分层和企业流程的环境 |

表格只概括主要关注点，不表示某工具完全不具备其他能力。功能和许可会变化，决策前应查看各项目当前官方文档。

## 哪吒监控 V2 vs Uptime Kuma

两者都能自托管并检查 HTTP、Ping 和 TCP 目标，也都提供通知和易读的 Web 界面。区别主要在默认问题域：

- **选择哪吒优先**：你还需要每台服务器的 CPU、内存、磁盘、流量与在线状态，并希望使用终端、文件、任务、DDNS 或服务器 API。
- **选择 Uptime Kuma 优先**：主要目标是多类型端点可用性、证书和面向访客的多个状态页，不需要在所有服务器安装运维 Agent。
- **组合使用**：用哪吒观察和管理主机，用独立 Uptime Kuma 从外部检查公开服务，降低“监控系统和被监控服务同故障域”的风险。

Uptime Kuma 的当前类型和状态页能力以其[官方 README](https://github.com/louislam/uptime-kuma#features)为准。

## 哪吒监控 V2 vs Netdata

两者都在节点安装 Agent，但采集深度和操作模型不同：

- **选择哪吒优先**：需要低门槛的多服务器总览、基础资源与流量、服务可用性、通知和远程运维功能。
- **选择 Netdata 优先**：需要每秒级实时指标、广泛自动采集、自动仪表板、异常检测，以及面向主机和应用的深度排障。
- **组合使用**：哪吒负责资产总览和日常操作，Netdata 负责出现性能问题后的高粒度调查。

Netdata 的 Agent、Parent、Cloud 和数据边缘存储设计见其[官方概览](https://learn.netdata.cloud/docs/welcome-to-netdata/)。某些集中管理或协作能力可能涉及 Netdata Cloud 与对应方案，选型时应单独核对。

## 哪吒监控 V2 vs Prometheus/Grafana

Prometheus/Grafana 通常是一套可组合生态，而不是与哪吒一一对应的单体工具：

- **选择哪吒优先**：主要管理服务器和网络检查，希望安装后很快获得固定的数据模型与运维界面，不准备设计 exporter、标签、PromQL、告警和仪表板体系。
- **选择 Prometheus/Grafana 优先**：需要采集自定义应用或业务指标、使用多维标签和 PromQL、接入 Kubernetes/服务发现，或跨指标、日志、追踪数据源建立仪表板。
- **组合使用**：Prometheus/Grafana 负责应用和平台可观测性，哪吒作为独立的主机在线状态、线路检查和授权运维入口。

Prometheus 的拉取模型、时序数据和适用边界见[官方 Overview](https://prometheus.io/docs/introduction/overview/)；Grafana 的数据源、可视化和告警定位见[官方 Introduction](https://grafana.com/docs/grafana/latest/introduction/)。

## 哪吒监控 V2 vs Zabbix

两者都能使用 Agent 监控服务器并提供告警，但默认规模与配置模型不同：

- **选择哪吒优先**：服务器数量与网络结构相对直接，重视快速部署、现代简洁界面和终端/文件/任务等日常运维入口。
- **选择 Zabbix 优先**：需要 SNMP、IPMI、JMX、VMware、网络发现、模板继承、Proxy 分布式采集、复杂触发器或企业级权限与流程。
- **组合使用**：Zabbix 管理网络与企业资产，哪吒提供部分 VPS 或独立节点的轻量视图与操作入口。

Zabbix 的轮询与接收、资产范围和分布式能力见[官方介绍](https://www.zabbix.com/documentation/current/en/manual/introduction/about)及[功能列表](https://www.zabbix.com/documentation/current/en/manual/introduction/features)。

## 用需求做最终选择

按顺序回答以下问题：

1. **监控对象是什么？** 主要是服务器、外部端点、应用指标、日志，还是网络设备？
2. **需要什么分辨率和保留期？** 不要把“能显示 CPU”误认为与秒级完整可观测性相同。
3. **是否需要远程操作？** 终端和文件管理能提升效率，也会扩大权限与攻击面。
4. **谁使用结果？** 个人、访客、小团队、SRE 还是企业网络运维，其权限和审计要求不同。
5. **愿意维护多少组件？** 更可组合的系统通常也需要更多数据模型、存储、查询和升级设计。
6. **故障域是否独立？** 如果监控服务和被监控目标部署在同一台机器或同一网络，整体故障时可能无法告警。

决定使用哪吒后，继续阅读[产品概览](/guide/overview.html)、[架构与数据流](/guide/architecture.html)、[安装 Dashboard](/guide/dashboard.html)和[安全与隐私](/guide/security.html)。

## 对比依据

本页只使用项目官方资料描述其主要定位：

- [Nezha Dashboard 官方仓库](https://github.com/nezhahq/nezha)
- [Uptime Kuma 官方仓库与功能列表](https://github.com/louislam/uptime-kuma)
- [Netdata 官方概览](https://learn.netdata.cloud/docs/welcome-to-netdata/)
- [Prometheus 官方概览](https://prometheus.io/docs/introduction/overview/)
- [Grafana 官方介绍](https://grafana.com/docs/grafana/latest/introduction/)
- [Zabbix 官方介绍](https://www.zabbix.com/documentation/current/en/manual/introduction/about)

本页不提供未经同一环境复现的性能、资源占用或成本排名。

---

## File: docs/guide/dashboard.md

---
outline: deep
---

# 安装 Dashboard

## 准备工作  

搭建哪吒监控的 Dashboard，你需要：
1. 一台可以连接公网的服务器。防火墙和安全策略需放行 8008 端口，否则无法访问或接收数据。单核 512MB 内存的服务器即可满足大多数使用场景。
2. 一个已设置好 A 记录，指向 Dashboard 服务器 IP 的域名。
::: tip  
如果你想使用 CDN，请准备两个域名：  
- 一个配置好 CDN，用作公开访问，CDN 需支持 WebSocket 协议；  
- 另一个域名不使用 CDN，用作 Agent 与 Dashboard 的通信。 

当前 V2 的访问和 Agent 通信可以共用同一端口；但不同 CDN 对 gRPC 和长连接的支持可能导致通信异常，因此仍建议按上述方式准备两个域名（非强制要求）。

本文档以 "dashboard.example.com" 和 "data.example.com" 为例。
:::

## 在服务器中安装 Dashboard

在面板服务器中，运行以下安装脚本：
```bash
curl -L https://raw.githubusercontent.com/nezhahq/scripts/refs/heads/main/install.sh -o nezha.sh && chmod +x nezha.sh && sudo ./nezha.sh
```  

如果你的服务器位于中国大陆，可以使用镜像：
```bash
curl -L https://gitee.com/naibahq/scripts/raw/main/install.sh -o nezha.sh && chmod +x nezha.sh && sudo CN=true ./nezha.sh
```

以 Docker 安装为例，安装完成后按提示输入以下信息：
- `请输入站点标题:` - 自定义站点标题。
- `请输入暴露端口:` - 公开访问端口（默认 8008，可自定义）。
- `请指定后台语言:` - 选择语言偏好。

输入完成后，等待拉取 Docker 镜像。安装结束后，如果一切正常，你可以通过域名和端口号访问 Dashboard，例如：  
`http://dashboard.example.com:8008`  

如果需要再次运行安装脚本，可输入以下命令：
```bash
./nezha.sh
```
打开管理脚本。

## 登录到 Dashboard 配置界面

后台管理界面的路径为 `/dashboard`，你只需访问：  
`http://dashboard.example.com:8008/dashboard`  

首次登录的默认用户名和密码均为 `admin`。

::: warning  
默认密码为弱密码，对于高权限的面板来说，使用弱密码非常危险！  
建议安装后立即进入管理页面：点击头像 → “个人信息” → “更新个人资料”修改密码。  
建议密码长度至少 18 位，并混合大小写字母、数字及符号。
:::

## 配置反向代理

[Dashboard 反向代理配置](/guide/q3.html)

## 更新 Dashboard

运行脚本：
```bash
./nezha.sh
```
选择重启面板并更新。

## 下一步

- [安装 Agent](/guide/agent.html)并确认第一台服务器上线。
- 阅读[架构与数据流](/guide/architecture.html)，核对反向代理和存储设计。
- 按[安全与隐私](/guide/security.html)完成生产环境加固。
- 升级前查看[版本与兼容性](/guide/version-compatibility.html)。

---

## File: docs/guide/dashboardq.md

---
outline: deep
---

# Dashboard 常见问题

---

## 为什么管理面板中显示的 IP 和 Agent 实际 IP 不一致？

管理面板中显示的 IP 是 Agent 使用 [IP-API](https://github.com/nezhahq/agent/blob/main/pkg/monitor/myip.go) 检测并上报的出口 IP。  
如显示的 IP 与服务商提供的 IP 不一致，可能原因如下：
1. **服务商使用入口 IP**：服务商提供的 IP 为高防或映射后的入口 IP，而非实际出口 IP。
2. **多线路或专线环境**：多线服务器或 IPLC 专线可能导致出口 IP 与预期不一致。

### 验证出口 IP
在 Agent 服务器中运行以下命令测试出口 IP：
```shell
curl https://ipapi.co/ip/
curl ip.sb
curl ip-api.com
```

---

## 面板安装/重启/更新失败：`iptables ......`

1. **重启 Docker**
   运行以下命令重启 Docker：
   ```shell
   systemctl status docker
   systemctl restart docker
   systemctl status docker
   ```

2. **关闭或移除 iptables**
   若问题仍未解决，尝试关闭或移除 `iptables`。

3. **更换官方内核**
   部分问题可能与内核有关，切换到官方内核后再尝试操作。

---

## 面板布局错误、CSS 资源无法被加载

通常由 CSS 文件丢失或无法加载导致。解决方法如下：
1. **重启并更新面板**  
   执行一键脚本选择 `更新面板`。

2. **检查 Nginx 配置**  
   若问题未解决，检查并修改 Nginx 的 vhost 文件：
   - 在宝塔面板中找到安装 Dashboard 时配置的站点，点击 **`设置` → `配置文件`**。
   - 删除以下内容：
     ```nginx
     location ~ .*\.(js|css)?$
         {
             expires      12h;
             error_log /dev/null;
             access_log /dev/null;
         }
     ```
   - 保存配置，并清空浏览器、Nginx 和 CDN 的缓存。

3. **刷新页面**  
   此时页面应恢复正常。

---

## 面板无法启动：`panic：无法找到配置的 DDNS 提供者...`

DDNS 提供者配置错误。支持的值包括：`webhook`、`cloudflare`、`tencentcloud` 和 `dummy`。请确认配置正确。

---

## 面板更新 DDNS 崩溃：`panic：interface conversion: interface {} is nil, not []interface {}`

DDNS `AccessID` 或 `AccessSecret` 填写有误，请检查并更正。

---

## 面板警告：`NEZHA>> 错误的服务监控上报...`

此问题通常由于 Dashboard 和 Agent 的版本不匹配导致。  
解决方法：更新 Dashboard 和 Agent 至最新版本。

---

## 服务器网络监控页显示空白

此错误说明：
1. 未在服务页中设置 `TCP-Ping` 或 `ICMP-Ping` 类型的监控。
2. 数据尚未生成。  
解决方法：完成设置后等待一段时间，再查看监控数据。

---

## 启用 HTTPS 后 `/terminal` 或 `/ws` 无法正常连接

此问题多因证书不完整导致：
1. 查看日志是否出现：
   ```plaintext
   x509:certificate signed by unknown authority
   ```
2. 若有该错误，更换完整证书即可解决。

---

## 数据修改/功能扩展需求

若需对 Dashboard 提供的数据进行修改（如批量新建 Agent），可直接操作数据库。  
### 注意事项：
- 数据库类型为 `sqlite3`，位于 `/opt/nezha/dashboard/data/sqlite.db`。
- 修改数据前，请备份数据库。
- 修改时，务必 **停止面板容器**。  
::: danger  
请勿随意修改数据库！错误修改可能导致数据混乱或无法启动 Dashboard。
:::

---

## Dashboard 是否会自动更新？

Dashboard 不会自动更新，需要手动运行脚本进行更新。  
Agent 在默认情况下会自动更新。

---

## 连接在线终端时提示：`Agent 信令下发失败`

此问题可能由于以下原因导致：
1. **Agent 离线**：检查 Agent 是否正常运行。
2. **连接不稳定**：确认 Agent 与 Dashboard 的连接是否稳定，并排除网络问题。

---

## 复制安装命令时提示：`You have not specify the installed host.`

### 错误原因

此错误表示您尚未在设置页面中配置 **`Agent 对接地址【域名/IP:端口】`**。  
该项配置是生成安装命令的必要条件，未配置时无法正确生成安装命令。

---

### 解决方法

1. **进入设置页面**  
   登录 Dashboard，点击右上角头像，选择 **`系统设置`**。

2. **配置服务器域名/IP**  
   在 **`Agent 对接地址【域名/IP:端口】`** 项中填写 Agent 连接 Dashboard 使用的地址。  
   示例：
   - **域名**：`data.example.com:8008`
   - **IP**：`123.123.123.123:8008`

3. **保存设置**  
   完成配置后，保存设置并返回安装命令页面，重新复制安装命令。

---

## File Manager 下载/上传时卡住

### 问题原因

1. **缓冲区设置问题**  
   File Manager (FM) 在传输文件时，每次发送的数据块大小为 **1 MiB**。如果代理的缓冲区小于 1 MiB，可能会导致传输卡住。

2. **CDN 影响性能**  
   使用 CDN 可能会严重降低文件传输性能，甚至导致卡顿。


### 解决方法

#### 1. 检查并调整代理缓冲区

对于常见的代理服务器（如 Nginx 和 Caddy），确保其缓冲区大于 1 MiB：

**Nginx 配置示例**：
```nginx
proxy_buffer_size 2m;
proxy_buffers 4 2m;
proxy_busy_buffers_size 4m;
```
- 将以上配置添加到 Nginx 的站点配置中，保存后重新加载配置：
  ```bash
  sudo nginx -s reload
  ```

**Caddy 配置示例**：
```caddy
reverse_proxy {
    transport http {
        read_buffer 2MB
        write_buffer 2MB
    }
}
```
- 将缓冲区大小设置为至少 2 MiB，保存配置并重启 Caddy 服务。

#### 2. 尝试直接连接

如果使用 CDN，建议绕过 CDN，直接连接到源服务器进行文件传输。  
检查连接方式是否直接指向源服务器的 IP 或域名，并确保网络畅通。

---

## 使用 Nginx 反代 gRPC 无法连接 Agent

当前版本的 Agent 会同时发送连字符形式的 `client-secret`、`client-uuid` 和旧版下划线形式的认证 Header，Dashboard 也同时兼容两种形式。因此，当 Dashboard 为 `v2.2.1` 或更高版本、Agent 为 `v2.2.2` 或更高版本时，通常不再需要为下划线 Header 设置 `underscores_in_headers` 或 `ignore_invalid_headers`。

如果仍无法连接，请优先确认：

1. Dashboard 与 Agent 均已升级，并重新生成或核对安装命令中的连接地址、UUID 和密钥。
2. Nginx 的 gRPC location 使用 `grpc_pass`，且没有清除 `client-secret` 或 `client-uuid`。
3. TLS 开关与代理入口协议一致，并查看 Dashboard、Agent 和 Nginx 错误日志。

只有在必须兼容旧版 Agent 或 Dashboard 时，才需要保留旧配置：在 `server` 块启用 `underscores_in_headers on;` 和 `ignore_invalid_headers off;`，并按需转发 `client_secret`、`client_uuid`。升级完成后可移除这组兼容设置。

---

## 在线终端、文件管理或内网穿透提示并发流过多

Dashboard 会限制活跃 IOStream 数量，避免大量终端、文件传输或穿透连接占满资源：

- `too many concurrent streams for this user`：同一用户已占用 20 条在线终端或文件管理流。
- `too many concurrent streams for this server`：同一目标服务器已占用 40 条流；此统计包括在线终端、文件管理、内网穿透和 MCP 文件传输。

关闭已经不用的终端、文件管理窗口、穿透连接或文件传输后再重试。若数量看起来不符，请先确认相关客户端确实已断开，再检查 Dashboard 日志定位未结束的连接。

---

## File: docs/guide/ddns.md

---
outline: deep
---

# DDNS

DDNS 功能适用于使用动态 IP 的服务器。当 Agent 上报一个新 IP 时，Dashboard 会根据配置自动更新 DNS 记录。

## 为什么使用哪吒监控的 DDNS 功能？

- **集中管理**：方便在 Dashboard 中集中管理 DDNS 设置，无需在每台服务器上部署单独的 DDNS 服务。
- **更高安全性**：机密信息仅存储在面板服务器中，降低泄露风险。

## 配置说明

可以直接在 Dashboard 的管理页面中添加 DDNS 配置。

1. **进入动态域名解析配置页面**  
   点击菜单栏中的“动态域名解析”，进入配置页面。  
2. **新建配置**  
   点击“新配置”按钮，在弹出窗口中填写相关信息：
   - **名称**：配置的名称，便于管理。
   - **DDNS 供应商**：选择提供服务的供应商类型。
   - **域名（逗号分隔）**：填写需要更新的域名，多个域名用逗号分隔。支持 IDN（国际化域名）。
   - **最大重试次数**：DDNS 更新的最大尝试次数，默认为 3，可设置范围为 1-10 的整数。
   - **DDNS 凭据 1** 和 **DDNS 凭据 2**：凭据选填，具体需求参见[供应商列表](#供应商列表)。
3. **Webhook 特殊说明**  
   如果使用 `webhook` 供应商，请根据[Webhook 配置说明](#webhook-配置说明)填写相关选项。
4. **启用选项**  
   至少勾选 **启用 DDNS IPv4** 或 **启用 DDNS IPv6**，否则不会进行更新。
5. **关联服务器**  
   添加配置后，需要修改服务器设置以启用 DDNS 功能：  
   - **启用 DDNS**：在 `服务器` 页面中为目标服务器启用 DDNS。  
   - **DDNS 配置**：选择适用的 DDNS 配置 ID，支持通过名称搜索。

## Webhook 配置说明

Webhook 支持自定义 HTTP 请求，适用于第三方供应商或其他定制化需求。

### 选项说明

- **Webhook URL**：目标请求的 URL，支持占位符替换。
- **Webhook 请求方式**：支持 `GET`、`POST`、`PATCH`、`DELETE` 和 `PUT`。
- **Webhook 请求类型**：请求体格式，可选择 `JSON` 或 `Form`。
- **Webhook 请求头**：以 JSON 格式填写请求头，注意不支持嵌套。
- **Webhook 请求体**：`GET` 和 `DELETE` 不使用请求体；如果使用嵌套格式，请选择 `JSON` 类型。

读取 DDNS 配置时，API 和管理前端会隐藏凭据 2（`access_secret`）及 Webhook 请求头。编辑时将这些敏感字段留空会保留原值；如果需要清空已保存的值，请删除并重新创建该 DDNS 配置。

### 占位符说明

| 占位符      | 含义                   |
| ----------- | ---------------------- |
| `#ip#`      | 主机 IP 地址            |
| `#domain#`  | 域名（每次单独请求）    |
| `#type#`    | IP 类型：`"ipv4"` 或 `"ipv6"` |
| `#record#`  | 记录类型：`"A"` 或 `"AAAA"` |
| `#access_id#` | DDNS 凭据 1           |
| `#access_secret#` | DDNS 凭据 2       |

### 花生壳 Webhook 示例

  点击展开/收起

- **URL**：`http://ddns.oray.com/ph/update?hostname=#domain#&myip=#ip#`
- **请求方式**: `GET`
- **请求头**:  
  ```json
  {
    "Authorization": "Basic pass"
  }
  ```
  其中 `pass` 是 Base64 编码后的用户名和密码（例如，`user:pass` 转换为 `dXNlcjpwYXNzCg==`）。
- **注意**：花生壳仅支持 A 记录，因此只需启用 IPv4。



## 供应商列表

| 供应商         | 凭据1（ID） | 凭据2（Secret） |
| -------------- | ----------- | --------------- |
| `dummy`        | ❌️          | ❌️              |
| `webhook`      | 可选        | 可选            |
| `cloudflare`   | ❌️          | ✅               |
| `tencentcloud` | ✅          | ✅               |
| `he`           | ❌️          | ✅              |


### `cloudflare` Token 权限

Token 需要为目标域名分配以下权限:
   `区域.区域:读取`, `区域.DNS:编辑`

### `he` Secret 获取

`he` 供应商使用每个记录独有的 DDNS 密钥作为 Secret，因此必须先创建对应 A/AAAA 记录，勾选 `Enable entry for dynamic dns`，之后再在对应的 DDNS 栏中设置新的 DDNS 密钥。

## 查看日志

在 Dashboard 的日志页面，可以查看 DDNS 更新的详细记录。如果配置正确，日志中会显示更新状态。例如：

```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成功
```

---

## File: docs/guide/group.md

---
outline: deep
---

# 分组管理

分组管理允许用户更高效地组织服务器和通知设置，提高 Dashboard 的可读性和操作便捷性。

---

## 服务器分组

### 功能说明
服务器分组用于在 Dashboard 中为服务器分类管理。分组后的服务器会在不同的标签页中展示，便于快速查找和区分。

### 配置步骤
1. **进入服务器页面**  
   在服务器页面中完成服务器的基础配置。

2. **设置分组**  
   为服务器设置分组名称，相同分组名称的服务器会被归类到同一个标签页。

### 应用场景
- **区域划分**：按地理位置（如 `中国区`、`海外区`）对服务器进行分组。
- **用途划分**：按服务器用途（如 `数据库`、`Web服务`）分组。
- **部门划分**：按使用部门（如 `研发部`、`运营部`）分组。

---

## 通知分组

### 功能说明
通知分组允许用户将多个通知方式组合成一个通知组，通知组可用作任务或告警的通知目标，实现一键发送多种方式的通知。

### 配置步骤
1. **进入通知页面**  
   在通知页面中配置所需的通知方式（如 Telegram、邮件、钉钉等）。

2. **创建通知组**  
   将一个或多个通知方式添加到同一个通知组中，命名该分组便于识别。

3. **应用通知组**  
   在任务或告警规则中选择通知组作为通知目标，触发时会同时通过分组内的所有通知方式发送通知。

### 应用场景
- **多渠道通知**：通过 Telegram 和邮件同时接收服务器告警。
- **分级通知**：针对不同告警类型或服务器分组，设置不同的通知组（如 `高优先级` 通知组与 `普通通知组`）。