Wobserver 实时架构揭秘:Cowboy WebSocket 如何实现零刷新监控仪表盘
Wobserver 实时架构揭秘:Cowboy WebSocket 如何实现零刷新监控仪表盘
Wobserver 是一款基于 Elixir 的 Web 实时监控工具,它用一条 Cowboy WebSocket 长连接驱动整个监控仪表盘,让 CPU、内存、进程、端口等数据在页面上零刷新地实时跳动。本文将带新手快速看懂这条"数据管道"是如何搭起来的:从服务端握手、JSON 命令协议,到前端心跳保活、断线重连与 REST 降级,最后还会聊聊它如何穿透防火墙监控远程节点。
为什么监控仪表盘需要"零刷新"?
传统监控页面往往靠 setInterval 定时发 HTTP 请求轮询数据,每轮一次就付出一次完整的 TCP/TLS 握手 + HTTP 开销;要么就是整页定时 reload,体验非常生硬。
Wobserver 的思路很直接:整站只开一条 WebSocket 长连接,所有页面(System、Processes、Ports、Table Viewer……)共用它,数据到了就渲染,页面从头到尾不需要刷新一次。这就是"零刷新仪表盘"的由来 📡
整体架构一览:一条 /ws 承载全站数据
Wobserver 默认以 :standalone 模式运行,启动时自建一个 Cowboy 监听器(默认 10 个 acceptor、端口 4001),并在 dispatch 表里做了清晰的路由划分:
| 路径 | 处理器 | 职责 |
|---|---|---|
/ws |
Wobserver.Web.Client |
WebSocket 实时数据通道 |
/api |
Wobserver.Web.Router.Api |
JSON REST API(降级/自动化用) |
/metrics |
Wobserver.Web.Router.Metrics |
Prometheus 格式指标输出 |
/ |
Wobserver.Web.Router.Static |
静态前端资源 |
核心配置只有短短几行,就在启动 Cowboy 的 cowboy_child_spec 里:
dispatch: [
{:_, [
{"/ws", Wobserver.Web.Client, []},
{:_, Cowboy.Handler, {Wobserver.Web.Router, []}}
]}
]
相关实现见 lib/wobserver/application.ex 与 lib/wobserver/web/router.ex。
服务端:Cowboy WebSocket 处理器三件套
握手与认证:升级协议前先验票
每个 WebSocket 连接在 init/3 阶段都会先过一道安全校验(默认模块为 Wobserver.Security),通过后才返回 {:upgrade, :protocol, :cowboy_websocket} 把 HTTP 升级为 WebSocket 协议;认证模块可自定义替换。默认实现基于"IP + User-Agent + 密钥"生成 HMAC cookie(_wobserver),防止匿名直连。
命令解析:极简的 JSON 文本协议
客户端发来的不是复杂协议,而是一条 JSON 文本:{"command": "system", "data": null}。服务端的 parse_command/1 把 command 按 / 拆成 atom(例如 application/wobserver 会变成 [:application, "wobserver"]),再交给业务回调 client_handle/2 处理。
业务层非常薄——hello 回 ehlo、ping 回 pong、system 回系统总览、process 回进程列表,每个命令就是一行数据收集函数,见 lib/wobserver/web/client.ex。
响应封装:统一加上 type 与 timestamp
所有回包都被 send_response/3 统一包装成三段式结构,前端靠 type 字段路由消息:
| 字段 | 含义 | 示例 |
|---|---|---|
type |
命令类型,用于前端匹配 | "system" |
timestamp |
服务端时间戳(秒) | 1729600000 |
data |
实际负载 | %{scheduler: [...], memory: %{...}} |
实现见 lib/wobserver/web/client_socket.ex。命令解析逻辑在 parse_command/1。
客户端:JavaScript 如何管理这条长连接
心跳保活:55 秒 ping 对上 60 秒超时
服务端给每个 socket 设了 @timeout 60_000(60 秒无消息即断开),客户端则在连接建立后每 55 秒发一次 ping,刚好在超时前"续命",见 src/js/wobserver_client.js。
断线重连 + REST 降级双保险
- 断线重连:socket 异常关闭后自动重建连接,失败则每 5 秒重试一次,重连成功后弹出/关闭"连接已恢复"提示(reconnect);
- REST 降级:如果 WebSocket 根本连不上(比如被中间代理拦截),前端会自动切换到
WobserverApiFallback,走/api/...的fetch请求返回同等数据,界面照常工作,见 src/js/wobserver_api_fallback.js。
Promise 队列:让"发命令"变成"等数据"
command_promise/2 会把每个命令的 resolve 函数按 type 入队,收到对应回包时弹出并执行,于是渲染代码可以写成优雅的 command_promise('process').then(e => render(e)),完全不用关心连接细节。
零刷新的秘密:页面级刷新因子
前端主类 Wobserver 里有一个 update_interval = 1000(1 秒基准),open(command, refresh, renderer) 先渲染一次,然后按 refresh × 1000ms 定时在同一 socket 上重发命令:
open(command, refresh, renderer) {
this.display(command, renderer);
if( refresh > 0 ) {
this.refreshTimer = setInterval(
() => this.display(command, renderer), refresh * this.update_interval);
}
}
不同页面按"数据变化频率"分配了不同的刷新因子,见 src/js/wobserver.js 与 src/js/wobserver_render.js:
| 页面 | 刷新因子 | 实际间隔 | 设计考量 |
|---|---|---|---|
| Load Charts(负载图表) | 0.25 | 250ms | 曲线要平滑,必须高频 |
| System(系统总览) | 1 | 1s | 核心指标,秒级感知 |
| Memory Allocators | 0.25 | 250ms | 分配器图表同样高频 |
| Processes | 4 | 4s | 进程列表变化慢 |
| Ports | 8 | 8s | 端口几乎静态 |
| Applications / Table | 0 | 不自动刷新 | 仅手动加载 |
自定义页面也能在注册时设置同样的 refresh 因子,让插件页面"即插即实时"。图表页更聪明:Canvas 只初始化一次,后续每次回包仅调用 chart.update(data) 追加数据点,而不是重建 DOM——这正是仪表盘"丝滑"的关键 ✅
集群玩法:一条 WebSocket 代理到远程节点
Wobserver 支持在防火墙、负载均衡之后发现并监控远程节点,玩法是"代理链":
- 前端点击 "Switch Node",向本地 socket 发送
setup_proxy命令(set_node); - 本地服务端用
websocket_client连上远端节点的/ws(Wobserver.Util.Node.Remote.socket_proxy/1),由 Wobserver.Web.ClientProxy 维持这条上游连接; - 之后浏览器发来的每一条命令都被原样转发给远端,远端回包再原路送回浏览器——浏览器始终只面对本地这一个 socket。
如果远端代理意外断开,服务端会通知前端并自动解除代理状态,链路见 websocket_info。若你的主应用是 Phoenix,还可以直接挂载官方提供的 Phoenix Socket 适配器:lib/wobserver/web/phoenix_socket.ex。
快速上手:三步接入 Wobserver
- 加依赖:在
mix.exs中加入{:wobserver, "~> 0.1"},并把:wobserver加入applications; - 拉依赖并启动:执行
mix deps.get后正常启动应用; - 打开仪表盘:浏览器访问
http://<host>:4001/,菜单底部会显示 "Connected to: local",说明 WebSocket 已连通。
默认端口可通过 config :wobserver, port: 80 修改;若你的应用已有 Web 服务器,可切换到 :plug 模式,不再自建 Cowboy,把 Wobserver.Web.Router 转发进你的路由即可(完整示例见 README.md 的 Plug Mode 章节)。
小结
Wobserver 的"零刷新"并不神秘,它由四个简单而扎实的设计拼成:
- 🧱 单通道多路复用:全站一条
/ws,Cowboy 10 个 acceptor 轻松扛住多浏览器并发; - 📮 极简 JSON 协议:
command/data进,type/timestamp/data出,前后端各自路由; - 🔁 心跳 + 重连 + REST 降级:55 秒 ping 保活、5 秒重试重连、被拦截时自动退化为 API 轮询;
- ⚙️ 页面级刷新因子:250ms 的图表与 8s 的端口表共享一条连接,按需取数不浪费。
理解这套架构后,你会发现它同样是学习 Elixir/BEAM 上做实时 Web 系统的一个绝佳范本:进程轻量到可以为每个 socket 独占一个进程,而 Cowboy 把协议层的脏活全部收走了。想深入源码,建议从 Wobserver.Web.ClientSocket 与 WobserverClient 这对"孪生文件"读起。