Terminal 插件

terminal 插件是 SDK 插件的参考实现。它提供基于 WebSocket 的交互式 Shell 中继，运维人员无需单独的 SSH 访问或 VPN，即可直接从 Umoo 平台向任意已连接设备打开实时终端会话。

---

概述

属性	值
插件 ID	terminal
层级	SDK（pluginsdk.BackendPlugin）
版本	1.0.0
HTTP 路由	有——WebSocket + REST
Prometheus 指标	有
总线订阅	evt.terminal.v1.*、cmd.terminal.v1.*
DB Schema	有——会话表

---

HTTP 路由

所有路由挂载在 /api/v1/plugins/terminal/ 下，经过标准中间件栈：

限流 → JWT 认证 → 租户认证 → 每路由 RBAC 检查

方法	路径	权限	说明
GET	/api/v1/plugins/terminal/ws/{device_id}	terminal/session:open	升级为 WebSocket；打开交互式 Shell
GET	/api/v1/plugins/terminal/sessions	terminal/session:read	列出所有当前活跃的终端会话

WebSocket 终端（GET /ws/{device_id}）

打开双向 WebSocket 连接，在浏览器与目标设备 Agent 之间中继原始终端 I/O。

连接生命周期：

1. 客户端发送 GET /api/v1/plugins/terminal/ws/{device_id}，附带 Upgrade: websocket。
2. 服务端验证 RBAC（terminal/session:open），查找设备，并通过消息总线开启中继通道。
3. 设备 Agent 收到 cmd.terminal.v1.open 命令并生成 Shell 进程。
4. 原始字节双向流动：客户端 → 服务端 → 设备，设备 → 服务端 → 客户端。
5. 任意一端关闭时，服务端发送 cmd.terminal.v1.close 命令并销毁会话。

Shell 默认值：

配置键	默认值	说明
shell	/bin/bash	设备上的 Shell 可执行文件
persistence	true	WebSocket 短暂断开时保持会话存活
enable_color	false	向 Shell 通告 TERM=xterm-256color

⚠️ 文档修正：旧版指南中列出的默认值为 /bin/sh、persistence=false、enable_color=true，以上为实际源码默认值。

列出会话（GET /sessions）

返回服务端当前追踪的所有会话（已连接或重连中）。

响应（JSON 数组）：

[
  {
    "session_id": "sess_abc123",
    "device_id":  "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id":  "660f9511-...",
    "user_id":    "770a0622-...",
    "opened_at":  "2025-03-25T10:00:00Z",
    "state":      "connected"
  }
]

---

RBAC 权限

权限在启动时自动写入（SDKPluginManager.Init()），存储在平台 permissions 表中，由保护 ConnectRPC 处理器的同一 PermissionCache 执行。

权限	默认角色	说明
terminal/session:read	viewer, operator, tenant_admin	列出活跃会话
terminal/session:open	operator, tenant_admin	向设备打开 WebSocket Shell

在 Web UI 中编程检查：

can(perms, 'terminal/session', 'read')   // 显示会话列表
can(perms, 'terminal/session', 'open')   // 显示"打开终端"按钮

---

消息总线

Terminal 插件在以下总线主题上发布和订阅：

方向	主题	Payload	说明
订阅	evt.terminal.v1.*	—	来自设备的终端状态事件
订阅	cmd.terminal.v1.*	—	内部命令路由
发布	cmd.terminal.v1.open	{session_id, device_id, shell, tenant_id}	告知设备 Agent 生成 Shell
发布	cmd.terminal.v1.close	{session_id}	告知设备 Agent 终止 Shell

---

Prometheus 指标

所有指标注册在 terminal_ 命名空间下：

指标	类型	标签	说明
terminal_active_sessions	Gauge	—	当前打开的 WebSocket 会话数
terminal_sessions_opened_total	Counter	—	已打开会话的生命周期总计数
terminal_sessions_closed_total	Counter	—	已关闭会话的生命周期总计数
terminal_bytes_relayed_total	Counter	direction（ingress|egress）	通过终端代理中继的总字节数

---

插件配置

配置通过 SetPluginConfig / GetPluginConfig RPC（资源：plugin，操作：write/read）按租户存储。

键	类型	默认值	说明
shell	string	/bin/bash	在设备上生成的 Shell
persistence	bool	true	WebSocket 短暂断开时是否维持会话
enable_color	bool	false	在 Shell 环境中设置 TERM=xterm-256color
max_sessions	int	10	每租户最大并发会话数
idle_timeout_sec	int	300	无活动多少秒后自动关闭会话

---

Agent 端插件

设备 Agent 运行对应的 terminal Agent 插件：

1. 订阅发送给其设备 ID 的 cmd.terminal.v1.open 命令。
2. 生成已配置的 Shell，附加 stdin/stdout/stderr。
3. 通过现有 Agent 连接将 I/O 中继回服务端。
4. 处理 cmd.terminal.v1.close——向 Shell 进程发送 SIGHUP。

该 Agent 插件支持热重载配置：SetPluginConfig 更改 shell 或 enable_color 后，无需重启 Agent，新配置即对新会话生效。

---

另请参阅

• 终端用户指南 — 最终用户操作指南
• 认证与 RBAC — 完整权限模型
• WireGuard 插件 — 另一个插件参考