silentwind0/kvmd

One-KVM Docker 镜像文档

1. 镜像概述

One-KVM Docker 镜像是一个基于Docker容器化的远程KVM（键盘、视频、鼠标）控制解决方案，支持通过Web界面实现对目标设备的远程控制。该镜像适用于amd64、arm64、armv7架构的Linux系统，可通过OTG或CH9329芯片实现虚拟HID（人机接口设备）功能，满足远程运维、设备管理等场景需求。

更多详细内容可参考 One-KVM文档。

2. 核心功能与特性

• 多模式虚拟HID支持：兼容OTG模式和CH9329芯片作为虚拟HID设备，实现键盘鼠标远程控制。
• 多服务端口暴露：集成Web服务（8080/4430）、VNC控制台（5900）、IPMI控制（623），满足多样化访问需求。
• 音视频设备映射：支持视频采集设备（如/dev/video0）、音频设备（如/dev/snd）映射，实现音视频远程传输。
• 身份认证机制：默认启用基于账号密码的身份认证，支持自定义账号密码。
• SSL加密：默认启用HTTPS（4430端口），保障数据传输安全（使用自签证书）。
• 灵活配置：支持通过环境变量自定义设备参数、功能开关，支持配置文件持久化挂载。

3. 适用场景

• 嵌入式设备远程调试与管理
• 服务器无物理控制台时的远程运维
• 工业设备、智能家居设备的远程控制
• 需跨网络访问目标设备的场景（如家庭、机房设备远程管理）

4. 使用方法

4.1 前提条件

• 已安装Docker环境（推荐Docker 20.10+）。
• 目标主机具备对应架构（amd64/arm64/armv7）的Linux系统。
• 若使用CH9329模式，需确保目标主机已连接相应硬件设备（如视频采集卡、USB转串口设备等）。

4.2 部署步骤

4.2.1 选择部署模式

根据虚拟HID实现方式，选择以下任一部署命令：

模式1：OTG模式（虚拟HID）

bash
sudo docker run --name kvmd -itd --privileged=true \
    -v /lib/modules:/lib/modules:ro -v /dev:/dev \
    -v /sys/kernel/config:/sys/kernel/config -e OTG=1 \
    -p 8080:8080 -p 4430:4430 -p 5900:5900 -p 623:623 \
    silentwind0/kvmd

模式2：CH9329模式（硬件HID）

bash
sudo docker run --name kvmd -itd \
    --device /dev/video0:/dev/video0 \
    --device /dev/ttyUSB0:/dev/ttyUSB0 \
    --device /dev/snd:/dev/snd \
    -p 8080:8080 -p 4430:4430 -p 5900:5900 -p 623:623 \
    silentwind0/kvmd

4.2.2 镜像源说明

默认从Docker Hub拉取镜像（silentwind0/kvmd）。若网络访问受限，可替换为阿里云镜像源：

bash
# 阿里云镜像源（杭州节点）
***.xuanyuan.run/silentwind/kvmd

4.3 访问与使用

1. 服务访问：部署完成后，通过浏览器访问 https://<主机IP>:4430。

   • 首次访问因自签SSL证书会触发浏览器安全提醒，点击“高级”→“继续访问”即可。
   • 默认登录账号密码：admin/admin。

2. 功能验证：登录后即可通过Web界面控制目标设备，包括视频监控、键盘鼠标输入等功能。

4.4 开机自启配置

为确保容器在主机重启后自动运行，需配置Docker服务与容器自启：

bash
# 设置Docker服务开机自启
systemctl enable docker

# 设置One-KVM容器自动重启
docker update --restart=always kvmd

4.5 更新版本

停止并删除现有容器，拉取最新镜像后重新部署：

bash
# 停止容器
docker stop kvmd

# 删除容器
docker rm kvmd

# 拉取最新镜像（使用对应镜像源）
docker pull silentwind0/kvmd

# 重新部署（使用原部署命令）

4.6 日志查看与问题排查

若服务无法访问或功能异常，可通过日志定位问题：

bash
# 查看容器运行日志
sudo docker logs kvmd

问题未解决可提交Issue或加入官方QQ群寻求支持。

5. 配置说明

5.1 设备映射参数

部署命令中通过--device或-v参数映射主机设备至容器，常见配置如下：

5.2 端口映射说明

容器默认暴露以下端口，需通过-p参数映射至主机：

5.3 环境变量详解

通过-e参数可自定义容器功能，常用环境变量如下：

5.3.1 账号密码配置

5.3.2 设备指定配置

5.3.3 功能启用/禁用

6. 注意事项

• 镜像源选择：网络访问Docker Hub受限可替换为阿里云镜像源 ***.xuanyuan.run/silentwind/kvmd。
• 设备权限：CH9329模式需确保主机设备（如/dev/ttyUSB0）有读写权限，可通过chmod调整或使用--privileged参数（谨慎使用）。
• 音频设备识别：Linux音频设备可通过arecord -L或arecord -l命令查看，用于配置AUDIONUM参数。
• SSL证书：自签证书仅用于测试环境，生产环境建议替换为可信证书（需挂载自定义配置目录修改）。