mirror of
https://github.com/handsomezhuzhu/QQuiz.git
synced 2026-02-20 20:10:14 +00:00
feat: 实现数据库驱动的API配置管理和项目结构重组
## 新功能 - 实现管理后台API配置管理（OpenAI/Anthropic/Qwen） - API配置保存到数据库，实时生效无需重启 - API密钥遮罩显示（前10位+后4位） - 完整endpoint URL自动显示 ## 后端改进 - 新增 config_service.py 用于加载数据库配置 - LLMService 支持动态配置注入，回退到环境变量 - 更新 exam.py 和 question.py 使用数据库配置 - 扩展 schemas.py 支持所有API配置字段 ## 前端改进 - 重写 AdminSettings.jsx 增强UI体验 - API密钥显示/隐藏切换 - 当前使用的提供商可视化标识 - 移除"需要重启"的误导性提示 ## 项目结构重组 - 移动所有脚本到 scripts/ 目录 - 移动所有文档到 docs/ 目录 - 清理 Python 缓存文件 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
234
docs/QUICK_START.md
Normal file
234
docs/QUICK_START.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# 🚀 QQuiz 快速开始指南（5 分钟上手）
|
||||
|
||||
## Windows 用户快速部署
|
||||
|
||||
### 第一步：准备工作（2 分钟）
|
||||
|
||||
1. **安装 Docker Desktop**
|
||||
- 下载：https://www.docker.com/products/docker-desktop/
|
||||
- 安装后重启电脑
|
||||
- 启动 Docker Desktop，等待启动完成
|
||||
|
||||
2. **配置 API Key**
|
||||
```powershell
|
||||
# 在项目目录打开 PowerShell
|
||||
cd E:\QQuiz
|
||||
|
||||
# 复制环境变量模板
|
||||
copy .env.example .env
|
||||
|
||||
# 编辑 .env 文件
|
||||
notepad .env
|
||||
```
|
||||
|
||||
**修改以下两项：**
|
||||
```env
|
||||
SECRET_KEY=change-this-to-a-very-long-random-string-at-least-32-characters
|
||||
OPENAI_API_KEY=sk-your-actual-openai-api-key-here
|
||||
```
|
||||
|
||||
### 第二步：启动服务（2 分钟）
|
||||
|
||||
**方式一：使用启动脚本（推荐）**
|
||||
```powershell
|
||||
# 双击运行
|
||||
start_windows.bat
|
||||
```
|
||||
|
||||
**方式二：手动启动**
|
||||
```powershell
|
||||
cd E:\QQuiz
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
等待服务启动完成（首次启动需要下载镜像，约 1-2 分钟）
|
||||
|
||||
### 第三步：开始使用（1 分钟）
|
||||
|
||||
1. **访问应用**
|
||||
- 打开浏览器访问：http://localhost:3000
|
||||
|
||||
2. **登录**
|
||||
- 用户名：`admin`
|
||||
- 密码：`admin123`
|
||||
|
||||
3. **创建第一个题库**
|
||||
- 点击「题库管理」
|
||||
- 点击「创建题库」
|
||||
- 输入名称：`Python 基础测试`
|
||||
- 上传文件：`test_data/sample_questions.txt`
|
||||
- 等待解析完成（约 10-30 秒）
|
||||
|
||||
4. **开始刷题**
|
||||
- 点击「开始刷题」
|
||||
- 答题并查看解析
|
||||
|
||||
---
|
||||
|
||||
## 🎯 测试功能清单
|
||||
|
||||
完成以下测试，确保所有功能正常：
|
||||
|
||||
### ✅ 基础功能
|
||||
- [ ] 登录系统
|
||||
- [ ] 创建题库
|
||||
- [ ] 上传文档并等待解析完成
|
||||
- [ ] 开始刷题
|
||||
- [ ] 答对一题
|
||||
- [ ] 答错一题（应自动加入错题本）
|
||||
- [ ] 查看错题本
|
||||
|
||||
### ✅ 高级功能
|
||||
- [ ] 向已有题库追加新文档
|
||||
- [ ] 验证去重功能（上传重复题目）
|
||||
- [ ] 测试不同题型（单选、多选、判断、简答）
|
||||
- [ ] 测试断点续做（刷到一半退出，再次进入继续）
|
||||
- [ ] 手动添加/移除错题
|
||||
- [ ] 修改管理员密码
|
||||
|
||||
### ✅ 管理员功能（使用 admin 账户）
|
||||
- [ ] 访问系统设置
|
||||
- [ ] 修改上传限制
|
||||
- [ ] 关闭用户注册
|
||||
|
||||
---
|
||||
|
||||
## 📝 测试数据文件
|
||||
|
||||
项目提供了两个测试文件：
|
||||
|
||||
1. **`test_data/sample_questions.txt`** - 基础选择题和判断题
|
||||
- 10 道题
|
||||
- 包含单选、多选、判断题
|
||||
- 适合快速测试
|
||||
|
||||
2. **`test_data/sample_questions_advanced.txt`** - 简答题
|
||||
- 8 道题
|
||||
- 全部为简答题
|
||||
- 测试 AI 评分功能
|
||||
|
||||
**使用方法：**
|
||||
1. 创建题库时上传 `sample_questions.txt`
|
||||
2. 解析完成后，点击「添加题目文档」
|
||||
3. 再次上传 `sample_questions.txt`（测试去重）
|
||||
4. 观察日志，应该显示"去重 10 题，新增 0 题"
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 常用命令
|
||||
|
||||
### 查看日志
|
||||
```powershell
|
||||
# 方式一：使用脚本
|
||||
logs_windows.bat
|
||||
|
||||
# 方式二：命令行
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
### 重启服务
|
||||
```powershell
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
### 停止服务
|
||||
```powershell
|
||||
# 方式一：使用脚本
|
||||
stop_windows.bat
|
||||
|
||||
# 方式二：命令行
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### 完全重置（清除所有数据）
|
||||
```powershell
|
||||
docker-compose down -v
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ❓ 常见问题
|
||||
|
||||
### 问题 1: 端口被占用
|
||||
|
||||
**错误信息：** `Bind for 0.0.0.0:3000 failed: port is already allocated`
|
||||
|
||||
**解决方案：**
|
||||
```powershell
|
||||
# 查找占用端口的进程
|
||||
netstat -ano | findstr :3000
|
||||
|
||||
# 结束进程（替换 <PID> 为实际进程 ID）
|
||||
taskkill /F /PID <PID>
|
||||
|
||||
# 重新启动
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### 问题 2: Docker Desktop 未启动
|
||||
|
||||
**错误信息：** `error during connect: ... Is the docker daemon running?`
|
||||
|
||||
**解决方案：**
|
||||
1. 打开 Docker Desktop 应用
|
||||
2. 等待底部状态显示 "Running"
|
||||
3. 重新运行启动脚本
|
||||
|
||||
### 问题 3: API Key 未配置
|
||||
|
||||
**现象：** 文档解析一直处于 "processing" 状态
|
||||
|
||||
**解决方案：**
|
||||
1. 检查 `.env` 文件中的 `OPENAI_API_KEY` 是否正确
|
||||
2. 查看后端日志：`docker-compose logs backend`
|
||||
3. 重新启动：`docker-compose restart`
|
||||
|
||||
### 问题 4: 前端无法连接后端
|
||||
|
||||
**现象：** 登录失败，显示网络错误
|
||||
|
||||
**解决方案：**
|
||||
```powershell
|
||||
# 检查后端是否运行
|
||||
docker-compose ps
|
||||
|
||||
# 检查后端健康状态
|
||||
# 浏览器访问: http://localhost:8000/health
|
||||
|
||||
# 查看后端日志
|
||||
docker-compose logs backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 下一步
|
||||
|
||||
✅ **部署成功后，建议阅读：**
|
||||
|
||||
1. **完整功能说明**: `README.md`
|
||||
2. **详细部署文档**: `DEPLOYMENT.md`
|
||||
3. **Windows 专用指南**: `WINDOWS_DEPLOYMENT.md`
|
||||
4. **项目架构**: `PROJECT_STRUCTURE.md`
|
||||
|
||||
✅ **进阶使用：**
|
||||
|
||||
1. 修改管理员密码
|
||||
2. 创建普通用户账户
|
||||
3. 上传真实的题目文档
|
||||
4. 配置系统限制（上传大小、次数等）
|
||||
5. 尝试不同的 AI 提供商（Qwen、Claude）
|
||||
|
||||
---
|
||||
|
||||
## 🎉 恭喜！
|
||||
|
||||
如果你已经完成了上述测试，说明 QQuiz 已经在你的 Windows 系统上成功部署运行了！
|
||||
|
||||
现在你可以：
|
||||
- 📚 上传自己的题库文档
|
||||
- 🎯 开始高效刷题学习
|
||||
- 📊 通过错题本巩固薄弱知识点
|
||||
- ⚙️ 自定义系统配置
|
||||
|
||||
祝你学习愉快！如有问题，请查看详细文档或提交 Issue。
|
||||
Reference in New Issue
Block a user