ForwardX 教程

Appearance

DDNS 与故障转移 ​

DDNS 用来把域名自动解析到可用入口。ForwardX 可以在主机 IP 变化、入口组成员变化或转发组故障切换时，自动更新 DNS 记录。

工作原理 ​

ForwardX 的 DDNS 功能分两层：

自动更新层：ForwardX 监听主机 Agent 上报的公网 IP 和入口组成员状态。当检测到变化时，调用你配置的 DNS 服务商 API，将指定域名的记录值改写为当前可用地址。

故障转移层：转发组持续对成员入口执行健康检查。当主入口不可用时，ForwardX 将域名切换到备用入口；主入口恢复后，可根据配置决定是否切回。

故障转移触发条件 ​

以下情况会触发 DDNS 更新或故障切换：

触发场景动作
Agent 上报的主机公网 IP 发生变化更新主机 DDNS 域名记录
入口组成员新增或移除将域名记录同步到当前全部成员 IP
转发组健康检查判定入口不可用将域名切换到健康备用入口
转发组主入口恢复（视配置）将域名切回主入口

TIP

故障切换依赖健康检查的判定周期，建议不要将检查间隔或切换阈值设置过短，避免网络抖动引发频繁切换。

支持的 DNS 服务商 ​

服务商官方教程和入口
Cloudflare创建 API Token / DNS Records API / API Token 控制台
华为云 DNS云解析 DNS 文档 / 访问密钥 AK/SK / DNS 控制台
阿里云 DNS创建 AccessKey / 云解析 OpenAPI / 云解析控制台
腾讯云 DNSPodDNSPod API 简介 / API 密钥管理 / DNSPod 控制台
自定义 Webhook适用于自有接口或暂未内置的服务商

配置步骤 ​

第一步：配置 DDNS 服务商 ​

配置路径：

text
系统设置 -> 系统配置 -> DDNS 服务商

基本流程：

  1. 在 DNS 服务商处准备好域名和 API 密钥。
  2. 在 ForwardX 的 DDNS 服务商中选择对应服务商。
  3. 填写服务商要求的密钥、主域名、Zone ID 或线路等信息。
  4. 设置 TTL，建议先使用默认值 600。
  5. 保存 DDNS 配置。

权限建议

DDNS 密钥只建议授予目标域名所需权限，不要使用拥有账号全部权限的长期密钥。

第二步：在功能模块中填写域名 ​

根据你的使用场景，到对应模块填写要自动维护的域名：

  • 主机 DDNS：主机管理 -> 新增/编辑主机 -> DDNS 服务
  • 入口组：链路管理 -> 入口组 -> 编辑入口组
  • 转发组：链路管理 -> 转发组 -> 编辑转发组

Cloudflare ​

适合域名托管在 Cloudflare 的用户。

官方入口：

需要准备：

  • Cloudflare API Token。
  • 可选：Zone ID。

Token 权限建议：

权限用途
Zone:Read未填写 Zone ID 时，用于自动查找域名所在 Zone
DNS:Edit创建或更新 DNS 记录

面板填写：

字段说明
Zone ID可留空，留空时系统会按域名自动识别
API Token填写 Cloudflare API Token

如果你手动填写了 Zone ID，Token 仍然需要能编辑该 Zone 的 DNS 记录。

华为云 DNS ​

适合域名解析托管在华为云云解析 DNS 的用户。

官方入口：

需要准备：

  • Access Key ID。
  • Secret Access Key。
  • 公网域名 Zone ID。
  • 区域，例如 cn-north-4。

面板填写：

字段说明
Access Key ID华为云 AK
Secret Access Key华为云 SK，留空保存时会保留旧密钥
公网 Zone ID云解析 DNS 中对应公网域名的 Zone ID
区域默认可使用 cn-north-4
默认线路默认 default_view
Endpoint一般留空即可，特殊环境再填写完整 URL

如果更新失败，优先确认 AK/SK 是否有云解析 DNS 的记录查询和编辑权限。

阿里云 DNS ​

适合域名解析托管在阿里云云解析 DNS 的用户。

官方入口：

需要准备：

  • AccessKey ID。
  • AccessKey Secret。
  • 主域名，例如 example.com。

面板填写：

