Cloudflare API接口调用教程｜生产环境实测

在生产环境中使用 Cloudflare，很多操作如果只依赖控制台手工完成，效率会非常低，也不利于自动化运维。例如：批量解析域名、自动刷新缓存、接入 CI/CD 发布流程、动态调整防火墙规则、查询流量与安全日志等。Cloudflare 提供了非常完整的 API 能力，几乎所有控制台里的功能都可以通过 API 完成。

本文将结合生产环境中的实际使用经验，系统讲解 Cloudflare API 的调用方式、认证配置、常见接口示例、自动化脚本写法以及线上使用时需要注意的安全与稳定性问题。

一、Cloudflare API 能做什么？

Cloudflare API 是 Cloudflare 官方提供的接口服务，允许开发者通过 HTTP 请求对 Cloudflare 账户下的资源进行管理。

常见使用场景包括：

• 自动添加、修改、删除 DNS 解析记录；
• 查询域名 Zone 信息；
• 自动清理 CDN 缓存；
• 查询防火墙事件、安全事件；
• 管理 WAF、防火墙规则、Page Rules；
• 查询流量统计、带宽、请求数；
• 自动化部署后刷新指定 URL 缓存；
• 结合 DevOps 平台实现发布流水线；
• 批量管理多个域名配置。

在生产环境中，最常用的 API 通常是：

1. DNS 解析管理 API
2. 缓存清理 API
3. Zone 查询 API
4. 防火墙与安全规则 API
5. Analytics 查询 API

二、Cloudflare API 认证方式

Cloudflare API 目前推荐使用 API Token 方式认证，而不是老版本的 Global API Key。

1. API Token 与 Global API Key 的区别

在生产环境中，强烈建议使用 API Token。原因很简单：
如果 Global API Key 泄露，攻击者几乎可以完全控制你的 Cloudflare 账户；而 API Token 可以限制只能操作某个域名、某类资源，即使泄露，影响范围也更可控。

三、创建 Cloudflare API Token

登录 Cloudflare 控制台后，进入：

My Profile -> API Tokens -> Create Token

Cloudflare 提供了一些模板，例如：

• Edit zone DNS
• Purge cache
• Read analytics
• Edit Cloudflare Workers

如果只是管理 DNS，可以选择：

Edit zone DNS

如果只是刷新缓存，可以选择：

Purge Cache

也可以选择自定义 Token，生产环境推荐使用自定义方式，便于权限最小化。

四、生产环境推荐的 Token 权限配置

假设我们只想让某个发布系统在部署完成后刷新 CDN 缓存，那么不应该给它 DNS 编辑权限，而只应该给它缓存清理权限。

缓存清理 Token 示例权限

Permissions:
Zone -> Cache Purge -> Purge

Zone Resources:
Include -> Specific zone -> example.com

DNS 管理 Token 示例权限

Permissions:
Zone -> DNS -> Edit

Zone Resources:
Include -> Specific zone -> example.com

查询 Zone 信息 Token 权限

Permissions:
Zone -> Zone -> Read

Zone Resources:
Include -> Specific zone -> example.com

生产环境建议：

• 不要把多个系统共用一个 Token；
• 不要创建全局权限 Token；
• 每个业务系统单独创建 Token；
• Token 只授权给必要的 Zone；
• 定期轮换 Token；
• 不要将 Token 写死在代码仓库中。

五、Cloudflare API 基础调用格式

Cloudflare API 的基础地址为：

https://api.cloudflare.com/client/v4

调用 API 时，需要在请求头中携带 Token。

curl 基础格式

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

如果 Token 有效，会返回类似结果：

{
  "result": {
    "id": "xxxxxxxxxxxxxxxx",
    "status": "active"
  },
  "success": true,
  "errors": [],
  "messages": [
    {
      "code": 10000,
      "message": "This API Token is valid and active",
      "type": null
    }
  ]
}

其中最关键的是：

"success": true

如果返回 success: false，通常说明 Token 无效、权限不足或请求格式错误。

六、获取 Zone ID

Cloudflare 的很多接口都需要 zone_id。Zone ID 可以理解为 Cloudflare 中某个域名的唯一标识。

