DDNS 环境变量配置文档

概述

DDNS 支持通过环境变量进行配置，环境变量的优先级为：命令行参数 > 配置文件 > 环境变量

所有环境变量都以 DDNS_ 为前缀，后跟参数名（推荐全大写）,对象和属性分隔符用_分割。

export DDNS_XXX="xxx" 命令作用于当前主机 docker run -e DDNS_XXX="xxx" 命令作用于容器内

环境变量完整参数列表

环境变量	参数格式	描述	示例
`DDNS_CONFIG`	文件路径，支持逗号或分号分隔多个路径，支持远程HTTP(S) URL	指定配置文件路径，支持多个配置文件和远程配置	`DDNS_CONFIG="config.json"` 或 `DDNS_CONFIG="cloudflare.json,dnspod.json"` `DDNS_CONFIG="https://ddns.newfuture.cc/tests/config/debug.json"`
`DDNS_DNS`	`51dns`、`alidns`、`aliesa`、`callback`、`cloudflare`、`debug`、`dnscom`、`dnspod_com`、`dnspod`、`edgeone`、`he`、`huaweidns`、`noip`、`tencentcloud`	DNS 服务商	`DDNS_DNS=cloudflare`
`DDNS_ID`	依 DNS 服务商而定	API 账号或 ID	`DDNS_ID="user@example.com"`
`DDNS_TOKEN`	依 DNS 服务商而定	API 授权令牌或 Secret	`DDNS_TOKEN="abcdef123456"`
`DDNS_ENDPOINT`	URL（http 或 https 协议）	自定义 API 地址	`DDNS_ENDPOINT=https://api.dns.cn`
`DDNS_IPV4`	域名，数组或逗号分隔字符串	IPv4 域名列表	`DDNS_IPV4='["t.com","4.t.com"]'`
`DDNS_IPV6`	域名，数组或逗号分隔字符串	IPv6 域名列表	`DDNS_IPV6=t.com,6.t.com`
`DDNS_INDEX4`	数字、default、public、url:、regex:、cmd:、shell:，可为数组	IPv4 获取方式	`DDNS_INDEX4="[0,'regex:192.168.*']"`
`DDNS_INDEX6`	数字、default、public、url:、regex:、cmd:、shell:，可为数组	IPv6 获取方式	`DDNS_INDEX6=public`
`DDNS_TTL`	整数（单位：秒），依服务商而定	设置 DNS TTL	`DDNS_TTL=600`
`DDNS_LINE`	依服务商而定，如：电信、移动	DNS 解析线路	`DDNS_LINE=电信`
`DDNS_PROXY`	`http://host:port` 或 DIRECT，支持多代理数组或分号分隔	HTTP 代理设置	`DDNS_PROXY="http://127.0.0.1:1080;DIRECT"`
`DDNS_CACHE`	true、false 或文件路径	启用缓存或指定缓存文件路径	`DDNS_CACHE="/tmp/cache"`
`DDNS_SSL`	true、false、auto 或文件路径	设置 SSL 验证方式或指定证书路径	`DDNS_SSL=false` `DDNS_SSL=/path/ca.crt`
`DDNS_CRON`	Cron 表达式格式字符串（仅 Docker 环境有效）	Docker 容器内定时任务周期	`DDNS_CRON="/10 * * *"`
`DDNS_LOG_LEVEL`	DEBUG、INFO、WARNING、ERROR、CRITICAL	设置日志等级	`DDNS_LOG_LEVEL="DEBUG"`
`DDNS_LOG_FILE`	文件路径	设置日志输出文件（默认输出到终端）	`DDNS_LOG_FILE="/tmp/ddns.log"`
`DDNS_LOG_FORMAT`	Python logging 格式模板	设置日志格式	`DDNS_LOG_FORMAT="%(message)s"`
`DDNS_LOG_DATEFMT`	日期时间格式字符串	设置日志时间格式	`DDNS_LOG_DATEFMT="%m-%d %H:%M"`

