zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
af43beadb05badf4139beb5c368b833bbf9bd6d1
cmr-mini/doc/gateway/实时网关运行手册.md

9.3 KiB
Raw Blame History

Realtime Gateway 运行手册

文档版本：v1.0 最后更新：2026-04-02

本文档用于整理当前 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 统计

相关接口：

  • /api/admin/overview
  • /api/admin/sessions
  • /api/admin/latest
  • /api/admin/channels
  • /api/admin/traffic
  • /api/admin/live

6. 本地联调方式

6.1 方式 A：直接用 CLI

  1. 启动网关
cd D:\dev\cmr-mini\realtime-gateway
go run .\cmd\gateway -config .\config\tunnel-dev.json
  1. 启动 consumer
cd D:\dev\cmr-mini\realtime-gateway
go run .\cmd\mock-consumer -config .\config\consumer-gps-heart.example.json
  1. 发 GPS
cd D:\dev\cmr-mini\realtime-gateway
go run .\cmd\mock-producer -device-id child-001 -topic telemetry.location -count 5
  1. 发心率
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
  1. 点“应用桥接配置”

这样可以同时保留：

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

6.3 现在最推荐的使用方式

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

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

这个组合的好处是：

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

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

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

处理方式：

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

12.4 管理台看不到实时数据

先检查：

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

13. 当前建议

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

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

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

Reference in New Issue View Git Blame Copy Permalink