zhangyan 6964e26ec9 同步前后端联调与文档更新		пре 5 дана
..
public	6964e26ec9 同步前后端联调与文档更新	пре 5 дана
README.md	6964e26ec9 同步前后端联调与文档更新	пре 5 дана
server.js	a70dc8d5d0 完善后端联调链路与模拟器多通道支持	пре 6 дана

Mock GPS Simulator

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

启动

在仓库根目录运行：

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
小程序端按同一个模拟通道号过滤三条链

默认通道号：

default

如果需要多人并行联调，可以在模拟器工作台里把“模拟通道号”改成例如：

runner-a
runner-b
group-01

然后在小程序调试面板里把“模拟通道号”也配成同一个值。

当前“模拟通道号”位于工作台顶部，属于全局调试参数，不再归属某个单独分组。

当前能力

直接载入 game.json
自动解析 map / mapmeta / course
自动切换自定义瓦片
自动渲染 KML 控制点
一键跳到开始点 / 结束点 / 任意检查点
地图点击跳点
实时连续发送 mock_gps
路径编辑
上传轨迹文件回放（GPX / KML / GeoJSON）
路径回放
速度、频率、精度调节
可选桥接到新实时网关
接收小程序侧 debug-log 调试日志

调试日志

调试日志 websocket 独立地址：

ws://127.0.0.1:17865/debug-log

发送消息格式：

{
  "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
页面里可以直接配置并启用新网关桥接
环境变量只作为服务启动时的默认值

页面里直接配置

启动模拟器后，打开：

http://127.0.0.1:17865/

在“新网关桥接”区域可以直接配置：

是否启用桥接
网关地址
Producer Token
Channel ID
目标 Device ID
Group ID
Source ID
Source Mode
本地桥接预设

点“应用桥接配置”后立即生效，不需要重启模拟器。

预设说明：

预设保存在浏览器本地存储
适合多人联调时快速切换 deviceId / groupId / sourceId
“套用预设”只会填入表单，不会自动提交到服务端
需要再点一次“应用桥接配置”才会真正切换运行时桥接目标

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，则要这样填：

$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

桥接状态查看

启动后可查看：

http://127.0.0.1:17865/bridge-status

桥接配置接口：

http://127.0.0.1:17865/bridge-config

返回内容包含：

是否启用桥接
是否已连上新网关
是否已认证
最近发送 topic
已发送条数
丢弃条数
最近错误

加载自己的地图

推荐方式：

启动模拟器后，打开 http://127.0.0.1:17865/
在“资源加载”里填自己的 game.json 地址
点“载入配置”

模拟器会自动：

读取 map 和 mapmeta
切换到你的瓦片底图
读取 course
渲染开始点、检查点、结束点

如果你不想走整套配置，也可以：

直接填“瓦片模板”，例如 https://host/tiles/{z}/{x}/{y}.webp
直接填 KML URL

路径回放也支持直接导入轨迹文件：

GPX
KML
GeoJSON / JSON

说明：

配置和 KML 是通过本地代理拉取的，所以浏览器跨域问题会少很多
如果你的资源需要鉴权，第一版代理还没有加认证头透传

真机调试注意

如果小程序跑在手机上，不要用 127.0.0.1。
把小程序里的 mock bridge 地址改成你电脑在局域网里的 IP，例如：

ws://192.168.1.23:17865/mock-gps

心率模拟地址应配置为：

ws://192.168.1.23:17865/mock-hr

同理，浏览器里的模拟器页面也建议用电脑局域网地址打开，例如：

http://192.168.1.23:17865/

如果你要在小程序里看调试日志，Logger 地址应配置为：

ws://192.168.1.23:17865/debug-log

README.md