DEPLOYMENT GUIDE

常見問題 FAQ

原始檔 docs/deploy/faq.md · 在 GitHub 上檢視

安裝與啟動

Q:docker compose up -d 後開網頁看到「502」或「無法連線」。 容器可能還在啟動(尤其首次要跑資料庫遷移)。等 20–30 秒再試,並看狀態:

docker compose ps          # 看是否都 healthy
      docker compose logs api    # 看 api 是否卡在遷移或報錯
      

Q:docker compose ps 有容器一直 restarting。 看該容器 log 找原因:

docker compose logs --tail=50 <服務名>   # 例如 api / worker / postgres
      

常見:.env 的 DATABASE_URL 與 POSTGRES_* 帳密不一致;SECRET_KEY 未設。

Q:80 埠被占用,啟動失敗(port is already allocated)。 改 .env 的 HTTP_PORT(例如 8080)再 docker compose up -d,改用 http://<主機IP>:8080。

Q:裝好後第一次登入就一直「帳號或密碼錯誤」,接著被鎖 15 分鐘。 會鎖定代表管理員帳號已經建好,只是資料庫裡的密碼和你輸入的不同;跟網路、IP、手機熱點或在國外都無關(用 localhost 登入時,連線根本不出這台電腦)。常見原因:

• 先啟動過一次才改 .env 的密碼。 管理員帳號只在第一次啟動時依 .env 建立,之後改 .env 不會生效。這時的密碼是當時 .env 的值,通常是預設的 changeme。
• 密碼裡有 $ 或 #。 docker compose 會把 $ 當成變數截掉,# 前有空白會被當成註解。

另外,鎖定是鎖帳號,不是鎖網路:被鎖的 15 分鐘內,換網路、換 IP、甚至密碼打對都進不去。

解法:在系統資料夾執行下面這行,畫面會印出一組臨時密碼並解除鎖定,用 admin 和它登入後再改成自己的密碼(v1.3.2 起):

docker compose exec api python -m app.scripts.reset_admin
      

Q:校內其他電腦連不到。 確認用的是主機的區網 IP(非 localhost),且主機防火牆放行該埠。手機/平板需與主機同一網段(同一 Wi-Fi)。

---

帳號與登入

Q:忘記管理員密碼怎麼辦? 在主機上、系統資料夾裡執行:

docker compose exec api python -m app.scripts.reset_admin
      

畫面會印出一組臨時密碼,並解除登入鎖定、重新啟用帳號;用它登入後系統會要求立即改密碼,原本各裝置的登入都會失效。資料完全不受影響。管理員帳號不是 admin 時加上 --username 你的帳號;帳號打錯時,指令會列出現有的系統管理員帳號。(v1.3.2 起;更早的版本請先升級。)

.env 的 ADMIN_PASSWORD 只在系統第一次啟動時使用,改它不會改到現有帳號的密碼。教師、組長忘記密碼,由系統管理員登入後到「帳號管理」重設即可,不需要這個指令。

Q:還原備份後大家被登出了。 這是預期行為。還原會替換整個資料庫(含帳號),為安全起見系統會強制所有人以還原時點的帳密重新登入。

Q:老師收不到調代課 Email。 Email 為選配;未在「系統管理」設定 SMTP 時,只有站內通知(鈴鐺),系統一切正常。要寄 Email 需填學校的 SMTP 主機資訊,並可按「寄測試信」當場驗證。

---

資料與備份

Q:我的資料存在哪?會不會不見? 存在 Docker volume pgdata。只要不刪這個 volume,docker compose down / 重啟 / 升級都不會動到資料。但主機硬碟壞掉 volume 會一起沒,所以務必做異地備援。

Q:docker compose down 會刪資料嗎? 不會。down 只停止並移除容器,volume 保留。只有 docker compose down -v 的 -v 會刪 volume(含你的資料),請勿誤用。

