Cloudflare API 实战指南：从 Token 配置到 DNS 与缓存自动化管理

发布人：慈云数据-客服中心发布时间：5小时前阅读量：4

Cloudflare API接口调用教程｜附配置文件

在现代网站运维、自动化部署、DNS管理、CDN配置与安全策略维护中，Cloudflare 是非常常用的一站式平台。它提供了 DNS 解析、CDN 加速、DDoS 防护、WAF 防火墙、SSL/TLS、Workers、Pages、R2 存储等大量能力。除了在 Cloudflare 控制台中手动操作外，Cloudflare 还提供了非常完整的 API 接口，方便开发者通过脚本、CI/CD、自动化平台或后端服务批量管理资源。

本文将从基础概念讲起，详细介绍 Cloudflare API 的认证方式、调用流程、常见接口示例，并附带可直接使用的配置文件与脚本示例，适合希望通过 API 自动化管理 Cloudflare 的开发者、运维人员和站长参考。

一、Cloudflare API 可以做什么？

Cloudflare API 能完成控制台中的大多数操作，例如：

查询账号信息
查询 Zone，也就是站点信息
新增、修改、删除 DNS 解析记录
修改 SSL/TLS 模式
清理 CDN 缓存
配置页面规则
管理防火墙规则
管理 Access、Workers、Pages、R2 等资源
自动化证书、域名、缓存和安全策略维护

其中最常见的使用场景包括：

自动更新 DNS 记录
例如家用宽带或云服务器 IP 变化后，自动将域名 A 记录更新为新 IP。
自动清理缓存
在网站发布新版本后，通过 API 自动清除 Cloudflare CDN 缓存。
批量管理域名解析
如果你管理大量域名，可以通过脚本统一新增或修改解析。
CI/CD 集成
在 GitHub Actions、GitLab CI、Jenkins 等流程中调用 Cloudflare API，实现部署后自动刷新缓存或更新配置。
安全策略自动化
根据业务需求自动调整防火墙规则、IP 黑白名单等。

二、调用 Cloudflare API 前的准备工作

在正式调用 API 之前，需要准备以下内容：

Cloudflare 账号
已托管到 Cloudflare 的域名
API Token
Zone ID
Account ID，部分接口需要

Cloudflare API 的官方基础地址为：

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

所有接口基本都以该地址作为前缀。

三、创建 Cloudflare API Token

Cloudflare 早期支持使用 Global API Key，但现在更推荐使用 API Token。API Token 可以按需配置权限，更安全，也更适合自动化调用。

1. 登录 Cloudflare 控制台

访问：

https://dash.cloudflare.com/

登录账号后，点击右上角头像，进入：

My Profile / 我的个人资料

然后选择：

API Tokens

点击：

Create Token

2. 选择 Token 模板

如果只是管理 DNS，可以选择 Cloudflare 提供的模板：

Edit zone DNS

也可以选择自定义 Token。

3. 推荐 DNS 管理 Token 权限

如果只想通过 API 管理某个域名的 DNS 记录，可以设置如下权限：

类型	权限
Zone	DNS
Zone	Zone

资源范围建议选择：

Include - Specific zone - example.com

这样 Token 只对某一个域名生效，安全性更高。

4. 保存 API Token

创建完成后，Cloudflare 只会显示一次 Token。请务必保存，例如：

CLOUDFLARE_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

注意：不要将 Token 直接提交到 GitHub、GitLab 等公开代码仓库中。

四、获取 Zone ID

Cloudflare 中的每个站点都有一个唯一的 Zone ID。很多接口都需要使用它。

方法一：控制台查看

进入 Cloudflare 控制台，选择某个域名，在首页右侧通常可以看到：

Zone ID

复制即可。

方法二：通过 API 查询 Zone ID

如果你知道域名，也可以通过 API 查询：

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"
    }
  ],
  "success": true
}

其中 id 就是 Zone ID。

五、Cloudflare API 请求格式说明

