# axisipkvm **Repository Path**: axisxy/axisipkvm ## Basic Information - **Project Name**: axisipkvm - **Description**: 基于香橙派 Zero 3 的轻量级 IP-KVM。通过 MS2109 采集 HDMI 画面，使用 CH9329 模拟键盘鼠标，支持浏览器远程控制、Gitee 动态 IP 发现、登录认证及记住登录。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-17 - **Last Updated**: 2026-08-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Axis IP-KVM 基于香橙派 Zero 3、MS2109 和 CH9329 的轻量 IP-KVM。浏览器中可查看 HDMI 画面、控制键盘鼠标，并在开机阶段连续发送 BIOS 进入键。仓库也支持先在 Windows 上完成 Windows-to-Windows 联调。 ## Quick Use（快速使用） ### 1. 接线 ```text 被控电脑 HDMI -> MS2109 -> USB Hub -> 香橙派 被控电脑 USB <- CH9329 HID 端 香橙派 USB Hub -> CH9329 串口控制端 ``` ### 2. 部署到香橙派 使用 Debian/Ubuntu 系镜像，以 root 执行： ```bash git clone https://gitee.com/axisxy/axisipkvm.git /root/axisipkvm cd /root/axisipkvm bash deploy/install-orange-pi.sh ``` 安装完成后服务开机自启，监听 `0.0.0.0:80`。 #### 插网线 如果路由器开启 DHCP，插上网线即可，**不需要配置 Wi-Fi**。到路由器的 DHCP 客户端列表查看香橙派 IP，然后访问 `http://香橙派IP/`。 #### 使用 Wi-Fi 本项目实测使用 NetworkManager。先把下面的占位内容换成自己的 Wi-Fi： ```bash nmcli radio wifi on nmcli --ask device wifi connect "YOUR_WIFI_NAME" ifname wlan0 nmcli connection modify "YOUR_WIFI_NAME" connection.autoconnect yes ip -4 addr show wlan0 ``` 第二条命令会交互询问密码，避免密码留在 Shell 历史中。`nmcli` 会把连接配置 保存在香橙派系统目录中，不会写入本仓库。不要把真实 SSID、Wi-Fi 密码或 Gitee token 写进 README、部署脚本或 Git 配置文件。若系统 没有 `nmcli`，请使用镜像自带的网络配置工具连接 Wi-Fi。 ### 3. 登录 ```text 地址：http://香橙派IP/ 账号：axis 密码：1234567890 ``` 登录页可以勾选“记住登录 30 天”。正式使用前建议修改默认账号密码，方法见 [修改配置](#修改配置)。 ### Windows 联调 把 MS2109 和 CH9329 控制端接到当前 Windows，在 PowerShell 中执行： ```powershell powershell -ExecutionPolicy Bypass -File .\run.ps1 ``` 首次运行会自动创建 Python 环境并打开 `http://127.0.0.1:8080/`。手动指定设备： ```powershell .\run.ps1 -Camera "USB Video" -Com COM5 ``` ## 界面与实测
Axis IP-KVM 登录页
登录页 		远程控制 Windows 桌面
Windows 桌面控制
连续发送 BIOS 按键
连续发送 BIOS 进入键 		Dell F12 启动菜单
F12 启动菜单
Dell BIOS Setup
BIOS Setup
## 硬件
香橙派 Zero 3 MS2109 HDMI USB 采集卡 CH9329 HID 模块
香橙派 Zero 3（2 GB） MS2109 HDMI → USB CH9329 键鼠 HID
CH9329 双头线不要只按插头大小判断方向：控制端应显示 FT232/USB Serial， 被控机应识别出键盘和鼠标；接反时直接对调。 ## 查找香橙派 IP 按推荐顺序选择一种方法： 1. 查看路由器 DHCP 客户端列表。 2. 同一广播网段内，在 Windows 运行 `./discover.ps1`，监听 UDP `39888`。 3. 跨路由或广播被隔离时，使用可选的 Gitee 状态仓库： ```powershell .\connect-ipkvm.ps1 -Owner "Gitee用户名" -Repo "状态仓库名" ``` 需要直接打开网页时，加上设备 ID： ```powershell .\connect-ipkvm.ps1 -Owner "Gitee用户名" -Repo "状态仓库名" ` -ExpectedDeviceId "设备ID" -Open ``` UDP 广播通常不会穿过路由器或 NAT；详细的发现广播、Gitee token 和状态发布配置见 [deploy/README.md](deploy/README.md)。 ## 操作 1. 等待页面顶部显示视频、HID 和控制通道正常，然后点击画面。 2. Windows 桌面使用“绝对坐标”；BIOS 或不兼容界面使用“相对移动”，按 Esc 退出。 3. Ctrl + Alt + Delete 等组合键使用右侧按钮发送。 4. 进入 BIOS：选择 Delete、F2 或 F12，开启连续发送，再手动重启被控机；进入后关闭。 5. 新打开或刷新的页面会接管控制；旧页面自动变为只读。 浏览器最大化、窗口缩放或被控机切换分辨率后，输入焦点和鼠标坐标会自动恢复， 不需要刷新页面。 ### 视频质量与帧率 Linux/香橙派默认请求采集卡的 MJPEG `1920×1080@30` 档位，并将 UVC 原始 JPEG 直接送到浏览器，不再先解码到 BGR、缩成 720p 后又做一次有损 JPEG 编码。页面状态中的 “MJPEG 直通”表示快速路径已经生效；如果显示“JPEG 二次编码”或分辨率/FPS 警告，先用 下面的命令确认采集卡真正支持的模式： ```bash v4l2-ctl --device /dev/video0 --list-formats-ext curl --user axis http://127.0.0.1/api/status ``` USB 2.0 采集卡应优先选择实测稳定的 MJPEG 模式。桌面文字优先使用 `1920×1080@30`；高动态操作可在设备确实支持时改成 `1280×720@60`。YUYV 的标称画质虽 然无压缩，但在 USB 2.0 上通常只能达到很低的帧率。浏览器标签页进入后台后会主动断开 视频流，恢复前台时从最新帧重新连接，避免后台连接继续消耗带宽或追赶旧帧。 ### 控制链路与低延迟 视频和键鼠使用两条独立连接：MJPEG 只走 `/stream.mjpg`，CH9329 控制只走 `/ws/input`。控制 WebSocket 收到事件后立即放进容量固定的单 HID worker，不在接收循环里 等待串口 ACK。连续绝对坐标只保留最新位置，相邻相对位移会合并；键盘、鼠标按钮、滚轮 和宏动作保持严格顺序。队列压力过大时优先丢旧移动，绝不单独丢弃 key-up/button-up；若 全是状态边沿，则清空并安排一次全释放，避免目标机粘键。 普通点击作为一个 `mouse_click` 操作，由 CH9329 worker 连续完成按下和抬起，避免鼠标移动 插入两者之间，也能保留 Windows 双击时间窗。超过 5 像素或按住 140 ms 后才切换为独立 按下/移动/抬起的拖拽路径。页面显示控制 WebSocket RTT、最近 HID 执行耗时和控制队列深度； 这些指标正常但操作反馈仍慢时，应继续检查视频帧龄，而不是重复发送输入。页面进入后台会 释放全部 HID 状态并同时断开视频和控制连接，回到前台后重新接管最新状态。 ### TCP 端口转发 页面顶部的“端口转发”可以把 IP-KVM 设备上的 TCP 端口桥接到被控机。例如， 被控机在直连网中的地址是 `10.77.0.20`，添加： ```text 设备端口 3389 → 10.77.0.20:3389 ``` 之后即可在同一管理网络中使用远程桌面连接 `IP-KVM设备IP:3389`。同样可以转发 SSH、VNC 等 TCP 服务；目标必须填写局域网或直连网络 IP，不能填写公网地址或域名。 配置保存在 `/var/lib/axisipkvm/port-forwards.json`，设备服务重启后会自动恢复。 如果被控机通过 DHCP 获得直连地址，请先在被控机上确认实际的 `10.77.0.x` 地址。 ## 直连文件共享 IP-KVM 可以把一个**专用以太网口**配置成文件中转网。被控端插入这条网线后会自动 获得 `10.77.0.x` 地址，并通过 IP-KVM 的本地 DNS 把 `feichanghaowan.com` 解析到共享页面。该 DHCP 服务不会下发默认网关，因此不会抢走被控端原有的 Wi-Fi 或其他上网线路。 首次部署或更新了 systemd 文件后，先重新运行安装脚本，再选择专门连接被控端的 网口（常见名称是 `end0`）： ```bash cd /root/axisipkvm bash deploy/install-orange-pi.sh bash deploy/configure-share-network.sh end0 ``` 脚本发现该接口已有全局 IP 地址或承担默认路由时会拒绝启动，避免误把管理网口变成 DHCP 服务器。被控端重新插拔网线或续租 DHCP 后，打开： ```text http://feichanghaowan.com/ ``` 页面支持查看、下载、拖放上传和同名文件确认替换。共享文件保存在 `/var/lib/axisipkvm/share`，默认单文件上限为 2 GiB。共享页只对 `10.77.0.0/24` 直连子网免登录；从管理 LAN 访问仍需原有 Axis IP-KVM 账号。 这里使用本地 DNS 覆盖同名公网域名，只提供 HTTP。若浏览器开启了“始终使用 HTTPS”或忽略系统 DNS，请明确输入上面的 `http://` 地址，并关闭该网络的安全 DNS 强制策略。停用直连网络： ```bash bash deploy/configure-share-network.sh --disable ``` ### iPhone 与 Android 手机浏览器支持直接点按和拖动画面。画面下方提供软键盘、Esc、方向键、常用 功能键、右键和滚轮按钮。相对模式在手机上使用单指滑动移动，轻点发送左键， 也可以开启“拖动”后持续按住左键。iPhone 无法进入元素全屏时，网页会自动切换 到等效的沉浸模式。 手机软键盘通过 USB HID 的美式键盘码发送英文、数字和常用符号。中文、日文等 输入法提交的 Unicode 文本无法由 CH9329 启动键盘协议直接表达，请在被控机上 使用英文键盘布局，或连接蓝牙实体键盘。登录后可将网页添加到主屏幕，以独立 窗口方式打开。Android Chrome 的标准 PWA 安装提示要求 HTTPS；继续使用局域网 HTTP 时仍可正常控制，但建议通过可信 VPN 或反向代理补上 HTTPS 后再安装到主屏幕。 ## 修改配置 默认账号密码位于 [src/ipkvm/auth.py](src/ipkvm/auth.py) 顶部： ```python AUTH_USERNAME = "axis" AUTH_PASSWORD = "1234567890" ``` 修改后使用与开发板相同的 Python 版本构建完整更新包： ```powershell .\.venv\Scripts\python.exe .\tools\build_release.py --version 2026.07.20.1 ``` 推荐在 Gitee 创建 tag `v2026.07.20.1`，再用该 tag 创建 Release，并把构建生成的 `axisipkvm-2026.07.20.1-cpython-311.zip` 作为 Release 附件上传。tag 去掉可选的 前缀 `v` 后必须与更新包 manifest 中的版本一致。Gitee 自动生成的源码 ZIP 不可 作为设备更新包。 设备不会后台检查或自动安装。登录控制台后，在“维护”区依次点击“检查 Gitee 更新”和“下载并安装”。默认公开更新源是 `axisxy/axisipkvm`，无需 Token；可以在 开发板的 `/etc/default/axisipkvm-release` 修改仓库或关闭该功能。本地 pyc ZIP 上传仍保留为备用方式。 开发板运行的应用代码固定来自 `/opt/axisipkvm/current.zip`。ZIP 中所有 Python 模块都是 `pyc`，不包含 `.py`；下载安装时会校验 Python 版本、pyc magic、文件清单和 每个文件的 SHA-256。校验通过后系统先独立预检，再原子切换单一 ZIP 并重启；健康 检查失败会自动回滚。因此更新不会混用旧目录里的零散 `pyc`。 构建更新包的 Python `cache_tag` 必须和开发板一致（当前开发板为 `cpython-311`）。更新后可直接在同一“维护”区下载运行日志 ZIP，包内包含主服务、 更新服务、USB/内核和当前运行版本等诊断信息，不需要再拔插开发板。 首次安装或 systemd 部署文件发生变化时，仍执行： ```bash cd /root/axisipkvm git pull bash deploy/install-orange-pi.sh ``` ## 常见问题 - **找不到视频：** 退出相机、OBS、Teams 等可能占用 MS2109 的程序，再重新扫描。 - **帧率低：** USB 2.0 下应优先使用 MJPG；页面底部建议显示 `MJPG`。 - **找不到 HID：** 控制端应看到 FT232/USB Serial，被控机应看到键盘鼠标；否则对调双头线。 - **Linux 下 FT232 能识别但 CH9329 超时：** 程序会自动启用兼容写入；连续超时会向 CH9329 发送官方 `CMD_RESET` 软件复位并限速重试，无需拔插。 - **多显示器坐标不准：** 把 HDMI 设为主屏或镜像，或者切换“相对移动”。 - **发现不到 IP：** 广播只适合同一网段；跨路由请查 DHCP 或使用 Gitee 状态方式。 ## 安全与测试 服务默认使用 HTTP，适合可信局域网。不要把 TCP 80 直接映射到互联网；远程访问请 增加 HTTPS 或可信 VPN。 运行测试： ```powershell .\.venv\Scripts\python.exe -m pytest -q ``` 香橙派安装、systemd、发现广播和 Gitee 发布的完整说明见 [deploy/README.md](deploy/README.md)。