PiKVM V4 Plus HDMI Video Passthrough 完全指南：零延迟本地显示与远程管理并行架构-平芜编程栈

文档
教程

【免费下载链接】pikvm

Open and inexpensive DIY IP-KVM based on Raspberry Pi

项目地址：https://gitcode.com/gh_mirrors/pi/pikvm

导读

本文围绕 PiKVM 在 V4 Plus 上独有的HDMI Video Passthrough（HDMI 视频透传）功能展开：它允许把目标主机的视频信号直接输出到连接在 PiKVM V4 Plus HDMI 输出口上的物理显示器，同时把同一路视频流复制到 Web UI 或 VNC 供远程访问。读完本文，你将掌握该功能的连接拓扑、启用与更新流程、1920x1200 高级采集模式的 EDID 调整方法、已知限制，以及如何通过 KVMD 配置彻底禁用透传——这些内容以 docs/pass.md 为主体，并结合 KVMD 3.333 发布说明与 EDID 配置文档等仓库资源进行深化。

一、功能定位：PiKVM 如何"透传"而不"切断"视频

传统 KVM-over-IP 设备通常只能二选一：要么把视频交给远程用户，要么把视频交给本地显示器。HDMI Video Passthrough 打破了这一限制——PiKVM 被串联在目标主机与本地显示器之间，平时不干扰显示器正常工作，视频信号在到达本地显示器的同时，被 PiKVM 复制一份流入 Web UI 或 VNC。

这一特性仅适用于 PiKVM V4 Plus，因为它是目前唯一带有 HDMI 输出口的 PiKVM 版本（V4 Mini 无此接口）。根据 V4 快速入门文档中的接口说明，V4 Plus 背面拥有两个 HDMI 视频输出口（OUT1与OUT2），其中OUT2正是透传功能使用的输出端口。

从 KVMD 3.333 发布说明可以确认该功能的几个关键设计目标：

零延迟本地显示：本地显示器上的画面不经过任何编码/解码环节，与直接连接主机的效果一致，并带有 VSync 支持；
本地与远程同时可用：透传进行时视频流依然会被复制到 Web UI 或 VNC，远程管理能力不因本地显示而中断；
不需要远程访问时 PiKVM 不干预显示链路，仅在需要时才"复制"视频流。

下图展示了该功能的核心数据流（图片来源：docs/pass/pass.png）：

如上图所示，视频从主机（Host）进入 PiKVM 后兵分两路：一路送到本地显示器（PiKVM shows it on your local display），另一路流向网络/云端的远程管理端（streams it for remote management），两条路径同时工作（图中标注的AND）。

另外需注意，官方文档明确该功能的最佳搭档是USB passthrough（USB 透传）：当 HDMI 透传与 USB 透传同时开启时，连接在 PiKVM 上的键盘/鼠标可以直接控制当前选中的主机，本地显示器实时显示该主机的画面，再配合 PiKVM Switch 即可在多台计算机之间无缝切换（详见 USB 透传文档）。

分辨率上限：透传功能支持最高1920x1200像素的画面。

二、启用透传：连接与 OS 更新

2.1 硬件连接

将显示器连接到 PiKVM V4 Plus背面的OUT2端口（在 V4 接口标注图中为第 8 项 "HDMI video output port 2"）。同时按照常规方式把主机的 HDMI 信号接入 PiKVM 的 HDMI 输入口（第 5 项），OTG USB 口连接主机。

2.2 确认默认开启状态

在新版镜像中，该功能默认已启用——刷新镜像或购买预装设备后，接通电源即可在物理显示器上看到画面，无需额外配置。

如果你的设备没有看到画面，说明当前 OS 版本过旧或配置被改动过，按下面两步恢复：

第一步：更新 PiKVM OS 并重启。以root身份执行（完整更新说明见 docs/_update_os.md）：

[root@pikvm ~]# pikvm-update

如果提示bash: pikvm-update: command not found，说明 OS 版本过旧，需先手动安装更新器：

