KVM-privacy/docs/architecture/overview.md

KVM-Privacy 系统架构总览

最后更新: 2026-03-05 | 版本: 1.0.0

1. 系统定位

KVM-Privacy 是基于 KVM-over-IP 的两层隐私保护系统，运行于 NanoPC-T6 (RK3588)。通过硬件加速（NPU + RGA + MPP）实现实时 PII 检测、视频流遮蔽、网络上传拦截和 AI 自主操控。所有防护完全在 KVM 设备端完成，无需在被控机器上部署任何软件。

2. 服务架构

┌─────────────────────────────────────────────────────────────┐
│                       KVM WebUI (React)                      │
│                     http://localhost:8080                    │
└──────────────┬──────────────────────────────────────────────┘
               │ HTTP + WebSocket + WebRTC
┌──────────────▼──────────────────────────────────────────────┐
│               KVM Server (Go, port 8080)                    │
│  ┌──────────┐ ┌───────┐ ┌────────┐ ┌──────┐ ┌───────────┐ │
│  │ 视频管道 │ │  HID  │ │ WebRTC │ │ RBAC │ │ 隐私处理  │ │
│  │ V4L2→MPP │ │hidg0/1│ │ pion   │ │Casbin│ │ OCR+遮蔽  │ │
│  └──────────┘ └───────┘ └────────┘ └──────┘ └───────────┘ │
│  ┌──────────┐ ┌───────┐ ┌────────┐ ┌──────┐ ┌───────────┐ │
│  │ 审计日志 │ │ 录制  │ │ 终端   │ │ 存储 │ │ Agent代理 │ │
│  │ SM3链+DB │ │ HLS   │ │SSH/WS  │ │虚拟U盘│ │ →:8890    │ │
│  └──────────┘ └───────┘ └────────┘ └──────┘ └───────────┘ │
└──┬───────┬───────────┬──────────────────────┬──────────────┘
   │       │           │                      │
   │  ┌────▼────┐ ┌────▼──────────┐  ┌───────▼──────────┐
   │  │隐私网关 │ │ KVM Agent     │  │ info-privacy-rs  │
   │  │mitmproxy│ │ Python 8890   │  │ Rust/RKNN 8000   │
   │  │port 8888│ │ LLM+OCR+HID  │  │ PII 检测/脱敏    │
   │  └────┬────┘ └───────┬───────┘  └──────────────────┘
   │       │              │
   │  ┌────▼────┐   ┌─────▼──────────────────┐
   │  │ 审计DB  │   │ mem-bridge (Python)     │
   │  │MariaDB/ │   │ Memory :8001 (FAISS)    │
   │  │SQLite   │   │ Router :8002 (LLM路由)  │
   │  └─────────┘   └────────────────────────┘
   │
┌──▼──────────────────────┐
│ 目标主机 (HDMI + USB)    │
│ V4L2 采集 + HID gadget  │
└─────────────────────────┘

3. 服务端口规划

服务	端口	协议	包名	说明
KVM Server	8080	HTTP/WS/WebRTC	kvm-server	Go 主服务
info-privacy-rs	8000	HTTP	kvm-privacy	Rust PII 检测/脱敏
mem-bridge memory	8001	HTTP	kvm-bridge	FAISS 向量搜索 + 会话存储
mem-bridge router	8002	HTTP	kvm-bridge	AI 路由 (OpenAI/Gemini/本地)
Privacy Gateway	8888	HTTP Proxy	kvm-mitm	mitmproxy 网络拦截
KVM Agent	8890	HTTP	kvm-agent	Python AI Agent daemon
Privacy API	8889	HTTP	kvm-mitm	隐私网关 REST API

4. 子系统划分

子系统	语言	文档	核心职责
KVM Server	Go 1.24	kvm-server.md	视频流、HID、WebRTC、RBAC、审计
原生视频管道	C/C++ + CGo	video-pipeline.md	V4L2→RGA→MPP 编码、隐私遮蔽、DMA-buf
KVM Agent	Python 3.12	kvm-agent.md	AI 自主操控（感知→规划→执行→验证）
隐私系统	Go+Python+Rust	privacy-system.md	PII 检测、视频遮蔽、网络拦截、Chrome 扩展
记忆桥接	Python 3.12	memory-bridge.md	FAISS 向量搜索、LLM 路由、上下文压缩
硬件优化	C/C++	hardware.md	RK3588 NPU/RGA/DMA-buf/CPU 亲和性
部署打包	Shell/Debian	deployment.md	5 个 deb 包、systemd 服务、CI 流程

5. 数据流概览

5.1 视频流路径

