DDNS API 使用文档

概述

DDNS (Dynamic DNS) API 允许用户通过 API 动态更新 DNS 记录，特别适用于家庭宽带、动态 IP 等场景。

API 端点

请求参数

支持的记录类型

响应格式

成功响应

{
  "success": true,
  "message": "DDNS 更新已提交，DNS 同步异步处理中",
  "data": {
    "domain": "blog.example.com",
    "ip": "192.168.1.100",
    "record_type": "A",
    "old_ip": "192.168.1.99",
    "updated": true
  }
}

IP 未变化

{
  "success": true,
  "message": "IP 地址未变化，无需更新",
  "data": {
    "domain": "blog.example.com",
    "ip": "192.168.1.100",
    "updated": false,
    "compensated": false
  }
}

compensated 字段说明：当 IP 未变化但系统检测到 DNS 服务器与数据库不一致时，会自动触发补偿同步，此时值为 true。

错误响应

{
  "success": false,
  "status_code": 400,
  "error": "错误描述信息"
}

常见错误代码

使用示例

1. cURL 命令

# 自动检测当前 IP 并更新
curl -X GET "https://pwdns.org/api/ddns/update?domain=blog.example.com&token=your_api_token"

# 指定 IP 地址更新
curl -X GET "https://pwdns.org/api/ddns/update?domain=blog.example.com&ip=192.168.1.100&token=your_api_token"

# IPv6 地址更新
curl -X GET "https://pwdns.org/api/ddns/update?domain=blog.example.com&ip=2001:db8::1&token=your_api_token"

# 多条同类型记录时，使用 old_value 精确指定要更新的记录
curl -X GET "https://pwdns.org/api/ddns/update?domain=blog.example.com&ip=192.168.1.200&old_value=192.168.1.100&token=your_api_token"

2. Linux/Mac 脚本

#!/bin/bash

# 配置
DOMAIN="blog.example.com"
API_TOKEN="your_api_token"
DDNS_URL="https://pwdns.org/api/ddns/update"

