白皮書

本文檔深入探討 WSL Dashboard 的架構設計、技術選擇以及核心功能的基礎實作邏輯，為開發者和高階使用者提供技術深度的視角。

1. 架構概覽

WSL Dashboard 採用經典的 反應式 UI + 非同步後端工作 架構，利用 Rust 語言的型別系統和所有權模型，確保記憶體安全性和高併發效能。

核心元件

• 前端 (UI): 基於 Slint 的宣告式介面。UI 執行緒負責渲染和使用者互動。
• 後端 (Runtime): 基於 Tokio 非同步執行時。負責分散、執行系統指令 (CLI)、檔案 I/O 和網路監聽。
• 通訊: UI 執行緒和非同步工作透過 通道 (MPSC) 和 共用狀態 (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 裝置連接狀態機器，確保附加/中斷程序的可追蹤性。

3.5 資源監控與輕量化

應用程式透過呼叫 Windows 原生 API（如 GetProcessMemoryInfo）監控自身資源使用。

• 極致輕量化: 在靜默系統匣模式下，應用程式主動釋放不必要的 UI 資源。英文等標準字元集場景下，記憶體使用可降至僅 10MB；繁體中文、日文、韓文等複雜字元集場景下，因需要載入更大的字體渲染快取，使用量約為 38MB。

4. 效能最佳化指標

指標	目標/實測	最佳化方法
啟動速度	< 500ms	Slint 介面預編譯，減少執行時分析。
基礎記憶體 (系統匣)	~10MB	最小化背景輪詢頻率，必要時釋放渲染快取。
CPU 使用 (靜態)	< 0.1%	使用 Windows 事件驅動模型，避免空轉輪詢迴圈。
渲染 FPS	60 FPS	Skia GPU 加速，次像素反鋸齒渲染。

5. 後端工作分散邏輯

為確保 UI 流暢度，所有耗時操作（如 VHDX 匯出）均透過非同步工作分散：

1. 請求封裝: UI 執行緒將使用者操作封裝為 Command 訊息。
2. 訊息通道: 透過 tokio::sync::mpsc 傳送至後端工作處理器。
3. 狀態回傳: 後端工作完成後，透過回呼或狀態共享更新 UI。此設計確保即使在處理數 GB 備份工作時，介面仍能即時回應使用者點擊。

6. 安全考量

• 原子操作: 對關鍵執行個體登出和移轉實作預檢查。
• UAC 提升管理: 僅在需要時（如 USB 裝置綁定）請求權限，遵循最小權限原則。
• 本機儲存: 設定僅本機儲存在 ~\.wsldashboard，無雲端同步，保護使用者隱私。