zzh/QQuiz
1
0
Fork 0
mirror of https://github.com/handsomezhuzhu/QQuiz.git synced 2026-02-20 12:00:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: 实现数据库驱动的API配置管理和项目结构重组

Browse Source 
## 新功能
- 实现管理后台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:
handsomezhuzhu
2025-12-01 19:24:12 +08:00
parent 0ea8e5aa1e
commit a01f3540c5
47 changed files with 1051 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

376
docs/DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,376 @@
# QQuiz 部署指南
## 🚀 快速开始
### 方式一：Docker Compose（推荐）
这是最简单的部署方式，适合快速体验和生产环境。
```bash
# 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**
```bash
# macOS
brew install postgresql@15
brew services start postgresql@15
# Ubuntu/Debian
sudo apt install postgresql-15
sudo systemctl start postgresql
# Windows
# 下载并安装 PostgreSQL 官方安装包
```
**2. 创建数据库**
```bash
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. 配置环境变量**
```bash
cp .env.example .env
```
编辑 `.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. 启动后端**
```bash
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. 启动前端**
打开新终端：
```bash
cd frontend
# 安装依赖
npm install
# 启动开发服务器
npm start
```
**6. 访问应用**
- 前端：http://localhost:3000
- 后端：http://localhost:8000
- API 文档：http://localhost:8000/docs
---
## 🔐 默认账户
首次启动后，系统会自动创建管理员账户：
- **用户名：** `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
```env
AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
```
#### Anthropic Claude
```env
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key
ANTHROPIC_MODEL=claude-3-haiku-20240307
```
#### 通义千问 (Qwen)
```env
AI_PROVIDER=qwen
QWEN_API_KEY=sk-your-key
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen-plus
```
---
## 📋 使用流程
### 1. 创建题库
1. 登录后进入「题库管理」
2. 点击「创建题库」
3. 输入题库名称
4. 上传题目文档（支持 TXT/PDF/DOCX/XLSX）
5. 等待 AI 解析完成（状态会自动刷新）
### 2. 追加题目
1. 进入题库详情页
2. 点击「添加题目文档」
3. 上传新文档
4. 系统会自动解析并去重
### 3. 开始刷题
1. 题库状态为「就绪」后，点击「开始刷题」或「继续刷题」
2. 选择答案并提交
3. 查看解析和正确答案
4. 点击「下一题」继续
### 4. 错题本
- 答错的题目会自动加入错题本
- 可以手动添加或移除题目
- 在错题本中复习和巩固
---
## 🛠️ 常见问题
### Q: 文档解析失败？
**A:** 检查以下几点：
1. AI API Key 是否正确配置
2. 文档格式是否支持
3. 文档内容是否包含题目
4. 查看后端日志获取详细错误信息
### Q: 如何修改上传限制？
**A:** 在「系统设置」中修改：
- 最大文件大小
- 每日上传次数
或直接修改 `.env` 文件：
```env
MAX_UPLOAD_SIZE_MB=20
MAX_DAILY_UPLOADS=50
```
### Q: 如何更换 AI 提供商？
**A:** 修改 `.env` 文件中的 `AI_PROVIDER` 和对应的 API Key：
```env
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key
```
### Q: 如何备份数据？
**A:** 备份 PostgreSQL 数据库：
```bash
# Docker 环境
docker exec qquiz_postgres pg_dump -U qquiz qquiz_db > backup.sql
# 本地环境
pg_dump -U qquiz qquiz_db > backup.sql
```
### Q: 如何关闭用户注册？
**A:** 在「系统设置」中关闭「允许用户注册」，或修改 `.env`：
```env
ALLOW_REGISTRATION=false
```
---
## 📊 生产环境建议
### 安全配置
1. **更改默认密码**
- 首次登录后立即修改 `admin` 账户密码
2. **生成强密钥**
```bash
# 生成随机密钥
openssl rand -hex 32
```
3. **配置 HTTPS**
- 使用 Nginx 或 Caddy 作为反向代理
- 配置 SSL 证书
4. **限制 CORS**
```env
CORS_ORIGINS=https://yourdomain.com
```
### 性能优化
1. **数据库连接池**
- 根据负载调整连接池大小
2. **文件存储**
- 考虑使用对象存储（如 S3）替代本地存储
3. **缓存**
- 使用 Redis 缓存频繁查询的数据
### 监控和日志
1. **日志收集**
```bash
# 查看 Docker 日志
docker-compose logs -f backend
# 保存日志到文件
docker-compose logs backend > backend.log
```
2. **健康检查**
- 访问 `http://localhost:8000/health` 检查服务状态
---
## 🐛 故障排查
### 后端无法启动
```bash
# 检查数据库连接
psql -U qquiz -d qquiz_db
# 检查端口占用
lsof -i :8000
# 查看详细日志
uvicorn main:app --reload --log-level debug
```
### 前端无法访问
```bash
# 检查端口占用
lsof -i :3000
# 清除缓存重新安装
rm -rf node_modules package-lock.json
npm install
```
### Docker 容器无法启动
```bash
# 查看容器状态
docker-compose ps
# 查看特定容器日志
docker-compose logs backend
# 重新构建
docker-compose build --no-cache
docker-compose up -d
```
---
## 📞 获取帮助
- GitHub Issues: [报告问题](https://github.com/your-repo/qquiz/issues)
- 文档: [README.md](./README.md)
- API 文档: http://localhost:8000/docs
---
## 📄 许可证
MIT License

199
docs/DOCKER_MIRROR_SETUP.md Normal file
View File

@@ -0,0 +1,199 @@
# Docker 镜像加速器配置指南
## 问题描述
错误信息：`failed to resolve reference "docker.io/library/postgres:15-alpine"`
**原因**：无法访问 Docker Hub，需要配置国内镜像加速器。
---
## 解决方案一：配置 Docker Desktop 镜像加速（推荐）
### 方法 1：使用阿里云镜像加速器
1. **打开 Docker Desktop**
2. **进入设置**
- 点击右上角齿轮图标 ⚙️
- 选择 "Docker Engine"
3. **添加镜像加速器配置**
在 JSON 配置中添加以下内容：
```json
{
"builder": {
"gc": {
"defaultKeepStorage": "20GB",
"enabled": true
}
},
"experimental": false,
"registry-mirrors": [
"https://docker.mirrors.ustc.edu.cn",
"https://hub-mirror.c.163.com",
"https://mirror.baidubce.com"
]
}
```
4. **应用并重启**
- 点击 "Apply & Restart"
- 等待 Docker Desktop 重启完成
5. **验证配置**
```powershell
docker info | findstr "Registry Mirrors"
```
应该看到配置的镜像地址。
---
## 解决方案二：手动拉取镜像（临时方案）
如果配置镜像加速器后仍然失败，可以手动拉取镜像：
```powershell
# 尝试使用不同的镜像源拉取
docker pull docker.mirrors.ustc.edu.cn/library/postgres:15-alpine
docker tag docker.mirrors.ustc.edu.cn/library/postgres:15-alpine postgres:15-alpine
docker pull docker.mirrors.ustc.edu.cn/library/node:18-alpine
docker tag docker.mirrors.ustc.edu.cn/library/node:18-alpine node:18-alpine
docker pull docker.mirrors.ustc.edu.cn/library/python:3.11-slim
docker tag docker.mirrors.ustc.edu.cn/library/python:3.11-slim python:3.11-slim
```
---
## 解决方案三：使用国内可用的基础镜像
修改 `docker-compose.yml` 使用国内镜像源：
```yaml
services:
postgres:
image: registry.cn-hangzhou.aliyuncs.com/library/postgres:15-alpine
# 或使用
# image: docker.mirrors.ustc.edu.cn/library/postgres:15-alpine
```
---
## 推荐配置（完整版）
### Docker Desktop 完整配置
```json
{
"builder": {
"gc": {
"defaultKeepStorage": "20GB",
"enabled": true
}
},
"experimental": false,
"features": {
"buildkit": true
},
"registry-mirrors": [
"https://docker.mirrors.ustc.edu.cn",
"https://hub-mirror.c.163.com",
"https://mirror.baidubce.com",
"https://dockerproxy.com"
],
"insecure-registries": [],
"debug": false
}
```
---
## 常用镜像加速器地址
| 提供商 | 镜像地址 | 说明 |
|--------|----------|------|
| 中科大 | https://docker.mirrors.ustc.edu.cn | 稳定，推荐 |
| 网易 | https://hub-mirror.c.163.com | 速度快 |
| 百度云 | https://mirror.baidubce.com | 国内访问快 |
| Docker Proxy | https://dockerproxy.com | 备用 |
---
## 验证是否成功
### 1. 检查配置
```powershell
docker info
```
查找 "Registry Mirrors" 部分，应该显示配置的镜像地址。
### 2. 测试拉取镜像
```powershell
docker pull hello-world
```
如果成功，说明镜像加速器配置正确。
### 3. 重新启动 QQuiz
```powershell
cd E:\QQuiz
docker-compose up -d
```
---
## 如果仍然失败
### 检查网络连接
```powershell
# 测试是否能访问镜像加速器
curl https://docker.mirrors.ustc.edu.cn
```
### 尝试其他镜像源
如果某个镜像源不可用，尝试注释掉它，只保留可用的：
```json
{
"registry-mirrors": [
"https://docker.mirrors.ustc.edu.cn"
]
}
```
### 检查防火墙/代理
- 暂时关闭防火墙测试
- 如果使用代理，在 Docker Desktop 设置中配置代理
---
## 完成后的下一步
配置成功后：
```powershell
# 1. 重新启动服务
cd E:\QQuiz
docker-compose down
docker-compose up -d
# 2. 查看启动日志
docker-compose logs -f
# 3. 访问应用
# http://localhost:3000
```
---
祝你成功！🎉

214
docs/GITHUB_PUSH_GUIDE.md Normal file
View File

@@ -0,0 +1,214 @@
# GitHub 推送指南
## 方式一：使用 Personal Access Token（推荐）
GitHub 已不再支持密码认证，需要使用 Personal Access Token (PAT)。
### 步骤 1：创建 GitHub Personal Access Token
1. **访问 GitHub 设置**
- 登录 GitHub: https://github.com
- 点击右上角头像 → Settings
- 左侧菜单选择 **Developer settings**
- 选择 **Personal access tokens** → **Tokens (classic)**
- 点击 **Generate new token** → **Generate new token (classic)**
2. **配置 Token**
- Note: `QQuiz Deploy`
- Expiration: 选择过期时间（建议 90 days 或 No expiration）
- 勾选权限：
- ✅ **repo** (完整仓库访问权限)
- 点击 **Generate token**
3. **保存 Token**
- ⚠️ **重要**：立即复制生成的 token，它只会显示一次！
- 格式类似：`ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
### 步骤 2：配置 Git 凭据
**方式 A：使用 Git Credential Manager（推荐）**
```powershell
# 配置凭据存储
git config --global credential.helper manager-core
# 首次推送时会弹出窗口，输入：
# Username: handsomezhuzhu
# Password: 粘贴你的 Personal Access Token
```
**方式 B：直接在 URL 中使用 Token**
```powershell
cd E:\QQuiz
# 移除旧的 remote
git remote remove origin
# 添加包含 token 的 remote
git remote add origin https://ghp_YOUR_TOKEN_HERE@github.com/handsomezhuzhu/QQuiz.git
# 推送
git push -u origin main
```
将 `ghp_YOUR_TOKEN_HERE` 替换为你的实际 token。
### 步骤 3：推送到 GitHub
```powershell
cd E:\QQuiz
# 推送代码
git push -u origin main
```
如果使用方式 A，会弹出认证窗口，输入：
- **Username**: `handsomezhuzhu`
- **Password**: 粘贴你的 Personal Access Token
---
## 方式二：使用 SSH Key（适合频繁推送）
### 步骤 1：生成 SSH Key
```powershell
# 生成新的 SSH Key
ssh-keygen -t ed25519 -C "your_email@example.com"
# 按提示操作：
# - 文件位置：直接回车（使用默认）
# - 密码：可以留空或设置密码
```
### 步骤 2：添加 SSH Key 到 GitHub
```powershell
# 查看公钥
cat ~/.ssh/id_ed25519.pub
# 或在 Windows 上
type %USERPROFILE%\.ssh\id_ed25519.pub
```
复制输出的公钥（以 `ssh-ed25519` 开头）
1. 访问 GitHub Settings → SSH and GPG keys
2. 点击 **New SSH key**
3. Title: `QQuiz Dev PC`
4. Key: 粘贴公钥
5. 点击 **Add SSH key**
### 步骤 3：修改 Remote 为 SSH
```powershell
cd E:\QQuiz
# 移除旧的 HTTPS remote
git remote remove origin
# 添加 SSH remote
git remote add origin git@github.com:handsomezhuzhu/QQuiz.git
# 推送
git push -u origin main
```
---
## 快速推送脚本
创建 `push_to_github.bat`：
```batch
@echo off
echo Pushing to GitHub...
cd /d "%~dp0"
git add .
git status
echo.
set /p commit_msg="Enter commit message: "
git commit -m "%commit_msg%"
git push origin main
echo.
echo Done!
pause
```
---
## 验证推送成功
推送成功后：
1. 访问：https://github.com/handsomezhuzhu/QQuiz
2. 应该能看到所有代码文件
3. 查看 Commits 历史
---
## 常见问题
### Q1: 推送失败 - Authentication failed
**原因**：密码认证已被 GitHub 禁用
**解决**：使用 Personal Access Token 或 SSH Key
### Q2: 推送被拒绝 - Updates were rejected
```
! [rejected] main -> main (fetch first)
```
**解决**：
```powershell
# 拉取远程更改
git pull origin main --allow-unrelated-histories
# 再次推送
git push -u origin main
```
### Q3: 推送很慢
**解决**：配置代理（如果使用 VPN）
```powershell
# 设置 HTTP 代理
git config --global http.proxy http://127.0.0.1:7890
# 取消代理
git config --global --unset http.proxy
```
---
## 后续推送
首次推送成功后，以后只需：
```powershell
cd E:\QQuiz
# 查看更改
git status
# 添加文件
git add .
# 提交
git commit -m "your commit message"
# 推送
git push
```
---
祝你推送成功！🚀

262
docs/MYSQL_SETUP.md Normal file
View File

@@ -0,0 +1,262 @@
# MySQL 安装与配置指南
QQuiz 使用 MySQL 8.0 作为数据库，你可以选择 Docker 部署或本地安装。
## 方式一：使用 Docker (推荐)
### 优点
- 无需手动安装 MySQL
- 自动配置和初始化
- 隔离环境，不影响系统
### 使用步骤
1. **安装 Docker Desktop**
- 下载地址：https://www.docker.com/products/docker-desktop/
- 安装后启动 Docker Desktop
2. **运行启动脚本**
```bash
scripts\fix_and_start.bat
```
选择 **[1] Use Docker**
3. **完成！**
- Docker 会自动下载 MySQL 镜像
- 自动创建数据库和用户
- 自动启动服务
---
## 方式二：本地安装 MySQL
### 下载 MySQL
1. 访问 MySQL 官网下载页面：
https://dev.mysql.com/downloads/installer/
2. 选择 **MySQL Installer for Windows**
3. 下载 `mysql-installer-community-8.0.x.x.msi`
### 安装步骤
1. **运行安装程序**
- 双击下载的 .msi 文件
2. **选择安装类型**
- 选择 "Developer Default" 或 "Server only"
- 点击 Next
3. **配置 MySQL Server**
- **Config Type**: Development Computer
- **Port**: 3306 (默认)
- **Authentication Method**: 选择 "Use Strong Password Encryption"
4. **设置 Root 密码**
- 输入并记住 root 用户的密码
- 建议密码：`root` (开发环境)
5. **Windows Service 配置**
- ✅ Configure MySQL Server as a Windows Service
- Service Name: MySQL80
- ✅ Start the MySQL Server at System Startup
6. **完成安装**
- 点击 Execute 开始安装
- 等待安装完成
- 点击 Finish
### 验证安装
打开命令提示符，运行：
```bash
mysql --version
```
应该显示：`mysql Ver 8.0.x for Win64 on x86_64`
### 配置 QQuiz 数据库
**方式 A：使用脚本自动创建 (推荐)**
运行：
```bash
scripts\fix_and_start.bat
```
选择 **[2] Use Local MySQL**
**方式 B：手动创建**
1. 打开 MySQL 命令行客户端：
```bash
mysql -u root -p
```
2. 输入 root 密码
3. 创建数据库和用户：
```sql
CREATE DATABASE qquiz_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'qquiz'@'localhost' IDENTIFIED BY 'qquiz_password';
GRANT ALL PRIVILEGES ON qquiz_db.* TO 'qquiz'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```
---
## 数据库配置说明
### .env 文件配置
确保 `.env` 文件中的数据库连接字符串正确：
**本地 MySQL:**
```env
DATABASE_URL=mysql+aiomysql://qquiz:qquiz_password@localhost:3306/qquiz_db
```
**Docker MySQL:**
```env
DATABASE_URL=mysql+aiomysql://qquiz:qquiz_password@mysql:3306/qquiz_db
```
### 连接参数说明
- `mysql+aiomysql://` - 使用 aiomysql 异步驱动
- `qquiz` - 数据库用户名
- `qquiz_password` - 数据库密码
- `localhost` 或 `mysql` - 数据库主机地址
- `3306` - MySQL 默认端口
- `qquiz_db` - 数据库名称
---
## 常见问题
### 1. 端口 3306 被占用
**错误信息：**
```
Error: Port 3306 is already in use
```
**解决方案：**
- 检查是否已经有 MySQL 运行：`netstat -ano | findstr :3306`
- 停止现有的 MySQL 服务
- 或修改 `.env` 中的端口号
### 2. 无法连接到 MySQL
**错误信息：**
```
Can't connect to MySQL server on 'localhost'
```
**解决方案：**
1. **检查 MySQL 服务是否运行**
- 按 Win+R，输入 `services.msc`
- 查找 "MySQL80" 服务
- 确认状态为 "正在运行"
2. **启动 MySQL 服务**
```bash
net start MySQL80
```
3. **检查防火墙设置**
- 确保防火墙允许 MySQL 端口 3306
### 3. 密码验证失败
**错误信息：**
```
Access denied for user 'qquiz'@'localhost'
```
**解决方案：**
重新创建用户并设置密码：
```sql
mysql -u root -p
DROP USER IF EXISTS 'qquiz'@'localhost';
CREATE USER 'qquiz'@'localhost' IDENTIFIED BY 'qquiz_password';
GRANT ALL PRIVILEGES ON qquiz_db.* TO 'qquiz'@'localhost';
FLUSH PRIVILEGES;
```
### 4. 字符集问题
**解决方案：**
确保数据库使用 UTF-8 字符集：
```sql
ALTER DATABASE qquiz_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
---
## 管理工具推荐
### 1. MySQL Workbench (官方)
- 下载：https://dev.mysql.com/downloads/workbench/
- 功能：可视化数据库管理、SQL 编辑器、备份还原
### 2. DBeaver (免费开源)
- 下载：https://dbeaver.io/download/
- 功能：多数据库支持、数据导入导出、ER 图
### 3. phpMyAdmin (Web 界面)
- 适合习惯 Web 界面的用户
---
## 数据库备份与恢复
### 备份数据库
```bash
mysqldump -u qquiz -p qquiz_db > backup.sql
```
### 恢复数据库
```bash
mysql -u qquiz -p qquiz_db < backup.sql
```
---
## 切换回 PostgreSQL
如果需要切换回 PostgreSQL：
1. 修改 `requirements.txt`：
```
asyncpg==0.29.0 # 替换 aiomysql
```
2. 修改 `.env`：
```
DATABASE_URL=postgresql+asyncpg://qquiz:qquiz_password@localhost:5432/qquiz_db
```
3. 修改 `docker-compose.yml`：
- 将 `mysql` 服务改回 `postgres`
4. 重新安装依赖：
```bash
pip install -r requirements.txt
```
---
## 技术支持
如遇到其他问题，请：
1. 检查 MySQL 错误日志
2. 确认防火墙和网络配置
3. 查看项目 issues: https://github.com/handsomezhuzhu/QQuiz/issues

399
docs/PROJECT_STRUCTURE.md Normal file
View File

@@ -0,0 +1,399 @@
# QQuiz 项目结构
## 📁 完整目录结构
```
QQuiz/
├── backend/ # FastAPI 后端
│ ├── alembic/ # 数据库迁移
│ │ ├── versions/ # 迁移脚本
│ │ ├── env.py # Alembic 环境配置
│ │ └── script.py.mako # 迁移脚本模板
│ ├── routers/ # API 路由
│ │ ├── __init__.py # 路由包初始化
│ │ ├── auth.py # 认证路由（登录/注册）
│ │ ├── admin.py # 管理员路由
│ │ ├── exam.py # 题库路由（创建/追加/查询）⭐
│ │ ├── question.py # 题目路由（刷题/答题）
│ │ └── mistake.py # 错题本路由
│ ├── services/ # 业务逻辑层
│ │ ├── __init__.py # 服务包初始化
│ │ ├── auth_service.py # 认证服务（JWT/权限）
│ │ ├── llm_service.py # AI 服务（解析/评分）⭐
│ │ └── document_parser.py # 文档解析服务
│ ├── models.py # SQLAlchemy 数据模型 ⭐
│ ├── schemas.py # Pydantic 请求/响应模型
│ ├── database.py # 数据库配置
│ ├── utils.py # 工具函数（Hash/密码）
│ ├── main.py # FastAPI 应用入口
│ ├── requirements.txt # Python 依赖
│ ├── alembic.ini # Alembic 配置
│ └── Dockerfile # 后端 Docker 镜像
│
├── frontend/ # React 前端
│ ├── src/
│ │ ├── api/
│ │ │ └── client.js # API 客户端（Axios）⭐
│ │ ├── components/
│ │ │ ├── Layout.jsx # 主布局（导航栏）
│ │ │ └── ProtectedRoute.jsx # 路由保护
│ │ ├── context/
│ │ │ └── AuthContext.jsx # 认证上下文
│ │ ├── pages/
│ │ │ ├── Login.jsx # 登录页
│ │ │ ├── Register.jsx # 注册页
│ │ │ ├── Dashboard.jsx # 仪表盘
│ │ │ ├── ExamList.jsx # 题库列表 ⭐
│ │ │ ├── ExamDetail.jsx # 题库详情（追加上传）⭐
│ │ │ ├── QuizPlayer.jsx # 刷题核心页面 ⭐
│ │ │ ├── MistakeList.jsx # 错题本
│ │ │ └── AdminSettings.jsx # 系统设置
│ │ ├── utils/
│ │ │ └── helpers.js # 工具函数
│ │ ├── App.jsx # 应用根组件
│ │ ├── index.jsx # 应用入口
│ │ └── index.css # 全局样式
│ ├── public/
│ │ └── index.html # HTML 模板
│ ├── package.json # Node 依赖
│ ├── vite.config.js # Vite 配置
│ ├── tailwind.config.js # Tailwind CSS 配置
│ ├── postcss.config.js # PostCSS 配置
│ └── Dockerfile # 前端 Docker 镜像
│
├── docker-compose.yml # Docker 编排配置 ⭐
├── .env.example # 环境变量模板
├── .gitignore # Git 忽略文件
├── README.md # 项目说明
├── DEPLOYMENT.md # 部署指南
├── PROJECT_STRUCTURE.md # 项目结构（本文件）
└── run_local.sh # 本地运行脚本
⭐ 表示核心文件
```
---
## 🔑 核心文件说明
### 后端核心
#### `models.py` - 数据模型
定义了 5 个核心数据表：
- **User**: 用户表（用户名、密码、管理员标识）
- **SystemConfig**: 系统配置（KV 存储）
- **Exam**: 题库表（标题、状态、进度、题目数）
- **Question**: 题目表（内容、类型、选项、答案、**content_hash**）
- **UserMistake**: 错题本（用户 ID、题目 ID）
**关键设计：**
- `content_hash`: MD5 哈希，用于题目去重
- `current_index`: 记录刷题进度
- `status`: Enum 管理题库状态（pending/processing/ready/failed）
#### `exam.py` - 题库路由
实现了最核心的业务逻辑：
- `POST /create`: 创建题库并上传第一份文档
- `POST /{exam_id}/append`: 追加文档到现有题库 ⭐
- `GET /`: 获取题库列表
- `GET /{exam_id}`: 获取题库详情
- `PUT /{exam_id}/progress`: 更新刷题进度
**去重逻辑：**
```python
# 1. 解析文档获取题目
questions_data = await llm_service.parse_document(content)
# 2. 计算每道题的 Hash
for q in questions_data:
q["content_hash"] = calculate_content_hash(q["content"])
# 3. 仅在当前 exam_id 范围内查询去重
existing_hashes = await db.execute(
select(Question.content_hash).where(Question.exam_id == exam_id)
)
# 4. 仅插入 Hash 不存在的题目
for q in questions_data:
if q["content_hash"] not in existing_hashes:
db.add(Question(**q))
```
#### `llm_service.py` - AI 服务
提供两个核心功能：
1. `parse_document()`: 调用 LLM 解析文档，提取题目
2. `grade_short_answer()`: AI 评分简答题
支持 3 个 AI 提供商：
- OpenAI (GPT-4o-mini)
- Anthropic (Claude-3-haiku)
- Qwen (通义千问)
---
### 前端核心
#### `client.js` - API 客户端
封装了所有后端 API：
- `authAPI`: 登录、注册、用户信息
- `examAPI`: 题库 CRUD、追加文档
- `questionAPI`: 获取题目、答题
- `mistakeAPI`: 错题本管理
- `adminAPI`: 系统配置
**特性：**
- 自动添加 JWT Token
- 统一错误处理和 Toast 提示
- 401 自动跳转登录
#### `ExamDetail.jsx` - 题库详情
最复杂的前端页面，包含：
- **追加上传**: 上传新文档并去重
- **状态轮询**: 每 3 秒轮询一次状态
- **智能按钮**:
- 处理中时禁用「添加文档」
- 就绪后显示「开始/继续刷题」
- **进度展示**: 题目数、完成度、进度条
**状态轮询实现：**
```javascript
useEffect(() => {
const interval = setInterval(() => {
pollExamStatus() // 轮询状态
}, 3000)
return () => clearInterval(interval)
}, [examId])
const pollExamStatus = async () => {
const newExam = await examAPI.getDetail(examId)
// 检测状态变化
if (exam?.status === 'processing' && newExam.status === 'ready') {
toast.success('文档解析完成！')
await loadExamDetail() // 重新加载数据
}
setExam(newExam)
}
```
#### `QuizPlayer.jsx` - 刷题核心
实现完整的刷题流程：
1. 基于 `current_index` 加载当前题目
2. 根据题型显示不同的答题界面
3. 提交答案并检查（简答题调用 AI 评分）
4. 答错自动加入错题本
5. 点击下一题自动更新进度
**断点续做实现：**
```javascript
// 始终基于 exam.current_index 加载题目
const loadCurrentQuestion = async () => {
const question = await questionAPI.getCurrentQuestion(examId)
// 后端会根据 current_index 返回对应题目
}
// 下一题时更新进度
const handleNext = async () => {
const newIndex = exam.current_index + 1
await examAPI.updateProgress(examId, newIndex)
await loadCurrentQuestion()
}
```
---
## 🔄 核心业务流程
### 1. 创建题库流程
```
用户上传文档
↓
后端创建 Exam (status=pending)
↓
后台任务开始解析
↓
更新状态为 processing
↓
调用 document_parser 解析文件
↓
调用 llm_service 提取题目
↓
计算 content_hash 并去重
↓
插入新题目到数据库
↓
更新 total_questions 和 status=ready
↓
前端轮询检测到状态变化
↓
自动刷新显示新题目
```
### 2. 追加文档流程
```
用户点击「添加题目文档」
↓
上传新文档
↓
后端检查 Exam 是否在处理中
↓
更新状态为 processing
↓
后台任务解析新文档
↓
提取题目并计算 Hash
↓
仅在当前 exam_id 范围内查重
↓
插入不重复的题目
↓
更新 total_questions
↓
更新状态为 ready
↓
前端轮询检测并刷新
```
### 3. 刷题流程
```
用户点击「开始刷题」
↓
基于 current_index 加载题目
↓
用户选择/输入答案
↓
提交答案到后端
↓
后端检查答案
├─ 选择题：字符串比对
├─ 多选题：排序后比对
├─ 判断题：字符串比对
└─ 简答题：调用 AI 评分
↓
答错自动加入错题本
↓
返回结果和解析
↓
用户点击「下一题」
↓
更新 current_index += 1
↓
加载下一题
```
---
## 🗄️ 数据库设计
### 关键索引
```sql
-- Exam 表
CREATE INDEX ix_exams_user_status ON exams(user_id, status);
-- Question 表
CREATE INDEX ix_questions_exam_hash ON questions(exam_id, content_hash);
CREATE INDEX ix_questions_content_hash ON questions(content_hash);
-- UserMistake 表
CREATE UNIQUE INDEX ix_user_mistakes_unique ON user_mistakes(user_id, question_id);
```
### 关键约束
- `Question.content_hash`: 用于去重，同一 exam_id 下不允许重复
- `UserMistake`: user_id + question_id 唯一约束，防止重复添加
- 级联删除：删除 Exam 时自动删除所有关联的 Question 和 UserMistake
---
## 🎨 技术栈
### 后端
- **FastAPI**: 现代化 Python Web 框架
- **SQLAlchemy 2.0**: 异步 ORM
- **Alembic**: 数据库迁移
- **Pydantic**: 数据验证
- **JWT**: 无状态认证
- **OpenAI/Anthropic/Qwen**: AI 解析和评分
### 前端
- **React 18**: UI 框架
- **Vite**: 构建工具（比 CRA 更快）
- **Tailwind CSS**: 原子化 CSS
- **Axios**: HTTP 客户端
- **React Router**: 路由管理
- **React Hot Toast**: 消息提示
### 部署
- **Docker + Docker Compose**: 容器化部署
- **PostgreSQL 15**: 关系型数据库
- **Nginx** (可选): 反向代理
---
## 📊 API 接口汇总
### 认证相关
- `POST /api/auth/register`: 用户注册
- `POST /api/auth/login`: 用户登录
- `GET /api/auth/me`: 获取当前用户信息
- `POST /api/auth/change-password`: 修改密码
### 题库相关
- `POST /api/exams/create`: 创建题库
- `POST /api/exams/{exam_id}/append`: 追加文档 ⭐
- `GET /api/exams/`: 获取题库列表
- `GET /api/exams/{exam_id}`: 获取题库详情
- `DELETE /api/exams/{exam_id}`: 删除题库
- `PUT /api/exams/{exam_id}/progress`: 更新进度
### 题目相关
- `GET /api/questions/exam/{exam_id}/questions`: 获取题库所有题目
- `GET /api/questions/exam/{exam_id}/current`: 获取当前题目
- `GET /api/questions/{question_id}`: 获取题目详情
- `POST /api/questions/check`: 检查答案
### 错题本相关
- `GET /api/mistakes/`: 获取错题列表
- `POST /api/mistakes/add`: 添加错题
- `DELETE /api/mistakes/{mistake_id}`: 移除错题
- `DELETE /api/mistakes/question/{question_id}`: 按题目 ID 移除
### 管理员相关
- `GET /api/admin/config`: 获取系统配置
- `PUT /api/admin/config`: 更新系统配置
---
## 🔒 安全特性
1. **密码加密**: bcrypt 哈希
2. **JWT 认证**: 无状态 Token
3. **权限控制**: 管理员/普通用户
4. **CORS 保护**: 可配置允许的来源
5. **文件类型验证**: 仅允许特定格式
6. **文件大小限制**: 可配置最大上传大小
7. **速率限制**: 每日上传次数限制
---
## 🎯 核心创新点
1. **智能去重**: 基于 content_hash 的高效去重算法
2. **追加上传**: 支持向现有题库添加新文档
3. **异步处理**: 后台任务处理文档解析，不阻塞用户
4. **状态轮询**: 前端实时显示处理状态
5. **断点续做**: 基于 current_index 的进度管理
6. **AI 评分**: 简答题智能评分和反馈
7. **自动错题本**: 答错自动收集，支持手动管理
8. **多 AI 支持**: 灵活切换 AI 提供商
---
这就是 QQuiz 的完整架构！🎉

234
docs/QUICK_START.md Normal file
View 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。

94
docs/README_QUICKSTART.md Normal file
View File

@@ -0,0 +1,94 @@
# QQuiz Quick Start Guide
## Step 1: Configure (30 seconds)
Double-click to run:
```
setup.bat
```
This will:
- Create `.env` file
- Open it in Notepad
- You need to replace `sk-your-openai-api-key-here` with your real OpenAI API key
**Where to get API key:**
- Visit: https://platform.openai.com/api-keys
- Create new secret key
- Copy and paste into `.env` file
## Step 2: Start Application (3-5 minutes)
Double-click to run:
```
start_app.bat
```
**PostgreSQL Password:**
- When prompted, enter your PostgreSQL password
- Default is usually: `postgres`
- Or just press Enter to try without password
The script will automatically:
- ✓ Check Python and Node.js
- ✓ Create database
- ✓ Install all dependencies
- ✓ Start backend (new window)
- ✓ Start frontend (new window)
## Step 3: Access System
Browser will open automatically: http://localhost:3000
**Login:**
- Username: `admin`
- Password: `admin123`
**Test the system:**
1. Click "题库管理" (Exam Management)
2. Click "创建题库" (Create Exam)
3. Enter name: `Test Exam`
4. Upload file: `test_data/sample_questions.txt`
5. Wait 10-30 seconds for AI to process
6. Click "开始刷题" (Start Quiz)
## What You'll See
✅ Beautiful login page
✅ Dashboard with statistics
✅ Create exam and upload documents
✅ AI processes questions automatically
✅ Quiz player with different question types
✅ Automatic mistake collection
✅ Progress tracking
## Troubleshooting
### Can't find PostgreSQL password
- Try: `postgres` or leave empty
- Or check PostgreSQL installation
### Port already in use
```cmd
netstat -ano | findstr :3000
taskkill /F /PID <PID>
```
### Dependencies install failed
- Check internet connection
- Script uses China mirrors for speed
## Success!
If you see the login page at http://localhost:3000 - congratulations! 🎉
The system is now running. You can:
- Create exam banks
- Upload documents (TXT/PDF/DOCX/XLSX)
- Start quizzing
- Review mistakes
- Track progress
---
Enjoy using QQuiz! 🚀

64
docs/START_HERE.txt Normal file
View File

@@ -0,0 +1,64 @@
==========================================
QQuiz 快速启动指南 (3步完成)
==========================================
【第1步】配置 OpenAI API Key
-------------------------------------------
1. 双击运行: quick_config.bat
2. 会自动打开记事本，找到这一行：
OPENAI_API_KEY=sk-your-openai-api-key-here
3. 将 "sk-your-openai-api-key-here" 替换为你的真实 API Key
4. 保存并关闭记事本
如果没有 API Key，可以：
- 去 https://platform.openai.com/api-keys 创建
- 或者暂时使用测试 Key（功能受限）
【第2步】启动系统
-------------------------------------------
双击运行: auto_setup_and_run.bat
脚本会自动：
✓ 检查 Python 和 Node.js
✓ 创建数据库
✓ 安装所有依赖
✓ 启动后端和前端
整个过程 3-5 分钟，请耐心等待
【第3步】访问系统
-------------------------------------------
浏览器打开: http://localhost:3000
默认账户：
用户名: admin
密码: admin123
【如果遇到问题】
-------------------------------------------
1. PostgreSQL 密码
- 脚本会询问 PostgreSQL 管理员密码
- 如果是首次安装，密码可能是你安装时设置的
- 常见默认密码: postgres 或 root
2. 数据库连接失败
- 确保 PostgreSQL 服务正在运行
- 打开"服务"查看 postgresql 服务状态
3. 端口被占用
- 3000/8000 端口可能被占用
- 关闭占用端口的程序重试
【测试数据】
-------------------------------------------
创建题库时可以上传：
test_data/sample_questions.txt
==========================================
准备好了吗？现在开始第1步！
==========================================

533
docs/WINDOWS_DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,533 @@
# QQuiz Windows 部署指南
## 🚀 方式一：Docker Desktop（推荐）
这是 Windows 上最简单的部署方式。
### 前置要求
1. **安装 Docker Desktop**
- 下载地址：https://www.docker.com/products/docker-desktop/
- 系统要求：Windows 10/11 64-bit (Pro/Enterprise/Education)
- 需要启用 WSL 2
2. **启用 WSL 2**（如果未启用）
```powershell
# 以管理员身份运行 PowerShell
wsl --install
# 重启计算机
```
### 部署步骤
#### 1. 配置环境变量
```powershell
# 在项目根目录（E:\QQuiz）打开 PowerShell
cd E:\QQuiz
# 复制环境变量模板
copy .env.example .env
# 使用记事本编辑 .env
notepad .env
```
**必须修改的配置：**
```env
# JWT 密钥（必须修改！至少 32 字符）
SECRET_KEY=your-very-long-secret-key-change-this-to-something-secure
# 选择一个 AI 提供商并配置 API Key
# 方案 1: 使用 OpenAI
AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-4o-mini
# 方案 2: 使用通义千问（国内推荐）
# AI_PROVIDER=qwen
# QWEN_API_KEY=sk-your-qwen-api-key
# QWEN_MODEL=qwen-plus
# 方案 3: 使用 Claude
# AI_PROVIDER=anthropic
# ANTHROPIC_API_KEY=sk-ant-your-key
# ANTHROPIC_MODEL=claude-3-haiku-20240307
```
#### 2. 启动 Docker Desktop
- 打开 Docker Desktop 应用
- 等待 Docker Engine 启动（底部状态显示 "Running"）
#### 3. 启动服务
```powershell
# 在项目根目录
cd E:\QQuiz
# 启动所有服务（第一次会比较慢，需要下载镜像）
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f
```
#### 4. 访问应用
- **前端**: http://localhost:3000
- **后端 API**: http://localhost:8000
- **API 文档**: http://localhost:8000/docs
#### 5. 默认账户登录
- **用户名**: `admin`
- **密码**: `admin123`
⚠️ **首次登录后请立即修改密码！**
### 常用 Docker 命令
```powershell
# 查看运行状态
docker-compose ps
# 查看日志
docker-compose logs -f backend
docker-compose logs -f frontend
# 停止服务
docker-compose stop
# 重启服务
docker-compose restart
# 停止并删除容器
docker-compose down
# 重新构建并启动
docker-compose up -d --build
# 进入容器内部
docker-compose exec backend bash
docker-compose exec postgres psql -U qquiz qquiz_db
```
### 问题排查
#### 问题 1: Docker Desktop 无法启动
**解决方案：**
```powershell
# 确保 WSL 2 已安装
wsl --list --verbose
# 如果版本是 1，升级到 2
wsl --set-version Ubuntu 2
# 设置默认版本为 2
wsl --set-default-version 2
```
#### 问题 2: 端口被占用
```powershell
# 查看端口占用
netstat -ano | findstr :3000
netstat -ano | findstr :8000
netstat -ano | findstr :5432
# 结束占用进程（替换 PID）
taskkill /F /PID <进程ID>
```
#### 问题 3: 容器启动失败
```powershell
# 查看详细错误日志
docker-compose logs backend
# 重新构建
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```
---
## 🛠️ 方式二：本地源码部署
适合开发调试，需要手动安装各种依赖。
### 前置要求
1. **Python 3.11+**
- 下载：https://www.python.org/downloads/
- 安装时勾选 "Add Python to PATH"
2. **Node.js 18+**
- 下载：https://nodejs.org/
- 推荐安装 LTS 版本
3. **PostgreSQL 15+**
- 下载：https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
- 记住安装时设置的密码
### 部署步骤
#### 1. 安装 PostgreSQL
1. 下载并安装 PostgreSQL 15
2. 安装完成后，打开 **pgAdmin 4** 或 **SQL Shell (psql)**
3. 创建数据库：
```sql
-- 使用 psql 或 pgAdmin 执行
CREATE DATABASE qquiz_db;
CREATE USER qquiz WITH PASSWORD 'qquiz_password';
GRANT ALL PRIVILEGES ON DATABASE qquiz_db TO qquiz;
```
#### 2. 配置环境变量
```powershell
cd E:\QQuiz
copy .env.example .env
notepad .env
```
**修改数据库连接为本地：**
```env
# 数据库（本地部署）
DATABASE_URL=postgresql+asyncpg://qquiz:qquiz_password@localhost:5432/qquiz_db
# JWT 密钥
SECRET_KEY=your-super-secret-key-at-least-32-characters-long
# AI 配置（选择一个）
AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-4o-mini
```
#### 3. 启动后端
**打开第一个 PowerShell 窗口：**
```powershell
cd E:\QQuiz\backend
# 创建虚拟环境
python -m venv venv
# 激活虚拟环境
.\venv\Scripts\Activate.ps1
# 如果遇到执行策略错误，运行：
# Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 安装依赖
pip install -r requirements.txt
# 运行数据库迁移
alembic upgrade head
# 启动后端服务
uvicorn main:app --reload
```
**成功后会看到：**
```
INFO: Uvicorn running on http://127.0.0.1:8000
INFO: Application startup complete.
```
#### 4. 启动前端
**打开第二个 PowerShell 窗口：**
```powershell
cd E:\QQuiz\frontend
# 安装依赖（第一次需要）
npm install
# 启动开发服务器
npm start
```
**成功后会自动打开浏览器：**
```
VITE v5.0.11 ready in 1234 ms
➜ Local: http://localhost:3000/
➜ Network: use --host to expose
```
#### 5. 访问应用
- **前端**: http://localhost:3000
- **后端**: http://localhost:8000
- **API 文档**: http://localhost:8000/docs
### 问题排查
#### 问题 1: PowerShell 执行策略错误
```powershell
# 错误信息：无法加载文件 xxx.ps1，因为在此系统上禁止运行脚本
# 解决方案：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 然后重新激活虚拟环境
.\venv\Scripts\Activate.ps1
```
#### 问题 2: pip 安装依赖失败
```powershell
# 使用国内镜像加速
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```
#### 问题 3: PostgreSQL 连接失败
```powershell
# 确认 PostgreSQL 服务正在运行
# 打开 "服务" (services.msc)
# 找到 "postgresql-x64-15"，确保状态为 "正在运行"
# 或使用命令行
sc query postgresql-x64-15
```
#### 问题 4: npm 安装慢
```powershell
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
# 然后重新安装
npm install
```
---
## 🧪 测试部署是否成功
### 1. 检查后端健康状态
浏览器访问：http://localhost:8000/health
**预期返回：**
```json
{"status": "healthy"}
```
### 2. 查看 API 文档
访问：http://localhost:8000/docs
应该能看到 Swagger UI 界面，显示所有 API 接口。
### 3. 测试登录
1. 访问 http://localhost:3000
2. 使用默认账户登录：
- 用户名：`admin`
- 密码：`admin123`
3. 成功后应该进入 Dashboard
### 4. 测试创建题库
1. 点击「题库管理」
2. 点击「创建题库」
3. 输入题库名称
4. 上传测试文档（可以创建一个简单的 TXT 文件）
**测试文档示例 (test_questions.txt):**
```txt
1. Python 是一种什么类型的语言？
A. 编译型语言
B. 解释型语言
C. 汇编语言
D. 机器语言
答案：B
解析：Python 是一种解释型、面向对象的高级编程语言。
2. 以下哪个不是 Python 的数据类型？
A. list
B. tuple
C. array
D. dict
答案：C
解析：Python 内置的数据类型包括 list、tuple、dict 等，array 需要导入 array 模块。
```
5. 上传后等待解析完成（状态会从「处理中」变为「就绪」）
6. 点击「开始刷题」测试刷题功能
---
## 📝 Windows 特定配置
### 1. 设置环境变量（可选）
**通过 GUI 设置：**
1. 右键「此电脑」→「属性」
2. 「高级系统设置」→「环境变量」
3. 在「用户变量」中添加：
- `OPENAI_API_KEY`: 你的 API Key
- `SECRET_KEY`: 你的密钥
### 2. 配置防火墙（如果需要局域网访问）
```powershell
# 允许端口访问（以管理员身份运行）
netsh advfirewall firewall add rule name="QQuiz Frontend" dir=in action=allow protocol=TCP localport=3000
netsh advfirewall firewall add rule name="QQuiz Backend" dir=in action=allow protocol=TCP localport=8000
```
### 3. 创建启动脚本
**创建 `start.bat` 文件：**
```batch
@echo off
echo Starting QQuiz...
REM 检查 Docker Desktop 是否运行
docker info >nul 2>&1
if %errorlevel% neq 0 (
echo Starting Docker Desktop...
start "" "C:\Program Files\Docker\Docker\Docker Desktop.exe"
timeout /t 10
)
REM 启动服务
cd /d "%~dp0"
docker-compose up -d
echo.
echo QQuiz is starting...
echo Frontend: http://localhost:3000
echo Backend: http://localhost:8000
echo.
pause
```
**使用方法：**
- 双击 `start.bat` 即可启动服务
---
## 🎯 性能优化建议
### 1. Docker Desktop 配置
1. 打开 Docker Desktop
2. 设置 → Resources
3. 调整资源分配：
- **CPUs**: 4 核（推荐）
- **Memory**: 4 GB（推荐）
- **Swap**: 1 GB
- **Disk image size**: 60 GB
### 2. WSL 2 优化
**限制 WSL 2 内存占用（可选）：**
创建 `%USERPROFILE%\.wslconfig` 文件：
```ini
[wsl2]
memory=4GB
processors=4
swap=1GB
```
重启 WSL：
```powershell
wsl --shutdown
```
### 3. 开发工具推荐
- **代码编辑器**: VS Code（安装 Python、ESLint、Prettier 插件）
- **API 测试**: Postman 或 Insomnia
- **数据库管理**: pgAdmin 4 或 DBeaver
- **终端**: Windows Terminal（更好的 PowerShell 体验）
---
## 🔧 常见问题汇总
### Q: 如何完全重置项目？
```powershell
# Docker 方式
docker-compose down -v # 删除容器和数据卷
docker-compose up -d # 重新启动
# 本地方式
# 1. 删除数据库
DROP DATABASE qquiz_db;
CREATE DATABASE qquiz_db;
# 2. 重新运行迁移
cd E:\QQuiz\backend
alembic upgrade head
```
### Q: 如何查看日志？
```powershell
# Docker 方式
docker-compose logs -f backend
docker-compose logs -f frontend
# 本地方式
# 直接在运行的 PowerShell 窗口中查看
```
### Q: 如何停止服务？
```powershell
# Docker 方式
docker-compose stop
# 本地方式
# 在运行的 PowerShell 窗口中按 Ctrl+C
```
### Q: 如何更新代码后重启？
```powershell
# Docker 方式
docker-compose restart
# 本地方式（uvicorn 和 vite 会自动重载）
# 无需操作，保存文件后自动刷新
```
---
## 📞 获取帮助
如果遇到问题：
1. **查看日志**: `docker-compose logs -f`
2. **检查文档**: 阅读 `DEPLOYMENT.md`
3. **查看 API 文档**: http://localhost:8000/docs
4. **GitHub Issues**: 提交问题报告
---
祝你部署顺利！🎉