Cloudflare API 通常采用 RESTful 风格，常用请求方法包括：

方法	说明
GET	查询资源
POST	创建资源
PUT	完整更新资源
PATCH	部分更新资源
DELETE	删除资源

认证方式通常为：

Authorization: Bearer YOUR_API_TOKEN

请求头一般需要：

Content-Type: application/json

典型请求结构如下：

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

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

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

其中：

success：请求是否成功
errors：错误信息列表
messages：提示信息
result：实际数据内容

六、附：基础配置文件示例

为了避免每次调用 API 都手动输入 Token、Zone ID、域名等参数，建议将配置写入单独的配置文件。

1. `.env` 配置文件

适合 Node.js、Python、Shell 脚本等场景。

# Cloudflare API Token
CLOUDFLARE_API_TOKEN=your_cloudflare_api_token

# Cloudflare Zone ID
CLOUDFLARE_ZONE_ID=your_zone_id

# 域名
CLOUDFLARE_DOMAIN=example.com

# 默认 API 地址
CLOUDFLARE_API_BASE=https://api.cloudflare.com/client/v4

注意：.env 文件通常包含敏感信息，应加入 .gitignore，避免泄露。

.gitignore 示例：

.env
*.log
node_modules/
__pycache__/

七、使用 curl 调用 Cloudflare API

curl 是最直接的 API 调试工具，适合快速验证 Token 是否有效，以及测试接口参数。

1. 查询账号下所有 Zone

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

如果 Token 权限正确，会返回当前 Token 可访问的域名列表。

2. 查询指定域名的 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 的 A 记录：

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

八、新增 DNS 解析记录

假设我们要新增一条 A 记录：

主机名：www.example.com
类型：A
记录值：1.2.3.4
TTL：自动
是否开启 Cloudflare 代理：开启

请求示例：

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": "www.example.com",
    "content": "1.2.3.4",
    "ttl": 1,
    "proxied": true
  }'

参数说明：

参数	说明
type	记录类型，如 A、AAAA、CNAME、TXT、MX
name	完整域名
content	解析目标
ttl	TTL，设置为 1 表示自动
proxied	是否开启 Cloudflare 代理

如果返回：

{
  "success": true
}

说明创建成功。

九、修改 DNS 解析记录

修改 DNS 记录需要先知道该记录的 record_id。可以先查询：

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

返回结果中会有类似字段：

{
  "id": "372e67954025e0ba6aaa6d586b9e0b59",
  "type": "A",
  "name": "www.example.com",
  "content": "1.2.3.4"
}

然后使用 PUT 更新：

curl -X PUT "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" \
  --data '{
    "type": "A",
    "name": "www.example.com",
    "content": "5.6.7.8",
    "ttl": 1,
    "proxied": true
  }'

如果只是修改部分字段，也可以使用 PATCH：

curl -X PATCH "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" \
  --data '{
    "content": "5.6.7.8"
  }'

十、删除 DNS 解析记录

删除记录同样需要 record_id：

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"

删除操作不可逆，建议在生产环境中先查询确认，再执行删除。

十一、清理 Cloudflare CDN 缓存

网站发布新版本后，可能需要清理 CDN 缓存。Cloudflare API 支持清理全部缓存，也支持按 URL 清理。

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
  }'

这种方式简单直接，但不建议频繁使用。因为清理全部缓存后，用户访问会重新回源，可能增加源站压力。

2. 按指定 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/assets/app.css"
    ]
  }'

更推荐按 URL 精准清理，尤其适合生产环境。

十二、使用 Shell 脚本自动更新 DNS

下面提供一个完整的 Shell 脚本，用于自动检测当前公网 IP，并更新 Cloudflare DNS A 记录。

1. 配置文件 `cloudflare.conf`

# Cloudflare API Token
CF_API_TOKEN="your_cloudflare_api_token"

# Zone ID
CF_ZONE_ID="your_zone_id"

# 要更新的完整域名
CF_RECORD_NAME="home.example.com"

