# Realtime Gateway 运行手册

本文档用于整理当前 `realtime-gateway` 的构建、运行、联调和排障方式，覆盖今天已经落地的能力。

## 1. 当前组成

当前工程由 3 部分组成：

- 新实时网关
  - 路径：`D:\dev\cmr-mini\realtime-gateway`
- 老模拟器
  - 路径：`D:\dev\cmr-mini\tools\mock-gps-sim`
- 文档目录
  - 路径：`D:\dev\cmr-mini\doc`

当前推荐的本地开发方式：

- 老模拟器继续负责地图拖点、路径回放、心率模拟
- 新网关负责实时中转、channel 管理、实时查看、流量统计

## 1.1 中转服务器在整个系统中的用法

中转服务器在整个系统里，应当被当成“实时中枢”来使用，而不是业务主服务器的一部分。

当前建议的角色分工：

- `Producer`
  - 老模拟器
  - 后续真机设备
  - 后续回放器
- `Consumer`
  - 管理台
  - CLI 调试端
  - 后续家长端 / 场控端 / 手机观察端
- `Controller`
  - 管理台
  - 后续场控后台
  - 后续回放控制器
- `Business Server`
  - 用户、设备关系、配置、历史存档

系统里的基本流向应当是：

`Producer -> Gateway -> Consumer / Plugin -> Business Server`

也就是说：

- 实时数据先进入网关
- 网关负责实时观察和分发
- 业务服务器负责低频业务数据和历史

## 2. 端口约定

本地开发建议统一使用以下端口：

- 老模拟器 HTTP / WS：`17865`
- 新网关 HTTP / WS：`18080`

对应地址：

- 老模拟器页面：`http://127.0.0.1:17865/`
- 老模拟器本地 mock WS：`ws://127.0.0.1:17865/mock-gps`
- 新网关管理台：`http://127.0.0.1:18080/`
- 新网关 WebSocket：`ws://127.0.0.1:18080/ws`

## 3. 构建命令

### 3.1 构建网关

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

### 3.2 构建调试 CLI

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

### 3.3 一次性编译检查

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

## 4. 运行命令

### 4.1 启动新网关

开发期建议直接使用 Tunnel 开发配置：

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

如果只想本机用默认开发配置：

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

### 4.2 启动老模拟器

在仓库根目录：

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

### 4.3 打开页面

- 新网关管理台：`http://127.0.0.1:18080/`
- 老模拟器页面：`http://127.0.0.1:17865/`

如果页面和实际代码不一致，先强刷一次：

```text
Ctrl + F5
```

## 5. 当前管理台能力

新网关管理台已经包含：

- 会话列表
- channel 创建与查看
- latest state 查看
- 实时数据窗口
- GPS / 心率专用格式化显示
- 轨迹预览
- 流量统计
  - Published
  - Dropped
  - Fanout
  - Topic 统计
  - Channel 统计

相关接口：

- `/api/admin/overview`
- `/api/admin/sessions`
- `/api/admin/latest`
- `/api/admin/channels`
- `/api/admin/traffic`
- `/api/admin/live`

## 6. 本地联调方式

### 6.1 方式 A：直接用 CLI

1. 启动网关

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

2. 启动 consumer

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

3. 发 GPS

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

4. 发心率

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

### 6.2 方式 B：老模拟器桥接新网关

这是当前最推荐的开发联调方式。

1. 启动网关
2. 启动老模拟器
3. 在老模拟器页面里打开“新网关桥接”
4. 填入：

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

5. 点“应用桥接配置”

这样可以同时保留：

- 老 mock 小程序链路
- 新网关旁路链路

### 6.3 现在最推荐的使用方式

今天这个阶段，最推荐这样用：

1. 老模拟器作为主 Producer
2. 新网关作为实时中转和观测面板
3. 管理台负责创建 channel、查看会话、观察实时流量
4. 业务服务器暂时不接入高频实时链路

这个组合的好处是：

- 不影响你现有模拟和调试方式
- 新网关可以独立收敛协议和运行态
- 出问题时边界清晰，便于排查

## 7. channel 模式怎么用

当前网关支持两种生产者接入模式。

### 7.1 老模式

