250 lines
6.8 KiB
Markdown
250 lines
6.8 KiB
Markdown
|
# cmvr-iot
|
|||
|
|
|
|||
|
|
cmvr-iot 是一个基于 Java 8 和 Spring Boot 2.5 的多模块后端工程，提供设备管理、边缘机器人控制、测试编排、巡检、TTS、AIMA、VI/TI 等业务能力。工程入口在 `cmvr-iot-admin`，其余模块按业务和基础能力拆分。
|
|||
|
|
|
|||
|
|
## 技术栈
|
|||
|
|
|
|||
|
|
- Java 8
|
|||
|
|
- Spring Boot 2.5.15
|
|||
|
|
- Spring Security
|
|||
|
|
- MyBatis Plus / MyBatis Plus Join
|
|||
|
|
- MySQL / Redis
|
|||
|
|
- Druid
|
|||
|
|
- Quartz
|
|||
|
|
- Knife4j / Swagger
|
|||
|
|
- gRPC Java 1.58.0
|
|||
|
|
- Protobuf / protoc-maven-plugin
|
|||
|
|
- MinIO
|
|||
|
|
|
|||
|
|
## 模块说明
|
|||
|
|
|
|||
|
|
| 模块 | 说明 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| `cmvr-iot-admin` | Web 启动模块，包含 REST Controller、启动类和运行配置 |
|
|||
|
|
| `cmvr-iot-framework` | Web、安全、配置、通用框架能力 |
|
|||
|
|
| `cmvr-iot-common` | 公共工具、通用响应、基础常量和通用能力 |
|
|||
|
|
| `cmvr-iot-system` | 系统管理、用户、角色、菜单、字典等基础业务 |
|
|||
|
|
| `cmvr-iot-quartz` | 定时任务模块 |
|
|||
|
|
| `cmvr-iot-generator` | 代码生成模块 |
|
|||
|
|
| `cmvr-iot-device` | 设备领域模型与设备相关能力 |
|
|||
|
|
| `cmvr-iot-test` | 测试任务、编排、执行实例等业务 |
|
|||
|
|
| `cmvr-iot-vi` | VI 相关业务 |
|
|||
|
|
| `cmvr-iot-ti` | TI 相关业务 |
|
|||
|
|
| `cmvr-iot-evaluation` | 评测相关业务 |
|
|||
|
|
| `cmvr-iot-inspection` | 巡检机器人、地图、任务、告警等业务 |
|
|||
|
|
| `cmvr-iot-aima` | AIMA 相关业务 |
|
|||
|
|
| `cmvr-iot-tts` | TTS 语音合成相关业务 |
|
|||
|
|
| `cmvr-iot-api` | API 聚合模块 |
|
|||
|
|
| `cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib` | gRPC proto 与生成代码模块 |
|
|||
|
|
| `cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client` | 边缘设备 gRPC 客户端、设备控制服务和请求 VO |
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
cmvr-iot
|
|||
|
|
├── cmvr-iot-admin # Spring Boot 启动模块
|
|||
|
|
├── cmvr-iot-common # 公共模块
|
|||
|
|
├── cmvr-iot-framework # 框架模块
|
|||
|
|
├── cmvr-iot-system # 系统管理模块
|
|||
|
|
├── cmvr-iot-device # 设备模块
|
|||
|
|
├── cmvr-iot-test # 测试业务模块
|
|||
|
|
├── cmvr-iot-api
|
|||
|
|
│ └── cmvr-iot-edge
|
|||
|
|
│ ├── cmvr-iot-grpc-lib # proto 与 gRPC 生成代码
|
|||
|
|
│ └── cmvr-iot-grpc-client # gRPC 客户端与边缘控制服务
|
|||
|
|
├── sql # 增量 SQL
|
|||
|
|
├── Dockerfile
|
|||
|
|
├── Jenkinsfile
|
|||
|
|
└── pom.xml # Maven 父工程
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 环境要求
|
|||
|
|
|
|||
|
|
- JDK 1.8
|
|||
|
|
- Maven 3.6+
|
|||
|
|
- MySQL 5.7+/8.x
|
|||
|
|
- Redis
|
|||
|
|
- 可访问的 gRPC 机器人/边缘终端服务
|
|||
|
|
- 可选：MinIO、外部大模型/TTS/评测服务
|
|||
|
|
|
|||
|
|
注意：`application-*.yml` 中包含环境相关地址、账号和密钥配置。实际部署或本地开发时，应使用本机配置、环境变量或配置中心覆盖，不要直接复用生产/测试环境敏感配置。
|
|||
|
|
|
|||
|
|
## 配置文件
|
|||
|
|
|
|||
|
|
主配置文件位于：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
cmvr-iot-admin/src/main/resources/application.yml
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
环境配置文件位于：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
cmvr-iot-admin/src/main/resources/application-dev.yml
|
|||
|
|
cmvr-iot-admin/src/main/resources/application-test.yml
|
|||
|
|
cmvr-iot-admin/src/main/resources/application-prod.yml
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
当前 `application.yml` 默认激活：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
spring:
|
|||
|
|
profiles:
|
|||
|
|
active: test
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
如需切换环境，可以修改 `spring.profiles.active`，或启动时指定：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
java -jar cmvr-iot-admin-dev.jar --spring.profiles.active=dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 构建
|
|||
|
|
|
|||
|
|
在项目根目录执行：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mvn clean package -DskipTests
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
只编译启动模块及其依赖：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mvn -pl cmvr-iot-admin -am compile -DskipTests
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
只重新生成并编译 gRPC 代码：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mvn -pl cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib -am compile -DskipTests
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 启动
|
|||
|
|
|
|||
|
|
启动类：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
cmvr-iot-admin/src/main/java/com/cmvr/CmvrIotApplication.java
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
IDE 中直接运行 `CmvrIotApplication` 即可。
|
|||
|
|
|
|||
|
|
打包后运行：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
java -jar cmvr-iot-admin/target/cmvr-iot-admin-dev.jar --spring.profiles.active=dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
默认开发端口以当前 profile 配置为准，例如 `application-dev.yml` 中为：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
server:
|
|||
|
|
port: 13080
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 接口文档
|
|||
|
|
|
|||
|
|
项目集成 Knife4j / Swagger。服务启动后可访问：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
http://localhost:13080/doc.html
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
如果端口或上下文路径被 profile 覆盖，请以实际配置为准。
|
|||
|
|
|
|||
|
|
## 数据库脚本
|
|||
|
|
|
|||
|
|
增量脚本位于：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
sql/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
当前包含：
|
|||
|
|
|
|||
|
|
- `aima_module.sql`
|
|||
|
|
- `inspection_module.sql`
|
|||
|
|
- `tts_corpus_module.sql`
|
|||
|
|
|
|||
|
|
初始化数据库时，需要结合目标环境的基础库结构和增量脚本执行。
|
|||
|
|
|
|||
|
|
## gRPC 与边缘设备
|
|||
|
|
|
|||
|
|
边缘设备相关代码集中在：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
cmvr-iot-api/cmvr-iot-edge/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
proto 文件位于：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib/src/main/proto/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
gRPC 客户端服务位于：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client/src/main/java/com/cmvr/edge/client/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
边缘控制器位于：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
cmvr-iot-admin/src/main/java/com/cmvr/web/controller/api/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
新增或修改 proto 后，执行 Maven compile 会触发 `protoc-maven-plugin` 生成 Java 和 gRPC Stub 代码。业务代码应复用现有 gRPC 客户端管理工具获取 Stub，避免在业务层重复创建底层 `ManagedChannel`。
|
|||
|
|
|
|||
|
|
## 实时语音对讲
|
|||
|
|
|
|||
|
|
当前实时语音对讲链路为：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
浏览器 WebSocket Binary PCM <-> Java 后端 <-> gRPC 双向流 <-> 机器人终端
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
约定音频格式：
|
|||
|
|
|
|||
|
|
- PCM_S16LE
|
|||
|
|
- 48000 Hz
|
|||
|
|
- 单声道
|
|||
|
|
- 16 bit
|
|||
|
|
- 10 ms 一帧
|
|||
|
|
- 960 bytes/帧
|
|||
|
|
|
|||
|
|
相关文件：
|
|||
|
|
|
|||
|
|
- WebSocket 控制器：`cmvr-iot-admin/src/main/java/com/cmvr/web/controller/api/WebRtcSignalingController.java`
|
|||
|
|
- 业务会话管理：`cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client/src/main/java/com/cmvr/edge/client/service/AudioService.java`
|
|||
|
|
- gRPC 音频适配：`cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client/src/main/java/com/cmvr/edge/client/adapter/RobotAudioGrpcAdapter.java`
|
|||
|
|
- proto：`cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib/src/main/proto/cmvr/api/robot_audio.proto`
|
|||
|
|
|
|||
|
|
说明：历史 WebRTC 相关类可能仍保留在源码中，但当前浏览器音频传输链路使用 WebSocket 二进制 PCM。
|
|||
|
|
|
|||
|
|
## 开发约定
|
|||
|
|
|
|||
|
|
- Controller 层只做参数接收、基础校验和响应封装。
|
|||
|
|
- POST 控制类接口优先使用单个 `@RequestBody VO` 承载完整请求参数。
|
|||
|
|
- GET 查询类接口可以使用 query 参数绑定 VO。
|
|||
|
|
- 不建议在同一个接口中同时声明通用 VO 和零散业务参数。
|
|||
|
|
- gRPC 调用统一通过现有客户端管理类获取 Stub。
|
|||
|
|
- proto 修改后必须重新编译并确认生成代码已更新。
|
|||
|
|
- 不要提交本地日志、崩溃 dump、临时音频文件和包含真实密钥的配置。
|
|||
|
|
|
|||
|
|
## 常用命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 编译全部模块
|
|||
|
|
mvn clean compile -DskipTests
|
|||
|
|
|
|||
|
|
# 编译启动模块及依赖
|
|||
|
|
mvn -pl cmvr-iot-admin -am compile -DskipTests
|
|||
|
|
|
|||
|
|
# 打包
|
|||
|
|
mvn clean package -DskipTests
|
|||
|
|
|
|||
|
|
# 运行指定 profile
|
|||
|
|
java -jar cmvr-iot-admin/target/cmvr-iot-admin-dev.jar --spring.profiles.active=dev
|
|||
|
|
```
|