DDNS 命令行参数完全指南：配置优先级、IP 探测与定时任务（task/web）实战详解

• 网络
• CLI

DDNS 是一款自动将域名解析更新到本机公网 IP 的轻量级 Python 工具，支持 DNSPod、阿里云 DNS、Cloudflare、华为云、DNS.COM 等主流解析服务商。命令行参数是 DDNS 配置体系中优先级最高的一环：它可以覆盖 JSON 配置文件与环境变量中的所有同名设置，让你无需编辑任何文件即可完成一次完整的动态解析更新。本文基于仓库内的官方命令行参考文档与对应源码实现，完整讲解每个参数的类型与用法、列表参数的多种传值方式、IP 探测规则、task定时任务子命令与--interval内置 Web 控制台，帮助你既会用命令行，也理解参数在底层是如何被解析、合并和生效的。

基本用法

DDNS 提供两种等价入口：安装后的ddns命令，或直接通过 Python 源码模块运行。使用-h即可查看完整参数列表：

# ddns [options] ddns -h

或者使用 Python 源码方式：

# python run.py [options] python -m ddns -h

其中 run.py 是仓库根目录下的运行入口，最终会调用 ddns/main.py 中的main()函数，经由 ddns/config/init.py 的load_configs()完成“命令行 → 配置文件 → 环境变量”三层配置的加载与合并。

列表参数的传值方式

对支持多值的列表型参数（如--ipv4、--ipv6、--index4、--index6、--proxy等），可以使用以下两种方式指定多个值。

方式一：重复参数名（推荐）

ddns --ipv4 example.com --ipv4 www.example.com --ipv4 api.example.com ddns --index4 public --index4 0 --index4 "regex:192\\.168\\..*" ddns --proxy SYSTEM --proxy DIRECT

方式二：空格分隔

ddns --ipv4 example.com www.example.com api.example.com ddns --index4 public 0 "regex:192\\.168\\..*" ddns --proxy SYSTEM DIRECT

值中包含空格

参数值若含有空格，请使用引号：

ddns --line "China Telecom" "China Unicom" "China Mobile" ddns --index4 "url:http://ip.example.com/api?type=ipv4" public

不支持的用法

# ❌ 不支持逗号分隔 ddns --ipv4 "example.com,www.example.com" ddns --ipv4=example.com,www.example.com

源码佐证：在 ddns/config/cli.py 中，列表参数使用自定义的ExtendAction注册，它把每次出现的值依次追加（extend）进同一个列表，因此重复参数名和空格分隔两种写法天然等价。而在 ddns/config/config.py 的split_array_string()中可以看到：只有url:、regex:、cmd:、shell:这类特殊前缀的值才允许在 JSON/环境变量字符串里用逗号分隔——命令行入口并不做逗号拆分，这就是文档明确标注“逗号分隔不受支持”的原因。

完整参数表

--cache-max-age控制的是整个缓存文件的过期时间，单位秒，默认 259200（72 小时）。下次调用时，当now - mtime >= cache_max_age或 mtime 位于未来（时钟异常）时，缓存被视为过期；设为0则每次调用都清空现有缓存。注意它与 DNS TTL 是两回事；由于扁平 JSON 缓存文件只有一个 mtime，任何一次缓存写入都会刷新所有条目的年龄。缓存格式保持不变、不做迁移，原有共享缓存的限制依旧存在。

源码佐证：该逻辑实现于 ddns/cache.py 的Cache.new()：expired = cache.time > now or now - cache.time >= cache_max_age，过期则cache.clear()；--cache-max-age的取值校验由 ddns/config/cli.py 的non_negative_int()保证为非负整数。另外，开启--debug时，ddns/config/cli.py 会强制把日志级别设为 DEBUG，并在缓存未显式指定时自动禁用缓存（args.cache = False）——这就是“调试模式只对命令行参数生效，配置文件中的 debug 设置会被忽略”的底层原因。

IP 探测方式（--index4/--index6）

示例：

# 使用公网 IP 探测 ddns --dns cloudflare --index4 public # 多种探测方式叠加（自动回退） ddns --dns cloudflare --index4 public --index4 "regex:192\\.168\\..*" # 自定义 URL 探测 ddns --dns cloudflare --index4 "url:http://api.ipify.org" # 使用命令输出获取 IP ddns --dns cloudflare --index4 "cmd:hostname -I | awk '{print $1}'"

