2026-10-18发表2026-10-20更新VPS1 小时读完 (大约11500个字)

Nezha 哪吒监控 v2 安装与配置教程：从零部署到服务器接入

一、前言

如果你同时管理着几台、十几台甚至更多 VPS，最头疼的往往不是“机器挂了”，而是“挂了却不知道”。打开一堆终端、一个个 htop 或 uptime，效率低下；等到发现某个站点打不开，可能已经过去好几个小时。有没有一个轻量、集中的方式，把所有服务器的状态、流量、可用性都放在一个页面里看？这就是哪吒监控（Nezha）要解决的问题。

1.1 Nezha 是什么

Nezha（哪吒监控）是一个轻量的服务器与服务监控工具。它由两部分组成：面板（Dashboard）负责展示数据、管理节点和发送告警；Agent 安装在被监控的机器上，负责采集系统信息并上报。整体设计简洁，部署门槛不高，适合个人站长和运维新手使用。

1.2 v2 版本的主要特点

v2 是一次较大的重构版本，与 v1 在架构和通信方式上都有明显变化。主要特点包括：

整体架构重构，面板与 Agent 的职责划分更清晰。
面板与 Agent 之间改用 gRPC 通信，后续配置反向代理时需要注意对 gRPC 的支持（具体写法后文会讲）。
界面和交互有所改进，日常查看状态更顺手。
功能上对告警、服务探测等能力做了调整与增强。
安装与配置流程相对 v1 有所简化，但与 v1 不兼容。

需要特别提醒：v2 与 v1 不能原地升级。已有 v1 环境的读者，请先阅读本教程中关于迁移的章节，再决定如何处理旧数据与旧节点。

1.3 适用场景

多台 VPS 需要统一查看 CPU、内存、磁盘、流量等基础状态。
希望对 HTTP/HTTPS 服务做简单可用性探测。
需要在服务器离线或关键指标异常时及时收到通知。
个人或小团队希望用一套轻量工具完成基础运维监控，而不想引入过重的监控体系。

1.4 本文将完成什么

本教程将按以下顺序带你完成一次完整部署：

部署 Nezha v2 面板
配置反向代理与 HTTPS
在被监控机器上安装 Agent
配置通知与告警

1.5 阅读提示

本文测试环境为：Debian 12 / Nezha v2.x.x / 测试时间 2026-10（具体版本号与官方文档为准）。文中出现的 your.domain.com、your-email@example.com 等均为占位符，请替换为你自己的域名和邮箱。命令与配置以实际环境为准，遇到差异时请优先参考官方文档。

接下来我们先从准备工作开始。

二、准备工作

正式动手前，先把环境和前置条件理顺。准备得越扎实，后面安装、反代、上线 Agent 就越少踩坑。本章只做准备工作，不涉及具体安装命令。

2.1 环境要求

面板服务器

面板（Dashboard）需要一台能从公网访问的服务器。推荐使用较新的稳定发行版，例如 Debian 12 或 Ubuntu 22.04 LTS。内存与磁盘没有特别严苛的硬性门槛，普通轻量 VPS 即可满足个人或少量节点的使用，具体建议以官方文档（nezha.wiki）为准。

必须具备公网 IP，否则外部无法访问面板，Agent 也无法正常上报。若服务器在内网或仅有私有 IP，需要额外做端口映射或隧道，本教程默认你使用带公网 IP 的 VPS。

被监控机器（Agent 端）

Agent 支持在多种系统和架构上运行。官方文档覆盖的主要平台如下（以实际发布和支持情况为准）：

系统	常见架构	说明
Linux	x86_64、ARM 等	最常用，一键脚本支持较好
Windows	x86_64	支持一键安装
macOS	官方文档已覆盖	适合少量桌面/测试机

更多特殊环境（如 OpenWrt、群晖等）可参考官方文档的对应章节。架构与系统支持列表以 nezha.wiki 最新说明为准。

典型拓扑

面板和 Agent 不必在同一台机器上。常见做法是：

一台专门的 VPS 跑面板（带域名、反向代理和 HTTPS）
其他需要监控的 VPS / 机器只安装 Agent，向面板上报数据

也可以把面板和一台 Agent 装在同一台机器上，适合节点很少的情况。

2.2 域名准备与 DNS 解析

虽然可以直接用 IP + 端口访问面板，但强烈建议使用域名，原因很简单：

方便配置 HTTPS（证书通常按域名签发）
反向代理时更清晰
以后更换服务器 IP 时，只需改 DNS，已安装的 Agent 不用批量改配置

在域名服务商处添加一条 A 记录（IPv4）或 AAAA 记录（IPv6），指向你的面板服务器公网 IP。示例：

主机记录：dashboard（或你喜欢的子域名）
记录类型：A
记录值：your_server_ip

最终完整域名形如 dashboard.your.domain.com。

添加后等待生效，可用以下命令验证：

1
2
3

ping dashboard.your.domain.com
# 或
dig +short dashboard.your.domain.com

预期结果是解析到你填写的服务器 IP。若长时间不生效，检查是否有本地 DNS 缓存，或换一个公共 DNS（如 1.1.1.1）再试。

提示：解析刚改完时，不同地区生效时间可能不一致，耐心等几分钟到十几分钟再继续。

2.3 端口规划与防火墙

