Files

T

BigCode d4c1334143 feat: WmailHub v1.0.0 —— Cloudflare Email Workers 邮件接收与转发平台(本地可用版本)

- Console:React 19 + antd 6.6.5 前端(登录 admin/admin)+ Hono 管理 API
  (Nodes/Domains/Mailboxes/Emails/Webhooks/Keys/OAuth/Admin)
- Node:Bun 转发节点(HMAC 签名、有限重试、心跳、结构化日志、优雅退出)
- Email Worker:Cloudflare email handler + 本地联调入口
- shared:HMAC 协议(docs/04)、wmh_ Key(32 位)、AES-GCM 加密、SSRF 防护
- 邮件管线:postal-mime 解析、附件、catch-all、限额、malformed 降级、TTL 1 天
- Webhook:签名投递、指数退避重试、SSRF 校验、投递日志
- API v1 + MCP(JSON-RPC,六工具,凭据 kind 隔离)
- Cloudflare OAuth:真实 + 本地 sim 模式,自动安装管线(幂等,无需手工命令)
- 测试:bun test 41 例(协议安全/管线/TTL/Webhook/SSRF/MCP/OAuth/鉴权)+ Playwright UI 冒烟
- LOGO/favicon 由 codex CLI 生成

2026-09-30 03:34:37 +08:00

2.3 KiB

Raw Blame History

WmailHub 开发设计总览

1. 项目定位

WmailHub 是一个基于 Cloudflare Email Workers 的轻量邮件接收与转发平台。

核心原则：

Cloudflare 负责邮件基础设施。
Console 是控制平面，包含前端与管理 Node。
Node 是邮件数据转发平面，无前端、无业务判断。
Console 通过 Cloudflare OAuth 自动完成 Node、Domain、Mailbox、Email Worker 的配置。
Node 只能处理被授权 Cloudflare Account 下的域名邮箱。
Node 与 Console 的通信必须使用 HTTPS + 应用层签名。
邮件默认短期保存，例如 1 天，过期自动删除。
邮件进入 Console 后才能进入 Webhook、API、MCP 等业务能力。

2. 总体架构

Internet
  |
  v
Cloudflare Email Routing
  |
  v
Cloudflare Email Worker
  |
  v
Node
  | HTTPS + Request Signature
  v
Console Management Node
  |
  +--> Database
  +--> Webhook
  +--> API
  +--> MCP
  +--> Frontend

3. Console

Console = Frontend + Management Node。

负责：Cloudflare OAuth、Cloudflare Account、Node、Domain、Mailbox、Email、Webhook、API、MCP、Node 安装与配置、数据存储、TTL 清理调度。

用户不执行 Node 安装命令。点击 Add Node 后进入 Cloudflare OAuth，授权后由 Cloudflare API 自动完成安装和配置。

4. Node

Node 是纯后端组件，只做：接收 Cloudflare Email Worker 的邮件、将邮件安全转发到 Console。

Node 不做 Domain 判断、Mailbox 判断、邮件业务路由、Webhook、MCP、API、用户权限、邮件长期存储。

Node 收到什么就转发什么。

5. 权限边界

一个 Node 与一个 Cloudflare Account 建立绑定。Node A 只能处理 Account A 下配置的 Email Worker，不允许处理其他 Account。

Domain 与 Mailbox 的具体业务信息由 Console 管理，Node 不需要理解这些业务字段。

6. 核心邮件流程

Email
  |
  v
Cloudflare Email Routing
  |
  v
Email Worker
  |
  v
Node
  |
  v
Console
  |
  +--> Store
  +--> Webhook
  +--> API
  +--> MCP

7. 生命周期

默认邮件 TTL 为 1 天。数据库记录 expires_at，Cron 定期删除过期记录及对应 R2 对象。

8. 第一版明确不做

自建 SMTP Server
IMAP / POP3
发件服务器
完整邮箱客户端
复杂邮件规则引擎
AI 邮件分析
多租户复杂组织系统
Node 端业务路由

2.3 KiB Raw Blame History