注意: 数组确认字符串引号，可打印出来查看

基础配置参数

配置文件路径

DDNS_CONFIG

类型: 字符串
必需: 否
默认值: 按默认路径搜索（config.json、~/.ddns/config.json等）
格式: 单个文件路径、多个文件路径（用逗号或分号分隔）、或远程HTTP(S) URL
说明: 指定配置文件路径，支持多个配置文件同时使用和远程配置文件

示例:

bash

# 单个配置文件
export DDNS_CONFIG="config.json"
export DDNS_CONFIG="/path/to/ddns.json"

# 远程配置文件
export DDNS_CONFIG="https://ddns.newfuture.cc/tests/config/debug.json"
export DDNS_CONFIG="https://user:password@config.example.com/ddns.json"

# 多个配置文件径
export DDNS_CONFIG="/etc/ddns/cloudflare.json,./dnspod.json"

# 混合本地和远程配置
export DDNS_CONFIG="local.json,https://remote.example.com/config.json"

DNS 服务商

DDNS_DNS

类型: 字符串
必需: 否
默认值: dnspod
可选值: 51dns, alidns, aliesa, callback, cloudflare, debug, dnscom, dnspod, dnspod_com, edgeone, he, huaweidns, noip, tencentcloud
说明: DNS 服务提供商

示例:

bash

export DDNS_DNS="alidns"        # 阿里云 DNS
export DDNS_DNS="aliesa"        # 阿里云企业版 DNS
export DDNS_DNS="cloudflare"    # CloudFlare
export DDNS_DNS="dnspod"        # DNSPod 国内版
export DDNS_DNS="dnspod_com"    # DNSPod 国际版
export DDNS_DNS="dnscom"        # DNS.COM
export DDNS_DNS="51dns"         # 51DNS (DNS.COM别名)
export DDNS_DNS="he"            # HE.net
export DDNS_DNS="huaweidns"     # 华为云 DNS
export DDNS_DNS="noip"          # NoIP
export DDNS_DNS="tencentcloud"  # 腾讯云 DNS
export DDNS_DNS="edgeone"       # 腾讯云 EdgeOne
export DDNS_DNS="callback"      # 自定义回调
export DDNS_DNS="debug"         # 调试模式

DDNS_ENDPOINT

类型: 字符串
必需: 否
默认值: 无（使用各DNS服务商的默认API端点）
说明: API端点URL，用于自定义或私有部署的API地址

示例:

bash

export DDNS_ENDPOINT="https://api.example.com"     # 自定义API端点
export DDNS_ENDPOINT="https://private.dns.com"     # 私有部署的DNS API
export DDNS_ENDPOINT=""                             # 使用默认端点

域名配置

IPv4 域名列表

DDNS_IPV4

类型: 数组（支持 JSON/python 格式）
必需: 否
默认值: []
说明: 需要更新 IPv4 记录的域名列表

示例:

bash

# JSON 数组格式（推荐）
export DDNS_IPV4='["example.com", "sub.example.com"]'

# 单个域名
export DDNS_IPV4="example.com"

# 禁用 IPv4 更新
export DDNS_IPV4="[]"

IP 获取方式

IPv4 获取方式

DDNS_INDEX4

类型: 字符串或数组
必需: 否
默认值: ["default"] (使用系统默认外网IP)
说明: IPv4 地址获取方式。支持逗号,或分号;分隔的字符串格式
特殊说明: 当值包含 regex:、cmd: 或 shell: 前缀时，不支持分隔符分割，整个字符串作为单一配置项

示例:

bash

# 默认方式（系统默认外网 IP）
export DDNS_INDEX4="default"

# 公网 IP
export DDNS_INDEX4="public"

# 指定网卡（第 0 个网卡）
export DDNS_INDEX4="0"

# 自定义 URL 获取
export DDNS_INDEX4="url:http://ip.sb"