例如你的域名是：

example.com

可以通过以下接口查询 Zone ID。

curl 示例

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

返回示例：

{
  "result": [
    {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com",
      "status": "active",
      "paused": false,
      "type": "full"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

这里的：

023e105f4ecef8ad9ca31a8372d0c353

就是 Zone ID。

在生产环境中，建议把 Zone ID 配置到环境变量或配置中心，避免每次调用都查询一次。

七、查询 DNS 解析记录

查询 DNS 记录是非常常见的操作，比如确认当前域名解析是否正确、脚本更新前先判断记录是否存在。

查询全部 DNS 记录

curl -X GET "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

查询指定域名记录

例如查询：

www.example.com

可以这样写：

curl -X GET "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/dns_records?name=www.example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

返回示例：

{
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b59",
      "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
      "zone_name": "example.com",
      "name": "www.example.com",
      "type": "A",
      "content": "192.0.2.1",
      "proxied": true,
      "ttl": 1
    }
  ],
  "success": true
}

其中：

• id：DNS 记录 ID，更新和删除记录时需要；
• type：记录类型，如 A、AAAA、CNAME、TXT；
• content：解析值；
• proxied：是否启用 Cloudflare 代理；
• ttl：TTL，1 表示自动。

八、新增 DNS 解析记录

假设需要新增一条 A 记录：

api.example.com -> 192.0.2.10

curl 示例

curl -X POST "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "A",
    "name": "api.example.com",
    "content": "192.0.2.10",
    "ttl": 1,
    "proxied": true
  }'

参数说明：

关于 proxied 的生产环境建议

如果是网站、API、静态资源等 HTTP/HTTPS 服务，通常可以设置：

"proxied": true

这样流量会经过 Cloudflare，享受 CDN、WAF、防护等能力。

如果是数据库、SSH、邮件相关记录，一般不要开启代理，应设置：

"proxied": false

否则可能导致协议不可用。

九、更新 DNS 解析记录

更新 DNS 记录需要先知道该记录的 record_id。

假设记录 ID 为：

372e67954025e0ba6aaa6d586b9e0b59

将 api.example.com 的 IP 更新为：

192.0.2.20

PUT 全量更新

curl -X PUT "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/dns_records/372e67954025e0ba6aaa6d586b9e0b59" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "A",
    "name": "api.example.com",
    "content": "192.0.2.20",
    "ttl": 1,
    "proxied": true
  }'

需要注意，PUT 通常是全量更新。也就是说，你最好把完整字段都传过去，避免某些配置被默认值覆盖。

PATCH 局部更新

如果只想修改某些字段，可以使用 PATCH：

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/dns_records/372e67954025e0ba6aaa6d586b9e0b59" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "content": "192.0.2.20"
  }'

在生产环境中，如果只是更新 IP，推荐使用 PATCH，减少误改其他字段的风险。

十、删除 DNS 解析记录

删除记录的接口如下：

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

返回示例：

{
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59"
  },
  "success": true,
  "errors": [],
  "messages": []
}

生产环境中不建议直接删除，尤其是批量脚本。更稳妥的方式是：

1. 先查询记录；
2. 打印即将删除的记录；
3. 要求二次确认；
4. 删除后再次查询验证；
5. 将操作日志写入审计系统。

十一、清理 Cloudflare CDN 缓存

这是生产环境中使用频率最高的 API 之一。

网站发布后，如果静态资源或页面被 Cloudflare 缓存，用户可能看到旧内容。此时可以通过 API 自动清理缓存。

1. 清理全部缓存

curl -X POST "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "purge_everything": true
  }'

这个操作会清理整个 Zone 的缓存。

生产环境不建议频繁使用 purge_everything，原因包括：

• 会导致大量缓存失效；
• 源站瞬间回源压力增大；
• 可能影响整体访问速度；
• 对高流量站点可能造成源站抖动。

2. 清理指定 URL 缓存

更推荐清理指定 URL：

curl -X POST "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "files": [
      "https://www.example.com/index.html",
      "https://www.example.com/static/app.js",
      "https://www.example.com/static/app.css"
    ]
  }'

