# temp_email

**Repository Path**: qq910183766/temp_email

## Basic Information

- **Project Name**: temp_email
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-25
- **Last Updated**: 2026-02-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 临时邮箱系统

一个基于 Java Spring Boot 和 Vue 3 的临时邮箱服务系统，为用户提供临时邮箱地址生成、邮件接收和验证码自动提取功能。

## 项目简介

临时邮箱系统是一个 Web 应用程序，旨在为用户提供隐私保护的临时邮箱服务。用户可以快速生成临时邮箱地址，接收邮件并自动提取验证码，避免使用真实邮箱地址导致的垃圾邮件和隐私泄露问题。

系统采用前后端分离架构，后端使用 Spring Boot 提供 RESTful API，前端使用 Vue 3 构建单页应用，通过集成 QQ 邮箱服务实现邮件接收功能。

## 功能特性

### 核心功能

- **用户注册与登录**：支持用户注册、登录，使用 JWT 进行身份认证
- **临时邮箱生成**：一键生成随机临时邮箱地址（8-12位字母数字混合前缀）
- **邮件自动接收**：定时从 QQ 邮箱服务器接收发送到临时邮箱的邮件（每30秒检查一次）
- **验证码自动提取**：智能识别并提取邮件中的验证码（支持多种格式）
- **邮件管理**：查看邮件列表、邮件详情，一键复制验证码
- **邮箱管理**：查看、删除临时邮箱，添加备注
- **分页与搜索**：邮箱列表和邮件列表支持分页显示和关键词搜索
- **未读标识**：未读邮件显示红色徽章，查看后自动标记为已读
- **移动端适配**：完整的响应式设计，支持手机、平板等移动设备访问

### 管理功能

- **角色权限管理**：基于 RBAC 的权限控制，支持普通用户和管理员角色
- **邮箱配置管理**：管理员可配置邮箱后缀和 QQ 邮箱授权码
- **用户权限隔离**：严格的权限隔离机制，确保用户只能访问自己的资源

### 安全特性

- **密码加密存储**：使用 BCrypt 算法加密存储用户密码
- **JWT 认证**：无状态身份认证，Token 有效期 24 小时
- **权限控制**：多层权限检查，防止横向越权攻击
- **敏感信息加密**：QQ 邮箱授权码使用 AES 加密存储
- **输入验证**：前后端双重输入验证，防止 SQL 注入和 XSS 攻击

## 技术栈

### 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                         用户浏览器                            │
│                    (Vue 3 + TypeScript)                      │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP/HTTPS
                     │ RESTful API
┌────────────────────▼────────────────────────────────────────┐
│                    Spring Boot 后端                          │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Controller Layer (REST API)                         │  │
│  └────────────┬─────────────────────────────────────────┘  │
│               │                                              │
│  ┌────────────▼─────────────────────────────────────────┐  │
│  │  Service Layer (业务逻辑)                             │  │
│  │  - AuthService (认证)                                 │  │
│  │  - EmailService (邮箱管理)                            │  │
│  │  - MailService (邮件收发)                             │  │
│  │  - ConfigService (配置管理)                           │  │
│  └────────────┬─────────────────────────────────────────┘  │
│               │                                              │
│  ┌────────────▼─────────────────────────────────────────┐  │
│  │  Repository Layer (数据访问)                          │  │
│  │  - Spring Data JPA                                    │  │
│  └────────────┬─────────────────────────────────────────┘  │
└───────────────┼──────────────────────────────────────────────┘
                │