# DNS记录类型
CF_RECORD_TYPE="A"

# 是否开启代理：true 或 false
CF_PROXIED=false

# API地址
CF_API_BASE="https://api.cloudflare.com/client/v4"

2. 更新脚本 `update-cloudflare-dns.sh`

#!/usr/bin/env bash

set -e

CONFIG_FILE="./cloudflare.conf"

if [ ! -f "$CONFIG_FILE" ]; then
  echo "配置文件不存在：$CONFIG_FILE"
  exit 1
fi

source "$CONFIG_FILE"

CURRENT_IP=$(curl -s https://api.ipify.org)

if [ -z "$CURRENT_IP" ]; then
  echo "获取公网IP失败"
  exit 1
fi

echo "当前公网IP：$CURRENT_IP"

RECORD_RESPONSE=$(curl -s -X GET "$CF_API_BASE/zones/$CF_ZONE_ID/dns_records?type=$CF_RECORD_TYPE&name=$CF_RECORD_NAME" \
  -H "Authorization: Bearer $CF_API_TOKEN" \
  -H "Content-Type: application/json")

RECORD_ID=$(echo "$RECORD_RESPONSE" | sed -n 's/.*"id":"\([^"]*\)".*/\1/p' | head -n 1)
OLD_IP=$(echo "$RECORD_RESPONSE" | sed -n 's/.*"content":"\([^"]*\)".*/\1/p' | head -n 1)

if [ -z "$RECORD_ID" ]; then
  echo "未找到DNS记录，准备创建新记录"

  curl -s -X POST "$CF_API_BASE/zones/$CF_ZONE_ID/dns_records" \
    -H "Authorization: Bearer $CF_API_TOKEN" \
    -H "Content-Type: application/json" \
    --data "{
      \"type\": \"$CF_RECORD_TYPE\",
      \"name\": \"$CF_RECORD_NAME\",
      \"content\": \"$CURRENT_IP\",
      \"ttl\": 1,
      \"proxied\": $CF_PROXIED
    }"

  echo
  echo "DNS记录创建完成"
  exit 0
fi

echo "原DNS记录IP：$OLD_IP"

if [ "$CURRENT_IP" = "$OLD_IP" ]; then
  echo "IP未变化，无需更新"
  exit 0
fi

echo "IP发生变化，准备更新DNS记录"

curl -s -X PUT "$CF_API_BASE/zones/$CF_ZONE_ID/dns_records/$RECORD_ID" \
  -H "Authorization: Bearer $CF_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data "{
    \"type\": \"$CF_RECORD_TYPE\",
    \"name\": \"$CF_RECORD_NAME\",
    \"content\": \"$CURRENT_IP\",
    \"ttl\": 1,
    \"proxied\": $CF_PROXIED
  }"

echo
echo "DNS记录更新完成：$CF_RECORD_NAME -> $CURRENT_IP"

3. 授权执行

chmod +x update-cloudflare-dns.sh

执行：

./update-cloudflare-dns.sh

4. 配置定时任务

如果希望每 5 分钟自动检测一次公网 IP，可以使用 crontab：

crontab -e

添加：

*/5 * * * * /path/to/update-cloudflare-dns.sh >> /path/to/cloudflare-ddns.log 2>&1

十三、使用 Python 调用 Cloudflare API

如果你希望在后端项目中调用 Cloudflare API，Python 是非常方便的选择。

1. Python 配置文件 `config.py`

CLOUDFLARE_API_TOKEN = "your_cloudflare_api_token"
CLOUDFLARE_ZONE_ID = "your_zone_id"
CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4"
DOMAIN = "example.com"

2. 查询 DNS 记录示例

import requests
from config import CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_BASE

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

url = f"{CLOUDFLARE_API_BASE}/zones/{CLOUDFLARE_ZONE_ID}/dns_records"

response = requests.get(url, headers=headers)
data = response.json()

print(data)

3. 新增 DNS 记录示例

