闲置Armbian机顶盒部署One-KVM实现远程管理

前言

最近在抖音上刷到关于One-KVM署视频，正好手头有一台刷好Armbian的闲置机顶盒、之前买的USB采集卡以及两根USB to USB数据线，便决定亲自动手尝试部署。经过一番实践，成功实现了通过浏览器远程控制另一台设备的界面，效果个人感觉还不错。本文将详细记录整个部署过程，供有类似需求的爱好者参考。

前提条件

一台已刷入Armbian系统的机顶盒（最好有两个USB接口），或任何x86/ARM架构的Linux小主机（推荐Debian/Ubuntu系统）
一个USB视频采集卡
一根USB to USB数据线（如果机顶盒支持OTG功能），或专用的CH340+CH9329 HID模拟线缆
一根HDMI线缆

Armbian机顶盒部署One-KVM-1.webp

检查并启用USB的OTG功能

One-KVM的核心原理是通过USB OTG将机顶盒模拟成键盘鼠标（HID设备）来控制目标主机。因此，确保USB OTG功能正常至关重要。

检查OTG端口：执行命令ls /sys/class/udc如果返回结果为空，则表明设备可能没有USB OTG端口，或该端口未在设备树中配置为OTG模式。后者可以尝试修改设备树（dtb）文件解决。
检查内核模块：执行命令ls /sys/kernel/config查看输出中是否包含usb_gadget目录。如果没有，可能是libcomposite内核模块未加载。可执行sudo modprobe libcomposite加载模块。
设置OTG端口为device模式：

#查看当前 USB OTG 状态
cat /sys/devices/platform/soc/*/usb_role/*/role

#使能 OTG device 模式
echo device > /sys/devices/platform/soc/*/usb_role/*/role

#将 OTG 端口使能命令写入开机启动脚本 /etc/rc.local
vim /etc/rc.local

Armbian机顶盒部署One-KVM-2.webp

使用Docker Compose部署One-KVM

推荐使用docker-compose管理容器，便于配置和维护。

mkdir ~/one-kvm && cd ~/one-kvm

创建docker-compose.yml文件

services:
  one-kvm:
    container_name: one-kvm
    image: silentwind0/one-kvm-full
    privileged: true  # 必须！赋予容器访问硬件的权限
    network_mode: host  # 使用主机网络，无需端口映射
    volumes:
      # 必须挂载！使容器能访问系统设备
      - /dev:/dev
      - /sys:/sys
      # 挂载数据目录，便于持久化配置
      - ./data:/data
    environment:
      # 时区设置
      TZ: Asia/Shanghai
      # HTTP访问端口（主机模式，直接使用主机端口）
      HTTP_PORT: 8080
      # HTTPS端口（启用HTTPS时有效）
      HTTPS_PORT: 8443
      # 是否启用HTTPS（启用则会使用自签名证书）
      ENABLE_HTTPS: "false"
      # 数据目录，对应容器内路径
      DATA_DIR: /data
      # 日志详细程度：0=默认，1=-v，2=-vv，3=-vvv
      VERBOSE: "0"
    stdin_open: true  # 保持标准输入打开
    tty: true         # 分配伪终端
    restart: unless-stopped  # 自动重启策略

启动服务

sudo docker-compose up -d

初始配置与使用

首次访问http://IP:8080会进入引导页面，按照提示完成即可，这里不赘述了，详细配置可参考：One-KVM官方文档

创建管理员账户：用户名/密码
音视频设备配置：选择你的USB采集卡对应的设备
HID设备配置（键鼠模拟）：选择和设置设置HID后端设备及参数

如果采集卡识别不到，可以尝试插拔和重启一下，音视频设备配置、鼠键配置可以在控制台里配置，OTG的鼠键无法使用，看看libcomposite内核模块是否加载、OTG端口是否为device模式（我就是因为重启之后OTG端口不是device模式，一直无法使用鼠键）
Armbian机顶盒部署One-KVM-5.webp

使用效果实测

部署完成后，使用起来效果还不错，我WINdows笔记本和Mac mini都可以显示实时画面，内网使用延迟还可以，远程也能满足基础的远程维护需求。
Armbian机顶盒部署One-KVM-3.webp Armbian机顶盒部署One-KVM-4.webp

结语

以上就是闲置Armbian机顶盒部署One-KVM远程管理的完整教程，整体部署难度不高，核心在于OTG功能的配置和硬件兼容性验证。One-KVM作为一款开源远程管理项目，不仅部署简单、操作友好，还支持多种硬件平台和跨系统访问，完美解决了闲置设备利用和远程控制的双重需求。
对于有闲置机顶盒、小主机的小伙伴来说，这个方案成本非常低，无论是用于远程管理家里的电脑、服务器，还是搭建家庭服务进行技术测试，都非常实用。如果在部署过程中遇到问题，建议多参考One-KVM官方文档教程，大部分问题都能快速解决。
最后，希望这篇教程能帮助到大家，让闲置设备重新发挥价值，也欢迎大家在评论区分享自己的部署经验和避坑技巧～

参考

One-KVM文档

推荐订阅源

文章列表

前言