生产环境建议：

• 首页、重要落地页可以指定 URL 刷新；
• 静态资源使用文件 hash，例如 app.abc123.js；
• 不要每次发布都全站刷新；
• 对大流量业务，刷新操作要限频；
• 发布系统中增加缓存刷新失败重试逻辑。

十二、Python 调用 Cloudflare API 示例

生产环境中，很多自动化脚本会使用 Python。下面给出一个完整的 Python 示例，用于查询 DNS 记录并更新 IP。

安装 requests

pip install requests

Python 示例代码

import os
import requests

API_TOKEN = os.getenv("CF_API_TOKEN")
ZONE_ID = os.getenv("CF_ZONE_ID")

BASE_URL = "https://api.cloudflare.com/client/v4"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}


def get_dns_record(name):
    url = f"{BASE_URL}/zones/{ZONE_ID}/dns_records"
    params = {
        "name": name
    }

    response = requests.get(url, headers=headers, params=params, timeout=10)
    response.raise_for_status()

    data = response.json()

    if not data.get("success"):
        raise RuntimeError(f"Cloudflare API error: {data.get('errors')}")

    records = data.get("result", [])
    if not records:
        return None

    return records[0]


def update_dns_record(record_id, record_type, name, content, proxied=True):
    url = f"{BASE_URL}/zones/{ZONE_ID}/dns_records/{record_id}"

    payload = {
        "type": record_type,
        "name": name,
        "content": content,
        "ttl": 1,
        "proxied": proxied
    }

    response = requests.put(url, headers=headers, json=payload, timeout=10)
    response.raise_for_status()

    data = response.json()

    if not data.get("success"):
        raise RuntimeError(f"Cloudflare API error: {data.get('errors')}")

    return data.get("result")


if __name__ == "__main__":
    domain = "api.example.com"
    new_ip = "192.0.2.20"

    record = get_dns_record(domain)

    if not record:
        print(f"DNS record not found: {domain}")
    else:
        print(f"Current IP: {record['content']}")
        result = update_dns_record(
            record_id=record["id"],
            record_type=record["type"],
            name=record["name"],
            content=new_ip,
            proxied=record.get("proxied", True)
        )
        print(f"Updated: {result['name']} -> {result['content']}")

环境变量配置

Linux/macOS：

export CF_API_TOKEN="your_api_token"
export CF_ZONE_ID="your_zone_id"
python update_dns.py

生产环境不建议将 Token 直接写进代码，而应该放在：

• 环境变量；
• Kubernetes Secret；
• CI/CD Secret；
• 配置中心；
• 密钥管理系统，例如 Vault、AWS Secrets Manager 等。

十三、Node.js 调用示例

如果你的发布系统是 Node.js，也可以很方便地调用 Cloudflare API。

const axios = require("axios");

const API_TOKEN = process.env.CF_API_TOKEN;
const ZONE_ID = process.env.CF_ZONE_ID;

const client = axios.create({
  baseURL: "https://api.cloudflare.com/client/v4",
  headers: {
    Authorization: `Bearer ${API_TOKEN}`,
    "Content-Type": "application/json"
  },
  timeout: 10000
});

async function purgeCache(files) {
  const response = await client.post(`/zones/${ZONE_ID}/purge_cache`, {
    files
  });

  if (!response.data.success) {
    throw new Error(JSON.stringify(response.data.errors));
  }

  return response.data.result;
}

(async () => {
  try {
    const result = await purgeCache([
      "https://www.example.com/index.html",
      "https://www.example.com/static/app.js"
    ]);

    console.log("Cache purged:", result);
  } catch (error) {
    console.error("Cloudflare API error:", error.message);
    process.exit(1);
  }
})();

十四、CI/CD 中自动刷新缓存

在生产部署流程中，通常会在发布完成后调用 Cloudflare API 刷新缓存。

一个常见流程如下：

拉取代码
  ↓
构建前端资源
  ↓
上传到服务器或对象存储
  ↓
更新服务
  ↓
健康检查
  ↓
