feat: v2.0.0 邮件接收架构改造 —— 移除 Node,Email Worker 直连 Console(docs/11)
- 两阶段接收:POST /internal/email/authorize(accept/reject/temporary_error)+ POST /internal/email/ingest(raw MIME 直传) - Worker-Console 协议:Authorization: WmailHub-Worker + timestamp/nonce/body-hash/HMAC,nonce 防重放,凭据撤销即时生效 - 数据模型:nodes/node_credentials -> cloudflare_accounts/worker_credentials(迁移 0003),emails/domains 归属 account_id - 接入流程 Connect Cloudflare Account:OAuth 自动同步域名 + 部署账号级 Email Worker + 签发 Worker 凭据;rotate 自动重部署 - 动态邮箱:创建/删除/禁用下一封邮件立即生效;拒绝码 DOMAIN_*/MAILBOX_*;超时/5xx 不伪装成邮箱不存在 - 删除 node/ 目录、旧 /api/internal/nodes 协议、ingress/enrollment 概念;dev.ts 简化为 console + email worker 双进程 - 前端:账号页 Email Worker/凭据管理,设置窗口移除默认 Ingress,仪表盘/文案同步;版本 2.0.0 - 测试 62 项全过(新增 authorize 决策矩阵 + Worker 两阶段临时错误语义);本机虚拟 E2E 12 场景全通 - docs 00-10 同步改写;README 更新
This commit is contained in:
+29
-11
@@ -1,42 +1,60 @@
|
||||
# Email 生命周期与 TTL
|
||||
# Email 生命周期与 TTL(v2,docs/11 §3/§10)
|
||||
|
||||
## 接收
|
||||
## 接收(两阶段)
|
||||
|
||||
第一阶段只回答"这封邮件是否应该由 WmailHub 接收?":
|
||||
|
||||
```text
|
||||
Cloudflare -> Email Worker -> Node -> Console
|
||||
Cloudflare -> Email Worker
|
||||
-> POST /internal/email/authorize { recipient, sender }
|
||||
+-- accept 继续第二阶段
|
||||
+-- reject message.setReject()(SMTP 永久拒绝)
|
||||
+-- temporary_error 由 Cloudflare 邮件机制处理后续重试
|
||||
```
|
||||
|
||||
Console 验证 Node 身份和请求完整性,然后解析 MIME、提取 header、text/html 和附件,保存元数据,raw MIME/大附件写入 R2,计算 expires_at,并创建 Webhook Delivery。
|
||||
Console 拒绝码:DOMAIN_NOT_FOUND / DOMAIN_DISABLED / MAILBOX_NOT_FOUND / MAILBOX_DISABLED / RECEIVING_DISABLED。
|
||||
Console 超时、网络失败、5xx 都不能被解释成邮箱不存在,也不能伪造永久拒绝。
|
||||
|
||||
第二阶段(accept 后)存储邮件:
|
||||
|
||||
```text
|
||||
Email Worker -> POST /internal/email/ingest(raw MIME)
|
||||
-> Console:验证 Worker 身份与 recipient -> 解析 MIME -> D1 元数据
|
||||
-> R2 raw MIME / 附件 -> 计算 expires_at -> 创建 Webhook Delivery
|
||||
```
|
||||
|
||||
SMTP 判断与邮件存储完全分离。动态邮箱:创建/删除/禁用邮箱后,下一封邮件的 authorize 立即生效,
|
||||
Worker 不需要保存 mailbox 列表。
|
||||
|
||||
## TTL
|
||||
|
||||
默认保留 1 天:
|
||||
默认保留 1 天,可按 Mailbox 配置:
|
||||
|
||||
```text
|
||||
received_at = 2026-09-30T10:00:00Z
|
||||
expires_at = 2026-10-01T10:00:00Z
|
||||
```
|
||||
|
||||
Retention 可按 Mailbox 配置。
|
||||
|
||||
## Cron
|
||||
|
||||
使用 Cloudflare Cron Trigger,建议每 15 分钟执行一次清理。实际频率根据当前 Cloudflare 限制调整。
|
||||
使用 Cloudflare Cron Trigger(本地每 60s 模拟):
|
||||
|
||||
```text
|
||||
Cron -> 查询 expires_at <= now -> 删除 R2 -> 删除附件 -> 删除 Email
|
||||
+ 过期 nonce / OAuth state 清理 + 过期 webhook delivery 重试
|
||||
```
|
||||
|
||||
删除必须幂等。
|
||||
|
||||
## Webhook
|
||||
|
||||
邮件保存成功后再执行 Webhook。Webhook 失败不能导致邮件重新进入 Node。
|
||||
邮件保存成功后投递(三级解析:邮箱 -> 域名 -> 全局)。Webhook 失败不能导致邮件重新进入接收流程。
|
||||
|
||||
## 异常
|
||||
|
||||
R2 删除失败时保留数据库记录并记录 cleanup error,下一次 Cron 重试。数据库已删除但 R2 删除失败时,需要 orphan cleanup。
|
||||
R2 删除失败时保留数据库记录并记录 cleanup error,下一次 Cron 重试;
|
||||
数据库已删除但 R2 删除失败时,由 orphan cleanup 兜底。ingest 失败不伪造业务拒绝。
|
||||
|
||||
## 数据最小化
|
||||
|
||||
邮件、附件、raw MIME、Webhook Delivery 和临时日志都应有生命周期,不做无限期保存。
|
||||
邮件、附件、raw MIME、Webhook Delivery 和临时日志都应有生命周期,不做无限期保存。
|
||||
|
||||
Reference in New Issue
Block a user