refactor: migrate project structure to Vue 3 with Vite and Tailwind CSS integration
This commit is contained in:
ws50529
@@ -1,71 +1,172 @@
|
||||
# Difference Equation Analyzer 專案維護指引
|
||||
# Difference Equation Analyzer
|
||||
|
||||
本文件提供 `diff-eq-analyzer` 專案的日常維護、環境更新與故障排除指南。
|
||||
差分方程式與數位濾波器分析工具。後端使用 FastAPI，前端使用 Vue 3 + Vite 建置後由 FastAPI 以靜態檔案服務。
|
||||
|
||||
## 1. 系統服務管理 (Systemd)
|
||||
## 專案結構
|
||||
|
||||
本專案的後端 API (FastAPI) 以 systemd 服務 (`dea.service`) 的形式在背景執行。
|
||||
- `dea_api.py`：FastAPI 後端、API 端點、LAN 存取限制、安全標頭。
|
||||
- `src/`：Vue 前端原始碼。
|
||||
- `static/index.html`：正式 UI 入口，載入建置後的前端資源。
|
||||
- `static/build/app.js`、`static/build/app.css`：前端建置產物，正式服務會載入這兩個檔案。
|
||||
- `static/style.css`：既有自訂 CSS，由 `src/style.css` 引入。
|
||||
- `tests/`：後端回歸測試。
|
||||
- `dea.service`：systemd 服務設定範本。
|
||||
- `dea_legacy.py`：舊 Streamlit 版本，僅供參考。
|
||||
|
||||
### 常用指令
|
||||
## 使用網址
|
||||
|
||||
* **查看服務狀態：**
|
||||
```bash
|
||||
sudo systemctl status dea.service
|
||||
```
|
||||
* **啟動服務：**
|
||||
```bash
|
||||
sudo systemctl start dea.service
|
||||
```
|
||||
* **停止服務：**
|
||||
```bash
|
||||
sudo systemctl stop dea.service
|
||||
```
|
||||
* **重新啟動服務（更新程式碼後必備）：**
|
||||
```bash
|
||||
sudo systemctl restart dea.service
|
||||
```
|
||||
* **查看即時日誌 (Logs)：**
|
||||
```bash
|
||||
sudo journalctl -u dea.service -f
|
||||
```
|
||||
本機：
|
||||
|
||||
## 2. 虛擬環境與套件管理
|
||||
```bash
|
||||
http://localhost:8000/ui/
|
||||
```
|
||||
|
||||
專案使用 Python 虛擬環境 (`.venv`) 隔離依賴套件。若您需要更新套件或是因移動專案路徑導致環境異常，請依下列步驟重建虛擬環境：
|
||||
區網其他裝置：
|
||||
|
||||
1. **進入專案目錄：**
|
||||
```bash
|
||||
cd /home/wisetop/diff-eq-analyzer
|
||||
```
|
||||
2. **刪除舊的虛擬環境並重建：**
|
||||
```bash
|
||||
rm -rf .venv
|
||||
python3 -m venv .venv
|
||||
```
|
||||
3. **安裝必要套件：**
|
||||
```bash
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
4. **重新啟動系統服務以套用新環境：**
|
||||
```bash
|
||||
sudo systemctl restart dea.service
|
||||
```
|
||||
```bash
|
||||
http://192.168.2.58:8000/ui/
|
||||
```
|
||||
|
||||
## 3. 常見問題排除
|
||||
根路徑 `/` 會自動導向 `/ui/`。
|
||||
|
||||
### 3.1 服務無法啟動 (status=203/EXEC)
|
||||
* **原因：** 通常是因為 Python 虛擬環境的路徑錯誤，或是啟動腳本 (`uvicorn`) 內部寫死的絕對路徑與實際位置不符（例如專案資料夾被重新命名）。
|
||||
* **解法：** 參考上方的「虛擬環境與套件管理」，將 `.venv` 刪除並重新安裝，然後重啟 `dea.service` 即可。
|
||||
## 後端環境
|
||||
|
||||
### 3.2 網頁無法連線
|
||||
* **檢查後端狀態：** 執行 `sudo systemctl status dea.service` 確認 FastAPI 伺服器是否正常運作中（應顯示 `Active: active (running)`）。
|
||||
* **檢查防火牆設定：** 預設使用的 Port 為 `8000`，請確認防火牆或安全群組允許 `8000` 埠的入站連線。
|
||||
* **檢查綁定 IP：** 服務預設綁定於 `0.0.0.0`，代表接受所有網路介面的連線。如需限制，請修改 `dea.service` 內的 `ExecStart` 參數。
|
||||
建立或重建 Python 虛擬環境：
|
||||
|
||||
## 4. 變更專案設定檔
|
||||
若您修改了 `dea.service`（位於專案目錄內或 `/etc/systemd/system/dea.service`），請務必執行下列指令讓系統重新載入設定：
|
||||
```bash
|
||||
cd /home/wisetop/diff-eq-analyzer
|
||||
python3 -m venv .venv
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
本機開發啟動：
|
||||
|
||||
```bash
|
||||
.venv/bin/uvicorn dea_api:app --host 127.0.0.1 --port 8000
|
||||
```
|
||||
|
||||
## 前端建置
|
||||
|
||||
前端依賴由 `package.json` / `package-lock.json` 管理。首次安裝：
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
重新建置正式前端：
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
建置後會更新：
|
||||
|
||||
```text
|
||||
static/build/app.js
|
||||
static/build/app.css
|
||||
```
|
||||
|
||||
注意：正式頁面不再載入 Vue CDN 或 Tailwind CDN；Vue 會被打包到 `static/build/app.js`。目前仍使用 Plotly CDN。
|
||||
|
||||
## systemd 服務
|
||||
|
||||
查看狀態：
|
||||
|
||||
```bash
|
||||
sudo systemctl status dea.service
|
||||
```
|
||||
|
||||
啟動、停止、重啟：
|
||||
|
||||
```bash
|
||||
sudo systemctl start dea.service
|
||||
sudo systemctl stop dea.service
|
||||
sudo systemctl restart dea.service
|
||||
```
|
||||
|
||||
查看即時日誌：
|
||||
|
||||
```bash
|
||||
sudo journalctl -u dea.service -f
|
||||
```
|
||||
|
||||
修改 `dea.service` 或 `/etc/systemd/system/dea.service` 後：
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart dea.service
|
||||
```
|
||||
|
||||
## 測試與檢查
|
||||
|
||||
Python 語法檢查：
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m py_compile dea_api.py tests/test_dea_api.py
|
||||
```
|
||||
|
||||
後端測試：
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m unittest discover -s tests
|
||||
```
|
||||
|
||||
前端建置檢查：
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 安全與效能設定
|
||||
|
||||
後端目前包含：
|
||||
|
||||
- 僅允許 private / loopback IP 存取。
|
||||
- CSP、安全回應標頭、`X-Frame-Options: DENY`、`nosniff`。
|
||||
- CSV 上傳大小限制：10 MB。
|
||||
- 圖表用 CSV 回傳最多 5000 點，下載 CSV 仍保留完整資料。
|
||||
- 係數數量上限：64。
|
||||
- 濾波器頻率、係數有限值、`a[0]` 等輸入驗證。
|
||||
|
||||
目前 CSP 的 `script-src` 僅允許：
|
||||
|
||||
```text
|
||||
'self' https://cdn.plot.ly
|
||||
```
|
||||
|
||||
因此不再需要 `'unsafe-eval'`。
|
||||
|
||||
## 常見問題
|
||||
|
||||
### 網頁空白
|
||||
|
||||
1. 強制刷新瀏覽器：`Ctrl+F5`。
|
||||
2. 確認服務狀態：
|
||||
|
||||
```bash
|
||||
sudo systemctl status dea.service
|
||||
```
|
||||
|
||||
3. 確認靜態檔案存在：
|
||||
|
||||
```bash
|
||||
ls static/build/app.js static/build/app.css
|
||||
```
|
||||
|
||||
4. 若剛改前端，請重新建置並重啟：
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
sudo systemctl restart dea.service
|
||||
```
|
||||
|
||||
### 服務無法啟動，出現 status=203/EXEC
|
||||
|
||||
通常是 `.venv` 路徑或 `uvicorn` 腳本路徑失效。重建虛擬環境後再重啟：
|
||||
|
||||
```bash
|
||||
rm -rf .venv
|
||||
python3 -m venv .venv
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
sudo systemctl restart dea.service
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user