项目全貌与快速部署
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本地运行时约束
- 入口模块只能保留
default导出:在src/index.ts中增加命名导出(例如export const)在tsc、Vitest 与pnpm run build:dry打包阶段均不会报错,但 Workers 运行时启动会直接报错拒绝加载。改动入口文件后务必执行pnpm run dev实际拉起一次。 - 本地模式无法真实发送邮件:
wrangler dev中调用send_email绑定不会触发云端发信,请求一路通过所有本地校验并在最后一步返回502 upstream_failed,该现象说明前置来源、鉴权与字段守卫已全数放行。
模式三:生产部署到 Cloudflare Workers
- 准备平台侧验证地址:在 Cloudflare Email Routing / Email Service 中完成发件域名及目标收件邮箱验证,并把真实地址填入
wrangler.local.jsonc(或你自己的部署副本)的send_email段落:allowed_sender_addressesallowed_destination_addresses
- 登录账号并注入加密密钥:
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- 本地冒烟、预打包与上线:
sh
pnpm run check && pnpm test
pnpm run build:dry
pnpm run deploy:local- 先用
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 确认所有配置开关组合与常见故障处理方法。