Maildrop 邮局服务：核心架构与实现机制全解析
0. 为什么你需要 Maildrop？（引流与应用场景）
在数字隐私日益受到威胁的今天，你是否遇到过以下场景？
- 场景一：垃圾邮件轰炸。注册一个只用一次的网站，结果主邮箱从此被推销邮件占领，每天清理垃圾邮件都要半小时。
- 场景二：账号批量测试。作为开发者，你需要测试系统的邮件注册逻辑，但手里只有一两个真实的邮箱，根本无法模拟多用户环境。
- 场景三：隐私信息泄露。主邮箱往往绑定了银行、支付宝等重要资产，将其暴露在安全性未知的第三方网站上，风险极大。
Maildrop 的核心使命：为你提供一个"阅后即焚"的专属邮局。你可以随时生成数以万计的临时地址，用完即弃。它是你主邮箱的"防火墙"，也是开发者手中最锋利的"测试利器"。
1. 前置条件：搭建前的准备工作
在深入架构之前，请确保你已经准备好以下"基础设施"，这是任何自建邮局能跑通的前提：
- 公网服务器：需要一台拥有公网 IP 的云服务器（建议海外，防止 25 端口被封禁）。
- 独享域名：你需要拥有一个域名的管理权。
- DNS 解析配置（关键） ：
- A 记录 ：将子域名（如
mail.yourdomain.com）解析到你的服务器 IP。 - MX 记录 ：这是邮局的"指路牌"。将根域名（
@）的 MX 记录指向你刚才设置的 A 记录（mail.yourdomain.com），优先级建议设为10。 - 25 端口开放 ：确保服务器防火墙和云商安全组已放行 TCP 25 端口 （SMTP 接收）和 5000 端口（Web 访问）。
- A 记录 ：将子域名（如
2. 总体设计概览
Maildrop 是一个集成了 SMTP 协议接收端 和 Web 管理端 的闭环邮件系统。其核心逻辑在于：将网络底层的字节流邮件转化为可被现代 Web 应用处理的结构化数据，并配合精密的生命周期管理。
密码就是在配置文件里面的内容，输入密码之后进入首页。
可以在里面创建自己的邮箱，域名也是在配置文件配置。
如果不知道MX记录怎么配置可以搜索一下，或者后续接着出这个的配置。
核心流转图
外界邮件投递 -> SMTP Server (25端口) -> Parser (邮件解析) -> Storage (SQLite/JSON) -> API/Web UI (用户查看)
2. 核心组件详解
Maildrop 是一个集成了 SMTP 协议接收端 和 Web 管理端 的闭环邮件系统。其核心逻辑在于：将网络底层的字节流邮件转化为可被现代 Web 应用处理的结构化数据，并配合精密的生命周期管理。
核心流转图
外界邮件投递 -> SMTP Server (25端口) -> Parser (邮件解析) -> Storage (SQLite/JSON) -> API/Web UI (用户查看)
2. 核心组件详解
2.1 SMTP 接收引擎 (src/backend/smtp_server.py)
这是整个邮局的"大门"。
- 异步驱动 ：采用
aiosmtpd库，基于 Python 的asyncio。它不像传统服务器那样为每个连接创建一个进程，而是在单个线程内高效处理成百上千的并发连接。 - 动态拦截 (
handle_DATA) ：这是最核心的钩子函数。当一封邮件完全传输完毕后，系统会拿到原始的字节流（envelope.content）。在此阶段，系统会优先提取发件人 IP，进行黑白名单校验，不合格的直接返回550 Access denied。
2.2 邮件解析专家 (src/backend/email_parser.py)
原始邮件流是一堆包含 Base64、Quoted-printable 编码的混乱字符。
- 任务：递归解析 MIME 结构。
- 处理细节 ：
- 自动识别并解码非 UTF-8 编码的标题和正文。
- 处理
Multipart/Alternative（同时包含 HTML 和纯文本）。 - 提取附件并将其元数据化，方便 Web 端直接渲染。
- 结果 ：生成一个标准化的 JSON 对象，包含
From,To,Subject,Body,Timestamp等字段。
2.3 存储与投递逻辑 (src/backend/inbox_handler.py)
这是邮局的"分拣中心"。
- 收件人分拣 ：根据解析出的
To字段，匹配系统中的虚拟邮箱。 - 多模式切换 ：
- V1 (JSON)：将所有邮件堆在一个巨大的 JSON 文件里（仅推荐小型测试）。
- V2 (SQLite/Database) ：通过
db_inbox_handler.py将邮件写入 SQL 数据库，实现毫秒级的检索速度。
- 配额管理：限制每个邮箱的最大邮件数量（默认 50 封），防止恶意灌水导致磁盘溢出。
2.4 邮箱生命周期管理 (src/backend/mailbox_service.py)
这是 Maildrop 区别于普通邮局的核心：
- 过期机制 ：每个虚拟邮箱创建时都有
expires_at。 - 服务层职责 ：
- 负责邮箱的 CRUD（增删改查）。
- 审计日志：记录所有管理操作。
- 白名单策略：在投递前再次确认该邮箱是否开启了"仅限特定发件人"模式。
3. 关键业务流程分析
3.1 邮件接收流程
SMTP Server建立连接，握手。- 接收
RCPT TO，校验域名是否属于本邮局。 - 接收
DATA字节流。 - 调用
email_parser转化为 JSON。 inbox_handler查找收件箱：- 检查收件箱是否存在且未过期。
- 检查发件人是否在白名单内。
- 写入存储，返回
250 OK。
3.2 自动清理流程
系统通过后台定时任务（或在每次请求时触发）执行以下操作：
- 清理邮件 ：删除超过
config.EMAIL_RETENTION_TIME的单封邮件。 - 清理邮箱 ：删除当前时间大于
expires_at的虚拟邮箱及其所有内容。 - 空间维护 ：确保
data/目录的大小保持在MAX_INBOX_SIZE以内。
4. 安全防护体系
- IP 网段白名单 ：通过
ipaddress库实现对 CIDR（如 192.168.1.0/24）的完美支持。 - 子管理员模式 ：允许通过特定的
Sub-Admin-Token创建受限邮箱，方便集成到第三方自动化系统。 - 双重 Auth：API 访问必须携带 Token，管理端必须携带密码。
5. 项目文件目录说明
text
src/
├── backend/
│ ├── smtp_server.py # SMTP 核心服务
│ ├── email_parser.py # 邮件解码转换
│ ├── mailbox_service.py # 业务逻辑与审计
│ ├── database.py # SQLite 封装
│ └── routes/ # API 接口定义
└── frontend/
├── templates/ # 页面模板
└── static/ # UI 资源Maildrop 是一个典型的"小而美"后端架构范本，它将复杂的邮件协议高度简化，为用户提供了一个开箱即用的隐私保护工具。
项目 GitHub 地址 ：https://github.com/autumuhh/mail
项目 Gitee 地址 ：
(如果觉得这个项目对你有帮助，欢迎点个 Star 支持一下！)