开源免费、单校自建、纯 Web 的中小学排课、调课与代课管理系统。 适用于小学、初中、普通高中、综合高中和中职，以教务主任的日常工作流程为中心设计。
系统覆盖学期基础数据、教学任务、手动与自动排课（OR-Tools CP-SAT 引擎），以及学期中的请假、调课、代课、通知和课时统计。使用 Docker Compose 即可部署到校内主机，业务数据保存在学校自己的环境中。
English summary: A free, open-source (MIT), self-hosted scheduling, course-change, and substitute-teaching system for schools in mainland China. It provides a Simplified Chinese interface, Gregorian academic years, the Asia/Shanghai timezone, manual and automatic scheduling, leave handling, notifications, exports, and backups.
| 领域 | 内容 |
|---|---|
| 排课工作台 | 创建学期并按五步维护班级、作息、科目与教师档案、教学任务，完成前置检查和自动排课 |
| 基础数据与手动排课 | 教室/场地、Excel 导入、教师账号绑定、拖拽式周课表、单格冲突检查(<100ms)、多草稿版本管理与发布 |
| 自动排课 | OR-Tools CP-SAT 引擎,H1–H10 硬约束 + S1–S8 软约束加权;后台求解显示实时进度;无解时以教务语言定位冲突并支持部分排课 |
| 调课与代课 | 请假登记与受影响节次展开、代课推荐引擎、调课验证、指派即生效、站内+Email 通知与确认、今日看板与 A4 公告打印、月结课时统计(Excel) |
| 报表/导出 | 班级、教师、教室/场地课表导出 Excel / PDF（内嵌中文字体）/ PNG、全校总表、批量 ZIP |
| 运维 | 每日自动备份 + 手动备份 / 下载 / 上传恢复(恢复前自动保护、恢复后强制重登)、审计记录、三角色 RBAC(内置系统管理员/教务主任/教师) |
需先安装 Docker。完整步骤(含 Windows / Linux / NAS)见 部署手册。
脚本会询问学校名称、管理员密码和对外端口，并自动生成密钥；执行前会先检查同名项目，避免误接管另一套部署。
Windows(PowerShell):
Invoke-WebRequest https://raw.githubusercontent.com/sine-io/Course_Scheduling_System/main/install.ps1 -OutFile install.ps1
.\install.ps1Linux / macOS / NAS:
curl -fLO https://raw.githubusercontent.com/sine-io/Course_Scheduling_System/main/install.sh
bash install.sh脚本刻意采用“先下载、再执行”的方式，方便学校管理员先检查内容；更多选项见安装指南。
mkdir scheduling && cd scheduling
curl -fLO https://raw.githubusercontent.com/sine-io/Course_Scheduling_System/main/docker-compose.yml
curl -fL https://raw.githubusercontent.com/sine-io/Course_Scheduling_System/main/.env.example -o .env
# 编辑 .env:改 ADMIN_PASSWORD、SCHOOL_NAME、SECRET_KEY
sudo docker compose pull
sudo docker compose up -dgit clone https://github.com/sine-io/Course_Scheduling_System.git
cd Course_Scheduling_System
cp .env.example .env # 改 ADMIN_PASSWORD、SCHOOL_NAME、SECRET_KEY
sudo docker compose up -d # 首次会构建镜像，需数分钟启动后开浏览器连 http://<主机IP>(本机为 http://localhost),以 .env 的管理员账号和密码登录；进入“排课工作台”创建当前学期，再使用工作台内的“学期管理”“校历与准备”“资源与导入”辅助工作面完成准备，随后按五个步骤继续排课。
- 健康检查:
http://localhost/api/health→{"status":"ok"} - 容器状态：
sudo docker compose ps（六个容器均应为 healthy）
2 核 / 4GB RAM / 10GB 磁盘(自动排课建议 4 核 8GB)。支持 x86-64 与 ARM64(NAS / 树莓派)。
| 排课工作台(拖拽排课、三视角、实时冲突检查) | 自动排课(进度、软约束达成度) |
|---|---|
 |
 |
| 今日调课与代课看板(可打印 A4 通知单) | 课表查询与导出(Excel / PDF / PNG) |
|---|---|
 |
 |
完整逐章图解见教务主任操作手册。
| 文件 | 内容 |
|---|---|
| 教务主任操作手册（源文件） | 面向用户：学期准备、教学任务、排课、调课与代课、导出、备份和常见问题 |
| 部署手册 | 给安装者:安装、升级、备份、域名 HTTPS、FAQ |
| 架构设计 | 需求、数据模型、排课引擎和技术栈（架构规范来源） |
| 开发任务卡 | Milestone 与逐卡实现记录 |
| 变更记录 | 各版本变更 |
| 贡献指南 | 开发环境、程序风格、测试、发布流程 |
离线阅读：
docs/下的部署与开发 Markdown 文档均有对应的.html文件。可直接用浏览器打开，无需联网；修改 Markdown 后运行python scripts/build_docs.py重新生成，CI 会检查两者是否同步。
| 层 | 技术 |
|---|---|
| 前端 | 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；三个后端容器共用 backend 镜像) |
v1.2.0 已发行(2026-08-02)。 六大里程碑 M0–M5 全部完成,功能齐备并经完整验收；本版加入可配置学校名称、教学任务超课时上限、一键安装脚本和离线文档。官方镜像(amd64 + arm64)已发布于 GHCR。当前未发布版本将 API、worker 与 worker-ops 统一为 course_scheduling_system-backend 镜像。
请直接从最新版开始安装(见上方快速开始);v1.2.0 是目前建议使用的版本。各版变更见 CHANGELOG,开发历程见 docs/tasks.md。
系统仍在实际校园环境试用中。如果你是第一批用户，欢迎通过 Issues 报告问题。
发现错误、有功能建议,或想分享贵校的使用经验,都非常欢迎:
- 反馈问题 / 提出建议：在本项目创建 GitHub Issue；附上操作步骤和
sudo docker compose logs片段有助于更快定位问题。
这套系统是为第一线教务主任而写的,你的实际使用反馈对它的改进最有帮助。
MIT — 可自由使用、修改、散布。欢迎各校自架与二次开发。
执行时使用的第三方组件与其授权见 THIRD-PARTY-NOTICES.md(均与 MIT 兼容)。