DEPLOYMENT GUIDE

部署與維運手冊

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

給學校資訊管理者/教學組長的完整操作文件。系統為單校自架、純 Web,以 Docker Compose 一鍵部署,六個容器(web / api / worker / worker-ops / postgres / redis)在一台主機上跑完。

worker 專跑自動排課(一次可跑好幾分鐘),worker-ops 跑匯出、備份、還原、寄信與定時任務。分開的用意是:排課那幾分鐘裡,你按「匯出課表」仍然是秒回的。

我該從哪裡開始?

三分鐘理解這套系統怎麼跑

                 使用者瀏覽器
                            │  http://校內主機IP
                    ┌───────▼────────┐
                    │  web (Caddy)   │  靜態前端 + 反向代理 /api
                    └───────┬────────┘
                            │
              ┌─────────────▼──────────────┐
              │  api (FastAPI)             │  登入、資料維護、手動排課、報表
              └───┬──────────────────┬─────┘
                  │                  │
           ┌──────▼──────┐    ┌──────▼───────┐
           │ postgres    │    │ redis        │  兩條工作佇列 + session 時效
           │ (你的資料)  │    └──┬────────┬──┘
           └─────────────┘       │        │
                  ▲       ┌──────▼─────┐ ┌▼──────────────┐
                  ├───────┤ worker     │ │ worker-ops    │
                  │       │ 自動排課   │ │ 匯出/備份/還原 │
                  └───────┤ (可跑數分鐘)│ │ 寄信/每日備份  │
                          └────────────┘ └───────────────┘
      

• 你的資料只在 postgres(存於 Docker volume pgdata),備份檔在 volume backups。只要這兩者在,系統可隨時重建。
• worker 只跑自動排課——它一開跑就會佔住好幾分鐘,這是正常的。
• worker-ops 跑匯出、備份、還原、寄信與每日自動備份。分開的用意:排課那幾分鐘正是組長最常按「匯出課表」的時候,不該排在排課後面等。
• 全部跑在一台主機,不需要外網、不需要雲端帳號,校內網路即可使用。

兩種部署方式

同一份 docker-compose.yml 支援兩種做法:

1. 拉取官方預建映像(推薦,免建置、升級快):只要 docker-compose.yml + .env 兩個檔案,docker compose pull && docker compose up -d。
2. 從原始碼自行建置(想改程式、或內網無法連 GHCR 時):git clone 本專案後 docker compose up -d,首次會在本機建置映像(數分鐘)。

詳見 安裝指南。

名詞對照