回退机制的源码级解释：在 ddns/main.py 的get_ip()中，规则按给定顺序逐条执行，前一条失败（抛异常或返回空）就continue尝试下一条，直到拿到可用地址；单条规则的分发逻辑在_get_ip_from_rule()中完成，数字规则走本机网卡、url:走public_v4/v6()、regex:走regex_v4/v6()、cmd:/shell:走subprocess.check_output()。因此“多条 index 规则 = 一条容错探测链”是该参数的核心设计。相关单元测试见 tests/test_ip.py 与 tests/test_main.py。

使用示例

配置文件用法

# 使用默认配置文件 ddns # 使用指定配置文件 ddns -c /path/to/config.json # 使用多个配置文件 ddns -c cloudflare.json -c dnspod.json # 使用远程配置文件 ddns -c https://ddns.newfuture.cc/tests/config/debug.json # 使用远程配置文件并经过代理 ddns -c https://config.example.com/ddns.json --proxy http://proxy:8080 # 生成新的配置文件 ddns --new-config config.json

多个配置文件时，ddns/config/init.py 的load_configs()会为每份 JSON 各构建一个Config对象，ddns/main.py 的main()再逐个执行并汇总成功/失败状态，全部成功才以退出码 0 结束。

命令行直接配置

# 最简配置 - DNSPod ddns --dns dnspod --id 12345 --token mytokenkey --ipv4 example.com # Cloudflare + API token ddns --dns cloudflare --token your_api_token --ipv4 example.com # 开启调试模式 ddns --dns cloudflare --token API_TOKEN --ipv4 example.com --debug # 多个域名（空格分隔） ddns --dns cloudflare --token API_TOKEN \ --ipv4 example.com www.example.com --ipv6 example.com # 多个域名（重复参数） ddns --dns cloudflare --token API_TOKEN \ --ipv4 example.com --ipv4 www.example.com --ipv6 example.com

各服务商示例

# 阿里云 DNS ddns --dns alidns --id your_access_key --token your_secret_key --ipv4 example.com # 华为云 DNS ddns --dns huaweidns --id your_access_key --token your_secret_key --ipv4 example.com # No-IP ddns --dns noip --id your_username --token your_password --ipv4 example.com # 自定义回调（GET 请求，__DOMAIN__/__IP__ 为占位符） ddns --dns callback --id "https://api.example.com/ddns?domain=__DOMAIN__&ip=__IP__" --ipv4 example.com

高级配置

# 完整配置：代理 + TTL + 自定义 IP 探测（空格分隔写法） ddns --dns cloudflare --token API_TOKEN \ --ipv4 example.com www.example.com \ --index4 public "regex:2001:.*" \ --ttl 300 --proxy http://127.0.0.1:1080 DIRECT \ --cache=/var/cache/ddns.cache \ --log_level=INFO --log_file=/var/log/ddns.log # 完整配置（重复参数写法） ddns --dns cloudflare --token API_TOKEN \ --ipv4 example.com --ipv4 www.example.com \ --index4 public --index6 "regex:2001:.*" \ --ttl 300 --proxy http://127.0.0.1:1080 --proxy DIRECT \ --cache=/var/cache/ddns.cache \ --log_level=INFO --log_file=/var/log/ddns.log # 运营商线路配置（面向国内服务商） ddns --dns dnspod --id 12345 --token mytokenkey \ --ipv4 telecom.example.com --line 电信 # 使用远程配置文件 ddns -c https://ddns.newfuture.cc/tests/config/debug.json --debug # 远程配置 + 代理 ddns -c https://config.example.com/ddns.json \ --proxy http://proxy.company.com:8080 # 关闭缓存与 SSL 验证 ddns --dns alidns --id ACCESS_KEY --token SECRET_KEY \ --ipv4 example.com --no-cache --no-ssl

DNS 服务商取值

DDNS 支持的 DNS 服务商（--dns可选值，取自 ddns/config/cli.py 中的choices定义，实际比英文文档列出项更多）：

