298 lines
7.1 KiB
Markdown
298 lines
7.1 KiB
Markdown
# Mock GPS Simulator
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-02 08:28:05
|
||
|
||
|
||
## 启动
|
||
|
||
在仓库根目录运行：
|
||
|
||
```bash
|
||
npm run mock-gps-sim
|
||
```
|
||
|
||
启动后：
|
||
|
||
- 新版工作台: `http://127.0.0.1:17865/`
|
||
- 小程序定位模拟地址: `ws://127.0.0.1:17865/mock-gps`
|
||
- 小程序心率模拟地址: `ws://127.0.0.1:17865/mock-hr`
|
||
- 小程序调试日志地址: `ws://127.0.0.1:17865/debug-log`
|
||
- 资源代理: `http://127.0.0.1:17865/proxy?url=<remote-url>`
|
||
|
||
补充说明：
|
||
|
||
- 模拟器工作台内部现在会按当前页面地址自动推导 websocket 地址。
|
||
- 本地访问 `http://127.0.0.1:17865/` 时，会自动连接：
|
||
- `ws://127.0.0.1:17865/mock-gps`
|
||
- `ws://127.0.0.1:17865/mock-hr`
|
||
- `ws://127.0.0.1:17865/debug-log`
|
||
- 外网访问例如 `https://gs.gotomars.xyz/` 时，会自动连接同源：
|
||
- `wss://gs.gotomars.xyz/mock-gps`
|
||
- `wss://gs.gotomars.xyz/mock-hr`
|
||
- `wss://gs.gotomars.xyz/debug-log`
|
||
- 因此外网页面不能再把 `https://gs.gotomars.xyz/` 当作 websocket 地址手工填写；应直接使用对应的 `wss://...` 路径，或让工作台按同源自动连接。
|
||
|
||
## 多通道联调
|
||
|
||
模拟器现在支持一个最小的多通道隔离方案：
|
||
|
||
- GPS 模拟消息带 `channelId`
|
||
- 心率模拟消息带 `channelId`
|
||
- 调试日志消息带 `channelId`
|
||
- 小程序端按同一个模拟通道号过滤三条链
|
||
|
||
默认通道号：
|
||
|
||
```text
|
||
default
|
||
```
|
||
|
||
如果需要多人并行联调，可以在模拟器工作台里把“模拟通道号”改成例如：
|
||
|
||
```text
|
||
runner-a
|
||
runner-b
|
||
group-01
|
||
```
|
||
|
||
然后在小程序调试面板里把“模拟通道号”也配成同一个值。
|
||
|
||
当前“模拟通道号”位于工作台顶部，属于全局调试参数，不再归属某个单独分组。
|
||
|
||
## 当前能力
|
||
|
||
- 直接载入 `game.json`
|
||
- 自动解析 `map / mapmeta / course`
|
||
- 自动切换自定义瓦片
|
||
- 自动渲染 KML 控制点
|
||
- 一键跳到开始点 / 结束点 / 任意检查点
|
||
- 地图点击跳点
|
||
- 实时连续发送 `mock_gps`
|
||
- 路径编辑
|
||
- 上传轨迹文件回放（GPX / KML / GeoJSON）
|
||
- 路径回放
|
||
- 速度、频率、精度调节
|
||
- 可选桥接到新实时网关
|
||
- 接收小程序侧 `debug-log` 调试日志
|
||
|
||
## 调试日志
|
||
|
||
调试日志 websocket 独立地址：
|
||
|
||
```text
|
||
ws://127.0.0.1:17865/debug-log
|
||
```
|
||
|
||
发送消息格式：
|
||
|
||
```json
|
||
{
|
||
"type": "debug-log",
|
||
"timestamp": 1712345678901,
|
||
"channelId": "runner-a",
|
||
"scope": "gps-logo",
|
||
"level": "info",
|
||
"message": "wx.getImageInfo success",
|
||
"payload": {
|
||
"src": "https://example.com/logo.png"
|
||
}
|
||
}
|
||
```
|
||
|
||
当前 UI 会通过独立日志通道把这类消息显示到“调试日志”区域。
|
||
|
||
日志区域当前是：
|
||
|
||
- 地图右下角浮层
|
||
- 可展开 / 缩小
|
||
- 支持按 `scope` 过滤
|
||
- 按当前 `channelId` 隔离显示
|
||
|
||
第一阶段主要用于承接：
|
||
|
||
- `gps-logo`
|
||
|
||
后面可以继续扩到：
|
||
|
||
- `compass`
|
||
- `h5`
|
||
- `content-card`
|
||
- `heart-rate`
|
||
|
||
## 桥接到新网关
|
||
|
||
旧模拟器现在支持保留原有本地广播链路的同时，把数据旁路转发到新的 Go 实时网关。
|
||
|
||
默认行为：
|
||
|
||
- 小程序定位模拟继续连接 `ws://127.0.0.1:17865/mock-gps`
|
||
- 小程序心率模拟继续连接 `ws://127.0.0.1:17865/mock-hr`
|
||
- 调试日志单独连接 `ws://127.0.0.1:17865/debug-log`
|
||
- 页面里可以直接配置并启用新网关桥接
|
||
- 环境变量只作为服务启动时的默认值
|
||
|
||
### 页面里直接配置
|
||
|
||
启动模拟器后，打开：
|
||
|
||
```text
|
||
http://127.0.0.1:17865/
|
||
```
|
||
|
||
在“新网关桥接”区域可以直接配置：
|
||
|
||
- 是否启用桥接
|
||
- 网关地址
|
||
- Producer Token
|
||
- Channel ID
|
||
- 目标 Device ID
|
||
- Group ID
|
||
- Source ID
|
||
- Source Mode
|
||
- 本地桥接预设
|
||
|
||
点“应用桥接配置”后立即生效，不需要重启模拟器。
|
||
|
||
预设说明：
|
||
|
||
- 预设保存在浏览器本地存储
|
||
- 适合多人联调时快速切换 `deviceId / groupId / sourceId`
|
||
- “套用预设”只会填入表单，不会自动提交到服务端
|
||
- 需要再点一次“应用桥接配置”才会真正切换运行时桥接目标
|
||
|
||
### PowerShell 启动示例
|
||
|
||
在仓库根目录执行：
|
||
|
||
```powershell
|
||
$env:MOCK_SIM_GATEWAY_ENABLED='1'
|
||
$env:MOCK_SIM_GATEWAY_URL='ws://127.0.0.1:18080/ws'
|
||
$env:MOCK_SIM_GATEWAY_TOKEN='dev-producer-token'
|
||
$env:MOCK_SIM_GATEWAY_CHANNEL_ID=''
|
||
$env:MOCK_SIM_GATEWAY_DEVICE_ID='child-001'
|
||
$env:MOCK_SIM_GATEWAY_SOURCE_ID='mock-gps-sim-a'
|
||
npm run mock-gps-sim
|
||
```
|
||
|
||
如果你使用新网关管理台创建的 `channel`，则要这样填：
|
||
|
||
```powershell
|
||
$env:MOCK_SIM_GATEWAY_ENABLED='1'
|
||
$env:MOCK_SIM_GATEWAY_URL='ws://127.0.0.1:18080/ws'
|
||
$env:MOCK_SIM_GATEWAY_TOKEN='<producerToken>'
|
||
$env:MOCK_SIM_GATEWAY_CHANNEL_ID='<channelId>'
|
||
$env:MOCK_SIM_GATEWAY_DEVICE_ID='child-001'
|
||
npm run mock-gps-sim
|
||
```
|
||
|
||
说明：
|
||
|
||
- 不填 `MOCK_SIM_GATEWAY_CHANNEL_ID` 时，旧模拟器走老的 `authenticate` 模式
|
||
- 填了 `MOCK_SIM_GATEWAY_CHANNEL_ID` 时，旧模拟器自动走 `join_channel` 模式
|
||
- 管理台里复制出来的 `producerToken` 只能和对应的 `channelId` 配套使用
|
||
|
||
### 可用环境变量
|
||
|
||
- `MOCK_SIM_GATEWAY_ENABLED`
|
||
- `1` 表示启用桥接
|
||
- `MOCK_SIM_GATEWAY_URL`
|
||
- 新网关地址，默认 `ws://127.0.0.1:18080/ws`
|
||
- `MOCK_SIM_GATEWAY_TOKEN`
|
||
- Producer token，默认 `dev-producer-token`
|
||
- `MOCK_SIM_GATEWAY_CHANNEL_ID`
|
||
- 可选 channel id；填写后会改走 `join_channel`
|
||
- `MOCK_SIM_GATEWAY_DEVICE_ID`
|
||
- 转发目标 `deviceId`，默认 `child-001`
|
||
- `MOCK_SIM_GATEWAY_GROUP_ID`
|
||
- 可选 `groupId`
|
||
- `MOCK_SIM_GATEWAY_SOURCE_ID`
|
||
- source id，默认 `mock-gps-sim`
|
||
- `MOCK_SIM_GATEWAY_SOURCE_MODE`
|
||
- source mode，默认 `mock`
|
||
- `MOCK_SIM_GATEWAY_RECONNECT_MS`
|
||
- 断线重连间隔，默认 `3000`
|
||
|
||
### 桥接状态查看
|
||
|
||
启动后可查看：
|
||
|
||
```text
|
||
http://127.0.0.1:17865/bridge-status
|
||
```
|
||
|
||
桥接配置接口：
|
||
|
||
```text
|
||
http://127.0.0.1:17865/bridge-config
|
||
```
|
||
|
||
返回内容包含：
|
||
|
||
- 是否启用桥接
|
||
- 是否已连上新网关
|
||
- 是否已认证
|
||
- 最近发送 topic
|
||
- 已发送条数
|
||
- 丢弃条数
|
||
- 最近错误
|
||
|
||
## 加载自己的地图
|
||
|
||
推荐方式：
|
||
|
||
1. 启动模拟器后，打开 `http://127.0.0.1:17865/`
|
||
2. 在“资源加载”里填自己的 `game.json` 地址
|
||
3. 点“载入配置”
|
||
|
||
模拟器会自动：
|
||
|
||
- 读取 `map` 和 `mapmeta`
|
||
- 切换到你的瓦片底图
|
||
- 读取 `course`
|
||
- 渲染开始点、检查点、结束点
|
||
|
||
如果你不想走整套配置，也可以：
|
||
|
||
- 直接填“瓦片模板”，例如 `https://host/tiles/{z}/{x}/{y}.webp`
|
||
- 直接填 `KML URL`
|
||
|
||
路径回放也支持直接导入轨迹文件：
|
||
|
||
- `GPX`
|
||
- `KML`
|
||
- `GeoJSON / JSON`
|
||
|
||
说明：
|
||
|
||
- 配置和 KML 是通过本地代理拉取的，所以浏览器跨域问题会少很多
|
||
- 如果你的资源需要鉴权，第一版代理还没有加认证头透传
|
||
|
||
## 真机调试注意
|
||
|
||
如果小程序跑在手机上，不要用 `127.0.0.1`。
|
||
把小程序里的 mock bridge 地址改成你电脑在局域网里的 IP，例如：
|
||
|
||
```text
|
||
ws://192.168.1.23:17865/mock-gps
|
||
```
|
||
|
||
心率模拟地址应配置为：
|
||
|
||
```text
|
||
ws://192.168.1.23:17865/mock-hr
|
||
```
|
||
|
||
同理，浏览器里的模拟器页面也建议用电脑局域网地址打开，例如：
|
||
|
||
```text
|
||
http://192.168.1.23:17865/
|
||
```
|
||
|
||
如果你要在小程序里看调试日志，Logger 地址应配置为：
|
||
|
||
```text
|
||
ws://192.168.1.23:17865/debug-log
|
||
```
|
||
|
||
|