unifi

核心用法

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 参数虽为必要妥协，但在不可信内网环境中可能被利用，建议配合证书固定或网络微分段