SynologyCloudflareDDNS脚本原理解析：从域名解析到IP自动更新的完整流程

【免费下载链接】SynologyCloudflareDDNS📜 Cloudflare DDNS script for Synology项目地址: https://gitcode.com/gh_mirrors/sy/SynologyCloudflareDDNS

SynologyCloudflareDDNS是一款专为群晖NAS设计的Cloudflare DDNS脚本，通过Cloudflare API v4实现域名解析与IP地址的自动同步，帮助用户轻松管理动态IP环境下的域名访问。本文将深入解析其工作原理，从IP检测到Cloudflare API交互的完整流程，让新手用户也能理解背后的技术细节。

核心功能：为何选择Cloudflare DDNS脚本？

传统的动态域名解析服务常受限于服务商支持，而SynologyCloudflareDDNS脚本通过以下特性解决了用户痛点：

• 双栈IP支持：自动检测IPv4和IPv6地址，分别对应A记录和AAAA记录的更新
• 安全认证机制：采用Cloudflare API Token替代传统密码，实现权限最小化控制
• 状态实时反馈：向群晖系统返回"good"（更新成功）、"nochg"（无需更新）、"badauth"（认证失败）等标准状态码
• 零手动干预：配置完成后全程自动运行，无需定期手动修改DNS记录

工作流程解析：四步实现IP自动同步

1. 环境初始化与参数获取

脚本启动时首先定义关键正则表达式（第4-5行），用于后续IP地址验证：

ipv4Regex="((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])" ipv6Regex="(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|...)" # 完整IPv6正则

随后从群晖系统接收四个关键参数（第11-14行）：

• username：Cloudflare区域ID（Zone ID）
• password：Cloudflare API Token
• hostname：需要更新的域名（如nas.example.com）
• ipAddr：群晖系统检测到的公网IP

2. IP地址智能检测机制

脚本采用双轨制IP获取策略（第17-33行）：

• IPv4处理：直接使用群晖提供的ipAddr参数
• IPv6处理：若未提供则通过ip -6 addr show eth0命令从网络接口获取（第18行），并截取有效前缀（第19行）

根据IP类型自动设置记录类型：

if [[ $ipAddr =~ $ipv4Regex ]]; then recordType="A"; # IPv4对应A记录 else recordType="AAAA"; # IPv6对应AAAA记录 fi

3. Cloudflare API交互流程

3.1 DNS记录查询

脚本构建Cloudflare DNS记录查询API（第36-38行）：

listDnsApi="https://api.cloudflare.com/client/v4/zones/${username}/dns_records?type=${recordType}&name=${hostname}"

通过curl发送GET请求获取现有记录（第40行），并使用jq工具解析响应：

• recordId：现有DNS记录ID（第53行）
• recordIp：当前解析的IP地址（第54行）
• recordProx：Cloudflare代理状态（第55行）

3.2 记录更新决策

脚本通过对比本地IP与Cloudflare记录判断是否需要更新（第70行）：

if [[ $recordIp = "$ipAddr" ]] && [[ $recordIpv6 = "$ip6Addr" ]]; then echo "nochg"; # IP未变化，返回无需更新状态 exit 0; fi

3.3 记录创建/更新操作

• 新建记录：当recordId为"null"时（第75行），发送POST请求创建新记录（第77-78行）
• 更新记录：当记录已存在时，发送PUT请求更新IP地址（第81行）

IPv6记录采用相同逻辑独立处理（第83-91行），确保双栈地址同步更新。

4. 结果反馈与错误处理

脚本通过解析API响应判断操作结果（第94-100行）：

resSuccess=$(echo "$res" | jq -r ".success") if [[ $resSuccess = "true" ]] || [[ $res6Success = "true" ]]; then echo "good"; # 更新成功 else echo "badauth"; # 认证失败或API错误 fi

配置要点：从脚本部署到DDNS设置

脚本部署步骤

1. 通过SSH登录群晖系统，下载脚本至/sbin目录：

wget https://raw.githubusercontent.com/joshuaavalon/SynologyCloudflareDDNS/master/cloudflareddns.sh -O /sbin/cloudflareddns.sh

2. 添加执行权限：

chmod +x /sbin/cloudflareddns.sh

3. 注册为群晖DDNS提供商（第33-38行）：

cat >> /etc.defaults/ddns_provider.conf << 'EOF' [Cloudflare] modulepath=/sbin/cloudflareddns.sh queryurl=https://www.cloudflare.com website=https://www.cloudflare.com EOF

Cloudflare参数获取

1. Zone ID：在域名概览页面获取
2. API Token：在个人资料→API令牌中创建，需勾选"Zone > DNS > Edit"权限

群晖DDNS设置

在群晖控制面板→外部访问→DDNS中添加条目：

• 服务提供商：选择"Cloudflare"
• 主机名：填写完整域名（如nas.example.com）
• 用户名/电子邮件：输入Cloudflare Zone ID
• 密码/密钥：输入Cloudflare API Token

常见问题与解决方案

认证失败（badauth）

可能原因：

• API Token权限不足：确保包含"DNS编辑"权限
• Zone ID错误：需使用域名对应的Zone ID而非账户ID
• API Token过期：检查令牌有效期或创建新令牌

IP未更新（nochg）

可能原因：

• 本地IP未变化：脚本默认每5分钟检查一次
• 网络接口选择错误：若eth0非公网接口，需修改第18行的网络接口名称

IPv6记录不更新

需确保：

• 群晖已获取IPv6地址（可通过ip -6 addr命令检查）
• Cloudflare域名已启用IPv6支持
• 脚本第6行ipv6="true"未被注释

版本演进与功能增强

根据CHANGELOG.md记录，2.0.0版本带来重大改进：

• 新增IPv4/IPv6自动检测
• 采用API Token认证替代传统密码
• 优化状态码返回逻辑
• 移除日志文件输出，改为直接向系统反馈状态

这些改进使脚本更安全、更易用，同时降低了维护成本。

总结：动态DNS的自动化实现

SynologyCloudflareDDNS脚本通过四个核心步骤实现了IP与域名的自动同步：环境初始化→IP智能检测→Cloudflare API交互→结果反馈。其设计遵循Unix哲学，以简洁的bash脚本完成复杂的网络交互，既保证了轻量性，又具备足够的灵活性。

对于需要在动态IP环境下远程访问群晖NAS的用户，该脚本提供了可靠、安全的解决方案，使域名解析维护从手动操作转变为全自动流程，显著降低了技术门槛和维护成本。

【免费下载链接】SynologyCloudflareDDNS📜 Cloudflare DDNS script for Synology项目地址: https://gitcode.com/gh_mirrors/sy/SynologyCloudflareDDNS