Nezha 运维手册

哪吒监控日常巡检、agent 增删迁移、CPU/内存/流量告警规则实战与触发任务实测、日志排障对照表、升级与备份操作，基于 v2.3.18/v2.3.5 实测

NezhaNezha2026/10/18

Nezha 运维手册

目标：给出 Nezha 日常运维闭环——巡检、agent 增删迁移、告警规则实战、日志排障与升级备份。本文承接《Nezha 安装部署指南》的实测环境：dashboard v2.3.18（systemd 二进制方式，端口 13903；另有一套 compose 实例 13930）+ agent v2.3.5。所有排障日志、告警触发记录、备份输出均为真实执行照录。

一、日常巡检

1.1 服务健康检查

dashboard（二进制/systemd 方式）：

systemctl is-active nezha-dashboard        # 应输出 active
systemctl status nezha-dashboard --no-pager | head -8

实测正常状态：

● nezha-dashboard.service - Nezha dashboard Service
     Loaded: loaded (/etc/systemd/system/nezha-dashboard.service; enabled; preset: enabled)
     Active: active (running) since Sat 2026-10-18 04:40:02 UTC; 7h ago
   Main PID: 3120 (dashboard-linux-amd64)
      Tasks: 7 (limit: 5753)
     Memory: 21.3M

dashboard（Docker Compose 方式，见《Nezha 安装部署指南》方案 A）：

docker compose -f /opt/data/nezha/compose/docker-compose.yml ps   # STATUS 应为 Up
docker logs --tail 20 nezha-dashboard-compose                     # 无持续报错即可

agent（每台被监控机器）：

systemctl is-active nezha-agent    # 应输出 active
/opt/nezha/agent/nezha-agent -v    # 版本确认

1.2 数据面巡检（面板/API）

  • 面板首页：所有机器在线、CPU/内存/磁盘曲线正常跳动、无离线灰机；
  • API 巡检（适合纳入外部拨测，如配合《Uptime Kuma 介绍与选型指南》中的 Uptime Kuma 监控面板本身）：