┌───────────────▼──────────────────────────────────────────────┐
│                      MySQL 数据库                             │
│  - users (用户表)                                             │
│  - roles (角色表)                                             │
│  - email_addresses (邮箱表)                                   │
│  - email_messages (邮件表)                                    │
│  - email_config (配置表)                                      │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                    QQ 邮箱服务器                              │
│  - IMAP (imap.qq.com:993) - 接收邮件                         │
│  - SMTP (smtp.qq.com:465) - 发送邮件                         │
└──────────────────────────────────────────────────────────────┘
```

### 后端技术

- **框架**：Spring Boot 3.2+
- **语言**：Java 17
- **数据库**：MySQL 8.0+
- **ORM**：Spring Data JPA / Hibernate
- **安全**：Spring Security + JWT
- **邮件**：Jakarta Mail API (JavaMail)
- **构建工具**：Maven 3.8+
- **其他**：Lombok, BCrypt, HikariCP

### 前端技术

- **框架**：Vue 3.4+
- **语言**：TypeScript 5.x
- **构建工具**：Vite 5.x
- **路由**：Vue Router 4.x
- **状态管理**：Pinia 2.x
- **HTTP 客户端**：Axios 1.6+
- **UI 组件库**：Element Plus 2.x
- **工具库**：Day.js, Lodash-es

### 外部服务

- **邮件服务**：QQ 邮箱 (IMAP/SMTP)
  - IMAP 服务器：imap.qq.com:993 (SSL)
  - SMTP 服务器：smtp.qq.com:465 (SSL)

### 技术选型说明

**后端技术选型理由**
- **Spring Boot**：快速开发、约定优于配置、丰富的生态系统
- **Spring Security + JWT**：成熟的安全框架，无状态认证适合前后端分离
- **Spring Data JPA**：简化数据访问层开发，支持多种数据库
- **MySQL**：稳定可靠的关系型数据库，适合结构化数据存储
- **Jakarta Mail**：Java 标准邮件 API，支持 IMAP/SMTP 协议

**前端技术选型理由**
- **Vue 3**：渐进式框架，组合式 API，性能优秀，学习曲线平缓
- **TypeScript**：类型安全，提高代码质量和可维护性
- **Vite**：快速的构建工具，开发体验好，热更新速度快
- **Element Plus**：成熟的 Vue 3 UI 组件库，组件丰富，文档完善
- **Pinia**：Vue 3 官方推荐的状态管理库，API 简洁直观

## 环境要求

### 必需环境

- **JDK**：17 或更高版本
- **Maven**：3.8 或更高版本
- **Node.js**：18.x 或更高版本
- **npm**：9.x 或更高版本
- **MySQL**：8.0 或更高版本

### 推荐配置

- **操作系统**：Windows 10+, Ubuntu 20.04+, CentOS 7+
- **内存**：至少 4GB RAM
- **磁盘空间**：至少 2GB 可用空间

## 快速开始

### 使用一键部署脚本（推荐）

#### Windows 环境

1. 确保已安装所有必需环境（JDK, Maven, Node.js, MySQL）
2. 打开命令提示符，进入项目根目录
3. 运行部署脚本：

```cmd
deploy.bat
```

4. 按照提示输入数据库配置信息
5. 等待自动构建和启动完成
6. 访问 http://localhost:5173 开始使用

#### Linux 环境

1. 确保已安装所有必需环境（JDK, Maven, Node.js, MySQL）
2. 打开终端，进入项目根目录
3. 添加执行权限并运行部署脚本：

```bash
chmod +x deploy.sh
./deploy.sh
```

4. 按照提示输入数据库配置信息
5. 等待自动构建和启动完成
6. 访问 http://localhost:5173 开始使用

### 停止服务

#### Windows

```cmd
stop.bat
```

#### Linux

```bash
./stop.sh
```

## 手动部署指南

如果一键部署脚本无法使用，可以按照以下步骤手动部署。

### 1. 准备数据库

创建数据库并执行初始化脚本：

```bash
# 登录 MySQL
mysql -u root -p

# 创建数据库
CREATE DATABASE temp_email_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 使用数据库
USE temp_email_db;

# 执行初始化脚本
SOURCE database/init.sql;

# 退出
EXIT;
```

### 2. 配置后端

编辑 `backend/src/main/resources/application.properties`：

```properties
# 数据库配置
spring.datasource.url=jdbc:mysql://localhost:3306/temp_email_db?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8
spring.datasource.username=root
spring.datasource.password=your_password

# JPA 配置
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=false

# 服务器端口
server.port=8080

# JWT 配置
jwt.secret=your-secret-key-change-this-in-production-min-256-bits
jwt.expiration=86400000

# 邮件配置
spring.mail.host=smtp.qq.com
spring.mail.port=465
spring.mail.protocol=smtps
```

### 3. 构建并启动后端

```bash
# 进入后端目录
cd backend

# 构建项目
mvn clean package -DskipTests

# 启动服务
java -jar target/temp-email-backend.jar

# 或者在开发模式下运行
mvn spring-boot:run
```

后端服务将在 http://localhost:8080 启动。

### 4. 配置前端

创建 `frontend/.env.production` 文件：

```env
VITE_API_BASE_URL=http://localhost:8080/api
```

### 5. 构建并启动前端

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 或构建生产版本
npm run build

# 使用 serve 启动生产版本
npm install -g serve
serve -s dist -l 5173
```

前端服务将在 http://localhost:5173 启动。

## 配置说明

### 数据库配置

在 `application.properties` 中配置数据库连接：

```properties
spring.datasource.url=jdbc:mysql://[主机]:[端口]/[数据库名]
spring.datasource.username=[用户名]
spring.datasource.password=[密码]
```

### QQ 邮箱配置

系统需要配置 QQ 邮箱来接收邮件：

1. **开启 IMAP/SMTP 服务**
   - 登录 QQ 邮箱网页版
   - 进入"设置" -> "账户"
   - 找到"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务"
   - 开启"IMAP/SMTP服务"
   - 生成授权码（不是 QQ 密码）

2. **在系统中配置**
   - 使用管理员账号登录系统
   - 进入"配置管理"页面
   - 输入 QQ 邮箱地址和授权码
   - 点击"测试连接"验证配置
   - 保存配置

### 邮箱后缀配置

管理员可以配置临时邮箱的后缀：

1. 登录管理员账号
2. 进入"配置管理"页面
3. 在"邮箱后缀配置"中输入后缀（如 @example.com）
4. 保存配置

后续生成的临时邮箱将使用新的后缀。

### JWT 配置

在 `application.properties` 中配置 JWT：

```properties
# JWT 密钥（生产环境请使用强密钥）
jwt.secret=your-secret-key-min-256-bits

# Token 有效期（毫秒，默认 24 小时）
jwt.expiration=86400000
```

