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

98 lines
5.0 KiB
Markdown

# 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`。