哪吒 v2 面板默认将 Web 访问与 Agent 通信放在同一端口上（官方文档中的默认值为 8008，具体以你安装时选择或官方最新说明为准）。反向代理后通常只对外暴露 80/443。

建议关注的端口如下：

端口用途	说明	备注
面板监听端口	Dashboard 实际监听的端口	默认常见为 8008，可自定义
Agent 通信	与面板通信使用同一端口（gRPC）	同上
80 / 443	反向代理对外提供 HTTP/HTTPS	建议最终只开放这两个
SSH 端口	服务器远程管理	按你实际配置放行

放行示例（按你实际使用的防火墙工具选择）：

ufw（Debian/Ubuntu 常见）：

sudo ufw allow 22/tcp          # SSH，按实际端口修改
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8008/tcp        # 若暂时直连面板端口，按实际端口修改
sudo ufw enable
sudo ufw reload
sudo ufw status

firewalld（部分 CentOS/RHEL 系）：

sudo firewall-cmd --permanent --add-port=22/tcp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=8008/tcp   # 按实际端口修改
sudo firewall-cmd --reload

注意：云服务商控制台的安全组 / 防火墙规则也必须同步放行对应端口，否则系统防火墙开了，外面仍然进不来。这是最常见的踩坑点之一。

2.4 是否使用 Cloudflare / CDN

v2 面板与 Agent 通过 gRPC 通信。CDN（尤其是 Cloudflare 的代理模式）对 gRPC 和长连接的支持并不总是开箱即用，容易导致 Agent 上线异常或数据上报不稳定。

给新手的建议：

第一次部署时，先把域名设为 仅 DNS 解析（灰云），不开启代理。
确认面板能正常访问、Agent 能稳定上线后，再考虑是否启用 CDN 以及如何正确配置 gRPC 相关规则。
详细的反向代理与 CDN 配置会在第四章展开。

如果暂时只用 IP 访问也可以，但后续申请证书和更换服务器会麻烦一些，仍建议尽早准备域名。

2.5 准备清单（Checklist）

进入下一章前，请确认以下事项都已完成：

面板服务器已准备好，有公网 IP，系统为较新的 Debian / Ubuntu 等
域名已添加 A/AAAA 记录，指向面板服务器 IP
用 ping 或 dig 验证解析正确
系统防火墙已放行必要端口
云服务商安全组已同步放行对应端口
（可选）决定是否暂时关闭 CDN 代理，仅使用 DNS 解析

三、安装面板

准备工作完成后，就可以开始安装哪吒监控的面板（Dashboard）了。本章只覆盖面板本身的安装与验证，反向代理、HTTPS 和 Agent 安装会放到后面章节。

3.1 安装方式选择

目前常见有两种安装方式，可根据自己的使用习惯选择：

方式	适用人群	优点	缺点
官方一键脚本	新手、想快速上手的读者	交互简单，自动处理依赖与服务管理，支持后续更新/重启	对底层细节控制较少
Docker / Docker Compose	已熟悉 Docker 的读者	环境隔离清晰，便于迁移和统一管理	需要自己维护 Compose 文件与数据卷

建议：第一次接触哪吒的读者优先用官方一键脚本, ；已经习惯用 Docker 管理服务的，可以选择 Docker 方式。

3.2 方式一：官方一键脚本安装

安装前检查

确认当前用户有 root 权限（或可使用 sudo），并确保 curl 或 wget 可用以及 unzip 可用：

whoami
# 预期输出 root，或后续命令前加 sudo

curl --version
# 或
wget --version

unzip --version

执行安装

官方安装命令请以 nezha.wiki - 安装 Dashboard 当前文档为准。通用形式如下：

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

若服务器位于中国大陆，官方通常会提供镜像地址，可按文档说明加上对应环境变量后执行（具体命令以官方页面为准）。

nezha 面板安装

脚本运行后会进入交互菜单，常见选项含义与建议如下（实际提示可能随版本略有调整，以屏幕显示为准）：

选项	含义	建议值
安装方式（Docker / 独立安装）	选择容器或二进制方式	新手选独立安装更省事
站点标题	面板显示的名称	随意填写，如 My Nezha
暴露端口	面板对外监听的端口	与第二章规划一致，官方默认常见为 8008
是否希望通过 TLS 连接 Agent	Agent 安装命令里是否启用 TLS（加密通信）	安装面板时建议直接选 N
后台语言	界面语言	按个人习惯选择

输入完成后，脚本会拉取镜像或下载二进制并启动服务。安装成功后，终端一般会提示可通过 http://你的IP:端口访问。

是否希望通过 TLS 连接 Agent，这个选项决定生成的 Agent 安装命令里是否启用 TLS（加密通信）
选 Y：Agent 会通过 TLS 连接面板（对应配置里的 tls: true）。适用于面板前面已经有 HTTPS 反向代理、或使用 CDN 终结 TLS 的情况。
选 N：明文连接（tls: false）。适用于直接用 IP:端口或还没上 HTTPS 的情况
安装面板时建议直接选 N, 因为现在还只是临时用 IP + 端口访问，还没配域名和 HTTPS。选错了会导致后面 Agent 连不上。以后随时可以在面板「系统设置」里改。
注意：
安装过程需要 root 权限。端口请与第二章防火墙、安全组规划保持一致，避免装完却访问不了。
端口默认常见为 8008

