Qbao
Qbao — 全能互动学习做题引擎
AI 智能出题 · 考试模拟 · 章节强弱复练 · 数据复盘 —— 面向个人学习与小组协作的一体化学习平台。 网页端在线使用，Windows 桌面端（Electron）双形态。
项目简介
Qbao 解决学习中最常见的问题：资料很多、题源很少、练完没有反馈。
- 将任意学习资料（PDF / 文本 / 图片）交给 AI，自动生成选择、判断、名词解释、简答题；
- 以「科目 → 章节 → 轮次」组织刷题，按章节强弱策略复练，配合答题历史复盘，让复习有节奏；
- 科目总览看板以统一口径呈现准确率、进度、连续学习与趋势——每个数字都可验算；
- 好友 / 群聊协作学习，题目与题库一键分享，聊天内直接答题。
网页端与 Windows 桌面端共用同一套前端产物（singlefile），数据经云端同步，多端一致。
核心特性
🧠 学习闭环
- 科目 / 章节体系、章节折叠定位、答题历史与章节强弱策略分析
- 练习轮次、限时考试、大考卷薄弱点组卷（键盘快捷键、两段式防误触确认）
- 答题历史按章节逐轮复盘（答对 / 答错 / 只看错题 / 搜索）；章节强弱策略与错题标签管理
- 科目总览看板：核心指标卡、掌握度环形图、章节明细、薄弱标签、趋势洞察
🤖 AI 能力
- 多 Provider：DeepSeek / OpenAI 兼容 / Gemini / ECNU
- 上传 PDF / 文本 / 图片自动出题（选择 / 判断 / 名词解释 / 简答），LaTeX / KaTeX 公式渲染
- 服务端任务队列后台生成：断点续做、失败自动标记、并发生成锁
- 流式输出 + 严格 JSON 校验；AI Key 用户自管、服务端不落库，成功才计费
🔄 数据与同步
- rev 乐观锁云端同步，409 自动合并重推；本地骨架 + IndexedDB 大字段分流
- 多账号、多标签页严格隔离（属主钉扎 + 跨标签守卫，E2E 验证零串账）
- 本地备份 / 云端恢复；题库 JSON / CSV 导入导出、批量移动 / 删除 / 打标
👥 协作与平台
- 好友 / 群聊：文字、图片、文件消息，Ctrl+V 粘贴图，消息撤回
- 题目与题库分享，聊天内直接答题
- 成就系统、积分经济（台账审计、防滥用、学期清零）
- 反馈工单闭环：悬浮入口 → 处理 → 用户确认
🎮 游戏空间
- 附属休闲门户（独立静态站，零后端负载）：2048、Flexbox Froggy、Grid Garden、俄罗斯方块
- 与主站共享登录态，成绩按账号隔离保存；等待 AI 出题时游戏入口自动高亮引导放松
- 开源原版托管（MIT），无广告无统计；游戏事件积分对接口已预留（见 docs/GAMES.md）
- 附网页版多人联机「狼人杀」（自托管房间服务，扫码/房号开桌，见 docs/GAMES.md 第四节）
💻 形态与分发
- 网页在线版 + Windows 桌面客户端（Electron 36，自动更新）
- 桌面端自托管更新源：stable / beta 双渠道、强制更新门槛、撤回熔断、历史版本回退
- 移动端响应式专项：竖屏交互规范、触控目标优化、存储配额治理
- 亮 / 暗双主题、字号调节；桌面端密钥 DPAPI 加密
快速开始
桌面端
从分发页下载最新 Qbao-Setup-*.exe 安装，首次启动按引导填写服务器地址即可使用（自动检查并更新）。
自托管部署
环境要求：Node.js ≥ 18、PostgreSQL ≥ 13、Caddy（线上静态托管与 TLS 终结；自托管可用任意反向代理）。
# 1) 后端
git clone git@github.com:Paraso42/Qbao.git
cd Qbao/server
npm ci
cp .env.example .env # 配置 PGPASSWORD / JWT_SECRET / AI Key
psql -U postgres -d qbao -f init.sql
node scripts/run_migration.js # 版本化迁移（schema_migrations 自动追踪）
npm start # 默认 3000 端口
# 2) 前端（singlefile 构建产物）
cd ../app && npm ci && npm run build
# 将 app/dist/ 发布到服务器静态目录（线上由 Caddy file_server 直出；桌面端内嵌加载同一产物，无需另行部署）
完整部署（Caddy 配置、HTTPS、防火墙、备份、升级）见 docs/DEPLOY.md。
本地开发
cd server && npm ci --include=dev && npm run dev # 后端 :3000（node --watch）
cd app && npm ci && npm run dev # 前端 Vite HMR
cd desktop && npm ci && npm run dev # Electron 窗口
质量与发布
- 测试：server 312 + app 317 + scripts 6 + desktop 5 = 640 例（2026-09-17 全量实跑复核），CI 全绿
- CI（6 个 job）：gitleaks 全历史密钥扫描 · 公开脱敏护栏（服务器 IP / 私钥名 / 部署根 / AppID 硬拦截）· 后端语法检查 + npm audit + Vitest + ESLint · 前端构建门禁 + 产物冒烟（singlefile + CSP）· 发布工具 node:test · 桌面端更新工具 node:test
- 发布纪律：本地提交 → 部署 → 用户验收「测试通过」→ push + tag（版本与三端断言）→ Release 构建 → 公网逐字节核验（见 docs/DEVELOPMENT_FLOW.md）
- 完整版本历史见 CHANGELOG.md 与 Releases
文档
| 文档 | 内容 |
|---|---|
| docs/ARCHITECTURE.md | 系统架构事实源：HTTPS 链路 / 双环境路由 / 安全边界 / 技术债登记 |
| docs/DEPLOY.md | 部署：Caddy / systemd / 数据库 / 备份 / 升级 |
| docs/PUBLISHING.md | 桌面端发布：双渠道、强制更新、撤回、回滚 |
| docs/DEVELOPMENT.md | 开发工作流、隐私分离规则、诊断脚本 |
| docs/DEVELOPMENT_FLOW.md | 发布流程唯一事实源 + DoD 检核表 |
| docs/MOBILE_UX.md | 移动端交互规范与真机验收清单 |
| docs/ENVIRONMENTS.md | 环境与网络地图：L0/L1/L2 隔离、内测入口与 FAQ |
| docs/REVIEW-2026-09.md | 项目全貌与专业点评（2026-09） |
| docs/LICENSING.md | 许可与边界说明：自研代码 / 第三方 MIT 组件 / 弹猪乐个人授权 |
| CONTRIBUTING.md / SECURITY.md | 贡献指南（含贡献许可条款）/ 安全政策 |
目录结构
Qbao/
├── app/ # 前端 SPA：Vue 3 + Vite + Pinia（源码 src/，singlefile 产物 dist/）
├── desktop/ # Electron 桌面壳（main / preload / updater，Windows NSIS 打包）
├── server/ # Node.js 后端：Express + PostgreSQL
│ ├── src/ # 路由、鉴权中间件、AI Provider 适配器、服务层
│ ├── sql/ # 版本化数据库迁移（NNN_*.sql，schema_migrations 追踪）
│ ├── scripts/ # 迁移执行 / 管理员引导 / 诊断脚本
│ ├── deploy/ # systemd 单元 + 上传目录初始化脚本
│ └── init.sql # 建库脚本
├── docs/ # 架构 / 部署 / 发布 / 开发文档
├── mobile/ # Capacitor 手机壳工程（Android / iOS，加载线上站点）
├── party/ # 联机游戏后端源码（werewolf 狼人杀，systemd qbao-werewolf）
├── scripts/ # 发布与部署工具（stage 双环境部署 / publish-installer manifest 入库）
├── tools/ # 一次性维护脚本（默认不上传）
└── local/ # 【本地专用】密钥 / 日志 / 备份快照，永不上传（.gitignore）
技术架构
Vue 3 + Vite + Pinia 前端（singlefile 产物，网页 / Electron 双形态共用，手机壳 App 同源加载）+ Node.js / Express 后端（17 个路由模块）+ PostgreSQL（业务状态 JSONB + rev 乐观锁同步；会话 / 聊天 / 工单 / 积分 / 游戏等独立关系表）。
关键设计：
- 双形态同源：同一份构建产物既是网页也是桌面端界面，API 地址运行时注入，桌面端免部署；
- 同步引擎：rev 乐观锁、409 实体级并集合并重推、空推跳过、账号与标签页隔离守卫；
- AI 代理层：Provider 工厂统一接入，任务队列（SKIP LOCKED）+ 生成锁 + 成功才计费；
- 自托管分发：manifest-first 双渠道下载 / 更新平台，服务器不依赖 GitHub 可达性。
公网部署架构（HTTPS 链路 · 简述）
在线服务由单台香港服务器直接提供（域名为占位符；真实域名/IP/路径只保存在本机 gitignored 文档，占位符纪律见 docs/DEVELOPMENT.md）：
用户（浏览器 / 手机壳 App / 桌面端）
│ https://{DOMAIN}（DNS → Cloudflare 代理） https://{BETA_HOST}（内测 · DNS 仅解析直连）
▼ ▼
单台服务器 {HK_IP} · Caddy（TLS 终结 · Let's Encrypt 自动证书 · gzip）
├─ 静态本地直出（file_server + SPA 兜底）：生产 {HOST_ROOT}/qbao/app（7 天缓存）
│ 内测 {HOST_ROOT}/qbao-beta/app（不缓存）
├─ /api /uploads /avatars /dl → 生产 Node :3000 → PostgreSQL 库 qbao
│ 内测 Node :3100 → 库 qbao_beta
└─ /games/werewolf/{api,werewolf-ws} → Node :3011（房间内存态，两环境共享）
- 为什么有两层在线环境：所有测试/内测先在 L1（独立库 / 端口 / 静态目录、可随时清库），验收通过后才部署 L2 生产；生产库禁止测试写入。生产与内测同机不同目录/进程/数据库，由 Caddy 的两个 site 块分流。
- 为什么单机直出：2026-09-10 起全量迁移至香港单机（此前为「CDN → 边缘网关 → 大陆源站」三层，源站已退役清理）。单机同时承担 TLS 终结、静态托管与 API 反向代理，链路短、无跨域回源，也不再需要为规避大陆机房备案拦截而设计的「回源 Host 改写 + 路由头分流」机制。
- 为什么用 Cloudflare：DNS 托管与边缘 TLS / 缓存加速；主域名走代理，内测域名仅解析直连。
- 完整机制（证书模型 / 缓存纪律 / 隔离矩阵 / 防互害权限 / 变更检查单 / 技术债）见 docs/ARCHITECTURE.md；环境通俗版见 docs/ENVIRONMENTS.md。
隐私与安全
- 公开仓库不含任何真实服务器地址与密钥（占位符纪律）；2026-07 已重写历史清除敏感信息
- 2026-09-12 再次重写历史（移除提交中的 AI 工具署名尾注）：旧克隆须删除后重新克隆，不可
git pull；文件内容与重写前逐字节一致，仅提交 SHA 变化 - 密码 bcrypt 哈希、JWT（强密钥启动校验）、登录与全局限流
- 上传通道扩展名白名单 + 魔数嗅探 + 附件响应头；CSP 收紧；API 与数据库只在回环可达（主机防火墙 ufw 仅放行 22/80/443，3000/3100/3011 显式拒绝，云安全组同口径）
- AI API Key 用户自管、服务端不落库；桌面端凭据以 DPAPI（safeStorage）加密
平台支持与致谢
本项目的 AI 能力（资料→题目生成、服务端出题任务队列、AI 二次自检、多模态视觉设计评审）默认且深度适配华东师范大学人工智能公共服务平台（ChatECNU，https://chat.ecnu.edu.cn/open/api/v1，ecnu-plus / ecnu-max / ecnu-turbo）；项目自身的开发过程——代码编写与重构、测试用例补全、线上故障定位、文档与发布工具打磨——同样依托该平台的大模型完成。谨此致谢：
本研究工作得到华东师范大学人工智能公共服务平台（ChatECNU）支持。
This work was supported by ChatECNU, the AI Service Platform of East China Normal University.
上述声明为本项目对外成果（论文、软件著作权、数据集、开源 Release、对外报告）的统一署名口径，逐字照抄学校《致谢声明模板》；在线服务（网页）与客户端（桌面端 / 手机端）内部的致谢展示将随后续版本加入。
许可证
本项目采用 PolyForm Noncommercial License 1.0.0（SPDX：PolyForm-Noncommercial-1.0.0）——源码公开，但禁止商业使用。
✅ 允许（免费、无需申请）
- 个人学习、研究、实验、私人娱乐与业余项目
- 慈善机构、教育机构、公共研究机构、公共安全与卫生机构、环保组织、政府机构使用（不论资金来源）
❌ 禁止（须事先取得书面授权）
- 任何商业目的：付费产品/服务、SaaS 转售、企业内部经营性使用、以本项目为基础的收费培训或外包交付
- 再许可（sublicense）或转让许可；去除版权与许可声明后分发
📩 商业授权：如需商业使用，请通过 GitHub Issues 联系作者洽谈授权。
第三方组件例外：仓库内游戏空间（
app/public/games/）的移植作品与party/werewolf/保持其上游原始许可证（多为 MIT），不受本项目非商业条款约束；app/public/games/marble/为作者个人授权引入。各组件许可与适用范围详见 docs/LICENSING.md。