docs: 完善文档和清理项目,添加 Gemini 配置指南

主要更新:

📚 文档改进
- 新增 AI_CONFIGURATION.md:详细的 AI 提供商配置指南
- 新增 CHINA_MIRROR_GUIDE.md:中国镜像加速指南
- 删除 6 个过时文档(DEPLOYMENT.md, QUICK_START.md 等)
- 更新 README.md:添加 Gemini 功能特性和 AI 提供商对比表

🧹 脚本清理
- 删除 11 个重复/过时脚本(从 25 个减少到 14 个)
- 删除 PostgreSQL 相关脚本(项目使用 MySQL)
- 删除重复的启动脚本(start_windows.bat, start_app.bat 等)

⚙️ 配置文件更新
- 更新 .env.example:添加 Gemini 配置示例和说明
- 默认 AI_PROVIDER 改为 gemini(推荐)
- 添加各提供商的获取 API Key 链接

🎯 核心改进
- 突出 Gemini 原生 PDF 理解优势
- 提供清晰的 AI 提供商选择指南
- 简化项目结构,提高可维护性

清理内容:
- 删除 docs: DEPLOYMENT.md, DOCKER_MIRROR_SETUP.md, GITHUB_PUSH_GUIDE.md,
  QUICK_START.md, README_QUICKSTART.md, START_HERE.txt
- 删除 scripts: auto_setup_and_run.bat, check_postgres.bat, logs_windows.bat,
  push_to_github.bat, quick_config.bat, restart_docker.bat, setup_docker_mirror.bat,
  start_app.bat, start_postgres.bat, start_windows.bat, start_windows_china.bat

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2025-12-01 23:21:04 +08:00
parent f403eacb9d
commit ed87aae014
30 changed files with 531 additions and 2206 deletions

View File

