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

124
docs/CHINA_MIRROR_GUIDE.md Normal file
View 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`