nezha Documentation

1. Project Overview & Quickstart (nezhahq/nezha) Copy Chapter

>> Telegram Channel: 哪吒监控（中文通知频道）
>> Telegram Group: Nezha Monitoring Global (English Only), 哪吒监控（中文群组）

>> Use Cases | 我们的用户 (Google)

User Guide Copy Chapter

• English
• 中文文档

Contributing Copy Chapter

Translation Copy Section

Is Nezha not in your language, or the translation is incorrect or incomplete? Get involved in the translations on Hosted Weblate.

Screenshots Copy Chapter

add your theme to service/singleton/frontend-templates.yaml

Contributors Copy Chapter

Special Thanks Copy Chapter

• IPInfo for providing an accurate GeoIP Database.

Star History Copy Chapter

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

File: README.md Copy Chapter

Nezha Monitoring V2 Documentation

Official Chinese and English documentation for Nezha Monitoring V2, 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 Copy Chapter

• Nezha Dashboard
• Nezha Agent
• Chinese documentation
• English documentation

Local development Copy Chapter

npm ci
npm run dev

Build and audit generated SEO metadata:

npm test

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

File: docs/guide/agent.md Copy Chapter

outline: deep Copy Chapter

安装 Agent

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

一键安装 Agent Copy Chapter

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

准备工作 Copy Section

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

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

一键安装步骤 Copy Section

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

平台特有说明 Copy Section

Windows 特殊说明

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

其他方式安装 Agent Copy Chapter

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

点击展开/收起

由于群晖（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 Copy

   uname -m

   常见架构对应关系：

   • x86_64 对应 amd64
   • armv7l 或 aarch64 对应 arm

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

   bash Copy

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

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

   bash Copy

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

4. 赋予运行权限

   bash Copy

   chmod +x /opt/nezha/nezha-agent

3. 创建配置文件

1. 创建并编辑配置文件
   在 /opt/nezha 目录下创建 config.yml 文件，并添加以下内容：
   yaml Copy

   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 Copy

       uuidgen

   • 保存文件：将文件保存至 /opt/nezha/config.yml。

4. 创建 systemctl 服务文件

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

   bash Copy

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

