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
+38 -43
View File
@@ -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`。