CMVR-IOT/README.md

CMVR IoT 物联网平台

CMVR IoT 是招商车研机器人及智能设备管理平台。本项目以 RuoYi-Vue 3.9.2 为基础升级到 Spring Boot 4，保留原有 REST、前端和 gRPC 对外接口，并将 QUIC Gateway 集成到主应用进程中。

Java 包名、Maven 坐标统一使用 com.cmvr。旧项目 cmvr-iot 仅作为迁移来源，不参与本项目构建。

主要功能

• 系统管理：用户、角色、部门、菜单、字典、参数、日志和通知。
• 机器人设备：以边缘端上报的永久 robotId 作为唯一业务身份，自动同步机器人地址、在线状态和设备清单。
• 测试业务：任务配置、任务编排、任务实例、检测项、语音唤醒、Flowise 和 AI 评估。
• 智能巡检：机器人、地图、点位、任务、执行实例、巡检结果和告警。
• 智能座舱：语音交互、触控交互、TTS、语料库和车机操作配置。
• 专项业务：爱玛电动车测试、评价指标库和大模型服务。
• 边缘控制：通过 gRPC 调用 AGV、相机、机械臂、灵巧手、机器人头部、麦克风和扬声器。
• QUIC 接入：节点注册、心跳、设备快照、媒体 DATAGRAM 和 gRPC 地址同步。
• 平台能力：Quartz 定时任务、代码生成、WebSocket、MinIO 文件服务和 Knife4j 接口文档。

技术栈

组件	版本或实现
Java	17
Spring Boot	4.0.6
Spring Security	JWT 认证
MyBatis	MyBatis-Plus 3.5.17、MPJ 1.5.9
数据库	MySQL
缓存	Redis
RPC	gRPC 1.58.0、Protobuf 3.25.5
QUIC	Netty QUIC 4.2.16.Final
API 文档	Springdoc 3.0.3、Knife4j 4.5.0
前端	Vue 3.4、Element Plus 2.9、Vite 5.3

工程结构

模块	说明
cmvr-iot-admin	Spring Boot 启动入口、REST 控制器和运行配置
cmvr-iot-framework	安全、Web、MyBatis、WebSocket 等框架配置
cmvr-iot-common	公共模型、注解、异常和工具类
cmvr-iot-system	用户、角色、菜单、字典、参数和通用分组
cmvr-iot-quartz	Quartz 任务调度和任务日志
cmvr-iot-generator	代码生成
cmvr-iot-device	设备协议模型、机器人配置和巡检告警监听
cmvr-iot-test	测试任务、流程、检测项和执行实例
cmvr-iot-vi	语音交互业务
cmvr-iot-ti	触控交互业务
cmvr-iot-evaluation	评价指标业务
cmvr-iot-inspection	智能巡检业务
cmvr-iot-aima	爱玛电动车专项业务
cmvr-iot-tts	TTS 任务和车载语料
cmvr-iot-api	边缘服务和大模型 API 聚合模块
cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib	原有 gRPC 协议及生成代码
cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client	原有机器人 gRPC 客户端
cmvr-iot-quic-contract	QUIC 控制、节点事件和媒体数据协议
cmvr-iot-quic	与主应用同进程运行的 QUIC Gateway
cmvr-iot-ui-lxl-dev-worktree	Vue 3 管理控制台（同级独立前端仓库）

环境准备

• JDK 17
• Maven 3.6.3 或更高版本
• MySQL 5.7/8.0
• Redis
• Node.js 18/20 LTS 和 pnpm 9
• MinIO，仅使用文件、语料或媒体存储功能时需要

默认激活 test profile，后端端口为 13080。运行前检查以下配置：

• cmvr-iot-admin/src/main/resources/application-test.yml：MySQL、Redis、MinIO、gRPC 和第三方服务。
• cmvr-iot-admin/src/main/resources/application.yml：上传目录、JWT、MyBatis、Knife4j 和 QUIC。
• 不要把生产密码、访问密钥或 TLS 私钥提交到仓库。

数据库初始化

新数据库以 sql/ry_20260417.sql 为基础脚本。按实际启用模块检查并执行以下补充脚本：

• sql/quartz.sql：Quartz 表结构。
• sql/aima_module.sql：爱玛业务。
• sql/inspection_module.sql、inspection_result.sql、inspection_detection_alert.sql：巡检业务。
• sql/tts_corpus_module.sql：TTS 和语料业务。
• sql/robot_quic_identity_migration.sql：机器人 QUIC 身份、运行状态和设备快照表。
• sql/robot_id_only_migration.sql：移除巡检机器人和任务实例中的历史终端 ID 字段。

补充脚本可能面向不同历史库版本。已有数据库升级前应先备份，并确认字段或索引尚未存在。

后端运行

在项目根目录执行：

mvn clean package -DskipTests
java -jar cmvr-iot-admin/target/cmvr-iot-admin.jar

也可以在 IDEA 中直接运行：

com.cmvr.CmvrIotApplication

DevTools 自动重启已关闭。修改代码后需要完整停止并重新启动应用，避免 MPJ 保留已经关闭的 Spring 上下文。

常用地址：

• 后端 API：http://localhost:13080
• Knife4j 文档：http://localhost:13080/doc.html
• OpenAPI JSON：http://localhost:13080/v3/api-docs/00-all

Knife4j 只展示带原有 @ApiOperation 注解的正式接口，并沿用中文 @Api(tags=...) 业务分类。

前端运行

cd ../cmvr-iot-ui-lxl-dev-worktree
pnpm install
pnpm dev

默认开发端口为 80。.env.development 中的 VITE_API_URL 必须与后端地址一致；本项目后端默认是 http://localhost:13080。更多说明见 ruoyi-ui/README.md。

gRPC 与 QUIC

原有机器人 gRPC 客户端与 proto 均保留，但业务调用只传永久 robotId。平台根据 inspection_robot.robot_id 查找 QUIC 最近同步的 ip_address 和 port，不再使用终端 ID 或终端配置解析 gRPC 地址。

边缘端通过 QUIC 上报设备快照后，平台按 robotId + deviceId 写入 inspection_robot_device。前端选择机器人后只展示该机器人当前在线且启用的设备；单一匹配设备会自动选中并锁定。

QUIC 不是独立服务，cmvr-iot-quic 已作为 cmvr-iot-admin 的运行时依赖。启用时主应用同时启动：

• QUIC：默认 0.0.0.0:4433/udp
• 节点和媒体事件：通过 Spring 单例 NodeEventBroker 在进程内直接分发，不占用内部端口

设置 cmvr.quic.enabled=true 前必须配置有效的 TLS 证书和私钥，否则应用会拒绝启动。详细配置见 cmvr-iot-quic/README.md。

构建与验证

# 运行测试
mvn test

# 构建全部后端模块
mvn clean package -DskipTests

# 构建前端生产包
cd ../cmvr-iot-ui-lxl-dev-worktree
pnpm build:prod

Windows 下也可以使用 bin/package.bat、bin/run.bat 和 bin/clean.bat。

排查提示

• ApplicationContext ... has been closed already：彻底停止旧 Java 进程后重新启动，不要使用 DevTools 热重启。
• 找不到机器人或机器人离线：确认机器人表已登记相同的永久 robotId，并检查 QUIC 注册日志、inspection_robot 的地址和连接状态。
• QUIC 启动失败：检查证书、私钥、ALPN、UDP 端口占用和 native library 对应的操作系统架构。
• 数据库提示缺少字段：确认基础脚本版本及对应模块迁移脚本已经执行。