[root@pikvm ~]# rw [root@pikvm ~]# pacman -Syy [root@pikvm ~]# pacman -S pikvm-os-updater [root@pikvm ~]# pikvm-update

官方建议仅在拥有设备物理访问权限时才执行 OS 更新。更新流程本身非常可靠，但存在极小概率需要重新刷写 SD 卡；PiKVM 不会被"变砖"，但物理刷卡操作需要接触存储卡。

第二步：重启后确认画面。更新并重启完成后，本地显示器上即应出现来自主机的视频画面。

2.3 与 USB Passthrough 的组合使用

如需同时启用 USB 透传以获得"一套键鼠 + 本地显示器 + 远程管理"的完整本地工位体验，在满足 KVMD 4.74+ 的前提下执行：

[root@pikvm ~]# rw; systemctl enable --now kvmd-localhid; ro

启用后可通过快捷键切换模式：LeftAlt, LeftAlt, K让键鼠控制 PiKVM 本身（KVM 模式），LeftAlt, LeftAlt, H切回透传模式把键鼠事件交给主机（Host 模式）；若接有 PiKVM Switch，还可使用LeftAlt, LeftAlt, 1～1-8在最多 8 个通道间切换（详见 docs/usb_pass.md）。

三、显示器不支持 1920x1200 时的处理

PiKVM V4 支持1920x1200 高级采集模式。如果你的物理显示器最大只支持 1920x1080，那么画面底部会被裁剪一部分（详见下一节"已知限制"）。官方提供了两种解决思路：

优先方案：在目标主机操作系统中把分辨率改为 1920x1080 或更低；
备选方案：若主机 OS 不支持改分辨率（例如卡在 BIOS/UEFI 阶段），则在 PiKVM 上禁用 1920x1200 采集模式：

[root@pikvm ~]# rw [root@pikvm ~]# kvmd-edidconf --import-preset=v4plus.no-1920x1200 [root@pikvm ~]# reboot

3.1 这条命令在底层做了什么

kvmd-edidconf是 PiKVM OS 中负责读写 EDID 的核心工具。EDID（Extended Display Identification Data）描述了采集设备（此处为 HDMI-CSI 桥接芯片）支持的视频模式，主机会依据它决定输出什么分辨率。

EDID 以 HEX 格式存储在/etc/kvmd/tc358743-edid.hex，开机时由kvmd-tc358743.service加载进采集芯片（详见 docs/edid.md）；
--import-preset=v4plus.no-1920x1200会导入 V4 Plus 的预设 EDID，并把 1920x1200 模式从能力列表中移除，使主机只能协商出 1920x1080 及以下分辨率；
与之对应，恢复默认 EDID 使用kvmd-edidconf --import-preset=v4plus --apply，可用的预设包括v0、v1、v2、v3、v4mini和v4plus；
若仅想在编辑后不重启就立即生效，可在命令末尾追加--apply（见 docs/edid.md 中的相关示例）。

3.2 更精细的 EDID 调优：借用真实显示器的身份

V4 Plus 还支持从物理显示器"收养"EDID 标识信息（docs/_edidconf_adopt.md），让目标主机把 PiKVM 识别为你的真实显示器——这可以避免某些 BIOS/UEFI 因显示器身份变化而产生兼容问题。操作时把显示器连接到OUT2端口后执行：

[root@pikvm ~]# rw [root@pikvm ~]# kvmd-edidconf --import-display-ids --apply [root@pikvm ~]# ro

完成后可以拔掉显示器，PiKVM 会把新设置持久化到/etc/kvmd/tc358743-edid.hex。该文档明确提到OUT2端口同时服务于 HDMI 透传与显示器身份收养，二者共用同一物理链路。

注意：EDID 调优仅适用于 V3/V4 及基于 CSI 桥的 DIY 版本；HDMI-USB 采集棒（dongle）无法修改 EDID。

四、当前已知限制（务必提前知晓）

该功能在仓库文档中被明确标注为"较新、将持续改进"（the feature is pretty new and will be improved）。当前存在以下限制：

