安装和重装哪吒 Agent

[!info] related notes

• 所属地图：哪吒监控 MOC
• 身份前置：哪吒 Agent 的用户密钥、UUID 与服务器记录
• 故障排查：哪吒 Agent 无法上线排查
• 重复清理：哪吒 Agent 重复注册排查与清理

目标

使一台 Linux 服务器只运行一个预期的 Agent 服务，并在面板中只出现一条可持续复用的服务器记录。

首次安装

1. 在 Dashboard 的“服务器 → 安装命令”复制当前用户生成的命令。
2. 检查 NZ_SERVER、NZ_TLS 和 NZ_CLIENT_SECRET 是否来自目标面板。
3. 在服务器执行命令。
4. 同时验证服务、进程、配置文件和面板记录。

curl -L https://raw.githubusercontent.com/nezhahq/scripts/main/agent/install.sh \
  -o agent.sh
chmod +x agent.sh
env NZ_SERVER=data.example.com:443 \
    NZ_TLS=true \
    NZ_CLIENT_SECRET='<从面板安装命令取得>' \
    ./agent.sh

不要把安装命令、密钥或完整配置写进公开笔记和日志。

安装后验证

systemctl list-unit-files --type=service | grep '^nezha-agent'
systemctl status nezha-agent --no-pager
ps -o pid,args -C nezha-agent
sudo ss -tpn | grep nezha-agent

成功状态：只有一个预期 unit、一个主进程，进程参数指向预期的 config.yml，面板中只新增一条记录。

已安装机器不能直接重复执行

先做盘点：

sudo find /opt/nezha/agent -maxdepth 1 -name 'config*.yml' -type f -print
systemctl list-unit-files --type=service | grep '^nezha-agent'
ps -o pid,args -C nezha-agent

如果已经存在 config.yml，官方脚本可能生成 config-xxxxx.yml 并安装第二个服务。这是多 Agent 功能，不是原地升级语义。

保留原记录重装

1. 备份原 config.yml。
2. 保存原 UUID；不要输出 client_secret。
3. 停止并卸载旧服务。
4. 使用面板当前用户密钥，并显式传入 NZ_UUID=<原 UUID>。
5. 检查没有遗留 nezha-agent-xxxx.service。

sudo cp /opt/nezha/agent/config.yml \
  /opt/nezha/agent/config.yml.bak-before-reinstall

sudo /opt/nezha/agent/nezha-agent service uninstall

env NZ_SERVER=data.example.com:443 \
    NZ_TLS=true \
    NZ_CLIENT_SECRET='<当前用户密钥>' \
    NZ_UUID='<原 UUID>' \
    ./agent.sh

[!warning] 不要从 Dashboard YAML 取全局密钥 v1+ 应使用服务器页面安装命令中的用户连接密钥。全局 agent_secret_key 已不再是普通用户 Agent 的权威凭据。

安全默认值

不需要远程控制时，可考虑：

disable_command_execute: true
disable_force_update: true
disable_nat: true
insecure_tls: false
debug: false

开启这些限制会牺牲面板远程终端、强制升级或 NAT 功能，应按用途选择，而不是机械套用。

资料来源

• 官方 Agent 安装
• 官方 Agent 配置
• 官方 Agent 安装脚本