尧图网站建设 
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]五个字段的含义与前端标签来自 英文语言包对照如下字段值界面显示含义connectedApConnected APs在线接入点数量activeUserActive devices活跃设备客户端数量alertsAlerts告警数量connectedGatewaysConnected gateways在线网关数量connectedSwitchesConnected 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 APIv5 / v6${url}/${cId}/api/v2/loginv2 API但路径中必须携带控制器实例 IDcId按版本获取站点列表登录成功后携带 token 请求站点列表。v4 请求${url}/api/v2/sitesv5/v6 请求${url}/${cId}/api/v2/sitesv3 则通过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.keyv5/6 使用site.id见 代理源码 中const siteName controllerVersionMajor 4 ? site.id : site.key一行。最终代理统一返回如下 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 foundsite填写的站点名与控制器的站点名不一致在控制器 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），仅供参考 Homepage Omada 组件接入指南：在 Dashboard 中实时监控 UniFi 控制器设备状态
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]五个字段的含义与前端标签来自 英文语言包对照如下字段值界面显示含义connectedApConnected APs在线接入点数量activeUserActive devices活跃设备客户端数量alertsAlerts告警数量connectedGatewaysConnected gateways在线网关数量connectedSwitchesConnected 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 APIv5 / v6${url}/${cId}/api/v2/loginv2 API但路径中必须携带控制器实例 IDcId按版本获取站点列表登录成功后携带 token 请求站点列表。v4 请求${url}/api/v2/sitesv5/v6 请求${url}/${cId}/api/v2/sitesv3 则通过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.keyv5/6 使用site.id见 代理源码 中const siteName controllerVersionMajor 4 ? site.id : site.key一行。最终代理统一返回如下 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 foundsite填写的站点名与控制器的站点名不一致在控制器 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），仅供参考