ws50529
173 lines
3.3 KiB
Markdown
173 lines
3.3 KiB
Markdown
# Difference Equation Analyzer
|
||
|
||
差分方程式與數位濾波器分析工具。後端使用 FastAPI，前端使用 Vue 3 + Vite 建置後由 FastAPI 以靜態檔案服務。
|
||
|
||
## 專案結構
|
||
|
||
- `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
|
||
http://localhost:8000/ui/
|
||
```
|
||
|
||
區網其他裝置：
|
||
|
||
```bash
|
||
http://192.168.2.58:8000/ui/
|
||
```
|
||
|
||
根路徑 `/` 會自動導向 `/ui/`。
|
||
|
||
## 後端環境
|
||
|
||
建立或重建 Python 虛擬環境：
|
||
|
||
```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
|
||
```
|