拆解 Hyvor Relay 整体架构:PHP Symfony + Go Worker + SvelteKit 如何实现一套自托管 Email API

原创2026-10-23 14:06:321,754 阅读

拆解 Hyvor Relay 整体架构:PHP Symfony + Go Worker + SvelteKit 如何实现一套自托管 Email API

Hyvor Relay 是一款开源的自托管 Email API,可看作 SES、Mailgun、SendGrid 的自托管替代方案:通过一个 HTTP 接口发信,底层用你自己的 SMTP 基础设施投递。它的技术栈分工非常清晰——PHP Symfony 负责 API 与业务大脑,Go Worker 负责收发信、DNS 与 Webhook,SvelteKit 负责管理界面。本文拆解这套架构的设计思路,帮你看懂一个生产级邮件服务是如何落地的。

🧭 一、Hyvor Relay 是什么

Hyvor Relay 的定位可以概括为一句话:"用简单 API 发邮件,基础设施自己掌控"。它把商业邮件服务里的核心能力全部内置了:

能力 说明
多租户 & 项目隔离 支持组织内多个互相隔离的 Project
双队列 transactional / distributional 两条队列,隔离 IP 信誉
自动重试 & Greylisting 处理 对端拒绝时自动排队重发
退信(Bounce)处理 自动解析 DSN/ARF 回执
抑制列表(Suppressions) 自动管理退订、无效地址
DNS 自动化 内置 DNS Server,SPF/DKIM/MX 记录自动托管
Webhooks 邮件事件以 HTTP 回调推送
可观测性 Prometheus 指标、Grafana 看板、30 天 SMTP 会话日志

功能清单可参考 README.md。

🗺️ 二、架构全景图:一张图看懂三大技术栈

Hyvor Relay Email API 整体架构图:Symfony API、Go Email Worker、SMTP/DNS Server 与 Postgres 队列协同

从上图中可以读出整个实例的分工:

  • Docker Swarm 里跑多个 Server 节点,外加一个 Postgres 数据库;
  • 每个 Server 是一个 host network 的 Docker 容器,里面同时装着:HTTP API(80/443)、SMTP 收信服务(25/587)、DNS Server(53)、Email Workers、Webhook Workers 和一个 IP Pool。

三个代码目录与技术栈一一对应,这是理解整个项目的钥匙:

目录 技术栈 职责
/backend PHP 8.4 + Symfony 7.4 + FrankenPHP REST API、业务逻辑、管理面
/worker Go(单二进制) 发信、收信、DNS、Webhook、指标
/frontend SvelteKit + TypeScript 官网文档、开发者控制台、管理后台

🧠 三、PHP Symfony 后端:Email API 的"大脑"

1. 依赖选型:现代 Symfony 全家桶

从 backend/composer.json 可以看到后端的关键选型:

  • FrankenPHP(runtime/frankenphp-symfony):用 PHP 做常驻 Web 服务器,性能远超传统 FPM;
  • Doctrine ORM + DBAL:实体与数据库迁移;
  • Symfony Messenger:异步消息总线,传输层直接复用 Postgres;
  • Scheduler / RateLimiter / Lock:定时任务、API 限流、分布式锁一应俱全。

2. 三层 API,权限各管各的

后端把 HTTP 接口分成了 4 类,目录结构非常整齐:

  • Console API(/api/console/...):开发者用的 Email API——发信、查日志、管域名/API Key/Webhook,见 SendController.php;
  • Sudo API(/api/sudo/...):管理员用的运维接口,如 IP、DNS 记录、健康检查;
  • Local API(/api/local/...):仅内部使用,是 Go Worker 与 PHP 通信的"私有走廊",如 /state(下发配置)和 /send-attempts/done(回报发送结果),见 LocalController.php;
  • Root API:/health 健康检查。

3. 发信入口:只写库,不直接发

调用 POST /api/console/sends 时,SendController.php 做的事非常克制:

  1. 校验发件域名是否已注册且状态允许发信;
  2. 校验收件人数量上限;
  3. 按项目类型(transactional / distributional)选定队列;
  4. 由 SendService.php 把邮件写入数据库并标记为 queued。

请求到此结束,毫秒级返回——真正的 SMTP 发送完全异步,交给 Go Worker。

⚙️ 四、Go Worker:一个二进制包揽四大服务

Go 部分的设计是"一个进程 = 一个邮件网关"。入口 worker/main.go 启动后做三件事:起一个本地 HTTP 服务供 Symfony 更新配置、从 /local/state 拉取 GoState 配置(IP 池、TLS 证书、DNS 记录、Worker 数量、是否 Leader)、然后拉起各服务池。

服务 作用 关键代码
Email Workers 从 Postgres 抢任务并发 SMTP email_worker.go
Incoming SMTP Server 收 25/587 端口的退信/投诉回执 incoming_server.go
Bounce 解析 解析 DSN / ARF 协议报文 worker/bounceparse/
DNS Server 托管实例的 SPF/DKIM/MX 记录 worker/dns.go
Webhook Workers 向用户系统推送 HTTP 事件 worker/webhooks.go

