哪吒 Agent 无法上线排查

[!info] related notes

• 所属地图：哪吒监控 MOC
• 架构：哪吒 Dashboard、Agent 与 gRPC 的协作架构
• 安装：安装和重装哪吒 Agent
• 重复记录：哪吒 Agent 重复注册排查与清理

[!abstract] 排障顺序 服务进程 → DNS/端口 → TLS/HTTP2 → gRPC 路径 → 身份鉴权 → Dashboard 记录。不要因为网页能打开就跳过中间层。

快速决策树

flowchart TD
    A[Agent 离线] --> B{systemd active?}
    B -- 否 --> C[查 unit、路径、权限和架构]
    B -- 是 --> D{443 可连接?}
    D -- 否 --> E[查 DNS、路由、NSG、UFW]
    D -- 是 --> F{gRPC 探测返回 application/grpc?}
    F -- 否: 403 HTML --> G[Cloudflare gRPC/WAF/Access]
    F -- 否: 502/GOAWAY --> H[反代 h2c 配置]
    F -- 是 --> I{Agent 日志鉴权成功?}
    I -- 否 --> J[用户 client_secret、UUID]
    I -- 是 --> K[查 Dashboard 数据与前端筛选]

第一步：进程与配置唯一性

systemctl status 'nezha-agent*' --no-pager
systemctl list-unit-files --type=service | grep '^nezha-agent'
ps -o pid,ppid,etime,args -C nezha-agent

active 只表示进程没有退出，不表示它已经通过鉴权。若有多个 unit 或多个 config-xxxxx.yml，先转到重复注册排障。

第二步：网络与 TLS

getent ahostsv4 data.example.com
nc -vz data.example.com 443
curl -svI --connect-timeout 8 https://data.example.com/

• timeout：优先查路由、云安全组、主机防火墙或源站只放行 CDN IP。
• 证书错误：查域名、SNI、证书链和 tls/insecure_tls。
• Web 200：只能继续证明 Web 入口正常，不能结束排障。

第三步：gRPC 协议探测

curl --http2 -v -X POST \
  -H 'Content-Type: application/grpc' \
  https://data.example.com/proto.NezhaService/

证据	典型根因
HTTP 403、server: cloudflare、HTML	Cloudflare Zone 未启用 gRPC，或安全规则阻断
502、GOAWAY	Caddy/Nginx 到 Dashboard 的 h2c/gRPC 转发错误
404 或普通 HTML	gRPC 路径没有进入正确 matcher
HTTP/2 + application/grpc + grpc-status: 12	协议路径正常，可以继续查鉴权

第四步：临时启用 Agent 调试日志

sudo cp /opt/nezha/agent/config.yml \
  /opt/nezha/agent/config.yml.bak-before-debug
sudo sed -i 's/^debug: false/debug: true/' \
  /opt/nezha/agent/config.yml
sudo systemctl restart nezha-agent
sudo journalctl -u nezha-agent --since '-5 min' --no-pager

完成后恢复 debug: false 并重启，避免长期产生噪声日志。

典型日志解释

• PermissionDenied + HTML 403：请求通常在 Dashboard 鉴权前被 CDN/代理拒绝。
• context deadline exceeded：TCP/TLS 或 HTTP/2 通道未能在截止时间内就绪。
• 连接建立后立即鉴权失败：核对用户生成的 client_secret，不要从 YAML 的旧全局字段猜测。
• client UUID does not belong to the agent secret owner：密钥有效，但该 UUID 的服务器记录属于另一个用户或 legacy 所有者；应转移记录所有权或用目标用户重新注册。
• Agent 不断访问 GitHub：可能正在检查更新；这不是 Dashboard 长连接，应结合目标 IP、持续时间与后续日志判断。

回归验证

• 只存在预期 Agent unit 和进程。
• gRPC 探测得到 application/grpc。
• Agent 日志不再循环重连。
• Dashboard 中 UUID 对应记录在线。
• 重启 Agent 后仍复用同一记录。

资料来源

• 官方 Agent 上线自检
• 官方反向代理配置
• Cloudflare gRPC