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

## 新功能 - 实现管理后台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>
2026-02-20 20:10:14 +00:00 · 2025-12-01 19:24:12 +08:00
parent 0ea8e5aa1e
commit a01f3540c5
47 changed files with 1051 additions and 129 deletions
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -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