UniFi 网络一站式智能管家

基于 aiounifi 库的 UniFi 网络管理工具，支持 UDM Pro/SE、Dream Machine 等设备的全生命周期管理，让网络运维自动化、可视化。

基本信息

• 技能名称?ez-unifi
• 中文名称?UniFi 网络一站式智能管家
• 作者?araa47
• 分类?开发
• 版本?v1.0.1
• 标签?devops, automation, backend, networking, operations

使用方法

使用说明
核心用法
ez-unifi 是一款面向 UniFi 网络生态的 Agent 友好型管理工具，基于成熟的 aiounifi Python 库构建，通过命令行接口实现对 UniFi 控制器的全面操控。用户需先创建专用本地管理员账户并配置 .env 文件，即可通过 uv run scripts/unifi.py 执行各类网络管理任务。
该 Skill 覆盖六大核心场景： 设备管理 （AP、交换机、网关的查询、重启、升级、定位）、 端口控制 （PoE 模式设置、端口启停、电源循环）、 客户端管控 （列表查询、阻断/解封、强制重连）、 WiFi 网络运维 （SSID 启停、密码修改、二维码生成）、 安全策略 （流量规则、防火墙策略、DPI 深度包检测）、 访客管理 （限时凭证生成、速率限制）。此外还提供原始 API 访问能力，满足高级定制需求。
显著优点

1. 生态完整度高 ：原生支持 UDM Pro/SE、Dream Machine、Cloud Key Gen2+ 及自托管控制器，覆盖 UniFi 全系列硬件。
2. 操作粒度精细 ：从整机重启到单端口 PoE 循环，从全局流量规则到单个客户端阻断，满足企业级网络运维的精细化需求。
3. 自动化友好 ：所有列表命令支持 --json 输出，便于脚本集成；事件流实时监听功能支持自动化告警触发。
4. 安全设计合理 ：强制要求专用本地账户、明确禁用远程访问规避 MFA 问题、敏感操作需用户主动调用，无静默数据收集。
5. 实用功能丰富 ：WiFi 二维码生成、访客凭证批量创建、设备 LED 定位等场景化功能显著提升运维效率。
   潜在缺点与局限性
6. SSL 验证妥协 ：为兼容自签名证书场景，代码使用 ssl_context=False 完全禁用 SSL 验证，在严格安全环境中存在中间人攻击风险。
7. 来源可信度有限 ：T3 级个人/社区来源，缺乏官方 UniFi 背书或大规模社区验证，长期维护稳定性存疑。
8. 网络环境依赖 ：仅适用于已部署 UniFi 控制器的网络，无法管理其他品牌设备。
9. 速率限制敏感 ：UniFi API 存在 429 限流机制，高频自动化操作可能触发服务降级。
10. 原始 API 风险 ： raw 命令虽灵活，但允许直接构造 API 请求，误操作可能导致配置损坏。
    适合的目标群体
    中小企业 IT 管理员 ：需要批量管理数十台 UniFi 设备的日常运维场景
    家庭网络极客 ：拥有 UDM Pro/SE 或 Dream Machine，追求自动化网络管理
    MSP（托管服务提供商） ：为多个客户站点提供 UniFi 网络远程运维服务
    DevOps/平台工程师 ：需要将网络配置纳入 Infrastructure as Code 流程
    教育/办公场景网管 ：频繁处理访客 WiFi、客户端阻断、流量管控等需求
    使用风险
    配置误操作风险 ：重启核心网关、误删流量规则可能导致网络中断，建议先在测试环境验证
    凭据泄露风险 ： .env 文件存储明文密码，需严格限制文件权限（建议 600）
    固件升级风险 ： upgrade 命令触发设备固件更新，存在升级失败导致设备变砖的可能性
    依赖项风险 ：aiounifi 库更新可能引入 API 变更，建议锁定版本并关注上游更新
    网络可达性风险 ：控制器 IP 变更或网络分区将导致 Skill 完全失效