代码仓
中
文档中心
在AtomGit上查看源码

remote_console ​

版本信息 ​

项目内容
组件版本1.120.1
首发版本openUBMC 1.0.0
文档作者openUBMC 社区
最后更新2026-09-14
许可证Mulan PSL v2
组件类型application

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 协议的标准化远程控制方案
VCEVideo 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输入/输出boolBIOS启动过程中是否允许kvm键盘输入true，false
方法参数说明 ​
方法名入参出参描述取值范围
SetPersisUSBConnEnabledbi设置虚拟键鼠是否支持连接入参：
b: 是否支持连接虚拟键鼠
出参：
i: 设置结果
SetVideoEnabledbi设置录像使能入参：
b: 是否支持录像
出参：
i: 设置结果
SetScreenshotEnabledbi设置最后一屏使能入参：
b: 是否支持最后一屏
出参：
i: 设置结果
CaptureScreenshotysu手动截屏入参：
y: 手动截屏模式（是否唤醒屏幕）
s：目标路径
出参：
u: 创建的任务标识
RemoveScreenshot--删除手动截屏
CreateVideoPlayTokensssy登录录像播放服务入参：
s: Web端Token
s: 录像名称
出参：
s: 播放录像Token
y：录像类型
ExitVideoPlay--退出录像播放服务
ExportVideossu导出录像文件入参：
s: 录像名称
s: 导出路径
出参：
u: 创建的任务标识
ExportScreenshotssu导出截图文件入参：
s: 导出路径
出参：
u: 创建的任务标识
Resets-重启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'

响应示例：

u 1111111111

# 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

响应示例：

i 0

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虚拟媒体连接状态
方法参数说明 ​
方法名入参出参描述取值范围
InsertMediasu插入媒体入参：
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

响应示例：

成功：返回命令的正常输出。
失败：返回对应错误信息。

# 返回资源协作接口信息
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

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输入/输出uint8VNC服务Id
SSLEncryptionEnabled输出boolssl加密使能true，false
KeyboardLayout输出string键盘模式en:美式键盘，jp:日式键盘，de:德式键盘
ReadOnlySessionStartIndex输出uint8从第几个VNC会话开始为只读
DisableKeyboardDuringBiosStartup输入/输出boolBIOS启动过程中是否允许vnc键盘输入true，false
方法参数说明 ​
方法名入参出参描述取值范围
SetSSLEncryptionEnabledb-设置ssl加密使能入参：
b: 是否开启ssl加密使能
SetKeyboardLayouts-设置键盘布局入参：
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

响应示例：

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

# 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输入/输出boolBIOS启动过程中是否允许kvm键盘输入true，false
方法参数说明 ​
方法名入参出参描述取值范围
SetPersisUSBConnEnabledbi设置虚拟键鼠是否支持连接入参：
b: 是否支持连接虚拟键鼠
出参：
i: 设置结果
CaptureScreenshotysu手动截屏入参：
y: 手动截屏模式（是否唤醒屏幕）
s：目标路径
出参：
u: 创建的任务标识
RemoveScreenshot--删除手动截屏
CreateVideoPlayTokensssy登录录像播放服务入参：
s: Web端Token
s: 录像名称
出参：
s: 播放录像Token
y：录像类型
ExportVideossu导出录像文件入参：
s: 录像名称
s: 导出路径
出参：
u: 创建的任务标识
ExportScreenshotssu导出截图文件入参：
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'

响应示例：

u 1111111111

# 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

响应示例：

i 0

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访问远程镜像使用的用户名
方法参数说明 ​
方法名入参出参描述取值范围
InsertMediassssu插入媒体入参：
s: 镜像URI
s：传输协议类型
s：插入镜像访问用户名
s：插入镜像访问密码
出参：
u: 任务标识
EjectMedia-u弹出媒体出参：
u: 任务标识
SetPasswords-设置访问远程镜像密码入参：
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

响应示例：

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

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输入/输出uint8VNC服务Id
DisableKeyboardDuringBiosStartup输入/输出boolBIOS启动过程中是否允许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

响应示例：

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

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

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

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

3.2 扩展点说明 ​

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

3.3 二次开发指导 ​

不适用

4. 日志说明 ​

4.1 一键日志收集 ​

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

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

4.2 关键日志信息 ​

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

5. 问题定界指南 ​

5.1 典型问题定界 ​

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

5.2 错误码速查表 ​

错误码含义可能原因排查建议
0成功操作已执行完成。无需处理。
非 0失败参数、状态、文件、任务或网络异常。结合接口错误信息、任务状态和组件日志定位。

remote_console 对外接口当前统一使用 0/非 0 表示执行结果，未定义独立的错误码枚举。

5.3 最小化复现与证据收集 ​

  1. 记录功能模块、系统 ID、接口方法、请求参数和返回的任务 ID。
  2. KVM、VMM、VNC 和 Video 问题分别记录当前连接状态、镜像路径、录像路径和客户端环境。
  3. 保存 remote_console、app.log、operation.log 和 USB 枚举日志。
  4. 网络类问题记录 BMC 管理网地址、端口监听状态、连通性和客户端浏览器或 VNC Viewer 版本。
  5. 对异步任务记录任务状态、执行结果和失败时的错误信息。

5.4 调试方法 ​

开启调试日志 ​

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

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

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

复现问题方法 ​

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

USB 设备状态检查 ​

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

6. 常见问题解答 ​

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

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

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

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

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

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

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

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

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

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

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

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

附录 ​

附录A 参考资料 ​

附录B 修订记录 ​

版本日期修订人修订内容
v1.02026-05-09openUBMC初始版本创建
下一篇探索openUBMC