Remote Console 远程控制台

版本信息

项目	内容
组件版本	1.120.1
首发版本	openUBMC 1.0.0
文档作者	openUBMC
最后更新	2026-05-09

1. 组件概述

1.1 组件简介

Remote Console（远程控制台）是 openUBMC 系统中负责远程管理和控制的核心组件，集成了 KVM、VMM、VNC 和 Video 四大功能模块，为用户提供完整的远程服务器管理和运维能力。通过 Remote Console，用户可以远程查看服务器状态、控制键盘鼠标、挂载虚拟镜像、播放录像等，实现高效的远程运维管理。

1.2 解决什么问题

Remote Console 组件为用户解决了服务器远程管理和运维的痛点问题，包括：如何在不亲临机房的情况下查看和控制服务器、如何远程安装操作系统、如何传输文件到服务器、如何记录和回放服务器关键时刻的运行状态等。通过统一的远程控制台，用户可以随时随地进行服务器管理，大幅提升运维效率，降低运维成本。

1.3 核心功能

KVM（Keyboard-Video-Mouse）：虚拟键盘鼠标图像，从 VCE 寄存器获取业务侧 OS 的图像映射到本地，支持远程键鼠操作、截屏和录像功能
VMM（Virtual Media Manager）：虚拟媒体管理，支持本地和远程挂载镜像文件、普通文件和文件夹，用于 OS 安装和文件传输
VNC（Virtual Network Console）：虚拟网络控制台，使用标准 RFB 协议提供兼容性更强的远程控制功能
Video：录像播放器，支持播放重启/下电/CPU 出错录像以及外部录像文件

1.4 关键术语表

术语	解释
KVM	虚拟键盘鼠标图像，通过远程图像和键鼠操作实现服务器控制
VMM	虚拟媒体管理器，将镜像文件挂载为虚拟光驱设备
VNC	虚拟网络控制台，基于 RFB 协议的标准化远程控制方案
VCE	Video Capture Engine，视频捕获引擎，用于获取带内 OS 的图像数据
最后一屏	服务器关机前最后一帧画面，以 JPEG 格式保存
RFB 协议	Remote Framebuffer 协议，VNC 使用的网络通信协议

1.5 外部交互边界图

2. API 使用说明与示例

2.1 KVM 功能管理

bash

busctl --user introspect bmc.kepler.remote_console /bmc/kepler/Managers/1/GraphicalConsole bmc.kepler.Managers.GraphicalConsole
NAME                                 TYPE      SIGNATURE RESULT/VALUE          FLAGS
.CaptureScreenshot                   method    a{ss}ys   u                     -
.CreateVideoPlayToken                method    a{ss}ss   sy                    -
.ExitVideoPlay                       method    a{ss}     -                     -
.ExportScreenshots                   method    a{ss}s    u                     -
.ExportVideo                         method    a{ss}ss   u                     -
.RemoveScreenshot                    method    a{ss}     -                     -
.Reset                               method    a{ss}s    -                     -
.SetPersisUSBConnEnabled             method    a{ss}b    i                     -
.SetScreenshotEnabled                method    a{ss}b    i                     -
.SetVideoEnabled                     method    a{ss}b    i                     -
.AutoOSLockEnabled                   property  b         false                 emits-change writable
.AutoOSLockKey                       property  as        1 ""                  emits-change writable
.AutoOSLockType                      property  s         "Custom"              emits-change writable
.AutoScreenshotTriggers              property  au        2 0 1                 emits-change writable
.DisableKeyboardDuringBiosStartup    property  b         false                 emits-change writable
.Id                                  property  y         0                     emits-change writable
.LocalKvmAutoDisable                 property  b         false                 emits-change writable
.LocalKvmEnabled                     property  b         true                  emits-change writable
.PersistentUSBConnectionEnabled      property  b         true                  emits-change writable
.ScreenshotAttributes                property  a(us)     4 0 "" 0 "" 0 "" 0 "" emits-change
.ScreenshotEnabled                   property  b         true                  emits-change
.VideoAttributes                     property  a(us)     3 0 "" 0 "" 0 ""      emits-change
.VideoEnabled                        property  b         true                  emits-change

