SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场unifi-network-config-tools

unifi-network-config-tools

部署与运维

查看项目

更新于 11-02 01:23

技能介绍

用途

该工具集用于在本地 UniFi 网关上进行网络配置的读取与修改，覆盖网络、WiFi、WAN、DHCP、DNS、QoS、端口配置、交换和 VPN 等主题。多数工具使用旧版 Network API，少数使用集成 API。修改已有工具前应先阅读说明；新增工具的一般流程参见 unifi-mcp-tool-builder。

主要能力（模块划分）

  • src/tools/networks.py（4 个）：get_network_details、list_vlans、get_subnet_info 等。
  • src/tools/network_config.py（3 个）：create_network、update_network、delete_network。
  • src/tools/wifi.py（5 个）：list_wlans、update_wlan、get_wlan_statistics 等。
  • src/tools/wans.py（6 个）：list_wan_connections、create_dynamic_dns 等。
  • src/tools/dhcp_reservations.py（5 个）：create_dhcp_reservation、remove_dhcp_reservation 等。
  • src/tools/dns_management.py（4 个）：list_wan_dns、update_dns_filter 等。
  • src/tools/qos.py（3 个）：list_traffic_routes、configure_smart_queue 等。
  • src/tools/port_profiles.py（8 个）：update_port_profile、set_device_port_overrides 等。
  • src/tools/switching.py（6 个）：list_switch_stacks、get_lag_details（只读）。
  • src/tools/vpn.py（2 个）：list_vpn_tunnels、list_vpn_servers。
  • src/tools/site_vpn.py（3 个）：get_site_to_site_vpn、update_site_to_site_vpn。

注册与运行模式

每个公开的 async def 都会注册为工具（src/tool_registry.py 中的 register_module_tools()）；port_profiles.get_device_by_mac 为公开函数，因此也是工具。辅助函数以 _ 开头命名。11 个模块均列于 src/main.py 的 _LOCAL_TOOL_MODULES，云模式下均不存在。DHCP、DNS、动态 DNS 和流量路由在运行时还会通过 _ensure_local_api() 拒绝非本地模式。

UNIFI_PROFILE 在 src/main.py 中定义的分组为：network（dhcp、dns、network_config、networks、wans、wifi）、devices（port_profiles、switching）、security（site_vpn、vpn）、system（qos）。新增模块需加入对应集合。代码不检查 Network 版本；若功能需要 Network 9.0+，应在工具 docstring 中说明。

URL 路径构建

  • Legacy：写 /ea/sites/{site_id}/<resource>，本地模式下 UniFiClient 会改写为 /proxy/network/api/s/{site_name}/<resource>；site_id 可以是 UUID 或名称，客户端会把 UUID 映射为站点名。
  • v2：settings.get_v2_api_path(site_id)。
  • Integration：settings.get_integration_path(f"sites/{site_id}/...")，客户端把站点名映射为 UUID，client.resolve_site_id() 返回 UUID。

在用旧版资源包括 rest/networkconf、rest/wlanconf、rest/portconf、rest/user、rest/dynamicdns、get/setting/ips；客户端还会将 devices 改写为 stat/device、sta 改写为 stat/sta。不要硬编码 /proxy/network/api/s/...，客户端会原样透传，导致站点 UUID 不会被转换为站点名。

模型

模型位于 src/models/ 下的 network.py、wan.py、vpn.py、port_profile.py、switching.py、qos_profile.py。旧版记录使用 id 并设 alias="_id"、populate_by_name=True；集成模型使用 camelCase 别名。仅 WANConnection 和 TrafficRoute 设置 extra="allow"，其余丢弃未知键。旧版 API 中 VLAN 字段名为 vlan；Network 模型将 vlan_id 别名到 vlan，但 network_config 返回原始控制器记录，其中为 vlan，两个模块返回结构不同。

写操作规范