2. 添加以下内容：

   ini Copy

   [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 Copy

   sudo systemctl daemon-reload

5. 启动 Agent

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

   bash Copy

   sudo systemctl start nezha-agent

2. 设置开机自启动

   bash Copy

   sudo systemctl enable nezha-agent

3. 查看服务状态
   确保 Agent 已成功启动：

   bash Copy

   sudo systemctl status nezha-agent

6. 验证 Agent 连接

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

在 Windows 系统中手动安装 Agent Copy Section

点击展开/收起

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

1. 准备工作

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

2. 安装必要工具

   • 确保有解压工具（如 7-Zip 或 WinRAR）。

2. 下载 Nezha Agent

1. 确认系统架构

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

2. 下载 Nezha Agent 文件

   • 访问 Nezha Agent Releases，下载适用于 Windows 的版本，例如：
     plaintext Copy

     nezha-agent_windows_amd64.zip

3. 解压文件

   • 将下载的压缩包解压到指定目录，例如：C:\nezha。

3. 创建配置文件

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

   yaml Copy

   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 Copy

   nezha-agent.exe -c config.yml

2. 验证连接

   • 登录 Dashboard，查看是否有新设备上线。
   • 如果日志中没有报错信息，说明安装成功。

5. 设置为服务运行

1. 安装为服务

   • 进入 Agent 的目录，在命令提示符中运行：
     powershell Copy

     nezha-agent.exe service install

2. 启动服务

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

3. 卸载服务

   • 如需卸载服务，运行以下命令：
     powershell Copy

     nezha-agent.exe service uninstall

在 OpenWrt 系统中安装 Agent Copy Section

点击展开/收起

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

1. 准备工作

1. 确保管理员权限

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

2. 安装必要工具

   • 更新软件包列表并安装必要工具：
     bash Copy

     opkg update
     opkg install wget unzip

2. 下载 Nezha Agent

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

   bash Copy

   uname -m

   常见架构对应关系：

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

2. 下载适配的 Nezha Agent

   bash Copy

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

3. 解压文件
   解压文件至 /etc/nezha 目录：

   bash Copy

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

3. 创建配置文件

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

   bash Copy

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

   yaml Copy

   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 Copy

   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 Copy

   vi /etc/init.d/nezha-service

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

   bash Copy

   #!/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 Copy

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

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

   bash Copy

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

5. 验证启动状态
   使用以下命令检查服务是否正常运行：

   bash Copy

   ps | grep nezha-agent

注意事项

• 配置文件路径：确保脚本中配置文件的路径（如 /etc/nezha/config.yml）正确。
• 服务管理：可以使用以下命令管理服务：
  • 手动启动服务：
    bash Copy

    /etc/init.d/nezha-service start

  • 停止服务：
    bash Copy

    /etc/init.d/nezha-service stop

  • 重启服务：
    bash Copy

    /etc/init.d/nezha-service restart

• 日志排查：如 Agent 无法正常启动，可通过 logread 检查相关日志。

卸载 Agent Copy Chapter

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

1. 停止并卸载服务：

   bash Copy

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

2. 删除 Agent 文件夹：

   bash Copy

   rm -rf /opt/nezha/agent/

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

./agent.sh uninstall

重新安装并指定 Agent 的 UUID Copy Chapter

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

操作步骤 Copy Section

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

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

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

示例安装命令 Copy Section

以下是一个带有 UUID 参数的完整安装命令示例：

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。

下一步 Copy Chapter

• 需要调整采集、更新或执行能力时查看 Agent 配置。
• 配置服务监控和通知。
• 上线授权终端或任务前阅读安全与隐私。
• Agent 无法上线时按启动/上线自检流程排查。

File: docs/guide/agentq.md Copy Chapter

outline: deep Copy Chapter

Agent 常见问题

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

解决办法：

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

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

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

一键脚本安装时出错 Copy Chapter

1. `curl: Failed to connect to raw.githubusercontent.com......` Copy Section

此问题多发生在中国大陆的服务器上，原因是 Github 的连接不稳定。解决方法：

1. 多次尝试：直接多尝试几次运行一键脚本。
2. 手动安装：按照 手动安装 Agent 的指南完成安装。
3. 使用加速服务：可使用第三方 Github 加速服务或镜像。找到加速地址后，在一键安装脚本中进行替换。

2. `sudo: command not found` Copy Section

如果提示 sudo: command not found，说明目标服务器未安装 sudo 工具。解决方法：

1. 手动安装 sudo：
   • 对于 Ubuntu 系统，可以运行以下命令：
     shell Copy

     apt install sudo

   • 对于 CentOS 系统，可以运行以下命令：
     shell Copy

     yum install sudo

2. 检查安装成功：安装完成后，再次运行一键脚本进行安装。

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

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

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

./agent.sh uninstall

Agent 有 Docker 镜像吗？ Copy Chapter

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

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

File: docs/guide/api.md Copy Chapter

outline: deep Copy Chapter

API 接口

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

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

获取完整 API 文档 Copy Chapter

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

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

   yaml Copy

   debug: true

2. 重启 Dashboard。

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

   text Copy

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

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

./script/bootstrap.sh

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

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

认证方式 Copy Chapter

登录获取 Token Copy Section

请求：

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

请求体：

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

成功后返回：

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

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

Authorization: Bearer JWT_TOKEN

Personal Access Token (PAT) Copy Section

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

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 权限范围 Copy Section

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 禁用接口 Copy Section

以下接口属于个人账户自我管理流程，会显式拒绝 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}

游客可访问接口 Copy Section

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

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

API Token (PAT) Copy Section

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 创建。创建时需要填写：

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

REST API 调用方式与 JWT 相同：

Authorization: Bearer nzp_xxxxxxxxxxxxxxxxxxxx

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

常见错误：

常用 scope：

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

REST 路由常见 scope 对照：

常见授权组合：

如果 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 接入 Copy Chapter

Dashboard 提供独立的 MCP 入口：

POST /mcp
Authorization: Bearer nzp_<secret>

MCP 不在 /api/v1 下，并且只接受 PAT，不接受 JWT。启用前需要在 Dashboard 配置或管理前端中打开 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 工具权限 Copy Section

返回格式 Copy Chapter

普通接口返回：

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

失败时通常返回：

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

带分页的列表接口返回：

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

常用接口 Copy Chapter

获取系统设置 Copy Section

请求：

GET /api/v1/setting

说明：

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

获取服务器列表 Copy Section

请求：

GET /api/v1/server
Authorization: Bearer JWT_TOKEN

说明：

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

获取服务器实时状态流 Copy Section

请求：

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

说明：

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

获取服务监控概览 Copy Section

请求：

GET /api/v1/service

说明：

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

获取服务监控历史 Copy Section

请求：

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

参数：

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

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

返回示例：

