From e8390717d55c8e160266d86544069a050bccdff4 Mon Sep 17 00:00:00 2001 From: itxiaohui <193942343@qq.com> Date: Sun, 22 Nov 2026 15:12:13 +0800 Subject: [PATCH] =?UTF-8?q?README=20=E6=94=B9=E4=B8=BA=E9=9D=A2=E5=90=91?= =?UTF-8?q?=E7=94=A8=E6=88=B7=E7=9A=84=E4=BD=BF=E7=94=A8=E4=B8=8E=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Code --- README.md | 103 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 80 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 4b30a8d..bc789db 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,97 @@ # XH巡课 -校园课堂直播、巡课和回放。Java 只在 Docker 里编译和运行,不要在 Windows 上安装 JDK。 +校园课堂直播、巡课与课程回放系统。教师在教室里用浏览器开播课堂,家长经审核后观看孩子班级的实时课堂与历史回放,学校管理员统一管理班级、课程、直播、录像和账号。 -## 本地开发(热更新预览) +## 功能一览 + +| 角色 | 入口 | 能做什么 | +| --- | --- | --- | +| 管理员 | `/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 -docker compose --env-file .env up -d # 起后端、数据库、LiveKit、Egress、MinIO -docker compose stop web # 18088 改用 Vite 开发服务器 -cd frontend -npm install -npm run dev # http://localhost:18088,改动即时生效 +# 编辑 .env:必须更换 JWT_SECRET、APP_ENCRYPTION_KEY、LIVEKIT_API_SECRET、 +# MINIO_SECRET_KEY 和数据库密码,并把 APP_PROD_GUARD 设为 true +docker compose --env-file .env up -d --build ``` -- 后端测试:`.\scripts\mvn.ps1 test` -- 前端测试:`cd frontend && npm test` -- API 验收:`.\scripts\acceptance.ps1`(建校、审核、开播、权限隔离) -- 浏览器端到端(真实推流+观看+录像+回放,需本机 Chrome):`node scripts\e2e-browser.mjs` +启动后: -角色入口(登录后自动跳转): +- 网站入口:`http://服务器IP:18088`(生产环境请用 Nginx/Caddy 配置 HTTPS 反向代理到 18088) +- 首次登录:用 `.env` 里的 `ADMIN_USERNAME` / `ADMIN_PASSWORD` 登录管理端,然后到「用户管理」修改密码、按需创建账号。系统不提供公开的固定默认密码。 +- 修改网站名称、Logo、公告:管理端 →「系统设置」→「网站设置」。 -- 管理端 `/admin`(超级管理员/学校管理员/巡课) -- 教师端 `/teacher`(选摄像头、麦克风,开播/停播) -- 家长端 `/parent`(绑定班级、看直播、看回放) -- 落地页 `/`,观看页 `/watch/:id` +### 端口说明 -## 生产构建 +| 端口 | 用途 | +| --- | --- | +| 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 -docker compose --env-file .env up --build +git pull +docker compose --env-file .env up -d --build ``` -网站入口 `http://localhost:18088`。初始管理员来自 `.env` 的 `ADMIN_USERNAME` / `ADMIN_PASSWORD`,示例口令只能用于本机;首次部署请更换全部密钥并把 `APP_PROD_GUARD` 设为 `true`。 +数据库结构由后端启动时自动迁移,升级前建议先备份。 -## 注意事项 +## 常见问题 -- 浏览器访问摄像头/麦克风必须用 `localhost`(或 HTTPS)这类安全上下文。 -- 跨公网观看 WebRTC 时,需要把 LiveKit 的节点 IP、`rtc` 端口段和 TURN 配到学校网络,不能只开放一个 HTTPS 端口。 -- 录像保存在 MinIO 私有桶,回放通过带权限校验的短期预签名链接访问,默认不提供下载。 +- **浏览器列不出摄像头/麦克风**:确认浏览器已允许权限,或设备被其他软件占用;希沃一体机上需确认摄像头/麦克风驱动已暴露给浏览器。 +- **直播卡顿/黑屏**:检查教师端与服务器之间、观看端与服务器之间的 50000-50100/UDP 端口是否放行;内网测试请用 `localhost` 访问。 +- **家长看不到回放**:确认管理员在绑定审核里授予了「回放」权限(直播与回放是分开授权的)。 +- **录像没有生成**:确认课程勾选了「允许录像」且学校开启了录像开关,可在管理端「课程录像」查看失败原因。 + +## 开发者 + +本地开发热更新预览与测试命令见 `docs/IMPLEMENTATION_STATUS.md`;系统架构见 `docs/ARCHITECTURE.md`;部署细节见 `docs/DEPLOYMENT.md`。