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:
@@ -1,61 +1,56 @@
|
||||
# ZCODE 实施计划
|
||||
# WmailHub 实施计划(v2,docs/11 §20)
|
||||
|
||||
## Phase 1 项目骨架
|
||||
## Phase 1 Console 重构(数据模型)
|
||||
|
||||
```text
|
||||
WmailHub/
|
||||
console/
|
||||
node/
|
||||
worker/
|
||||
docs/
|
||||
```
|
||||
Cloudflare Account(cloudflare_accounts)、Domain、Mailbox、WorkerCredential;
|
||||
迁移 0003 移除 nodes / node_credentials,emails/domains 归属改为 account_id。
|
||||
|
||||
Console、Node、Worker 必须边界清晰,共享协议独立。
|
||||
## Phase 2 Authorization API
|
||||
|
||||
## Phase 2 Console
|
||||
POST /internal/email/authorize:recipient/sender -> accept | reject(code+reason) | temporary_error;
|
||||
拒绝码 DOMAIN_NOT_FOUND / DOMAIN_DISABLED / MAILBOX_NOT_FOUND / MAILBOX_DISABLED / RECEIVING_DISABLED。
|
||||
|
||||
实现 Console Web、Management API、数据库、认证、Node CRUD、Domain CRUD、Mailbox CRUD、Email CRUD。
|
||||
## Phase 3 Email Worker
|
||||
|
||||
## Phase 3 Cloudflare OAuth
|
||||
email handler + HMAC 签名 + authorize + setReject + ingest(共享逻辑见
|
||||
shared/src/email-worker-template.ts 与 worker/src)。
|
||||
|
||||
实现 OAuth start、callback、state、token exchange、Account/Zone discovery、加密 token storage。
|
||||
## Phase 4 Mail Ingest API
|
||||
|
||||
## Phase 4 自动 Node 安装
|
||||
POST /internal/email/ingest:message/rfc822 原文直传(不转 JSON 字符串),
|
||||
复验 recipient(动态邮箱),只允许 accept 后调用。
|
||||
|
||||
Add Node 后完成:OAuth、Node identity、Node credential、Email Worker、Worker -> Node、Email Routing、Domain、Mailbox、Node heartbeat。正常流程禁止要求用户复制安装命令。
|
||||
## Phase 5 Cloudflare 自动配置
|
||||
|
||||
## Phase 5 Node
|
||||
Connect Cloudflare Account:OAuth -> Account/Zone 发现 -> 域名同步 ->
|
||||
Email Worker 部署(注入 CONSOLE_URL/WORKER_ID/WORKER_SECRET)-> WorkerCredential 签发;
|
||||
逐域名:Email Routing + catch-all 规则。
|
||||
|
||||
实现 bootstrap、secure config、Email Worker ingress、Console egress、HMAC signing、heartbeat、有限 retry、graceful shutdown、structured logging。
|
||||
## Phase 6 邮件存储
|
||||
|
||||
Node 不实现业务路由。
|
||||
D1 元数据 + R2 raw MIME/附件 + MIME 解析(降级入库)+ 大小/数量限额。
|
||||
|
||||
## Phase 6 Email Pipeline
|
||||
## Phase 7 Webhook / REST API / MCP / TTL
|
||||
|
||||
```text
|
||||
Cloudflare -> Worker -> Node -> Console -> D1/R2
|
||||
```
|
||||
三级 Webhook(邮箱 -> 域名 -> 全局,冻结投递配置)、Bearer API/MCP Key、MCP 工具、
|
||||
Cron 清理(过期邮件 + orphan + nonce/state)+ Webhook 重试。
|
||||
|
||||
测试 plain text、HTML、MIME、attachment、多收件人、大正文和 malformed mail。
|
||||
## Phase 8 完整测试
|
||||
|
||||
## Phase 7 Webhook
|
||||
1. 存在邮箱 -> 接收成功;
|
||||
2. 不存在邮箱 -> message.setReject()(MAILBOX_NOT_FOUND);
|
||||
3. 禁用邮箱 -> setReject(MAILBOX_DISABLED);
|
||||
4. 禁用域名 -> setReject(DOMAIN_DISABLED);
|
||||
5. Console 超时 -> temporary_error,不能变成 mailbox not found;
|
||||
6. Console 5xx -> temporary_error;
|
||||
7. ingest 失败 -> 不伪造业务拒绝;
|
||||
8. Worker credential revoke/rotate -> Worker 无法访问 Console;
|
||||
9. 新建邮箱后测试立即接收;
|
||||
10. 删除邮箱后测试立即拒绝;
|
||||
11. 多域名并发测试;
|
||||
12. catch-all 地址测试。
|
||||
|
||||
实现 CRUD、secret、signing、delivery、retry、timeout、失败状态和日志。
|
||||
## 最终验收
|
||||
|
||||
## Phase 8 TTL
|
||||
|
||||
实现 retention configuration、expires_at、Cron cleanup、R2 cleanup 和 orphan cleanup。默认 1 day。
|
||||
|
||||
## Phase 9 API / MCP
|
||||
|
||||
实现 Console API,并提供 list_mailboxes、list_emails、get_email、create_mailbox、delete_mailbox、list_webhooks 等 MCP 工具。权限必须基于 Console credential。
|
||||
|
||||
## Phase 10 安全测试
|
||||
|
||||
测试 OAuth CSRF、credential revoke、replay attack、伪造 Node 请求、body 篡改、过期 timestamp、Webhook SSRF、未授权 mailbox、未授权 Cloudflare Account、超大邮件和超大附件。
|
||||
|
||||
## Phase 11 验收
|
||||
|
||||
必须完成:Cloudflare OAuth -> 自动 Node 安装 -> Domain 配置 -> Mailbox 创建 -> 真实 Email -> Email Worker -> Node -> Console -> Database/Webhook/API/MCP -> TTL 自动删除。
|
||||
|
||||
如果正常流程要求用户手工登录服务器执行安装命令,则不符合设计目标。
|
||||
运行架构必须是 `Internet -> Cloudflare Email Routing -> Email Worker -> Console(D1/R2/Webhook/API/MCP)`;
|
||||
不得存在 `Email Worker -> Node -> Console`。
|
||||
|
||||
Reference in New Issue
Block a user