UniFi API Browser 部署与控制器数据查询实战指南
在管理 Ubiquiti UniFi 网络设备时，直接调用控制器 API 往往需要处理复杂的 JSON 结构和认证流程。UniFi API Browser 作为一个开源的 PHP Web 应用，为网络工程师和开发者提供了一个轻量级的可视化面板，用于直接查询和渲染 UniFi Controller 暴露的底层数据。
核心架构与特性
- 多维度数据渲染：将原始的 API JSON 响应转换为结构化的 HTML 表格，涵盖客户端状态、AP 射频指标、交换机端口统计等。
- 多租户会话管理：原生支持多站点（Site）上下文切换，允许在单一面板中管理分布在不同物理位置的 UniFi 站点。
- 可扩展的数据集合：通过模块化的集合定义（Collections），开发者可以快速添加自定义的 API 端点查询逻辑。
环境部署与凭证配置
该工具基于 PHP 构建，建议部署在支持 PHP 7.4+ 及 cURL 扩展的 Web 服务器（如 Nginx 或 Apache）上。
1. 获取源码
通过版本控制系统拉取项目代码，并安装必要的依赖：
# 克隆项目仓库
git clone https://github.com/malle-pietje/UniFi-API-browser.git unifi-browser
cd unifi-browser
# 如果使用 Composer 管理依赖，可执行安装
composer install --no-dev2. 控制器凭证注入
系统通过独立的配置文件管理 UniFi 控制器的连接凭证。我们需要在 config/ 目录下创建身份验证文件，而不是直接修改核心代码。
创建 config/users.php，定义控制器集群的访问凭据：
<?php
// config/users.php
// 定义 UniFi 控制器节点及其认证参数
$controller_nodes = [
'main-office' => [
'host' => '192.168.1.100',
'port' => 8443,
'user' => 'api_readonly_user',
'password' => 'SecureP@ssw0rd!',
'version' => '7.2.92', // 控制器版本号
'site_id' => 'default'
],
'branch-site' => [
'host' => 'unifi.branch.example.com',
'port' => 443,
'user' => 'admin',
'password' => 'BranchSecret123',
'version' => '7.1.68',
'site_id' => 'branch_01'
]
];
// 安全设置：防止未授权访问面板
$require_login = true;
$admin_password_hash = password_hash('WebUI_Password', PASSWORD_BCRYPT);
3. 自定义数据集合 (Collections)
若需查询官方预置集合之外的数据，可通过扩展集合配置文件来注册新的 API 路由。以下示例展示了如何添加一个获取特定网关深度检测数据的自定义集合：
<?php
// config/collections-custom.php
$custom_api_collections = [
'gateway_dpi_stats' => [
'name' => 'Gateway DPI Statistics',
'description' => '获取 UXG/UDM 设备的深度包检测应用统计',
'api_path' => '/stat/dpi',
'method' => 'GET',
'requires_id' => false,
'parser' => function($raw_data) {
// 自定义数据清洗逻辑，仅保留流量大于 1MB 的应用
return array_filter($raw_data, fn($app) => $app['rx_bytes'] > 1048576);
}
]
];
项目目录与路由解析
- ajax/：处理前端异步数据拉取。例如
fetch_sites.php负责在用户切换下拉菜单时，动态请求并缓存当前控制器的站点列表。 - templates/：基于 Twig 模板引擎的视图层。
layout/main.html.twig定义了全局导航栏和站点切换组件的 DOM 结构。 - src/：核心业务逻辑层，封装了与 UniFi Controller 的 cURL 会话保持、CSRF 令牌处理及 Cookie 管理。
会话控制与调试建议
在进行 API 调试时，建议开启 PHP 的错误日志记录。工具内置了会话控制路由：
- 访问
login.php触发身份验证流程，系统会校验users.php中定义的哈希密码，并建立与后端控制器的 cURL Cookie 会话。 - 通过
logout.php销毁本地 PHP Session，并向 UniFi 控制器发送注销请求以释放 API 连接池资源。 - 在排查"数据为空"的问题时，优先检查配置文件中的控制器版本号是否与实际运行的 UniFi Network Application 版本严格匹配，版本不匹配会导致 API 端点路径解析失败。
