Home Explore Help
Register Sign In
Apq
/
DDNS
mirror of https://github.com/NewFuture/DDNS.git
1
0
Fork 0
Files Issues 0 Wiki
Tree: 39f645a91b
Branches Tags
DDNS
/
doc
/
config
/
json.md

json.md 12 KB
History Raw

title: DDNS JSON配置文件参考

description: 了解DDNS工具的JSON配置文件格式和参数，如何使用配置文件以及配置文件的优先级

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

基本用法

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

  • 当前目录 config.json (注意Docker运行目录是 /ddns/)
  • 当前用户目录 ~/.ddns/config.json
  • Linux当前系统 /etc/ddns/config.json

注意：在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端点，大多数服务商都有默认端点，除非有特殊需求，否则不需要修改。

特殊情况包括：

  • 不同区域部署的服务商（如腾讯云、阿里云等）需要指定对应区域的API端点。
  • 私有云部署：如果您使用的是私有部署的DNS服务，需要指定相应的私有API端点地址。
  • 代理转发：如果您使用第三方API代理服务，需要指定代理的URL。

ipv4-ipv6

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

支持格式

  • 无值时，表示不更新对应类型的DNS记录。
  • 单个域名："ddns.newfuture.cc"
  • 多个域名：["ddns.newfuture.cc", "ipv6.ddns.newfuture.cc"]

index4-index6

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

支持类型:

  • false表示禁止更新相应IP类型的DNS记录
  • 数字（如0、1、2...）：表示使用第N个网卡的IP地址
  • "default"：系统访问外网的默认IP
  • "public"：使用公网IP（通过API查询）
  • "url:http..."：通过指定URL获取IP，例如"url:http://ip.sb"
  • "regex:xxx"：使用正则表达式匹配本地网络配置中的IP，例如"regex:192\\.168\\..*"
    • 注意：JSON中反斜杠需要转义，如"regex:10\\.00\\..*"表示匹配10.00.开头的IP
  • "cmd:xxx"：执行指定命令并使用其输出作为IP
  • "shell:xxx"：使用系统shell运行命令并使用其输出作为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代理，可以是单个代理地址或多个代理地址的数组。支持以下格式：

代理类型:

  • 具体代理: "http://<proxy_host>:<proxy_port>" 或 "https://<proxy_host>:<proxy_port>"
  • 直连: "DIRECT" - 强制不使用代理，忽略系统代理设置
  • 系统代理: "SYSTEM" - 使用系统默认代理设置（如IE代理、环境变量等）
  • 自动: null 或不设置 - 使用系统默认代理设置

配置示例

{
    "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验证方式，支持以下值：

  • "auto"：自动降级到不验证SSL证书（不太安全）
  • true：强制验证SSL证书
  • false：禁用SSL验证 (不安全)
  • "/path/to/ca.crt"，用于指定自定义的CA证书文件

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

cache

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

  • true：启用缓存，默认位置为临时目录下的ddns.{hash}.cache
  • false：禁用缓存
  • "/path/to/cache.file"：指定自定义缓存文件路径

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": "[email protected]",
      "token": "cloudflare-token",
      "ipv4": ["test1.example.com"],
      "ttl": 300
    },
    {
      "provider": "dnspod",
      "id": "[email protected]",
      "token": "dnspod-token",
      "ipv4": ["test2.example.com"],
      "ttl": 600
    }
  ]
}

v4.1格式特性

  • 全局配置继承: providers 外的所有配置项（如 ssl, cache, log 等）作为全局设置，会被所有provider继承
  • provider覆盖: 每个provider内的配置可以覆盖相应的全局设置
  • provider字段: 必须字段，指定DNS服务商类型（等同于传统格式中的 dns 字段）
  • 完整兼容: 支持所有传统格式中的配置参数
  • 嵌套对象扁平化: provider内的嵌套对象会被自动扁平化处理

冲突检查

  • providers 和 dns 字段不能同时存在
  • 多providers时，不能在全局配置中使用 ipv4 或 ipv6 字段
    • 每个provider必须包含 provider 字段
    • 外层(global)不得包含 ipv4或者 ipv6 字段

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

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

  • 命令行参数：优先级最高，会覆盖JSON配置文件和环境变量中的相同设置
  • JSON配置文件：介于命令行参数和环境变量之间，会覆盖环境变量中的设置
  • 环境变量：优先级最低，当命令行参数和JSON配置文件中都没有相应设置时使用

配置覆盖示例

假设有以下配置：

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

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

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

特殊情况

  • 当JSON配置文件中某个值明确设为null时，将覆盖环境变量设置，相当于未设置该值
  • 当JSON配置文件中缺少某个键时，会尝试使用对应的环境变量
  • 某些参数（如debug）仅在特定配置方式下有效：debug参数只在命令行中有效，JSON配置中的设置会被忽略

注意事项

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