拆解 Hyvor Relay 整体架构:PHP Symfony + Go Worker + SvelteKit 如何实现一套自托管 Email API
拆解 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。
🗺️ 二、架构全景图:一张图看懂三大技术栈
从上图中可以读出整个实例的分工:
- 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 做的事非常克制:
- 校验发件域名是否已注册且状态允许发信;
- 校验收件人数量上限;
- 按项目类型(transactional / distributional)选定队列;
- 由 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/,按受众分成三块路由:
(marketing)/:官网落地页与产品文档,SvelteKit 直接做 SEO 友好的静态页;console/:开发者控制台——查看 Sends 日志、域名验证、API Key、Webhook、抑制列表;sudo/:管理员后台——Server 列表、IP 与 PTR 校验、队列分配、健康检查、调试面板。
Sudo 后台:可以直观看到每台 Server 的 IP、所属队列与 PTR 校验状态。
Console 里查看每封邮件的完整 SMTP 对话,排障时非常直观:
域名验证时,控制台会直接给出需要添加的 DNS 记录(DKIM/SPF 等):
📬 六、一封邮件的完整旅程
把上面各部分串起来,一封邮件的生命周期是这样的:
- 发起:你的系统调用
POST /api/console/sends(可用 Postman 或任意 HTTP 客户端),Symfony 校验后把邮件写入 Postgres 队列并立即返回; - 投递:Go Email Worker 用
SKIP LOCKED抢到这封邮件,按目标域名分组,通过 SMTP 投递,重试与 Greylisting 自动处理; - 记录:每次尝试经 Local API 回写,形成可回溯的 SendAttempt 日志;
- 回执:对端返回退信(DSN)或投诉(ARF),落在 Incoming SMTP Server,解析后更新抑制列表并触发 Webhook;
- 通知:Webhook Workers 把
send.bounced、send.delivered等事件推送到你的回调地址。
🚀 七、部署形态:一个镜像,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 个设计点
- Postgres 当消息队列:
SKIP LOCKED一行 SQL 解决分布式任务抢占,少维护一套中间件; - 按 IO 特征分语言:PHP 写业务与 API 快、Go 扛 SMTP/DNS/HTTP 推送这类高并发 IO,各取所长;
- Local API 做内部总线:进程间通信也走 HTTP 接口,边界清晰、可测试;
- 队列隔离 IP 信誉:事务邮件与营销邮件走不同队列和 IP,是邮件投递率的实用技巧;
- 观测先行:Prometheus 指标 + 完整 SMTP 会话留痕,自托管服务"敢自托管"的前提。
总结
Hyvor Relay 用 PHP Symfony(业务大脑)+ Go Worker(邮件通道)+ SvelteKit(双控制台)+ Postgres(数据兼队列) 组成了一个可水平扩展的自托管 Email API。它的架构没有炫技的组件,却把"发信、回执、排障、扩容"这条主链路打磨得很完整——如果你想自己掌控邮件基础设施,这套代码是很好的蓝本。




