Files
XH-XunKe/README.md
T
2026-11-22 15:12:13 +08:00

5.0 KiB

XH巡课

校园课堂直播、巡课与课程回放系统。教师在教室里用浏览器开播课堂,家长经审核后观看孩子班级的实时课堂与历史回放,学校管理员统一管理班级、课程、直播、录像和账号。

功能一览

角色 入口 能做什么
管理员 /admin 学校/年级/班级/课程/课表管理,用户与家长绑定审核,直播监控与强制停播,录像管理与删除,巡课记录,邮件与短信配置,通知模板,存储占用,操作日志,网站名称/Logo/主题/注册策略/安全设置
教师 /teacher 选择班级和课程,独立选择摄像头和麦克风,预览画面、测试声音,一键开播/停播,查看直播时长与在线人数
家长 /parent 注册账号,申请绑定孩子班级,审核通过后观看授权班级的实时直播与历史回放,查看今日课程表
巡课人员 /inspect 多教室同屏巡课(默认静音,点选一间听声音),填写巡课记录

登录后系统按角色自动跳转到对应入口。首页 / 是网站落地页。

家长使用流程

  1. 打开网站,点「注册家长账号」,填写用户名、姓名、邮箱或手机号。
  2. 如果学校开启了注册审核,需等管理员在「用户管理」里通过。
  3. 登录后进入家长端,点「申请绑定班级」,选择学校班级,填写孩子姓名和学号,勾选需要的权限(直播/回放可分别申请)。
  4. 管理员在「家长绑定审核」核实身份后,分别授予直播和回放权限。
  5. 通过后,首页会出现「正在直播」卡片,点进去即可观看;「最近回放」和「回放」页可看历史课程录像。

教师开播流程

  1. 打开 /teacher,浏览器会请求摄像头和麦克风权限,点「允许」。
  2. 页面自动列出电脑上的摄像头和麦克风(两个独立选择框),选择要用的设备。
  3. 点「预览画面」确认摄像头正常,点「测试麦克风」说话看电平条是否跳动。
  4. 选择班级和课程,点「开始直播」。
  5. 直播中页面持续显示「正在直播」、直播时长和在线人数;下课后点「结束直播」,系统自动停止采集并生成课程录像。

部署(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。