Realtime Gateway + Cloudflare Tunnel 本机联调说明

本文档说明如何在不正式部署到线上服务器的前提下，把本机的 realtime-gateway 暴露给外部设备或远程联调方。

适用场景：

真机调试
外网联调
家长端 / 场控端远程验证
演示环境

不适用场景：

正式生产实时链路
严格 SLA 场景
高稳定长时间压测

1. 推荐结论

当前阶段建议：

网关继续运行在本机
本机使用 Cloudflare Tunnel 暴露新网关
旧模拟器继续本地运行
旧模拟器通过桥接把数据发给本机新网关
外部客户端只访问 Cloudflare Tunnel 暴露出来的 wss 地址

这样做的好处：

不需要先买独立服务器
不需要先做正式公网部署
不改变当前本机开发结构
新旧链路可以并行使用

2. 本机网关配置

推荐先使用：

tunnel-dev.json

这个配置相比开发默认配置更适合 Tunnel 联调：

端口改为 18080
关闭匿名 consumer
token 不再使用默认开发值

建议先把其中的 token 改成你自己的值。

启动方式：

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

本机地址：

HTTP: http://127.0.0.1:18080
WebSocket: ws://127.0.0.1:18080/ws

3. Quick Tunnel 方案

Quick Tunnel 最适合当前阶段。

Cloudflare 官方文档说明：

Quick Tunnel 用于测试和开发，不建议生产使用
可以直接把本地 http://localhost:8080 之类的地址暴露出去
命令形式是 cloudflared tunnel --url http://localhost:8080

来源：

3.1 启动 Quick Tunnel

你的网关如果跑在 18080：

cloudflared tunnel --url http://localhost:18080

启动后，cloudflared 会输出一个随机 trycloudflare.com 域名。

例如：

https://random-name.trycloudflare.com

对应的 WebSocket 地址就是：

wss://random-name.trycloudflare.com/ws

注意：

对外使用时，WebSocket 必须写成 wss://
本地 origin 仍然是 http://localhost:18080

3.2 Quick Tunnel 限制

Cloudflare 官方说明里，Quick Tunnel 当前有这些限制：

仅适合测试和开发
有并发请求上限
不支持 SSE

因此它适合：

临时分享联调地址
验证 WebSocket 接入
短期演示

不适合拿来当正式生产入口。

另外，官方文档提到：

如果本机 .cloudflared 目录里已有 config.yaml，Quick Tunnel 可能不能直接使用

来源：

Quick Tunnels

4. Named Tunnel 方案

如果你后面不想每次拿随机域名，可以改用 Named Tunnel。

这时推荐的本地 cloudflared 配置示例在：

config.example.yml

示例内容：

tunnel: YOUR_TUNNEL_ID
credentials-file: C:\Users\YOUR_USER\.cloudflared\YOUR_TUNNEL_ID.json

ingress:
  - hostname: gateway-dev.example.com
    service: http://localhost:18080
  - service: http_status:404

关键点：

Tunnel 把 gateway-dev.example.com 映射到本机 http://localhost:18080
最后一条 http_status:404 是 catch-all

Cloudflare 官方文档对 published application 和 ingress 的说明见：

启动后，对外 WebSocket 地址就是：

wss://gateway-dev.example.com/ws

4.1 外部 consumer 小工具

如果你要在另一台机器上用仓库里的 mock-consumer 做联调，推荐复制：

consumer-tunnel.example.json consumer-gps-heart.example.json

填好实际的公网地址和 token，例如：

{
  "url": "wss://gateway-dev.example.com/ws",
  "token": "your-consumer-token",
  "deviceId": "child-001",
  "topics": [
    "telemetry.location",
    "telemetry.heart_rate"
  ],
  "snapshot": true
}

然后运行：

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

命令行参数会覆盖配置文件中的同名项，所以临时换 deviceId 时可以直接追加：

go run .\cmd\mock-consumer -config .\config\consumer-tunnel.example.json -device-id child-002

如果只想临时直接从命令行看 GPS 和心率：

go run .\cmd\mock-consumer -url wss://gateway-dev.example.com/ws -token your-consumer-token -device-id child-001 -topics telemetry.location,telemetry.heart_rate

5. 旧模拟器如何配合

旧模拟器仍然本地运行：

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

然后在旧模拟器页面的“新网关桥接”区域里填：

网关地址：ws://127.0.0.1:18080/ws
Producer Token：与你 tunnel-dev.json 里配置一致
目标 Device ID：按你的联调对象填写
Source ID：例如 mock-gps-sim-a

这里要注意：

旧模拟器桥接到的是本机网关地址
外部消费者连接的是Cloudflare Tunnel 暴露的公网地址

不要把旧模拟器桥接目标直接写成公网 wss 地址。
旧模拟器和网关都在本机，直接走本地回环最稳。

6. 推荐联调拓扑

旧模拟器页面
  -> 本机 mock-gps-sim
  -> 本机 realtime-gateway (ws://127.0.0.1:18080/ws)
  -> Cloudflare Tunnel
  -> 外部 consumer / 真机 / 调试端 (wss://<public-host>/ws)

这样职责最清晰：

旧模拟器只负责发模拟数据
新网关负责实时中转
Cloudflare Tunnel 只负责把本机网关暴露到外部

7. 当前阶段的安全建议

即使只是联调，也建议至少做到：

allowAnonymousConsumers = false
Producer / Consumer / Controller token 全部替换
不把默认 token 长期暴露在公网链接中
Tunnel 只暴露新网关，不一定要暴露旧模拟器 UI

如果只是你自己本机调试：

旧模拟器 UI 保持本地访问即可
只把 realtime-gateway 暴露出去

8. 结论

当前阶段最推荐的方案是：

本机用 tunnel-dev.json 启动新网关
本机旧模拟器桥接到 ws://127.0.0.1:18080/ws
用 cloudflared tunnel --url http://localhost:18080 先跑 Quick Tunnel
外部客户端使用 wss://<quick-tunnel-domain>/ws
等你需要固定域名或更稳定的入口时，再切换 Named Tunnel

这条路径最轻、最稳，也最符合你现在“先不正式上线”的目标。

cloudflare-tunnel-dev-guide.md 7.1 KB Vēsture Neapstrādāts