（1635期）EZ Unifi – UniFi 网络全能命令行管家

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