ez-unifi

核心用法

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 定位等场景化功能显著提升运维效率。

潜在缺点与局限性

1. SSL 验证妥协：为兼容自签名证书场景，代码使用 ssl_context=False 完全禁用 SSL 验证，在严格安全环境中存在中间人攻击风险。
2. 来源可信度有限：T3 级个人/社区来源，缺乏官方 UniFi 背书或大规模社区验证，长期维护稳定性存疑。
3. 网络环境依赖：仅适用于已部署 UniFi 控制器的网络，无法管理其他品牌设备。
4. 速率限制敏感：UniFi API 存在 429 限流机制，高频自动化操作可能触发服务降级。
5. 原始 API 风险：raw 命令虽灵活，但允许直接构造 API 请求，误操作可能导致配置损坏。

适合的目标群体

• 中小企业 IT 管理员：需要批量管理数十台 UniFi 设备的日常运维场景
• 家庭网络极客：拥有 UDM Pro/SE 或 Dream Machine，追求自动化网络管理
• MSP（托管服务提供商）：为多个客户站点提供 UniFi 网络远程运维服务
• DevOps/平台工程师：需要将网络配置纳入 Infrastructure as Code 流程
• 教育/办公场景网管：频繁处理访客 WiFi、客户端阻断、流量管控等需求

使用风险

• 配置误操作风险：重启核心网关、误删流量规则可能导致网络中断，建议先在测试环境验证
• 凭据泄露风险：.env 文件存储明文密码，需严格限制文件权限（建议 600）
• 固件升级风险：upgrade 命令触发设备固件更新，存在升级失败导致设备变砖的可能性
• 依赖项风险：aiounifi 库更新可能引入 API 变更，建议锁定版本并关注上游更新
• 网络可达性风险：控制器 IP 变更或网络分区将导致 Skill 完全失效