# 正则匹配（注意转义）- 不支持分割
export DDNS_INDEX4="regex:192\\.168\\..*"

# 执行命令 - 不支持分割
export DDNS_INDEX4="cmd:curl -s http://ipv4.icanhazip.com"

# Shell 命令 - 不支持分割
export DDNS_INDEX4="shell:ip route get 8.8.8.8 | awk '{print \$7}'"

# 逗号分隔多种方式（仅限无特殊前缀时）
export DDNS_INDEX4="public,default"

# 包含逗号的正则表达式（整体作为单一配置）
export DDNS_INDEX4="regex:192\\.168\\..*,10\\..*"

# 多种方式组合（JSON 数组）
export DDNS_INDEX4='["public", "regex:172\\..*"]'

# 禁用 IPv4 获取
export DDNS_INDEX4="false"

网络配置

代理设置

DDNS_PROXY

类型: 数组（支持 JSON 格式或分号分隔）
必需: 否
默认值: 无
说明: HTTP 代理设置，支持多代理轮换

示例:

bash

# 单个代理
export DDNS_PROXY="http://127.0.0.1:1080"

# 多个代理（JSON 数组格式）
export DDNS_PROXY='["http://proxy1:8080", "http://proxy2:8080", "DIRECT"]'

# 分号分隔格式
export DDNS_PROXY="http://proxy1:8080;http://proxy2:8080;DIRECT"

# DIRECT 表示直连
export DDNS_PROXY="DIRECT"

系统配置

缓存设置

DDNS_CACHE

类型: 布尔值或字符串
必需: 否
默认值: true
说明: 启用缓存以减少 API 请求

示例:

bash

# 启用缓存（默认路径）
export DDNS_CACHE="true"

# 禁用缓存
export DDNS_CACHE="false"

# 自定义缓存文件路径
export DDNS_CACHE="/path/to/ddns.cache"

SSL证书验证

DDNS_SSL

类型: 字符串或布尔值
必需: 否
默认值: "auto"
说明: SSL证书验证方式，控制HTTPS连接的证书验证行为
可选值:
- "true": 强制验证SSL证书（最安全）
- "false": 禁用SSL证书验证（最不安全）
- "auto": 优先验证，SSL证书错误时自动降级（不安全）
- 文件路径: 使用指定路径的自定义CA证书（最安全）

示例:

bash

export DDNS_SSL="true"     # 强制验证SSL证书
export DDNS_SSL="false"    # 禁用SSL验证（不推荐）
export DDNS_SSL="auto"     # 自动降级模式
export DDNS_SSL="/etc/ssl/certs/ca-certificates.crt"  # 自定义CA证书

Docker 定时任务配置

DDNS_CRON

类型: 字符串
必需: 否
默认值: */5 * * * * （每 5 分钟）
说明: Docker 容器中定时任务的执行周期，仅在 Docker 环境中有效。使用标准的 cron 表达式格式
格式: 分钟小时日月星期

示例:

bash

# 每 10 分钟执行一次
export DDNS_CRON="*/10 * * * *"

# 每小时执行一次
export DDNS_CRON="0 * * * *"

# 每天凌晨 2 点执行一次
export DDNS_CRON="0 2 * * *"

# 每 15 分钟执行一次
export DDNS_CRON="*/15 * * * *"

# 每 2 小时执行一次
export DDNS_CRON="0 */2 * * *"

Cron 表达式说明:

字段	允许值	允许的特殊字符
分钟	0-59	* , - /
小时	0-23	* , - /
日	1-31	* , - /
月	1-12	* , - /
星期	0-7	* , - /

常用表达式:

*/5 * * * * - 每 5 分钟（默认）
*/10 * * * * - 每 10 分钟
*/15 * * * * - 每 15 分钟
0 * * * * - 每小时
0 */2 * * * - 每 2 小时
0 0 * * * - 每天午夜
0 2 * * * - 每天凌晨 2 点
0 0 * * 0 - 每周日午夜

