物联网云平台工业设备对接远程控制数据采集视频接入开源可二次开发 该物联网云平台使用 Java 语言、主流技术组合开发，支持多数据源，支持代码一键生成，方便快速开发。 1、内含物联网云平台全套源码（源码全部开放，无任何加密，可二次开发）、MQTT服务、数据库设计、相关资料、相关工具软件等； 2、使用基于发布/订阅模式的轻量级通讯协议 MQTT，具有自动重连机制，具有设备上下线提醒功能； 3、支持 Modbus RTU、Modbus TCP 协议03、05功能码，亦可自定义协议接入；支持各类 DTU、透传模块以及各类工业设备接入等； 4、支持云固件升级、远程重启等；可存储各路开关状态，设备断电或重启后可自动同步云端各路开关状态，具有开关状态记忆功能； 5、云平台可对各类传感器管理，适用各种业务场景；对传感器数据有多种展示方式； 6、可配置报警规则，符合报警规则可执行自定义动作、联动报警、报警通知等； 7、控制命令下达后有执行状态反馈，可确保设备控制命令执行成功； 8、具有可视化在线定时任务配置功能，可指定某一时刻执行、周期执行、自定义 Cron 表达式执行等操作； 9、具有场景管理功能，可一键执行设定的动作； 10、具有视频管理功能，支持萤石云协议的摄像头均可接入云平台，可在云平台直接预览视频画面； 11、可记录设备、用户所有操作记录，设备、用户上下线记录等，并具有多种类型的数据统计展示； 12、云平台可对所有用户管理，每个用户可配置不同角色、不同权限，具有权限分配功能；支持对人员进行菜单、按钮及数据权限控制，亦可自定义数据权限； 13、前端采用完全响应式布局，支持电脑、平板、手机等所有主流设备； 14、Maven 多项目依赖，模块及插件分项目，尽量松耦合，方便模块升级、增减模块； 等等……内容较多，在此无法一一列举

KSoft 物联网通用平台

《ksoft-common》模块源码级功能说明书

—— 写给二次开发者与运维人员

------------------------------------------------

一、模块定位

ksoft-common 是整个 KSoft 物联网平台的“技术底座”，它不提供业务页面，却为所有业务微服务（ksoft-system、ksoft-website、ksoft-mqtt 等）统一提供：

1. 工具级 API（日期、加解密、Excel、MQTT 配置、字典缓存、IP 获取、XSS 过滤……）
2. 通用技术中间件（多数据源切换、异步线程池、操作日志 AOP、数据权限 AOP、防重复提交、Shiro 安全工具、全局异常体系）
3. 代码生成器与调度器依赖的“元数据”模型（BaseEntity、TreeEntity、Ztree、字典实体、权限常量）

一句话：只要引用了 ksoft-common，就能直接获得一套“开箱即用”的物联网后台基础设施。

------------------------------------------------

二、包结构速览

com.ksoft.common

├─ annotation // 自定义注解（@DataScope、@Log、@RepeatSubmit、@Excel …）

├─ config // 全局配置类（KSoftConfig、MqttConfig、ThreadPoolConfig）

├─ constant // 系统级常量（Constants、UserConstants、PermissionConstants…）

├─ core // 统一返回、分页、基础实体（AjaxResult、BaseEntity、TableDataInfo）

├─ enums // 通用枚举（BusinessType、DataSourceType、DeviceOperType…）

├─ exception // 全局异常体系（BusinessException、UserException、FileException…）

├─ json // JSON 与 JSONObject 封装（jackson 二次封装）

├─ utils // 工具大合集（日期、Http、IP、DES、MD5、Excel、反射、SpringUtils…）

└─ xss // XSS 过滤器（XssFilter + XssHttpServletRequestWrapper）

------------------------------------------------

三、核心能力逐条拆解

1. 统一响应与分页
   • AjaxResult（code/msg/data）—— 所有 Controller 返回同一结构
   • TableDataInfo（total/rows）—— 与 PageHelper 无缝衔接，前端表格直接渲染
   • BaseController 提供 startPage()/getDataTable(list) 模板方法，一句代码完成分页

1. 多数据源 & 读写分离
   • 注解 @DataSource(DataSourceType.MASTER/SLAVE)
   • DataSourceAspect 在方法调用前把数据源名称压入 ThreadLocal
   • DynamicDataSource 继承 AbstractRoutingDataSource，根据 ThreadLocal 动态切换
   • 主从库故障时，Druid 会自动降级；业务方零感知

1. 数据权限（部门/用户维度）
   • 注解 @DataScope(deptAlias = "d", userAlias = "u")
   • DataScopeAspect 在 Mapper 执行前改写 SQL，自动拼接
   AND (d.deptid IN (…当前角色可见部门…) OR u.userid = …当前用户…)
   • 支持 5 种内置规则（全部/自定义/本部门/本部门及下级/仅本人）

1. 操作日志 & 登录日志（AOP 无侵入）
   • @Log(title = "设备管理", businessType = BusinessType.INSERT)
   • LogAspect 在方法返回/异常时异步记录：类名+方法、入参、耗时、IP、地点、浏览器、错误信息
   • AsyncManager + ScheduledExecutorService 日志落库，即使高并发也不阻塞业务

1. 防重复提交
   • @RepeatSubmit 标记在 Controller 方法
   • SameUrlDataInterceptor 用 session 缓存“URL+参数+时间戳”，10 秒内相同参数直接拒绝
   • 支持前后分离场景（Header 里加 token 也能识别）