HDMI 输入 → V4L2 (/dev/video0) → [BGR/NV12]
  → RGA 色彩转换/缩放 → NV12 buffer
  → 隐私遮蔽 (redact_nv12_regions, 如果 mode=redact)
  → MPP H.264 编码 (或 DMA-buf 零拷贝)
  → RTP 打包 (pion/rtp)
  → WebRTC DTLS-SRTP → 浏览器 <video>

5.2 OCR 感知路径

V4L2 BGR 帧 → JPEG 编码 → /tmp/kvm-ocr/frame.jpg
  → HID 事件触发 OCR (L1/L2/L3 优先级)
  → kvm-ocr 分析 (exec 或 CGo 内联)
  → 文本 + 区域坐标 → 模式匹配 (sensitive_commands.json)
  → 危险命令? → HID 阻断
  → mode=redact? → detectPIIBboxes → SetRedactRegions → 视频管道

5.3 Agent 自主操控

用户提交任务 → POST /api/v1/agent/tasks
  → LLM 规划 (Vision: screenshot + OCR + 历史)
  → 执行动作 (鼠标优先, 安全白名单)
  → 截图验证 (OCR 语义检查)
  → 成功? → 保存模板 | 失败? → 重试/放弃

5.4 隐私拦截

浏览器流量 → mitmproxy (8888)
  → AI 域名匹配 → 文件上传检测
  → info-privacy-rs API 分析 PII
  → audit: 记录日志 | redact: 脱敏后放行 | off: 直通

6. 技术栈

层	技术	版本
前端	React + TypeScript	18+ / 5.3+
Go 后端	Go + gorm + pion WebRTC	1.24.0
Python 服务	asyncio + aiohttp + httpx	3.12
Rust 加速	Axum + RKNN + RGA	2024 edition
视频编码	Rockchip MPP + RGA (native) / GStreamer (fallback)	—
向量搜索	FAISS + RKNNLite (embedding)	—
数据库	MariaDB + SQLite	10.4+
认证	JWT (RS256) + TOTP + Casbin RBAC	—
国密	SM3 哈希 (审计链)	emmansun/gmsm

7. 安全架构

纵深防御（设备端完成，不依赖被控机器）

Layer 1: Agent Safety (Python)
  ├─ 20 键白名单, 组合键全禁
  ├─ Unicode NFKC 归一化 (防全角绕过)
  ├─ 危险命令 regex 拦截
  └─ 文本长度 ≤10000

Layer 2: KVM Server (Go)
  ├─ OCR 模式匹配 (sensitive_commands.json)
  ├─ HID 实时阻断 (检测到危险命令)
  ├─ RBAC 权限控制 (admin/auditor/operator)
  ├─ JWT + TOTP 双因素认证
  └─ SM3 哈希链审计日志

Layer 3: Privacy Gateway (Python + Rust)
  ├─ MITM SSL 拦截 AI 平台上传
  ├─ info-privacy-rs PII 检测/脱敏
  └─ append-only 审计日志

8. 目录结构

KVM-privacy/
├── CLAUDE.md                   # 项目编码规范
├── README.md                   # 项目概览
├── DEVELOP.md                  # 开发指南
├── RELEASE.md                  # 版本历史
├── Makefile                    # 部署命令
├── debian/                     # 5 个 deb 包定义
│   ├── kvm-agent/             #   Python AI Agent
│   ├── kvm-bridge/            #   mem-bridge 记忆服务
│   ├── kvm-meta/              #   元包 (依赖全部)
│   ├── kvm-mitm/              #   mitmproxy 网关
│   └── kvm-privacy/           #   Rust PII 检测
├── deploy/
│   ├── kvm.toml.example       # KVM 配置模板
│   └── systemd/               # 8 个 systemd 服务文件
├── deps/                       # Git submodules
│   ├── KVM/                   #   Go KVM 核心 + React WebUI
│   │   ├── go/                #     Go 后端 (28 个 internal 包)
│   │   ├── web/               #     React 前端
│   │   ├── src/video/         #     C 视频管道 (V4L2/RGA/MPP)
│   │   ├── src/audit/         #     C OCR 模块 (RKNN)
│   │   ├── systemd/           #     KVM systemd 服务
│   │   ├── debian/            #     kvm-server deb 定义
│   │   └── scripts/           #     构建脚本
│   ├── embedding/             #   Python mem-bridge
│   └── info-privacy-rs/       #   Rust PII 检测
├── services/
│   ├── kvm_agent/             # Python AI Agent (26 个模块)
│   └── privacy_gateway/       # Python mitmproxy 网关
├── scripts/                    # 部署/测试脚本
├── docs/
│   ├── architecture/          # 子系统架构文档 (本目录)
│   └── plans/                 # 历史设计文档 (14 个)
└── web/
    └── src/                   # TypeScript 组件库