**安全建议**：
- 生产环境使用至少 256 位的随机密钥
- 密钥应存储在环境变量中，不要提交到代码库
- 定期更换密钥

### 环境变量配置（推荐）

生产环境建议使用环境变量管理敏感配置：

```bash
# Linux/Mac
export DB_PASSWORD=your_password
export JWT_SECRET=your_secret_key

# Windows
set DB_PASSWORD=your_password
set JWT_SECRET=your_secret_key
```

在 `application.properties` 中引用：

```properties
spring.datasource.password=${DB_PASSWORD}
jwt.secret=${JWT_SECRET}
```

## 默认管理员账号

系统初始化后会自动创建默认管理员账号：

- **用户名**：`admin`
- **密码**：`admin123`

**重要提示**：
- 首次登录后请立即修改默认密码
- 生产环境部署前务必更改默认账号信息
- 建议创建新的管理员账号后删除默认账号

## 使用指南

### 普通用户操作

1. **注册账号**
   - 访问系统首页
   - 点击"注册"
   - 填写用户名、密码和邮箱
   - 提交注册

2. **登录系统**
   - 输入用户名和密码
   - 点击"登录"

3. **生成临时邮箱**
   - 登录后进入"邮箱列表"页面
   - 点击"生成邮箱"按钮
   - 系统自动生成临时邮箱地址

4. **查看邮件**
   - 点击邮箱卡片进入邮箱详情
   - 查看收到的邮件列表
   - 点击邮件查看详情
   - 如果邮件包含验证码，会自动提取并高亮显示

5. **复制验证码**
   - 在邮件详情页面
   - 点击验证码旁的"复制"按钮
   - 验证码已复制到剪贴板

6. **删除邮箱**
   - 在邮箱列表页面
   - 点击邮箱卡片上的"删除"按钮
   - 确认删除（邮箱及其所有邮件将被删除）

### 管理员操作

1. **配置邮箱后缀**
   - 使用管理员账号登录
   - 进入"配置管理"页面
   - 在"邮箱后缀配置"中输入后缀
   - 点击"保存"

2. **配置 QQ 邮箱**
   - 进入"配置管理"页面
   - 在"QQ 邮箱配置"中输入邮箱地址和授权码
   - 点击"测试连接"验证配置
   - 点击"保存"

3. **管理用户角色**
   - 进入"角色管理"页面
   - 查看、创建、编辑角色
   - 为用户分配角色

## 常见问题解答（FAQ）

### 1. 部署相关

**Q: 部署脚本提示找不到 JDK/Maven/Node.js？**

A: 请确保已正确安装并配置环境变量：
- JDK: 设置 JAVA_HOME 环境变量，并添加 `%JAVA_HOME%\bin` 到 PATH
- Maven: 设置 MAVEN_HOME 并添加 `%MAVEN_HOME%\bin` 到 PATH
- Node.js: 安装后会自动添加到 PATH，可运行 `node -v` 验证

**Q: 数据库连接失败？**

A: 检查以下几点：
- MySQL 服务是否正在运行（Windows: 服务管理器，Linux: `systemctl status mysql`）
- 数据库用户名和密码是否正确
- 数据库 `temp_email_db` 是否已创建
- 防火墙是否允许 3306 端口
- MySQL 是否允许远程连接（如果数据库在其他服务器）

**Q: 后端启动失败，提示端口被占用？**

A: 8080 端口已被其他程序占用，解决方法：
- Windows: `netstat -ano | findstr :8080` 查找占用进程，然后结束进程
- Linux: `lsof -i :8080` 查找占用进程，`kill -9 PID` 结束进程
- 或修改 `application.properties` 中的 `server.port` 配置为其他端口

**Q: 前端启动失败，提示依赖安装错误？**

A: 尝试以下方法：
```bash
# 清除缓存
npm cache clean --force

# 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json

# 重新安装
npm install

# 如果还是失败，尝试使用 cnpm 或 yarn
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install
```

### 2. 邮件接收相关

**Q: 收不到邮件？**

A: 请按以下步骤排查：

1. **检查 QQ 邮箱配置**
   - 确认已开启 IMAP/SMTP 服务
   - 确认授权码正确（不是 QQ 密码）
   - 在系统配置页面点击"测试连接"

2. **检查系统配置**
   - 登录管理员账号
   - 进入"配置管理"页面
   - 确认 QQ 邮箱地址和授权码已保存

3. **检查后端日志**
   - 查看 `backend/logs/temp-email-system.log-mail.log`
   - 查找错误信息，如认证失败、连接超时等

4. **检查邮箱后缀**
   - 确认临时邮箱后缀与 QQ 邮箱配置的转发规则一致
   - 例如：临时邮箱 `abc123@example.com`，需要在 QQ 邮箱设置转发规则

5. **手动测试**
   - 向临时邮箱发送测试邮件
   - 等待 30 秒（系统每 30 秒检查一次）
   - 刷新邮件列表

**Q: 邮件接收有延迟？**

A: 系统默认每 30 秒检查一次新邮件，可能会有最多 30 秒的延迟。这是正常现象。