调用 Cloudflare API 刷新缓存
  ↓
通知发布结果

GitHub Actions 示例

name: Deploy and Purge Cloudflare Cache

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy
        run: |
          echo "Deploy your application here"

      - name: Purge Cloudflare Cache
        run: |
          curl -X POST "https://api.cloudflare.com/client/v4/zones/${{ secrets.CF_ZONE_ID }}/purge_cache" \
            -H "Authorization: Bearer ${{ secrets.CF_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            --data '{
              "files": [
                "https://www.example.com/index.html"
              ]
            }'

需要注意：

• CF_API_TOKEN 必须放在 GitHub Secrets；
• 不要在日志中打印 Token；
• 如果部署失败，不应执行缓存刷新；
• 建议在健康检查成功之后再刷新缓存；
• 对大型站点建议只刷新必要 URL。

十五、API 返回结构解析

Cloudflare API 的返回通常包含以下字段：

{
  "result": {},
  "success": true,
  "errors": [],
  "messages": []
}

字段说明：

生产环境中不能只判断 HTTP 状态码，还应该判断：

data.get("success")

因为有些情况下 HTTP 状态码可能是 200，但 Cloudflare 返回的 success 可能为 false。

十六、常见错误与排查方法

1. 认证失败

错误表现：

{
  "success": false,
  "errors": [
    {
      "code": 10000,
      "message": "Authentication error"
    }
  ]
}

常见原因：

• Token 写错；
• Token 已被删除；
• 请求头格式错误；
• 使用了错误的认证方式。

正确请求头：

Authorization: Bearer YOUR_API_TOKEN

2. 权限不足

可能返回：

{
  "success": false,
  "errors": [
    {
      "message": "Actor does not have permission"
    }
  ]
}

排查方向：

• Token 是否具有对应权限；
• Token 是否授权给当前 Zone；
• 是否把 DNS Token 用来刷新缓存；
• 是否把只读 Token 用来执行写操作。

3. Zone ID 错误

如果 Zone ID 写错，通常会出现资源不存在或权限不足。

排查方式：

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

确认返回的 Zone ID 是否与配置一致。

4. DNS 记录不存在

更新 DNS 时必须提供记录 ID，而不是域名本身。如果你直接拿域名当 record_id，会调用失败。

正确流程：

1. 根据 name 查询 DNS 记录；
2. 从返回结果中获取 id；
3. 使用该 id 更新或删除记录。

5. 请求超时

生产环境中调用 Cloudflare API 应设置超时时间，不建议无限等待。

例如 Python：

requests.get(url, headers=headers, timeout=10)

如果没有 timeout，脚本可能因为网络异常一直挂起，影响部署流程。

十七、生产环境实测经验总结

结合实际线上使用，Cloudflare API 非常稳定，但生产环境使用时仍然需要注意以下几点。

1. Token 权限必须最小化

这是最重要的一点。不要为了方便给 Token 配置过大的权限。

例如刷新缓存只需要：

Zone -> Cache Purge -> Purge

不要额外给 DNS 编辑权限。

2. 不要频繁全站清缓存

purge_everything 看起来方便，但对高流量站点并不友好。缓存全部失效后，用户请求会大量回源，如果源站容量不足，可能出现接口变慢甚至雪崩。

更推荐：

• 静态资源使用版本号或 hash；
• HTML 页面指定 URL 清理；
• 大规模更新分批刷新；
• 对刷新频率做限制。

3. 部署流程中加入失败处理

例如缓存刷新失败时，不一定要直接判定整个发布失败。具体要看业务场景：

• 如果是静态站点首页更新，刷新失败影响较大；
• 如果只是某个非核心页面，可以记录告警后人工处理；
• 如果涉及紧急修复，刷新失败应立即通知运维。

建议将 API 调用结果写入日志，并接入告警系统。

4. API 调用要有重试机制

网络抖动、临时超时是正常现象。生产脚本建议支持重试。

例如：

• 第一次失败后等待 1 秒；
• 第二次失败后等待 3 秒；
• 第三次失败后记录错误并退出。

