# 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 下进行。 ### 安装步骤 ```powershell 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 数据。 ### 升级 ```powershell git pull docker compose --env-file .env up -d --build ``` 数据库结构由后端启动时自动迁移,升级前建议先备份。 ## 常见问题 - **浏览器列不出摄像头/麦克风**:确认浏览器已允许权限,或设备被其他软件占用;希沃一体机上需确认摄像头/麦克风驱动已暴露给浏览器。 - **直播卡顿/黑屏**:检查教师端与服务器之间、观看端与服务器之间的 50000-50100/UDP 端口是否放行;内网测试请用 `localhost` 访问。 - **家长看不到回放**:确认管理员在绑定审核里授予了「回放」权限(直播与回放是分开授权的)。 - **录像没有生成**:确认课程勾选了「允许录像」且学校开启了录像开关,可在管理端「课程录像」查看失败原因。 ## 开发者 本地开发热更新预览与测试命令见 `docs/IMPLEMENTATION_STATUS.md`;系统架构见 `docs/ARCHITECTURE.md`;部署细节见 `docs/DEPLOYMENT.md`。