如需调整检查频率，修改 `MailScheduler.java` 中的 `@Scheduled` 注解：
```java
@Scheduled(fixedDelay = 30000)  // 改为 10000 表示 10 秒
```

**Q: 验证码提取不准确？**

A: 系统支持以下验证码格式：
- 中文：`验证码：123456`、`验证码: 123456`、`验证码是123456`
- 英文：`verification code: ABC123`、`code: 123456`
- 纯数字：4-8 位连续数字（如 `123456`）

如果邮件中的验证码格式特殊，可能无法自动提取。可以：
1. 查看完整邮件内容手动复制
2. 修改 `VerificationCodeExtractor.java` 添加新的正则表达式

**Q: QQ 邮箱授权码在哪里获取？**

A: 获取步骤：
1. 登录 QQ 邮箱网页版（mail.qq.com）
2. 点击"设置" -> "账户"
3. 找到"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务"
4. 开启"IMAP/SMTP服务"
5. 按提示发送短信验证
6. 获取授权码（16位字符，如 `abcdefghijklmnop`）
7. 保存授权码，在系统配置中使用

### 3. 使用相关

**Q: 忘记密码怎么办？**

A: 当前版本暂不支持密码找回功能。解决方法：
1. 联系管理员重置密码
2. 或直接在数据库中修改密码（需要使用 BCrypt 加密）

生成 BCrypt 密码的方法：
```java
String password = "new_password";
String encoded = new BCryptPasswordEncoder().encode(password);
System.out.println(encoded);
```

**Q: 可以修改临时邮箱地址吗？**

A: 临时邮箱地址由系统随机生成，不支持自定义。如果不满意，可以：
1. 删除当前邮箱
2. 重新生成新的邮箱

**Q: 临时邮箱会过期吗？**

A: 当前版本的临时邮箱不会自动过期，除非：
1. 用户手动删除
2. 管理员在数据库中删除

如需实现自动过期功能，可以：
1. 在 `email_addresses` 表添加 `expired_at` 字段
2. 创建定时任务定期清理过期邮箱

**Q: 可以同时生成多个临时邮箱吗？**

A: 可以。每个用户可以生成多个临时邮箱，没有数量限制。

**Q: 如何给邮箱添加备注？**

A: 在邮箱列表页面：
1. 找到要添加备注的邮箱卡片
2. 点击"添加备注"按钮
3. 输入备注内容（最多 200 字符）
4. 按回车或点击外部保存

**Q: 如何搜索邮箱？**

A: 在邮箱列表页面：
1. 在搜索框中输入关键词
2. 可以搜索邮箱地址或备注内容
3. 按回车或点击"搜索"按钮
4. 点击"清空"按钮恢复显示所有邮箱

### 4. 安全相关

**Q: 系统安全吗？**

A: 系统采用多重安全措施：
- **密码安全**：使用 BCrypt 加密存储，不可逆
- **认证安全**：JWT Token 认证，有效期 24 小时
- **权限控制**：基于 RBAC 的权限系统，严格的资源隔离
- **数据加密**：敏感配置（如 QQ 授权码）使用 AES-256 加密
- **输入验证**：前后端双重验证，防止 SQL 注入和 XSS 攻击
- **HTTPS**：生产环境建议使用 HTTPS 加密传输

**Q: 其他用户能看到我的邮件吗？**

A: 不能。系统实现了严格的权限隔离：
- 每个用户只能访问自己创建的邮箱
- API 层面验证用户身份和资源所有权
- 数据库查询自动过滤其他用户的数据

**Q: 管理员能看到我的邮件吗？**

A: 管理员通过系统界面无法查看用户邮件。但管理员可以：
- 访问数据库直接查询（需要数据库权限）
- 查看系统日志（可能包含部分邮件信息）

**建议**：不要在临时邮箱中接收敏感信息（如银行密码、身份证号等）

**Q: JWT Token 泄露了怎么办？**

A: 如果怀疑 Token 泄露：
1. 立即退出登录（Token 会失效）
2. 重新登录获取新 Token
3. 修改密码
4. 检查是否有异常登录记录

预防措施：
- 不要在公共场所使用系统
- 不要将 Token 分享给他人
- 定期更换密码
- 使用 HTTPS 访问系统

**Q: 如何修改 JWT 密钥？**

A: 修改 `application.properties`：
```properties
jwt.secret=your-new-secret-key-min-256-bits
```

**重要**：
- 密钥至少 256 位（32 字符）
- 使用随机字符串，不要使用简单密码
- 修改密钥后，所有用户需要重新登录

### 5. 性能相关

**Q: 系统支持多少并发用户？**

A: 系统设计支持至少 1000 个并发用户。实际性能取决于：
- 服务器配置（CPU、内存、带宽）
- 数据库性能
- 邮件接收频率

优化建议：
- 使用 Redis 缓存热点数据
- 数据库添加索引
- 使用 Nginx 反向代理和负载均衡
- 邮件接收使用消息队列异步处理

**Q: 数据库会不会越来越大？**

A: 会的。随着使用时间增长，邮件数据会不断增加。建议：

1. **定期清理**
   - 删除 30 天前的已读邮件
   - 删除 90 天前的所有邮件
   - 删除已删除邮箱的邮件

