# Email **Repository Path**: itmoenyu/Email ## Basic Information - **Project Name**: Email - **Description**: No description available - **Primary Language**: JavaScript - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-26 - **Last Updated**: 2026-01-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 邮箱验证码服务 基于SMTP协议的自建邮箱验证码发送系统，支持163、126、QQ等个人邮箱服务，提供完整的API接口和客户端SDK。 ## 功能特性 ### 核心功能 - ✅ 支持多邮箱服务商（163、126、QQ等） - ✅ 验证码生成与存储 - ✅ 邮件模板系统 - ✅ 发送频率限制 - ✅ 异常处理与日志记录 - ✅ 成功率监控与告警 ### API功能 - ✅ RESTful API接口 - ✅ API密钥认证 - ✅ 权限管理 - ✅ 批量发送支持 - ✅ 请求限流 - ✅ 详细统计与仪表盘 ### 客户端SDK - ✅ JavaScript SDK（浏览器和Node.js） - ✅ Python SDK - ✅ 完整的使用示例 ## 快速开始 ### 环境要求 - Node.js 16+ - MySQL 8.0+ - Python 3.6+（可选，用于Python SDK） ### 安装依赖 ```bash npm install ``` ### 配置环境变量 复制`.env.example`为`.env`，并配置以下参数： ```env # 数据库配置 DB_HOST=localhost DB_PORT=3306 DB_USER=root DB_PASSWORD=your_password DB_NAME=email_verification # SMTP配置（QQ邮箱示例） SMTP_HOST=smtp.qq.com SMTP_PORT=465 SMTP_SECURE=true SMTP_USER=your_email@qq.com SMTP_PASSWORD=your_authorization_code SMTP_FROM_NAME=验证码服务 # 验证码配置 CODE_LENGTH=6 CODE_EXPIRE_MINUTES=5 MAX_SEND_PER_HOUR=5 # 服务器配置 SERVER_PORT=3000 # 监控配置 ALERT_EMAIL=admin@example.com ALERT_THRESHOLD=0.8 ``` ### 初始化数据库 ```bash # 方法1：使用Node.js脚本 node database/init.js # 方法2：使用MySQL命令行 mysql -u root -p < database/schema.sql mysql -u root -p < database/api_tables.sql ``` ### 启动服务 ```bash npm start ``` 服务将在 `http://localhost:3000` 启动。 ## API文档 ### 基础接口 #### 健康检查 ```bash GET /api/health ``` #### 发送验证码 ```bash POST /api/send Content-Type: application/json X-API-Key: your_api_key { "email": "user@example.com", "purpose": "login" } ``` #### 批量发送验证码 ```bash POST /api/batch-send Content-Type: application/json X-API-Key: your_api_key { "emails": ["user1@example.com", "user2@example.com"], "purpose": "register" } ``` #### 验证验证码 ```bash POST /api/verify Content-Type: application/json X-API-Key: your_api_key { "email": "user@example.com", "code": "123456", "purpose": "login" } ``` ### 统计接口 #### 获取统计信息 ```bash GET /api/stats?days=7 X-API-Key: your_api_key ``` #### 获取仪表盘 ```bash GET /api/dashboard X-API-Key: your_api_key ``` #### 获取发送日志 ```bash GET /api/logs?email=user@example.com&days=7 X-API-Key: your_api_key ``` #### 获取告警信息 ```bash GET /api/alerts?status=unresolved X-API-Key: your_api_key ``` ### API密钥管理 #### 创建API密钥 ```bash POST /api/keys/create Content-Type: application/json X-API-Key: admin_api_key { "keyName": "测试密钥", "description": "用于测试的API密钥", "permissions": { "send": true, "verify": true, "view_stats": true }, "rateLimit": 500, "dailyLimit": 5000 } ``` #### 获取API密钥列表 ```bash GET /api/keys/list X-API-Key: admin_api_key ``` #### 更新API密钥 ```bash PUT /api/keys/{keyId} Content-Type: application/json X-API-Key: admin_api_key { "description": "更新描述", "rateLimit": 1000 } ``` #### 删除API密钥 ```bash DELETE /api/keys/{keyId} X-API-Key: admin_api_key ``` 详细的API文档请参考：[API文档](./docs/API文档.md) ## SDK使用 ### JavaScript SDK ```javascript const EmailVerificationClient = require('./sdk/javascript/EmailVerificationClient'); const client = new EmailVerificationClient({ baseUrl: 'http://localhost:3000/api', apiKey: 'your_api_key' }); async function sendCode() { const result = await client.sendCode('user@example.com', 'login'); if (result.success) { console.log('验证码已发送'); } } ``` ### Python SDK ```python from email_verification_client import EmailVerificationClient client = EmailVerificationClient( base_url='http://localhost:3000/api', api_key='your_api_key' ) result = client.send_code('user@example.com', purpose='login') if result['success']: print('验证码已发送') ``` 详细的SDK使用示例请参考：[SDK使用示例](./docs/SDK使用示例.md) ## 项目结构 ``` Email/ ├── src/ # 源代码 │ ├── config/ # 配置文件 │ │ └── database.js # 数据库配置 │ ├── middleware/ # 中间件 │ │ └── auth.js # 认证中间件 │ ├── routes/ # 路由 │ │ ├── api.js # API路由 │ │ └── apiKeys.js # API密钥管理路由 │ ├── services/ # 服务层 │ │ ├── apiKey.js # API密钥服务 │ │ ├── emailSender.js # 邮件发送服务 │ │ ├── emailTemplate.js # 邮件模板服务 │ │ ├── monitor.js # 监控服务 │ │ └── verificationCode.js # 验证码服务 │ ├── utils/ # 工具函数 │ │ └── logger.js # 日志工具 │ └── index.js # 入口文件 ├── database/ # 数据库脚本 │ ├── schema.sql # 核心表结构 │ ├── api_tables.sql # API管理表结构 │ └── init.js # 初始化脚本 ├── sdk/ # 客户端SDK │ ├── javascript/ # JavaScript SDK │ │ └── EmailVerificationClient.js │ ├── python/ # Python SDK │ │ └── email_verification_client.py │ └── README.md # SDK使用指南 ├── examples/ # 示例代码 │ ├── send-verification-code.js │ └── send-verification-code.py ├── docs/ # 文档 │ ├── API文档.md │ ├── SDK使用示例.md │ └── 部署指南.md ├── .env.example # 环境变量示例 ├── .gitignore ├── package.json ├── deploy.sh # Linux部署脚本 └── deploy.bat # Windows部署脚本 ``` ## 部署 ### Linux部署 ```bash chmod +x deploy.sh ./deploy.sh ``` ### Windows部署 ```cmd deploy.bat ``` 详细的部署指南请参考：[部署指南](./docs/部署指南.md) ## 配置说明 ### SMTP配置 #### QQ邮箱 - SMTP服务器：smtp.qq.com - 端口：465（SSL）或 587（TLS） - 需要授权码（不是QQ密码） #### 163邮箱 - SMTP服务器：smtp.163.com - 端口：465（SSL）或 994（SSL） - 需要授权码（不是163密码） #### 126邮箱 - SMTP服务器：smtp.126.com - 端口：465（SSL）或 994（SSL） - 需要授权码（不是126密码） ### 验证码配置 - `CODE_LENGTH`：验证码长度（默认6位） - `CODE_EXPIRE_MINUTES`：验证码有效期（默认5分钟） - `MAX_SEND_PER_HOUR`：每小时最大发送次数（默认5次） ### API密钥配置 - `rateLimit`：每分钟请求限制（默认1000次） - `dailyLimit`：每日请求限制（默认10000次） - `ipWhitelist`：IP白名单（可选） - `expiresAt`：过期时间（可选） ## 监控与告警 系统提供以下监控功能： - 发送成功率监控 - SMTP连接状态监控 - API调用统计 - 告警通知（邮件） 告警阈值可在`.env`文件中配置： ```env ALERT_EMAIL=admin@example.com ALERT_THRESHOLD=0.8 ``` ## 安全建议 1. **API密钥管理** - 不要在客户端代码中硬编码API密钥 - 定期轮换API密钥 - 为不同应用创建专用密钥 2. **数据库安全** - 使用强密码 - 限制数据库访问权限 - 定期备份数据 3. **SMTP安全** - 使用SSL/TLS加密连接 - 不要在代码中存储邮箱密码 - 使用授权码而非密码 4. **网络安全** - 部署时使用HTTPS - 配置防火墙规则 - 限制API访问频率 ## 常见问题 ### Q: 如何获取QQ邮箱授权码？ A: 1. 登录QQ邮箱网页版 2. 点击设置 -> 账户 3. 找到"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务" 4. 开启"POP3/SMTP服务" 5. 按提示发送短信获取授权码 ### Q: 验证码发送失败怎么办？ A: 检查以下几点： 1. SMTP配置是否正确 2. 授权码是否有效 3. 邮箱地址是否真实存在 4. 是否超过发送频率限制 ### Q: 如何提高发送速度？ A: 1. 使用批量发送接口 2. 合理设置批次大小 3. 使用高性能服务器 4. 优化数据库查询 ### Q: 如何处理大量发送需求？ A: 1. 使用批量发送接口（单次最多100个） 2. 分批处理，每批间隔1-2秒 3. 实现队列机制 4. 考虑使用消息队列（如RabbitMQ） ## 技术栈 - **后端框架**：Node.js + Express.js - **数据库**：MySQL 8.0 - **邮件发送**：Nodemailer - **日志**：Winston - **认证**：API密钥 + JWT - **限流**：express-rate-limit ## 许可证 MIT License ## 贡献 欢迎提交Issue和Pull Request！ ## 联系方式 如有问题，请提交Issue或联系管理员。