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:
+35
-40
@@ -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 邮箱缓存与同步(性能需要时再评估,须接受传播延迟)
|
||||
|
||||
Reference in New Issue
Block a user