From cab8b3b48332ab4d021d1a4b8ad142f85f150e5f Mon Sep 17 00:00:00 2001 From: handsomezhuzhu <2658601135@qq.com> Date: Fri, 17 Apr 2026 20:02:28 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README.md=EF=BC=8C?= =?UTF-8?q?=E5=AE=8C=E5=96=84=E5=8A=9F=E8=83=BD=E6=8F=8F=E8=BF=B0=E5=92=8C?= =?UTF-8?q?=E5=BF=AB=E9=80=9F=E5=BC=80=E5=A7=8B=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 210 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 125 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 8deef42..13d1493 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,141 @@ # QQuiz -QQuiz 是一个面向题库管理与刷题训练的全栈应用，支持文档导入、异步解析、题目去重、断点续做、错题本与管理员配置。 - -## 界面预览 +QQuiz 是一个用于题库导入、刷题训练和错题管理的全栈应用，支持文档解析、题目去重、断点续做、管理员配置和多模型接入。 ![QQuiz 界面截图](docs/cover.png) -## 核心能力 +## 功能 -- 多文件导入与题目去重 -- 异步解析进度回传 -- 单选、多选、判断、简答题统一管理 -- 刷题进度保存与继续作答 -- 错题本与错题练习 -- 管理员用户管理与系统配置 -- 支持 Gemini / OpenAI / Anthropic / Qwen - -## 当前架构 - -- `backend/`：FastAPI + SQLAlchemy + Alembic -- `web/`：当前主前端，Next.js App Router + TypeScript + Tailwind CSS -- `frontend/`：保留中的 legacy Vite 前端，用于单容器兼容路径 - -说明： - -- 分离部署优先使用 `web/` -- 单容器镜像当前仍复用 `frontend/` 构建静态资源 +- 文档导入：支持 TXT / PDF / DOC / DOCX / XLS / XLSX +- 异步解析：后台解析文档并回传进度 +- 题目去重：同题库内自动去重 +- 刷题与续做：记录当前进度，支持继续作答 +- 错题本：自动收集错误题目 +- 管理后台：用户管理、系统配置、模型配置 +- AI 提供商：Gemini / OpenAI / Anthropic / Qwen ## 快速开始 -### 1. 分离部署，推荐 +### 方式一：直接运行 GitHub Actions 构建好的镜像 -前端运行在 `3000`，后端运行在 `8000`。 +适合只想快速启动，不想先克隆仓库。 + +#### 1. 下载环境变量模板 + +Linux / macOS: ```bash -cp .env.example .env - -docker compose up -d --build +curl -L https://raw.githubusercontent.com/handsomezhuzhu/QQuiz/main/.env.example -o .env ``` -访问地址： +Windows PowerShell: + +```powershell +Invoke-WebRequest ` + -Uri "https://raw.githubusercontent.com/handsomezhuzhu/QQuiz/main/.env.example" ` + -OutFile ".env" +``` + +#### 2. 编辑 `.env` + +至少填写以下字段： + +```env +SECRET_KEY=replace-with-a-random-32-char-secret +ADMIN_USERNAME=admin +ADMIN_PASSWORD=replace-with-a-strong-password + +AI_PROVIDER=gemini +GEMINI_API_KEY=your-real-gemini-api-key +``` + +如果你不用 Gemini，也可以改成： + +- `AI_PROVIDER=openai` 并填写 `OPENAI_API_KEY` +- `AI_PROVIDER=anthropic` 并填写 `ANTHROPIC_API_KEY` +- `AI_PROVIDER=qwen` 并填写 `QWEN_API_KEY` + +#### 3. 拉取镜像 + +```bash +docker pull ghcr.io/handsomezhuzhu/qquiz-backend:latest +docker pull ghcr.io/handsomezhuzhu/qquiz-frontend:latest +``` + +#### 4. 创建网络和数据卷 + +```bash +docker network create qquiz_net +docker volume create qquiz_sqlite_data +docker volume create qquiz_upload_files +``` + +#### 5. 启动后端 + +```bash +docker run -d \ + --name qquiz_backend \ + --network qquiz_net \ + --env-file .env \ + -e DATABASE_URL=sqlite+aiosqlite:////app/data/qquiz.db \ + -e UPLOAD_DIR=/app/uploads \ + -v qquiz_sqlite_data:/app/data \ + -v qquiz_upload_files:/app/uploads \ + -p 8000:8000 \ + ghcr.io/handsomezhuzhu/qquiz-backend:latest +``` + +#### 6. 启动前端 + +```bash +docker run -d \ + --name qquiz_frontend \ + --network qquiz_net \ + -e API_BASE_URL=http://qquiz_backend:8000 \ + -p 3000:3000 \ + ghcr.io/handsomezhuzhu/qquiz-frontend:latest +``` + +访问： - 前端：`http://localhost:3000` - 后端：`http://localhost:8000` -- 后端健康检查：`http://localhost:8000/health` -### 2. 分离部署 + MySQL +停止： + +```bash +docker rm -f qquiz_frontend qquiz_backend +``` + +### 方式二：从源码用 Docker Compose 启动 + +#### 前后端分离，推荐 ```bash cp .env.example .env +docker compose up -d --build +``` +访问： + +- 前端：`http://localhost:3000` +- 后端：`http://localhost:8000` + +#### 使用 MySQL + +```bash +cp .env.example .env docker compose -f docker-compose.yml -f docker-compose.mysql.yml up -d --build ``` -### 3. 单容器部署 - -单容器模式会把前端静态资源集成到后端服务中，统一通过 `8000` 提供。 +#### 单容器模式 ```bash cp .env.example .env - docker compose -f docker-compose-single.yml up -d --build ``` -访问地址： +访问： - 应用：`http://localhost:8000` - API 文档：`http://localhost:8000/docs` @@ -79,7 +151,9 @@ alembic upgrade head uvicorn main:app --reload --host 0.0.0.0 --port 8000 ``` -### 新前端 +### 前端 + +当前主前端在 `web/`： ```bash cd web @@ -87,21 +161,10 @@ npm install npm run dev ``` -### 旧前端 +说明： -仅在兼容或迁移场景下需要： - -```bash -cd frontend -npm install -npm run dev -``` - -## 运行要求 - -- Python 3.11+ -- Node.js 18+ -- Docker / Docker Compose +- `web/` 是当前主前端，基于 Next.js +- `frontend/` 是保留中的旧 Vite 前端，主要用于单容器兼容路径 ## 关键环境变量 @@ -109,34 +172,28 @@ npm run dev | --- | --- | | `DATABASE_URL` | 数据库连接字符串 | | `SECRET_KEY` | JWT 密钥，至少 32 位 | +| `ADMIN_USERNAME` | 默认管理员用户名 | | `ADMIN_PASSWORD` | 默认管理员密码，至少 12 位 | | `AI_PROVIDER` | `gemini` / `openai` / `anthropic` / `qwen` | | `GEMINI_API_KEY` | Gemini API Key | | `OPENAI_API_KEY` | OpenAI API Key | | `OPENAI_BASE_URL` | OpenAI 或兼容网关地址 | +| `ANTHROPIC_API_KEY` | Anthropic API Key | +| `QWEN_API_KEY` | Qwen API Key | | `ALLOW_REGISTRATION` | 是否允许注册 | | `MAX_UPLOAD_SIZE_MB` | 单次上传大小限制 | | `MAX_DAILY_UPLOADS` | 每日上传次数限制 | -更多示例见 [`.env.example`](.env.example)。 +完整模板见 [`.env.example`](.env.example)。 -## 目录结构 +## 项目结构 ```text QQuiz/ ├─ backend/ FastAPI 后端 -│ ├─ alembic/ 数据库迁移 -│ ├─ routers/ API 路由 -│ ├─ services/ 业务服务 -│ ├─ models.py ORM 模型 -│ ├─ schemas.py Pydantic Schema -│ └─ main.py 应用入口 ├─ web/ Next.js 前端 -│ ├─ src/app/ App Router 页面与 API Route -│ ├─ src/components/ UI 与业务组件 -│ └─ src/lib/ 前端 API、鉴权、工具 ├─ frontend/ Legacy Vite 前端 -├─ docs/ 部署、审计与截图 +├─ docs/ 文档与截图 ├─ test_data/ 示例题库文件 ├─ docker-compose.yml 前后端分离部署 ├─ docker-compose.mysql.yml MySQL overlay @@ -146,39 +203,22 @@ QQuiz/ ## 技术栈 -### 后端 +- 后端：FastAPI、SQLAlchemy、Alembic、SQLite / MySQL、httpx +- 前端：Next.js 14、React 18、TypeScript、Tailwind CSS、TanStack Query -- FastAPI -- SQLAlchemy 2.x -- Alembic -- SQLite / MySQL -- httpx -- OpenAI / Anthropic SDK - -### 前端 - -- Next.js 14 App Router -- React 18 -- TypeScript -- Tailwind CSS -- TanStack Query -- Radix UI / shadcn 风格组件 - -## 构建检查 - -常用检查命令： +## 提交前建议检查 ```bash cd web && npm run build docker compose build backend frontend ``` -仓库当前没有完整自动化测试套件，提交前至少建议手动验证： +建议至少手动验证： - 登录 / 退出 - 创建题库 / 上传文档 / 查看解析进度 -- 刷题与错题加入 -- 管理员用户管理与系统设置 +- 刷题 / 续做 / 错题加入 +- 管理员配置 - 大数据量列表分页 ## 开源协议