nezha 初始安装后的主页面

3.3 方式二：Docker / Docker Compose 部署

前置条件

先确认 Docker 与 Compose 已安装，安装过程可参考安装并配置docker-compose：

安装完成后检查docker 和 docker compose:

1 2	docker --version docker compose version

能正常输出版本号即可。

示例 Compose 框架

官方一键脚本内部也会生成 Compose 文件。若你希望手动管理，可参考以下框架（镜像名、版本标签、端口与路径均请以官方文档为准，以下为示意）：

# docker-compose.yml 示例框架【待核实具体镜像与路径】
services:
  dashboard:
    # image: ghcr.io/nezhahq/nezha            # 使用最新版本
    image: ghcr.io/nezhahq/nezha:<版本标签>   # 使用指定版本
    container_name: nezha-dashboard
    restart: always
    ports:
      - "8008:8008"                 # 主机端口:容器端口，按实际修改
    volumes:
      - ./data:/dashboard/data      # 数据目录，务必持久化
    # 其他配置项以官方示例为准

数据目录（如 ./data 或官方默认的 /opt/nezha/dashboard/data）非常重要，后续备份、升级都依赖它，请务必挂载到宿主机持久化位置。
如果不了解如何配置 nezha docker compose 文件，可以使用官方脚本以docker compose安装一次然后查看官方配置文件


$ docker compose ls
NAME                STATUS              CONFIG FILES
dashboard           running(1)          /opt/nezha/dashboard/docker-compose.yaml

$ cat  /opt/nezha/dashboard/docker-compose.yaml
services:
  dashboard:
    image: ghcr.io/nezhahq/nezha
    container_name: nezha-dashboard
    restart: always
    volumes:
      - ./data:/dashboard/data
    ports:
      - 8008:8008

常用操作

# 启动
docker compose up -d

# 停止
docker compose down

# 查看日志
docker compose logs -f
# 或
docker logs -f nezha-dashboard

提示：手动维护 Compose 时，建议把文件和数据目录放在固定路径（如 /opt/nezha/dashboard），方便以后升级和备份。

3.4 检查服务是否正常运行

查看服务状态

一键脚本（独立安装方式）：

1 2	systemctl status nezha-dashboard # 或官方脚本生成的具体服务名，以实际为准

预期：状态为 active (running)。

Docker 方式：

1	docker ps \| grep nezha

预期：容器处于 Up 状态。

查看日志

# systemd
journalctl -u nezha-dashboard -f --no-pager

# Docker
docker logs -f nezha-dashboard

日志中不应出现持续报错或反复重启的信息。

检查端口监听

1
2
3

ss -tlnp | grep 8008
# 或
netstat -tlnp | grep 8008

预期：对应端口处于 LISTEN 状态。

检查项	预期结果	异常表现
服务状态	running / Up	inactive、Exited、反复重启
端口监听	指定端口处于 LISTEN	无输出，端口未监听
日志	无明显报错	端口占用、权限错误、镜像拉取失败等

3.5 首次访问面板

在尚未配置反向代理前，可通过 IP 临时访问：

1	http://your_server_ip:面板端口

后台管理路径一般为 /dashboard，完整地址示例：

1	http://your_server_ip:8008/dashboard

首次登录的默认账号密码，官方文档目前写明默认用户名和密码均为 admin。

登录成功后，请立刻修改默认密码：

点击右上角头像
进入个人信息 / 更新个人资料
设置一个足够强的新密码（建议长度 ≥ 18，包含大小写、数字和符号）

注意：面板权限较高，默认弱密码非常危险。在公网环境下，务必第一时间改密，且不要把面板端口长期直接暴露在公网，后续应通过反向代理 + HTTPS 访问。

3.6 常见问题速查

端口被占用：安装时报端口已使用。用 ss -tlnp 查看占用进程，换一个端口或释放原端口。详细处理见第十章。
镜像拉取失败：网络问题或镜像源不可达。检查网络、尝试官方提供的国内镜像，或手动拉取后再启动。
服务启动后无法访问：防火墙/安全组未放行，或服务实际未监听。对照第二章检查端口与安全组，并查看日志。
页面能打开但登录异常：确认访问的是正确路径（通常含 /dashboard），并核对是否使用了最新默认凭据。

四、配置反向代理与 HTTPS

面板已经能通过 IP 临时访问，但生产环境更推荐用域名 + HTTPS。本章重点是把反向代理配好，让浏览器访问和 Agent 的 gRPC 通信都能正确转发。这一步最容易踩坑，请按顺序仔细操作。

4.1 为什么需要反向代理

反向代理主要解决三件事：

域名访问：用 https://your.domain.com 代替 http://IP:端口，更规范也更安全。
HTTPS 加密：浏览器与面板之间的流量加密，避免明文传输。
gRPC 转发：v2 的面板与 Agent 通过 gRPC 通信，反向代理必须正确转发这类流量，否则 Agent 无法上线。

简单拓扑如下：

浏览器 / Agent
      │
      ▼
反向代理（监听 80/443）
      │
      ▼
本机面板（默认常见端口 8008）

Agent 最终连接的地址（域名或 IP + 端口）需要与你在面板里设置的「Agent 对接地址」保持一致。

4.2 方案选择

