DDNS/docs/providers/cloudflare.md

Cloudflare DNS 配置指南

概述

Cloudflare 是全球领先的 CDN 和网络安全服务提供商，提供权威 DNS 解析服务，支持动态 DNS 记录的创建与更新。本 DDNS 项目通过 Cloudflare API 进行 DNS 记录的自动管理。

官网链接：

• 官方网站：https://www.cloudflare.com/
• 服务商控制台：https://dash.cloudflare.com/

认证信息

1. API Token 认证（推荐）

API Token 方式更安全，支持精细化权限控制，是 Cloudflare 推荐的集成方法。

获取认证信息

1. 登录 Cloudflare 控制台
2. 进入"我的个人资料" > "API 令牌"或访问 https://dash.cloudflare.com/profile/api-tokens
3. 点击"创建令牌"，选择"自定义令牌"模板
4. 配置权限：
   • 区域：读取 (Zone:Read)
   • DNS：编辑 (Zone:DNS:Edit)
5. 选择要管理的域名区域
6. 复制生成的 API Token，令牌只显示一次，请妥善保存

{
    "dns": "cloudflare",
    "token": "your_cloudflare_api_token"  // Cloudflare API Token, ID 留空或者不填
}

2. Global API Key 认证（不推荐）

使用 Cloudflare 账户邮箱和 Global API Key，权限过大，安全性较低，仅建议特殊场景使用。

获取 Global API Key

1. 登录 Cloudflare 控制台
2. 进入"我的个人资料" > "API 令牌"
3. 查看"Global API Key"并复制

{
    "dns": "cloudflare",
    "id": "your-email@example.com",    // Cloudflare 账户邮箱
    "token": "your_global_api_key"     // Cloudflare Global API Key
}

权限要求

确保使用的 Cloudflare 账号具有以下权限：

API Token 权限

• Zone:Read：区域读取权限，用于列出和获取域名区域信息
• Zone:DNS:Edit：DNS 编辑权限，用于创建、更新和删除 DNS 记录

Global API Key 权限

• 完全访问权限：拥有账户下所有资源的完全控制权限

可以在 Cloudflare API 令牌管理 中查看和配置权限。

完整配置示例

{
    "$schema": "https://ddns.newfuture.cc/schema/v4.1.json", // 格式验证
    "dns": "cloudflare",                // 当前服务商
    "token": "your_cloudflare_api_token", // Cloudflare API Token
    "index4": ["url:http://api.ipify.org", "public"], // IPv4地址来源
    "index6": "public",                     // IPv6地址来源
    "ipv4": ["ddns.newfuture.cc"],           // IPv4 域名
    "ipv6": ["ddns.newfuture.cc", "ipv6.ddns.newfuture.cc"], // IPv6 域名
    "ttl": 300,                             // DNS记录TTL（秒）
    "proxied": false                        // 是否启用 Cloudflare 代理
}

参数说明

参数	说明	类型	取值范围/选项	默认值	参数类型
dns	服务商标识	字符串	cloudflare	无	服务商参数
id	认证邮箱	字符串	Cloudflare 账户邮箱（仅 Global API Key）	无	服务商参数
token	认证密钥	字符串	Cloudflare API Token 或 Global API Key	无	服务商参数
index4	IPv4 来源	数组	参考配置	default	公用配置
index6	IPv6 来源	数组	参考配置	default	公用配置
ipv4	IPv4 域名	数组	域名列表	无	公用配置
ipv6	IPv6 域名	数组	域名列表	无	公用配置
ttl	TTL 时间	整数（秒）	参考下方	300/auto	服务商参数
proxied	代理状态	布尔	true、false	无	服务商参数
proxy	代理设置	数组	参考配置	无	公用网络
ssl	SSL 验证方式	布尔/字符串	"auto"、true、false	auto	公用网络
cache	缓存设置	布尔/字符串	true、false、filepath	true	公用配置
log	日志配置	对象	参考配置	无	公用配置

参数类型说明：

• 公用配置：所有支持的DNS服务商均适用的标准DNS配置参数
• 公用网络：所有支持的DNS服务商均适用的网络设置参数
• 服务商参数：当前服务商支持, 值与当前服务商相关

proxied

proxied 参数控制 DNS 记录是否通过 Cloudflare 代理。这是 Cloudflare 特有的功能，用于启用或禁用其 CDN 和安全保护功能。

查询记录匹配逻辑

当配置了 proxied 参数时，DDNS 会按照以下优先级查询现有的 DNS 记录：

1. 优先使用 proxied 过滤：首先尝试查询匹配指定 proxied 状态的记录
2. 回退到无过滤查询：如果带有 proxied 过滤的查询没有找到记录，将自动重试不带 proxied 过滤的查询

这种回退机制确保了以下场景的正确处理：

• 场景1: 配置文件从 "proxied": true 改为 "proxied": false

  • 即使原记录是 proxied=true，系统也能找到并更新它

• 场景2: 配置文件从 "proxied": false 改为 "proxied": true

  • 即使原记录是 proxied=false，系统也能找到并更新它

• 场景3: 配置文件新增 "proxied": true/false 参数

  • 能够找到不带 proxied 过滤创建的记录并进行更新

注意：如果查询时带 proxied 过滤找到了记录，则不会执行回退查询，直接使用匹配的记录。

ttl

ttl 参数指定 DNS 记录的生存时间（TTL），单位为秒。Cloudflare 的 TTL 设置根据记录是否启用代理而有所不同。

代理记录 (Proxied Records)

所有代理记录的 TTL 默认为 Auto，固定设置为 300 秒（5 分钟），此值无法编辑。

由于只有用于 IP 地址解析的记录才能被代理，此设置确保分配的任播 IP 地址的潜在变化能够快速生效，因为递归解析器不会将其缓存超过 300 秒。

注意：实际体验记录变化可能需要超过 5 分钟，因为本地 DNS 缓存可能需要更长时间才能更新。

非代理记录 (Unproxied Records)

对于仅 DNS 记录，您可以选择以下 TTL 范围：

套餐类型	支持的 TTL 范围（秒）	说明
Free/Pro/Business	60 - 86400	最低 TTL 为 1 分钟
Enterprise	30 - 86400	最低 TTL 为 30 秒

参考：Cloudflare TTL 说明

故障排除

调试模式

启用调试日志查看详细信息：

ddns -c config.json --debug

常见问题

• Invalid API token：检查 API Token 是否正确，确认权限配置
• Zone not found：确保域名已添加到 Cloudflare 账号，域名处于活跃状态
• Record creation failed：检查记录格式和 TTL 值，确认权限设置
• Rate limit exceeded：API 调用频率超限，降低请求频率

错误处理与缓存

Cloudflare 请求只有在 HTTP 状态为 2xx 且 API 返回 success: true 时才视为成功。 最终收到 HTTP 429 等错误状态，或 API 返回 success: false、无效响应时，本次域名更新会失败，不会将待更新的 IP 写入成功缓存，后续同步仍会重试。 区域或记录查询失败会终止当前域名的处理，不会被当作“记录不存在”而创建新记录；成功查询返回空记录列表时，仍会正常进入创建流程。

支持与资源

• Cloudflare 开发者文档
• Cloudflare API 参考
• Cloudflare 控制台
• Cloudflare 社区支持

建议：推荐使用 API Token 方式，支持精细化权限控制，提升账号安全性，避免使用 Global API Key。