Erupt Remote 远程访问
erupt-remote 把远程主机桥接到浏览器:VNC 桌面用 noVNC 渲染,SSH 终端用 xterm.js 渲染,二者共用一条 WebSocket 通道,无需在客户端安装任何工具。
最低版本要求:2.2.0
安全提示
远程访问等同于把主机控制权交到浏览器里。仅应授权给受信任的管理员,生产环境务必启用 HTTPS/WSS。
引入方式
<dependency>
<groupId>xyz.erupt</groupId>
<artifactId>erupt-remote</artifactId>
<version>${erupt.version}</version>
</dependency>引入后自动装配生效,菜单中出现 远程主机(RemoteHost)表格入口。
使用流程
- 在 远程主机 表格中新建一条记录,填写主机地址、端口与协议。
- 点击行按钮 连接,在应用内路由
/remote/{id}打开桌面或终端页面。 - 服务端把二进制 WebSocket(
/erupt-remote)桥接到目标主机端口。
VNC 远程桌面(Windows)

VNC 远程桌面(macOS)

SSH 终端

操作工具栏
桌面与终端页面顶部提供一致的操作栏,会话状态(连接中 / 已连接 / 已断开)以左上角圆点标识。
VNC 桌面
| 按钮 | 说明 |
|---|---|
| Keys | 发送本地无法直接传递的组合键:Ctrl + Alt + Del、Alt + Tab、Tab、Esc、Print Screen |
| Paste | 把本地剪贴板内容发送到远程桌面 |
| Shot | 截取当前画面并下载 |
| Quality | 画质与带宽档位:Low bandwidth(低带宽)、Balanced(均衡)、Best quality(最佳画质) |
| Power | 远程电源操作:Reboot(重启)、Reset(强制重启)、Shut down(关机) |
| View only | 只读模式,仅观看不发送任何输入 |
| Fit | 画面缩放适应窗口 |
| Fullscreen | 全屏 |
| Disconnect | 断开会话;断开后按钮变为 Reconnect |
SSH 终端
| 按钮 | 说明 |
|---|---|
| Ctrl+C | 向远程进程发送中断信号 |
| Paste | 粘贴本地剪贴板内容 |
| Clear | 清屏 |
| Fullscreen | 全屏 |
| Disconnect | 断开会话;断开后按钮变为 Reconnect |
开启了文件传输的 SSH 主机,工具栏还会多出一个 Files 按钮,点击后在终端旁打开 SFTP 文件面板,详见下方 SFTP 文件传输。
SFTP 文件传输 v2.3.0+
SSH 终端页面的 Files 按钮会在终端旁打开一个侧边面板,通过 SFTP 子系统直接操作远程主机的文件系统,不需要在目标主机上额外安装任何东西:
- 浏览:从登录用户的 home 目录开始,进入任意目录;目录优先、按名称排序,符号链接按其指向的类型展示,可直接进入被链接的目录。
- 上传:点击按钮选择文件,或把文件直接拖进面板;带上传进度,同名文件会被覆盖。
- 下载:把远程文件以附件形式下载到本地。
- 新建文件夹:在当前目录下创建子目录。
- 删除:删除一个文件,或一个空目录。
- 插入路径:把条目的路径以带引号的形式输入到 Shell 中,方便接着敲命令。
面板只在主机开启了文件传输时显示;VNC 主机没有文件通道(RFB 协议本身不含文件传输),需要传文件时请把同一台机器再配一条 SSH 主机记录。
按主机开关
远程主机 记录中的 文件传输 开关(RemoteHost.fileTransfer,数据库列 e_remote_host.file_transfer,BIT(1))默认开启,仅在协议为 SSH 时显示。关闭后:
- 终端页面不再出现 Files 按钮;
- 所有 SFTP 接口一律拒绝(提示「该主机未开启文件传输」);
- Shell 本身不受影响。
适合「允许敲命令,但不允许把文件带进带出」的主机。
安全说明
| 环节 | 做法 |
|---|---|
| 连接方式 | 每次调用都新开一条短生命周期的 SSH 会话,完成后立即关闭;与终端 WebSocket 互不绑定,终端断开不会中断正在进行的下载 |
| 凭据与主机密钥 | 与终端共用主机记录里的用户名 / 密码 / 私钥、TOFU 主机密钥策略(.erupt/remote_known_hosts)以及 connect-timeout-seconds,远程权限即 SSH 登录用户的权限 |
| 鉴权 | 每次调用都重新校验:erupt-upms token + RemoteHost 菜单权限 + 主机 是否启用 + 授权用户 + 文件传输 开关。页面打开后被禁用、被移除授权或关闭了文件传输的主机,下一次点击即被拒绝 |
| 路径规则 | 由 SftpPaths 统一约束:路径必须是绝对路径,. / .. 在服务端按字面解析,含 NUL 字符一律拒绝;新建 / 上传的名称必须是不含 /、\ 的纯文件名,不能是 . 或 .. |
| 删除 | 永不递归:只删单个文件或空目录,且拒绝删除 /。清空整棵目录树请在 Shell 里操作,让用户看见自己敲的命令 |
| 上传 | 请求体直接流式写入 SFTP,不落临时文件、不经过 multipart,因此没有 multipart 大小上限;反向代理的 client_max_body_size 需要相应放大 |
接口一览
所有接口挂在 /erupt-api/remote/sftp/{id} 下({id} 为主机记录 id),均要求 RemoteHost 菜单权限,路径参数一律为远程主机上的绝对路径:
| 方法 | 路径 | 参数 | 说明 |
|---|---|---|---|
| GET | /{id}/home | — | 登录用户 home 目录的绝对路径 |
| GET | /{id}/ls | path | 列出目录;返回 name / directory / size / mtime / mode |
| GET | /{id}/download | path | 以附件流式下载文件,_token 放在 URL 中;目标为目录时拒绝 |
| POST | /{id}/upload | path(目录)、name | 请求体即文件内容,写入 path/name,同名覆盖 |
| POST | /{id}/mkdir | path(目录)、name | 在 path 下创建目录 name |
| DELETE | /{id} | path | 删除一个文件或一个空目录 |
主机配置项
| 配置项 | 说明 |
|---|---|
| 主机名称 | 列表展示名 |
| 协议 | VNC(桌面)或 SSH(终端) |
| 主机 | erupt 服务端可达的 IP 或域名 |
| 端口 | VNC 默认 5900,SSH 默认 22 |
| 用户名 | SSH 登录用户,选择 SSH 时显示 |
| 密码 | VNC:服务端密码(取前 8 位);SSH:登录密码,或私钥的 passphrase |
| 私钥 | SSH 公钥认证用的 PEM 私钥,优先级高于密码 |
| 文件传输 v2.3.0+ | 是否在 SSH 终端旁提供 SFTP 文件面板(浏览、上传、下载),默认开启,仅协议为 SSH 时显示;关闭后 Files 按钮与 SFTP 接口一并禁用,Shell 不受影响 |
| 是否启用 | 关闭后不可连接 |
凭据以 AES-GCM 加密存储,密钥由 erupt.remote.secret-key 指定,未配置时自动生成一次并写入 .erupt/remote.key。
安全模型
| 环节 | 做法 |
|---|---|
| 目标地址 | 由服务端按记录 id 查出,浏览器无法自行指定连接目标 |
| 鉴权 | erupt-upms token + RemoteHost 菜单权限(票据接口与 WebSocket 各校验一次)+ 一次性票据 |
| VNC 密码 | 已存密码时由服务端代答 RFB 认证,凭据不下发到浏览器;未存密码(或服务器只支持其他安全类型,如 macOS ARD 认证)时透传握手,由 noVNC 提示用户输入 |
| SSH 主机密钥 | 首次连接信任(TOFU),记录在 .erupt/remote_known_hosts,密钥变更直接拒绝连接 |
| 会话 | 全局并发上限 + 空闲回收 |
参数配置
erupt:
remote:
# 凭据加密密钥,建议用环境变量注入;多节点部署必须共用同一个值
secret-key: ${ERUPT_REMOTE_SECRET_KEY}
# 全局并发会话上限
max-sessions: 20
# 无浏览器输入超过该时长的会话将被关闭(分钟)
idle-timeout-minutes: 30
# 连接远程主机的 TCP 超时(秒)
connect-timeout-seconds: 5Nginx 反向代理
与 erupt-terminal 同理,需要为 /erupt-remote 转发 WebSocket 升级请求:
location /erupt-remote {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
}目标主机准备
erupt-remote 是 VNC 客户端,目标主机上必须先运行一个 VNC 服务端(SSH 则用系统自带的 sshd,无需额外安装)。支持任意 RFB 3.3 / 3.7 / 3.8 服务端。
Windows:需手动安装 VNC 服务端
Windows 不自带 VNC 服务端——系统自带的「远程桌面」走的是 RDP 协议,与 VNC 不通用,因此必须另行安装:
| 软件 | 下载地址 | 说明 |
|---|---|---|
| TightVNC | tightvnc.com/download.php | 免费、体积小,安装包自带服务端,推荐首选 |
| UltraVNC | uvnc.com/downloads/ultravnc.html | 免费,功能更多(文件传输、多显示器) |
| TigerVNC | github.com/TigerVNC/tigervnc/releases | 开源,跨平台 |
| RealVNC Server | realvnc.com/download/vnc | 商业软件,个人使用有免费额度 |
以 TightVNC 为例:
- 下载对应位数的 MSI 安装包(64 位系统选
tightvnc-x.x.x-gpl-setup-64bit.msi)。 - 安装时选择 Typical,确保勾选 TightVNC Server 组件。
- 安装过程中会要求设置密码,在 Password for Remote Access 处填写,这就是 erupt 主机记录里要填的「密码」。
- 安装完成后服务以 Windows 服务方式常驻,默认监听 5900 端口;托盘图标右键 → Configuration 可再次修改密码与端口。
- 在 Windows Defender 防火墙中放行 5900 端口的入站连接(安装程序通常会提示自动添加规则)。
VNC 密码只有前 8 位有效
这是 RFB 协议本身的限制,与 erupt 无关。设置密码时请控制在 8 位以内,避免「密码填长了却连不上」的困惑。
macOS:开启系统自带的屏幕共享
macOS 内置 VNC 服务端,只需开启并允许密码访问:
- 打开 系统设置 → 通用 → 共享(旧版本为 系统偏好设置 → 共享)。
- 打开 屏幕共享(Screen Sharing) 开关。
- 点击其右侧的 ⓘ 按钮 → 电脑设置(Computer Settings…)。
- 勾选 「VNC 显示程序可以使用密码控制屏幕」(VNC viewers may control screen with password),并设置密码(同样只有前 8 位有效)。
- 确认 允许访问 的用户范围包含你要使用的账户。
开启后主机记录填 macOS 的 IP、端口 5900、密码填上一步设置的 VNC 密码即可。
不设置 VNC 密码时
不勾选第 4 步时,macOS 只提供 Apple Remote Desktop 认证方式。此时服务端无法代答,erupt 会透传握手,由浏览器端的 noVNC 弹窗提示输入 macOS 的用户名与密码——连接同样可用,只是凭据不再由服务端保管。
Linux:安装 x11vnc 或 TigerVNC
- 共享已有物理桌面:
x11vnc,如sudo apt install x11vnc,再执行x11vnc -display :0 -rfbauth ~/.vnc/passwd -forever(x11vnc -storepasswd生成密码文件)。 - 开独立虚拟桌面:
tigervnc-standalone-server,vncpasswd设置密码后执行vncserver :1,此时端口为5901(端口 = 5900 + 显示号)。
纯命令行运维场景直接用 SSH 协议即可,无需安装任何 VNC 服务端。
与 erupt-terminal 的区别
erupt-terminal 打开的是 erupt 服务自身所在主机的 Shell;erupt-remote 连接的是受管的其他主机,按条目维护、按菜单授权,且支持图形桌面。逐项对比见 erupt-terminal → 与 erupt-remote 的区别。