# Realtime Gateway
> 文档版本：v1.0
> 最后更新：2026-04-02 08:28:05


`realtime-gateway` 是一个独立于现有模拟器的 Go 实时设备数据网关工程。

当前目标：

- 以实时中转为核心
- 纯内存运行
- 单二进制部署
- 支持 WebSocket 接入
- 支持 channel 模型
- 支持内置管理台、实时窗口、流量统计
- 为后续规则、通知、归档、回放预留插件总线

## 文档入口

优先看这几份：

- 运行手册：[实时网关运行手册.md](D:/dev/cmr-mini/doc/gateway/实时网关运行手册.md)
- 架构方案：[实时设备网关架构.md](D:/dev/cmr-mini/doc/gateway/实时设备网关架构.md)
- 协议说明：[网关协议规范.md](D:/dev/cmr-mini/doc/gateway/网关协议规范.md)
- Tunnel 联调：[Cloudflare隧道开发说明.md](D:/dev/cmr-mini/doc/gateway/Cloudflare隧道开发说明.md)
- 老模拟器桥接说明：[README.md](D:/dev/cmr-mini/tools/mock-gps-sim/README.md)

## 快速开始

### 1. 启动网关

```powershell
cd D:\dev\cmr-mini\realtime-gateway
go run .\cmd\gateway -config .\config\tunnel-dev.json
```

### 2. 打开管理台

```text
http://127.0.0.1:18080/
```

### 3. 启动老模拟器

```powershell
cd D:\dev\cmr-mini
npm run mock-gps-sim
```

### 4. 打开模拟器页面

```text
http://127.0.0.1:17865/
```

### 5. 用老模拟器桥接新网关

在“新网关桥接”区域填写：

- 网关地址：`ws://127.0.0.1:18080/ws`
- `Producer Token / Channel Token`
- `Channel ID` 可选
- `Device ID`

## 目录结构

```text
realtime-gateway/
├── cmd/gateway
├── cmd/mock-consumer
├── cmd/mock-producer
├── config
├── deploy
├── internal/channel
├── internal/config
├── internal/gateway
├── internal/model
├── internal/plugin
├── internal/router
└── internal/session
```

## 构建

```powershell
cd D:\dev\cmr-mini\realtime-gateway
go build -o .\bin\gateway.exe .\cmd\gateway
go build -o .\bin\mock-producer.exe .\cmd\mock-producer
go build -o .\bin\mock-consumer.exe .\cmd\mock-consumer
```

或直接做一次完整编译检查：

```powershell
cd D:\dev\cmr-mini\realtime-gateway
go build ./...
```

## 默认地址

推荐开发配置：

- 网关 HTTP / Admin：`http://127.0.0.1:18080/`
- 网关 WebSocket：`ws://127.0.0.1:18080/ws`
- 模拟器页面：`http://127.0.0.1:17865/`
- 模拟器 mock WS：`ws://127.0.0.1:17865/mock-gps`

## CLI 调试

### producer

```powershell
cd D:\dev\cmr-mini\realtime-gateway
go run .\cmd\mock-producer -device-id child-001 -topic telemetry.location -count 5
go run .\cmd\mock-producer -device-id child-001 -topic telemetry.heart_rate -bpm 148 -count 5
```

### consumer

```powershell
cd D:\dev\cmr-mini\realtime-gateway
go run .\cmd\mock-consumer -config .\config\consumer-gps-heart.example.json
```

### channel 模式

```powershell
cd D:\dev\cmr-mini\realtime-gateway
go run .\cmd\mock-producer -channel-id ch-xxxx -token <producer-token> -topic telemetry.location -count 5
go run .\cmd\mock-consumer -channel-id ch-xxxx -token <consumer-token> -topics telemetry.location,telemetry.heart_rate
```

## 当前已落地能力

- WebSocket 接入
- `authenticate`
- `join_channel`
- `subscribe`
- `publish`
- `snapshot`
- latest state 缓存
- channel 管理
- `cache_latest`
- `drop_if_no_consumer`
- 管理台
- 实时数据窗口
- GPS 轨迹预览
- 流量统计

更多运行和排障细节，直接看：

- [实时网关运行手册.md](D:/dev/cmr-mini/doc/gateway/实时网关运行手册.md)