Nezha v2.3.18 配置参数详解

目标：逐字段讲清 dashboard config.yaml 与 agent config.yml 的参数含义与生效方式，字段说明基于 dashboard v2.3.18 实测配置文件与同版本源码结构定义核对，agent 部分为 v2.3.5 实测。所有"改值重启实测"均为真实执行结果，不是转抄文档。部署步骤见《Nezha 安装部署指南》。

一、配置文件清单与生效方式

Nezha 的配置分三处载体，改哪个、怎么生效是初学者最常踩的坑：

实测确认：全新启动的 dashboard 会把最小配置自动补全为完整配置（实测 1422 字节），未填写的密钥字段自动生成。

二、Dashboard config.yaml 字段详解

以下为 v2.3.18 实测文件全文（密钥字段已脱敏）：

admin_template: admin-dist
agent_secret_key: <自动生成，此处省略>
avg_ping_count: 2
cover: 1
https: {}
ip_change_notification_group_id: 0
jwt_secret_key: <自动生成，此处省略>
jwt_secret_key_last_rotated_version: 2.3.18
jwt_timeout: 1
language: zh_CN
listen_port: 8008
location: Asia/Shanghai
memory: {}
site_name: Nezha Test Site
tsdb: {}
user_template: user-dist

逐字段说明（实测 + 源码核对）：

2.1 站点基础项

2.2 密钥与认证项

2.3 Agent 接入项

2.4 IP 变更提醒项

2.5 外观与高级项

2.6 https / tsdb / memory 三个子配置（实测均为空 {}）

三、环境变量覆盖（NZ_ 前缀）

dashboard 读取配置时会先加载 NZ_ 前缀的环境变量，优先级高于 config.yaml（源码 koanf env provider，实测日志佐证）：

NEZHA>> jwt_secret_key loaded from config.yaml; recommend injecting via env NZ_JWTSECRETKEY to keep it off disk

常用形式：NZ_LISTENPORT、NZ_SITENAME、NZ_JWTSECRETKEY、NZ_AGENTSECRETKEY。Docker 编排部署时用 environment: 段注入即可把敏感密钥移出配置文件。

四、Agent config.yml 字段详解

路径 /opt/nezha/agent/config.yml（安装脚本自动生成，见《Nezha 安装部署指南》§4.5 全文），关键字段：

五、改值重启实测对比

5.1 Dashboard listen_port：8008 → 8009

$ sed -i 's/^listen_port: 8008/listen_port: 8009/' data/config.yaml
$ docker compose restart dashboard
$ docker logs nezha-dashboard-compose | tail -3
NEZHA>> jwt_secret_key loaded from config.yaml; recommend injecting via env NZ_JWTSECRETKEY to keep it off disk
NEZHA>> TSDB is disabled (tsdb.data_path not configured)
Dashboard::START ON :8009          # ← 端口已生效（改前为 Listening for http on 0.0.0.0:8008）

$ curl -s -o /dev/null -w '%{http_code}' http://localhost:13930/   # 宿主映射仍指向 8008
000                                                                # ← 连接失败，面板已不在 8008

改回 8008 重启后恢复 200。结论：listen_port 即改即生效，但注意端口映射与防火墙需同步调整。

5.2 Dashboard site_name：空 → Nezha Compose Demo

修改保存重启后，通过管理 API 验证（实测输出）：

$ curl -s http://localhost:13930/api/v1/setting -H "Authorization: Bearer $TOKEN"
{"success":true,"data":{"version":"2.3.18","site_name":"Nezha Compose Demo",...}}

5.3 Agent debug：false → true

$ sed -i 's/^debug: false/debug: true/' /opt/nezha/agent/config.yml
$ systemctl restart nezha-agent
$ journalctl -u nezha-agent --no-pager -n 5
... Started 哪吒监控 Agent.
... NEZHA@2026-10-18 04:17:52>> 检查更新: 2.3.5
... NEZHA@2026-10-18 04:17:52>> 更新失败: GET https://api.github.com/repos/nezhahq/agent/releases: 403 API rate limit exceeded ... [rate reset in 2m17s]
... NEZHA@2026-10-18 04:17:52>> Connection to 172.30.0.2:8008 established
... NEZHA@2026-10-18 04:17:52>> 正在更新本地缓存IP信息

结论： ① debug: true 后日志输出信息级明细（更新检查、连接建立、IP 缓存刷新）；② 顺带实测确认 agent 自动更新机制会请求 api.github.com/repos/nezhahq/agent（agent 独立仓库发版），GitHub 接口限流时更新检查会失败但不影响上报。改回 false 重启后日志恢复安静。

六、告警规则与通知配置参数

这两类不在 config.yaml，通过面板后台或 REST API 维护（存数据库）。实测整理的字段如下。

6.1 告警规则（Alert Rule）

{
  "name": "CPU使用率超过50%",
  "rules":  [ {"type": "cpu", "duration": 3, "min": 0, "max": 50} ],
  "notification_group_id": 1,
  "fail_trigger_tasks":    [1],
  "recover_trigger_tasks": [],
  "enable": true,
  "trigger_mode": 0
}

rules[].type 实测可用枚举（v2.3.18 源码核对 + 实测验证 cpu/memory/transfer_out 三类）：

6.2 通知组与通知方式

• 通知组（Notification Group）：告警规则的 notification_group_id 指向通知组，一个组可挂多个通知方式；
• 通知方式（Notification）：支持 Webhook、Telegram、钉钉、飞书、邮件等，请求体支持占位符：#NEZHA#（通知内容）、#SERVER.NAME#（服务器名）、#DATETIME#（时间）等；
• 实测重要发现（安全限制）：v2.3.18 对 Webhook 通知 URL 做 SSRF 防护，禁止指向私网/回环地址（实测 http://127.0.0.1:9999/hook 保存时被拒绝，提示 is not allowed，对应官方安全公告 GHSA-6x26-5727-rrm9 修复）。对接内网告警系统需走公网可达中转端点，或使用平台内置通知渠道类型；
• 实测行为细节：通知组内没有任何通知方式时，每次告警投递会在 dashboard 日志记录 Notification group 1 has no recipients（可据此排查"告警没发出来"）。

七、常见配置误区

1. 改错文件：OAuth2、告警、通知都在后台界面配（存数据库），config.yaml 只管服务本体；
2. 改完不重启：config.yaml 与 agent config.yml 都要重启对应服务才生效；
3. 端口映射不同步：改 listen_port 后，Docker 端口映射、防火墙、反代 upstream 都要跟着改（见 §5.1 实测）；
4. 阈值方向理解反了：min/max 是"越界即告警"，想让 CPU 低于某值才告警（如流量异常归零检测）应把 min 设为目标下限；
5. 密钥落盘：jwt_secret_key 官方建议用 NZ_JWTSECRETKEY 环境变量注入，避免明文留盘（实测启动日志即有此提示）。

八、参考链接

1. Dashboard 配置结构（config.yaml 字段定义）：https://github.com/nezhahq/nezha
2. Agent 配置与发版（config.yml 字段核对）：https://github.com/nezhahq/agent
3. 站内延伸：《Nezha 运维手册》——日常巡检、agent 迁移、告警实战、日志排障与升级备份。