feat: 添加 RustDesk 协议支持和项目文档

- 新增 RustDesk 模块，支持与 RustDesk 客户端连接
  - 实现会合服务器协议和 P2P 连接
  - 支持 NaCl 加密和密钥交换
  - 添加视频帧和 HID 事件适配器
- 添加 Protobuf 协议定义 (message.proto, rendezvous.proto)
- 新增完整项目文档
  - 各功能模块文档 (video, hid, msd, otg, webrtc 等)
  - hwcodec 和 RustDesk 协议技术报告
  - 系统架构和技术栈文档
- 更新 Web 前端 RustDesk 配置界面和 API

docs/README.md

@@ -0,0 +1,130 @@
+# One-KVM 技术文档
+
+本目录包含 One-KVM 项目的完整技术文档。
+
+## 文档结构
+
+```
+docs/
+├── README.md                 # 本文件 - 文档索引
+├── system-architecture.md    # 系统架构文档
+├── tech-stack.md            # 技术栈文档
+└── modules/                 # 模块文档
+    ├── video.md            # 视频模块
+    ├── hid.md              # HID 模块
+    ├── otg.md              # OTG 模块
+    ├── msd.md              # MSD 模块
+    ├── atx.md              # ATX 模块
+    ├── audio.md            # 音频模块
+    ├── webrtc.md           # WebRTC 模块
+    ├── rustdesk.md         # RustDesk 模块
+    ├── auth.md             # 认证模块
+    ├── config.md           # 配置模块
+    ├── events.md           # 事件模块
+    └── web.md              # Web 模块
+```
+
+## 快速导航
+
+### 核心文档
+
+| 文档 | 描述 |
+|------|------|
+| [系统架构](./system-architecture.md) | 整体架构设计、数据流、模块依赖 |
+| [技术栈](./tech-stack.md) | 使用的技术、库和开发规范 |
+
+### 功能模块
+
+| 模块 | 描述 | 关键文件 |
+|------|------|---------|
+| [Video](./modules/video.md) | 视频采集和编码 | `src/video/` |
+| [HID](./modules/hid.md) | 键盘鼠标控制 | `src/hid/` |
+| [OTG](./modules/otg.md) | USB Gadget 管理 | `src/otg/` |
+| [MSD](./modules/msd.md) | 虚拟存储设备 | `src/msd/` |
+| [ATX](./modules/atx.md) | 电源控制 | `src/atx/` |
+| [Audio](./modules/audio.md) | 音频采集编码 | `src/audio/` |
+| [WebRTC](./modules/webrtc.md) | WebRTC 流媒体 | `src/webrtc/` |
+| [RustDesk](./modules/rustdesk.md) | RustDesk 协议集成 | `src/rustdesk/` |
+
+### 基础设施
+
+| 模块 | 描述 | 关键文件 |
+|------|------|---------|
+| [Auth](./modules/auth.md) | 认证和会话 | `src/auth/` |
+| [Config](./modules/config.md) | 配置管理 | `src/config/` |
+| [Events](./modules/events.md) | 事件系统 | `src/events/` |
+| [Web](./modules/web.md) | HTTP API | `src/web/` |
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      One-KVM System                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                 Web Frontend (Vue3)                       │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                              │                                   │
+│                              ▼                                   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                   Axum Web Server                         │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                              │                                   │
+│                              ▼                                   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                     AppState                              │   │
+│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐            │   │
+│  │  │ Video  │ │  HID   │ │  MSD   │ │  ATX   │            │   │
+│  │  │ Module │ │ Module │ │ Module │ │ Module │            │   │
+│  │  └────────┘ └────────┘ └────────┘ └────────┘            │   │
+│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐            │   │
+│  │  │ Audio  │ │ WebRTC │ │RustDesk│ │ Events │            │   │
+│  │  │ Module │ │ Module │ │ Module │ │  Bus   │            │   │
+│  │  └────────┘ └────────┘ └────────┘ └────────┘            │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                              │                                   │
+│                              ▼                                   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                  Hardware Layer                           │   │
+│  │  V4L2 │ USB OTG │ GPIO │ ALSA │ Network                  │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 关键特性
+
+- **单一二进制**: Web UI + 后端一体化部署
+- **双流模式**: WebRTC (H264/H265/VP8/VP9) + MJPEG
+- **USB OTG**: 虚拟键鼠、虚拟存储
+- **硬件加速**: VAAPI/RKMPP/V4L2 M2M
+- **RustDesk**: 跨平台远程访问
+- **无配置文件**: SQLite 配置存储
+
+## 目标平台
+
+| 平台 | 架构 | 用途 |
+|------|------|------|
+| aarch64-unknown-linux-gnu | ARM64 | 主要目标 |
+| armv7-unknown-linux-gnueabihf | ARMv7 | 备选 |
+| x86_64-unknown-linux-gnu | x86-64 | 开发/测试 |
+
+## 快速开始
+
+```bash
+# 构建前端
+cd web && npm install && npm run build && cd ..
+
+# 构建后端
+cargo build --release
+
+# 运行
+./target/release/one-kvm --enable-https
+```
+
+## 相关链接
+
+- [项目仓库](https://github.com/mofeng-git/One-KVM)
+- [开发计划](./DEVELOPMENT_PLAN.md)
+- [项目目标](./PROJECT_GOALS.md)

docs/modules/atx.md

@@ -0,0 +1,484 @@
+# ATX 模块文档
+
+## 1. 模块概述
+
+ATX 模块提供电源控制功能，通过 GPIO 或 USB 继电器控制目标计算机的电源和重置按钮。
+
+### 1.1 主要功能
+
+- 电源按钮控制
+- 重置按钮控制
+- 电源 LED 状态监视
+- Wake-on-LAN 支持
+- 多后端支持 (GPIO/USB 继电器)
+
+### 1.2 文件结构
+
+```
+src/atx/
+├── mod.rs              # 模块导出
+├── controller.rs       # AtxController (11KB)
+├── executor.rs         # 动作执行器 (10KB)
+├── types.rs            # 类型定义 (7KB)
+├── led.rs              # LED 监视 (5KB)
+└── wol.rs              # Wake-on-LAN (5KB)
+```
+
+---
+
+## 2. 架构设计
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          ATX Architecture                                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                Web API
+                   │
+                   ▼
+         ┌─────────────────┐
+         │  AtxController  │
+         │ (controller.rs) │
+         └────────┬────────┘
+                  │
+    ┌─────────────┼─────────────┐
+    │             │             │
+    ▼             ▼             ▼
+┌────────┐  ┌────────┐    ┌────────┐
+│ Power  │  │ Reset  │    │  LED   │
+│Executor│  │Executor│    │Monitor │
+└───┬────┘  └───┬────┘    └───┬────┘
+    │           │             │
+    ▼           ▼             ▼
+┌────────┐  ┌────────┐    ┌────────┐
+│ GPIO   │  │ GPIO   │    │ GPIO   │
+│ or USB │  │ or USB │    │  Input │
+│ Relay  │  │ Relay  │    │        │
+└───┬────┘  └───┬────┘    └───┬────┘
+    │           │             │
+    └───────────┼─────────────┘
+                │
+                ▼
+        ┌───────────────┐
+        │   Target PC   │
+        │ (ATX Header)  │
+        └───────────────┘
+```
+
+---
+
+## 3. 核心组件
+
+### 3.1 AtxController (controller.rs)
+
+```rust
+pub struct AtxController {
+    /// 电源按钮配置
+    power: Arc<AtxButton>,
+
+    /// 重置按钮配置
+    reset: Arc<AtxButton>,
+
+    /// LED 监视器
+    led_monitor: Arc<RwLock<Option<LedMonitor>>>,
+
+    /// WoL 控制器
+    wol: Arc<RwLock<Option<WolController>>>,
+
+    /// 当前状态
+    state: Arc<RwLock<AtxState>>,
+
+    /// 事件总线
+    events: Arc<EventBus>,
+}
+
+impl AtxController {
+    /// 创建控制器
+    pub fn new(config: &AtxConfig, events: Arc<EventBus>) -> Result<Self>;
+
+    /// 短按电源按钮 (开机/正常关机)
+    pub async fn power_short_press(&self) -> Result<()>;
+
+    /// 长按电源按钮 (强制关机)
+    pub async fn power_long_press(&self) -> Result<()>;
+
+    /// 按重置按钮
+    pub async fn reset_press(&self) -> Result<()>;
+
+    /// 获取电源状态
+    pub fn power_state(&self) -> PowerState;
+
+    /// 发送 WoL 魔术包
+    pub async fn wake_on_lan(&self, mac: &str) -> Result<()>;
+
+    /// 获取状态
+    pub fn state(&self) -> AtxState;
+
+    /// 重新加载配置
+    pub async fn reload(&self, config: &AtxConfig) -> Result<()>;
+}
+
+pub struct AtxState {
+    /// 是否可用
+    pub available: bool,
+
+    /// 电源是否开启
+    pub power_on: bool,
+
+    /// 最后操作时间
+    pub last_action: Option<DateTime<Utc>>,
+
+    /// 错误信息
+    pub error: Option<String>,
+}
+
+pub enum PowerState {
+    On,
+    Off,
+    Unknown,
+}
+```
+
+### 3.2 AtxButton (executor.rs)
+
+```rust
+pub struct AtxButton {
+    /// 按钮名称
+    name: String,
+
+    /// 驱动类型
+    driver: AtxDriverType,
+
+    /// GPIO 句柄
+    gpio: Option<LineHandle>,
+
+    /// USB 继电器句柄
+    relay: Option<UsbRelay>,
+
+    /// 配置
+    config: AtxKeyConfig,
+}
+
+impl AtxButton {
+    /// 创建按钮
+    pub fn new(name: &str, config: &AtxKeyConfig) -> Result<Self>;
+
+    /// 短按 (100ms)
+    pub async fn short_press(&self) -> Result<()>;
+
+    /// 长按 (3000ms)
+    pub async fn long_press(&self) -> Result<()>;
+
+    /// 自定义按压时间
+    pub async fn press(&self, duration: Duration) -> Result<()>;
+
+    /// 设置输出状态
+    fn set_output(&self, high: bool) -> Result<()>;
+}
+
+pub enum AtxDriverType {
+    /// GPIO 直连
+    Gpio,
+
+    /// USB 继电器
+    UsbRelay,
+
+    /// 禁用
+    None,
+}
+```
+
+### 3.3 LedMonitor (led.rs)
+
+```rust
+pub struct LedMonitor {
+    /// GPIO 引脚
+    pin: u32,
+
+    /// GPIO 句柄
+    line: LineHandle,
+
+    /// 当前状态
+    state: Arc<AtomicBool>,
+
+    /// 监视任务
+    monitor_task: Option<JoinHandle<()>>,
+}
+
+impl LedMonitor {
+    /// 创建监视器
+    pub fn new(config: &AtxLedConfig) -> Result<Self>;
+
+    /// 启动监视
+    pub fn start(&mut self, events: Arc<EventBus>) -> Result<()>;
+
+    /// 停止监视
+    pub fn stop(&mut self);
+
+    /// 获取当前状态
+    pub fn state(&self) -> bool;
+}
+```
+
+### 3.4 WolController (wol.rs)
+
+```rust
+pub struct WolController {
+    /// 网络接口
+    interface: String,
+
+    /// 广播地址
+    broadcast_addr: SocketAddr,
+}
+
+impl WolController {
+    /// 创建控制器
+    pub fn new(interface: Option<&str>) -> Result<Self>;
+
+    /// 发送 WoL 魔术包
+    pub async fn wake(&self, mac: &str) -> Result<()>;
+
+    /// 构建魔术包
+    fn build_magic_packet(mac: &[u8; 6]) -> [u8; 102];
+
+    /// 解析 MAC 地址
+    fn parse_mac(mac: &str) -> Result<[u8; 6]>;
+}
+```
+
+---
+
+## 4. 配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct AtxConfig {
+    /// 是否启用
+    pub enabled: bool,
+
+    /// 电源按钮配置
+    pub power: AtxKeyConfig,
+
+    /// 重置按钮配置
+    pub reset: AtxKeyConfig,
+
+    /// LED 监视配置
+    pub led: AtxLedConfig,
+
+    /// WoL 配置
+    pub wol: WolConfig,
+}
+
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct AtxKeyConfig {
+    /// 驱动类型
+    pub driver: AtxDriverType,
+
+    /// GPIO 芯片 (如 /dev/gpiochip0)
+    pub gpio_chip: Option<String>,
+
+    /// GPIO 引脚号
+    pub gpio_pin: Option<u32>,
+
+    /// USB 继电器设备
+    pub relay_device: Option<String>,
+
+    /// 继电器通道
+    pub relay_channel: Option<u8>,
+
+    /// 激活电平
+    pub active_level: ActiveLevel,
+}
+
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct AtxLedConfig {
+    /// 是否启用
+    pub enabled: bool,
+
+    /// GPIO 芯片
+    pub gpio_chip: Option<String>,
+
+    /// GPIO 引脚号
+    pub gpio_pin: Option<u32>,
+
+    /// 激活电平
+    pub active_level: ActiveLevel,
+}
+
+pub enum ActiveLevel {
+    High,
+    Low,
+}
+
+impl Default for AtxConfig {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            power: AtxKeyConfig::default(),
+            reset: AtxKeyConfig::default(),
+            led: AtxLedConfig::default(),
+            wol: WolConfig::default(),
+        }
+    }
+}
+```
+
+---
+
+## 5. API 端点
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/atx/status` | GET | 获取 ATX 状态 |
+| `/api/atx/power/short` | POST | 短按电源 |
+| `/api/atx/power/long` | POST | 长按电源 |
+| `/api/atx/reset` | POST | 按重置 |
+| `/api/atx/wol` | POST | 发送 WoL |
+
+### 响应格式
+
+```json
+// GET /api/atx/status
+{
+    "available": true,
+    "power_on": true,
+    "last_action": "2024-01-15T10:30:00Z",
+    "error": null
+}
+
+// POST /api/atx/wol
+// Request: { "mac": "00:11:22:33:44:55" }
+{
+    "success": true
+}
+```
+
+---
+
+## 6. 硬件连接
+
+### 6.1 GPIO 直连
+
+```
+One-KVM Device                 Target PC
+┌─────────────┐               ┌─────────────┐
+│   GPIO Pin  │───────────────│ Power SW    │
+│   (Output)  │               │             │
+└─────────────┘               └─────────────┘
+
+接线说明:
+- GPIO 引脚连接到 ATX 电源按钮
+- 使用光耦或继电器隔离 (推荐)
+- 注意电平匹配
+```
+
+### 6.2 USB 继电器
+
+```
+One-KVM Device                 USB Relay                Target PC
+┌─────────────┐               ┌─────────────┐          ┌─────────────┐
+│    USB      │───────────────│   Relay     │──────────│ Power SW    │
+│             │               │             │          │             │
+└─────────────┘               └─────────────┘          └─────────────┘
+
+优点:
+- 完全隔离
+- 无需担心电平问题
+- 更安全
+```
+
+---
+
+## 7. 事件
+
+```rust
+pub enum SystemEvent {
+    AtxStateChanged {
+        power_on: bool,
+        last_action: Option<String>,
+        error: Option<String>,
+    },
+
+    AtxActionPerformed {
+        action: String,  // "power_short" | "power_long" | "reset" | "wol"
+        success: bool,
+    },
+}
+```
+
+---
+
+## 8. 错误处理
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum AtxError {
+    #[error("ATX not available")]
+    NotAvailable,
+
+    #[error("GPIO error: {0}")]
+    GpioError(String),
+
+    #[error("Relay error: {0}")]
+    RelayError(String),
+
+    #[error("WoL error: {0}")]
+    WolError(String),
+
+    #[error("Invalid MAC address: {0}")]
+    InvalidMac(String),
+
+    #[error("Operation in progress")]
+    Busy,
+}
+```
+
+---
+
+## 9. 使用示例
+
+```rust
+let atx = AtxController::new(&config, events)?;
+
+// 开机
+atx.power_short_press().await?;
+
+// 检查状态
+tokio::time::sleep(Duration::from_secs(5)).await;
+if atx.power_state() == PowerState::On {
+    println!("PC is now on");
+}
+
+// 强制关机
+atx.power_long_press().await?;
+
+// 重置
+atx.reset_press().await?;
+
+// Wake-on-LAN
+atx.wake_on_lan("00:11:22:33:44:55").await?;
+```
+
+---
+
+## 10. 常见问题
+
+### Q: GPIO 无法控制?
+
+1. 检查引脚配置
+2. 检查权限 (`/dev/gpiochip*`)
+3. 检查接线
+
+### Q: LED 状态不正确?
+
+1. 检查 active_level 配置
+2. 检查 GPIO 输入模式
+
+### Q: WoL 不工作?
+
+1. 检查目标 PC BIOS 设置
+2. 检查网卡支持
+3. 检查网络广播

docs/modules/audio.md

@@ -0,0 +1,463 @@
+# Audio 模块文档
+
+## 1. 模块概述
+
+Audio 模块负责音频采集和编码，支持 ALSA 采集和 Opus 编码。
+
+### 1.1 主要功能
+
+- ALSA 音频采集
+- Opus 编码
+- 多质量配置
+- WebSocket/WebRTC 传输
+
+### 1.2 文件结构
+
+```
+src/audio/
+├── mod.rs              # 模块导出
+├── controller.rs       # AudioController (15KB)
+├── capture.rs          # ALSA 采集 (12KB)
+├── encoder.rs          # Opus 编码 (8KB)
+├── shared_pipeline.rs  # 共享管道 (15KB)
+├── monitor.rs          # 健康监视 (11KB)
+└── device.rs           # 设备枚举 (8KB)
+```
+
+---
+
+## 2. 架构设计
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Audio Architecture                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+ALSA Device (hw:0,0)
+        │
+        │ PCM 48kHz/16bit/Stereo
+        ▼
+┌─────────────────┐
+│ AudioCapturer   │
+│  (capture.rs)   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│         SharedAudioPipeline             │
+│  ┌─────────────────────────────────┐   │
+│  │      Opus Encoder               │   │
+│  │   48kHz → 24-96 kbps            │   │
+│  └─────────────────────────────────┘   │
+└────────────────┬────────────────────────┘
+                 │
+       ┌─────────┴─────────┐
+       │                   │
+       ▼                   ▼
+┌─────────────┐    ┌─────────────┐
+│  WebSocket  │    │   WebRTC    │
+│   Stream    │    │ Audio Track │
+└─────────────┘    └─────────────┘
+```
+
+---
+
+## 3. 核心组件
+
+### 3.1 AudioController (controller.rs)
+
+```rust
+pub struct AudioController {
+    /// 采集器
+    capturer: Arc<RwLock<Option<AudioCapturer>>>,
+
+    /// 共享管道
+    pipeline: Arc<SharedAudioPipeline>,
+
+    /// 配置
+    config: Arc<RwLock<AudioConfig>>,
+
+    /// 状态
+    state: Arc<RwLock<AudioState>>,
+
+    /// 事件总线
+    events: Arc<EventBus>,
+}
+
+impl AudioController {
+    /// 创建控制器
+    pub fn new(config: &AudioConfig, events: Arc<EventBus>) -> Result<Self>;
+
+    /// 启动音频
+    pub async fn start(&self) -> Result<()>;
+
+    /// 停止音频
+    pub async fn stop(&self) -> Result<()>;
+
+    /// 订阅音频帧
+    pub fn subscribe(&self) -> broadcast::Receiver<AudioFrame>;
+
+    /// 获取状态
+    pub fn status(&self) -> AudioStatus;
+
+    /// 设置质量
+    pub fn set_quality(&self, quality: AudioQuality) -> Result<()>;
+
+    /// 列出设备
+    pub fn list_devices(&self) -> Vec<AudioDeviceInfo>;
+
+    /// 重新加载配置
+    pub async fn reload(&self, config: &AudioConfig) -> Result<()>;
+}
+
+pub struct AudioStatus {
+    pub enabled: bool,
+    pub streaming: bool,
+    pub device: Option<String>,
+    pub sample_rate: u32,
+    pub channels: u16,
+    pub bitrate: u32,
+    pub error: Option<String>,
+}
+```
+
+### 3.2 AudioCapturer (capture.rs)
+
+```rust
+pub struct AudioCapturer {
+    /// PCM 句柄
+    pcm: PCM,
+
+    /// 设备名
+    device: String,
+
+    /// 采样率
+    sample_rate: u32,
+
+    /// 通道数
+    channels: u16,
+
+    /// 帧大小
+    frame_size: usize,
+
+    /// 运行状态
+    running: AtomicBool,
+}
+
+impl AudioCapturer {
+    /// 打开设备
+    pub fn open(device: &str, config: &CaptureConfig) -> Result<Self>;
+
+    /// 读取音频帧
+    pub fn read_frame(&self) -> Result<Vec<i16>>;
+
+    /// 启动采集
+    pub fn start(&self) -> Result<()>;
+
+    /// 停止采集
+    pub fn stop(&self);
+
+    /// 是否运行中
+    pub fn is_running(&self) -> bool;
+}
+
+pub struct CaptureConfig {
+    pub sample_rate: u32,   // 48000
+    pub channels: u16,      // 2
+    pub frame_size: usize,  // 960 (20ms)
+    pub buffer_size: usize, // 4800
+}
+```
+
+### 3.3 OpusEncoder (encoder.rs)
+
+```rust
+pub struct OpusEncoder {
+    /// Opus 编码器
+    encoder: audiopus::Encoder,
+
+    /// 采样率
+    sample_rate: u32,
+
+    /// 通道数
+    channels: u16,
+
+    /// 帧大小
+    frame_size: usize,
+
+    /// 码率
+    bitrate: u32,
+}
+
+impl OpusEncoder {
+    /// 创建编码器
+    pub fn new(quality: AudioQuality) -> Result<Self>;
+
+    /// 编码 PCM 数据
+    pub fn encode(&mut self, pcm: &[i16]) -> Result<Vec<u8>>;
+
+    /// 设置码率
+    pub fn set_bitrate(&mut self, bitrate: u32) -> Result<()>;
+
+    /// 获取码率
+    pub fn bitrate(&self) -> u32;
+
+    /// 重置编码器
+    pub fn reset(&mut self) -> Result<()>;
+}
+```
+
+### 3.4 SharedAudioPipeline (shared_pipeline.rs)
+
+```rust
+pub struct SharedAudioPipeline {
+    /// 采集器
+    capturer: Arc<RwLock<Option<AudioCapturer>>>,
+
+    /// 编码器
+    encoder: Arc<Mutex<OpusEncoder>>,
+
+    /// 广播通道
+    tx: broadcast::Sender<AudioFrame>,
+
+    /// 采集任务
+    capture_task: Arc<RwLock<Option<JoinHandle<()>>>>,
+
+    /// 配置
+    config: Arc<RwLock<AudioConfig>>,
+}
+
+impl SharedAudioPipeline {
+    /// 创建管道
+    pub fn new(config: &AudioConfig) -> Result<Self>;
+
+    /// 启动管道
+    pub async fn start(&self) -> Result<()>;
+
+    /// 停止管道
+    pub async fn stop(&self) -> Result<()>;
+
+    /// 订阅音频帧
+    pub fn subscribe(&self) -> broadcast::Receiver<AudioFrame>;
+
+    /// 获取统计
+    pub fn stats(&self) -> PipelineStats;
+}
+
+pub struct AudioFrame {
+    /// Opus 数据
+    pub data: Bytes,
+
+    /// 时间戳
+    pub timestamp: u64,
+
+    /// 帧序号
+    pub sequence: u64,
+}
+```
+
+---
+
+## 4. 音频质量
+
+```rust
+pub enum AudioQuality {
+    /// 24 kbps - 最低带宽
+    VeryLow,
+
+    /// 48 kbps - 低带宽
+    Low,
+
+    /// 64 kbps - 中等
+    Medium,
+
+    /// 96 kbps - 高质量
+    High,
+}
+
+impl AudioQuality {
+    pub fn bitrate(&self) -> u32 {
+        match self {
+            Self::VeryLow => 24000,
+            Self::Low => 48000,
+            Self::Medium => 64000,
+            Self::High => 96000,
+        }
+    }
+}
+```
+
+---
+
+## 5. 配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct AudioConfig {
+    /// 是否启用
+    pub enabled: bool,
+
+    /// 设备名
+    pub device: Option<String>,
+
+    /// 音频质量
+    pub quality: AudioQuality,
+
+    /// 自动启动
+    pub auto_start: bool,
+}
+
+impl Default for AudioConfig {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            device: None,  // 使用默认设备
+            quality: AudioQuality::Medium,
+            auto_start: false,
+        }
+    }
+}
+```
+
+---
+
+## 6. API 端点
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/audio/status` | GET | 获取音频状态 |
+| `/api/audio/start` | POST | 启动音频 |
+| `/api/audio/stop` | POST | 停止音频 |
+| `/api/audio/devices` | GET | 列出设备 |
+| `/api/audio/quality` | GET | 获取质量 |
+| `/api/audio/quality` | POST | 设置质量 |
+| `/api/ws/audio` | WS | 音频流 |
+
+### 响应格式
+
+```json
+// GET /api/audio/status
+{
+    "enabled": true,
+    "streaming": true,
+    "device": "hw:0,0",
+    "sample_rate": 48000,
+    "channels": 2,
+    "bitrate": 64000,
+    "error": null
+}
+
+// GET /api/audio/devices
+{
+    "devices": [
+        {
+            "name": "hw:0,0",
+            "description": "USB Audio Device",
+            "is_default": true
+        }
+    ]
+}
+```
+
+---
+
+## 7. WebSocket 音频流
+
+```javascript
+// 连接 WebSocket
+const ws = new WebSocket('/api/ws/audio');
+ws.binaryType = 'arraybuffer';
+
+// 初始化 Opus 解码器
+const decoder = new OpusDecoder();
+
+// 接收音频帧
+ws.onmessage = (event) => {
+    const frame = new Uint8Array(event.data);
+    const pcm = decoder.decode(frame);
+    audioContext.play(pcm);
+};
+```
+
+---
+
+## 8. 事件
+
+```rust
+pub enum SystemEvent {
+    AudioStateChanged {
+        enabled: bool,
+        streaming: bool,
+        device: Option<String>,
+        error: Option<String>,
+    },
+}
+```
+
+---
+
+## 9. 错误处理
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum AudioError {
+    #[error("Device not found: {0}")]
+    DeviceNotFound(String),
+
+    #[error("Device busy: {0}")]
+    DeviceBusy(String),
+
+    #[error("ALSA error: {0}")]
+    AlsaError(String),
+
+    #[error("Encoder error: {0}")]
+    EncoderError(String),
+
+    #[error("Not streaming")]
+    NotStreaming,
+}
+```
+
+---
+
+## 10. 使用示例
+
+```rust
+let controller = AudioController::new(&config, events)?;
+
+// 启动音频
+controller.start().await?;
+
+// 订阅音频帧
+let mut rx = controller.subscribe();
+while let Ok(frame) = rx.recv().await {
+    // 处理 Opus 数据
+    send_to_client(frame.data);
+}
+
+// 停止
+controller.stop().await?;
+```
+
+---
+
+## 11. 常见问题
+
+### Q: 找不到音频设备?
+
+1. 检查 ALSA 配置
+2. 运行 `arecord -l`
+3. 检查权限
+
+### Q: 音频延迟高?
+
+1. 减小帧大小
+2. 降低质量
+3. 检查网络
+
+### Q: 音频断断续续?
+
+1. 增大缓冲区
+2. 检查 CPU 负载
+3. 使用更低质量

docs/modules/auth.md

@@ -0,0 +1,340 @@
+# Auth 模块文档
+
+## 1. 模块概述
+
+Auth 模块提供用户认证和会话管理功能。
+
+### 1.1 主要功能
+
+- 用户管理
+- 密码哈希 (Argon2)
+- 会话管理
+- 认证中间件
+- 权限控制
+
+### 1.2 文件结构
+
+```
+src/auth/
+├── mod.rs              # 模块导出
+├── user.rs             # 用户管理 (5KB)
+├── session.rs          # 会话管理 (4KB)
+├── password.rs         # 密码哈希 (1KB)
+└── middleware.rs       # 中间件 (4KB)
+```
+
+---
+
+## 2. 核心组件
+
+### 2.1 UserStore (user.rs)
+
+```rust
+pub struct UserStore {
+    db: Pool<Sqlite>,
+}
+
+impl UserStore {
+    /// 创建存储
+    pub async fn new(db: Pool<Sqlite>) -> Result<Self>;
+
+    /// 创建用户
+    pub async fn create_user(&self, user: &CreateUser) -> Result<User>;
+
+    /// 获取用户
+    pub async fn get_user(&self, id: &str) -> Result<Option<User>>;
+
+    /// 按用户名获取
+    pub async fn get_by_username(&self, username: &str) -> Result<Option<User>>;
+
+    /// 更新用户
+    pub async fn update_user(&self, id: &str, update: &UpdateUser) -> Result<()>;
+
+    /// 删除用户
+    pub async fn delete_user(&self, id: &str) -> Result<()>;
+
+    /// 列出用户
+    pub async fn list_users(&self) -> Result<Vec<User>>;
+
+    /// 验证密码
+    pub async fn verify_password(&self, username: &str, password: &str) -> Result<Option<User>>;
+
+    /// 更新密码
+    pub async fn update_password(&self, id: &str, new_password: &str) -> Result<()>;
+
+    /// 检查是否需要初始化
+    pub async fn needs_setup(&self) -> Result<bool>;
+}
+
+pub struct User {
+    pub id: String,
+    pub username: String,
+    pub role: UserRole,
+    pub created_at: DateTime<Utc>,
+}
+
+pub enum UserRole {
+    Admin,
+    User,
+}
+
+pub struct CreateUser {
+    pub username: String,
+    pub password: String,
+    pub role: UserRole,
+}
+```
+
+### 2.2 SessionStore (session.rs)
+
+```rust
+pub struct SessionStore {
+    /// 会话映射
+    sessions: RwLock<HashMap<String, Session>>,
+
+    /// 会话超时
+    timeout: Duration,
+}
+
+impl SessionStore {
+    /// 创建存储
+    pub fn new(timeout: Duration) -> Self;
+
+    /// 创建会话
+    pub fn create_session(&self, user: &User) -> String;
+
+    /// 获取会话
+    pub fn get_session(&self, token: &str) -> Option<Session>;
+
+    /// 删除会话
+    pub fn delete_session(&self, token: &str);
+
+    /// 清理过期会话
+    pub fn cleanup_expired(&self);
+
+    /// 刷新会话
+    pub fn refresh_session(&self, token: &str) -> bool;
+}
+
+pub struct Session {
+    pub token: String,
+    pub user_id: String,
+    pub username: String,
+    pub role: UserRole,
+    pub created_at: Instant,
+    pub last_active: Instant,
+}
+```
+
+### 2.3 密码哈希 (password.rs)
+
+```rust
+/// 哈希密码
+pub fn hash_password(password: &str) -> Result<String> {
+    let salt = SaltString::generate(&mut OsRng);
+    let argon2 = Argon2::default();
+    let hash = argon2
+        .hash_password(password.as_bytes(), &salt)?
+        .to_string();
+    Ok(hash)
+}
+
+/// 验证密码
+pub fn verify_password(password: &str, hash: &str) -> Result<bool> {
+    let parsed_hash = PasswordHash::new(hash)?;
+    Ok(Argon2::default()
+        .verify_password(password.as_bytes(), &parsed_hash)
+        .is_ok())
+}
+```
+
+### 2.4 认证中间件 (middleware.rs)
+
+```rust
+pub async fn auth_middleware(
+    State(state): State<Arc<AppState>>,
+    cookies: Cookies,
+    request: Request,
+    next: Next,
+) -> Response {
+    // 获取 session token
+    let token = cookies
+        .get("session_id")
+        .map(|c| c.value().to_string());
+
+    // 验证会话
+    let session = token
+        .and_then(|t| state.sessions.get_session(&t));
+
+    if let Some(session) = session {
+        // 将用户信息注入请求
+        let mut request = request;
+        request.extensions_mut().insert(session);
+        next.run(request).await
+    } else {
+        StatusCode::UNAUTHORIZED.into_response()
+    }
+}
+
+pub async fn admin_middleware(
+    session: Extension<Session>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if session.role == UserRole::Admin {
+        next.run(request).await
+    } else {
+        StatusCode::FORBIDDEN.into_response()
+    }
+}
+```
+
+---
+
+## 3. API 端点
+
+| 端点 | 方法 | 权限 | 描述 |
+|------|------|------|------|
+| `/api/auth/login` | POST | Public | 登录 |
+| `/api/auth/logout` | POST | User | 登出 |
+| `/api/auth/check` | GET | User | 检查认证 |
+| `/api/auth/password` | POST | User | 修改密码 |
+| `/api/users` | GET | Admin | 列出用户 |
+| `/api/users` | POST | Admin | 创建用户 |
+| `/api/users/:id` | DELETE | Admin | 删除用户 |
+| `/api/setup/init` | POST | Public | 初始化设置 |
+
+### 请求/响应格式
+
+```json
+// POST /api/auth/login
+// Request:
+{
+    "username": "admin",
+    "password": "password123"
+}
+
+// Response:
+{
+    "user": {
+        "id": "uuid",
+        "username": "admin",
+        "role": "admin"
+    }
+}
+
+// GET /api/auth/check
+{
+    "authenticated": true,
+    "user": {
+        "id": "uuid",
+        "username": "admin",
+        "role": "admin"
+    }
+}
+```
+
+---
+
+## 4. 配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct AuthConfig {
+    /// 会话超时 (秒)
+    pub session_timeout_secs: u64,
+
+    /// 是否启用认证
+    pub enabled: bool,
+}
+
+impl Default for AuthConfig {
+    fn default() -> Self {
+        Self {
+            session_timeout_secs: 86400,  // 24 小时
+            enabled: true,
+        }
+    }
+}
+```
+
+---
+
+## 5. 安全特性
+
+### 5.1 密码存储
+
+- Argon2id 哈希
+- 随机盐值
+- 不可逆
+
+### 5.2 会话安全
+
+- 随机 token (UUID v4)
+- HTTPOnly Cookie
+- 会话超时
+- 自动清理
+
+### 5.3 权限控制
+
+- 两级权限: Admin / User
+- 中间件检查
+- 敏感操作需 Admin
+
+---
+
+## 6. 使用示例
+
+```rust
+// 创建用户
+let user = users.create_user(&CreateUser {
+    username: "admin".to_string(),
+    password: "password123".to_string(),
+    role: UserRole::Admin,
+}).await?;
+
+// 验证密码
+if let Some(user) = users.verify_password("admin", "password123").await? {
+    // 创建会话
+    let token = sessions.create_session(&user);
+
+    // 设置 Cookie
+    cookies.add(Cookie::build("session_id", token)
+        .http_only(true)
+        .path("/")
+        .finish());
+}
+
+// 获取会话
+if let Some(session) = sessions.get_session(&token) {
+    println!("User: {}", session.username);
+}
+```
+
+---
+
+## 7. 错误处理
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum AuthError {
+    #[error("Invalid credentials")]
+    InvalidCredentials,
+
+    #[error("User not found")]
+    UserNotFound,
+
+    #[error("User already exists")]
+    UserExists,
+
+    #[error("Session expired")]
+    SessionExpired,
+
+    #[error("Permission denied")]
+    PermissionDenied,
+
+    #[error("Setup required")]
+    SetupRequired,
+}
+```

docs/modules/config.md

@@ -0,0 +1,297 @@
+# Config 模块文档
+
+## 1. 模块概述
+
+Config 模块提供配置管理功能，所有配置存储在 SQLite 数据库中。
+
+### 1.1 主要功能
+
+- SQLite 配置存储
+- 类型安全的配置结构
+- 热重载支持
+- TypeScript 类型生成
+
+### 1.2 文件结构
+
+```
+src/config/
+├── mod.rs              # 模块导出
+├── schema.rs           # 配置结构定义 (12KB)
+└── store.rs            # SQLite 存储 (8KB)
+```
+
+---
+
+## 2. 核心组件
+
+### 2.1 ConfigStore (store.rs)
+
+```rust
+pub struct ConfigStore {
+    db: Pool<Sqlite>,
+}
+
+impl ConfigStore {
+    /// 创建存储
+    pub async fn new(db_path: &Path) -> Result<Self>;
+
+    /// 获取完整配置
+    pub async fn get_config(&self) -> Result<AppConfig>;
+
+    /// 更新配置
+    pub async fn update_config(&self, config: &AppConfig) -> Result<()>;
+
+    /// 获取单个配置项
+    pub async fn get<T: DeserializeOwned>(&self, key: &str) -> Result<Option<T>>;
+
+    /// 设置单个配置项
+    pub async fn set<T: Serialize>(&self, key: &str, value: &T) -> Result<()>;
+
+    /// 删除配置项
+    pub async fn delete(&self, key: &str) -> Result<()>;
+
+    /// 重置为默认
+    pub async fn reset_to_default(&self) -> Result<()>;
+}
+```
+
+### 2.2 AppConfig (schema.rs)
+
+```rust
+#[derive(Serialize, Deserialize, Default)]
+#[typeshare]
+pub struct AppConfig {
+    /// 视频配置
+    pub video: VideoConfig,
+
+    /// 流配置
+    pub stream: StreamConfig,
+
+    /// HID 配置
+    pub hid: HidConfig,
+
+    /// MSD 配置
+    pub msd: MsdConfig,
+
+    /// ATX 配置
+    pub atx: AtxConfig,
+
+    /// 音频配置
+    pub audio: AudioConfig,
+
+    /// 认证配置
+    pub auth: AuthConfig,
+
+    /// Web 配置
+    pub web: WebConfig,
+
+    /// RustDesk 配置
+    pub rustdesk: RustDeskConfig,
+
+    /// 扩展配置
+    pub extensions: ExtensionsConfig,
+}
+```
+
+### 2.3 各模块配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct VideoConfig {
+    pub device: Option<String>,
+    pub format: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub fps: u32,
+    pub quality: u32,
+}
+
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct StreamConfig {
+    pub mode: StreamMode,
+    pub bitrate_kbps: u32,
+    pub gop_size: u32,
+    pub encoder: EncoderType,
+    pub stun_server: Option<String>,
+    pub turn_server: Option<String>,
+    pub turn_username: Option<String>,
+    pub turn_password: Option<String>,
+}
+
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct HidConfig {
+    pub backend: HidBackendType,
+    pub ch9329_device: Option<String>,
+    pub ch9329_baud_rate: Option<u32>,
+    pub default_mouse_mode: MouseMode,
+}
+
+// ... 其他配置结构
+```
+
+---
+
+## 3. TypeScript 类型生成
+
+使用 `#[typeshare]` 属性自动生成 TypeScript 类型：
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct VideoConfig {
+    pub device: Option<String>,
+    pub width: u32,
+    pub height: u32,
+}
+```
+
+生成的 TypeScript：
+
+```typescript
+export interface VideoConfig {
+    device?: string;
+    width: number;
+    height: number;
+}
+```
+
+生成命令：
+
+```bash
+./scripts/generate-types.sh
+# 或
+typeshare src --lang=typescript --output-file=web/src/types/generated.ts
+```
+
+---
+
+## 4. API 端点
+
+| 端点 | 方法 | 权限 | 描述 |
+|------|------|------|------|
+| `/api/config` | GET | Admin | 获取完整配置 |
+| `/api/config` | PATCH | Admin | 更新配置 |
+| `/api/config/video` | GET | Admin | 获取视频配置 |
+| `/api/config/video` | PATCH | Admin | 更新视频配置 |
+| `/api/config/stream` | GET | Admin | 获取流配置 |
+| `/api/config/stream` | PATCH | Admin | 更新流配置 |
+| `/api/config/hid` | GET | Admin | 获取 HID 配置 |
+| `/api/config/hid` | PATCH | Admin | 更新 HID 配置 |
+| `/api/config/reset` | POST | Admin | 重置为默认 |
+
+### 响应格式
+
+```json
+// GET /api/config/video
+{
+    "device": "/dev/video0",
+    "format": "MJPEG",
+    "width": 1920,
+    "height": 1080,
+    "fps": 30,
+    "quality": 80
+}
+
+// PATCH /api/config/video
+// Request:
+{
+    "width": 1280,
+    "height": 720
+}
+
+// Response: 更新后的完整配置
+```
+
+---
+
+## 5. 配置热重载
+
+配置更改后自动重载相关组件：
+
+```rust
+// 更新配置
+config_store.update_config(&new_config).await?;
+
+// 发布配置变更事件
+events.publish(SystemEvent::ConfigChanged {
+    section: "video".to_string(),
+});
+
+// 各组件监听事件并重载
+// VideoStreamManager::on_config_changed()
+// HidController::reload()
+// etc.
+```
+
+---
+
+## 6. 数据库结构
+
+```sql
+CREATE TABLE IF NOT EXISTS config (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+```
+
+配置以 JSON 格式存储：
+
+```
+key: "app_config"
+value: { "video": {...}, "hid": {...}, ... }
+```
+
+---
+
+## 7. 使用示例
+
+```rust
+// 获取配置
+let config = config_store.get_config().await?;
+println!("Video device: {:?}", config.video.device);
+
+// 更新配置
+let mut config = config_store.get_config().await?;
+config.video.width = 1280;
+config.video.height = 720;
+config_store.update_config(&config).await?;
+
+// 获取单个配置项
+let video: Option<VideoConfig> = config_store.get("video").await?;
+
+// 设置单个配置项
+config_store.set("video", &video_config).await?;
+```
+
+---
+
+## 8. 默认配置
+
+```rust
+impl Default for AppConfig {
+    fn default() -> Self {
+        Self {
+            video: VideoConfig {
+                device: None,
+                format: None,
+                width: 1920,
+                height: 1080,
+                fps: 30,
+                quality: 80,
+            },
+            stream: StreamConfig {
+                mode: StreamMode::Mjpeg,
+                bitrate_kbps: 2000,
+                gop_size: 60,
+                encoder: EncoderType::H264,
+                ..Default::default()
+            },
+            // ...
+        }
+    }
+}
+```

docs/modules/events.md

@@ -0,0 +1,353 @@
+# Events 模块文档
+
+## 1. 模块概述
+
+Events 模块提供事件总线功能，用于模块间通信和状态广播。
+
+### 1.1 主要功能
+
+- 事件发布/订阅
+- 多订阅者广播
+- WebSocket 事件推送
+- 状态变更通知
+
+### 1.2 文件结构
+
+```
+src/events/
+└── mod.rs              # EventBus 实现
+```
+
+---
+
+## 2. 架构设计
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          Event System                                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌────────────────┐ ┌────────────────┐ ┌────────────────┐
+│     Video      │ │      HID       │ │     Audio      │
+│    Module      │ │    Module      │ │    Module      │
+└───────┬────────┘ └───────┬────────┘ └───────┬────────┘
+        │                  │                  │
+        │   publish()      │   publish()      │   publish()
+        └──────────────────┼──────────────────┘
+                           │
+                           ▼
+                ┌─────────────────────┐
+                │      EventBus       │
+                │ (broadcast channel) │
+                └──────────┬──────────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         │                 │                 │
+         │   subscribe()   │   subscribe()   │
+         ▼                 ▼                 ▼
+┌────────────────┐ ┌────────────────┐ ┌────────────────┐
+│   WebSocket    │ │   DeviceInfo   │ │   Internal     │
+│   Handler      │ │  Broadcaster   │ │    Tasks       │
+└────────────────┘ └────────────────┘ └────────────────┘
+```
+
+---
+
+## 3. 核心组件
+
+### 3.1 EventBus
+
+```rust
+pub struct EventBus {
+    /// 广播发送器
+    tx: broadcast::Sender<SystemEvent>,
+}
+
+impl EventBus {
+    /// 创建事件总线
+    pub fn new() -> Self {
+        let (tx, _) = broadcast::channel(1024);
+        Self { tx }
+    }
+
+    /// 发布事件
+    pub fn publish(&self, event: SystemEvent) {
+        let _ = self.tx.send(event);
+    }
+
+    /// 订阅事件
+    pub fn subscribe(&self) -> broadcast::Receiver<SystemEvent> {
+        self.tx.subscribe()
+    }
+}
+```
+
+### 3.2 SystemEvent
+
+```rust
+#[derive(Clone, Debug, Serialize)]
+pub enum SystemEvent {
+    // 视频事件
+    StreamStateChanged {
+        state: String,
+        device: Option<String>,
+        resolution: Option<Resolution>,
+        fps: Option<f32>,
+    },
+
+    VideoDeviceChanged {
+        added: Vec<String>,
+        removed: Vec<String>,
+    },
+
+    // HID 事件
+    HidStateChanged {
+        backend: String,
+        initialized: bool,
+        keyboard_connected: bool,
+        mouse_connected: bool,
+        mouse_mode: String,
+        error: Option<String>,
+    },
+
+    // MSD 事件
+    MsdStateChanged {
+        mode: String,
+        connected: bool,
+        image: Option<String>,
+        error: Option<String>,
+    },
+
+    MsdDownloadProgress {
+        download_id: String,
+        downloaded: u64,
+        total: u64,
+        speed: u64,
+    },
+
+    // ATX 事件
+    AtxStateChanged {
+        power_on: bool,
+        last_action: Option<String>,
+        error: Option<String>,
+    },
+
+    // 音频事件
+    AudioStateChanged {
+        enabled: bool,
+        streaming: bool,
+        device: Option<String>,
+        error: Option<String>,
+    },
+
+    // 配置事件
+    ConfigChanged {
+        section: String,
+    },
+
+    // 设备信息汇总
+    DeviceInfo {
+        video: VideoInfo,
+        hid: HidInfo,
+        msd: MsdInfo,
+        atx: AtxInfo,
+        audio: AudioInfo,
+    },
+
+    // 系统错误
+    SystemError {
+        module: String,
+        severity: String,
+        message: String,
+    },
+
+    // RustDesk 事件
+    RustDeskStatusChanged {
+        status: String,
+        device_id: Option<String>,
+        error: Option<String>,
+    },
+
+    RustDeskConnectionOpened {
+        connection_id: String,
+        peer_id: String,
+    },
+
+    RustDeskConnectionClosed {
+        connection_id: String,
+        peer_id: String,
+        reason: String,
+    },
+}
+```
+
+---
+
+## 4. 设备信息广播器
+
+在 `main.rs` 中启动的后台任务：
+
+```rust
+pub fn spawn_device_info_broadcaster(
+    state: Arc<AppState>,
+    events: Arc<EventBus>,
+) -> JoinHandle<()> {
+    tokio::spawn(async move {
+        let mut rx = events.subscribe();
+        let mut debounce = tokio::time::interval(Duration::from_millis(100));
+        let mut pending = false;
+
+        loop {
+            tokio::select! {
+                // 收到事件
+                result = rx.recv() => {
+                    if result.is_ok() {
+                        pending = true;
+                    }
+                }
+
+                // 防抖定时器
+                _ = debounce.tick() => {
+                    if pending {
+                        pending = false;
+                        // 收集设备信息
+                        let device_info = state.get_device_info().await;
+                        // 广播
+                        events.publish(SystemEvent::DeviceInfo(device_info));
+                    }
+                }
+            }
+        }
+    })
+}
+```
+
+---
+
+## 5. WebSocket 事件推送
+
+```rust
+pub async fn ws_handler(
+    ws: WebSocketUpgrade,
+    State(state): State<Arc<AppState>>,
+) -> impl IntoResponse {
+    ws.on_upgrade(|socket| handle_ws(socket, state))
+}
+
+async fn handle_ws(mut socket: WebSocket, state: Arc<AppState>) {
+    let mut rx = state.events.subscribe();
+
+    loop {
+        tokio::select! {
+            // 发送事件给客户端
+            result = rx.recv() => {
+                if let Ok(event) = result {
+                    let json = serde_json::to_string(&event).unwrap();
+                    if socket.send(Message::Text(json)).await.is_err() {
+                        break;
+                    }
+                }
+            }
+
+            // 接收客户端消息
+            msg = socket.recv() => {
+                match msg {
+                    Some(Ok(Message::Close(_))) | None => break,
+                    _ => {}
+                }
+            }
+        }
+    }
+}
+```
+
+---
+
+## 6. 使用示例
+
+### 6.1 发布事件
+
+```rust
+// 视频模块发布状态变更
+events.publish(SystemEvent::StreamStateChanged {
+    state: "streaming".to_string(),
+    device: Some("/dev/video0".to_string()),
+    resolution: Some(Resolution { width: 1920, height: 1080 }),
+    fps: Some(30.0),
+});
+
+// HID 模块发布状态变更
+events.publish(SystemEvent::HidStateChanged {
+    backend: "otg".to_string(),
+    initialized: true,
+    keyboard_connected: true,
+    mouse_connected: true,
+    mouse_mode: "absolute".to_string(),
+    error: None,
+});
+```
+
+### 6.2 订阅事件
+
+```rust
+let mut rx = events.subscribe();
+
+loop {
+    match rx.recv().await {
+        Ok(SystemEvent::StreamStateChanged { state, .. }) => {
+            println!("Stream state: {}", state);
+        }
+        Ok(SystemEvent::HidStateChanged { backend, .. }) => {
+            println!("HID backend: {}", backend);
+        }
+        Err(_) => break,
+    }
+}
+```
+
+---
+
+## 7. 前端事件处理
+
+```typescript
+// 连接 WebSocket
+const ws = new WebSocket('/api/ws');
+
+ws.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+
+    switch (data.type) {
+        case 'StreamStateChanged':
+            updateStreamStatus(data);
+            break;
+        case 'HidStateChanged':
+            updateHidStatus(data);
+            break;
+        case 'MsdStateChanged':
+            updateMsdStatus(data);
+            break;
+        case 'DeviceInfo':
+            updateAllDevices(data);
+            break;
+    }
+};
+```
+
+---
+
+## 8. 最佳实践
+
+### 8.1 事件粒度
+
+- 使用细粒度事件便于精确更新
+- DeviceInfo 用于初始化和定期同步
+
+### 8.2 防抖
+
+- 使用 100ms 防抖避免事件风暴
+- 合并多个快速变更
+
+### 8.3 错误处理
+
+- 发布失败静默忽略 (fire-and-forget)
+- 订阅者断开自动清理

docs/modules/hid.md

@@ -0,0 +1,850 @@
+# HID 模块文档
+
+## 1. 模块概述
+
+HID (Human Interface Device) 模块负责将键盘和鼠标事件转发到目标计算机，是 One-KVM 实现远程控制的核心模块。
+
+### 1.1 主要功能
+
+- 键盘事件处理 (按键、修饰键)
+- 鼠标事件处理 (移动、点击、滚轮)
+- 支持绝对和相对鼠标模式
+- 多后端支持 (OTG、CH9329)
+- WebSocket 和 DataChannel 输入
+
+### 1.2 文件结构
+
+```
+src/hid/
+├── mod.rs              # HidController (16KB)
+├── backend.rs          # 后端抽象
+├── otg.rs              # OTG 后端 (33KB)
+├── ch9329.rs           # CH9329 串口后端 (46KB)
+├── keymap.rs           # 按键映射 (14KB)
+├── types.rs            # 类型定义
+├── monitor.rs          # 健康监视 (14KB)
+├── datachannel.rs      # DataChannel 适配 (8KB)
+└── websocket.rs        # WebSocket 适配 (6KB)
+```
+
+---
+
+## 2. 架构设计
+
+### 2.1 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          HID Architecture                                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+           Browser Input Events
+                   │
+         ┌─────────┴─────────┐
+         │                   │
+         ▼                   ▼
+┌─────────────────┐  ┌─────────────────┐
+│   WebSocket     │  │  DataChannel    │
+│   Handler       │  │   Handler       │
+│ (websocket.rs)  │  │(datachannel.rs) │
+└────────┬────────┘  └────────┬────────┘
+         │                    │
+         └──────────┬─────────┘
+                    │
+                    ▼
+         ┌─────────────────────┐
+         │   HidController     │
+         │     (mod.rs)        │
+         │  - send_keyboard()  │
+         │  - send_mouse()     │
+         │  - select_backend() │
+         └──────────┬──────────┘
+                    │
+         ┌──────────┼──────────┐
+         │          │          │
+         ▼          ▼          ▼
+┌─────────────┐ ┌──────────┐ ┌──────────┐
+│  OTG Backend│ │  CH9329  │ │   None   │
+│  (otg.rs)   │ │ Backend  │ │ (dummy)  │
+└──────┬──────┘ └────┬─────┘ └──────────┘
+       │             │
+       ▼             ▼
+┌─────────────┐ ┌──────────┐
+│ /dev/hidg*  │ │ Serial   │
+│ USB Gadget  │ │ Port     │
+└─────────────┘ └──────────┘
+       │             │
+       └──────┬──────┘
+              │
+              ▼
+      ┌─────────────┐
+      │  Target PC  │
+      └─────────────┘
+```
+
+### 2.2 后端选择
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Backend Selection                                     │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+HidBackendType::Otg
+    │
+    ├── 检查 OtgService 是否可用
+    │
+    ├── 请求 HID 函数 (3个设备)
+    │   ├── /dev/hidg0 (键盘)
+    │   ├── /dev/hidg1 (相对鼠标)
+    │   └── /dev/hidg2 (绝对鼠标)
+    │
+    └── 创建 OtgHidBackend
+
+HidBackendType::Ch9329 { port, baud_rate }
+    │
+    ├── 打开串口设备
+    │
+    ├── 初始化 CH9329 芯片
+    │
+    └── 创建 Ch9329HidBackend
+
+HidBackendType::None
+    │
+    └── 创建空后端 (丢弃所有事件)
+```
+
+---
+
+## 3. 核心组件
+
+### 3.1 HidController (mod.rs)
+
+HID 控制器主类，统一管理所有 HID 操作。
+
+```rust
+pub struct HidController {
+    /// 当前后端
+    backend: Arc<RwLock<Box<dyn HidBackend>>>,
+
+    /// 后端类型
+    backend_type: Arc<RwLock<HidBackendType>>,
+
+    /// OTG 服务引用
+    otg_service: Arc<OtgService>,
+
+    /// 健康监视器
+    monitor: Arc<HidHealthMonitor>,
+
+    /// 配置
+    config: Arc<RwLock<HidConfig>>,
+
+    /// 事件总线
+    events: Arc<EventBus>,
+
+    /// 鼠标模式
+    mouse_mode: Arc<RwLock<MouseMode>>,
+}
+
+impl HidController {
+    /// 初始化控制器
+    pub async fn init(
+        otg_service: Arc<OtgService>,
+        config: &HidConfig,
+        events: Arc<EventBus>,
+    ) -> Result<Arc<Self>>;
+
+    /// 发送键盘事件
+    pub async fn send_keyboard(&self, event: &KeyboardEvent) -> Result<()>;
+
+    /// 发送鼠标事件
+    pub async fn send_mouse(&self, event: &MouseEvent) -> Result<()>;
+
+    /// 设置鼠标模式
+    pub fn set_mouse_mode(&self, mode: MouseMode);
+
+    /// 获取鼠标模式
+    pub fn get_mouse_mode(&self) -> MouseMode;
+
+    /// 重新加载配置
+    pub async fn reload(&self, config: &HidConfig) -> Result<()>;
+
+    /// 重置 HID 状态
+    pub async fn reset(&self) -> Result<()>;
+
+    /// 获取状态信息
+    pub fn info(&self) -> HidInfo;
+}
+
+pub struct HidInfo {
+    pub backend: String,
+    pub initialized: bool,
+    pub keyboard_connected: bool,
+    pub mouse_connected: bool,
+    pub mouse_mode: MouseMode,
+    pub error: Option<String>,
+}
+```
+
+### 3.2 HidBackend Trait (backend.rs)
+
+```rust
+#[async_trait]
+pub trait HidBackend: Send + Sync {
+    /// 发送键盘事件
+    async fn send_keyboard(&self, event: &KeyboardEvent) -> Result<()>;
+
+    /// 发送鼠标事件
+    async fn send_mouse(&self, event: &MouseEvent, mode: MouseMode) -> Result<()>;
+
+    /// 重置状态
+    async fn reset(&self) -> Result<()>;
+
+    /// 获取后端信息
+    fn info(&self) -> HidBackendInfo;
+
+    /// 检查连接状态
+    fn is_connected(&self) -> bool;
+}
+
+pub struct HidBackendInfo {
+    pub name: String,
+    pub backend_type: HidBackendType,
+    pub keyboard_connected: bool,
+    pub mouse_connected: bool,
+}
+
+#[derive(Clone, Debug)]
+pub enum HidBackendType {
+    /// USB OTG gadget 模式
+    Otg,
+
+    /// CH9329 串口 HID 控制器
+    Ch9329 {
+        port: String,
+        baud_rate: u32,
+    },
+
+    /// 禁用 HID
+    None,
+}
+```
+
+### 3.3 OTG 后端 (otg.rs)
+
+通过 Linux USB OTG gadget 模拟 HID 设备。
+
+```rust
+pub struct OtgHidBackend {
+    /// HID 设备路径
+    paths: HidDevicePaths,
+
+    /// 键盘设备文件
+    keyboard_fd: RwLock<Option<File>>,
+
+    /// 相对鼠标设备文件
+    mouse_rel_fd: RwLock<Option<File>>,
+
+    /// 绝对鼠标设备文件
+    mouse_abs_fd: RwLock<Option<File>>,
+
+    /// 当前键盘状态
+    keyboard_state: Mutex<KeyboardState>,
+
+    /// OTG 服务引用
+    otg_service: Arc<OtgService>,
+}
+
+impl OtgHidBackend {
+    /// 创建 OTG 后端
+    pub async fn new(otg_service: Arc<OtgService>) -> Result<Self>;
+
+    /// 打开 HID 设备
+    async fn open_devices(&self) -> Result<()>;
+
+    /// 关闭 HID 设备
+    async fn close_devices(&self);
+
+    /// 写入键盘报告
+    fn write_keyboard_report(&self, report: &KeyboardReport) -> Result<()>;
+
+    /// 写入鼠标报告
+    fn write_mouse_report(&self, report: &[u8], absolute: bool) -> Result<()>;
+}
+
+pub struct HidDevicePaths {
+    pub keyboard: PathBuf,       // /dev/hidg0
+    pub mouse_relative: PathBuf, // /dev/hidg1
+    pub mouse_absolute: PathBuf, // /dev/hidg2
+}
+```
+
+#### HID 报告格式
+
+```rust
+/// 键盘报告 (8 字节)
+#[repr(C, packed)]
+pub struct KeyboardReport {
+    pub modifiers: u8,    // Ctrl, Shift, Alt, GUI
+    pub reserved: u8,     // 保留
+    pub keys: [u8; 6],    // 最多 6 个按键 scancode
+}
+
+/// 相对鼠标报告 (4 字节)
+#[repr(C, packed)]
+pub struct MouseRelativeReport {
+    pub buttons: u8,      // 按钮状态
+    pub x: i8,            // X 移动 (-127 ~ 127)
+    pub y: i8,            // Y 移动 (-127 ~ 127)
+    pub wheel: i8,        // 滚轮 (-127 ~ 127)
+}
+
+/// 绝对鼠标报告 (6 字节)
+#[repr(C, packed)]
+pub struct MouseAbsoluteReport {
+    pub buttons: u8,      // 按钮状态
+    pub x: u16,           // X 坐标 (0 ~ 32767)
+    pub y: u16,           // Y 坐标 (0 ~ 32767)
+    pub wheel: i8,        // 滚轮 (-127 ~ 127)
+}
+```
+
+### 3.4 CH9329 后端 (ch9329.rs)
+
+通过 CH9329 芯片（串口转 HID）实现 HID 功能。
+
+```rust
+pub struct Ch9329HidBackend {
+    /// 串口设备
+    port: Mutex<Box<dyn SerialPort>>,
+
+    /// 设备路径
+    device_path: String,
+
+    /// 波特率
+    baud_rate: u32,
+
+    /// 当前键盘状态
+    keyboard_state: Mutex<KeyboardState>,
+
+    /// 连接状态
+    connected: AtomicBool,
+}
+
+impl Ch9329HidBackend {
+    /// 创建 CH9329 后端
+    pub fn new(device: &str, baud_rate: u32) -> Result<Self>;
+
+    /// 发送命令
+    fn send_command(&self, cmd: &[u8]) -> Result<Vec<u8>>;
+
+    /// 发送键盘数据包
+    fn send_keyboard_packet(&self, report: &KeyboardReport) -> Result<()>;
+
+    /// 发送鼠标数据包
+    fn send_mouse_packet(&self, report: &[u8], absolute: bool) -> Result<()>;
+}
+```
+
+#### CH9329 协议
+
+```
+帧格式:
+┌──────┬──────┬──────┬──────────┬──────────┬──────┐
+│ HEAD │ ADDR │ CMD  │ LEN      │ DATA     │ SUM  │
+│ 0x57 │ 0xAB │ 0xXX │ data_len │ payload  │ csum │
+└──────┴──────┴──────┴──────────┴──────────┴──────┘
+
+命令码:
+0x02 - 发送键盘数据
+0x04 - 发送绝对鼠标数据
+0x05 - 发送相对鼠标数据
+0x0E - 获取芯片信息
+```
+
+---
+
+## 4. 事件类型
+
+### 4.1 键盘事件 (types.rs)
+
+```rust
+pub struct KeyboardEvent {
+    /// 按下的键列表
+    pub keys: Vec<KeyCode>,
+
+    /// 修饰键状态
+    pub modifiers: KeyboardModifiers,
+}
+
+#[derive(Default)]
+pub struct KeyboardModifiers {
+    pub left_ctrl: bool,
+    pub left_shift: bool,
+    pub left_alt: bool,
+    pub left_gui: bool,
+    pub right_ctrl: bool,
+    pub right_shift: bool,
+    pub right_alt: bool,
+    pub right_gui: bool,
+}
+
+impl KeyboardModifiers {
+    /// 转换为 USB HID 修饰符字节
+    pub fn to_byte(&self) -> u8 {
+        let mut byte = 0u8;
+        if self.left_ctrl { byte |= 0x01; }
+        if self.left_shift { byte |= 0x02; }
+        if self.left_alt { byte |= 0x04; }
+        if self.left_gui { byte |= 0x08; }
+        if self.right_ctrl { byte |= 0x10; }
+        if self.right_shift { byte |= 0x20; }
+        if self.right_alt { byte |= 0x40; }
+        if self.right_gui { byte |= 0x80; }
+        byte
+    }
+}
+```
+
+### 4.2 鼠标事件 (types.rs)
+
+```rust
+pub struct MouseEvent {
+    /// 按钮
+    pub button: Option<MouseButton>,
+
+    /// 事件类型
+    pub event_type: MouseEventType,
+
+    /// 相对移动 X
+    pub dx: i16,
+
+    /// 相对移动 Y
+    pub dy: i16,
+
+    /// 绝对位置 X (0-32767)
+    pub x: u32,
+
+    /// 绝对位置 Y (0-32767)
+    pub y: u32,
+
+    /// 滚轮移动
+    pub wheel: i8,
+}
+
+pub enum MouseButton {
+    Left,
+    Right,
+    Middle,
+    Button4,
+    Button5,
+}
+
+pub enum MouseEventType {
+    Press,
+    Release,
+    Move,
+    Wheel,
+}
+
+pub enum MouseMode {
+    /// 相对模式 (用于普通操作)
+    Relative,
+
+    /// 绝对模式 (用于 BIOS/精确定位)
+    Absolute,
+}
+```
+
+---
+
+## 5. 按键映射
+
+### 5.1 KeyCode 枚举 (keymap.rs)
+
+```rust
+pub enum KeyCode {
+    // 字母键
+    KeyA, KeyB, KeyC, /* ... */ KeyZ,
+
+    // 数字键
+    Digit1, Digit2, /* ... */ Digit0,
+
+    // 功能键
+    F1, F2, /* ... */ F12,
+
+    // 控制键
+    Escape, Tab, CapsLock, Space, Enter, Backspace,
+    Insert, Delete, Home, End, PageUp, PageDown,
+
+    // 方向键
+    ArrowUp, ArrowDown, ArrowLeft, ArrowRight,
+
+    // 修饰键
+    ShiftLeft, ShiftRight,
+    ControlLeft, ControlRight,
+    AltLeft, AltRight,
+    MetaLeft, MetaRight,
+
+    // 小键盘
+    Numpad0, Numpad1, /* ... */ Numpad9,
+    NumpadAdd, NumpadSubtract, NumpadMultiply, NumpadDivide,
+    NumpadEnter, NumpadDecimal, NumLock,
+
+    // 其他
+    PrintScreen, ScrollLock, Pause,
+    /* ... */
+}
+
+impl KeyCode {
+    /// 转换为 USB HID scancode
+    pub fn to_scancode(&self) -> u8;
+
+    /// 从 JavaScript keyCode 转换
+    pub fn from_js_code(code: &str) -> Option<Self>;
+
+    /// 是否为修饰键
+    pub fn is_modifier(&self) -> bool;
+}
+```
+
+### 5.2 JavaScript 键码映射
+
+```javascript
+// 前端发送的格式
+{
+    "type": "keyboard",
+    "keys": ["KeyA", "KeyB"],
+    "modifiers": {
+        "ctrl": false,
+        "shift": true,
+        "alt": false,
+        "meta": false
+    }
+}
+```
+
+---
+
+## 6. 输入处理器
+
+### 6.1 WebSocket Handler (websocket.rs)
+
+```rust
+pub struct WsHidHandler {
+    hid: Arc<HidController>,
+}
+
+impl WsHidHandler {
+    pub fn new(hid: Arc<HidController>) -> Self;
+
+    /// 处理 WebSocket 消息
+    pub async fn handle_message(&self, msg: &str) -> Result<()> {
+        let event: HidMessage = serde_json::from_str(msg)?;
+
+        match event {
+            HidMessage::Keyboard(kb) => {
+                self.hid.send_keyboard(&kb).await?;
+            }
+            HidMessage::Mouse(mouse) => {
+                self.hid.send_mouse(&mouse).await?;
+            }
+            HidMessage::SetMouseMode(mode) => {
+                self.hid.set_mouse_mode(mode);
+            }
+        }
+
+        Ok(())
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(tag = "type")]
+pub enum HidMessage {
+    #[serde(rename = "keyboard")]
+    Keyboard(KeyboardEvent),
+
+    #[serde(rename = "mouse")]
+    Mouse(MouseEvent),
+
+    #[serde(rename = "mouse_mode")]
+    SetMouseMode(MouseMode),
+}
+```
+
+### 6.2 DataChannel Handler (datachannel.rs)
+
+用于 WebRTC 模式下的 HID 事件处理。
+
+```rust
+pub struct HidDataChannelHandler {
+    hid: Arc<HidController>,
+}
+
+impl HidDataChannelHandler {
+    pub fn new(hid: Arc<HidController>) -> Self;
+
+    /// 处理 DataChannel 消息
+    pub async fn handle_message(&self, data: &[u8]) -> Result<()>;
+
+    /// 创建 DataChannel 配置
+    pub fn datachannel_config() -> RTCDataChannelInit;
+}
+```
+
+---
+
+## 7. 健康监视
+
+### 7.1 HidHealthMonitor (monitor.rs)
+
+```rust
+pub struct HidHealthMonitor {
+    /// 错误计数
+    error_count: AtomicU32,
+
+    /// 连续错误计数
+    consecutive_errors: AtomicU32,
+
+    /// 最后错误时间
+    last_error: RwLock<Option<Instant>>,
+
+    /// 最后错误消息
+    last_error_msg: RwLock<Option<String>>,
+
+    /// 重试配置
+    config: MonitorConfig,
+}
+
+impl HidHealthMonitor {
+    /// 记录错误
+    pub fn record_error(&self, error: &str);
+
+    /// 记录成功
+    pub fn record_success(&self);
+
+    /// 是否应该重试
+    pub fn should_retry(&self) -> bool;
+
+    /// 是否需要重新初始化
+    pub fn needs_reinit(&self) -> bool;
+
+    /// 获取健康状态
+    pub fn health_status(&self) -> HealthStatus;
+}
+
+pub enum HealthStatus {
+    Healthy,
+    Degraded { error_rate: f32 },
+    Unhealthy { consecutive_errors: u32 },
+}
+```
+
+---
+
+## 8. 配置
+
+### 8.1 HID 配置结构
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct HidConfig {
+    /// 后端类型
+    pub backend: HidBackendType,
+
+    /// CH9329 设备路径 (如果使用 CH9329)
+    pub ch9329_device: Option<String>,
+
+    /// CH9329 波特率
+    pub ch9329_baud_rate: Option<u32>,
+
+    /// 默认鼠标模式
+    pub default_mouse_mode: MouseMode,
+
+    /// 鼠标灵敏度 (1-10)
+    pub mouse_sensitivity: u8,
+
+    /// 启用滚轮
+    pub enable_wheel: bool,
+}
+
+impl Default for HidConfig {
+    fn default() -> Self {
+        Self {
+            backend: HidBackendType::Otg,
+            ch9329_device: None,
+            ch9329_baud_rate: Some(9600),
+            default_mouse_mode: MouseMode::Absolute,
+            mouse_sensitivity: 5,
+            enable_wheel: true,
+        }
+    }
+}
+```
+
+---
+
+## 9. API 端点
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/hid/status` | GET | 获取 HID 状态 |
+| `/api/hid/reset` | POST | 重置 HID 状态 |
+| `/api/hid/keyboard` | POST | 发送键盘事件 |
+| `/api/hid/mouse` | POST | 发送鼠标事件 |
+| `/api/hid/mouse/mode` | GET | 获取鼠标模式 |
+| `/api/hid/mouse/mode` | POST | 设置鼠标模式 |
+
+### 响应格式
+
+```json
+// GET /api/hid/status
+{
+    "backend": "otg",
+    "initialized": true,
+    "keyboard_connected": true,
+    "mouse_connected": true,
+    "mouse_mode": "absolute",
+    "error": null
+}
+```
+
+---
+
+## 10. 事件
+
+```rust
+pub enum SystemEvent {
+    HidStateChanged {
+        backend: String,
+        initialized: bool,
+        keyboard_connected: bool,
+        mouse_connected: bool,
+        mouse_mode: String,
+        error: Option<String>,
+    },
+}
+```
+
+---
+
+## 11. 错误处理
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum HidError {
+    #[error("Backend not initialized")]
+    NotInitialized,
+
+    #[error("Device not found: {0}")]
+    DeviceNotFound(String),
+
+    #[error("Device busy: {0}")]
+    DeviceBusy(String),
+
+    #[error("Write error: {0}")]
+    WriteError(String),
+
+    #[error("Serial port error: {0}")]
+    SerialError(String),
+
+    #[error("Invalid key code: {0}")]
+    InvalidKeyCode(String),
+
+    #[error("OTG service error: {0}")]
+    OtgError(String),
+}
+```
+
+---
+
+## 12. 使用示例
+
+### 12.1 初始化 HID 控制器
+
+```rust
+let otg_service = Arc::new(OtgService::new()?);
+let events = Arc::new(EventBus::new());
+
+let hid = HidController::init(
+    otg_service,
+    &HidConfig::default(),
+    events,
+).await?;
+```
+
+### 12.2 发送键盘事件
+
+```rust
+// 按下 Ctrl+C
+hid.send_keyboard(&KeyboardEvent {
+    keys: vec![KeyCode::KeyC],
+    modifiers: KeyboardModifiers {
+        left_ctrl: true,
+        ..Default::default()
+    },
+}).await?;
+
+// 释放所有键
+hid.send_keyboard(&KeyboardEvent {
+    keys: vec![],
+    modifiers: KeyboardModifiers::default(),
+}).await?;
+```
+
+### 12.3 发送鼠标事件
+
+```rust
+// 移动鼠标到绝对位置
+hid.send_mouse(&MouseEvent {
+    button: None,
+    event_type: MouseEventType::Move,
+    dx: 0,
+    dy: 0,
+    x: 16384,  // 屏幕中心
+    y: 16384,
+    wheel: 0,
+}).await?;
+
+// 点击左键
+hid.send_mouse(&MouseEvent {
+    button: Some(MouseButton::Left),
+    event_type: MouseEventType::Press,
+    ..Default::default()
+}).await?;
+
+hid.send_mouse(&MouseEvent {
+    button: Some(MouseButton::Left),
+    event_type: MouseEventType::Release,
+    ..Default::default()
+}).await?;
+```
+
+---
+
+## 13. 常见问题
+
+### Q: OTG 模式下键盘/鼠标不工作?
+
+1. 检查 `/dev/hidg*` 设备是否存在
+2. 检查 USB gadget 是否正确配置
+3. 检查目标 PC 是否识别 USB 设备
+4. 查看 `dmesg` 日志
+
+### Q: CH9329 无法初始化?
+
+1. 检查串口设备路径
+2. 检查波特率设置
+3. 使用 `minicom` 测试串口连接
+
+### Q: 鼠标定位不准确?
+
+1. 使用绝对鼠标模式
+2. 校准屏幕分辨率
+3. 检查缩放设置
+
+### Q: 按键有延迟?
+
+1. 检查网络延迟
+2. 使用 WebRTC 模式
+3. 减少中间代理

docs/modules/msd.md

@@ -0,0 +1,617 @@
+# MSD 模块文档
+
+## 1. 模块概述
+
+MSD (Mass Storage Device) 模块提供虚拟存储设备功能，允许将 ISO/IMG 镜像作为 USB 存储设备挂载到目标计算机。
+
+### 1.1 主要功能
+
+- ISO/IMG 镜像挂载
+- 镜像下载管理
+- Ventoy 多 ISO 启动盘
+- 热插拔支持
+- 下载进度追踪
+
+### 1.2 文件结构
+
+```
+src/msd/
+├── mod.rs              # 模块导出
+├── controller.rs       # MsdController (20KB)
+├── image.rs            # 镜像管理 (21KB)
+├── ventoy_drive.rs     # Ventoy 驱动 (24KB)
+├── monitor.rs          # 健康监视 (9KB)
+└── types.rs            # 类型定义 (6KB)
+```
+
+---
+
+## 2. 架构设计
+
+### 2.1 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          MSD Architecture                                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                    Web API
+                       │
+                       ▼
+              ┌─────────────────┐
+              │  MsdController  │
+              │ (controller.rs) │
+              └────────┬────────┘
+                       │
+         ┌─────────────┼─────────────┐
+         │             │             │
+         ▼             ▼             ▼
+┌─────────────┐ ┌───────────┐ ┌───────────┐
+│   Image     │ │  Ventoy   │ │    OTG    │
+│  Manager    │ │   Drive   │ │  Service  │
+│ (image.rs)  │ │(ventoy.rs)│ │           │
+└──────┬──────┘ └─────┬─────┘ └─────┬─────┘
+       │              │             │
+       ▼              ▼             ▼
+┌─────────────┐ ┌───────────┐ ┌───────────┐
+│  /data/     │ │  exFAT    │ │  MSD      │
+│  images/    │ │  Drive    │ │ Function  │
+└─────────────┘ └───────────┘ └───────────┘
+                                    │
+                                    ▼
+                            ┌───────────────┐
+                            │  Target PC    │
+                            │  (USB Drive)  │
+                            └───────────────┘
+```
+
+### 2.2 MSD 模式
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            MSD Modes                                         │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  Image Mode                                                                  │
+│  ┌───────────┐                                                              │
+│  │ ISO/IMG   │ ──► MSD LUN ──► Target PC sees single drive                 │
+│  │ File      │                                                              │
+│  └───────────┘                                                              │
+│  特点:                                                                       │
+│  - 单个镜像文件                                                              │
+│  - 直接挂载                                                                  │
+│  - 适合系统安装                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  Ventoy Mode                                                                 │
+│  ┌───────────┐                                                              │
+│  │  ISO 1    │                                                              │
+│  ├───────────┤      ┌───────────┐                                          │
+│  │  ISO 2    │ ──►  │  Ventoy   │ ──► Target PC sees bootable drive       │
+│  ├───────────┤      │  Drive    │     with ISO selection menu              │
+│  │  ISO 3    │      └───────────┘                                          │
+│  └───────────┘                                                              │
+│  特点:                                                                       │
+│  - 多个 ISO 文件                                                             │
+│  - exFAT 文件系统                                                            │
+│  - 启动菜单选择                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 核心组件
+
+### 3.1 MsdController (controller.rs)
+
+MSD 控制器主类。
+
+```rust
+pub struct MsdController {
+    /// 当前状态
+    state: Arc<RwLock<MsdState>>,
+
+    /// 镜像管理器
+    image_manager: Arc<ImageManager>,
+
+    /// Ventoy 驱动器
+    ventoy_drive: Arc<RwLock<Option<VentoyDrive>>>,
+
+    /// OTG 服务
+    otg_service: Arc<OtgService>,
+
+    /// MSD 函数句柄
+    msd_function: Arc<RwLock<Option<MsdFunction>>>,
+
+    /// 事件总线
+    events: Arc<EventBus>,
+
+    /// 数据目录
+    data_dir: PathBuf,
+}
+
+impl MsdController {
+    /// 创建控制器
+    pub async fn new(
+        otg_service: Arc<OtgService>,
+        data_dir: PathBuf,
+        events: Arc<EventBus>,
+    ) -> Result<Arc<Self>>;
+
+    /// 获取状态
+    pub fn state(&self) -> MsdState;
+
+    /// 连接 MSD
+    pub async fn connect(&self) -> Result<()>;
+
+    /// 断开 MSD
+    pub async fn disconnect(&self) -> Result<()>;
+
+    /// 切换到镜像模式
+    pub async fn set_image(&self, image_id: &str) -> Result<()>;
+
+    /// 切换到 Ventoy 模式
+    pub async fn set_ventoy(&self) -> Result<()>;
+
+    /// 清除当前挂载
+    pub async fn clear(&self) -> Result<()>;
+
+    /// 列出镜像
+    pub fn list_images(&self) -> Vec<ImageInfo>;
+
+    /// 上传镜像
+    pub async fn upload_image(&self, name: &str, data: Bytes) -> Result<ImageInfo>;
+
+    /// 从 URL 下载镜像
+    pub async fn download_image(&self, url: &str) -> Result<String>;
+
+    /// 删除镜像
+    pub async fn delete_image(&self, image_id: &str) -> Result<()>;
+
+    /// 获取下载进度
+    pub fn get_download_progress(&self, download_id: &str) -> Option<DownloadProgress>;
+}
+
+pub struct MsdState {
+    /// 是否可用
+    pub available: bool,
+
+    /// 当前模式
+    pub mode: MsdMode,
+
+    /// 是否已连接
+    pub connected: bool,
+
+    /// 当前镜像信息
+    pub current_image: Option<ImageInfo>,
+
+    /// 驱动器信息
+    pub drive_info: Option<DriveInfo>,
+
+    /// 错误信息
+    pub error: Option<String>,
+}
+
+pub enum MsdMode {
+    /// 未激活
+    None,
+
+    /// 单镜像模式
+    Image,
+
+    /// Ventoy 模式
+    Drive,
+}
+```
+
+### 3.2 ImageManager (image.rs)
+
+镜像文件管理器。
+
+```rust
+pub struct ImageManager {
+    /// 镜像目录
+    images_dir: PathBuf,
+
+    /// 镜像列表缓存
+    images: RwLock<HashMap<String, ImageInfo>>,
+
+    /// 下载任务
+    downloads: RwLock<HashMap<String, DownloadTask>>,
+
+    /// HTTP 客户端
+    http_client: reqwest::Client,
+}
+
+impl ImageManager {
+    /// 创建管理器
+    pub fn new(images_dir: PathBuf) -> Result<Self>;
+
+    /// 扫描镜像目录
+    pub fn scan_images(&self) -> Result<Vec<ImageInfo>>;
+
+    /// 获取镜像信息
+    pub fn get_image(&self, id: &str) -> Option<ImageInfo>;
+
+    /// 添加镜像
+    pub async fn add_image(&self, name: &str, data: Bytes) -> Result<ImageInfo>;
+
+    /// 删除镜像
+    pub fn delete_image(&self, id: &str) -> Result<()>;
+
+    /// 开始下载
+    pub async fn start_download(&self, url: &str) -> Result<String>;
+
+    /// 取消下载
+    pub fn cancel_download(&self, download_id: &str) -> Result<()>;
+
+    /// 获取下载进度
+    pub fn get_download_progress(&self, download_id: &str) -> Option<DownloadProgress>;
+
+    /// 验证镜像文件
+    fn validate_image(path: &Path) -> Result<ImageFormat>;
+}
+
+pub struct ImageInfo {
+    /// 唯一 ID
+    pub id: String,
+
+    /// 文件名
+    pub name: String,
+
+    /// 文件大小
+    pub size: u64,
+
+    /// 格式
+    pub format: ImageFormat,
+
+    /// 创建时间
+    pub created_at: DateTime<Utc>,
+
+    /// 下载状态
+    pub download_status: Option<DownloadStatus>,
+}
+
+pub enum ImageFormat {
+    /// ISO 光盘镜像
+    Iso,
+
+    /// 原始磁盘镜像
+    Img,
+
+    /// 未知格式
+    Unknown,
+}
+
+pub struct DownloadProgress {
+    /// 已下载字节
+    pub downloaded: u64,
+
+    /// 总字节数
+    pub total: u64,
+
+    /// 下载速度 (bytes/sec)
+    pub speed: u64,
+
+    /// 预计剩余时间
+    pub eta_secs: u64,
+
+    /// 状态
+    pub status: DownloadStatus,
+}
+
+pub enum DownloadStatus {
+    Pending,
+    Downloading,
+    Completed,
+    Failed(String),
+    Cancelled,
+}
+```
+
+### 3.3 VentoyDrive (ventoy_drive.rs)
+
+Ventoy 可启动驱动器管理。
+
+```rust
+pub struct VentoyDrive {
+    /// 驱动器路径
+    drive_path: PathBuf,
+
+    /// 镜像路径
+    images: Vec<PathBuf>,
+
+    /// 容量
+    capacity: u64,
+
+    /// 已用空间
+    used: u64,
+}
+
+impl VentoyDrive {
+    /// 创建 Ventoy 驱动器
+    pub fn create(drive_path: PathBuf, capacity: u64) -> Result<Self>;
+
+    /// 添加 ISO
+    pub fn add_iso(&mut self, iso_path: &Path) -> Result<()>;
+
+    /// 移除 ISO
+    pub fn remove_iso(&mut self, name: &str) -> Result<()>;
+
+    /// 列出 ISO
+    pub fn list_isos(&self) -> Vec<String>;
+
+    /// 获取驱动器信息
+    pub fn info(&self) -> DriveInfo;
+
+    /// 获取驱动器路径
+    pub fn path(&self) -> &Path;
+}
+
+pub struct DriveInfo {
+    /// 容量
+    pub capacity: u64,
+
+    /// 已用空间
+    pub used: u64,
+
+    /// 可用空间
+    pub available: u64,
+
+    /// ISO 列表
+    pub isos: Vec<String>,
+}
+```
+
+---
+
+## 4. 类型定义
+
+### 4.1 MSD 配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct MsdConfig {
+    /// 是否启用 MSD
+    pub enabled: bool,
+
+    /// 镜像目录
+    pub images_dir: Option<String>,
+
+    /// 默认模式
+    pub default_mode: MsdMode,
+
+    /// Ventoy 容量 (MB)
+    pub ventoy_capacity_mb: u32,
+}
+
+impl Default for MsdConfig {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            images_dir: None,
+            default_mode: MsdMode::None,
+            ventoy_capacity_mb: 4096,  // 4GB
+        }
+    }
+}
+```
+
+---
+
+## 5. API 端点
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/msd/status` | GET | 获取 MSD 状态 |
+| `/api/msd/connect` | POST | 连接 MSD |
+| `/api/msd/disconnect` | POST | 断开 MSD |
+| `/api/msd/images` | GET | 列出镜像 |
+| `/api/msd/images` | POST | 上传镜像 |
+| `/api/msd/images/:id` | DELETE | 删除镜像 |
+| `/api/msd/images/download` | POST | 从 URL 下载 |
+| `/api/msd/images/download/:id` | GET | 获取下载进度 |
+| `/api/msd/images/download/:id` | DELETE | 取消下载 |
+| `/api/msd/set-image` | POST | 设置当前镜像 |
+| `/api/msd/set-ventoy` | POST | 设置 Ventoy 模式 |
+| `/api/msd/clear` | POST | 清除挂载 |
+
+### 响应格式
+
+```json
+// GET /api/msd/status
+{
+    "available": true,
+    "mode": "image",
+    "connected": true,
+    "current_image": {
+        "id": "abc123",
+        "name": "ubuntu-22.04.iso",
+        "size": 4700000000,
+        "format": "iso"
+    },
+    "drive_info": null,
+    "error": null
+}
+
+// GET /api/msd/images
+{
+    "images": [
+        {
+            "id": "abc123",
+            "name": "ubuntu-22.04.iso",
+            "size": 4700000000,
+            "format": "iso",
+            "created_at": "2024-01-15T10:30:00Z"
+        }
+    ]
+}
+
+// POST /api/msd/images/download
+// Request: { "url": "https://example.com/image.iso" }
+// Response: { "download_id": "xyz789" }
+
+// GET /api/msd/images/download/xyz789
+{
+    "downloaded": 1234567890,
+    "total": 4700000000,
+    "speed": 12345678,
+    "eta_secs": 280,
+    "status": "downloading"
+}
+```
+
+---
+
+## 6. 事件
+
+```rust
+pub enum SystemEvent {
+    MsdStateChanged {
+        mode: MsdMode,
+        connected: bool,
+        image: Option<String>,
+        error: Option<String>,
+    },
+
+    MsdDownloadProgress {
+        download_id: String,
+        progress: DownloadProgress,
+    },
+
+    MsdDownloadComplete {
+        download_id: String,
+        image_id: String,
+        success: bool,
+        error: Option<String>,
+    },
+}
+```
+
+---
+
+## 7. 错误处理
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum MsdError {
+    #[error("MSD not available")]
+    NotAvailable,
+
+    #[error("Already connected")]
+    AlreadyConnected,
+
+    #[error("Not connected")]
+    NotConnected,
+
+    #[error("Image not found: {0}")]
+    ImageNotFound(String),
+
+    #[error("Invalid image format: {0}")]
+    InvalidFormat(String),
+
+    #[error("Download failed: {0}")]
+    DownloadFailed(String),
+
+    #[error("Storage full")]
+    StorageFull,
+
+    #[error("OTG error: {0}")]
+    OtgError(String),
+
+    #[error("IO error: {0}")]
+    IoError(#[from] std::io::Error),
+}
+```
+
+---
+
+## 8. 使用示例
+
+### 8.1 挂载 ISO 镜像
+
+```rust
+let msd = MsdController::new(otg_service, data_dir, events).await?;
+
+// 列出镜像
+let images = msd.list_images();
+println!("Available images: {:?}", images);
+
+// 设置镜像
+msd.set_image("abc123").await?;
+
+// 连接到目标 PC
+msd.connect().await?;
+
+// 目标 PC 现在可以看到 USB 驱动器...
+
+// 断开连接
+msd.disconnect().await?;
+```
+
+### 8.2 从 URL 下载
+
+```rust
+// 开始下载
+let download_id = msd.download_image("https://example.com/ubuntu.iso").await?;
+
+// 监控进度
+loop {
+    if let Some(progress) = msd.get_download_progress(&download_id) {
+        println!("Progress: {}%", progress.downloaded * 100 / progress.total);
+
+        if matches!(progress.status, DownloadStatus::Completed) {
+            break;
+        }
+    }
+    tokio::time::sleep(Duration::from_secs(1)).await;
+}
+```
+
+### 8.3 使用 Ventoy 模式
+
+```rust
+// 切换到 Ventoy 模式
+msd.set_ventoy().await?;
+
+// 获取驱动器信息
+let state = msd.state();
+if let Some(drive_info) = state.drive_info {
+    println!("Capacity: {} MB", drive_info.capacity / 1024 / 1024);
+    println!("ISOs: {:?}", drive_info.isos);
+}
+
+// 连接
+msd.connect().await?;
+```
+
+---
+
+## 9. 常见问题
+
+### Q: 镜像无法挂载?
+
+1. 检查镜像文件完整性
+2. 确认文件格式正确
+3. 检查存储空间
+
+### Q: 目标 PC 不识别?
+
+1. 检查 USB 连接
+2. 尝试重新连接
+3. 查看目标 PC 的设备管理器
+
+### Q: 下载速度慢?
+
+1. 检查网络连接
+2. 使用更近的镜像源
+3. 检查磁盘 I/O
+
+### Q: Ventoy 启动失败?
+
+1. 检查目标 PC BIOS 设置
+2. 尝试不同的启动模式
+3. 确认 ISO 文件支持 Ventoy

docs/modules/otg.md

@@ -0,0 +1,667 @@
+# OTG 模块文档
+
+## 1. 模块概述
+
+OTG (On-The-Go) 模块负责管理 Linux USB Gadget，为 HID 和 MSD 功能提供统一的 USB 设备管理。
+
+### 1.1 主要功能
+
+- USB Gadget 生命周期管理
+- HID 函数配置 (键盘、鼠标)
+- MSD 函数配置 (虚拟存储)
+- ConfigFS 操作
+- UDC 绑定/解绑
+
+### 1.2 文件结构
+
+```
+src/otg/
+├── mod.rs              # 模块导出
+├── service.rs          # OtgService (17KB)
+├── manager.rs          # OtgGadgetManager (12KB)
+├── hid.rs              # HID Function (7KB)
+├── msd.rs              # MSD Function (14KB)
+├── configfs.rs         # ConfigFS 操作 (4KB)
+├── endpoint.rs         # 端点分配 (2KB)
+└── report_desc.rs      # HID 报告描述符 (6KB)
+```
+
+---
+
+## 2. 架构设计
+
+### 2.1 设计目标
+
+解决 HID 和 MSD 共享同一个 USB Gadget 的所有权问题：
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         OTG Ownership Model                                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+              ┌─────────────────┐
+              │   OtgService    │ ◄── 唯一所有者
+              │  (service.rs)   │
+              └────────┬────────┘
+                       │
+         ┌─────────────┼─────────────┐
+         │             │             │
+         ▼             ▼             ▼
+   enable_hid()   enable_msd()   状态查询
+         │             │
+         └──────┬──────┘
+                │
+                ▼
+         ┌─────────────────┐
+         │OtgGadgetManager │
+         │  (manager.rs)   │
+         └────────┬────────┘
+                  │
+    ┌─────────────┼─────────────┐
+    │             │             │
+    ▼             ▼             ▼
+┌───────┐   ┌───────┐   ┌───────┐
+│ HID   │   │ MSD   │   │ UDC   │
+│ Func  │   │ Func  │   │ Bind  │
+└───────┘   └───────┘   └───────┘
+```
+
+### 2.2 ConfigFS 结构
+
+```
+/sys/kernel/config/usb_gadget/one-kvm/
+├── idVendor                    # 0x05ac (Apple)
+├── idProduct                   # 0x0001
+├── bcdDevice                   # 0x0100
+├── bcdUSB                      # 0x0200
+├── bMaxPacketSize0             # 64
+│
+├── strings/
+│   └── 0x409/                  # English
+│       ├── manufacturer        # "One-KVM"
+│       ├── product             # "KVM Device"
+│       └── serialnumber        # UUID
+│
+├── configs/
+│   └── c.1/
+│       ├── MaxPower            # 500
+│       ├── strings/
+│       │   └── 0x409/
+│       │       └── configuration  # "Config 1"
+│       └── (function symlinks)
+│
+├── functions/
+│   ├── hid.usb0/               # 键盘
+│   │   ├── protocol            # 1 (keyboard)
+│   │   ├── subclass            # 1 (boot)
+│   │   ├── report_length       # 8
+│   │   └── report_desc         # (binary)
+│   │
+│   ├── hid.usb1/               # 相对鼠标
+│   │   ├── protocol            # 2 (mouse)
+│   │   ├── subclass            # 1 (boot)
+│   │   ├── report_length       # 4
+│   │   └── report_desc         # (binary)
+│   │
+│   ├── hid.usb2/               # 绝对鼠标
+│   │   ├── protocol            # 2 (mouse)
+│   │   ├── subclass            # 0 (none)
+│   │   ├── report_length       # 6
+│   │   └── report_desc         # (binary)
+│   │
+│   └── mass_storage.usb0/      # 虚拟存储
+│       ├── stall               # 1
+│       └── lun.0/
+│           ├── cdrom           # 1 (ISO mode)
+│           ├── ro              # 1 (read-only)
+│           ├── removable       # 1
+│           ├── nofua           # 1
+│           └── file            # /path/to/image.iso
+│
+└── UDC                         # UDC 设备名
+```
+
+---
+
+## 3. 核心组件
+
+### 3.1 OtgService (service.rs)
+
+OTG 服务主类，提供统一的 USB Gadget 管理接口。
+
+```rust
+pub struct OtgService {
+    /// Gadget 管理器
+    manager: Arc<Mutex<OtgGadgetManager>>,
+
+    /// 当前状态
+    state: Arc<RwLock<OtgServiceState>>,
+
+    /// HID 函数句柄
+    hid_function: Arc<RwLock<Option<HidFunction>>>,
+
+    /// MSD 函数句柄
+    msd_function: Arc<RwLock<Option<MsdFunction>>>,
+
+    /// 请求计数器 (lock-free)
+    pending_requests: AtomicU8,
+}
+
+impl OtgService {
+    /// 创建服务
+    pub fn new() -> Result<Self>;
+
+    /// 启用 HID 功能
+    pub async fn enable_hid(&self) -> Result<HidDevicePaths>;
+
+    /// 禁用 HID 功能
+    pub async fn disable_hid(&self) -> Result<()>;
+
+    /// 启用 MSD 功能
+    pub async fn enable_msd(&self) -> Result<MsdFunction>;
+
+    /// 禁用 MSD 功能
+    pub async fn disable_msd(&self) -> Result<()>;
+
+    /// 获取状态
+    pub fn state(&self) -> OtgServiceState;
+
+    /// 检查 HID 是否启用
+    pub fn is_hid_enabled(&self) -> bool;
+
+    /// 检查 MSD 是否启用
+    pub fn is_msd_enabled(&self) -> bool;
+}
+
+pub struct OtgServiceState {
+    /// Gadget 是否激活
+    pub gadget_active: bool,
+
+    /// HID 是否启用
+    pub hid_enabled: bool,
+
+    /// MSD 是否启用
+    pub msd_enabled: bool,
+
+    /// HID 设备路径
+    pub hid_paths: Option<HidDevicePaths>,
+
+    /// 错误信息
+    pub error: Option<String>,
+}
+
+pub struct HidDevicePaths {
+    pub keyboard: PathBuf,        // /dev/hidg0
+    pub mouse_relative: PathBuf,  // /dev/hidg1
+    pub mouse_absolute: PathBuf,  // /dev/hidg2
+}
+```
+
+### 3.2 OtgGadgetManager (manager.rs)
+
+Gadget 生命周期管理器。
+
+```rust
+pub struct OtgGadgetManager {
+    /// Gadget 路径
+    gadget_path: PathBuf,
+
+    /// UDC 设备名
+    udc_name: Option<String>,
+
+    /// 是否已创建
+    created: bool,
+
+    /// 是否已绑定
+    bound: bool,
+
+    /// 端点分配器
+    endpoint_allocator: EndpointAllocator,
+}
+
+impl OtgGadgetManager {
+    /// 创建管理器
+    pub fn new() -> Result<Self>;
+
+    /// 创建 Gadget
+    pub fn create_gadget(&mut self, config: &GadgetConfig) -> Result<()>;
+
+    /// 销毁 Gadget
+    pub fn destroy_gadget(&mut self) -> Result<()>;
+
+    /// 绑定 UDC
+    pub fn bind_udc(&mut self) -> Result<()>;
+
+    /// 解绑 UDC
+    pub fn unbind_udc(&mut self) -> Result<()>;
+
+    /// 添加函数
+    pub fn add_function(&mut self, func: &dyn GadgetFunction) -> Result<()>;
+
+    /// 移除函数
+    pub fn remove_function(&mut self, func: &dyn GadgetFunction) -> Result<()>;
+
+    /// 链接函数到配置
+    pub fn link_function(&self, func: &dyn GadgetFunction) -> Result<()>;
+
+    /// 取消链接函数
+    pub fn unlink_function(&self, func: &dyn GadgetFunction) -> Result<()>;
+
+    /// 检测可用 UDC
+    fn detect_udc() -> Result<String>;
+}
+
+pub struct GadgetConfig {
+    pub name: String,            // "one-kvm"
+    pub vendor_id: u16,          // 0x05ac
+    pub product_id: u16,         // 0x0001
+    pub manufacturer: String,    // "One-KVM"
+    pub product: String,         // "KVM Device"
+    pub serial: String,          // UUID
+}
+```
+
+### 3.3 HID Function (hid.rs)
+
+```rust
+pub struct HidFunction {
+    /// 键盘函数
+    keyboard: HidFunctionConfig,
+
+    /// 相对鼠标函数
+    mouse_relative: HidFunctionConfig,
+
+    /// 绝对鼠标函数
+    mouse_absolute: HidFunctionConfig,
+}
+
+pub struct HidFunctionConfig {
+    /// 函数名
+    pub name: String,            // "hid.usb0"
+
+    /// 协议
+    pub protocol: u8,            // 1=keyboard, 2=mouse
+
+    /// 子类
+    pub subclass: u8,            // 1=boot, 0=none
+
+    /// 报告长度
+    pub report_length: u8,
+
+    /// 报告描述符
+    pub report_desc: Vec<u8>,
+}
+
+impl HidFunction {
+    /// 创建 HID 函数
+    pub fn new() -> Self;
+
+    /// 获取键盘报告描述符
+    pub fn keyboard_report_desc() -> Vec<u8>;
+
+    /// 获取相对鼠标报告描述符
+    pub fn mouse_relative_report_desc() -> Vec<u8>;
+
+    /// 获取绝对鼠标报告描述符
+    pub fn mouse_absolute_report_desc() -> Vec<u8>;
+}
+
+impl GadgetFunction for HidFunction {
+    fn name(&self) -> &str;
+    fn function_type(&self) -> &str;  // "hid"
+    fn configure(&self, path: &Path) -> Result<()>;
+}
+```
+
+### 3.4 MSD Function (msd.rs)
+
+```rust
+pub struct MsdFunction {
+    /// 函数名
+    name: String,
+
+    /// LUN 配置
+    luns: Vec<MsdLun>,
+}
+
+pub struct MsdLun {
+    /// LUN 编号
+    pub lun_id: u8,
+
+    /// 镜像文件路径
+    pub file: Option<PathBuf>,
+
+    /// 是否 CD-ROM 模式
+    pub cdrom: bool,
+
+    /// 是否只读
+    pub readonly: bool,
+
+    /// 是否可移除
+    pub removable: bool,
+}
+
+impl MsdFunction {
+    /// 创建 MSD 函数
+    pub fn new() -> Self;
+
+    /// 设置镜像文件
+    pub fn set_image(&mut self, path: &Path, cdrom: bool) -> Result<()>;
+
+    /// 清除镜像
+    pub fn clear_image(&mut self) -> Result<()>;
+
+    /// 弹出介质
+    pub fn eject(&mut self) -> Result<()>;
+}
+
+impl GadgetFunction for MsdFunction {
+    fn name(&self) -> &str;
+    fn function_type(&self) -> &str;  // "mass_storage"
+    fn configure(&self, path: &Path) -> Result<()>;
+}
+```
+
+### 3.5 ConfigFS 操作 (configfs.rs)
+
+```rust
+pub struct ConfigFs;
+
+impl ConfigFs {
+    /// ConfigFS 根路径
+    const ROOT: &'static str = "/sys/kernel/config/usb_gadget";
+
+    /// 创建目录
+    pub fn mkdir(path: &Path) -> Result<()>;
+
+    /// 删除目录
+    pub fn rmdir(path: &Path) -> Result<()>;
+
+    /// 写入文件
+    pub fn write_file(path: &Path, content: &str) -> Result<()>;
+
+    /// 写入二进制文件
+    pub fn write_binary(path: &Path, data: &[u8]) -> Result<()>;
+
+    /// 读取文件
+    pub fn read_file(path: &Path) -> Result<String>;
+
+    /// 创建符号链接
+    pub fn symlink(target: &Path, link: &Path) -> Result<()>;
+
+    /// 删除符号链接
+    pub fn unlink(path: &Path) -> Result<()>;
+
+    /// 列出目录
+    pub fn list_dir(path: &Path) -> Result<Vec<String>>;
+}
+```
+
+### 3.6 端点分配 (endpoint.rs)
+
+```rust
+pub struct EndpointAllocator {
+    /// 已使用的端点
+    used_endpoints: HashSet<u8>,
+
+    /// 最大端点数
+    max_endpoints: u8,
+}
+
+impl EndpointAllocator {
+    /// 创建分配器
+    pub fn new(max_endpoints: u8) -> Self;
+
+    /// 分配端点
+    pub fn allocate(&mut self, count: u8) -> Result<Vec<u8>>;
+
+    /// 释放端点
+    pub fn release(&mut self, endpoints: &[u8]);
+
+    /// 检查可用端点数
+    pub fn available(&self) -> u8;
+}
+```
+
+### 3.7 报告描述符 (report_desc.rs)
+
+```rust
+pub struct ReportDescriptor;
+
+impl ReportDescriptor {
+    /// 标准键盘报告描述符
+    pub fn keyboard() -> Vec<u8> {
+        vec![
+            0x05, 0x01,        // Usage Page (Generic Desktop)
+            0x09, 0x06,        // Usage (Keyboard)
+            0xA1, 0x01,        // Collection (Application)
+            0x05, 0x07,        //   Usage Page (Key Codes)
+            0x19, 0xE0,        //   Usage Minimum (224)
+            0x29, 0xE7,        //   Usage Maximum (231)
+            0x15, 0x00,        //   Logical Minimum (0)
+            0x25, 0x01,        //   Logical Maximum (1)
+            0x75, 0x01,        //   Report Size (1)
+            0x95, 0x08,        //   Report Count (8)
+            0x81, 0x02,        //   Input (Data, Variable, Absolute)
+            0x95, 0x01,        //   Report Count (1)
+            0x75, 0x08,        //   Report Size (8)
+            0x81, 0x01,        //   Input (Constant)
+            0x95, 0x06,        //   Report Count (6)
+            0x75, 0x08,        //   Report Size (8)
+            0x15, 0x00,        //   Logical Minimum (0)
+            0x25, 0x65,        //   Logical Maximum (101)
+            0x05, 0x07,        //   Usage Page (Key Codes)
+            0x19, 0x00,        //   Usage Minimum (0)
+            0x29, 0x65,        //   Usage Maximum (101)
+            0x81, 0x00,        //   Input (Data, Array)
+            0xC0,              // End Collection
+        ]
+    }
+
+    /// 相对鼠标报告描述符
+    pub fn mouse_relative() -> Vec<u8>;
+
+    /// 绝对鼠标报告描述符
+    pub fn mouse_absolute() -> Vec<u8>;
+}
+```
+
+---
+
+## 4. 生命周期管理
+
+### 4.1 初始化流程
+
+```
+OtgService::new()
+    │
+    ├── 检测 UDC 设备
+    │   └── 读取 /sys/class/udc/
+    │
+    ├── 创建 OtgGadgetManager
+    │
+    └── 初始化状态
+
+enable_hid()
+    │
+    ├── 检查 Gadget 是否存在
+    │   └── 如不存在，创建 Gadget
+    │
+    ├── 创建 HID 函数
+    │   ├── hid.usb0 (键盘)
+    │   ├── hid.usb1 (相对鼠标)
+    │   └── hid.usb2 (绝对鼠标)
+    │
+    ├── 配置函数
+    │   └── 写入报告描述符
+    │
+    ├── 链接函数到配置
+    │
+    ├── 绑定 UDC (如未绑定)
+    │
+    └── 等待设备节点出现
+        └── /dev/hidg0, hidg1, hidg2
+```
+
+### 4.2 清理流程
+
+```
+disable_hid()
+    │
+    ├── 检查是否有其他函数使用
+    │
+    ├── 如果只有 HID，解绑 UDC
+    │
+    ├── 取消链接 HID 函数
+    │
+    └── 删除 HID 函数目录
+
+disable_msd()
+    │
+    ├── 同上...
+    │
+    └── 如果没有任何函数，销毁 Gadget
+```
+
+---
+
+## 5. 配置
+
+### 5.1 OTG 配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct OtgConfig {
+    /// 是否启用 OTG
+    pub enabled: bool,
+
+    /// 厂商 ID
+    pub vendor_id: u16,
+
+    /// 产品 ID
+    pub product_id: u16,
+
+    /// 厂商名称
+    pub manufacturer: String,
+
+    /// 产品名称
+    pub product: String,
+}
+
+impl Default for OtgConfig {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            vendor_id: 0x05ac,  // Apple
+            product_id: 0x0001,
+            manufacturer: "One-KVM".to_string(),
+            product: "KVM Device".to_string(),
+        }
+    }
+}
+```
+
+---
+
+## 6. 错误处理
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum OtgError {
+    #[error("No UDC device found")]
+    NoUdcDevice,
+
+    #[error("Gadget already exists")]
+    GadgetExists,
+
+    #[error("Gadget not found")]
+    GadgetNotFound,
+
+    #[error("Function already exists: {0}")]
+    FunctionExists(String),
+
+    #[error("UDC busy")]
+    UdcBusy,
+
+    #[error("ConfigFS error: {0}")]
+    ConfigFsError(String),
+
+    #[error("Permission denied: {0}")]
+    PermissionDenied(String),
+
+    #[error("Device node not found: {0}")]
+    DeviceNodeNotFound(String),
+}
+```
+
+---
+
+## 7. 使用示例
+
+### 7.1 启用 HID
+
+```rust
+let otg = OtgService::new()?;
+
+// 启用 HID
+let paths = otg.enable_hid().await?;
+println!("Keyboard: {:?}", paths.keyboard);
+println!("Mouse relative: {:?}", paths.mouse_relative);
+println!("Mouse absolute: {:?}", paths.mouse_absolute);
+
+// 使用设备...
+
+// 禁用 HID
+otg.disable_hid().await?;
+```
+
+### 7.2 启用 MSD
+
+```rust
+let otg = OtgService::new()?;
+
+// 启用 MSD
+let mut msd = otg.enable_msd().await?;
+
+// 挂载 ISO
+msd.set_image(Path::new("/data/ubuntu.iso"), true)?;
+
+// 弹出
+msd.eject()?;
+
+// 禁用 MSD
+otg.disable_msd().await?;
+```
+
+---
+
+## 8. 常见问题
+
+### Q: 找不到 UDC 设备?
+
+1. 检查内核是否支持 USB Gadget
+2. 加载必要的内核模块:
+   ```bash
+   modprobe libcomposite
+   modprobe usb_f_hid
+   modprobe usb_f_mass_storage
+   ```
+3. 检查 `/sys/class/udc/` 目录
+
+### Q: 权限错误?
+
+1. 以 root 运行
+2. 或配置 udev 规则
+
+### Q: 设备节点不出现?
+
+1. 检查 UDC 是否正确绑定
+2. 查看 `dmesg` 日志
+3. 检查 ConfigFS 配置
+
+### Q: 目标 PC 不识别?
+
+1. 检查 USB 线缆
+2. 检查报告描述符
+3. 使用 `lsusb` 确认设备

docs/modules/rustdesk.md

@@ -0,0 +1,776 @@
+# RustDesk 模块文档
+
+## 1. 模块概述
+
+RustDesk 模块实现 RustDesk 协议集成，允许使用标准 RustDesk 客户端访问 One-KVM 设备。
+
+### 1.1 主要功能
+
+- RustDesk 协议实现
+- 渲染服务器 (hbbs) 通信
+- 中继服务器 (hbbr) 通信
+- 视频/音频/HID 转换
+- 端到端加密
+
+### 1.2 文件结构
+
+```
+src/rustdesk/
+├── mod.rs              # RustDeskService (21KB)
+├── connection.rs       # 连接管理 (49KB)
+├── rendezvous.rs       # 渲染服务器 (32KB)
+├── crypto.rs           # NaCl 加密 (16KB)
+├── config.rs           # 配置 (7KB)
+├── hid_adapter.rs      # HID 适配 (14KB)
+├── frame_adapters.rs   # 帧转换 (9KB)
+├── protocol.rs         # 协议包装 (6KB)
+└── bytes_codec.rs      # 帧编码 (8KB)
+```
+
+---
+
+## 2. 架构设计
+
+### 2.1 RustDesk 网络架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      RustDesk Network Architecture                           │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────┐                                      ┌─────────────┐
+│  RustDesk   │                                      │  One-KVM    │
+│   Client    │                                      │   Device    │
+└──────┬──────┘                                      └──────┬──────┘
+       │                                                    │
+       │ 1. 查询设备地址                                     │
+       │─────────────────────►┌─────────────┐◄──────────────│
+       │                      │    hbbs     │               │
+       │                      │ (Rendezvous)│               │
+       │◄─────────────────────└─────────────┘               │
+       │ 2. 返回地址                                         │
+       │                                                    │
+       │ 3a. 直接连接 (如果可达)                              │
+       │────────────────────────────────────────────────────│
+       │                                                    │
+       │ 3b. 中继连接 (如果 NAT)                              │
+       │─────────────────────►┌─────────────┐◄──────────────│
+       │                      │    hbbr     │               │
+       │                      │  (Relay)    │               │
+       │◄─────────────────────└─────────────┘───────────────│
+       │                                                    │
+       │ 4. 建立加密通道                                     │
+       │◄───────────────────────────────────────────────────│
+       │                                                    │
+       │ 5. 传输视频/音频/HID                                │
+       │◄───────────────────────────────────────────────────│
+```
+
+### 2.2 模块内部架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      RustDesk Module Architecture                            │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                    ┌─────────────────┐
+                    │ RustDeskService │
+                    │    (mod.rs)     │
+                    └────────┬────────┘
+                             │
+         ┌───────────────────┼───────────────────┐
+         │                   │                   │
+         ▼                   ▼                   ▼
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+│  Rendezvous     │ │  Connection     │ │   Crypto        │
+│  (rendezvous)   │ │  (connection)   │ │   (crypto)      │
+└────────┬────────┘ └────────┬────────┘ └─────────────────┘
+         │                   │
+         │                   │
+         ▼                   ▼
+┌─────────────────┐ ┌─────────────────────────────────────┐
+│  hbbs Server    │ │              Adapters               │
+│  Connection     │ │  ┌──────────┐ ┌──────────────────┐ │
+└─────────────────┘ │  │ HID      │ │ Frame            │ │
+                    │  │ Adapter  │ │ Adapters         │ │
+                    │  └──────────┘ └──────────────────┘ │
+                    └─────────────────────────────────────┘
+                                      │
+                    ┌─────────────────┼─────────────────┐
+                    │                 │                 │
+                    ▼                 ▼                 ▼
+             ┌───────────┐    ┌───────────┐    ┌───────────┐
+             │    HID    │    │   Video   │    │   Audio   │
+             │ Controller│    │  Pipeline │    │ Pipeline  │
+             └───────────┘    └───────────┘    └───────────┘
+```
+
+---
+
+## 3. 核心组件
+
+### 3.1 RustDeskService (mod.rs)
+
+RustDesk 服务主类。
+
+```rust
+pub struct RustDeskService {
+    /// 服务配置
+    config: Arc<RwLock<RustDeskConfig>>,
+
+    /// 渲染连接
+    rendezvous: Arc<RwLock<Option<RendezvousConnection>>>,
+
+    /// 客户端连接
+    connections: Arc<RwLock<HashMap<String, Arc<ClientConnection>>>>,
+
+    /// 加密密钥
+    keys: Arc<RustDeskKeys>,
+
+    /// 视频管道
+    video_pipeline: Arc<SharedVideoPipeline>,
+
+    /// 音频管道
+    audio_pipeline: Arc<SharedAudioPipeline>,
+
+    /// HID 控制器
+    hid: Arc<HidController>,
+
+    /// 服务状态
+    status: Arc<RwLock<ServiceStatus>>,
+
+    /// 事件总线
+    events: Arc<EventBus>,
+}
+
+impl RustDeskService {
+    /// 创建服务
+    pub async fn new(
+        config: RustDeskConfig,
+        video_pipeline: Arc<SharedVideoPipeline>,
+        audio_pipeline: Arc<SharedAudioPipeline>,
+        hid: Arc<HidController>,
+        events: Arc<EventBus>,
+    ) -> Result<Arc<Self>>;
+
+    /// 启动服务
+    pub async fn start(&self) -> Result<()>;
+
+    /// 停止服务
+    pub async fn stop(&self) -> Result<()>;
+
+    /// 获取设备 ID
+    pub fn device_id(&self) -> String;
+
+    /// 获取状态
+    pub fn status(&self) -> ServiceStatus;
+
+    /// 更新配置
+    pub async fn update_config(&self, config: RustDeskConfig) -> Result<()>;
+
+    /// 获取连接列表
+    pub fn connections(&self) -> Vec<ConnectionInfo>;
+
+    /// 断开连接
+    pub async fn disconnect(&self, connection_id: &str) -> Result<()>;
+}
+
+pub enum ServiceStatus {
+    Stopped,
+    Starting,
+    Running,
+    Error(String),
+}
+
+pub struct ConnectionInfo {
+    pub id: String,
+    pub peer_id: String,
+    pub connected_at: DateTime<Utc>,
+    pub ip: String,
+}
+```
+
+### 3.2 RendezvousConnection (rendezvous.rs)
+
+渲染服务器连接管理。
+
+```rust
+pub struct RendezvousConnection {
+    /// 服务器地址
+    server_addr: SocketAddr,
+
+    /// TCP 连接
+    stream: TcpStream,
+
+    /// 设备 ID
+    device_id: String,
+
+    /// 公钥
+    public_key: [u8; 32],
+
+    /// 注册状态
+    registered: AtomicBool,
+
+    /// 心跳任务
+    heartbeat_task: Option<JoinHandle<()>>,
+}
+
+impl RendezvousConnection {
+    /// 连接到渲染服务器
+    pub async fn connect(
+        server: &str,
+        device_id: &str,
+        keys: &RustDeskKeys,
+    ) -> Result<Self>;
+
+    /// 注册设备
+    pub async fn register(&self) -> Result<()>;
+
+    /// 发送心跳
+    async fn heartbeat(&self) -> Result<()>;
+
+    /// 接收消息
+    pub async fn recv_message(&mut self) -> Result<RendezvousMessage>;
+
+    /// 处理穿孔请求
+    pub async fn handle_punch_request(&self, peer_id: &str) -> Result<SocketAddr>;
+}
+
+pub enum RendezvousMessage {
+    RegisterOk,
+    PunchRequest { peer_id: String, socket_addr: SocketAddr },
+    Heartbeat,
+    Error(String),
+}
+```
+
+### 3.3 ClientConnection (connection.rs)
+
+客户端连接处理。
+
+```rust
+pub struct ClientConnection {
+    /// 连接 ID
+    id: String,
+
+    /// 对端 ID
+    peer_id: String,
+
+    /// 加密通道
+    channel: EncryptedChannel,
+
+    /// 帧适配器
+    frame_adapter: FrameAdapter,
+
+    /// HID 适配器
+    hid_adapter: HidAdapter,
+
+    /// 状态
+    state: Arc<RwLock<ConnectionState>>,
+}
+
+impl ClientConnection {
+    /// 创建连接
+    pub async fn new(
+        stream: TcpStream,
+        keys: &RustDeskKeys,
+        peer_public_key: &[u8],
+    ) -> Result<Self>;
+
+    /// 处理连接
+    pub async fn handle(
+        &self,
+        video_rx: broadcast::Receiver<EncodedFrame>,
+        audio_rx: broadcast::Receiver<AudioFrame>,
+        hid: Arc<HidController>,
+    ) -> Result<()>;
+
+    /// 发送视频帧
+    async fn send_video_frame(&self, frame: &EncodedFrame) -> Result<()>;
+
+    /// 发送音频帧
+    async fn send_audio_frame(&self, frame: &AudioFrame) -> Result<()>;
+
+    /// 处理输入事件
+    async fn handle_input(&self, msg: &InputMessage) -> Result<()>;
+
+    /// 关闭连接
+    pub async fn close(&self) -> Result<()>;
+}
+
+pub enum ConnectionState {
+    Handshaking,
+    Authenticating,
+    Connected,
+    Closing,
+    Closed,
+}
+```
+
+### 3.4 RustDeskKeys (crypto.rs)
+
+加密密钥管理。
+
+```rust
+pub struct RustDeskKeys {
+    /// 设备 ID
+    pub device_id: String,
+
+    /// Curve25519 公钥
+    pub public_key: [u8; 32],
+
+    /// Curve25519 私钥
+    secret_key: [u8; 32],
+
+    /// Ed25519 签名公钥
+    pub sign_public_key: [u8; 32],
+
+    /// Ed25519 签名私钥
+    sign_secret_key: [u8; 64],
+}
+
+impl RustDeskKeys {
+    /// 生成新密钥
+    pub fn generate() -> Self;
+
+    /// 从配置加载
+    pub fn from_config(config: &KeyConfig) -> Result<Self>;
+
+    /// 保存到配置
+    pub fn to_config(&self) -> KeyConfig;
+
+    /// 计算共享密钥
+    pub fn shared_secret(&self, peer_public_key: &[u8; 32]) -> [u8; 32];
+
+    /// 签名消息
+    pub fn sign(&self, message: &[u8]) -> [u8; 64];
+
+    /// 验证签名
+    pub fn verify(public_key: &[u8; 32], message: &[u8], signature: &[u8; 64]) -> bool;
+}
+
+pub struct EncryptedChannel {
+    /// 发送密钥
+    send_key: [u8; 32],
+
+    /// 接收密钥
+    recv_key: [u8; 32],
+
+    /// 发送 nonce
+    send_nonce: AtomicU64,
+
+    /// 接收 nonce
+    recv_nonce: AtomicU64,
+}
+
+impl EncryptedChannel {
+    /// 加密消息
+    pub fn encrypt(&self, plaintext: &[u8]) -> Vec<u8>;
+
+    /// 解密消息
+    pub fn decrypt(&self, ciphertext: &[u8]) -> Result<Vec<u8>>;
+}
+```
+
+### 3.5 HidAdapter (hid_adapter.rs)
+
+RustDesk HID 事件转换。
+
+```rust
+pub struct HidAdapter {
+    hid: Arc<HidController>,
+}
+
+impl HidAdapter {
+    /// 创建适配器
+    pub fn new(hid: Arc<HidController>) -> Self;
+
+    /// 处理键盘事件
+    pub async fn handle_keyboard(&self, event: &RdKeyboardEvent) -> Result<()>;
+
+    /// 处理鼠标事件
+    pub async fn handle_mouse(&self, event: &RdMouseEvent) -> Result<()>;
+
+    /// 转换键码
+    fn convert_keycode(rd_key: u32) -> Option<KeyCode>;
+
+    /// 转换鼠标按钮
+    fn convert_button(rd_button: u32) -> Option<MouseButton>;
+}
+
+/// RustDesk 键盘事件
+pub struct RdKeyboardEvent {
+    pub keycode: u32,
+    pub down: bool,
+    pub modifiers: u32,
+}
+
+/// RustDesk 鼠标事件
+pub struct RdMouseEvent {
+    pub x: i32,
+    pub y: i32,
+    pub mask: u32,
+}
+```
+
+### 3.6 FrameAdapter (frame_adapters.rs)
+
+帧格式转换。
+
+```rust
+pub struct FrameAdapter;
+
+impl FrameAdapter {
+    /// 转换视频帧到 RustDesk 格式
+    pub fn to_rd_video_frame(frame: &EncodedFrame) -> RdVideoFrame;
+
+    /// 转换音频帧到 RustDesk 格式
+    pub fn to_rd_audio_frame(frame: &AudioFrame) -> RdAudioFrame;
+}
+
+/// RustDesk 视频帧
+pub struct RdVideoFrame {
+    pub data: Vec<u8>,
+    pub key_frame: bool,
+    pub pts: i64,
+    pub format: RdVideoFormat,
+}
+
+pub enum RdVideoFormat {
+    H264,
+    H265,
+    VP8,
+    VP9,
+}
+
+/// RustDesk 音频帧
+pub struct RdAudioFrame {
+    pub data: Vec<u8>,
+    pub timestamp: u64,
+}
+```
+
+### 3.7 协议消息 (protocol.rs)
+
+Protobuf 消息包装。
+
+```rust
+/// 使用 prost 生成的 protobuf 消息
+pub mod proto {
+    include!(concat!(env!("OUT_DIR"), "/rendezvous.rs"));
+    include!(concat!(env!("OUT_DIR"), "/message.rs"));
+}
+
+pub struct MessageCodec;
+
+impl MessageCodec {
+    /// 编码消息
+    pub fn encode<M: prost::Message>(msg: &M) -> Vec<u8>;
+
+    /// 解码消息
+    pub fn decode<M: prost::Message + Default>(data: &[u8]) -> Result<M>;
+}
+```
+
+### 3.8 帧编码 (bytes_codec.rs)
+
+变长帧协议。
+
+```rust
+pub struct BytesCodec {
+    state: DecodeState,
+    buffer: BytesMut,
+}
+
+impl BytesCodec {
+    /// 编码帧
+    pub fn encode_frame(data: &[u8]) -> Vec<u8> {
+        let mut buf = Vec::with_capacity(4 + data.len());
+        buf.extend_from_slice(&(data.len() as u32).to_be_bytes());
+        buf.extend_from_slice(data);
+        buf
+    }
+
+    /// 解码帧
+    pub fn decode_frame(&mut self, src: &mut BytesMut) -> Result<Option<Bytes>>;
+}
+
+enum DecodeState {
+    Length,
+    Data(usize),
+}
+```
+
+---
+
+## 4. 协议详解
+
+### 4.1 Protobuf 定义
+
+```protobuf
+// protos/rendezvous.proto
+message RegisterPeer {
+    string id = 1;
+    bytes public_key = 2;
+}
+
+message RegisterPeerResponse {
+    bool ok = 1;
+    string error = 2;
+}
+
+message PunchHoleRequest {
+    string id = 1;
+    string nat_type = 2;
+}
+
+// protos/message.proto
+message VideoFrame {
+    bytes data = 1;
+    bool key = 2;
+    int64 pts = 3;
+    VideoCodec codec = 4;
+}
+
+message AudioFrame {
+    bytes data = 1;
+    int64 timestamp = 2;
+}
+
+message KeyboardEvent {
+    uint32 keycode = 1;
+    bool down = 2;
+    uint32 modifiers = 3;
+}
+
+message MouseEvent {
+    int32 x = 1;
+    int32 y = 2;
+    uint32 mask = 3;
+}
+```
+
+### 4.2 连接握手
+
+```
+1. TCP 连接
+   Client ────► Device
+
+2. 公钥交换
+   Client ◄───► Device
+
+3. DH 密钥协商
+   shared_secret = X25519(my_private, peer_public)
+
+4. 密钥派生
+   send_key = HKDF(shared_secret, "send")
+   recv_key = HKDF(shared_secret, "recv")
+
+5. 认证 (可选)
+   Client ────► Device: encrypted(password)
+   Client ◄──── Device: encrypted(ok/fail)
+
+6. 开始传输
+```
+
+---
+
+## 5. 配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct RustDeskConfig {
+    /// 是否启用
+    pub enabled: bool,
+
+    /// 渲染服务器地址
+    pub rendezvous_server: String,
+
+    /// 中继服务器地址
+    pub relay_server: Option<String>,
+
+    /// 设备 ID (自动生成)
+    pub device_id: Option<String>,
+
+    /// 访问密码
+    pub password: Option<String>,
+
+    /// 允许的客户端 ID
+    pub allowed_clients: Vec<String>,
+}
+
+impl Default for RustDeskConfig {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            rendezvous_server: "rs-ny.rustdesk.com:21116".to_string(),
+            relay_server: None,
+            device_id: None,
+            password: None,
+            allowed_clients: vec![],
+        }
+    }
+}
+```
+
+---
+
+## 6. API 端点
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/rustdesk/status` | GET | 获取服务状态 |
+| `/api/rustdesk/start` | POST | 启动服务 |
+| `/api/rustdesk/stop` | POST | 停止服务 |
+| `/api/rustdesk/config` | GET | 获取配置 |
+| `/api/rustdesk/config` | PATCH | 更新配置 |
+| `/api/rustdesk/device-id` | GET | 获取设备 ID |
+| `/api/rustdesk/connections` | GET | 获取连接列表 |
+| `/api/rustdesk/connections/:id` | DELETE | 断开连接 |
+
+### 响应格式
+
+```json
+// GET /api/rustdesk/status
+{
+    "status": "running",
+    "device_id": "123456789",
+    "rendezvous_connected": true,
+    "active_connections": 1
+}
+
+// GET /api/rustdesk/connections
+{
+    "connections": [
+        {
+            "id": "conn-abc",
+            "peer_id": "987654321",
+            "connected_at": "2024-01-15T10:30:00Z",
+            "ip": "192.168.1.100"
+        }
+    ]
+}
+```
+
+---
+
+## 7. 事件
+
+```rust
+pub enum SystemEvent {
+    RustDeskStatusChanged {
+        status: String,
+        device_id: Option<String>,
+        error: Option<String>,
+    },
+
+    RustDeskConnectionOpened {
+        connection_id: String,
+        peer_id: String,
+    },
+
+    RustDeskConnectionClosed {
+        connection_id: String,
+        peer_id: String,
+        reason: String,
+    },
+}
+```
+
+---
+
+## 8. 错误处理
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum RustDeskError {
+    #[error("Service not running")]
+    NotRunning,
+
+    #[error("Already running")]
+    AlreadyRunning,
+
+    #[error("Rendezvous connection failed: {0}")]
+    RendezvousFailed(String),
+
+    #[error("Authentication failed")]
+    AuthFailed,
+
+    #[error("Connection refused")]
+    ConnectionRefused,
+
+    #[error("Encryption error: {0}")]
+    EncryptionError(String),
+
+    #[error("Protocol error: {0}")]
+    ProtocolError(String),
+
+    #[error("Timeout")]
+    Timeout,
+}
+```
+
+---
+
+## 9. 使用示例
+
+### 9.1 启动服务
+
+```rust
+let config = RustDeskConfig {
+    enabled: true,
+    rendezvous_server: "rs-ny.rustdesk.com:21116".to_string(),
+    password: Some("mypassword".to_string()),
+    ..Default::default()
+};
+
+let service = RustDeskService::new(
+    config,
+    video_pipeline,
+    audio_pipeline,
+    hid,
+    events,
+).await?;
+
+service.start().await?;
+
+println!("Device ID: {}", service.device_id());
+```
+
+### 9.2 客户端连接
+
+```
+1. 打开 RustDesk 客户端
+2. 输入设备 ID
+3. 输入密码 (如果设置)
+4. 连接成功后即可控制
+```
+
+---
+
+## 10. 常见问题
+
+### Q: 无法连接到渲染服务器?
+
+1. 检查网络连接
+2. 检查服务器地址
+3. 检查防火墙
+
+### Q: 客户端连接失败?
+
+1. 检查设备 ID
+2. 检查密码
+3. 检查 NAT 穿透
+
+### Q: 视频延迟高?
+
+1. 使用更近的中继服务器
+2. 检查网络带宽
+3. 降低视频质量
+
+### Q: 如何自建服务器?
+
+参考 RustDesk Server 部署文档:
+- hbbs: 渲染服务器
+- hbbr: 中继服务器

docs/modules/video.md

@@ -0,0 +1,895 @@
+# Video 模块文档
+
+## 1. 模块概述
+
+Video 模块负责视频采集、编码和流传输，是 One-KVM 的核心功能模块。
+
+### 1.1 主要功能
+
+- V4L2 视频设备采集
+- 多格式像素转换
+- 硬件/软件视频编码
+- MJPEG 和 WebRTC 流传输
+- 帧去重和质量控制
+
+### 1.2 文件结构
+
+```
+src/video/
+├── mod.rs                    # 模块导出
+├── capture.rs                # V4L2 视频采集 (22KB)
+├── streamer.rs               # 视频流服务 (34KB)
+├── stream_manager.rs         # 流管理器 (24KB)
+├── shared_video_pipeline.rs  # 共享视频管道 (35KB)
+├── h264_pipeline.rs          # H264 编码管道 (22KB)
+├── format.rs                 # 像素格式定义 (9KB)
+├── frame.rs                  # 视频帧结构 (6KB)
+├── convert.rs                # 格式转换 (21KB)
+└── encoder/                  # 编码器
+    ├── mod.rs
+    ├── traits.rs             # Encoder trait
+    ├── h264.rs               # H264 编码
+    ├── h265.rs               # H265 编码
+    ├── vp8.rs                # VP8 编码
+    ├── vp9.rs                # VP9 编码
+    ├── jpeg.rs               # JPEG 编码
+    └── registry.rs           # 编码器注册表
+```
+
+---
+
+## 2. 架构设计
+
+### 2.1 数据流
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          Video Data Flow                                     │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+V4L2 Device (/dev/video0)
+    │
+    │ Raw frames (MJPEG/YUYV/NV12)
+    ▼
+┌───────────────────┐
+│  VideoCapturer    │ ◄─── capture.rs
+│  - open_device()  │
+│  - read_frame()   │
+│  - set_format()   │
+└─────────┬─────────┘
+          │ VideoFrame
+          ▼
+┌───────────────────┐
+│    Streamer       │ ◄─── streamer.rs
+│  - start()        │
+│  - stop()         │
+│  - get_info()     │
+└─────────┬─────────┘
+          │
+    ┌─────┴─────┐
+    │           │
+    ▼           ▼
+┌────────┐  ┌────────────────────────────┐
+│ MJPEG  │  │  SharedVideoPipeline       │
+│ Mode   │  │  - Decode (MJPEG→YUV)      │
+│        │  │  - Convert (YUV→target)    │
+│        │  │  - Encode (H264/H265/VP8)  │
+└────────┘  └─────────────┬──────────────┘
+    │                     │
+    ▼                     ▼
+┌────────┐          ┌────────┐
+│ HTTP   │          │ WebRTC │
+│ Stream │          │ RTP    │
+└────────┘          └────────┘
+```
+
+### 2.2 组件关系
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       Component Relationships                                │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+VideoStreamManager (stream_manager.rs)
+    │
+    ├──► Streamer (MJPEG mode)
+    │    └──► VideoCapturer
+    │
+    └──► WebRtcStreamer (WebRTC mode)
+         └──► SharedVideoPipeline
+              ├──► VideoCapturer
+              ├──► MjpegDecoder
+              ├──► YuvConverter
+              └──► Encoders[]
+                   ├── H264Encoder
+                   ├── H265Encoder
+                   ├── VP8Encoder
+                   └── VP9Encoder
+```
+
+---
+
+## 3. 核心组件
+
+### 3.1 VideoCapturer (capture.rs)
+
+V4L2 视频采集器，负责从摄像头/采集卡读取视频帧。
+
+#### 主要接口
+
+```rust
+pub struct VideoCapturer {
+    device: Device,
+    stream: Option<MmapStream<'static>>,
+    config: CaptureConfig,
+    format: PixelFormat,
+    resolution: Resolution,
+}
+
+impl VideoCapturer {
+    /// 打开视频设备
+    pub fn open(device_path: &str) -> Result<Self>;
+
+    /// 设置视频格式
+    pub fn set_format(&mut self, config: &CaptureConfig) -> Result<()>;
+
+    /// 开始采集
+    pub fn start(&mut self) -> Result<()>;
+
+    /// 停止采集
+    pub fn stop(&mut self) -> Result<()>;
+
+    /// 读取一帧
+    pub fn read_frame(&mut self) -> Result<VideoFrame>;
+
+    /// 列出设备支持的格式
+    pub fn list_formats(&self) -> Vec<FormatInfo>;
+
+    /// 列出支持的分辨率
+    pub fn list_resolutions(&self, format: PixelFormat) -> Vec<Resolution>;
+}
+```
+
+#### 采集配置
+
+```rust
+pub struct CaptureConfig {
+    pub device: String,           // /dev/video0
+    pub width: u32,               // 1920
+    pub height: u32,              // 1080
+    pub fps: u32,                 // 30
+    pub format: Option<PixelFormat>, // 优先格式
+    pub buffer_count: u32,        // 4
+}
+```
+
+#### 使用示例
+
+```rust
+// 打开设备
+let mut capturer = VideoCapturer::open("/dev/video0")?;
+
+// 设置格式
+capturer.set_format(&CaptureConfig {
+    device: "/dev/video0".to_string(),
+    width: 1920,
+    height: 1080,
+    fps: 30,
+    format: Some(PixelFormat::Mjpeg),
+    buffer_count: 4,
+})?;
+
+// 开始采集
+capturer.start()?;
+
+// 读取帧
+loop {
+    let frame = capturer.read_frame()?;
+    process_frame(frame);
+}
+```
+
+### 3.2 VideoFrame (frame.rs)
+
+视频帧数据结构，支持零拷贝和帧去重。
+
+```rust
+pub struct VideoFrame {
+    /// 帧数据 (引用计数)
+    data: Arc<Bytes>,
+
+    /// xxHash64 缓存 (用于去重)
+    hash: Arc<OnceLock<u64>>,
+
+    /// 分辨率
+    resolution: Resolution,
+
+    /// 像素格式
+    format: PixelFormat,
+
+    /// 行步长
+    stride: u32,
+
+    /// 是否关键帧
+    key_frame: bool,
+
+    /// 帧序号
+    sequence: u64,
+
+    /// 采集时间戳
+    capture_ts: Instant,
+
+    /// 是否有信号
+    online: bool,
+}
+
+impl VideoFrame {
+    /// 创建新帧
+    pub fn new(data: Bytes, resolution: Resolution, format: PixelFormat) -> Self;
+
+    /// 获取帧数据
+    pub fn data(&self) -> &[u8];
+
+    /// 计算帧哈希 (懒加载)
+    pub fn hash(&self) -> u64;
+
+    /// 检查帧是否相同 (用于去重)
+    pub fn is_same_as(&self, other: &Self) -> bool;
+
+    /// 克隆帧 (零拷贝)
+    pub fn clone_ref(&self) -> Self;
+}
+```
+
+### 3.3 PixelFormat (format.rs)
+
+支持的像素格式定义。
+
+```rust
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum PixelFormat {
+    // 压缩格式
+    Mjpeg,      // Motion JPEG (优先级: 100)
+    Jpeg,       // Static JPEG (优先级: 99)
+
+    // YUV 4:2:2 打包格式
+    Yuyv,       // YUYV/YUY2 (优先级: 80)
+    Yvyu,       // YVYU (优先级: 64)
+    Uyvy,       // UYVY (优先级: 65)
+
+    // YUV 半平面格式
+    Nv12,       // NV12 (优先级: 75)
+    Nv16,       // NV16 (优先级: 60)
+    Nv24,       // NV24 (优先级: 55)
+
+    // YUV 平面格式
+    Yuv420,     // I420/YU12 (优先级: 70)
+    Yvu420,     // YV12 (优先级: 63)
+
+    // RGB 格式
+    Rgb565,     // RGB565 (优先级: 40)
+    Rgb24,      // RGB24 (优先级: 50)
+    Bgr24,      // BGR24 (优先级: 49)
+
+    // 灰度
+    Grey,       // 8-bit grayscale (优先级: 10)
+}
+
+impl PixelFormat {
+    /// 获取格式优先级 (越高越好)
+    pub fn priority(&self) -> u32;
+
+    /// 计算帧大小
+    pub fn frame_size(&self, width: u32, height: u32) -> usize;
+
+    /// 转换为 V4L2 FourCC
+    pub fn to_fourcc(&self) -> u32;
+
+    /// 从 V4L2 FourCC 转换
+    pub fn from_fourcc(fourcc: u32) -> Option<Self>;
+
+    /// 是否压缩格式
+    pub fn is_compressed(&self) -> bool;
+}
+```
+
+### 3.4 SharedVideoPipeline (shared_video_pipeline.rs)
+
+多会话共享的视频编码管道。
+
+```rust
+pub struct SharedVideoPipeline {
+    /// 视频采集器
+    capturer: Arc<Mutex<VideoCapturer>>,
+
+    /// MJPEG 解码器
+    decoder: MjpegDecoder,
+
+    /// YUV 转换器
+    converter: YuvConverter,
+
+    /// 编码器实例
+    encoders: HashMap<VideoCodec, Box<dyn Encoder>>,
+
+    /// 活跃会话
+    sessions: Arc<RwLock<Vec<SessionSender>>>,
+
+    /// 配置
+    config: PipelineConfig,
+}
+
+impl SharedVideoPipeline {
+    /// 创建管道
+    pub async fn new(config: PipelineConfig) -> Result<Self>;
+
+    /// 启动管道
+    pub async fn start(&self) -> Result<()>;
+
+    /// 停止管道
+    pub async fn stop(&self) -> Result<()>;
+
+    /// 添加会话订阅
+    pub fn subscribe(&self, codec: VideoCodec) -> Receiver<EncodedFrame>;
+
+    /// 移除会话订阅
+    pub fn unsubscribe(&self, session_id: &str);
+
+    /// 编码单帧 (多编码器)
+    async fn encode_frame(&self, frame: VideoFrame) -> Result<()>;
+}
+```
+
+#### 编码流程
+
+```
+Input: VideoFrame (MJPEG)
+    │
+    ▼
+┌───────────────────┐
+│   MJPEG Decode    │  turbojpeg / VAAPI
+│   MJPEG → YUV420  │
+└─────────┬─────────┘
+          │
+          ▼
+┌───────────────────┐
+│   YUV Convert     │  libyuv (SIMD)
+│  YUV420 → target  │
+└─────────┬─────────┘
+          │
+    ┌─────┴─────┬─────────┬─────────┐
+    │           │         │         │
+    ▼           ▼         ▼         ▼
+┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐
+│ H264  │  │ H265  │  │  VP8  │  │  VP9  │
+│Encoder│  │Encoder│  │Encoder│  │Encoder│
+└───┬───┘  └───┬───┘  └───┬───┘  └───┬───┘
+    │          │          │          │
+    └──────────┴──────────┴──────────┘
+                    │
+                    ▼
+            EncodedFrame[]
+            (distribute to sessions)
+```
+
+### 3.5 Streamer (streamer.rs)
+
+高层视频流服务，管理采集和分发。
+
+```rust
+pub struct Streamer {
+    /// 采集器
+    capturer: Option<Arc<Mutex<VideoCapturer>>>,
+
+    /// 采集任务句柄
+    capture_task: Option<JoinHandle<()>>,
+
+    /// 帧广播通道
+    frame_tx: broadcast::Sender<VideoFrame>,
+
+    /// 状态
+    state: Arc<RwLock<StreamerState>>,
+
+    /// 配置
+    config: StreamerConfig,
+
+    /// 事件总线
+    events: Arc<EventBus>,
+}
+
+impl Streamer {
+    /// 创建流服务
+    pub fn new(events: Arc<EventBus>) -> Self;
+
+    /// 启动流
+    pub async fn start(&self, config: StreamerConfig) -> Result<()>;
+
+    /// 停止流
+    pub async fn stop(&self) -> Result<()>;
+
+    /// 订阅帧
+    pub fn subscribe(&self) -> broadcast::Receiver<VideoFrame>;
+
+    /// 获取状态
+    pub fn state(&self) -> StreamerState;
+
+    /// 获取信息
+    pub fn get_info(&self) -> StreamerInfo;
+
+    /// 应用配置
+    pub async fn apply_config(&self, config: StreamerConfig) -> Result<()>;
+}
+
+pub struct StreamerState {
+    pub status: StreamStatus,
+    pub device: Option<String>,
+    pub resolution: Option<Resolution>,
+    pub format: Option<PixelFormat>,
+    pub fps: f32,
+    pub frame_count: u64,
+    pub error: Option<String>,
+}
+
+pub enum StreamStatus {
+    Idle,
+    Starting,
+    Streaming,
+    Stopping,
+    Error,
+}
+```
+
+### 3.6 VideoStreamManager (stream_manager.rs)
+
+统一管理 MJPEG 和 WebRTC 流模式。
+
+```rust
+pub struct VideoStreamManager {
+    /// MJPEG 流服务
+    mjpeg_streamer: Arc<Streamer>,
+
+    /// WebRTC 流服务
+    webrtc_streamer: Arc<RwLock<Option<WebRtcStreamer>>>,
+
+    /// 当前模式
+    mode: Arc<RwLock<StreamMode>>,
+
+    /// 配置存储
+    config_store: ConfigStore,
+
+    /// 事件总线
+    events: Arc<EventBus>,
+}
+
+impl VideoStreamManager {
+    /// 创建管理器
+    pub fn new(config_store: ConfigStore, events: Arc<EventBus>) -> Self;
+
+    /// 启动流
+    pub async fn start(&self) -> Result<()>;
+
+    /// 停止流
+    pub async fn stop(&self) -> Result<()>;
+
+    /// 切换模式
+    pub async fn set_mode(&self, mode: StreamMode) -> Result<()>;
+
+    /// 获取当前模式
+    pub fn get_mode(&self) -> StreamMode;
+
+    /// 获取设备列表
+    pub fn list_devices(&self) -> Vec<DeviceInfo>;
+
+    /// 获取统计信息
+    pub fn get_stats(&self) -> StreamStats;
+
+    /// 获取 MJPEG 订阅
+    pub fn subscribe_mjpeg(&self) -> broadcast::Receiver<VideoFrame>;
+
+    /// 创建 WebRTC 会话
+    pub async fn create_webrtc_session(&self, params: SessionParams) -> Result<Session>;
+}
+
+pub enum StreamMode {
+    Mjpeg,
+    Webrtc,
+}
+```
+
+---
+
+## 4. 编码器系统
+
+### 4.1 Encoder Trait (encoder/traits.rs)
+
+```rust
+pub trait Encoder: Send + Sync {
+    /// 编码一帧
+    fn encode(&mut self, frame: &VideoFrame) -> Result<EncodedFrame>;
+
+    /// 获取编码器类型
+    fn codec(&self) -> VideoCodec;
+
+    /// 获取当前码率
+    fn bitrate(&self) -> u32;
+
+    /// 设置码率
+    fn set_bitrate(&mut self, bitrate: u32) -> Result<()>;
+
+    /// 获取 GOP 大小
+    fn gop_size(&self) -> u32;
+
+    /// 强制关键帧
+    fn force_keyframe(&mut self);
+
+    /// 重置编码器
+    fn reset(&mut self) -> Result<()>;
+
+    /// 获取编码器信息
+    fn info(&self) -> EncoderInfo;
+}
+
+pub struct EncodedFrame {
+    pub data: Bytes,
+    pub codec: VideoCodec,
+    pub key_frame: bool,
+    pub pts: u64,
+    pub dts: u64,
+}
+
+pub enum VideoCodec {
+    H264,
+    H265,
+    VP8,
+    VP9,
+}
+```
+
+### 4.2 编码器优先级
+
+```
+H264 编码器选择顺序:
+1. VAAPI (Intel/AMD GPU)
+2. RKMPP (Rockchip)
+3. V4L2 M2M
+4. x264 (Software)
+
+H265 编码器选择顺序:
+1. VAAPI
+2. RKMPP
+(无软件后备)
+
+VP8/VP9 编码器:
+1. VAAPI only
+```
+
+### 4.3 EncoderRegistry (encoder/registry.rs)
+
+```rust
+pub struct EncoderRegistry {
+    /// 已注册的编码器工厂
+    factories: HashMap<VideoCodec, Vec<EncoderFactory>>,
+}
+
+impl EncoderRegistry {
+    /// 创建注册表
+    pub fn new() -> Self;
+
+    /// 注册编码器工厂
+    pub fn register(&mut self, codec: VideoCodec, factory: EncoderFactory);
+
+    /// 创建最佳编码器
+    pub fn create_encoder(&self, codec: VideoCodec, config: EncoderConfig) -> Result<Box<dyn Encoder>>;
+
+    /// 列出可用编码器
+    pub fn list_available(&self, codec: VideoCodec) -> Vec<EncoderInfo>;
+
+    /// 探测硬件能力
+    pub fn probe_hardware() -> HardwareCapabilities;
+}
+
+pub struct EncoderFactory {
+    pub name: String,
+    pub priority: u32,
+    pub create: Box<dyn Fn(EncoderConfig) -> Result<Box<dyn Encoder>>>,
+    pub probe: Box<dyn Fn() -> bool>,
+}
+```
+
+---
+
+## 5. 格式转换
+
+### 5.1 MjpegDecoder (convert.rs)
+
+```rust
+pub struct MjpegDecoder {
+    /// turbojpeg 解压缩器
+    decompressor: Decompressor,
+
+    /// 输出缓冲区
+    output_buffer: Vec<u8>,
+}
+
+impl MjpegDecoder {
+    /// 创建解码器
+    pub fn new() -> Result<Self>;
+
+    /// 解码 MJPEG 到 YUV420
+    pub fn decode(&mut self, jpeg_data: &[u8]) -> Result<YuvFrame>;
+
+    /// 获取图像信息
+    pub fn get_info(jpeg_data: &[u8]) -> Result<ImageInfo>;
+}
+```
+
+### 5.2 YuvConverter (convert.rs)
+
+使用 libyuv 进行高性能格式转换。
+
+```rust
+pub struct YuvConverter;
+
+impl YuvConverter {
+    /// YUYV → YUV420
+    pub fn yuyv_to_yuv420(src: &[u8], dst: &mut [u8], width: u32, height: u32);
+
+    /// NV12 → YUV420
+    pub fn nv12_to_yuv420(src: &[u8], dst: &mut [u8], width: u32, height: u32);
+
+    /// RGB24 → YUV420
+    pub fn rgb24_to_yuv420(src: &[u8], dst: &mut [u8], width: u32, height: u32);
+
+    /// YUV420 → NV12
+    pub fn yuv420_to_nv12(src: &[u8], dst: &mut [u8], width: u32, height: u32);
+
+    /// 缩放 YUV420
+    pub fn scale_yuv420(
+        src: &[u8], src_width: u32, src_height: u32,
+        dst: &mut [u8], dst_width: u32, dst_height: u32,
+        filter: ScaleFilter,
+    );
+}
+
+pub enum ScaleFilter {
+    None,       // 最近邻
+    Linear,     // 双线性
+    Bilinear,   // 双线性 (同 Linear)
+    Box,        // 盒式滤波
+}
+```
+
+---
+
+## 6. 配置说明
+
+### 6.1 视频配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct VideoConfig {
+    /// 设备路径 (/dev/video0)
+    pub device: Option<String>,
+
+    /// 像素格式 (MJPEG/YUYV/NV12)
+    pub format: Option<String>,
+
+    /// 宽度
+    pub width: u32,
+
+    /// 高度
+    pub height: u32,
+
+    /// 帧率
+    pub fps: u32,
+
+    /// JPEG 质量 (1-100)
+    pub quality: u32,
+}
+
+impl Default for VideoConfig {
+    fn default() -> Self {
+        Self {
+            device: None,
+            format: None,
+            width: 1920,
+            height: 1080,
+            fps: 30,
+            quality: 80,
+        }
+    }
+}
+```
+
+### 6.2 流配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct StreamConfig {
+    /// 流模式
+    pub mode: StreamMode,
+
+    /// 码率 (kbps)
+    pub bitrate_kbps: u32,
+
+    /// GOP 大小
+    pub gop_size: u32,
+
+    /// 编码器类型
+    pub encoder: EncoderType,
+
+    /// STUN 服务器
+    pub stun_server: Option<String>,
+
+    /// TURN 服务器
+    pub turn_server: Option<String>,
+
+    /// TURN 用户名
+    pub turn_username: Option<String>,
+
+    /// TURN 密码
+    pub turn_password: Option<String>,
+}
+```
+
+---
+
+## 7. API 端点
+
+### 7.1 流控制
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/stream/status` | GET | 获取流状态 |
+| `/api/stream/start` | POST | 启动流 |
+| `/api/stream/stop` | POST | 停止流 |
+| `/api/stream/mode` | GET | 获取流模式 |
+| `/api/stream/mode` | POST | 设置流模式 |
+| `/api/stream/mjpeg` | GET | MJPEG 流 |
+| `/api/stream/snapshot` | GET | 获取快照 |
+
+### 7.2 设备管理
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/devices/video` | GET | 列出视频设备 |
+| `/api/devices/video/:id/formats` | GET | 列出设备格式 |
+| `/api/devices/video/:id/resolutions` | GET | 列出分辨率 |
+
+### 7.3 响应格式
+
+```json
+// GET /api/stream/status
+{
+    "status": "streaming",
+    "device": "/dev/video0",
+    "resolution": { "width": 1920, "height": 1080 },
+    "format": "MJPEG",
+    "fps": 30.0,
+    "frame_count": 12345,
+    "mode": "mjpeg"
+}
+
+// GET /api/devices/video
+{
+    "devices": [
+        {
+            "path": "/dev/video0",
+            "name": "USB Capture",
+            "driver": "uvcvideo",
+            "bus": "usb-0000:00:14.0-1"
+        }
+    ]
+}
+```
+
+---
+
+## 8. 事件
+
+视频模块发布的事件:
+
+```rust
+pub enum SystemEvent {
+    /// 流状态变化
+    StreamStateChanged {
+        state: String,      // "idle" | "starting" | "streaming" | "stopping" | "error"
+        device: Option<String>,
+        resolution: Option<Resolution>,
+        fps: Option<f32>,
+    },
+
+    /// 设备变化
+    VideoDeviceChanged {
+        added: Vec<String>,
+        removed: Vec<String>,
+    },
+
+    /// 编码器变化
+    EncoderChanged {
+        codec: String,
+        hardware: bool,
+    },
+}
+```
+
+---
+
+## 9. 错误处理
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum VideoError {
+    #[error("Device not found: {0}")]
+    DeviceNotFound(String),
+
+    #[error("Device busy: {0}")]
+    DeviceBusy(String),
+
+    #[error("Format not supported: {0:?}")]
+    FormatNotSupported(PixelFormat),
+
+    #[error("Resolution not supported: {0}x{1}")]
+    ResolutionNotSupported(u32, u32),
+
+    #[error("Capture error: {0}")]
+    CaptureError(String),
+
+    #[error("Encoder error: {0}")]
+    EncoderError(String),
+
+    #[error("No signal")]
+    NoSignal,
+
+    #[error("Device lost")]
+    DeviceLost,
+}
+```
+
+---
+
+## 10. 性能优化
+
+### 10.1 零拷贝
+
+- `Arc<Bytes>` 共享帧数据
+- 引用计数避免复制
+
+### 10.2 帧去重
+
+- xxHash64 快速哈希
+- 相同帧跳过编码
+
+### 10.3 硬件加速
+
+- VAAPI 优先
+- 自动后备软件编码
+
+### 10.4 内存池
+
+- 预分配帧缓冲区
+- 复用编码器缓冲区
+
+---
+
+## 11. 常见问题
+
+### Q: 如何添加新的视频格式?
+
+1. 在 `format.rs` 添加枚举值
+2. 实现 `to_fourcc()` 和 `from_fourcc()`
+3. 在 `convert.rs` 添加转换函数
+
+### Q: 如何添加新的编码器?
+
+1. 实现 `Encoder` trait
+2. 创建 `EncoderFactory`
+3. 在 `EncoderRegistry` 注册
+
+### Q: 帧率不稳定怎么办?
+
+1. 检查 USB 带宽
+2. 降低分辨率
+3. 使用 MJPEG 格式
+4. 启用硬件编码

docs/modules/web.md

@@ -0,0 +1,428 @@
+# Web 模块文档
+
+## 1. 模块概述
+
+Web 模块提供 HTTP API 和静态文件服务。
+
+### 1.1 主要功能
+
+- REST API
+- WebSocket
+- 静态文件服务
+- 认证中间件
+- CORS 支持
+
+### 1.2 文件结构
+
+```
+src/web/
+├── mod.rs              # 模块导出
+├── routes.rs           # 路由定义 (9KB)
+├── ws.rs               # WebSocket (8KB)
+├── audio_ws.rs         # 音频 WebSocket (8KB)
+├── static_files.rs     # 静态文件 (6KB)
+└── handlers/           # API 处理器
+    ├── mod.rs
+    └── config/
+        ├── mod.rs
+        ├── apply.rs
+        ├── types.rs
+        └── rustdesk.rs
+```
+
+---
+
+## 2. 路由结构
+
+### 2.1 公共路由 (无认证)
+
+| 路由 | 方法 | 描述 |
+|------|------|------|
+| `/health` | GET | 健康检查 |
+| `/auth/login` | POST | 登录 |
+| `/setup` | GET | 获取设置状态 |
+| `/setup/init` | POST | 初始化设置 |
+
+### 2.2 用户路由 (需认证)
+
+| 路由 | 方法 | 描述 |
+|------|------|------|
+| `/info` | GET | 系统信息 |
+| `/devices` | GET | 设备列表 |
+| `/stream/*` | * | 流控制 |
+| `/webrtc/*` | * | WebRTC 信令 |
+| `/hid/*` | * | HID 控制 |
+| `/audio/*` | * | 音频控制 |
+| `/ws` | WS | 事件 WebSocket |
+| `/ws/audio` | WS | 音频 WebSocket |
+
+### 2.3 管理员路由 (需 Admin)
+
+| 路由 | 方法 | 描述 |
+|------|------|------|
+| `/config/*` | * | 配置管理 |
+| `/msd/*` | * | MSD 操作 |
+| `/atx/*` | * | ATX 控制 |
+| `/extensions/*` | * | 扩展管理 |
+| `/rustdesk/*` | * | RustDesk |
+| `/users/*` | * | 用户管理 |
+
+---
+
+## 3. 路由定义
+
+```rust
+pub fn create_router(state: Arc<AppState>) -> Router {
+    Router::new()
+        // 公共路由
+        .route("/health", get(handlers::health))
+        .route("/auth/login", post(handlers::login))
+        .route("/setup", get(handlers::setup_status))
+        .route("/setup/init", post(handlers::setup_init))
+
+        // 用户路由
+        .nest("/api", user_routes())
+
+        // 管理员路由
+        .nest("/api/admin", admin_routes())
+
+        // 静态文件
+        .fallback(static_files::serve)
+
+        // 中间件
+        .layer(CorsLayer::permissive())
+        .layer(CompressionLayer::new())
+        .layer(TraceLayer::new_for_http())
+
+        // 状态
+        .with_state(state)
+}
+
+fn user_routes() -> Router {
+    Router::new()
+        .route("/info", get(handlers::system_info))
+        .route("/devices", get(handlers::list_devices))
+
+        // 流控制
+        .route("/stream/status", get(handlers::stream_status))
+        .route("/stream/start", post(handlers::stream_start))
+        .route("/stream/stop", post(handlers::stream_stop))
+        .route("/stream/mjpeg", get(handlers::mjpeg_stream))
+
+        // WebRTC
+        .route("/webrtc/session", post(handlers::webrtc_create_session))
+        .route("/webrtc/offer", post(handlers::webrtc_offer))
+        .route("/webrtc/ice", post(handlers::webrtc_ice))
+        .route("/webrtc/close", post(handlers::webrtc_close))
+
+        // HID
+        .route("/hid/status", get(handlers::hid_status))
+        .route("/hid/reset", post(handlers::hid_reset))
+
+        // WebSocket
+        .route("/ws", get(handlers::ws_handler))
+        .route("/ws/audio", get(handlers::audio_ws_handler))
+
+        // 认证中间件
+        .layer(middleware::from_fn(auth_middleware))
+}
+
+fn admin_routes() -> Router {
+    Router::new()
+        // 配置
+        .route("/config", get(handlers::config::get_config))
+        .route("/config", patch(handlers::config::update_config))
+
+        // MSD
+        .route("/msd/status", get(handlers::msd_status))
+        .route("/msd/connect", post(handlers::msd_connect))
+
+        // ATX
+        .route("/atx/status", get(handlers::atx_status))
+        .route("/atx/power/short", post(handlers::atx_power_short))
+
+        // 认证中间件
+        .layer(middleware::from_fn(auth_middleware))
+        .layer(middleware::from_fn(admin_middleware))
+}
+```
+
+---
+
+## 4. 静态文件服务
+
+```rust
+#[derive(RustEmbed)]
+#[folder = "web/dist"]
+#[include = "*.html"]
+#[include = "*.js"]
+#[include = "*.css"]
+#[include = "assets/*"]
+struct Assets;
+
+pub async fn serve(uri: Uri) -> impl IntoResponse {
+    let path = uri.path().trim_start_matches('/');
+
+    // 尝试获取文件
+    if let Some(content) = Assets::get(path) {
+        let mime = mime_guess::from_path(path)
+            .first_or_octet_stream();
+
+        return (
+            [(header::CONTENT_TYPE, mime.as_ref())],
+            content.data.into_owned(),
+        ).into_response();
+    }
+
+    // SPA 回退到 index.html
+    if let Some(content) = Assets::get("index.html") {
+        return (
+            [(header::CONTENT_TYPE, "text/html")],
+            content.data.into_owned(),
+        ).into_response();
+    }
+
+    StatusCode::NOT_FOUND.into_response()
+}
+```
+
+---
+
+## 5. WebSocket 处理
+
+### 5.1 事件 WebSocket (ws.rs)
+
+```rust
+pub async fn ws_handler(
+    ws: WebSocketUpgrade,
+    State(state): State<Arc<AppState>>,
+) -> impl IntoResponse {
+    ws.on_upgrade(|socket| handle_ws(socket, state))
+}
+
+async fn handle_ws(mut socket: WebSocket, state: Arc<AppState>) {
+    // 发送初始设备信息
+    let device_info = state.get_device_info().await;
+    let json = serde_json::to_string(&device_info).unwrap();
+    let _ = socket.send(Message::Text(json)).await;
+
+    // 订阅事件
+    let mut rx = state.events.subscribe();
+
+    loop {
+        tokio::select! {
+            // 发送事件
+            result = rx.recv() => {
+                if let Ok(event) = result {
+                    let json = serde_json::to_string(&event).unwrap();
+                    if socket.send(Message::Text(json)).await.is_err() {
+                        break;
+                    }
+                }
+            }
+
+            // 接收消息 (心跳/关闭)
+            msg = socket.recv() => {
+                match msg {
+                    Some(Ok(Message::Ping(data))) => {
+                        let _ = socket.send(Message::Pong(data)).await;
+                    }
+                    Some(Ok(Message::Close(_))) | None => break,
+                    _ => {}
+                }
+            }
+        }
+    }
+}
+```
+
+### 5.2 音频 WebSocket (audio_ws.rs)
+
+```rust
+pub async fn audio_ws_handler(
+    ws: WebSocketUpgrade,
+    State(state): State<Arc<AppState>>,
+) -> impl IntoResponse {
+    ws.on_upgrade(|socket| handle_audio_ws(socket, state))
+}
+
+async fn handle_audio_ws(mut socket: WebSocket, state: Arc<AppState>) {
+    // 订阅音频帧
+    let mut rx = state.audio.subscribe();
+
+    loop {
+        tokio::select! {
+            // 发送音频帧
+            result = rx.recv() => {
+                if let Ok(frame) = result {
+                    if socket.send(Message::Binary(frame.data.to_vec())).await.is_err() {
+                        break;
+                    }
+                }
+            }
+
+            // 处理关闭
+            msg = socket.recv() => {
+                match msg {
+                    Some(Ok(Message::Close(_))) | None => break,
+                    _ => {}
+                }
+            }
+        }
+    }
+}
+```
+
+---
+
+## 6. MJPEG 流
+
+```rust
+pub async fn mjpeg_stream(
+    State(state): State<Arc<AppState>>,
+) -> impl IntoResponse {
+    let boundary = "frame";
+
+    // 订阅视频帧
+    let rx = state.stream_manager.subscribe_mjpeg();
+
+    // 创建流
+    let stream = async_stream::stream! {
+        let mut rx = rx;
+        while let Ok(frame) = rx.recv().await {
+            let header = format!(
+                "--{}\r\nContent-Type: image/jpeg\r\nContent-Length: {}\r\n\r\n",
+                boundary,
+                frame.data.len()
+            );
+            yield Ok::<_, std::io::Error>(Bytes::from(header));
+            yield Ok(frame.data.clone());
+            yield Ok(Bytes::from("\r\n"));
+        }
+    };
+
+    (
+        [(
+            header::CONTENT_TYPE,
+            format!("multipart/x-mixed-replace; boundary={}", boundary),
+        )],
+        Body::from_stream(stream),
+    )
+}
+```
+
+---
+
+## 7. 错误处理
+
+```rust
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        let (status, message) = match self {
+            AppError::AuthError => (StatusCode::UNAUTHORIZED, "Authentication failed"),
+            AppError::Unauthorized => (StatusCode::UNAUTHORIZED, "Unauthorized"),
+            AppError::Forbidden => (StatusCode::FORBIDDEN, "Forbidden"),
+            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg.as_str()),
+            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg.as_str()),
+            AppError::Internal(err) => {
+                tracing::error!("Internal error: {:?}", err);
+                (StatusCode::INTERNAL_SERVER_ERROR, "Internal server error")
+            }
+            // ...
+        };
+
+        (status, Json(json!({ "error": message }))).into_response()
+    }
+}
+```
+
+---
+
+## 8. 请求提取器
+
+```rust
+// 从 Cookie 获取会话
+pub struct AuthUser(pub Session);
+
+#[async_trait]
+impl<S> FromRequestParts<S> for AuthUser
+where
+    S: Send + Sync,
+{
+    type Rejection = AppError;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let cookies = Cookies::from_request_parts(parts, state).await?;
+        let token = cookies
+            .get("session_id")
+            .map(|c| c.value().to_string())
+            .ok_or(AppError::Unauthorized)?;
+
+        let state = parts.extensions.get::<Arc<AppState>>().unwrap();
+        let session = state.sessions
+            .get_session(&token)
+            .ok_or(AppError::Unauthorized)?;
+
+        Ok(AuthUser(session))
+    }
+}
+```
+
+---
+
+## 9. 中间件
+
+### 9.1 认证中间件
+
+```rust
+pub async fn auth_middleware(
+    State(state): State<Arc<AppState>>,
+    cookies: Cookies,
+    mut request: Request,
+    next: Next,
+) -> Response {
+    let token = cookies
+        .get("session_id")
+        .map(|c| c.value().to_string());
+
+    if let Some(session) = token.and_then(|t| state.sessions.get_session(&t)) {
+        request.extensions_mut().insert(session);
+        next.run(request).await
+    } else {
+        StatusCode::UNAUTHORIZED.into_response()
+    }
+}
+```
+
+### 9.2 Admin 中间件
+
+```rust
+pub async fn admin_middleware(
+    Extension(session): Extension<Session>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if session.role == UserRole::Admin {
+        next.run(request).await
+    } else {
+        StatusCode::FORBIDDEN.into_response()
+    }
+}
+```
+
+---
+
+## 10. HTTPS 支持
+
+```rust
+// 使用 axum-server 提供 TLS
+let tls_config = RustlsConfig::from_pem_file(cert_path, key_path).await?;
+
+axum_server::bind_rustls(addr, tls_config)
+    .serve(app.into_make_service())
+    .await?;
+
+// 或自动生成自签名证书
+let (cert, key) = generate_self_signed_cert()?;
+let tls_config = RustlsConfig::from_pem(cert, key).await?;
+```

docs/modules/webrtc.md

@@ -0,0 +1,731 @@
+# WebRTC 模块文档
+
+## 1. 模块概述
+
+WebRTC 模块提供低延迟的实时音视频流传输，支持多种视频编码格式和 DataChannel HID 控制。
+
+### 1.1 主要功能
+
+- WebRTC 会话管理
+- 多编码器支持 (H264/H265/VP8/VP9)
+- 音频轨道 (Opus)
+- DataChannel HID
+- ICE/STUN/TURN 支持
+
+### 1.2 文件结构
+
+```
+src/webrtc/
+├── mod.rs                  # 模块导出
+├── webrtc_streamer.rs      # 统一管理器 (34KB)
+├── universal_session.rs    # 会话管理 (32KB)
+├── video_track.rs          # 视频轨道 (19KB)
+├── rtp.rs                  # RTP 打包 (24KB)
+├── h265_payloader.rs       # H265 RTP (15KB)
+├── peer.rs                 # PeerConnection (17KB)
+├── config.rs               # 配置 (3KB)
+├── signaling.rs            # 信令 (5KB)
+└── track.rs                # 轨道基类 (11KB)
+```
+
+---
+
+## 2. 架构设计
+
+### 2.1 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         WebRTC Architecture                                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                Browser
+                   │
+                   │ HTTP Signaling
+                   ▼
+         ┌─────────────────┐
+         │ WebRtcStreamer  │
+         │(webrtc_streamer)│
+         └────────┬────────┘
+                  │
+    ┌─────────────┼─────────────┐
+    │             │             │
+    ▼             ▼             ▼
+┌────────┐  ┌────────┐    ┌────────┐
+│Session │  │Session │    │Session │
+│   1    │  │   2    │    │   N    │
+└───┬────┘  └───┬────┘    └───┬────┘
+    │           │             │
+    ├───────────┼─────────────┤
+    │           │             │
+    ▼           ▼             ▼
+┌─────────────────────────────────────┐
+│       SharedVideoPipeline           │
+│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐  │
+│  │H264 │ │H265 │ │VP8  │ │VP9  │  │
+│  └─────┘ └─────┘ └─────┘ └─────┘  │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+         ┌────────────────┐
+         │ VideoCapturer  │
+         └────────────────┘
+```
+
+### 2.2 会话生命周期
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      Session Lifecycle                                       │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+1. 创建会话
+   POST /webrtc/session
+        │
+        ▼
+   ┌─────────────────┐
+   │ Create Session  │
+   │ Generate ID     │
+   └────────┬────────┘
+            │
+            ▼
+   { session_id: "..." }
+
+2. 发送 Offer
+   POST /webrtc/offer
+   { session_id, codec, offer_sdp }
+        │
+        ▼
+   ┌─────────────────┐
+   │ Process Offer   │
+   │ Create Answer   │
+   │ Setup Tracks    │
+   └────────┬────────┘
+            │
+            ▼
+   { answer_sdp, ice_candidates }
+
+3. ICE 候选
+   POST /webrtc/ice
+   { session_id, candidate }
+        │
+        ▼
+   ┌─────────────────┐
+   │ Add ICE         │
+   │ Candidate       │
+   └─────────────────┘
+
+4. 连接建立
+   ┌─────────────────┐
+   │ DTLS Handshake  │
+   │ SRTP Setup      │
+   │ DataChannel     │
+   └────────┬────────┘
+            │
+            ▼
+   开始传输视频/音频
+
+5. 关闭会话
+   POST /webrtc/close
+   { session_id }
+        │
+        ▼
+   ┌─────────────────┐
+   │ Cleanup         │
+   │ Release         │
+   └─────────────────┘
+```
+
+---
+
+## 3. 核心组件
+
+### 3.1 WebRtcStreamer (webrtc_streamer.rs)
+
+WebRTC 服务主类。
+
+```rust
+pub struct WebRtcStreamer {
+    /// 会话映射
+    sessions: Arc<RwLock<HashMap<String, Arc<UniversalSession>>>>,
+
+    /// 共享视频管道
+    video_pipeline: Arc<SharedVideoPipeline>,
+
+    /// 共享音频管道
+    audio_pipeline: Arc<SharedAudioPipeline>,
+
+    /// HID 控制器
+    hid: Arc<HidController>,
+
+    /// 配置
+    config: WebRtcConfig,
+
+    /// 事件总线
+    events: Arc<EventBus>,
+}
+
+impl WebRtcStreamer {
+    /// 创建流服务
+    pub async fn new(
+        video_pipeline: Arc<SharedVideoPipeline>,
+        audio_pipeline: Arc<SharedAudioPipeline>,
+        hid: Arc<HidController>,
+        config: WebRtcConfig,
+        events: Arc<EventBus>,
+    ) -> Result<Self>;
+
+    /// 创建会话
+    pub async fn create_session(&self) -> Result<String>;
+
+    /// 处理 Offer
+    pub async fn process_offer(
+        &self,
+        session_id: &str,
+        offer: &str,
+        codec: VideoCodec,
+    ) -> Result<OfferResponse>;
+
+    /// 添加 ICE 候选
+    pub async fn add_ice_candidate(
+        &self,
+        session_id: &str,
+        candidate: &str,
+    ) -> Result<()>;
+
+    /// 关闭会话
+    pub async fn close_session(&self, session_id: &str) -> Result<()>;
+
+    /// 获取会话列表
+    pub fn list_sessions(&self) -> Vec<SessionInfo>;
+
+    /// 获取统计信息
+    pub fn get_stats(&self) -> WebRtcStats;
+}
+
+pub struct OfferResponse {
+    pub answer_sdp: String,
+    pub ice_candidates: Vec<String>,
+}
+
+pub struct WebRtcStats {
+    pub active_sessions: usize,
+    pub total_bytes_sent: u64,
+    pub avg_bitrate: u32,
+}
+```
+
+### 3.2 UniversalSession (universal_session.rs)
+
+单个 WebRTC 会话。
+
+```rust
+pub struct UniversalSession {
+    /// 会话 ID
+    id: String,
+
+    /// PeerConnection
+    peer: Arc<RTCPeerConnection>,
+
+    /// 视频轨道
+    video_track: Arc<UniversalVideoTrack>,
+
+    /// 音频轨道
+    audio_track: Option<Arc<dyn TrackLocal>>,
+
+    /// HID DataChannel
+    hid_channel: Arc<RwLock<Option<Arc<RTCDataChannel>>>>,
+
+    /// HID 处理器
+    hid_handler: Arc<HidDataChannelHandler>,
+
+    /// 状态
+    state: Arc<RwLock<SessionState>>,
+
+    /// 编码器类型
+    codec: VideoCodec,
+}
+
+impl UniversalSession {
+    /// 创建会话
+    pub async fn new(
+        id: String,
+        config: &WebRtcConfig,
+        video_pipeline: Arc<SharedVideoPipeline>,
+        audio_pipeline: Arc<SharedAudioPipeline>,
+        hid_handler: Arc<HidDataChannelHandler>,
+        codec: VideoCodec,
+    ) -> Result<Self>;
+
+    /// 处理 Offer SDP
+    pub async fn handle_offer(&self, offer_sdp: &str) -> Result<String>;
+
+    /// 添加 ICE 候选
+    pub async fn add_ice_candidate(&self, candidate: &str) -> Result<()>;
+
+    /// 获取 ICE 候选
+    pub fn get_ice_candidates(&self) -> Vec<String>;
+
+    /// 关闭会话
+    pub async fn close(&self) -> Result<()>;
+
+    /// 获取状态
+    pub fn state(&self) -> SessionState;
+
+    /// 获取统计
+    pub fn stats(&self) -> SessionStats;
+}
+
+pub enum SessionState {
+    New,
+    Connecting,
+    Connected,
+    Disconnected,
+    Failed,
+    Closed,
+}
+
+pub struct SessionStats {
+    pub bytes_sent: u64,
+    pub packets_sent: u64,
+    pub bitrate: u32,
+    pub frame_rate: f32,
+    pub round_trip_time: Duration,
+}
+```
+
+### 3.3 VideoTrack (video_track.rs)
+
+视频轨道封装。
+
+```rust
+pub struct UniversalVideoTrack {
+    /// 轨道 ID
+    id: String,
+
+    /// 编码类型
+    codec: VideoCodec,
+
+    /// RTP 发送器
+    rtp_sender: Arc<RtpSender>,
+
+    /// 帧计数
+    frame_count: AtomicU64,
+
+    /// 统计
+    stats: Arc<RwLock<TrackStats>>,
+}
+
+impl UniversalVideoTrack {
+    /// 创建轨道
+    pub fn new(id: &str, codec: VideoCodec) -> Result<Self>;
+
+    /// 发送编码帧
+    pub async fn send_frame(&self, frame: &EncodedFrame) -> Result<()>;
+
+    /// 获取 RTP 参数
+    pub fn rtp_params(&self) -> RtpParameters;
+
+    /// 获取统计
+    pub fn stats(&self) -> TrackStats;
+}
+
+pub struct TrackStats {
+    pub frames_sent: u64,
+    pub bytes_sent: u64,
+    pub packets_sent: u64,
+    pub packet_loss: f32,
+}
+```
+
+### 3.4 RTP 打包 (rtp.rs)
+
+RTP 协议实现。
+
+```rust
+pub struct RtpPacketizer {
+    /// SSRC
+    ssrc: u32,
+
+    /// 序列号
+    sequence: u16,
+
+    /// 时间戳
+    timestamp: u32,
+
+    /// 负载类型
+    payload_type: u8,
+
+    /// 时钟频率
+    clock_rate: u32,
+}
+
+impl RtpPacketizer {
+    /// 创建打包器
+    pub fn new(codec: VideoCodec) -> Self;
+
+    /// 打包 H264 帧
+    pub fn packetize_h264(&mut self, frame: &[u8], keyframe: bool) -> Vec<Vec<u8>>;
+
+    /// 打包 VP8 帧
+    pub fn packetize_vp8(&mut self, frame: &[u8], keyframe: bool) -> Vec<Vec<u8>>;
+
+    /// 打包 VP9 帧
+    pub fn packetize_vp9(&mut self, frame: &[u8], keyframe: bool) -> Vec<Vec<u8>>;
+
+    /// 打包 Opus 帧
+    pub fn packetize_opus(&mut self, frame: &[u8]) -> Vec<u8>;
+}
+
+/// H264 NAL 单元分片
+pub struct H264Fragmenter;
+
+impl H264Fragmenter {
+    /// 分片大于 MTU 的 NAL
+    pub fn fragment(nal: &[u8], mtu: usize) -> Vec<Vec<u8>>;
+
+    /// 创建 STAP-A 聚合
+    pub fn aggregate(nals: &[&[u8]]) -> Vec<u8>;
+}
+```
+
+### 3.5 H265 打包器 (h265_payloader.rs)
+
+H265/HEVC RTP 打包。
+
+```rust
+pub struct H265Payloader {
+    /// MTU 大小
+    mtu: usize,
+}
+
+impl H265Payloader {
+    /// 创建打包器
+    pub fn new(mtu: usize) -> Self;
+
+    /// 打包 H265 帧
+    pub fn packetize(&self, frame: &[u8]) -> Vec<Vec<u8>>;
+
+    /// 分析 NAL 单元类型
+    fn get_nal_type(nal: &[u8]) -> u8;
+
+    /// 是否需要分片
+    fn needs_fragmentation(&self, nal: &[u8]) -> bool;
+}
+```
+
+---
+
+## 4. 信令协议
+
+### 4.1 创建会话
+
+```
+POST /api/webrtc/session
+Content-Type: application/json
+
+{}
+
+Response:
+{
+    "session_id": "abc123-def456"
+}
+```
+
+### 4.2 发送 Offer
+
+```
+POST /api/webrtc/offer
+Content-Type: application/json
+
+{
+    "session_id": "abc123-def456",
+    "video_codec": "h264",
+    "enable_audio": true,
+    "offer_sdp": "v=0\r\no=- ..."
+}
+
+Response:
+{
+    "answer_sdp": "v=0\r\no=- ...",
+    "ice_candidates": [
+        "candidate:1 1 UDP ...",
+        "candidate:2 1 TCP ..."
+    ]
+}
+```
+
+### 4.3 ICE 候选
+
+```
+POST /api/webrtc/ice
+Content-Type: application/json
+
+{
+    "session_id": "abc123-def456",
+    "candidate": "candidate:1 1 UDP ..."
+}
+
+Response:
+{
+    "success": true
+}
+```
+
+### 4.4 关闭会话
+
+```
+POST /api/webrtc/close
+Content-Type: application/json
+
+{
+    "session_id": "abc123-def456"
+}
+
+Response:
+{
+    "success": true
+}
+```
+
+---
+
+## 5. 配置
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[typeshare]
+pub struct WebRtcConfig {
+    /// STUN 服务器
+    pub stun_servers: Vec<String>,
+
+    /// TURN 服务器
+    pub turn_servers: Vec<TurnServer>,
+
+    /// 默认编码器
+    pub default_codec: VideoCodec,
+
+    /// 码率 (kbps)
+    pub bitrate_kbps: u32,
+
+    /// GOP 大小
+    pub gop_size: u32,
+
+    /// 启用音频
+    pub enable_audio: bool,
+
+    /// 启用 DataChannel HID
+    pub enable_datachannel_hid: bool,
+}
+
+pub struct TurnServer {
+    pub url: String,
+    pub username: String,
+    pub password: String,
+}
+
+impl Default for WebRtcConfig {
+    fn default() -> Self {
+        Self {
+            stun_servers: vec!["stun:stun.l.google.com:19302".to_string()],
+            turn_servers: vec![],
+            default_codec: VideoCodec::H264,
+            bitrate_kbps: 2000,
+            gop_size: 60,
+            enable_audio: true,
+            enable_datachannel_hid: true,
+        }
+    }
+}
+```
+
+---
+
+## 6. DataChannel HID
+
+### 6.1 消息格式
+
+```javascript
+// 键盘事件
+{
+    "type": "keyboard",
+    "keys": ["KeyA", "KeyB"],
+    "modifiers": {
+        "ctrl": false,
+        "shift": true,
+        "alt": false,
+        "meta": false
+    }
+}
+
+// 鼠标事件
+{
+    "type": "mouse",
+    "x": 16384,
+    "y": 16384,
+    "button": "left",
+    "event": "press"
+}
+
+// 鼠标模式
+{
+    "type": "mouse_mode",
+    "mode": "absolute"
+}
+```
+
+### 6.2 处理流程
+
+```
+DataChannel Message
+        │
+        ▼
+┌─────────────────┐
+│Parse JSON Event │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│HidDataChannel   │
+│   Handler       │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ HidController   │
+└────────┬────────┘
+         │
+         ▼
+    USB/Serial
+```
+
+---
+
+## 7. 支持的编码器
+
+| 编码器 | RTP 负载类型 | 时钟频率 | 硬件加速 |
+|--------|-------------|---------|---------|
+| H264 | 96 (动态) | 90000 | VAAPI/RKMPP/V4L2 |
+| H265 | 97 (动态) | 90000 | VAAPI |
+| VP8 | 98 (动态) | 90000 | VAAPI |
+| VP9 | 99 (动态) | 90000 | VAAPI |
+| Opus | 111 (动态) | 48000 | 无 (软件) |
+
+---
+
+## 8. 错误处理
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum WebRtcError {
+    #[error("Session not found: {0}")]
+    SessionNotFound(String),
+
+    #[error("Session already exists")]
+    SessionExists,
+
+    #[error("Invalid SDP: {0}")]
+    InvalidSdp(String),
+
+    #[error("Codec not supported: {0}")]
+    CodecNotSupported(String),
+
+    #[error("ICE failed")]
+    IceFailed,
+
+    #[error("DTLS failed")]
+    DtlsFailed,
+
+    #[error("Track error: {0}")]
+    TrackError(String),
+
+    #[error("Connection closed")]
+    ConnectionClosed,
+}
+```
+
+---
+
+## 9. 使用示例
+
+### 9.1 创建会话
+
+```rust
+let streamer = WebRtcStreamer::new(
+    video_pipeline,
+    audio_pipeline,
+    hid,
+    WebRtcConfig::default(),
+    events,
+).await?;
+
+// 创建会话
+let session_id = streamer.create_session().await?;
+
+// 处理 Offer
+let response = streamer.process_offer(
+    &session_id,
+    &offer_sdp,
+    VideoCodec::H264,
+).await?;
+
+println!("Answer: {}", response.answer_sdp);
+```
+
+### 9.2 前端连接
+
+```javascript
+// 创建 PeerConnection
+const pc = new RTCPeerConnection({
+    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+});
+
+// 创建 DataChannel
+const hidChannel = pc.createDataChannel('hid');
+
+// 创建 Offer
+const offer = await pc.createOffer();
+await pc.setLocalDescription(offer);
+
+// 发送到服务器
+const response = await fetch('/api/webrtc/offer', {
+    method: 'POST',
+    body: JSON.stringify({
+        session_id,
+        video_codec: 'h264',
+        offer_sdp: offer.sdp
+    })
+});
+
+const { answer_sdp, ice_candidates } = await response.json();
+
+// 设置 Answer
+await pc.setRemoteDescription({ type: 'answer', sdp: answer_sdp });
+
+// 添加 ICE 候选
+for (const candidate of ice_candidates) {
+    await pc.addIceCandidate({ candidate });
+}
+```
+
+---
+
+## 10. 常见问题
+
+### Q: 连接超时?
+
+1. 检查 STUN/TURN 配置
+2. 检查防火墙设置
+3. 尝试使用 TURN 中继
+
+### Q: 视频卡顿?
+
+1. 降低分辨率/码率
+2. 检查网络带宽
+3. 使用硬件编码
+
+### Q: 音频不同步?
+
+1. 检查时间戳同步
+2. 调整缓冲区大小
+3. 使用 NTP 同步

docs/report/hwcodec/00-architecture.md

@@ -0,0 +1,550 @@
+# hwcodec 技术架构报告
+
+## 1. 项目概述
+
+hwcodec 是一个基于 FFmpeg 的硬件视频编解码库，来源于 RustDesk 项目并针对 One-KVM 进行了定制优化。该库提供跨平台的 GPU 加速视频编解码能力，支持多个 GPU 厂商和多种编码标准。
+
+### 1.1 项目位置
+
+```
+libs/hwcodec/
+├── src/          # Rust 源代码
+├── cpp/          # C++ 源代码
+├── externals/    # 外部依赖 (SDK)
+├── dev/          # 开发工具
+└── examples/     # 示例程序
+```
+
+### 1.2 核心特性
+
+- **多编解码格式支持**: H.264, H.265 (HEVC), VP8, VP9, AV1, MJPEG
+- **硬件加速**: NVENC/NVDEC, AMF, Intel QSV/MFX, VAAPI, RKMPP, V4L2 M2M, VideoToolbox
+- **跨平台**: Windows, Linux, macOS, Android, iOS
+- **低延迟优化**: 专为实时流媒体场景设计
+- **Rust/C++ 混合架构**: Rust 提供安全的上层 API，C++ 实现底层编解码逻辑
+
+## 2. 架构设计
+
+### 2.1 整体架构图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Rust API Layer                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │ ffmpeg_ram  │  │    vram     │  │        mux          │  │
+│  │   module    │  │   module    │  │      module         │  │
+│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
+├─────────┼────────────────┼───────────────────┼──────────────┤
+│         │                │                   │              │
+│         │         FFI Bindings (bindgen)     │              │
+│         ▼                ▼                   ▼              │
+├─────────────────────────────────────────────────────────────┤
+│                     C++ Core Layer                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │ ffmpeg_ram  │  │ ffmpeg_vram │  │    mux.cpp          │  │
+│  │  encode/    │  │  encode/    │  │                     │  │
+│  │  decode     │  │  decode     │  │                     │  │
+│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
+├─────────┼────────────────┼───────────────────┼──────────────┤
+│         │                │                   │              │
+│         └────────────────┴───────────────────┘              │
+│                          │                                  │
+│                          ▼                                  │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │                    FFmpeg Libraries                   │   │
+│  │  libavcodec │ libavutil │ libavformat │ libswscale   │   │
+│  └──────────────────────────────────────────────────────┘   │
+│                          │                                  │
+├──────────────────────────┼──────────────────────────────────┤
+│         Hardware Acceleration Backends                      │
+│  ┌────────┐ ┌─────┐ ┌─────┐ ┌───────┐ ┌───────┐ ┌───────┐  │
+│  │ NVENC  │ │ AMF │ │ MFX │ │ VAAPI │ │ RKMPP │ │V4L2M2M│  │
+│  └────────┘ └─────┘ └─────┘ └───────┘ └───────┘ └───────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 模块职责
+
+| 模块 | 职责 | 关键文件 |
+|------|------|----------|
+| `ffmpeg_ram` | 基于 RAM 的软件/硬件编解码 | `src/ffmpeg_ram/` |
+| `vram` | GPU 显存直接编解码 (Windows) | `src/vram/` |
+| `mux` | 视频混流 (MP4/MKV) | `src/mux.rs` |
+| `common` | 公共定义和 GPU 检测 | `src/common.rs` |
+| `ffmpeg` | FFmpeg 日志和初始化 | `src/ffmpeg.rs` |
+
+## 3. 模块详细分析
+
+### 3.1 库入口 (lib.rs)
+
+```rust
+// libs/hwcodec/src/lib.rs
+pub mod common;
+pub mod ffmpeg;
+pub mod ffmpeg_ram;
+pub mod mux;
+#[cfg(all(windows, feature = "vram"))]
+pub mod vram;
+#[cfg(target_os = "android")]
+pub mod android;
+```
+
+**功能**:
+- 导出所有子模块
+- 提供 C 日志回调函数 `hwcodec_log`
+- 条件编译: `vram` 模块仅在 Windows + vram feature 启用时编译
+
+### 3.2 公共模块 (common.rs)
+
+**核心类型**:
+
+```rust
+pub enum Driver {
+    NV,      // NVIDIA
+    AMF,     // AMD
+    MFX,     // Intel
+    FFMPEG,  // 软件编码
+}
+```
+
+**GPU 检测函数**:
+
+| 平台 | 检测函数 | 检测方式 |
+|------|----------|----------|
+| Linux | `linux_support_nv()` | 加载 CUDA/NVENC 动态库 |
+| Linux | `linux_support_amd()` | 检查 `libamfrt64.so.1` |
+| Linux | `linux_support_intel()` | 检查 `libvpl.so`/`libmfx.so` |
+| Linux | `linux_support_rkmpp()` | 检查 `/dev/mpp_service` |
+| Linux | `linux_support_v4l2m2m()` | 检查 `/dev/video*` 设备 |
+| macOS | `get_video_toolbox_codec_support()` | 调用 VideoToolbox API |
+| Windows | 通过 VRAM 模块检测 | 查询 D3D11 设备 |
+
+### 3.3 FFmpeg RAM 编码模块
+
+#### 3.3.1 Rust 层 (src/ffmpeg_ram/)
+
+**CodecInfo 结构体**:
+
+```rust
+pub struct CodecInfo {
+    pub name: String,           // 编码器名称如 "h264_nvenc"
+    pub mc_name: Option<String>, // MediaCodec 名称 (Android)
+    pub format: DataFormat,      // H264/H265/VP8/VP9/AV1/MJPEG
+    pub priority: i32,           // 优先级 (Best=0, Good=1, Normal=2, Soft=3, Bad=4)
+    pub hwdevice: AVHWDeviceType, // 硬件设备类型
+}
+```
+
+**EncodeContext 结构体**:
+
+```rust
+pub struct EncodeContext {
+    pub name: String,          // 编码器名称
+    pub width: i32,            // 视频宽度
+    pub height: i32,           // 视频高度
+    pub pixfmt: AVPixelFormat, // 像素格式 (NV12/YUV420P)
+    pub align: i32,            // 内存对齐
+    pub fps: i32,              // 帧率
+    pub gop: i32,              // GOP 大小
+    pub rc: RateControl,       // 码率控制模式
+    pub quality: Quality,      // 质量级别
+    pub kbs: i32,              // 目标码率 (kbps)
+    pub q: i32,                // 量化参数
+    pub thread_count: i32,     // 线程数
+}
+```
+
+**Encoder 类**:
+
+```rust
+pub struct Encoder {
+    codec: *mut c_void,           // C++ 编码器指针
+    frames: *mut Vec<EncodeFrame>, // 编码输出帧
+    pub ctx: EncodeContext,
+    pub linesize: Vec<i32>,       // 行大小
+    pub offset: Vec<i32>,         // 平面偏移
+    pub length: i32,              // 总数据长度
+}
+```
+
+**核心方法**:
+
+| 方法 | 功能 |
+|------|------|
+| `Encoder::new()` | 创建编码器实例 |
+| `Encoder::encode()` | 编码一帧 YUV 数据 |
+| `Encoder::set_bitrate()` | 动态调整码率 |
+| `Encoder::request_keyframe()` | 请求下一帧为关键帧 |
+| `Encoder::available_encoders()` | 检测系统可用编码器 |
+
+#### 3.3.2 C++ 层 (cpp/ffmpeg_ram/)
+
+**FFmpegRamEncoder 类** (ffmpeg_ram_encode.cpp:97-420):
+
+```cpp
+class FFmpegRamEncoder {
+    AVCodecContext *c_ = NULL;     // FFmpeg 编码上下文
+    AVFrame *frame_ = NULL;        // 输入帧
+    AVPacket *pkt_ = NULL;         // 编码输出包
+    AVBufferRef *hw_device_ctx_;   // 硬件设备上下文
+    AVFrame *hw_frame_ = NULL;     // 硬件帧
+    bool force_keyframe_ = false;  // 强制关键帧标志
+
+    // 主要方法
+    bool init(int *linesize, int *offset, int *length);
+    int encode(const uint8_t *data, int length, const void *obj, uint64_t ms);
+    int do_encode(AVFrame *frame, const void *obj, int64_t ms);
+    int set_hwframe_ctx();         // 设置硬件帧上下文
+};
+```
+
+**编码流程**:
+
+```
+输入 YUV 数据
+      │
+      ▼
+fill_frame() - 填充 AVFrame 数据指针
+      │
+      ├──▶ (软件编码) 直接使用 frame_
+      │
+      └──▶ (硬件编码) av_hwframe_transfer_data() 传输到 GPU
+                            │
+                            ▼
+                    使用 hw_frame_
+                            │
+                            ▼
+              avcodec_send_frame() - 发送帧到编码器
+                            │
+                            ▼
+              avcodec_receive_packet() - 获取编码数据
+                            │
+                            ▼
+                    callback() - 回调输出
+```
+
+### 3.4 FFmpeg RAM 解码模块
+
+**Decoder 类**:
+
+```rust
+pub struct Decoder {
+    codec: *mut c_void,
+    frames: *mut Vec<DecodeFrame>,
+    pub ctx: DecodeContext,
+}
+
+pub struct DecodeFrame {
+    pub pixfmt: AVPixelFormat,
+    pub width: i32,
+    pub height: i32,
+    pub data: Vec<Vec<u8>>,   // Y, U, V 平面数据
+    pub linesize: Vec<i32>,
+    pub key: bool,
+}
+```
+
+**C++ 实现** (ffmpeg_ram_decode.cpp):
+
+```cpp
+class FFmpegRamDecoder {
+    AVCodecContext *c_ = NULL;
+    AVBufferRef *hw_device_ctx_ = NULL;
+    AVFrame *sw_frame_ = NULL;   // 软件帧 (用于硬件→软件转换)
+    AVFrame *frame_ = NULL;      // 解码输出帧
+    AVPacket *pkt_ = NULL;
+    bool hwaccel_ = true;
+
+    int do_decode(const void *obj);
+};
+```
+
+**解码流程**:
+
+```
+输入编码数据
+      │
+      ▼
+avcodec_send_packet() - 发送数据到解码器
+      │
+      ▼
+avcodec_receive_frame() - 获取解码帧
+      │
+      ├──▶ (软件解码) 直接使用 frame_
+      │
+      └──▶ (硬件解码) av_hwframe_transfer_data()
+                            │
+                            ▼
+                    sw_frame_ (GPU → CPU)
+                            │
+                            ▼
+                    callback() - 回调输出
+```
+
+## 4. 硬件加速支持
+
+### 4.1 支持的硬件加速后端
+
+| 后端 | 厂商 | 平台 | 编码器名称 |
+|------|------|------|-----------|
+| NVENC | NVIDIA | Windows/Linux | h264_nvenc, hevc_nvenc |
+| AMF | AMD | Windows/Linux | h264_amf, hevc_amf |
+| QSV | Intel | Windows | h264_qsv, hevc_qsv |
+| VAAPI | 通用 | Linux | h264_vaapi, hevc_vaapi, vp8_vaapi, vp9_vaapi |
+| RKMPP | Rockchip | Linux | h264_rkmpp, hevc_rkmpp |
+| V4L2 M2M | ARM SoC | Linux | h264_v4l2m2m, hevc_v4l2m2m |
+| VideoToolbox | Apple | macOS/iOS | hevc_videotoolbox |
+| MediaCodec | Google | Android | h264_mediacodec, hevc_mediacodec |
+
+### 4.2 硬件检测逻辑 (Linux)
+
+```cpp
+// libs/hwcodec/cpp/common/platform/linux/linux.cpp
+
+// NVIDIA 检测 - 加载 CUDA 和 NVENC 动态库
+int linux_support_nv() {
+    CudaFunctions *cuda_dl = NULL;
+    NvencFunctions *nvenc_dl = NULL;
+    CuvidFunctions *cvdl = NULL;
+    load_driver(&cuda_dl, &nvenc_dl, &cvdl);
+    // 成功加载则返回 0
+}
+
+// AMD 检测 - 检查 AMF 运行时库
+int linux_support_amd() {
+    void *handle = dlopen("libamfrt64.so.1", RTLD_LAZY);
+    // 成功加载则返回 0
+}
+
+// Intel 检测 - 检查 VPL/MFX 库
+int linux_support_intel() {
+    const char *libs[] = {"libvpl.so", "libmfx.so", ...};
+    // 任一成功加载则返回 0
+}
+
+// Rockchip MPP 检测 - 检查设备节点
+int linux_support_rkmpp() {
+    if (access("/dev/mpp_service", F_OK) == 0) return 0;
+    if (access("/dev/rga", F_OK) == 0) return 0;
+    return -1;
+}
+
+// V4L2 M2M 检测 - 检查视频设备
+int linux_support_v4l2m2m() {
+    const char *devices[] = {"/dev/video10", "/dev/video11", ...};
+    // 任一设备可打开则返回 0
+}
+```
+
+### 4.3 编码器优先级系统
+
+```rust
+pub enum Priority {
+    Best = 0,    // 最高优先级 (硬件加速)
+    Good = 1,    // 良好 (VAAPI, 部分硬件)
+    Normal = 2,  // 普通
+    Soft = 3,    // 软件编码
+    Bad = 4,     // 最低优先级
+}
+```
+
+**优先级分配**:
+
+| 编码器 | 优先级 |
+|--------|--------|
+| h264_nvenc, hevc_nvenc | Best (0) |
+| h264_amf, hevc_amf | Best (0) |
+| h264_qsv, hevc_qsv | Best (0) |
+| h264_rkmpp, hevc_rkmpp | Best (0) |
+| h264_vaapi, hevc_vaapi | Good (1) |
+| h264_v4l2m2m, hevc_v4l2m2m | Good (1) |
+| h264 (x264), hevc (x265) | Soft (3) |
+
+### 4.4 低延迟优化配置
+
+```cpp
+// libs/hwcodec/cpp/common/util.cpp
+
+bool set_lantency_free(void *priv_data, const std::string &name) {
+    // NVENC: 禁用延迟缓冲
+    if (name.find("nvenc") != std::string::npos) {
+        av_opt_set(priv_data, "delay", "0", 0);
+    }
+    // AMF: 设置查询超时
+    if (name.find("amf") != std::string::npos) {
+        av_opt_set(priv_data, "query_timeout", "1000", 0);
+    }
+    // QSV/VAAPI: 设置异步深度为 1
+    if (name.find("qsv") != std::string::npos ||
+        name.find("vaapi") != std::string::npos) {
+        av_opt_set(priv_data, "async_depth", "1", 0);
+    }
+    // VideoToolbox: 实时模式
+    if (name.find("videotoolbox") != std::string::npos) {
+        av_opt_set_int(priv_data, "realtime", 1, 0);
+        av_opt_set_int(priv_data, "prio_speed", 1, 0);
+    }
+    // libvpx: 实时模式
+    if (name.find("libvpx") != std::string::npos) {
+        av_opt_set(priv_data, "deadline", "realtime", 0);
+        av_opt_set_int(priv_data, "cpu-used", 6, 0);
+        av_opt_set_int(priv_data, "lag-in-frames", 0, 0);
+    }
+    return true;
+}
+```
+
+## 5. 混流模块 (Mux)
+
+### 5.1 功能概述
+
+混流模块提供将编码后的视频流写入容器格式 (MP4/MKV) 的功能。
+
+### 5.2 Rust API
+
+```rust
+// libs/hwcodec/src/mux.rs
+
+pub struct MuxContext {
+    pub filename: String,    // 输出文件名
+    pub width: usize,        // 视频宽度
+    pub height: usize,       // 视频高度
+    pub is265: bool,         // 是否为 H.265
+    pub framerate: usize,    // 帧率
+}
+
+pub struct Muxer {
+    inner: *mut c_void,      // C++ Muxer 指针
+    pub ctx: MuxContext,
+    start: Instant,          // 开始时间
+}
+
+impl Muxer {
+    pub fn new(ctx: MuxContext) -> Result<Self, ()>;
+    pub fn write_video(&mut self, data: &[u8], key: bool) -> Result<(), i32>;
+    pub fn write_tail(&mut self) -> Result<(), i32>;
+}
+```
+
+### 5.3 C++ 实现
+
+```cpp
+// libs/hwcodec/cpp/mux/mux.cpp
+
+class Muxer {
+    OutputStream video_st;       // 视频流
+    AVFormatContext *oc = NULL;  // 格式上下文
+    int framerate;
+    int64_t start_ms;           // 起始时间戳
+    int64_t last_pts;           // 上一帧 PTS
+    int got_first;              // 是否收到第一帧
+
+    bool init(const char *filename, int width, int height,
+              int is265, int framerate);
+    int write_video_frame(const uint8_t *data, int len,
+                          int64_t pts_ms, int key);
+};
+```
+
+**写入流程**:
+
+```
+write_video_frame()
+      │
+      ├── 检查是否为关键帧 (第一帧必须是关键帧)
+      │
+      ├── 计算 PTS (相对于 start_ms)
+      │
+      ├── 填充 AVPacket
+      │
+      ├── av_packet_rescale_ts() (ms → stream timebase)
+      │
+      └── av_write_frame() → 写入文件
+```
+
+## 6. 构建系统
+
+### 6.1 Cargo.toml 配置
+
+```toml
+[package]
+name = "hwcodec"
+version = "0.7.1"
+
+[features]
+default = []
+vram = []  # GPU VRAM 直接编解码 (Windows only)
+
+[dependencies]
+log = "0.4"
+serde_derive = "1.0"
+serde = "1.0"
+serde_json = "1.0"
+
+[build-dependencies]
+cc = "1.0"      # C++ 编译
+bindgen = "0.59" # FFI 绑定生成
+```
+
+### 6.2 构建流程 (build.rs)
+
+```
+build.rs
+    │
+    ├── build_common()
+    │   ├── 生成 common_ffi.rs (bindgen)
+    │   ├── 编译平台相关 C++ 代码
+    │   └── 链接系统库 (d3d11, dxgi, stdc++)
+    │
+    ├── ffmpeg::build_ffmpeg()
+    │   ├── 生成 ffmpeg_ffi.rs
+    │   ├── 链接 FFmpeg 库 (VCPKG 或 pkg-config)
+    │   ├── build_ffmpeg_ram()
+    │   │   └── 编译 ffmpeg_ram_encode.cpp, ffmpeg_ram_decode.cpp
+    │   ├── build_ffmpeg_vram() [vram feature]
+    │   │   └── 编译 ffmpeg_vram_encode.cpp, ffmpeg_vram_decode.cpp
+    │   └── build_mux()
+    │       └── 编译 mux.cpp
+    │
+    └── sdk::build_sdk() [Windows + vram feature]
+        ├── build_nv() - NVIDIA SDK
+        ├── build_amf() - AMD AMF
+        └── build_mfx() - Intel MFX
+```
+
+### 6.3 FFmpeg 链接方式
+
+| 方式 | 平台 | 条件 |
+|------|------|------|
+| VCPKG 静态链接 | 跨平台 | 设置 `VCPKG_ROOT` 环境变量 |
+| pkg-config 动态链接 | Linux | 默认方式 |
+
+## 7. 外部依赖
+
+### 7.1 SDK 版本
+
+| SDK | 版本 | 用途 |
+|-----|------|------|
+| nv-codec-headers | n12.1.14.0 | NVIDIA 编码头文件 |
+| Video_Codec_SDK | 12.1.14 | NVIDIA 编解码 SDK |
+| AMF | v1.4.35 | AMD Advanced Media Framework |
+| MediaSDK | 22.5.4 | Intel Media SDK |
+
+### 7.2 FFmpeg 依赖库
+
+```
+libavcodec   - 编解码核心
+libavutil    - 工具函数
+libavformat  - 容器格式
+libswscale   - 图像缩放转换
+```
+
+## 8. 总结
+
+hwcodec 库通过 Rust/C++ 混合架构，在保证内存安全的同时实现了高性能的视频编解码。其核心设计特点包括:
+
+1. **统一的编解码器 API**: 无论使用硬件还是软件编解码，上层 API 保持一致
+2. **自动硬件检测**: 运行时自动检测并选择最优的硬件加速后端
+3. **优先级系统**: 基于质量和性能为不同编码器分配优先级
+4. **低延迟优化**: 针对实时流媒体场景进行了专门优化
+5. **跨平台支持**: 覆盖主流操作系统和 GPU 厂商

docs/report/hwcodec/01-api-reference.md

@@ -0,0 +1,445 @@
+# hwcodec 编解码器 API 详解
+
+## 1. 编码器 API
+
+### 1.1 编码器初始化
+
+#### EncodeContext 参数
+
+```rust
+pub struct EncodeContext {
+    pub name: String,          // 编码器名称
+    pub mc_name: Option<String>, // MediaCodec 名称 (Android)
+    pub width: i32,            // 视频宽度 (必须为偶数)
+    pub height: i32,           // 视频高度 (必须为偶数)
+    pub pixfmt: AVPixelFormat, // 像素格式
+    pub align: i32,            // 内存对齐 (通常为 0 或 32)
+    pub fps: i32,              // 帧率
+    pub gop: i32,              // GOP 大小 (关键帧间隔)
+    pub rc: RateControl,       // 码率控制模式
+    pub quality: Quality,      // 编码质量
+    pub kbs: i32,              // 目标码率 (kbps)
+    pub q: i32,                // 量化参数 (CQ 模式)
+    pub thread_count: i32,     // 编码线程数
+}
+```
+
+#### 参数说明
+
+| 参数 | 类型 | 说明 | 推荐值 |
+|------|------|------|--------|
+| `name` | String | FFmpeg 编码器名称 | 见下表 |
+| `width` | i32 | 视频宽度 | 1920 |
+| `height` | i32 | 视频高度 | 1080 |
+| `pixfmt` | AVPixelFormat | 像素格式 | NV12 / YUV420P |
+| `align` | i32 | 内存对齐 | 0 (自动) |
+| `fps` | i32 | 帧率 | 30 |
+| `gop` | i32 | GOP 大小 | 30 (1秒) |
+| `rc` | RateControl | 码率控制 | CBR / VBR |
+| `quality` | Quality | 质量级别 | Medium |
+| `kbs` | i32 | 码率 (kbps) | 2000-8000 |
+| `thread_count` | i32 | 线程数 | 4 |
+
+#### 编码器名称对照表
+
+| 名称 | 格式 | 加速 | 平台 |
+|------|------|------|------|
+| `h264_nvenc` | H.264 | NVIDIA GPU | Windows/Linux |
+| `hevc_nvenc` | H.265 | NVIDIA GPU | Windows/Linux |
+| `h264_amf` | H.264 | AMD GPU | Windows/Linux |
+| `hevc_amf` | H.265 | AMD GPU | Windows/Linux |
+| `h264_qsv` | H.264 | Intel QSV | Windows |
+| `hevc_qsv` | H.265 | Intel QSV | Windows |
+| `h264_vaapi` | H.264 | VAAPI | Linux |
+| `hevc_vaapi` | H.265 | VAAPI | Linux |
+| `vp8_vaapi` | VP8 | VAAPI | Linux |
+| `vp9_vaapi` | VP9 | VAAPI | Linux |
+| `h264_rkmpp` | H.264 | Rockchip MPP | Linux |
+| `hevc_rkmpp` | H.265 | Rockchip MPP | Linux |
+| `h264_v4l2m2m` | H.264 | V4L2 M2M | Linux |
+| `hevc_v4l2m2m` | H.265 | V4L2 M2M | Linux |
+| `hevc_videotoolbox` | H.265 | VideoToolbox | macOS |
+| `h264` | H.264 | 软件 (x264) | 全平台 |
+| `hevc` | H.265 | 软件 (x265) | 全平台 |
+| `libvpx` | VP8 | 软件 | 全平台 |
+| `libvpx-vp9` | VP9 | 软件 | 全平台 |
+| `mjpeg` | MJPEG | 软件 | 全平台 |
+
+### 1.2 创建编码器
+
+```rust
+use hwcodec::ffmpeg_ram::encode::{Encoder, EncodeContext};
+use hwcodec::ffmpeg::{AVPixelFormat};
+use hwcodec::common::{RateControl, Quality};
+
+let ctx = EncodeContext {
+    name: "h264_vaapi".to_string(),
+    mc_name: None,
+    width: 1920,
+    height: 1080,
+    pixfmt: AVPixelFormat::AV_PIX_FMT_NV12,
+    align: 0,
+    fps: 30,
+    gop: 30,
+    rc: RateControl::RC_CBR,
+    quality: Quality::Quality_Medium,
+    kbs: 4000,
+    q: 0,
+    thread_count: 4,
+};
+
+let encoder = Encoder::new(ctx)?;
+println!("Linesize: {:?}", encoder.linesize);
+println!("Offset: {:?}", encoder.offset);
+println!("Buffer length: {}", encoder.length);
+```
+
+### 1.3 编码帧
+
+```rust
+// 准备 YUV 数据
+let yuv_data: Vec<u8> = prepare_yuv_frame();
+
+// 编码
+let pts_ms: i64 = 0; // 时间戳 (毫秒)
+match encoder.encode(&yuv_data, pts_ms) {
+    Ok(frames) => {
+        for frame in frames.iter() {
+            println!("Encoded: {} bytes, pts={}, key={}",
+                     frame.data.len(), frame.pts, frame.key);
+            // 发送 frame.data
+        }
+    }
+    Err(code) => {
+        eprintln!("Encode error: {}", code);
+    }
+}
+```
+
+### 1.4 动态调整码率
+
+```rust
+// 动态调整到 6000 kbps
+encoder.set_bitrate(6000)?;
+```
+
+### 1.5 请求关键帧
+
+```rust
+// 下一帧强制编码为 IDR 帧
+encoder.request_keyframe();
+```
+
+### 1.6 检测可用编码器
+
+```rust
+use hwcodec::ffmpeg_ram::encode::{Encoder, EncodeContext};
+use hwcodec::ffmpeg_ram::CodecInfo;
+
+let ctx = EncodeContext {
+    name: String::new(),
+    mc_name: None,
+    width: 1920,
+    height: 1080,
+    pixfmt: AVPixelFormat::AV_PIX_FMT_NV12,
+    align: 0,
+    fps: 30,
+    gop: 30,
+    rc: RateControl::RC_DEFAULT,
+    quality: Quality::Quality_Default,
+    kbs: 4000,
+    q: 0,
+    thread_count: 4,
+};
+
+let available_encoders = Encoder::available_encoders(ctx, None);
+for encoder in available_encoders {
+    println!("Available: {} (format: {:?}, priority: {})",
+             encoder.name, encoder.format, encoder.priority);
+}
+```
+
+## 2. 解码器 API
+
+### 2.1 解码器初始化
+
+#### DecodeContext 参数
+
+```rust
+pub struct DecodeContext {
+    pub name: String,           // 解码器名称
+    pub device_type: AVHWDeviceType, // 硬件设备类型
+    pub thread_count: i32,      // 解码线程数
+}
+```
+
+#### 硬件设备类型
+
+| AVHWDeviceType | 说明 |
+|----------------|------|
+| `AV_HWDEVICE_TYPE_NONE` | 软件解码 |
+| `AV_HWDEVICE_TYPE_CUDA` | NVIDIA CUDA |
+| `AV_HWDEVICE_TYPE_VAAPI` | Linux VAAPI |
+| `AV_HWDEVICE_TYPE_D3D11VA` | Windows D3D11 |
+| `AV_HWDEVICE_TYPE_VIDEOTOOLBOX` | macOS VideoToolbox |
+| `AV_HWDEVICE_TYPE_MEDIACODEC` | Android MediaCodec |
+
+### 2.2 创建解码器
+
+```rust
+use hwcodec::ffmpeg_ram::decode::{Decoder, DecodeContext};
+use hwcodec::ffmpeg::AVHWDeviceType;
+
+let ctx = DecodeContext {
+    name: "h264".to_string(),
+    device_type: AVHWDeviceType::AV_HWDEVICE_TYPE_VAAPI,
+    thread_count: 4,
+};
+
+let decoder = Decoder::new(ctx)?;
+```
+
+### 2.3 解码帧
+
+```rust
+// 输入编码数据
+let encoded_packet: Vec<u8> = receive_encoded_data();
+
+match decoder.decode(&encoded_packet) {
+    Ok(frames) => {
+        for frame in frames.iter() {
+            println!("Decoded: {}x{}, format={:?}, key={}",
+                     frame.width, frame.height, frame.pixfmt, frame.key);
+
+            // 访问 YUV 数据
+            let y_plane = &frame.data[0];
+            let u_plane = &frame.data[1];
+            let v_plane = &frame.data[2]; // 仅 YUV420P
+        }
+    }
+    Err(code) => {
+        eprintln!("Decode error: {}", code);
+    }
+}
+```
+
+### 2.4 DecodeFrame 结构体
+
+```rust
+pub struct DecodeFrame {
+    pub pixfmt: AVPixelFormat,  // 输出像素格式
+    pub width: i32,             // 帧宽度
+    pub height: i32,            // 帧高度
+    pub data: Vec<Vec<u8>>,     // 平面数据 [Y, U, V] 或 [Y, UV]
+    pub linesize: Vec<i32>,     // 每个平面的行字节数
+    pub key: bool,              // 是否为关键帧
+}
+```
+
+#### 像素格式与平面布局
+
+| 像素格式 | 平面数 | data[0] | data[1] | data[2] |
+|----------|--------|---------|---------|---------|
+| `YUV420P` | 3 | Y | U | V |
+| `YUVJ420P` | 3 | Y | U | V |
+| `YUV422P` | 3 | Y | U | V |
+| `NV12` | 2 | Y | UV (交错) | - |
+| `NV21` | 2 | Y | VU (交错) | - |
+
+### 2.5 检测可用解码器
+
+```rust
+use hwcodec::ffmpeg_ram::decode::Decoder;
+
+let available_decoders = Decoder::available_decoders();
+for decoder in available_decoders {
+    println!("Available: {} (format: {:?}, hwdevice: {:?})",
+             decoder.name, decoder.format, decoder.hwdevice);
+}
+```
+
+## 3. 码率控制模式
+
+### 3.1 RateControl 枚举
+
+```rust
+pub enum RateControl {
+    RC_DEFAULT,  // 使用编码器默认
+    RC_CBR,      // 恒定码率
+    RC_VBR,      // 可变码率
+    RC_CQ,       // 恒定质量 (需设置 q 参数)
+}
+```
+
+### 3.2 模式说明
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| `RC_CBR` | 码率恒定，质量随场景变化 | 网络带宽受限 |
+| `RC_VBR` | 质量优先，码率波动 | 本地存储 |
+| `RC_CQ` | 恒定质量，码率波动大 | 质量敏感场景 |
+
+### 3.3 各编码器支持情况
+
+| 编码器 | CBR | VBR | CQ |
+|--------|-----|-----|-----|
+| nvenc | ✓ | ✓ | ✓ |
+| amf | ✓ | ✓ (低延迟) | ✗ |
+| qsv | ✓ | ✓ | ✗ |
+| vaapi | ✓ | ✓ | ✗ |
+| mediacodec | ✓ | ✓ | ✓ |
+
+## 4. 质量等级
+
+### 4.1 Quality 枚举
+
+```rust
+pub enum Quality {
+    Quality_Default, // 使用编码器默认
+    Quality_High,    // 高质量 (慢速)
+    Quality_Medium,  // 中等质量 (平衡)
+    Quality_Low,     // 低质量 (快速)
+}
+```
+
+### 4.2 编码器预设映射
+
+| 质量 | nvenc | amf | qsv |
+|------|-------|-----|-----|
+| High | - | quality | veryslow |
+| Medium | p4 | balanced | medium |
+| Low | p1 | speed | veryfast |
+
+## 5. 混流器 API
+
+### 5.1 创建混流器
+
+```rust
+use hwcodec::mux::{Muxer, MuxContext};
+
+let ctx = MuxContext {
+    filename: "/tmp/output.mp4".to_string(),
+    width: 1920,
+    height: 1080,
+    is265: false,  // H.264
+    framerate: 30,
+};
+
+let muxer = Muxer::new(ctx)?;
+```
+
+### 5.2 写入视频帧
+
+```rust
+// 编码后的帧数据
+let encoded_data: Vec<u8> = encoder.encode(...)?;
+let is_keyframe = true;
+
+muxer.write_video(&encoded_data, is_keyframe)?;
+```
+
+### 5.3 完成写入
+
+```rust
+// 写入文件尾
+muxer.write_tail()?;
+// muxer 被 drop 时自动释放资源
+```
+
+## 6. 错误处理
+
+### 6.1 错误码
+
+| 错误码 | 常量 | 说明 |
+|--------|------|------|
+| 0 | `HWCODEC_SUCCESS` | 成功 |
+| -1 | `HWCODEC_ERR_COMMON` | 通用错误 |
+| -2 | `HWCODEC_ERR_HEVC_COULD_NOT_FIND_POC` | HEVC 解码参考帧丢失 |
+
+### 6.2 常见错误处理
+
+```rust
+match encoder.encode(&yuv_data, pts) {
+    Ok(frames) => {
+        // 处理编码帧
+    }
+    Err(-1) => {
+        eprintln!("编码失败，可能是输入数据格式错误");
+    }
+    Err(code) => {
+        eprintln!("未知错误: {}", code);
+    }
+}
+```
+
+## 7. 最佳实践
+
+### 7.1 编码器选择策略
+
+```rust
+fn select_best_encoder(
+    width: i32,
+    height: i32,
+    format: DataFormat
+) -> Option<String> {
+    let ctx = EncodeContext {
+        width,
+        height,
+        pixfmt: AVPixelFormat::AV_PIX_FMT_NV12,
+        // ... 其他参数
+    };
+
+    let encoders = Encoder::available_encoders(ctx, None);
+
+    // 按优先级排序，选择最佳
+    encoders.into_iter()
+        .filter(|e| e.format == format)
+        .min_by_key(|e| e.priority)
+        .map(|e| e.name)
+}
+```
+
+### 7.2 帧内存布局
+
+```rust
+// 获取 NV12 帧布局信息
+let (linesize, offset, length) = ffmpeg_linesize_offset_length(
+    AVPixelFormat::AV_PIX_FMT_NV12,
+    1920,
+    1080,
+    0,  // align
+)?;
+
+// 分配缓冲区
+let mut buffer = vec![0u8; length as usize];
+
+// 填充 Y 平面: buffer[0..offset[0]]
+// 填充 UV 平面: buffer[offset[0]..length]
+```
+
+### 7.3 关键帧控制
+
+```rust
+let mut frame_count = 0;
+
+loop {
+    // 每 30 帧强制一个关键帧
+    if frame_count % 30 == 0 {
+        encoder.request_keyframe();
+    }
+
+    encoder.encode(&yuv_data, pts)?;
+    frame_count += 1;
+}
+```
+
+### 7.4 线程安全
+
+```rust
+// Decoder 实现了 Send + Sync
+unsafe impl Send for Decoder {}
+unsafe impl Sync for Decoder {}
+
+// 可以安全地在多线程间传递
+let decoder = Arc::new(Mutex::new(Decoder::new(ctx)?));
+```

docs/report/hwcodec/02-hardware-acceleration.md

@@ -0,0 +1,615 @@
+# hwcodec 硬件加速详解
+
+## 1. 硬件加速架构
+
+### 1.1 整体流程
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     应用层 (Rust)                           │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ Encoder::available_encoders() → 自动检测可用硬件编码器   ││
+│  └─────────────────────────────────────────────────────────┘│
+└────────────────────────────┬────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   硬件检测层 (C++)                          │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│
+│  │linux_    │ │linux_    │ │linux_    │ │linux_support_    ││
+│  │support_nv│ │support_  │ │support_  │ │rkmpp/v4l2m2m     ││
+│  └────┬─────┘ │amd       │ │intel     │ └─────────┬────────┘│
+│       │       └────┬─────┘ └────┬─────┘           │         │
+└───────┼────────────┼────────────┼─────────────────┼─────────┘
+        │            │            │                 │
+        ▼            ▼            ▼                 ▼
+┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────────┐
+│ CUDA/     │ │ AMF       │ │ VPL/MFX   │ │ 设备节点检测       │
+│ NVENC     │ │ Runtime   │ │ Library   │ │ /dev/mpp_service  │
+│ 动态库    │ │ 动态库    │ │ 动态库    │ │ /dev/video*       │
+└───────────┘ └───────────┘ └───────────┘ └───────────────────┘
+```
+
+### 1.2 编码器测试验证
+
+每个检测到的硬件编码器都会进行实际编码测试：
+
+```rust
+// libs/hwcodec/src/ffmpeg_ram/encode.rs:358-450
+
+// 生成测试用 YUV 数据
+let yuv = Encoder::dummy_yuv(ctx.clone())?;
+
+// 尝试创建编码器并编码测试帧
+match Encoder::new(c) {
+    Ok(mut encoder) => {
+        let start = std::time::Instant::now();
+        match encoder.encode(&yuv, 0) {
+            Ok(frames) => {
+                let elapsed = start.elapsed().as_millis();
+                // 验证: 必须产生 1 帧且为关键帧，且在 1 秒内完成
+                if frames.len() == 1 && frames[0].key == 1
+                   && elapsed < TEST_TIMEOUT_MS {
+                    res.push(codec);
+                }
+            }
+            Err(_) => { /* 编码失败，跳过 */ }
+        }
+    }
+    Err(_) => { /* 创建失败，跳过 */ }
+}
+```
+
+## 2. NVIDIA NVENC/NVDEC
+
+### 2.1 检测机制 (Linux)
+
+```cpp
+// libs/hwcodec/cpp/common/platform/linux/linux.cpp:57-73
+
+int linux_support_nv() {
+    CudaFunctions *cuda_dl = NULL;
+    NvencFunctions *nvenc_dl = NULL;
+    CuvidFunctions *cvdl = NULL;
+
+    // 加载 CUDA 动态库
+    if (cuda_load_functions(&cuda_dl, NULL) < 0)
+        throw "cuda_load_functions failed";
+
+    // 加载 NVENC 动态库
+    if (nvenc_load_functions(&nvenc_dl, NULL) < 0)
+        throw "nvenc_load_functions failed";
+
+    // 加载 CUVID (解码) 动态库
+    if (cuvid_load_functions(&cvdl, NULL) < 0)
+        throw "cuvid_load_functions failed";
+
+    // 全部成功则支持 NVIDIA 硬件加速
+    return 0;
+}
+```
+
+### 2.2 编码配置
+
+```cpp
+// libs/hwcodec/cpp/common/util.cpp
+
+// NVENC 低延迟配置
+if (name.find("nvenc") != std::string::npos) {
+    // 禁用编码延迟
+    av_opt_set(priv_data, "delay", "0", 0);
+}
+
+// GPU 选择
+if (name.find("nvenc") != std::string::npos) {
+    av_opt_set_int(priv_data, "gpu", gpu_index, 0);
+}
+
+// 质量预设
+switch (quality) {
+    case Quality_Medium:
+        av_opt_set(priv_data, "preset", "p4", 0);
+        break;
+    case Quality_Low:
+        av_opt_set(priv_data, "preset", "p1", 0);
+        break;
+}
+
+// 码率控制
+av_opt_set(priv_data, "rc", "cbr", 0);  // 或 "vbr"
+```
+
+### 2.3 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `RUSTDESK_HWCODEC_NVENC_GPU` | 指定使用的 GPU 索引 (-1 = 自动) |
+
+### 2.4 依赖库
+
+- `libcuda.so` - CUDA 运行时
+- `libnvidia-encode.so` - NVENC 编码器
+- `libnvcuvid.so` - NVDEC 解码器
+
+## 3. AMD AMF
+
+### 3.1 检测机制 (Linux)
+
+```cpp
+// libs/hwcodec/cpp/common/platform/linux/linux.cpp:75-91
+
+int linux_support_amd() {
+#if defined(__x86_64__) || defined(__aarch64__)
+    #define AMF_DLL_NAMEA "libamfrt64.so.1"
+#else
+    #define AMF_DLL_NAMEA "libamfrt32.so.1"
+#endif
+
+    void *handle = dlopen(AMF_DLL_NAMEA, RTLD_LAZY);
+    if (!handle) {
+        return -1;  // AMF 不可用
+    }
+    dlclose(handle);
+    return 0;  // AMF 可用
+}
+```
+
+### 3.2 编码配置
+
+```cpp
+// libs/hwcodec/cpp/common/util.cpp
+
+// AMF 低延迟配置
+if (name.find("amf") != std::string::npos) {
+    av_opt_set(priv_data, "query_timeout", "1000", 0);
+}
+
+// 质量预设
+switch (quality) {
+    case Quality_High:
+        av_opt_set(priv_data, "quality", "quality", 0);
+        break;
+    case Quality_Medium:
+        av_opt_set(priv_data, "quality", "balanced", 0);
+        break;
+    case Quality_Low:
+        av_opt_set(priv_data, "quality", "speed", 0);
+        break;
+}
+
+// 码率控制
+av_opt_set(priv_data, "rc", "cbr", 0);      // 恒定码率
+av_opt_set(priv_data, "rc", "vbr_latency", 0);  // 低延迟 VBR
+```
+
+### 3.3 依赖库
+
+- `libamfrt64.so.1` (64位) 或 `libamfrt32.so.1` (32位)
+
+### 3.4 外部 SDK
+
+```
+externals/AMF_v1.4.35/
+├── amf/
+│   ├── public/common/    # 公共代码
+│   │   ├── AMFFactory.cpp
+│   │   ├── Thread.cpp
+│   │   └── TraceAdapter.cpp
+│   └── public/include/   # 头文件
+│       ├── components/   # 组件定义
+│       └── core/         # 核心定义
+```
+
+## 4. Intel QSV/MFX
+
+### 4.1 检测机制 (Linux)
+
+```cpp
+// libs/hwcodec/cpp/common/platform/linux/linux.cpp:93-107
+
+int linux_support_intel() {
+    const char *libs[] = {
+        "libvpl.so",           // oneVPL (新版)
+        "libmfx.so",           // Media SDK
+        "libmfx-gen.so.1.2",   // 新驱动
+        "libmfxhw64.so.1"      // 旧版驱动
+    };
+
+    for (size_t i = 0; i < sizeof(libs) / sizeof(libs[0]); i++) {
+        void *handle = dlopen(libs[i], RTLD_LAZY);
+        if (handle) {
+            dlclose(handle);
+            return 0;  // 找到可用库
+        }
+    }
+    return -1;  // Intel MFX 不可用
+}
+```
+
+### 4.2 编码配置
+
+```cpp
+// libs/hwcodec/cpp/common/util.cpp
+
+// QSV 低延迟配置
+if (name.find("qsv") != std::string::npos) {
+    av_opt_set(priv_data, "async_depth", "1", 0);
+}
+
+// QSV 特殊码率配置
+if (name.find("qsv") != std::string::npos) {
+    c->rc_max_rate = c->bit_rate;
+    c->bit_rate--;  // 实现 CBR 效果
+}
+
+// 质量预设
+switch (quality) {
+    case Quality_High:
+        av_opt_set(priv_data, "preset", "veryslow", 0);
+        break;
+    case Quality_Medium:
+        av_opt_set(priv_data, "preset", "medium", 0);
+        break;
+    case Quality_Low:
+        av_opt_set(priv_data, "preset", "veryfast", 0);
+        break;
+}
+
+// 严格标准兼容性 (用于某些特殊设置)
+c->strict_std_compliance = FF_COMPLIANCE_UNOFFICIAL;
+```
+
+### 4.3 限制
+
+- QSV 不支持 `YUV420P` 像素格式，必须使用 `NV12`
+- 仅在 Windows 平台完全支持
+
+### 4.4 外部 SDK
+
+```
+externals/MediaSDK_22.5.4/
+├── api/
+│   ├── include/           # MFX 头文件
+│   ├── mfx_dispatch/      # MFX 调度器
+│   └── mediasdk_structures/ # 数据结构
+└── samples/sample_common/ # 示例代码
+```
+
+## 5. VAAPI (Linux)
+
+### 5.1 工作原理
+
+VAAPI (Video Acceleration API) 是 Linux 上的通用硬件视频加速接口：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Application                               │
+├─────────────────────────────────────────────────────────────┤
+│                    FFmpeg libavcodec                         │
+├─────────────────────────────────────────────────────────────┤
+│                    VAAPI (libva)                             │
+├──────────────┬──────────────┬──────────────┬────────────────┤
+│ Intel i965   │ Intel iHD    │ AMD radeonsi │ NVIDIA VDPAU   │
+│ (Gen8-)      │ (Gen9+)      │              │ (via wrapper)  │
+├──────────────┴──────────────┴──────────────┴────────────────┤
+│                    Kernel DRM Driver                         │
+├──────────────┬──────────────┬──────────────┬────────────────┤
+│ i915         │ amdgpu       │ nvidia       │ ...            │
+└──────────────┴──────────────┴──────────────┴────────────────┘
+```
+
+### 5.2 编码配置
+
+```cpp
+// libs/hwcodec/cpp/common/util.cpp
+
+// VAAPI 低延迟配置
+if (name.find("vaapi") != std::string::npos) {
+    av_opt_set(priv_data, "async_depth", "1", 0);
+}
+```
+
+### 5.3 硬件上下文初始化
+
+```cpp
+// libs/hwcodec/cpp/ffmpeg_ram/ffmpeg_ram_encode.cpp
+
+// 检测 VAAPI 编码器
+if (name_.find("vaapi") != std::string::npos) {
+    hw_device_type_ = AV_HWDEVICE_TYPE_VAAPI;
+    hw_pixfmt_ = AV_PIX_FMT_VAAPI;
+}
+
+// 创建硬件设备上下文
+ret = av_hwdevice_ctx_create(&hw_device_ctx_, hw_device_type_,
+                             NULL,  // 使用默认设备
+                             NULL, 0);
+
+// 设置硬件帧上下文
+set_hwframe_ctx();
+
+// 分配硬件帧
+hw_frame_ = av_frame_alloc();
+av_hwframe_get_buffer(c_->hw_frames_ctx, hw_frame_, 0);
+```
+
+### 5.4 编码流程
+
+```
+输入 YUV (CPU 内存)
+       │
+       ▼
+av_hwframe_transfer_data(hw_frame_, frame_, 0)  // CPU → GPU
+       │
+       ▼
+avcodec_send_frame(c_, hw_frame_)  // 发送 GPU 帧
+       │
+       ▼
+avcodec_receive_packet(c_, pkt_)   // 获取编码数据
+       │
+       ▼
+编码数据 (CPU 内存)
+```
+
+### 5.5 依赖库
+
+- `libva.so` - VAAPI 核心库
+- `libva-drm.so` - DRM 后端
+- `libva-x11.so` - X11 后端 (可选)
+
+## 6. Rockchip MPP
+
+### 6.1 检测机制
+
+```cpp
+// libs/hwcodec/cpp/common/platform/linux/linux.cpp:122-137
+
+int linux_support_rkmpp() {
+    // 检测 MPP 服务设备
+    if (access("/dev/mpp_service", F_OK) == 0) {
+        return 0;  // MPP 可用
+    }
+    // 备用: 检测 RGA 设备
+    if (access("/dev/rga", F_OK) == 0) {
+        return 0;  // MPP 可能可用
+    }
+    return -1;  // MPP 不可用
+}
+```
+
+### 6.2 支持的编码器
+
+| 编码器 | 优先级 | 说明 |
+|--------|--------|------|
+| `h264_rkmpp` | Best (0) | H.264 硬件编码 |
+| `hevc_rkmpp` | Best (0) | H.265 硬件编码 |
+
+### 6.3 适用设备
+
+- Rockchip RK3328 (Onecloud, Chainedbox)
+- Rockchip RK3399/RK3588 系列
+- 其他 Rockchip SoC
+
+## 7. V4L2 M2M
+
+### 7.1 检测机制
+
+```cpp
+// libs/hwcodec/cpp/common/platform/linux/linux.cpp:139-163
+
+int linux_support_v4l2m2m() {
+    const char *m2m_devices[] = {
+        "/dev/video10",  // 常见 M2M 编码设备
+        "/dev/video11",  // 常见 M2M 解码设备
+        "/dev/video0",   // 某些 SoC 使用
+    };
+
+    for (size_t i = 0; i < sizeof(m2m_devices) / sizeof(m2m_devices[0]); i++) {
+        if (access(m2m_devices[i], F_OK) == 0) {
+            int fd = open(m2m_devices[i], O_RDWR | O_NONBLOCK);
+            if (fd >= 0) {
+                close(fd);
+                return 0;  // V4L2 M2M 可用
+            }
+        }
+    }
+    return -1;
+}
+```
+
+### 7.2 支持的编码器
+
+| 编码器 | 优先级 | 说明 |
+|--------|--------|------|
+| `h264_v4l2m2m` | Good (1) | H.264 V4L2 编码 |
+| `hevc_v4l2m2m` | Good (1) | H.265 V4L2 编码 |
+
+### 7.3 适用设备
+
+- 通用 ARM SoC (Allwinner, Amlogic 等)
+- 支持 V4L2 M2M API 的设备
+
+## 8. Apple VideoToolbox
+
+### 8.1 检测机制 (macOS)
+
+```rust
+// libs/hwcodec/src/common.rs:57-87
+
+#[cfg(target_os = "macos")]
+pub(crate) fn get_video_toolbox_codec_support() -> (bool, bool, bool, bool) {
+    extern "C" {
+        fn checkVideoToolboxSupport(
+            h264_encode: *mut i32,
+            h265_encode: *mut i32,
+            h264_decode: *mut i32,
+            h265_decode: *mut i32,
+        ) -> c_void;
+    }
+
+    let mut h264_encode = 0;
+    let mut h265_encode = 0;
+    let mut h264_decode = 0;
+    let mut h265_decode = 0;
+
+    unsafe {
+        checkVideoToolboxSupport(&mut h264_encode, &mut h265_encode,
+                                 &mut h264_decode, &mut h265_decode);
+    }
+
+    (h264_encode == 1, h265_encode == 1,
+     h264_decode == 1, h265_decode == 1)
+}
+```
+
+### 8.2 编码配置
+
+```cpp
+// libs/hwcodec/cpp/common/util.cpp
+
+// VideoToolbox 低延迟配置
+if (name.find("videotoolbox") != std::string::npos) {
+    av_opt_set_int(priv_data, "realtime", 1, 0);
+    av_opt_set_int(priv_data, "prio_speed", 1, 0);
+}
+
+// 强制硬件编码
+if (name.find("videotoolbox") != std::string::npos) {
+    av_opt_set_int(priv_data, "allow_sw", 0, 0);
+}
+```
+
+### 8.3 限制
+
+- H.264 编码不稳定，已禁用
+- 仅支持 H.265 编码
+- 完全支持 H.264/H.265 解码
+
+### 8.4 依赖框架
+
+```
+CoreFoundation
+CoreVideo
+CoreMedia
+VideoToolbox
+AVFoundation
+```
+
+## 9. 硬件加速优先级
+
+### 9.1 优先级定义
+
+```rust
+pub enum Priority {
+    Best = 0,    // 专用硬件编码器
+    Good = 1,    // 通用硬件加速
+    Normal = 2,  // 基本硬件支持
+    Soft = 3,    // 软件编码
+    Bad = 4,     // 最低优先级
+}
+```
+
+### 9.2 各编码器优先级
+
+| 优先级 | 编码器 |
+|--------|--------|
+| Best (0) | nvenc, amf, qsv, rkmpp |
+| Good (1) | vaapi, v4l2m2m |
+| Soft (3) | x264, x265, libvpx |
+
+### 9.3 选择策略
+
+```rust
+// libs/hwcodec/src/ffmpeg_ram/mod.rs:49-117
+
+pub fn prioritized(coders: Vec<CodecInfo>) -> CodecInfos {
+    // 对于每种格式，选择优先级最高的编码器
+    for coder in coders {
+        match coder.format {
+            DataFormat::H264 => {
+                if h264.is_none() || h264.priority > coder.priority {
+                    h264 = Some(coder);
+                }
+            }
+            // ... 其他格式类似
+        }
+    }
+}
+```
+
+## 10. 故障排除
+
+### 10.1 NVIDIA
+
+```bash
+# 检查 NVIDIA 驱动
+nvidia-smi
+
+# 检查 NVENC 支持
+ls /dev/nvidia*
+
+# 检查 CUDA 库
+ldconfig -p | grep cuda
+ldconfig -p | grep nvidia-encode
+```
+
+### 10.2 AMD
+
+```bash
+# 检查 AMD 驱动
+lspci | grep AMD
+
+# 检查 AMF 库
+ldconfig -p | grep amf
+```
+
+### 10.3 Intel
+
+```bash
+# 检查 Intel 驱动
+vainfo
+
+# 检查 MFX 库
+ldconfig -p | grep mfx
+ldconfig -p | grep vpl
+```
+
+### 10.4 VAAPI
+
+```bash
+# 安装 vainfo
+sudo apt install vainfo
+
+# 检查 VAAPI 支持
+vainfo
+
+# 输出示例:
+# libva info: VA-API version 1.14.0
+# libva info: Trying to open /usr/lib/x86_64-linux-gnu/dri/iHD_drv_video.so
+# vainfo: Driver version: Intel iHD driver for Intel(R) Gen Graphics
+# vainfo: Supported profile and entrypoints
+#       VAProfileH264Main               : VAEntrypointVLD
+#       VAProfileH264Main               : VAEntrypointEncSlice
+#       ...
+```
+
+### 10.5 Rockchip MPP
+
+```bash
+# 检查 MPP 设备
+ls -la /dev/mpp_service
+ls -la /dev/rga
+
+# 检查 MPP 库
+ldconfig -p | grep rockchip_mpp
+```
+
+### 10.6 V4L2 M2M
+
+```bash
+# 列出 V4L2 设备
+v4l2-ctl --list-devices
+
+# 检查设备能力
+v4l2-ctl -d /dev/video10 --all
+```

docs/report/hwcodec/03-build-integration.md

@@ -0,0 +1,539 @@
+# hwcodec 构建系统与集成指南
+
+## 1. 项目结构
+
+```
+libs/hwcodec/
+├── Cargo.toml           # 包配置
+├── Cargo.lock           # 依赖锁定
+├── build.rs             # 构建脚本
+├── src/                 # Rust 源码
+│   ├── lib.rs           # 库入口
+│   ├── common.rs        # 公共定义
+│   ├── ffmpeg.rs        # FFmpeg 集成
+│   ├── mux.rs           # 混流器
+│   ├── android.rs       # Android 支持
+│   ├── ffmpeg_ram/      # RAM 编解码
+│   │   ├── mod.rs
+│   │   ├── encode.rs
+│   │   └── decode.rs
+│   ├── vram/            # GPU 编解码 (Windows)
+│   │   ├── mod.rs
+│   │   ├── encode.rs
+│   │   ├── decode.rs
+│   │   └── ...
+│   └── res/             # 测试资源
+│       ├── 720p.h264
+│       └── 720p.h265
+├── cpp/                 # C++ 源码
+│   ├── common/          # 公共代码
+│   ├── ffmpeg_ram/      # FFmpeg RAM 实现
+│   ├── ffmpeg_vram/     # FFmpeg VRAM 实现
+│   ├── nv/              # NVIDIA 实现
+│   ├── amf/             # AMD 实现
+│   ├── mfx/             # Intel 实现
+│   ├── mux/             # 混流实现
+│   └── yuv/             # YUV 处理
+├── externals/           # 外部 SDK (Git 子模块)
+│   ├── nv-codec-headers_n12.1.14.0/
+│   ├── Video_Codec_SDK_12.1.14/
+│   ├── AMF_v1.4.35/
+│   └── MediaSDK_22.5.4/
+├── dev/                 # 开发工具
+│   ├── capture/         # 捕获工具
+│   ├── render/          # 渲染工具
+│   └── tool/            # 通用工具
+└── examples/            # 示例程序
+```
+
+## 2. Cargo 配置
+
+### 2.1 Cargo.toml
+
+```toml
+[package]
+name = "hwcodec"
+version = "0.7.1"
+edition = "2021"
+
+[features]
+default = []
+vram = []  # GPU VRAM 直接编解码 (仅 Windows)
+
+[dependencies]
+log = "0.4"              # 日志
+serde_derive = "1.0"     # 序列化派生宏
+serde = "1.0"            # 序列化
+serde_json = "1.0"       # JSON 序列化
+
+[build-dependencies]
+cc = "1.0"               # C++ 编译
+bindgen = "0.59"         # FFI 绑定生成
+
+[dev-dependencies]
+env_logger = "0.10"      # 日志输出
+rand = "0.8"             # 随机数
+```
+
+### 2.2 Feature 说明
+
+| Feature | 说明 | 平台 |
+|---------|------|------|
+| `default` | 基础功能 | 全平台 |
+| `vram` | GPU VRAM 直接编解码 | 仅 Windows |
+
+### 2.3 使用方式
+
+```toml
+# 基础使用
+[dependencies]
+hwcodec = { path = "libs/hwcodec" }
+
+# 启用 VRAM 功能 (Windows)
+[dependencies]
+hwcodec = { path = "libs/hwcodec", features = ["vram"] }
+```
+
+## 3. 构建脚本详解 (build.rs)
+
+### 3.1 主入口
+
+```rust
+fn main() {
+    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let mut builder = Build::new();
+
+    // 1. 构建公共模块
+    build_common(&mut builder);
+
+    // 2. 构建 FFmpeg 相关模块
+    ffmpeg::build_ffmpeg(&mut builder);
+
+    // 3. 构建 SDK 模块 (Windows + vram feature)
+    #[cfg(all(windows, feature = "vram"))]
+    sdk::build_sdk(&mut builder);
+
+    // 4. 编译生成静态库
+    builder.static_crt(true).compile("hwcodec");
+}
+```
+
+### 3.2 公共模块构建
+
+```rust
+fn build_common(builder: &mut Build) {
+    let common_dir = manifest_dir.join("cpp").join("common");
+
+    // 生成 FFI 绑定
+    bindgen::builder()
+        .header(common_dir.join("common.h"))
+        .header(common_dir.join("callback.h"))
+        .rustified_enum("*")
+        .generate()
+        .write_to_file(OUT_DIR.join("common_ffi.rs"));
+
+    // 平台相关代码
+    #[cfg(windows)]
+    builder.file(common_dir.join("platform/win/win.cpp"));
+
+    #[cfg(target_os = "linux")]
+    builder.file(common_dir.join("platform/linux/linux.cpp"));
+
+    #[cfg(target_os = "macos")]
+    builder.file(common_dir.join("platform/mac/mac.mm"));
+
+    // 工具代码
+    builder.files([
+        common_dir.join("log.cpp"),
+        common_dir.join("util.cpp"),
+    ]);
+}
+```
+
+### 3.3 FFmpeg 模块构建
+
+```rust
+mod ffmpeg {
+    pub fn build_ffmpeg(builder: &mut Build) {
+        // 生成 FFmpeg FFI 绑定
+        ffmpeg_ffi();
+
+        // 链接 FFmpeg 库
+        if let Ok(vcpkg_root) = std::env::var("VCPKG_ROOT") {
+            link_vcpkg(builder, vcpkg_root.into());
+        } else {
+            link_system_ffmpeg(builder);  // pkg-config
+        }
+
+        // 链接系统库
+        link_os();
+
+        // 构建子模块
+        build_ffmpeg_ram(builder);
+        #[cfg(feature = "vram")]
+        build_ffmpeg_vram(builder);
+        build_mux(builder);
+    }
+}
+```
+
+### 3.4 FFmpeg 链接方式
+
+#### VCPKG (跨平台静态链接)
+
+```rust
+fn link_vcpkg(builder: &mut Build, path: PathBuf) -> PathBuf {
+    // 目标平台识别
+    let target = match (target_os, target_arch) {
+        ("windows", "x86_64") => "x64-windows-static",
+        ("macos", "x86_64") => "x64-osx",
+        ("macos", "aarch64") => "arm64-osx",
+        ("linux", arch) => format!("{}-linux", arch),
+        _ => panic!("unsupported platform"),
+    };
+
+    let lib_path = path.join("installed").join(target).join("lib");
+
+    // 链接 FFmpeg 静态库
+    println!("cargo:rustc-link-search=native={}", lib_path);
+    ["avcodec", "avutil", "avformat"].iter()
+        .for_each(|lib| println!("cargo:rustc-link-lib=static={}", lib));
+}
+```
+
+#### pkg-config (Linux 动态链接)
+
+```rust
+fn link_system_ffmpeg(builder: &mut Build) {
+    let libs = ["libavcodec", "libavutil", "libavformat", "libswscale"];
+
+    for lib in &libs {
+        // 获取编译标志
+        let cflags = Command::new("pkg-config")
+            .args(["--cflags", lib])
+            .output()?;
+
+        // 获取链接标志
+        let libs = Command::new("pkg-config")
+            .args(["--libs", lib])
+            .output()?;
+
+        // 解析并应用
+        for flag in libs.split_whitespace() {
+            if flag.starts_with("-L") {
+                println!("cargo:rustc-link-search=native={}", &flag[2..]);
+            } else if flag.starts_with("-l") {
+                println!("cargo:rustc-link-lib={}", &flag[2..]);
+            }
+        }
+    }
+}
+```
+
+### 3.5 系统库链接
+
+```rust
+fn link_os() {
+    let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap();
+
+    let libs: Vec<&str> = match target_os.as_str() {
+        "windows" => vec!["User32", "bcrypt", "ole32", "advapi32"],
+        "linux" => vec!["drm", "X11", "stdc++", "z"],
+        "macos" | "ios" => vec!["c++", "m"],
+        "android" => vec!["z", "m", "android", "atomic", "mediandk"],
+        _ => panic!("unsupported os"),
+    };
+
+    for lib in libs {
+        println!("cargo:rustc-link-lib={}", lib);
+    }
+
+    // macOS 框架
+    if target_os == "macos" || target_os == "ios" {
+        for framework in ["CoreFoundation", "CoreVideo", "CoreMedia",
+                         "VideoToolbox", "AVFoundation"] {
+            println!("cargo:rustc-link-lib=framework={}", framework);
+        }
+    }
+}
+```
+
+### 3.6 SDK 模块构建 (Windows)
+
+```rust
+#[cfg(all(windows, feature = "vram"))]
+mod sdk {
+    pub fn build_sdk(builder: &mut Build) {
+        build_amf(builder);  // AMD AMF
+        build_nv(builder);   // NVIDIA
+        build_mfx(builder);  // Intel MFX
+    }
+
+    fn build_nv(builder: &mut Build) {
+        let sdk_path = externals_dir.join("Video_Codec_SDK_12.1.14");
+
+        // 包含 SDK 头文件
+        builder.includes([
+            sdk_path.join("Interface"),
+            sdk_path.join("Samples/Utils"),
+            sdk_path.join("Samples/NvCodec"),
+        ]);
+
+        // 编译 SDK 源文件
+        builder.file(sdk_path.join("Samples/NvCodec/NvEncoder/NvEncoder.cpp"));
+        builder.file(sdk_path.join("Samples/NvCodec/NvEncoder/NvEncoderD3D11.cpp"));
+        builder.file(sdk_path.join("Samples/NvCodec/NvDecoder/NvDecoder.cpp"));
+
+        // 编译封装代码
+        builder.files([
+            nv_dir.join("nv_encode.cpp"),
+            nv_dir.join("nv_decode.cpp"),
+        ]);
+    }
+}
+```
+
+## 4. FFI 绑定生成
+
+### 4.1 bindgen 配置
+
+```rust
+bindgen::builder()
+    .header("path/to/header.h")
+    .rustified_enum("*")           // 生成 Rust 枚举
+    .parse_callbacks(Box::new(Callbacks))  // 自定义回调
+    .generate()
+    .write_to_file(OUT_DIR.join("ffi.rs"));
+```
+
+### 4.2 自定义派生
+
+```rust
+#[derive(Debug)]
+struct CommonCallbacks;
+
+impl bindgen::callbacks::ParseCallbacks for CommonCallbacks {
+    fn add_derives(&self, name: &str) -> Vec<String> {
+        // 为特定类型添加序列化支持
+        match name {
+            "DataFormat" | "SurfaceFormat" | "API" => {
+                vec!["Serialize".to_string(), "Deserialize".to_string()]
+            }
+            _ => vec![],
+        }
+    }
+}
+```
+
+### 4.3 生成的文件
+
+| 文件 | 来源 | 内容 |
+|------|------|------|
+| `common_ffi.rs` | `common.h`, `callback.h` | 枚举、常量、回调类型 |
+| `ffmpeg_ffi.rs` | `ffmpeg_ffi.h` | FFmpeg 日志级别、函数 |
+| `ffmpeg_ram_ffi.rs` | `ffmpeg_ram_ffi.h` | 编解码器函数 |
+| `mux_ffi.rs` | `mux_ffi.h` | 混流器函数 |
+
+## 5. 外部依赖管理
+
+### 5.1 Git 子模块
+
+```bash
+# 初始化子模块
+git submodule update --init --recursive
+
+# 更新子模块
+git submodule update --remote externals
+```
+
+### 5.2 子模块配置 (.gitmodules)
+
+```
+[submodule "externals"]
+    path = libs/hwcodec/externals
+    url = https://github.com/rustdesk-org/externals.git
+```
+
+### 5.3 依赖版本
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| nv-codec-headers | n12.1.14.0 | NVIDIA FFmpeg 编码头 |
+| Video_Codec_SDK | 12.1.14 | NVIDIA 编解码 SDK |
+| AMF | v1.4.35 | AMD Advanced Media Framework |
+| MediaSDK | 22.5.4 | Intel Media SDK |
+
+## 6. 平台构建指南
+
+### 6.1 Linux 构建
+
+```bash
+# 安装 FFmpeg 开发库
+sudo apt install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev
+
+# 安装其他依赖
+sudo apt install libdrm-dev libx11-dev pkg-config
+
+# 构建
+cargo build --release -p hwcodec
+```
+
+### 6.2 Windows 构建 (VCPKG)
+
+```powershell
+# 安装 VCPKG
+git clone https://github.com/microsoft/vcpkg
+cd vcpkg
+./bootstrap-vcpkg.bat
+
+# 安装 FFmpeg
+./vcpkg install ffmpeg:x64-windows-static
+
+# 设置环境变量
+$env:VCPKG_ROOT = "C:\path\to\vcpkg"
+
+# 构建
+cargo build --release -p hwcodec --features vram
+```
+
+### 6.3 macOS 构建
+
+```bash
+# 安装 FFmpeg (Homebrew)
+brew install ffmpeg pkg-config
+
+# 或使用 VCPKG
+export VCPKG_ROOT=/path/to/vcpkg
+vcpkg install ffmpeg:arm64-osx  # Apple Silicon
+vcpkg install ffmpeg:x64-osx    # Intel
+
+# 构建
+cargo build --release -p hwcodec
+```
+
+### 6.4 交叉编译
+
+```bash
+# 安装 cross
+cargo install cross --git https://github.com/cross-rs/cross
+
+# ARM64 Linux
+cross build --release -p hwcodec --target aarch64-unknown-linux-gnu
+
+# ARMv7 Linux
+cross build --release -p hwcodec --target armv7-unknown-linux-gnueabihf
+```
+
+## 7. 集成到 One-KVM
+
+### 7.1 依赖配置
+
+```toml
+# Cargo.toml
+[dependencies]
+hwcodec = { path = "libs/hwcodec" }
+```
+
+### 7.2 使用示例
+
+```rust
+use hwcodec::ffmpeg_ram::encode::{Encoder, EncodeContext};
+use hwcodec::ffmpeg_ram::decode::{Decoder, DecodeContext};
+use hwcodec::ffmpeg::AVPixelFormat;
+
+// 检测可用编码器
+let encoders = Encoder::available_encoders(ctx, None);
+
+// 创建编码器
+let encoder = Encoder::new(EncodeContext {
+    name: "h264_vaapi".to_string(),
+    width: 1920,
+    height: 1080,
+    pixfmt: AVPixelFormat::AV_PIX_FMT_NV12,
+    fps: 30,
+    gop: 30,
+    kbs: 4000,
+    // ...
+})?;
+
+// 编码
+let frames = encoder.encode(&yuv_data, pts_ms)?;
+```
+
+### 7.3 日志集成
+
+```rust
+// hwcodec 使用 log crate，与 One-KVM 日志系统兼容
+use log::{debug, info, warn, error};
+
+// C++ 层日志通过回调传递
+#[no_mangle]
+pub extern "C" fn hwcodec_log(level: i32, message: *const c_char) {
+    match level {
+        0 => error!("{}", message),
+        1 => warn!("{}", message),
+        2 => info!("{}", message),
+        3 => debug!("{}", message),
+        4 => trace!("{}", message),
+        _ => {}
+    }
+}
+```
+
+## 8. 故障排除
+
+### 8.1 编译错误
+
+**FFmpeg 未找到**:
+```
+error: pkg-config failed for libavcodec
+```
+解决: 安装 FFmpeg 开发库
+```bash
+sudo apt install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev
+```
+
+**bindgen 错误**:
+```
+error: failed to run custom build command for `hwcodec`
+```
+解决: 安装 clang
+```bash
+sudo apt install clang libclang-dev
+```
+
+### 8.2 链接错误
+
+**符号未定义**:
+```
+undefined reference to `av_log_set_level'
+```
+解决: 检查 FFmpeg 库链接顺序，确保 pkg-config 正确配置
+
+**动态库未找到**:
+```
+error while loading shared libraries: libavcodec.so.59
+```
+解决:
+```bash
+sudo ldconfig
+# 或设置 LD_LIBRARY_PATH
+export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
+```
+
+### 8.3 运行时错误
+
+**硬件编码器不可用**:
+```
+Encoder h264_vaapi test failed
+```
+检查:
+1. 驱动是否正确安装: `vainfo`
+2. 权限是否足够: `ls -la /dev/dri/`
+3. 用户是否在 video 组: `groups`
+
+**解码失败**:
+```
+avcodec_receive_frame failed, ret = -11
+```
+解决: 这通常表示需要更多输入数据 (EAGAIN)，是正常行为

docs/report/rustdesk/00-overview.md

@@ -0,0 +1,69 @@
+# RustDesk 通信协议技术报告
+
+## 概述
+
+本报告详细分析 RustDesk 远程桌面软件的客户端与服务器之间的通信协议，包括 Rendezvous 服务器（hbbs）、Relay 服务器（hbbr）以及客户端之间的 P2P 连接机制。
+
+## 文档结构
+
+| 文档 | 内容 |
+|------|------|
+| [01-architecture.md](01-architecture.md) | 整体架构设计 |
+| [02-rendezvous-protocol.md](02-rendezvous-protocol.md) | Rendezvous 服务器协议 |
+| [03-relay-protocol.md](03-relay-protocol.md) | Relay 服务器协议 |
+| [04-p2p-connection.md](04-p2p-connection.md) | P2P 连接流程 |
+| [05-message-format.md](05-message-format.md) | 消息格式定义 |
+| [06-encryption.md](06-encryption.md) | 加密机制 |
+| [07-nat-traversal.md](07-nat-traversal.md) | NAT 穿透技术 |
+| [08-onekvm-comparison.md](08-onekvm-comparison.md) | **One-KVM 实现对比分析** |
+
+## 核心组件
+
+### 1. Rendezvous Server (hbbs)
+- **功能**: ID 注册、Peer 发现、NAT 类型检测、连接协调
+- **端口**: 21116 (TCP/UDP), 21115 (NAT 测试), 21118 (WebSocket)
+- **源文件**: `rustdesk-server/src/rendezvous_server.rs`
+
+### 2. Relay Server (hbbr)
+- **功能**: 当 P2P 连接失败时提供数据中转
+- **端口**: 21117 (TCP), 21119 (WebSocket)
+- **源文件**: `rustdesk-server/src/relay_server.rs`
+
+### 3. 客户端 (RustDesk)
+- **功能**: 远程桌面控制、文件传输、屏幕共享
+- **核心模块**:
+  - `rendezvous_mediator.rs` - 与 Rendezvous 服务器通信
+  - `client.rs` - 客户端连接逻辑
+  - `server/connection.rs` - 被控端连接处理
+
+## 协议栈
+
+```
+┌─────────────────────────────────────────┐
+│            Application Layer            │
+│   (Video/Audio/Keyboard/Mouse/File)     │
+├─────────────────────────────────────────┤
+│            Message Layer                │
+│         (Protobuf Messages)             │
+├─────────────────────────────────────────┤
+│           Security Layer                │
+│    (Sodium: X25519 + ChaCha20)          │
+├─────────────────────────────────────────┤
+│           Transport Layer               │
+│   (TCP/UDP/WebSocket/KCP)               │
+└─────────────────────────────────────────┘
+```
+
+## 关键技术特点
+
+1. **混合连接模式**: 优先尝试 P2P 直连，失败后自动切换到 Relay 中转
+2. **多协议支持**: TCP、UDP、WebSocket、KCP
+3. **端到端加密**: 使用 libsodium 实现的 X25519 密钥交换和 ChaCha20-Poly1305 对称加密
+4. **NAT 穿透**: 支持 UDP 打洞和 TCP 打洞技术
+5. **服务器签名**: 可选的服务器公钥签名验证，防止中间人攻击
+
+## 版本信息
+
+- 分析基于 RustDesk 最新版本源码
+- Protocol Buffer 版本: proto3
+- 加密库: libsodium (sodiumoxide)

docs/report/rustdesk/01-architecture.md

@@ -0,0 +1,218 @@
+# RustDesk 架构设计
+
+## 系统架构图
+
+```
+                                    ┌──────────────────────┐
+                                    │   Rendezvous Server  │
+                                    │       (hbbs)         │
+                                    │  Port: 21116         │
+                                    └──────────┬───────────┘
+                                               │
+                    ┌──────────────────────────┼──────────────────────────┐
+                    │                          │                          │
+                    ▼                          ▼                          ▼
+            ┌───────────────┐          ┌───────────────┐          ┌───────────────┐
+            │   Client A    │          │   Client B    │          │   Client C    │
+            │   (控制端)     │          │   (被控端)     │          │   (被控端)     │
+            └───────┬───────┘          └───────┬───────┘          └───────────────┘
+                    │                          │
+                    │    P2P Connection        │
+                    │◄────────────────────────►│
+                    │                          │
+                    │   (如果 P2P 失败)         │
+                    │          │               │
+                    │          ▼               │
+                    │  ┌───────────────┐       │
+                    └─►│  Relay Server │◄──────┘
+                       │    (hbbr)     │
+                       │  Port: 21117  │
+                       └───────────────┘
+```
+
+## 服务器组件详解
+
+### Rendezvous Server (hbbs)
+
+**监听端口：**
+| 端口 | 协议 | 用途 |
+|------|------|------|
+| 21116 | TCP | 主要通信端口，处理 punch hole 请求 |
+| 21116 | UDP | Peer 注册、NAT 类型检测 |
+| 21115 | TCP | NAT 测试专用端口 |
+| 21118 | WebSocket | Web 客户端支持 |
+
+**核心数据结构：**
+
+```rust
+// rustdesk-server/src/rendezvous_server.rs:64-83
+pub struct RendezvousServer {
+    tcp_punch: Arc<Mutex<HashMap<SocketAddr, Sink>>>,  // TCP punch hole 连接
+    pm: PeerMap,                                        // Peer 映射表
+    tx: Sender,                                         // 消息发送通道
+    relay_servers: Arc<RelayServers>,                  // 可用 Relay 服务器列表
+    relay_servers0: Arc<RelayServers>,                 // 原始 Relay 服务器列表
+    rendezvous_servers: Arc<Vec<String>>,              // Rendezvous 服务器列表
+    inner: Arc<Inner>,                                  // 内部配置
+}
+
+struct Inner {
+    serial: i32,                      // 配置序列号
+    version: String,                  // 软件版本
+    software_url: String,             // 软件更新 URL
+    mask: Option<Ipv4Network>,        // LAN 掩码
+    local_ip: String,                 // 本地 IP
+    sk: Option<sign::SecretKey>,      // 服务器签名密钥
+}
+```
+
+**Peer 数据结构：**
+
+```rust
+// rustdesk-server/src/peer.rs:32-42
+pub struct Peer {
+    pub socket_addr: SocketAddr,   // 最后注册的地址
+    pub last_reg_time: Instant,    // 最后注册时间
+    pub guid: Vec<u8>,             // 数据库 GUID
+    pub uuid: Bytes,               // 设备 UUID
+    pub pk: Bytes,                 // 公钥
+    pub info: PeerInfo,            // Peer 信息
+    pub reg_pk: (u32, Instant),    // 注册频率限制
+}
+```
+
+### Relay Server (hbbr)
+
+**监听端口：**
+| 端口 | 协议 | 用途 |
+|------|------|------|
+| 21117 | TCP | 主要中转端口 |
+| 21119 | WebSocket | Web 客户端支持 |
+
+**核心特性：**
+
+```rust
+// rustdesk-server/src/relay_server.rs:40-44
+static DOWNGRADE_THRESHOLD_100: AtomicUsize = AtomicUsize::new(66);        // 降级阈值
+static DOWNGRADE_START_CHECK: AtomicUsize = AtomicUsize::new(1_800_000);   // 检测开始时间(ms)
+static LIMIT_SPEED: AtomicUsize = AtomicUsize::new(32 * 1024 * 1024);      // 限速(bit/s)
+static TOTAL_BANDWIDTH: AtomicUsize = AtomicUsize::new(1024 * 1024 * 1024);// 总带宽
+static SINGLE_BANDWIDTH: AtomicUsize = AtomicUsize::new(128 * 1024 * 1024);// 单连接带宽
+```
+
+## 客户端架构
+
+### 核心模块
+
+```
+rustdesk/src/
+├── rendezvous_mediator.rs  # Rendezvous 服务器通信
+├── client.rs               # 控制端核心逻辑
+├── server/
+│   ├── mod.rs              # 被控端服务
+│   ├── connection.rs       # 连接处理
+│   ├── video_service.rs    # 视频服务
+│   ├── audio_service.rs    # 音频服务
+│   └── input_service.rs    # 输入服务
+├── common.rs               # 通用函数（加密、解密）
+└── platform/               # 平台特定代码
+```
+
+### RendezvousMediator
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:44-50
+pub struct RendezvousMediator {
+    addr: TargetAddr<'static>,   // 服务器地址
+    host: String,                // 服务器主机名
+    host_prefix: String,         // 主机前缀
+    keep_alive: i32,             // 保活间隔
+}
+```
+
+**两种连接模式：**
+
+1. **UDP 模式** (默认):
+   - 用于 Peer 注册和心跳
+   - 更低延迟
+   - 可能被某些防火墙阻止
+
+2. **TCP 模式**:
+   - 用于代理环境
+   - WebSocket 模式
+   - 更可靠
+
+## 连接流程概述
+
+### 被控端启动流程
+
+```
+1. 生成设备 ID 和密钥对
+2. 连接 Rendezvous Server
+3. 发送 RegisterPeer 消息
+4. 如果需要，发送 RegisterPk 注册公钥
+5. 定期发送心跳保持在线状态
+6. 等待 PunchHole 或 RequestRelay 请求
+```
+
+### 控制端连接流程
+
+```
+1. 输入目标设备 ID
+2. 连接 Rendezvous Server
+3. 发送 PunchHoleRequest 消息
+4. 根据响应决定连接方式:
+   a. 直连 (P2P): 使用 PunchHole 信息尝试打洞
+   b. 局域网: 使用 LocalAddr 信息直连
+   c. 中转: 通过 Relay Server 连接
+5. 建立安全加密通道
+6. 发送 LoginRequest 进行身份验证
+7. 开始远程控制会话
+```
+
+## 数据流
+
+### 视频流
+
+```
+被控端                              控制端
+  │                                  │
+  │  VideoFrame (H264/VP9/...)       │
+  ├─────────────────────────────────►│
+  │                                  │
+  │  加密 → 传输 → 解密 → 解码 → 显示 │
+```
+
+### 输入流
+
+```
+控制端                              被控端
+  │                                  │
+  │  MouseEvent/KeyEvent             │
+  ├─────────────────────────────────►│
+  │                                  │
+  │  加密 → 传输 → 解密 → 模拟输入    │
+```
+
+## 高可用设计
+
+### 多服务器支持
+
+- 客户端可配置多个 Rendezvous Server
+- 自动选择延迟最低的服务器
+- 连接失败时自动切换备用服务器
+
+### Relay Server 选择
+
+- 支持配置多个 Relay Server
+- 轮询算法分配负载
+- 定期检查 Relay Server 可用性
+
+### 重连机制
+
+```rust
+// 连接超时和重试参数
+const REG_INTERVAL: i64 = 12_000;      // 注册间隔 12 秒
+const REG_TIMEOUT: i32 = 30_000;       // 注册超时 30 秒
+const CONNECT_TIMEOUT: u64 = 18_000;   // 连接超时 18 秒
+```

docs/report/rustdesk/02-rendezvous-protocol.md

@@ -0,0 +1,438 @@
+# Rendezvous 服务器协议
+
+## 概述
+
+Rendezvous Server（hbbs）是 RustDesk 的核心协调服务器，负责：
+- Peer ID 注册和发现
+- 公钥存储和分发
+- NAT 类型检测
+- P2P 连接协调（打洞辅助）
+- Relay Server 分配
+
+## 协议消息定义
+
+所有消息使用 Protocol Buffers 定义在 `protos/rendezvous.proto`：
+
+```protobuf
+message RendezvousMessage {
+  oneof union {
+    RegisterPeer register_peer = 6;
+    RegisterPeerResponse register_peer_response = 7;
+    PunchHoleRequest punch_hole_request = 8;
+    PunchHole punch_hole = 9;
+    PunchHoleSent punch_hole_sent = 10;
+    PunchHoleResponse punch_hole_response = 11;
+    FetchLocalAddr fetch_local_addr = 12;
+    LocalAddr local_addr = 13;
+    ConfigUpdate configure_update = 14;
+    RegisterPk register_pk = 15;
+    RegisterPkResponse register_pk_response = 16;
+    SoftwareUpdate software_update = 17;
+    RequestRelay request_relay = 18;
+    RelayResponse relay_response = 19;
+    TestNatRequest test_nat_request = 20;
+    TestNatResponse test_nat_response = 21;
+    PeerDiscovery peer_discovery = 22;
+    OnlineRequest online_request = 23;
+    OnlineResponse online_response = 24;
+    KeyExchange key_exchange = 25;
+    HealthCheck hc = 26;
+  }
+}
+```
+
+## 核心流程
+
+### 1. Peer 注册流程
+
+**客户端 → 服务器：RegisterPeer**
+
+```protobuf
+message RegisterPeer {
+  string id = 1;      // Peer ID (如 "123456789")
+  int32 serial = 2;   // 配置序列号
+}
+```
+
+**服务器处理逻辑：**
+
+```rust
+// rustdesk-server/src/rendezvous_server.rs:318-333
+Some(rendezvous_message::Union::RegisterPeer(rp)) => {
+    if !rp.id.is_empty() {
+        log::trace!("New peer registered: {:?} {:?}", &rp.id, &addr);
+        self.update_addr(rp.id, addr, socket).await?;
+        // 如果服务器配置更新，发送 ConfigUpdate
+        if self.inner.serial > rp.serial {
+            let mut msg_out = RendezvousMessage::new();
+            msg_out.set_configure_update(ConfigUpdate {
+                serial: self.inner.serial,
+                rendezvous_servers: (*self.rendezvous_servers).clone(),
+                ..Default::default()
+            });
+            socket.send(&msg_out, addr).await?;
+        }
+    }
+}
+```
+
+**服务器 → 客户端：RegisterPeerResponse**
+
+```protobuf
+message RegisterPeerResponse {
+  bool request_pk = 2;  // 是否需要注册公钥
+}
+```
+
+### 2. 公钥注册流程
+
+当服务器检测到 Peer 的公钥为空或 IP 变化时，会请求注册公钥。
+
+**客户端 → 服务器：RegisterPk**
+
+```protobuf
+message RegisterPk {
+  string id = 1;       // Peer ID
+  bytes uuid = 2;      // 设备 UUID
+  bytes pk = 3;        // Ed25519 公钥
+  string old_id = 4;   // 旧 ID（如果更换）
+}
+```
+
+**服务器处理逻辑：**
+
+```rust
+// rustdesk-server/src/rendezvous_server.rs:334-418
+Some(rendezvous_message::Union::RegisterPk(rk)) => {
+    // 验证 UUID 和公钥
+    if rk.uuid.is_empty() || rk.pk.is_empty() {
+        return Ok(());
+    }
+    let id = rk.id;
+    let ip = addr.ip().to_string();
+
+    // ID 长度检查
+    if id.len() < 6 {
+        return send_rk_res(socket, addr, UUID_MISMATCH).await;
+    }
+
+    // IP 封锁检查
+    if !self.check_ip_blocker(&ip, &id).await {
+        return send_rk_res(socket, addr, TOO_FREQUENT).await;
+    }
+
+    // UUID 匹配验证
+    let peer = self.pm.get_or(&id).await;
+    // ... UUID 验证逻辑 ...
+
+    // 更新数据库
+    if changed {
+        self.pm.update_pk(id, peer, addr, rk.uuid, rk.pk, ip).await;
+    }
+
+    // 发送成功响应
+    msg_out.set_register_pk_response(RegisterPkResponse {
+        result: register_pk_response::Result::OK.into(),
+        ..Default::default()
+    });
+}
+```
+
+**服务器 → 客户端：RegisterPkResponse**
+
+```protobuf
+message RegisterPkResponse {
+  enum Result {
+    OK = 0;
+    UUID_MISMATCH = 2;
+    ID_EXISTS = 3;
+    TOO_FREQUENT = 4;
+    INVALID_ID_FORMAT = 5;
+    NOT_SUPPORT = 6;
+    SERVER_ERROR = 7;
+  }
+  Result result = 1;
+  int32 keep_alive = 2;  // 心跳间隔
+}
+```
+
+### 3. Punch Hole 请求流程
+
+当控制端要连接被控端时，首先发送 PunchHoleRequest。
+
+**控制端 → 服务器：PunchHoleRequest**
+
+```protobuf
+message PunchHoleRequest {
+  string id = 1;           // 目标 Peer ID
+  NatType nat_type = 2;    // 请求方的 NAT 类型
+  string licence_key = 3;  // 许可证密钥
+  ConnType conn_type = 4;  // 连接类型
+  string token = 5;        // 认证令牌
+  string version = 6;      // 客户端版本
+}
+
+enum NatType {
+  UNKNOWN_NAT = 0;
+  ASYMMETRIC = 1;
+  SYMMETRIC = 2;
+}
+
+enum ConnType {
+  DEFAULT_CONN = 0;
+  FILE_TRANSFER = 1;
+  PORT_FORWARD = 2;
+  RDP = 3;
+  VIEW_CAMERA = 4;
+}
+```
+
+**服务器处理逻辑：**
+
+```rust
+// rustdesk-server/src/rendezvous_server.rs:674-765
+async fn handle_punch_hole_request(...) {
+    // 1. 验证许可证密钥
+    if !key.is_empty() && ph.licence_key != key {
+        return Ok((PunchHoleResponse { failure: LICENSE_MISMATCH }, None));
+    }
+
+    // 2. 查找目标 Peer
+    if let Some(peer) = self.pm.get(&id).await {
+        let (elapsed, peer_addr) = peer.read().await;
+
+        // 3. 检查在线状态
+        if elapsed >= REG_TIMEOUT {
+            return Ok((PunchHoleResponse { failure: OFFLINE }, None));
+        }
+
+        // 4. 判断是否同一局域网
+        let same_intranet = (peer_is_lan && is_lan) ||
+                            (peer_addr.ip() == addr.ip());
+
+        if same_intranet {
+            // 请求获取本地地址
+            msg_out.set_fetch_local_addr(FetchLocalAddr {
+                socket_addr: AddrMangle::encode(addr).into(),
+                relay_server,
+            });
+        } else {
+            // 发送 Punch Hole 请求给被控端
+            msg_out.set_punch_hole(PunchHole {
+                socket_addr: AddrMangle::encode(addr).into(),
+                nat_type: ph.nat_type,
+                relay_server,
+            });
+        }
+        return Ok((msg_out, Some(peer_addr)));
+    }
+
+    // Peer 不存在
+    Ok((PunchHoleResponse { failure: ID_NOT_EXIST }, None))
+}
+```
+
+**服务器 → 被控端：PunchHole 或 FetchLocalAddr**
+
+```protobuf
+message PunchHole {
+  bytes socket_addr = 1;    // 控制端地址（编码）
+  string relay_server = 2;  // Relay 服务器地址
+  NatType nat_type = 3;     // 控制端 NAT 类型
+}
+
+message FetchLocalAddr {
+  bytes socket_addr = 1;    // 控制端地址（编码）
+  string relay_server = 2;  // Relay 服务器地址
+}
+```
+
+### 4. 被控端响应流程
+
+**被控端 → 服务器：PunchHoleSent 或 LocalAddr**
+
+```protobuf
+message PunchHoleSent {
+  bytes socket_addr = 1;    // 控制端地址
+  string id = 2;            // 被控端 ID
+  string relay_server = 3;  // Relay 服务器
+  NatType nat_type = 4;     // 被控端 NAT 类型
+  string version = 5;       // 客户端版本
+}
+
+message LocalAddr {
+  bytes socket_addr = 1;    // 控制端地址
+  bytes local_addr = 2;     // 被控端本地地址
+  string relay_server = 3;  // Relay 服务器
+  string id = 4;            // 被控端 ID
+  string version = 5;       // 客户端版本
+}
+```
+
+**服务器 → 控制端：PunchHoleResponse**
+
+```protobuf
+message PunchHoleResponse {
+  bytes socket_addr = 1;    // 被控端地址
+  bytes pk = 2;             // 被控端公钥（已签名）
+  enum Failure {
+    ID_NOT_EXIST = 0;
+    OFFLINE = 2;
+    LICENSE_MISMATCH = 3;
+    LICENSE_OVERUSE = 4;
+  }
+  Failure failure = 3;
+  string relay_server = 4;
+  oneof union {
+    NatType nat_type = 5;
+    bool is_local = 6;      // 是否为局域网连接
+  }
+  string other_failure = 7;
+  int32 feedback = 8;
+}
+```
+
+### 5. Relay 请求流程
+
+当 P2P 连接失败或 NAT 类型不支持打洞时，使用 Relay。
+
+**客户端 → 服务器：RequestRelay**
+
+```protobuf
+message RequestRelay {
+  string id = 1;            // 目标 Peer ID
+  string uuid = 2;          // 连接 UUID（用于配对）
+  bytes socket_addr = 3;    // 本端地址
+  string relay_server = 4;  // 指定的 Relay 服务器
+  bool secure = 5;          // 是否使用加密
+  string licence_key = 6;   // 许可证密钥
+  ConnType conn_type = 7;   // 连接类型
+  string token = 8;         // 认证令牌
+}
+```
+
+**服务器 → 客户端：RelayResponse**
+
+```protobuf
+message RelayResponse {
+  bytes socket_addr = 1;    // 对端地址
+  string uuid = 2;          // 连接 UUID
+  string relay_server = 3;  // Relay 服务器地址
+  oneof union {
+    string id = 4;          // 对端 ID
+    bytes pk = 5;           // 对端公钥
+  }
+  string refuse_reason = 6; // 拒绝原因
+  string version = 7;       // 版本
+  int32 feedback = 9;
+}
+```
+
+## NAT 类型检测
+
+**客户端 → 服务器：TestNatRequest**
+
+```protobuf
+message TestNatRequest {
+  int32 serial = 1;  // 配置序列号
+}
+```
+
+**服务器 → 客户端：TestNatResponse**
+
+```protobuf
+message TestNatResponse {
+  int32 port = 1;           // 观测到的源端口
+  ConfigUpdate cu = 2;      // 配置更新
+}
+```
+
+NAT 检测原理：
+1. 客户端同时向主端口（21116）和 NAT 测试端口（21115）发送请求
+2. 比较两次响应中观测到的源端口
+3. 如果端口一致，则为 ASYMMETRIC NAT（适合打洞）
+4. 如果端口不一致，则为 SYMMETRIC NAT（需要 Relay）
+
+## 地址编码
+
+RustDesk 使用 `AddrMangle` 对 SocketAddr 进行编码：
+
+```rust
+// 编码示例
+// IPv4: 4 bytes IP + 2 bytes port = 6 bytes
+// IPv6: 16 bytes IP + 2 bytes port = 18 bytes
+pub fn encode(addr: SocketAddr) -> Vec<u8>;
+pub fn decode(bytes: &[u8]) -> SocketAddr;
+```
+
+## 安全机制
+
+### 服务器签名
+
+当服务器配置了私钥时，会对 Peer 的公钥进行签名：
+
+```rust
+// rustdesk-server/src/rendezvous_server.rs:1160-1182
+async fn get_pk(&mut self, version: &str, id: String) -> Bytes {
+    if version.is_empty() || self.inner.sk.is_none() {
+        Bytes::new()
+    } else {
+        match self.pm.get(&id).await {
+            Some(peer) => {
+                let pk = peer.read().await.pk.clone();
+                // 使用服务器私钥签名 IdPk
+                sign::sign(
+                    &IdPk { id, pk, ..Default::default() }
+                        .write_to_bytes()
+                        .unwrap_or_default(),
+                    self.inner.sk.as_ref().unwrap(),
+                ).into()
+            }
+            _ => Bytes::new(),
+        }
+    }
+}
+```
+
+### IP 封锁
+
+服务器实现了 IP 封锁机制防止滥用：
+
+```rust
+// rustdesk-server/src/rendezvous_server.rs:866-894
+async fn check_ip_blocker(&self, ip: &str, id: &str) -> bool {
+    let mut lock = IP_BLOCKER.lock().await;
+    if let Some(old) = lock.get_mut(ip) {
+        // 每秒请求超过 30 次则封锁
+        if counter.0 > 30 {
+            return false;
+        }
+        // 每天超过 300 个不同 ID 则封锁
+        if counter.0.len() > 300 {
+            return !is_new;
+        }
+    }
+    true
+}
+```
+
+## 时序图
+
+### 完整连接建立流程
+
+```
+控制端              Rendezvous Server           被控端
+  │                       │                       │
+  │  PunchHoleRequest     │                       │
+  ├──────────────────────►│                       │
+  │                       │    PunchHole          │
+  │                       ├──────────────────────►│
+  │                       │                       │
+  │                       │    PunchHoleSent      │
+  │                       │◄──────────────────────┤
+  │  PunchHoleResponse    │                       │
+  │◄──────────────────────┤                       │
+  │                       │                       │
+  │  ─────────── P2P Connection ──────────────────│
+  │◄─────────────────────────────────────────────►│
+```

docs/report/rustdesk/03-relay-protocol.md

@@ -0,0 +1,318 @@
+# Relay 服务器协议
+
+## 概述
+
+Relay Server（hbbr）是 RustDesk 的数据中转服务器，当 P2P 连接无法建立时（如双方都在 Symmetric NAT 后面），所有通信数据通过 Relay Server 转发。
+
+## 服务器架构
+
+### 监听端口
+
+| 端口 | 协议 | 用途 |
+|------|------|------|
+| 21117 | TCP | 主要中转端口 |
+| 21119 | WebSocket | Web 客户端支持 |
+
+### 核心配置
+
+```rust
+// rustdesk-server/src/relay_server.rs:40-46
+static DOWNGRADE_THRESHOLD_100: AtomicUsize = AtomicUsize::new(66);        // 0.66
+static DOWNGRADE_START_CHECK: AtomicUsize = AtomicUsize::new(1_800_000);   // 30分钟 (ms)
+static LIMIT_SPEED: AtomicUsize = AtomicUsize::new(32 * 1024 * 1024);      // 32 Mb/s
+static TOTAL_BANDWIDTH: AtomicUsize = AtomicUsize::new(1024 * 1024 * 1024);// 1024 Mb/s
+static SINGLE_BANDWIDTH: AtomicUsize = AtomicUsize::new(128 * 1024 * 1024);// 128 Mb/s
+const BLACKLIST_FILE: &str = "blacklist.txt";
+const BLOCKLIST_FILE: &str = "blocklist.txt";
+```
+
+## 连接配对机制
+
+### 配对原理
+
+Relay Server 使用 UUID 来配对两个客户端的连接：
+
+1. 第一个客户端连接并发送 `RequestRelay` 消息（包含 UUID）
+2. 服务器将该连接存储在等待队列中
+3. 第二个客户端使用相同的 UUID 连接
+4. 服务器将两个连接配对，开始转发数据
+
+### 配对流程
+
+```rust
+// rustdesk-server/src/relay_server.rs:425-462
+async fn make_pair_(stream: impl StreamTrait, addr: SocketAddr, key: &str, limiter: Limiter) {
+    let mut stream = stream;
+    if let Ok(Some(Ok(bytes))) = timeout(30_000, stream.recv()).await {
+        if let Ok(msg_in) = RendezvousMessage::parse_from_bytes(&bytes) {
+            if let Some(rendezvous_message::Union::RequestRelay(rf)) = msg_in.union {
+                // 验证许可证密钥
+                if !key.is_empty() && rf.licence_key != key {
+                    log::warn!("Relay authentication failed from {}", addr);
+                    return;
+                }
+
+                if !rf.uuid.is_empty() {
+                    // 尝试查找配对
+                    let mut peer = PEERS.lock().await.remove(&rf.uuid);
+                    if let Some(peer) = peer.as_mut() {
+                        // 找到配对，开始中转
+                        log::info!("Relay request {} got paired", rf.uuid);
+                        relay(addr, &mut stream, peer, limiter).await;
+                    } else {
+                        // 没找到，存储等待配对
+                        log::info!("New relay request {} from {}", rf.uuid, addr);
+                        PEERS.lock().await.insert(rf.uuid.clone(), Box::new(stream));
+                        sleep(30.).await;  // 等待 30 秒
+                        PEERS.lock().await.remove(&rf.uuid);  // 超时移除
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## 数据转发
+
+### 转发逻辑
+
+```rust
+// rustdesk-server/src/relay_server.rs:464-566
+async fn relay(
+    addr: SocketAddr,
+    stream: &mut impl StreamTrait,
+    peer: &mut Box<dyn StreamTrait>,
+    total_limiter: Limiter,
+) -> ResultType<()> {
+    let limiter = <Limiter>::new(SINGLE_BANDWIDTH.load(Ordering::SeqCst) as f64);
+    let blacklist_limiter = <Limiter>::new(LIMIT_SPEED.load(Ordering::SeqCst) as _);
+
+    loop {
+        tokio::select! {
+            // 从 peer 接收数据，发送给 stream
+            res = peer.recv() => {
+                if let Some(Ok(bytes)) = res {
+                    // 带宽限制
+                    if blacked || downgrade {
+                        blacklist_limiter.consume(bytes.len() * 8).await;
+                    } else {
+                        limiter.consume(bytes.len() * 8).await;
+                    }
+                    total_limiter.consume(bytes.len() * 8).await;
+                    stream.send_raw(bytes.into()).await?;
+                } else {
+                    break;
+                }
+            },
+            // 从 stream 接收数据，发送给 peer
+            res = stream.recv() => {
+                if let Some(Ok(bytes)) = res {
+                    // 带宽限制
+                    limiter.consume(bytes.len() * 8).await;
+                    total_limiter.consume(bytes.len() * 8).await;
+                    peer.send_raw(bytes.into()).await?;
+                } else {
+                    break;
+                }
+            },
+            _ = timer.tick() => {
+                // 超时检测
+                if last_recv_time.elapsed().as_secs() > 30 {
+                    bail!("Timeout");
+                }
+            }
+        }
+
+        // 降级检测
+        if elapsed > DOWNGRADE_START_CHECK && total > elapsed * downgrade_threshold {
+            downgrade = true;
+            log::info!("Downgrade {}, exceed threshold", id);
+        }
+    }
+    Ok(())
+}
+```
+
+### 原始模式
+
+当两端都支持原始模式时，跳过 protobuf 解析以提高性能：
+
+```rust
+// rustdesk-server/src/relay_server.rs:440-444
+if !stream.is_ws() && !peer.is_ws() {
+    peer.set_raw();
+    stream.set_raw();
+    log::info!("Both are raw");
+}
+```
+
+## 带宽控制
+
+### 多级限速
+
+1. **总带宽限制**：整个服务器的总带宽
+2. **单连接限制**：每个中转连接的带宽
+3. **黑名单限速**：对黑名单 IP 的特殊限制
+
+### 降级机制
+
+当连接持续占用高带宽时，会触发降级：
+
+```rust
+// 条件：
+// 1. 连接时间 > DOWNGRADE_START_CHECK (30分钟)
+// 2. 平均带宽 > SINGLE_BANDWIDTH * 0.66
+// 降级后使用 LIMIT_SPEED (32 Mb/s) 限速
+if elapsed > DOWNGRADE_START_CHECK.load(Ordering::SeqCst)
+    && !downgrade
+    && total > elapsed * downgrade_threshold
+{
+    downgrade = true;
+}
+```
+
+## 安全控制
+
+### 黑名单
+
+用于限速特定 IP：
+
+```
+# blacklist.txt
+192.168.1.100
+10.0.0.50
+```
+
+### 封锁名单
+
+用于完全拒绝特定 IP：
+
+```
+# blocklist.txt
+1.2.3.4
+5.6.7.8
+```
+
+### 运行时管理命令
+
+通过本地 TCP 连接（仅限 localhost）发送命令：
+
+```rust
+// rustdesk-server/src/relay_server.rs:152-324
+match fds.next() {
+    Some("h") => // 帮助
+    Some("blacklist-add" | "ba") => // 添加黑名单
+    Some("blacklist-remove" | "br") => // 移除黑名单
+    Some("blacklist" | "b") => // 查看黑名单
+    Some("blocklist-add" | "Ba") => // 添加封锁名单
+    Some("blocklist-remove" | "Br") => // 移除封锁名单
+    Some("blocklist" | "B") => // 查看封锁名单
+    Some("downgrade-threshold" | "dt") => // 设置降级阈值
+    Some("downgrade-start-check" | "t") => // 设置降级检测时间
+    Some("limit-speed" | "ls") => // 设置限速
+    Some("total-bandwidth" | "tb") => // 设置总带宽
+    Some("single-bandwidth" | "sb") => // 设置单连接带宽
+    Some("usage" | "u") => // 查看使用统计
+}
+```
+
+## 协议消息
+
+### RequestRelay
+
+用于建立中转连接的请求消息：
+
+```protobuf
+message RequestRelay {
+  string id = 1;            // 目标 Peer ID
+  string uuid = 2;          // 连接 UUID（配对用）
+  bytes socket_addr = 3;    // 本端地址
+  string relay_server = 4;  // Relay 服务器
+  bool secure = 5;          // 是否加密
+  string licence_key = 6;   // 许可证密钥
+  ConnType conn_type = 7;   // 连接类型
+  string token = 8;         // 认证令牌
+}
+```
+
+## 时序图
+
+### 中转连接建立
+
+```
+客户端 A                  Relay Server                  客户端 B
+   │                          │                            │
+   │   RequestRelay(uuid)     │                            │
+   ├─────────────────────────►│                            │
+   │                          │                            │
+   │                          │  (存储等待配对)              │
+   │                          │                            │
+   │                          │        RequestRelay(uuid)  │
+   │                          │◄───────────────────────────┤
+   │                          │                            │
+   │                          │  (配对成功)                 │
+   │                          │                            │
+   │  ◄────────── 数据转发 ─────────────────────────────────►│
+   │                          │                            │
+```
+
+### 数据转发
+
+```
+客户端 A           Relay Server           客户端 B
+   │                    │                    │
+   │ ────[数据]───────► │                    │
+   │                    │ ────[数据]───────► │
+   │                    │                    │
+   │                    │ ◄───[数据]──────── │
+   │ ◄───[数据]──────── │                    │
+   │                    │                    │
+```
+
+## 性能优化
+
+### 零拷贝
+
+使用 `Bytes` 类型减少内存拷贝：
+
+```rust
+async fn send_raw(&mut self, bytes: Bytes) -> ResultType<()>;
+```
+
+### WebSocket 支持
+
+支持 WebSocket 协议以穿越防火墙：
+
+```rust
+#[async_trait]
+impl StreamTrait for tokio_tungstenite::WebSocketStream<TcpStream> {
+    async fn recv(&mut self) -> Option<Result<BytesMut, Error>> {
+        if let Some(msg) = self.next().await {
+            match msg {
+                Ok(tungstenite::Message::Binary(bytes)) => {
+                    Some(Ok(bytes[..].into()))
+                }
+                // ...
+            }
+        }
+    }
+}
+```
+
+## 监控指标
+
+服务器跟踪以下指标：
+
+| 指标 | 说明 |
+|------|------|
+| elapsed | 连接持续时间 (ms) |
+| total | 总传输数据量 (bit) |
+| highest | 最高瞬时速率 (kb/s) |
+| speed | 当前速率 (kb/s) |
+
+通过 `usage` 命令查看：
+
+```
+192.168.1.100:12345: 3600s 1024.00MB 50000kb/s 45000kb/s 42000kb/s
+```

docs/report/rustdesk/04-p2p-connection.md

@@ -0,0 +1,424 @@
+# P2P 连接流程
+
+## 概述
+
+RustDesk 优先尝试建立 P2P 直连，只有在直连失败时才使用 Relay 中转。P2P 连接支持多种方式：
+- TCP 打洞
+- UDP 打洞（KCP）
+- 局域网直连
+- IPv6 直连
+
+## 连接决策流程
+
+```
+                              开始连接
+                                 │
+                                 ▼
+                         ┌──────────────┐
+                         │ 是否强制 Relay？│
+                         └──────┬───────┘
+                           是   │   否
+                     ┌─────────┴─────────┐
+                     ▼                   ▼
+              使用 Relay           检查 NAT 类型
+                                        │
+                         ┌──────────────┴──────────────┐
+                         │                             │
+                         ▼                             ▼
+                  双方都是对称 NAT？            有一方是可穿透 NAT
+                         │                             │
+                    是   │                             │
+                         ▼                             ▼
+                  使用 Relay                  尝试 P2P 连接
+                                                      │
+                                        ┌─────────────┴─────────────┐
+                                        │                           │
+                                        ▼                           ▼
+                                 同一局域网？                  不同网络
+                                        │                           │
+                                   是   │                           │
+                                        ▼                           ▼
+                               局域网直连                      尝试打洞
+                                                                   │
+                                                    ┌──────────────┴──────────────┐
+                                                    │                             │
+                                                    ▼                             ▼
+                                            TCP 打洞成功？                  UDP 打洞成功？
+                                                    │                             │
+                                               是   │   否                   是   │   否
+                                                    ▼    │                        ▼    │
+                                            TCP P2P 连接  └───────────► KCP P2P 连接   │
+                                                                                       ▼
+                                                                               使用 Relay
+```
+
+## 客户端连接入口
+
+```rust
+// rustdesk/src/client.rs:188-230
+impl Client {
+    pub async fn start(
+        peer: &str,
+        key: &str,
+        token: &str,
+        conn_type: ConnType,
+        interface: impl Interface,
+    ) -> ResultType<...> {
+        // 检查是否为 IP 直连
+        if hbb_common::is_ip_str(peer) {
+            return connect_tcp_local(check_port(peer, RELAY_PORT + 1), None, CONNECT_TIMEOUT).await;
+        }
+
+        // 检查是否为域名:端口格式
+        if hbb_common::is_domain_port_str(peer) {
+            return connect_tcp_local(peer, None, CONNECT_TIMEOUT).await;
+        }
+
+        // 通过 Rendezvous Server 连接
+        let (rendezvous_server, servers, _) = crate::get_rendezvous_server(1_000).await;
+        Self::_start_inner(peer, key, token, conn_type, interface, rendezvous_server, servers).await
+    }
+}
+```
+
+## 被控端处理连接请求
+
+### 处理 PunchHole 消息
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:554-619
+async fn handle_punch_hole(&self, ph: PunchHole, server: ServerPtr) -> ResultType<()> {
+    let peer_addr = AddrMangle::decode(&ph.socket_addr);
+    let relay_server = self.get_relay_server(ph.relay_server);
+
+    // 判断是否需要 Relay
+    if ph.nat_type.enum_value() == Ok(NatType::SYMMETRIC)
+        || Config::get_nat_type() == NatType::SYMMETRIC as i32
+        || relay
+    {
+        // 使用 Relay
+        let uuid = Uuid::new_v4().to_string();
+        return self.create_relay(ph.socket_addr, relay_server, uuid, server, true, true).await;
+    }
+
+    // 尝试 UDP 打洞
+    if ph.udp_port > 0 {
+        peer_addr.set_port(ph.udp_port as u16);
+        self.punch_udp_hole(peer_addr, server, msg_punch).await?;
+        return Ok(());
+    }
+
+    // 尝试 TCP 打洞
+    log::debug!("Punch tcp hole to {:?}", peer_addr);
+    let socket = {
+        let socket = connect_tcp(&*self.host, CONNECT_TIMEOUT).await?;
+        let local_addr = socket.local_addr();
+        // 关键步骤：尝试连接对方，让 NAT 建立映射
+        allow_err!(socket_client::connect_tcp_local(peer_addr, Some(local_addr), 30).await);
+        socket
+    };
+
+    // 发送 PunchHoleSent 告知 Rendezvous Server
+    let mut msg_out = Message::new();
+    msg_out.set_punch_hole_sent(PunchHoleSent {
+        socket_addr: ph.socket_addr,
+        id: Config::get_id(),
+        relay_server,
+        nat_type: nat_type.into(),
+        version: crate::VERSION.to_owned(),
+    });
+    socket.send_raw(msg_out.write_to_bytes()?).await?;
+
+    // 接受控制端连接
+    crate::accept_connection(server.clone(), socket, peer_addr, true).await;
+    Ok(())
+}
+```
+
+### 处理 FetchLocalAddr（局域网连接）
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:481-552
+async fn handle_intranet(&self, fla: FetchLocalAddr, server: ServerPtr) -> ResultType<()> {
+    let peer_addr = AddrMangle::decode(&fla.socket_addr);
+    let relay_server = self.get_relay_server(fla.relay_server.clone());
+
+    // 尝试局域网直连
+    if is_ipv4(&self.addr) && !relay && !config::is_disable_tcp_listen() {
+        if let Err(err) = self.handle_intranet_(fla.clone(), server.clone(), relay_server.clone()).await {
+            log::debug!("Failed to handle intranet: {:?}, will try relay", err);
+        } else {
+            return Ok(());
+        }
+    }
+
+    // 局域网直连失败，使用 Relay
+    let uuid = Uuid::new_v4().to_string();
+    self.create_relay(fla.socket_addr, relay_server, uuid, server, true, true).await
+}
+
+async fn handle_intranet_(&self, fla: FetchLocalAddr, server: ServerPtr, relay_server: String) -> ResultType<()> {
+    let peer_addr = AddrMangle::decode(&fla.socket_addr);
+    let mut socket = connect_tcp(&*self.host, CONNECT_TIMEOUT).await?;
+    let local_addr = socket.local_addr();
+
+    // 发送本地地址给 Rendezvous Server
+    let mut msg_out = Message::new();
+    msg_out.set_local_addr(LocalAddr {
+        id: Config::get_id(),
+        socket_addr: AddrMangle::encode(peer_addr).into(),
+        local_addr: AddrMangle::encode(local_addr).into(),
+        relay_server,
+        version: crate::VERSION.to_owned(),
+    });
+    socket.send_raw(msg_out.write_to_bytes()?).await?;
+
+    // 接受连接
+    crate::accept_connection(server.clone(), socket, peer_addr, true).await;
+    Ok(())
+}
+```
+
+## UDP 打洞 (KCP)
+
+### 打洞原理
+
+UDP 打洞利用 NAT 的端口映射特性：
+
+1. A 向 Rendezvous Server 注册，NAT 创建映射 `A_internal:port1 → A_external:port2`
+2. B 同样注册，创建映射 `B_internal:port3 → B_external:port4`
+3. A 向 B 的外部地址发送 UDP 包，A 的 NAT 创建到 B 的映射
+4. B 向 A 的外部地址发送 UDP 包，B 的 NAT 创建到 A 的映射
+5. 如果 NAT 不是 Symmetric 类型，双方的包可以到达对方
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:621-642
+async fn punch_udp_hole(
+    &self,
+    peer_addr: SocketAddr,
+    server: ServerPtr,
+    msg_punch: PunchHoleSent,
+) -> ResultType<()> {
+    let mut msg_out = Message::new();
+    msg_out.set_punch_hole_sent(msg_punch);
+    let (socket, addr) = new_direct_udp_for(&self.host).await?;
+    let data = msg_out.write_to_bytes()?;
+
+    // 发送到 Rendezvous Server
+    socket.send_to(&data, addr).await?;
+
+    // 多次尝试发送以增加成功率
+    let socket_cloned = socket.clone();
+    tokio::spawn(async move {
+        for _ in 0..2 {
+            let tm = (hbb_common::time_based_rand() % 20 + 10) as f32 / 1000.;
+            hbb_common::sleep(tm).await;
+            socket.send_to(&data, addr).await.ok();
+        }
+    });
+
+    // 等待对方连接
+    udp_nat_listen(socket_cloned.clone(), peer_addr, peer_addr, server).await?;
+    Ok(())
+}
+```
+
+### KCP 协议
+
+RustDesk 在 UDP 上使用 KCP 协议提供可靠传输：
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:824-851
+async fn udp_nat_listen(
+    socket: Arc<tokio::net::UdpSocket>,
+    peer_addr: SocketAddr,
+    peer_addr_v4: SocketAddr,
+    server: ServerPtr,
+) -> ResultType<()> {
+    socket.connect(peer_addr).await?;
+
+    // 执行 UDP 打洞
+    let res = crate::punch_udp(socket.clone(), true).await?;
+
+    // 建立 KCP 流
+    let stream = crate::kcp_stream::KcpStream::accept(
+        socket,
+        Duration::from_millis(CONNECT_TIMEOUT as _),
+        res,
+    ).await?;
+
+    // 创建连接
+    crate::server::create_tcp_connection(server, stream.1, peer_addr_v4, true).await?;
+    Ok(())
+}
+```
+
+## TCP 打洞
+
+### 原理
+
+TCP 打洞比 UDP 更难，因为 TCP 需要三次握手。基本思路：
+
+1. A 和 B 都尝试同时向对方发起连接
+2. 第一个 SYN 包会被对方的 NAT 丢弃（因为没有映射）
+3. 但这个 SYN 包会在 A 的 NAT 上创建映射
+4. 当 B 的 SYN 包到达 A 的 NAT 时，由于已有映射，会被转发给 A
+5. 连接建立
+
+### 实现
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:604-617
+log::debug!("Punch tcp hole to {:?}", peer_addr);
+let mut socket = {
+    let socket = connect_tcp(&*self.host, CONNECT_TIMEOUT).await?;
+    let local_addr = socket.local_addr();
+    // 关键：使用相同的本地地址尝试连接对方
+    // 这会在 NAT 上创建映射，使对方的连接请求能够到达
+    allow_err!(socket_client::connect_tcp_local(peer_addr, Some(local_addr), 30).await);
+    socket
+};
+```
+
+## Relay 连接
+
+当 P2P 失败时，使用 Relay：
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:434-479
+async fn create_relay(
+    &self,
+    socket_addr: Vec<u8>,
+    relay_server: String,
+    uuid: String,
+    server: ServerPtr,
+    secure: bool,
+    initiate: bool,
+) -> ResultType<()> {
+    let peer_addr = AddrMangle::decode(&socket_addr);
+    log::info!(
+        "create_relay requested from {:?}, relay_server: {}, uuid: {}, secure: {}",
+        peer_addr, relay_server, uuid, secure,
+    );
+
+    // 连接 Rendezvous Server 发送 RelayResponse
+    let mut socket = connect_tcp(&*self.host, CONNECT_TIMEOUT).await?;
+    let mut msg_out = Message::new();
+    let mut rr = RelayResponse {
+        socket_addr: socket_addr.into(),
+        version: crate::VERSION.to_owned(),
+        ..Default::default()
+    };
+    if initiate {
+        rr.uuid = uuid.clone();
+        rr.relay_server = relay_server.clone();
+        rr.set_id(Config::get_id());
+    }
+    msg_out.set_relay_response(rr);
+    socket.send(&msg_out).await?;
+
+    // 连接 Relay Server
+    crate::create_relay_connection(
+        server,
+        relay_server,
+        uuid,
+        peer_addr,
+        secure,
+        is_ipv4(&self.addr),
+    ).await;
+    Ok(())
+}
+```
+
+## IPv6 支持
+
+RustDesk 优先尝试 IPv6 连接：
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:808-822
+async fn start_ipv6(
+    peer_addr_v6: SocketAddr,
+    peer_addr_v4: SocketAddr,
+    server: ServerPtr,
+) -> bytes::Bytes {
+    crate::test_ipv6().await;
+    if let Some((socket, local_addr_v6)) = crate::get_ipv6_socket().await {
+        let server = server.clone();
+        tokio::spawn(async move {
+            allow_err!(udp_nat_listen(socket.clone(), peer_addr_v6, peer_addr_v4, server).await);
+        });
+        return local_addr_v6;
+    }
+    Default::default()
+}
+```
+
+## 连接状态机
+
+```
+          ┌─────────────────────────────────────────┐
+          │                                         │
+          ▼                                         │
+    ┌───────────┐                              ┌────┴────┐
+    │ 等待连接   │──────PunchHoleRequest──────►│正在连接  │
+    └───────────┘                              └────┬────┘
+                                                   │
+                    ┌──────────────────────────────┼──────────────────────────────┐
+                    │                              │                              │
+                    ▼                              ▼                              ▼
+             ┌────────────┐                ┌─────────────┐                ┌─────────────┐
+             │ P2P TCP    │                │ P2P UDP/KCP │                │   Relay     │
+             │ 连接中     │                │ 连接中      │                │   连接中     │
+             └─────┬──────┘                └──────┬──────┘                └──────┬──────┘
+                   │                              │                              │
+          成功     │   失败                成功   │   失败                 成功   │   失败
+                   │    │                        │    │                         │    │
+                   ▼    │                        ▼    │                         ▼    │
+            ┌──────────┐│                 ┌──────────┐│                  ┌──────────┐│
+            │已连接     ││                 │已连接     ││                  │已连接     ││
+            │(直连)    ││                 │(UDP)     ││                  │(中转)    ││
+            └──────────┘│                 └──────────┘│                  └──────────┘│
+                        │                             │                              │
+                        └──────────────►尝试 Relay◄───┘                              │
+                                            │                                        │
+                                            └────────────────────────────────────────┘
+```
+
+## 直接连接模式
+
+用户可以配置允许直接 TCP 连接（不经过 Rendezvous Server）：
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:727-792
+async fn direct_server(server: ServerPtr) {
+    let mut listener = None;
+    let mut port = get_direct_port();  // 默认 21118
+
+    loop {
+        let disabled = !option2bool(OPTION_DIRECT_SERVER, &Config::get_option(OPTION_DIRECT_SERVER));
+
+        if !disabled && listener.is_none() {
+            match hbb_common::tcp::listen_any(port as _).await {
+                Ok(l) => {
+                    listener = Some(l);
+                    log::info!("Direct server listening on: {:?}", l.local_addr());
+                }
+                Err(err) => {
+                    log::error!("Failed to start direct server: {}", err);
+                }
+            }
+        }
+
+        if let Some(l) = listener.as_mut() {
+            if let Ok(Ok((stream, addr))) = hbb_common::timeout(1000, l.accept()).await {
+                stream.set_nodelay(true).ok();
+                log::info!("direct access from {}", addr);
+                let server = server.clone();
+                tokio::spawn(async move {
+                    crate::server::create_tcp_connection(server, stream, addr, false).await
+                });
+            }
+        }
+    }
+}
+```

docs/report/rustdesk/05-message-format.md

@@ -0,0 +1,574 @@
+# 消息格式定义
+
+## 概述
+
+RustDesk 使用 Protocol Buffers (protobuf) 定义所有网络消息格式。主要有两个 proto 文件：
+
+- `rendezvous.proto` - Rendezvous/Relay 服务器通信消息
+- `message.proto` - 客户端之间通信消息
+
+## Rendezvous 消息 (rendezvous.proto)
+
+### 顶层消息
+
+```protobuf
+message RendezvousMessage {
+  oneof union {
+    RegisterPeer register_peer = 6;
+    RegisterPeerResponse register_peer_response = 7;
+    PunchHoleRequest punch_hole_request = 8;
+    PunchHole punch_hole = 9;
+    PunchHoleSent punch_hole_sent = 10;
+    PunchHoleResponse punch_hole_response = 11;
+    FetchLocalAddr fetch_local_addr = 12;
+    LocalAddr local_addr = 13;
+    ConfigUpdate configure_update = 14;
+    RegisterPk register_pk = 15;
+    RegisterPkResponse register_pk_response = 16;
+    SoftwareUpdate software_update = 17;
+    RequestRelay request_relay = 18;
+    RelayResponse relay_response = 19;
+    TestNatRequest test_nat_request = 20;
+    TestNatResponse test_nat_response = 21;
+    PeerDiscovery peer_discovery = 22;
+    OnlineRequest online_request = 23;
+    OnlineResponse online_response = 24;
+    KeyExchange key_exchange = 25;
+    HealthCheck hc = 26;
+  }
+}
+```
+
+### 注册相关
+
+```protobuf
+// Peer 注册
+message RegisterPeer {
+  string id = 1;      // Peer ID
+  int32 serial = 2;   // 配置序列号
+}
+
+message RegisterPeerResponse {
+  bool request_pk = 2;  // 是否需要注册公钥
+}
+
+// 公钥注册
+message RegisterPk {
+  string id = 1;       // Peer ID
+  bytes uuid = 2;      // 设备 UUID
+  bytes pk = 3;        // Ed25519 公钥
+  string old_id = 4;   // 旧 ID
+}
+
+message RegisterPkResponse {
+  enum Result {
+    OK = 0;
+    UUID_MISMATCH = 2;
+    ID_EXISTS = 3;
+    TOO_FREQUENT = 4;
+    INVALID_ID_FORMAT = 5;
+    NOT_SUPPORT = 6;
+    SERVER_ERROR = 7;
+  }
+  Result result = 1;
+  int32 keep_alive = 2;
+}
+```
+
+### 连接协调相关
+
+```protobuf
+// 连接类型
+enum ConnType {
+  DEFAULT_CONN = 0;
+  FILE_TRANSFER = 1;
+  PORT_FORWARD = 2;
+  RDP = 3;
+  VIEW_CAMERA = 4;
+}
+
+// NAT 类型
+enum NatType {
+  UNKNOWN_NAT = 0;
+  ASYMMETRIC = 1;   // 可打洞
+  SYMMETRIC = 2;    // 需要中转
+}
+
+// Punch Hole 请求
+message PunchHoleRequest {
+  string id = 1;           // 目标 Peer ID
+  NatType nat_type = 2;
+  string licence_key = 3;
+  ConnType conn_type = 4;
+  string token = 5;
+  string version = 6;
+}
+
+// Punch Hole 响应
+message PunchHoleResponse {
+  bytes socket_addr = 1;      // 目标地址
+  bytes pk = 2;               // 公钥（已签名）
+  enum Failure {
+    ID_NOT_EXIST = 0;
+    OFFLINE = 2;
+    LICENSE_MISMATCH = 3;
+    LICENSE_OVERUSE = 4;
+  }
+  Failure failure = 3;
+  string relay_server = 4;
+  oneof union {
+    NatType nat_type = 5;
+    bool is_local = 6;
+  }
+  string other_failure = 7;
+  int32 feedback = 8;
+}
+
+// 服务器转发给被控端
+message PunchHole {
+  bytes socket_addr = 1;      // 控制端地址
+  string relay_server = 2;
+  NatType nat_type = 3;
+}
+
+// 被控端发送给服务器
+message PunchHoleSent {
+  bytes socket_addr = 1;
+  string id = 2;
+  string relay_server = 3;
+  NatType nat_type = 4;
+  string version = 5;
+}
+```
+
+### Relay 相关
+
+```protobuf
+// Relay 请求
+message RequestRelay {
+  string id = 1;
+  string uuid = 2;          // 配对 UUID
+  bytes socket_addr = 3;
+  string relay_server = 4;
+  bool secure = 5;
+  string licence_key = 6;
+  ConnType conn_type = 7;
+  string token = 8;
+}
+
+// Relay 响应
+message RelayResponse {
+  bytes socket_addr = 1;
+  string uuid = 2;
+  string relay_server = 3;
+  oneof union {
+    string id = 4;
+    bytes pk = 5;
+  }
+  string refuse_reason = 6;
+  string version = 7;
+  int32 feedback = 9;
+}
+```
+
+## 会话消息 (message.proto)
+
+### 顶层消息
+
+```protobuf
+message Message {
+  oneof union {
+    SignedId signed_id = 3;
+    PublicKey public_key = 4;
+    TestDelay test_delay = 5;
+    VideoFrame video_frame = 6;
+    LoginRequest login_request = 7;
+    LoginResponse login_response = 8;
+    Hash hash = 9;
+    MouseEvent mouse_event = 10;
+    AudioFrame audio_frame = 11;
+    CursorData cursor_data = 12;
+    CursorPosition cursor_position = 13;
+    uint64 cursor_id = 14;
+    KeyEvent key_event = 15;
+    Clipboard clipboard = 16;
+    FileAction file_action = 17;
+    FileResponse file_response = 18;
+    Misc misc = 19;
+    Cliprdr cliprdr = 20;
+    MessageBox message_box = 21;
+    SwitchSidesResponse switch_sides_response = 22;
+    VoiceCallRequest voice_call_request = 23;
+    VoiceCallResponse voice_call_response = 24;
+    PeerInfo peer_info = 25;
+    PointerDeviceEvent pointer_device_event = 26;
+    Auth2FA auth_2fa = 27;
+    MultiClipboards multi_clipboards = 28;
+  }
+}
+```
+
+### 认证相关
+
+```protobuf
+// ID 和公钥
+message IdPk {
+  string id = 1;
+  bytes pk = 2;
+}
+
+// 密钥交换
+message PublicKey {
+  bytes asymmetric_value = 1;  // X25519 公钥
+  bytes symmetric_value = 2;   // 加密的对称密钥
+}
+
+// 签名的 ID
+message SignedId {
+  bytes id = 1;  // 签名的 IdPk
+}
+
+// 密码哈希挑战
+message Hash {
+  string salt = 1;
+  string challenge = 2;
+}
+
+// 登录请求
+message LoginRequest {
+  string username = 1;
+  bytes password = 2;         // 加密的密码
+  string my_id = 4;
+  string my_name = 5;
+  OptionMessage option = 6;
+  oneof union {
+    FileTransfer file_transfer = 7;
+    PortForward port_forward = 8;
+    ViewCamera view_camera = 15;
+  }
+  bool video_ack_required = 9;
+  uint64 session_id = 10;
+  string version = 11;
+  OSLogin os_login = 12;
+  string my_platform = 13;
+  bytes hwid = 14;
+}
+
+// 登录响应
+message LoginResponse {
+  oneof union {
+    string error = 1;
+    PeerInfo peer_info = 2;
+  }
+  bool enable_trusted_devices = 3;
+}
+
+// 2FA 认证
+message Auth2FA {
+  string code = 1;
+  bytes hwid = 2;
+}
+```
+
+### 视频相关
+
+```protobuf
+// 编码后的视频帧
+message EncodedVideoFrame {
+  bytes data = 1;
+  bool key = 2;     // 是否关键帧
+  int64 pts = 3;    // 时间戳
+}
+
+message EncodedVideoFrames {
+  repeated EncodedVideoFrame frames = 1;
+}
+
+// 视频帧
+message VideoFrame {
+  oneof union {
+    EncodedVideoFrames vp9s = 6;
+    RGB rgb = 7;
+    YUV yuv = 8;
+    EncodedVideoFrames h264s = 10;
+    EncodedVideoFrames h265s = 11;
+    EncodedVideoFrames vp8s = 12;
+    EncodedVideoFrames av1s = 13;
+  }
+  int32 display = 14;  // 显示器索引
+}
+
+// 显示信息
+message DisplayInfo {
+  sint32 x = 1;
+  sint32 y = 2;
+  int32 width = 3;
+  int32 height = 4;
+  string name = 5;
+  bool online = 6;
+  bool cursor_embedded = 7;
+  Resolution original_resolution = 8;
+  double scale = 9;
+}
+```
+
+### 输入相关
+
+```protobuf
+// 鼠标事件
+message MouseEvent {
+  int32 mask = 1;      // 按钮掩码
+  sint32 x = 2;
+  sint32 y = 3;
+  repeated ControlKey modifiers = 4;
+}
+
+// 键盘事件
+message KeyEvent {
+  bool down = 1;       // 按下/释放
+  bool press = 2;      // 单击
+  oneof union {
+    ControlKey control_key = 3;
+    uint32 chr = 4;         // 字符码
+    uint32 unicode = 5;     // Unicode
+    string seq = 6;         // 字符序列
+    uint32 win2win_hotkey = 7;
+  }
+  repeated ControlKey modifiers = 8;
+  KeyboardMode mode = 9;
+}
+
+// 键盘模式
+enum KeyboardMode {
+  Legacy = 0;
+  Map = 1;
+  Translate = 2;
+  Auto = 3;
+}
+
+// 控制键枚举（部分）
+enum ControlKey {
+  Unknown = 0;
+  Alt = 1;
+  Backspace = 2;
+  CapsLock = 3;
+  Control = 4;
+  Delete = 5;
+  // ... 更多按键
+  CtrlAltDel = 100;
+  LockScreen = 101;
+}
+```
+
+### 音频相关
+
+```protobuf
+// 音频格式
+message AudioFormat {
+  uint32 sample_rate = 1;
+  uint32 channels = 2;
+}
+
+// 音频帧
+message AudioFrame {
+  bytes data = 1;  // Opus 编码数据
+}
+```
+
+### 剪贴板相关
+
+```protobuf
+// 剪贴板格式
+enum ClipboardFormat {
+  Text = 0;
+  Rtf = 1;
+  Html = 2;
+  ImageRgba = 21;
+  ImagePng = 22;
+  ImageSvg = 23;
+  Special = 31;
+}
+
+// 剪贴板内容
+message Clipboard {
+  bool compress = 1;
+  bytes content = 2;
+  int32 width = 3;
+  int32 height = 4;
+  ClipboardFormat format = 5;
+  string special_name = 6;
+}
+
+message MultiClipboards {
+  repeated Clipboard clipboards = 1;
+}
+```
+
+### 文件传输相关
+
+```protobuf
+// 文件操作
+message FileAction {
+  oneof union {
+    ReadDir read_dir = 1;
+    FileTransferSendRequest send = 2;
+    FileTransferReceiveRequest receive = 3;
+    FileDirCreate create = 4;
+    FileRemoveDir remove_dir = 5;
+    FileRemoveFile remove_file = 6;
+    ReadAllFiles all_files = 7;
+    FileTransferCancel cancel = 8;
+    FileTransferSendConfirmRequest send_confirm = 9;
+    FileRename rename = 10;
+    ReadEmptyDirs read_empty_dirs = 11;
+  }
+}
+
+// 文件响应
+message FileResponse {
+  oneof union {
+    FileDirectory dir = 1;
+    FileTransferBlock block = 2;
+    FileTransferError error = 3;
+    FileTransferDone done = 4;
+    FileTransferDigest digest = 5;
+    ReadEmptyDirsResponse empty_dirs = 6;
+  }
+}
+
+// 文件传输块
+message FileTransferBlock {
+  int32 id = 1;
+  sint32 file_num = 2;
+  bytes data = 3;
+  bool compressed = 4;
+  uint32 blk_id = 5;
+}
+
+// 文件条目
+message FileEntry {
+  FileType entry_type = 1;
+  string name = 2;
+  bool is_hidden = 3;
+  uint64 size = 4;
+  uint64 modified_time = 5;
+}
+```
+
+### 杂项消息
+
+```protobuf
+message Misc {
+  oneof union {
+    ChatMessage chat_message = 4;
+    SwitchDisplay switch_display = 5;
+    PermissionInfo permission_info = 6;
+    OptionMessage option = 7;
+    AudioFormat audio_format = 8;
+    string close_reason = 9;
+    bool refresh_video = 10;
+    bool video_received = 12;
+    BackNotification back_notification = 13;
+    bool restart_remote_device = 14;
+    // ... 更多选项
+  }
+}
+
+// Peer 信息
+message PeerInfo {
+  string username = 1;
+  string hostname = 2;
+  string platform = 3;
+  repeated DisplayInfo displays = 4;
+  int32 current_display = 5;
+  bool sas_enabled = 6;
+  string version = 7;
+  Features features = 9;
+  SupportedEncoding encoding = 10;
+  SupportedResolutions resolutions = 11;
+  string platform_additions = 12;
+  WindowsSessions windows_sessions = 13;
+}
+
+// 选项消息
+message OptionMessage {
+  enum BoolOption {
+    NotSet = 0;
+    No = 1;
+    Yes = 2;
+  }
+  ImageQuality image_quality = 1;
+  BoolOption lock_after_session_end = 2;
+  BoolOption show_remote_cursor = 3;
+  BoolOption privacy_mode = 4;
+  BoolOption block_input = 5;
+  int32 custom_image_quality = 6;
+  BoolOption disable_audio = 7;
+  BoolOption disable_clipboard = 8;
+  BoolOption enable_file_transfer = 9;
+  SupportedDecoding supported_decoding = 10;
+  int32 custom_fps = 11;
+  // ... 更多选项
+}
+```
+
+## 消息编码
+
+### 长度前缀
+
+TCP 传输时使用长度前缀编码：
+
+```rust
+// hbb_common/src/bytes_codec.rs
+pub struct BytesCodec {
+    state: DecodeState,
+    raw: bool,
+}
+
+impl Decoder for BytesCodec {
+    type Item = BytesMut;
+    type Error = std::io::Error;
+
+    fn decode(&mut self, buf: &mut BytesMut) -> Result<Option<BytesMut>, Self::Error> {
+        if self.raw {
+            // 原始模式：直接返回数据
+            if buf.is_empty() {
+                Ok(None)
+            } else {
+                Ok(Some(buf.split()))
+            }
+        } else {
+            // 标准模式：4 字节长度前缀 + 数据
+            match self.state {
+                DecodeState::Head => {
+                    if buf.len() < 4 {
+                        return Ok(None);
+                    }
+                    let len = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]) as usize;
+                    buf.advance(4);
+                    self.state = DecodeState::Data(len);
+                    self.decode(buf)
+                }
+                DecodeState::Data(len) => {
+                    if buf.len() < len {
+                        return Ok(None);
+                    }
+                    let data = buf.split_to(len);
+                    self.state = DecodeState::Head;
+                    Ok(Some(data))
+                }
+            }
+        }
+    }
+}
+```
+
+### 加密模式
+
+当启用加密时，消息结构为：
+
+```
+┌─────────────┬─────────────┬─────────────────────────┐
+│  Length(4)  │  Nonce(8)   │  Encrypted Data(N)      │
+└─────────────┴─────────────┴─────────────────────────┘
+```

docs/report/rustdesk/06-encryption.md

@@ -0,0 +1,342 @@
+# 加密机制
+
+## 概述
+
+RustDesk 使用 libsodium (sodiumoxide) 库实现端到端加密，主要包含：
+
+- **Ed25519**: 用于身份签名和验证
+- **X25519**: 用于密钥交换
+- **ChaCha20-Poly1305**: 用于对称加密
+
+## 密钥类型
+
+### 1. 身份密钥对 (Ed25519)
+
+用于 Peer 身份认证和签名：
+
+```rust
+// 生成密钥对
+use sodiumoxide::crypto::sign;
+let (pk, sk) = sign::gen_keypair();
+// pk: sign::PublicKey (32 bytes)
+// sk: sign::SecretKey (64 bytes)
+```
+
+### 2. 服务器签名密钥
+
+Rendezvous Server 可以配置签名密钥，用于签名 Peer 公钥：
+
+```rust
+// rustdesk-server/src/rendezvous_server.rs:1185-1210
+fn get_server_sk(key: &str) -> (String, Option<sign::SecretKey>) {
+    let mut out_sk = None;
+    let mut key = key.to_owned();
+
+    // 如果是 base64 编码的私钥
+    if let Ok(sk) = base64::decode(&key) {
+        if sk.len() == sign::SECRETKEYBYTES {
+            log::info!("The key is a crypto private key");
+            key = base64::encode(&sk[(sign::SECRETKEYBYTES / 2)..]);  // 公钥部分
+            let mut tmp = [0u8; sign::SECRETKEYBYTES];
+            tmp[..].copy_from_slice(&sk);
+            out_sk = Some(sign::SecretKey(tmp));
+        }
+    }
+
+    // 如果是占位符，生成新密钥对
+    if key.is_empty() || key == "-" || key == "_" {
+        let (pk, sk) = crate::common::gen_sk(0);
+        out_sk = sk;
+        if !key.is_empty() {
+            key = pk;
+        }
+    }
+
+    if !key.is_empty() {
+        log::info!("Key: {}", key);
+    }
+    (key, out_sk)
+}
+```
+
+### 3. 会话密钥 (X25519 + ChaCha20)
+
+用于客户端之间的加密通信：
+
+```rust
+// hbb_common/src/tcp.rs:27-28
+#[derive(Clone)]
+pub struct Encrypt(pub Key, pub u64, pub u64);
+// Key: secretbox::Key (32 bytes)
+// u64: 发送计数器
+// u64: 接收计数器
+```
+
+## 密钥交换流程
+
+### 1. 身份验证
+
+客户端首先交换签名的身份：
+
+```protobuf
+message IdPk {
+  string id = 1;   // Peer ID
+  bytes pk = 2;    // Ed25519 公钥
+}
+
+message SignedId {
+  bytes id = 1;    // 签名的 IdPk (by server or self)
+}
+```
+
+### 2. X25519 密钥交换
+
+使用 X25519 ECDH 生成共享密钥：
+
+```rust
+// 生成临时密钥对
+use sodiumoxide::crypto::box_;
+let (our_pk, our_sk) = box_::gen_keypair();
+
+// 计算共享密钥
+let shared_secret = box_::curve25519xsalsa20poly1305::scalarmult(&our_sk, &their_pk);
+
+// 派生对称密钥
+let symmetric_key = secretbox::Key::from_slice(&shared_secret[..32]).unwrap();
+```
+
+### 3. 对称密钥消息
+
+```protobuf
+message PublicKey {
+  bytes asymmetric_value = 1;  // X25519 公钥
+  bytes symmetric_value = 2;   // 加密的对称密钥（用于额外安全）
+}
+```
+
+## 会话加密
+
+### 加密实现
+
+```rust
+// hbb_common/src/tcp.rs
+impl Encrypt {
+    pub fn new(key: Key) -> Self {
+        Self(key, 0, 0)  // 初始化计数器为 0
+    }
+
+    // 加密
+    pub fn enc(&mut self, data: &[u8]) -> Vec<u8> {
+        self.1 += 1;  // 递增发送计数器
+        let nonce = self.get_nonce(self.1);
+        let encrypted = secretbox::seal(data, &nonce, &self.0);
+
+        // 格式: nonce (8 bytes) + encrypted data
+        let mut result = Vec::with_capacity(8 + encrypted.len());
+        result.extend_from_slice(&self.1.to_le_bytes());
+        result.extend_from_slice(&encrypted);
+        result
+    }
+
+    // 解密
+    pub fn dec(&mut self, data: &mut BytesMut) -> io::Result<()> {
+        if data.len() < 8 + secretbox::MACBYTES {
+            return Err(io::Error::new(io::ErrorKind::InvalidData, "too short"));
+        }
+
+        // 提取 nonce
+        let counter = u64::from_le_bytes(data[..8].try_into().unwrap());
+
+        // 防重放攻击检查
+        if counter <= self.2 {
+            return Err(io::Error::new(io::ErrorKind::InvalidData, "replay attack"));
+        }
+        self.2 = counter;
+
+        let nonce = self.get_nonce(counter);
+        let plaintext = secretbox::open(&data[8..], &nonce, &self.0)
+            .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "decrypt failed"))?;
+
+        data.clear();
+        data.extend_from_slice(&plaintext);
+        Ok(())
+    }
+
+    fn get_nonce(&self, counter: u64) -> Nonce {
+        let mut nonce = [0u8; 24];
+        nonce[..8].copy_from_slice(&counter.to_le_bytes());
+        Nonce(nonce)
+    }
+}
+```
+
+### 消息格式
+
+加密后的消息结构：
+
+```
+┌──────────────────┬─────────────────────────────────────────┐
+│   Counter (8B)   │   Encrypted Data + MAC (N+16 bytes)     │
+└──────────────────┴─────────────────────────────────────────┘
+```
+
+## 密码验证
+
+### 挑战-响应机制
+
+被控端生成随机盐和挑战，控制端计算哈希响应：
+
+```protobuf
+message Hash {
+  string salt = 1;       // 随机盐
+  string challenge = 2;  // 随机挑战
+}
+```
+
+### 密码处理
+
+```rust
+// 客户端计算密码哈希
+fn get_password_hash(password: &str, salt: &str) -> Vec<u8> {
+    let mut hasher = Sha256::new();
+    hasher.update(password.as_bytes());
+    hasher.update(salt.as_bytes());
+    hasher.finalize().to_vec()
+}
+
+// 发送加密的密码（使用对称密钥加密）
+fn encrypt_password(password_hash: &[u8], symmetric_key: &Key) -> Vec<u8> {
+    secretbox::seal(password_hash, &nonce, symmetric_key)
+}
+```
+
+## 服务器公钥验证
+
+### 签名验证
+
+如果 Rendezvous Server 配置了密钥，会签名 Peer 公钥：
+
+```rust
+// 服务器签名 IdPk
+let signed_id_pk = sign::sign(
+    &IdPk { id, pk, ..Default::default() }
+        .write_to_bytes()?,
+    &server_sk,
+);
+
+// 客户端验证
+fn verify_server_signature(signed_pk: &[u8], server_pk: &sign::PublicKey) -> Option<IdPk> {
+    if let Ok(verified) = sign::verify(signed_pk, server_pk) {
+        return IdPk::parse_from_bytes(&verified).ok();
+    }
+    None
+}
+```
+
+### 客户端获取服务器公钥
+
+```rust
+pub async fn get_rs_pk(id: &str) -> ResultType<(String, sign::PublicKey)> {
+    // 从配置或 Rendezvous Server 获取公钥
+    let key = Config::get_option("key");
+    if !key.is_empty() {
+        if let Ok(pk) = base64::decode(&key) {
+            if pk.len() == sign::PUBLICKEYBYTES {
+                return Ok((key, sign::PublicKey::from_slice(&pk).unwrap()));
+            }
+        }
+    }
+    // ... 从服务器获取
+}
+```
+
+## TCP 连接加密
+
+### 安全 TCP 握手
+
+```rust
+// rustdesk/src/common.rs
+pub async fn secure_tcp(conn: &mut Stream, key: &str) -> ResultType<()> {
+    // 1. 生成临时 X25519 密钥对
+    let (our_pk, our_sk) = box_::gen_keypair();
+
+    // 2. 发送我们的公钥
+    let mut msg = Message::new();
+    msg.set_public_key(PublicKey {
+        asymmetric_value: our_pk.0.to_vec().into(),
+        ..Default::default()
+    });
+    conn.send(&msg).await?;
+
+    // 3. 接收对方公钥
+    let msg = conn.next_timeout(CONNECT_TIMEOUT).await?
+        .ok_or_else(|| anyhow!("timeout"))?;
+    let their_pk = msg.get_public_key();
+
+    // 4. 计算共享密钥
+    let shared = box_::curve25519xsalsa20poly1305::scalarmult(
+        &our_sk,
+        &box_::PublicKey::from_slice(&their_pk.asymmetric_value)?,
+    );
+
+    // 5. 设置加密
+    conn.set_key(secretbox::Key::from_slice(&shared[..32]).unwrap());
+    Ok(())
+}
+```
+
+## 安全特性
+
+### 1. 前向保密
+
+每个会话使用临时密钥对，即使长期密钥泄露，历史会话仍然安全。
+
+### 2. 重放攻击防护
+
+使用递增计数器作为 nonce 的一部分，拒绝旧的或重复的消息。
+
+### 3. 中间人攻击防护
+
+- 服务器签名 Peer 公钥
+- 可配置服务器公钥验证
+
+### 4. 密码暴力破解防护
+
+- 使用盐和多次哈希
+- 服务器端限流
+
+## 加密算法参数
+
+| 算法 | 密钥大小 | Nonce 大小 | MAC 大小 |
+|------|----------|------------|----------|
+| Ed25519 | 64 bytes (private), 32 bytes (public) | N/A | 64 bytes |
+| X25519 | 32 bytes | N/A | N/A |
+| ChaCha20-Poly1305 | 32 bytes | 24 bytes | 16 bytes |
+
+## 密钥生命周期
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     长期密钥 (Ed25519)                        │
+│  ┌─────────────────┐                                        │
+│  │ 设备首次启动时生成 │                                        │
+│  │ 存储在配置文件中  │                                        │
+│  └─────────────────┘                                        │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     会话密钥 (X25519)                        │
+│  ┌─────────────────┐    ┌─────────────────┐                 │
+│  │ 每次连接时生成    │───►│ 用于密钥协商     │                 │
+│  │ 临时密钥对       │    │ 派生对称密钥     │                 │
+│  └─────────────────┘    └─────────────────┘                 │
+│                              │                              │
+│                              ▼                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              对称密钥 (ChaCha20-Poly1305)            │   │
+│  │              用于会话中的所有消息加密                   │   │
+│  │              会话结束时销毁                            │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```

docs/report/rustdesk/07-nat-traversal.md

@@ -0,0 +1,410 @@
+# NAT 穿透技术
+
+## 概述
+
+RustDesk 实现了多种 NAT 穿透技术，以在不同网络环境下建立 P2P 连接：
+
+- NAT 类型检测
+- UDP 打洞
+- TCP 打洞
+- Relay 中转（作为后备）
+
+## NAT 类型
+
+### 分类
+
+```protobuf
+enum NatType {
+  UNKNOWN_NAT = 0;   // 未知
+  ASYMMETRIC = 1;    // 非对称 NAT (Cone NAT) - 可打洞
+  SYMMETRIC = 2;     // 对称 NAT - 通常需要 Relay
+}
+```
+
+### NAT 类型说明
+
+| 类型 | 描述 | 可打洞 |
+|------|------|--------|
+| Full Cone | 外部端口固定，任何外部主机可访问 | ✅ 最容易 |
+| Restricted Cone | 外部端口固定，仅允许曾发送过数据的 IP | ✅ 容易 |
+| Port Restricted Cone | 外部端口固定，仅允许曾发送过数据的 IP:Port | ✅ 可能 |
+| Symmetric | 每个目标地址使用不同外部端口 | ❌ 困难 |
+
+## NAT 类型检测
+
+### 检测原理
+
+RustDesk 使用双端口检测法：
+
+1. 客户端向 Rendezvous Server 的主端口 (21116) 发送 TestNatRequest
+2. 同时向 NAT 测试端口 (21115) 发送 TestNatRequest
+3. 比较两次响应中观测到的源端口
+
+```
+客户端                    Rendezvous Server
+   │                           │
+   │   TestNatRequest ────────►│ Port 21116
+   │                           │
+   │   TestNatRequest ────────►│ Port 21115
+   │                           │
+   │◄──────── TestNatResponse  │ (包含观测到的源端口)
+   │                           │
+   │                           │
+   │ 比较两次源端口             │
+   │ 相同 → ASYMMETRIC         │
+   │ 不同 → SYMMETRIC           │
+```
+
+### 实现代码
+
+**客户端发送检测请求：**
+
+```rust
+// rustdesk/src/lib.rs
+pub fn test_nat_type() {
+    tokio::spawn(async move {
+        let rendezvous_server = Config::get_rendezvous_servers().first().cloned();
+        if let Some(host) = rendezvous_server {
+            // 连接主端口
+            let host = check_port(&host, RENDEZVOUS_PORT);
+
+            // 连接 NAT 测试端口
+            let host2 = crate::increase_port(&host, -1);
+
+            // 发送测试请求
+            let mut msg = RendezvousMessage::new();
+            msg.set_test_nat_request(TestNatRequest {
+                serial: Config::get_serial(),
+            });
+
+            // 收集两次响应的端口
+            let port1 = send_and_get_port(&host, &msg).await;
+            let port2 = send_and_get_port(&host2, &msg).await;
+
+            // 判断 NAT 类型
+            let nat_type = if port1 == port2 {
+                NatType::ASYMMETRIC  // 可打洞
+            } else {
+                NatType::SYMMETRIC   // 需要 Relay
+            };
+
+            Config::set_nat_type(nat_type as i32);
+        }
+    });
+}
+```
+
+**服务器响应：**
+
+```rust
+// rustdesk-server/src/rendezvous_server.rs:1080-1087
+Some(rendezvous_message::Union::TestNatRequest(_)) => {
+    let mut msg_out = RendezvousMessage::new();
+    msg_out.set_test_nat_response(TestNatResponse {
+        port: addr.port() as _,  // 返回观测到的源端口
+        ..Default::default()
+    });
+    stream.send(&msg_out).await.ok();
+}
+```
+
+## UDP 打洞
+
+### 原理
+
+UDP 打洞利用 NAT 的端口映射机制：
+
+```
+    A (内网)                                             B (内网)
+       │                                                    │
+       │ ──► NAT_A ──► Internet ──► NAT_B ──► (丢弃)        │
+       │                                                    │
+       │                                                    │
+       │ (NAT_A 创建了映射 A:port → A_ext:port_a)           │
+       │                                                    │
+       │                                                    │
+       │ (丢弃) ◄── NAT_A ◄── Internet ◄── NAT_B ◄── │
+       │                                                    │
+       │                                                    │
+       │ (NAT_B 创建了映射 B:port → B_ext:port_b)           │
+       │                                                    │
+       │ ──► NAT_A ──► Internet ──► NAT_B ──► │
+       │ (NAT_A 的映射存在，包被转发)                        │
+       │                                                    │
+       │ ◄── NAT_A ◄── Internet ◄── NAT_B ◄── │
+       │ (NAT_B 的映射存在，包被转发)                        │
+       │                                                    │
+       │ ◄───────── 双向通信建立 ──────────► │
+```
+
+### 实现
+
+**被控端打洞：**
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:621-642
+async fn punch_udp_hole(
+    &self,
+    peer_addr: SocketAddr,
+    server: ServerPtr,
+    msg_punch: PunchHoleSent,
+) -> ResultType<()> {
+    let mut msg_out = Message::new();
+    msg_out.set_punch_hole_sent(msg_punch);
+
+    // 创建 UDP socket
+    let (socket, addr) = new_direct_udp_for(&self.host).await?;
+    let data = msg_out.write_to_bytes()?;
+
+    // 发送到 Rendezvous Server（会转发给控制端）
+    socket.send_to(&data, addr).await?;
+
+    // 多次发送以增加成功率
+    let socket_cloned = socket.clone();
+    tokio::spawn(async move {
+        for _ in 0..2 {
+            let tm = (hbb_common::time_based_rand() % 20 + 10) as f32 / 1000.;
+            hbb_common::sleep(tm).await;
+            socket.send_to(&data, addr).await.ok();
+        }
+    });
+
+    // 等待对方连接
+    udp_nat_listen(socket_cloned, peer_addr, peer_addr, server).await?;
+    Ok(())
+}
+```
+
+**UDP 监听和 KCP 建立：**
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:824-851
+async fn udp_nat_listen(
+    socket: Arc<tokio::net::UdpSocket>,
+    peer_addr: SocketAddr,
+    peer_addr_v4: SocketAddr,
+    server: ServerPtr,
+) -> ResultType<()> {
+    // 连接到对方地址
+    socket.connect(peer_addr).await?;
+
+    // 执行 UDP 打洞
+    let res = crate::punch_udp(socket.clone(), true).await?;
+
+    // 建立 KCP 可靠传输层
+    let stream = crate::kcp_stream::KcpStream::accept(
+        socket,
+        Duration::from_millis(CONNECT_TIMEOUT as _),
+        res,
+    ).await?;
+
+    // 创建连接
+    crate::server::create_tcp_connection(server, stream.1, peer_addr_v4, true).await?;
+    Ok(())
+}
+```
+
+### KCP 协议
+
+RustDesk 在 UDP 上使用 KCP 提供可靠传输，KCP 特点：
+
+- 更激进的重传策略
+- 更低的延迟
+- 可配置的可靠性级别
+
+## TCP 打洞
+
+### 原理
+
+TCP 打洞比 UDP 困难，因为 TCP 需要三次握手。技巧是让双方同时发起连接：
+
+```
+    A                       NAT_A     NAT_B                       B
+    │                         │         │                         │
+    │ ─── SYN ───────────────►│─────────│────► (丢弃，无映射)     │
+    │                         │         │                         │
+    │ (NAT_A 创建到 B 的映射)  │         │                         │
+    │                         │         │                         │
+    │ (丢弃，无映射) ◄─────────│─────────│◄─── SYN ───────────── │
+    │                         │         │                         │
+    │                         │         │ (NAT_B 创建到 A 的映射)  │
+    │                         │         │                         │
+    │ ─── SYN ───────────────►│─────────│────► SYN ───────────► │
+    │                         │         │ (映射存在，转发成功)     │
+    │                         │         │                         │
+    │ ◄─── SYN+ACK ──────────│─────────│◄─── SYN+ACK ───────── │
+    │                         │         │                         │
+    │ ─── ACK ───────────────►│─────────│────► ACK ───────────► │
+    │                         │         │                         │
+    │ ◄─────────── 连接建立 ─────────────────────────────────────►│
+```
+
+### 实现
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:604-617
+log::debug!("Punch tcp hole to {:?}", peer_addr);
+let mut socket = {
+    // 1. 先连接 Rendezvous Server 获取本地地址
+    let socket = connect_tcp(&*self.host, CONNECT_TIMEOUT).await?;
+    let local_addr = socket.local_addr();
+
+    // 2. 用相同的本地地址尝试连接对方
+    // 这会在 NAT 上创建映射
+    // 虽然连接会失败，但映射已建立
+    allow_err!(socket_client::connect_tcp_local(peer_addr, Some(local_addr), 30).await);
+
+    socket
+};
+
+// 3. 发送 PunchHoleSent 通知服务器
+// 服务器会转发给控制端
+let mut msg_out = Message::new();
+msg_out.set_punch_hole_sent(msg_punch);
+socket.send_raw(msg_out.write_to_bytes()?).await?;
+
+// 4. 等待控制端连接
+// 由于已有映射，控制端的连接可以成功
+crate::accept_connection(server.clone(), socket, peer_addr, true).await;
+```
+
+## 局域网直连
+
+### 检测同一局域网
+
+```rust
+// rustdesk-server/src/rendezvous_server.rs:721-728
+let same_intranet: bool = !ws
+    && (peer_is_lan && is_lan || {
+        match (peer_addr, addr) {
+            (SocketAddr::V4(a), SocketAddr::V4(b)) => a.ip() == b.ip(),
+            (SocketAddr::V6(a), SocketAddr::V6(b)) => a.ip() == b.ip(),
+            _ => false,
+        }
+    });
+```
+
+### 局域网连接流程
+
+```
+控制端              Rendezvous Server              被控端
+   │                       │                          │
+   │ PunchHoleRequest ────►│                          │
+   │                       │                          │
+   │                       │ (检测到同一局域网)         │
+   │                       │                          │
+   │                       │    FetchLocalAddr ──────►│
+   │                       │                          │
+   │                       │◄────── LocalAddr ────────│
+   │                       │   (包含被控端内网地址)     │
+   │                       │                          │
+   │◄─ PunchHoleResponse ──│                          │
+   │  (is_local=true)      │                          │
+   │  (socket_addr=内网地址)│                          │
+   │                       │                          │
+   │ ─────────── 直接连接内网地址 ────────────────────►│
+```
+
+## IPv6 支持
+
+IPv6 通常不需要 NAT 穿透，但 RustDesk 仍支持 IPv6 打洞以处理有状态防火墙：
+
+```rust
+// rustdesk/src/rendezvous_mediator.rs:808-822
+async fn start_ipv6(
+    peer_addr_v6: SocketAddr,
+    peer_addr_v4: SocketAddr,
+    server: ServerPtr,
+) -> bytes::Bytes {
+    crate::test_ipv6().await;
+    if let Some((socket, local_addr_v6)) = crate::get_ipv6_socket().await {
+        let server = server.clone();
+        tokio::spawn(async move {
+            allow_err!(udp_nat_listen(socket.clone(), peer_addr_v6, peer_addr_v4, server).await);
+        });
+        return local_addr_v6;
+    }
+    Default::default()
+}
+```
+
+## 连接策略决策树
+
+```
+                         开始连接
+                            │
+                            ▼
+                   ┌───────────────┐
+                   │  NAT 类型检测  │
+                   └───────┬───────┘
+                           │
+           ┌───────────────┼───────────────┐
+           │               │               │
+           ▼               ▼               ▼
+      ASYMMETRIC       UNKNOWN        SYMMETRIC
+           │               │               │
+           ▼               ▼               │
+     ┌──────────┐    ┌──────────┐         │
+     │ 尝试 UDP  │    │ 尝试 TCP  │         │
+     │ 打洞     │    │ 打洞     │         │
+     └────┬─────┘    └────┬─────┘         │
+          │               │               │
+     成功  │  失败    成功  │  失败         │
+          ▼    │          ▼    │          │
+     ┌────────┐│     ┌────────┐│          │
+     │UDP P2P ││     │TCP P2P ││          │
+     └────────┘│     └────────┘│          │
+               │               │          │
+               └───────┬───────┘          │
+                       │                  │
+                       ▼                  │
+               ┌───────────────┐          │
+               │   使用 Relay   │◄─────────┘
+               └───────────────┘
+```
+
+## 性能优化
+
+### 多路径尝试
+
+RustDesk 同时尝试多种连接方式，选择最快成功的：
+
+```rust
+// rustdesk/src/client.rs:342-364
+let mut connect_futures = Vec::new();
+
+// 同时尝试 UDP 和 TCP
+if udp.0.is_some() {
+    connect_futures.push(Self::_start_inner(..., udp).boxed());
+}
+connect_futures.push(Self::_start_inner(..., (None, None)).boxed());
+
+// 使用 select_ok 选择第一个成功的
+match select_ok(connect_futures).await {
+    Ok(conn) => Ok(conn),
+    Err(e) => Err(e),
+}
+```
+
+### 超时控制
+
+```rust
+const CONNECT_TIMEOUT: u64 = 18_000;  // 18 秒
+const REG_TIMEOUT: i32 = 30_000;      // 30 秒
+
+// 连接超时处理
+if let Ok(Ok((stream, addr))) = timeout(CONNECT_TIMEOUT, socket.accept()).await {
+    // 连接成功
+} else {
+    // 超时，尝试其他方式
+}
+```
+
+## 常见问题和解决方案
+
+| 问题 | 原因 | 解决方案 |
+|------|------|----------|
+| 双 Symmetric NAT | 两端都是对称 NAT | 使用 Relay |
+| 防火墙阻止 UDP | 企业防火墙 | 使用 TCP 或 WebSocket |
+| 端口预测失败 | NAT 端口分配不规律 | 多次尝试或使用 Relay |
+| IPv6 不通 | ISP 或防火墙问题 | 回退到 IPv4 |

docs/report/rustdesk/08-onekvm-comparison.md

@@ -0,0 +1,401 @@
+# RustDesk 协议 vs One-KVM 实现对比分析
+
+本文档对比分析 RustDesk 原始协议与 One-KVM 的实现差异。
+
+## 1. 概述
+
+One-KVM 作为 IP-KVM 解决方案，只实现了 RustDesk 协议的**被控端（Controlled）** 功能，不实现控制端（Controller）功能。这是设计决策，因为 KVM 设备只需要接收远程控制，不需要控制其他设备。
+
+### 架构差异
+
+| 方面 | RustDesk 原版 | One-KVM |
+|------|---------------|---------|
+| 角色 | 双向（控制端+被控端） | 单向（仅被控端） |
+| 连接方式 | P2P + Relay | 仅 Relay (TCP) |
+| NAT 穿透 | UDP/TCP 打洞 + TURN | 不支持 |
+| 传输协议 | UDP/TCP | 仅 TCP |
+
+## 2. 已实现功能
+
+### 2.1 Rendezvous 协议 (hbbs 通信)
+
+| 消息类型 | 实现状态 | 备注 |
+|----------|----------|------|
+| RegisterPeer | ✅ 已实现 | 注册设备到服务器 |
+| RegisterPeerResponse | ✅ 已实现 | 处理注册响应 |
+| RegisterPk | ✅ 已实现 | 注册公钥 |
+| RegisterPkResponse | ✅ 已实现 | 处理公钥注册响应 |
+| PunchHoleSent | ✅ 已实现 | 响应打洞请求 |
+| FetchLocalAddr | ✅ 已实现 | 获取本地地址 |
+| LocalAddr | ✅ 已实现 | 返回本地地址 |
+| RequestRelay | ✅ 已实现 | 请求中继连接 |
+| RelayResponse | ✅ 已实现 | 处理中继响应 |
+| ConfigUpdate | ✅ 已实现 | 接收配置更新 |
+
+**实现文件**: `src/rustdesk/rendezvous.rs` (~829 行)
+
+```rust
+// 核心结构
+pub struct RendezvousMediator {
+    config: RustDeskConfig,
+    key_pair: KeyPair,
+    signing_key: SigningKeyPair,
+    socket: UdpSocket,
+    status: Arc<RwLock<RendezvousStatus>>,
+    // ...
+}
+```
+
+### 2.2 连接协议 (客户端连接)
+
+| 消息类型 | 实现状态 | 备注 |
+|----------|----------|------|
+| SignedId | ✅ 已实现 | 签名身份验证 |
+| PublicKey | ✅ 已实现 | 公钥交换 |
+| Hash | ✅ 已实现 | 哈希挑战响应 |
+| LoginRequest | ✅ 已实现 | 登录认证 |
+| LoginResponse | ✅ 已实现 | 登录响应 |
+| TestDelay | ✅ 已实现 | 延迟测试 |
+| VideoFrame | ✅ 已实现 | 视频帧发送 |
+| AudioFrame | ✅ 已实现 | 音频帧发送 |
+| CursorData | ✅ 已实现 | 光标图像 |
+| CursorPosition | ✅ 已实现 | 光标位置 |
+| MouseEvent | ✅ 已实现 | 鼠标事件接收 |
+| KeyEvent | ✅ 已实现 | 键盘事件接收 |
+
+**实现文件**: `src/rustdesk/connection.rs` (~1349 行)
+
+```rust
+// 连接状态机
+pub enum ConnectionState {
+    WaitingForSignedId,
+    WaitingForPublicKey,
+    WaitingForHash,
+    WaitingForLogin,
+    Authenticated,
+    Streaming,
+}
+```
+
+### 2.3 加密模块
+
+| 功能 | 实现状态 | 备注 |
+|------|----------|------|
+| Curve25519 密钥对 | ✅ 已实现 | 用于加密 |
+| Ed25519 签名密钥对 | ✅ 已实现 | 用于签名 |
+| Ed25519 → Curve25519 转换 | ✅ 已实现 | 密钥派生 |
+| XSalsa20-Poly1305 | ✅ 已实现 | 会话加密 (secretbox) |
+| 密码哈希 | ✅ 已实现 | 单重/双重 SHA256 |
+| 会话密钥协商 | ✅ 已实现 | 对称密钥派生 |
+
+**实现文件**: `src/rustdesk/crypto.rs` (~468 行)
+
+```rust
+// 密钥对结构
+pub struct KeyPair {
+    secret_key: [u8; 32],  // Curve25519 私钥
+    public_key: [u8; 32],  // Curve25519 公钥
+}
+
+pub struct SigningKeyPair {
+    secret_key: [u8; 64],  // Ed25519 私钥
+    public_key: [u8; 32],  // Ed25519 公钥
+}
+```
+
+### 2.4 视频/音频流
+
+| 编码格式 | 实现状态 | 备注 |
+|----------|----------|------|
+| H.264 | ✅ 已实现 | 主要格式 |
+| H.265/HEVC | ✅ 已实现 | 高效编码 |
+| VP8 | ✅ 已实现 | WebRTC 兼容 |
+| VP9 | ✅ 已实现 | 高质量 |
+| AV1 | ✅ 已实现 | 新一代编码 |
+| Opus 音频 | ✅ 已实现 | 低延迟音频 |
+
+**实现文件**: `src/rustdesk/frame_adapters.rs` (~316 行)
+
+### 2.5 HID 事件
+
+| 功能 | 实现状态 | 备注 |
+|------|----------|------|
+| 鼠标移动 | ✅ 已实现 | 绝对/相对坐标 |
+| 鼠标按键 | ✅ 已实现 | 左/中/右键 |
+| 鼠标滚轮 | ✅ 已实现 | 垂直滚动 |
+| 键盘按键 | ✅ 已实现 | 按下/释放 |
+| 控制键映射 | ✅ 已实现 | ControlKey → USB HID |
+| X11 键码映射 | ✅ 已实现 | X11 → USB HID |
+
+**实现文件**: `src/rustdesk/hid_adapter.rs` (~386 行)
+
+### 2.6 协议帧编码
+
+| 功能 | 实现状态 | 备注 |
+|------|----------|------|
+| BytesCodec | ✅ 已实现 | 变长帧编码 |
+| 1-4 字节头 | ✅ 已实现 | 根据长度自动选择 |
+| 最大 1GB 消息 | ✅ 已实现 | 与原版一致 |
+
+**实现文件**: `src/rustdesk/bytes_codec.rs` (~253 行)
+
+## 3. 未实现功能
+
+### 3.1 NAT 穿透相关
+
+| 功能 | 原因 |
+|------|------|
+| UDP 打洞 | One-KVM 仅使用 TCP 中继 |
+| TCP 打洞 | 同上 |
+| STUN/TURN | 不需要 NAT 类型检测 |
+| TestNat | 同上 |
+| P2P 直连 | 设计简化，仅支持中继 |
+
+### 3.2 客户端发起功能
+
+| 功能 | 原因 |
+|------|------|
+| PunchHole (发起) | KVM 只接收连接 |
+| RelayRequest | 同上 |
+| ConnectPeer | 同上 |
+| OnlineRequest | 不需要查询其他设备 |
+
+### 3.3 文件传输
+
+| 功能 | 原因 |
+|------|------|
+| FileTransfer | 超出 KVM 功能范围 |
+| FileAction | 同上 |
+| FileResponse | 同上 |
+| FileTransferBlock | 同上 |
+
+### 3.4 高级功能
+
+| 功能 | 原因 |
+|------|------|
+| 剪贴板同步 | 超出 KVM 功能范围 |
+| 多显示器切换 | One-KVM 使用单一视频源 |
+| 虚拟显示器 | 不适用 |
+| 端口转发 | 超出 KVM 功能范围 |
+| 语音通话 | 不需要 |
+| RDP 输入 | 不需要 |
+| 插件系统 | 不支持 |
+| 软件更新 | One-KVM 有自己的更新机制 |
+
+### 3.5 权限协商
+
+| 功能 | 原因 |
+|------|------|
+| Option 消息 | One-KVM 假设完全控制权限 |
+| 权限请求 | 同上 |
+| PermissionInfo | 同上 |
+
+## 4. 实现差异
+
+### 4.1 连接模式
+
+**RustDesk 原版:**
+```
+客户端 ──UDP打洞──> 被控端 (P2P 优先)
+       └──Relay──> 被控端 (回退)
+```
+
+**One-KVM:**
+```
+RustDesk客户端 ──TCP中继──> hbbr服务器 ──> One-KVM设备
+```
+
+One-KVM 只支持 TCP 中继连接，不支持 P2P 直连。这简化了实现，但可能增加延迟。
+
+### 4.2 会话加密
+
+**RustDesk 原版:**
+- 支持 ChaCha20-Poly1305 (流式)
+- 支持 XSalsa20-Poly1305 (secretbox)
+- 动态协商加密方式
+
+**One-KVM:**
+- 仅支持 XSalsa20-Poly1305 (secretbox)
+- 使用序列号作为 nonce
+
+```rust
+// One-KVM 的加密实现
+fn encrypt_message(&mut self, plaintext: &[u8]) -> Vec<u8> {
+    let nonce = make_nonce(&self.send_nonce);
+    self.send_nonce = self.send_nonce.wrapping_add(1);
+    secretbox::seal(plaintext, &nonce, &self.session_key)
+}
+```
+
+### 4.3 视频流方向
+
+**RustDesk 原版:**
+- 双向视频流（可控制和被控制）
+- 远程桌面捕获
+
+**One-KVM:**
+- 单向视频流（仅发送）
+- 从 V4L2 设备捕获
+- 集成到 One-KVM 的 VideoStreamManager
+
+```rust
+// One-KVM 视频流集成
+pub async fn start_video_stream(&self, state: &AppState) {
+    let stream_manager = &state.video_stream_manager;
+    // 从 One-KVM 的视频管理器获取帧
+}
+```
+
+### 4.4 HID 事件处理
+
+**RustDesk 原版:**
+- 转发到远程系统的输入子系统
+- 使用 enigo 或 uinput
+
+**One-KVM:**
+- 转发到 USB OTG/HID 设备
+- 控制物理 KVM 目标机器
+
+```rust
+// One-KVM HID 适配
+pub fn convert_mouse_event(event: &RustDeskMouseEvent) -> Option<OneKvmMouseEvent> {
+    // 转换 RustDesk 鼠标事件到 One-KVM HID 事件
+}
+
+pub fn convert_key_event(event: &RustDeskKeyEvent) -> Option<OneKvmKeyEvent> {
+    // 转换 RustDesk 键盘事件到 One-KVM HID 事件
+}
+```
+
+### 4.5 配置管理
+
+**RustDesk 原版:**
+- 使用 TOML/JSON 配置文件
+- 硬编码默认值
+
+**One-KVM:**
+- 集成到 SQLite 配置系统
+- Web UI 管理
+- 使用 typeshare 生成 TypeScript 类型
+
+```rust
+#[typeshare]
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RustDeskConfig {
+    pub enabled: bool,
+    pub rendezvous_server: String,
+    pub device_id: String,
+    // ...
+}
+```
+
+### 4.6 设备 ID 生成
+
+**RustDesk 原版:**
+- 基于 MAC 地址和硬件信息
+- 固定便携式 ID
+
+**One-KVM:**
+- 随机生成 9 位数字
+- 存储在配置中
+
+```rust
+pub fn generate_device_id() -> String {
+    let mut rng = rand::thread_rng();
+    let id: u32 = rng.gen_range(100_000_000..999_999_999);
+    id.to_string()
+}
+```
+
+## 5. 协议兼容性
+
+### 5.1 完全兼容
+
+| 功能 | 说明 |
+|------|------|
+| Rendezvous 注册 | 可与官方 hbbs 服务器通信 |
+| 中继连接 | 可通过官方 hbbr 服务器中继 |
+| 加密握手 | 与 RustDesk 客户端兼容 |
+| 视频编码 | 支持所有主流编码格式 |
+| HID 事件 | 接收标准 RustDesk 输入事件 |
+
+### 5.2 部分兼容
+
+| 功能 | 说明 |
+|------|------|
+| 密码认证 | 仅支持设备密码，不支持一次性密码 |
+| 会话加密 | 仅 XSalsa20-Poly1305 |
+
+### 5.3 不兼容
+
+| 功能 | 说明 |
+|------|------|
+| P2P 连接 | 客户端必须通过中继连接 |
+| 文件传输 | 不支持 |
+| 剪贴板 | 不支持 |
+
+## 6. 代码结构对比
+
+### RustDesk 原版结构
+
+```
+rustdesk/
+├── libs/hbb_common/     # 公共库
+│   ├── protos/          # Protobuf 定义
+│   └── src/
+├── src/
+│   ├── server/          # 被控端服务
+│   ├── client/          # 控制端
+│   ├── ui/              # 用户界面
+│   └── rendezvous_mediator.rs
+```
+
+### One-KVM 结构
+
+```
+src/rustdesk/
+├── mod.rs               # 模块导出
+├── config.rs            # 配置类型 (~164 行)
+├── crypto.rs            # 加密模块 (~468 行)
+├── bytes_codec.rs       # 帧编码 (~253 行)
+├── protocol.rs          # 消息辅助 (~170 行)
+├── rendezvous.rs        # Rendezvous 中介 (~829 行)
+├── connection.rs        # 连接处理 (~1349 行)
+├── hid_adapter.rs       # HID 转换 (~386 行)
+└── frame_adapters.rs    # 视频/音频适配 (~316 行)
+```
+
+**总计**: ~3935 行代码
+
+## 7. 总结
+
+### 实现率统计
+
+| 类别 | RustDesk 功能数 | One-KVM 实现数 | 实现率 |
+|------|-----------------|----------------|--------|
+| Rendezvous 协议 | 15+ | 10 | ~67% |
+| 连接协议 | 30+ | 12 | ~40% |
+| 加密功能 | 8 | 6 | 75% |
+| 视频/音频 | 6 | 6 | 100% |
+| HID 功能 | 6 | 6 | 100% |
+
+### 设计理念
+
+One-KVM 的 RustDesk 实现专注于 **IP-KVM 核心功能**:
+
+1. **精简**: 只实现必要的被控端功能
+2. **可靠**: 使用 TCP 中继保证连接稳定性
+3. **集成**: 与 One-KVM 现有视频/HID 系统无缝集成
+4. **安全**: 完整实现加密和认证机制
+
+### 客户端兼容性
+
+One-KVM 可与标准 RustDesk 客户端配合使用:
+- RustDesk 桌面客户端 (Windows/macOS/Linux)
+- RustDesk 移动客户端 (Android/iOS)
+- RustDesk Web 客户端
+
+只需确保:
+1. 配置相同的 Rendezvous 服务器
+2. 使用设备 ID 和密码连接
+3. 客户端支持中继连接

docs/system-architecture.md

@@ -0,0 +1,876 @@
+# One-KVM 系统架构文档
+
+## 1. 项目概述
+
+One-KVM 是一个用 Rust 编写的轻量级、开源 IP-KVM 解决方案。它提供 BIOS 级别的远程服务器管理能力，支持视频流、键鼠控制、虚拟存储、电源管理和音频等功能。
+
+### 1.1 核心特性
+
+- **单一二进制部署**：Web UI + 后端一体化，无需额外配置文件
+- **双流模式**：支持 WebRTC（H264/H265/VP8/VP9）和 MJPEG 两种流模式
+- **USB OTG**：虚拟键鼠、虚拟存储、虚拟网卡
+- **ATX 电源控制**：GPIO/USB 继电器
+- **RustDesk 协议集成**：支持跨平台访问
+- **Vue3 SPA 前端**：支持中文/英文
+- **SQLite 配置存储**：无需配置文件
+
+### 1.2 目标平台
+
+| 平台 | 架构 | 用途 |
+|------|------|------|
+| aarch64-unknown-linux-gnu | ARM64 | 主要目标（Rockchip RK3328 等） |
+| armv7-unknown-linux-gnueabihf | ARMv7 | 备选平台 |
+| x86_64-unknown-linux-gnu | x86-64 | 开发/测试环境 |
+
+---
+
+## 2. 系统架构图
+
+### 2.1 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              One-KVM System                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                        Web Frontend (Vue3)                           │   │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │   │
+│  │  │ Console  │ │ Settings │ │  Login   │ │  Setup   │ │ Virtual  │  │   │
+│  │  │   View   │ │   View   │ │   View   │ │   View   │ │ Keyboard │  │   │
+│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │   │
+│  │                                │                                     │   │
+│  │              ┌─────────────────┴─────────────────┐                  │   │
+│  │              │        Pinia State Store          │                  │   │
+│  │              └─────────────────┬─────────────────┘                  │   │
+│  │                                │                                     │   │
+│  │  ┌──────────────────────────────────────────────────────────────┐  │   │
+│  │  │                      API Client Layer                         │  │   │
+│  │  │  HTTP REST  │  WebSocket  │  WebRTC Signaling  │  MJPEG      │  │   │
+│  │  └──────────────────────────────────────────────────────────────┘  │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    │ HTTP/WS/WebRTC                         │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                     Axum Web Server (routes.rs)                      │   │
+│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐           │   │
+│  │  │  Public   │ │   User    │ │   Admin   │ │  Static   │           │   │
+│  │  │  Routes   │ │  Routes   │ │  Routes   │ │  Files    │           │   │
+│  │  └───────────┘ └───────────┘ └───────────┘ └───────────┘           │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                       AppState (state.rs)                            │   │
+│  │  ┌─────────────────────────────────────────────────────────────┐    │   │
+│  │  │                    Central State Hub                         │    │   │
+│  │  │  ┌────────────┐ ┌────────────┐ ┌────────────┐              │    │   │
+│  │  │  │ConfigStore │ │SessionStore│ │ UserStore  │              │    │   │
+│  │  │  │  (SQLite)  │ │  (Memory)  │ │  (SQLite)  │              │    │   │
+│  │  │  └────────────┘ └────────────┘ └────────────┘              │    │   │
+│  │  │                                                              │    │   │
+│  │  │  ┌────────────┐ ┌────────────┐ ┌────────────┐              │    │   │
+│  │  │  │  EventBus  │ │ OtgService │ │ Extensions │              │    │   │
+│  │  │  │ (Broadcast)│ │   (USB)    │ │  Manager   │              │    │   │
+│  │  │  └────────────┘ └────────────┘ └────────────┘              │    │   │
+│  │  └─────────────────────────────────────────────────────────────┘    │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│      ┌─────────────────────────────┼─────────────────────────────┐         │
+│      │                             │                             │         │
+│      ▼                             ▼                             ▼         │
+│  ┌────────────┐             ┌────────────┐             ┌────────────┐      │
+│  │   Video    │             │    HID     │             │   Audio    │      │
+│  │  Module    │             │  Module    │             │  Module    │      │
+│  ├────────────┤             ├────────────┤             ├────────────┤      │
+│  │ Capture    │             │ Controller │             │ Capture    │      │
+│  │ Encoder    │             │ OTG Backend│             │ Encoder    │      │
+│  │ Streamer   │             │ CH9329     │             │ Pipeline   │      │
+│  │ Pipeline   │             │ DataChannel│             │ (Opus)     │      │
+│  └────────────┘             └────────────┘             └────────────┘      │
+│        │                           │                          │            │
+│        └───────────────────────────┼──────────────────────────┘            │
+│                                    │                                        │
+│      ┌─────────────────────────────┼─────────────────────────────┐         │
+│      │                             │                             │         │
+│      ▼                             ▼                             ▼         │
+│  ┌────────────┐             ┌────────────┐             ┌────────────┐      │
+│  │    MSD     │             │    ATX     │             │  RustDesk  │      │
+│  │  Module    │             │  Module    │             │  Module    │      │
+│  ├────────────┤             ├────────────┤             ├────────────┤      │
+│  │ Controller │             │ Controller │             │  Service   │      │
+│  │ Image Mgr  │             │ Executor   │             │ Rendezvous │      │
+│  │ Ventoy     │             │ LED Monitor│             │ Connection │      │
+│  │ Drive      │             │ WOL        │             │ Protocol   │      │
+│  └────────────┘             └────────────┘             └────────────┘      │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            Hardware Layer                                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐            │
+│  │ V4L2 Video │  │  USB OTG   │  │   GPIO     │  │   ALSA     │            │
+│  │   Device   │  │  Gadget    │  │  Sysfs     │  │   Audio    │            │
+│  │/dev/video* │  │ ConfigFS   │  │            │  │            │            │
+│  └────────────┘  └────────────┘  └────────────┘  └────────────┘            │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 数据流架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              Data Flow Overview                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                        ┌─────────────────┐
+                        │   Target PC     │
+                        └────────┬────────┘
+                                 │
+        ┌────────────────────────┼────────────────────────┐
+        │                        │                        │
+        ▼                        ▼                        ▼
+┌───────────────┐      ┌───────────────┐      ┌───────────────┐
+│  HDMI Capture │      │   USB Port    │      │   GPIO/Relay  │
+│    Card       │      │  (OTG Mode)   │      │   (ATX)       │
+└───────┬───────┘      └───────┬───────┘      └───────┬───────┘
+        │                      │                      │
+        ▼                      ▼                      ▼
+┌───────────────┐      ┌───────────────┐      ┌───────────────┐
+│  /dev/video0  │      │  /dev/hidg*   │      │  /sys/class/  │
+│  (V4L2)       │      │  (USB Gadget) │      │  gpio/gpio*   │
+└───────┬───────┘      └───────┬───────┘      └───────┬───────┘
+        │                      │                      │
+        ▼                      ▼                      ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    One-KVM Application                       │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   Video     │  │    HID      │  │    ATX      │         │
+│  │  Pipeline   │  │ Controller  │  │ Controller  │         │
+│  └─────┬───────┘  └─────┬───────┘  └─────┬───────┘         │
+│        │                │                │                  │
+│        ▼                ▼                ▼                  │
+│  ┌───────────────────────────────────────────────────────┐ │
+│  │                   Event Bus                            │ │
+│  │              (tokio broadcast channel)                 │ │
+│  └───────────────────────────────────────────────────────┘ │
+│        │                │                │                  │
+│        ▼                ▼                ▼                  │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                 Web Server (Axum)                    │   │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │   │
+│  │  │  MJPEG   │ │  WebRTC  │ │WebSocket │            │   │
+│  │  │  Stream  │ │  Stream  │ │  Events  │            │   │
+│  │  └──────────┘ └──────────┘ └──────────┘            │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+        │                      │                      │
+        ▼                      ▼                      ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Client Browser                            │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   Video     │  │    Input    │  │   Control   │         │
+│  │  Display    │  │  Events     │  │   Panel     │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 模块依赖关系
+
+### 3.1 模块层次图
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            Application Layer                                 │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  main.rs ──► state.rs ──► web/routes.rs                                     │
+│                 │                                                            │
+│     ┌───────────┼───────────┬───────────┬───────────┬───────────┐          │
+│     │           │           │           │           │           │          │
+│     ▼           ▼           ▼           ▼           ▼           ▼          │
+│  ┌──────┐  ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐          │
+│  │video/│  │ hid/ │   │ msd/ │   │ atx/ │   │audio/│   │webrtc│          │
+│  └──┬───┘  └──┬───┘   └──┬───┘   └──┬───┘   └──┬───┘   └──┬───┘          │
+│     │         │          │          │          │          │               │
+│     │         └──────────┼──────────┘          │          │               │
+│     │                    │                     │          │               │
+│     │              ┌─────▼─────┐               │          │               │
+│     │              │   otg/    │               │          │               │
+│     │              │ (OtgSvc)  │               │          │               │
+│     │              └───────────┘               │          │               │
+│     │                                          │          │               │
+│     └──────────────────────────────────────────┼──────────┘               │
+│                                                │                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                           Infrastructure Layer                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐                    │
+│  │ config/  │  │  auth/   │  │ events/  │  │extensions│                    │
+│  │(ConfigSt)│  │(Session) │  │(EventBus)│  │(ExtMgr)  │                    │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘                    │
+│                                                                              │
+│  ┌───────────────────────────────────────────────────────────┐             │
+│  │                    rustdesk/ (RustDeskService)             │             │
+│  │  connection.rs │ rendezvous.rs │ crypto.rs │ protocol.rs   │             │
+│  └───────────────────────────────────────────────────────────┘             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 依赖矩阵
+
+| 模块 | 依赖的模块 |
+|------|-----------|
+| `main.rs` | state, config, auth, video, hid, msd, atx, audio, webrtc, web, rustdesk, events |
+| `state.rs` | config, auth, video, hid, msd, atx, audio, webrtc, rustdesk, events, otg |
+| `video/` | events, hwcodec (外部) |
+| `hid/` | otg, events |
+| `msd/` | otg, events |
+| `atx/` | events |
+| `audio/` | events |
+| `webrtc/` | video, audio, hid, events |
+| `web/` | state, auth, config, video, hid, msd, atx, audio, webrtc, events |
+| `rustdesk/` | video, audio, hid, events |
+| `otg/` | (无内部依赖) |
+| `config/` | (无内部依赖) |
+| `auth/` | config |
+| `events/` | (无内部依赖) |
+
+---
+
+## 4. 核心组件详解
+
+### 4.1 AppState (state.rs)
+
+AppState 是整个应用的状态中枢，通过 `Arc` 包装的方式在所有 handler 之间共享。
+
+```rust
+pub struct AppState {
+    // 配置和存储
+    config: ConfigStore,              // SQLite 配置存储
+    sessions: SessionStore,           // 内存会话存储
+    users: UserStore,                 // SQLite 用户存储
+
+    // 核心服务
+    otg_service: Arc<OtgService>,     // USB Gadget 统一管理
+    stream_manager: Arc<VideoStreamManager>,  // 视频流管理器
+    hid: Arc<HidController>,          // HID 控制器
+    msd: Arc<RwLock<Option<MsdController>>>,  // MSD 控制器（可选）
+    atx: Arc<RwLock<Option<AtxController>>>,  // ATX 控制器（可选）
+    audio: Arc<AudioController>,      // 音频控制器
+    rustdesk: Arc<RwLock<Option<Arc<RustDeskService>>>>,  // RustDesk（可选）
+    extensions: Arc<ExtensionManager>,// 扩展管理器
+
+    // 通信和生命周期
+    events: Arc<EventBus>,            // 事件总线
+    shutdown_tx: broadcast::Sender<()>,  // 关闭信号
+    data_dir: PathBuf,                // 数据目录
+}
+```
+
+### 4.2 视频流管道
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Video Pipeline Architecture                          │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌───────────────────┐
+│  V4L2 Device      │
+│  /dev/video0      │
+└─────────┬─────────┘
+          │ Raw MJPEG/YUYV/NV12
+          ▼
+┌───────────────────┐
+│  VideoCapturer    │  ◄─── src/video/capture.rs
+│  (capture.rs)     │
+└─────────┬─────────┘
+          │ VideoFrame
+          ▼
+┌───────────────────────────────────────────────────────────────────────────┐
+│                        SharedVideoPipeline                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐  │
+│  │                          Decode Stage                                │  │
+│  │  ┌─────────────┐                                                    │  │
+│  │  │ MJPEG → YUV │  turbojpeg / VAAPI                                 │  │
+│  │  └─────────────┘                                                    │  │
+│  └─────────────────────────────────────────────────────────────────────┘  │
+│                              │                                             │
+│                              ▼                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐  │
+│  │                         Convert Stage                                │  │
+│  │  ┌─────────────┐                                                    │  │
+│  │  │YUV → Target │  libyuv (SIMD accelerated)                         │  │
+│  │  │   Format    │                                                    │  │
+│  │  └─────────────┘                                                    │  │
+│  └─────────────────────────────────────────────────────────────────────┘  │
+│                              │                                             │
+│                              ▼                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐  │
+│  │                         Encode Stage                                 │  │
+│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐                       │  │
+│  │  │  H264  │ │  H265  │ │  VP8   │ │  VP9   │                       │  │
+│  │  │Encoder │ │Encoder │ │Encoder │ │Encoder │                       │  │
+│  │  └────────┘ └────────┘ └────────┘ └────────┘                       │  │
+│  │      │ (VAAPI/RKMPP/V4L2 M2M/Software)                              │  │
+│  └─────────────────────────────────────────────────────────────────────┘  │
+└───────────────────────────────────────────────────────────────────────────┘
+          │
+          ├──────────────────────────────────────────┐
+          │                                          │
+          ▼                                          ▼
+┌───────────────────┐                      ┌───────────────────┐
+│  MJPEG Streamer   │                      │  WebRTC Streamer  │
+│  (HTTP Stream)    │                      │  (RTP Packets)    │
+└───────────────────┘                      └───────────────────┘
+```
+
+### 4.3 OTG 服务架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           OTG Service Architecture                           │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            OtgService (service.rs)                           │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                      Public Interface                                │   │
+│  │  enable_hid()  │  disable_hid()  │  enable_msd()  │  disable_msd() │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                    OtgGadgetManager (manager.rs)                     │   │
+│  │  ┌───────────────────────────────────────────────────────────────┐  │   │
+│  │  │                   Gadget Lifecycle                             │  │   │
+│  │  │  create_gadget() │ destroy_gadget() │ bind_udc() │ unbind()   │  │   │
+│  │  └───────────────────────────────────────────────────────────────┘  │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│           ┌────────────────────────┼────────────────────────┐              │
+│           │                        │                        │              │
+│           ▼                        ▼                        ▼              │
+│  ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐      │
+│  │  HID Function   │     │  MSD Function   │     │ Endpoint Alloc  │      │
+│  │    (hid.rs)     │     │    (msd.rs)     │     │ (endpoint.rs)   │      │
+│  └─────────────────┘     └─────────────────┘     └─────────────────┘      │
+│           │                        │                                        │
+│           ▼                        ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                       ConfigFS Operations                            │   │
+│  │  /sys/kernel/config/usb_gadget/one-kvm/                             │   │
+│  │  ├── idVendor, idProduct, strings/                                   │   │
+│  │  ├── configs/c.1/                                                    │   │
+│  │  │   └── functions/ (symlinks)                                       │   │
+│  │  └── functions/                                                      │   │
+│  │      ├── hid.usb0, hid.usb1, hid.usb2                               │   │
+│  │      └── mass_storage.usb0                                           │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              Linux Kernel                                    │
+│  ┌─────────────────┐     ┌─────────────────┐                               │
+│  │   /dev/hidg*    │     │  Mass Storage   │                               │
+│  │  (HID devices)  │     │    Backend      │                               │
+│  └─────────────────┘     └─────────────────┘                               │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.4 事件系统架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Event System Architecture                          │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          Event Producers                                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐         │
+│  │  Video   │ │   HID    │ │   MSD    │ │   ATX    │ │  Audio   │         │
+│  │ Module   │ │ Module   │ │ Module   │ │ Module   │ │ Module   │         │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘         │
+│       │            │            │            │            │               │
+│       └────────────┴────────────┼────────────┴────────────┘               │
+│                                 │                                          │
+│                                 ▼                                          │
+│  ┌─────────────────────────────────────────────────────────────────────┐  │
+│  │                          EventBus                                    │  │
+│  │                   (tokio broadcast channel)                          │  │
+│  │  ┌───────────────────────────────────────────────────────────────┐  │  │
+│  │  │                    SystemEvent Enum                            │  │  │
+│  │  │  StreamStateChanged │ HidStateChanged │ MsdStateChanged       │  │  │
+│  │  │  AtxStateChanged │ AudioStateChanged │ DeviceInfo │ Error     │  │  │
+│  │  └───────────────────────────────────────────────────────────────┘  │  │
+│  └─────────────────────────────────────────────────────────────────────┘  │
+│                                 │                                          │
+│       ┌─────────────────────────┼─────────────────────────┐               │
+│       │                         │                         │               │
+│       ▼                         ▼                         ▼               │
+│  ┌──────────┐            ┌──────────┐            ┌──────────┐            │
+│  │WebSocket │            │ DeviceInfo│            │ Internal │            │
+│  │ Clients  │            │Broadcaster│            │  Tasks   │            │
+│  └──────────┘            └──────────┘            └──────────┘            │
+│                                                                           │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 5. 初始化流程
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Application Startup Flow                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+main()
+   │
+   ├──► Parse CLI Arguments (clap)
+   │      - address, port, data_dir
+   │      - enable_https, ssl_cert, ssl_key
+   │      - verbosity (-v, -vv, -vvv)
+   │
+   ├──► Initialize Logging (tracing)
+   │
+   ├──► Create/Open SQLite Database
+   │      └─► ConfigStore::new()
+   │      └─► UserStore::new()
+   │      └─► SessionStore::new()
+   │
+   ├──► Initialize Core Services
+   │      │
+   │      ├──► EventBus::new()
+   │      │
+   │      ├──► OtgService::new()
+   │      │      └─► Detect UDC device
+   │      │
+   │      ├──► HidController::init()
+   │      │      └─► Select backend (OTG/CH9329/None)
+   │      │      └─► Request HID function from OtgService
+   │      │
+   │      ├──► MsdController::init() (if configured)
+   │      │      └─► Request MSD function from OtgService
+   │      │      └─► Initialize Ventoy drive (if available)
+   │      │
+   │      ├──► AtxController::init() (if configured)
+   │      │      └─► Setup GPIO pins
+   │      │
+   │      ├──► AudioController::init()
+   │      │      └─► Open ALSA device
+   │      │      └─► Initialize Opus encoder
+   │      │
+   │      ├──► VideoStreamManager::new()
+   │      │      └─► Initialize SharedVideoPipeline
+   │      │      └─► Setup encoder registry
+   │      │
+   │      └──► RustDeskService::new() (if configured)
+   │             └─► Load/generate device ID and keys
+   │             └─► Connect to rendezvous server
+   │
+   ├──► Create AppState
+   │      └─► Wrap all services in Arc<>
+   │
+   ├──► Spawn Background Tasks
+   │      ├──► spawn_device_info_broadcaster()
+   │      ├──► extension_health_check_task()
+   │      └──► rustdesk_reconnect_task()
+   │
+   ├──► Create Axum Router
+   │      └─► create_router(app_state)
+   │
+   └──► Start HTTP/HTTPS Server
+          └─► axum::serve() or axum_server with TLS
+```
+
+---
+
+## 6. 目录结构
+
+```
+One-KVM-RUST/
+├── src/                              # Rust 源代码
+│   ├── main.rs                      # 应用入口点
+│   ├── lib.rs                       # 库导出
+│   ├── state.rs                     # AppState 定义
+│   ├── error.rs                     # 错误类型定义
+│   │
+│   ├── video/                       # 视频模块
+│   │   ├── mod.rs
+│   │   ├── capture.rs              # V4L2 采集
+│   │   ├── streamer.rs             # 视频流服务
+│   │   ├── stream_manager.rs       # 流管理器
+│   │   ├── shared_video_pipeline.rs # 共享视频管道
+│   │   ├── format.rs               # 像素格式
+│   │   ├── frame.rs                # 视频帧
+│   │   ├── convert.rs              # 格式转换
+│   │   └── encoder/                # 编码器
+│   │       ├── mod.rs
+│   │       ├── traits.rs
+│   │       ├── h264.rs
+│   │       ├── h265.rs
+│   │       ├── vp8.rs
+│   │       ├── vp9.rs
+│   │       └── jpeg.rs
+│   │
+│   ├── hid/                         # HID 模块
+│   │   ├── mod.rs                  # HidController
+│   │   ├── backend.rs              # 后端抽象
+│   │   ├── otg.rs                  # OTG 后端
+│   │   ├── ch9329.rs               # CH9329 串口后端
+│   │   ├── keymap.rs               # 按键映射
+│   │   ├── types.rs                # 类型定义
+│   │   ├── monitor.rs              # 健康监视
+│   │   ├── datachannel.rs          # DataChannel 适配
+│   │   └── websocket.rs            # WebSocket 适配
+│   │
+│   ├── otg/                         # USB OTG 模块
+│   │   ├── mod.rs
+│   │   ├── service.rs              # OtgService
+│   │   ├── manager.rs              # GadgetManager
+│   │   ├── hid.rs                  # HID Function
+│   │   ├── msd.rs                  # MSD Function
+│   │   ├── configfs.rs             # ConfigFS 操作
+│   │   ├── endpoint.rs             # 端点分配
+│   │   └── report_desc.rs          # HID 报告描述符
+│   │
+│   ├── msd/                         # MSD 模块
+│   │   ├── mod.rs
+│   │   ├── controller.rs           # MsdController
+│   │   ├── image.rs                # 镜像管理
+│   │   ├── ventoy_drive.rs         # Ventoy 驱动
+│   │   ├── monitor.rs              # 健康监视
+│   │   └── types.rs                # 类型定义
+│   │
+│   ├── atx/                         # ATX 模块
+│   │   ├── mod.rs
+│   │   ├── controller.rs           # AtxController
+│   │   ├── executor.rs             # 动作执行器
+│   │   ├── types.rs                # 类型定义
+│   │   ├── led.rs                  # LED 监视
+│   │   └── wol.rs                  # Wake-on-LAN
+│   │
+│   ├── audio/                       # 音频模块
+│   │   ├── mod.rs
+│   │   ├── controller.rs           # AudioController
+│   │   ├── capture.rs              # ALSA 采集
+│   │   ├── encoder.rs              # Opus 编码
+│   │   ├── shared_pipeline.rs      # 共享管道
+│   │   ├── monitor.rs              # 健康监视
+│   │   └── device.rs               # 设备枚举
+│   │
+│   ├── webrtc/                      # WebRTC 模块
+│   │   ├── mod.rs
+│   │   ├── webrtc_streamer.rs      # WebRTC 管理器
+│   │   ├── universal_session.rs    # 会话管理
+│   │   ├── video_track.rs          # 视频轨道
+│   │   ├── rtp.rs                  # RTP 打包
+│   │   ├── h265_payloader.rs       # H265 RTP
+│   │   ├── peer.rs                 # PeerConnection
+│   │   ├── config.rs               # 配置
+│   │   ├── signaling.rs            # 信令
+│   │   └── track.rs                # 轨道基类
+│   │
+│   ├── auth/                        # 认证模块
+│   │   ├── mod.rs
+│   │   ├── user.rs                 # 用户管理
+│   │   ├── session.rs              # 会话管理
+│   │   ├── password.rs             # 密码哈希
+│   │   └── middleware.rs           # Axum 中间件
+│   │
+│   ├── config/                      # 配置模块
+│   │   ├── mod.rs
+│   │   ├── schema.rs               # 配置结构定义
+│   │   └── store.rs                # SQLite 存储
+│   │
+│   ├── events/                      # 事件模块
+│   │   └── mod.rs                  # EventBus
+│   │
+│   ├── rustdesk/                    # RustDesk 模块
+│   │   ├── mod.rs                  # RustDeskService
+│   │   ├── connection.rs           # 连接管理
+│   │   ├── rendezvous.rs           # 渲染服务器通信
+│   │   ├── crypto.rs               # NaCl 加密
+│   │   ├── config.rs               # 配置
+│   │   ├── hid_adapter.rs          # HID 适配
+│   │   ├── frame_adapters.rs       # 帧格式转换
+│   │   ├── protocol.rs             # 协议包装
+│   │   └── bytes_codec.rs          # 帧编码
+│   │
+│   ├── extensions/                  # 扩展模块
+│   │   └── mod.rs                  # ExtensionManager
+│   │
+│   ├── web/                         # Web 模块
+│   │   ├── mod.rs
+│   │   ├── routes.rs               # 路由定义
+│   │   ├── ws.rs                   # WebSocket
+│   │   ├── audio_ws.rs             # 音频 WebSocket
+│   │   ├── static_files.rs         # 静态文件
+│   │   └── handlers/               # API 处理器
+│   │       ├── mod.rs
+│   │       └── config/
+│   │
+│   ├── stream/                      # MJPEG 流
+│   │   └── mod.rs
+│   │
+│   └── utils/                       # 工具函数
+│       └── mod.rs
+│
+├── web/                             # Vue3 前端
+│   ├── src/
+│   │   ├── views/                  # 页面组件
+│   │   ├── components/             # UI 组件
+│   │   ├── api/                    # API 客户端
+│   │   ├── stores/                 # Pinia 状态
+│   │   ├── router/                 # 路由配置
+│   │   ├── i18n/                   # 国际化
+│   │   └── types/                  # TypeScript 类型
+│   └── package.json
+│
+├── libs/                            # 外部库
+│   ├── hwcodec/                    # 硬件视频编码
+│   └── ventoy-img-rs/              # Ventoy 支持
+│
+├── protos/                          # Protobuf 定义
+│   ├── message.proto               # RustDesk 消息
+│   └── rendezvous.proto            # RustDesk 渲染
+│
+├── docs/                            # 文档
+├── scripts/                         # 脚本
+├── Cargo.toml                       # Rust 配置
+├── build.rs                         # 构建脚本
+└── README.md
+```
+
+---
+
+## 7. 安全架构
+
+### 7.1 认证流程
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Authentication Flow                                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌───────────┐        ┌───────────┐        ┌───────────┐        ┌───────────┐
+│  Client   │        │  Axum     │        │  Auth     │        │  SQLite   │
+│  Browser  │        │  Server   │        │  Module   │        │  Database │
+└─────┬─────┘        └─────┬─────┘        └─────┬─────┘        └─────┬─────┘
+      │                    │                    │                    │
+      │  POST /auth/login  │                    │                    │
+      │  {username, pass}  │                    │                    │
+      │───────────────────►│                    │                    │
+      │                    │  verify_user()     │                    │
+      │                    │───────────────────►│                    │
+      │                    │                    │  SELECT user       │
+      │                    │                    │───────────────────►│
+      │                    │                    │◄───────────────────│
+      │                    │                    │                    │
+      │                    │                    │  Argon2 verify     │
+      │                    │                    │  ────────────►     │
+      │                    │                    │                    │
+      │                    │  session_token     │                    │
+      │                    │◄───────────────────│                    │
+      │                    │                    │                    │
+      │  Set-Cookie:       │                    │                    │
+      │  session_id=token  │                    │                    │
+      │◄───────────────────│                    │                    │
+      │                    │                    │                    │
+      │  GET /api/...      │                    │                    │
+      │  Cookie: session   │                    │                    │
+      │───────────────────►│                    │                    │
+      │                    │  validate_session()│                    │
+      │                    │───────────────────►│                    │
+      │                    │  user_info         │                    │
+      │                    │◄───────────────────│                    │
+      │                    │                    │                    │
+      │  Response          │                    │                    │
+      │◄───────────────────│                    │                    │
+```
+
+### 7.2 权限层级
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          Permission Levels                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  Public (No Auth)                                                            │
+│  ├── GET /health                                                             │
+│  ├── POST /auth/login                                                        │
+│  ├── GET /setup                                                              │
+│  └── POST /setup/init                                                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  User (Authenticated)                                                        │
+│  ├── GET /info                     (系统信息)                                │
+│  ├── GET /devices                  (设备列表)                                │
+│  ├── GET/POST /stream/*            (流控制)                                  │
+│  ├── POST /webrtc/*                (WebRTC 信令)                            │
+│  ├── POST /hid/*                   (HID 控制)                               │
+│  ├── POST /audio/*                 (音频控制)                               │
+│  └── WebSocket endpoints           (实时通信)                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  Admin (Admin Role)                                                          │
+│  ├── GET/PATCH /config/*           (配置管理)                               │
+│  ├── POST /msd/*                   (MSD 操作)                               │
+│  ├── POST /atx/*                   (电源控制)                               │
+│  ├── POST /extensions/*            (扩展管理)                               │
+│  ├── POST /rustdesk/*              (RustDesk 配置)                          │
+│  └── POST /users/*                 (用户管理)                               │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 8. 部署架构
+
+### 8.1 单机部署
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Single Binary Deployment                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  ARM64 Device (e.g., Rockchip RK3328)                                       │
+│  ┌───────────────────────────────────────────────────────────────────────┐ │
+│  │  one-kvm (single binary, ~15MB)                                        │ │
+│  │  ┌─────────────────────────────────────────────────────────────────┐  │ │
+│  │  │  Embedded Assets (rust-embed, gzip compressed)                   │  │ │
+│  │  │  - index.html, app.js, app.css, assets/*                        │  │ │
+│  │  └─────────────────────────────────────────────────────────────────┘  │ │
+│  │  ┌─────────────────────────────────────────────────────────────────┐  │ │
+│  │  │  Runtime Data (data_dir)                                         │  │ │
+│  │  │  - one-kvm.db (SQLite)                                          │  │ │
+│  │  │  - images/ (MSD images)                                          │  │ │
+│  │  │  - certs/ (SSL certificates)                                     │  │ │
+│  │  └─────────────────────────────────────────────────────────────────┘  │ │
+│  └───────────────────────────────────────────────────────────────────────┘ │
+│                                                                             │
+│  Hardware Connections:                                                      │
+│  ┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐      │
+│  │  HDMI Input       │  │  USB OTG Port     │  │  GPIO Header      │      │
+│  │  (/dev/video0)    │  │  (USB Gadget)     │  │  (ATX Control)    │      │
+│  └───────────────────┘  └───────────────────┘  └───────────────────┘      │
+└─────────────────────────────────────────────────────────────────────────────┘
+                          │
+                          │ USB Cable
+                          ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  Target PC                                                                   │
+│  - Receives USB HID events (keyboard/mouse)                                 │
+│  - Provides HDMI video output                                               │
+│  - Can boot from virtual USB drive                                          │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 8.2 网络拓扑
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Network Topology                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                    Internet
+                        │
+                        │
+            ┌───────────┴───────────┐
+            │                       │
+            ▼                       ▼
+    ┌───────────────┐       ┌───────────────┐
+    │   RustDesk    │       │    Client     │
+    │   Server      │       │   Browser     │
+    │  (hbbs/hbbr)  │       │               │
+    └───────────────┘       └───────────────┘
+            │                       │
+            │                       │
+            └───────────┬───────────┘
+                        │
+                   ┌────┴────┐
+                   │  Router │
+                   │   NAT   │
+                   └────┬────┘
+                        │
+              Local Network
+                        │
+            ┌───────────┴───────────┐
+            │                       │
+            ▼                       ▼
+    ┌───────────────┐       ┌───────────────┐
+    │   One-KVM     │───────│  Target PC    │
+    │   Device      │  USB  │               │
+    │  :8080/:8443  │  HID  │               │
+    └───────────────┘       └───────────────┘
+
+Access Methods:
+1. Local: http://one-kvm.local:8080
+2. HTTPS: https://one-kvm.local:8443
+3. RustDesk: Via RustDesk client with device ID
+```
+
+---
+
+## 9. 扩展点
+
+### 9.1 添加新编码器
+
+```rust
+// 1. 实现 Encoder trait
+impl Encoder for MyEncoder {
+    fn encode(&mut self, frame: &VideoFrame) -> Result<Vec<u8>>;
+    fn codec(&self) -> Codec;
+    fn bitrate(&self) -> u32;
+    // ...
+}
+
+// 2. 在 registry 中注册
+encoder_registry.register("my-encoder", || Box::new(MyEncoder::new()));
+```
+
+### 9.2 添加新 HID 后端
+
+```rust
+// 1. 实现 HidBackend trait
+impl HidBackend for MyBackend {
+    async fn send_keyboard(&self, event: &KeyboardEvent) -> Result<()>;
+    async fn send_mouse(&self, event: &MouseEvent) -> Result<()>;
+    fn info(&self) -> HidBackendInfo;
+    // ...
+}
+
+// 2. 在 HidController::init() 中添加分支
+match config.backend {
+    HidBackendType::MyBackend => MyBackend::new(config),
+    // ...
+}
+```
+
+### 9.3 添加新扩展
+
+```rust
+// 通过 ExtensionManager 管理外部进程
+extension_manager.register("my-extension", ExtensionConfig {
+    command: "my-binary",
+    args: vec!["--port", "9000"],
+    health_check: HealthCheckConfig::Http { url: "http://localhost:9000/health" },
+});
+```
+
+---
+
+## 10. 参考资料
+
+- [Axum Web Framework](https://github.com/tokio-rs/axum)
+- [webrtc-rs](https://github.com/webrtc-rs/webrtc)
+- [V4L2 Documentation](https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/v4l2.html)
+- [Linux USB Gadget](https://www.kernel.org/doc/html/latest/usb/gadget_configfs.html)
+- [RustDesk Protocol](https://github.com/rustdesk/rustdesk)