Homepage Omada 组件接入指南：在 Dashboard 中实时监控 UniFi 控制器设备状态
【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage
本指南介绍如何在 Homepage 中配置 Omada 组件，将 TP-Link Omada SDN 控制器的 AP、活跃客户端、网关、交换机与告警数量实时呈现在应用仪表盘中。读完本文，你将掌握 Omada 组件的完整配置方法、可用的统计字段、其对控制器 3/4/5/6 各版本 API 的差异化适配原理，以及基于源码的故障排查思路。
一、Omada 组件是什么
Homepage 的 Omada 组件是一个典型的“服务状态类”组件，用于轮询 TP-Link Omada SDN 控制器的 API，并展示五个关键运维指标：
- 已连接的 AP（接入点）数量
- 活跃设备（客户端）数量
- 当前告警数量
- 已连接网关数量
- 已连接交换机数量
官方文档 Omada 组件配置说明 明确指出，该组件支持控制器3、4、5 和 6四个大版本。这意味着无论你的 Omada 控制器是仍在服役的老版本（v3/v4），还是最新的 v5/v6 软件控制器（Software Controller）或硬件控制器（如 OC200/OC300），都可以通过同一套配置接入。
二、快速配置
在 Homepage 的服务配置中为 Omada 控制器添加一个 widget 即可。完整的配置示例见下（与官方文档 services 配置说明 中的服务组结构一致）：
widget: type: omada url: http://omada.host.or.ip:port username: username password: password site: sitename各字段含义如下：
| 字段 | 必填 | 说明 |
|---|---|---|
type | 是 | 固定为omada，用于指定组件类型 |
url | 是 | Omada 控制器的地址，格式为http://主机或IP:端口，需包含协议与端口 |
username | 是 | 登录控制器的用户名 |
password | 是 | 登录控制器的密码 |
site | 是 | 要监控的站点名称（Site Name），例如Default（默认站点） |
默认情况下，组件会展示 4 个指标块。如果需要自定义展示哪些指标，可以通过fields字段指定。官方文档允许的字段集合为：
fields: ["connectedAp", "activeUser", "alerts", "connectedGateways", "connectedSwitches"]五个字段的含义与前端标签（来自 英文语言包）对照如下：
| 字段值 | 界面显示 | 含义 |
|---|---|---|
connectedAp | Connected APs | 在线接入点数量 |
activeUser | Active devices | 活跃设备（客户端）数量 |
alerts | Alerts | 告警数量 |
connectedGateways | Connected gateways | 在线网关数量 |
connectedSwitches | Connected switches | 在线交换机数量 |
需要说明的是，在 组件前端实现 中，当用户显式配置了fields时，组件最多只渲染前 4 个字段（widget.fields?.length > 4时会被截断）；若未配置fields，则默认使用["connectedAp", "activeUser", "alerts", "connectedGateways"]这四个字段，即connectedSwitches默认不展示。这一行为也被 组件测试用例 所验证：默认情况下页面只渲染 4 个.service-block，且connectedSwitches对应的文本不会出现。
三、控制器版本差异与底层 API 适配
这是 Omada 组件最有技术含量的一部分。不同大版本的 Omada 控制器暴露的 API 结构差异很大，代理实现 通过以下流程自动适配：
- 探测控制器版本：请求
${url}/api/info获取控制器信息，从响应中解析result.omadacId（控制器实例 ID）与result.controllerVer（版本号）。若响应不是合法 JSON（例如controllerVer解析失败），则按3.2.x兜底处理。 - 校验版本范围：取出版本号的主版本号（如
4.5.6的4），仅当主版本号属于[3, 4, 5, 6]时才继续；否则返回 500 与Error determining controller version错误。 - 按版本选择登录接口：
| 版本 | 登录 URL | 说明 |
|---|---|---|
| v3 | ${url}/api/user/login?ajax | 使用旧版登录接口，请求体额外携带method: "login"与嵌套的params: { name, password } |
| v4 | ${url}/api/v2/login | 新版 v2 API |
| v5 / v6 | ${url}/${cId}/api/v2/login | v2 API，但路径中必须携带控制器实例 IDcId |
- 按版本获取站点列表：登录成功后携带 token 请求站点列表。v4 请求
${url}/api/v2/sites，v5/v6 请求${url}/${cId}/api/v2/sites，v3 则通过web/v1/controller的 RPC 方式调用getUserSites方法。之后在返回的站点数组中按widget.site匹配站点；若找不到，返回Site xxx is not found错误。 - 按版本获取统计数据：这是新旧架构差异最大的环节——
- v3：由于 v3 控制器不支持直接按站点取统计，代理会先调用
switchSite方法把会话切换到目标站点，再调用getGlobalStat获取connectedAp、activeUser、alerts三个指标（v3 下网关与交换机数量无法获取）。 - v4/5/6：直接请求站点的
dashboard/overviewDiagram接口，从响应中读取totalClientNum、connectedApNum、connectedGatewayNum、connectedSwitchNum，再请求alerts/num接口获取alertNum。注意 v4 与 v5/6 在站点标识的选取上也有差异：v4 使用site.key，v5/6 使用site.id（见 代理源码 中const siteName = controllerVersionMajor > 4 ? site.id : site.key一行）。
- v3：由于 v3 控制器不支持直接按站点取统计，代理会先调用
最终，代理统一返回如下 JSON 结构给前端：
{ "connectedAp": 2, "activeUser": 10, "alerts": 4, "connectedGateways": 1, "connectedSwitches": 3 }上述 v4 流程（探测 → 登录 → 取站点 → 取 overviewDiagram → 取告警数，共 5 次 HTTP 请求）被完整地固化在 代理测试用例 中，可作为理解整个调用链的参考。
四、会话管理：55 分钟缓存与自动重登
Omada 控制器的 API 需要 token 与会话 Cookie 双重认证，为避免每次轮询都重新登录，代理实现了会话缓存机制：
- 登录成功后，代理将
result.token与从Set-Cookie响应头中提取的 Cookie（通过getCookieHeader合并，重复 Cookie 名取最后一个值）写入内存缓存，有效期为 55 分钟，缓存键由group、service、index组合而成，保证不同 widget 之间的会话互不串用（见 代理测试用例 中“不跨 widget 复用会话”的测试）。 - 之后的每次数据请求都会带上
Csrf-Token请求头以及 Cookie。 - 自动重登机制：当使用缓存会话请求时返回
401/403或errorCode > 0，代理会立即清除缓存会话并重新登录后重试一次（shouldRetryWithFreshSession逻辑）；若缓存会话对应的响应已不是合法 JSON（如控制器重启后返回了登录页 HTML），同样会清缓存重登。这两条路径均有对应的测试用例覆盖。
五、前端渲染与刷新频率
前端组件（component.jsx）通过useWidgetAPI以5 秒的刷新间隔（refreshInterval: 5000）轮询代理接口：
- 数据未返回时渲染占位符（
-）； - 请求失败时渲染错误 UI（受全局
hideErrors设置控制）； - 数据返回后，各数值经
common.number格式化后展示在五个Block中。
组件本身通过 widgets.js 注册代理处理器、经 components.js 动态懒加载（dynamic(() => import("./omada/component"))），并按 widget.js 中声明的info映射（endpoint: "api/info"）发起请求。
六、常见问题排查
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
返回HTTP Error 503，且提示Unable to retrieve Omada controller info | 控制器地址不可达或/api/info路径不通 | 检查url的协议、端口是否正确，控制器是否在线 |
返回 500Error determining controller version | 控制器主版本不在 3/4/5/6 范围内 | 确认控制器版本；该组件仅支持文档声明的 3、4、5、6 四个大版本 |
返回Error logging in to Omada controller | 用户名或密码错误，或控制器禁用了该账户的 API 登录 | 核对凭据；v3 控制器需确认账号具备站点访问权限 |
返回Site xxx is not found | site填写的站点名与控制器的站点名不一致 | 在控制器 Web 界面确认站点名称（区分大小写），如默认站点为Default |
| 指标长时间不更新且偶发失败 | 控制器端会话过期，缓存会话失效 | 无需干预，代理会自动清缓存并重新登录（见第四节自动重登机制） |
七、相关资源
- 组件官方文档：docs/widgets/services/omada.md
- 代理实现（登录、会话缓存、版本适配核心逻辑）：src/widgets/omada/proxy.js
- 前端渲染组件：src/widgets/omada/component.jsx
- 组件注册与 API 映射：src/widgets/omada/widget.js
- 代理与组件测试（含 v3/v4/v5 各流程与重登场景）：src/widgets/omada/proxy.test.js、src/widgets/omada/component.test.jsx
- 界面文案定义：public/locales/en/common.json
- 全部服务类组件文档索引：docs/widgets/services/index.md
综上，Omada 组件是一个对多版本控制器兼容性处理相当完整的 widget：它通过一次/api/info探测自动分流 v3 与 v4+ 两条 API 路径，以 55 分钟会话缓存 + 自动重登机制保证轮询稳定，并在前端以 5 秒间隔实时刷新五个网络运维关键指标。只需一份 5 行的 YAML 配置，即可把 Omada 控制器的网络状态纳入 Homepage 仪表盘统一视图中。
【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
