README.md 17 KB
DDNS
自动更新 DNS 解析到本机 IP 地址，支持 IPv4/IPv6，内网/公网 IP，自动创建 DNS 记录
主要特性
🚀 多平台支持
- Docker: 推荐方式，支持
amd64、arm64、arm/v7等多架构 (使用文档) - 二进制文件: 单文件运行，支持 Windows/Linux/macOS (下载地址)
- pip 安装:
pip install ddns - 源码运行: 无依赖，仅需 Python 环境
⚙️ 灵活配置
- 命令行参数:
ddns --dns=dnspod --id=xxx --token=xxx(配置文档) - JSON 配置文件: 支持多域名、多服务商配置，支持远程URL配置 (配置文档)
- 环境变量: Docker 友好的配置方式 (配置文档)
🌍 DNS 服务商支持
支持 15+ 主流 DNS 服务商，包括：
- 国内: 阿里DNS ⚡、阿里云ESA ⚡、DNSPOD、腾讯云DNS ⚡、腾讯云EdgeOne ⚡、华为云DNS ⚡、DNS.COM
- 国际: Cloudflare、DNSPOD国际版、HE.net、NameSilo、No-IP
- 自定义: 回调 API、调试模式
⚡ 表示支持 HMAC-SHA256 企业级安全认证 | 查看所有服务商
🔧 高级功能
- 多域名和多级域名解析
- IPv4/IPv6 双栈支持
- 自动创建 DNS 记录
- 内网/公网 IP 自动检测
- HTTP 代理和多代理切换
- 本地缓存减少 API 调用
- 定时任务和日志管理
使用
① 安装
根据需要选择一种方式：一键脚本、二进制版、pip版、源码运行，或者 Docker。
推荐 Docker 版，兼容性最佳，体积小，性能优化。
- #### Docker（推荐）
详细说明和高级用法请查看 Docker 使用文档
支持命令行，配置文件，和环境变量传参
命令行cli
docker run newfuture/ddns -h使用配置文件（docker 工作目录
/ddns/，默认配置位置/ddns/config.json）：docker run -d -v /host/config/:/ddns/ --network host newfuture/ddns使用环境变量：
docker run -d \ -e DDNS_DNS=dnspod \ -e DDNS_ID=12345 \ -e DDNS_TOKEN=mytokenkey \ -e DDNS_IPV4=ddns.newfuture.cc \ --network host \ newfuture/ddns
- #### 二进制版（单文件，无需 python）
也可使用一键安装脚本自动下载并安装对应平台的二进制：
curl -#fSL https://ddns.newfuture.cc/install.sh | sh
提示：安装到系统目录（如 /usr/local/bin）可能需要 root 或 sudo 权限；若权限不足，可改为 sudo sh 运行。
详细说明请查看 一键安装文档
pip 安装（需要 pip 或 easy_install）
- 安装 ddns:
pip install ddns或easy_install ddns - 运行:
ddns -h或者python -m ddns
- 安装 ddns:
源码运行（无任何依赖，需 python 环境）
- clone 或者 下载此仓库 并解压
- 运行
python -m ddns
② 快速配置
申请 api
token，填写到对应的id和token字段:- DNSPOD(中国版): 创建 token | 详细配置文档
- 阿里云 DNS: 申请 accesskey | 详细配置文档
- 阿里云边缘安全加速(ESA): 申请 accesskey | 详细配置文档
- 51DNS(dns.com): API Key/Secret | 详细配置文档
- DNSPOD(国际版): 获取 token | 详细配置文档
- CloudFlare: API Key（除了
email + API KEY，也可使用Token，需要list Zone 权限） | 详细配置文档 - HE.net: DDNS 文档（仅需将设置的密码填入
token字段，id字段可留空） | 详细配置文档 - 华为云 DNS: APIKEY 申请（点左边访问密钥，然后点新增访问密钥） | 详细配置文档
- NameSilo: API Key（API Manager 中获取 API Key） | 详细配置文档
- 腾讯云 DNS: API Secret | 详细配置文档
- 腾讯云 EdgeOne: API Secret | 详细配置文档
- No-IP: 用户名和密码（使用 No-IP 账户的用户名和密码） | 详细配置文档
- 自定义回调: 参数填写方式请查看下方的自定义回调配置说明
修改配置文件，
ipv4和ipv6字段，为待更新的域名，详细参照配置说明
详细配置
所有字段可通过三种方式进行配置，优先级为：命令行参数 > JSON配置文件 > 环境变量
- 命令行参数
ddns --key=value（ddns -h查看详情），优先级最高 - JSON 配置文件（值为 null 认为是有效值，会覆盖环境变量的设置，如果没有对应的 key 则会尝试使用环境变量）
- 环境变量 DDNS_ 前缀加上 key （
${ddns_id}或${DDNS_ID}，${DDNS_LOG_LEVEL}）
配置优先级和字段覆盖关系
如果同一个配置项在多个地方设置，将按照以下优先级规则生效：
- 命令行参数：优先级最高，会覆盖其他所有设置
- JSON配置文件：介于命令行和环境变量之间，会覆盖环境变量中的设置
- 环境变量：优先级最低，当其他方式未设置时使用
高级用法：
- JSON配置中明确设为
null的值会覆盖环境变量设置 debug参数只在命令行中有效，JSON配置文件中的同名设置无效- 多值参数（如
ipv4、ipv6等）在命令行中使用方式为重复使用参数，如--ipv4 domain1 --ipv4 domain2
各配置方式的详细说明请查看对应文档：命令行、JSON配置、环境变量、服务商配置
📖 环境变量详细配置: 查看 环境变量配置文档 了解所有环境变量的详细用法和示例
config.json 配置文件
- 首次运行会自动生成一个模板配置文件 - 可以使用 `-c` 使用指定的配置文件（默认读取当前目录的 config.json） - 推荐使用 vscode 等支持 JsonSchema 的编辑器编辑配置文件 - 查看 [JSON配置文件详细文档](doc/config/json.md) 了解完整的配置选项和示例 ```bash 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`。部分服务商有[详细配置文档](doc/providers/) | | 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 参数说明 - 数字（`0`，`1`，`2`，`3`等）：第 i 个网卡 ip - 字符串 `"default"`（或者无此项）：系统访问外网默认 IP - 字符串 `"public"`：使用公网 ip（使用公网 API 查询，url 的简化模式） - 字符串 `"url:xxx"`：打开 URL `xxx`（如：`"url:http://ip.sb"`），从返回的数据提取 IP 地址 - 字符串 `"regex:xxx"` 正则表达（如 `"regex:192.*"`）：提取 `ifconfig`/`ipconfig` 中与之匹配的首个 IP 地址，**注意 json 转义**（`\`要写成`\\`） - `"192.*"` 表示 192 开头的所有 ip（注意 `regex:` 不可省略） - 如果想匹配 `10.00.xxxx` 应该写成 `"regex:10\\.00\\..*"`（`"\\"` json 转义成 `\`） - 字符串 `"cmd:xxxx"`：执行命令 `xxxx` 的 stdout 输出结果作为目标 IP - 字符串 `"shell:xxx"`：使用系统 shell 运行 `xxx`，并把结果 stdout 作为目标 IP - `false`：强制禁止更新 ipv4 或 ipv6 的 DNS 解析 - 列表：依次执行列表中的 index 规则，并将最先获得的结果作为目标 IP - 例如 `["public", "regex:172\\..*"]` 将先查询公网 API，未获取到 IP 后再从本地寻找 172 开头的 IP #### 自定义回调配置说明 - `id` 字段填写回调地址，以 HTTP 或 HTTPS 开头，推荐采用 HTTPS 方式的回调 API，支持变量替换功能。 - `token` 字段为 POST 请求参数（JSON对象或JSON字符串），本字段为空或不存在则使用 GET 方式发起回调。当 JSON 的参数值包含下表所示的常量字符串时，会自动替换为实际内容。 详细配置指南请查看：[Callback Provider 配置文档](doc/providers/callback.md) | 常量名称 | 常量内容 | 说明 | | ---------------- | ------------------------ | -------- | | `__DOMAIN__` | DDNS 域名 | | | `__IP__` | 获取的对应类型的 IP 地址 | | | `__RECORDTYPE__` | DDNS 记录类型 | | | `__TTL__` | DDNS TTL | | | `__TIMESTAMP__` | 请求发起时间戳 | 包含小数 | #### 配置示例 ```json { "$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" } } ```