UniFi 网络实时监控专家

基于 UniFi OS 本地网关 API 的只读网络监控工具，可实时查看设备状态、客户端连接、流量分析及告警，适合家庭/中小企业网络管理员快速掌握网络健康状况。

基本信息

• 技能名称?unifi
• 中文名称?UniFi 网络实时监控专家
• 作者?jmagar
• 分类?其他
• 版本?未标注
• 标签?devops, networking, monitoring, automation, backend, operations

使用方法

使用说明
核心用法
UniFi Network Monitoring Skill 是一款面向 UniFi 网络生态的本地监控工具，通过调用 Cloud Gateway Max 等 UniFi OS 设备的本地 API，实现网络状态的实时查询。用户需在 ~/.clawdbot/credentials/unifi/config.json 中配置网关地址、本地管理员账号及站点信息，即可通过一系列 Bash 脚本获取网络数据。
该技能提供六大核心功能模块：
Dashboard 综合面板 ：一键输出网络健康度、设备列表、客户端、DPI 流量等全量指标的 ASCII 可视化报表
Devices 设备管理 ：列出所有 AP、交换机、网关的型号、IP、在线状态、运行时长及接入客户端数
Clients 客户端监控 ：展示当前在线设备的 hostname、IP、MAC、所连 AP、信号强度及实时速率
Health 健康检查 ：站点级子系统状态（WAN/LAN/WLAN）及设备 adoption 状态统计
Top Apps 流量分析 ：基于 DPI（深度包检测）识别 top 带宽消耗应用，支持自定义显示数量
Alerts 告警中心 ：按时间倒序展示近期网络事件与故障告警
所有命令均支持 json 参数切换为原始 JSON 输出，便于二次开发或自动化集成。
显著优点

1. 只读安全设计 ：全量 GET 请求，零配置变更风险，适合生产环境常态化监控
2. 本地化部署 ：数据不出内网，直接对接 UniFi 网关，无需依赖 Ubiquiti 云服务
3. 零外部依赖 ：仅依赖系统标配工具 curl 与 jq，无 npm/pip 等包管理器引入的供应链风险
4. 轻量高效 ：Bash 脚本实现，启动毫秒级，资源占用极低，适合边缘设备长期运行
5. 场景化工作流 ：内置 "What's on my network?" "Is everything healthy?" 等典型问题的标准处置路径，降低运维门槛
   潜在缺点与局限性
   功能边界受限 ：纯只读设计，无法执行重启 AP、阻断客户端、修改 VLAN 等运维操作
   单站点限制 ：当前版本仅支持单一 site（通常为 default），多站点企业需分别配置
   证书兼容性妥协 ：使用 curl -k 跳过 SSL 验证以适配 UniFi 自签名证书，存在中间人攻击理论风险（需配合网络隔离缓解）
   凭据管理依赖用户 ：配置文件权限控制（chmod 600）需用户手动执行，工具本身无强制校验
   T3 来源属性 ：社区维护项目，长期更新承诺与漏洞响应速度不及官方或商业方案
   适合的目标群体
   家庭网络极客 ：拥有 UniFi 全家桶（UDM/UDR/UCK 等），希望自建监控面板的用户
   中小企业 IT 管理员 ：需快速排查 "谁连了网" "哪台 AP 掉线" "什么应用占带宽" 等日常问题的场景
   DevOps/SRE 工程师 ：希望将 UniFi 网络状态集成到现有监控体系（如通过 JSON 输出对接 Prometheus/Grafana）
   网络故障排查场景 ：临时性诊断需求，无需登录 UniFi Web 控制台即可命令行获取关键信息
   使用风险
   凭据泄露风险 ：配置文件以明文存储密码，若权限设置不当（非 600）或备份同步至不安全位置，可能导致内网管理员凭据泄露
   网络可达性依赖 ：运行节点需与 UniFi 网关 Layer 3 可达，跨 VLAN 或 VPN 场景需提前规划路由
   API 兼容性 ：基于 UniFi OS 3.x/4.x 测试，未来 UniFi 官方 API 变更可能导致脚本失效
   性能瓶颈 ：大规模网络（500+ 客户端）下，全量 JSON 拉取与 jq 解析可能产生秒级延迟，建议分页或按需查询
   SSL 验证弱化 ： -k 参数虽为必要妥协，但在不可信内网环境中可能被利用，建议配合证书固定或网络微分段