功能说明

管理虚拟键盘鼠标图像，从 VCE 寄存器获取业务侧 OS 的图像映射到本地，支持远程键鼠操作、截屏和录像功能

属性	内容
接口名	bmc.kepler.Managers.GraphicalConsole
首发版本	openUBMC 1.0.0
废弃状态	正常可用

参数说明

属性参数说明

参数名	方向	类型	描述	取值范围
Id	输入/输出	uint8	控制台Id
PersistentUSBConnectionEnabled	输入/输出	bool	虚拟键鼠是否支持连接	true，false
VideoEnabled	输出	bool	录像使能	true，false
ScreenshotEnabled	输出	bool	最后一屏使能	true，false
VideoAttributes	输出	array	录像文件信息
ScreenshotAttributes	输出	array	截屏创建时间
LocalKvmEnabled	输入/输出	bool	本地kvm使能	true，false
LocalKvmAutoDisable	输入/输出	bool	远程KVM连接时自动关闭本地KVM设置	true，false
AutoOSLockEnabled	输入/输出	bool	系统自动锁定使能	true，false
AutoOSLockType	输入/输出	string	系统自动锁定方式	Custom(自定义快捷键)、Windows(Windows默认锁定快捷键)
AutoOSLockKey	输入/输出	string[]	系统自动锁定自定义快捷键
AutoScreenshotTriggers	输入/输出	uint32[]	自动截屏触发类型	0:PowerOff,1: OSReset,2:CatError
DisableKeyboardDuringBiosStartup	输入/输出	bool	BIOS启动过程中是否允许kvm键盘输入	true，false

方法参数说明

方法名	入参	出参	描述	取值范围
SetPersisUSBConnEnabled	b	i	设置虚拟键鼠是否支持连接	入参： b: 是否支持连接虚拟键鼠出参： i: 设置结果
SetVideoEnabled	b	i	设置录像使能	入参： b: 是否支持录像出参： i: 设置结果
SetScreenshotEnabled	b	i	设置最后一屏使能	入参： b: 是否支持最后一屏出参： i: 设置结果
CaptureScreenshot	ys	u	手动截屏	入参： y: 手动截屏模式（是否唤醒屏幕） s：目标路径出参： u: 创建的任务标识
RemoveScreenshot	-	-	删除手动截屏
CreateVideoPlayToken	ss	sy	登录录像播放服务	入参： s: Web端Token s: 录像名称出参： s: 播放录像Token y：录像类型
ExitVideoPlay	-	-	退出录像播放服务
ExportVideo	ss	u	导出录像文件	入参： s: 录像名称 s: 导出路径出参： u: 创建的任务标识
ExportScreenshots	s	u	导出截图文件	入参： s: 导出路径出参： u: 创建的任务标识
Reset	s	-	重启Kvm相关服务	入参： s: 重启服务类型

返回值与异常

返回值	含义	触发条件	处理建议
0	成功	设置 KVM 配置成功	无
非0	失败	设置 KVM 配置失败	检查组件日志和组件状态

应用场景

问题定位：服务器出现异常时手动截屏保存当前状态
状态记录：记录服务器某一时刻的显示状态
审计归档：保存服务器操作过程的关键画面
远程安装 OS：挂载 OS 安装镜像进行远程系统安装
文件传输：通过镜像文件传输数据到服务器
驱动安装：挂载驱动程序镜像进行驱动安装

限制条件

截屏功能需要服务器处于上电状态
如果 VCE 寄存器中无图像数据，将返回预设的 NO SIGNAL 图像
截屏文件格式固定为 JPEG
同一时刻只能挂载一个镜像文件
NFS/CIFS 协议对文件系统大小写敏感，需确保路径正确
远程挂载需要确保网络连通性

调试示例

命令行调试

bash

# busctl 方法调用手动截屏
busctl --user call bmc.kepler.remote_console \
  /bmc/kepler/Managers/1/GraphicalConsole \
  bmc.kepler.Managers.GraphicalConsole CaptureScreenshot \
  'a{ss}ys' 3 Interface KVM UserName Administrator ClientAddr 127.0.0.1 0 '/tmp/web'

