WebSocket API

Web.Casa 使用 WebSocket 提供实时双向通信能力。所有 WebSocket 连接使用与 REST API 相同的 JWT 令牌进行认证。

认证

在建立 WebSocket 连接时，通过查询参数传递 JWT 令牌：

ws://your-server:39921/api/plugins/filemanager/terminal/ws?token=<jwt-token>

重要： WebSocket 连接同样受 RBAC 权限控制。查看者角色的令牌无法访问仅限管理员的 WebSocket 端点（如终端）。

端点列表

终端（PTY）

/api/plugins/filemanager/terminal/ws

提供完整的 PTY 访问，前端由 xterm.js 驱动，实现网页终端功能。

特性	说明
协议	二进制帧传输输入/输出
窗口调整	支持动态窗口大小变更事件，自动调整 PTY
多会话	支持通过独立连接同时运行多个终端会话
访问权限	仅限管理员

通信流程：

1. 客户端携带 JWT 令牌建立 WebSocket 连接
2. 服务端创建 PTY 进程
3. 客户端以二进制帧发送键盘输入
4. 服务端以二进制帧推送终端输出
5. 客户端在终端窗口尺寸变化时发送 resize 事件

监控（实时指标）

/api/plugins/monitoring/metrics/ws

实时向连接的客户端推送系统指标数据。

指标	说明
CPU	各核心和总体使用百分比
内存	已用、可用、总量和交换分区
磁盘	使用量、I/O 速率和挂载点
网络	各接口的入站/出站流量速率

• 服务端定时推送 JSON 消息
• 相比 REST 轮询，延迟更低、开销更小

Docker（容器日志流）

/api/plugins/docker/containers/:id/logs

实时推送容器的 stdout/stderr 输出，等效于 docker logs -f。

参数	说明
:id	容器 ID 或名称

• 同时推送 stdout 和 stderr
• 支持时间戳显示
• 连接保持打开状态，持续跟踪日志

消息格式

所有 WebSocket 消息使用以下两种格式之一：

• 二进制帧 — 用于终端 I/O（原始 PTY 数据）
• JSON 文本帧 — 用于监控指标、部署日志和容器日志

监控消息示例：

{
  "type": "metrics",
  "data": {
    "cpu": 12.5,
    "memory": { "used": 2147483648, "total": 8589934592 },
    "disk": { "used": 42949672960, "total": 107374182400 },
    "network": { "rx_rate": 1048576, "tx_rate": 524288 }
  }
}