• 51dns（dnscom 的别名）：DNS.COM 服务
• alidns：阿里云 DNS
• aliesa：阿里云 ESA（边缘安全加速）
• callback：自定义回调 / Webhook
• cloudflare：Cloudflare DNS
• cloudns：Cloudns.net
• debug：调试服务商（只打印 IP，不真正更新解析）
• dnscom：DNS.COM（与 51dns 相同）
• dnspod：DNSPod（国内）
• dnspod_com：DNSPod 国际站
• edgeone：腾讯云 EdgeOne
• edgeone_dns：腾讯云 EdgeOne DNS
• he：Hurricane Electric DNS
• huaweidns：华为云 DNS
• namesilo：NameSilo
• noip：No-IP 动态 DNS
• tencentcloud：腾讯云 DNS
• west：西部数码

每家服务商的字段差异（如--id/--token具体含义）可查阅 各服务商配置文档。

Web 控制台与内置定时调度（--interval）

在顶层命令中提供--interval会自动进入常驻控制台模式，此时显式写web子命令是可选的。Web 进程同时负责周期性 DNS 同步，并在同一监听端口上暴露 MCP2026-07-28Streamable HTTP 端点（路径/mcp）。传统的ddns web写法保持兼容。

ddns -c /etc/ddns/config.json --interval 5 --open

监听配置的优先级为：命令行 > 根 JSON 中的http>DDNS_HTTP_*环境变量 > 默认127.0.0.1:9876。这一优先级在 ddns/http_config.py 的resolve_http_settings()中按“env → JSONhttp→ CLI”逐级覆盖实现。当监听在回环地址且未设置 token 时，Web API（含完整配置与服务商凭证）以及/mcp均为无鉴权访问；一旦监听非回环/通配地址，则强制要求一个非空、无空格的可见 ASCII token（见 ddns/http_config.py 中enforce_bind_auth的校验）。带 token 后，页面仍可继续使用X-DDNS-Token请求头，同时接受Authorization: Bearer；MCP 客户端使用 Bearer 形式（令牌校验采用恒定时间比较，见 ddns/http_config.py）。

DDNS 本身不提供 TLS。若监听局域网地址，请将其置于可信的 HTTPS 反向代理之后，并保证代理保留Authorization、Host、Origin头。浏览器经由 TLS 终结代理访问时，必须把公网 HTTPS 源精确写入http.origins或--http-origin，即使页面看起来是同源的；原生 MCP 客户端可以省略Origin。

--interval是显式的 Web 模式信号；配置文件顶层的 JSONinterval字段同样会让ddns -c FILE自动进入 Web 模式，优先级为命令行--interval> JSONinterval> 默认 5 分钟。该“参数展开”逻辑位于 ddns/config/cli.py 的_expand_web_interval_shorthand()，它检测到--interval后会自动向sys.argv插入web子命令。取值校验由interval_minutes()完成（1～1440 的整数）。在控制台保存间隔会立即生效，但监听地址与鉴权变更需要重启进程。

当检测到已启用的ddns task系统定时任务时，Web 内置调度会停止并报告冲突（该检查见 ddns/web/service.py 的_scheduled_sync_guard()），需要你在控制台显式接管，或先执行ddns task --disable。请勿让多个 Web、MCP 或系统定时任务进程并发更新同一份配置。MCP 客户端配置、stdio/HTTP 用法与工具清单详见 MCP 服务文档。

定时任务管理（task 子命令）

面向无头（headless）部署，DDNS 通过task子命令提供系统级定时任务，会自动检测系统并选择最合适的调度器。

task 子命令参数

重要说明：

• --install命令自动覆盖已有定时任务，无需先检查或卸载旧任务；
• 这一设计简化了任务管理流程，避免了手动卸载步骤；
• task子命令支持全部主 DDNS 配置参数（如--dns、--id、--token、--ipv4、--ipv6等），它们会被保存并传递给定时任务执行；
• 仅限命令行使用的参数：--debug、--new-config、--no-cache、--no-ssl、--help、--version。

