Cloudflare 临时邮箱接入 S3 附件存储R2 Bucket 配置、Worker Secrets 注入与前后端调用链路全解析【免费下载链接】cloudflare_temp_emailCloudFlare free temp domain email 免费收发 临时域名邮箱 支持附件 IMAP SMTP TelegramBot项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare_temp_email导读本文讲解 cloudflare_temp_email 项目如何将邮件附件从 Cloudflare Worker 内置存储迁移到 S3 兼容的对象存储官方推荐使用 Cloudflare R2。你将掌握创建 R2 Bucket 并配置 CORS、生成 S3 令牌并通过wrangler secret put注入四个核心环境变量、理解S3_ENDPOINT/S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY/S3_BUCKET/S3_URL_EXPIRES五个配置项的作用以及保存、列表、下载、删除附件四类 API 的完整前端到后端调用链路与对象键Key组织规则。该功能是可选增强项不配置时系统照常工作配置后即可在收件箱与“S3附件”页中持久化管理大附件。功能定位什么时候需要 S3 附件S3 附件不是必选项文档开篇明确说明“如果你不需要 S3 附件可以跳过此步骤”。它解决的是临时邮箱场景下的一个典型问题Worker 的持久化资源D1 数据库、KV 等并不适合存放体积较大的二进制邮件附件而将附件原样存入数据库会快速消耗 D1 配额并拖慢查询。启用 S3 附件后收件箱中每个附件的“保存到 S3”按钮可将附件对象存储到 S3/R2释放站内存储前端出现独立的“S3附件”页面对应 Attachment.vue可以查看、下载、删除已经保存到 S3 的附件。需要特别说明的是该功能默认关闭、按需启用且必须四个核心 secret 全部就绪才会生效从源码看isS3Enabled 的逻辑是“四个环境变量任一缺失即视为未启用”该布尔值会被 commom_api.ts 注入到/api/settings响应中前端 api/index.js 读取isS3Enabled后才渲染“S3附件”标签页与“保存到S3”按钮。配置 S3/R2 存储第一步创建 Bucket 并配置 CORS在 Cloudflare 控制台创建 R2 bucket也可使用其他 S3 兼容服务若遇到兼容性 bug 可向项目提交 issue。创建完成后必须为 Bucket 配置 CORS 策略允许前端浏览器跨域发起对象读写请求。Cloudflare 官方的 CORS 配置面板操作位于 R2 → Bucket → Settings → CORS典型策略需要允许你的前端域名如*或具体站点域名发起GET、PUT、DELETE、POST请求。[!NOTE] CORS 配置直接影响浏览器端预检请求能否通过未配置时前端“保存到 S3”“下载”功能会出现跨域报错。第二步创建 S3 Token 并获取凭据在 Cloudflare R2 → Manage R2 API Tokens 中创建一个 S3 兼容的 API Token官方文档路径为 R2 → API → S3 Tokens创建后你会得到三样东西ENDPOINT如https://accountid.r2.cloudflarestorage.comAccess Key IDSecret Access Key第三步通过 wrangler 注入 Secrets拿到上述凭据后进入worker目录执行以下命令把配置写入 Worker 的加密 Secrets。命令运行时会提示你粘贴对应的值cd worker pnpm wrangler secret put S3_ENDPOINT pnpm wrangler secret put S3_ACCESS_KEY_ID pnpm wrangler secret put S3_SECRET_ACCESS_KEY # Note: Replace bucket with your bucket name pnpm wrangler secret put S3_BUCKET[!NOTE] 你也可以在 Cloudflare Worker 的 UI 界面Settings → Variables and Secrets中直接添加上述 Secrets效果相同。从 types.d.ts 可以看到除了上述四个必填项还支持一个可选的S3_URL_EXPIRES: number配置——它控制预签名 URL 的有效期秒数默认 360 秒见 s3_attachment.ts。在 wrangler.toml 中它属于 vars 而非 secrets 范畴若需调整可参考 wrangler.toml.template 的[vars]段添加S3_URL_EXPIRES 360。核心配置项速查表配置项类型必填说明S3_ENDPOINTSecret是S3 兼容服务的端点地址R2 形如https://accountid.r2.cloudflarestorage.comS3_ACCESS_KEY_IDSecret是S3 Token 的 Access Key IDS3_SECRET_ACCESS_KEYSecret是S3 Token 的 Secret Access KeyS3_BUCKETSecret是Bucket 名称S3_URL_EXPIRESvar否预签名 URL 有效期秒默认 360后端实现四类 API 与对象键组织S3 相关后端代码集中在 s3_attachment.ts并统一注册在 mails_api/index.ts 的四个路由上方法路由后端处理器作用GET/api/attachment/listlist列出当前地址保存的全部附件键POST/api/attachment/put_urlgetSignedPutUrl获取上传预签名 URLPOST/api/attachment/get_urlgetSignedGetUrl获取下载预签名 URLPOST/api/attachment/deletedeleteKey删除指定附件对象S3 Client 初始化getS3Client使用aws-sdk/client-s3构建客户端region固定为auto适配 R2 无需分区的特性endpoint取S3_ENDPOINT凭据取S3_ACCESS_KEY_ID与S3_SECRET_ACCESS_KEY任一配置缺失时直接抛出S3 config is not set错误与isS3Enabled的四项检查保持一致。对象键Key组织规则按地址隔离所有对象键都遵循${address}/${key}的命名空间约定见 s3_attachment.tsaddress来自 JWT 载荷c.get(jwtPayload).address保证每个邮箱地址只能访问属于自己的附件上传时前端提交的原始key即邮件附件文件名如one-api.db会被拼接为地址/文件名写入 Bucket列表接口通过ListObjectsV2Command以Prefix: ${address}/过滤并去掉前缀后返回纯净的 key 列表删除接口同样按地址/key精确删除防止越权操作。预签名 URL 机制上传和下载都不经过 Worker 转发文件二进制流而是用aws-sdk/s3-request-presigner的getSignedUrl生成有效期默认 360 秒的预签名 URL前端直接对 S3/R2 发起PUT上传与GET下载。这意味着大文件流量不消耗 Worker 的计算配额浏览器与对象存储之间直连是本功能降低 Worker 负载的核心设计。前端调用链路从收件箱到 S3 附件页保存附件到 S3在收件箱打开邮件附件详情时若isS3Enabled为 trueMailContentRenderer.vue 会渲染“保存到S3”按钮文案见 message-registry.ts。点击后由 Index.vue 中的saveToS3执行两步调用POST /api/attachment/put_url携带{ key: filename }换取预签名上传 URL用该 URL 直接将附件 blobPUT到 S3/R2成功后提示“保存到S3成功”。对应界面如 s3-save.png 所示附件详情弹窗展示文件名如one-api.db与大小右侧为“保存到S3”操作按钮。S3 附件页列表、下载与删除启用后主界面出现“S3附件”标签页Index.vue对应视图 Attachment.vue页面加载时调用GET /api/attachment/list拉取当前地址的附件键列表渲染为 key 操作两列表格点击“下载”时调用POST /api/attachment/get_url获取预签名 URL弹出下载确认框最终通过带download属性的链接在新窗口下载文件名中的/会被替换为_见 Attachment.vue点击“删除”时经NPopconfirm二次确认后调用POST /api/attachment/delete删除对象成功后刷新列表。对应界面如 s3-download.png 所示顶部导航高亮“S3附件”标签表格中展示存储键如3/7/one-api.db即“地址/文件名”拼接形态与下载操作按钮。与相关功能的边界与扩展附件是否在收件时就进入 S3从源码看S3 只保存用户主动点击“保存到S3”的附件常规邮件的附件仍走项目自身的解析与存储流程如邮件解析产物存 D1、原始邮件可启用 gzip 压缩见 wrangler.toml.template 中的ENABLE_MAIL_GZIP。若想整体丢弃大附件可另行配置REMOVE_EXCEED_SIZE_ATTACHMENT或REMOVE_ALL_ATTACHMENT同为 wrangler.toml.template 中的可选开关二者与 S3 附件是互补而非替代关系。Webhook 附件下载走独立的BACKEND_URL签名链接机制见 webhook_attachment.ts 与 wrangler.toml.template 中BACKEND_URL配置与 S3 附件页的下载是两条并行链路互不干扰。若你的 Worker 同时启用了 Telegram 推送附件ENABLE_TG_PUSH_ATTACHMENT请知悉其受 50MB 单文件上限约束S3 附件页则无此限制。常见问题排查思路前端不显示“S3附件”标签或“保存到S3”按钮检查四个 secret 是否全部注入任缺一个isS3Enabled即为 false可在浏览器访问/api/settings确认isS3Enabled字段值。上传/下载出现 CORS 报错核对 R2 Bucket 的 CORS 策略是否放行了你的前端域名及对应 HTTP 方法。预签名 URL 过期确认S3_URL_EXPIRES取值是否合理默认 360 秒下载弹窗停留过久导致 URL 失效时可重新点击下载刷新 URL。使用非 R2 的 S3 服务时行为异常文档明确建议此时提交 issue 反馈因为项目主要针对 R2 适配。总结S3 附件是 cloudflare_temp_email 的可选增强能力通过 Cloudflare R2或任意 S3 兼容服务承载邮件大附件配合四个 secret 的最小化配置即可生效。后端按邮箱地址组织对象键并以预签名 URL 直连对象存储前端提供保存、列表、下载、删除的完整闭环既释放了 Worker/D1 的存储压力也让临时邮箱的用户体验更接近正式邮箱服务。【免费下载链接】cloudflare_temp_emailCloudFlare free temp domain email 免费收发 临时域名邮箱 支持附件 IMAP SMTP TelegramBot项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare_temp_email创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cloudflare 临时邮箱接入 S3 附件存储：R2 Bucket 配置、Worker Secrets 注入与前后端调用链路全解析
Cloudflare 临时邮箱接入 S3 附件存储R2 Bucket 配置、Worker Secrets 注入与前后端调用链路全解析【免费下载链接】cloudflare_temp_emailCloudFlare free temp domain email 免费收发 临时域名邮箱 支持附件 IMAP SMTP TelegramBot项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare_temp_email导读本文讲解 cloudflare_temp_email 项目如何将邮件附件从 Cloudflare Worker 内置存储迁移到 S3 兼容的对象存储官方推荐使用 Cloudflare R2。你将掌握创建 R2 Bucket 并配置 CORS、生成 S3 令牌并通过wrangler secret put注入四个核心环境变量、理解S3_ENDPOINT/S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY/S3_BUCKET/S3_URL_EXPIRES五个配置项的作用以及保存、列表、下载、删除附件四类 API 的完整前端到后端调用链路与对象键Key组织规则。该功能是可选增强项不配置时系统照常工作配置后即可在收件箱与“S3附件”页中持久化管理大附件。功能定位什么时候需要 S3 附件S3 附件不是必选项文档开篇明确说明“如果你不需要 S3 附件可以跳过此步骤”。它解决的是临时邮箱场景下的一个典型问题Worker 的持久化资源D1 数据库、KV 等并不适合存放体积较大的二进制邮件附件而将附件原样存入数据库会快速消耗 D1 配额并拖慢查询。启用 S3 附件后收件箱中每个附件的“保存到 S3”按钮可将附件对象存储到 S3/R2释放站内存储前端出现独立的“S3附件”页面对应 Attachment.vue可以查看、下载、删除已经保存到 S3 的附件。需要特别说明的是该功能默认关闭、按需启用且必须四个核心 secret 全部就绪才会生效从源码看isS3Enabled 的逻辑是“四个环境变量任一缺失即视为未启用”该布尔值会被 commom_api.ts 注入到/api/settings响应中前端 api/index.js 读取isS3Enabled后才渲染“S3附件”标签页与“保存到S3”按钮。配置 S3/R2 存储第一步创建 Bucket 并配置 CORS在 Cloudflare 控制台创建 R2 bucket也可使用其他 S3 兼容服务若遇到兼容性 bug 可向项目提交 issue。创建完成后必须为 Bucket 配置 CORS 策略允许前端浏览器跨域发起对象读写请求。Cloudflare 官方的 CORS 配置面板操作位于 R2 → Bucket → Settings → CORS典型策略需要允许你的前端域名如*或具体站点域名发起GET、PUT、DELETE、POST请求。[!NOTE] CORS 配置直接影响浏览器端预检请求能否通过未配置时前端“保存到 S3”“下载”功能会出现跨域报错。第二步创建 S3 Token 并获取凭据在 Cloudflare R2 → Manage R2 API Tokens 中创建一个 S3 兼容的 API Token官方文档路径为 R2 → API → S3 Tokens创建后你会得到三样东西ENDPOINT如https://accountid.r2.cloudflarestorage.comAccess Key IDSecret Access Key第三步通过 wrangler 注入 Secrets拿到上述凭据后进入worker目录执行以下命令把配置写入 Worker 的加密 Secrets。命令运行时会提示你粘贴对应的值cd worker pnpm wrangler secret put S3_ENDPOINT pnpm wrangler secret put S3_ACCESS_KEY_ID pnpm wrangler secret put S3_SECRET_ACCESS_KEY # Note: Replace bucket with your bucket name pnpm wrangler secret put S3_BUCKET[!NOTE] 你也可以在 Cloudflare Worker 的 UI 界面Settings → Variables and Secrets中直接添加上述 Secrets效果相同。从 types.d.ts 可以看到除了上述四个必填项还支持一个可选的S3_URL_EXPIRES: number配置——它控制预签名 URL 的有效期秒数默认 360 秒见 s3_attachment.ts。在 wrangler.toml 中它属于 vars 而非 secrets 范畴若需调整可参考 wrangler.toml.template 的[vars]段添加S3_URL_EXPIRES 360。核心配置项速查表配置项类型必填说明S3_ENDPOINTSecret是S3 兼容服务的端点地址R2 形如https://accountid.r2.cloudflarestorage.comS3_ACCESS_KEY_IDSecret是S3 Token 的 Access Key IDS3_SECRET_ACCESS_KEYSecret是S3 Token 的 Secret Access KeyS3_BUCKETSecret是Bucket 名称S3_URL_EXPIRESvar否预签名 URL 有效期秒默认 360后端实现四类 API 与对象键组织S3 相关后端代码集中在 s3_attachment.ts并统一注册在 mails_api/index.ts 的四个路由上方法路由后端处理器作用GET/api/attachment/listlist列出当前地址保存的全部附件键POST/api/attachment/put_urlgetSignedPutUrl获取上传预签名 URLPOST/api/attachment/get_urlgetSignedGetUrl获取下载预签名 URLPOST/api/attachment/deletedeleteKey删除指定附件对象S3 Client 初始化getS3Client使用aws-sdk/client-s3构建客户端region固定为auto适配 R2 无需分区的特性endpoint取S3_ENDPOINT凭据取S3_ACCESS_KEY_ID与S3_SECRET_ACCESS_KEY任一配置缺失时直接抛出S3 config is not set错误与isS3Enabled的四项检查保持一致。对象键Key组织规则按地址隔离所有对象键都遵循${address}/${key}的命名空间约定见 s3_attachment.tsaddress来自 JWT 载荷c.get(jwtPayload).address保证每个邮箱地址只能访问属于自己的附件上传时前端提交的原始key即邮件附件文件名如one-api.db会被拼接为地址/文件名写入 Bucket列表接口通过ListObjectsV2Command以Prefix: ${address}/过滤并去掉前缀后返回纯净的 key 列表删除接口同样按地址/key精确删除防止越权操作。预签名 URL 机制上传和下载都不经过 Worker 转发文件二进制流而是用aws-sdk/s3-request-presigner的getSignedUrl生成有效期默认 360 秒的预签名 URL前端直接对 S3/R2 发起PUT上传与GET下载。这意味着大文件流量不消耗 Worker 的计算配额浏览器与对象存储之间直连是本功能降低 Worker 负载的核心设计。前端调用链路从收件箱到 S3 附件页保存附件到 S3在收件箱打开邮件附件详情时若isS3Enabled为 trueMailContentRenderer.vue 会渲染“保存到S3”按钮文案见 message-registry.ts。点击后由 Index.vue 中的saveToS3执行两步调用POST /api/attachment/put_url携带{ key: filename }换取预签名上传 URL用该 URL 直接将附件 blobPUT到 S3/R2成功后提示“保存到S3成功”。对应界面如 s3-save.png 所示附件详情弹窗展示文件名如one-api.db与大小右侧为“保存到S3”操作按钮。S3 附件页列表、下载与删除启用后主界面出现“S3附件”标签页Index.vue对应视图 Attachment.vue页面加载时调用GET /api/attachment/list拉取当前地址的附件键列表渲染为 key 操作两列表格点击“下载”时调用POST /api/attachment/get_url获取预签名 URL弹出下载确认框最终通过带download属性的链接在新窗口下载文件名中的/会被替换为_见 Attachment.vue点击“删除”时经NPopconfirm二次确认后调用POST /api/attachment/delete删除对象成功后刷新列表。对应界面如 s3-download.png 所示顶部导航高亮“S3附件”标签表格中展示存储键如3/7/one-api.db即“地址/文件名”拼接形态与下载操作按钮。与相关功能的边界与扩展附件是否在收件时就进入 S3从源码看S3 只保存用户主动点击“保存到S3”的附件常规邮件的附件仍走项目自身的解析与存储流程如邮件解析产物存 D1、原始邮件可启用 gzip 压缩见 wrangler.toml.template 中的ENABLE_MAIL_GZIP。若想整体丢弃大附件可另行配置REMOVE_EXCEED_SIZE_ATTACHMENT或REMOVE_ALL_ATTACHMENT同为 wrangler.toml.template 中的可选开关二者与 S3 附件是互补而非替代关系。Webhook 附件下载走独立的BACKEND_URL签名链接机制见 webhook_attachment.ts 与 wrangler.toml.template 中BACKEND_URL配置与 S3 附件页的下载是两条并行链路互不干扰。若你的 Worker 同时启用了 Telegram 推送附件ENABLE_TG_PUSH_ATTACHMENT请知悉其受 50MB 单文件上限约束S3 附件页则无此限制。常见问题排查思路前端不显示“S3附件”标签或“保存到S3”按钮检查四个 secret 是否全部注入任缺一个isS3Enabled即为 false可在浏览器访问/api/settings确认isS3Enabled字段值。上传/下载出现 CORS 报错核对 R2 Bucket 的 CORS 策略是否放行了你的前端域名及对应 HTTP 方法。预签名 URL 过期确认S3_URL_EXPIRES取值是否合理默认 360 秒下载弹窗停留过久导致 URL 失效时可重新点击下载刷新 URL。使用非 R2 的 S3 服务时行为异常文档明确建议此时提交 issue 反馈因为项目主要针对 R2 适配。总结S3 附件是 cloudflare_temp_email 的可选增强能力通过 Cloudflare R2或任意 S3 兼容服务承载邮件大附件配合四个 secret 的最小化配置即可生效。后端按邮箱地址组织对象键并以预签名 URL 直连对象存储前端提供保存、列表、下载、删除的完整闭环既释放了 Worker/D1 的存储压力也让临时邮箱的用户体验更接近正式邮箱服务。【免费下载链接】cloudflare_temp_emailCloudFlare free temp domain email 免费收发 临时域名邮箱 支持附件 IMAP SMTP TelegramBot项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare_temp_email创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
