Tauri 與 Rust 架構

啟動器是一個「有窗口的安裝器 + 進程監督器」。它沒有前端工程，WebView 加載的是 Rust 內嵌的 HTML，通過 tauri:// 之外的自定義協議提供。

窗口

窗口	尺寸	特性
main	1280×880	可縮放，初始不可見，等後端就緒後顯示
splash	800×450	無邊框、不可縮放，先於主窗口建立

WebView 參數刻意關掉了一些預設行為：

--enable-features=msWebView2EnableDraggableRegions
--disable-features=ElasticOverscroll,msWebOOUI,msPdfOOUI,msSmartScreenProtection
--no-proxy-server

• --no-proxy-server：連接本地 WebUI 不走系統代理，避免代理攔截 127.0.0.1。
• 關閉 SmartScreen 保護：內嵌頁面不是外部站點，不需要該攔截。

macOS 的 WKWebView

Windows 的 additionalBrowserArgs 在 macOS 上無效。平台差異用 #[cfg] 處理，不要假設參數通用。

自定義協議

協議	內容
alas-splash://	啟動畫面（進度、階段文案）
alas-error://	錯誤頁（原因、日誌路徑、重試）

頁面由 Rust 內嵌字符串 + splash-progress.js 驅動。進度通過 Tauri 事件從 Rust 推到 WebView，JS 只負責渲染。

改介面的正確方式：

1. 改 main.rs 裏的 HTML 模板或 splash-progress.js。
2. 補 4 個語言的 locales/*.yml。
3. 用 --preview-crash 預覽錯誤頁。
4. 三平台各截一次圖確認。

啟動狀態機

Idle
 → Splash（显示窗口）
   → Provisioning（环境自举）
     → Updating（git pull + uv sync）
       → StartingBackend（清理端口、起 gui.py）
         → Waiting（最多 60 秒）
           → Ready（显示主窗口、注入登录态）
             → Running（托盘常驻）

任一步失敗 → Error 狀態 → alas-error:// 頁面，保留日誌路徑與重試按鈕。

WebView 與 Rust 的通信

方向	機制	用途
Rust → WebView	Tauri event	啟動進度、錯誤、主題
WebView → Rust	#[tauri::command]	重試、打開日誌、退出
後端 → 啟動器	HTTP SSE /api/notify_stream	任務通知
後端 → 啟動器	HTTP /api/launcher/stream	退出、重新啟動、開機自啟指令

後端不能直接調用啟動器函數：它只能通過 HTTP 流發指令，啟動器解析後執行。這條邊界避免了「後端拿到啟動器句柄亂殺進程」。

托盤與通知

能力	實現
托盤	tauri tray-icon feature
菜單	顯示主窗口、重新啟動後端、打開日誌、退出
通知	Windows Toast / macOS / Linux 原生通知
單實例	重複啟動聚焦已有窗口
開機自啟	Windows 註冊表 Run 鍵 + --start-minimized

通知內容來自 SSE 流，語言跟隨啟動器當前 locale。

國際化

locales/zh-CN.yml   # 基准
locales/zh-TW.yml
locales/ja.yml
locales/en.yml

代碼中用 t!("module.key")，帶參數用 t!("k", p = v) 並在 YAML 裏寫 %{p}。新增文案必須同時補四份；缺鍵會回退到 key 本身，介面上會直接露出來。

安全邊界

面	措施
管理員權限	Windows manifest requireAdministrator
自更新	mTLS 客戶端證書，證書不打進倉庫
本地 WebUI	--no-proxy-server，一次性登入令牌
子進程	CREATE_NO_WINDOW，不彈控制台
進程回收	環境標記 + Job Object，退出時全表掃描
日誌	不輸出令牌與密碼

修改時的注意

不要	因為
在 macOS 上依賴 additionalBrowserArgs	WKWebView 不支援
用 println! 記日誌	無窗口程序看不到，且不進日誌檔案
直接 kill 後端進程	跳過 Job/進程組回收，會留孤兒
只改一個語言的 yml	其他語言會顯示鍵名
把 uv 路徑寫死	內嵌 uv 缺失時要回退 PATH

相關文檔

• 後端進程生命週期最容易被改壞的部分
• 更新鏈路git、uv、mTLS
• 構建與發佈三平台產物