Difference Equation Analyzer 專案維護指引

本文件提供 diff-eq-analyzer 專案的日常維護、環境更新與故障排除指南。

1. 系統服務管理 (Systemd)

本專案的後端 API (FastAPI) 以 systemd 服務 (dea.service) 的形式在背景執行。

常用指令

• 查看服務狀態：

  sudo systemctl status dea.service
  

• 啟動服務：

  sudo systemctl start dea.service
  

• 停止服務：

  sudo systemctl stop dea.service
  

• 重新啟動服務（更新程式碼後必備）：

  sudo systemctl restart dea.service
  

• 查看即時日誌 (Logs)：

  sudo journalctl -u dea.service -f
  

2. 虛擬環境與套件管理

專案使用 Python 虛擬環境 (.venv) 隔離依賴套件。若您需要更新套件或是因移動專案路徑導致環境異常，請依下列步驟重建虛擬環境：

1. 進入專案目錄：

   cd /home/wisetop/diff-eq-analyzer
   

2. 刪除舊的虛擬環境並重建：

   rm -rf .venv
   python3 -m venv .venv
   

3. 安裝必要套件：

   .venv/bin/pip install -r requirements.txt
   

4. 重新啟動系統服務以套用新環境：

   sudo systemctl restart dea.service
   

3. 常見問題排除

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 參數。

4. 變更專案設定檔

若您修改了 dea.service（位於專案目錄內或 /etc/systemd/system/dea.service），請務必執行下列指令讓系統重新載入設定：

sudo systemctl daemon-reload
sudo systemctl restart dea.service