mirror of
https://github.com/handsomezhuzhu/QQuiz.git
synced 2026-02-20 12:00:14 +00:00
handsomezhuzhu
a01f3540c5
## 新功能 - 实现管理后台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>
377 lines
6.9 KiB
Markdown
377 lines
6.9 KiB
Markdown
# 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
|