library-picturebook-activity/backend/docs/DATABASE_SETUP.md

数据库配置指南

1. 创建数据库

首先需要在 MySQL 中创建数据库：

CREATE DATABASE db_competition_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. 配置环境变量

方式一：复制示例文件

cd backend
cp .env.example .env

方式二：手动创建 .env 文件

在 backend 目录下创建 .env 文件，内容如下：

DATABASE_URL="mysql://root:password@localhost:3306/competition_management?schema=public"
JWT_SECRET="your-secret-key-change-in-production"
PORT=3001
NODE_ENV=development

3. 配置说明

DATABASE_URL 格式

mysql://用户名:密码@主机:端口/数据库名?参数

示例：

• 本地 MySQL，默认端口：

  DATABASE_URL="mysql://root:password@localhost:3306/competition_management?schema=public"
  

• 远程 MySQL：

  DATABASE_URL="mysql://user:password@192.168.1.100:3306/competition_management?schema=public"
  

• 使用 SSL：

  DATABASE_URL="mysql://user:password@localhost:3306/competition_management?schema=public&sslmode=require"
  

• 包含特殊字符的密码（需要 URL 编码）：

  DATABASE_URL="mysql://user:p%40ssw0rd@localhost:3306/competition_management?schema=public"
  

JWT_SECRET

用于 JWT token 签名的密钥，生产环境必须使用强随机字符串。

生成方式：

# 使用 Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# 或使用 openssl
openssl rand -hex 32

4. 初始化数据库

配置好 .env 文件后，执行以下命令初始化数据库：

# 生成 Prisma Client
pnpm prisma:generate

# 运行数据库迁移（创建表结构）
pnpm prisma:migrate

# 或使用开发模式（会提示输入迁移名称）
pnpm prisma:migrate dev

5. 验证连接

方式一：使用 Prisma Studio

pnpm prisma:studio

这会打开一个可视化界面，可以在浏览器中查看和管理数据库。

方式二：测试连接

启动后端服务：

pnpm start:dev

如果连接成功，服务会正常启动；如果失败，会显示具体的错误信息。

6. 常见问题

问题 1: 连接被拒绝

错误信息： Can't reach database server

解决方案：

• 检查 MySQL 服务是否启动
• 检查主机和端口是否正确
• 检查防火墙设置

问题 2: 认证失败

错误信息： Access denied for user

解决方案：

• 检查用户名和密码是否正确
• 确认用户有访问该数据库的权限
• 如果密码包含特殊字符，需要进行 URL 编码

问题 3: 数据库不存在

错误信息： Unknown database

解决方案：

• 先创建数据库（见步骤 1）
• 检查数据库名称是否正确

问题 4: 字符集问题

解决方案： 创建数据库时指定字符集：

CREATE DATABASE competition_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

7. 生产环境配置

生产环境建议：

1. 使用环境变量管理工具（如 AWS Secrets Manager、Azure Key Vault）
2. 使用连接池（Prisma 默认已配置）
3. 启用 SSL 连接
4. 定期备份数据库
5. 使用强密码和 JWT_SECRET

8. 数据库迁移

创建新迁移

pnpm prisma:migrate dev --name migration_name

应用迁移（生产环境）

pnpm prisma:migrate deploy

重置数据库（开发环境）

pnpm prisma:migrate reset

注意： 这会删除所有数据，仅用于开发环境！