cloud-mail-global

Cloudflare Workers 邮箱服务终极增强版 — 原版功能 + Plus 增强能力深度融合

简体中文 | English

Credits

本项目深度融合 maillab/cloud-mail 与 AndrewYukon/cloud-mail-plus，以 Plus 增强版为主干，同时补回原版中遗漏的黑名单、AI 验证码识别、登录页细节等能力，目标是形成保留全部功能的 cloud-mail-global 终极增强版。感谢两位原作者的开源贡献。

长期开发、换机恢复、架构决策、功能边界、部署与上游同步记录请从项目知识库开始阅读。知识库使用独立于项目名称的稳定身份，项目改名后仍继续沿用。

上游同步记录

本项目同时融合两个上游项目。为了后续排查问题、确认功能来源和判断是否需要继续同步，每次同步上游后都必须在这里记录对应的上游版本信息。

同步日期	上游项目	上游分支/版本	上游提交	本项目提交	同步说明
2026-07-10	maillab/cloud-mail	`main` / `v3.0.0-13-ga6b66fc`	`a6b66fc`	`1603052`	同步邮件列表并发查询优化、OAuth `silenced` 状态修复、角色空值判断修复、Telegram Token 展示保护、邮件 HTML 预览安全处理、添加用户弹窗体验优化、邮件详情分隔线样式对齐。
2026-07-10	AndrewYukon/cloud-mail-plus	`main`	`c9b5542`	`1603052`	已检查主分支更新；AI Email Agent 相关源码在本项目中已同步，无需重复覆盖。未同步其项目名、部署脚本和 `wrangler.toml` 回退为 `cloud-mail` 的改动，避免破坏 `cloud-mail-global` 生产配置。

说明：如果上游没有正式 release/tag，则以上游分支最新提交号作为版本号；如果有 tag，则同时记录 tag 与提交号。

新增功能

1. Cloudflare Email Service 集成

使用 Cloudflare 原生 send_email Workers binding 发送邮件，替代 Resend 作为主要发送方式。

CF 优先模式（默认）：先通过 Cloudflare Email Service 发送，失败自动回退 Resend
仅 Resend 模式：与原版行为一致
仅 CF 模式：只用 Cloudflare，无回退

优势：

无需第三方 API key（Cloudflare 自动管理 SPF/DKIM/DMARC）
更好的发件信誉度（Cloudflare IP 而非自建服务器 IP）
零额外成本（Workers 付费计划已包含）

在管理后台 设置 → 邮件发送方式 中切换。

2. External API（外部发件 API）

允许其他应用通过 HTTP API 发送邮件和查询状态，支持所有已配置的域名。

# 发送邮件
curl -X POST "https://your-domain.com/api/external/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "from": "App <noreply@example.com>",
    "to": "user@gmail.com",
    "subject": "Hello",
    "html": "<p>Hello world</p>"
  }'

# 查询状态
curl "https://your-domain.com/api/external/status/9" \
  -H "X-API-Key: YOUR_API_KEY"

API Key 在管理后台 设置 → 外部 API 密钥 中生成。

详细文档：External API Guide

3. 邮件删除 + R2 附件清理（Web UI + API）

Web UI：选中邮件后工具栏有两个删除按钮：

🗑️ 软删除 — 标记删除，可恢复
🗑️ 永久删除 — 删除邮件 + R2/S3/KV 附件 + 收藏，不可恢复（有二次确认弹窗）

External API 同时提供删除端点：

# 软删除（标记删除，可恢复）
curl -X DELETE "https://your-domain.com/api/external/email/123" -H "X-API-Key: KEY"

# 永久删除（删除邮件 + R2 附件 + 收藏）
curl -X DELETE "https://your-domain.com/api/external/email/123/permanent" -H "X-API-Key: KEY"

# 批量删除
curl -X POST "https://your-domain.com/api/external/email/batch-delete" \
  -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{"emailIds":[1,2,3],"permanent":true}'

4. 邮件导出为 .eml 文件（Web UI + API）

支持将邮件导出为标准 .eml 格式（RFC 5322），可在 Outlook/Thunderbird 等任意邮件客户端中打开。

