📬 自动邮箱验证码发送工具

v2.0 官方文档 端口 58008 纯 Python 标准库

📖 产品概述

轻量级 HTTP 服务，按需生成随机验证码并通过 SMTP 邮箱发送。内置 Web 管理后台，支持在线修改邮件模板、SMTP 配置等，修改后即时生效（无需重启）。

🚀
单文件部署
仅需 Python 3.6+，无任何第三方依赖。
🎨
Web 配置面板
可视化编辑 SMTP、邮件文案、验证码规则，实时预览。
🖼️
内嵌图标
自动读取同目录 icon.jpg 并嵌入邮件 HTML。
📊
详细终端日志
每一步操作实时输出，方便监控与调试。

🧱 系统架构

graph TB subgraph 业务系统 A[Web / App 后端] end subgraph 验证码发送服务 B[HTTP API :58008] C[配置管理模块] D[验证码生成器] E[SMTP 邮件发送器] F[(config.json)] G[icon.jpg
可选内嵌图片] end subgraph 外部服务 H[163/QQ/企业邮 SMTP] I[收件人邮箱] end A -->|POST /send| B B --> D B --> E C --> F C -.->|热加载| B D -.-> E E -->|读取| G E --> H H --> I

⚙️ 请求处理流程

sequenceDiagram participant Client as 业务系统 participant API as HTTP API (:58008) participant Gen as 验证码生成器 participant SMTP as SMTP 邮件发送器 participant MailSrv as 163/QQ SMTP participant User as 收件人 Client->>API: POST /send {"to_email":"..."} API->>Gen: generate_code(length) Gen-->>API: 随机数字串 API->>SMTP: send_email(config, to_email, code) SMTP->>SMTP: 检测 icon.jpg? alt 有图标 SMTP->>SMTP: 构建 HTML 邮件，内嵌图片 else 无图标 SMTP->>SMTP: 构建纯文本邮件 end SMTP->>MailSrv: SMTP_SSL 登录并发送 MailSrv-->>SMTP: 发送结果 SMTP-->>API: 成功/失败 API-->>Client: JSON 响应（含 code 可选） MailSrv->>User: 验证码邮件

🔄 配置热更新流程

sequenceDiagram participant Admin as 管理员浏览器 participant WebUI as Web 管理界面 participant API as /api/config (POST) participant Validator as 配置校验器 participant Memory as 当前配置(内存) participant Disk as config.json Admin->>WebUI: 修改参数并点击保存 WebUI->>API: POST /api/config (新配置JSON) API->>Validator: validate_config(new_cfg) alt 校验失败 Validator-->>API: 错误列表 API-->>WebUI: 400 错误信息 else 校验通过 Validator-->>API: 通过 API->>Memory: 对比新旧配置，记录变更日志 API->>Disk: 写入 config.json Memory->>Memory: 替换 current_config API-->>WebUI: 200 成功 WebUI->>Admin: Toast 提示"配置已保存并即时生效" end

🗂️ 配置文件结构

classDiagram class SMTP { +string host +int port +string user +string password +string from_name } class EmailTemplate { +string subject +string body } class CodeConfig { +int length +bool return_code_in_response } class ServerConfig { +int port } class Config { +SMTP smtp +EmailTemplate email_template +CodeConfig code +ServerConfig server } Config *-- SMTP Config *-- EmailTemplate Config *-- CodeConfig Config *-- ServerConfig

📊 服务生命周期

stateDiagram-v2 [*] --> 启动中 启动中 --> 运行中: 加载配置成功 启动中 --> 启动失败: 配置错误 运行中 --> 处理请求: POST /send 处理请求 --> 运行中: 响应返回 运行中 --> 配置更新: POST /api/config 配置更新 --> 运行中: 配置已替换 运行中 --> 关闭: Ctrl+C 关闭 --> [*] 启动失败 --> [*]

🧪 测试脚本交互

sequenceDiagram participant Tester as 测试人员 participant Script as test_email_service.py participant API as 验证码服务 :58008 participant Mail as 163 SMTP Tester->>Script: python test_email_service.py Script->>API: POST /send {"to_email":"17840523301@163.com"} API->>API: 生成验证码 API->>Mail: 发送邮件 Mail-->>API: 成功 API-->>Script: {"success":true, "code":"384921"} Script->>Tester: 终端打印成功信息 Script->>Script: sleep(30s) Script->>API: POST /send ... (循环) Tester->>Script: Ctrl+C 停止

📦 部署视图

graph TB subgraph 服务器 direction TB Python[Python 3.6+] Script[mail_code_server.py] Config[config.json] Icon[icon.jpg] Script -.-> Config Script -.-> Icon end subgraph 网络 Firewall[防火墙/反向代理] end subgraph 客户端 Browser[浏览器
管理界面] App[业务系统
HTTP Client] end Script -->|监听 :58008| Firewall Firewall --> Browser Firewall --> App

📡 API 接口参考

发送验证码

POST /send

{
  "to_email": "user@example.com"
}

成功响应 (200)

{
  "success": true,
  "message": "验证码已发送",
  "code": "384921"        // 可选
}
状态码含义示例
200成功{"success":true}
400参数缺失/非法 JSON{"success":false,"message":"缺少 to_email 字段"}
500SMTP 发送失败{"success":false,"message":"SMTP 认证失败"}

获取/更新配置

GET /api/config 获取当前完整配置。

POST /api/config 提交新配置（即时生效）。

🔧 配置参数详解

组字段类型说明
smtphoststringSMTP 地址，如 smtp.163.com
portintSSL 端口，通常 465
userstring邮箱账号
passwordstring授权码（非登录密码）
from_namestring发件人显示名称
email_templatesubjectstring邮件主题，支持 {code}
bodystring邮件正文，支持 {code}
codelengthint验证码位数：4/5/6
return_code_in_responsebool是否在 HTTP 响应中返回验证码
serverportintHTTP 监听端口，默认 58008

🖼️ 内嵌图片图标

将任意图片命名为 icon.jpg 并放在 mail_code_server.py 同目录下。服务启动时自动检测并嵌入邮件顶部（48×48 像素）。若无该文件，则自动回退为纯文本邮件。

⚠️ 安全与最佳实践

重要：config.json 含有授权码，请勿泄露，不要提交到公开仓库。