Skip to content

架构决策与兼容迁移 ​

本页记录构建本服务时做出的关键设计权衡(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;全部长度上限(subject 256B、name 128B、text/html 96 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_TOKENAUTH_TOKENS运行期会与 AUTH_TOKENS 合并去重;迁移时先写入新名 AUTH_TOKENS,待旧配置清理完毕后移除旧 secret
SENDER_DOMAINALLOWED_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 并存与切流核查步骤 ​

  1. 并行部署新 Worker:先保持旧 Worker 线上运行不中断,在独立名字或测试 workers.dev 域上线本服务,并确保双方的 send_email 已验证地址均已就绪。
  2. 多令牌灰度接管:将旧调用方正在使用的令牌与新生成的 32+ 位令牌同时写入 AUTH_TOKENS(逗号分隔),逐步把调用方请求路径从旧面板或旧地址切换至 POST /v1/send(无自定义头能力的旧面板可暂切至 POST /v1/panel)。
  3. 日志与探针验收:通过 GET /healthz 验证 200 且 checks 全部符合预期,使用 wrangler tail 观察 email_sent 结构化日志稳定出现后再下线旧 Worker 与旧 secret 别名。