注意: 此环境变量仅在 Docker 容器中生效，不影响通过其他方式运行的 DDNS 程序。

日志配置

DDNS_LOG_LEVEL

类型: 字符串
必需: 否
默认值: INFO
可选值: CRITICAL, FATAL, ERROR, WARN, WARNING, INFO, DEBUG, NOTSET
说明: 日志级别

示例:

bash

export DDNS_LOG_LEVEL="DEBUG"    # 调试模式
export DDNS_LOG_LEVEL="INFO"     # 信息模式
export DDNS_LOG_LEVEL="ERROR"    # 仅错误

DDNS_LOG_FILE

类型: 字符串
必需: 否
默认值: 无（输出到控制台）
说明: 日志文件路径

示例:

bash

export DDNS_LOG_FILE="/var/log/ddns.log"
export DDNS_LOG_FILE="./ddns.log"

DDNS_LOG_FORMAT

类型: 字符串
必需: 否
默认值: %(asctime)s %(levelname)s [%(module)s]: %(message)s
说明: 日志格式字符串，参考Python logging模块的格式化语法

示例:

bash

# 默认格式（含模块名）
export DDNS_LOG_FORMAT="%(asctime)s %(levelname)s [%(module)s]: %(message)s"

# 包含文件名和行号（debug模式下默认格式）
export DDNS_LOG_FORMAT="%(asctime)s %(levelname)s [%(filename)s:%(lineno)d]: %(message)s"

# 简单格式
export DDNS_LOG_FORMAT="%(levelname)s: %(message)s"

DDNS_LOG_DATEFMT

类型: 字符串
必需: 否
默认值: %Y-%m-%dT%H:%M:%S
说明: 日期时间格式字符串，参考Python time.strftime()的格式化语法

示例:

bash

# ISO 格式（默认）
export DDNS_LOG_DATEFMT="%Y-%m-%dT%H:%M:%S"

# 简短格式
export DDNS_LOG_DATEFMT="%m-%d %H:%M:%S"

# 标准格式
export DDNS_LOG_DATEFMT="%Y-%m-%d %H:%M:%S"

使用示例

Docker 环境变量示例

bash

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=your_token_here \
  -e DDNS_IPV4=example.com \
  -e DDNS_IPV6='["ipv6.example.com","example.com"]' \
  -e DDNS_INDEX4=["public", 0] \
  -e DDNS_INDEX6=public \
  -e DDNS_TTL=600 \
  -e DDNS_LOG_LEVEL=INFO \
  -e DDNS_LOG_FORMAT="%(asctime)s %(levelname)s [%(module)s]: %(message)s" \
  -e DDNS_LOG_DATEFMT="%Y-%m-%dT%H:%M:%S" \
  --network host \
  newfuture/ddns

复杂配置示例

bash

#!/bin/bash
# 阿里云 DNS 高级配置
export DDNS_DNS="alidns"
export DDNS_ID="your_access_key_id"
export DDNS_TOKEN="your_access_key_secret"

# 多域名配置
export DDNS_IPV4='["ddns.example.com", "home.example.com", "server.example.com"]'
export DDNS_IPV6='["ipv6.example.com"]'

# 多种 IP 获取方式
export DDNS_INDEX4='["public", "regex:192\\.168\\.1\\..*", "cmd:curl -s ipv4.icanhazip.com"]'
export DDNS_INDEX6="public"

# 代理和缓存配置
export DDNS_PROXY='["http://proxy.example.com:8080", "DIRECT"]'
export DDNS_CACHE="/home/user/.ddns_cache"

# 日志配置
export DDNS_LOG_LEVEL="DEBUG"
export DDNS_LOG_FILE="/var/log/ddns.log"
export DDNS_LOG_FORMAT="%(asctime)s %(levelname)s [%(filename)s:%(lineno)d]: %(message)s"
export DDNS_LOG_DATEFMT="%Y-%m-%d %H:%M:%S"

