白皮书

本文档深入探讨 WSL Dashboard 的架构设计、技术选型以及关键功能的底层实现逻辑，旨在为开发者和高级用户提供技术深度视角。

1. 架构概览

WSL Dashboard 采用经典的 响应式 UI 驱动 + 异步后端任务 架构，利用 Rust 语言的类型系统和所有权模型确保内存安全与高并发性能。

核心组件

• Frontend (UI): 基于 Slint 声明式界面。UI 线程负责渲染和用户交互。
• Backend (Runtime): 基于 Tokio 异步运行时。负责分发、执行系统命令 (CLI)、文件 I/O 以及网络监听。
• Communication: UI 线程与异步任务通过 Channel (MPSC) 和 Shared State (Arc/Mutex/RwLock) 进行高效、线程安全的通信。

2. 技术选型理由

为什么选择 Rust?

• 性能: 零成本抽象，编译为原生机器码，无 GC 抖动。
• 内存安全: 在编译期消除缓冲区溢出和数据竞争，这对于涉及系统底层操作（如磁盘迁移、网络配置）的工具至关重要。
• 二进制体积: 静态链接所有依赖，产出单文件便携式可执行程序。

为什么选择 Slint + Skia?

• 声明式语法: 界面描述与逻辑分离，代码易于维护。
• Skia 渲染: 直接利用 GPU 加速（通过 Skia 引擎），提供亚像素级清晰度的文字和丝滑的动画效果。
• 低开销: 相比 Electron 或 WPF，Slint 的运行时开销极小。

3. 关键技术实现

3.1 WSL 实例探测与解析

应用通过调用 wsl.exe --list --verbose 并解析其输出（处理 UTF-16 编码）来实时获取实例状态。

• 底层解码: 自研的高效编码解码器，确保在不同区域设置的 Windows 环境下都能正确解析输出。
• 状态同步: 采用定时轮询 + 操作触发的双重同步机制。

3.2 磁盘映像迁移 (VHDX Move)

迁移功能利用了 WSL 的导入导出机制，但进行了高度抽象和原子化处理。

• 事务性保障: 在迁移开始前，应用会通过互斥锁 (Mutex) 锁定目标分发，防止并发操作导致数据损坏。
• 自动注册: 迁移完成后，应用会自动重定向 VHDX 路径并重新注册发行版，用户无需手动干预。

3.3 端口转发与防火墙自动化

网络功能不仅是简单的 netsh interface portproxy 调用。

• 规则生命周期管理: 应用会自动检测现有的防火墙规则。当用户创建转发时，应用会利用 Windows API 或 CLI 同步创建入站例外规则。
• IP 自动获取: 通过解析 wsl hostname -I 结果，自动映射宿主机与实例间的虚拟网络 IP。

3.4 USBIP 集成

利用 usbipd-win 的命令行接口。

• 提权处理: 绑定操作需要管理员权限，后端逻辑实现了优雅的 UAC 提权请求转发。
• 状态状态机: 内部维护一个 USB 设备连接状态机，确保 Attach/Detach 过程的可追溯性。

3.5 资源监控与轻量化

应用通过调用 Windows 原生 API (如 GetProcessMemoryInfo) 来监控自身的资源占用。

• 极致轻量: 在托盘静默模式下，应用会主动释放不必要的 UI 资源。对于英文等标准字符集，内存占用可低至 10MB；对于中日韩等复杂字符集，由于需要加载较大的字体渲染缓存，占用约在 38MB 左右。

4. 性能优化指标

指标	目标/实测	优化手段
启动速度	< 500ms	预编译 Slint 界面，减少运行时解析。
基础内存 (托盘)	~10MB	最小化后台轮询频率，按需释放渲染缓存。
CPU 占用 (静止)	< 0.1%	使用 Windows 事件驱动模型，避免空循环轮询。
渲染帧率	60 FPS	Skia GPU 加速，亚像素级抗锯齿渲染。

5. 后端任务分发逻辑

为了保证 UI 的流畅度，所有耗时操作（如导出 VHDX）均通过异步任务分发：

1. 请求封装: UI 线程将用户操作封装为 Command 消息。
2. 消息通道: 通过 tokio::sync::mpsc 发送到后台任务处理器。
3. 状态回传: 后台任务完成后，通过回调或状态共享更新 UI。这种设计确保了即时在处理数 GB 的备份任务时，界面依然能够实时响应用户点击。

6. 安全性考量

• 原子操作: 针对关键的实例卸载和迁移，实现了前置校验。
• UAC 提权管理: 仅在必要时（如绑定 USB 设备）请求权限，遵循最小权限原则。
• 本地存储: 配置仅保存在本地 ~\.wsldashboard，不进行任何云端同步，保护用户隐私。