简介一套基于MQTT协议的智慧路灯管理系统完整项目面向物联网、自动化、电子信息等相关专业学生与开发者适用于毕业设计、课程设计或项目演示。系统通过MQTT.fx模拟采集端数据经MQTT协议传输至服务器并最终展示于前端Web页面。资源共102个文件压缩包大小约14.24MB主要包含jar依赖库、xml配置、java源码、class编译文件、properties配置以及js/css/html/jsp等前端资源覆盖后端逻辑与前端界面。目前已有71人浏览/学习。项目代码测试运行成功并获导师认可答辩评审分95分核心代码涵盖MQTT连接控制、消息回调处理与数据实体定义等模块配套详细文档与全部资料便于直接复用或二次开发是一份可落地的课设/毕设参考方案。1. 智慧路灯项目里MQTT才是那个把设备、云端和网页串起来的“语义总线”一个路灯管理系统硬件侧无非是灯控器、光敏传感器和继电器真正让项目变得复杂的是如何让PC端的Web页面实时感知每一盏灯的状态并把开关指令可靠地下发到对应设备。这里卡住大多数人的不是Vue或Spring Boot的语法而是“数据从哪来、以什么格式来、来了之后怎么知道是哪个灯的消息”。基于MQTT协议的物联网云平台方案之所以成为主流核心原因不是MQTT协议本身有多新而是它天然把“设备上报”和“服务端订阅”解耦成一对发布/订阅关系在无真实硬件的情况下用MQTT.fx模拟采集端就能把整条链路完整跑通。这套系统的价值在于用一套所有人都能看懂的Topic命名规范把灯杆编号、回路编号和业务属性编码进主题里让Web端拿到消息时不需要查数据库就能定位设备。适合正在做物联网课程设计、毕业设计或企业Demo验证的开发者也适合想弄清楚数据到底“怎么从模拟器流到浏览器”的前端工程师。2. MQTT协议核心机制——从路灯场景看QoS等级、Topic通配与遗嘱消息2.1 为什么路灯控制必须用Topic层级来组织而不是按设备ID平铺在MQTT协议中Topic是消息的路由地址它的设计直接决定了服务端和Web端能不能按需订阅。对于智慧路灯最常见的错误做法是把Topic设置成扁平结构例如streetlight/001、streetlight/002这种写法在路灯数量少时没问题但一旦涉及“按回路查询”“按区域批量下发”就非常难处理。正确的做法是设计一套三级层级{分区}/{回路}/{灯位}/{属性}比如dist-01/circuit-03/lamp-07/state。这样Web端只需要订阅dist-01///state即可收齐该分区的全部状态而不需要一个个订阅单独的主题。从MQTT协议机制上看Topic层级之间的分隔符是/通配符有两种匹配单层#匹配多层。在路灯场景中用来过滤“任意回路、任意灯位”#用来接收“某回路下所有属性的全部消息”。这套设计是MQTT协议中最基础却最容易被忽略的部分它直接决定了服务端接收消息后需要做多少解析工作。2.2 QoS等级选择开关指令用1遥测数据用0固件升级用2MQTT协议定义了三个服务质量等级QoS 0至多发送一次、QoS 1保证到达但可能重复、QoS 2保证只到达一次。在实际路灯系统中这三者各有对应场景。路灯的开关/调光指令必须用QoS 1因为它不能被丢失而偶发的重复执行是可以接受的灯杆上的电流、电压、功率等遥测数据用QoS 0即可因为这类数据每秒都在产生丢一帧没有影响真正需要QoS 2的场景极少除非是配置文件的远程更新但这种操作通常走HTTPS回传而不是MQTT协议。消息类型建议QoS理由灯控开关指令下行1不能丢重复影响小状态上报上行0频率高丢帧可容忍告警事件上行1必须到达允许重复固件或配置更新2不能丢也不能重复这里有一个容易踩的坑如果把QoS 1的消息在同一个连接中高频发送超过每秒几十条Broker的会话队列会堆积重复消息导致服务端处理逻辑要用消息ID做去重。路灯项目的下行指令频率一般很低选QoS 1安全但如果某天你要做“全城路灯批量开关”建议在服务端做一个简单的消息去重表按clientId messageId去重。2.3 遗嘱消息与保留消息路灯掉线和新网页上线时数据怎么补MQTT协议里有两个容易被Web开发者忽略的特性一个是遗嘱消息LWT一个是保留消息Retained。路灯终端或MQTT.fx模拟终端在建立连接时可以指定一个遗嘱Topic和遗嘱Payload。如果终端非正常断开Broker会代替它发布这条遗嘱消息。我通常会在路灯场景中把遗嘱内容约定为{state:offline,timestamp:...}发布到{路灯主题}/status上。这样服务端不用做心跳超时检测就能在几秒内感知到设备掉线。保留消息的作用则是解决“新页面打开时没有任何状态数据”的问题。MQTT.fx模拟设备可以每隔一段时间把最新状态以保留消息发布到dist-01/circuit-03/lamp-07/state之后任何一个新接入的Web客户端订阅这个主题时Broker会立即把最后一条保留消息推送给它。这比Web端每次刷新都去查数据库要快得多也让Web前端的初始化逻辑统一为“订阅主题 等待推送”。3. 服务端接入MQTT——用EMQX做云平台Broker并处理上行数据的完整步骤3.1 Broker选型自建EMQX还是物联网云平台在PC机上做Web开发和联调时最顺手的方式是在本地跑一个开源MQTT Broker这能让你完全掌控每一个消息流向。我一般会选EMQX因为它自带Dashboard能在浏览器里看到当前连接数、消息吞吐和订阅关系排查问题比黑盒的云平台方便很多。在PC机上安装EMQX很简单Windows或Linux环境都支持下载解压后执行bin/emqx start即完成启动默认监听1883端口MQTT over WebSocket监听8083端口。如果项目要求使用物联网云平台则通常是买一个MQTT实例把连接地址、端口、认证信息填入设备端配置。这种方式少了维护成本但排查消息问题时要靠平台提供的日志服务调试效率略低。对于标题中“在PC机上进行Web开发”的定位本地EMQX是最务实的选择。3.2 用Node.js订阅MQTT主题并把数据写入业务存储服务端是整个系统的中枢它一边订阅设备上行Topic一边把处理后的数据通过WebSocket推送或REST接口提供给前端。这里我用Node.js的mqtt包实现一个最小订阅服务const mqtt require(mqtt); const client mqtt.connect(mqtt://127.0.0.1:1883, { clientId: server- Math.random().toString(16).substring(2, 8), cleanSession: true }); client.on(connect, () { // 订阅整个园区所有路灯的状态与告警话题 client.subscribe(dist-01///state, { qos: 1 }, (err) { if (err) console.error(订阅失败, err); }); }); client.on(message, (topic, payload) { const { circuitId, lampId } parseTopic(topic); const data JSON.parse(payload.toString()); // 过滤掉非法的消息格式防止脏数据入库 if (!data.state || typeof data.state ! string) return; console.log(回路${circuitId} 灯位${lampId} - ${data.state}); // 这里写数据库写入逻辑或WebSocket广播 }); function parseTopic(topic) { // 主题格式: dist-01/{circuitId}/{lampId}/state const parts topic.split(/); return { circuitId: parts[1], lampId: parts[2] }; }这段代码的逻辑核心是两点第一mqtt.connect时的clientId绝不能和设备端重复否则MQTT协议会强制踢掉旧连接导致设备反复掉线第二在message回调中先解析Topic再处理Payload因为MQTT协议本身不携带业务语义所有路由信息都编码在Topic字符串里必须由一个统一解析函数来维护。3.3 EMQX接入参数表连接认证、心跳和会话过期时间在对接EMQX时有几个参数需要手动确认。本地调试时通常不需要认证但一旦把Broker暴露到局域网就必须开启密码认证。以下是常用的参数配置参数推荐值说明监听端口1883 / 80831883是TCP端口8083是WebSocket端口心跳间隔30s低于Broker的keep_alive超时即可cleanSessionfalse服务端建议false断线后恢复离线消息会话过期2小时配合cleanSessionfalse使用认证方式username/password设备端按产品密钥填入有一类问题特别值得注意如果服务端同时订阅了多个主题但某个主题的消息量特别大Node.js单线程的message回调可能成为瓶颈。解决方案是按消息类型拆成多个client连接一个专门处理高频遥测另一个处理低频指令和告警。4. Web前端实现——从MQTT over WebSocket到配电工艺图的可视化方案4.1 为什么前端不用轮询而是直接走MQTT协议在传统的Web开发里页面要拿到设备状态通常会每隔2秒请求一次REST接口。但在路灯系统中开关状态变化需要毫秒级反馈轮询会造成两个问题一是页面刷新速度受限于轮询间隔二是并发请求量会随着页面数量线性增长。MQTT over WebSocket则让浏览器直接成为MQTT Client。Web端建立连接后订阅dist-01///state任何一盏灯的开关变化都会在100毫秒内被推送到页面无需刷新、无需轮询。这种模式也被称为“MQTT协议直接穿透到前端”是物联网云平台Web开发的典型架构。4.2 Vue3 mqtt库建立长连接的最小实现在Vue3工程中安装mqtt库后可以封装一个可复用的连接模块避免每个组件都创建独立连接import mqtt from mqtt; import { reactive } from vue; export const lampStore reactive({ statusMap: {}, client: null, }); export function connectMqtt() { if (lampStore.client) return lampStore.client; const url ws://127.0.0.1:8083/mqtt; lampStore.client mqtt.connect(url, { clientId: web- Math.random().toString(16).substring(2, 8), cleanSession: true, }); lampStore.client.on(connect, () { lampStore.client.subscribe(dist-01///state, { qos: 0 }); }); lampStore.client.on(message, (topic, payload) { const parts topic.split(/); const key ${parts[1]}-${parts[2]}; lampStore.statusMap[key] JSON.parse(payload.toString()); }); return lampStore.client; }在Vue组件里只需调用connectMqtt()并把lampStore.statusMap绑定到页面模板即可。由于statusMap是reactive对象当MQTT消息到达并修改它时Vue视图会自动更新这是整个Web前端开发里最关键的响应式联动。要注意的是浏览器端不能直连1883端口因为该端口是TCP协议浏览器JavaScript无法建立原生TCP Socket必须使用WebSocket端口EMQX默认8083且路径通常是/mqtt。4.3 配电工艺图在Web端的绘制思路SVG图形数据驱动配电工艺图是智慧路灯Web项目中可视化程度最高的部分。它通常展示一个配电柜内的主回路、支路开关和各个路灯之间的电气关系。在Vue中我一般用SVG来绘制因为SVG的每个图元都可以绑定独立的Vue响应式数据。例如一个灯位回路的开关状态反映为断路器符号的颜色回路合闸时断路器填充绿色回路跳闸时填充红色并显示告警闪烁灯位灯泡图标根据state.on属性切换亮灭。SVG的rect和circle元素可以手动编写也可以通过用户点击事件来切换状态。这里要注意的是不要把所有图元写在一个大的静态SVG模板里而应该按回路把图元拆成circuit子组件通过props传入回路数据。这样当MQTT推送某一回路的状态时Vue的组件diff只更新对应子组件避免全量重绘。4.4 下行控制指令如何通过Web端发布Web端不仅能订阅还能发布。用户点击“开灯”按钮时客户端向dist-01/{circuitId}/{lampId}/command主题发布一条JSON指令client.publish(dist-01/${circuitId}/${lampId}/command, JSON.stringify({ action: on, brightness: 80, timestamp: Date.now() }), { qos: 1 });这里的Topic特意设计为command而非state是为了在语义上把控制命令和上报状态分开。设备端订阅command主题执行动作后上报新的state。如果发布和上报混在同一个主题里服务端就无法判断消息来源到底是设备还是用户会出现状态回环。这个设计细节是MQTT协议工程化中常见的规范几乎所有物联网云平台都是这样区分“属性下发”和“属性上报”的。5. 用MQTT.fx把模拟调试做成生产级验证——从单灯模拟到批量压测的完整技巧5.1 MQTT.fx连接参数的设置与常见连接失败排查MQTT.fx是PC端最常用的MQTT客户端模拟工具标题中用它模拟采集端数据再合适不过。打开MQTT.fx后点击齿轮图标新建连接配置Profile Name填lamp-simulatorBroker Address填127.0.0.1Port填1883。连接成功后左侧Subscribe页签填写主题dist-01/circuit-01/lamp-01/command点Subscribe按钮右侧Publish页签填写同一个主题Payload按JSON格式填入开灯指令点Publish按钮。注意MQTT.fx自身的Client ID不能与Web端或服务端重复否则会互相踢下线。如果连接失败先用ping 127.0.0.1确认Broker在运行然后看EMQX Dashboard的Listeners页面检查端口是否被占用。Windows下常见问题是防火墙拦截了1883端口入站TCP流量需要放行emqx.exe或直接放行该端口。5.2 批量模拟多盏路灯用MQTT.fx的脚本功能产生多路数据MQTT.fx支持用JavaScript脚本自动发布消息这对模拟“采集端”很有价值。比如模拟一个回路下5盏路灯的周期性状态上报可以在Scripts面板中写一段定时循环每个循环发布一个不同Topic的状态消息。Payload格式保持统一{ state: on, voltage: 220.5, current: 0.36, power: 79.4, timestamp: 1712073600000 }脚本每隔5秒执行一次Topic中的灯位编号按循环变量递增。这样你不需要同时打开5个MQTT.fx窗口也能让Web端看到多盏灯在线。实际调试中我发现大部分同学在模拟阶段只发不做状态机转换导致命令下发后看不到反馈。因此脚本里最好让state字段在on和off间切换模拟真实的开关响应。5.3 时间戳与乱序消息处理这是Web端最容易忽略的脏数据来源用MQTT.fx模拟数据时Payload里的timestamp如果不手动设置所有消息都会使用本机当前时间。但真实设备上报会有网络延迟不同灯的时间戳可能乱序到达。如果在Web端直接用收到的消息覆盖上一帧状态很可能出现“旧数据覆盖新状态”的竞态问题。正确做法是在Web端收到消息时先比较时间戳只有新消息的时间戳大于当前状态时间戳才更新视图。这个细节决定了系统在弱网环境下是否会闪现错误的状态。另一个验证技巧是在MQTT.fx中手动发送一条错误Payload比如{state:on,voltage:abc}确认服务端不会因JSON解析异常而崩溃。在严格模式下服务端应捕获解析异常并丢弃该消息而不是让整个订阅回调抛出未捕获异常。给Web端的建议是所有来自MQTT协议的消息都必须在显示前做一层类型校验因为模拟器和真实设备的字段类型并不总是保持一致。当你在PC机上跑通以上全部链路时整个智慧路灯系统的核心价值已经验证完毕剩下的只是把模拟数据换成真实设备上报。本文还有配套的精品资源点击获取