开源免费、单校自架、纯 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.3.0 已发行(2026-10-18)。 六大里程碑 M0–M5 全部完成,功能齐备并经完整验收(后端 654 项单元/整合测试、50 项 Playwright 端对端测试涵盖全部 20 个页面,每次提交皆对真实 Docker 全栈跑过)。官方映像(amd64 + arm64)已发布于 GHCR。
v1.3.0 支援单双周课程(同一节单周、双周轮流上不同的课,排课、请假代课、调课、巡堂表、课时都分单双周;
请直接从最新版开始安装(见上方快速开始);v1.3.0 是目前建议使用的版本。各版变更见 CHANGELOG,开发历程见 docs/tasks.md。
系统仍在实际校园环境试用中,若你是第一批用户,欢迎通过 Issues 回报任何问题。
发现错误、有功能建议,或想分享贵校的使用经验,都非常欢迎:
- 回报问题 / 提出建议:于本专案开 GitHub Issue(附上操作步骤与
docker compose logs片段会更快解决) - 来信联络:专案开发者 国立南大附中 李佳恩老师 — begin0808@gmail.com
这套系统是为第一线教学组长而写的,你的实际使用回馈对它的改进最有帮助。
MIT — 可自由使用、修改、散布。欢迎各校自架与二次开发。
执行时使用的第三方元件与其授权见 THIRD-PARTY-NOTICES.md(皆与 MIT 相容)。



