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:
bigcode
2026-09-30 13:10:26 +08:00
parent 421cfb2f04
commit fec96e49cc
56 changed files with 2584 additions and 1416 deletions
+35 -40
View File
@@ -1,18 +1,19 @@
# WmailHub 开发设计总览
# WmailHub 开发设计总览(v2,docs/11)
## 1. 项目定位
WmailHub 是一个基于 Cloudflare Email Workers 的轻量邮件接收与转发平台。
核心原则:
核心原则:
- Cloudflare 负责邮件基础设施。
- Console 是控制平面,包含前端与管理 Node。
- Node 是邮件数据转发平面,无前端、无业务判断。
- Console 通过 Cloudflare OAuth 自动完成 Node、Domain、Mailbox、Email Worker 的配置。
- Node 只能处理被授权 Cloudflare Account 下的域名邮箱。
- Node 与 Console 的通信必须使用 HTTPS + 应用层签名。
- 邮件默认短期保存,例如 1 天,过期自动删除。
- 不自建 SMTP、IMAP、POP3。
- 不部署邮件转发 Node(v1 的 Node 已从邮件链路移除)。
- Email Worker 是邮件入口 + SMTP reject 执行者。
- Console 是唯一业务控制中心,也是"是否允许接收邮件"的唯一事实来源。
- Worker 不保存邮箱业务数据;邮箱、域名、启用状态全部由 Console 管理。
- Console 明确允许时,Worker 接收邮件;明确拒绝时执行 `message.setReject()`;
Console 超时或 5xx 不能被解释成邮箱不存在。
- 邮件默认短期保存,例如 1 天,过期自动删除。
- 邮件进入 Console 后才能进入 Webhook、API、MCP 等业务能力。
## 2. 总体架构
@@ -25,14 +26,12 @@ Cloudflare Email Routing
|
v
Cloudflare Email Worker
|
| HTTPS + HMAC(authorize / ingest)
v
Node
| HTTPS + Request Signature
v
Console Management Node
Console
|
+--> Database
+--> D1
+--> R2
+--> Webhook
+--> API
+--> MCP
@@ -41,60 +40,56 @@ Console Management Node
## 3. Console
Console = Frontend + Management Node。
Console = Frontend + Management API。
负责:Cloudflare OAuth、Cloudflare Account、Node、Domain、Mailbox、Email、Webhook、API、MCP、Node 安装与配置、数据存储、TTL 清理调度。
负责:Cloudflare OAuth、Cloudflare Account、Domain、Mailbox、邮箱启用/禁用、Email Storage、
Webhook、REST API、MCP、TTL Cleanup、Cloudflare Email Routing 配置、Email Worker 部署、
Worker Credential。
用户不执行 Node 安装命令。点击 Add Node 后进入 Cloudflare OAuth,授权后由 Cloudflare API 自动完成安装和配置。
用户不执行安装命令。点击「添加账号」进入 Cloudflare OAuth(Connect Cloudflare Account),
授权后由 Cloudflare API 自动完成域名同步、Worker 部署与凭据配置。
## 4. Node
## 4. Email Worker
Node 是纯后端组件,只做:接收 Cloudflare Email Worker 的邮件、将邮件安全转发到 Console。
Worker 只做:接收 Cloudflare Email Routing 邮件 -> authorize(询问 Console)->
reject 时 `message.setReject()` -> accept 时把 raw MIME 提交 ingest。
Node 不做 Domain 判断、Mailbox 判断、邮件业务路由、Webhook、MCP、API、用户权限、邮件长期存储。
Node 收到什么就转发什么。
不做邮箱/域名管理、用户权限、Webhook、API、MCP、D1/R2 业务查询、TTL、邮箱业务规则。
## 5. 权限边界
一个 Node 与一个 Cloudflare Account 建立绑定。Node A 只能处理 Account A 下配置的 Email Worker,不允许处理其他 Account。
一个账号绑定一个 Cloudflare Account 与一个 Email Worker;Worker credential 只能处理
所属账号下的域名邮箱(docs/04 归属校验)。
Domain 与 Mailbox 的具体业务信息由 Console 管理,Node 不需要理解这些业务字段。
## 6. 核心邮件流程
## 6. 核心邮件流程(两阶段)
```text
Email
|
v
Cloudflare Email Routing
Cloudflare Email Routing(catch-all)
|
v
Email Worker
|
v
Node
|
v
Console
|
+--> Store
+--> Webhook
+--> API
+--> MCP
Console /internal/email/authorize
+-- accept -> /internal/email/ingest -> D1 + R2 + Webhook
+-- reject -> message.setReject()
+-- temporary_error -> 交由 Cloudflare 邮件机制重试
```
## 7. 生命周期
默认邮件 TTL 为 1 天。数据库记录 expires_at,Cron 定期删除过期记录及对应 R2 对象。
默认邮件 TTL 为 1 天。数据库记录 expires_at,Cron 定期删除过期记录及对应 R2 对象。
## 8. 第一版明确不做
- 自建 SMTP Server
- IMAP / POP3
- 发件服务器
- 发件服务器 / NDR(反站)
- 完整邮箱客户端
- 复杂邮件规则引擎
- AI 邮件分析
- 多租户复杂组织系统
- Node 端业务路由
- KV/DO 邮箱缓存与同步(性能需要时再评估,须接受传播延迟)