CMVR-IOT/cmvr-iot-quic

CMVR 集成式 QUIC Gateway

cmvr-iot-quic 是 cmvr-iot-admin 的运行时模块，不单独部署。Spring Boot 主应用启动和停止时，IntegratedQuicGatewayLifecycle 在同一 JVM 中管理 QUIC 监听器，节点和媒体事件通过 Spring 单例事件代理直接分发。

数据链路

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。

协议定义位于：

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。没有证书时必须保持关闭：

cmvr:
  quic:
    enabled: false

启用示例：

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 已配置允许接入的节点；生产环境不要留空。

节点绑定

首次使用前执行：

sql/quic_gateway_terminal_migration.sql

然后把边缘节点的稳定 node_id 绑定到已有终端：

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，应在最终部署系统或相同架构的构建机上打包。

# 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。

运行检查

启动日志应包含：

已通过进程内事件总线订阅 QUIC 节点事件
集成式 QUIC Gateway 已随 CMVR 应用启动

常见问题：

• 缺少证书或私钥：Gateway 配置校验失败，主应用停止启动。
• UDP 端口占用：修改 cmvr.quic.port 或释放原端口。
• native library 加载失败：确认构建产物与 Windows/Linux 和 CPU 架构匹配。
• 节点在线但未同步：检查 quic_node_id 绑定、节点白名单和节点上报内容。