# busctl 方法启用虚拟键鼠持续连接
busctl --user call bmc.kepler.remote_console \
  /bmc/kepler/Managers/1/GraphicalConsole \
  bmc.kepler.Managers.GraphicalConsole SetPersisUSBConnEnabled \
  'a{ss}b' 3 Interface KVM UserName Administrator ClientAddr 127.0.0.1 true

2.2 远程镜像挂载

bash

busctl --user introspect bmc.kepler.remote_console /bmc/kepler/Managers/1/VirtualMedia/CD bmc.kepler.Managers.VirtualMedia.CD
NAME                                TYPE      SIGNATURE RESULT/VALUE   FLAGS
.EjectMedia                         method    a{ss}     u              -
.InsertMedia                        method    a{ss}s    u              -
.ConnectNum                         property  y         0              emits-change writable
.ConnectState                       property  y         0              emits-change writable
.ConnectedVia                       property  s         "NotConnected" emits-change writable
.Id                                 property  y         0              emits-change writable
.Image                              property  s         ""             emits-change writable
.ImageName                          property  s         ""             emits-change writable
.MediaTypes                         property  as        0              emits-change writable

功能说明

通过 NFS/CIFS/HTTPS 协议将远程镜像文件挂载到 BMC 的虚拟光驱设备，使带内 OS 可以访问镜像内容，用于安装操作系统或传输文件。

属性	内容
接口名	bmc.kepler.Managers.VirtualMedia.CD
首发版本	openUBMC 1.0.0
废弃状态	正常可用

参数说明

属性参数说明

参数名	方向	类型	描述
Id	输入/输出	uint8	虚拟媒体ID
ConnectedVia	输入/输出	string	虚拟媒体连接途径
Image	输入/输出	string	远程镜像URI
ImageName	输入/输出	string	远程镜像文件名
MediaTypes	输入/输出	string[]	虚拟媒体类型
ConnectNum	输入/输出	uint8	虚拟媒体连接数量
ConnectState	输入/输出	uint8	虚拟媒体连接状态

方法参数说明

方法名	入参	出参	描述	取值范围
InsertMedia	s	u	插入媒体	入参： s: 镜像URI 出参： u: 任务标识
EjectMedia	-	u	弹出媒体	出参： u: 任务标识

返回值与异常

返回值	含义	触发条件	处理建议
0	成功	镜像挂载成功	无
非 0	失败	网络不通或文件不存在	检查网络连通性和文件路径

应用场景

远程安装 OS：挂载 OS 安装镜像进行远程系统安装
文件传输：通过镜像文件传输数据到服务器
驱动安装：挂载驱动程序镜像进行驱动安装

限制条件

同一时刻只能挂载一个镜像文件
NFS/CIFS 协议对文件系统大小写敏感，需确保路径正确
远程挂载需要确保网络连通性

调试示例

命令行调试

bash

# busctl 方法查看远程挂载信息
busctl --user introspect bmc.kepler.remote_console \
  /bmc/kepler/Managers/1/VirtualMedia/CD bmc.kepler.Managers.VirtualMedia.CD

2.3 VNC 服务管理

bash

busctl --user introspect bmc.kepler.remote_console /bmc/kepler/Managers/1/VncService bmc.kepler.Managers.VncService
NAME                              TYPE      SIGNATURE RESULT/VALUE FLAGS
.SetKeyboardLayout                method    a{ss}s    -            -
.SetSSLEncryptionEnabled          method    a{ss}b    -            -
.DisableKeyboardDuringBiosStartup property  b         false        emits-change writable
.Id                               property  y         0            emits-change writable
.KeyboardLayout                   property  s         "jp"         emits-change
.ReadOnlySessionStartIndex        property  y         0            emits-change
.SSLEncryptionEnabled             property  b         true         emits-change

功能说明

提供基于 RFB 协议的 VNC 远程控制功能，支持标准 VNC 客户端连接，实现兼容性更强的远程服务器管理。

属性	内容
接口名	bmc.kepler.Managers.VncService
首发版本	openUBMC 1.0.0
废弃状态	正常可用

参数说明

属性参数说明