2. **自动清理脚本**
   ```sql
   -- 删除 30 天前的已读邮件
   DELETE FROM email_messages 
   WHERE is_read = true 
   AND received_at < DATE_SUB(NOW(), INTERVAL 30 DAY);
   
   -- 删除 90 天前的所有邮件
   DELETE FROM email_messages 
   WHERE received_at < DATE_SUB(NOW(), INTERVAL 90 DAY);
   ```

3. **数据归档**
   - 将历史数据导出到归档表
   - 使用分区表提高查询性能

**Q: 如何提高系统性能？**

A: 优化建议：

1. **数据库优化**
   ```sql
   -- 添加索引
   CREATE INDEX idx_email_user ON email_addresses(user_id);
   CREATE INDEX idx_message_email ON email_messages(email_address_id);
   CREATE INDEX idx_message_time ON email_messages(received_at);
   ```

2. **应用优化**
   - 启用 Spring Boot 缓存
   - 使用连接池（HikariCP 已配置）
   - 减少 N+1 查询问题

3. **前端优化**
   - 启用 Gzip 压缩
   - 使用 CDN 加速静态资源
   - 图片懒加载

4. **服务器优化**
   - 使用 Nginx 反向代理
   - 启用 HTTP/2
   - 配置缓存策略

### 6. 部署相关

**Q: 如何部署到生产环境？**

A: 生产环境部署步骤：

1. **准备服务器**
   - 推荐配置：2核4G内存，40G硬盘
   - 安装 JDK 17、MySQL 8.0、Nginx

2. **配置数据库**
   ```bash
   # 创建数据库
   mysql -u root -p
   CREATE DATABASE temp_email_db;
   SOURCE /path/to/init.sql;
   ```

3. **配置后端**
   - 修改 `application.properties` 为生产配置
   - 使用环境变量管理敏感信息
   - 关闭 SQL 日志：`spring.jpa.show-sql=false`

4. **构建后端**
   ```bash
   cd backend
   mvn clean package -DskipTests
   ```

5. **配置前端**
   - 修改 `.env.production` 中的 API 地址
   - 构建生产版本：`npm run build`

6. **配置 Nginx**
   ```nginx
   server {
       listen 80;
       server_name your-domain.com;
       
       # 前端
       location / {
           root /path/to/frontend/dist;
           try_files $uri $uri/ /index.html;
       }
       
       # 后端 API
       location /api {
           proxy_pass http://localhost:8080;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }
   ```

7. **启动服务**
   ```bash
   # 后端（使用 systemd 或 supervisor 管理）
   java -jar backend/target/temp-email-backend.jar
   
   # 或使用 nohup
   nohup java -jar backend/target/temp-email-backend.jar > app.log 2>&1 &
   ```

8. **配置 HTTPS**
   - 使用 Let's Encrypt 免费证书
   - 或购买商业 SSL 证书

**Q: 如何配置开机自启动？**

A: Linux 使用 systemd：

1. 创建服务文件 `/etc/systemd/system/temp-email.service`：
   ```ini
   [Unit]
   Description=Temp Email System
   After=network.target mysql.service
   
   [Service]
   Type=simple
   User=your-user
   WorkingDirectory=/path/to/backend
   ExecStart=/usr/bin/java -jar /path/to/backend/target/temp-email-backend.jar
   Restart=on-failure
   
   [Install]
   WantedBy=multi-user.target
   ```

2. 启用服务：
   ```bash
   sudo systemctl daemon-reload
   sudo systemctl enable temp-email
   sudo systemctl start temp-email
   sudo systemctl status temp-email
   ```

**Q: 如何备份数据？**

A: 定期备份数据库：

```bash
# 备份
mysqldump -u root -p temp_email_db > backup_$(date +%Y%m%d).sql

# 恢复
mysql -u root -p temp_email_db < backup_20260225.sql

# 自动备份脚本（添加到 crontab）
0 2 * * * /path/to/backup.sh
```

## API 文档

详细的 API 文档请参考 `docs/API.md` 文件。

主要 API 端点：

### 认证相关
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录
- `GET /api/auth/current` - 获取当前用户信息
- `POST /api/auth/logout` - 用户注销

### 邮箱管理
- `POST /api/emails/generate` - 生成临时邮箱
- `GET /api/emails` - 获取用户邮箱列表
- `GET /api/emails/{id}` - 获取邮箱详情
- `DELETE /api/emails/{id}` - 删除邮箱
- `GET /api/emails/{id}/messages` - 获取邮箱的邮件列表

### 配置管理（管理员）
- `GET /api/config` - 获取系统配置
- `PUT /api/config/email-suffix` - 更新邮箱后缀
- `PUT /api/config/qq-auth-code` - 更新 QQ 邮箱授权码
- `POST /api/config/test-connection` - 测试邮箱连接

## 项目结构