但要注意，删除记录、修改安全规则等操作不应盲目重试，最好保证幂等性。

5. 关键操作要记录审计日志

尤其是：

• DNS 修改；
• DNS 删除；
• 防火墙规则修改；
• WAF 开关变更；
• 缓存全站清理。

日志中应记录：

• 操作时间；
• 操作人或系统；
• 操作对象；
• 修改前内容；
• 修改后内容；
• Cloudflare 返回结果。

6. 注意 API 速率限制

Cloudflare API 有速率限制。普通业务调用通常不会触发，但批量操作大量 DNS 记录、批量刷新 URL 时需要注意。

建议：

• 批量任务分批执行；
• 控制并发数量；
• 失败后指数退避；
• 不要在短时间内重复清理相同资源。

十八、一个生产可用的缓存刷新 Shell 脚本

下面是一个更接近生产环境的 Shell 示例。

#!/usr/bin/env bash

set -euo pipefail

CF_API_TOKEN="${CF_API_TOKEN:-}"
CF_ZONE_ID="${CF_ZONE_ID:-}"

if [[ -z "$CF_API_TOKEN" ]]; then
  echo "ERROR: CF_API_TOKEN is empty"
  exit 1
fi

if [[ -z "$CF_ZONE_ID" ]]; then
  echo "ERROR: CF_ZONE_ID is empty"
  exit 1
fi

URLS=(
  "https://www.example.com/index.html"
  "https://www.example.com/about.html"
)

FILES_JSON=$(printf '"%s",' "${URLS[@]}")
FILES_JSON="[${FILES_JSON%,}]"

PAYLOAD="{\"files\":${FILES_JSON}}"

echo "Purging Cloudflare cache..."
echo "Files: ${URLS[*]}"

RESPONSE=$(curl -sS -X POST "https://api.cloudflare.com/client/v4/zones/${CF_ZONE_ID}/purge_cache" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "${PAYLOAD}")

echo "Response: ${RESPONSE}"

SUCCESS=$(echo "$RESPONSE" | grep -o '"success":[^,}]*' | head -n1 | cut -d':' -f2)

if [[ "$SUCCESS" != "true" ]]; then
  echo "ERROR: Cloudflare cache purge failed"
  exit 1
fi

echo "Cloudflare cache purge success"

实际生产环境中，如果服务器安装了 jq，建议使用 jq 解析 JSON，而不是 grep。

十九、接口调用安全建议

Cloudflare API Token 属于敏感凭证，安全管理非常重要。

建议遵循以下原则：

1. 不写入代码仓库
   即使是私有仓库，也不要硬编码 Token。

2. 不打印到日志
   CI/CD 日志、服务器日志中都不应出现 Token。

3. 按环境隔离
   开发、测试、生产环境使用不同 Token。

4. 按系统隔离
   发布系统、监控系统、运维脚本分别使用不同 Token。

5. 定期轮换
   至少每隔一段时间更换一次 Token。

6. 离职或系统下线及时删除
   不再使用的 Token 应立即吊销。

7. 设置最小权限
   只给必要权限，不给额外权限。

二十、总结

Cloudflare API 是生产环境自动化运维中非常实用的工具。通过 API，可以把 DNS 管理、缓存刷新、安全规则调整、数据查询等操作纳入自动化流程，减少人工操作，提高发布效率和稳定性。

生产环境使用 Cloudflare API 时，核心要点可以总结为：

• 使用 API Token，不使用 Global API Key；
• Token 权限遵循最小化原则；
• 获取并固定 Zone ID；
• DNS 更新前先查询 record_id；
• 缓存刷新优先指定 URL，谨慎使用全站刷新；
• 所有 API 调用都要判断 success 字段；
• 设置超时、重试与错误处理；
• 关键操作记录审计日志；
• Token 不进代码仓库，不出现在日志里；
• 批量操作注意速率限制和源站压力。

如果只是简单调用，Cloudflare API 并不复杂；但如果要在生产环境长期稳定使用，就必须关注权限、安全、幂等、重试和审计。把这些细节做好，Cloudflare API 可以非常可靠地支撑你的自动化发布和运维体系。