方案	配置难度	证书管理	适用人群
Nginx	中等，需手动写配置	用 certbot / acme.sh 申请并续期	已有 Nginx 环境，或需要精细控制
Caddy	较低	自动申请与续期	想省事、快速上线的读者

建议：想少折腾就选 Caddy；服务器上已经跑着 Nginx，或习惯用它的，继续用 Nginx 即可。

4.3 方案一：Nginx 反向代理

安装 Nginx 与申请证书

以常见方式为例（具体命令以你系统包管理器为准）：

# Debian / Ubuntu 示例
sudo apt update
sudo apt install -y nginx

# 使用 certbot 申请证书（需域名已解析且 80 端口可访问）
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your.domain.com

证书路径通常类似 /etc/letsencrypt/live/your.domain.com/fullchain.pem 和 privkey.pem。也可用 acme.sh，按官方文档操作即可。

注意：申请证书前请确认域名已正确解析到服务器，且防火墙/安全组已放行 80 端口。

完整配置示例

创建或编辑站点配置（路径因发行版而异，常见为 /etc/nginx/conf.d/nezha.conf）。以下示例基于官方文档结构，请把域名、证书路径、上游端口替换为你的实际值：

如果是 Debian或者 Ubuntu 在使用Certbot生成证书时，其会在/etc/nginx/sites-available/default 下生成一段默认配置，这个会影响我们真正需要为your.domain.com的设置，建议将这段配置删除。

# 80 跳转 HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name your.domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    # Nginx > 1.25.1 时可改用：http2 on;

    server_name your.domain.com;

    ssl_certificate     /path/to/fullchain.pem;   # 替换为实际证书路径
    ssl_certificate_key /path/to/privkey.pem;     # 替换为实际私钥路径
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_session_timeout 1d;
    ssl_session_cache   shared:SSL:10m;
    ssl_stapling on;

    # 如使用 Cloudflare 等 CDN，可按官方文档开启 real_ip 相关配置
    # underscores_in_headers on;

    # gRPC 转发（关键！）
    location ^~ /proto.NezhaService/ {
        grpc_set_header Host $host;
        # 若 Nginx 是最外层，可用下面这行获取真实 IP
        # grpc_set_header nz-realip $remote_addr;
        grpc_read_timeout 600s;
        grpc_send_timeout 600s;
        grpc_socket_keepalive on;
        client_max_body_size 10m;
        grpc_buffer_size 4m;
        grpc_pass grpc://dashboard;
    }

    # WebSocket（终端、文件、实时数据等）
    location ~* ^/api/v1/ws/(server|terminal|file)(.*)$ {
        proxy_set_header Host $host;
        proxy_set_header Origin https://$host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_pass http://127.0.0.1:8008;
    }

    # 普通网页
    location / {
        proxy_set_header Host $host;
        # proxy_set_header X-Forwarded-Proto $scheme;  # 最外层时可开启
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
        proxy_max_temp_file_size 0;
        proxy_pass http://127.0.0.1:8008;
    }
}

upstream dashboard {
    server 127.0.0.1:8008;   # 与面板实际监听端口一致
    keepalive 512;
}

关键说明：

listen … http2：gRPC 依赖 HTTP/2，必须开启。
location ^~ /proto.NezhaService/：官方定义的 gRPC 路径，使用 grpc_pass 转发。
WebSocket location：保证终端、文件管理、实时状态更新正常。
upstream：把请求转到本机面板端口。

提示：修改前先备份原配置。改完务必先检查再重载。

检查与重载

1	sudo nginx -t

预期输出类似：syntax is ok / test is successful。
注意：在Debian或者 Ubuntu操作系统下Certbot生成证书时在/etc/nginx/sites-available/default生成的一段配置对整体配置的影响。

重载nginx服务

1
2
3

sudo systemctl reload nginx
# 或
sudo nginx -s reload

4.4 方案二：Caddy 反向代理

Caddy 能自动申请并续期证书，配置更简洁。

安装

请按 Caddy 官方文档安装。

# 安装所需的依赖软件包
# debian-keyring / debian-archive-keyring: Debian 官方密钥环,用于校验软件包签名
# apt-transport-https: 允许 apt 通过 HTTPS 访问软件源
# curl: 用于下载文件
sudo apt install --yes debian-keyring debian-archive-keyring apt-transport-https curl

# 导入 Caddy 软件源的 GPG 公钥
# 下载公钥后用 gpg --dearmor 转换为二进制格式,保存到系统密钥环目录
# (-1 强制使用 TLS 1.x;-s 静默模式;-L 跟随重定向;-f 请求失败时不输出错误页)
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# 将 Caddy 软件源添加到 apt 的源列表中
# tee 会把下载到的源配置内容写入 /etc/apt/sources.list.d/caddy-stable.list
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# 给密钥文件和源列表文件添加"其他用户可读"权限(o+r)
# 否则 apt 在以非 root 的内部用户身份运行时,可能因权限不足而无法读取
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list

# 刷新软件包索引,使 apt 识别新添加的 Caddy 软件源
sudo apt update

# 安装 Caddy
sudo apt install caddy

安装完成后,Caddy 会自动注册为 systemd 服务,可以用 systemctl status caddy 查看运行状态。

安装完成后确认：


# 查看版本
caddy version

# 查看运行状态
systemctl status caddy

Caddyfile 示例

