BigCode
d4c1334143
- 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 生成
101 lines
2.3 KiB
Markdown
101 lines
2.3 KiB
Markdown
# 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. 总体架构
|
|
|
|
```text
|
|
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. 核心邮件流程
|
|
|
|
```text
|
|
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 端业务路由
|