```
temp-email-system/
├── backend/                    # 后端项目
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/
│   │   │   │   └── com/tempemail/
│   │   │   │       ├── config/         # 配置类
│   │   │   │       │   ├── CorsConfig.java           # 跨域配置
│   │   │   │       │   ├── SecurityConfig.java       # 安全配置
│   │   │   │       │   ├── DataInitializer.java      # 数据初始化
│   │   │   │       │   └── ...
│   │   │   │       ├── controller/     # 控制器
│   │   │   │       │   ├── AuthController.java       # 认证接口
│   │   │   │       │   ├── EmailController.java      # 邮箱接口
│   │   │   │       │   └── ConfigController.java     # 配置接口
│   │   │   │       ├── dto/            # 数据传输对象
│   │   │   │       │   ├── LoginRequest.java
│   │   │   │       │   ├── RegisterRequest.java
│   │   │   │       │   └── EmailAddressDTO.java
│   │   │   │       ├── entity/         # 实体类
│   │   │   │       │   ├── User.java               # 用户实体
│   │   │   │       │   ├── Role.java               # 角色实体
│   │   │   │       │   ├── EmailAddress.java       # 邮箱实体
│   │   │   │       │   ├── EmailMessage.java       # 邮件实体
│   │   │   │       │   └── EmailConfig.java        # 配置实体
│   │   │   │       ├── exception/      # 异常处理
│   │   │   │       │   ├── GlobalExceptionHandler.java
│   │   │   │       │   └── ResourceNotFoundException.java
│   │   │   │       ├── filter/         # 过滤器
│   │   │   │       │   └── JwtAuthenticationFilter.java
│   │   │   │       ├── repository/     # 数据访问层
│   │   │   │       │   ├── UserRepository.java
│   │   │   │       │   ├── EmailAddressRepository.java
│   │   │   │       │   └── EmailMessageRepository.java
│   │   │   │       ├── scheduler/      # 定时任务
│   │   │   │       │   └── MailScheduler.java      # 邮件定时接收
│   │   │   │       ├── service/        # 服务层
│   │   │   │       │   ├── AuthService.java        # 认证服务
│   │   │   │       │   ├── EmailService.java       # 邮箱服务
│   │   │   │       │   ├── MailService.java        # 邮件服务
│   │   │   │       │   └── ConfigService.java      # 配置服务
│   │   │   │       ├── util/           # 工具类
│   │   │   │       │   ├── JwtTokenProvider.java   # JWT工具
│   │   │   │       │   ├── EmailPrefixGenerator.java
│   │   │   │       │   └── VerificationCodeExtractor.java
│   │   │   │       └── validation/     # 验证器
│   │   │   │           ├── EmailValidator.java
│   │   │   │           └── PasswordStrengthValidator.java
│   │   │   └── resources/
│   │   │       ├── application.properties          # 应用配置
│   │   │       ├── logback-spring.xml             # 日志配置
│   │   │       └── ValidationMessages.properties   # 验证消息
│   │   └── test/                       # 测试代码
│   │       └── java/com/tempemail/
│   │           ├── service/
│   │           └── controller/
│   ├── logs/                           # 日志文件目录（运行时生成）
│   ├── pom.xml                         # Maven配置
│   └── .gitignore
├── frontend/                   # 前端项目
│   ├── src/
│   │   ├── api/                # API 服务
│   │   │   ├── auth.ts                 # 认证API
│   │   │   ├── email.ts                # 邮箱API
│   │   │   └── config.ts               # 配置API
│   │   ├── components/         # 组件
│   │   │   ├── AppHeader.vue           # 头部组件
│   │   │   ├── EmailCard.vue           # 邮箱卡片
│   │   │   ├── MessageList.vue         # 邮件列表
│   │   │   ├── MessageDetail.vue       # 邮件详情
│   │   │   └── GenerateEmailButton.vue # 生成邮箱按钮
│   │   ├── router/             # 路由配置
│   │   │   └── index.ts
│   │   ├── stores/             # 状态管理
│   │   │   ├── auth.ts                 # 认证状态
│   │   │   └── email.ts                # 邮箱状态
│   │   ├── types/              # TypeScript 类型
│   │   │   └── api.ts
│   │   ├── utils/              # 工具函数
│   │   │   ├── request.ts              # HTTP请求封装
│   │   │   └── auth.ts                 # 认证工具
│   │   ├── views/              # 页面组件
│   │   │   ├── LoginView.vue           # 登录页
│   │   │   ├── RegisterView.vue        # 注册页
│   │   │   ├── EmailListView.vue       # 邮箱列表页
│   │   │   ├── EmailDetailView.vue     # 邮箱详情页
│   │   │   └── ConfigView.vue          # 配置管理页
│   │   ├── App.vue
│   │   └── main.ts
│   ├── public/                 # 静态资源
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── .gitignore
├── database/                   # 数据库脚本
│   ├── init.sql                        # 初始化脚本
│   └── migration_add_remark.sql        # 迁移脚本
├── docs/                       # 文档目录
│   ├── API.md                          # API文档
│   └── CODE_STYLE.md                   # 代码注释规范
├── deploy.bat                  # Windows 部署脚本
├── deploy.sh                   # Linux 部署脚本
├── stop.bat                    # Windows 停止脚本
├── stop.sh                     # Linux 停止脚本
├── .gitignore                  # Git忽略文件
├── CHANGELOG.md                # 更新日志
├── LICENSE                     # 许可证
└── README.md                   # 本文件
```

## 开发指南

