適用場景什么時候會用到這個接口家庭寬帶或小型辦公室的網絡出口 IP 通常由運營商動態分配重啟光貓、路由器或長時間在線后 IP 都可能變化。如果域名解析記錄還停留在舊 IP 上遠程訪問就會失敗。Cloudflare DNS 更新DDNS接口解決的正是這類問題通過 Cloudflare API Token 更新指定域名的 A/AAAA 記錄讓域名始終指向當前的公網 IP。典型使用場景包括家庭寬帶 DDNS路由器或內網主機定時對比本機 IP 與解析記錄不一致時調用接口更新。辦公室外網 IP 自動同步將辦公網絡出口 IP 映射到子域名配合端口映射實現遠程接入。臨時主機的動態解析云服務器或開發機 IP 變化后快速把域名切到新地址。這類任務不需要完整的 Cloudflare API 客戶端一個輕量 HTTP 請求即可完成適合放在腳本、定時任務或小型服務中。接口能力邊界在使用前需要明確該接口能做什么、不能做什么避免后續踩坑。支持記錄類型A 與 AAAA分別對應 IPv4 與 IPv6。默認解析為 A 記錄。更新粒度按根域名 主機記錄定位一條 DNS 記錄例如home.example.com中的home為主機記錄example.com為根域名。TTL 范圍120 至 86400 秒默認 120 秒。CDN 代理可選開啟 Cloudflare 橙色云代理默認關閉。鑒權方式請求頭攜帶 API Key接口內部使用請求體中的 Cloudflare Token 執行更新。Token 僅作轉發使用不會持久化。需要強調的是該接口自身不負責探測公網 IP。若請求體中的ip為空具體行為以文檔為準工程實踐中建議先通過其它渠道獲取本機公網 IP再顯式傳入ip這樣行為更可控。請求參數與鑒權該接口的完整請求地址為POST https://v1.apizero.cn/api/cf-dnsHeader 參數參數名類型必填說明Authorizationstring是接口訪問憑據在調用平臺申請后獲得Content-Typestring是設置為application/json在 curl 示例中通常使用X-API-Key傳遞 API Key實際以你的調用平臺所要求的 Header 為準也可以統一放在Authorization字段中。請求體字段字段類型必填默認值說明domainstring是無根域名例如example.comhoststring是無主機記錄例如、www或homeipstring是無要設置的 IP 地址tokenstring是無Cloudflare API Token需具備目標域名 DNS 編輯權限typestring否A記錄類型可選A或AAAAttlnumber否120TTL范圍 120 至 86400proxiedboolean否false是否啟用 CDN 代理其中domain、host、ip、token四個字段構成一次最小可用請求。type在更新 IPv6 記錄時必須顯式傳入AAAA。最小可運行 curl 示例下面是一個完整的 POST 請求示例。將$APIZERO_API_KEY替換為你自己的 API Key并將domain、host、ip、token換成真實值curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, host: home, ip: 5.6.7.8, token: your_cloudflare_api_token, type: A, ttl: 120, proxied: false } \ https://v1.apizero.cn/api/cf-dns如果希望更新 IPv6 記錄將type改為AAAA并傳入 IPv6 格式的ipcurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, host: home, ip: 240e:390:1234:5678::1, token: your_cloudflare_api_token, type: AAAA, ttl: 300, proxied: false } \ https://v1.apizero.cn/api/cf-dns注意host字段填寫表示根域名本身填寫www或其它子域名前綴時不要帶圓點。返回字段解讀一個典型的成功響應如下{ code: 0, data: { changed: true, full_name: home.example.com, message: DNS 記錄更新成功, new_ip: 5.6.7.8, old_ip: 1.2.3.4, type: A }, msg: 成功 }各字段含義如下字段說明code業務狀態碼0表示成功msg狀態描述文本data.changed本次請求是否實際更改了 DNS 記錄。若新舊 IP 相同可能為falsedata.full_name更新完成的完整域名由host與domain拼接而成data.message接口返回的說明信息data.new_ip更新后的 IP 地址data.old_ip更新前的舊 IP 地址。首次創建記錄時可能為空data.type記錄類型A或AAAA判斷一次請求是否成功建議先看code是否為0再結合data.changed決定是否需要后續操作。例如定時任務中如果changed為false說明域名解析已經是目標 IP無需重復更新其它系統。常見錯誤與排查思路實際接入中以下問題出現頻率較高。1. 鑒權失敗現象接口返回與鑒權相關的錯誤碼。排查步驟確認 Header 中的 API Key 是否與調用平臺中生成的值一致。確認是否同時正確設置了Content-Type: application/json。如果 Header 同時使用了Authorization與X-API-Key確認平臺要求的是哪一種。2. Cloudflare Token 無權限現象請求已到達平臺但 Cloudflare 側拒絕更新。排查步驟登錄 Cloudflare 控制臺檢查 Token 是否包含目標區域的 DNS 編輯權限。確認 Token 對應的域名是請求體中的domain。如果 Token 設置了 IP 白名單確認當前調用出口 IP 在白名單內。3. 域名或主機記錄不存在現象接口提示找不到記錄。排查步驟確認domain是根域名而不帶www前綴。確認host在 Cloudflare 中已存在對應解析記錄。若記錄不存在該接口是否能自動創建以文檔為準。檢查host是否誤帶了圓點例如home.這種寫法通常是錯誤的。4. IP 格式不匹配現象type為A但傳入了 IPv6 地址或反之。排查步驟確認type與ip格式一致。如果使用腳本自動獲取 IP注意區分 IPv4 與 IPv6避免拿到的地址來自不同的網絡出口設備。工程化接入注意事項定時更新頻率該接口 QPS 為 5 次/秒。DDNS 場景中不建議高頻輪詢通常每 5 到 10 分鐘執行一次即可。更新前先比較本地獲取的公網 IP 與當前 DNS 解析結果只有不一致時才調用接口既能減少無效請求也能降低觸發限流的概率。獲取公網 IP 的方式接口本身不負責探測公網 IP因此客戶端需要自行獲取。常見方法包括# 獲取 IPv4 curl -4 -sS https://api.ipify.org # 獲取 IPv6 curl -6 -sS https://api.ipify.org獲取到 IP 后再將其組裝進 Cloudflare DNS 更新請求體中。注意使用公共 IP 查詢服務時應選擇可信來源并評估其穩定性。失敗重試策略敏感信息管理Cloudflare API Token 是敏感憑據應避免硬編碼在腳本或代碼倉庫中。建議通過環境變量、密鑰管理服務或配置文件注入。示例export CLOUDFLARE_API_TOKENyour_cloudflare_api_token然后在腳本中讀取TOKEN${CLOUDFLARE_API_TOKEN}日志記錄每次更新應記錄時間、域名、舊 IP、新 IP 以及接口返回的code和changed字段。這樣在 DNS 解析異常時可以快速定位是更新失敗、IP 獲取錯誤還是 Cloudflare Token 權限變更。參考文檔接口文檔https://apizero.cn/aidocs/cf-dns原始 Markdown 文檔https://apizero.cn/aidocs/cf-dns/raw.md