Q:怎麼把系統搬到新主機? 新主機裝好空系統 → 舊主機下載一份備份 .dump → 新主機「系統管理 → 上傳還原」。詳見備份指南。

---

效能與規模

Q:自動排課很慢或跑不出來。 排課是計算密集工作,受班級數、約束複雜度影響。建議主機 ≥ 4 核 8GB。無解時系統會給「衝突定位」報告,依提示放寬條件或補資源。可設定求解逾時(預設 10 分鐘),逾時取當前最佳解。

Q:頁面偶爾轉圈久。 自動排課/大量匯出時 worker 較忙,但與 api 分離,一般操作不受影響。自 v1.1 起排課(worker)與匯出/備份(worker-ops)分屬兩個容器,排課進行中按匯出仍是秒回。若持續緩慢,查主機資源(docker stats)是否吃緊。

Q:匯出/備份時出現「維運背景服務(worker-ops)沒有在執行」。

你的 docker-compose.yml 少了 worker-ops 這個容器(多半是用了舊版的 compose 檔)。它負責匯出、備份、還原、寄信與每日自動備份——沒有它,這些功能全都沒人處理,而且每日自動備份是無聲停擺的。

取得最新的 compose 檔再重啟即可,資料不受影響:

curl -fLO https://raw.githubusercontent.com/begin0808/Course_Scheduling_System/main/docker-compose.yml
      docker compose up -d
      docker compose ps          # 應看到六個容器,含 worker 與 worker-ops
      

Q:匯出課表 / 備份失敗,說「背景忙碌或逾時」。

worker-ops 有在跑但沒做完。查它的 log:

docker compose ps worker-ops
      docker compose logs --tail=50 worker-ops
      

PDF/PNG 匯出在低階機器上偶爾會超過 90 秒;主機吃緊(docker stats)時先讓自動排課跑完再試。

---

升級與版本

Q:怎麼知道有沒有新版、這版改了什麼? v1.2.3 起,系統管理員登入後:有新版時右上角會出現「有新版本 vX.Y.Z」,「系統管理 → 系統版本」可看到目前版本、最新正式版,並連到更新內容與升級指南。系統只提醒、不會自動升級。也可以直接看專案 CHANGELOG.md 與 GitHub Releases。

Q:新版本提醒會把學校資料傳出去嗎?可以關掉嗎? 不會。系統每天最多一次向 GitHub 讀取本專案公開的最新版本資訊(一個 GET 請求),不送出任何學校資料。學校主機不能連外時,只會在系統版本卡片顯示「無法連線」,不影響任何功能。若不希望主機連外,在 .env 加上 UPDATE_CHECK_ENABLED=false 後執行 docker compose up -d 即可關閉。

Q:怎麼看目前是哪一版? 左側選單最下方會顯示版本號(v1.2.3 起)。回報問題時附上版本號,會比較容易查。

Q:升級會不會弄壞資料? 資料表結構變更由 api 啟動時自動、向前相容地遷移,資料保留。仍建議升級前先「立即備份」。破壞性變更(若有)會在 CHANGELOG 該版本以 ⚠️ 標註。

---

其他

Q:可以多所學校共用一套嗎? 本系統設計為單校自架,一所學校一套部署,資料彼此隔離、最單純也最安全。多校請各自部署。

Q:這套系統的授權是什麼?學校可以免費用嗎? 可以。v1.4.1 起採用 AGPL-3.0,學校自架、使用、修改都免費,不需要申請。 只有在修改程式後再提供給別人使用(包括架成網站讓其他學校從網路上使用)時,必須公開修改後的完整原始碼, 並同樣採用 AGPL-3.0。v1.4.0 以前的版本以 MIT 發布,仍照 MIT 使用。

Q:如何完全移除?

docker compose down -v     # ⚠️ 連同資料 volume 一起刪除,不可復原,請先備份!
      

Q:找不到答案 / 想回報問題? 到專案 GitHub 開 Issue(見 CONTRIBUTING.md)。回報時附上 docker compose logs 相關片段會更快解決。