1. 项目概述与系统定位

这几年在项目圈里跑得比较多的就是智慧工地方向，尤其是有政府侧或大型建工集团背景的项目，几乎都会提一嘴“整合物联网、大数据、人工智能”，但真正能把这三样落地成一个可交付的Java后端源码项目的，其实并不算多。大部分智慧工地系统要么只做了视频监控和台账管理，要么就堆了一堆大屏图表，设备数据接不进来，AI识别只是演示Demo。

这套Java智慧工地项目管理系统源码，核心定位就是解决上面这些问题。它是一个面向工地现场管理场景的综合性平台，覆盖了人员实名制与定位、车辆出入管理、环境监测、塔吊运行监控、视频AI识别（安全帽/反光衣/区域闯入）、能耗分析、质量安全巡检、进度管理和数据大屏展示等模块。技术侧把物联网设备接入、大数据分析链路和AI视觉识别能力统一到了同一个后端体系中，而不是各做各的孤岛系统。

适合谁来参考？如果你是做Java后端开发、想了解IoT数据如何与业务系统打通的技术人员，或者你所在的公司正准备承接智慧工地类项目、需要一套能落地的架构参考，再或者你只是对“物联网+AI+大数据”这套组合在后端工程里怎么真正组织代码感兴趣，这套源码都有很直接的参考价值。

需要提前说明的是，本文不是给你堆需求文档，也不是贴一张大屏截图讲故事。我会从源码工程结构、技术选型逻辑、核心模块实现、部署注意事项和常见坑这几个角度，把这个项目里“为什么这么做”“代码层面长什么样”“跑起来会遇到哪些问题”讲透。内容偏实战，看完之后你可以直接用这套思路去复现或改造自己的项目。

2. 整体架构设计与技术选型

2.1 系统从哪里切入：先抓住“数据流”而不是“功能清单”

我第一次看到这个项目的源码目录时，第一反应是去看它的包结构。说实话，很多号称“整合物联网、大数据、AI”的项目，打开源码之后就是一堆管理后台的CRUD，物联网设备数据用定时任务模拟，AI能力是调第三方接口，所谓的“整合”只是页面上的按钮。

这个项目的切入点不太一样。它把整条数据链路作为系统的主干线来设计：设备端产生数据 → IoT网关接入 → 消息队列缓冲 → 数据解析与清洗 → 规则引擎告警 → 业务模块消费 → 数据仓库统计分析 → 大屏呈现。整条链路是通的，而不是每个模块各自为政。

举个例子，环境监测模块里的PM2.5、噪声、温湿度数据，不是直接写进MySQL就完事了。传感器数据通过MQTT协议接入IoT网关服务，网关服务负责解析不同厂商的报文格式（JSON、MQTT自定义Topic），统一成标准结构后写入Kafka，再通过流处理任务做阈值判断，如果噪声超过国标限值就触发告警。告警事件既会落入MySQL用于业务展示，也会推送给WebSocket，让大屏端实时弹窗。与此同时，原始数据还会进入ClickHouse做聚合统计，供后续的日报、周报和趋势分析使用。

这样设计的好处很明显：业务系统不需要关心设备怎么接入、报文怎么解析，IoT网关层把设备差异屏蔽掉了；告警和数据分析都走事件驱动，不会因为设备上报频率高而拖垮业务库；而且每一层都可以独立扩容。比如接入的设备从几百台增加到几千台，Kafka和ClickHouse的压力远小于直接让MySQL硬抗。

2.2 技术栈选型的几个关键判断

这套源码的Java技术栈选得比较务实，没有刻意追新。主框架是Spring Boot 2.7.x，配合Spring Cloud Alibaba做微服务拆分，服务注册与配置中心用Nacos，服务间调用用OpenFeign。网关层用了Spring Cloud Gateway，权限模型用的是Spring Security + OAuth2 + JWT。这些都是国内Java项目的常见组合，人员上手成本低，排查问题也有大量社区经验可参考。

有几个选型值得单独拿出来说：

第一，Kafka在数据链路里的位置不是可选项。环境监测设备的上报频率通常是每30秒到1分钟一次，塔吊的监测数据频率更高，再加上视频AI识别产生的事件数据，整个系统的峰值TPS并不低。如果所有数据都直接打到MySQL，数据库根本扛不住。源码里Kafka承担了两个核心职责：一是削峰填谷，让大量设备上报数据先进队列，再由消费端按业务需要去处理；二是做服务间的解耦，比如AI识别服务只需要把识别结果丢到指定的Topic里，业务模块自己去订阅，两边的版本迭代互不影响。

第二，时序数据没有硬塞给MySQL，而是单独用了ClickHouse。工地数据的“大数据”部分不是指数据量有多夸张，而是指数据的维度多、时间粒度细、需要灵活的聚合分析。比如你要看某台塔吊一周内每天的平均工作时长，同时要看某个时间段内起重量的累计值，这种查询如果走MySQL的聚合，一旦数据量上了千万级别，查询响应就会变得很难看。ClickHouse在这种场景下几乎是降维打击，它在源码里被用在环境数据历史分析、设备运行时长统计、施工进度趋势这几个模块中。

第三，AI能力的接入方式是“服务化”而不是“硬编码”。源码里没有把模型推理逻辑写死在业务代码里，而是单独拆了一个ai-service服务。这个服务负责接入视频流、抽帧、调用模型推理、输出检测结果。业务系统与AI服务之间通过接口和消息队列通信，模型本身是离线训练好的YOLO系列模型，源码里带的是训练脚本和推理服务的工程，而不是简单调一个在线API。这样做的好处是，后续如果要替换更好的模型、调整识别阈值，只需要在ai-service内部改，不会动到其他模块。

业务侧还保留了人工复核的入口。AI识别到未戴安全帽的事件后，会自动抓拍图片并推送告警，但并不会直接生成扣款或处罚记录，而是由安全员在后台确认。这个设计非常现实，因为AI识别总有误报，直接自动处罚会引发纠纷。在项目交付的时候，这种“AI识别+人工确认”的处理流程，往往是客户真正认可的关键细节。

2.3 微服务模块边界怎么划

模块划分是这类项目中最容易出事的地方。划得过粗，代码全堆在一个服务里，后期改一处要重新部署整个系统；划得过细，服务间调用链条拉长，事务和排查难度都会上去。这套源码把边界控制在了合理粒度，总共拆成这么几个服务：

• gateway：统一入口，路由转发、鉴权过滤
• system：基础数据，组织架构、用户角色权限、字典管理
• project：项目与施工进度管理，包括计划、工序、进度上报
• personnel：劳务人员实名制，含实名建档、考勤、闸机通行记录
• iot-core：物联网接入核心，负责设备管理、协议解析、数据接入
• security：质量安全巡检，隐患登记、整改闭环
• environment：环境监测数据消费与告警
• monitor：视频监控与AI识别联动
• >