@@ -5,7 +5,9 @@ QQuiz 是一个支持 Docker/源码双模部署的智能刷题平台,核心功
## 功能特性
- 📚 **多文件上传与去重**: 支持向同一题库追加文档,自动识别并过滤重复题目
- 🤖 **AI 智能解析**: 支持 OpenAI/Anthropic/Qwen 多种 AI 提供商
- 🤖 **AI 智能解析**: 支持 Google Gemini (推荐) / OpenAI / Anthropic / Qwen 多种 AI 提供商
- 📄 **原生 PDF 理解**: Gemini 支持直接处理 PDF最多1000页完整保留图片、表格、公式等内容
- 🎓 **AI 参考答案**: 对于没有提供答案的题目,自动生成 AI 参考答案
- 📊 **断点续做**: 自动记录刷题进度,随时继续
-**错题本管理**: 自动收集错题,支持手动添加/移除
- 🎯 **多题型支持**: 单选、多选、判断、简答
@@ -66,6 +68,23 @@ chmod +x scripts/run_local.sh
**MySQL 安装指南:** 详见 [docs/MYSQL_SETUP.md](docs/MYSQL_SETUP.md)
### Docker 构建加速(中国用户)
如果你在中国大陆Docker 构建速度可能较慢。我们提供了使用国内镜像的可选配置:
**详细指南:** 参见 [docs/CHINA_MIRROR_GUIDE.md](docs/CHINA_MIRROR_GUIDE.md)
**快速使用:**
```bash
# 后端使用中国镜像构建
docker build -f backend/Dockerfile.china -t qquiz-backend ./backend
# 前端使用中国镜像构建
docker build -f frontend/Dockerfile.china -t qquiz-frontend ./frontend
```
构建速度可提升 3-5 倍 ⚡
## 默认账户
**管理员账户:**
@@ -98,11 +117,13 @@ QQuiz/
│ ├── fix_and_start.bat # Windows 快速启动(推荐)
│ ├── start_with_docker_db.bat # Docker 数据库启动
│ ├── setup.bat # 环境配置脚本
── run_local.sh # Linux/macOS 启动脚本
── run_local.sh # Linux/macOS 启动脚本
│ └── [其他辅助脚本...]
├── docs/ # 文档目录
│ ├── QUICK_START.md # 快速入门指南
│ ├── WINDOWS_DEPLOYMENT.md # Windows 部署指南
│ ├── DOCKER_MIRROR_SETUP.md # Docker 镜像加速配置
│ ├── AI_CONFIGURATION.md # AI 提供商配置指南(重要)
│ ├── MYSQL_SETUP.md # MySQL 安装配置指南
│ ├── CHINA_MIRROR_GUIDE.md # 中国镜像加速指南
│ ├── WINDOWS_DEPLOYMENT.md # Windows 部署详细指南
│ └── PROJECT_STRUCTURE.md # 项目架构详解
├── test_data/ # 测试数据
│ └── sample_questions.txt # 示例题目
@@ -141,12 +162,51 @@ QQuiz/
|------|------|--------|
| `DATABASE_URL` | 数据库连接字符串 | - |
| `SECRET_KEY` | JWT 密钥 | - |
| `AI_PROVIDER` | AI 提供商 (openai/anthropic/qwen) | openai |
| `AI_PROVIDER` | AI 提供商 (gemini/openai/anthropic/qwen) | gemini |
| `GEMINI_API_KEY` | Google Gemini API 密钥 | - |
| `GEMINI_BASE_URL` | Gemini API 地址(可选,支持代理) | https://generativelanguage.googleapis.com |
| `GEMINI_MODEL` | Gemini 模型 | gemini-2.0-flash-exp |
| `OPENAI_API_KEY` | OpenAI API 密钥 | - |
| `OPENAI_BASE_URL` | OpenAI API 地址 | https://api.openai.com/v1 |
| `OPENAI_MODEL` | OpenAI 模型 | gpt-4o-mini |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | - |
| `ANTHROPIC_MODEL` | Anthropic 模型 | claude-3-haiku-20240307 |
| `QWEN_API_KEY` | 通义千问 API 密钥 | - |
| `QWEN_BASE_URL` | 通义千问 API 地址 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| `QWEN_MODEL` | 通义千问模型 | qwen-plus |
| `ALLOW_REGISTRATION` | 是否允许注册 | true |
| `MAX_UPLOAD_SIZE_MB` | 最大上传文件大小 (MB) | 10 |
| `MAX_DAILY_UPLOADS` | 每日上传次数限制 | 20 |
### AI 提供商对比
| 提供商 | PDF 原生支持 | 文本解析 | 推荐度 | 说明 |
|--------|--------------|----------|--------|------|
| **Google Gemini** | ✅ | ✅ | ⭐⭐⭐⭐⭐ | 支持原生 PDF最多1000页保留图片、表格、公式 |
| OpenAI | ❌ | ✅ | ⭐⭐⭐⭐ | 仅文本提取PDF 会丢失格式和图片 |
| Anthropic | ❌ | ✅ | ⭐⭐⭐⭐ | 仅文本提取PDF 会丢失格式和图片 |
| Qwen (通义千问) | ❌ | ✅ | ⭐⭐⭐ | 仅文本提取PDF 会丢失格式和图片 |
**推荐使用 Gemini**:如果你的题库包含 PDF 文件(特别是含有图片、公式、表格的学科试卷),强烈推荐使用 Gemini。
### 如何获取 API Key
- **Google Gemini**: https://aistudio.google.com/apikey (免费额度充足)
- **OpenAI**: https://platform.openai.com/api-keys
- **Anthropic**: https://console.anthropic.com/settings/keys
- **Qwen (通义千问)**: https://dashscope.console.aliyun.com/apiKey
### AI 配置方式
QQuiz 支持两种配置方式:
1. **环境变量配置** (`.env` 文件):适合 Docker 部署和开发环境
2. **数据库配置** (管理员后台):适合生产环境,支持在线修改,无需重启服务
**推荐流程**:首次部署使用环境变量,部署成功后通过管理员后台修改配置。
**Gemini 自定义代理**: 如果需要使用 Key 轮训服务或代理,可以在管理员后台配置 `GEMINI_BASE_URL`,支持自定义 Gemini API 地址。
## 技术栈
**后端:**