源码佐证：子命令处理逻辑在 ddns/config/cli.py 的_handle_task_command()：它会先把status/install/uninstall/enable/disable/command/scheduler/func等管理键剔除，剩余参数（即“全部 DDNS 配置参数”）原样交给调度器；而命令行的拼装由 ddns/scheduler/_base.py 的_build_ddns_command()完成——列表值会展开为逐个--key value，字符串中含空格的参数会被自动加引号。这也解释了为什么“覆盖式重装”成立：每次 install 都是用当前参数重新生成整套任务定义。

task 子命令用法

# 查看帮助 ddns task --help # 检查任务状态 ddns task --status # 安装定时任务（默认 5 分钟间隔） ddns task --install # 指定间隔（分钟）安装 ddns task --install 10 ddns task -i 15 # 安装时指定调度器 ddns task --install 5 --scheduler systemd ddns task --install 10 --scheduler cron ddns task --install 15 --scheduler auto # 启用 / 禁用已安装任务 ddns task --enable ddns task --disable # 卸载已安装任务 ddns task --uninstall

支持的调度器与自动检测

DDNS 会自动检测系统并选择最合适的调度器（检测逻辑见 ddns/scheduler/init.py 的get_scheduler()）：

• Linux：systemd（优先）或 cron——通过读取/proc/1/comm或尝试systemctl --version判断 systemd 是否可用；
• macOS：launchd（优先）或 cron——以/Library/LaunchDaemons等目录是否存在为判断依据；
• Windows：schtasks（任务计划程序）。

安装后的产物：以 systemd 为例（ddns/scheduler/systemd.py），--install 5会写入/etc/systemd/system/ddns.service（Type=oneshot，ExecStart为拼装好的 ddns 命令行）与/etc/systemd/system/ddns.timer（OnUnitActiveSec=5m），随后执行daemon-reload、enable、start；权限不足时会提示改用sudo或--scheduler=cron。

权限要求

不同调度器需要的权限不同：

• systemd：需要 root 权限（sudo）
• cron：普通用户权限
• launchd：普通用户权限
• schtasks：需要管理员权限

任务管理示例

# 查看当前状态 ddns task --status # 快速安装（自动覆盖已有任务） ddns task --install # 使用指定配置文件安装 10 分钟间隔任务 ddns task --install 10 -c /etc/ddns/config.json # 直接用 DDNS 参数安装（无需配置文件） ddns task --install 5 --dns cloudflare --id user@example.com --token API_TOKEN --ipv4 example.com # 带高级配置参数的任务安装 ddns task --install 10 --dns dnspod --id 12345 --token secret \ --ipv4 example.com --ttl 600 --proxy http://proxy:8080 \ --log_file /var/log/ddns.log --log_level INFO # 指定调度器安装 ddns task --install 5 --scheduler systemd --dns cloudflare --id user@example.com --token API_TOKEN --ipv4 example.com # 强制使用 cron（适用于无 systemd 的 Linux） ddns task --install 10 --scheduler cron -c config.json # macOS 上强制使用 launchd ddns task --install 15 --scheduler launchd --dns dnspod --id 12345 --token secret --ipv4 example.com # Windows 上使用 schtasks ddns task --install 5 --scheduler schtasks --dns cloudflare --id user@example.com --token API_TOKEN --ipv4 example.com # Linux 下用 sudo 安装 systemd timer sudo ddns task --install 5 -c /etc/ddns/config.json # 更新任务配置（自动覆盖） ddns task --install 15 --dns cloudflare --id user@example.com --token NEW_TOKEN --ipv4 example.com # 启用 / 禁用 / 卸载 ddns task --enable ddns task --disable # 不删除任务，只是停止执行 ddns task --uninstall

与配置文件组合使用

task子命令与配置文件完全兼容：

# 使用本地配置文件 ddns task --install 10 -c config.json # 使用多个配置文件 ddns task --install 5 -c cloudflare.json -c dnspod.json # 使用远程配置文件 ddns task --install 15 -c https://config.example.com/ddns.json # 配置文件 + 命令行参数覆盖 ddns task --install 10 -c config.json --debug --ttl 300 # 指定调度器 + 配置文件 ddns task --install 5 --scheduler cron -c config.json # 远程配置 + 指定调度器 ddns task --install 10 --scheduler systemd -c https://config.example.com/ddns.json

