Skip to content

项目全貌与快速部署 ​

Cloudflare Email Relay 是一个运行在 Cloudflare Workers 上的 HTTP 邮件转发服务,把经身份鉴权与结构校验的 JSON 请求通过平台原生 send_email(EMAIL)绑定交给 Cloudflare Email Service 发送。仓库源码内不写死任何域名、收发地址或密钥,全部规则由部署配置注入。

运行边界与非目标 ​

在上线或接入前,先明确当前实现做什么与刻意不做什么:

维度当前提供能力明确不在支持范围内
发信通道原生 send_email 绑定(EMAIL)不接入 MailChannels、Resend 或外部 SMTP 服务器
报文内容纯文本 text 与 HTML 字符串 html(各上限 96 KiB)不内置 HTML 模板渲染引擎、不支持附件或自定义邮件头
接口路径POST /v1/send、POST /v1/panel、GET/HEAD /healthz不提供 /send-email、不接受 URL query 参数与压缩请求体
结果语义200 返回 messageId 与规范化 accepted 清单不保证收件箱真实送达;平台侧发信绑定限制独立于代码白名单

需逐字段核对 /v1/send、/v1/panel 与 /healthz 请求体 Schema 及标准 curl 示例?可直接前往交互式 API 与组件参考。

多模式运行与部署路径 ​

仓库提供三类日常工作流:离线规则验证、本地带绑定仿真,以及线上 Cloudflare Workers 部署。

模式一:离线类型检查与模拟绑定测试 ​

测试通过向 worker.fetch(Request, env) 注入假 EMAIL 与假 RATE_LIMITER 运行,不需要 Cloudflare 账号或网络连接:

sh
pnpm install --frozen-lockfile
pnpm run check
pnpm test

模式二:本地 HTTP 仿真(模板与私有隔离) ​

本地启动 wrangler dev 时,密钥写入被 .gitignore 忽略的 .dev.vars(从 .dev.vars.example 复制),绝不要写入跟踪的 wrangler.jsonc。

sh
# 1. 复制本地密钥模板并填入占位或测试令牌(32–512 位)与本地允许 IP
cp .dev.vars.example .dev.vars

# 2. 使用仓库模板启动本地仿真
pnpm run dev

本机私有配置隔离 ​

仓库内的 wrangler.jsonc 只保留公共占位值(如 example.com)。实际私有域名、已验证收发邮箱和自定义路由应放在不入库的 wrangler.local.jsonc 中,借助 package.json 内置脚本运行:

sh
cp wrangler.jsonc wrangler.local.jsonc
pnpm run dev:local      # 等价于 wrangler dev --config wrangler.local.jsonc
pnpm run deploy:local   # 等价于 wrangler deploy --config wrangler.local.jsonc

本地运行时约束

  1. 入口模块只能保留 default 导出:在 src/index.ts 中增加命名导出(例如 export const)在 tsc、Vitest 与 pnpm run build:dry 打包阶段均不会报错,但 Workers 运行时启动会直接报错拒绝加载。改动入口文件后务必执行 pnpm run dev 实际拉起一次。
  2. 本地模式无法真实发送邮件:wrangler dev 中调用 send_email 绑定不会触发云端发信,请求一路通过所有本地校验并在最后一步返回 502 upstream_failed,该现象说明前置来源、鉴权与字段守卫已全数放行。

模式三:生产部署到 Cloudflare Workers ​

  1. 准备平台侧验证地址:在 Cloudflare Email Routing / Email Service 中完成发件域名及目标收件邮箱验证,并把真实地址填入 wrangler.local.jsonc(或你自己的部署副本)的 send_email 段落:
    • allowed_sender_addresses
    • allowed_destination_addresses
  2. 登录账号并注入加密密钥:
sh
pnpm dlx wrangler login
pnpm dlx wrangler secret put AUTH_TOKENS --config wrangler.local.jsonc
pnpm dlx wrangler secret put IP_ALLOWLIST --config wrangler.local.jsonc
  1. 本地冒烟、预打包与上线:
sh
pnpm run check && pnpm test
pnpm run build:dry
pnpm run deploy:local
  1. 先用 workers.dev 验证,再绑定自定义域名:首次部署保持 workers_dev: true 验证 /healthz 与一次真实发信;确认无误后在配置中设 "workers_dev": false,并启用 "routes": [{ "pattern": "mail.example.com", "custom_domain": true }] 再次部署。

上线前核查清单 ​

  • 运行 git status,确认 .dev.vars 与 wrangler.local.jsonc 未出现在待跟踪或已暂存列表中。
  • 核对 ALLOWED_SENDER_DOMAINS 是否显式包含裸域(例如 example.com,*.example.com),而不仅仅写了通配项。
  • 核对 Cloudflare 控制台与 Wrangler send_email 绑定两处的收发地址列表是否一致。
  • 部署后立即请求 GET /healthz 或 curl -I https://<你的域名>/healthz,确认状态码为 200 且 checks 符合预期。

下一步请查阅 环境变量矩阵与排错 FAQ 确认所有配置开关组合与常见故障处理方法。