家里自建了 DNS(OxiDNS、mosdns、AdGuard Home 之类),海外域名解析迟早会碰到一个老问题:公共 DoH 在国内直连不稳定,延迟飘得厉害;自己搭一台 VPS 当转发器,又得多操心一台机器的安全、续费和带宽。
doh-relay 就是为这个场景写的小工具——把 DoH 中转部署到 Vercel 或 Cloudflare Workers 这类边缘函数平台上,对外提供标准 DoH 接口,请求原样转发给上游,不解析、不改写、不注入 ECS。不用服务器,一份代码两个平台都能跑。
1. 什么情况下用得上
- 自建 DNS 需要海外解析出口,但不想为这一件事长期养一台 VPS。
- 希望查询走加密通道,并且中转地址带密钥、能按 IP 限流,不想被别人白嫖额度。
- 上游不止一个,主上游挂了能自动切备用,调用方不用自己写重试。
- 已经在用 Cloudflare 或 Vercel,想顺手把 DoH 出口也放到边缘节点上。
一句话总结:你只想要一个干净的「DoH 转发出口」,不想为它单独维护服务器,这个工具就对路。
2. 设计上做的是减法
- 纯透传:DNS 报文原样转发给上游,不解析、不改写、不注入 ECS。
- 不做分流:国内外分流是调用方(你的 mosdns / OxiDNS)的职责,中转只负责转发,不掺和判断。
- 内置三件套:实例内 TTL 缓存、按客户端 IP 限流、上游自动故障切换。
- 两个平台共用一份代码:核心逻辑只依赖 Web 标准 API(
fetch、TextEncoder、DataView、atob、AbortController),不碰Buffer、process.env等 Node 专有模块,Workers 侧无需开启nodejs_compat。 - 零依赖、无构建步骤,没有第三方包。
目录结构也能看出这种分层——核心只有一份,平台差异被两个极薄的适配层挡在外面:
| 文件 | 作用 |
|---|---|
lib/doh.js | 平台无关核心:DNS 报文解析、上游转发、缓存、限流 |
lib/test-query.js | 构造测试查询报文 |
api/dns-query.js | Vercel 适配层(Node req/res) |
api/health.js | Vercel 适配层 |
worker/index.mjs | Cloudflare Workers 适配层(Web Request/Response) |
vercel.json / wrangler.jsonc | 两个平台各自的路由与运行配置 |
3. 接口长什么样
两个平台的路由完全一致:
| 方法 | 路径 | 说明 |
|---|---|---|
GET / POST | /<DOH_SECRET>/dns-query | 主入口;POST 需带 Content-Type: application/dns-message |
GET | /<DOH_SECRET>/dns-query?dns=<base64url> | RFC 8484 的 GET 形式 |
GET | /<DOH_SECRET>/dns-query?name=example.com&type=A | 调试用,由服务端构造查询 |
GET | /dns-query?secret=<DOH_SECRET> | 直连形式,路径带密钥不可用时使用 |
GET | /api/health 或 /health | 健康检查,返回 JSON |
响应是 application/dns-message 二进制报文,Cache-Control: no-store。密钥不匹配返回 404,触发限流返回 429,两个上游都失败则返回 SERVFAIL 报文而不是挂起,调用方可以自行 fallback。
4. 配置项
| 环境变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
DOH_SECRET | 是 | 无 | 路径中的密钥;为空时路径不受保护,仅打警告 |
UPSTREAM_PRIMARY | 否 | https://dns.google/dns-query | 主上游 |
UPSTREAM_FALLBACK | 否 | https://cloudflare-dns.com/dns-query | 备用上游 |
UPSTREAM_TIMEOUT_MS | 否 | 3000 | 单个上游超时(毫秒) |
RATE_PER_MIN | 否 | 120 | 每客户端 IP 每分钟请求上限 |
密钥用 openssl rand -hex 16 生成,通过平台的环境变量 / secret 机制注入,不要写进代码或提交到仓库。
5. 部署到 Vercel
- 把仓库导入 Vercel,Framework Preset 选 Other(没有构建步骤)。
- Settings → Environment Variables 添加
DOH_SECRET,其余变量按需。 - 加完变量后 Redeploy 一次,环境变量才会生效。
- Settings → Functions → Function Region 选 Tokyo (hnd1)。
vercel.json里已写regions: ["hnd1"],但默认区域是美国东部,不改会多出约 200ms。香港(hkg1)虽然也在可选列表里,底层是 AWS opt-in 区,对等质量与容量优先级靠后,晚高峰抖动明显,不建议。 - 部署完成后地址是
https://<项目名>.vercel.app/<DOH_SECRET>/dns-query。
6. 部署到 Cloudflare Workers
npx wrangler login
npx wrangler secret put DOH_SECRET # 粘贴随机串
npx wrangler deploy部署后地址为 https://doh-relay.<你的子域>.workers.dev/<DOH_SECRET>/dns-query。非敏感变量已写在 wrangler.jsonc 的 vars 中,改完重新 deploy 即可。
要绑自定义域名,在 wrangler.jsonc 里加:
"routes": [{ "pattern": "doh.example.com", "custom_domain": true }]注意:Workers 的自定义域名要求该域名的 NS 托管在同一个 Cloudflare 账号下,不支持 CNAME 接入。如果域名 NS 在别家(比如在 DNSPod),就只能继续用
workers.dev地址,或者走 Vercel 那边 CNAME 接入。
本地想跑真实的 Workers 运行时(workerd,行为与线上一致):
echo 'DOH_SECRET=testsecret' > .dev.vars
npx wrangler devVercel 侧对应 vercel dev。查线上日志,Workers 用 npx wrangler tail,Vercel 去 Dashboard → Logs。
7. 两个平台怎么选
| 对比项 | Vercel Hobby | Cloudflare Workers Free |
|---|---|---|
| 额度 | 100 万调用/月、100GB 带宽、4 CPU 小时/月,超额暂停不扣费 | 10 万请求/天,CPU 10ms/次,超额返回 1027 |
| 出口位置 | 可固定为 hnd1 东京,延迟可预期 | 离客户端最近的边缘节点,不固定 |
| 自定义域名 | 支持 CNAME 接入任意 DNS | 要求域名 NS 托管在同一 Cloudflare 账号 |
| 日志 | Dashboard → Logs | Workers Logs + wrangler tail |
个人量级(每天几千次查询)在两边都远低于额度。想要延迟数字稳定,选 Vercel 固定东京区域;想要到上游的链路更短、排障更方便,选 Workers。也可以两个都部署,在上游配置里互为主备。
8. 验证部署
# 1. 健康检查
curl https://<地址>/api/health
# 期望 {"ok":true,"platform":"...","region":"...","upstream":"...","fallback":"..."}
# 2. 真实查询(返回二进制 DNS 报文,不是 JSON)
curl -s "https://<地址>/<DOH_SECRET>/dns-query?name=example.com&type=A" | xxd | head
# 3. 错误密钥应返回 404
curl -o /dev/null -w "%{http_code}\n" "https://<地址>/wrongsecret/dns-query?name=example.com&type=A"
# 4. 量延迟
curl -w "%{time_total}\n" -o /dev/null -s https://<地址>/api/healthplatform 字段会返回 vercel 或 cloudflare-workers,方便确认当前命中的是哪个部署。单次查询超过 8 秒说明链路异常,先查上游。
9. 这些坑提前知道
- 不要公开中转地址(含密钥)。 地址泄露后被滥用会烧掉额度(Vercel 超额暂停到下个周期,Workers 超额直接返回 1027)。注意要保密的是部署地址和里面的密钥,不是源码仓库:
DOH_SECRET通过环境变量注入,代码里没有硬编码,仓库的.gitignore也已排除.dev.vars、.env、*.pem、*.key,所以公开仓库并不会泄露密钥。README 里「建议设为私有」是保守做法,想开源分享就保持公开,只要别把本地密钥文件和真实地址提交上去即可。 - 缓存和限流都是实例内内存。 函数实例或 isolate 回收后即清空,跨实例不共享,只能减少上游调用,不能当作可靠的配额控制。
- 上游超时策略:每个上游只尝试一次,最坏
3s + 3s = 6s返回;两个上游都失败返回 SERVFAIL 报文而非挂起。 - Workers 免费版 CPU 上限 10ms/请求。 当前逻辑只遍历 DNS 报文头部和记录,实测远低于上限,但别往里加重型处理(大报文改写、ECS 注入等)。
- 不要设置
Connection: close这类逐跳头部。 Workers 与 Node 对它们的处理不一致,代码里已省略。 - 平台条款风险:Cloudflare 会限制把 Workers 当纯代理/隧道使用。DoH 报文体积很小,不属于带宽滥用,但若被判定为纯代理服务,可能被限流。
- 免费额度的出口 IP 是共享的,上游 DoH 对这些 IP 的策略可能变化;出现大面积失败时先确认上游本身是否可用。
项目地址
代码开源,仓库公开不影响安全——密钥走环境变量、不进代码,.gitignore 也挡住了本地密钥文件。真正要保管好的是部署地址和 DOH_SECRET 本身。