DDNS

自动更新 DNS 解析到本机 IP 地址，支持 IPv4/IPv6，内网/公网 IP，自动创建 DNS 记录

GitHub Build Publish Release PyPI Python Version Docker Docker image size

主要特性

🚀 多平台支持

⚙️ 灵活配置

🌍 DNS 服务商支持

支持 15+ 主流 DNS 服务商，包括：

⚡ 表示支持 HMAC-SHA256 企业级安全认证 查看所有服务商

🔧 高级功能

使用

① 安装

根据需要选择一种方式：一键脚本、二进制版、pip版、源码运行，或者 Docker。

推荐 Docker 版，兼容性最佳，体积小，性能优化。

② 快速配置

  1. 申请 api token，填写到对应的 id 和 token 字段:

  2. 修改配置文件，ipv4 和 ipv6 字段，为待更新的域名，详细参照配置说明

详细配置

所有字段可通过三种方式进行配置，优先级为：命令行参数 > JSON配置文件 > 环境变量

  1. 命令行参数 ddns --key=value（ddns -h 查看详情），优先级最高
  2. JSON 配置文件（值为 null 认为是有效值，会覆盖环境变量的设置，如果没有对应的 key 则会尝试使用环境变量）
  3. 环境变量 DDNS_ 前缀加上 key （${ddns_id} 或 ${DDNS_ID}，${DDNS_LOG_LEVEL}）

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

如果同一个配置项在多个地方设置，将按照以下优先级规则生效：

高级用法：

各配置方式的详细说明请查看对应文档：命令行、JSON配置、环境变量、服务商配置

📖 环境变量详细配置: 查看 环境变量配置文档 了解所有环境变量的详细用法和示例

config.json 配置文件 
ddns -c path/to/config.json
# 或者python运行
python -m ddns -c /path/to/config.json
# 远程配置文件
ddns -c https://ddns.newfuture.cc/tests/config/debug.json

配置参数表

key type required default description tips
id string √ 无 api 访问 ID Cloudflare 为邮箱（使用 Token 时留空）
HE.net 可留空
华为云为 Access Key ID (AK)
token string √ 无 api 授权 token 部分平台叫 secret key，反馈粘贴时删除
dns string No "dnspod" dns 服务商 阿里 DNS 为 alidns，阿里ESA为 aliesa，Cloudflare 为 cloudflare，dns.com 为 dnscom，DNSPOD 国内为 dnspod，DNSPOD 国际为 dnspod_com，HE.net 为 he，华为云为 huaweidns，NameSilo 为 namesilo，腾讯云为 tencentcloud，腾讯云EdgeOne为 edgeone，No-IP 为 noip，自定义回调为 callback。部分服务商有详细配置文档
ipv4 array No [] ipv4 域名列表 为 [] 时，不会获取和更新 IPv4 地址
ipv6 array No [] ipv6 域名列表 为 [] 时，不会获取和更新 IPv6 地址
index4 string|int|array No "default" ipv4 获取方式 可设置 网卡、内网、公网、正则 等方式
index6 string|int|array No "default" ipv6 获取方式 可设置 网卡、内网、公网、正则 等方式
ttl number No null DNS 解析 TTL 时间 不设置采用 DNS 默认策略
proxy string|array No 无 HTTP 代理格式：http://host:port 多代理逐个尝试直到成功，DIRECT 为直连
ssl string|boolean No "auto" SSL证书验证方式 true（强制验证）、false（禁用验证）、"auto"（自动降级）或自定义CA证书文件路径
debug bool No false 是否开启调试 调试模式，仅命令行参数--debug有效
cache string|bool No true 是否缓存记录 正常情况打开避免频繁更新，默认位置为临时目录下 ddns.cache，也可以指定一个具体路径
log object No null 日志配置（可选） 日志配置对象，支持level、file、format、datefmt参数

index4 和 index6 参数说明

自定义回调配置说明

详细配置指南请查看：Callback Provider 配置文档

常量名称 常量内容 说明
__DOMAIN__ DDNS 域名  
__IP__ 获取的对应类型的 IP 地址  
__RECORDTYPE__ DDNS 记录类型  
__TTL__ DDNS TTL  
__TIMESTAMP__ 请求发起时间戳 包含小数

配置示例

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.0.json",
  "id": "12345",
  "token": "mytokenkey",
  "dns": "dnspod 或 dnspod_com 或 alidns 或 aliesa 或 dnscom 或 cloudflare 或 he 或 huaweidns 或 namesilo 或 tencentcloud 或 noip 或 callback",
  "ipv4": ["ddns.newfuture.cc", "ipv4.ddns.newfuture.cc"],
  "ipv6": ["ddns.newfuture.cc", "ipv6.ddns.newfuture.cc"],
  "index4": 0,
  "index6": "public",
  "ttl": 600,
  "proxy": ["http://127.0.0.1:1080", "DIRECT"],
  "log": {
    "level": "DEBUG",
    "file": "dns.log",
    "datefmt": "%Y-%m-%dT%H:%M:%S"
  }
}

定时任务

使用内置的 task 命令设置定时任务（默认每 5 分钟检查一次 IP，自动更新）

DDNS 提供内置的 task 子命令来管理定时任务，支持跨平台自动化部署：

高级管理

# 安装并指定更新间隔（分钟）
ddns task --install 10 -c /etc/config/ddns.json

# 启用/禁用任务
ddns task --enable
ddns task --disable

详细配置指南请参考：命令行参数文档

Docker

Docker 镜像在无额外参数的情况下，已默认启用每 5 分钟执行一次的定时任务

问题排查反馈
  1. 先确认排查是否是系统/网络环境问题
  2. 在 issues 中搜索是否有类似问题
  3. 前两者均无法解决或者确定是 bug，在此新建 issue
    • 开启 --debug
    • 附上这些内容 运行版本和方式、系统环境、出错日志、去掉 id/token 的配置文件
    • 源码运行注明使用的 python 环境
This site is open source. Improve this page.