zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

整理中文文档结构与索引

Browse Source
This commit is contained in:
zhangyan
2026-03-30 18:49:22 +08:00
parent 3b9117427e
commit 24bc60bc7f
49 changed files with 462 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

444
doc/gateway/实时网关运行手册.md Normal file
View File

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