DDNS

本文档详细说明DDNS工具的JSON配置文件格式和参数。JSON配置文件优先级介于命令行参数和环境变量之间。

基本用法

默认情况下，DDNS会在当前目录查找config.json文件。您也可以使用-c参数指定配置文件路径：

注意：在Docker中使用配置文件时，需要通过卷映射将配置文件挂载到容器的/ddns/目录。详情请参考Docker使用文档。

# 生成配置文件
ddns --new-config
# 指定参数和配置文件
ddns --dns dnspod --ipv4 ddns.newfuture.cc --new-config config.json

# 使用指定配置文件
ddns -c /path/to/config.json
# 或者使用Python源码
python -m ddns -c /path/to/config.json

# 使用多个配置文件
ddns -c cloudflare.json -c dnspod.json
# 或通过环境变量
export DDNS_CONFIG="cloudflare.json,dnspod.json"
ddns

JSON模式

DDNS配置文件遵循JSON模式(Schema)，推荐在配置文件中添加$schema字段以获得编辑器的自动补全和验证功能：

自v4.1.0版本开始，配置文件支持单行注释。

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.0.json"
}

Schema

配置参数表

键名 类型 必需 默认值 参数说明 备注
dns string 否 无 DNS服务商 可选值: 51dns, alidns, aliesa, callback, cloudflare, debug, dnscom, dnspod_com, dnspod, edgeone, he, huaweidns, namesilo, noip, tencentcloud
id string 是 无 API 访问 ID 请根据服务商说明配置(如 AccessKeyID)
token string 是 无 API 授权令牌 请根据服务商说明配置(如 AccessSecret)
endpoint string 否 无 API端点URL 用于自定义或私有部署的API地址，为空时使用默认端点
ipv4 array 否 [] IPv4域名列表  
ipv6 array 否 [] IPv6域名列表  
index4 string|int|array 否 ["default"] IPv4获取方式 详见下方说明
index6 string|int|array 否 ["default"] IPv6获取方式 详见下方说明
ttl number 否 null DNS TTL时间 单位为秒，不设置则采用DNS默认策略
line string 否 null DNS解析线路 ISP线路选择，支持的值视DNS服务商而定
proxy string|array 否 无 HTTP代理 多代理逐个尝试直到成功，支持DIRECT(直连)、SYSTEM(系统代理)
ssl string|boolean 否 "auto" SSL验证方式 true（强制验证）、false（禁用验证）、"auto"（自动降级）或自定义CA证书文件路径
cache string|bool 否 true 是否缓存记录 正常情况打开避免频繁更新，默认位置为临时目录下ddns.{hash}.cache，也可以指定具体路径
log object 否 null 日志配置 日志配置对象，支持level、file、format、datefmt参数

dns

dns参数指定使用的DNS服务商标识，支持以下值, 请参考 服务商列表:

当 debug 模式，且未配置dns参数时,使用 debug provider。

id-token

id和token参数用于API认证，具体含义和格式取决于所选的DNS服务商。

endpoint

endpoint参数用于指定自定义API端点，大多数服务商都有默认端点，除非有特殊需求，否则不需要修改。

特殊情况包括：

ipv4-ipv6

ipv4和ipv6参数指定需要更新的DNS记录名称，可以是域名或子域名列表。可以使用数组形式指定多个记录。

支持格式

index4-index6

index4和index6参数用于指定获取IP地址的方式，可以使用以下值：

支持类型:

配置示例：

{
    "index4": ["public", "url:http://ipv4.icanhazip.com"], // 优先使用公网IP，失败后使用指定URL获取
    "index6": ["shell:ip route", "regex:2003:.*"], // 使用shell命令,失败换成正则匹配IPv6地址
    "index4": [0, "public"], // 使用第一个网卡IP,失败换成公网IP
    "index6": "public", // 使用公网IPv6地址
    "index4": false // 禁止更新IPv4记录
}

ttl

