哪吒 Agent 的用户密钥、UUID 与服务器记录

[!info] related notes

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

[!abstract] 一句话理解 client_secret 回答“这台 Agent 属于哪个面板用户”，uuid 回答“它是哪一个逻辑 Agent”，数据库服务器记录则是 Dashboard 对该 UUID 的持久表示。

三种身份信息不能混用

信息	作用	是否应每台不同	稳定性要求
用户 client_secret	认证连接并确定所有者	同一用户下可相同	轮换时统一更新
Agent uuid	唯一识别逻辑数据源	是	重装/迁移时应保留
服务器记录 ID	Dashboard 数据库内部主键	是	不应写入 Agent 配置

V1 之后连接密钥与用户绑定。官方文档明确建议使用“服务器页面生成的安装命令”中的 NZ_CLIENT_SECRET，不要把 Dashboard YAML 中旧的全局 agent_secret_key 当作普通用户连接密钥。

注册状态机

stateDiagram-v2
    [*] --> Connecting
    Connecting --> Rejected: 密钥错误或协议被拦截
    Connecting --> Existing: UUID 已存在
    Connecting --> NewRecord: UUID 不存在且认证通过
    NewRecord --> Online
    Existing --> Online
    Online --> Offline: 连接中断
    Offline --> Online: 同 UUID 重连

同一 UUID 重连会复用服务器记录；新 UUID 则创建新记录。因此“同一物理机”不是去重依据，Dashboard 只看身份数据。

服务器记录还带有所有者。即使 client_secret 本身有效，只要该 UUID 已经由另一个用户或旧全局身份注册，Dashboard 也会拒绝连接并返回 client UUID does not belong to the agent secret owner。此时应通过面板的服务器转移能力把记录交给目标用户；只有在无法使用受支持接口且已有数据库备份时，才考虑直接修正所有者字段。

重装为什么容易产生重复记录

官方安装脚本在发现 /opt/nezha/agent/config.yml 已存在时，会为新参数生成另一个随机命名配置文件，并安装额外的 Agent 服务。这允许一台机器运行多个 Agent，但也意味着重复执行安装命令可能产生第二个 UUID、第二个 systemd 单元和第二条面板记录。

[!warning] 安全重装原则 想继承原记录时，必须先取回原 UUID，并在安装命令中显式传入 NZ_UUID=<原 UUID>；若已有服务，先确认是否应更新现有配置，而不是再次无脑运行安装脚本。

可验证实验

# 列出所有哪吒服务，而不是只看默认服务
systemctl list-unit-files --type=service | grep '^nezha-agent'

# 查看每个进程实际加载了哪个配置文件
ps -o pid,args -C nezha-agent

# 只显示 UUID 的哈希，便于跨机器比对而不暴露 UUID
awk -F': *' '/^uuid:/{print $2}' /opt/nezha/agent/config.yml \
  | tr -d '\r\n"' | sha256sum

资料来源

• 官方 Agent 配置说明
• 官方 Agent 安装与带 UUID 重装说明
• 官方安装脚本源码