QQuiz/docs/MYSQL_SETUP.md

MySQL 安装与配置指南

QQuiz 使用 MySQL 8.0 作为数据库，你可以选择 Docker 部署或本地安装。

方式一：使用 Docker (推荐)

优点

• 无需手动安装 MySQL
• 自动配置和初始化
• 隔离环境，不影响系统

使用步骤

1. 安装 Docker Desktop

   • 下载地址：https://www.docker.com/products/docker-desktop/
   • 安装后启动 Docker Desktop

2. 运行启动脚本

   scripts\fix_and_start.bat
   

   选择 [1] Use Docker

3. 完成！

   • Docker 会自动下载 MySQL 镜像
   • 自动创建数据库和用户
   • 自动启动服务

---

方式二：本地安装 MySQL

下载 MySQL

1. 访问 MySQL 官网下载页面： https://dev.mysql.com/downloads/installer/

2. 选择 MySQL Installer for Windows

3. 下载 mysql-installer-community-8.0.x.x.msi

安装步骤

1. 运行安装程序

   • 双击下载的 .msi 文件

2. 选择安装类型

   • 选择 "Developer Default" 或 "Server only"
   • 点击 Next

3. 配置 MySQL Server

   • Config Type: Development Computer
   • Port: 3306 (默认)
   • Authentication Method: 选择 "Use Strong Password Encryption"

4. 设置 Root 密码

   • 输入并记住 root 用户的密码
   • 建议密码：root (开发环境)

5. Windows Service 配置

   • ✅ Configure MySQL Server as a Windows Service
   • Service Name: MySQL80
   • ✅ Start the MySQL Server at System Startup

6. 完成安装

   • 点击 Execute 开始安装
   • 等待安装完成
   • 点击 Finish

验证安装

打开命令提示符，运行：

mysql --version

应该显示：mysql Ver 8.0.x for Win64 on x86_64

配置 QQuiz 数据库

方式 A：使用脚本自动创建 (推荐)

运行：

scripts\fix_and_start.bat

选择 [2] Use Local MySQL

方式 B：手动创建

1. 打开 MySQL 命令行客户端：

   mysql -u root -p
   

2. 输入 root 密码

3. 创建数据库和用户：

   CREATE DATABASE qquiz_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'qquiz'@'localhost' IDENTIFIED BY 'qquiz_password';
   GRANT ALL PRIVILEGES ON qquiz_db.* TO 'qquiz'@'localhost';
   FLUSH PRIVILEGES;
   EXIT;
   

---

数据库配置说明

.env 文件配置

确保 .env 文件中的数据库连接字符串正确：

本地 MySQL:

DATABASE_URL=mysql+aiomysql://qquiz:qquiz_password@localhost:3306/qquiz_db

Docker MySQL:

DATABASE_URL=mysql+aiomysql://qquiz:qquiz_password@mysql:3306/qquiz_db

连接参数说明

• mysql+aiomysql:// - 使用 aiomysql 异步驱动
• qquiz - 数据库用户名
• qquiz_password - 数据库密码
• localhost 或 mysql - 数据库主机地址
• 3306 - MySQL 默认端口
• qquiz_db - 数据库名称

---

常见问题

1. 端口 3306 被占用

错误信息：

Error: Port 3306 is already in use

解决方案：

• 检查是否已经有 MySQL 运行：netstat -ano | findstr :3306
• 停止现有的 MySQL 服务
• 或修改 .env 中的端口号

2. 无法连接到 MySQL

错误信息：

Can't connect to MySQL server on 'localhost'

解决方案：

1. 检查 MySQL 服务是否运行

   • 按 Win+R，输入 services.msc
   • 查找 "MySQL80" 服务
   • 确认状态为 "正在运行"

2. 启动 MySQL 服务

   net start MySQL80
   

3. 检查防火墙设置

   • 确保防火墙允许 MySQL 端口 3306

3. 密码验证失败

错误信息：

Access denied for user 'qquiz'@'localhost'

解决方案：

重新创建用户并设置密码：

mysql -u root -p
DROP USER IF EXISTS 'qquiz'@'localhost';
CREATE USER 'qquiz'@'localhost' IDENTIFIED BY 'qquiz_password';
GRANT ALL PRIVILEGES ON qquiz_db.* TO 'qquiz'@'localhost';
FLUSH PRIVILEGES;

4. 字符集问题

解决方案：

确保数据库使用 UTF-8 字符集：

ALTER DATABASE qquiz_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

---

管理工具推荐

1. MySQL Workbench (官方)

• 下载：https://dev.mysql.com/downloads/workbench/
• 功能：可视化数据库管理、SQL 编辑器、备份还原

2. DBeaver (免费开源)

• 下载：https://dbeaver.io/download/
• 功能：多数据库支持、数据导入导出、ER 图

3. phpMyAdmin (Web 界面)

• 适合习惯 Web 界面的用户

---

数据库备份与恢复

备份数据库

mysqldump -u qquiz -p qquiz_db > backup.sql

恢复数据库

mysql -u qquiz -p qquiz_db < backup.sql

---

切换回 PostgreSQL

如果需要切换回 PostgreSQL：

1. 修改 requirements.txt：

   asyncpg==0.29.0  # 替换 aiomysql
   

2. 修改 .env：

   DATABASE_URL=postgresql+asyncpg://qquiz:qquiz_password@localhost:5432/qquiz_db
   

3. 修改 docker-compose.yml：

   • 将 mysql 服务改回 postgres

4. 重新安装依赖：

   pip install -r requirements.txt
   

---

技术支持

如遇到其他问题，请：

1. 检查 MySQL 错误日志
2. 确认防火墙和网络配置
3. 查看项目 issues: https://github.com/handsomezhuzhu/QQuiz/issues