写工具签名包含 confirm: bool | str = False 与 dry_run: bool | str = False；test_every_mutating_tool_declares_dry_run 要求所有写工具声明 dry_run。工具应先调用 validate_confirmation(confirm, "<operation>", dry_run)，并在创建客户端前返回 dry run 结果。不应自行添加审计代码，注册表包装器会审计所有变更调用。

读-改-写工具（先 GET 完整记录、合并修改、再整体 PUT）包括：update_network、update_wlan、update_port_profile、set_device_port_overrides（PUT 整个设备）、update_site_to_site_vpn。规则：可选更新参数默认值必须为 None（如默认 False 会在每次更新时覆盖已存值）；从列表响应取记录应使用 first_response_item()（src/utils/helpers.py），不能用 [0]；控制器会自行改写部分字段，port_profiles 会重读记录并报告差异（_stored_value_warnings），新增读-改-写工具应同样处理；set_device_port_overrides(merge=False) 会替换全部 override，update_dns_filter 中的 dns_filters 列表会整体替换，替换列表的参数应在 docstring 中注明。

部分更新：update_wan_dns 和 configure_smart_queue 仅向 rest/networkconf 发送变更字段；DHCP 仅向 rest/user 发送部分字段。

响应、错误与缓存

UniFiClient 对有 data 键的响应返回 {"data": ...}，空响应体返回 {}，需处理列表或字典。404 抛 ResourceNotFoundError，401/403 抛 AuthenticationError，其他错误抛 APIError。

Redis 读缓存仅覆盖 networks 和 wifi 模块（src/cache.py 的 CACHED_MODULES）；名称含 "statistics" 的工具永不缓存。非 dry run 的写操作会清除该控制器的所有缓存读取，写工具无需自行处理缓存。

src/tools/wifi.py 通过 _redact_wlan() 处理 WLAN 输出；任何返回 WLAN 记录的工具都应保留该处理，因为记录中含口令。

测试

测试文件位于 tests/unit/tools/test_<module>_tools.py；switching 测试在 tests/unit/test_switching.py；示例可参考 tests/unit/tools/test_network_config_tools.py。应 patch 模块内的客户端名称，如 patch.object(nc_module, "UniFiClient", ...)；使用 MagicMock 客户端配 AsyncMock 方法，并让 aexit 返回 False，否则工具内异常会被吞掉。断言请求体用 client.put.call_args[1]["json_data"]。若工具检查 API 模式，需在 settings fixture 上设置 settings.api_type = APIType.LOCAL。

固件注意事项

  • 仅 mock 的测试曾对不存在的端点（rest/qosprofile、rest/wanconf）通过。新增端点前应在 docs/UNIFI_API.md 或 scripts/ 中的规范快照里确认，并说明是否已在硬件上验证。
  • Smart Queue 速率以 kbps 存储，UI 显示为 Mbps。
  • 固件 10.2.x 上 DNS-over-TLS 没有对应 REST 字段。
  • 对控制器已知的 MAC 执行 POST 会返回 api.err.MacUsed，因此 DHCP 会先查找客户端；只设置 fixed_ip 而不设 use_fixedip 不会生效。
  • 网络创建后 purpose 不可更改。
  • 集成 API 的 WAN 列表只返回 id 和 name。

已知缺陷（未修复）

  • src/tools/site_vpn.py 发送 /ea/sites/{site_id}/rest/networkconf，客户端会转换为带站点名的旧版路径，因此站点 UUID 与站点名均可用。
  • 各模块确认检查不一致：site_vpn 返回 {"error": ...}，而其他模块抛异常；DHCP 和 DNS 抛 ValueError，其他模块抛 ValidationError。
  • 各模块 dry-run 响应不同：network_config 为 {"dry_run": True, "would_create": ...}，dhcp_reservations 为 {"status": "dry_run", ...}。
  • qos.py 通过 client._site_uuid_to_name 手工映射站点 UUID 到名称，而客户端对 v2 路径本已执行该映射。