DDNS JSON 配置文件参考

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

可视化配置

可以使用配置生成与校验工具创建多服务商配置、定位错误并下载 config.json。凭据仅在浏览器本地处理，不会上传；在工具中填写的认证信息会完整写入导出的配置，如需避免写入文件，请改用环境变量或命令行参数。

基本用法

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

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

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

bash

# 生成配置文件
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版本开始，配置文件支持单行注释。

jsonc

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.1.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`，也可以指定具体路径
cache_max_age	integer	否	`259200`	缓存文件最大有效期（秒）	`0` 表示下一次运行清空已有缓存；与 DNS TTL 无关
interval	integer	否	无	Web 自动同步间隔（分钟）	顶层配置，范围 1–1440；配置后普通启动会自动进入 Web 模式
http	object	否	`127.0.0.1:9876`	Web 与 HTTP MCP 共享监听配置	顶层配置；支持 `host`、`port`、`token`、`origins`
log	object	否	`null`	日志配置	日志配置对象，支持`level`、`file`、`format`、`datefmt`参数

interval

在配置文件顶层设置 interval 后，ddns -c config.json 会启动常驻 Web 控制台，并按该分钟数自动同步。命令行 --interval 优先于配置值；省略两者时，普通 ddns -c config.json 仍只同步一次。interval 只能配置在顶层，范围为 1–1440。

http

http 同时控制 Web 控制台及 MCP 2026-07-28 Streamable HTTP endpoint /mcp：

jsonc

{
  "http": {
    "host": "127.0.0.1",
    "port": 9876,
    "token": null,
    "origins": ["https://ddns.example.com"]
  }
}

字段	类型	默认值	说明
`host`	string	`"127.0.0.1"`	监听地址；支持具体局域网地址及 `0.0.0.0` / `::`
`port`	integer	`9876`	监听端口，范围 0–65535；`0` 由系统分配
`token`	string\|null	`null`	Web API 与 HTTP MCP 共享 token；使用无空格的可见 ASCII 字符，明文保存在配置中
`origins`	array	`[]`	允许跨源访问 `/mcp` 的精确 HTTP(S) origin，不支持通配符或路径

回环监听且 token 为空时，Web API（包括完整 provider 配置和凭据）与 /mcp 均免认证。非回环或通配监听必须配置非空 token；HTTP MCP 通过 Authorization: Bearer 发送，Web 页面也使用相同 token。DDNS 不内置 TLS，局域网监听应放在受信 HTTPS 反向代理后，并确保代理不会记录 token。

监听设置优先级为命令行参数 > JSON http > DDNS_HTTP_HOST、DDNS_HTTP_PORT、DDNS_HTTP_TOKEN、DDNS_HTTP_ORIGINS > 默认值。保存这些设置后需重启进程。

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

配置示例：

jsonc

{
    "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 或不设置 - 使用系统默认代理设置

配置示例

jsonc

{
    "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"：指定自定义缓存文件路径

cache_max_age

缓存文件按整体 mtime 判断有效期，单位为秒，默认 259200（72 小时）。下一次运行时，now - mtime >= cache_max_age 或 mtime 在未来即视为过期；设置为 0 会在每次运行清空已有缓存。缓存仍为原有扁平 JSON，不保存每条记录时间戳，也不迁移。由于整个文件只有一个 mtime，任何缓存内容写入都会刷新所有记录的有效期；共享缓存文件的限制不变。

log

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

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

配置示例

单Provider格式

jsonc

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.1.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 数组格式：

jsonc

{
  "$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格式特性

全局配置继承: 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配置文件中都没有相应设置时使用

配置覆盖示例

假设有以下配置：

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

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

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

特殊情况

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

注意事项

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

DDNS JSON 配置文件参考 ​

基本用法 ​

JSON模式 ​

Schema ​

interval ​

http ​

dns ​

id-token ​

endpoint ​

ipv4-ipv6 ​

index4-index6 ​

ttl ​

line ​

proxy ​

ssl ​

cache ​

cache_max_age ​

log ​

配置示例 ​

单Provider格式 ​

多Provider格式 ​

v4.1格式特性 ​

冲突检查 ​

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

配置覆盖示例 ​

特殊情况 ​

注意事项 ​

DDNS JSON 配置文件参考

基本用法

JSON模式

Schema

interval

http

dns

id-token

endpoint

ipv4-ipv6

index4-index6

ttl

line

proxy

ssl

cache

cache_max_age

log

配置示例

单Provider格式

多Provider格式

v4.1格式特性

冲突检查

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

配置覆盖示例

特殊情况

注意事项