d8b5b99b9ed942c45b25c8e75086e1484c0fca94
Reviewed-on: #2
XH巡课
校园课堂直播、巡课与课程回放系统。教师在教室里用浏览器开播课堂,家长经审核后观看孩子班级的实时课堂与历史回放,学校管理员统一管理班级、课程、直播、录像和账号。
功能一览
| 角色 | 入口 | 能做什么 |
|---|---|---|
| 管理员 | /admin |
学校/年级/班级/课程/课表管理,用户与家长绑定审核,直播监控与强制停播,录像管理与删除,巡课记录,邮件与短信配置,通知模板,存储占用,操作日志,网站名称/Logo/主题/注册策略/安全设置 |
| 教师 | /teacher |
选择班级和课程,独立选择摄像头和麦克风,预览画面、测试声音,一键开播/停播,查看直播时长与在线人数 |
| 家长 | /parent |
注册账号,申请绑定孩子班级,审核通过后观看授权班级的实时直播与历史回放,查看今日课程表 |
| 巡课人员 | /inspect |
多教室同屏巡课(默认静音,点选一间听声音),填写巡课记录 |
登录后系统按角色自动跳转到对应入口。首页 / 是网站落地页。
家长使用流程
- 打开网站,点「注册家长账号」,填写用户名、姓名、邮箱或手机号。
- 如果学校开启了注册审核,需等管理员在「用户管理」里通过。
- 登录后进入家长端,点「申请绑定班级」,选择学校班级,填写孩子姓名和学号,勾选需要的权限(直播/回放可分别申请)。
- 管理员在「家长绑定审核」核实身份后,分别授予直播和回放权限。
- 通过后,首页会出现「正在直播」卡片,点进去即可观看;「最近回放」和「回放」页可看历史课程录像。
教师开播流程
- 打开
/teacher,浏览器会请求摄像头和麦克风权限,点「允许」。 - 页面自动列出电脑上的摄像头和麦克风(两个独立选择框),选择要用的设备。
- 点「预览画面」确认摄像头正常,点「测试麦克风」说话看电平条是否跳动。
- 选择班级和课程,点「开始直播」。
- 直播中页面持续显示「正在直播」、直播时长和在线人数;下课后点「结束直播」,系统自动停止采集并生成课程录像。
部署(Docker Compose)
环境要求
- 服务器 4 核 8G 起步,直播观看人数越多需要的 CPU 和带宽越高(每间直播教室上行建议 ≥ 4 Mbps)。
- 摄像头/麦克风采集发生在教师电脑的浏览器里,服务器只做转发和录像。
- 浏览器访问摄像头必须在
localhost或 HTTPS 下进行。
安装步骤
git clone https://git.xhmcl.com/xhgit/XH-XunKe.git
cd XH-XunKe
copy .env.example .env
# 编辑 .env:必须更换 JWT_SECRET、APP_ENCRYPTION_KEY、LIVEKIT_API_SECRET、
# MINIO_SECRET_KEY 和数据库密码,并把 APP_PROD_GUARD 设为 true
docker compose --env-file .env up -d --build
启动后:
- 网站入口:
http://服务器IP:18088(生产环境请用 Nginx/Caddy 配置 HTTPS 反向代理到 18088) - 首次登录:用
.env里的ADMIN_USERNAME/ADMIN_PASSWORD登录管理端,然后到「用户管理」修改密码、按需创建账号。系统不提供公开的固定默认密码。 - 修改网站名称、Logo、公告:管理端 →「系统设置」→「网站设置」。
端口说明
| 端口 | 用途 |
|---|---|
| 18088 | 网站(HTTP) |
| 8080 | 后端 API(一般只对内) |
| 7880/7881 | LiveKit WebSocket / TCP |
| 50000-50100/UDP | WebRTC 媒体传输 |
| 9000/9001 | MinIO 对象存储(录像)/ 控制台 |
跨公网观看时,上述 LiveKit 与 UDP 端口段必须可达,不能只开一个 HTTPS 端口;学校网络有 NAT 时还需配置 TURN 服务器,否则远端浏览器无法建立媒体连接。
数据与备份
数据保存在三个 Docker 卷里,备份这三个卷即可完整恢复:
pg-data:账号、班级、课程、直播与录像记录redis-data:会话与在线状态(可丢弃,不影响业务数据)minio-data:课程录像文件
建议定期用 docker run --rm -v pg-data:/data ... 方式 dump PostgreSQL 并快照 MinIO 数据。
升级
git pull
docker compose --env-file .env up -d --build
数据库结构由后端启动时自动迁移,升级前建议先备份。
常见问题
- 浏览器列不出摄像头/麦克风:确认浏览器已允许权限,或设备被其他软件占用;希沃一体机上需确认摄像头/麦克风驱动已暴露给浏览器。
- 直播卡顿/黑屏:检查教师端与服务器之间、观看端与服务器之间的 50000-50100/UDP 端口是否放行;内网测试请用
localhost访问。 - 家长看不到回放:确认管理员在绑定审核里授予了「回放」权限(直播与回放是分开授权的)。
- 录像没有生成:确认课程勾选了「允许录像」且学校开启了录像开关,可在管理端「课程录像」查看失败原因。
开发者
本地开发热更新预览与测试命令见 docs/IMPLEMENTATION_STATUS.md;系统架构见 docs/ARCHITECTURE.md;部署细节见 docs/DEPLOYMENT.md。
Languages
Java
46.6%
Vue
42.9%
JavaScript
4.6%
CSS
2.3%
TypeScript
2%
Other
1.5%