import requests
from config import CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_BASE

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

payload = {
    "type": "A",
    "name": "api.example.com",
    "content": "1.2.3.4",
    "ttl": 1,
    "proxied": True
}

url = f"{CLOUDFLARE_API_BASE}/zones/{CLOUDFLARE_ZONE_ID}/dns_records"

response = requests.post(url, headers=headers, json=payload)
print(response.json())

4. 清理缓存示例

import requests
from config import CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_BASE

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

payload = {
    "files": [
        "https://www.example.com/index.html",
        "https://www.example.com/assets/main.js"
    ]
}

url = f"{CLOUDFLARE_API_BASE}/zones/{CLOUDFLARE_ZONE_ID}/purge_cache"

response = requests.post(url, headers=headers, json=payload)
print(response.json())

十四、使用 Node.js 调用 Cloudflare API

Node.js 适合用于 Web 项目、部署脚本或 CI/CD 自动化。

1. 安装依赖

npm install axios dotenv

2. `.env` 配置文件

CLOUDFLARE_API_TOKEN=your_cloudflare_api_token
CLOUDFLARE_ZONE_ID=your_zone_id
CLOUDFLARE_API_BASE=https://api.cloudflare.com/client/v4

3. 查询 DNS 记录

require("dotenv").config();
const axios = require("axios");

const api = axios.create({
  baseURL: process.env.CLOUDFLARE_API_BASE,
  headers: {
    Authorization: `Bearer ${process.env.CLOUDFLARE_API_TOKEN}`,
    "Content-Type": "application/json",
  },
});

async function listDnsRecords() {
  try {
    const res = await api.get(`/zones/${process.env.CLOUDFLARE_ZONE_ID}/dns_records`);
    console.log(res.data);
  } catch (error) {
    console.error(error.response?.data || error.message);
  }
}

listDnsRecords();

4. 清理全部缓存

require("dotenv").config();
const axios = require("axios");

const api = axios.create({
  baseURL: process.env.CLOUDFLARE_API_BASE,
  headers: {
    Authorization: `Bearer ${process.env.CLOUDFLARE_API_TOKEN}`,
    "Content-Type": "application/json",
  },
});

async function purgeEverything() {
  try {
    const res = await api.post(`/zones/${process.env.CLOUDFLARE_ZONE_ID}/purge_cache`, {
      purge_everything: true,
    });
    console.log(res.data);
  } catch (error) {
    console.error(error.response?.data || error.message);
  }
}

purgeEverything();

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

1. `Authentication error`

通常表示 Token 错误或请求头不正确。

请检查：

Token 是否复制完整
是否使用了 Authorization: Bearer xxx
Token 是否已被删除或过期
是否错误使用了 Global API Key 的认证方式

正确示例：

-H "Authorization: Bearer YOUR_API_TOKEN"

2. `com.cloudflare.api.account.zone.invalid`

通常表示 Zone ID 不正确，或者 Token 没有访问该 Zone 的权限。

解决方法：

确认 Zone ID 是否复制正确
确认 Token 资源范围是否包含当前域名
确认域名是否已经添加到 Cloudflare

3. `Record already exists`

表示相同类型、相同名称的 DNS 记录可能已经存在。

解决方法：

先查询记录是否存在
如果存在则使用 PUT 或 PATCH 更新
不要重复创建相同记录

4. `Invalid content for DNS record`

表示 DNS 记录内容不合法。

例如：

A 记录必须是 IPv4 地址
AAAA 记录必须是 IPv6 地址
CNAME 记录应填写目标域名
MX 记录需要额外设置优先级

5. API 返回 `success: false`

如果返回：

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

应优先查看 errors 数组中的 message 和 code，Cloudflare 的错误信息通常比较明确。

十六、安全建议

调用 Cloudflare API 时，一定要注意 Token 安全。以下是一些推荐做法：

