CMVR-IOT/cmvr-iot-quic/README.md

# 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` 绑定、节点白名单和节点上报内容。