并发抢任务的精髓:FOR UPDATE SKIP LOCKED

多 Server 节点同时消费同一个队列时,靠的是数据库行锁:send_pg.go 中用 SELECT ... FOR UPDATE SKIP LOCKED 原子地"领取"一封邮件。这条 SQL 让 Postgres 同时充当数据库和消息队列——不需要 Kafka、RabbitMQ 这类额外中间件,部署和运维成本直线下降。

发信结果再通过 /local/send-attempts/done 回报给 Symfony,写入 SendAttempt,控制台里 30 天内可查完整 SMTP 会话。

🖥️ 五、SvelteKit 前端:Console + Sudo 双控制台

前端源码在 frontend/src/routes/,按受众分成三块路由:

  1. (marketing)/:官网落地页与产品文档,SvelteKit 直接做 SEO 友好的静态页;
  2. console/:开发者控制台——查看 Sends 日志、域名验证、API Key、Webhook、抑制列表;
  3. sudo/:管理员后台——Server 列表、IP 与 PTR 校验、队列分配、健康检查、调试面板。

Sudo 后台:可以直观看到每台 Server 的 IP、所属队列与 PTR 校验状态。

Hyvor Relay Sudo 管理后台界面截图:显示多服务器 IP 地址与队列分配

Console 里查看每封邮件的完整 SMTP 对话,排障时非常直观:

Hyvor Relay 开发者 Console 界面截图:显示邮件事件与 SMTP 发送会话日志

域名验证时,控制台会直接给出需要添加的 DNS 记录(DKIM/SPF 等):

Hyvor Relay 控制台 DNS 记录配置界面截图:显示 DKIM TXT 记录内容

📬 六、一封邮件的完整旅程

把上面各部分串起来,一封邮件的生命周期是这样的:

  1. 发起:你的系统调用 POST /api/console/sends(可用 Postman 或任意 HTTP 客户端),Symfony 校验后把邮件写入 Postgres 队列并立即返回;
  2. 投递:Go Email Worker 用 SKIP LOCKED 抢到这封邮件,按目标域名分组,通过 SMTP 投递,重试与 Greylisting 自动处理;
  3. 记录:每次尝试经 Local API 回写,形成可回溯的 SendAttempt 日志;
  4. 回执:对端返回退信(DSN)或投诉(ARF),落在 Incoming SMTP Server,解析后更新抑制列表并触发 Webhook;
  5. 通知:Webhook Workers 把 send.bounced、send.delivered 等事件推送到你的回调地址。

使用 Postman 调用 Hyvor Relay Email API 发送接口的截图

🚀 七、部署形态:一个镜像,Swarm 水平扩展

1. 多阶段 Dockerfile

根目录的 Dockerfile 采用多阶段构建:node 阶段构建 SvelteKit 前端、golang 阶段编译出 Go 单二进制、frankenphp 阶段安装 PHP 依赖。生产 final 阶段把三者打进同一个镜像——所以官方镜像里 API、Worker、前端全部自包含。

2. 容器内多进程 + 容器间多副本

容器内部用 supervisord 管理进程(见 meta/image/prod/supervisord.conf):FrankenPHP(API)、Go worker、以及 3 个 Messenger 消费者(async + 两个 scheduler)。容器之间则靠 Docker Swarm 的 mode: global + host 网络(见 deploy/prod/compose.yaml)做到"每个节点恰好一个副本",天然适配"每机多 IP"的邮件基础设施模型。

3. 本地体验

仓库自带开发用 Compose 文件(compose.yaml),并内置 SMTP 模拟器,可以本地触发 tempfail、退信等场景。文档见 DEV.md。想克隆下来跑一遍,仓库地址是 https://gitcode.com/gh_mirrors/relay34/relay。监控侧还附带了 Grafana 看板 与 Alertmanager 告警规则。

💡 八、新手可以借鉴的 5 个设计点

  1. Postgres 当消息队列:SKIP LOCKED 一行 SQL 解决分布式任务抢占,少维护一套中间件;
  2. 按 IO 特征分语言:PHP 写业务与 API 快、Go 扛 SMTP/DNS/HTTP 推送这类高并发 IO,各取所长;
  3. Local API 做内部总线:进程间通信也走 HTTP 接口,边界清晰、可测试;
  4. 队列隔离 IP 信誉:事务邮件与营销邮件走不同队列和 IP,是邮件投递率的实用技巧;
  5. 观测先行:Prometheus 指标 + 完整 SMTP 会话留痕,自托管服务"敢自托管"的前提。

总结

Hyvor Relay 用 PHP Symfony(业务大脑)+ Go Worker(邮件通道)+ SvelteKit(双控制台)+ Postgres(数据兼队列) 组成了一个可水平扩展的自托管 Email API。它的架构没有炫技的组件,却把"发信、回执、排障、扩容"这条主链路打磨得很完整——如果你想自己掌控邮件基础设施,这套代码是很好的蓝本。

登录后查看全文
relay