lixiaolong
86a8e02d85
- 修改AudioService中terminalId为robotId，包括变量声明、参数传递和日志输出 - 更新BaseChannelSubscribeHandler中的注释和参数解析逻辑 - 修改CameraStreamTicketService中的方法参数和记录类定义 - 更新DeRobotConfig文档中的术语描述 - 替换DeviceListController和EdgeAgvController中的terminalId参数为robotId - 修改EdgeAgvServiceImpl中所有方法的参数引用 - 更新EdgeArmController中所有终端ID参数为机器人ID - 修改EdgeArmServiceImpl中所有gRPC客户端调用的参数 - 调整EdgeArmTeleopOpenVO中的字段定义顺序
133 lines
4.7 KiB
Markdown
133 lines
4.7 KiB
Markdown
# CMVR 集成式 QUIC Gateway
|
||
|
||
`cmvr-iot-quic` 是 `cmvr-iot-admin` 的运行时模块，不单独部署。Spring Boot 主应用启动和停止时，`IntegratedQuicGatewayLifecycle` 在同一 JVM 中管理 QUIC 监听器，节点和媒体事件通过 Spring 单例事件代理直接分发。
|
||
|
||
## 数据链路
|
||
|
||
```text
|
||
cmvr-es / 边缘节点
|
||
|
|
||
| QUIC UDP 4433
|
||
| 注册、心跳、设备快照、控制帧、媒体 DATAGRAM
|
||
v
|
||
cmvr-iot-admin
|
||
|-- QuicGatewayServer
|
||
|-- NodeEventBroker
|
||
`-- RobotQuicEventSubscriber（进程内直接订阅）
|
||
v
|
||
inspection_robot + inspection_robot_device + 原有机器人 gRPC 客户端
|
||
```
|
||
|
||
QUIC 链路不启动内部 gRPC Server，也不经过本机 TCP 端口。QUIC 注册中的永久 `robotId` 是机器人唯一业务身份；平台据此同步机器人 gRPC endpoint、设备快照，并在地址变化时清理对应 channel。
|
||
|
||
## 组件职责
|
||
|
||
- `IntegratedQuicGatewayLifecycle`：跟随 Spring 生命周期启停全部 QUIC 组件。
|
||
- `QuicGatewayServer`：TLS、QUIC 连接、控制流和 DATAGRAM 接入。
|
||
- `ControlStreamHandler`：解析注册、心跳和设备快照控制帧。
|
||
- `MediaReassembler`：按帧重组媒体 DATAGRAM，并限制内存和超时。
|
||
- `NodeEventBroker`：Spring 单例，向当前 JVM 内的订阅者直接发布节点和媒体事件。
|
||
- `RobotQuicEventSubscriber`：订阅当前 JVM 中的 QUIC 节点事件。
|
||
- `RobotQuicStateService`：按永久 `robotId` 更新机器人、设备在线状态和 gRPC endpoint，并清理旧 gRPC channel。
|
||
|
||
协议定义位于：
|
||
|
||
```text
|
||
cmvr-iot-quic-contract/src/main/proto/cmvr/quic_edge/v1/quic_edge.proto
|
||
cmvr-iot-quic-contract/src/main/proto/cmvr/quic_gateway/v1/quic_gateway.proto
|
||
```
|
||
|
||
## 启用配置
|
||
|
||
配置入口为 `cmvr-iot-admin/src/main/resources/application.yml`。没有证书时必须保持关闭：
|
||
|
||
```yaml
|
||
cmvr:
|
||
quic:
|
||
enabled: false
|
||
```
|
||
|
||
启用示例：
|
||
|
||
```yaml
|
||
cmvr:
|
||
quic:
|
||
enabled: true
|
||
bind-host: 0.0.0.0
|
||
port: 4433
|
||
grpc-host-source: observed-source
|
||
alpn: cmvr-quic-edge/1
|
||
allowed-node-ids: robot-edge-001,robot-edge-002
|
||
tls:
|
||
certificate: D:/cmvr-iot/certs/quic-gateway.crt
|
||
private-key: D:/cmvr-iot/certs/quic-gateway.key
|
||
require-client-certificate: true
|
||
client-ca: D:/cmvr-iot/certs/edge-client-ca.crt
|
||
```
|
||
|
||
Linux 部署时将证书路径换成实际绝对路径。对应配置也可以由 `CMVR_QUIC_*` 环境变量或 JVM 参数覆盖。
|
||
|
||
启用前必须确认：
|
||
|
||
- 证书和私钥文件存在且匹配。
|
||
- 证书适用于边缘节点访问的主机名或 IP。
|
||
- ALPN 与 `cmvr-es` 完全一致。
|
||
- 防火墙放行 `4433/udp`。
|
||
- `allowed-node-ids` 已配置允许接入的节点；生产环境不要留空。
|
||
|
||
## 节点绑定
|
||
|
||
首次使用前执行：
|
||
|
||
```text
|
||
sql/robot_quic_identity_migration.sql
|
||
sql/robot_id_only_migration.sql
|
||
```
|
||
|
||
先在机器人管理页面新增机器人并填写边缘端上报的永久 `robotId`。机器人首次连接后，平台自动补全地址、端口、QUIC 会话信息和设备清单，无需绑定终端：
|
||
|
||
```sql
|
||
INSERT INTO inspection_robot (id, robot_name, robot_id, connect_status, archived_status)
|
||
VALUES ('业务主键', '测试机器人', '边缘端永久机器人ID', '0', '0');
|
||
```
|
||
|
||
平台不会根据陌生 `robotId` 自动创建机器人，未登记的机器人只记录警告；已登记机器人上报的新设备会自动写入设备快照表，未继续上报的设备会标记为离线。
|
||
|
||
机器人上线后，平台会根据 `cmvr.quic.grpc-host-source` 更新机器人的 gRPC 地址：
|
||
|
||
- `observed-source`：使用 Gateway 观察到的连接源 IP，适合 QUIC 与机器人 gRPC 同机部署。
|
||
- `advertised`：使用节点注册时主动上报的 gRPC host。
|
||
|
||
endpoint 变化或机器人离线时，`GrpcServiceManager` 中按 `robotId` 缓存的 channel 会立即失效，下次业务调用使用最新地址建立连接。
|
||
|
||
## 构建与测试
|
||
|
||
QUIC native artifact 带操作系统 classifier，应在最终部署系统或相同架构的构建机上打包。
|
||
|
||
```bash
|
||
# QUIC 模块及其依赖
|
||
mvn -pl cmvr-iot-quic -am test
|
||
|
||
# 完整应用
|
||
mvn clean package -DskipTests
|
||
java -jar cmvr-iot-admin/target/cmvr-iot-admin.jar
|
||
```
|
||
|
||
只发布 `cmvr-iot-admin.jar`，不需要额外启动 Gateway jar。
|
||
|
||
## 运行检查
|
||
|
||
启动日志应包含：
|
||
|
||
```text
|
||
已通过进程内事件总线订阅 QUIC 节点事件
|
||
集成式 QUIC Gateway 已随 CMVR 应用启动
|
||
```
|
||
|
||
常见问题：
|
||
|
||
- 缺少证书或私钥：Gateway 配置校验失败，主应用停止启动。
|
||
- UDP 端口占用：修改 `cmvr.quic.port` 或释放原端口。
|
||
- native library 加载失败：确认构建产物与 Windows/Linux 和 CPU 架构匹配。
|
||
- 节点在线但未同步：检查 `quic_node_id` 绑定、节点白名单和节点上报内容。
|