zzh/QQuiz

mirror of https://github.com/handsomezhuzhu/QQuiz.git synced 2026-02-20 20:10:14 +00:00

Files

handsomezhuzhu c5ecbeaec2 🎉 Initial commit: QQuiz - 智能刷题与题库管理平台

## 功能特性

✅ **核心功能**
- 多文件上传与智能去重（基于 content_hash）
- 异步文档解析（支持 TXT/PDF/DOCX/XLSX）
- AI 智能题目提取与评分（OpenAI/Anthropic/Qwen）
- 断点续做与进度管理
- 自动错题本收集

✅ **技术栈**
- Backend: FastAPI + SQLAlchemy 2.0 + PostgreSQL
- Frontend: React 18 + Vite + Tailwind CSS
- Deployment: Docker Compose

✅ **项目结构**
- 53 个文件
- 完整的前后端分离架构
- Docker/源码双模部署支持

🚀 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-12-01 12:39:46 +08:00

6.9 KiB

Raw Blame History

QQuiz 部署指南

🚀 快速开始

方式一：Docker Compose（推荐）

这是最简单的部署方式，适合快速体验和生产环境。

# 1. 配置环境变量
cp .env.example .env

# 2. 编辑 .env 文件，填入必要配置
# 必填项：
# - SECRET_KEY: JWT 密钥（至少 32 字符）
# - OPENAI_API_KEY: OpenAI API 密钥（或其他 AI 提供商）

# 3. 启动所有服务
docker-compose up -d

# 4. 查看日志
docker-compose logs -f

# 5. 访问应用
# 前端：http://localhost:3000
# 后端：http://localhost:8000
# API 文档：http://localhost:8000/docs

方式二：本地源码运行

适合开发环境和自定义部署。

前置要求

Python 3.11+
Node.js 18+
PostgreSQL 15+

步骤

1. 安装并启动 PostgreSQL

# macOS
brew install postgresql@15
brew services start postgresql@15

# Ubuntu/Debian
sudo apt install postgresql-15
sudo systemctl start postgresql

# Windows
# 下载并安装 PostgreSQL 官方安装包

2. 创建数据库

psql -U postgres
CREATE DATABASE qquiz_db;
CREATE USER qquiz WITH PASSWORD 'qquiz_password';
GRANT ALL PRIVILEGES ON DATABASE qquiz_db TO qquiz;
\q

3. 配置环境变量

cp .env.example .env

编辑 .env 文件：

# 数据库（本地部署）
DATABASE_URL=postgresql+asyncpg://qquiz:qquiz_password@localhost:5432/qquiz_db

# JWT 密钥（必须修改！）
SECRET_KEY=your-very-long-secret-key-at-least-32-characters-long

# AI 提供商（选择一个）
AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-4o-mini

# 或者使用其他提供商
# AI_PROVIDER=anthropic
# ANTHROPIC_API_KEY=sk-ant-your-key
# ANTHROPIC_MODEL=claude-3-haiku-20240307

# AI_PROVIDER=qwen
# QWEN_API_KEY=sk-your-key
# QWEN_MODEL=qwen-plus

4. 启动后端

cd backend

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 运行数据库迁移
alembic upgrade head

# 启动服务
uvicorn main:app --reload

5. 启动前端

打开新终端：

cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm start

6. 访问应用

🔐 默认账户

首次启动后，系统会自动创建管理员账户：

用户名： admin
密码： admin123

⚠️ 重要： 首次登录后请立即修改密码！

⚙️ 配置说明

必填配置

配置项	说明	示例
`DATABASE_URL`	数据库连接字符串	`postgresql+asyncpg://user:pass@host:5432/db`
`SECRET_KEY`	JWT 密钥（至少 32 字符）	`your-super-secret-key-change-in-production`
`OPENAI_API_KEY`	OpenAI API 密钥	`sk-...`

可选配置

配置项	说明	默认值
`ALLOW_REGISTRATION`	是否允许用户注册	`true`
`MAX_UPLOAD_SIZE_MB`	最大上传文件大小（MB）	`10`
`MAX_DAILY_UPLOADS`	每日上传次数限制	`20`
`AI_PROVIDER`	AI 提供商	`openai`

AI 提供商配置

OpenAI

AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

Anthropic Claude

AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key
ANTHROPIC_MODEL=claude-3-haiku-20240307

通义千问 (Qwen)

AI_PROVIDER=qwen
QWEN_API_KEY=sk-your-key
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen-plus

📋 使用流程

1. 创建题库

登录后进入「题库管理」
点击「创建题库」
输入题库名称
上传题目文档（支持 TXT/PDF/DOCX/XLSX）
等待 AI 解析完成（状态会自动刷新）

2. 追加题目

进入题库详情页
点击「添加题目文档」
上传新文档
系统会自动解析并去重

3. 开始刷题

题库状态为「就绪」后，点击「开始刷题」或「继续刷题」
选择答案并提交
查看解析和正确答案
点击「下一题」继续

4. 错题本

答错的题目会自动加入错题本
可以手动添加或移除题目
在错题本中复习和巩固

🛠️ 常见问题

Q: 文档解析失败？

A: 检查以下几点：

AI API Key 是否正确配置
文档格式是否支持
文档内容是否包含题目
查看后端日志获取详细错误信息

Q: 如何修改上传限制？

A: 在「系统设置」中修改：

最大文件大小
每日上传次数

或直接修改 .env 文件：

MAX_UPLOAD_SIZE_MB=20
MAX_DAILY_UPLOADS=50

Q: 如何更换 AI 提供商？

A: 修改 .env 文件中的 AI_PROVIDER 和对应的 API Key：

AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key

Q: 如何备份数据？

A: 备份 PostgreSQL 数据库：

# Docker 环境
docker exec qquiz_postgres pg_dump -U qquiz qquiz_db > backup.sql

# 本地环境
pg_dump -U qquiz qquiz_db > backup.sql

Q: 如何关闭用户注册？

A: 在「系统设置」中关闭「允许用户注册」，或修改 .env：

ALLOW_REGISTRATION=false

📊 生产环境建议

安全配置

更改默认密码
- 首次登录后立即修改 admin 账户密码

生成强密钥

# 生成随机密钥
openssl rand -hex 32

配置 HTTPS
- 使用 Nginx 或 Caddy 作为反向代理
- 配置 SSL 证书
限制 CORS
```
CORS_ORIGINS=https://yourdomain.com
```

性能优化

数据库连接池
- 根据负载调整连接池大小
文件存储
- 考虑使用对象存储（如 S3）替代本地存储
缓存
- 使用 Redis 缓存频繁查询的数据

监控和日志

日志收集

# 查看 Docker 日志
docker-compose logs -f backend

# 保存日志到文件
docker-compose logs backend > backend.log

健康检查
- 访问 http://localhost:8000/health 检查服务状态

🐛 故障排查

后端无法启动

# 检查数据库连接
psql -U qquiz -d qquiz_db

# 检查端口占用
lsof -i :8000

# 查看详细日志
uvicorn main:app --reload --log-level debug

前端无法访问

# 检查端口占用
lsof -i :3000

# 清除缓存重新安装
rm -rf node_modules package-lock.json
npm install

Docker 容器无法启动

# 查看容器状态
docker-compose ps

# 查看特定容器日志
docker-compose logs backend

# 重新构建
docker-compose build --no-cache
docker-compose up -d

📞 获取帮助

GitHub Issues: 报告问题
文档: README.md
API 文档: http://localhost:8000/docs

📄 许可证

MIT License

6.9 KiB Raw Blame History Unescape Escape