關(guān)：DoH原理與實(shí)戰(zhàn))
過去幾年很多開發(fā)者把個人主頁或項(xiàng)目文檔放到了 GitHub Pages、Gitee Pages 上以為“Pages”只是托個靜態(tài)網(wǎng)頁。但如果把目光放到 Cloudflare Pages你會發(fā)現(xiàn)它和 Workers 共用同一套邊緣運(yùn)行環(huán)境還能跑真正的服務(wù)端邏輯。一個很典型的玩法就是用 Workers 或 Pages Functions 自建一個加密 DNS 解析網(wǎng)關(guān)。先說一個明確判斷這篇文章要搭的“加密 DNS 服務(wù)器”并不是傳統(tǒng)意義上的權(quán)威 DNS 服務(wù)器而是一個帶隱私和可控策略的DoH 網(wǎng)關(guān)。它接收客戶端發(fā)來的 HTTPS 加密 DNS 請求再轉(zhuǎn)發(fā)給上游遞歸解析服務(wù)最后把結(jié)果返回給客戶端。通過這一層你可以擁有一個自定義域名的加密 DNS 入口還能統(tǒng)一加緩存、鑒權(quán)和解析策略。讀完這篇文章你能跑通兩件事一是用 Cloudflare Worker 實(shí)現(xiàn)一個支持 JSON 格式的 DoH 解析 API二是用 Cloudflare Pages 實(shí)現(xiàn)“靜態(tài)頁面 DNS 轉(zhuǎn)發(fā)函數(shù)”的一體化部署。文章里還會講 wire format 方式的實(shí)現(xiàn)思路、常見坑、鑒權(quán)和緩存策略方便你在生產(chǎn)環(huán)境中落地。1. 這篇文章真正要解決的問題不少人會有這樣的經(jīng)歷打開電腦連上 WiFi 后DNS 查詢默認(rèn)走路由器下發(fā)的地址在某些網(wǎng)絡(luò)環(huán)境下DNS 響應(yīng)被篡改、被加廣告、長時間無響應(yīng)問題排查起來非常被動。普通 DNS 請求是明文傳輸?shù)闹虚g設(shè)備確實(shí)有可能看到你在查詢哪些域名。所以現(xiàn)在越來越多人開始關(guān)注加密 DNS也就是 DoHDNS over HTTPS、DoTDNS over TLS這類方案。但直接使用公共 DoH 服務(wù)也有不舒服的地方公共地址大家都在用不方便統(tǒng)計(jì)自己的查詢量想在里面加一層“域名過濾”或“本地緩存”也比較麻煩。于是就有了“自建加密 DNS 網(wǎng)關(guān)”的需求。云服務(wù)商里Cloudflare Workers 和 Pages 是很適合做這件事的載體。它們不需要你買服務(wù)器不需要自己管證書和守護(hù)進(jìn)程寫完代碼直接發(fā)布到邊緣節(jié)點(diǎn)幾十行代碼就能把 DNS 查詢包一層 HTTPS。這篇文章真正適合的讀者有三類想搞懂 DoH 原理并希望用 Serverless 方式落地一個真實(shí)服務(wù)的開發(fā)者家里有多臺設(shè)備、多個網(wǎng)絡(luò)環(huán)境想統(tǒng)一一個自定義 DNS 入口的工程師Page 托管用戶想知道 Cloudflare Pages 除了托管靜態(tài)頁面還能做什么的人。也要提前說清楚邊界Cloudflare Workers 上跑的是“DNS 代理/轉(zhuǎn)發(fā)器”不是權(quán)威 DNS。你不能在這里面管理自己的域名記錄也不適合把它當(dāng)作大規(guī)模內(nèi)部 DNS 基礎(chǔ)設(shè)施。它的定位是“加密 DNS 入口 策略控制層”。2. 加密 DNS 基礎(chǔ)DoH、DoT、DoQ 概念與區(qū)別在進(jìn)入代碼之前先把幾個概念理清楚。很多文章把 DoH、DoT、DoQ 混著說初學(xué)者很容易被繞暈。2.1 明文 DNS 的問題普通 DNS 一般是客戶端向 53 端口發(fā)起 UDP 查詢。這個請求從你的電腦到路由器再到運(yùn)營商遞歸 DNS中間經(jīng)過的鏈路如果被監(jiān)聽對方可以看到你查詢的域名。更麻煩的是如果響應(yīng)被篡改客戶端可能被引導(dǎo)到錯誤的 IP 地址。2.2 三種主流加密 DNS 方式協(xié)議全稱傳輸方式默認(rèn)端口優(yōu)點(diǎn)弱點(diǎn)DoHDNS over HTTPSHTTPSHTTP/2 或 HTTP/3443和普通網(wǎng)頁流量混在一起難以被單獨(dú)識別瀏覽器支持度高實(shí)現(xiàn)相對復(fù)雜要求服務(wù)端支持 HTTPSDoTDNS over TLSTLS 專屬連接853實(shí)現(xiàn)簡單連接生命周期穩(wěn)定專用端口容易被網(wǎng)絡(luò)設(shè)備識別和封鎖DoQDNS over QUICQUIC基于 UDP853低延遲多路復(fù)用正在被主流客戶端逐步支持生態(tài)系統(tǒng)還不夠成熟客戶端支持較少這里最容易混淆的是 DoH 和 DoT。簡單記DoH 的流量是“HTTPS 請求”和你看網(wǎng)頁用的是同一個模型DoT 是“為 DNS 單獨(dú)開設(shè)一條 TLS 通道”。兩者都做了加密但在網(wǎng)絡(luò)中的“可見性”不同。2.3 DoH 的兩種數(shù)據(jù)格式文章后面會頻繁提到兩種格式application/dns-jsonJSON 格式適合開發(fā)調(diào)試、腳本調(diào)用也適合在 Worker 里直接處理 JSON 對象。瀏覽器地址欄直接訪問也能看到可讀結(jié)果。application/dns-message二進(jìn)制 DNS 消息格式和傳統(tǒng) DNS 報文結(jié)構(gòu)一致只是外面包了一層 HTTPS。系統(tǒng)級的原生 DoH 功能比如 Windows 上的自定義 DoH 模板通常使用這種格式。做網(wǎng)關(guān)時最簡單的是先做 JSON 格式因?yàn)榇a好寫、驗(yàn)證方便。但如果想讓手機(jī)系統(tǒng)或?yàn)g覽器原生 DoH 直接用就需要支持 wire format。2.4 加密 DNS 網(wǎng)關(guān)的請求鏈路用 Cloudflare Worker 實(shí)現(xiàn)的自建加密 DNS 網(wǎng)關(guān)請求鏈路是這樣的客戶端設(shè)備/瀏覽器 ↓ HTTPSDoH 請求 Cloudflare Worker自定義域名 ↓ 上游 DoH 請求 Cloudflare 公共 DNS 或其他遞歸 DNS ↓ DNS 明文解析 互聯(lián)網(wǎng)權(quán)威 DNS 服務(wù)器關(guān)鍵點(diǎn)在于客戶端和 Worker 之間是加密的Worker 和上游之間也走 DoH那么從網(wǎng)關(guān)出去的查詢也是加密的。中間只多了一層自己的策略邏輯。3. Workers 還是 Pages方案選型與適用場景很多讀者會問標(biāo)題里又說 Workers 又說 Pages到底該用哪個其實(shí) Cloudflare Pages Functions 底層就是 Workers 運(yùn)行時寫法也很接近。區(qū)別主要在于“你還需要不需要托管靜態(tài)資源”。維度Cloudflare WorkersCloudflare Pages部署目標(biāo)純函數(shù) / API靜態(tài)資源 Functions項(xiàng)目類型wrangler deploy發(fā)布 Worker構(gòu)建靜態(tài)站點(diǎn)后發(fā)布Functions 放在functions/目錄適用場景只想快速發(fā)布一個 API、網(wǎng)關(guān)、代理已有靜態(tài)站點(diǎn)希望站點(diǎn)接口也跑在同一域名下自定義域名通過 Worker 路由綁定Pages 自定義域名綁定免費(fèi)額度有每日請求量限制超出會停止服務(wù)同樣有免費(fèi)額度適合中小流量項(xiàng)目本地開發(fā)wrangler devwrangler pages dev選型建議很直接如果你只是想要一個 DNS API 或一個隱藏服務(wù)直接選 Worker項(xiàng)目結(jié)構(gòu)最簡潔。如果你想做一個“帶管理后臺的加密 DNS 控制臺”或者已經(jīng)有一個靜態(tài)站點(diǎn)希望把接口合到同一個域名下用 Pages 更舒服。不過要注意二者都跑在 Cloudflare 邊緣節(jié)點(diǎn)上。默認(rèn)域名是*.workers.dev或*.pages.dev這兩個域名雖然免費(fèi)但如果要做生產(chǎn)環(huán)境 DNS 入口建議綁定自己的域名。一來行為更可控二來在客戶端配置 DoH 地址時也更像正式服務(wù)。4. 環(huán)境準(zhǔn)備與前置條件開始寫代碼前先把環(huán)境準(zhǔn)備好。這里的核心依賴是 Cloudflare 的 wrangler 命令行工具。4.1 需要準(zhǔn)備的東西Cloudflare 賬號如果沒有先去官網(wǎng)注冊一個。免費(fèi)版足夠完成本文章的所有實(shí)驗(yàn)。Node.js 環(huán)境建議使用當(dāng)前 LTS 版本。wrangler 是 npm 包需要 Node 環(huán)境來安裝和運(yùn)行。一個域名可選但推薦如果域名已經(jīng)托管在 Cloudflare后面綁定自定義域名會非常方便。本地開發(fā)工具VS Code 或任意編輯器都可以。4.2 安裝 wrangler安裝命令npm install -g wrangler安裝完成后確認(rèn)版本wrangler --version如果網(wǎng)絡(luò)環(huán)境不允許全局安裝也可以把 wrangler 裝到項(xiàng)目本地npm init -y npm install -D wrangler然后通過npx wrangler使用本地命令。4.3 登錄 Cloudflare在項(xiàng)目目錄執(zhí)行wrangler login命令會打開瀏覽器讓你授權(quán) wrangler 訪問你的賬號。授權(quán)完成后wrangler 會把憑證保存到本地后續(xù)發(fā)布和部署都可以直接用。如果是在 CI/CD 環(huán)境中使用一般會用CLOUDFLARE_API_TOKEN環(huán)境變量代替交互登錄。本文章的家庭/個人部署場景直接wrangler login就夠了。4.4 創(chuàng)建項(xiàng)目目錄以最常用的 Worker 方案為例mkdir my-doh-gateway cd my-doh-gateway npm init -y后續(xù)代碼都放在這個目錄里。5. 方案一用 Worker 實(shí)現(xiàn) DoH JSON 解析 API這是最簡單、也最容易跑通的方案。整個 Worker 就是一段 JavaScript處理 GET 請求從 URL 參數(shù)里讀取域名和記錄類型再請求上游 DoH 服務(wù)把結(jié)果轉(zhuǎn)成 JSON 返回給客戶端。5.1 創(chuàng)建 wrangler.toml在項(xiàng)目根目錄創(chuàng)建wrangler.tomlname my-doh-gateway main src/index.js compatibility_date 2024-01-01name是 Worker 名稱會出現(xiàn)在部署后的默認(rèn)域名里。main指定入口文件。compatibility_date是 Cloudflare Workers 的兼容性日期按 wrangler 提示填寫即可不需要過度糾結(jié)。5.2 Worker 核心代碼創(chuàng)建src/index.jsconst UPSTREAM_DOH https://cloudflare-dns.com/dns-query; const VALID_TYPES [ A, AAAA, CNAME, MX, NS, TXT, SOA, SRV, CAA, HTTPS ]; function isValidDomain(name) { return /^(?.{1,253}$)(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)[a-zA-Z]{2,63}$/.test(name); } export default { async fetch(request, env, ctx) { const url new URL(request.url); if (request.method ! GET) { return new Response(Method Not Allowed, { status: 405 }); } const name url.searchParams.get(name); const type (url.searchParams.get(type) || A).toUpperCase(); if (!name || !isValidDomain(name)) { return new Response(Invalid name param, { status: 400 }); } if (!VALID_TYPES.includes(type)) { return new Response(Unsupported type: ${type}, { status: 400 }); } const upstreamUrl ${UPSTREAM_DOH}?name${encodeURIComponent(name)}type${type}; try { const upstreamResponse await fetch(upstreamUrl, { headers: { accept: application/dns-json, user-agent: cloudflare-worker-doh/1.0, }, }); if (!upstreamResponse.ok) { return new Response(Upstream error: ${upstreamResponse.status}, { status: 502, }); } const payload await upstreamResponse.json(); const body JSON.stringify(payload, null, 2); return new Response(body, { headers: { content-type: application/dns-json; charsetutf-8, cache-control: max-age60, access-control-allow-origin: *, }, }); } catch (error) { return new Response(Upstream request failed: ${error.message}, { status: 502, }); } }, };這段代碼的核心邏輯有四個部分參數(shù)校驗(yàn)只接受 GET 請求并且校驗(yàn)name和type。域名不合法或記錄類型不支持時直接返回 400避免把無效請求轉(zhuǎn)發(fā)到上游。上游轉(zhuǎn)發(fā)通過fetch請求cloudflare-dns.com/dns-query并說明自己要application/dns-json格式。異常處理上游連接失敗或返回非 2xx 狀態(tài)時返回 502并保留原始錯誤狀態(tài)碼。響應(yīng)頭設(shè)置了 CORS 頭方便瀏覽器側(cè)的腳本直接跨域調(diào)用同時設(shè)置了cache-control給客戶端一點(diǎn)緩存空間。5.3 本地調(diào)試在項(xiàng)目目錄執(zhí)行wrangler dev默認(rèn)會在本地開一個服務(wù)一般是http://localhost:8787。打開瀏覽器訪問http://localhost:8787/dns-query?nameexample.comtypeA如果一切正常你會看到一個 JSON 響應(yīng)里面包含 DNS 查詢的Status、Answer等字段。5.4 發(fā)布到 Cloudflare執(zhí)行wrangler deploy發(fā)布成功后控制臺會輸出一個*.workers.dev地址。比如https://my-doh-gateway.xxxxxxxx.workers.dev/dns-query這個地址就是你的 DoH JSON API 入口。5.5 綁定自定義域名推薦如果你的域名已經(jīng)接入 Cloudflare在 Cloudflare 控制臺進(jìn)入 Worker 詳情頁找到“設(shè)置”里的“域名和路由”添加一條路由dns.example.com/*然后選擇這個 Worker。等 DNS 生效后就可以通過https://dns.example.com/dns-query?nameexample.comtypeA訪問自己的加密 DNS 網(wǎng)關(guān)。6. 方案二用 Pages Functions 實(shí)現(xiàn) DNS 轉(zhuǎn)發(fā)與靜態(tài)頁面一體化如果你除了 DNS API還想在同一個站點(diǎn)下放一個簡單的查詢頁面Pages 是更好的選擇。Pages 項(xiàng)目把靜態(tài)資源放在根目錄把函數(shù)放在functions/目錄文件名就是路由路徑。比如functions/dns-query.js對應(yīng)的路由就是/dns-query。6.1 項(xiàng)目結(jié)構(gòu)my-pages-doh/ ├── public/ │ └── index.html └── functions/ └── dns-query.jspublic/目錄是靜態(tài)資源根目錄functions/目錄中的 JS 文件會被當(dāng)作服務(wù)端函數(shù)編譯運(yùn)行。6.2 編寫 DNS 轉(zhuǎn)發(fā)函數(shù)創(chuàng)建functions/dns-query.jsconst UPSTREAM_DOH https://cloudflare-dns.com/dns-query; const VALID_TYPES [ A, AAAA, CNAME, MX, NS, TXT, SOA, SRV, CAA, HTTPS ]; function isValidDomain(name) { return /^(?.{1,253}$)(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)[a-zA-Z]{2,63}$/.test(name); } export async function onRequestGet(context) { const { request } context; const url new URL(request.url); const name url.searchParams.get(name); const type (url.searchParams.get(type) || A).toUpperCase(); if (!name || !isValidDomain(name)) { return new Response(Invalid name param, { status: 400 }); } if (!VALID_TYPES.includes(type)) { return new Response(Unsupported type: ${type}, { status: 400 }); } const upstreamUrl ${UPSTREAM_DOH}?name${encodeURIComponent(name)}type${type}; try { const upstreamResponse await fetch(upstreamUrl, { headers: { accept: application/dns-json, user-agent: cloudflare-pages-function-doh/1.0, }, }); if (!upstreamResponse.ok) { return new Response(Upstream error: ${upstreamResponse.status}, { status: 502, }); } const payload await upstreamResponse.json(); const body JSON.stringify(payload, null, 2); return new Response(body, { headers: { content-type: application/dns-json; charsetutf-8, cache-control: max-age60, access-control-allow-origin: *, }, }); } catch (error) { return new Response(Upstream request failed: ${error.message}, { status: 502, }); } }Pages Functions 的入口約定是onRequestGet、onRequestPost這樣的命名導(dǎo)出。context對象里包含了request、env、params等字段和 Worker 的fetch回調(diào)參數(shù)不完全一樣但核心邏輯可以復(fù)用。6.3 可選的靜態(tài)查詢頁面在public/index.html放一個最簡單的頁面方便在瀏覽器里測試!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleMy DoH Gateway/title /head body h1My DoH Gateway/h1 p這是一個示例頁面。DNS API 入口為 /dns-query。/p /body /html6.4 本地運(yùn)行 Pages在項(xiàng)目根目錄執(zhí)行wrangler pages dev public它會同時啟動靜態(tài)資源和 Functions。訪問http://localhost:8788/dns-query?nameexample.comtypeA就能看到 JSON 響應(yīng)。6.5 發(fā)布 Pages 項(xiàng)目先構(gòu)建靜態(tài)資源如果只是上面的純靜態(tài)頁面不需要打包然后發(fā)布wrangler pages deploy public命令執(zhí)行后wrangler 會提示你創(chuàng)建 Pages 項(xiàng)目并返回一個*.pages.dev地址。之后在 Cloudflare Pages 控制臺可以綁定自定義域名。7. 進(jìn)階支持 Wire Format讓系統(tǒng)原生 DoH 也能用JSON 格式方便調(diào)試但一個關(guān)鍵問題是Windows、Android 等系統(tǒng)自帶的 DoH 客戶端通常不會發(fā) JSON 請求而是發(fā)標(biāo)準(zhǔn)的二進(jìn)制 DNS 消息。為了讓系統(tǒng)原生 DoH 也能享受自建網(wǎng)關(guān)網(wǎng)關(guān)需要處理application/dns-message。7.1 Wire Format 工作原理系統(tǒng)發(fā)起 DoH GET 請求時一般會帶上一個dns查詢參數(shù)參數(shù)值是 DNS 二進(jìn)制消息的 base64url 編碼。網(wǎng)關(guān)接收到這個參數(shù)后需要把 base64url 字符串解碼成二進(jìn)制 DNS 消息把二進(jìn)制 DNS 消息作為 bodyPOST 到上游 DoH 服務(wù)拿到上游返回的二進(jìn)制 DNS 響應(yīng)把它原樣返回給客戶端響應(yīng)類型為application/dns-message。7.2 支持 Wire Format 的 Worker 代碼const UPSTREAM_DOH https://cloudflare-dns.com/dns-query; function b64UrlToArrayBuffer(input) { const b64 input.replace(/-/g, ).replace(/_/g, /); const padding b64.length % 4 0 ? : .repeat(4 - (b64.length % 4)); const base64 b64 padding; const binary atob(base64); const bytes new Uint8Array(binary.length); for (let i 0; i binary.length; i) { bytes[i] binary.charCodeAt(i); } return bytes.buffer; } export default { async fetch(request, env, ctx) { const url new URL(request.url); const b64DnsMessage url.searchParams.get(dns); if (!b64DnsMessage) { return new Response(Missing dns parameter, { status: 400 }); } let dnsMessage; try { dnsMessage b64UrlToArrayBuffer(b64DnsMessage); } catch (error) { return new Response(Invalid dns message encoding, { status: 400 }); } try { const upstreamResponse await fetch(UPSTREAM_DOH, { method: POST, headers: { content-type: application/dns-message, accept: application/dns-message, }, body: dnsMessage, }); if (!upstreamResponse.ok) { return new Response(Upstream error: ${upstreamResponse.status}, { status: 502, }); } const responseBuffer await upstreamResponse.arrayBuffer(); return new Response(responseBuffer, { status: 200, headers: { content-type: application/dns-message, cache-control: max-age60, }, }); } catch (error) { return new Response(Upstream request failed: ${error.message}, { status: 502, }); } }, };這段代碼的細(xì)節(jié)在于 base64url 解碼URL 安全的 base64 會把換成-把/換成_并且可能不帶 padding。這里先補(bǔ)回標(biāo)準(zhǔn)字符再補(bǔ)上 padding最后用atob解碼成二進(jìn)制字節(jié)。7.3 在系統(tǒng)里使用如果你的系統(tǒng)支持自定義 DoH 服務(wù)器 URL可以填https://dns.example.com/dns-query系統(tǒng)會自動使用標(biāo)準(zhǔn) DNS-over-HTTPS 格式請求。注意不同系統(tǒng)對“自定義 DoH”的支持程度不一樣。有些瀏覽器只允許填公共 DoH 提供商的下拉選項(xiàng)有些則允許輸入模板 URL。如果系統(tǒng)不支持自定義模板也可以通過第三方客戶端工具來二次轉(zhuǎn)發(fā)。8. 運(yùn)行驗(yàn)證與效果檢查代碼寫完之后不要急著收工。逐個驗(yàn)證 JSON、wire format、自定義域名和日志。8.1 驗(yàn)證 JSON 格式 API假設(shè) Worker 地址是https://my-doh-gateway.xxxxxxxx.workers.dev執(zhí)行curl -s https://my-doh-gateway.xxxxxxxx.workers.dev/dns-query?nameexample.comtypeA預(yù)期輸出類似{ Status: 0, TC: false, RD: true, RA: true, AD: true, CD: false, Question: [ { name: example.com, type: 1 } ], Answer: [ { name: example.com, type: 1, TTL: 3600, data: 93.184.216.34 } ] }Status: 0表示解析成功。如果Answer字段為空說明該域名沒有對應(yīng)記錄需要檢查記錄類型是否正確。8.2 驗(yàn)證非法參數(shù)curl -i https://my-doh-gateway.xxxxxxxx.workers.dev/dns-query?namenot-a-domaintypeA預(yù)期返回400 Invalid name param。這一步很關(guān)鍵能確認(rèn)參數(shù)校驗(yàn)邏輯生效。8.3 查看 Worker 日志部署到 Cloudflare 后可以用以下命令查看實(shí)時日志wrangler tail my-doh-gateway日志里能看到每次請求的 URL、是否命中異常分支、上游響應(yīng)狀態(tài)等。如果用戶訪問報錯先從這里找線索。8.4 驗(yàn)證 Pages 版本Pages 部署完成后同樣執(zhí)行curl -s https://your-project.pages.dev/dns-query?namecloudflare.comtypeAAAA驗(yàn)證返回結(jié)果。如果整個頁面是靜態(tài)站點(diǎn) 函數(shù)模式需要同時確認(rèn)/路徑能打開頁面/dns-query能返回 API JSON。8.5 失敗時的第一排查步驟一個常見錯誤是訪問 502。此時按順序做三步看 URL 參數(shù)是否包含非法字符或空格看 Worker 日志里有沒有上游 DNS 返回錯誤碼在本地用同樣 URL 請求 Cloudflare 公共 DNS確認(rèn)上游本身可以訪問。如果上游正常、本地也有權(quán)限那大概率是代碼里的參數(shù)拼接或響應(yīng)解析出了問題。9. 常見問題與排查方法問題現(xiàn)象可能原因排查方式解決方案返回 400 Invalid name域名格式不對或帶了協(xié)議頭先用瀏覽器訪問確認(rèn)參數(shù)去掉https://只保留主機(jī)名返回 502 Upstream error上游 DoH 服務(wù)暫時不可用或請求頭不被接受查看 Worker 日志記錄上游返回的狀態(tài)碼切換上游地址比如改用https://dns.google/resolve返回 405 Method Not Allowed客戶端使用了 POST/PUT 等方法確認(rèn) curl 或系統(tǒng)客戶端發(fā)的是 GET代碼中只開放 GET或按實(shí)際需求增加 POST 處理自定義域名訪問不了Worker 路由未生效或 DNS 記錄解析到了其他地方Cloudflare 控制臺檢查 Worker 路由和 DNS 記錄添加dns.example.com/*路由等待 DNS 生效Pages 函數(shù)的/dns-query返回 404functions/文件名或路徑不對查看項(xiàng)目結(jié)構(gòu)和文件名確保文件路徑是functions/dns-query.js對應(yīng)路由/dns-query系統(tǒng)原生 DoH 無法使用系統(tǒng)需要application/dns-message但你的 Worker 只支持 JSON用 curl 模擬dns參數(shù)請求測試部署支持 wire format 的版本請求量大了后 Worker 被暫停免費(fèi)版額度耗盡Cloudflare 控制臺查看用量增加鑒權(quán)、加緩存或考慮升級付費(fèi)版大多數(shù)問題都出在三處參數(shù)校驗(yàn)、上游地址、響應(yīng)格式。排查時先用瀏覽器和 curl 走一遍通道路徑再進(jìn)入代碼邏輯。10. 最佳實(shí)踐與工程建議自建 DoH 網(wǎng)關(guān)雖然代碼量不大但從“能跑”到“能穩(wěn)定服務(wù)”中間還差很多工程細(xì)節(jié)。10.1 加鑒權(quán)避免被陌生人當(dāng)公共 DNS如果 Worker 地址公開且沒有任何鑒權(quán)任何人都能拿它當(dāng)公共 DoH 用免費(fèi)額度很快會被耗盡。最輕量的做法是加一個請求頭 Tokenconst AUTH_TOKEN your-secret-token; export default { async fetch(request, env, ctx) { const token request.headers.get(x-auth-token); if (token ! AUTH_TOKEN) { return new Response(Unauthorized, { status: 401 }); } // 繼續(xù)處理請求 } };Token 不要放在 URL 參數(shù)里避免出現(xiàn)在訪問日志中。更規(guī)范的做法是使用 Cloudflare 的 Access 服務(wù)做身份認(rèn)證但那種方案更適合內(nèi)部系統(tǒng)。10.2 合理使用緩存DoH 請求天然適合做緩存。同一個域名可能會在短時間內(nèi)被多次查詢可以用 Cloudflare KV 或 Cache API 緩存解析結(jié)果減少上游請求。需要注意DNS 解析結(jié)果有 TTL緩存時間不宜超過上游返回的 TTL否則會拿到過期的解析結(jié)果。10.3 日志與隱私策略自建網(wǎng)關(guān)意味著你會看到所有通過它查詢的域名。對個人用戶來說這是“掌握自己的數(shù)據(jù)”如果開放給別人使用就要承擔(dān)隱私責(zé)任。建議只記錄統(tǒng)計(jì)信息比如查詢數(shù)量和類型分布不要完整記錄用戶查詢的域名。如果公司內(nèi)部使用要先明確合規(guī)要求。10.4 上游故障切換不要只依賴一個上游?？梢栽?Worker 里配置多個上游地址當(dāng)主上游返回 5xx 或超時時自動切到備用上游。簡單的做法是const UPSTREAM_LIST [ https://cloudflare-dns.com/dns-query, https://dns.google/resolve ];循環(huán)嘗試列表中的上游成功就返回失敗就換下一個。10.5 控制請求速率即使加了 Token也要在邏輯上限制單個 IP 的調(diào)用頻率。Cloudflare 免費(fèi)版對單 Worker 的請求量有額度限制你可以在代碼中用 KV 做簡單的滑動窗口計(jì)數(shù)。注意 KV 的寫入是最終一致的不適合做高并發(fā)精確限流。更嚴(yán)格的限流方案需要結(jié)合 Cloudflare WAF Rate Limiting。10.6 面向生產(chǎn)環(huán)境域名、證書與穩(wěn)定性建議不要長期依賴*.workers.dev或*.pages.dev作為生產(chǎn)入口。雖然它們免費(fèi)但對外提供服務(wù)時綁定自己的域名能統(tǒng)一證書策略和訪問控制也能避免默認(rèn)域名被人猜測后濫用。域名接入 Cloudflare 后證書自動由 Cloudflare 管理不需要自己處理 HTTPS 配置。11. 總結(jié)與后續(xù)學(xué)習(xí)方向到這里你已經(jīng)用 Cloudflare Workers 和 Pages 分別實(shí)現(xiàn)了加密 DNS 網(wǎng)關(guān)。方案一適合快速跑通 API方案二適合靜態(tài)站點(diǎn)和 API 一起部署進(jìn)階版本則可以讓系統(tǒng)原生 DoH 客戶端直接接入?；仡^看幾個關(guān)鍵收獲Cloudflare Pages 并不只是“靜態(tài)托管平臺”它和 Workers 共用一套運(yùn)行時DoH 網(wǎng)關(guān)的核心是參數(shù)校驗(yàn)、上游轉(zhuǎn)發(fā)和響應(yīng)格式轉(zhuǎn)換自建網(wǎng)關(guān)真正帶來的價值是“自定義入口 策略控制層”。下一步可以繼續(xù)深入的方向有三個第一把 DNS 解析結(jié)果寫到 Cloudflare KV 里做持久化緩存第二在 Worker 里加入域名黑名單/白名單邏輯做成一個簡短的家庭 DNS 過濾規(guī)則第三加上一個可視化管理頁面讓你在瀏覽器里查看查詢統(tǒng)計(jì)和配置上游地址。最后提醒一點(diǎn)把網(wǎng)關(guān)開放給外部用戶時要先想清楚鑒權(quán)、日志和額度問題。先用本地wrangler dev把完整邏輯跑通再部署到線上遇到問題優(yōu)先查看wrangler tail的日志輸出。這套思路適合輕量級自用和個人項(xiàng)目如果要用到企業(yè)生產(chǎn)環(huán)境還需要結(jié)合更完整的監(jiān)控、限流和權(quán)限體系。 基于Cloudflare Workers和Pages自建加密DNS網(wǎng)關(guān)：DoH原理與實(shí)戰(zhàn)
過去幾年很多開發(fā)者把個人主頁或項(xiàng)目文檔放到了 GitHub Pages、Gitee Pages 上以為“Pages”只是托個靜態(tài)網(wǎng)頁。但如果把目光放到 Cloudflare Pages你會發(fā)現(xiàn)它和 Workers 共用同一套邊緣運(yùn)行環(huán)境還能跑真正的服務(wù)端邏輯。一個很典型的玩法就是用 Workers 或 Pages Functions 自建一個加密 DNS 解析網(wǎng)關(guān)。先說一個明確判斷這篇文章要搭的“加密 DNS 服務(wù)器”并不是傳統(tǒng)意義上的權(quán)威 DNS 服務(wù)器而是一個帶隱私和可控策略的DoH 網(wǎng)關(guān)。它接收客戶端發(fā)來的 HTTPS 加密 DNS 請求再轉(zhuǎn)發(fā)給上游遞歸解析服務(wù)最后把結(jié)果返回給客戶端。通過這一層你可以擁有一個自定義域名的加密 DNS 入口還能統(tǒng)一加緩存、鑒權(quán)和解析策略。讀完這篇文章你能跑通兩件事一是用 Cloudflare Worker 實(shí)現(xiàn)一個支持 JSON 格式的 DoH 解析 API二是用 Cloudflare Pages 實(shí)現(xiàn)“靜態(tài)頁面 DNS 轉(zhuǎn)發(fā)函數(shù)”的一體化部署。文章里還會講 wire format 方式的實(shí)現(xiàn)思路、常見坑、鑒權(quán)和緩存策略方便你在生產(chǎn)環(huán)境中落地。1. 這篇文章真正要解決的問題不少人會有這樣的經(jīng)歷打開電腦連上 WiFi 后DNS 查詢默認(rèn)走路由器下發(fā)的地址在某些網(wǎng)絡(luò)環(huán)境下DNS 響應(yīng)被篡改、被加廣告、長時間無響應(yīng)問題排查起來非常被動。普通 DNS 請求是明文傳輸?shù)闹虚g設(shè)備確實(shí)有可能看到你在查詢哪些域名。所以現(xiàn)在越來越多人開始關(guān)注加密 DNS也就是 DoHDNS over HTTPS、DoTDNS over TLS這類方案。但直接使用公共 DoH 服務(wù)也有不舒服的地方公共地址大家都在用不方便統(tǒng)計(jì)自己的查詢量想在里面加一層“域名過濾”或“本地緩存”也比較麻煩。于是就有了“自建加密 DNS 網(wǎng)關(guān)”的需求。云服務(wù)商里Cloudflare Workers 和 Pages 是很適合做這件事的載體。它們不需要你買服務(wù)器不需要自己管證書和守護(hù)進(jìn)程寫完代碼直接發(fā)布到邊緣節(jié)點(diǎn)幾十行代碼就能把 DNS 查詢包一層 HTTPS。這篇文章真正適合的讀者有三類想搞懂 DoH 原理并希望用 Serverless 方式落地一個真實(shí)服務(wù)的開發(fā)者家里有多臺設(shè)備、多個網(wǎng)絡(luò)環(huán)境想統(tǒng)一一個自定義 DNS 入口的工程師Page 托管用戶想知道 Cloudflare Pages 除了托管靜態(tài)頁面還能做什么的人。也要提前說清楚邊界Cloudflare Workers 上跑的是“DNS 代理/轉(zhuǎn)發(fā)器”不是權(quán)威 DNS。你不能在這里面管理自己的域名記錄也不適合把它當(dāng)作大規(guī)模內(nèi)部 DNS 基礎(chǔ)設(shè)施。它的定位是“加密 DNS 入口 策略控制層”。2. 加密 DNS 基礎(chǔ)DoH、DoT、DoQ 概念與區(qū)別在進(jìn)入代碼之前先把幾個概念理清楚。很多文章把 DoH、DoT、DoQ 混著說初學(xué)者很容易被繞暈。2.1 明文 DNS 的問題普通 DNS 一般是客戶端向 53 端口發(fā)起 UDP 查詢。這個請求從你的電腦到路由器再到運(yùn)營商遞歸 DNS中間經(jīng)過的鏈路如果被監(jiān)聽對方可以看到你查詢的域名。更麻煩的是如果響應(yīng)被篡改客戶端可能被引導(dǎo)到錯誤的 IP 地址。2.2 三種主流加密 DNS 方式協(xié)議全稱傳輸方式默認(rèn)端口優(yōu)點(diǎn)弱點(diǎn)DoHDNS over HTTPSHTTPSHTTP/2 或 HTTP/3443和普通網(wǎng)頁流量混在一起難以被單獨(dú)識別瀏覽器支持度高實(shí)現(xiàn)相對復(fù)雜要求服務(wù)端支持 HTTPSDoTDNS over TLSTLS 專屬連接853實(shí)現(xiàn)簡單連接生命周期穩(wěn)定專用端口容易被網(wǎng)絡(luò)設(shè)備識別和封鎖DoQDNS over QUICQUIC基于 UDP853低延遲多路復(fù)用正在被主流客戶端逐步支持生態(tài)系統(tǒng)還不夠成熟客戶端支持較少這里最容易混淆的是 DoH 和 DoT。簡單記DoH 的流量是“HTTPS 請求”和你看網(wǎng)頁用的是同一個模型DoT 是“為 DNS 單獨(dú)開設(shè)一條 TLS 通道”。兩者都做了加密但在網(wǎng)絡(luò)中的“可見性”不同。2.3 DoH 的兩種數(shù)據(jù)格式文章后面會頻繁提到兩種格式application/dns-jsonJSON 格式適合開發(fā)調(diào)試、腳本調(diào)用也適合在 Worker 里直接處理 JSON 對象。瀏覽器地址欄直接訪問也能看到可讀結(jié)果。application/dns-message二進(jìn)制 DNS 消息格式和傳統(tǒng) DNS 報文結(jié)構(gòu)一致只是外面包了一層 HTTPS。系統(tǒng)級的原生 DoH 功能比如 Windows 上的自定義 DoH 模板通常使用這種格式。做網(wǎng)關(guān)時最簡單的是先做 JSON 格式因?yàn)榇a好寫、驗(yàn)證方便。但如果想讓手機(jī)系統(tǒng)或?yàn)g覽器原生 DoH 直接用就需要支持 wire format。2.4 加密 DNS 網(wǎng)關(guān)的請求鏈路用 Cloudflare Worker 實(shí)現(xiàn)的自建加密 DNS 網(wǎng)關(guān)請求鏈路是這樣的客戶端設(shè)備/瀏覽器 ↓ HTTPSDoH 請求 Cloudflare Worker自定義域名 ↓ 上游 DoH 請求 Cloudflare 公共 DNS 或其他遞歸 DNS ↓ DNS 明文解析 互聯(lián)網(wǎng)權(quán)威 DNS 服務(wù)器關(guān)鍵點(diǎn)在于客戶端和 Worker 之間是加密的Worker 和上游之間也走 DoH那么從網(wǎng)關(guān)出去的查詢也是加密的。中間只多了一層自己的策略邏輯。3. Workers 還是 Pages方案選型與適用場景很多讀者會問標(biāo)題里又說 Workers 又說 Pages到底該用哪個其實(shí) Cloudflare Pages Functions 底層就是 Workers 運(yùn)行時寫法也很接近。區(qū)別主要在于“你還需要不需要托管靜態(tài)資源”。維度Cloudflare WorkersCloudflare Pages部署目標(biāo)純函數(shù) / API靜態(tài)資源 Functions項(xiàng)目類型wrangler deploy發(fā)布 Worker構(gòu)建靜態(tài)站點(diǎn)后發(fā)布Functions 放在functions/目錄適用場景只想快速發(fā)布一個 API、網(wǎng)關(guān)、代理已有靜態(tài)站點(diǎn)希望站點(diǎn)接口也跑在同一域名下自定義域名通過 Worker 路由綁定Pages 自定義域名綁定免費(fèi)額度有每日請求量限制超出會停止服務(wù)同樣有免費(fèi)額度適合中小流量項(xiàng)目本地開發(fā)wrangler devwrangler pages dev選型建議很直接如果你只是想要一個 DNS API 或一個隱藏服務(wù)直接選 Worker項(xiàng)目結(jié)構(gòu)最簡潔。如果你想做一個“帶管理后臺的加密 DNS 控制臺”或者已經(jīng)有一個靜態(tài)站點(diǎn)希望把接口合到同一個域名下用 Pages 更舒服。不過要注意二者都跑在 Cloudflare 邊緣節(jié)點(diǎn)上。默認(rèn)域名是*.workers.dev或*.pages.dev這兩個域名雖然免費(fèi)但如果要做生產(chǎn)環(huán)境 DNS 入口建議綁定自己的域名。一來行為更可控二來在客戶端配置 DoH 地址時也更像正式服務(wù)。4. 環(huán)境準(zhǔn)備與前置條件開始寫代碼前先把環(huán)境準(zhǔn)備好。這里的核心依賴是 Cloudflare 的 wrangler 命令行工具。4.1 需要準(zhǔn)備的東西Cloudflare 賬號如果沒有先去官網(wǎng)注冊一個。免費(fèi)版足夠完成本文章的所有實(shí)驗(yàn)。Node.js 環(huán)境建議使用當(dāng)前 LTS 版本。wrangler 是 npm 包需要 Node 環(huán)境來安裝和運(yùn)行。一個域名可選但推薦如果域名已經(jīng)托管在 Cloudflare后面綁定自定義域名會非常方便。本地開發(fā)工具VS Code 或任意編輯器都可以。4.2 安裝 wrangler安裝命令npm install -g wrangler安裝完成后確認(rèn)版本wrangler --version如果網(wǎng)絡(luò)環(huán)境不允許全局安裝也可以把 wrangler 裝到項(xiàng)目本地npm init -y npm install -D wrangler然后通過npx wrangler使用本地命令。4.3 登錄 Cloudflare在項(xiàng)目目錄執(zhí)行wrangler login命令會打開瀏覽器讓你授權(quán) wrangler 訪問你的賬號。授權(quán)完成后wrangler 會把憑證保存到本地后續(xù)發(fā)布和部署都可以直接用。如果是在 CI/CD 環(huán)境中使用一般會用CLOUDFLARE_API_TOKEN環(huán)境變量代替交互登錄。本文章的家庭/個人部署場景直接wrangler login就夠了。4.4 創(chuàng)建項(xiàng)目目錄以最常用的 Worker 方案為例mkdir my-doh-gateway cd my-doh-gateway npm init -y后續(xù)代碼都放在這個目錄里。5. 方案一用 Worker 實(shí)現(xiàn) DoH JSON 解析 API這是最簡單、也最容易跑通的方案。整個 Worker 就是一段 JavaScript處理 GET 請求從 URL 參數(shù)里讀取域名和記錄類型再請求上游 DoH 服務(wù)把結(jié)果轉(zhuǎn)成 JSON 返回給客戶端。5.1 創(chuàng)建 wrangler.toml在項(xiàng)目根目錄創(chuàng)建wrangler.tomlname my-doh-gateway main src/index.js compatibility_date 2024-01-01name是 Worker 名稱會出現(xiàn)在部署后的默認(rèn)域名里。main指定入口文件。compatibility_date是 Cloudflare Workers 的兼容性日期按 wrangler 提示填寫即可不需要過度糾結(jié)。5.2 Worker 核心代碼創(chuàng)建src/index.jsconst UPSTREAM_DOH https://cloudflare-dns.com/dns-query; const VALID_TYPES [ A, AAAA, CNAME, MX, NS, TXT, SOA, SRV, CAA, HTTPS ]; function isValidDomain(name) { return /^(?.{1,253}$)(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)[a-zA-Z]{2,63}$/.test(name); } export default { async fetch(request, env, ctx) { const url new URL(request.url); if (request.method ! GET) { return new Response(Method Not Allowed, { status: 405 }); } const name url.searchParams.get(name); const type (url.searchParams.get(type) || A).toUpperCase(); if (!name || !isValidDomain(name)) { return new Response(Invalid name param, { status: 400 }); } if (!VALID_TYPES.includes(type)) { return new Response(Unsupported type: ${type}, { status: 400 }); } const upstreamUrl ${UPSTREAM_DOH}?name${encodeURIComponent(name)}type${type}; try { const upstreamResponse await fetch(upstreamUrl, { headers: { accept: application/dns-json, user-agent: cloudflare-worker-doh/1.0, }, }); if (!upstreamResponse.ok) { return new Response(Upstream error: ${upstreamResponse.status}, { status: 502, }); } const payload await upstreamResponse.json(); const body JSON.stringify(payload, null, 2); return new Response(body, { headers: { content-type: application/dns-json; charsetutf-8, cache-control: max-age60, access-control-allow-origin: *, }, }); } catch (error) { return new Response(Upstream request failed: ${error.message}, { status: 502, }); } }, };這段代碼的核心邏輯有四個部分參數(shù)校驗(yàn)只接受 GET 請求并且校驗(yàn)name和type。域名不合法或記錄類型不支持時直接返回 400避免把無效請求轉(zhuǎn)發(fā)到上游。上游轉(zhuǎn)發(fā)通過fetch請求cloudflare-dns.com/dns-query并說明自己要application/dns-json格式。異常處理上游連接失敗或返回非 2xx 狀態(tài)時返回 502并保留原始錯誤狀態(tài)碼。響應(yīng)頭設(shè)置了 CORS 頭方便瀏覽器側(cè)的腳本直接跨域調(diào)用同時設(shè)置了cache-control給客戶端一點(diǎn)緩存空間。5.3 本地調(diào)試在項(xiàng)目目錄執(zhí)行wrangler dev默認(rèn)會在本地開一個服務(wù)一般是http://localhost:8787。打開瀏覽器訪問http://localhost:8787/dns-query?nameexample.comtypeA如果一切正常你會看到一個 JSON 響應(yīng)里面包含 DNS 查詢的Status、Answer等字段。5.4 發(fā)布到 Cloudflare執(zhí)行wrangler deploy發(fā)布成功后控制臺會輸出一個*.workers.dev地址。比如https://my-doh-gateway.xxxxxxxx.workers.dev/dns-query這個地址就是你的 DoH JSON API 入口。5.5 綁定自定義域名推薦如果你的域名已經(jīng)接入 Cloudflare在 Cloudflare 控制臺進(jìn)入 Worker 詳情頁找到“設(shè)置”里的“域名和路由”添加一條路由dns.example.com/*然后選擇這個 Worker。等 DNS 生效后就可以通過https://dns.example.com/dns-query?nameexample.comtypeA訪問自己的加密 DNS 網(wǎng)關(guān)。6. 方案二用 Pages Functions 實(shí)現(xiàn) DNS 轉(zhuǎn)發(fā)與靜態(tài)頁面一體化如果你除了 DNS API還想在同一個站點(diǎn)下放一個簡單的查詢頁面Pages 是更好的選擇。Pages 項(xiàng)目把靜態(tài)資源放在根目錄把函數(shù)放在functions/目錄文件名就是路由路徑。比如functions/dns-query.js對應(yīng)的路由就是/dns-query。6.1 項(xiàng)目結(jié)構(gòu)my-pages-doh/ ├── public/ │ └── index.html └── functions/ └── dns-query.jspublic/目錄是靜態(tài)資源根目錄functions/目錄中的 JS 文件會被當(dāng)作服務(wù)端函數(shù)編譯運(yùn)行。6.2 編寫 DNS 轉(zhuǎn)發(fā)函數(shù)創(chuàng)建functions/dns-query.jsconst UPSTREAM_DOH https://cloudflare-dns.com/dns-query; const VALID_TYPES [ A, AAAA, CNAME, MX, NS, TXT, SOA, SRV, CAA, HTTPS ]; function isValidDomain(name) { return /^(?.{1,253}$)(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)[a-zA-Z]{2,63}$/.test(name); } export async function onRequestGet(context) { const { request } context; const url new URL(request.url); const name url.searchParams.get(name); const type (url.searchParams.get(type) || A).toUpperCase(); if (!name || !isValidDomain(name)) { return new Response(Invalid name param, { status: 400 }); } if (!VALID_TYPES.includes(type)) { return new Response(Unsupported type: ${type}, { status: 400 }); } const upstreamUrl ${UPSTREAM_DOH}?name${encodeURIComponent(name)}type${type}; try { const upstreamResponse await fetch(upstreamUrl, { headers: { accept: application/dns-json, user-agent: cloudflare-pages-function-doh/1.0, }, }); if (!upstreamResponse.ok) { return new Response(Upstream error: ${upstreamResponse.status}, { status: 502, }); } const payload await upstreamResponse.json(); const body JSON.stringify(payload, null, 2); return new Response(body, { headers: { content-type: application/dns-json; charsetutf-8, cache-control: max-age60, access-control-allow-origin: *, }, }); } catch (error) { return new Response(Upstream request failed: ${error.message}, { status: 502, }); } }Pages Functions 的入口約定是onRequestGet、onRequestPost這樣的命名導(dǎo)出。context對象里包含了request、env、params等字段和 Worker 的fetch回調(diào)參數(shù)不完全一樣但核心邏輯可以復(fù)用。6.3 可選的靜態(tài)查詢頁面在public/index.html放一個最簡單的頁面方便在瀏覽器里測試!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleMy DoH Gateway/title /head body h1My DoH Gateway/h1 p這是一個示例頁面。DNS API 入口為 /dns-query。/p /body /html6.4 本地運(yùn)行 Pages在項(xiàng)目根目錄執(zhí)行wrangler pages dev public它會同時啟動靜態(tài)資源和 Functions。訪問http://localhost:8788/dns-query?nameexample.comtypeA就能看到 JSON 響應(yīng)。6.5 發(fā)布 Pages 項(xiàng)目先構(gòu)建靜態(tài)資源如果只是上面的純靜態(tài)頁面不需要打包然后發(fā)布wrangler pages deploy public命令執(zhí)行后wrangler 會提示你創(chuàng)建 Pages 項(xiàng)目并返回一個*.pages.dev地址。之后在 Cloudflare Pages 控制臺可以綁定自定義域名。7. 進(jìn)階支持 Wire Format讓系統(tǒng)原生 DoH 也能用JSON 格式方便調(diào)試但一個關(guān)鍵問題是Windows、Android 等系統(tǒng)自帶的 DoH 客戶端通常不會發(fā) JSON 請求而是發(fā)標(biāo)準(zhǔn)的二進(jìn)制 DNS 消息。為了讓系統(tǒng)原生 DoH 也能享受自建網(wǎng)關(guān)網(wǎng)關(guān)需要處理application/dns-message。7.1 Wire Format 工作原理系統(tǒng)發(fā)起 DoH GET 請求時一般會帶上一個dns查詢參數(shù)參數(shù)值是 DNS 二進(jìn)制消息的 base64url 編碼。網(wǎng)關(guān)接收到這個參數(shù)后需要把 base64url 字符串解碼成二進(jìn)制 DNS 消息把二進(jìn)制 DNS 消息作為 bodyPOST 到上游 DoH 服務(wù)拿到上游返回的二進(jìn)制 DNS 響應(yīng)把它原樣返回給客戶端響應(yīng)類型為application/dns-message。7.2 支持 Wire Format 的 Worker 代碼const UPSTREAM_DOH https://cloudflare-dns.com/dns-query; function b64UrlToArrayBuffer(input) { const b64 input.replace(/-/g, ).replace(/_/g, /); const padding b64.length % 4 0 ? : .repeat(4 - (b64.length % 4)); const base64 b64 padding; const binary atob(base64); const bytes new Uint8Array(binary.length); for (let i 0; i binary.length; i) { bytes[i] binary.charCodeAt(i); } return bytes.buffer; } export default { async fetch(request, env, ctx) { const url new URL(request.url); const b64DnsMessage url.searchParams.get(dns); if (!b64DnsMessage) { return new Response(Missing dns parameter, { status: 400 }); } let dnsMessage; try { dnsMessage b64UrlToArrayBuffer(b64DnsMessage); } catch (error) { return new Response(Invalid dns message encoding, { status: 400 }); } try { const upstreamResponse await fetch(UPSTREAM_DOH, { method: POST, headers: { content-type: application/dns-message, accept: application/dns-message, }, body: dnsMessage, }); if (!upstreamResponse.ok) { return new Response(Upstream error: ${upstreamResponse.status}, { status: 502, }); } const responseBuffer await upstreamResponse.arrayBuffer(); return new Response(responseBuffer, { status: 200, headers: { content-type: application/dns-message, cache-control: max-age60, }, }); } catch (error) { return new Response(Upstream request failed: ${error.message}, { status: 502, }); } }, };這段代碼的細(xì)節(jié)在于 base64url 解碼URL 安全的 base64 會把換成-把/換成_并且可能不帶 padding。這里先補(bǔ)回標(biāo)準(zhǔn)字符再補(bǔ)上 padding最后用atob解碼成二進(jìn)制字節(jié)。7.3 在系統(tǒng)里使用如果你的系統(tǒng)支持自定義 DoH 服務(wù)器 URL可以填https://dns.example.com/dns-query系統(tǒng)會自動使用標(biāo)準(zhǔn) DNS-over-HTTPS 格式請求。注意不同系統(tǒng)對“自定義 DoH”的支持程度不一樣。有些瀏覽器只允許填公共 DoH 提供商的下拉選項(xiàng)有些則允許輸入模板 URL。如果系統(tǒng)不支持自定義模板也可以通過第三方客戶端工具來二次轉(zhuǎn)發(fā)。8. 運(yùn)行驗(yàn)證與效果檢查代碼寫完之后不要急著收工。逐個驗(yàn)證 JSON、wire format、自定義域名和日志。8.1 驗(yàn)證 JSON 格式 API假設(shè) Worker 地址是https://my-doh-gateway.xxxxxxxx.workers.dev執(zhí)行curl -s https://my-doh-gateway.xxxxxxxx.workers.dev/dns-query?nameexample.comtypeA預(yù)期輸出類似{ Status: 0, TC: false, RD: true, RA: true, AD: true, CD: false, Question: [ { name: example.com, type: 1 } ], Answer: [ { name: example.com, type: 1, TTL: 3600, data: 93.184.216.34 } ] }Status: 0表示解析成功。如果Answer字段為空說明該域名沒有對應(yīng)記錄需要檢查記錄類型是否正確。8.2 驗(yàn)證非法參數(shù)curl -i https://my-doh-gateway.xxxxxxxx.workers.dev/dns-query?namenot-a-domaintypeA預(yù)期返回400 Invalid name param。這一步很關(guān)鍵能確認(rèn)參數(shù)校驗(yàn)邏輯生效。8.3 查看 Worker 日志部署到 Cloudflare 后可以用以下命令查看實(shí)時日志wrangler tail my-doh-gateway日志里能看到每次請求的 URL、是否命中異常分支、上游響應(yīng)狀態(tài)等。如果用戶訪問報錯先從這里找線索。8.4 驗(yàn)證 Pages 版本Pages 部署完成后同樣執(zhí)行curl -s https://your-project.pages.dev/dns-query?namecloudflare.comtypeAAAA驗(yàn)證返回結(jié)果。如果整個頁面是靜態(tài)站點(diǎn) 函數(shù)模式需要同時確認(rèn)/路徑能打開頁面/dns-query能返回 API JSON。8.5 失敗時的第一排查步驟一個常見錯誤是訪問 502。此時按順序做三步看 URL 參數(shù)是否包含非法字符或空格看 Worker 日志里有沒有上游 DNS 返回錯誤碼在本地用同樣 URL 請求 Cloudflare 公共 DNS確認(rèn)上游本身可以訪問。如果上游正常、本地也有權(quán)限那大概率是代碼里的參數(shù)拼接或響應(yīng)解析出了問題。9. 常見問題與排查方法問題現(xiàn)象可能原因排查方式解決方案返回 400 Invalid name域名格式不對或帶了協(xié)議頭先用瀏覽器訪問確認(rèn)參數(shù)去掉https://只保留主機(jī)名返回 502 Upstream error上游 DoH 服務(wù)暫時不可用或請求頭不被接受查看 Worker 日志記錄上游返回的狀態(tài)碼切換上游地址比如改用https://dns.google/resolve返回 405 Method Not Allowed客戶端使用了 POST/PUT 等方法確認(rèn) curl 或系統(tǒng)客戶端發(fā)的是 GET代碼中只開放 GET或按實(shí)際需求增加 POST 處理自定義域名訪問不了Worker 路由未生效或 DNS 記錄解析到了其他地方Cloudflare 控制臺檢查 Worker 路由和 DNS 記錄添加dns.example.com/*路由等待 DNS 生效Pages 函數(shù)的/dns-query返回 404functions/文件名或路徑不對查看項(xiàng)目結(jié)構(gòu)和文件名確保文件路徑是functions/dns-query.js對應(yīng)路由/dns-query系統(tǒng)原生 DoH 無法使用系統(tǒng)需要application/dns-message但你的 Worker 只支持 JSON用 curl 模擬dns參數(shù)請求測試部署支持 wire format 的版本請求量大了后 Worker 被暫停免費(fèi)版額度耗盡Cloudflare 控制臺查看用量增加鑒權(quán)、加緩存或考慮升級付費(fèi)版大多數(shù)問題都出在三處參數(shù)校驗(yàn)、上游地址、響應(yīng)格式。排查時先用瀏覽器和 curl 走一遍通道路徑再進(jìn)入代碼邏輯。10. 最佳實(shí)踐與工程建議自建 DoH 網(wǎng)關(guān)雖然代碼量不大但從“能跑”到“能穩(wěn)定服務(wù)”中間還差很多工程細(xì)節(jié)。10.1 加鑒權(quán)避免被陌生人當(dāng)公共 DNS如果 Worker 地址公開且沒有任何鑒權(quán)任何人都能拿它當(dāng)公共 DoH 用免費(fèi)額度很快會被耗盡。最輕量的做法是加一個請求頭 Tokenconst AUTH_TOKEN your-secret-token; export default { async fetch(request, env, ctx) { const token request.headers.get(x-auth-token); if (token ! AUTH_TOKEN) { return new Response(Unauthorized, { status: 401 }); } // 繼續(xù)處理請求 } };Token 不要放在 URL 參數(shù)里避免出現(xiàn)在訪問日志中。更規(guī)范的做法是使用 Cloudflare 的 Access 服務(wù)做身份認(rèn)證但那種方案更適合內(nèi)部系統(tǒng)。10.2 合理使用緩存DoH 請求天然適合做緩存。同一個域名可能會在短時間內(nèi)被多次查詢可以用 Cloudflare KV 或 Cache API 緩存解析結(jié)果減少上游請求。需要注意DNS 解析結(jié)果有 TTL緩存時間不宜超過上游返回的 TTL否則會拿到過期的解析結(jié)果。10.3 日志與隱私策略自建網(wǎng)關(guān)意味著你會看到所有通過它查詢的域名。對個人用戶來說這是“掌握自己的數(shù)據(jù)”如果開放給別人使用就要承擔(dān)隱私責(zé)任。建議只記錄統(tǒng)計(jì)信息比如查詢數(shù)量和類型分布不要完整記錄用戶查詢的域名。如果公司內(nèi)部使用要先明確合規(guī)要求。10.4 上游故障切換不要只依賴一個上游?？梢栽?Worker 里配置多個上游地址當(dāng)主上游返回 5xx 或超時時自動切到備用上游。簡單的做法是const UPSTREAM_LIST [ https://cloudflare-dns.com/dns-query, https://dns.google/resolve ];循環(huán)嘗試列表中的上游成功就返回失敗就換下一個。10.5 控制請求速率即使加了 Token也要在邏輯上限制單個 IP 的調(diào)用頻率。Cloudflare 免費(fèi)版對單 Worker 的請求量有額度限制你可以在代碼中用 KV 做簡單的滑動窗口計(jì)數(shù)。注意 KV 的寫入是最終一致的不適合做高并發(fā)精確限流。更嚴(yán)格的限流方案需要結(jié)合 Cloudflare WAF Rate Limiting。10.6 面向生產(chǎn)環(huán)境域名、證書與穩(wěn)定性建議不要長期依賴*.workers.dev或*.pages.dev作為生產(chǎn)入口。雖然它們免費(fèi)但對外提供服務(wù)時綁定自己的域名能統(tǒng)一證書策略和訪問控制也能避免默認(rèn)域名被人猜測后濫用。域名接入 Cloudflare 后證書自動由 Cloudflare 管理不需要自己處理 HTTPS 配置。11. 總結(jié)與后續(xù)學(xué)習(xí)方向到這里你已經(jīng)用 Cloudflare Workers 和 Pages 分別實(shí)現(xiàn)了加密 DNS 網(wǎng)關(guān)。方案一適合快速跑通 API方案二適合靜態(tài)站點(diǎn)和 API 一起部署進(jìn)階版本則可以讓系統(tǒng)原生 DoH 客戶端直接接入?；仡^看幾個關(guān)鍵收獲Cloudflare Pages 并不只是“靜態(tài)托管平臺”它和 Workers 共用一套運(yùn)行時DoH 網(wǎng)關(guān)的核心是參數(shù)校驗(yàn)、上游轉(zhuǎn)發(fā)和響應(yīng)格式轉(zhuǎn)換自建網(wǎng)關(guān)真正帶來的價值是“自定義入口 策略控制層”。下一步可以繼續(xù)深入的方向有三個第一把 DNS 解析結(jié)果寫到 Cloudflare KV 里做持久化緩存第二在 Worker 里加入域名黑名單/白名單邏輯做成一個簡短的家庭 DNS 過濾規(guī)則第三加上一個可視化管理頁面讓你在瀏覽器里查看查詢統(tǒng)計(jì)和配置上游地址。最后提醒一點(diǎn)把網(wǎng)關(guān)開放給外部用戶時要先想清楚鑒權(quán)、日志和額度問題。先用本地wrangler dev把完整邏輯跑通再部署到線上遇到問題優(yōu)先查看wrangler tail的日志輸出。這套思路適合輕量級自用和個人項(xiàng)目如果要用到企業(yè)生產(chǎn)環(huán)境還需要結(jié)合更完整的監(jiān)控、限流和權(quán)限體系。