444 lines
9.2 KiB
Markdown
444 lines
9.2 KiB
Markdown
# 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. 当前建议
|
||
|
||
今天这个阶段，最稳的开发方式是：
|
||
|
||
- 老模拟器继续做主生产者
|
||
- 新网关继续做中转和观测
|
||
- 手机端暂时不接正式消费链路
|
||
- 先把网关本身的运行态、流量、实时查看能力做稳
|
||
|
||
这也是当前最省风险的组合。
|