docs: update ARCHITECTURE.md deployment notes for HTTPS proxy and URLs
This commit is contained in:
+33
-18
@@ -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**| **是** | **否,完全不需啟用!** |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user