动态 DNS

了解动态 DNS 以及如何使用动态 DNS API 更新 DNS 记录。

本说明适用于我们新的 Cloud DNS。您可以在此处找到适用于传统 DNS 的客户端：DynDNS 客户端

1. 什么是动态 DNS？

2. 设置 DynDNS

3. 常见问题解答 (FAQ)

1. 什么是动态 DNS？

动态 DNS（DynDNS、DDNS）是一种在 IP 地址发生变化时自动更新 DNS 记录的服务。例如，当您希望使位于家中的服务器可供外部访问，即使 IP 地址由于互联网服务提供商的原因而定期变动，通常也会使用 DynDNS。借助 DynDNS API，您可以自动更新 netcup 账户中域名或子域名的 A 记录 (IPv4) 和/或 AAAA 记录 (IPv6)。使用 DynDNS 时，您的路由器或脚本会定期检查 URL，并自动将当前 IP 地址写入您的 CloudDNS 区域中。

前提条件

要使用 DynDNS API，您需要满足某些条件：

该域名必须通过 CloudDNS 进行管理。
您拥有有效的身份验证令牌。
至少传递一个 IP 地址（IPv4 或 IPv6），例如：https://customercontrolpanel.de/wsDynDns.php?action=update&token=YOUR_TOKEN&fqdn=home.example.com&ipv4Address=203.0.113.10
对于 IPv6，您还必须指定 ipv6Address，或将其作为替代：https://customercontrolpanel.de/wsDynDns.php?action=update&token=YOUR_TOKEN&fqdn=home.example.com&ipv4Address=203.0.113.10&ipv6Address=2001:db8::10

可以通过 HTTP GET(URL) 或 POST 请求传递这些参数。

参数

下面列出了所使用参数的概览：

参数

必要性

类型

说明

Action

是

String

必须设置为 Update，其他值将被拒绝并返回 HTTP 错误码 404

Token

是

String

将请求与相应客户账户关联的身份验证令牌，无效或未知的令牌将被拒绝并返回 HTTP 错误码 401

FQDN (完全合格域名)

是

String

要更新的条目的完全合格域名，例如 “example.com” 或 “home.example.com”；必须是有效的域名，并且属于该令牌所属账户中存在的域名

ipv4Address

可选

String

A 记录的新 IPv4 地址，必须是有效的 IPv4 地址

ipv6Address

可选

String

AAAA 记录的新 IPv6 地址，必须是有效的 IPv6 地址

请注意，ipv4Address 或 ipv6Address 这两个参数中至少必须设置一个。如果两者均未提供，请求将被拒绝并返回 HTTP 错误码 400。

单个参数的详细说明

FQDN

DynDNS 会自动确定 FQDN 的哪部分是与账户关联的域名，哪部分是主机名。对于多段顶级域名 (TLD)（例如 “.co.uk”）同样适用。
- “home.example.com” → 域名：“example.com”，主机名：“home”
- “example.com” → 域名：“example.com”，主机名：”@“（区域根目录）
国际化域名会在内部转换为 Punycode。
如果在账户中未找到匹配的域名，请求将被拒绝并返回 HTTP 错误码 404。
如果域名未通过 CloudDNS 进行管理，请求将被拒绝并返回 HTTP 错误码 400。

ipv4Address / ipv6Address

新条目将使用默认生存时间 (TTL) 和默认区域创建。
A 记录和 AAAA 记录均可在单次调用中同时更新。

2. 设置 DynDNS

您可以在此处找到在 FRITZ!Box 上设置 DynDNS 的说明：

https://fritz.com/en-at/apps/knowledge-base/FRITZ-Box-7590/30_Setting-up-dynamic-DNS-in-the-FRITZ-Box（外部链接）

在设置过程中，在提供的字段中输入以下信息：

Update URL: https://customercontrolpanel.de/wsDynDns.php?action=update&token=&fqdn=&ipv4Address=ipaddr>&ipv6Address=
Domain Name: <sub.domain.tld>
Username: 客户编号
Password

更新逻辑

系统将检查所识别主机现有的 A 或 AAAA 记录：

记录已存在且 IP 地址完全相同。
1. 无需任何更改。
记录已存在但 IP 地址不同。
1. 使用提供的 IP 地址更新该记录。
记录尚不存在。
1. 创建一条新记录。如果这导致了实际变更，这些变更将保存到 CloudDNS 区域中。如果所有提供的值均已设置，则不进行任何更改。

响应格式

响应将以 JSON 格式返回 (Content Type: text/json; charset=utf-8)：

{
    "status": "success",
    "message": "Record(s) have been saved."
}

字段说明

字段

说明

Status

成功时为 success，否则为 error

Message

人类可读的状态消息

成功时的可能消息值

“Record(s) have been saved.”
“No record update needed.”

HTTP 状态与错误代码

HTTP 代码

消息

状态/错误

200

“Record(s) have been saved.” / “No record update needed.”

处理成功

400

“At least one of the two fields need to be specified: ipv4Address , ipv6Address.”

既未传递 IPv4 地址也未传递 IPv6 地址

400

“At least one of the two fields need to be specified: ipv4Address , ipv6Address.”

无效的参数格式

400

“This domain is not managed through CloudDNS, for this reason this service will not work.”

域名未通过 CloudDNS 管理

401

“Unable to authenticate with provided token.”

令牌无效或未知

404

“No matching domain for the given fqdn was found in your account.”

账户中未找到匹配的域名

404

“Requested action is not known or not implemented.”

action 缺失或不等于 Update

500

“An error occurred while trying to … Please reach out to our support.”

访问 CloudDNS 区域/记录时发生内部错误

400

”< feld> is a required field.”

必需参数 (token, fqdn) 缺失

3. 常见问题解答 (FAQ)

更新后的 DNS 记录的传播取决于配置的 TTL 以及解析器/DNS 服务器更新 DNS 的方式，最长可能需要 48 小时。但是，DNS 记录通常会在极短时间内传播到各大主流解析器/DNS 服务器。

不可以，这是不支持的。不过，欢迎您使用我们的 DNS API 来自动管理其他 DNS 记录。

您可能还对以下内容感兴趣：

API

CloudDNS

配置 DNS (CloudDNS)

设置您自己的域名服务器 (CloudDNS)

DNSSEC (CloudDNS)

最后更新：2026年8月28日

api scp