编辑 Caddyfile（常见路径 /etc/caddy/Caddyfile），内容示例如下（基于官方文档结构）：

your.domain.com {
        @grpcProto {
                path /proto.NezhaService/*
        }

        reverse_proxy @grpcProto {
                header_up Host {host}
                # 最外层时可使用：
                # header_up nz-realip {remote_host}
                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 {remote_host}
                transport http {
                        read_buffer 16384
                }
                to localhost:8008  # 上游端口以实际为准
        }
}

说明：

@grpcProto 匹配官方 gRPC 路径，使用 h2c（明文 HTTP/2）转发到本机面板。
其余流量走普通反向代理。
前提：域名已正确解析，80/443 可从公网访问，Caddy 才能自动申请证书。

校验与重载

1
2
3

caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
# 或按你的安装方式使用 caddy reload

4.5 使用 Cloudflare 时的注意事项

若域名接入 Cloudflare：

Cloudflare代理模式会对 gRPC 有影响。需要在 Cloudflare 后台开启 gRPC 支持（具体开关名称与路径以 Cloudflare 当前界面为准）。
Agent 使用的端口必须在 Cloudflare 支持代理的端口范围内，否则建议改用仅 DNS。

两种常见策略：

Agent 通信使用仅 DNS模式：面板访问域名可以使用代理模式，Agent 对接地址用另一个仅 DNS 解析的域名或直接 IP，稳定性更高。
统一代理模式：开启 gRPC，并确保使用 Cloudflare 支持的端口，同时 SSL/TLS 加密模式建议选「完全（严格）」。

注意：SSL/TLS 模式选「灵活」容易导致证书或回源异常，生产环境不推荐。

4.6 回到面板修改相关设置

反代与 HTTPS 生效后，请登录面板，把对外相关地址改为域名形式：

Agent 对接地址（例如 your.domain.com:443）
其他与对外访问相关的设置项

详细操作见第五章。同时建议：

防火墙只保留 80/443（以及 SSH），把原来临时开放的面板端口对公网关闭。
确认面板实际只监听本机（或通过反代访问），不再直接暴露例如8008。

4.7 验证配置是否成功

浏览器验证：

访问 https://your.domain.com，应能看到登录页，地址栏显示锁图标，证书有效。

命令验证：

1	curl -I https://your.domain.com

预期返回 HTTP/2 200 或 HTTP/1.1 200 等成功状态。

1	echo \| openssl s_client -connect your.domain.com:443 -servername your.domain.com 2>/dev/null \| openssl x509 -noout -dates

可查看证书有效期。

gRPC 验证：

此时还无法完整验证 gRPC。需在第六章安装 Agent 后，观察服务器是否正常上线。如果 Agent 一直离线，优先回头检查反代中的 gRPC location 与 grpc_pass / h2c 配置。

4.8 常见问题速查

证书申请失败：域名未解析、80 端口不通或被占用。检查解析与防火墙后重试。
502 Bad Gateway：上游面板未运行，或端口写错。用 ss -tlnp 确认面板监听端口。
页面能开但实时数据不更新：WebSocket 未正确转发。检查对应 location 与 Upgrade 头。
Agent 连不上：gRPC 路径或 grpc_pass / h2c 配置有问题。对照官方示例排查。
使用 Cloudflare 后连接异常：未开 gRPC、端口不支持或 SSL 模式不正确。详见第十章。

五、面板基础设置

面板已经能通过 https://your.domain.com 正常访问，反向代理与 gRPC 转发也在上一章配好了。这一章我们把后台里和「能不能顺利装 Agent、前台长什么样、怎么安全登录」直接相关的基础项一次理清楚。

其中最关键的是 Agent 对接地址：它会直接决定第六章生成的安装命令里写什么地址。地址写错，Agent 就连不上。

5.1 认识后台界面

登录后进入的是管理后台（路径一般为 /dashboard）。左侧是功能菜单，右上角头像可进入个人信息、系统设置等。

哪吒监控：后台首页

常见菜单与本教程对应关系如下：

菜单	作用	本教程讲解章节
服务器	查看已上线服务器、复制 Agent 安装命令、编辑名称与分组	第六章
服务	配置 HTTP / Ping / TCP 等服务探测	第七章
任务	计划任务、触发任务（批量执行命令等）	第七章
通知	配置通知渠道与通知组	第七章
设置	系统配置、用户管理、API Token、在线用户等	本章
个人信息（头像菜单）	改密码、绑定 OAuth2、个人偏好	第四章已改过密码

先有个整体印象即可，后面按需深入。

5.2 系统设置（本章重点）

路径：右上角头像 → 系统设置。

哪吒监控：系统设置页

与部署、Agent 上线直接相关的项建议先核对一遍：

设置项	含义	建议填写方式
站点名称	前台与后台显示的站点标题	自定义，如 `My VPS Monitor`
语言设置	通知文案、部分界面语言	按使用习惯选择（如简体中文）
Agent 对接地址【域名/IP:端口】	生成 Agent 安装命令时使用的连接地址，也是 Agent 实际连接目标	与第四章反向代理方案一致，例如 `your.domain.com:443` 或你实际对外提供的 host:port
Agent 使用 TLS 连接	安装命令是否带 TLS 参数	若 Agent 经 HTTPS / 反向代理 TLS 终结连接则开启；明文直连 host:port 则不要开
面板 OAuth2 回调域名	Dashboard 对外访问并接收 OAuth2 回调的地址（格式：域名/IP[:端口]，不要写协议和路径）	使用 OAuth2 或公网域名与 Agent 地址不同时建议填写，例如 `your.domain.com`
前端真实 IP 请求头	识别访客真实 IP（在线用户、防爆破、WAF 等依赖）	直连选「使用直连 IP」；经 Cloudflare 常用 `CF-Connecting-IP`；经 Nginx/Caddy 等则按实际传递的 Header 填写（详见官方文档）

操作建议：

把 Agent 对接地址 改成你实际给 Agent 用的域名或 IP + 端口，并与第四章的反向代理、gRPC 转发保持一致。
若使用 Cloudflare 橙云（代理开启），请确认所用端口在 Cloudflare 支持范围内，并参考第四章 4.5 的说明；Agent 通信域名一般不建议强依赖 CDN，具体以你实际方案为准。
保存后，到 服务器 页再点一次「安装命令」，看生成的命令里 NZ_SERVER（或同类参数）是否已是新地址。

注意
Agent 对接地址填错：安装命令里的地址会错，Agent 无法上线或一直离线。
TLS 开关与真实连接方式不一致：Agent 可能按 TLS 去连明文端口（或反过来），同样连不上。
修改后若界面仍像旧值，可强制刷新浏览器缓存，或重新打开系统设置页确认。

时区等更多项若在界面中有单独选项，以当前版本界面为准；部分项仅存在于配置文件（如 location，默认多为 Asia/Shanghai），修改配置文件后需重启 Dashboard 才生效，详见官方配置文档。

5.3 前台主题与展示设置

前台：未登录或访客看到的公开展示页，用来看服务器状态、服务探测结果等。
后台：登录后的管理界面，用于配置、安装命令、用户与权限等。

在系统设置中可以：

修改 站点名称（影响前台标题等展示）；
选择主题（用户前端模板）；内置主题由官方维护，社区主题请确认来源可信且与当前 Dashboard 版本兼容；
使用 自定义代码（用户前端 / 管理前端分开），例如改 Logo、背景、外链等。可用的全局变量与写法以官方文档「设置」页为准。

提示
公开展示页会暴露服务器名称、在线状态等信息。若不想把所有机器都公开展示，可在后续服务器管理中控制展示范围，或结合官方「强制验证」等能力（若你版本支持）限制未登录访问，具体以 nezha.wiki 为准。

5.4 （可选）OAuth2 登录配置

OAuth2 可以用 GitHub 等第三方账号登录，减少弱密码风险。哪吒支持为已有本地账户绑定第三方账号。

配置需要改 Dashboard 配置文件（常见路径示例：/opt/nezha/dashboard/data/config.yaml，以你实际安装方式为准），改完后重启面板。

以 GitHub 为例，流程如下。

1. 在 GitHub 创建 OAuth 应用

打开 GitHub Developer Settings → OAuth Apps → New OAuth App。
填写：
- Application name：随意
- Homepage URL：面板访问地址，例如 https://your.domain.com
- Authorization callback URL：https://your.domain.com/api/v1/oauth2/callback（官方说明只检测前缀，路径以官方文档为准）
创建后保存 Client ID 与 Client secrets。

2. 在面板配置文件中填写

参考官方示例结构：

dashboard_host: "your.domain.com"
oauth2:
  GitHub:
    client_id: "your_client_id"
    client_secret: "your_client_secret"
    endpoint:
      auth_url: "https://github.com/login/oauth/authorize"
      token_url: "https://github.com/login/oauth/access_token"
    user_info_url: "https://api.github.com/user"
    user_id_path: "id"

保存后重启 Dashboard。

3. 在后台绑定并验证

登录后台 → 右上角头像 → 个人信息 → 在 OAuth2 相关区域点击对应提供方的「绑定」，完成授权后，登录页会出现 OAuth 登录入口。

注意
启用或绑定前，务必保留一种可用的登录方式（本地密码或其它已绑定方式），避免把自己锁在外面。
若开启「禁止密码登录」，需先完成至少一种 OAuth2 绑定；只剩一个绑定时不能删掉最后一个绑定。
Client Secret 不要截图、不要提交到公开仓库。

5.5 用户与权限管理

路径：系统设置 → 用户管理（需管理员权限）。

新建用户：由管理员在此添加。
权限（以官方文档为准）：
- 管理员：可访问几乎全部资源，并可修改系统设置；
- 普通用户：只能管理自己的资源，不能改系统设置，只能改自己的用户信息。
每个用户有独立的 Agent 连接密钥；安装命令里会带上当前用户对应的密钥。用户被删除后，其密钥失效，关联服务器也会被删除。

个人站长实用建议：

日常查看状态用普通权限账号；
改系统设置、装 Agent、改关键配置时再用管理员账号；
密码保持足够强度，并考虑启用 OAuth2。

修改自己的密码：头像 → 个人信息 → 更新个人资料（第四章若已改过可跳过）。

5.6 常见问题速查

Agent 安装命令里的地址不对
多半是系统设置里「Agent 对接地址」未填或未保存。到系统设置核对后重新复制安装命令。详见第十章。
修改设置后不生效
先确认已点保存；浏览器强刷；若改的是配置文件项，需重启 Dashboard。详见第十章。
OAuth2 登录回调报错
检查 GitHub（或其它提供方）的回调 URL 是否与面板公网域名一致，以及 dashboard_host / 配置是否正确，并已重启面板。详见第十章。
前台页面显示异常
先排除自定义代码或社区主题兼容问题，可临时切回默认主题对比。详见第十章。

面板侧地址与展示相关设置已经就绪，接下来就可以进入第六章，安装 Agent 并把第一台服务器接入上线。

六、安装 Agent 并添加服务器

面板侧地址与反向代理已经就绪，这一章把第一台被监控机器真正接上线。装成功后，你就能在后台和前台看到实时的 CPU、内存、磁盘和网络数据——这也是检验第四、五章配置是否正确的关键一步。

6.1 Agent 工作原理简述

Agent（探针程序）安装在你要监控的那台机器上，由它主动连接面板，并周期上报系统状态。面板根据安装命令里的连接密钥（与当前登录用户绑定）识别是谁的 Agent；连接成功后，后台会出现对应的服务器记录。

Agent 连接的目标，就是第五章在系统设置里填写的 Agent 对接地址（域名或 IP + 端口）。这个地址或端口写错、TLS 开关与实际不一致、gRPC 没正确转发，都会表现为一直离线。

6.2 在面板中获取安装命令

v2 推荐流程是：先确认 Agent 对接地址已保存，再到服务器页复制一键安装命令；Agent 连上后，列表里会出现新服务器，再编辑名称、分组等即可。

登录后台，进入 服务器 页面。
点击 安装命令（或同类入口），选择目标系统（Linux / Windows / macOS 等）。
安装命令会自动复制到剪贴板。命令中会包含对接地址、是否使用 TLS，以及当前用户的连接密钥等信息。

上线后，可在列表中点击编辑，为服务器设置名称、分组、备注（私有备注仅登录用户可见，公开备注游客也可能看到）等，具体字段以你当前版本界面为准。

【此处插入截图：添加服务器页面（密钥已打码）】

注意
安装命令里含有专属连接密钥，不要截图发到群聊、论坛或公开仓库。
每个用户有自己的连接密钥；同一用户下多台机器各自执行一次安装即可，不要把「一整条命令」当成万能密钥随意转发。
若复制安装命令时提示未指定安装主机，请回到第五章核对 Agent 对接地址 是否已填写并保存。

6.3 在 Linux 上安装 Agent

安装前建议先做这几项检查：

系统与架构是否在官方支持范围内（以 Agent 安装文档为准）。
被控机能访问面板域名，例如：

1	curl -I https://your.domain.com

能返回正常 HTTP 状态即可（示例结果因环境而异）。

系统时间大致正确（偏差过大可能导致证书校验或数据异常），可用 date 查看；需要同步时按你发行版使用 ntp / chrony / timedatectl 等工具。

安装步骤：

在被控端用 root 或具备 sudo 的用户登录。
粘贴并执行面板生成的安装命令（整段以你面板里复制的为准，不要手抄或改参数）：

1 2	# 将下面整行替换为面板「安装命令」复制出的内容 <面板生成的安装命令>

安装脚本会下载 Agent、写入配置并注册为系统服务。常见结果是出现 nezha-agent 相关服务；安装目录常见为 /opt/nezha/agent/（以你机器上实际结果为准【待核实】）。

查看服务是否在跑：

1	sudo systemctl status nezha-agent

预期：状态为 active (running)（示例，实际以你环境为准）。

查看最近日志（排查离线时很有用）：

1	sudo journalctl -u nezha-agent -n 50 --no-pager

提示
若服务起不来或一直连不上面板，按顺序排查：先看 Agent 日志 → 在本机测能否访问 your.domain.com → 回查第四章 gRPC / 反向代理 → 回查第五章 Agent 对接地址与 TLS 开关。

6.4 在 Windows 与 macOS 上安装 Agent

Windows

以 管理员身份 打开 PowerShell。
粘贴并执行面板为 Windows 生成的安装命令（整段以面板复制内容为准）：

1 2	# 将下面整行替换为面板「安装命令」复制出的内容 <面板生成的 Windows 安装命令>

若提示更改执行策略，按提示输入 Y 确认（以官方说明为准）。
安装完成后，回到面板「服务器」页查看是否上线。也可在安装目录用内置服务管理命令管理服务（路径与命令以实际安装结果与官方文档为准）。

macOS

在面板选择 macOS 对应的安装命令，在终端中执行（整段以面板复制内容为准）。若系统弹出权限或安全相关提示，按本机策略允许即可。细节以官方文档为准。

本节 Windows / macOS 流程基于官方文档整理；若你环境与文档示例不一致，以面板生成的命令和 nezha.wiki 为准。

6.5 验证服务器已上线

安装完成后稍等几秒到一两分钟，刷新面板：

后台 → 服务器：应出现新记录，状态为在线；可点编辑改成易记的名称。
打开该服务器详情或前台展示页：CPU、内存、磁盘、网络等数据应持续刷新。

预期结果	异常表现
状态显示在线	一直离线或灰色
CPU / 内存 / 磁盘 / 网速有数值且会变	全是 0 或长时间不更新
前台公开展示页也能看到该机（若未对游客隐藏）	前台没有这台机器

【此处插入截图：服务器在线状态与实时数据】

若离线，不要急着重装：先在被控端看 systemctl status 与 journalctl，再按 6.3 的排查顺序往回查网络与第四、五章配置。

6.6 Agent 的配置、升级与卸载

配置

一键安装后，Agent 会在本机生成配置文件（常见路径示例：/opt/nezha/agent/config.yml，以实际为准【待核实】）。也可在后台服务器列表中通过编辑配置下发部分选项。常见相关项包括连接地址 server、密钥 client_secret、是否 TLS、是否自动更新等，完整字段见官方 Agent 配置。

升级

默认情况下 Agent 会自动更新。若关闭了自动更新，可在后台对指定服务器执行 强制更新（若同时禁用了强制更新，则该操作无效）。也可按官方文档手动替换二进制后重启服务。

卸载（Linux 常见写法，以官方文档为准）

cd /opt/nezha/agent/   # 目录以实际安装位置为准
sudo ./nezha-agent service uninstall
# 如需清理文件，再删除对应安装目录，例如：
# sudo rm -rf /opt/nezha/agent/

Windows 可在安装目录执行类似的 nezha-agent.exe service uninstall（以实际程序名为准）。

注意
卸载本机 Agent 后，面板里的服务器记录不会自动消失，需要你在后台手动删除；否则会留下一条离线记录。

6.7 批量添加多台服务器的建议

先在一台机器上完整跑通：安装 → 在线 → 数据刷新正常，再复制同一套流程到其它机器。
每台机器各自在面板复制一次安装命令并在本机执行，不要多机共用同一条已跑过的历史命令当「模板乱贴」。
命名建议带用途或地区，例如 hk-web-01、jp-db-02，并善用分组，方便前台按组浏览。
需要「重装并继承原记录」时，可按官方说明在安装命令中附带该服务器的 UUID（见官方 Agent 文档中的 UUID 相关说明），并先卸掉旧 Agent，避免重复注册。

6.8 常见问题速查

Agent 一直离线
优先看本机日志，再测能否访问面板域名；仍不行则回查第四章 gRPC/反代与第五章 Agent 对接地址、TLS。详见第十章。
安装命令执行失败
多为网络拉不下脚本、权限不足或系统架构不匹配。检查网络与 root/管理员权限。详见第十章。
数据异常或时间相关报错
检查被控端系统时间是否同步。详见第十章。
重复安装出现多条记录
同一台机多次安装且未带原 UUID 时可能产生新记录；卸掉多余 Agent，面板侧删除多余条目。详见第十章。
走了 Cloudflare 橙云后连不上
Agent 通信对 CDN/代理较敏感，需确认端口与协议是否被支持，并对照第四章 4.5。详见第十章。

基础监控链路已经打通。下一章我们配置服务探测、通知与告警，让面板不只是「能看」，还能在出问题时主动提醒你。

Nezha 哪吒监控 v2 安装与配置教程：从零部署到服务器接入

https://pengtech.net/vps/install-Nezha-Monitoring-V2.html

作者

鹏叔

发布于

2026-10-18

更新于

2026-10-20

许可协议

#VPS Monitoring

Nezha 哪吒监控 v2 安装与配置教程：从零部署到服务器接入

一、前言

1.1 Nezha 是什么

1.2 v2 版本的主要特点

1.3 适用场景

1.4 本文将完成什么

1.5 阅读提示

二、准备工作

2.1 环境要求

面板服务器

被监控机器（Agent 端）

典型拓扑

2.2 域名准备与 DNS 解析

2.3 端口规划与防火墙

2.4 是否使用 Cloudflare / CDN

2.5 准备清单（Checklist）

三、安装面板

3.1 安装方式选择

3.2 方式一：官方一键脚本安装

安装前检查

执行安装

3.3 方式二：Docker / Docker Compose 部署

前置条件

示例 Compose 框架

常用操作

3.4 检查服务是否正常运行

查看服务状态

查看日志

检查端口监听

3.5 首次访问面板

3.6 常见问题速查

四、配置反向代理与 HTTPS

4.1 为什么需要反向代理

4.2 方案选择

4.3 方案一：Nginx 反向代理

安装 Nginx 与申请证书

完整配置示例

检查与重载

4.4 方案二：Caddy 反向代理

安装

Caddyfile 示例

校验与重载

4.5 使用 Cloudflare 时的注意事项

4.6 回到面板修改相关设置

4.7 验证配置是否成功

4.8 常见问题速查

五、面板基础设置

5.1 认识后台界面

5.2 系统设置（本章重点）

5.3 前台主题与展示设置

5.4 （可选）OAuth2 登录配置

5.5 用户与权限管理

5.6 常见问题速查

六、安装 Agent 并添加服务器

6.1 Agent 工作原理简述

6.2 在面板中获取安装命令

6.3 在 Linux 上安装 Agent

6.4 在 Windows 与 macOS 上安装 Agent

6.5 验证服务器已上线

6.6 Agent 的配置、升级与卸载

6.7 批量添加多台服务器的建议

6.8 常见问题速查

相关文章

使用 fail2ban 保护你的 VPS?

2026年各大主流域名服务商汇总

选择 VPS 需要考虑的关键因素及建议

作者

发布于

更新于

许可协议

热门文章

最新文章

follow.it

分类

热门文章