diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 26b77c0..a0b0b9c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -92,31 +92,46 @@ A reactive "Single Page Application" (SPA) approach. --- -## ⚙️ Development Environment Notes (開發環境注意事項) +## ⚙️ Deployment & Development Notes (部署與開發環境注意事項) -### 1. Vite Proxy 設定 -`vite.config.js` 中的 proxy target **必須**使用 `http://`(而非 `https://`),因為 uvicorn 預設以 HTTP 模式啟動。若設定為 `https://`,Vite 會嘗試發送 TLS 握手封包到純 HTTP 的 uvicorn,導致所有 API 請求失敗 (502 Bad Gateway),uvicorn 日誌會大量出現 `Invalid HTTP request received.` 警告。 +為了支援 **Web Serial API** 直接與外部 MCU 通訊,本專案在生產與正式使用中**全面採用 HTTPS 加密傳輸**。這對於開發代理(Proxy)與存取路徑有以下影響: + +### 1. Vite Proxy 與 SSL 協定對齊 +當 Uvicorn 以 **HTTPS** 模式啟動時(綁定 `key.pem` 與 `cert.pem`),Vite Dev Server 的 `/api` 代理目標**必須對齊為 `https://`**,並加上 `secure: false` 以允許自簽憑證: ```js -// ✅ 正確 -proxy: { '/api': { target: 'http://127.0.0.1:8000', changeOrigin: true } } - -// ❌ 錯誤 — 會導致 API 全部失敗 -proxy: { '/api': { target: 'https://127.0.0.1:8000', secure: false } } +// ✅ 正確 (HTTPS 模式下) +proxy: { + '/api': { + target: 'https://127.0.0.1:8000', + changeOrigin: true, + secure: false + } +} ``` -### 2. Production Build 流程 -若使用者透過 `http://localhost:8000/ui/` 存取系統(FastAPI serve 靜態檔),則前端程式碼修改後**必須**執行以下命令: +### 2. 生產部署流程(純使用者使用) +如果您是**純使用者**,或者需要進行系統正式展示,**完全不需要啟動 Vite Dev Server (5173)**! +您只需要在修改前端後進行一次編譯,然後使用 FastAPI 單獨運行 8000 連接埠即可: + ```bash -npm run build # 將 src/ 編譯輸出至 static/build/ +# 1. 前端編譯 (只需在修改 src/ 代碼後執行一次,若無修改則免) +npm run build # 將 Vue 代碼打包至 static/build/ + +# 2. 啟動後端 HTTPS 服務 (同時提供 API 與網頁 UI) +.venv/bin/uvicorn dea_api:app --host 0.0.0.0 --port 8000 --ssl-keyfile certs/key.pem --ssl-certfile certs/cert.pem +``` +或直接利用 systemd 後台服務啟動(開機自動拉起): +```bash +sudo systemctl restart dea.service ``` -然後在瀏覽器中按 `Ctrl+Shift+R` (硬重新整理) 以清除快取載入最新版本。 -### 3. 兩種存取方式對照表 -| 項目 | Vite Dev Server | Production (FastAPI) | +### 3. 開發模式 vs 生產模式對照表 +| 項目 | 開發模式 (Vite Dev Server) | 生產模式 (FastAPI Static Serve) | |------|----------------|---------------------| -| URL | `http://localhost:5173` | `http://localhost:8000/ui/` | -| 修改後生效 | 自動 (HMR) | 需 `npm run build` | -| 適用場景 | 開發 / 除錯 | 正式使用 / Demo | -| API 轉發 | 透過 Vite proxy | 直接打同一 port | +| **運行連接埠** | `http://localhost:5173` | `https://localhost:8000/ui/` | +| **後端通訊** | 透過 Vite Proxy 轉發至 8000 (HTTPS) | 同一 Port 直接連線,極致穩定且高效 | +| **修改後生效** | 自動熱更新 (HMR),不需手動 build | 必須執行 `npm run build`,並在瀏覽器進行硬重新整理 | +| **主要用途** | 適合前端網頁排版、UI 除錯開發 | **正式使用、Demo 展示、MCU Web Serial 通訊** | +| **是否需 5173**| **是** | **否,完全不需啟用!** |