### 后端开发

1. **导入项目**
   - 使用 IntelliJ IDEA 打开 backend 目录
   - IDE 会自动识别为 Maven 项目并下载依赖

2. **配置数据库**
   - 创建数据库并执行 `database/init.sql`
   - 修改 `application.properties` 中的数据库配置

3. **运行项目**
   - 方式1：直接运行 `TempEmailApplication.java` 主类
   - 方式2：使用 Maven 命令 `mvn spring-boot:run`
   - 方式3：打包后运行 `java -jar target/temp-email-backend.jar`

4. **访问接口**
   - API 基础路径：http://localhost:8080/api
   - Swagger 文档（如已配置）：http://localhost:8080/swagger-ui.html

5. **调试技巧**
   - 查看日志：`backend/logs/` 目录
   - 开启 SQL 日志：`spring.jpa.show-sql=true`
   - 使用 Postman 或 Apifox 测试 API

### 前端开发

1. **安装依赖**
   ```bash
   cd frontend
   npm install
   ```

2. **配置环境**
   - 开发环境：创建 `.env.development` 文件
   ```env
   VITE_API_BASE_URL=http://localhost:8080/api
   ```
   - 生产环境：创建 `.env.production` 文件
   ```env
   VITE_API_BASE_URL=https://your-domain.com/api
   ```

3. **启动开发服务器**
   ```bash
   npm run dev
   ```
   访问 http://localhost:5173

4. **构建生产版本**
   ```bash
   npm run build
   ```
   构建产物在 `dist/` 目录

5. **代码检查和格式化**
   ```bash
   npm run lint        # 代码检查
   npm run format      # 代码格式化
   ```

### 开发规范

**后端代码规范**
- 遵循 Java 编码规范（Google Java Style Guide）
- 使用 Lombok 简化代码
- 所有 public 方法添加 JavaDoc 注释（中文）
- Service 层方法添加事务注解 `@Transactional`
- 异常统一使用 `GlobalExceptionHandler` 处理
- 敏感信息不要硬编码，使用配置文件或环境变量

**前端代码规范**
- 遵循 Vue 3 和 TypeScript 编码规范
- 组件命名使用 PascalCase（如 `EmailCard.vue`）
- 使用组合式 API（Composition API）
- 所有 API 调用统一在 `api/` 目录管理
- 使用 TypeScript 类型定义，避免使用 `any`
- CSS 使用 scoped 避免样式污染
- 函数和接口添加 JSDoc 注释（中文）

**注释规范**
- 统一使用中文注释
- 类、方法、函数必须添加文档注释
- 复杂逻辑添加行内注释说明
- 配置文件添加详细的中文注释
- 详见 [代码注释规范](docs/CODE_STYLE.md)

**Git 提交规范**
- feat: 新功能
- fix: 修复 bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 重构代码
- test: 测试相关
- chore: 构建/工具链相关

示例：
```
feat: 添加邮箱备注功能
fix: 修复邮件未读标记不更新的问题
docs: 更新 README 部署说明
```

### 数据库迁移

当需要修改数据库结构时：

1. **创建迁移脚本**
   - 在 `database/` 目录创建新的 SQL 文件
   - 命名格式：`migration_描述.sql`
   - 示例：`migration_add_remark.sql`

2. **编写迁移 SQL**
   ```sql
   -- 添加备注字段
   ALTER TABLE email_addresses 
   ADD COLUMN remark VARCHAR(200) COMMENT '邮箱备注';
   ```

3. **执行迁移**
   ```bash
   mysql -u root -p temp_email_db < database/migration_add_remark.sql
   ```

4. **更新实体类**
   - 在对应的 Entity 类中添加新字段
   - 更新 DTO 和 Repository

### 测试

**后端测试**
```bash
cd backend
mvn test                    # 运行所有测试
mvn test -Dtest=类名        # 运行指定测试类
```

**前端测试**
```bash
cd frontend
npm run test               # 运行单元测试（如已配置）
```

### 常用命令

**后端**
```bash
mvn clean                  # 清理构建
mvn compile                # 编译
mvn package                # 打包
mvn spring-boot:run        # 运行
mvn test                   # 测试
```

**前端**
```bash
npm install                # 安装依赖
npm run dev                # 开发模式
npm run build              # 构建生产版本
npm run preview            # 预览生产版本
npm run lint               # 代码检查
```

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. **Fork 本仓库**
   - 点击右上角的 Fork 按钮
   - 克隆到本地：`git clone https://github.com/your-username/temp-email-system.git`

2. **创建特性分支**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **开发和测试**
   - 编写代码
   - 添加测试用例
   - 确保所有测试通过
   - 遵循代码规范

4. **提交更改**
   ```bash
   git add .
   git commit -m "feat: 添加某某功能"
   ```

5. **推送到分支**
   ```bash
   git push origin feature/your-feature-name
   ```

6. **提交 Pull Request**
   - 在 GitHub 上创建 Pull Request
   - 描述你的更改
   - 等待代码审查

### 贡献类型

- **Bug 修复**：修复已知问题
- **新功能**：添加新的功能特性
- **文档改进**：完善文档和注释
- **性能优化**：提升系统性能
- **代码重构**：改进代码结构
- **测试用例**：增加测试覆盖率

