白皮書

本文件深入探討 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，不進行任何雲端同步，保護使用者隱私。