# 动态域名与 DDNS

DDNS 绑定把服务器或转发端点上报的公网地址同步到外部 DNS，适合公网地址会变化、希望客户端使用固定域名连接的场景。

## 分清动态 IP、动态入口与 DDNS

| 功能 | 作用 | 是否写外部 DNS |
| --- | --- | --- |
| 动态 IP | 探测并上报节点的公网出口地址，供动态地址等功能使用 | 本开关不创建 DNS 绑定 |
| 动态入口地址 | 让面板内部连接地址使用已上报的动态候选，需先开启动态 IP | 否 |
| DDNS 绑定 | 把指定资源的地址同步为外部 A / AAAA 记录 | 启用且关闭观察态后才允许写入 |
| 服务器组 DNS 自动切换 | 按组成员健康调整组入口解析 | 由组配置单独管理 |

动态 IP 和 DDNS 都不会替你完成 NAT 端口映射。探测到公网出口地址，也不代表公网能连接该机器的入站端口；仍需公网可达的地址、端口映射和防火墙规则。

## 配置 DNS API

管理员进入 **系统设置 → 系统设置 → DNS 与证书 → DNS配置管理**，点击 **新增DNS配置**。

![DNS API 示例：Cloudflare 认证、API 地址、最低 TTL 与启用开关](https://img.coderluny.com:444/uploads/zfc-tutorial-20261018-dns-api-cloudflare-46bb4a9e76d4.png)

1. 填写配置名称和显示名称，选择服务商。
2. 按对应表单填写凭据；Cloudflare 可使用 API Token。
3. 核对授权覆盖的域名与解析读写能力，使用 **测试连接**检查域名列表，再保存并启用配置。
4. 核对 **最低 TTL**。绑定和服务器组输入较低 TTL 时会被抬升到配置下限，以保存后返回值为准。

| 服务商 | 主要认证字段 | 需要注意 |
| --- | --- | --- |
| Cloudflare | API Token，或邮箱 + Global API Key | 表单支持 CDN 代理能力，普通原始 TCP / UDP 服务不要直接套用网站代理设置 |
| 阿里云 DNS | AccessKey ID / Secret | 使用具备相应解析读写权限的账号 |
| 腾讯云 DNSPod | Secret ID / Key、站点 | 按账号选择中国站或国际站；国际站界面标注尚未经真实账号验证 |
| 华为云 DNS | AK / SK、Region，可选 Project ID | 核对站点和区域；同一账号只配置一份，避免其他工具同时修改受管记录集 |
| Webhook | 接收地址、Secret、域名列表等 | 需要接收端实现面板的签名、版本和完整记录集协议，不是任意通知 URL |

选择 Webhook 时，先按 [DNS Webhook 接入指南](/docs/dns-webhook/)核对适用版本、从面板下载对应接收端，再完成部署和写入验收。Secret 至少 32 字节，接收端须在实际应用变更后返回成功，并正确处理代次、序号和重复请求。

Webhook 的 **测试连接**只发送已签名的 ping；返回的域名列表来自表单配置，不代表已验证 DNS 写权限。还需在专用记录上验证实际 put 和权威解析，步骤见[验收接入](/docs/dns-webhook/#验收接入)。

编辑现有 DNS 配置时，密钥留空表示保留原凭据。更换服务商需要重新填写其凭据，仍被绑定、服务器组、证书或未完成写入引用的配置可能拒绝更换。

## 确认 DDNS 已就绪

在同一设置页进入 **DDNS 上线状态**，先检查标记状态、冲突项和悬挂 Claim。

![DDNS 上线状态：Ready、冲突清单和悬挂 Claim](https://img.coderluny.com:444/uploads/zfc-tutorial-20261018-ddns-ready-6bca882dd3d4.png)

- **Ready / 已就绪**表示可以进行绑定配置，不代表每条绑定已经同步成功。
- **未就绪、禁写**时，先按冲突清单处理资源或记录归属，再使用 **重试 / 完成回填**。
- 悬挂 Claim 是需要核对的归属记录，不应通过删库方式消除；页面也明确保留部分已关闭组的残留归属。

“重试 / 完成回填”是状态推进操作，不是每次刷新页面都必须点击的按钮。

## 准备节点的动态地址上报

进入 **服务器管理 → 添加 / 编辑服务器 → 高级选项**，核对 **动态IP**；转发端点也有对应的动态地址设置。

![动态 IP 与动态入口地址：两者分别控制上报与内部连接地址](https://img.coderluny.com:444/uploads/zfc-tutorial-20261018-dynamic-address-options-4da84a7afa66.png)

1. 开启需要更新地址的节点的动态 IP 功能，保存并确认配置到达在线节点。
2. 等待公网地址探测与上报，查看已探测到的候选。
3. 只有希望面板内部节点连接也跟随动态地址时，才额外开启 **动态入口地址**；它不是创建 DDNS 绑定的必填开关。
4. 核对 IPv4 / IPv6 的实际入站可达性，再决定发布哪个地址族。

DDNS 使用上报中符合条件且新鲜的公网候选，不会仅凭手填的静态 IP 自动生成有效动态证据。没有候选或候选过期时，先处理探测、网络和节点上报，不要把这些状态当作自动切换到了另一台机器。

## 新建 DDNS 绑定

进入 **DNS 与证书 → DDNS 绑定 → 新建绑定**。

![DDNS 绑定：资源、DNS 配置、Zone、记录名、地址族、TTL 和观察态](https://img.coderluny.com:444/uploads/zfc-tutorial-20261018-ddns-binding-f8f0b129805c.png)

| 字段 | 填写方法 |
| --- | --- |
| 资源类型 | 选择服务器或转发端点 |
| 资源 ID | 对应管理列表中该资源的 ID，不是端口规则 ID、组 ID 或认证 Token |
| DNS API 配置 | 选择刚才启用的服务商配置 |
| Zone | 服务商的区域标识，优先从加载的列表选择，不要把它与域名字符串混为一谈 |
| Zone 名称 | 该区域的实际域名，例如 `example.com`；从列表选择后核对自动填入值 |
| 记录名 | `home`，或完整的 `home.example.com`；必须位于该区域内 |
| 地址族 | 仅 IPv4、仅 IPv6 或双栈，按实际可达性选择 |
| TTL | 受 DNS 配置的最低 TTL 与服务商能力约束 |
| CDN 代理 | 仅在服务商支持时显示；按实际业务协议决定 |
| 启用 / 观察态 | 两个独立开关，观察态下只计算差异并记录，不写外部 DNS |

确认资源 ID 对应自己的服务器或转发端点，再选择 DNS 配置和所属区域。

建议先保存为 **启用 + 观察态**，检查规范名、候选地址和目标归属。确认无误后编辑绑定，关闭观察态并保存，允许外部写入。

新建绑定不会自动把“服务器的入口地址”或客户端配置改成这个域名。需要客户端使用动态域名时，另行更新连接地址；节点监听端口仍保持实际配置。

## 核对 A、AAAA 与实际业务

保存后在绑定列表分别查看 A / AAAA 的同步状态、最近成功、最近尝试、连续失败、过期时间和最近错误。

| 状态 | 含义与处理 |
| --- | --- |
| 正常 | 继续核对服务商记录和真实连接，不只依赖一个状态标记 |
| 未同步 / 未建立 | 检查观察态、启用状态、节点候选和资源归属 |
| 候选过期 | 节点缺少新鲜地址证据；检查动态 IP 探测与上报 |
| 配置错误 | 核对凭据、Zone、记录名、权限与服务商参数 |
| 瞬时错误 / 限流 | 查看最近错误与重试情况，避免连续手动触发写入 |

可以在自己的终端查询记录：

```bash
dig +short home.example.com A
dig +short home.example.com AAAA
```

查询结果还受递归缓存影响。先核对服务商记录，再从实际客户端连接 `域名:端口`，验证 TCP 或 UDP 的真实请求。只使用 IPv4 的服务，不要误把一条无法入站的 AAAA 记录发布给客户端。

## 记录冲突与未知写入

同一个 DNS 目标可能已由另一条绑定、服务器组或智能 DNS 管理。遇到归属冲突时，核对是哪套配置负责该名字与类型，再安排交接，不要重复创建同名绑定强行覆盖。

出现“结果未知”或交接阻塞时，展开 **DNS 写入与交接状态**，核对未决操作、最后可能写入时间、服务商读回和操作历史。读取失败或读回为空，都不能单独证明原写入没有发生。

需要人工核实时，按界面暂停目标的新写入，等待本地在途操作结束，并自最后可能写入起等待至少 10 分钟，核对服务商终态及当前业务期望后再使用人工核实流程。恢复写入不会自动清除未决操作。

停用、删除或更换绑定目标后，还应核对外部记录和交接状态；删除面板绑定不能直接当作公共 DNS 已清空的证明。

继续阅读：[服务器组](/docs/server-groups/) · [智能 DNS](/docs/smart-dns/) · [连接诊断与测速](/docs/diagnostics-speed-test/)。