unifi.py devices --json            # JSON output
unifi.py clients --json

ez-unifi

基于 aiounifi 库的、对智能体友好的 UniFi 网络工具。支持 UDM Pro/SE、Dream Machine、Cloud Key Gen2+ 以及自托管控制器。

所有命令通过以下方式运行： uv run scripts/unifi.py [args]

设置

步骤 1：请用户创建一个专用的本地管理员账户

要管理您的 UniFi 网络，我需要 API 访问权限。请创建一个专用的本地管理员账户：

1. 1. 打开您的 UniFi 控制器（例如，https://192.168.1.1）
2. 转到 设置 → 系统 → 管理员与用户
3. 点击 添加管理员
4. 输入用户名（例如，agent-api）
5. 输入电子邮件和密码
6. 重要：禁用“远程访问” - 仅限本地可避免 MFA 问题
7. 将角色设置为 超级管理员 或 站点管理员
8. 点击 添加

然后提供：

• - 控制器 IP（例如，192.168.1.1）
• 用户名
• 密码
• 是否为 UDM Pro/SE/Dream Machine？（是/否）

步骤 2：将凭据保存到 .env

bash
UNIFI_HOST=https://192.168.1.1
UNIFI_USERNAME=agent-api
UNIFIPASSWORD=thepassword
UNIFI_SITE=default
UNIFIISUDM=true

对于 Cloud Key Gen1 或自托管控制器，请设置 UNIFIISUDM=false。

---

系统与站点

bash
unifi.py sites # 列出所有站点
unifi.py sysinfo # 系统信息
unifi.py health # 站点健康状态（WAN、WLAN、LAN）

设备（AP、交换机、网关）

bash
unifi.py devices # 列出所有设备
unifi.py device MAC # 设备详情
unifi.py restart MAC # 重启设备
unifi.py restart MAC --hard # 硬重启（循环交换机上的 PoE 供电）
unifi.py upgrade MAC # 升级设备固件
unifi.py locate MAC # 闪烁 LED 以定位设备
unifi.py unlocate MAC # 停止 LED 闪烁
unifi.py led MAC on|off|default # 设置 LED 状态
unifi.py led MAC on --color=#FF0000 --brightness=50 # 带颜色/亮度设置

交换机端口

bash
unifi.py ports # 列出所有交换机端口
unifi.py port MAC PORT_IDX # 端口详情
unifi.py port-enable MAC PORT_IDX # 启用交换机端口
unifi.py port-disable MAC PORT_IDX # 禁用交换机端口
unifi.py poe MAC PORT_IDX MODE # 设置 PoE 模式（auto|off|passthrough|24v）
unifi.py power-cycle MAC PORT_IDX # 对 PoE 端口进行电源循环

智能电源（PDU/插座）

bash
unifi.py outlets # 列出所有插座
unifi.py outlet MAC IDX on|off # 控制插座继电器
unifi.py outlet-cycle MAC IDX on|off # 启用/禁用互联网断连时的自动循环

客户端

bash
unifi.py clients # 列出活跃客户端
unifi.py clients-all # 列出所有客户端（包括离线/已知设备）
unifi.py client MAC # 客户端详情
unifi.py block MAC # 阻止客户端访问网络
unifi.py unblock MAC # 解除客户端阻止
unifi.py reconnect MAC # 踢出/重新连接客户端
unifi.py forget MAC [MAC2...] # 永久忘记客户端

WiFi 网络

bash
unifi.py wlans # 列出无线网络
unifi.py wlan ID # WLAN 详情
unifi.py wlan-enable ID # 启用 WLAN
unifi.py wlan-disable ID # 禁用 WLAN
unifi.py wlan-password ID NEWPASS # 更改 WLAN 密码
unifi.py wlan-qr ID # 生成 WiFi 二维码（PNG 文件）
unifi.py wlan-qr ID -o myqr.png # 自定义输出文件名

端口转发

bash
unifi.py port-forwards # 列出端口转发规则
unifi.py port-forward ID # 端口转发详情

流量规则

bash
unifi.py traffic-rules # 列出流量规则
unifi.py traffic-rule ID # 流量规则详情
unifi.py traffic-rule-enable ID # 启用流量规则
unifi.py traffic-rule-disable ID # 禁用流量规则
unifi.py traffic-rule-toggle ID on|off # 切换流量规则状态

流量路由

bash
unifi.py traffic-routes # 列出流量路由
unifi.py traffic-route ID # 流量路由详情
unifi.py traffic-route-enable ID # 启用流量路由
unifi.py traffic-route-disable ID # 禁用流量路由

防火墙

bash
unifi.py firewall-policies # 列出防火墙策略
unifi.py firewall-policy ID # 防火墙策略详情
unifi.py firewall-zones # 列出防火墙区域
unifi.py firewall-zone ID # 防火墙区域详情

DPI（深度包检测）

bash
unifi.py dpi-apps # 列出 DPI 限制应用
unifi.py dpi-app ID # DPI 应用详情
unifi.py dpi-app-enable ID # 启用 DPI 应用限制
unifi.py dpi-app-disable ID # 禁用 DPI 应用限制
unifi.py dpi-groups # 列出 DPI 限制组
unifi.py dpi-group ID # DPI 组详情

热点凭证

bash
unifi.py vouchers # 列出凭证
unifi.py voucher-create --duration=60 --quota=1 --note=Guest
unifi.py voucher-create --duration=1440 --quota=5 --rate-up=5000 --rate-down=10000
unifi.py voucher-delete ID # 删除凭证

凭证选项：

• - --duration - 有效期（分钟，默认：60）
• --quota - 使用次数（默认：1）
• --usage-quota - 使用配额（MB）
• --rate-up - 上传速率限制（Kbps）
• --rate-down - 下载速率限制（Kbps）
• --note - 备注/描述

事件

bash
unifi.py events # 实时流式传输事件（按 Ctrl+C 停止）

原始 API 访问

bash
unifi.py raw GET /stat/health # 原始 GET 请求
unifi.py raw POST /cmd/devmgr {cmd:restart,mac:aa:bb:cc:dd:ee:ff}
unifi.py raw PUT /rest/wlanconf/ID {enabled:false}

输出选项

在任何列表命令后添加 --json 标志以输出 JSON：
bash
unifi.py devices --json # JSON 输出
unifi.py clients --json

---

示例

bash

检查网络健康状态

uv run scripts/unifi.py health

列出所有已连接的客户端

uv run scripts/unifi.py clients

阻止一个设备

uv run scripts/unifi.py block aa:bb:cc:dd:ee:ff

重启一个接入点

uv run scripts/unifi.py restart 11:22:33:44:55:66

禁用访客 WiFi

uv run scripts/unifi.py wlan-disable 5f8b3d2e1a4c7b9e0d6f8a2c

升级设备固件

uv run scripts/unifi.py upgrade 11:22:33:44:55:66

对 PoE 端口进行电源循环（用于重启 PoE 设备）

uv run scripts/unifi.py power-cycle switch_mac 5

创建访客凭证（24 小时，单次使用）

uv run scripts/unifi.py voucher-create --duration=1440 --quota=1 --note=Guest access

生成 WiFi 二维码以便快速连接

uv run scripts/unifi.py wlan-qr wlanid -o guestwifi.png

控制流量规则

uv run scripts/unifi.py traffic-rule-disable rule_id

查找 ID

• - WLAN ID：运行 wlans 并查找 ID 列
• 设备 MAC