ttl参数指定DNS记录的生存时间（TTL），单位为秒。默认值为null，表示使用DNS服务商的默认TTL策略。 具体取值范围和默认值取决于所选的DNS服务商。

line

line参数用于指定DNS解析线路，支持的值取决于所选的DNS服务商。

proxy

proxy参数用于设置HTTP代理，可以是单个代理地址或多个代理地址的数组。支持以下格式：

代理类型:

配置示例

{
    "proxy": "http://127.0.0.1:1080",                    // 单个代理地址
    "proxy": "SYSTEM",                                   // 使用系统代理设置
    "proxy": "DIRECT",                                   // 强制直连，不使用代理
    "proxy": ["http://127.0.0.1:1080", "DIRECT"],       // 先尝试代理，失败后直连
    "proxy": ["SYSTEM", "http://backup:8080", "DIRECT"], // 系统代理→备用代理→直连
    "proxy": null                                        // 使用系统默认代理设置
}

注意：如果配置了proxy，代理只对provider请求有效，获取IP的API不会使用proxy参数。

ssl

ssl参数用于配置SSL验证方式，支持以下值：

注意：如果配置了ssl，则所有API请求，包括 provider 和 IP 获取 API 都会使用该配置。

cache

cache参数用于配置DNS记录的缓存方式，支持以下值：

log

log参数用于配置日志记录，是一个对象，支持以下字段：

键名 类型 必需 默认值 说明
level string 否 INFO 日志级别
file string 否 无 日志文件路径
format string 否 自动调整 日志格式字符串
datefmt string 否 %Y-%m-%dT%H:%M:%S 日期时间格式

配置示例

单Provider格式

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.0.json",
  "id": "12345",
  "token": "mytokenkey",
  "dns": "cloudflare",
  "ipv4": ["ddns.newfuture.cc"],
  "ipv6": ["ddns.newfuture.cc", "ipv6.ddns.newfuture.cc"],
  "index4": ["public", "regex:192\\.168\\.1\\..*"],
  "index6": "public",
  "ttl": 300,
  "proxy": ["http://127.0.0.1:1080", "DIRECT"],
  "ssl": "auto",
  "cache": "/var/cache/ddns.cache",
  "log": {
    "level": "DEBUG",
    "file": "/var/log/ddns.log",
    "datefmt": "%Y-%m-%d %H:%M:%S"
  }
}

多Provider格式

从v4.1.0版本开始，支持在单个配置文件中定义多个DNS Provider，使用新的 providers 数组格式：

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.1.json",
  "ssl": "auto",
  "cache": true,
  "log": {"level": "INFO", "file": "/var/log/ddns.log"},
  "providers": [
    {
      "provider": "cloudflare",
      "id": "user1@example.com",
      "token": "cloudflare-token",
      "ipv4": ["test1.example.com"],
      "ttl": 300
    },
    {
      "provider": "dnspod",
      "id": "user2@example.com",
      "token": "dnspod-token",
      "ipv4": ["test2.example.com"],
      "ttl": 600
    }
  ]
}

v4.1格式特性

冲突检查

配置优先级和字段覆盖关系

DDNS工具中的配置优先级顺序为：命令行参数 > JSON配置文件 > 环境变量。

配置覆盖示例

假设有以下配置：

  1. 环境变量：DDNS_TTL=600
  2. JSON配置文件："ttl": 300
  3. 命令行参数：--ttl 900

最终生效的是命令行参数的值：ttl=900

如果没有提供命令行参数，则使用JSON配置值：ttl=300

特殊情况

注意事项

  1. 配置文件使用UTF-8编码，不包含BOM标记
  2. JSON中所有键名区分大小写
  3. 在配置文件中，对于需要使用反斜杠的字符串（如正则表达式），需要进行双重转义
  4. debug参数在配置文件中设置无效，仅支持命令行参数--debug
  5. 首次运行时会在当前目录自动生成一个模板配置文件
  6. 推荐使用支持JSONSchema的编辑器（如VSCode）编辑配置文件，可获得自动补全和验证功能
This site is open source. Improve this page.