Skip to content

Cloudflare Email Relay基于 send_email 的 HTTP 发信网关

跑在 Cloudflare Workers 上的受控邮件转发接口:来源 IP 白名单、常数时间多令牌轮换、边缘限流与严格报文校验。

能力定位与明确边界 ​

能做到什么程度(已实现能力)

  • 配置驱动的边缘邮件中继:暴露标准 POST /v1/send、旧面板兼容 POST /v1/panel 及 7 项配置就绪检查 /healthz,完全通过 Cloudflare 原生 EMAIL(send_email)绑定投递。
  • 失败关闭的认证与轮换:在读取 128 KiB UTF-8 JSON 前执行 CF-Connecting-IP IPv4/IPv6/CIDR 白名单与 RATE_LIMITER 检查;AUTH_TOKENS 支持零停机多密钥轮换与 SHA-256 常数时间全遍历异或校验。
  • 严格报文归一化与脱敏日志:精确按 UTF-8 字节上限(主题 256 B、正文 text/html 各 96 KiB)校验并拦截未知字段,日志绝不输出令牌或正文。

明确不能做什么(非目标与硬限制)

  • 无模板引擎、无附件、无第三方驱动:不接入 Resend、MailChannels 或外部 SMTP,不支持邮件附件、自定义邮件头、URL query 参数或 gzip 压缩请求体(415)。
  • 受限于平台绑定且不担保送达:200 OK 仅表示 Cloudflare EMAIL 绑定已受理;wrangler.jsonc 中的收发地址白名单独立于代码运行,本地 wrangler dev 无法外发真邮件(到发信步返 502)。

拓扑示意预览 ​

拓扑画布说明

下方交互式画布为保留的静态概念拓扑资源;实际源码已收敛为 Cloudflare Workers 原生 send_email(EMAIL 绑定)、POST /v1/send、POST /v1/panel 与 GET/HEAD /healthz,不含画布历史标签中标注的模板渲染器或 Resend/MailChannels 驱动。精确的实时请求链路请查阅 请求链路与交互架构图。

邮件中继服务概念拓扑画布(支持平移、缩放与节点检索)

离线验证与本地仿真速览 ​

sh
# 1. 在仓库根目录安装依赖并运行类型检查与 86 项 Vitest 回归(使用模拟绑定)
pnpm install --frozen-lockfile
pnpm run check && pnpm test

# 2. 复制模板变量并启动本地仿真(本地模式无法真实投递 send_email,到达上游步骤返 502 即表示前置守卫全通)
cp .dev.vars.example .dev.vars
pnpm run dev

向本地或线上端点提交标准发信请求示例(示例域名与占位令牌仅作格式演示):

sh
curl -X POST "https://relay.example.com/v1/send" \
  -H "Authorization: Bearer <32_to_512_char_token>" \
  -H "Content-Type: application/json" \
  -d '{"from":"alert@example.com","to":"ops@example.org","subject":"构建失败","text":"请检查构建日志"}'

文档分层导航 ​

按照读者需求快速跳转