MailFlare 附件全链路解析从 MIME 拆包到 R2 存储再到带鉴权的下载与 inline 图片【免费下载链接】mailflareEmail client with custom domain based on Cloudflare项目地址: https://gitcode.com/gh_mirrors/mai/mailflareMailFlare 是一款基于 Cloudflare 构建的自托管邮箱客户端而附件处理正是其中最复杂的一环一封带图邮件从收到、拆开、存到 R2 对象存储再到用户下载或正文中内联显示图片中间横跨解析、存储、鉴权、渲染四层链路。本文带你完整走一遍这条链路看懂每一步在做什么、为什么这么做。一、附件全链路的四个环节 把一条附件的生命周期拆开看就是四步环节做什么核心文件收信拆包原始邮件落 R2MIME 解析出附件src/lib/email/inbound.ts、src/lib/email/parse.ts存储归档附件逐个写入 R2元数据入库src/lib/email/attachments.ts带鉴权下载Cookie 登录态 邮箱访问权限校验src/app/api/messages/[messageId]/attachments/[attachmentId]/route.tsinline 渲染正文cid:引用替换为鉴权预览地址src/app/(dashboard)/inbox/[messageId]/utils.ts二、收信原始邮件先落 R2再 MIME 拆包一封外部来信到达后worker.ts不会直接解析正文而是先调用storeRawToR2把完整的 EML 原始字节以inbound/{时间戳}-{id}.eml为键存入 R2见src/lib/email/inbound.ts随后丢进队列异步处理。processInboundMessage从 R2 取回原始邮件交给parseRawMime见src/lib/email/parse.ts。它基于 postal-mime 库完成真正的 MIME 拆包提取主题、纯文本/HTML 正文、发件人等头部信息把email.attachments逐个规整成统一的AttachmentContent结构文件名、MIME 类型、内容字节自动处理 base64 解码、inline/attachmentdisposition以及关键的contentId即 CID正文内嵌图片靠它定位无名附件自动命名为attachment-1、attachment-2未知类型兜底为application/octet-stream。原始邮件保留在 R2 还有一个用途邮件详情页据此生成退订链接。三、存储附件写 R2元数据进 D1失败自动回滚拆出的附件由storeMessageAttachments见src/lib/email/attachments.ts归档键名结构attachments/{messageId}/{attId}/{filename}按消息隔离便于整封邮件清理文件名消毒路径分隔符、反斜杠、空字节统一替换为下划线防止越权路径元数据入库D1 的message_attachments表只存文件名、类型、大小、disposition、CID、R2 键名等轻量字段二进制本体始终在 R2数据库不膨胀失败回滚批量写入中途出错时已上传的 R2 对象会被逐一删除避免产生孤儿文件。发信走同一套存储函数但先过一道validateAttachments硬限制单个附件 ≤ 10 MB、一封合计 ≤ 20 MB、最多 10 个附件超限时直接报错拒绝而不是截断发送。四、发信inline 图片在这里第一次上岗sendEmail见src/lib/email/send.ts把消息、正文、附件落库后通过 Cloudflare Email 服务真正发出去。发信时对附件做了精细区分带contentId且 disposition 为inline的附件比如正文里的一张配图会以inline Content-ID方式发出——收件方客户端能用cid:引用在正文位置直接显示图片其余一律按普通附件发出。也就是说CID 这套正文内嵌附件机制在发信端就已就位为收信端的 inline 渲染埋下伏笔。五、下载与预览一个接口三种模式 附件访问入口是GET /api/messages/{messageId}/attachments/{attachmentId}。这个接口的设计值得细看它同时解决了安全和体验两个问题。先鉴权再谈文件见src/app/api/messages/[messageId]/attachments/[attachmentId]/route.ts与src/lib/email/attachments.ts中的getAttachmentForUser未登录无有效 Cookie直接 401查询消息归属若是共享邮箱调用getMailboxAccessLevel校验当前用户是否有读权限没有则 404附件必须同时匹配附件 ID 与消息 ID杜绝跨消息越权取件。再用查询参数切换模式?download1→ 强制下载?preview1且类型可预览 → 内联展示附件本身 disposition 为inline→ 内联展示这正是 inline 图片的通道。可预览由isPreviewableAttachmentType判定见src/app/api/messages/[messageId]/attachments/[attachmentId]/utils.tsPDF、音频、视频、图片刻意排除 SVG 以防脚本注入、纯文本、JSON、XML、CSV 都算其余一律走下载。响应头里还有两道安全保险X-Content-Type-Options: nosniff 严格的Content-Security-Policy含sandbox浏览器不敢自作聪明把文件当脚本执行Cache-Control: private, max-age3600——只允许当前登录用户缓存一小时多用户共享部署下不会串号。六、inline 图片把cid:翻译成带 Cookie 的 URL ️收件时正文里的内嵌图片长得像img srccid:abc123img浏览器根本打不开这种地址。MailFlare 在页面渲染前用resolveInlineAttachmentUrls见src/app/(dashboard)/inbox/[messageId]/utils.ts做一次替换从附件元数据里取出contentId去掉尖括号把 HTML 正文中的cid:{contentId}全部替换为/api/messages/{messageId}/attachments/{attId}?preview1。由于该接口认的是登录 Cookie而img标签默认就携带同源 Cookie图片于是无感地在正文原位置渲染出来——这就是上一节 disposition 为inline的通道发挥作用的场景。前端则由两个组件完成最后一步体验src/components/message-attachment-card.tsx渲染附件卡片图标、文件名、大小、下载按钮src/components/message-attachment-viewer.tsx点击卡片弹出预览器图片/PDF/音视频直接内嵌播放文本类附件通过authFetch拉取内容展示不支持的类型优雅降级为下载。七、小结MailFlare 的附件模块做对了三件关键的事✅二进制与元数据分离文件本体进 R2、描述进 D1存储成本与查询性能兼得✅全链路鉴权下载、预览、inline 图片全部走同一个带登录态校验的 API共享邮箱场景下按读权限逐人把关✅CID 机制闭环发信端以 inlineContent-ID 发出收信端把cid:翻译成鉴权预览 URL正文图片收发都能原位显示。从worker.ts收到原始邮件那一刻到你在浏览器里点开附件卡片这条链路只用了四个核心模块。如果你想动手看源码建议按本文第二节到第六节的文件路径顺序阅读十分钟即可跑通整个心智模型。【免费下载链接】mailflareEmail client with custom domain based on Cloudflare项目地址: https://gitcode.com/gh_mirrors/mai/mailflare创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考