Web UI：打开邮件详情 → 点击下载图标 📥 → 自动下载 .eml 文件。

External API：

curl "https://your-domain.com/api/external/email/9/export" \
  -H "X-API-Key: KEY" -o email-9.eml

导出内容包含：邮件头（From/To/Subject/Date）、HTML + 纯文本正文、内嵌图片（CID）、附件。

5. 新用户注册通知

新用户注册时自动发送通知到 Telegram Bot 和管理员邮箱（通过 CF Email Service）。无需额外配置 — 使用已有的 Telegram Bot 设置。

5. 管理员密码重置

忘记管理员密码时，通过 JWT Secret 重置：

curl -X POST "https://your-domain.com/api/reset-admin/<jwt_secret>" \
  -H "Content-Type: application/json" \
  -d '{"password":"newpassword"}'

7. D1 自动备份到 R2

Worker 内置 cron 定时任务，每天自动导出 D1 全量数据为 SQL 并 gzip 压缩上传到 R2。

每天 02:00 UTC 自动运行
保留最近 30 个备份，自动清理旧备份
零外部依赖 — 完全在 Cloudflare 内部完成
支持手动触发：POST /api/backup/<jwt_secret>
查看备份列表：GET /api/backup/<jwt_secret>/list

8. AI 邮件助手（Cloudflare Workers AI）

集成 Cloudflare Workers AI (@cf/moonshotai/kimi-k2.5) 的对话式邮件助手，登录后从 Header ✨ 邮件助手 按钮打开侧边栏即可与 AI 对话。

9 个邮件工具（AI 自动选择调用）：