# TTL 设置
export DDNS_TTL="300"

# 运行
ddns

注意事项

数组参数格式: index4, index6, ipv4, ipv6, proxy 等数组参数支持两种格式：
- JSON 数组格式：'["item1", "item2"]'（推荐）
- 逗号分隔格式："item1,item2"
特殊前缀规则: 对于 index4 和 index6 参数：
- 当值包含 regex:、cmd: 或 shell: 前缀时，整个字符串将作为单一配置项，不会按分隔符分割
- 例如："regex:192\\.168\\..*,10\\..*" 会被视为一个完整的正则表达式，而不是两个配置项
- 这是因为这些前缀的值内部可能包含逗号或分号，分割会破坏配置的完整性
配置优先级和字段覆盖关系:
DDNS工具中的配置优先级顺序为：命令行参数 > JSON配置文件 > 环境变量
- 命令行参数: 优先级最高，会覆盖JSON配置文件和环境变量中的相同设置
- JSON配置文件: 优先级中等，会覆盖环境变量中的设置，但会被命令行参数覆盖
- 环境变量: 优先级最低，当命令行参数和JSON配置文件中都没有相应设置时使用
举例说明：
```
# 环境变量设置
export DDNS_TTL="600"

# JSON配置文件内容
{
  "ttl": 300
}

# 命令行参数
ddns --ttl 900
```
1
2
3
4
5
6
7
8
9
10
在上述例子中：
- 最终生效的是命令行参数值：ttl=900
- 如果不提供命令行参数，则使用JSON配置文件值：ttl=300
- 如果JSON配置和命令行参数都不提供，则使用环境变量值：ttl=600
另外，JSON配置文件中明确设置为null的值会覆盖环境变量设置，相当于未设置该值。
大小写兼容: 环境变量名支持大写、小写或混合大小写
安全提醒:
- 请妥善保管 DDNS_TOKEN 等敏感信息
- 在脚本中使用时避免明文存储
- 考虑使用 .env 文件或密钥管理系统
调试建议: 出现问题时，可设置 DDNS_LOG_LEVEL=DEBUG 获取详细日志信息

DDNS 环境变量配置文档 ​

概述 ​

环境变量完整参数列表 ​

基础配置参数 ​

配置文件路径 ​

DDNS_CONFIG ​

DNS 服务商 ​

DDNS_DNS ​

DDNS_ENDPOINT ​

域名配置 ​

IPv4 域名列表 ​

DDNS_IPV4 ​

IP 获取方式 ​

IPv4 获取方式 ​

DDNS_INDEX4 ​

网络配置 ​

代理设置 ​

DDNS_PROXY ​

系统配置 ​

缓存设置 ​

DDNS_CACHE ​

SSL证书验证 ​

DDNS_SSL ​

Docker 定时任务配置 ​

DDNS_CRON ​

日志配置 ​

DDNS_LOG_LEVEL ​

DDNS_LOG_FILE ​

DDNS_LOG_FORMAT ​

DDNS_LOG_DATEFMT ​

使用示例 ​

Docker 环境变量示例 ​

复杂配置示例 ​

注意事项 ​

DDNS 环境变量配置文档

概述

环境变量完整参数列表

基础配置参数

配置文件路径

DDNS_CONFIG

DNS 服务商

DDNS_DNS

DDNS_ENDPOINT

域名配置

IPv4 域名列表

DDNS_IPV4

IP 获取方式

IPv4 获取方式

DDNS_INDEX4

网络配置

代理设置

DDNS_PROXY

系统配置

缓存设置

DDNS_CACHE

SSL证书验证

DDNS_SSL

Docker 定时任务配置

DDNS_CRON

日志配置

DDNS_LOG_LEVEL

DDNS_LOG_FILE

DDNS_LOG_FORMAT

DDNS_LOG_DATEFMT

使用示例

Docker 环境变量示例

复杂配置示例

注意事项