通过命令行全面管理 UniFi 网络设备，支持 UDM Pro/SE、Dream Machine、Cloud Key 及自建控制器，实现设备监控、客户端管控、WiFi 配置、PoE 端口控制等自动化运维。
说明：
## 核心用法
**ez-unifi** 是基于 `aiounifi` 库构建的 UniFi 网络管理工具，通过命令行脚本实现对 Ubiquiti UniFi 生态系统的全面控制。用户需先创建专用本地管理员账户并配置环境变量（`UNIFI_HOST`、`UNIFI_USERNAME`、`UNIFI_PASSWORD` 等），即可通过 `uv run scripts/unifi.py ` 执行各类操作。
### 功能覆盖
– **设备管理**：列出/重启/升级 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` 命令触发固件更新，若过程中断可能导致设备变砖
– **网络隔离失效**：错误的防火墙/流量规则配置可能意外开放攻击面或阻断关键服务
会员专属
