mirror of
https://github.com/handsomezhuzhu/QQuiz.git
synced 2026-02-20 12:00:14 +00:00
Document secure secrets and prune unused assets
This commit is contained in:
Simon
@@ -1,201 +0,0 @@
|
||||
# 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 轮训服务
|
||||
@@ -1,533 +0,0 @@
|
||||
# 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**: 提交问题报告
|
||||
|
||||
---
|
||||
|
||||
祝你部署顺利！🎉
|
||||
Reference in New Issue
Block a user