调度器选择示例

# 自动选择（推荐，让系统选最优调度器） ddns task --install 5 --scheduler auto # Linux 系统选择 ddns task --install 5 --scheduler systemd # 首选，功能完整 ddns task --install 5 --scheduler cron # 备选，兼容性好 # macOS 系统选择 ddns task --install 5 --scheduler launchd # 首选，系统原生 ddns task --install 5 --scheduler cron # 备选，兼容性好 # Windows 系统选择 ddns task --install 5 --scheduler schtasks # 唯一选项，Windows 任务计划程序

排查安装问题

# 开启调试模式查看详细安装过程 ddns task --install 5 --debug # 查看任务状态与配置 ddns task --status --debug # 查看指定调度器的状态 ddns task --status --scheduler systemd --debug

相关行为在 tests/test_scheduler_base.py、tests/test_scheduler_systemd.py、tests/test_scheduler_cron.py、tests/test_scheduler_launchd.py、tests/test_scheduler_schtasks.py 以及 tests/test_config_cli_task.py 中有对应的测试覆盖；端到端脚本见 tests/scripts/ 下的test-task-systemd.sh、test-task-cron.sh、test-task-macos.sh、test-task-windows.bat。

配置优先级与合并机制

DDNS 按以下顺序（从高到低）合并配置：

1. 命令行参数（最高优先级）
2. JSON 配置文件
3. 环境变量（最低优先级）

也就是说，命令行参数会覆盖配置文件或环境变量中的任意同名设置。从源码结构看，这一优先级在 ddns/config/config.py 的Config._get()中逐 key 实现：先查 CLI，为空再查 JSON，最后落到环境变量；而 ddns/config/init.py 的load_configs()则按“先解析 CLI → 再读环境变量 → 最后加载一个或多个 JSON”的顺序组织整个流程。

此外还有两个容易忽略的细节，均有源码依据：

• 额外字段（extra）：命令行支持--extra.xxx value形式的任意扩展参数，未知参数会被警告；ddns/config/config.py 的_collect_extra()按 ENV → JSON → CLI 顺序收集extra_*前缀字段，最终合并进extra并透传给各服务商的set_record()；
• 环境变量：以DDNS_为前缀的环境变量（如DDNS_DNS、DDNS_TOKEN）由 ddns/config/env.py 的load_config()解析，DDNS_EXTRA_XXX会转换为extra_xxx，PYTHONHTTPSVERIFY还会映射到ssl设置。

重要注意事项

1. 命令行参数优先级：命令行参数优先级最高，将覆盖配置文件与环境变量中的设置。

2. 引号使用：参数值包含空格或特殊字符时请使用引号，例如--log_format="%(asctime)s: %(message)s"。

3. 列表参数配置：多值参数（--ipv4、--ipv6、--index4、--index6、--proxy等）支持两种写法：

   # ✅ 方式一：重复参数名（推荐） ddns --ipv4 example.com --ipv4 sub.example.com --ipv4 api.example.com ddns --index4 public --index4 0 --index4 "regex:192\\.168\\..*" ddns --proxy http://127.0.0.1:1080 --proxy DIRECT # ✅ 方式二：空格分隔 ddns --ipv4 example.com sub.example.com api.example.com ddns --index4 public 0 "regex:192\\.168\\..*" ddns --proxy http://127.0.0.1:1080 DIRECT # ✅ 值含空格时使用引号 ddns --line "China Telecom" "China Unicom" # ❌ 错误用法 - 不受支持 ddns --ipv4 "example.com,sub.example.com" # 不支持逗号分隔 ddns --ipv4=example.com,sub.example.com # 等号 + 逗号不支持

4. 调试模式：--debug仅作为命令行参数生效，配置文件中的 debug 设置会被忽略。

5. 正则表达式：使用正则时需正确转义特殊字符，建议加引号，例如--index4 "regex:192\\.168\\..*"。

延伸阅读

• 环境变量配置
• JSON 配置文件
• MCP 服务
• Docker 使用
• 各服务商配置
• 参数解析与合并的单元测试：tests/test_config_cli.py、tests/test_config_config.py、tests/test_config_env.py、tests/test_config_cli_web.py

• 网络
• CLI