字段说明
AccessKey ID阿里云 AccessKey ID
AccessKey Secret阿里云 AccessKey Secret，留空保存时会保留旧密钥
主域名根域名，例如 example.com
Endpoint默认 https://alidns.aliyuncs.com
默认线路默认 default

例如你要维护 a.example.com，主域名填 example.com，ForwardX 会自动拆分主机记录 a。

腾讯云 DNSPod ​

适合域名解析托管在腾讯云 DNSPod 的用户。

官方入口：

需要准备：

  • SecretId。
  • SecretKey。
  • 主域名，例如 example.com。

面板填写：

字段说明
SecretId腾讯云 SecretId
SecretKey腾讯云 SecretKey，留空保存时会保留旧密钥
主域名根域名，例如 example.com
默认线路名称通常填 默认
默认线路 ID可留空，特殊线路才需要填写

如果记录无法更新，检查域名是否在 DNSPod 下，并确认密钥有 DNSPod 记录管理权限。

自定义 Webhook ​

Webhook 适合你有自己的 DNS 更新接口，或使用暂未内置支持的服务商。

面板填写：

字段说明
请求方法支持 POST、PUT、GET
Webhook URL接收 DDNS 更新的接口地址
请求头支持 JSON 或每行一个 Header

Webhook URL 可以使用变量：

变量含义
要更新的完整域名
记录类型，例如 A、AAAA、CNAME
要写入的记录值
TTL

示例：

text
https://ddns.example.com/update?domain={{domain}}&type={{type}}&value={{value}}&ttl={{ttl}}

请求头 JSON 示例：

json
{"Authorization":"Bearer your-token"}

主机 DDNS ​

配置路径：

text
主机管理 -> 新增/编辑主机 -> DDNS 服务

开启后，Agent 上报的公网 IP 变化时，ForwardX 会自动更新该主机的 DDNS 域名。

记录类型建议：

场景建议
只需要 IPv4 入口选择 IPv4，会生成 A 记录
只需要 IPv6 入口选择 IPv6，会生成 AAAA 记录

如果服务商配置未启用，主机 DDNS 开关会不可用，需要先回到系统设置配置 DDNS 服务商。

入口组与转发组 ​

入口组适合多个入口机器共用一个域名，ForwardX 将全部成员的地址同步到同一条域名记录。

配置路径：

text
链路管理 -> 入口组

记录类型要求：

类型要求
A成员机器需要有 IPv4
AAAA成员机器需要有 IPv6
CNAME成员机器需要配置 DDNS 域名

如果选择 CNAME，ForwardX 会把入口域名指向成员机器配置好的 DDNS 域名。这样成员 IP 变化时，通常只需要更新成员自己的 DDNS，入口域名记录无需重新写入。

故障切换建议 ​

  • 不要把故障切换时间设置得太短，网络偶发抖动可能导致频繁切换。
  • 重要业务建议开启链路测试和延迟观察，基于实测延迟判断入口健康状态。
  • 恢复后是否切回，取决于你是否希望优先使用主入口，可在转发组配置中选择。
  • 建议先用测试域名验证切换流程，确认正常后再切换生产域名。
  • TTL 较大时，DNS 切换后客户端缓存未过期，实际生效会有延迟，建议在切换验证阶段临时调低 TTL。

域名来源优先级 ​

ForwardX 展示入口地址时，优先级如下：

  1. 用户在主机或组内手动填写的域名或 IP。
  2. 自动检测到的公网地址或 DDNS 地址。

建议重要业务手动设置清晰的域名，避免直接依赖可能变化的 IP。

排查 DDNS ​

如果 DDNS 没有更新：

  1. 确认系统设置中 DDNS 已启用，且服务商不是"不使用"。
  2. 确认主域名、Zone ID、线路、密钥填写正确。
  3. 确认 API 密钥有 DNS 记录查询和编辑权限。
  4. 确认主机或入口组填写的域名属于对应主域名。
  5. 查看系统日志和入口组事件记录。

常见错误：

现象可能原因
提示域名不在主域名下阿里云、腾讯云主域名填写错误
Cloudflare 找不到 ZoneToken 没有 Zone:Read 权限，或 Zone ID 未填写且自动识别失败
权限不足API 密钥权限太小或绑定了错误域名
AAAA 不更新成员机器没有可用 IPv6
CNAME 不更新成员机器没有配置 DDNS 域名
切换后域名未生效DNS 缓存未过期，等待 TTL 时间后重试