使用 API Token，不要优先使用 Global API Key
API Token 可以限制权限和资源范围，更适合自动化。
最小权限原则
如果脚本只需要更新 DNS，就不要授予缓存、WAF、Workers 等权限。
限制 Zone 范围
尽量选择 Specific zone，而不是所有 Zone。
不要硬编码 Token
建议使用 .env、系统环境变量或密钥管理工具。
不要提交配置文件到公开仓库
将 .env、cloudflare.conf 加入 .gitignore。
定期轮换 Token
对长期运行的自动化任务，建议定期更换 API Token。
CI/CD 中使用 Secret
在 GitHub Actions、GitLab CI 中应使用平台提供的 Secrets 功能保存 Token。

十七、GitHub Actions 中调用 Cloudflare API 示例

如果你希望在网站部署后自动清理 Cloudflare 缓存，可以使用 GitHub Actions。

1. 添加 GitHub Secrets

在仓库中进入：

Settings -> Secrets and variables -> Actions

添加：

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ZONE_ID

2. 工作流配置文件

创建文件：

.github/workflows/purge-cloudflare-cache.yml

内容如下：

name: Purge Cloudflare Cache

on:
  push:
    branches:
      - main

jobs:
  purge-cache:
    runs-on: ubuntu-latest

    steps:
      - name: Purge Cloudflare Cache
        run: |
          curl -X POST "https://api.cloudflare.com/client/v4/zones/${{ secrets.CLOUDFLARE_ZONE_ID }}/purge_cache" \
            -H "Authorization: Bearer ${{ secrets.CLOUDFLARE_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            --data '{"purge_everything":true}'

这样，每次推送到 main 分支后，都会自动清理 Cloudflare 缓存。

如果你的网站资源较多，不建议清理全部缓存，可以改为按 URL 清理。

十八、生产环境调用建议

在生产环境中使用 Cloudflare API，不建议只关注“能不能调用成功”，还应该考虑稳定性和可维护性。

1. 增加错误处理

脚本中应判断接口返回的 success 字段。如果为 false，应记录错误内容，并停止后续操作。

2. 增加日志

对于 DNS 更新、缓存清理、防火墙规则变更等操作，建议记录操作时间、请求参数和返回结果，方便追踪。

3. 避免频繁清理全部缓存

频繁清理全部缓存会导致大量请求回源，可能影响源站性能。建议优先使用按 URL 清理、缓存版本号或文件 hash 策略。

4. 控制调用频率

Cloudflare API 有一定的速率限制。批量操作时应控制请求间隔，避免短时间内发起过多请求。

5. 区分测试环境和生产环境

如果脚本用于多个域名或多个环境，建议使用不同的配置文件，例如：

cloudflare.dev.conf
cloudflare.prod.conf

避免误操作生产环境。

十九、总结

Cloudflare API 是实现网站自动化运维的重要工具。通过 API，我们可以完成 DNS 管理、缓存清理、安全策略配置、资源查询等操作。对于个人站长来说，它可以实现 DDNS、自动刷新缓存；对于团队和企业来说，它可以集成到 CI/CD 流程中，提升部署效率和运维一致性。

本文介绍了 Cloudflare API 的 Token 创建、Zone ID 获取、curl 调用方式、DNS 记录增删改查、缓存清理、Shell/Python/Node.js 示例，以及常见错误排查和安全建议。实际使用时，建议遵循最小权限原则，将 Token 保存在安全位置，并为生产环境脚本增加日志、错误处理和权限隔离。

只要掌握了 Cloudflare API 的基本调用方式，就可以将很多重复的控制台操作变成自动化流程，从而显著提升运维效率。

文章标签： CloudflareAPI APIToken DNS管理缓存清理

上一篇：Cloudflare API 实战指南：DNS 管理、缓存清理与自动化命令大全

下一篇：不用公网 IP，把家里 Docker 服务接入 Cloudflare Tunnel 教程 2026最新版

更多栏目

新闻动态

文档中心

下载中心

目录结构

全文

产品与服务

新闻帮助

生态合作

了解我们