不使用 channel，直接走 `authenticate`：

```json
{"type":"authenticate","role":"producer","token":"dev-producer-token"}
```

适合：

- 早期本机调试
- 兼容老桥接工具

### 7.2 新模式

先创建 channel，再用 `join_channel`：

```json
{"type":"join_channel","role":"producer","channelId":"ch-xxxx","token":"<producerToken>"}
```

适合：

- 多人联调
- 多会话隔离
- `drop_if_no_consumer` / `cache_latest` 策略

### 7.3 管理台创建 channel

在管理台可直接创建 channel，返回：

- `channelId`
- `producerToken`
- `consumerToken`
- `controllerToken`

### 7.4 老模拟器接 channel

老模拟器现在已经支持：

- 不填 `Channel ID`：走老的 `authenticate`
- 填 `Channel ID`：自动走 `join_channel`

所以如果你在管理台里创建了 channel：

- `Channel ID` 填 `channelId`
- `Producer Token / Channel Token` 填 `producerToken`

两者必须配套使用。

## 8. delivery mode 说明

当前 channel 支持两种分发策略：

- `cache_latest`
  - 即使没有消费者，也会保留 latest state
- `drop_if_no_consumer`
  - 没有消费者就直接丢弃，不保留 latest state

适用建议：

- 开发调试或临时通道：可用 `drop_if_no_consumer`
- 常规联调和状态观察：建议 `cache_latest`

## 9. 管理台实时窗口说明

“实时数据窗口”当前支持：

- 按 `topic` 过滤
- 按 `channelId` 过滤
- 按 `deviceId` 过滤
- 实时事件滚动显示
- GPS 专用摘要
  - 经纬度
  - 速度
  - 航向
  - 精度
- 心率专用摘要
  - bpm
- 轨迹预览
  - 按 `channelId / deviceId` 聚合

建议使用方式：

- 如果联调设备较多，先填 `channelId`
- 如果只看单个对象，再加 `deviceId`

## 10. 流量统计说明

网关已累计以下指标：

- `Published`
  - 收到的总发布数
- `Dropped`
  - 因策略被丢弃的发布数
- `Fanout`
  - 实际分发到消费者的总次数

同时支持：

- 按 `topic` 统计
- 按 `channel` 统计

这几个指标适合用来观察：

- 老模拟器是否在稳定发流
- 哪个 topic 最热
- 哪个 channel 在大量占用实时流量
- `drop_if_no_consumer` 是否正在生效

## 11. 常用命令备忘

### 11.1 启动网关

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

### 11.2 启动老模拟器

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

### 11.3 编译检查

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

### 11.4 直接发 GPS

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

### 11.5 直接发心率

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

### 11.6 channel 模式下的 producer

```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
```

### 11.7 channel 模式下的 consumer

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

## 12. 常见问题

### 12.1 老模拟器显示 `authentication failed`

通常是这两种情况：

- 你填了 `producerToken`，但没填 `channelId`
- 你填的是 channel 的 token，却还在走老的 `authenticate`

处理方式：

- 如果用 channel：
  - 必须同时填 `Channel ID` 和对应 `producerToken`
- 如果不用 channel：
  - `Channel ID` 留空
  - token 使用全局 `dev-producer-token`

### 12.2 模拟器还连到 8080

当前开发统一使用 `18080`。

如果页面还显示旧地址：

- 重启模拟器服务
- 浏览器强刷 `Ctrl + F5`

### 12.3 管理台创建 channel 成功，但页面没显示

这通常是浏览器缓存旧前端资源。

处理方式：

- 重启网关
- 打开 `http://127.0.0.1:18080/`
- 按一次 `Ctrl + F5`

### 12.4 管理台看不到实时数据

先检查：

- 网关是否启动在 `18080`
- 老模拟器桥接是否已认证
- 管理台实时窗口是否误填了 `channelId / deviceId` 过滤

## 13. 当前建议

今天这个阶段，最稳的开发方式是：

- 老模拟器继续做主生产者
- 新网关继续做中转和观测
- 手机端暂时不接正式消费链路
- 先把网关本身的运行态、流量、实时查看能力做稳

这也是当前最省风险的组合。