上一篇文章介绍了 NMS 侧 xxlsnmpnms CLI 的对接验证方法。本篇聚焦 设备端 Agent SDK 演示 Demo（xxl_snmp_agent_demo.c）：它通过 snmp_agent_api.h 全套标准接口，把 Agent 侧的能力——MIB 注册回调、SNMPv3 用户管理、引擎 ID 动态设置、Trap/Inform 主动上报、NMS 访问白名单——封装成一条条 CLI 命令，业务开发人员照着命令即可掌握接口调用方式。
一、Agent CLI 与 NMS CLI 的定位差异
Agent CLI 运行在设备端，NMS CLI 运行在管理端，两者通过 UDP 161/162 配合完成完整的设备管理闭环：
Agent CLI（设备端）
status / stop / start —— 运行状态
comm —— 读写共同体
engineid / seteng —— 引擎 ID
userget / usercnt —— V3 用户
trapauto / trap —— 告警上报
wladd / wlcnt —— NMS 白名单
NMS CLI（管理端）
get / getnext —— 数据采集
set —— 远程配置
bulkwalk —— 批量遍历
traplisten —— 告警监听
图 1：Agent CLI 与 NMS CLI 的设备管理闭环
二、命令速查表（26 条）
| 分组 | 命令 | 对应 SDK 接口 | 说明 |
|---|---|---|---|
| 运行状态 | status | agent_snmp_get_state | 查询运行状态 + 自动告警开关 |
| stop / start | agent_snmp_stop / start | 临时停止 / 重启 UDP 监听 | |
| comm | agent_snmp_get_community | 查询读写共同体 | |
| SNMPv3 | engineid | agent_snmp_get_engine_id | 打印引擎 ID 字节 |
| seteng [hex] | agent_snmp_set_engine_id | 动态设置引擎 ID，v3 密钥重新派生 | |
| usercnt / userget / deladmin | agent_snmp_v3_* | V3 用户统计 / 查询 / 删除 | |
| MIB 管理 | mibcnt | agent_snmp_mib_get_count | 已注册节点总数 |
| mibdel [oid] | agent_snmp_mib_unregister | 删除指定 OID 节点 | |
| refresh | agent_snmp_mib_refresh | 手动刷新温度 MIB 缓存 | |
| 告警上报 | trapauto / informauto | （业务开关） | 开启/关闭自动温度上报 |
| trap [ip] / inform [ip] | agent_snmp_trap_custom / inform_custom | 手动单发，可指定目标 NMS IP | |
| 白名单 | wladd a.b.c.d | agent_snmp_whitelist_add | 添加 NMS 访问白名单 |
| wldel a.b.c.d | agent_snmp_whitelist_remove | 删除白名单条目 | |
| wlclear | agent_snmp_whitelist_clear | 清空全部白名单 | |
| wlcnt | agent_snmp_whitelist_get_count | 查看白名单条目数 | |
| 日志 | log0 ~ log3 | agent_snmp_set_log_level | DEBUG / INFO / WARN / ERROR |
| 其他 | oidchk / exit | agent_snmp_oid_validate / deinit | OID 合法性校验 / 安全退出释放资源 |
三、Demo 主循环架构
Demo 采用单线程主循环设计，SDK 内核调度、业务自动采集上报、CLI 命令处理三件事在一个循环内完成，适配 Windows（_kbhit）与 Linux（select）双平台非阻塞输入：
// 主循环：SDK 调度 + 业务自动采集上报 + 控制台 CLI 交互
while (!g_exit_flag)
{
// 1. SDK 内核调度：报文收发、Inform 应答匹配、超时回收
agent_snmp_loop();
// 2. 业务自动逻辑：温度采集 → 阈值判断 → 温差过滤 → 上报
int temp = hardware_get_temp();
if (temp > TEMP_INFORM_THRESHOLD) { ... agent_snmp_inform_custom(...); }
else if (temp > TEMP_TRAP_THRESHOLD) { ... agent_snmp_trap_custom(...); }
// 3. CLI 命令处理（Windows _kbhit / Linux select 非阻塞）
if (有键盘输入) handle_cmd(input_buf);
usleep(MAIN_LOOP_SLEEP_US); // 10ms 轮询
}
图 2：Agent Demo 初始化与主循环流程
四、温度告警业务逻辑与 OID 设计
Demo 内置模拟温度采集（hardware_get_temp，42~88℃ 波动），业务 OID 统一使用企业私有前缀 .1.3.6.1.4.1.12345：
| OID | 用途 | 类型 |
|---|---|---|
| .1.3.6.1.4.1.12345.1.1.0 | 当前温度（NMS 可读） | 只读 MIB 节点 |
| .1.3.6.1.4.1.12345.1.2.0 | 告警参数温度（随 Trap/Inform 携带） | 告警负载 |
| .1.3.6.1.4.1.12345.2.1 | 温度普通告警 Trap OID | 告警标识 |
| .1.3.6.1.4.1.12345.2.2 | 温度严重告警 Inform OID | 告警标识 |
告警规则采用「阈值 + 温差过滤」双重判定，避免温度抖动导致告警风暴：
图 3：温度告警分级规则（阈值 + 温差过滤）
五、核心操作实战
1. 动态设置 SNMPv3 引擎 ID
# 查看当前引擎 ID（十六进制字节）
engineid
# 引擎ID长度：6 字节数据：44 45 56 30 30 31 （DEV001）
# 动态设置引擎 ID（十六进制字符串），v3 用户密钥自动重新派生
seteng 444556303032
# 动态设置引擎ID成功，所有v3用户密钥已重新派生
2. SNMPv3 用户管理
# 统计 V3 用户数量
usercnt
# 当前SNMPv3用户总数：2
# 查询指定用户安全配置
userget admin
# 用户名：admin
# 认证算法：SHA256
# 加密算法：AES128
# 删除内置测试账号
deladmin
3. NMS 访问白名单配置
# 添加 NMS 管理端 IP 到白名单（仅名单内 IP 可访问设备）
wladd 192.168.1.200
# 添加白名单IP 192.168.1.200 成功
# 查看白名单条目数
wlcnt
# 当前白名单条目总数：1
# 删除 / 清空
wldel 192.168.1.200
wlclear
4. 手动触发 Trap / Inform 上报
# 手动单发 Trap（默认目标 NMS 或指定 IP）
trap
# 测试Trap发送完成，目标：默认NMS
trap 192.168.1.100
# 测试Trap发送完成，目标：192.168.1.100
# 手动单发 Inform（等待 NMS 应答确认）
inform 192.168.1.100
# 测试Inform报文已发送，目标：192.168.1.100，等待NMS应答
六、告警闭环验证：Agent 触发 + NMS 监听
新版机制下，告警由 Agent 侧主动上报，NMS 侧只需保持监听。推荐闭环验证流程：
# 终端 1（NMS 侧）：开启 Trap 监听
xxlsnmpnms traplisten -p 162
# 终端 2（Agent 侧 CLI）：开启自动温度告警
trapauto 1
informauto 1
# 温度超过 80℃ 自动发 Trap，超过 85℃ 自动发 Inform
# 或手动触发验证：
trap 192.168.1.100
inform 192.168.1.100
监听窗口即可看到 Agent 上报的告警报文（来源 IP、版本、共同体、变量绑定）。也可先在 NMS 侧用 get 读取温度节点 .1.3.6.1.4.1.12345.1.1.0，确认设备在线后等待自动告警。
七、跨平台实现要点
| 能力 | Windows | Linux |
|---|---|---|
| 控制台编码 | SetConsoleOutputCP(CP_UTF8) 切换 UTF-8 | 默认 UTF-8 |
| 退出信号 | SetConsoleCtrlHandler 捕获 Ctrl+C/窗口关闭 | signal(SIGINT) |
| 非阻塞输入 | _kbhit() + fgets | select() 超时 0ms 轮询 |
| 休眠 | Sleep(us/1000) | usleep(us) |