跳转至

DEB 安装

本文介绍如何在 Debian/Ubuntu 系统上使用 .deb 软件包安装 One-KVM。

前提条件

  • 系统要求：Debian 12+ 或 Ubuntu 24.04+
  • 支持架构：amd64、arm64、armhf
  • 硬件准备：启用 USB OTG 或插好 CH340+CH9329 HID 线（用于 HID 模拟），插好 USB HDMI 采集卡（或者已有其他视频采集设备）。

软件包按 Debian 12 的运行时库构建。较旧的系统可能缺少所需的 libc6、视频编码或音频库，建议升级系统后再安装。

Debian 13（x86-64）补充依赖

若在 Debian 13、x86-64 上运行 One-KVM 时出现：

error while loading shared libraries: libmfx.so.1: cannot open shared object file: No such file or directory

说明缺少 libmfx 动态库。当前 Debian 13 官方源中暂无对应包，需手动安装旧版仓库中的 libmfx1 deb，例如：

  1. 下载：libmfx1_22.5.4-1_amd64.deb
  2. 在 deb 所在目录执行：
1
apt install ./libmfx1_22.5.4-1_amd64.deb

安装软件

从 GitHub Releases 下载与 CPU 架构匹配的 one-kvm_*.deb，在软件包所在目录执行：

1
2
sudo apt update
sudo apt install ./one-kvm_0.x.x_amd64.deb

将文件名中的版本号和架构替换为实际下载的文件名。安装包会注册 one-kvm.service 并设置为开机启动；在支持 systemd 的系统上，安装完成后会尝试立即启动服务。

可以使用以下命令检查服务状态和日志：

1
2
sudo systemctl status one-kvm
sudo journalctl -u one-kvm -f

配置、数据库、证书和虚拟介质默认保存在 /etc/one-kvm。首次启动后打开 Web 界面完成初始化配置；修改监听地址、端口或 HTTPS 等选项时，优先使用 Web 界面中的设置。

如果安装完成后服务没有启动，请先查看日志。也可以手动执行：

1
sudo systemctl restart one-kvm

OTG 使用说明

如果你需要使用 OTG，请确保系统开启 OTG 功能并使能了 OTG 端口。

执行 ls /sys/class/udc 命令返回为空，说明设备没有 USB OTG 端口，或 USB 端口尚未设置为 OTG 模式；如果是后者，可以尝试修改设备树（dtb）。

执行 ls /sys/kernel/config 命令返回的内容中如果没有 usb_gadget，可能是没有加载 libcomposite 内核模块。可以手动加载，或在 /etc/modprobe.d/ 目录下新建内核模块自动加载规则文件。手动加载命令为 modprobe libcomposite，需要在 One-KVM 服务启动之前执行。

最后将 OTG 端口切换为 device 状态。如果设备树（dtb）中的 USB OTG 端口属性 dr_mode 为 peripheral，开机后通常已经是 device 状态；更常见的 dr_mode = "otg" 则需要手动切换。命令因 CPU 平台（全志、晶晨、瑞芯微等）而异，请参考平台文档。确认命令有效后，可以将其加入 /etc/rc.local，让端口在开机时自动切换。

实例：晶晨平台 OTG 使能命令

1
2
3
4
#查看当前 USB OTG 状态
cat /sys/devices/platform/soc/*/usb_role/*/role
#手动使能 OTG 端口
echo "device" > /sys/devices/platform/soc/*/usb_role/*/role

访问 Web 界面

打开浏览器访问 http://<设备IP>:8080。默认 HTTP 端口为 8080；如果已在 Web 配置中修改端口，请使用修改后的端口。

首次访问

首次访问时，系统会引导您完成初始配置，包括创建管理员账户。