mirror of
https://github.com/handsomezhuzhu/QQuiz.git
synced 2026-04-18 22:42:53 +00:00
更新 README.md，完善功能描述和快速开始指南
This commit is contained in:
210
README.md
210
README.md
@@ -1,69 +1,141 @@
|
||||
# QQuiz
|
||||
|
||||
QQuiz 是一个面向题库管理与刷题训练的全栈应用，支持文档导入、异步解析、题目去重、断点续做、错题本与管理员配置。
|
||||
|
||||
## 界面预览
|
||||
QQuiz 是一个用于题库导入、刷题训练和错题管理的全栈应用，支持文档解析、题目去重、断点续做、管理员配置和多模型接入。
|
||||
|
||||
|
||||
|
||||
## 核心能力
|
||||
## 功能
|
||||
|
||||
- 多文件导入与题目去重
|
||||
- 异步解析进度回传
|
||||
- 单选、多选、判断、简答题统一管理
|
||||
- 刷题进度保存与继续作答
|
||||
- 错题本与错题练习
|
||||
- 管理员用户管理与系统配置
|
||||
- 支持 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
|
||||
```
|
||||
|
||||
仓库当前没有完整自动化测试套件，提交前至少建议手动验证：
|
||||
建议至少手动验证：
|
||||
|
||||
- 登录 / 退出
|
||||
- 创建题库 / 上传文档 / 查看解析进度
|
||||
- 刷题与错题加入
|
||||
- 管理员用户管理与系统设置
|
||||
- 刷题 / 续做 / 错题加入
|
||||
- 管理员配置
|
||||
- 大数据量列表分页
|
||||
|
||||
## 开源协议
|
||||
|
||||
Reference in New Issue
Block a user