Skip to main content

架构

总体​

KVM 是一个单一 Go 进程 kvm-server（+ 若干 Rust sidecar 服务）部署在 RK3588 上：

┌─────────────── 浏览器 ───────────────┐
│  WebRTC 视频解码 + HID 键鼠输入       │
└────────────┬───────────────┬─────────┘
   WSS 信令  │           SRTP/H.264
             ▼               │
┌─────────────────────────────┴──────┐
│         kvm-server (Go)            │
│  ┌─────────┐  ┌────────────────┐   │
│  │ Web UI  │  │ REST + WS API  │   │
│  └─────────┘  └────────────────┘   │
│  ┌────────────────────────────┐    │
│  │ NativePipeline (cgo)       │    │
│  │  ↓                         │    │
│  │ video_pipeline.cpp (C++)   │    │
│  │   - V4L2 capture           │    │
│  │   - RGA color/resize       │    │
│  │   - RKMPP H.264 encode     │    │
│  │   - HDMI passthrough       │    │
│  │   - Watermark + Redact     │    │
│  └────────────────────────────┘    │
│  ┌────────────────────────────┐    │
│  │ HID Gadget (sysfs configfs)│    │
│  └────────────────────────────┘    │
│  ┌────────────────────────────┐    │
│  │ Agent / OCR / Audit / DB   │    │
│  └────────────────────────────┘    │
└────────────────────────────────────┘
         │           │           │
         ▼           ▼           ▼
   kvm-privacy   kvm-agent   kvm-agent-governance
    (Rust)        (Rust)         (Rust)

视频管线​

四阶段流水线，实测端到端延迟 ~50ms（同 LAN，1080p）：

  1. HDMI 捕获：v4l2_capture.cpp 读 /dev/video40，BGR24 1920×1080 ~6.2 MB/帧
  2. 色彩 + 缩放：RGA 硬件 NV12 转换 + 目标分辨率
  3. 隐私 + 水印：Redact bbox 填黑 + DCT 域水印嵌入
  4. MPP 编码：H.264 VBR / bframes=0 / 切片输出

输出 H.264 NAL → pion/WebRTC → SRTP → 浏览器解码。

v2.0.4 优化（详 RELEASE.md）：

  • WebRTC playoutDelayHint=0 让浏览器不缓存 → -40ms
  • MPP VBR + max_reenc_times=0 + split:mode=1 → 编码侧 -30ms
  • V4L2 BUFFER_COUNT 4→2 → capture 侧 -33ms
  • 鼠标 throttle 8ms→4ms + 累积 movement → 鼠标延迟感更佳

键鼠管线​

  • 浏览器：useMouse.ts / useKeyboard.ts hook 抓事件 → 累积 + throttle → 发给 datachannel
  • kvm-server：hid_handler.go 收 → 翻译成 HID report → 写 /dev/hidg0 / /dev/hidg1
  • 目标机：USB Gadget 表现为标准 keyboard/mouse，BIOS / OS 全识别

Agent 治理（v2.x）​

3-Agent 隔离架构（CLAUDE.md §Agent Hub）：

  • kvm-agent：执行 Agent — 实际调 OCR / 决策 / HID 写
  • kvm-agent-governance：审计 Agent — 监控所有调用 + token / NPU 计数
  • kvm-server inline：control Agent — 用户层意图收发，调度上面两个

每条 Agent 决策都签名进审计链；NPU usage 跨 Agent 隔离统计。

隐私服务​

  • kvm-privacy（Rust，systemd unit）独立进程跑
  • gRPC 接口供 kvm-server 调用
  • fail-closed：服务挂 → kvm-server 视频流停（不漏）

数据存储​

  • SQLite：用户 / 审计日志 / Agent decision / NPU usage（WAL mode + 加密）
  • 文件系统：屏幕快照 / OCR 缓存 / HLS 录像（按 retention 自动清）
  • 配置：/etc/kvm/config.json + per-service /etc/kvm-*/config.yaml

部署形态​

  • 单机：所有服务在 KVM 设备本机（RK3588）
  • deb 包：kvm-server / kvm-ocr / kvm-privacy / kvm-agent / kvm-agent-governance
  • systemd：unit 间用 After= / Wants= 排序

不依赖任何云端服务即可工作（默认本地 OCR + 本地 LLM）。