ddns-go 动态解析同步到 DNS

ddns-go 是基于 Go 语言开发的轻量动态域名解析工具，核心是自动获取公网 IPv4/IPv6 并同步到 DNS 服务商，支持多平台、多厂商、可视化配置与系统服务化运行。

一、核心定位与架构

1. 核心定位

自动获取公网 IP（IPv4/IPv6）→ 检测 IP 变化 → 调用 DNS 服务商 API 更新域名解析记录 → 实现域名永久指向动态公网 IP。

2. 技术架构（极简）

• 语言：Go（单二进制、无依赖、跨平台）
• 运行模式：前台/后台/系统服务（systemd/Windows Service）
• 核心流程：IP 采集 → 缓存对比 → DNS API 调用 → 结果通知
• 配置方式：Web UI（9876端口）+ 配置文件（~/.ddns_go_config.yaml）
• 资源占用：内存<20MB、CPU<1%，适合嵌入式/服务器/家庭设备。

二、核心技术特性

1. IP 采集能力（多源、双栈）

• 支持类型：IPv4（A记录）、IPv6（AAAA记录），可同时启用双栈
• 采集方式：
  • 网卡/接口获取（优先，本地直读，无外网依赖）
  • 公网 API 获取（如 icanhazip.com、ipify.org，多地址容错）
  • 自定义命令获取（适配特殊网络环境）
• 策略：默认5分钟轮询，支持自定义间隔（-f 参数），支持缓存对比减少 API 调用。

2. DNS 服务商支持（全覆盖）

支持30+主流厂商，原生集成无需额外配置：

• 国内：阿里云、腾讯云 DNSPod、华为云、百度云、DNSLA、时代互联
• 国际：Cloudflare、Porkbun、GoDaddy、Namecheap、NameSilo、Dynadot
• 自定义：Callback 模式（通过 HTTP 回调适配任意 DNS API）

3. 部署与运行能力

• 跨平台：Linux（x86/ARM）、Windows、macOS、FreeBSD，支持树莓派/路由器
• 安装方式：
  • 二进制（推荐，单文件）
  • Deb/RPM 包（系统集成）
  • Docker（--net=host 优先，适配 IPv6）
  • 手动运行（前台/后台）
• 服务化：一键注册为 systemd/Windows Service，开机自启、日志管理、进程守护。

4. 安全与管理

• Web UI 安全：默认禁止公网访问（仅内网），支持账号密码登录、IP 白名单
• 配置安全：敏感信息（API Key）加密存储，支持环境变量注入
• 日志：Web 端查看最近50条日志，支持文件日志、Syslog 导出
• 热重载：修改配置无需重启服务，自动生效

5. 高级功能

• 多域名/多服务商：同时管理多个域名、绑定多个 DNS 账号
• TTL 自定义：支持设置解析记录 TTL（1-86400秒）
• Webhook 通知：IP 变化/更新成功/失败时，推送至钉钉、飞书、Server 酱、Telegram 等
• 地域解析：部分服务商支持自定义参数，实现智能解析
• 失败重试：网络异常时自动重试，恢复后自动同步

三、命令行参数（核心）

1. 服务管理（Linux/macOS）

1
2
3
4
5
6
7
8

# 安装为系统服务（开机自启）
sudo ddns-go -s install
# 卸载服务
sudo ddns-go -s uninstall
# 启动/停止/重启服务
sudo systemctl start/stop/restart ddns-go
# 查看服务状态
sudo systemctl status ddns-go

2. 运行参数（启动时指定）

3. 手动运行

1
2
3
4

# 前台运行（终端关闭即停止）
./ddns-go
# 后台运行（关闭终端仍运行，日志输出到文件）
nohup ./ddns-go > /var/log/ddns-go.log 2>&1 &

四、配置文件说明（~/.ddns_go_config.yaml）

1. 基础配置

1
2
3
4
5
6
7

listen: :9876          # Web 监听地址
interval: 300          # 同步间隔（秒）
user: admin            # Web 用户名
password: ********     # Web 密码（加密）
allowIPs:              # 允许访问 Web 的 IP 白名单
  - 127.0.0.1
  - 192.168.1.0/24

2. DNS 服务商配置（以 Cloudflare 为例）

1
2
3
4
5
6
7
8
9

dns:
  - provider: cloudflare
    accessKey: your_api_token  # Cloudflare API Token
    secretKey: ""              # 留空（Token 模式）
    domains:
      - domain: home.example.com  # 子域名
        recordType: AAAA          # IPv6 解析
        ttl: 60                   # TTL 60秒
        ipv6: true                # 启用 IPv6

3. IP 采集配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

ipv4:
  enable: true
  source: netif  # 网卡获取（可选：web/command）
  netif: eth0    # 指定网卡（留空自动检测）
  webUrls:       # 公网 API 地址（多地址容错）
    - https://icanhazip.com
    - https://api.ipify.org
ipv6:
  enable: true
  source: netif
  netif: eth0
  webUrls:
    - https://icanhazip.com

4. Webhook 配置（钉钉示例）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

webhook:
  enable: true
  url: https://oapi.dingtalk.com/robot/send?access_token=xxx
  method: POST
  body: |
    {
      "msgtype": "markdown",
      "markdown": {
        "title": "IP 变化通知",
        "text": "### 公网 IP 已更新\n- IPv6: #{ipv6Addr}\n- 结果: #{ipv6Result}"
      }
    }

五、IPv6 部署

1. 前提条件

• 设备获取公网 IPv6（curl -6 icanhazip.com 可返回 IPv6）
• 路由器放行 IPv6 端口（需访问的服务端口，如 22/80/443）
• DNS 服务商支持 AAAA 记录（主流均支持）

2. 配置步骤

1. 安装 ddns-go（二进制/Docker），启动服务
2. 访问 http://内网IP:9876，登录 Web UI
3. 启用 IPv6，选择网卡/公网 API 作为 IP 源
4. 添加 DNS 服务商（如 Cloudflare），填写 API Token
5. 配置子域名（如 home.example.com），记录类型选 AAAA
6. 保存配置，查看日志确认「更新成功」

六、故障排查（常见问题）

1. IP 采集失败

• 检查 IPv6 连通性：ping6 ipv6.google.com
• 公网 API 不可用：更换 API 地址（如 ipify.org）
• 网卡无 IPv6：检查路由器 DHCPv6/RA 设置

2. DNS 更新失败

• 检查 API Key/Token 权限（需域名解析权限）
• 检查域名是否在当前账号下
• 检查 TTL 设置是否合规（部分服务商最低 60 秒）

3. Web UI 无法访问

• 检查服务状态：systemctl status ddns-go
• 检查端口占用：netstat -tuln | grep 9876
• 检查防火墙：放行 9876 端口（内网）

七、性能与稳定性

• 内存：单实例<20MB，多域名/多服务商<50MB
• CPU：轮询时<1%，无持续高负载
• 稳定性：Go 语言编译，无内存泄漏，支持7×24小时运行
• 容错：多 IP 源、多 DNS API、失败重试，保障解析不中断

八、官方资源

• GitHub： https://github.com/jeessy2/ddns-go
• Releases： https://github.com/jeessy2/ddns-go/releases
• Docker Hub： https://hub.docker.com/r/jeessy/ddns-go