1. 物联网专用配置
   • MqttConfig 读取 application.yml 中 mqtt.* 属性，统一给出 host、port、clientId、userName、password、qos、keepAlive、threadPoolSize
   • 其他模块只需 @Autowired MqttConfig 即可拿到全套参数，避免到处硬编码

1. 字典/参数缓存
   • DictUtils 提供 getDictLabel()/getDictValue()，自动加 Ehcache
   • 后台修改字典后调用 DictUtils.clearDictCache() 即可实时刷新
   • 同理 SysConfigCache 处理系统参数（短信密钥、文件路径等）

1. Excel 一键导入导出（poi 封装）
   • 在实体字段加 @Excel(name = "温度", readConverterExp = "0=正常,1=偏高")
   • ExcelUtil 自动解析下拉框、日期格式、字典翻译、图片插入、合计行
   • 支持 65536 行以上大数据 SXSSF 模式，内存无压力

1. 全局异常兜底
   • 业务异常 BusinessException → 前端弹窗提示
   • 文件异常 FileException → 统一返回“文件过大/格式不符”
   • 所有异常被 GlobalExceptionHandler 捕获 → AjaxResult.error(msg)
   • 生产环境关闭堆栈，防止信息泄露

1. 安全加固
   • XssFilter 全局过滤，白名单机制，支持 excludes 路径放行
   • DesUtils、MD5、SHA1、随机盐，满足密码加密与固件校验
   • ShiroUtils 提供 getSysUser()/getIp()/randomSalt()，任何层都能直接拿当前登录人

------------------------------------------------

四、典型调用链（以“分页查询设备列表”为例）

前端 → DeviceController.list(Device device)

① BaseController.startPage() // ThreadLocal 注入分页参数

② DeviceService.selectDeviceList(device)

  @DataScope(deptAlias="d") // DataScopeAspect 改写 SQL

  MyBatis Mapper → 多数据源切换（若方法标 @DataSource(SLAVE)）

③ PageHelper 拦截器 → SELECT … LIMIT ?

④ 结果封装 TableDataInfo → AjaxResult → 前端表格渲染

⑤ LogAspect 记录操作日志（异步线程池）

⑥ 异常 → GlobalExceptionHandler → AjaxResult.error(msg)

------------------------------------------------

五、二次开发必看指南

1. 新增工具方法
   直接新建 XxxUtils 放在 common.utils 包，静态方法+private 构造，补充单元测试即可。

1. 新增通用枚举
   实现 IEnum（getValue/getDescription）即可被 ExcelUtil、DictUtils 自动识别。

1. 新增数据源
   步骤① application-druid.yml 加 spring.datasource.druid.xxx
   步骤② DataSourceType 枚举新增 XXX
   步骤③ DruidConfig.java 新增 xxxDataSource() Bean
   步骤④ 在 Service/Mapper 方法加 @DataSource(xxx)

1. 自定义异常
   继承 BaseException 并写对应枚举，GlobalExceptionHandler 中追加一个 @ExceptionHandler，统一返回格式保持 AjaxResult。

1. 关闭/降级功能
   • xss.enabled=false → 关闭 XSS 过滤
   • user.password.maxRetryCount=0 → 关闭密码重试限制
   • mqtt.enabled=false → 关闭 MQTT 自动配置

------------------------------------------------

六、性能与运维指标

维度	数据（单实例 4C8G）	备注
最大在线设备	50 万	MQTT 集群+LB
并发 HTTP	3 k QPS	PageHelper+读写分离
日志异步延迟	<50 ms	ScheduledThreadPool
堆内存占用	启动 350 MB	开启 30 个线程池
FullGC 频率	1 次/天	G1 + 6G Heap

------------------------------------------------

七、常见坑与排查

1. 分页失效
   现象：PageHelper 返回全部数据
   原因：startPage() 与 Mapper 调用之间插了别的 SQL（如 selectDictLabel）
   解决：把非分页 SQL 提到 startPage() 之前

1. 数据源切换不生效
   现象：@DataSource(SLAVE) 仍走主库
   原因：方法被同类内部调用，AOP 未生效
   解决：拆到另一个 Service，或启用 AopContext.currentProxy()

1. MQTT 断线重连风暴
   现象：EMQX 看到海量重连
   原因：clientId 重复（serverId001）
   解决：clientId = "serverId" + IpUtils.getHostIp() + "_" + PID

1. Excel 导出 OOM
   现象：SXSSF 仍内存溢出
   原因：row.createCell() 之后未 flush()，或图片一次性读入
   解决：图片采用 InputStream 延迟读取；每 5000 行 flush

------------------------------------------------

八、版本演进路线

v2.2（当前）

└─ 多数据源、MQTT、防重、XSS、代码生成

v2.4（规划中）

└─ 集成 Redis 缓存、Spring Validation 分组、Flowable 工作流、EMQX 规则引擎桥接

v3.0（远期）

└─ 全面云原生：Spring Cloud Alibaba + K8s + Istio + Prometheus + SkyWalking

------------------------------------------------

九、结语

ksoft-common 通过“注解驱动 + AOP 织入 + 工具下沉”的策略，把 80% 的物联网后台通用问题一次性解决。

作为二次开发者，只需关注：

① 业务实体 ② 业务 Mapper ③ 业务 Controller——其余基础设施，ksoft-common 已全部备好。

熟读本文，即可在 30 分钟内跑通新模块，1 小时内发布到测试环境，次日即可交付客户。祝开发愉快！