132 lines
4.2 KiB
Markdown
132 lines
4.2 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
|
||
`-- QuicGatewayNodeSyncService（进程内直接订阅）
|
||
v
|
||
de_device_terminal_config + 原有机器人 gRPC 客户端
|
||
```
|
||
|
||
QUIC 链路不启动内部 gRPC Server，也不经过本机 TCP 端口。平台调用机器人设备的原有 gRPC 客户端保持不变，两者只在终端 endpoint 同步和 channel 失效处理处协作。
|
||
|
||
## 组件职责
|
||
|
||
- `IntegratedQuicGatewayLifecycle`：跟随 Spring 生命周期启停全部 QUIC 组件。
|
||
- `QuicGatewayServer`：TLS、QUIC 连接、控制流和 DATAGRAM 接入。
|
||
- `ControlStreamHandler`：解析注册、心跳和设备快照控制帧。
|
||
- `MediaReassembler`：按帧重组媒体 DATAGRAM，并限制内存和超时。
|
||
- `NodeEventBroker`：Spring 单例，向当前 JVM 内的订阅者直接发布节点和媒体事件。
|
||
- `QuicGatewayNodeSyncService`：把在线状态和 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/quic_gateway_terminal_migration.sql
|
||
```
|
||
|
||
然后把边缘节点的稳定 `node_id` 绑定到已有终端：
|
||
|
||
```sql
|
||
UPDATE de_device_terminal_config
|
||
SET quic_node_id = 'robot-edge-001'
|
||
WHERE id = '平台终端ID';
|
||
```
|
||
|
||
平台不会根据陌生 QUIC 节点自动创建设备。未绑定节点只记录警告，不更新业务数据。
|
||
|
||
节点上线后，平台会根据 `cmvr.quic.grpc-host-source` 更新终端的 gRPC 地址：
|
||
|
||
- `observed-source`：使用 Gateway 观察到的连接源 IP，适合 QUIC 与机器人 gRPC 同机部署。
|
||
- `advertised`：使用节点注册时主动上报的 gRPC host。
|
||
|
||
endpoint 变化或节点离线时，原有 `GrpcServiceManager` 缓存的 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` 绑定、节点白名单和节点上报内容。
|