nxxy335
a3be81b261
严重漏洞：roster_import 使用 $_FILES 的原始扩展名拼 roster_YYYYMMDD_HHMMSS.<ext>
落在 Web 根目录内的 data/uploads/，既无扩展名白名单（可上传 .php），文件名又
可按秒枚举；而 bootstrap 只写了 data/.htaccess，nginx 不读 .htaccess，
生产环境（nginx + PHP-FPM）下可直接远程代码执行。
修复（api.php roster_import 四层防护）：
- 扩展名白名单：仅 xlsx / xlsm / csv / txt
- 随机文件名：bin2hex(random_bytes(16))，杜绝枚举
- 解析完成后 @unlink 立即删除，Web 目录下不留存任何上传文件
- 20MB 大小限制 + UPLOAD_ERR 检查
加固（bootstrap.php）：data 及 cache/uploads/snapshots 每个目录都写
.htaccess（Deny from all）+ index.html 占位；README 与文档补充 nginx
location ^~ /data/ { deny all; return 404; } 规则。
测试：新增 e2e tools/test-upload-guard.js（11 断言，覆盖 .php/.phtml 被拒、
无残留、合法 csv 导入成功且即删、无可枚举文件名），并入 tests/run-all.sh。
全套 90 项通过。
docs: 新增 VitePress 文档站（18 页）
- 使用指南 12 页：简介/部署/快速上手/系统设置/名单管理/统计口径/试卷设置/
快照趋势异常/导出打印/数据看板/随机抽取/常见问题
- 安全 2 页：安全总览（含本次漏洞复盘）与部署加固清单（P0-P2）
- 开发 4 页：架构与目录/接口一览/SQLite 存储/测试
- 配图迁移至 docs/public/images/；.gitignore 忽略文档构建产物
4.3 KiB
常见问题
连接与登录
Q：提示"无法连接卷王系统"
依次检查：
- 卷王地址与端口是否正确、是否带多余的路径或结尾
/； - 服务器防火墙 / 安全组是否放行；
- 接口前缀是否为
/api（企业版可能是/admin-api）； - 账号密码是否正确；
- 在平台所在服务器本机执行
curl http://127.0.0.1:19911/api/system验证卷王本身是否可达。
Q：自己写的客户端登录成功却返回 401 "Full authentication is required to access this resource"
卷王社区版 v1.13 的 JwtTokenFilter 只从 Cookie sk-token 读取令牌，不读 Authorization 头。
务必从登录响应的 Set-Cookie 中取出 sk-token，并在后续每个请求带上
Cookie: sk-token=<token>。本平台已处理此细节。
Q：登录一直失败并被锁住
连续 5 次失败会锁定 10 分钟。等待即可；如需立即解锁，删除 data/login_fail.json。
Q：卷王改了密码后平台一直提示未登录
到 设置 里重新填写密码并保存（连接信息变化会自动清除本地令牌并重新登录）。
匹配与数据
Q：读到了答卷但学号为空
说明答卷里的姓名与名单不一致：
- 到 姓名字段 下拉里手动指定正确的题目；
- 或到 设置 → 姓名题关键词 里补充关键词；
- 未匹配答卷 面板会列出这些人，可据此核对（常见原因是姓名前后有空格、用了别名）。
Q：成绩列全是 -
该问卷不是考试模式，或没有开启自动评分，卷王未返回 examScore。
Q：考试时长全是 -
答卷的 metaInfo.answerInfo 中没有开始 / 结束时间（例如后台手动录入的答卷）。
Q：同一个人交了多次，看板里的成绩取哪次？
由 设置 → 同一学号去重 决定代表成绩取「最新」还是「最高」。 但考试次数始终是全部提交次数，点击成员可查看每一次提交。
Q：我想让某个学生不计入某张试卷的缺考
用 试卷设置 → 免考名单，只对该试卷生效， 不要从名单里删除（否则其它试卷也会少人）。
Q：合格率是按 60 分算吗？
不是写死的 60 分，而是「成绩 ≥ 满分 × 合格率阈值」。阈值全局默认 60%， 可在 试卷设置 里为单张试卷覆盖。卡片标题会显示当前阈值。
Q：切换班级后数字变了，是不是重新请求了服务器？
没有。切班级是本地即时重算，不额外打卷王。
性能
Q：人多的时候页面卡 / 后台刷新失败
已内置以下优化：结果缓存（默认 15 秒）、虚拟滚动、搜索防抖、页面切到后台自动暂停刷新、 分页大小夹在 20–200。仍有问题时可适当调大「结果缓存（秒）」并调小刷新频率。
Q：后台刷新报错 "Allowed memory size exhausted"
拉取大量答卷时 PHP 内存不足。程序已把单页条数夹在 20–200，并在入口尝试把
memory_limit 提到 512M。若主机用 php_admin_value memory_limit 硬锁，
ini_set 会静默失效，需要改 php.ini 或 FPM 池配置。
存储与迁移
Q：数据存在哪？
启用 pdo_sqlite 时存在 data/ny.db（表 ny_settings / ny_roster / ny_project_config）；
未启用时回落到 data/config.json、data/roster.json、data/project_config.json。
两者始终双写，切换不会丢数据。
Q：可以把平台搬到另一台服务器吗？
可以。整个目录复制过去，并把 data/ 一起带上（里面有配置、名单、快照），确保 data/ 可写。
安全
Q：上传的名单文件会被别人访问到吗？
不会。上传文件落在 data/uploads/，扩展名白名单（.xlsx / .xlsm / .csv / .txt）、
随机文件名，且解析完成后立刻删除。另外请确保按
部署加固清单 在 Web 服务器上屏蔽 /data/ 目录。
Q：为什么配置文件能被直接下载？
说明 /data/ 没有被屏蔽。Apache 下仓库会自动生成 .htaccess；
nginx 不读 .htaccess，必须显式加：
location ^~ /data/ {
deny all;
return 404;
}
详见 部署加固清单。