哪吒 Agent 重复注册排查与清理

[!info] related notes

• 所属地图：哪吒监控 MOC
• 身份原理：哪吒 Agent 的用户密钥、UUID 与服务器记录
• 正确重装：安装和重装哪吒 Agent

[!abstract] 根因模型 一台物理服务器可以合法运行多个 Agent。重复执行安装脚本时，已有 config.yml 会促使脚本生成随机配置和额外 systemd unit；每份配置拥有不同 UUID，于是 Dashboard 创建多条记录。

可识别现象

• 面板突然出现两条随机英文名记录。
• 两条记录的内存、磁盘容量、网卡速率和系统版本高度一致。
• ps -C nezha-agent 显示多个进程，参数分别指向 config.yml 和 config-xxxxx.yml。
• systemctl list-unit-files 同时出现 nezha-agent.service 与 nezha-agent-xxxx.service。

先确定“保留哪一个”

默认保留由预期 systemd unit 加载的持久配置，而不是按面板名称或创建顺序猜测。

systemctl cat nezha-agent
ps -o pid,args -C nezha-agent
sudo find /opt/nezha/agent -maxdepth 1 -name 'config*.yml' -type f -print

跨 Agent 和 Dashboard 比对 UUID 时，可以只显示哈希：

for file in /opt/nezha/agent/config*.yml; do
  printf '%s|' "$file"
  sudo awk -F': *' '/^uuid:/{print $2}' "$file" \
    | tr -d '\r\n"' | sha256sum | cut -c1-12
done

Dashboard SQLite 也可在本机计算 UUID 哈希，但不要把完整 UUID、密钥或数据库复制到公共日志。

安全清理顺序

1. 精确记录临时 unit、临时配置、Dashboard 记录 ID 和 UUID 映射。
2. 停止并禁用临时 unit，确认不会再次拉起。
3. 将临时 unit 与配置移动到受限备份目录，而不是立即删除。
4. 检查目标 Dashboard 记录是否关联分组、任务、服务或历史。
5. 使用 Dashboard UI 删除无关联的重复记录；必须操作 SQLite 时，先做一致性备份并在事务中执行。
6. 重启 Dashboard 或等待缓存刷新，核对保留记录在线。

停止额外 unit

sudo systemctl disable --now nezha-agent-abcdef.service
sudo install -d -m 700 /opt/nezha/agent/duplicate-backup
sudo mv /etc/systemd/system/nezha-agent-abcdef.service \
  /opt/nezha/agent/duplicate-backup/
sudo mv /opt/nezha/agent/config-xxxxx.yml \
  /opt/nezha/agent/duplicate-backup/
sudo systemctl daemon-reload

[!warning] 不要先删面板记录 如果额外 Agent unit 仍在运行，它会再次使用同一 UUID 连接，导致记录重新出现或持续消耗资源。先处理进程生命周期，再清理展示层。

本次 Oracle 案例

两台 Oracle 机器各存在默认 unit 和随机后缀 unit。四条随机命名记录中，成对记录的内存与磁盘比例一致。通过 UUID 哈希完成映射后，保留默认 config.yml 对应记录，禁用并归档额外 unit，再删除无任何关联数据的两条临时记录。Dashboard 数据库在修改前使用 SQLite .backup 保存快照。

回归验证

systemctl list-units --type=service | grep nezha-agent
ps -o pid,args -C nezha-agent

• 每台机器只剩一个预期 unit 和进程。
• 面板每台物理机只显示一条预期记录。
• 重启 Agent 后不会生成新记录。
• 备份中仍能找到被归档的配置和数据库快照。

资料来源

• 官方 Agent 安装与多服务说明
• 官方 Agent 配置与多服务管理
• 官方安装脚本源码