ez-unifi

ez-unifi

由 aiounifi 库驱动、适合 Agent 使用的 UniFi Network 工具。支持 UDM Pro/SE、Dream Machine、Cloud Key Gen2+ 和可自托管的控制器。

使用以下命令运行所有命令： uv run scripts/unifi.py <command> [args]

设置

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

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

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

UNIFI_HOST=https://192.168.1.1
UNIFI_USERNAME=agent-api
UNIFI_PASSWORD=the_password
UNIFI_SITE=default
UNIFI_IS_UDM=true

为 Cloud Key Gen1 或可自托管的控制器设置 UNIFI_IS_UDM=false。

---

系统和站点

unifi.py sites                     # List all sites
unifi.py sysinfo                   # System information
unifi.py health                    # Site health status (WAN, WLAN, LAN)

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

unifi.py devices                   # List all devices
unifi.py device MAC                # Device details
unifi.py restart MAC               # Restart device
unifi.py restart MAC --hard        # Hard restart (cycles PoE on switches)
unifi.py upgrade MAC               # Upgrade device firmware
unifi.py locate MAC                # Blink LED to locate
unifi.py unlocate MAC              # Stop LED blinking
unifi.py led MAC on|off|default    # Set LED status
unifi.py led MAC on --color=#FF0000 --brightness=50  # With color/brightness

交换机端口

unifi.py ports                     # List all switch ports
unifi.py port MAC PORT_IDX         # Port details
unifi.py port-enable MAC PORT_IDX  # Enable switch port
unifi.py port-disable MAC PORT_IDX # Disable switch port
unifi.py poe MAC PORT_IDX MODE     # Set PoE mode (auto|off|passthrough|24v)
unifi.py power-cycle MAC PORT_IDX  # Power cycle a PoE port

智能电源（PDU/插座）

unifi.py outlets                   # List all outlets
unifi.py outlet MAC IDX on|off     # Control outlet relay
unifi.py outlet-cycle MAC IDX on|off  # Enable/disable auto-cycle on internet down

客户端

unifi.py clients                   # List active clients
unifi.py clients-all               # List all clients (including offline/known)
unifi.py client MAC                # Client details
unifi.py block MAC                 # Block client from network
unifi.py unblock MAC               # Unblock client
unifi.py reconnect MAC             # Kick/reconnect client
unifi.py forget MAC [MAC2...]      # Forget client(s) permanently

WiFi 网络

unifi.py wlans                     # List wireless networks
unifi.py wlan ID                   # WLAN details
unifi.py wlan-enable ID            # Enable WLAN
unifi.py wlan-disable ID           # Disable WLAN
unifi.py wlan-password ID NEWPASS  # Change WLAN password
unifi.py wlan-qr ID                # Generate WiFi QR code (PNG file)
unifi.py wlan-qr ID -o myqr.png    # Custom output filename

端口转发

unifi.py port-forwards             # List port forwarding rules
unifi.py port-forward ID           # Port forward details

流量规则

unifi.py traffic-rules             # List traffic rules
unifi.py traffic-rule ID           # Traffic rule details
unifi.py traffic-rule-enable ID    # Enable traffic rule
unifi.py traffic-rule-disable ID   # Disable traffic rule
unifi.py traffic-rule-toggle ID on|off  # Toggle traffic rule state

流量路由

unifi.py traffic-routes            # List traffic routes
unifi.py traffic-route ID          # Traffic route details
unifi.py traffic-route-enable ID   # Enable traffic route
unifi.py traffic-route-disable ID  # Disable traffic route

防火墙

unifi.py firewall-policies         # List firewall policies
unifi.py firewall-policy ID        # Firewall policy details
unifi.py firewall-zones            # List firewall zones
unifi.py firewall-zone ID          # Firewall zone details

DPI（深度数据包检测）

unifi.py dpi-apps                  # List DPI restriction apps
unifi.py dpi-app ID                # DPI app details
unifi.py dpi-app-enable ID         # Enable DPI app restriction
unifi.py dpi-app-disable ID        # Disable DPI app restriction
unifi.py dpi-groups                # List DPI restriction groups
unifi.py dpi-group ID              # DPI group details

热点凭证

unifi.py vouchers                  # List 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         # Delete voucher

凭证选项：

• --duration - 时长（分钟，默认值：60）
• --quota - 使用次数（默认值：1）
• --usage-quota - 使用配额（MB）
• --rate-up - 上传速率限制（Kbps）
• --rate-down - 下载速率限制（Kbps）
• --note - 备注/说明

事件

unifi.py events                    # Stream events in real-time (Ctrl+C to stop)

原始 API 访问

unifi.py raw GET /stat/health      # Raw GET request
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 格式输出：

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

---

示例

# Check network health
uv run scripts/unifi.py health

# List all connected clients
uv run scripts/unifi.py clients

# Block a device
uv run scripts/unifi.py block "aa:bb:cc:dd:ee:ff"

# Restart an access point
uv run scripts/unifi.py restart "11:22:33:44:55:66"

# Disable guest WiFi
uv run scripts/unifi.py wlan-disable "5f8b3d2e1a4c7b9e0d6f8a2c"

# Upgrade device firmware
uv run scripts/unifi.py upgrade "11:22:33:44:55:66"

# Power cycle a PoE port (useful for rebooting PoE devices)
uv run scripts/unifi.py power-cycle "switch_mac" 5

# Create a guest voucher (24 hours, single use)
uv run scripts/unifi.py voucher-create --duration=1440 --quota=1 --note="Guest access"

# Generate WiFi QR code for easy connection
uv run scripts/unifi.py wlan-qr "wlan_id" -o guest_wifi.png

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

查找 ID

• WLAN ID：运行 wlans 并查看 ID 列
• 设备 MAC 地址：运行 devices 并查看 MAC 列
• 客户端 MAC 地址：运行 clients 或 clients-all 并查看 MAC 列
• 流量规则 ID：运行 traffic-rules 并查看 ID 列
• 凭证 ID：运行 vouchers 并查看 ID 列

注意事项

• MAC 地址可以采用任何格式（使用冒号、连字符或不使用分隔符）
• 所有输出均为 JSON 格式，便于解析
• 使用专用的本地账户可避免云关联账户的 MFA 问题
• 如果遇到速率限制（429 错误），请等待几分钟后再重试