跳到主要内容

远程控制台（VNC / SPICE）

QVMConsole 为每台虚拟机提供两种图形控制台：

控制台接入方式适用场景
VNC面板内置 noVNC（WebSocket 代理），也可对外暴露端口直连浏览器直接操作，最通用
SPICE外部客户端（virt-viewer / spicy）直连，支持 .vv 连接文件更高画质与外设体验
前提条件

控制台依赖虚拟机的显示设备。显示设备为「无」（video_model=none）的虚拟机不可使用控制台，详情页会隐藏 VNC / SPICE 标签页。

VNC 控制台​

开启与监听​

  • 开启 VNC 时注入 graphics type='vnc'，监听地址固定为 127.0.0.1、端口自动分配（仅面板代理可访问，外部不可直连）
  • 可选设置 VNC 密码（超过 8 位会被截断为 8 位）
  • 开启/关闭需要重启虚拟机生效（运行中的虚拟机会自动重启）
  • 开启 VNC 不要求二次验证

密码管理​

  • 运行中可通过 QEMU monitor 热修改 VNC 密码，即时生效、无需重启
  • 密码同时持久化到虚拟机 XML

WebSocket 代理与 noVNC 窗口​

面板通过 /vm/{name}/vnc/ws 提供 WebSocket 代理（自动适配 UNIX socket 与 TCP 监听），内置 noVNC 客户端：

能力说明
详情页 VNC 标签状态展示、开关、密码修改、对外暴露开关
独立 VNC 窗口路由 /vm/:id/vnc-window，支持全屏、自适应缩放
组合键Ctrl+Alt+Del 快捷键与常用组合键下拉菜单
粘贴与输入支持向虚拟机粘贴密码/发送文本（逐字符模拟按键）
密码提示VNC 需要认证时弹窗输入密码
详情页预览Hero 区 VNC 预览卡每 20 秒抓取一帧画面缩略图

对外暴露​

  • 「对外暴露」将监听地址改为 0.0.0.0，外部可使用 VNC 客户端直连分配的端口（需要二次确认）
  • VNC 暴露不会联动宿主机防火墙，如需外部访问请自行放行端口（或使用宿主机防火墙规则管理）

SPICE 控制台​

SPICE 供外部客户端直连（不走面板代理），面板负责生命周期与连接信息管理。所有 SPICE 写操作（开启/关闭/改密/暴露）均要求高风险二次验证。

开启与监听​

  • 开启时注入 graphics type='spice'，默认监听 127.0.0.1、可选密码（无 8 位截断限制，不允许空格）
  • 自动确保虚拟机配置 QXL 显示设备（aarch64 平台跳过 QXL）
  • SPICE 与 VNC 可共存，互不干扰
  • 开启/关闭需要重启虚拟机生效

对外暴露与防火墙联动​

  • 「对外暴露」将监听改为 0.0.0.0，并自动在宿主机 UFW 防火墙放行新端口（ufw allow <port>/tcp）；收回暴露或删除 SPICE 时自动移除该规则
  • 连接信息接口返回主机地址（暴露时为宿主机公网/出口 IP）、运行端口与密码，供客户端直连

.vv 连接文件​

详情页支持下载 .vv 连接文件，可直接用 virt-viewer 打开：

选项说明
一次性（默认）文件内容含 delete-this-file=1，客户端连接后自动删除
可重复使用delete-this-file=0，可多次使用
下载限制

.vv 文件仅在虚拟机运行中可下载（运行中才分配端口）。

VNC 与 SPICE 对比​

特性VNCSPICE
面板内置查看支持（noVNC + WebSocket 代理）不支持（需外部客户端）
默认监听127.0.0.1（自动端口）127.0.0.1（自动端口）
密码位数限制8 位截断无截断（不允许空格）
修改密码是否需重启否（热修改）否（热修改）
对外暴露联动防火墙否（手动放行）是（自动 ufw 放行/回收）
开启/关闭二次验证否是
推荐显示设备任意QXL（开启时自动补齐）

API 摘要​

接口说明
GET /vm/{name}/vnc/statusVNC 状态（端口/认证/密码/暴露）
POST /vm/{name}/vnc/enable | disable | passwd | exposeVNC 开关 / 改密 / 暴露
GET /vm/{name}/vnc/wsnoVNC WebSocket 代理（token 认证）
GET /vm/{name}/spice/status | infoSPICE 状态 / 连接信息（host+port+密码）
POST /vm/{name}/spice/enable | disable | passwd | exposeSPICE 开关 / 改密 / 暴露（均需二次验证）
GET /vm/{name}/spice/vv下载 .vv 连接文件（?delete=0 生成可重复使用文件）