终端

基于浏览器的 WebSocket 终端，远程访问在线设备。

概述

terminal 插件提供从 Umoo 控制台直接对任何在线设备的交互式 Shell 访问。会话通过 WebSocket 运行，支持完整的 PTY（伪终端）功能：

• ANSI 颜色和光标控制
• 窗口调整（SIGWINCH）
• Ctrl+C / Ctrl+Z 信号转发
• 滚动缓冲区

前提条件

1. 必须为租户启用 terminal 插件（设置 → 插件配置 → 终端 → 启用）。
2. 设备必须处于在线状态（Agent 已连接到平台）。
3. 你的用户角色必须具有 terminal/session:open 权限（默认授予 operator 及以上角色）。

打开终端

1. 导航到设备 → [设备名称]。
2. 点击终端标签页。
3. 终端会自动连接。几秒钟内你应该会看到 Shell 提示符。

如果设备离线，终端标签页会显示 "设备离线" 且不会尝试连接。

工作原理

浏览器 → WebSocket /api/v1/plugins/terminal/ws/{device_id}
       → 后端终端插件
       → NATS 消息总线
       → 设备上的 umoo-agent
       → PTY fork（Shell 进程）

1. 浏览器向后端打开 WebSocket 连接。
2. 后端的终端插件验证请求（JWT + terminal/session:open RBAC 检查）。
3. 通过 NATS 总线在设备上创建 PTY 会话。
4. 按键从浏览器 → 后端 → NATS → Agent → PTY 转发。
5. 输出反向流回：PTY → Agent → NATS → 后端 → WebSocket → 浏览器。

活跃会话

导航到设置 → 插件配置 → 终端或使用 CLI 列出活跃会话：

# 列出活跃终端会话（需要 terminal/session:read 权限）
GET /api/v1/plugins/terminal/sessions

会话列表包含：会话 ID、设备 ID、连接用户、开始时间。

终端配置

按租户和设备组配置 Shell 和显示设置：

设置	默认值	描述
Shell 路径	/bin/sh	设备上的 Shell 可执行文件
默认列数	80	初始终端宽度
默认行数	24	初始终端高度
持久化	false	浏览器断开后保持会话
启用颜色输出	true	ANSI 颜色支持

持久化： 启用后，会话在浏览器断开后存活，可以重新连接。禁用时，关闭浏览器标签页会终止 Shell 进程。

安全性

• 所有终端会话都需要 terminal/session:open 权限。
• 会话限定在已认证的租户范围内 — 你无法打开其他租户设备的终端。
• 所有按键和输出都经过 Umoo 后端（浏览器和设备之间非端到端加密）。
• 会话事件会写入审计日志。

故障排除

终端显示"设备离线"：

• 检查设备列表中的设备状态。
• 验证 Agent 正在运行：systemctl status umoo-agent

连接立即断开：

• 检查终端插件是否在租户插件配置中启用。
• 验证设备上配置的 Shell 路径是否存在。
• 检查后端日志中的 terminal 插件错误。

连接时"权限被拒绝"：

• 你的角色可能没有 terminal/session:open 权限。联系你的租户管理员。