参数名	方向	类型	描述	取值范围
Id	输入/输出	uint8	VNC服务Id
SSLEncryptionEnabled	输出	bool	ssl加密使能	true，false
KeyboardLayout	输出	string	键盘模式	en:美式键盘, jp:日式键盘, de:德式键盘
ReadOnlySessionStartIndex	输出	uint8	从第几个VNC会话开始为只读
DisableKeyboardDuringBiosStartup	输入/输出	bool	BIOS启动过程中是否允许vnc键盘输入	true，false

方法参数说明

方法名	入参	出参	描述	取值范围
SetSSLEncryptionEnabled	b	-	设置ssl加密使能	入参： b: 是否开启ssl加密使能
SetKeyboardLayout	s	-	设置键盘布局	入参： s: VNC键盘布局

返回值与异常

返回值	含义	触发条件	处理建议
0	成功	设置 VNC 配置成功	无
非 0	失败	设置 VNC 配置失败	查看组件日志和组件服务状态

应用场景

VNC 远程登录：通过 VNC 客户端远程登录服务器

限制条件

开启 ssl 加密后，需要保证客户端证书配置正确

调试示例

命令行调试

bash

# busctl 查看 VNC 服务管理配置
busctl --user introspect bmc.kepler.remote_console \
  /bmc/kepler/Managers/1/VncService bmc.kepler.Managers.VncService

# busctl 方法设置 ssl 加密使能
busctl --user call bmc.kepler.remote_console \
  /bmc/kepler/Managers/1/VncService bmc.kepler.Managers.VncService \
  SetSSLEncryptionEnabled 'a{ss}b' 3 Interface VNC UserName Administrator ClientAddr 127.0.0.1 false

2.4 KVM 功能管理

bash

busctl --user introspect bmc.kepler.remote_console /bmc/kepler/Systems/1/GraphicalConsole bmc.kepler.Systems.GraphicalConsole
NAME                                TYPE      SIGNATURE RESULT/VALUE FLAGS
.CaptureScreenshot                  method    a{ss}ys   u            -
.CreateVideoPlayToken               method    a{ss}ss   sy           -
.EnableGraphicDisplay               method    a{ss}     -            -
.ExportScreenshots                  method    a{ss}s    u            -
.ExportVideo                        method    a{ss}ss   u            -
.RemoveScreenshot                   method    a{ss}     -            -
.SetPersisUSBConnEnabled            method    a{ss}b    i            -
.AutoOSLockEnabled                  property  b         false        emits-change writable
.AutoOSLockKey                      property  as        1 ""         emits-change writable
.AutoOSLockType                     property  s         "Custom"     emits-change writable
.AutoScreenshotTriggers             property  au        2 0 1        emits-change writable
.DisableKeyboardDuringBiosStartup   property  b         false        emits-change writable
.PersistentUSBConnectionEnabled     property  b         true         emits-change writable
.ScreenshotAttributes               property  a(uss)    0            emits-change
.ScreenshotEnabled                  property  b         true         emits-change
.VideoAttributes                    property  a(uss)    0            emits-change
.VideoEnabled                       property  b         true         emits-change

功能说明

多 system 下管理虚拟键盘鼠标图像，从 VCE 寄存器获取业务侧 OS 的图像映射到本地，支持远程键鼠操作、截屏和录像功能

属性	内容
接口名	bmc.kepler.Systems.GraphicalConsole
首发版本	openUBMC 1.0.0
废弃状态	正常可用

参数说明

属性参数说明

参数名	方向	类型	描述	取值范围
PersistentUSBConnectionEnabled	输入/输出	bool	虚拟键鼠是否支持连接	true，false
VideoEnabled	输出	bool	录像使能	true，false
ScreenshotEnabled	输出	bool	最后一屏使能	true，false
VideoAttributes	输出	array	录像文件信息
ScreenshotAttributes	输出	array	截屏创建时间
AutoOSLockEnabled	输入/输出	bool	系统自动锁定使能	true，false
AutoOSLockType	输入/输出	string	系统自动锁定方式	Custom(自定义快捷键)、Windows(Windows默认锁定快捷键)
AutoOSLockKey	输入/输出	string[]	系统自动锁定自定义快捷键
AutoScreenshotTriggers	输入/输出	uint32[]	自动截屏触发类型	0:PowerOff,1: OSReset,2:CatError
DisableKeyboardDuringBiosStartup	输入/输出	bool	BIOS启动过程中是否允许kvm键盘输入	true，false

