Mosquitto Dashboard 本地开发与运行指南：基于 HTTP API 的 Web 监控界面实战

Mosquitto Dashboard 本地开发与运行指南基于 HTTP API 的 Web 监控界面实战【免费下载链接】mosquittoEclipse Mosquitto - An open source MQTT broker项目地址: https://gitcode.com/gh_mirrors/mos/mosquittoMosquitto Dashboard 是 Eclipse Mosquitto 仓库中附带的一套纯前端 Web 图形界面它不直接订阅 MQTT 主题而是通过调用 broker 的 HTTP API/api/v1/systree与/api/v1/listeners来渲染实时监控面板包括消息收发速率、客户端连接数、监听器状态等。本文基于 dashboard/README.md 的完整说明结合仓库内前端源码与 src/http_api.c 的 broker 端实现逐步骤讲解如何在本地把该控制台跑起来、如何接入真实 broker并深入剖析其数据采集、图表渲染与页面交互的底层原理。一、Dashboard 是什么dashboard/目录下的代码是一套「简单且基于 Web 的 Mosquitto 图形用户界面」README 原文如此描述它的目标不是替代mosquitto_sub/mosquitto_pub这类命令行工具而是提供一块可视化的监控看板用于观察 broker 的运行状态。与常见的通过 WebSocket 桥接 MQTT方案不同本 Dashboard 的数据来源是Mosquitto 内置的 HTTP API。从 dashboard/src/app/consts.js 可以看到两个核心端点定义const SYSTOPIC_ENDPOINT /api/v1/systree; const LISTENERS_ENDPOINT /api/v1/listeners;而这两个端点在 broker 端的实现位于 src/http_api.c 的http_api__process_api()中/api/v1/systree返回全部$SYS系统主题的当前值/api/v1/listeners返回各监听器配置。因此运行 Dashboard 的前提是 broker 启动了protocol http_api类型的监听器。二、本地开发环境准备README 给出的依赖非常简单——Dashboard 是纯静态前端不依赖 Node.js 构建链仅需要 Tailwind CSS 与一个静态文件服务器。具体依赖如下存放于dashboard/src/lib目录仓库已随附依赖版本用途chartjs4.3.0折线图/面积图渲染chartjs-plugin-zoom2.2.0图表的缩放滚轮/双指与平移hammer.js2.0.8触屏手势支持为 zoom 插件提供 pinch 手势对应文件为 dashboard/src/lib/chart.umd.js、dashboard/src/lib/chartjs-plugin-zoom.min.js 与 dashboard/src/lib/hammer.min.js无需自行下载。另外还需要全局安装 Tailwind CSS 3用于把index.html中的 Tailwind 类编译为 CSSnpm -g install tailwindcss3三、五步跑通本地开发环境README 给出了完整的本地开发步骤下面按原文档顺序展开并补充每一步的细节与原理。第 1 步生成 Tailwind CSS进入dashboard/src目录执行cd dashboard/src tailwindcss -i ./css/styles.css -o ./tailwind/styles.css该命令以 dashboard/src/css/styles.css 为输入Tailwind 指令入口扫描 dashboard/src/tailwind.config.js 中content声明的./*.html与./*.js把实际用到的工具类生成到 dashboard/src/tailwind/styles.css。也就是说每次修改了 HTML/JS 中的 Tailwind 类名后都需要重新执行这条命令否则新类不会出现在最终样式文件中。如果后续新增了 Tailwind 工具类而页面样式未生效先检查这一步是否已重新执行。第 2 步准备 HTTP API 数据源README 第 3 步是「运行 mosquitto http api mock」——即先不连真实 broker用 mock 数据验证前端。这一步有两种做法方式 A推荐最贴近真实直接启动一个开启了 HTTP API 的 Mosquitto broker见下文「接入真实 broker」一节mosquitto自身就是最可信的 API 服务方式 B仅前端调试自行实现一个简单的 mock 服务返回systree与listeners两个 JSON 接口。第 3 步修改 API 端点地址README 第 4 步要求修改 dashboard/src/app/consts.js 中的 Mosquitto API 端点。默认值如下const SYSTOPIC_ENDPOINT /api/v1/systree; const LISTENERS_ENDPOINT /api/v1/listeners;由于consts.js中的端点默认是相对路径当前端由python3 -m http.server在3000端口提供服务、而 broker API 在另一个端口如8080时需要把这里改为绝对地址例如const SYSTOPIC_ENDPOINT http://localhost:8080/api/v1/systree; const LISTENERS_ENDPOINT http://localhost:8080/api/v1/listeners;注意跨端口访问会触发浏览器同源策略CORS。从 src/http_api.c 的实现看HTTP API 端点默认不携带 CORS 响应头因此最稳妥的做法是让静态页面与 API 同源见第 5 步的替代方案或者由 mock 服务自行附带Access-Control-Allow-Origin头。第 4 步启动静态文件服务器进入dashboard/src运行任意静态服务器README 给出的示例是 Pythoncd dashboard/src python3 -m http.server 3000随后浏览器访问http://localhost:3000即可看到index.html总览看板访问http://localhost:3000/listeners.html查看监听器页。页面初始化逻辑集中在 dashboard/src/app/index.jsdocument.addEventListener(DOMContentLoaded, () { new Sidebar(); new MosquittoDashboard(); });第 5 步替代方案让 Mosquitto 直接托管前端其实 Dashboard 与 broker 同源有更优雅的路径Mosquitto 的http_api监听器支持http_dir配置项可以直接把静态文件目录交给 broker 托管。此时访问 broker 的 HTTP 端口就能同时拿到页面与/api/v1/*数据彻底规避 CORS 与手动改consts.js的问题部署形态见下文第五节。四、前端源码结构导读整个dashboard/src的目录组织如下与 README 描述的src/lib依赖目录对应路径职责dashboard/src/index.html总览看板页面图表、指标卡、bannerdashboard/src/listeners.html监听器列表页面dashboard/src/app/index.js页面入口初始化 Sidebar 与 Dashboard、网格/单列布局切换、banner 探测dashboard/src/app/dashboard.js核心数据拉取、$SYS主题→DOM/图表的映射、Chart.js 图表管理dashboard/src/app/listeners.js监听器信息展示与连接命令生成dashboard/src/app/consts.js常量API 端点、轮询/保留窗口等时间参数dashboard/src/app/sidebar.js侧边导航dashboard/src/utils/utils.jsfetchData、时间格式化、数字美化等工具函数dashboard/src/utils/queue.js串行任务队列防止图表更新互相竞争dashboard/src/utils/assert.js断言工具dashboard/src/css/styles.cssTailwind 输入样式dashboard/src/tailwind/styles.cssTailwind 编译产物dashboard/src/lib/*.js第三方库chartjs / zoom / hammer五、接入真实 broker配置 HTTP API 监听器要让 Dashboard 显示真实数据需要启动一个启用 HTTP API 的 Mosquitto。相关配置项在仓库根目录的 mosquitto.conf 中有完整注释核心为listener与protocol http_api# listener 端口 可选: ip 地址/主机名/unix socket 路径 listener 8080 127.0.0.1 # 该监听器协议: mqtt / websockets / http_api protocol http_api # 指定由该监听器托管的静态文件目录可选 http_dir /path/to/dashboard/src关于protocol http_apimosquitto.conf 的注释明确指出它将监听器启动为一个非常简单的 Web 服务器可处理部分 HTTP API 请求该监听器支持 TLS但当前无法进行认证因此强烈建议只绑定到 loopback 地址如127.0.0.1。完成配置后启动mosquitto -c /path/to/mosquitto.conf验证 API 是否就绪curl http://127.0.0.1:8080/api/v1/systree curl http://127.0.0.1:8080/api/v1/listeners curl http://127.0.0.1:8080/api/v1/version若配置了http_dir指向dashboard/src则直接访问http://127.0.0.1:8080/与http://127.0.0.1:8080/listeners.html即可看到完整界面且无需修改consts.js。从 src/http_api.c 的实现可见若http_dir未显式配置代码还会尝试回退到编译期宏HTTP_API_DIR指定的目录。broker 端 API 的响应内容/api/v1/systree的实现src/http_api.c会遍历内部指标表metrics[]把每个$SYS主题的当前值以{$SYS/broker/clients/total: 5, ...}的形式序列化为 JSON并额外附上$SYS/broker/uptime。注意该端点依赖编译开关WITH_SYS_TREE未开启时会返回 404。/api/v1/listeners的实现src/http_api.c 附近会遍历db.config-listeners为每个监听器输出端口或 Unix socket 路径、协议、TLS、mTLS、allow_anonymous等字段protocol为httpapi的监听器也会被标记出来。六、看板的数据流与刷新机制理解了 API 端点后再看前端如何消费这些数据。dashboard/src/app/dashboard.js 中的checkForDataUpdates()是核心轮询函数调用fetchData(SYSTOPIC_ENDPOINT, { cache: no-store })拉取最新$SYS快照dashboard/src/utils/utils.js 中的fetchData会强制附带Accept: application/json头从中提取$SYS/broker/version更新 broker 版本号并根据请求成败把「broker-status」置为 Online/Offline调用getElementsToUpdate(sysTopics)只更新发生变化的指标与图表——该方法内部维护了一份lastSysTopics快照逐个$SYS主题比对前后值有变化才写入待更新集合调用updateCharts(...)推进所有图表的 data/labels并将最新数据写入sessionStorage。轮询节奏由 dashboard/src/app/consts.js 控制const INTERVAL_5SECS_IN_MILLISECONDS 1000 * 5; // 每 5 秒拉取一次 const KEEP_DATAPOINTS_FOR_INTERVAL 1000 * 60 * 60 * 2; // 原始数据最多保留 2 小时 const MAX_POINTS_IN_CHART 5_000; // 单图表最多 5000 个点 const CHART_UPDATE_INTERVAL_IN_MILLISECONDS 1000 * 60; // 强制刷新周期 1 分钟startDataUpdates()dashboard/src/app/dashboard.js的实现细节值得注意首次拉取后它会计算「下一个能被 5 秒整除的时间点」并据此安排setTimeout从而让各浏览器标签页的数据点尽量对齐每次拉取完成后会用「5 秒减去本次请求耗时」作为下次超时时间再叠加 Chart.js 动画时长CHARTJS_ANIMATION_DURATION_MS 400的缓冲并通过 dashboard/src/utils/queue.js 的串行队列执行避免图表更新与动画进入竞争状态。$SYS主题与界面元素的映射getElementsToUpdate()中维护了一张详尽的「主题 → 界面」映射表例如$SYS主题对应界面元素$SYS/broker/uptimebroker-uptime格式化为「X days X hours …」$SYS/broker/clients/connectedclients-connected chart-clients-connected$SYS/broker/clients/disconnectedclients-disconnected chart-clients-disconnected$SYS/broker/messages/sent/received独立图 chart-message-overview双线对比图$SYS/broker/load/messages/sent/1min/received/1min速率图 chart-message-rate-overview对比图$SYS/broker/publish/messages/droppedchart-messages-dropped$SYS/broker/heap/current/maximum堆内存展示$SYS/broker/subscriptions/count订阅总数其中发送/接收速率图使用$SYS/broker/load/messages/{sent,received}/1min这类「每分钟消息数」指标映射关系定义在updateMatchingChart()中dashboard/src/app/dashboard.js它还会把「发送」与「接收」两幅图配对联动更新保证对比图两条曲线时间轴一致。原始数据与平滑数据看板右上角提供了「Show Raw Data / Show Smoothed Data」切换addToggle()。每个图表同时维护两套数据raw原始每次拉取到的真实数值直接追加smoothed平滑只有满足一定条件才插入新点——当值的变化幅度超过 20%datapointsAreSufficientlyDifferent或与前一个点的时间间隔超过 5 分钟SMOOTHED_CHART_UPDATE_INTERVAL_IN_MILLISECONDS时。这种「事件驱动 定时兜底」的策略见addSmoothedDataPoint()让平滑图既能过滤抖动、又不会长时间静止显示陈旧数据。图表本身基于 Chart.js 折线图启用了chartjs-plugin-zoom的滚轮/双指缩放与平移且每个图表都有独立的缩放/平移/重置按钮handleChartAction()中的chart.zoom(1.2)、chart.pan({x:100})、chart.resetZoom()等。会话级持久化Dashboard 把图表数据、最新$SYS快照、布局偏好网格/单列与「原始/平滑」选项全部写入sessionStorageupdateStore()dashboard/src/app/dashboard.js。刷新页面时composeDashboardObject()会优先从sessionStorage恢复历史曲线而不是从空白开始——因此浏览器标签页关闭前图表数据不会丢失但关闭标签页后sessionStorage即被清空重新打开将重新开始累积曲线。此外index.js会把「单列视图」偏好存入sessionStorage下次访问时自动恢复。七、监听器页面listeners.html功能解读listeners.html由 dashboard/src/app/listeners.js 驱动页面加载时请求LISTENERS_ENDPOINT为每个监听器生成一张卡片展示端口或 Unix socket 路径、协议、是否启用 TLS/mTLS、是否允许匿名连接等字段。两个值得注意的能力匿名监听器告警displayListeners()会统计allow_anonymous为真的监听器数量若大于 0则会在顶部显示带「UNSAFE」红色徽标的计数提示当前存在未认证开放的端口一键复制连接命令generateConnectionCommand(listener, mosquitto_pub)会根据监听器的协议MQTT / WebSockets / Unix socket、TLS/mTLS、匿名与否动态拼出可直接使用的mosquitto_pub命令模板例如# TLS 需认证的 WebSocket 监听器会生成类似 mosquitto_pub -h host -p 9001 --ws --cafile ca-crt.pem \ --cert client-crt.pem --key client-key.pem \ -u username -P password -t topic -m message卡片上的复制按钮把命令写入剪贴板copyToClipboard()优先使用navigator.clipboard并降级到document.execCommand(copy)方便直接粘贴到终端测试连通性。若监听器协议为httpapi则不生成 pub 命令而是提示「使用 REST 调用代替 mosquitto_pub/sub」。八、常见问题与注意事项结合 README 步骤与源码实现本地开发时容易踩的坑集中在以下几点Tailwind 类不生效修改了 HTML/JS 后未重新执行tailwindcss -i ./css/styles.css -o ./tailwind/styles.css数据不显示/接口 404确认 broker 编译时启用了WITH_SYS_TREE/api/v1/systree依赖它且监听器配置了protocol http_api跨域被拦前端由独立端口服务时访问http://localhost:8080/api/...会触发 CORS最省事的解法是用http_dir让 broker 同时托管页面与 API实现同源访问刷新后曲线消失这是sessionStorage的预期行为——数据只在当前标签页会话内保留默认保留最近 2 小时、最多 5000 个点Firefox 下快速切换页面可能短暂弹错registerAbortController()dashboard/src/utils/utils.js的源码注释明确提到Firefox 在导航前不会可靠执行 abort 回调可能导致请求已取消但仍弹出一次错误提示属已知浏览器行为不影响功能。九、小结本文完整复现并扩展了 dashboard/README.md 的本地开发流程从安装 Tailwind、生成 CSS、修改 dashboard/src/app/consts.js 中的 API 端点到启动静态服务器或直接由protocol http_api监听器配合http_dir托管前端。在此基础上结合 dashboard/src/app/dashboard.js、dashboard/src/app/listeners.js 与 src/http_api.c 的源码梳理了$SYS指标到图表的映射、5 秒轮询与平滑采样策略、sessionStorage持久化以及监听器页面的命令生成与匿名告警机制。按照上述步骤你可以在几分钟内把 Mosquitto 的实时运行状态变成一组可视化图表并将其作为本地监控或演示环境的一部分。【免费下载链接】mosquittoEclipse Mosquitto - An open source MQTT broker项目地址: https://gitcode.com/gh_mirrors/mos/mosquitto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考