Agent 接入与维护

Zeno Agent 安装在被监控服务器上，主动向 Controller 上报主机、资源、流量和探测结果。Agent 不接受远程命令，不提供终端、文件管理或脚本执行。

支持范围

平台	架构	服务方式
Linux	amd64、arm64、armv6、armv7	systemd
macOS	Intel、Apple Silicon	LaunchDaemon
Windows	amd64、arm64	Windows Service

Linux 官方安装器要求 systemd，并创建专用非登录用户。其他 init 系统可以手动运行二进制，但不属于官方安装器支持范围。Controller 与 Agent 独立发布，版本号不要求相同；使用前查看 已验证组合。

接入前检查

1. Controller /ready 正常。
2. 后台“设置”中的 Agent 接入 URL 能从目标服务器访问。
3. 远程地址使用有效 HTTPS 证书。
4. 目标服务器时间同步正常。
5. 防火墙允许目标服务器访问 Controller 的 HTTPS 端口。

可在目标服务器先测试：

curl -fsS https://zeno.example.com/ready

安装 Agent

1. 在后台“服务器”创建或打开目标服务器。
2. 点击“复制安装命令”。
3. 选择 Linux、macOS 或 Windows。
4. 在对应服务器执行完整命令。

安装命令是敏感信息

安装命令包含一次性 enrollment token。不要保存到公共脚本、Shell 历史分享、Issue、截图或聊天群。安装成功后，Agent 会换取该节点独立的 runtime token。

重新生成安装命令可能使旧 enrollment 凭据失效；不要把同一条命令复制到多台服务器。

验证上报

Linux：

systemctl is-active zeno-agent.service
journalctl -u zeno-agent.service --since '10 minutes ago' --no-pager

同时检查：

• 首页节点从 no_data 变为 online 或 warning；
• 后台服务器列表出现 last seen、Agent 版本和主机信息；
• CPU、内存、磁盘、网络速率和累计流量不再为空；
• 配置探测目标后能看到延迟或明确的探测错误，而不是伪造 0 ms。

状态含义

状态	含义
online	最近收到心跳，且没有活动中的资源异常
warning	Agent 仍在线，但资源规则或探测状态命中异常
offline	超过离线规则的心跳时限
no_data	Controller 从未收到该节点的有效上报

warning 不等于 Agent 断开。先看后台通知规则和节点详情，再检查 Agent 日志。

探测任务

Controller 可向 Agent 下发三种探测：

• ping：ICMP，多样本统计延迟和丢包；
• tcping：TCP connect，需要端口；
• http_get：HTTP/HTTPS GET，2xx/3xx 视为成功，4xx/5xx 视为 unhealthy。

目标创建后还需要分配给具体服务器。不要把内网管理地址、云元数据地址或敏感端口配置为公共探测目标；相关安全边界见 安全文档。

更新 Agent

Controller 升级通常不要求同步升级 Agent。只有 Release notes 或 兼容性表 明确要求时，才重新运行后台生成的安装命令。

更新后重新检查服务状态、Agent 版本、last seen 和一次真实指标上报。不要只根据安装脚本退出码判断成功。

移除或迁移

移除 Agent 前先在目标服务器停止并卸载服务，再由管理员确认是否删除 Zeno 中的服务器记录。删除服务器记录会影响关联历史与配置，按后台确认提示操作。

迁移到新机器时应新建服务器或重新生成该节点的安装命令，不要复制旧 runtime token、服务配置或数据目录。

常见问题

一直是 no_data

按顺序检查：

1. 目标服务器能否访问 Controller /ready；
2. 安装命令中的域名和协议是否正确；
3. Agent 服务是否 active；
4. Agent 日志是否有 TLS、DNS、401/403 或时间同步错误；
5. 是否误把同一条 enrollment 命令用于多台服务器。

突然 offline

检查 Agent 服务、目标服务器网络、Controller readiness 和反向代理。离线阈值由通知规则控制，不能通过修改浏览器显示掩盖。

指标正常但探测无数据

确认目标已分配给该节点，并检查类型、地址、端口、探测间隔以及 Agent 到目标的真实网络可达性。