核心用法
ez-unifi 是一款面向 Agent 的 UniFi 网络管理工具，基于 aiounifi 库构建，支持 UDM Pro/SE、Dream Machine、Cloud Key Gen2+ 及自托管控制器。通过命令行界面提供完整的网络运维能力，涵盖设备生命周期管理、客户端接入控制、WiFi 网络配置、PoE 供电管理、流量规则调控等核心场景。
主要功能模块
- 设备管理：查看设备状态、重启/硬重启、固件升级、LED 定位
- 交换机端口：端口详情查看、PoE 模式配置（auto/off/passthrough/24v）、电源循环
- 客户端控制：列出活跃/历史客户端、阻断/解除阻断、强制重连、永久遗忘
- WiFi 网络：启用/禁用网络、生成 WiFi 二维码
- 流量管理：查看和启停流量规则、流量路由、防火墙策略
- 访客系统：创建带时长/配额/限速的临时凭证
- 智能电源：PDU 插座开关控制、断网自动循环配置
- 实时监控：事件流实时输出
显著优点
1. 硬件覆盖广：支持 Ubiquiti 主流网关、交换机、AP 全系列
2. 操作粒度细：从整设备到单端口级别的精准控制
3. 安全设计：推荐使用本地专用账号，规避云账户 MFA 问题
4. 输出友好：默认 JSON 格式，便于自动化解析集成
潜在局限
- 依赖 Python 环境及
uv包管理器 - 需预先配置
.env凭证文件 - 频繁操作可能触发 API 速率限制（429 错误）
- 部分高级功能需 Super Admin 权限
适合人群
- 家庭/中小企业网络管理员
- DevOps 工程师需自动化网络运维
- 智能家居集成开发者
- 技术爱好者进行网络实验
常规风险
- 凭证泄露：
.env文件存储明文密码，需严格限制文件权限 - 误操作断网：重启网关或错误配置 PoE 可能导致网络中断
- 固件风险：自动升级可能引入兼容性问题
- 权限过高：Super Admin 账号泄露将导致全网失控