{
  "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 查询。
:::

获取服务器指标历史 Copy Section

请求：

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

返回示例：

{
  "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 配置详见 管理面板配置。
:::

获取服务下的服务器 Copy Section

请求：

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

说明：

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

获取服务器下的服务监控 Copy Section

请求：

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

说明：

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

管理类接口 Copy Chapter

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

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

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

MCP 入口 Copy Chapter

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

完整的客户端配置、工具参数示例和文件传输说明，见 MCP 使用指南。

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：

需要调用 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。

使用案例 Copy Chapter

获取服务器列表 Copy Section

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 历史 Copy Section

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"])

相关文档 Copy Chapter

• 版本与兼容性：区分产品 V2、组件 Release 与 /api/v1。
• 安全与隐私：PAT 最小 scope、到期、存储与 MCP 风险。
• 架构与数据流：API、WebSocket、gRPC、任务与 IOStream 的关系。

File: docs/guide/architecture.md Copy Chapter

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

哪吒监控 V2 架构与数据流

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

逻辑拓扑 Copy Chapter

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

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

Dashboard 是什么角色？ Copy Chapter

Dashboard 承担以下职责：

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

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

Agent 是什么角色？ Copy Chapter

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

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

不需要远程操作的节点应使用 Agent 的 disable_command_execute、disable_force_update、disable_nat 等配置缩小能力范围。完整字段见 Agent 配置。

连接与反向代理 Copy Chapter

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 反向代理配置及 WebSocket 排障。

如果公开访问域名和 Agent 通信域名不同，应分别设置 dashboard_host 和 install_host。它们还参与 OAuth2 回调 Host 与 NAT 保留域名判断，详见 Dashboard 配置。

状态数据如何流动？ Copy Chapter

主机状态 Copy Section

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

服务监控 Copy Section

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

未启用 TSDB 时，服务监控历史从 SQLite 读取；启用 TSDB 后改为从 TSDB 查询。启用步骤和迁移限制见如何启用 TSDB。

远程操作 Copy Section

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

数据存在哪里？ Copy Chapter

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

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

常见架构选择 Copy Chapter

单域名部署 Copy Section

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

访问域名与通信域名分离 Copy Section

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

私有 Dashboard Copy Section

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

上线前检查 Copy Chapter

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

File: docs/guide/comparison.md Copy Chapter

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

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

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

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

一页对比 Copy Chapter

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

哪吒监控 V2 vs Uptime Kuma Copy Chapter

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

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

Uptime Kuma 的当前类型和状态页能力以其官方 README为准。

哪吒监控 V2 vs Netdata Copy Chapter

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

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

Netdata 的 Agent、Parent、Cloud 和数据边缘存储设计见其官方概览。某些集中管理或协作能力可能涉及 Netdata Cloud 与对应方案，选型时应单独核对。

哪吒监控 V2 vs Prometheus/Grafana Copy Chapter

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

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

Prometheus 的拉取模型、时序数据和适用边界见官方 Overview；Grafana 的数据源、可视化和告警定位见官方 Introduction。

哪吒监控 V2 vs Zabbix Copy Chapter

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

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

Zabbix 的轮询与接收、资产范围和分布式能力见官方介绍及功能列表。

用需求做最终选择 Copy Chapter

按顺序回答以下问题：

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

决定使用哪吒后，继续阅读产品概览、架构与数据流、安装 Dashboard和安全与隐私。

对比依据 Copy Chapter

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

• Nezha Dashboard 官方仓库
• Uptime Kuma 官方仓库与功能列表
• Netdata 官方概览
• Prometheus 官方概览
• Grafana 官方介绍
• Zabbix 官方介绍

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

File: docs/guide/dashboard.md Copy Chapter

outline: deep Copy Chapter

安装 Dashboard

准备工作 Copy Chapter

搭建哪吒监控的 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 Copy Chapter

在面板服务器中，运行以下安装脚本：

curl -L https://raw.githubusercontent.com/nezhahq/scripts/refs/heads/main/install.sh -o nezha.sh && chmod +x nezha.sh && sudo ./nezha.sh

如果你的服务器位于中国大陆，可以使用镜像：

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

如果需要再次运行安装脚本，可输入以下命令：

./nezha.sh

打开管理脚本。

登录到 Dashboard 配置界面 Copy Chapter

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

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

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

配置反向代理 Copy Chapter

Dashboard 反向代理配置

更新 Dashboard Copy Chapter

运行脚本：

./nezha.sh

选择重启面板并更新。

下一步 Copy Chapter

• 安装 Agent并确认第一台服务器上线。
• 阅读架构与数据流，核对反向代理和存储设计。
• 按安全与隐私完成生产环境加固。
• 升级前查看版本与兼容性。

File: docs/guide/dashboardq.md Copy Chapter

outline: deep Copy Chapter

Dashboard 常见问题

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

管理面板中显示的 IP 是 Agent 使用 IP-API 检测并上报的出口 IP。
如显示的 IP 与服务商提供的 IP 不一致，可能原因如下：

1. 服务商使用入口 IP：服务商提供的 IP 为高防或映射后的入口 IP，而非实际出口 IP。
2. 多线路或专线环境：多线服务器或 IPLC 专线可能导致出口 IP 与预期不一致。

验证出口 IP Copy Section

在 Agent 服务器中运行以下命令测试出口 IP：

curl https://ipapi.co/ip/
curl ip.sb
curl ip-api.com

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

1. 重启 Docker
   运行以下命令重启 Docker：

   shell Copy

   systemctl status docker
   systemctl restart docker
   systemctl status docker

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

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

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

通常由 CSS 文件丢失或无法加载导致。解决方法如下：

1. 重启并更新面板
   执行一键脚本选择 更新面板。

2. 检查 Nginx 配置
   若问题未解决，检查并修改 Nginx 的 vhost 文件：

   • 在宝塔面板中找到安装 Dashboard 时配置的站点，点击 设置 → 配置文件。
   • 删除以下内容：
     nginx Copy

     location ~ .*\.(js|css)?$
         {
             expires      12h;
             error_log /dev/null;
             access_log /dev/null;
         }

   • 保存配置，并清空浏览器、Nginx 和 CDN 的缓存。

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

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

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

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

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

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

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

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

此错误说明：

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

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

此问题多因证书不完整导致：

1. 查看日志是否出现：
   plaintext Copy

   x509:certificate signed by unknown authority

2. 若有该错误，更换完整证书即可解决。

数据修改/功能扩展需求 Copy Chapter

若需对 Dashboard 提供的数据进行修改（如批量新建 Agent），可直接操作数据库。

注意事项： Copy Section

• 数据库类型为 sqlite3，位于 /opt/nezha/dashboard/data/sqlite.db。
• 修改数据前，请备份数据库。
• 修改时，务必 停止面板容器。
  ::: danger
  请勿随意修改数据库！错误修改可能导致数据混乱或无法启动 Dashboard。
  :::

Dashboard 是否会自动更新？ Copy Chapter

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

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

此问题可能由于以下原因导致：

1. Agent 离线：检查 Agent 是否正常运行。
2. 连接不稳定：确认 Agent 与 Dashboard 的连接是否稳定，并排除网络问题。

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

错误原因 Copy Section

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

解决方法 Copy Section

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

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

   • 域名：data.example.com:8008
   • IP：123.123.123.123:8008

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

File Manager 下载/上传时卡住 Copy Chapter

问题原因 Copy Section

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

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

解决方法 Copy Section

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

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

Nginx 配置示例：

proxy_buffer_size 2m;
proxy_buffers 4 2m;
proxy_busy_buffers_size 4m;

• 将以上配置添加到 Nginx 的站点配置中，保存后重新加载配置：
  bash Copy

  sudo nginx -s reload

Caddy 配置示例：

reverse_proxy {
    transport http {
        read_buffer 2MB
        write_buffer 2MB
    }
}

• 将缓冲区大小设置为至少 2 MiB，保存配置并重启 Caddy 服务。

2. 尝试直接连接

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

使用 Nginx 反代 gRPC 无法连接 Agent Copy Chapter

当前版本的 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。升级完成后可移除这组兼容设置。

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

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 Copy Chapter

outline: deep Copy Chapter

DDNS

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

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

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

配置说明 Copy Chapter

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

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

Webhook 配置说明 Copy Chapter

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

选项说明 Copy Section

• 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 配置。

占位符说明 Copy Section

花生壳 Webhook 示例 Copy Section

点击展开/收起

• URL：http://ddns.oray.com/ph/update?hostname=#domain#&myip=#ip#
• 请求方式: GET
• 请求头:
  json Copy

  {
    "Authorization": "Basic pass"
  }

  其中 pass 是 Base64 编码后的用户名和密码（例如，user:pass 转换为 dXNlcjpwYXNzCg==）。
• 注意：花生壳仅支持 A 记录，因此只需启用 IPv4。

供应商列表 Copy Chapter

`cloudflare` Token 权限 Copy Section

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

`he` Secret 获取 Copy Section

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

查看日志 Copy Chapter

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

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 Copy Chapter

outline: deep Copy Chapter

分组管理

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

服务器分组 Copy Chapter

功能说明 Copy Section

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

配置步骤 Copy Section

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

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

应用场景 Copy Section

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

通知分组 Copy Chapter

功能说明 Copy Section

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

配置步骤 Copy Section

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

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

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

应用场景 Copy Section

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