方法参数说明

方法名	入参	出参	描述	取值范围
SetPersisUSBConnEnabled	b	i	设置虚拟键鼠是否支持连接	入参： b: 是否支持连接虚拟键鼠出参： i: 设置结果
CaptureScreenshot	ys	u	手动截屏	入参： y: 手动截屏模式（是否唤醒屏幕） s：目标路径出参： u: 创建的任务标识
RemoveScreenshot	-	-	删除手动截屏
CreateVideoPlayToken	ss	sy	登录录像播放服务	入参： s: Web端Token s: 录像名称出参： s: 播放录像Token y：录像类型
ExportVideo	ss	u	导出录像文件	入参： s: 录像名称 s: 导出路径出参： u: 创建的任务标识
ExportScreenshots	s	u	导出截图文件	入参： s: 导出路径出参： u: 创建的任务标识

返回值与异常

返回值	含义	触发条件	处理建议
0	成功	设置 KVM 配置成功	无
非0	失败	设置 KVM 配置失败	检查组件日志和组件状态

应用场景

问题定位：服务器出现异常时手动截屏保存当前状态
状态记录：记录服务器某一时刻的显示状态
审计归档：保存服务器操作过程的关键画面
远程安装 OS：挂载 OS 安装镜像进行远程系统安装
文件传输：通过镜像文件传输数据到服务器
驱动安装：挂载驱动程序镜像进行驱动安装

限制条件

截屏功能需要服务器处于上电状态
如果 VCE 寄存器中无图像数据，将返回预设的 NO SIGNAL 图像
截屏文件格式固定为 JPEG
同一时刻只能挂载一个镜像文件
NFS/CIFS 协议对文件系统大小写敏感，需确保路径正确
远程挂载需要确保网络连通性

调试示例

命令行调试

bash

# busctl 方法调用手动截屏
busctl --user call bmc.kepler.remote_console \
  /bmc/kepler/Systems/1/GraphicalConsole \
  bmc.kepler.Systems.GraphicalConsole CaptureScreenshot \
  'a{ss}ys' 3 Interface KVM UserName Administrator ClientAddr 127.0.0.1 0 '/tmp/web'

# busctl 方法启用虚拟键鼠持续连接
busctl --user call bmc.kepler.remote_console \
  /bmc/kepler/Systems/1/GraphicalConsole \
  bmc.kepler.Systems.GraphicalConsole SetPersisUSBConnEnabled \
  'a{ss}b' 3 Interface KVM UserName Administrator ClientAddr 127.0.0.1 true

2.5 远程镜像挂载

bash

busctl --user introspect bmc.kepler.remote_console /bmc/kepler/Systems/1/VirtualMedia/CD bmc.kepler.Systems.VirtualMedia.CD
NAME                               TYPE      SIGNATURE RESULT/VALUE   FLAGS
.EjectMedia                        method    a{ss}     u              -
.InsertMedia                       method    a{ss}ssss u              -
.SetPassword                       method    a{ss}s    -              -
.ConnectNum                        property  y         0              emits-change writable
.ConnectState                      property  y         0              emits-change writable
.ConnectedVia                      property  s         "NotConnected" emits-change writable
.EjectPolicy                       property  s         "Persistent"   emits-change writable
.EjectTimeoutSeconds               property  u         3600           emits-change writable
.Image                             property  s         ""             emits-change writable
.ImageName                         property  s         ""             emits-change writable
.MediaTypes                        property  as        0              emits-change writable
.UserName                          property  s         ""             emits-change writable

功能说明

多 system 下支持通过 NFS/CIFS/HTTPS 协议将远程镜像文件挂载到 BMC 的虚拟光驱设备，使带内 OS 可以访问镜像内容，用于安装操作系统或传输文件。

属性	内容
接口名	bmc.kepler.Systems.VirtualMedia.CD
首发版本	openUBMC 1.0.0
废弃状态	正常可用

参数说明

属性参数说明