工具	用途	是否需确认
`listEmails`	列出收件箱 / 已发送 / 草稿 / 垃圾箱	否
`searchEmails`	按主题/发件人/日期搜索邮件	否
`getEmail`	读取指定邮件全文 + 附件列表	否
`getAttachmentText`	读取文本类附件（text/* / json / xml / csv）	否
`summarizeEmail`	3-5 行要点摘要 + 行动项	否
`draftReply`	起草回复（保存到草稿箱）	否
`draftNew`	起草新邮件	否
`sendDraft`	发送草稿	是 ✓
`deleteEmail`	删除邮件（软删除/永久删除）	是 ✓

自动起草新邮件回复 — 收到新邮件时，AI 自动阅读并生成回复草稿保存到草稿箱（永远不会自动发送，必须用户在 UI 中确认）。

安全特性：

发送、删除操作必须由用户在侧边栏底部的确认卡片中点击「确认」才执行
所有工具调用按用户隔离 — 一个用户的 AI 助手永远看不到其他用户的邮件
工具调用计数封顶（每次对话最多 8 步），避免成本爆炸
自动起草仅 2 步上限（读取 + 起草）
AI 模型决定该邮件无需回复时（noreply / spam / 自动通知）会自动跳过

配置：登录后进入设置 → 滑动到底部 ✨ AI 邮件助手 部分 → 启用「AI 助手」开关 + 可选「自动起草」+ 自定义人设说明。

模型与计费：使用 Cloudflare Workers AI Kimi K2.5。免费层每天 10000 neurons，单次对话约消耗 50-200 neurons，足够正常使用。

集成栈：AI SDK v6 + @ai-sdk/vue v3 (Chat 类) + workers-ai-provider + Cloudflare Workers AI。完整中英文 i18n。

cloud-mail-global 额外优化说明

下面这些是当前 cloud-mail-global 在原版功能和 Plus 增强能力之外继续补强的体验与业务功能，原版说明仍完整保留在后文。

1. 写邮件收件人输入增强

一键粘贴识别收件人：收件人输入框支持一次粘贴多个邮箱地址，自动按逗号、分号、空格、换行、中英文标点等拆分识别。
兼容常见联系人格式：支持 name@example.com、Name <name@example.com> 等常见格式，减少手动整理收件人的成本。
自动去重与校验：重复邮箱不会反复加入，非法邮箱会被过滤，降低批量输入时发错人的风险。
标签化收件人管理：识别后的地址以标签形式展示，便于逐个删除、检查和继续补充。

2. 抄送、密送与分别发送

新增抄送 Cc 输入框：发送邮件时可以选择性添加抄送人。
新增密送 Bcc 输入框：发送邮件时可以选择性添加密送人，保护收件人隐私。
支持分别发送：开启后会对多个主收件人逐个单独发送，每个收件人收到的邮件中只包含自己，适合通知、营销、批量邀请等场景。
Web UI 与 External API 同步支持：前端写信窗口和外部发件 API 都支持 cc、bcc；分别发送目前在 Web UI 写信窗口中使用。

3. 注册码生成方式升级

单个可复用注册码：管理员可以生成或手动填写一个注册码，并设置可使用次数 N，适合内部邀请码、长期测试码等场景。
批量一次性注册码：管理员可以批量生成多条注册码，每条注册码自动设置为只能使用 1 次，适合公开邀请、批量发放和一次性注册入口。
后台自由选择模式：在注册密钥管理页面新增生成模式选择，管理员可在“单个注册码”和“批量一次性码”之间切换。
生成结果可复制：批量生成完成后会展示本次生成的注册码列表，并支持一键复制，方便发放给用户。

4. 系统设置页视觉优化

邮件设置区域对齐优化：修复输入框、按钮、开关、下拉框在同一设置卡片中错位的问题。
外部 API 密钥行优化：密钥输入框、生成按钮和相关操作按钮重新排布，避免拥挤和视觉断层。
后台表单一致性增强：让设置页、注册密钥页、写信窗口的输入控件更接近统一的后台管理体验。

5. 发送链路兼容性增强

Cloudflare Email Service 与 Resend 兼容：新增的抄送、密送、分别发送能力会根据当前发送方式走对应服务。
保留回退策略：在 CF 优先模式下，Cloudflare Email Service 发送失败仍可按配置回退到 Resend。
API 参数向后兼容：原有只传 to 的调用方式继续可用，新参数为增强能力，不破坏旧集成。

部署

前置条件

Cloudflare 账号
Node.js 16.17+
pnpm 8+（推荐）或 npm
jq、python3、openssl、curl（一键脚本依赖）
域名已添加到 Cloudflare DNS

一键部署（推荐）

git clone git@github.com:akweksks/cloud-mail-global.git
cd cloud-mail-global
bash scripts/deploy.sh

脚本会自动完成：

检查 wrangler 登录状态（未登录会启动 wrangler login）
幂等创建 D1 / KV / R2（已存在则复用，不会重复创建）
生成 64 字符 JWT secret
可选启用 AI Email Agent（Workers AI kimi-k2.5 + 自动起草） — 自动写入 [ai] binding、EmailAgent Durable Object、DO migration、agent schema
在 wrangler.toml 的标记块内写入 bindings + vars（重跑替换不重复）
wrangler deploy（自动构建 Vue 前端）
调用 /api/init/<jwt_secret> 初始化 D1 schema（含 agent 表）
状态保存在 .cloud-mail-global-deploy.env（已 gitignore，含 JWT secret）

子命令：

bash scripts/deploy.sh                  # 交互式首次部署（会询问是否启用 AI Agent）
bash scripts/deploy.sh --with-ai        # 自动启用 AI Email Agent（非交互）
bash scripts/deploy.sh --no-ai          # 自动禁用 AI Email Agent（非交互）
bash scripts/deploy.sh --redeploy       # 仅重建+部署，跳过资源创建
bash scripts/deploy.sh --reset          # 清除本地状态文件，重新来
bash scripts/deploy.sh --destroy        # 拆除 Worker + D1 + KV + R2（不可逆）
bash scripts/deploy.sh --destroy --yes  # 跳过确认（CI/自动化）

--destroy 会永久删除邮箱数据、附件、备份。请谨慎使用，建议先 wrangler r2 object 备份重要数据。

AI Email Agent 一键启用：

bash scripts/deploy.sh --with-ai

部署完成后：

登录 Web UI（首次需注册管理员账号 — 邮箱必须与 wrangler.toml 的 admin 一致）
顶部 Header 出现 ✨ 邮件助手 / Email Agent 黄色胶囊按钮
设置页面下方有 ✨ AI 邮件助手 部分 — 打开「启用 AI 助手」+ 可选「自动起草」+ 自定义人设
点击 Header 按钮 → 侧边栏滑出 → 与 AI 对话

启用后包含的功能：

9 个邮件工具：listEmails / searchEmails / getEmail / getAttachmentText / summarizeEmail / draftReply / draftNew / sendDraft / deleteEmail
发送 + 删除需要二次确认（在侧边栏底部弹出确认卡片，永远不会自动执行）
收到新邮件时自动起草回复（保存到草稿箱，不会自动发送）
完整的中英文 i18n（跟随系统语言切换）
模型：@cf/moonshotai/kimi-k2.5（Cloudflare Workers AI，按 neuron 计费，免费层每天 10000 neurons）

集成架构：AI SDK v6 (ai 包) + @ai-sdk/vue v3 (Chat 类) + workers-ai-provider + Cloudflare Workers AI。Worker 路由直接调用 streamText() 通过 SSE 流响应（不使用 Durable Object，避免 AIChatAgent 与 Vue Chat 的 WebSocket/HTTP 协议不匹配问题）。

已知部署注意事项

pnpm install — 首次部署若 worker deps 未安装会报 Could not resolve "workers-ai-provider" 等错误。脚本会自动检测并安装，但首次会比较慢。
compatibility_flags = ["nodejs_compat"] — 必须开启（agents 依赖包用了 node:async_hooks / node:diagnostics_channel）。一键脚本已自动写入。
/api/init/<jwt_secret> 是 GET 请求，不是 POST。
Turnstile — 默认如果没配 site_key 会报 "Verification module failed to load"。一键部署后若遇到，运行：
```
npx wrangler d1 execute cloud-mail-global --remote --command "UPDATE setting SET site_key='', secret_key='';"
```
然后硬刷新浏览器（Cmd+Shift+R）即可禁用验证码。
PWA 缓存 — 重新部署后 Service Worker 可能仍服务旧版本。DevTools → Application → Service Workers → Unregister，再硬刷新。

手动部署（步骤分解）

如果你需要更细的控制（例如自定义域名、共享已有 D1），可以按以下步骤手动操作。

克隆仓库

git clone git@github.com:akweksks/cloud-mail-global.git
cd cloud-mail-global

创建 Cloudflare 资源

cd mail-worker
wrangler d1 create cloud-mail-global
wrangler kv namespace create cloud-mail-global-kv
wrangler r2 bucket create cloud-mail-global-r2

配置 wrangler.toml

将上一步生成的 ID 填入 wrangler.toml：

[[d1_databases]]
binding = "db"
database_name = "cloud-mail-global"
database_id = "<your-d1-id>"

[[kv_namespaces]]
binding = "kv"
id = "<your-kv-id>"

[[r2_buckets]]
binding = "r2"
bucket_name = "cloud-mail-global-r2"

[vars]
domain = '["example.com"]'
admin = "admin@example.com"
jwt_secret = "<random-string>"

启用 Cloudflare Email Service（可选）

在 Cloudflare Dashboard → Email → Email Sending 中 onboard 你的域名，然后在 wrangler.toml 中取消注释：

[[send_email]]
name = "EMAIL"

部署

wrangler deploy

初始化数据库

https://your-worker.workers.dev/api/init/<your-jwt-secret>

注册管理员账号

访问你的 Worker URL，用 admin 配置中的邮箱注册。

CF Email Service API 注意事项

在集成 Cloudflare Email Service 时发现的 API 细节（文档未充分说明）：

项目	说明
`from` 字段	必须是 `{ name, email }` 对象，不能用 `"Name <email>"` 字符串格式
附件 `type` 字段	MIME 类型字段名是 `type`，不是 `mimeType` 或 `contentType`
附件 `disposition`	必填，值为 `"attachment"` 或 `"inline"`
发件状态	同步返回成功/失败，无 webhook 回调（与 Resend 不同）
收件人上限	to + cc + bcc 总计不超过 50

常见问题

子域名 catch-all 邮件路由（主域名已绑定其他邮件服务）

如果你的主域名（如 example.com）已绑定其他邮件服务（如 Google Workspace），无法在 Cloudflare 开启 Email Routing，可以使用子域名：

在 Cloudflare Dashboard 为子域名 mail.example.com 开启 Email Routing
设置 catch-all → cloud-mail-global Worker
在 wrangler.toml 的 domain 中添加 "mail.example.com"
用户邮箱格式变为 user@mail.example.com

注意：子域名和主域名的 Email Routing 是独立的，互不影响。

IMAP/POP3/SMTP 客户端支持（Outlook/Thunderbird）

Cloudflare Workers 无法运行 IMAP/SMTP 等 TCP 协议服务。如需在 Outlook 等客户端中收发邮件，推荐搭配 Stalwart Mail Server 使用：

部署指南：stalwart-mail-deploy
Stalwart 提供 IMAP (993) + SMTP (465) 给 Outlook
Cloud-Mail Plus 通过 External API 提供发件（走 CF Email Service，更高信誉度）
可通过 Mail Bridge 组件将两者打通（详见 stalwart-mail-deploy 的 Cloudflare Workers 策略）

原版功能

本项目保留了 maillab/cloud-mail 的所有原版功能，并叠加 cloud-mail-plus 的增强能力：

多域名支持
邮件收发（Cloudflare Email Routing 收件 + Resend 发件）
附件支持（R2/S3/KV 存储）
响应式 Web UI（Vue 3 + Element Plus）
多用户 + RBAC 权限控制
Telegram 推送
Turnstile 验证码
邮件转发
暗色模式
多语言（中/英）

技术栈

组件	技术
运行环境	Cloudflare Workers
后端框架	Hono.js
数据库	Cloudflare D1 (SQLite) + Drizzle ORM
缓存	Cloudflare KV
文件存储	Cloudflare R2
发件	Cloudflare Email Service（主） + Resend（备）
收件	Cloudflare Email Routing
前端	Vue 3 + Element Plus + Vite

支持项目

如果这个项目对你有帮助，欢迎请我喝杯咖啡 ☕

License

MIT — 与原项目一致。详见 LICENSE。

Name		Name	Last commit message	Last commit date
.github		.github
doc		doc
docs		docs
mail-vue		mail-vue
mail-worker		mail-worker
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README-en.md		README-en.md
README.md		README.md

Navigation Menu

Repository files navigation

cloud-mail-global

Credits

上游同步记录

新增功能

1. Cloudflare Email Service 集成

2. External API（外部发件 API）

3. 邮件删除 + R2 附件清理（Web UI + API）

4. 邮件导出为 .eml 文件（Web UI + API）

5. 新用户注册通知

5. 管理员密码重置

7. D1 自动备份到 R2

8. AI 邮件助手（Cloudflare Workers AI）

cloud-mail-global 额外优化说明

1. 写邮件收件人输入增强

2. 抄送、密送与分别发送

3. 注册码生成方式升级

4. 系统设置页视觉优化

5. 发送链路兼容性增强

部署

前置条件

一键部署（推荐）

已知部署注意事项

手动部署（步骤分解）

CF Email Service API 注意事项

常见问题

子域名 catch-all 邮件路由（主域名已绑定其他邮件服务）

IMAP/POP3/SMTP 客户端支持（Outlook/Thunderbird）

原版功能

技术栈

支持项目

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

cloud-mail-global

Credits

上游同步记录

新增功能

1. Cloudflare Email Service 集成

2. External API（外部发件 API）

3. 邮件删除 + R2 附件清理（Web UI + API）

4. 邮件导出为 .eml 文件（Web UI + API）

5. 新用户注册通知

5. 管理员密码重置

7. D1 自动备份到 R2

8. AI 邮件助手（Cloudflare Workers AI）

cloud-mail-global 额外优化说明

1. 写邮件收件人输入增强

2. 抄送、密送与分别发送

3. 注册码生成方式升级

4. 系统设置页视觉优化

5. 发送链路兼容性增强

部署

前置条件

一键部署（推荐）

已知部署注意事项

手动部署（步骤分解）

CF Email Service API 注意事项

常见问题

子域名 catch-all 邮件路由（主域名已绑定其他邮件服务）

IMAP/POP3/SMTP 客户端支持（Outlook/Thunderbird）

原版功能

技术栈

支持项目

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages