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