# 获取当前公网 IP（使用多个服务以提高可靠性）
CURRENT_IP=$(curl -s https://api.ipify.org || curl -s https://ifconfig.me || curl -s https://icanhazip.com)

if [ -z "$CURRENT_IP" ]; then
    echo "错误：无法获取当前公网 IP"
    exit 1
fi

echo "当前 IP: $CURRENT_IP"

# 更新 DDNS
RESPONSE=$(curl -s -G "$DDNS_URL" \
  --data-urlencode "domain=$DOMAIN" \
  --data-urlencode "ip=$CURRENT_IP" \
  --data-urlencode "token=$API_TOKEN")

echo "响应：$RESPONSE"

# 检查是否成功
if echo "$RESPONSE" | grep -q '"success":true'; then
    echo "DDNS 更新成功！"
else
    echo "DDNS 更新失败：$RESPONSE"
    exit 1
fi

3. Windows PowerShell

# 配置
$Domain = "blog.example.com"
$ApiToken = "your_api_token"
$DdnsUrl = "https://pwdns.org/api/ddns/update"

# 获取当前公网 IP
try {
    $CurrentIp = Invoke-RestMethod -Uri "https://api.ipify.org?format=json" | Select-Object -ExpandProperty ip
} catch {
    Write-Error "无法获取当前公网 IP"
    exit 1
}

Write-Host "当前 IP: $CurrentIp"

# 更新 DDNS
try {
    $Response = Invoke-RestMethod -Uri "$DdnsUrl?domain=$Domain&ip=$CurrentIp&token=$ApiToken" -Method Get
    
    if ($Response.success) {
        Write-Host "DDNS 更新成功！"
        Write-Host "新 IP: $($Response.data.ip)"
        if ($Response.data.updated) {
            Write-Host "旧 IP: $($Response.data.old_ip)"
        }
        Write-Host "记录类型：$($Response.data.record_type)"
    } else {
        Write-Error "DDNS 更新失败：$($Response.error)"
        exit 1
    }
} catch {
    Write-Error "请求失败：$_"
    exit 1
}

4. Python 脚本

#!/usr/bin/env python3
import requests
import sys

# 配置
DOMAIN = "blog.example.com"
API_TOKEN = "your_api_token"
DDNS_URL = "https://pwdns.org/api/ddns/update"

def get_public_ip():
    """获取公网 IP"""
    services = [
        "https://api.ipify.org?format=json",
        "https://ifconfig.me/ip",
        "https://icanhazip.com"
    ]
    
    for service in services:
        try:
            response = requests.get(service, timeout=5)
            if service == "https://api.ipify.org?format=json":
                return response.json().get('ip')
            else:
                return response.text.strip()
        except Exception as e:
            print(f"获取 IP 失败 ({service}): {e}")
            continue
    
    return None

def update_ddns(ip):
    """更新 DDNS"""
    params = {
        'domain': DOMAIN,
        'ip': ip,
        'token': API_TOKEN
    }
    
    try:
        response = requests.get(DDNS_URL, params=params, timeout=10)
        result = response.json()
        
        if result.get('success'):
            print(f"✓ DDNS 更新成功！")
            print(f"  域名：{result['data']['domain']}")
            print(f"  IP: {result['data']['ip']}")
            print(f"  记录类型：{result['data'].get('record_type', 'N/A')}")
            if result['data'].get('old_ip'):
                print(f"  旧 IP: {result['data']['old_ip']}")
            return True
        else:
            print(f"✗ DDNS 更新失败：{result.get('error')}")
            return False
    except Exception as e:
        print(f"✗ 请求失败：{e}")
        return False

if __name__ == "__main__":
    # 获取当前 IP
    current_ip = get_public_ip()
    if not current_ip:
        print("错误：无法获取公网 IP")
        sys.exit(1)
    
    print(f"当前 IP: {current_ip}")
    
    # 更新 DDNS
    success = update_ddns(current_ip)
    sys.exit(0 if success else 1)

多条记录精确匹配

当同一域名存在多条同类型（A 或 AAAA）记录时，系统无法自动确定要更新哪一条记录，此时必须提供 old_value 参数。

# 通过 old_value=192.168.1.100 精确指定要更新第一条记录
curl -X GET "https://pwdns.org/api/ddns/update?domain=blog.example.com&ip=192.168.1.200&old_value=192.168.1.100&token=your_api_token"

错误处理

如果未提供 old_value，API 将返回 409 错误，并在响应中附带现有记录值列表：

{
  "success": false,
  "error": "域名 blog.example.com 存在 2 条 A 记录，无法确定更新目标。请提供 old_value 参数指定要更新的记录当前值",
  "data": {
    "existing_values": ["192.168.1.100", "10.0.0.1"],
    "hint": "在请求中添加 old_value=<当前IP> 参数来指定要更新的记录"
  }
}

定时任务配置

Linux Crontab

# 编辑 crontab
crontab -e

# 添加以下行
*/5 * * * * /path/to/ddns_script.sh >> /var/log/ddns.log 2>&1

Windows 任务计划程序

# 创建计划任务（每 5 分钟执行一次）
$action = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument "-File C:\path\to\ddns_script.ps1"
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes 5)
Register-ScheduledTask -TaskName "DDNS Update" -Action $action -Trigger $trigger -User "SYSTEM"

安全建议

常见问题

Q: 提示"无效的 token"？

Q: 提示"域名不存在或无权操作"？

Q: 提示"DDNS 功能仅支持子域名，不支持一级域名"？

Q: 更新后 DNS 记录没有立即生效？

Q: 支持 IPv6 吗？

技术细节

认证流程

1. 系统验证提供的 token 是否有效
2. 检查用户账号状态（是否被禁用）
3. 验证用户对域名是否有操作权限

更新流程

1. 检查新旧 IP 是否相同（相同则跳过更新，同时自动检测 DNS 一致性并在不一致时触发补偿同步）
2. 使用数据库事务原子化更新记录并投递同步事件
3. 后台异步处理 DNS 服务器同步
4. 事务失败时数据库和同步事件同时回滚，保持一致性

错误处理

• 所有写操作都有数据库事务保护
• DNS 同步通过后台异步事件管道处理
• 事务失败时自动回滚，不会产生数据不一致
• IP 未变化时会自动检测 DNS 服务器一致性，不一致时触发补偿同步

版本历史