参数名	方向	类型	描述
ConnectedVia	输入/输出	string	虚拟媒体连接途径
Image	输入/输出	string	远程镜像URI
ImageName	输入/输出	string	远程镜像文件名
MediaTypes	输入/输出	string[]	虚拟媒体类型
ConnectNum	输入/输出	uint8	虚拟媒体连接数量
ConnectState	输入/输出	uint8	虚拟媒体连接状态
EjectPolicy	输入/输出	string	镜像弹出策略
EjectTimeoutSeconds	输入/输出	uint32	虚拟媒体超时弹出时间
UserName	输入/输出	string	访问远程镜像使用的用户名

方法参数说明

方法名	入参	出参	描述	取值范围
InsertMedia	ssss	u	插入媒体	入参： s: 镜像URI s：传输协议类型 s：插入镜像访问用户名 s：插入镜像访问密码出参： u: 任务标识
EjectMedia	-	u	弹出媒体	出参： u: 任务标识
SetPassword	s	-	设置访问远程镜像密码	入参： s: 访问密码字符串

返回值与异常

返回值	含义	触发条件	处理建议
0	成功	镜像挂载成功	无
非 0	失败	网络不通或文件不存在	检查网络连通性和文件路径

应用场景

远程安装 OS：挂载 OS 安装镜像进行远程系统安装
文件传输：通过镜像文件传输数据到服务器
驱动安装：挂载驱动程序镜像进行驱动安装

限制条件

同一时刻只能挂载一个镜像文件
NFS/CIFS 协议对文件系统大小写敏感，需确保路径正确
远程挂载需要确保网络连通性

调试示例

命令行调试

bash

# busctl 方法查看远程挂载信息
busctl --user introspect bmc.kepler.remote_console \
  /bmc/kepler/Systems/1/VirtualMedia/CD bmc.kepler.Systems.VirtualMedia.CD

2.6 VNC 服务管理

bash

busctl --user introspect bmc.kepler.remote_console /bmc/kepler/Systems/1/VncService bmc.kepler.Systems.VncService
NAME                              TYPE      SIGNATURE RESULT/VALUE FLAGS
.DisableKeyboardDuringBiosStartup property  b         false        emits-change writable
.Id                               property  y         0            emits-change writable

功能说明

多 System 场景下提供基于 RFB 协议的 VNC 远程控制功能，支持标准 VNC 客户端连接。

属性	内容
接口名	bmc.kepler.Systems.VncService
首发版本	openUBMC 1.0.0
废弃状态	正常可用

参数说明

属性参数说明

参数名	方向	类型	描述	取值范围
Id	输入/输出	uint8	VNC服务Id
DisableKeyboardDuringBiosStartup	输入/输出	bool	BIOS启动过程中是否允许vnc键盘输入	true，false

返回值与异常

返回值	含义	触发条件	处理建议
0	成功	设置 VNC 配置成功	无
非 0	失败	设置 VNC 配置失败	查看组件日志和组件服务状态

应用场景

VNC 远程登录：通过 VNC 客户端远程登录服务器

限制条件

开启 ssl 加密后，需要保证客户端证书配置正确

调试示例

命令行调试

bash

# busctl 查看 VNC 服务管理配置
busctl --user introspect bmc.kepler.remote_console \
  /bmc/kepler/Systems/1/VncService bmc.kepler.Systems.VncService

3. 组件扩展案例

3.1 扩展能力概述

Remote Console 组件的扩展能力主要体现在以下方面：

预设图像定制：支持定制 POWER OFF、NO SIGNAL 等预设图像
录像格式扩展：支持添加新的录像格式解析
键盘布局扩展：支持添加新的键盘布局类型
传输协议扩展：VMM 支持添加新的文件传输协议

3.2 扩展点说明

预设图像路径：通过配置文件指定预设图像的存储路径
录像解析器：录像播放器支持插件式的录像格式解析
键盘映射表：VNC 键盘布局转换表可扩展
传输协议模块：VMM 的文件传输模块可支持新协议

3.3 二次开发指导

不适用

4. 日志说明

4.1 一键日志收集

执行系统一键日志收集功能时，会自动收集以下日志文件：

