開源免費、單校自架、純 Web 的中小學排課與調代課系統。 適用國小、國中、普通型高中、綜合型高中、技術型高中,以教學組長的日常工作流程為中心設計。
從學期基礎資料、手動與自動排課(OR-Tools CP-SAT 引擎),到學期中最繁瑣的請假、代課、調課、通知與鐘點統計,一套涵蓋。以 Docker Compose 一鍵部署在校內一台主機上,資料不出校。
English summary: A free, open-source (MIT), self-hosted, web-based course-scheduling and teacher-substitution system for Taiwanese K–12 schools. It covers the school-timetabling office's full workflow: semester/period setup, manual drag-and-drop scheduling, automatic scheduling via an OR-Tools CP-SAT engine with human-readable conflict explanation, and the day-to-day of leave requests, substitute assignment, notifications, and substitution-hour reporting. One school, one self-hosted deployment (no multi-tenant SaaS). One-command Docker Compose install. UI is Traditional Chinese with Taiwan educational terminology.
| 領域 | 內容 |
|---|---|
| 基礎資料 | 學期/節次表(多學制範本)、教師/班級/科目/場地、Excel 匯入、設定精靈、開新學期複製、混合學制(班級↔節次表指派) |
| 配課與手動排課 | 配課管理(跑班群組、協同教學、連堂)、鐘點即時統計、拖拉式週課表、單格衝突檢查(<100ms)、多草稿版本管理與發布 |
| 自動排課 | OR-Tools CP-SAT 引擎,H1–H10 硬約束 + S1–S8 軟約束加權;背景求解含即時進度;無解時以教務語言定位衝突並支援部分排課 |
| 調代課 | 請假登記與受影響節次展開、代課推薦引擎、調課驗證、指派即生效、站內+Email 通知與確認、今日看板與 A4 公告列印、月結鐘點統計(Excel) |
| 報表/匯出 | 班級/教師/場地課表匯出 Excel / PDF(內嵌中文字型)/ PNG、全校總表、批次 zip |
| 維運 | 每日自動備份 + 手動備份 / 下載 / 上傳還原(還原前自動保護、還原後強制重登)、稽核紀錄、RBAC(管理員/主任/組長/教師) |
需先安裝 Docker。完整步驟(含 Windows / Linux / NAS)見 部署手冊。
下載後執行,回答校名、管理員密碼、埠號三個問題即可。金鑰自動產生、埠號衝突自動閃開,不必手改 .env。
Windows(PowerShell):
Invoke-WebRequest https://raw.githubusercontent.com/begin0808/Course_Scheduling_System/main/install.ps1 -OutFile install.ps1
.\install.ps1Linux / macOS / NAS:
curl -fLO https://raw.githubusercontent.com/begin0808/Course_Scheduling_System/main/install.sh
bash install.sh刻意設計成「先下載、再執行」而非
curl | sh——這是要進學校主機的東西,請先打開看過內容。
mkdir scheduling && cd scheduling
curl -fLO https://raw.githubusercontent.com/begin0808/Course_Scheduling_System/main/docker-compose.yml
curl -fL https://raw.githubusercontent.com/begin0808/Course_Scheduling_System/main/.env.example -o .env
# 編輯 .env:改 ADMIN_PASSWORD、SCHOOL_NAME、SECRET_KEY
docker compose pull
docker compose up -dWindows 使用者:上面是 bash 語法,PowerShell 的
curl是Invoke-WebRequest的別名、 吃不懂-fLO。請改用安裝指南裡的 PowerShell 版本下載指令。
git clone https://github.com/begin0808/Course_Scheduling_System.git
cd Course_Scheduling_System
cp .env.example .env # 改 ADMIN_PASSWORD、SCHOOL_NAME、SECRET_KEY
docker compose up -d # 首次會建置映像,需數分鐘啟動後開瀏覽器連 http://<主機IP>(本機為 http://localhost),以 .env 的管理員帳密登入,依設定精靈完成建置。
想先試看看? 還沒建學期時,到「系統管理 → 示範資料」按一下,會建出一所完整的虛構國中(18 班、48 位教師、384 筆配課),十幾秒就能跑出全校課表——不必先手 key 資料就能把排課、調代課、匯出、備份整套流程走過一遍。
- 健康檢查:
http://localhost/api/health→{"status":"ok"} - 容器狀態:
docker compose ps(六個容器皆應 healthy)
2 核 / 4GB RAM / 10GB 磁碟(自動排課建議 4 核 8GB)。支援 x86-64 與 ARM64(NAS / 樹莓派)。
| 排課工作台(拖拉排課、三視角、即時衝突) | 自動排課(進度、軟約束達成度) |
|---|---|
 |
 |
