mirror of
https://github.com/handsomezhuzhu/QQuiz.git
synced 2026-02-20 12:00:14 +00:00
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:
201
docs/AI_CONFIGURATION.md
Normal file
201
docs/AI_CONFIGURATION.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# AI 提供商配置指南
|
||||
|
||||
QQuiz 支持多个 AI 提供商，推荐使用 Google Gemini 以获得最佳的 PDF 解析体验。
|
||||
|
||||
## 🌟 推荐：Google Gemini
|
||||
|
||||
### 优势
|
||||
|
||||
- ✅ **原生 PDF 理解**：直接处理 PDF（最多1000页），完整保留图片、表格、公式
|
||||
- ✅ **免费额度充足**：每天免费 15 次/分钟，1500 次/天
|
||||
- ✅ **多模态理解**：支持图片、图表、公式的理解
|
||||
- ✅ **自定义代理**：支持配置自定义 Base URL 实现 Key 轮训等功能
|
||||
|
||||
### 获取 API Key
|
||||
|
||||
1. 访问 https://aistudio.google.com/apikey
|
||||
2. 使用 Google 账号登录
|
||||
3. 点击 "Create API Key"
|
||||
4. 复制生成的 API Key（格式：`AIza...`）
|
||||
|
||||
### 配置方式
|
||||
|
||||
#### 方式一：环境变量配置（推荐首次部署）
|
||||
|
||||
编辑 `.env` 文件：
|
||||
|
||||
```env
|
||||
AI_PROVIDER=gemini
|
||||
GEMINI_API_KEY=AIza-your-actual-gemini-api-key
|
||||
GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
GEMINI_MODEL=gemini-2.0-flash-exp
|
||||
```
|
||||
|
||||
#### 方式二：管理员后台配置（推荐生产环境）
|
||||
|
||||
1. 使用管理员账号登录（默认：admin / admin123）
|
||||
2. 进入"系统设置"
|
||||
3. 选择 AI 提供商："Google Gemini (推荐)"
|
||||
4. 填入 API Key
|
||||
5. 点击"保存所有设置"
|
||||
|
||||
**优势**：无需重启服务即可生效，支持在线修改配置
|
||||
|
||||
### 自定义 Gemini Base URL（可选）
|
||||
|
||||
如果需要使用 Key 轮训服务或代理（例如提高速度、负载均衡），可以配置自定义 Base URL：
|
||||
|
||||
```env
|
||||
# 使用自定义代理服务
|
||||
GEMINI_BASE_URL=https://your-proxy-service.com/proxy/gemini-self
|
||||
```
|
||||
|
||||
**使用场景**：
|
||||
- Key 轮训（多个 API Key 负载均衡）
|
||||
- 国内加速代理
|
||||
- 自建中转服务
|
||||
|
||||
---
|
||||
|
||||
## 其他 AI 提供商
|
||||
|
||||
### OpenAI (GPT)
|
||||
|
||||
**限制**：⚠️ 仅支持文本解析，PDF 文件会通过文本提取处理，丢失图片和格式信息
|
||||
|
||||
#### 获取 API Key
|
||||
- 访问：https://platform.openai.com/api-keys
|
||||
- 创建新的 Secret Key
|
||||
|
||||
#### 配置
|
||||
```env
|
||||
AI_PROVIDER=openai
|
||||
OPENAI_API_KEY=sk-your-openai-api-key
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4o-mini
|
||||
```
|
||||
|
||||
**推荐模型**：
|
||||
- `gpt-4o-mini`（推荐，性价比高）
|
||||
- `gpt-4o`（最强，成本高）
|
||||
- `gpt-3.5-turbo`（便宜，效果一般）
|
||||
|
||||
---
|
||||
|
||||
### Anthropic (Claude)
|
||||
|
||||
**限制**：⚠️ 仅支持文本解析，PDF 文件会通过文本提取处理，丢失图片和格式信息
|
||||
|
||||
#### 获取 API Key
|
||||
- 访问：https://console.anthropic.com/settings/keys
|
||||
- 创建新的 API Key
|
||||
|
||||
#### 配置
|
||||
```env
|
||||
AI_PROVIDER=anthropic
|
||||
ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key
|
||||
ANTHROPIC_MODEL=claude-3-haiku-20240307
|
||||
```
|
||||
|
||||
**推荐模型**：
|
||||
- `claude-3-haiku-20240307`（推荐，速度快）
|
||||
- `claude-3-5-sonnet-20241022`（最强，成本高）
|
||||
- `claude-3-opus-20240229`（超强，成本很高）
|
||||
|
||||
---
|
||||
|
||||
### Qwen (通义千问)
|
||||
|
||||
**限制**：⚠️ 仅支持文本解析，PDF 文件会通过文本提取处理，丢失图片和格式信息
|
||||
|
||||
#### 获取 API Key
|
||||
- 访问：https://dashscope.console.aliyun.com/apiKey
|
||||
- 使用阿里云账号登录
|
||||
- 创建新的 API Key
|
||||
|
||||
#### 配置
|
||||
```env
|
||||
AI_PROVIDER=qwen
|
||||
QWEN_API_KEY=sk-your-qwen-api-key
|
||||
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
QWEN_MODEL=qwen-plus
|
||||
```
|
||||
|
||||
**推荐模型**：
|
||||
- `qwen-plus`（推荐，平衡）
|
||||
- `qwen-max`（最强，成本高）
|
||||
- `qwen-turbo`（快速，效果一般）
|
||||
- `qwen-long`（超长文本支持）
|
||||
|
||||
---
|
||||
|
||||
## AI 提供商对比表
|
||||
|
||||
| 提供商 | PDF 原生支持 | 图片/表格/公式 | 文本解析 | 免费额度 | 推荐度 |
|
||||
|--------|--------------|----------------|----------|----------|--------|
|
||||
| **Google Gemini** | ✅ 支持 | ✅ 完整保留 | ✅ | ⭐⭐⭐⭐⭐ | 最推荐 |
|
||||
| OpenAI (GPT) | ❌ 不支持 | ❌ 丢失 | ✅ | 💰 | ⭐⭐⭐⭐ |
|
||||
| Anthropic (Claude) | ❌ 不支持 | ❌ 丢失 | ✅ | 💰 | ⭐⭐⭐⭐ |
|
||||
| Qwen (通义千问) | ❌ 不支持 | ❌ 丢失 | ✅ | ✅ | ⭐⭐⭐ |
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q1: 如何判断 AI 提供商是否配置正确？
|
||||
|
||||
上传一个包含题目的文档，如果能成功解析出题目，说明配置正确。查看后端日志可以看到详细的解析过程。
|
||||
|
||||
### Q2: 可以同时配置多个 AI 提供商吗？
|
||||
|
||||
可以。配置多个提供商的 API Key，通过 `AI_PROVIDER` 环境变量或管理员后台切换使用哪个提供商。
|
||||
|
||||
### Q3: Gemini 原生 PDF 处理和文本提取有什么区别？
|
||||
|
||||
- **原生 PDF 处理**（Gemini）：AI 直接"看"PDF，能识别图片中的文字、理解表格结构、识别数学公式
|
||||
- **文本提取**（其他提供商）：先用 PyPDF2/python-docx 提取纯文本，然后交给 AI，丢失所有图片和格式
|
||||
|
||||
**示例**：如果试卷中有带图的选择题，Gemini 能理解图片内容并提取题目，其他提供商只能提取文字部分。
|
||||
|
||||
### Q4: Gemini 自定义 Base URL 有什么用？
|
||||
|
||||
- **场景一**：使用多个 API Key 的轮训服务，避免单个 Key 频率限制
|
||||
- **场景二**：使用国内加速代理，提高访问速度
|
||||
- **场景三**：自建中转服务，统一管理和监控 API 调用
|
||||
|
||||
**格式要求**：Base URL 应该是完整的域名，例如 `https://your-service.com`，后端会自动拼接 `/v1beta/models/{model}:generateContent`
|
||||
|
||||
### Q5: 如果文档中没有提供答案怎么办？
|
||||
|
||||
QQuiz 会自动使用 AI 生成参考答案，标注为"AI参考答案："。这个功能对所有 AI 提供商都支持。
|
||||
|
||||
---
|
||||
|
||||
## 推荐配置方案
|
||||
|
||||
### 方案一：仅使用 Gemini（推荐）
|
||||
```env
|
||||
AI_PROVIDER=gemini
|
||||
GEMINI_API_KEY=your-key
|
||||
```
|
||||
- ✅ 最佳 PDF 支持
|
||||
- ✅ 免费额度充足
|
||||
- ✅ 配置简单
|
||||
|
||||
### 方案二：Gemini + OpenAI（备用）
|
||||
```env
|
||||
AI_PROVIDER=gemini
|
||||
GEMINI_API_KEY=your-gemini-key
|
||||
OPENAI_API_KEY=your-openai-key
|
||||
```
|
||||
- 主用 Gemini，当遇到限制时手动切换到 OpenAI
|
||||
|
||||
### 方案三：全配置（多选）
|
||||
配置所有提供商，根据需求灵活切换
|
||||
|
||||
---
|
||||
|
||||
**推荐流程**：
|
||||
1. 首次部署：使用 Gemini（免费额度充足）
|
||||
2. 生产环境：使用管理员后台配置，支持在线切换
|
||||
3. 高频使用：配置 Gemini 自定义 Base URL 使用 Key 轮训服务
|
||||
124
docs/CHINA_MIRROR_GUIDE.md
Normal file
124
docs/CHINA_MIRROR_GUIDE.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# 中国镜像加速指南
|
||||
|
||||
如果你在中国大陆，Docker 构建速度可能很慢。我们提供了使用国内镜像的可选 Dockerfile。
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 方法一：使用中国镜像版 Dockerfile（推荐）
|
||||
|
||||
```bash
|
||||
# 构建后端（使用中国镜像）
|
||||
cd backend
|
||||
docker build -f Dockerfile.china -t qquiz-backend .
|
||||
|
||||
# 构建前端（使用中国镜像）
|
||||
cd ../frontend
|
||||
docker build -f Dockerfile.china -t qquiz-frontend .
|
||||
|
||||
# 或者一次性构建所有服务
|
||||
docker-compose build
|
||||
```
|
||||
|
||||
### 方法二：临时使用 Docker Compose 覆盖
|
||||
|
||||
创建 `docker-compose.override.yml`（已在 .gitignore 中）：
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
backend:
|
||||
build:
|
||||
context: ./backend
|
||||
dockerfile: Dockerfile.china
|
||||
|
||||
frontend:
|
||||
build:
|
||||
context: ./frontend
|
||||
dockerfile: Dockerfile.china
|
||||
```
|
||||
|
||||
然后正常运行：
|
||||
```bash
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
### 方法三：配置 Docker Hub 镜像加速
|
||||
|
||||
编辑 Docker 配置文件：
|
||||
- **Windows**: Docker Desktop → Settings → Docker Engine
|
||||
- **Linux**: `/etc/docker/daemon.json`
|
||||
|
||||
添加以下内容：
|
||||
```json
|
||||
{
|
||||
"registry-mirrors": [
|
||||
"https://docker.mirrors.ustc.edu.cn",
|
||||
"https://hub-mirror.c.163.com",
|
||||
"https://mirror.baidubce.com"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
重启 Docker 服务。
|
||||
|
||||
## 镜像源说明
|
||||
|
||||
### Dockerfile.china 使用的镜像源：
|
||||
|
||||
- **apt-get**: 阿里云镜像 (mirrors.aliyun.com)
|
||||
- **pip**: 清华大学镜像 (pypi.tuna.tsinghua.edu.cn)
|
||||
- **npm**: 淘宝镜像 (registry.npmmirror.com)
|
||||
|
||||
### 其他可选镜像源：
|
||||
|
||||
**Python PyPI:**
|
||||
- 清华：https://pypi.tuna.tsinghua.edu.cn/simple
|
||||
- 阿里云：https://mirrors.aliyun.com/pypi/simple/
|
||||
- 中科大：https://pypi.mirrors.ustc.edu.cn/simple/
|
||||
|
||||
**Node.js npm:**
|
||||
- 淘宝：https://registry.npmmirror.com
|
||||
- 华为云：https://repo.huaweicloud.com/repository/npm/
|
||||
|
||||
**Debian/Ubuntu apt:**
|
||||
- 阿里云：mirrors.aliyun.com
|
||||
- 清华：mirrors.tuna.tsinghua.edu.cn
|
||||
- 中科大：mirrors.ustc.edu.cn
|
||||
|
||||
## 注意事项
|
||||
|
||||
⚠️ **不要提交 docker-compose.override.yml 到 Git**
|
||||
⚠️ **Dockerfile.china 仅供中国大陆用户使用**
|
||||
⚠️ **国际用户请使用默认的 Dockerfile**
|
||||
|
||||
## 速度对比
|
||||
|
||||
| 构建步骤 | 默认源 | 中国镜像 | 加速比 |
|
||||
|---------|--------|---------|--------|
|
||||
| apt-get update | 30-60s | 5-10s | 3-6x |
|
||||
| pip install | 3-5min | 30-60s | 3-5x |
|
||||
| npm install | 2-4min | 30-60s | 2-4x |
|
||||
| **总计** | **5-10min** | **1-3min** | **3-5x** |
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 如果镜像源失效
|
||||
|
||||
1. 尝试其他镜像源（见上方"其他可选镜像源"）
|
||||
2. 检查镜像源是否可访问：
|
||||
```bash
|
||||
# 测试 PyPI 镜像
|
||||
curl -I https://pypi.tuna.tsinghua.edu.cn/simple
|
||||
|
||||
# 测试 npm 镜像
|
||||
curl -I https://registry.npmmirror.com
|
||||
```
|
||||
|
||||
3. 如果所有镜像都不可用，使用默认的 Dockerfile
|
||||
|
||||
### 如果构建仍然很慢
|
||||
|
||||
1. 检查 Docker Desktop 内存分配（建议 ≥ 4GB）
|
||||
2. 清理 Docker 缓存：`docker system prune -a`
|
||||
3. 使用 BuildKit：`DOCKER_BUILDKIT=1 docker-compose build`
|
||||
@@ -1,376 +0,0 @@
|
||||
# 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
|
||||
@@ -1,199 +0,0 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
祝你成功！🎉
|
||||
@@ -1,214 +0,0 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
祝你推送成功！🚀
|
||||
@@ -1,234 +0,0 @@
|
||||
# 🚀 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。
|
||||
@@ -1,94 +0,0 @@
|
||||
# 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! 🚀
|
||||
@@ -1,64 +0,0 @@
|
||||
==========================================
|
||||
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步！
|
||||
==========================================
|
||||
Reference in New Issue
Block a user