文件路径	内容说明
/var/log/app.log	Remote Console 组件日志
/var/log/operation.log	操作日志

4.2 关键日志信息

日志片段	日志级别	含义解读	建议处理动作
2026-04-04 06:00:04.143603 remote_console ERROR: xxxxxx	ERROR	组件 error 日志	根据报错确认异常事件原因
2026-04-04 06:00:04.143603 remote_console WARNING: xxxxxx	WARNING	组件 warning 日志	根据报错确认告警事件原因
2026-04-04 06:00:04.143603 remote_console NOTICE: xxxxxx	NOTICE	组件 notice 日志	组件正常功能重要节点日志记录
2026-04-03 23:16:58 xxxxxx,remote_console, xxxxxx	OPERATION	组件 operation 日志	根据操作日志判断设置动作是否成功

5. 问题定界指南

5.1 典型问题定界

现象描述	是否为本组件问题	判断依据	关键证据收集方法
远程镜像挂载失败	是或否	检查网络和文件路径	查看 vmm.log 和网络连通性
KVM 界面键鼠无法输入	是或否	检查 USB 枚举状态	查看 dmesg 中的 USB 设备日志
KVM 界面图像无变化	否	检查 hibmc_drm 驱动加载	检查 OS 侧驱动状态
VNC 连接失败	是或否	检查 VNC 服务状态和端口	查看 vnc.log 和端口监听状态
本地挂载安装 OS 用时过长	否	检查 BMC 网络传输速率	测试网络传输速率
录像无法播放	是	检查录像文件格式和完整性	确认录像文件格式和大小

5.3 调试方法

开启调试日志

Remote Console 组件的日志位于 /var/log/ 目录下，可通过以下方式查看：

bash

# 实时查看 Remote Console 主日志
tail -f /var/log/app.log

# 查看操作日志
tail -f /var/log/operation.log

复现问题方法

前置条件设置：确保 Remote Console 服务正常运行，服务器处于上电状态
操作步骤：通过 Web 界面或 API 接口触发相应的功能
预期现象：功能正常执行，图像显示正常，键鼠响应正常

USB 设备状态检查

bash

# 检查 USB 设备枚举状态
dmesg | grep -i usb

6. 常见问题解答

Q1：远程镜像文件挂载失败怎么办？

问题描述：通过 NFS/CIFS/HTTPS 挂载远程镜像时失败
一句话答案：检查 VMM 使能状态、网络连通性和文件路径
根因说明：可能原因包括 VMM 未启用、网络不通、文件路径错误、文件系统大小写问题等
解决方案：
1. 确认 VMM 使能已打开且未被占用
2. 确认远程服务器上存在对应的镜像文件
3. NFS/CIFS 协议注意文件系统大小写敏感性
4. 避免挂载重名目录
规避方案：使用本地挂载替代远程挂载
适用版本：openUBMC 1.0.0

Q2：KVM 界面键鼠无法输入如何处理？

问题描述：KVM 界面显示正常但键盘鼠标无响应
一句话答案：检查 USB 设备枚举状态
根因说明：USB 枚举未下发或 USB 驱动异常
解决方案：
1. 查看一键收集日志中的 dmesg 日志
2. 检查 OS 启动时 USB device-0 连接日志
3. 确认是否出现枚举未下发的情况
4. 尝试键鼠复位操作
规避方案：使用虚拟键鼠持续连接功能
适用版本：openUBMC 1.0.0

Q3：VMM 本地挂载安装 OS 用时过长？

问题描述：通过 VMM 本地挂载镜像安装 OS 时间超过基线要求
一句话答案：检查 BMC 网络传输速率
根因说明：本地挂载需要将镜像数据传输到 BMC，受网络传输速率影响
解决方案：
1. 测试 BMC 网络传输速率（传输文件到 /tmp 目录查看速率）
2. 确保传输速率至少满足 5MB/s 的基线要求
3. 排查网络问题：物理距离、机房网络环境、网口模式等
规避方案：使用远程挂载方式或优化网络环境
适用版本：openUBMC 1.0.0

Q4：上电后 KVM 界面卡住无变化？

