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 构建网关

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

3.2 构建调试 CLI

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 一次性编译检查

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

4. 运行命令

4.1 启动新网关

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

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

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

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

4.2 启动老模拟器

在仓库根目录：

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

4.3 打开页面

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

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

Ctrl + F5

5. 当前管理台能力

新网关管理台已经包含：

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

6. 本地联调方式

6.1 方式 A：直接用 CLI

启动网关

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

启动 consumer

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

发 GPS

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

发心率

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：老模拟器桥接新网关

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

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

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

点“应用桥接配置”

这样可以同时保留：

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

6.3 现在最推荐的使用方式

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

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

这个组合的好处是：

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

7. channel 模式怎么用

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

7.1 老模式

不使用 channel，直接走 authenticate：

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

适合：

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

7.2 新模式

先创建 channel，再用 join_channel：

{"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 启动网关

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

11.2 启动老模拟器

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

11.3 编译检查

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

11.4 直接发 GPS

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

11.5 直接发心率

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

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

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 成功，但页面没显示

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