TOKEN=$(curl -s -X POST http://localhost:13903/api/v1/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<你的密码>"}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['token'])")
curl -s 'http://localhost:13903/api/v1/server?page=1&page_size=10' -H "Authorization: Bearer $TOKEN"

实测返回中重点看：last_active（持续刷新 = 心跳正常）、state.cpu/mem_used/disk_used（指标非零且合理）。

二、Agent 增删与迁移

2.1 新增 agent（第二台机器实测）

在新的被监控机器上重复官方脚本流程（前置：能出站连通 dashboard 端口）：

$ export NZ_SERVER=172.30.0.2:8008 NZ_TLS=false NZ_CLIENT_SECRET=nX3qmk2cXMKuCY0SCO2N3g8bLdun25gF
$ /agent.sh
Installing...
2026/10/18 04:20:34 Successfully executed action install!
nezha-agent successfully installed
$ systemctl is-active nezha-agent
active

dashboard 无需任何预注册操作，agent 连上即自动出现在「服务器」列表（实测自动分配随机名称，可在后台改名）：

id: 1 | uuid: 6186c917...
id: 2 | uuid: ae8465fd...    ← 新机器自动注册

2.2 删除 agent

两步，缺一不可：

① dashboard 侧移除记录（后台服务器页删除，API 实测如下）：

$ curl -s -b cookie.txt -H "Authorization: Bearer $TOKEN" -H "X-CSRF-Token: $CSRF" \
    -H 'Content-Type: application/json' \
    -X POST 'http://localhost:13903/api/v1/batch-delete/server' -d '[2]'
{"success":true}

注意：删除接口是 POST /api/v1/batch-delete/server，请求体为 ID 数组（实测 [2]）；DELETE /api/v1/server/2 返回 404。

② 机器侧卸载服务（实测流程）：

systemctl disable --now nezha-agent
rm -f /etc/systemd/system/nezha-agent.service && systemctl daemon-reload
rm -rf /opt/nezha

2.3 迁移 / 重装保持同一身份

agent 的身份由 /opt/nezha/agent/config.yml 中的 uuid 决定（见《Nezha v2.3.18 配置参数详解》§4）。重装系统或换机迁移时，先备份这份 config.yml，装好新 agent 后覆盖回去再重启服务，dashboard 中仍是同一台机器，历史标记与告警覆盖关系不变：

# 迁移前（旧机）
scp /opt/nezha/agent/config.yml backup-host:/staging/
# 新机装好后
cp /staging/config.yml /opt/nezha/agent/config.yml
systemctl restart nezha-agent

三、告警规则实战（CPU / 内存 / 流量阈值实测）

告警三要素（配置字段详解见《Nezha v2.3.18 配置参数详解》§6）：告警规则（阈值判定）→ 通知组（发给谁）→ 触发任务（自动处置，可选）。本章为全部真实触发记录。

3.1 实测环境搭建

  1. 通知组：后台新建通知组（实测 id=1）。注意：组内不挂通知方式时告警只留日志（见 §4.3）；
  2. 触发任务：后台新建触发任务（task_type=1），命令设计为留痕，便于验证触发链路：
date "+%F %T 告警触发" >> /tmp/nezha-alert.log
  1. 三条告警规则（均挂通知组 1 与触发任务 1）：
规则rules 条件实测目的
CPU 使用率超过 50%{"type":"cpu","duration":3,"min":0,"max":50}真实压测触发
内存使用率超过 75%{"type":"memory","duration":3,"min":0,"max":75}阈值验证法触发
累计出站流量超过 400KB{"type":"transfer_out","duration":3,"min":0,"max":400000}长期越界型触发

3.2 CPU 告警：真实压测触发（实测）

在 agent 机器注入压力（12 核机器起 10 个死循环）：

for i in $(seq 1 10); do (while :; do :; done) & done

dashboard 侧实时观察到 agent 上报的 CPU 值（实测采样）：

cpu: 94.4   load1: 5.59
cpu: 95.8   load1: 5.94
cpu: 94.4   load1: 7.5
cpu: 93.2   load1: 7.86
cpu: 94.8   load1: 8.19

约半分钟后，触发任务在 agent 机器上开始留痕（/tmp/nezha-alert.log 实测，多条规则同时越界时同秒多条）：

2026-10-18 03:59:19 告警触发
2026-10-18 03:59:19 告警触发
2026-10-18 03:59:22 告警触发
2026-10-18 03:59:22 告警触发
2026-10-18 03:59:22 告警触发

压力移除后 CPU 回落，规则恢复（trigger_mode: 0 时任务在失败期间每个采样周期都会执行，实测约每 3 秒一条）。

3.3 内存告警：阈值验证法（实测）

真实压内存会波及宿主机，验证规则链路更稳妥的方法是临时下调阈值：将内存规则 max 临时改为 20（实测机器内存占用约 30%，立即越界）。实测改值后告警触发任务随即与流量规则成对出现（同秒两条 = 两条规则同时失败）：

2026-10-18 04:13:52 告警触发
2026-10-18 04:13:55 告警触发
2026-10-18 04:13:55 告警触发

验证完毕将阈值改回 75，触发停止。生产环境则直接按真实水位配置（如 85% 告警、95% 严重）。

3.4 流量告警：长期越界型（实测）

transfer_out 是开机以来累计出站流量（字节），一旦超过阈值便持续为真——实测从规则生效起每 3 秒触发一次任务，日志稳定增长（实测累计 260+ 条）。这条规则天然适合"月度流量限额"场景：用 transfer_out_cycle 类型并配置 cycle_interval（按月重置），超额即告警。

3.5 实测得出的告警行为细节

  • 判定方向：min/max 是越界判定（值 < min 或 > max 为失败），不是区间内告警；
  • 采样周期：dashboard 内部每 3 秒评估一次，duration: 3 约等于"持续 9 秒以上越界才告警"（窗口 70% 失败即触发）；
  • 通知节流：持续触发期间通知按 30 秒间隔重试投递（实测 dashboard 日志每 30 秒一条投递记录），任务则每采样周期执行；
  • 恢复通知：规则恢复时会发恢复通知并执行 recover_trigger_tasks；
  • 版本兼容注意：实测 agent v2.3.5 配 dashboard v2.3.18 时，指标采样呈间歇性（有约数分钟的采样静默窗口，期间越界不触发）；agent 自更新对齐版本后消失。生产环境建议双端版本保持一致。

四、日志排障

4.1 日志位置

组件Docker 方式systemd 方式
dashboarddocker logs nezha-dashboard-composejournalctl -u nezha-dashboard
agent-journalctl -u nezha-agent

排障时打开调试日志：dashboard 配置 debug: true 重启；agent 配置 debug: true 后 systemctl restart nezha-agent（实测输出见《Nezha v2.3.18 配置参数详解》§5.3）。

4.2 实测错误对照表

以下四条均为本次实测中真实出现过的日志/报错：

现象（实测原文）原因处置
agent 日志：更新失败: GET https://api.github.com/repos/nezhahq/agent/releases: 403 API rate limit exceeded ... [rate reset in 2m17s]agent 自动更新检查触发 GitHub API 匿名限流不影响上报，等待限流重置；频繁出现可在 agent 配置 disable_auto_update: true 或 use_gitee_to_upgrade: true
dashboard 日志：Notification group 1 has no recipients告警规则的通知组里没有挂任何通知方式后台编辑通知组，添加通知方式
保存通知时报错：http://127.0.0.1:9999/hook is not allowedv2.3.x Webhook SSRF 防护：禁止私网/回环地址换公网可达端点或改用内置通知渠道类型
dashboard 日志：TSDB is disabled (tsdb.data_path not configured)未配置内置时序库配置 tsdb.data_path 后重启，即有历史曲线存储

4.3 agent 连不上 dashboard 的排查顺序

# 1. 机器侧确认出站可达（实测命令）
timeout 3 bash -c "echo > /dev/tcp/172.30.0.2/8008" && echo reachable
# 2. 核对 config.yml 三要素
grep -E 'server|tls|client_secret' /opt/nezha/agent/config.yml
#    server 指向对端正确？tls 与 dashboard 配置一致？client_secret 与 dashboard
#    config.yaml 的 agent_secret_key 一致？
# 3. debug 日志看握手
sed -i 's/^debug: false/debug: true/' /opt/nezha/agent/config.yml && systemctl restart nezha-agent
journalctl -u nezha-agent -n 20    # 实测成功标志：Connection to ... established

五、升级与备份

5.1 Dashboard 升级

Docker Compose 方式（数据在宿主 ./data，升级不丢数据，实测过重建流程）：

cd /opt/data/nezha/compose
docker compose pull && docker compose up -d

生产建议：compose 中把 latest 换成具体版本标签（如 ghcr.io/nezhahq/nezha:v2.3.18），升级前先看官方 Release Note，v2 大版本内直接替换即可。

二进制方式（机制已在独立安装实测中验证：下载→替换→重启）：

cd /tmp
curl -sL -o dashboard.zip https://github.com/nezhahq/nezha/releases/download/v2.3.18/dashboard-linux-amd64.zip
unzip -qo dashboard.zip && systemctl stop nezha-dashboard
mv dashboard-linux-amd64 /opt/nezha/dashboard/app && chmod +x /opt/nezha/dashboard/app
systemctl start nezha-dashboard && journalctl -u nezha-dashboard -n 5

5.2 Agent 升级

agent 默认自动更新（实测日志：检查更新: 2.3.5，配置 disable_auto_update: false 时生效）。手动升级即重跑官方安装脚本（保持 NZ_* 环境变量不变，脚本会原地覆盖二进制并重启服务）：

export NZ_SERVER=172.30.0.2:8008 NZ_TLS=false NZ_CLIENT_SECRET=<密钥>
curl -L https://raw.githubusercontent.com/nezhahq/scripts/main/agent/install.sh -o agent.sh && chmod +x agent.sh && ./agent.sh

提醒：agent 与 dashboard 分属两个仓库发版（agent 在 nezhahq/agent），版本号不同步是正常的；升级 dashboard 后建议确认 agent 已更新到最新，避免采样兼容性问题（见 §3.5）。

5.3 备份（实测可用）

需要备份的只有 dashboard 数据目录（compose 部署即 ./data；二进制部署为 /opt/nezha/dashboard/data），内含 config.yaml（密钥）+ sqlite.db（全部业务数据）。

在线热备 SQLite（实测输出）——用 Python 内置 sqlite3 的 backup API，无需停服务：

$ python3 -c "
import sqlite3
src = sqlite3.connect('/opt/data/nezha/dashboard/data/sqlite.db')
dst = sqlite3.connect('/opt/data/nezha/dashboard/data/sqlite-backup.db')
src.backup(dst); dst.close(); src.close()
print('backup ok')"
backup ok
$ ls -la /opt/data/nezha/dashboard/data/ | grep sqlite
-rw-r--r-- 1 root root 335872 Oct 18 04:20 sqlite.db
-rw-r--r-- 1 root root 335872 Oct 18 04:20 sqlite-backup.db

整目录冷备（停服务后打包，最稳妥）：

systemctl stop nezha-dashboard
tar -czf /opt/data/backup/nezha-data-$(date +%F).tar.gz -C /opt/nezha/dashboard data
systemctl start nezha-dashboard

恢复：停服务 → 还原 data 目录（或覆盖 sqlite.db 与 config.yaml）→ 启动。agent 无状态（config.yml 记住 uuid 即可，见 §2.3），无需备份。

六、巡检清单速查

频率项目命令/位置
每天面板可达 + 机器在线面板首页 / docker compose ps / systemctl is-active
每天告警日志无异常journalctl -u nezha-dashboard --since today | grep NEZHA
每周双端版本核对面板后台版本号 + /opt/nezha/agent/nezha-agent -v
每周磁盘水位（TSDB/日志增长）du -sh /opt/data/nezha/*/data
每月数据备份演练§5.3 热备 + 一次恢复测试
每月agent 密钥轮换评估更换 agent_secret_key 并批量更新各机 config.yml

七、参考链接

  1. GitHub 仓库与 Releases（升级包下载核实）：https://github.com/nezhahq/nezha/releases
  2. Agent 仓库（自动更新与版本核对）：https://github.com/nezhahq/agent
  3. 相关阅读：《Nezha 介绍与选型指南》《Nezha 安装部署指南》《Nezha v2.3.18 配置参数详解》