核心用法
ez-unifi 是基于 aiounifi 库构建的 UniFi 网络管理工具，通过命令行脚本实现对 Ubiquiti UniFi 生态系统的全面控制。用户需先创建专用本地管理员账户并配置环境变量（UNIFI_HOST、UNIFI_USERNAME、UNIFI_PASSWORD 等），即可通过 uv run scripts/unifi.py <command> 执行各类操作。
功能覆盖
- 设备管理：列出/重启/升级 AP、交换机、网关，LED 定位，硬重启（PoE 循环）
- 端口控制：交换机端口启用/禁用、PoE 模式设置（auto/off/passthrough/24v）、电源循环
- 客户端管控：查看在线/离线客户端、阻断/解封设备、强制重连、永久遗忘
- WiFi 网络：SSID 管理、密码修改、生成 WiFi 二维码
- 高级功能：流量规则/路由控制、防火墙策略管理、DPI 深度包检测、热点凭证创建、事件实时流、原始 API 访问
输出格式
默认表格化输出，附加 --json 标志可获取结构化数据便于脚本集成。
显著优点
1. 生态完整：覆盖 UniFi 全系硬件（UDM Pro/SE/Dream Machine/Cloud Key Gen2+）及自建控制器
2. 功能纵深：从基础设备重启到 PoE 精细控制、DPI 应用层过滤、访客凭证系统，满足企业级需求
3. Agent 友好：标准化 JSON 输出、清晰的 ID/MAC 查找机制、详细的命令示例，适合自动化脚本和 AI Agent 集成
4. 安全设计：强制要求本地专用账户，禁用远程访问以避免 MFA 冲突，降低凭证泄露风险
潜在缺点与局限性
1. 准入门槛：需手动创建本地管理员账户并配置环境变量，对非技术用户不够友好
2. 硬件依赖：功能受限于 UniFi 控制器 API 版本，部分新特性可能需等待固件更新
3. 网络可达性：要求运行环境能与 UniFi 控制器网络通信，远程管理需额外 VPN 或端口转发
4. 速率限制：存在 API 限流机制（429 错误），高频自动化场景需设计退避策略
5. 无云原生：不支持 Ubiquiti 官方云服务直接管理，必须基于本地控制器
适合人群
- 家庭/小型办公网络管理员：需要快速重启设备、管理访客 WiFi、控制孩子设备上网
- IT 运维工程师：批量管理多站点 UniFi 网络，集成到现有监控/自动化体系
- 智能家居开发者：通过脚本实现网络状态感知、设备联动（如断网自动重启 PoE 摄像头）
- 技术爱好者：深度定制网络行为，探索 DPI、流量路由等高级功能
常规风险
- 权限过高：Super Admin/Site Admin 权限可完全控制网络，凭证泄露后果严重
- 误操作风险：
forget命令永久删除客户端记录、power-cycle可能中断关键 PoE 设备供电 - 固件升级风险：
upgrade命令触发固件更新，若过程中断可能导致设备变砖 - 网络隔离失效：错误的防火墙/流量规则配置可能意外开放攻击面或阻断关键服务