docs: update ARCHITECTURE.md deployment notes for HTTPS proxy and URLs

This commit is contained in:
pchang718
2026-05-17 14:26:26 +08:00
parent c259f91380
commit d9841fe7bc
+33 -18
View File
@@ -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**| **是** | **否,完全不需啟用!** |