11.1 启动与访问类
| 现象 |
可能原因 |
处理 |
| 双击 exe 无反应 / 只打开页面 |
端口上已有实例在运行（单实例设计） |
直接使用已打开的页面；如需重启，先运行 一键关闭服务.bat |
| 提示端口被占用 |
上一次进程未退出、其它软件占用 8000 |
运行 一键关闭服务.bat；或改 config.ini [app] port |
| 学生机打不开网页 |
不同网段 / 防火墙未放行 / 路由器开启 AP 或访客隔离 |
检查网段与防火墙；关闭 AP 隔离；确认使用教师机 IP 而非 127.0.0.1 |
| 管理页提示"需要教师/管理员权限" |
用学生账号登录 |
用教师或管理员账号登录 /login |
| 页面样式错乱/按钮无反应 |
浏览器版本过旧或缓存 |
升级浏览器（Chromium ≥109）；Ctrl+F5 强制刷新 |
11.2 登录与账号类
| 现象 |
处理 |
| 学号登录失败但邮箱能登录 |
学号登录必须选对"所在学校" |
| 忘记密码 |
教师在账号管理为其「重置密码」 |
| 一直提示账号不可用 |
账号可能被锁定（连续失败）或已停用；教师可「解除锁定」或在账号管理启用 |
| 同班有重名学生 |
用户名（学号）唯一即可，姓名可重复 |
| 导入时大量冲突行 |
用户名/邮箱与库中已有账号重复；可勾选"覆盖更新"（不会改原密码） |
11.3 答题与判分类
| 现象 |
处理 |
| 学生说没跟上、前面题没答 |
开启「自由答题」补答（默认不计分，可按需计分） |
| 学生端一直显示"等待主持人开始答题" |
主持台尚未点「开始」或本轮已结算 |
| 答题分布没有数据 |
学生尚未提交；或本轮处于补答模式且未开启补答计分 |
| Excel 操作题没分 |
学生未点「提交」；或题目未上传考点 JSON；或浏览器版本过低 |
| 编程题判分不动 |
首次加载 Pyodide 需 5–15 秒；确认浏览器为 Chromium 内核且版本达标 |
| 排行榜看板上无在线学生 |
学生端页面被关闭或长时间无操作（在线判定窗口 30 秒） |
| 某题答案要更正 |
主持台「编辑题目」即时改正；历史作答可点「重判」 |
11.4 数据与性能类
| 现象 |
处理 |
| 数据库偶尔报错 / 卡顿 |
避免上课时段做整库级操作；确认只有一个实例运行 |
| 拷贝数据库后数据不一致 |
必须 quiz.db + -wal + -shm 一起拷，或先「关闭服务」 |
| 磁盘占用持续增长 |
excelstore/ 下学生作答只增不删，定期人工清理；backups/ 按天数自动清理 |
| 想恢复到某次备份 |
关闭服务 → 用备份替换 quiz.db（删除残留 -wal/-shm）→ 重启 |
11.5 日志排查速查
Select-String -Path 运行日志.txt -Pattern '\[login\]' # 登录链路（含失败原因）
Select-String -Path 运行日志.txt -Pattern '\[draw\]' # 抽题全生命周期
Select-String -Path 运行日志.txt -Pattern 'ok=0' # 所有失败记录
Select-String -Path 运行日志.txt -Pattern 'room=DM3001' # 指定房间
