用 Cloud Mail 搭域名邮箱,收信之后还有归属问题
记录 Cloud Mail 域名邮箱部署、历史邮件认领和私有 R2 切换,说明如何保留 KV 配置、兼容旧文件读取,并验证附件权限、内联图片和下载。
- 22 分钟阅读
- 2026.10.13
Cloud Mail 的正文和归属保存在 D1,附件可以写入私有 R2 并保留 KV 读取回退;切换前要盘点真实文件,附件入口也要检查登录和归属权限。
工作室网站搭好以后,我接着给它配了一套域名邮箱。最后用的是开源项目 Cloud Mail,网页和 API 放在 Cloudflare Workers,收件交给 Email Routing,发件用 Resend。
2026 年 10 月 8 日做到一半,邮箱工作先暂停了。第二天继续,把登录、外部收件和域名回复跑通,还补了一个原来没有的邮件认领功能。
10 月 12 日,我又把文件存储切到了私有 R2,KV 留着保存设置和登录状态。
10 月 13 日补做的真实附件收信、预览下载和匿名访问检查,以及 Resend 密钥轮换,另写在 R2 附件验证与 Resend 密钥轮换补记 中。
这次最值得记下来的问题,是邮件已经收进系统,后来建好的邮箱却看不到它。排查到这里,部署就从配域名、填密钥,变成了处理邮件到底属于谁。
下面按这次实际用过的方案来写。域名和邮箱地址统一替换成 example.com 下的示例,配置中的资源标识也不公开。文中记录的是这次部署的结果,不保证后续上游版本仍采用相同实现。
收件、网页和发件分别配置
10 月 9 日首次上线时,我把几件事分开了。
| 部分 | 这次使用的服务 | 负责的事情 |
|---|---|---|
| 网页和 API | Cloudflare Workers | 提供网页邮箱、登录及邮件操作接口 |
| 域名收件 | Cloudflare Email Routing 与 Email Worker | 将来信交给应用解析和保存 |
| 邮件数据 | D1 | 保存正文、元数据和邮件归属 |
| 附件 | KV 回退方案 | 保存附件内容 |
| 发件与回复 | Resend | 用经过验证的域名身份发出邮件 |
这里有两个容易混在一起的地址。mail.example.com 是网页入口,user@example.com 是邮箱地址。网页自定义域名负责 HTTPS 访问;邮件能不能收到,还要看根域 MX 和 Email Routing 的配置。
我给收件配置了 catch-all,将这个域名的来信交给 Email Worker。已有邮箱收到的邮件,按对应账号保存。对于还没创建的地址,这次启用了接收未知收件人的设置,让邮件先留在管理页面的“无人收件”里。
catch-all 的意义到这里就很具体了。一个新前缀可以先收到邮件,存储和请求仍然受服务额度限制。这套配置也需要有人处理无人收件列表,不能配完以后就一直放着。
R2 没开通,附件先用 KV
最初检查 Cloudflare 资源时,R2 API 提示尚未启用,需要到后台开通。当时邮箱工作暂停,恢复部署后也没有启用 R2。
我检查了这版代码的存储选择。应用会先看 S3 配置,再看 R2 绑定,两者都没有时走 KV。因此这次让邮件正文和元数据进 D1,附件使用 KV 回退,收发所需的功能仍然可以继续验证。
这个选择只覆盖了眼下的使用需求。附件长期保存多少、怎样备份、何时清理,当时都没有定下来。自动删除也保持关闭。后续如果要换成 R2,需要另外检查已有附件的读取和迁移,不能只加一个绑定就认定旧数据已经搬过去。
Resend 的认证记录要和收件 MX 分开
收件配置完成以后,回复邮件还要单独配置 Resend。应用里填了发信 key,也仍然需要完成域名认证和启用发件设置。
这次保留了根域用于 Cloudflare 收件的 MX,另外添加 Resend 要求的记录。下面只列用途,具体值以自己账户后台生成的内容为准。
| 记录 | 示例名称 | 用途 |
|---|---|---|
| TXT | resend._domainkey.example.com | Resend 的 DKIM 认证 |
| MX | send.example.com | Resend 要求的发件反馈记录 |
| TXT | send.example.com | SPF 认证 |
| CNAME | rsend.example.com | 本次后台要求的附加记录 |
send.example.com 的 MX 和根域 MX 是不同名称下的记录,可以按各自用途配置。照着发件服务的后台填 DNS 时,要看清主机名,保留已有的根域收件记录。
发信 key 用的是仅允许指定域名发送的专用 key。凭据留在应用设置和受限配置中,JWT 签名密钥放在 Worker Secrets,文章和仓库都不保存这些值。
10 月 9 日,Resend 域名验证通过,发件配置启用。外部客户端也收到了测试邮箱的域名回复。那次没有逐项核对邮件认证头和投递事件,因此验收结果只写到已收到回复,不延伸成所有收件服务都能稳定进主收件箱的保证。
先收信,后建邮箱,旧邮件留在原处
这次遇到的具体情况,是向一个尚未创建的地址发送测试邮件。catch-all 把邮件收了下来,管理员能在“全部邮件 → 无人收件”中找到它。
随后创建这个地址对应的邮箱,打开收件箱,旧邮件没有出现。
沿着代码看,邮件到达时就已经保存了归属。找到已有账号时,记录写入对应的用户和邮箱 ID;地址还没有账号时,归属 ID 为 0。后来创建邮箱,只新增账号,不会回头修改这些邮件。
这也解释了为什么“全部邮件里能看到”和“我的收件箱里能看到”会是两个结果。普通收件箱按归属查询,历史邮件还处在无人收件状态。
我最后补了一个管理员认领功能。操作顺序很短。
- 创建与原收件地址一致的邮箱。
- 在无人收件列表打开那封旧邮件。
- 点击“认领到邮箱”,选择匹配的目标并确认。
认领以后,邮件离开无人收件列表,出现在目标邮箱的收件箱,附件也一起归属过去。邮件正文和未读状态保持原样。
认领功能不能只改邮件表
这个功能的界面只有一个按钮,后端要检查的条件不少。
先看权限。系统已有“查看全部邮件”的委派权限,认领会改变邮件归属,所以单独限制为管理员操作。能查看全部邮件的账号,不自动拥有移动归属的权限。
再看地址。目标邮箱必须匹配原始 SMTP 信封收件地址,忽略大小写。邮件内容里的 To 标头不能代替这个判断,应用实际接收这封邮件的地址才是匹配依据。
应用原有的收件流程支持 plus 别名,在没有精确邮箱时尝试对应基础邮箱。这次新增的历史邮件认领暂时只做地址精确匹配,没有把别名规则一起扩进去。
附件也有归属字段。如果只更新邮件,正文可能已经进入新收件箱,附件却仍然留在原状态。我把邮件和普通附件、内联附件的归属更新放进同一个 D1 事务中,有一项失败就回滚。
更新语句还要再次检查邮件是否仍然无人收件、目标账号是否仍然有效。读取和写入之间,另一个管理员可能已经完成认领,账号也可能被停用。前面查过一次,不足以保证写入时条件还成立。
这次为认领功能跑了 10 项测试,覆盖管理员权限、地址匹配、附件转移和事务回滚,也检查了并发和参数错误。发布后确认未登录请求被拒绝,再在页面上确认旧邮件归属成功。这个改动没有新增数据库字段,也没有重建已有数据。
发布配置要和上游默认值分开
部署时,我单独保留了 wrangler.personal.toml,把自己的 D1、KV、静态资源目录和网页域名绑定放在里面。这样更新上游代码时,可以明确看到个人部署需要保留哪些配置。
下面是这次项目的更新发布顺序。路径使用相对目录,命令针对已经初始化好的实例;首次部署还需要先创建资源、填写绑定、配置 Secrets 和邮件路由。
# 在 cloud-mail 仓库根目录开始,前端发布构建输出到 mail-worker/dist。
cd mail-vue
pnpm install --frozen-lockfile
pnpm run build
cd ../mail-worker
pnpm install --frozen-lockfile
# 这是本次 fork 新增的认领测试,需要支持 node:sqlite 的 Node。
pnpm run test:claim
# 后续 R2 改动增加的存储与附件权限测试。
pnpm run test:storage
# 显式指定个人配置,使用已经确认的资源绑定。
pnpm exec wrangler deploy --config wrangler.personal.toml
test:claim 和 test:storage 都是这次 fork 增加的脚本,上游版本未必有它们。前端产物的位置来自这版发布环境配置,换一个版本也要重新核对。
数据库已经初始化,普通更新发布不重放初始化 SQL,更不执行清空操作。代码推到 GitHub 后,这次仍然执行了 Wrangler 发布,再检查线上 Worker 和网页资源,才把改动记为已经部署。
网页返回 HTTP 200 只能证明页面可访问。收件要用外部邮件检查,回复也要去外部收件箱确认。无人收件和历史认领则分别检查,才能知道问题出在哪一段。
邮箱能用了,客户端接入还没有做
收发之外,这次还调整了个性化设置页面,加上登录效果预览和面板透明度滑块,让背景、标题的修改更容易看清结果。前端构建通过,桌面和手机宽度下也做了本地验证。
当时确认完成的事情,包括管理员登录并修改初始密码、已有地址外部收件、未知地址进入无人收件,以及认领后在目标邮箱查看旧邮件。外部客户端收到的域名回复,也补上了发件验证。
我使用的入口仍然是网页邮箱。这次没有配置 IMAP、POP3 或 SMTP 客户端接入,网页地址和 Resend API key 都不能拿来当邮件客户端的登录参数。
公开注册保持关闭,转发、AI 提取和自动删除也没有启用。后续需要处理的,是附件与 D1 的备份、保留策略,以及是否真的需要客户端接入。至于规划中的联系和售后地址,要先创建并验证,再替换网站上的联系方式。
10 月 12 日更新,把文件存储切到私有 R2
第一次上线先用了 KV 回退。这次决定把附件和上传的背景文件交给 R2,邮件正文、归属仍留在 D1。KV 继续保存配置、登录状态和缓存。
先盘点,结果没有旧文件可搬
动手前,我查了 D1 的附件记录,也列了 KV 的 key。结果附件记录为 0,背景还是默认图片,KV 里只有设置和登录状态,没有附件或上传背景。
因此这次没有发生历史文件复制,也没有删除业务 KV 数据。完成的是文件存储切换和兼容处理。已有邮件正文原本就在 D1,不需要跟着移动。
有旧文件的实例需要另外走复制和校验。对象 key 要保留,MIME 类型、下载文件名等 HTTP 元数据也要带过去,确认目标文件的字节一致、访问正常以后,再清理对应的 KV 文件副本。设置和缓存不在这个清理范围里。
桶保持私有,Worker 使用绑定访问
我先在 Cloudflare 后台完成 R2 订阅开通,再创建 Standard 存储桶。r2.dev 公共访问保持关闭,也没有给桶连接公开域名。
下面的桶名是示例,在 mail-worker 目录执行。这组命令用于首次创建和检查桶,不需要每次发布都重跑创建。
# 创建文件存储桶,再分别检查两种公开访问入口。
pnpm exec wrangler r2 bucket create example-mail-files --config wrangler.personal.toml
pnpm exec wrangler r2 bucket dev-url get example-mail-files --config wrangler.personal.toml
pnpm exec wrangler r2 bucket domain list example-mail-files --config wrangler.personal.toml
个人发布配置里增加 R2 绑定,原来的 D1、KV 和 Secrets 保留。
# 仅增加文件存储绑定,保留已有数据库与 KV 配置。
[[r2_buckets]]
binding = "r2"
bucket_name = "example-mail-files"
应用通过 env.r2 访问文件,这次没有新建 S3 密钥,也没有把桶地址作为公开下载入口。
附件链接也要经过权限检查
检查读取流程时,又找到两处要一起调整的地方。旧附件地址会直接读 KV,背景文件也固定从 KV 读取。只加 R2 绑定,会让写入和这些旧入口的读取分开。
我把读取统一到存储服务里,先查 R2,文件不存在时再读 KV。R2 请求本身报错时会保留错误,不把服务故障当成文件不存在。
附件入口同时增加登录和归属检查。普通用户只能读取自己有附件记录的文件,管理员和有全部邮件查看权限的账号按既有权限访问。知道一个对象 key,不足以获得下载权限。
浏览器原来的图片和下载链接不会自动携带登录请求头,我把它们改成先用带认证头的请求取文件,再生成本地 Blob URL。内联图片和附件预览使用这个地址,下载也从同一份文件内容开始,登录 token 不放进 URL。
线上已有的对象地址配置指向网页 Worker 自身。邮件里的图片既可能是相对 key,也可能展开成完整的网站地址,两种写法都要转成认证读取,否则只测相对路径,旧邮件里的图片仍可能打不开。
登录背景单独处理。只有当前配置的背景允许匿名读取,让登录页可以显示它;邮件附件不共用这条规则。
响应头和验证工具还出了一次小问题
R2 读取返回对象及其元数据,原来的 KV 回退返回 Response。统一读取以后,两种结果都需要保留内容类型和下载文件名。私有附件另外设置 Cache-Control: private, no-store,避免作为公共文件缓存。
真实 R2 验证中还遇到过一次 500。原因是验证工具通过远程绑定代理调用对象的方法,无法把本地 Headers 实例序列化过去。我改成读取对象的 HTTP 元数据,在当前运行环境里组装响应头,再跑了一遍验证。这是当时验证环境的边界,没有把它归因成 R2 存储故障。
验证之后再发布
存储和权限增加了 10 项回归测试,覆盖 R2 优先读取、KV 回退、文件删除和越权访问。原来的 10 项邮件认领测试也重新通过。
网页验证用了本地测试邮箱,检查内联图片、附件预览和下载。下载文件逐字节比对,邮件原有的正文样式也保留了。真实 R2 桶则通过远程绑定验证读写和元数据,认证身份及 D1、KV 都使用本地测试数据,没有为了验证存储改动生产邮件或发送测试邮件。
发布后,线上网页返回 200,新附件 API 和旧附件入口的匿名请求都返回 401。再次检查桶的公开访问仍然关闭,KV 设置和原登录状态也还在。临时验证对象清理完,桶里没有留下测试文件。
10 月 13 日补记,真实附件收信与密钥轮换
后续用真实邮件补做了生产验证。两份新附件从远程 R2 读出,SHA-256 与原文件一致,对应文件没有留在 KV。生产网页中预览和下载正常,新旧附件入口的匿名请求都返回 401。桶概览当时仍显示零,不能把这个汇总数字当作逐对象读取的结果。
同一天还更换了 Resend 发送密钥,确认 D1 设置、KV 缓存和本地凭据一致。旧 key 的发送请求被拒绝,新 key 通过 Cloud Mail 正常发送入口完成发信,真实邮箱收到测试邮件。
具体的操作顺序、验证证据和这轮没有覆盖的部分,见 Cloud Mail 补记,R2 附件验证与 Resend 密钥轮换。这里保留 10 月 12 日的切换记录,后续测试附件则继续留在系统里。