跳到主要内容

常见问题

视频流​

Q1：浏览器看不到画面，黑屏​

排查顺序：

  1. 右上角 "HDMI: ✓ 已连接" 是否绿勾？
    • 红 ✗ → 目标机 HDMI 没插好 / 目标机没开机 / HDMI 1.4 不识别 4K@60Hz 源（改 1080p）
  2. "视频: ✓ 运行中" 是否绿勾？
    • 红 ✗ → ssh pi@<KVM> sudo journalctl -u kvm-server -n 30，看 V4L2 错误
  3. 浏览器开 DevTools → Network → 看 /ws WebSocket 是否 connected
    • 红 ✗ → JWT 过期，重新登录

Q2：延迟大，按键明显滞后​

  • 优先：分辨率切 720p
  • 网络：用有线，无线 5GHz；ping KVM RTT 应 < 5ms 同 LAN
  • 浏览器：Chrome 优先（pion WebRTC 对 Chrome 优化最好）
  • 目标机：HDMI 源 60Hz 比 30Hz 体感好（即使 KVM 编码 30fps）

实测 v2.0.4 同 LAN 1080p 端到端 ~50ms。> 200ms 是异常。

Q3：切分辨率后画面卡住几秒​

v2.0.4 之前的 bug — 切分辨率 hang 15s 然后视频流断。升级到 v2.0.4 解决。

如果 v2.0.4 上仍出现，看 audit log：

ssh pi@<KVM> sudo journalctl -u kvm-server | grep video_resolution_change

应该看到 result=success 在 ~20ms 内。result=failure 含具体卡哪步 description。

键鼠​

Q4：目标机识别不到键盘 / 鼠标​

  • 检查 USB 线：必须 USB-C OTG 模式（不是充电线）
  • 检查 USB Gadget：ssh pi@<KVM> ls /dev/hidg* 应见 hidg0 (kbd) + hidg1 (mouse)
  • 重新 setup：ssh pi@<KVM> sudo /usr/lib/kvm/setup-usb-gadget.sh

Q5：鼠标坐标不对（漂移 / 跳）​

  • 浏览器 fullscreen → "ABS" 按钮切绝对坐标
  • 非 fullscreen → 用相对坐标（默认）+ 鼠标点入视频区先锁定 pointer

Q6：Caps Lock / Num Lock 不同步​

KVM 不主动读目标机 lock 状态（USB Boot 协议限制）。右上指示器是浏览器 KeyboardEvent 推测的，可能跟目标机实际状态不一致。

部署​

Q7：HTTPS 证书无效​

默认自签证书。生产环境放正式 cert：

ssh pi@<KVM>
sudo cp your.crt /etc/kvm/certs/server.crt
sudo cp your.key /etc/kvm/certs/server.key
sudo chmod 600 /etc/kvm/certs/server.key
sudo systemctl restart kvm-server

Q8：忘记 admin 密码​

ssh pi@<KVM>
sudo sqlite3 /var/lib/kvm/kvm.db "UPDATE users SET password_hash='\$2a\$12\$...' WHERE username='admin';"

bcrypt hash 用 htpasswd -bnBC 12 "" newpassword | tr -d ':\n' 生成。

Q9：Wake-on-LAN 不工作​

  • 目标机 BIOS 开 "Wake on LAN" / "Power on by PCIe"
  • 目标机 OS：Linux ethtool -s eth0 wol g，Windows 设备管理器 NIC 属性
  • KVM 跟目标机必须同二层网段（WoL 是 broadcast）

AI / Agent​

Q10：Agent 启动失败 / kvm-agent inactive​

ssh pi@<KVM>
sudo systemctl status kvm-agent
cat /etc/kvm-agent/config.yaml  # LLM API key 填了吗？

默认 Agent 服务 不自启动（per CLAUDE.md §Agent 设计）— 操作员必须先配置 LLM provider + JWT key 才能启。

Q11：本地 LLM 跑太慢​

3B 模型 RKNN INT8 在 RK3588 NPU 上 ~6-10 token/s。慢的话：

  • 看 cat /sys/kernel/debug/rknpu/load — 满 100% 是正常
  • 切更小模型（如 phi3-mini-1.5B）
  • 或切云端 LLM（gpt-4o-mini / gemini-flash）— Agent governance 仍生效

升级​

Q12：v1.x → v2.0.4 数据怎么迁​

  • 审计日志 / 用户 / 配置自动迁移（sqlite migration in kvm-server startup）
  • v2.0.0 起改了 token store schema — v1.x 老 session 全失效，所有用户重新登录
  • v2.0.4 强制 JWT for /ws — 老客户端版本（v1.x web UI）不能连，必须用 v2.0.4 web UI

Q13：如何降级​

不推荐。降级会丢 v2.x 新增的 Agent 数据 + governance 审计链。如必须：

ssh pi@<KVM>
sudo dpkg -i kvm-server_2.0.3-1_arm64.deb  # 强降级
sudo journalctl -u kvm-server -n 50  # 看 migration 是否报错

其他​

Q14：怎么提 bug / 提建议​

GitHub Issues: https://github.com/qiurui144/KVM/issues — 附设备 IP / 浏览器版本 / 复现步骤 / journalctl -u kvm-server 末尾 100 行。

Q15：商用 license​

仓库目前是私有 — 商用 / 大规模部署联系仓库 owner（GitHub @qiurui144）。