### 代码审查标准

- 代码符合项目规范
- 有适当的注释和文档
- 包含必要的测试用例
- 不引入新的安全问题
- 不破坏现有功能

## 更新日志

### v1.0.0 (2026-02-25)

**新功能**
- ✨ 用户注册和登录功能
- ✨ 临时邮箱生成功能
- ✨ 邮件自动接收和显示
- ✨ 验证码自动提取
- ✨ 邮箱备注功能
- ✨ 邮箱和邮件分页显示
- ✨ 关键词搜索功能
- ✨ 未读邮件标识
- ✨ 移动端响应式设计
- ✨ 管理员配置管理

**安全**
- 🔒 BCrypt 密码加密
- 🔒 JWT 身份认证
- 🔒 AES 敏感信息加密
- 🔒 RBAC 权限控制

**优化**
- ⚡ 数据库连接池优化
- ⚡ 前端打包体积优化
- ⚡ API 响应速度优化

## 路线图

### v1.1.0（计划中）

- [ ] 邮件搜索功能
- [ ] 邮件标签分类
- [ ] 邮件导出功能
- [ ] 邮箱自动过期
- [ ] 密码找回功能
- [ ] 用户头像上传
- [ ] 邮件附件支持

### v1.2.0（计划中）

- [ ] 多语言支持（英文、日文）
- [ ] 暗黑模式
- [ ] 邮件推送通知
- [ ] WebSocket 实时更新
- [ ] 邮箱分享功能
- [ ] API 接口文档（Swagger）

### v2.0.0（计划中）

- [ ] 微服务架构重构
- [ ] Redis 缓存集成
- [ ] 消息队列（RabbitMQ）
- [ ] Docker 容器化部署
- [ ] Kubernetes 编排
- [ ] 监控和日志系统
- [ ] 性能测试和优化

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

MIT License 允许：
- ✅ 商业使用
- ✅ 修改代码
- ✅ 分发代码
- ✅ 私人使用

要求：
- 📄 保留版权声明
- 📄 保留许可证声明

限制：
- ❌ 不提供责任担保
- ❌ 不提供质量保证

## 联系方式

如有问题或建议，请通过以下方式联系：

- **GitHub Issues**：[提交 Issue](https://github.com/your-username/temp-email-system/issues)
- **Pull Request**：[提交 PR](https://github.com/your-username/temp-email-system/pulls)
- **Email**：your-email@example.com

## 致谢

感谢以下开源项目和技术社区：

**后端框架和库**
- [Spring Boot](https://spring.io/projects/spring-boot) - 强大的 Java 应用框架
- [Spring Security](https://spring.io/projects/spring-security) - 安全框架
- [Spring Data JPA](https://spring.io/projects/spring-data-jpa) - 数据访问框架
- [MySQL](https://www.mysql.com/) - 关系型数据库
- [Lombok](https://projectlombok.org/) - Java 代码简化工具
- [Jakarta Mail](https://jakarta.ee/specifications/mail/) - 邮件 API

**前端框架和库**
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Element Plus](https://element-plus.org/) - Vue 3 UI 组件库
- [Vite](https://vitejs.dev/) - 下一代前端构建工具
- [TypeScript](https://www.typescriptlang.org/) - JavaScript 的超集
- [Pinia](https://pinia.vuejs.org/) - Vue 状态管理库
- [Axios](https://axios-http.com/) - HTTP 客户端
- [Vue Router](https://router.vuejs.org/) - Vue 路由管理

**开发工具**
- [IntelliJ IDEA](https://www.jetbrains.com/idea/) - Java IDE
- [Visual Studio Code](https://code.visualstudio.com/) - 代码编辑器
- [Postman](https://www.postman.com/) - API 测试工具
- [Git](https://git-scm.com/) - 版本控制系统

**特别感谢**
- 所有贡献者和使用者
- 开源社区的无私分享
- Stack Overflow 和各技术论坛的帮助

## 免责声明

**重要提示**：

1. **用途限制**
   - 本系统仅供学习、研究和个人使用
   - 不得用于任何非法用途
   - 不得用于发送垃圾邮件或进行网络攻击

2. **隐私保护**
   - 不要在临时邮箱中接收敏感信息
   - 不要使用临时邮箱注册重要账号
   - 系统管理员可能访问数据库查看邮件内容

3. **服务可用性**
   - 系统不保证 100% 可用性
   - 邮件可能丢失或延迟
   - 数据可能因故障而丢失

4. **责任声明**
   - 使用本系统产生的任何后果由使用者自行承担
   - 开发者不对数据丢失、隐私泄露等问题负责
   - 开发者不对因使用本系统导致的任何损失负责

5. **安全建议**
   - 定期更新系统和依赖库
   - 使用强密码和定期更换
   - 生产环境使用 HTTPS
   - 定期备份数据

**使用本系统即表示您已阅读并同意以上声明。**

---

**最后更新时间**：2026-02-25  
**版本**：v1.0.0  
**维护状态**：✅ 积极维护中

如果觉得这个项目对你有帮助，欢迎 ⭐ Star 支持！