实时课堂模块安全加固与 AI 教学材料生成——EduMind 暑期冲刺记录
一次针对 EduMind 实时课堂模块的集中攻关，横跨安全、性能、可靠性和 AI 生成能力四个维度，一天内完成 16 项修复与功能新增。
一、安全纵向加固：学生身份防冒用
问题
/api/live/join 是公开接口，学生自报学号就能拿到合法 JWT。WebSocket Handler 又直接信任消息体中的 studentId，导致学生 A 可以任意冒用学生 B 的身份答题、举手、提问。
方案：四层纵深防御
- Join 入口验证 — 在
LiveSessionService.joinSession中增加班级花名册校验：如果教师已导入学生名单，则不在名单内的学号拒绝加入 - WebSocket Handler 覆盖身份 —
InteractionHandler、ReactionHandler、QASessionHandler全部改为从 STOMP Session Attributes（CONNECT 阶段 JWT 验证后存储）读取学生身份，忽略 payload 中的studentId/studentName - REST 端点修复 —
markConfusion从 JWT 提取身份而非请求体 - WebSocket CORS 收紧 —
setAllowedOriginPatterns("*")改为读取app.cors.allowed-origins配置
二、可靠性与性能
scheduleAutoClose 线程池化
InteractionService 中每次限时互动都 new Thread() sleep，改为共享 ScheduledExecutorService，支持手动关闭时取消定时任务，@PreDestroy 优雅退出。
倒计时同步
学生端倒计时从 setInterval(remaining--) 纯前端自减改为 deadlineEpochMs - Date.now() 实时计算。InteractionPushDTO 新增绝对截止时间戳字段，消除网络延迟和页面刷新带来的偏移。
教师断线检测
WebSocketAuthInterceptor 新增教师连接追踪，断开时通过 /topic/session/{sid}/teacher-status 广播 {online: false}。学生端收到后显示 “⚠️ 老师暂时离开” 红色提示。修复了 streamChat 不传 sessionId 的已有 Bug。
学生断线 30s 宽限期
StudentPresenceService 新增宽限期机制：学生 WebSocket 断开后启动 30s 定时器，超时才标记离场。宽限期内重连自动取消定时器，消除切 Wi-Fi 时的在线列表闪烁。
N+1 查询 → 批量查询
getInteractionHistory 和 getStudentProfile 中每次循环调 responseMapper.findByInteractionId() → 改为 findBySessionId 一次批量拉取 + 内存分组。20 个互动的课堂从 21 次查询降到 2 次。同步修复了 LiveNotificationService.sendPersonalizedReview 中的同类问题。
Presence 内存泄漏
LiveSessionService.endSession 新增调用 presenceService.clearSession(sessionId)，结课时清理 onlineStudents map + 取消待执行的宽限期任务。
出勤持久化
新增 live_attendance_log 表（V8 迁移），studentJoined 写 JOIN 事件，studentLeft 写 LEAVE 事件。getClassId 使用 ConcurrentHashMap 缓存避免重复查 DB。
三、举手队列
新增 HandRaiseService + HandRaiseHandler，实现 FIFO 举手队列：
- 学生举手入队，再点取消
- 教师按序点名（队首出队）或指定点名
- 教师可移除任意排队学生
- 结课时自动清空队列
- 教师端左侧栏新增队列面板，学生端 ✋ 改为 toggle 蓝色按钮
四、PPT → AI 生成教学材料
核心实现
新增 TeachingMaterialGenerator 服务，调用 OpenClaw → LLM 分析 PPT 内容，同时生成预习作业和课堂试题。
- 预习作业 — prompt 模板
ppt-preview-generation.txt，输出 JSON +===GUIDE===分隔符 + Markdown 导读 - 课堂试题 — prompt 模板
ppt-quiz-generation.txt，输出混合题型 JSON 数组（CHOICE/OPEN/EXERCISE）
关键踩坑
- DeepSeek 超时 — 不是超时，是梯子 DNS 劫持导致
api.deepseek.com解析出内网 IP，OpenClaw 安全层直接拦截Blocked: resolves to private/internal/special-use IP address - 流式返回空 —
streamChat(message, sessionId, status)的请求体 bug：buildRequestBody(message, null, agent, true)—sessionId参数根本没传进去，导致 Agent 行为异常 - JSON 解析失败 — 预习作业的
guideText是长段 Markdown，换行引号导致 JSON 断裂。改为===GUIDE===分隔符方案，JSON 和 Markdown 分家 session_idNOT NULL — 草稿题没有课堂 session，V9 迁移删除外键 + NOT NULL 约束；V11 迁移补充class_id和source_doc_id- INSERT 缺列 —
source_doc_id加到了列定义但漏了 VALUES 子句 correct_key VARCHAR(10)太短 — 简答题答案超长，V10 迁移扩为 TEXT
前端
知识库页面选中 PPT 文件后：
- 文件详情面板显示”🤖 AI 生成教学材料”按钮
- 弹窗内选班级 → 生成 → 审核编辑 → 逐条发布/保存
- 下方展示该文档历史上生成的草稿列表，可点击查看详情或删除
- Axios 请求超时从默认 10s 扩展到 120s
数据库迁移汇总
V8 出勤日志 → V9 草稿允许空 session_id → V10 扩 correct_key 字段 → V11 加 class_id → V12 加 source_doc_id
五、修改文件清单（共计 28 个文件）
| 类别 | 文件 | 改动 |
|---|---|---|
| 安全 | LiveSessionService.java |
join 花名册验证 |
| 安全 | InteractionHandler.java |
从 Session 读身份 |
| 安全 | ReactionHandler.java |
同上 |
| 安全 | QASessionHandler.java |
同上，修复匿名 |
| 安全 | LiveSessionController.java |
confusion 从 JWT 读身份 |
| 安全 | WebSocketConfig.java |
CORS 收紧 |
| 安全 | WebSocketAuthInterceptor.java |
权限 + 教师追踪 + @Lazy |
| 安全 | JwtUtil.java |
新增 getSubjectFromToken |
| 安全 | ClassStudentMapper.java |
新增 existsByClassIdAndStudentId |
| 可靠性 | InteractionService.java |
scheduleAutoClose 线程池 + 倒计时 deadlineEpochMs |
| 可靠性 | StudentPresenceService.java |
30s 宽限期 + clearSession + 出勤日志 |
| 可靠性 | LiveSessionService.java |
endSession 清理 presence + 举手队列 |
| 可靠性 | InteractionResponseMapper.java |
新增 findBySessionId/sessionIds |
| 可靠性 | InteractionMapper.java |
新增 findBySessionIds + 草稿查询 + 插入补列 |
| 可靠性 | LiveNotificationService.java |
删除 N+1 查询 |
| 可靠性 | OpenClawServiceImpl.java |
修复 streamChat sessionId bug |
| 可靠性 | PreviewTaskMapper.java |
插入加 sourceDocId + findBySourceDocId |
| 可靠性 | DTO/InteractionPushDTO.java |
新增 deadlineEpochMs |
| 功能 | HandRaiseService.java |
新增 举手队列 |
| 功能 | HandRaiseHandler.java |
新增 举手 WS 端点 |
| 功能 | TeachingMaterialGenerator.java |
新增 AI 生成教学材料 |
| 功能 | GenerateMaterialsRequest.java |
新增 请求 DTO |
| 功能 | GenerateMaterialsResponse.java |
新增 响应 DTO + 嵌套类型 |
| 功能 | prompts/ppt-preview-generation.txt |
新增 预习生成模板 |
| 功能 | prompts/ppt-quiz-generation.txt |
新增 试题生成模板 |
| 功能 | DocumentController.java |
新增 generate/save/drafts API |
| 前端 | live-session.ts |
状态同步：举手队列 + 教师在线 |
| 前端 | StudentLive.vue |
举手 toggle + 倒计时修复 + 教师离线提示 |
| 前端 | LiveDashboard.vue |
举手队列面板 |
| 前端 | KnowledgeBase.vue |
AI 生成面板 + 草稿列表 + 详情弹窗 |
| 前端 | live.ts |
API 类型扩展 |
| DB | V8~V12 共 5 个迁移 | 见上文汇总 |
本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 LKL-ZREO！
相关推荐
2026-07-20
告别 OpenClaw：从 AI 网关依赖到自研 Agent 编排
背景EduMind 是一个 AI 驱动的智能教学平台，技术栈是 Spring Boot 4 + Vue 3，核心功能包括 RAG 知识库检索、作业批改、课堂实时互动和 QQ 机器人答疑。 从项目初期开始，所有 LLM 调用都经过 OpenClaw——一个开源的 AI Agent 框架（38 万 star，2026 年仍然极度活跃）。它负责：接收 QQ 消息、调用 MCP 工具、管理会话、路由 LLM 请求。 用了三个月后，我们决定把它从项目里彻底移除。这篇文章记录了为什么、怎么做、以及做完之后的架构变成了什么样。 为什么要移除 OpenClaw？1. 品类错配OpenClaw 是一个聊天机器人框架——它的核心价值是多频道消息（QQ/微信/Discord/Telegram）、Skill 插件系统、多 Agent 工作流。但 EduMind 只用了它最小的一块功能：作为一个 HTTP 代理把请求转发给 DeepSeek。 这就像租了一整层办公楼，只用了两间房，其中一间还漏水。 2. 问题积累三个月的使用中，OpenClaw 带来的问题逐渐超过了它提供的便...
2026-05-12
RAG 检索增强生成系统升级实录——从哈希伪向量到 ONNX 真实嵌入
背景为「作业批改系统」的 OneBot QQ Bot 接入 RAG（检索增强生成），让学生能通过 QQ 直接向知识库文档提问。插件侧配置已开启，但后端 RAG 接口返回异常。 时间线 时间 事件 10:09 发现 RAG 接口返回 {"enhancedMessage":"????","hasContext":false} 11:00 定位根因：SIMILARITY_THRESHOLD = 0.75 对哈希向量过高 11:13 实现 RRF 双路混合检索 11:27 修复 SQL 拼接空格/LIMIT 类型匹配 11:32 修复 LIMIT 参数类型 11:50 Gateway 重启导致 OneBot 断开 14:59 升级到 ONNX 真实嵌入模型 bge-small-zh-v1.5 15:27 模型下载完成，512 维向量就绪 15:31 pgvector 列维度不匹配报错，改表后修复 15:40 检索精度被 C 语言文档淹没，Top-K 从 3 提到 ...
2026-04-27
为NapCatQQ插件添加RAG功能
背景正在开发的作业批改系统需要支持 QQ 群聊答疑功能。学生通过 QQ 向机器人提问时，希望机器人能够基于上传的教学文档（知识库）进行回答，而不是仅依赖模型自身的知识。 架构设计最终架构1学生QQ提问 → NapCat(WS) → OpenClaw OneBot插件 → RAG增强 → 贾维斯Agent → OpenClaw → 回复学生 关键点： 在 OneBot 插件层拦截消息，调用后端 RAG 接口增强 prompt 增强后的消息再发给 Agent 处理 复用现有的向量检索和文档存储系统 实现过程1. 后端接口开发创建 OnebotRagController.java，提供 RAG 增强接口： 123456789101112131415161718192021222324@PostMapping("/rag")public ResponseEntity<RagResponse> rag(@RequestBody RagRequest request) { // 1. RAG 检索 List<String>...
2026-06-08
AI 教学平台深度优化实录 — RAG 检索从 0% 到 60% 的全链路排查与修复
概述今天对 AI 编程教学平台进行了一次系统性深度优化，覆盖了四个维度： RAG 可观测性：从零搭建检索质量评估体系 RAG 精准度：定位并修复两个数据链路 bug 工程规范化：Prompt 模板化、前端状态管理、配置治理 性能调优：Reranker 候选数控制、连接池调整 核心成果：RAG 检索 Hit@3 从 0% → 60%，忠实度从 2.4 → 4.2。 一、RAG 评估体系搭建问题在此之前，RAG 检索效果完全靠”感觉”——改完 Prompt 不知道有没有变好，换模型不知道命中率涨没涨。简历上写 RAG 却拿不出任何量化数据。 方案自建评估系统，不引入 Python 生态的 RAGAS（太重），全部放在 src/test 下零侵入： 123456789src/test/java/.../eval/├── RagEvaluator.java # 评估运行器（两轮）├── EvalReport.java # 报告 DTO├── EvalDataset.java # JSON 数据集加载├── MetricCalculat...
2026-06-05
AI 教学平台 — 从 RAG 到 Agentic RAG 的全链路实战与面试复盘
项目亮点本项目是一个基于 Spring Boot + Vue 3 的 AI 教学平台，核心亮点： 自建 RAG 全链路：本地 ONNX Embedding（bge-small）+ pgvector + 双路检索（向量 + 关键词）+ RRF 融合 + Reranker 精排 + Query Rewrite，不是调包 Demo Agentic RAG：通过 MCP Tool Server 注册 5 个工具，LLM 自主决策检索知识库、查成绩、看作业、查课表、获取时间 本地模型部署：DJL + ONNX Runtime + bge-small-zh-v1.5（Embedding）+ bge-reranker-base（Reranker），多源镜像自动下载 + 哈希降级 智能分块策略：文档类型检测 → 结构切割 → 语义边界切割 → 滑动窗口 → 上下文引用 DAG 工作流引擎：GRADE → ERROR_ANALYSIS → SUGGESTION，条件路由 + 失败回退 + 类型安全状态 分布式基础设施：Bucket4j 令牌桶限流 + 布隆过滤器防穿透 + Cache-Aside...
2026-07-16
课堂直播系统 × OneBot QQ 整合 + 备课学情仪表盘
概述本次迭代围绕课中互动 → 课后反馈 → 课前备课三个环节，打通了课堂直播系统与 OneBot QQ 机器人的消息推送，并新建了备课学情仪表盘与预习任务系统，形成”备课 → 上课 → 复盘”的完整闭环。 一、OneBot QQ × 课堂直播 整合已实现功能 功能 触发时机 推送方式 🔔 未答题提醒 互动关闭时（手动/倒计时） QQ 私聊未作答学生 + 群内汇总 📊 课堂总结 教师结束课堂 群消息（互动数/正确率/MVP/缺席名单）+ 私聊缺席学生 📢 开课通知 教师创建课堂 群消息（课堂码 + 加入方式） 📖 预习任务推送 教师发布预习任务 群消息（主题 + 知识点） 技术实现新建 LiveNotificationService，注入已有的 OneBotHttpService（调 NapCat HTTP API）和 StudentQqBindingMapper（学号 → QQ 号映射），在以下切面织入： 1234LiveSessionService.createSession() → notify...
评论