显示器分辨率必须 ≥ PiKVM 采集分辨率，且不做缩放。例如采集信号为 1080p、而显示器最大仅支持 720p，则完全看不到画面（PiKVM 不执行任何 downscaling）。
尽力而为的裁剪兜底。如果输入信号为 1920x1200、显示器仅支持 1920x1080，画面会显示但底部被裁剪——这是刻意为之：至少让你有机会进入主机系统调整画面参数，而不是黑屏。
当前不支持音频。透传链路只转发视频信号，音频需另行处理（PiKVM 的音频功能见 docs/audio.md）。

结合 docs/edid.md 中的硬件能力说明，可进一步明确边界：V4 系列的最大采集能力为1920x1200 @ 60Hz；因此透传输出同样受限于该上限，任何声称超过该规格的 EDID（如 8K）都会失效。

五、禁用透传（完全关闭该功能）

如果出于兼容性、功耗或安全策略考虑需要彻底关闭透传，可在 KVMD 配置中移除视频流进程的--v4p参数：

编辑/etc/kvmd/override.yaml，加入以下内容：

kvmd: streamer: forever: false cmd_remove: - "--v4p"

重启 PiKVM：

[root@pikvm ~]# reboot

5.1 配置项解析

从配置结构看，这段 YAML 直接作用于 KVMD 的视频流进程（streamer）：

kvmd.streamer.forever: false：与 KVMD 对视频流进程的常驻管理策略相关，配合cmd_remove使用，确保修改后的进程参数在重启后仍被遵守；
kvmd.streamer.cmd_remove：声明要从流进程启动命令行中移除的参数字段，--v4p即启用 V4 Plus 透传/复制流的标志位。移除该标志后，PiKVM 将不再把采集到的视频复制到本地 HDMI 输出，本地显示器将无画面。

如果你需要恢复默认行为，只需把这两项从override.yaml中删除并再次重启。override.yaml是 PiKVM OS 推荐的用户级配置覆盖入口，系统级默认配置位于/usr/share/kvmd/configs.default/，用户修改不应直接编辑系统默认文件（参见 docs/config.md 的配置体系说明）。

六、平台镜像与固件背景（便于排查）

透传功能依赖专门的平台镜像。从 docs/building_os.md 可以看到，V4 Plus 的构建平台标识为PLATFORM=v4plus-hdmi，对应的官方预编译镜像为v4plus-hdmi-rpi4-aarch64-latest.img.xz（docs/flashing_os.md）。刷机时务必选择与v4plus-hdmi匹配的镜像，可通过pacman -Q | grep kvmd-platform核对当前安装的平台包。

如果你遇到"本地显示器无画面"类问题，可先按 V4 故障排查建议执行：

[root@pikvm ~]# dmesg | egrep 'tc35|1-1.4|uvc' [root@pikvm ~]# systemctl status kvmd-tc358743

确认采集链路（TC358743 桥接芯片、UVC 设备）是否正常，再回到本文第二节检查透传启用状态。

总结

PiKVM V4 Plus 的 HDMI Video Passthrough 提供了一条"本地零延迟直连 + 远程并行管理"的双路径视频架构：视频进入 PiKVM 后同时流向本地显示器（OUT2）与 Web UI/VNC。启用该功能只需保证 OS 为最新（默认开启）；当显示器不支持 1920x1200 时，可通过kvmd-edidconf --import-preset=v4plus.no-1920x1200切换 EDID 预设规避底部裁剪；如需完全关闭，则在/etc/kvmd/override.yaml中移除流进程的--v4p参数并重启。官方文档同时明确了该功能的边界：最高 1920x1200、不做分辨率缩放、底部裁剪兜底、暂不支持音频，且仅 V4 Plus 因独有 HDMI 输出口而支持此特性。结合 docs/pass.md、docs/edid.md 与 docs/usb_pass.md 阅读，可以形成从配置、EDID 调优到组合使用的完整知识闭环。