DDNS

DDNS

自动将 DNS 记录同步到当前 IPv4/IPv6 地址。一个无第三方运行依赖、可跨平台部署的动态 DNS 客户端。

查看构建、版本与发布状态

三步完成首次更新

安装后可以先使用不会修改真实 DNS 记录的 Debug 服务商验证运行链路：

ddns --dns=debug --ipv4=home.example.com --debug

确认输出符合预期后，再在配置工具中选择实际服务商并导出配置。

选择安装方式

• Docker（推荐）：适合 NAS、服务器与容器平台，支持多架构，镜像默认每 5 分钟运行一次更新任务。
• 二进制文件：适合不希望安装 Python 的 Windows、Linux 与 macOS 用户，单文件即可运行。
• pip：适合已有 Python 环境的设备，运行 pip install ddns 即可安装。
• 源码运行：适合需要审阅或定制代码的用户，解压后运行 python -m ddns。

Linux 与 macOS 也可以使用一键安装脚本获取匹配当前平台的二进制：

curl -fsSL https://ddns.newfuture.cc/install.sh | sh

为什么适合长期运行

DNS 更新能力

• 同时管理多个域名、多个服务商和多份配置文件。
• 支持 IPv4/IPv6、内网地址、公网地址、URL、正则表达式与自定义命令取值。
• 自动查找 DNS 记录；多数服务商可自动创建不存在的记录（HE.net 与 No-IP 除外）；服务商支持时可配置 TTL 与解析线路。
• 本地缓存减少无变化时的 DNS API 请求。

部署与维护

• 仅使用 Python 标准库，兼容 Python 2.7 与 Python 3.x。
• 支持 HTTP 代理、多代理回退、SSL 验证策略与自定义 CA。
• Web 控制台内置常驻调度；无 Web 场景仍可使用 systemd/cron、launchd 或 Windows 任务计划程序。
• 支持日志级别、日志文件、格式与时间格式配置。

配置与凭据

配置生成与校验工具会在浏览器中处理输入，不会调用 DNS 服务商 API。可以先用 Debug 服务商校验结构，再切换到真实服务商。

多数运行配置项都可通过以下方式提供，优先级为：

1. 命令行参数：ddns --key=value
2. JSON 配置文件：适合多域名、多服务商和远程配置
3. 环境变量：适合 Docker 与自动化部署

少数控制项仅支持命令行，详见命令行参数文档。

凭据名称会因服务商而异，例如 API Token、Access Key 或 Secret。请从对应的服务商文档获取最小权限配置，并在日志、Issue 或配置示例中删除真实凭据。

DNS 服务商

• 国内与云平台：阿里 DNS、阿里云 ESA、DNSPod、腾讯云 DNS、腾讯云 EdgeOne、EdgeOne DNS、华为云 DNS、DNS.COM / 51DNS、西部数码
• 国际服务商：Cloudflare、ClouDNS、DNSPod 国际版、HE.net、NameSilo、No-IP
• 集成与验证：回调 API、Debug

标有相关说明的云服务商使用 HMAC-SHA256 签名认证。完整能力、凭据格式与限制以所有服务商文档为准。

运行与自动化

使用配置文件运行：

ddns -c config.json

长期运行本机控制台，并由同一进程每 5 分钟自动同步：

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

提供 --interval 会自动进入 Web 模式，无需额外写 web；也可在本地 JSON 顶层配置 "interval": 5。Web 同时在 /mcp 提供 MCP 2026-07-28 Streamable HTTP。默认回环监听未配置 token 时，Web API 与 /mcp 均免认证；非回环或通配监听必须配置共享 HTTP token，并应由 HTTPS 反向代理保护。页面保存的新间隔会写回配置；暂停和恢复只影响当前进程。

让 GitHub Copilot 等本机 MCP 客户端查询缓存状态，或在人工确认后触发一次完整同步：

ddns mcp -c /etc/ddns/config.json

该 stdio 服务只使用 Python 标准库，不监听网络，也不会向模型暴露配置凭据；支持 MCP 2026-07-28，并兼容 GitHub Copilot CLI 使用的 2025-11-25。具体客户端配置、工具与限制见 MCP 服务文档。

不能启动本机进程的 MCP 客户端也可连接独立 HTTP endpoint：

ddns mcp -c /etc/ddns/config.json --transport http

不需要 Web 控制台时，可以安装每 5 分钟执行一次的系统定时任务：

ddns task --install 5 -c /etc/ddns/config.json

任务可通过 ddns task --status 查看，并使用 --enable、--disable 或 --uninstall 管理。不要让系统任务与 Web 内置调度同时运行。参数与平台差异请查看命令行文档。

路由器或光猫仅支持传统 DDNS 协议时，可以使用 edge-ddns-proxy 转换到现代 DNS 服务商 API。

获取帮助

1. 使用 --debug 复现问题，并确认是否来自网络、权限或系统环境。
2. 在 Issues 中搜索相同错误。
3. 仍无法解决时，提交 Issue，附上运行版本、安装方式、系统环境和已删除凭据的日志与配置。

开发与扩展请查看 Provider 开发指南和配置系统设计。

项目

DDNS 采用 MIT License 发布。源码、版本与变更记录均可在 GitHub 仓库查看。