问题描述：服务器上电后 KVM 界面图像无变化
一句话答案：检查是否真正进入 OS 以及 hibmc_drm 驱动状态
根因说明：可能是图像卡住或 hibmc_drm 驱动未加载
解决方案：
1. 通过串口确认 OS 是否真正启动
2. 检查 hibmc_drm 驱动是否加载
3. 尝试手动加载驱动：modprobe hibmc_drm
4. 如驱动未加载则需要 OS 领域继续定位
规避方案：无，需要 OS 领域配合解决
适用版本：openUBMC 1.0.0

Q5：VNC 连接失败如何排查？

问题描述：无法通过 VNC Viewer 连接到服务器
一句话答案：检查 VNC 服务状态和网络配置
根因说明：VNC 功能默认关闭、端口未监听、认证失败等
解决方案：
1. 确认 VNC 功能已启用
2. 检查 VNC 服务端口是否正常监听
3. 验证用户名密码配置正确
4. 检查防火墙规则是否阻止连接
规避方案：使用 KVM 功能替代 VNC
适用版本：openUBMC 1.0.0

Q6：录像无法播放怎么办？

问题描述：通过 Video 播放录像时提示格式不支持或播放失败
一句话答案：确认录像文件格式和完整性
根因说明：录像文件损坏、格式不支持或文件不完整
解决方案：
1. 确认录像文件格式为 .rep 格式
2. 检查录像文件大小是否正常
3. 尝试重新生成录像
4. 查看播放器日志获取详细错误信息
规避方案：使用其他录像播放工具或转换格式
适用版本：openUBMC 1.0.0

附录

附录 A 参考资料

openUBMC 官网：https://www.openubmc.cn/
RFB 协议规范：https://tools.ietf.org/html/rfc6143
VNC 官网：https://www.realvnc.com/

附录 B 修订记录

版本	日期	修订人	修订内容
v1.0	2026-05-09	openUBMC	初始版本创建

Remote Console 远程控制台 ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

1.2 解决什么问题 ​

1.3 核心功能 ​

1.4 关键术语表 ​

1.5 外部交互边界图 ​

2. API 使用说明与示例 ​

2.1 KVM 功能管理 ​

功能说明 ​

参数说明 ​

属性参数说明 ​

方法参数说明 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.2 远程镜像挂载 ​

功能说明 ​

参数说明 ​

属性参数说明 ​

方法参数说明 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.3 VNC 服务管理 ​

功能说明 ​

参数说明 ​

属性参数说明 ​

方法参数说明 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.4 KVM 功能管理 ​

功能说明 ​

参数说明 ​

属性参数说明 ​

方法参数说明 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.5 远程镜像挂载 ​

功能说明 ​

参数说明 ​

属性参数说明 ​

方法参数说明 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.6 VNC 服务管理 ​

功能说明 ​

参数说明 ​

属性参数说明 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

3.2 扩展点说明 ​

3.3 二次开发指导 ​

4. 日志说明 ​

4.1 一键日志收集 ​

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.3 调试方法 ​

开启调试日志 ​

复现问题方法 ​

Remote Console 远程控制台

版本信息

1. 组件概述

1.1 组件简介

1.2 解决什么问题

1.3 核心功能

1.4 关键术语表

1.5 外部交互边界图

2. API 使用说明与示例

2.1 KVM 功能管理

功能说明

参数说明

属性参数说明

方法参数说明

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.2 远程镜像挂载

功能说明

参数说明

属性参数说明

方法参数说明

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.3 VNC 服务管理

功能说明

参数说明

属性参数说明

方法参数说明

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.4 KVM 功能管理

功能说明

参数说明

属性参数说明

方法参数说明

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.5 远程镜像挂载

功能说明

参数说明

属性参数说明

方法参数说明

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.6 VNC 服务管理

功能说明

参数说明

属性参数说明

返回值与异常

应用场景

限制条件

调试示例

命令行调试

3. 组件扩展案例

3.1 扩展能力概述

3.2 扩展点说明

3.3 二次开发指导

4. 日志说明

4.1 一键日志收集

4.2 关键日志信息

5. 问题定界指南

5.1 典型问题定界

5.3 调试方法

开启调试日志

复现问题方法