架构决策与兼容迁移
本页记录构建本服务时做出的关键设计权衡(ADR),以及从历史环境变量命名迁移至现行规范时的兼容过渡指南。
关键架构决策(ADR)
ADR-01:先读入有界 JSON 体、后执行鉴权,但严格后置业务字段校验
- 背景:标准路径
/v1/send从Authorization头读取令牌,但兼容面板路由/v1/panel的调用方无法发送自定义请求头,只能把token放入 JSON 体。 - 决策:在
handleSend中将readJsonBody(含 128 KiB 字节计数与严格 UTF-8 解码)放在tokenMatches之前,而将buildMessage(字段白名单与域名校验)严格留在鉴权成功之后。 - 取舍:面板路径获得兼容能力的同时,未授权方无法利用未认证请求探测业务字段规则(未过鉴权一律只返
401);而面板若同时在头与体传递合法令牌则返400 credentials_ambiguous,杜绝轮换期间因猜测优先级导致的假象。
ADR-02:失败关闭的来源控制与显式降级开关
- 背景:云端 CI 构建器出口 IP 动态变化,早期运维习惯用
IP_ALLOWLIST=""或*绕过拦截,容易把「配置漏填」和「有意放开」混为一谈。 - 决策:将
IP_ALLOWLIST留空且未关闭检查时判定为ConfigError(返回503而非放行);引入独立开关IP_ALLOWLIST_ENABLED,即便设为0仍要求请求存在CF-Connecting-IP、仍解析非空名单里的语法错误,并在每次发信请求打印一条ip_allowlist_disabled警告日志。 - 取舍:日志量略微增加(通过单请求级警告避开跨请求 isolate 共享状态陷阱),换来对生产安全降级状态的持续可观测性与零静默漏放。
ADR-03:未知字段拒收与 UTF-8 字节计量
- 背景:JSON 调用方拼错可选字段名(如把
cc写成ccs)或依赖字符数限制中文邮件时,静默忽略或按字符放行会造成静默漏发或载荷膨胀。 - 决策:使用
STANDARD_FIELDS/PANEL_FIELDS严密集合,出现任何未列明字段即抛FieldError返回400 invalid_field;全部长度上限(subject256B、name128B、text/html96 KiB)均通过TextEncoder按 UTF-8 字节核验;英文报错信息作为稳定契约供下游断言。 - 取舍:对拼写零容忍,换取调用集成阶段的即时反馈与可控的内存配额。
ADR-04:请求路径与 /healthz 共享同一套校验函数
- 背景:健康探针若只校验
env.VAR !== undefined,在密钥过短或 CIDR 写坏时探针仍返200,而每封发信请求却报503。 - 决策:
loadConfig与inspectConfig共用readTokens、readSenderDomains、readIpAllowlist与readMaxRecipients四组读取器;任何「存在但非法」的配置都会令/healthz返回503,而选配的RATE_LIMITER仅在「已绑定却不可调用」时才阻塞就绪。 - 取舍:探针状态能真实反映发信路径是否可用,杜绝假绿灯。
配置别名与历史端平滑迁移指南
为实现从旧版 Worker 到当前实现的零停机过渡,src/config.ts 在读取阶段对以下旧变量名保留过渡兼容(新名优先、合并去重):
| 旧环境变量 / 写法 | 现行标准变量名 | 兼容规则与迁移建议 |
|---|---|---|
AUTH_TOKEN、WEBHOOK_TOKEN | AUTH_TOKENS | 运行期会与 AUTH_TOKENS 合并去重;迁移时先写入新名 AUTH_TOKENS,待旧配置清理完毕后移除旧 secret |
SENDER_DOMAIN | ALLOWED_SENDER_DOMAINS | 与 ALLOWED_SENDER_DOMAINS 合并归一化;切记裸域与 *. 通配需并列写全(如 example.com,*.example.com) |
IP_ALLOWLIST="*" | IP_ALLOWLIST_ENABLED="0" | * 仍可被识别为关闭来源限制,但严禁与 IP_ALLOWLIST_ENABLED=1 共存(否则报 503);建议改用 IP_ALLOWLIST_ENABLED="0" 以保留历史白名单列表 |
旧 Worker 并存与切流核查步骤
- 并行部署新 Worker:先保持旧 Worker 线上运行不中断,在独立名字或测试
workers.dev域上线本服务,并确保双方的send_email已验证地址均已就绪。 - 多令牌灰度接管:将旧调用方正在使用的令牌与新生成的 32+ 位令牌同时写入
AUTH_TOKENS(逗号分隔),逐步把调用方请求路径从旧面板或旧地址切换至POST /v1/send(无自定义头能力的旧面板可暂切至POST /v1/panel)。 - 日志与探针验收:通过
GET /healthz验证200且checks全部符合预期,使用wrangler tail观察email_sent结构化日志稳定出现后再下线旧 Worker 与旧 secret 别名。