哪吒监控 V2 自托管：8008 单端口下 gRPC 反代怎么配、Agent 为什么不上线
哪吒监控（Nezha Monitoring）是 Go 编写的自托管服务器与网站监控工具，支持系统状态、HTTP（SSL 证书变更/即将到期/已过期）、TCP、Ping 监控，以及推送告警、定时任务和 Web 终端。
- 仓库：
- 文档：
下面按官方 V2 文档的安装顺序走一遍，并把反代、Agent 上线和几个社区踩坑点一并记下来。
准备条件
- 一台能连公网的服务器，防火墙和安全策略放行 8008 端口，否则面板访问不到、Agent 数据也收不到。单核 512MB 内存可满足大多数场景。
- 一个已设置 A 记录、指向 Dashboard 服务器 IP 的域名。
如果要用 CDN，建议准备两个域名：一个接 CDN 做公开访问（CDN 需支持 WebSocket），另一个不接 CDN，专门给 Agent 与 Dashboard 通信。V2 里访问和 Agent 通信可以共用同一端口，但不同 CDN 对 gRPC 和长连接的支持差异会导致通信异常，所以分开更稳（非强制）。
示例：dashboard.example.com（面板）和 data.example.com（Agent 通信）。
Docker 安装 Dashboard
在 Dashboard 服务器上运行：
curl -L https://raw.githubusercontent.com/nezhahq/scripts/refs/heads/main/install.sh -o nezha.sh && chmod +x nezha.sh && sudo ./nezha.sh
中国大陆可用 Gitee 镜像：
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）、后台语言。安装结束后通过 http://dashboard.example.com:8008 访问，后台管理界面路径是 /dashboard，即 http://dashboard.example.com:8008/dashboard。
再次运行 ./nezha.sh 会打开管理脚本；更新 Dashboard 也是运行 ./nezha.sh，选择重启面板并更新。
登录后立刻改掉 admin/admin
首次登录默认用户名和密码均为 admin。高权限面板用弱密码风险很高，进管理页面后立刻改：点击头像 → 个人信息 → 更新个人资料。建议密码至少 18 位，混合大小写字母、数字和符号。
反向代理：gRPC 与 WebSocket 要分开处理
从 V1 起，哪吒不再区分 Dashboard 和 gRPC 端口，访问与通信都走默认的 8008。这带来一个容易踩的点：Agent 通信走 gRPC（HTTP/2），Web 终端和文件管理走 WebSocket，普通页面又是普通 HTTP 请求——反代必须支持 h2c/http2，并把 /proto.NezhaService/ 单独 route。
官方 Caddy v2 配置：
dashboard.example.com {
@grpcProto { path /proto.NezhaService/* }
reverse_proxy @grpcProto {
header_up Host {host}
header_up nz-realip {http.CF-Connecting-IP} # 替换为你的 CDN 提供的私有 header，此处为 CloudFlare 默认
# header_up nz-realip {remote_host} # 如果你使用 caddy 作为最外层，把上面一行注释掉，启用此行
transport http { versions h2c read_buffer 4096 }
to localhost:8008
}
reverse_proxy {
header_up Host {host}
header_up Origin https://{host}
header_up nz-realip {http.CF-Connecting-IP}
transport http { read_buffer 16384 }
to localhost:8008
}
}
Nginx（IPV4 机器 + 域名）需要 http2、grpc 与 websocket 分开 location：
server {
listen 443 ssl http2;
server_name vps.demo.com;
ssl_certificate /cert/fullchain.pem;
ssl_certificate_key /cert/privkey.pem;
underscores_in_headers on;
location ^~ /proto.NezhaService/ {
grpc_set_header Host $host;
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;
}
location ~* ^/api/v1/ws/(server|terminal|file)(.*)$ {
proxy_set_header Host $host;
proxy_set_header nz-realip $remote_addr;
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 nz-realip $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:8008;
}
}
upstream dashboard {
server 127.0.0.1:8008;
keepalive 512;
}
CDN 如果不支持 gRPC 长连接，Agent 通信就会异常——这也是前面建议给 Agent 单独留一个不挂 CDN 域名的原因。
安装 Agent
被控端服务叫 Agent，支持 Windows、macOS、Linux 一键安装。安装前先在管理面板设置通信域名（不建议接 CDN），示例 data.example.com：
- 后台点击头像，进入「系统设置」页。
- 在「Agent 对接地址【域名/IP:端口】」填入
data.example.com:8008，点击确认保存。 - 在「服务器」页面点击「安装命令」，选择对应操作系统，命令会自动复制到剪贴板。
- 在被控端运行安装命令，完成后回到「服务器」页面看是否上线。
- 安装成功会自动弹出新服务器，可点编辑设置名称。
不需要域名访问时，连接地址直接填 IP+端口，TLS 选 N；需要域名访问就填域名+端口，TLS 选 y。
带 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
NZ_CLIENT_SECRET 要用目标用户的连接密钥，不是 Dashboard 配置文件里的全局 agent_secret_key。当前前台没有单独的连接密钥复制入口，优先以服务器页面生成的安装命令为准。
Agent 配置文件 config.yml 的关键字段：
server：Dashboard 地址和端口，如data.example.com:8008（也支持1.1.1.1:8008、"[2606:4700:4700::1111]:8008"）client_secret：Dashboard 中对应用户的连接密钥uuid：该 Agent 的唯一标识符，不要与同一 Dashboard 中其他 Agent 重复，可用uuidgen生成
Agent 不上线的排查顺序
对照上面的配置，逐条确认：8008 端口在防火墙/安全策略里是否放行；Agent 通信域名是否误挂了 CDN；填的地址与 TLS 选项是否匹配（域名访问却选了 N，或 IP 访问却选了 y）；反代是否把 /proto.NezhaService/ 单独走 h2c/http2；client_secret 是否误用了全局 agent_secret_key。
群晖等特殊设备手动安装 Agent
群晖（Synology NAS）基于特定版本 Linux，shell 环境与软件包管理都不同，需要手动安装：
- 创建配置文件。
- 创建 systemd 服务文件
/etc/systemd/system/nezha-agent.service：
[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
- 启动 Agent，登录 Dashboard 检查是否上线。
用 NZ_UUID 重装，继承原有记录
想让新 Agent 继承原有服务器记录和配置，在安装命令里加 NZ_UUID=服务器的UUID。步骤：复制目标服务器的 UUID → 生成安装命令并添加 NZ_UUID 参数 → 卸载旧 Agent（避免重复注册或冲突）。
Oauth2 登录
哪吒只支持 Oauth2 方式接入第三方登录，常见用 GitHub，也支持 GitLab、Gitee、Gitea。以 GitHub 为例：打开 GitHub Oauth App，Homepage URL 填面板访问域名（http://dashboard.example.com），Authorization callback URL 填 http://dashboard.example.com/oauth2/callback（不要漏掉 /oauth2/callback）。保存 Client ID 并生成 Client Secret（只显示一次）。配置里的 Oauth2.Admin 填管理员用户名。
如果用未接 CDN 的域名，用 IP+端口访问时 Agent 连接端口仍用 8008。
社区踩坑
有用户反馈：一键脚本装完服务端 Docker 后系统 CPU 长期 100%，怀疑是后台定时发送或脚本被重复执行导致进程占用，最后重装了系统。结论是别盲目重复跑安装脚本；装完确认只有一份面板/Agent 进程在跑；资源敏感的小机器先确认版本和进程状态，再考虑加机器。
附：不用一键脚本的 docker compose
services:
dashboard:
image: ghcr.io/nezhahq/nezha:latest
container_name: nezha-dashboard
restart: always
volumes:
- 【你的存储路径】:/dashboard/data
ports:
- 8008:8008