| 今日調代課看板(可列印 A4 通知單) | 課表查詢與匯出(Excel / PDF / PNG) |
|---|---|
 |
 |
完整逐章圖解見教學組長操作手冊。
| 文件 | 內容 |
|---|---|
| 教學組長操作手冊（原始檔） | 給使用者:設定精靈、配課、排課、調代課、匯出、備份、FAQ(11 章圖文網頁) |
| 部署手冊 | 給安裝者:安裝、升級、備份、網域 HTTPS、FAQ |
| 架構設計 | 需求、資料模型、排課引擎、技術棧(規格權威來源) |
| 開發任務卡 | Milestone 與逐卡實作紀錄 |
| 變更紀錄 | 各版本變更 |
| 貢獻指南 | 開發環境、程式風格、測試、發布流程 |
離線閱讀:上表
docs/下的每份.md都有一份對應的.html(如docs/deploy/install.html), 附側邊目錄與深/淺色切換,雙擊即可用瀏覽器開,不必連網、不必裝軟體——機房裡沒網路時特別好用。 這些 HTML 由python scripts/build_docs.py從 Markdown 產生,請勿直接編輯;改完.md重跑一次即可。
| 層 | 技術 |
|---|---|
| 前端 | Vue 3 + TypeScript + Vite + Pinia + Naive UI |
| 後端 | Python 3.12 + FastAPI + SQLAlchemy 2 + Pydantic v2 |
| 排課引擎 | Google OR-Tools CP-SAT(RQ + Redis 背景執行) |
| 匯出 | openpyxl(Excel)、WeasyPrint(PDF,內嵌 Noto CJK)、poppler(PNG) |
| 資料庫 | PostgreSQL 16 |
| 反向代理 | Caddy(內網 HTTP;設網域即自動 HTTPS) |
| 部署 | Docker Compose(6 容器:web / api / worker(排課)/ worker-ops(匯出·備份·定時)/ postgres / redis) |
v1.2.0 已發行(2026-08-02)。 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 522 項單元/整合測試、33 項 Playwright 端對端測試涵蓋全部 20 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。
本版新增一鍵示範資料——裝好後不必輸入任何資料,兩分鐘內就能看到一張排好的全校課表。
請直接從最新版開始安裝(見上方快速開始);v1.2.0 是目前建議使用的版本。各版變更見 CHANGELOG,開發歷程見 docs/tasks.md。
系統仍在實際校園環境試用中,若你是第一批使用者,歡迎透過 Issues 回報任何問題。
發現錯誤、有功能建議,或想分享貴校的使用經驗,都非常歡迎:
- 回報問題 / 提出建議:於本專案開 GitHub Issue(附上操作步驟與
docker compose logs片段會更快解決) - 來信聯絡:專案開發者 國立南大附中 李佳恩老師 — begin0808@gmail.com
這套系統是為第一線教學組長而寫的,你的實際使用回饋對它的改進最有幫助。
MIT — 可自由使用、修改、散布。歡迎各校自架與二次開發。
執行時使用的第三方元件與其授權見 THIRD-PARTY-NOTICES.md(皆與 MIT 相容)。