🌐 DDNS API 使用文档

📋 概述

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

🔗 API 端点

📝 请求参数

🔖 支持的记录类型

📤 响应格式

成功响应

{
  "success": true,
  "message": "DDNS 更新成功",
  "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
  }
}

错误响应

{
  "success": false,
  "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"

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)

⏰ 定时任务配置

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 是否相同（相同则跳过更新）
2. 调用 DNS 服务器 API 更新记录
3. 更新本地数据库记录
4. 如果数据库更新失败，尝试回滚 DNS 服务器

错误处理

• 所有写操作都有事务保护
• DNS 服务器更新失败会返回错误
• 数据库更新失败会尝试回滚 DNS 更改

📦 版本历史