DDNS：自动同步域名解析到本机 IP

项目简介

DDNS 是一个自动将 DNS 记录同步到当前 IPv4/IPv6 地址的动态 DNS 客户端。它无第三方运行时依赖，只使用 Python 标准库，可以跨平台部署到 NAS、服务器、路由器旁的小主机或普通电脑上，适合需要长期维护动态公网 IP 解析的个人与运维用户。

核心兼容性：

• IPv4 + IPv6：支持内网、公网与自定义地址来源
• 15+ DNS 服务商：覆盖国内、国际与自定义回调
• 4 种运行方式：Docker、二进制、pip、源码
• 仅 Python 标准库：运行时无需安装第三方依赖

主要功能

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

安装与使用

三步完成首次更新

1. 安装：选择适合当前设备的运行方式。
2. 配置：选择服务商，填写凭据与待更新域名。
3. 运行：验证结果，再由常驻 Web 或系统任务持续更新。

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

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

安装方式

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

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

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

pip install ddns

运行

使用配置文件运行：

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。页面保存的新间隔会写回配置；暂停和恢复只影响当前进程。

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

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

该 stdio 服务只使用 Python 标准库，不监听网络，也不会向模型暴露配置凭据。不能启动本机进程的 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 管理。

配置优先级

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

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

少数控制项仅支持命令行。

注意事项

• 凭据名称会因服务商而异，例如 API Token、Access Key 或 Secret。请从对应的服务商文档获取最小权限配置，并在日志、Issue 或配置示例中删除真实凭据。
• Web 默认回环监听且未配置 token 时，Web API 与 /mcp 均免认证；非回环或通配监听必须配置共享 HTTP token，并应由 HTTPS 反向代理保护。
• 不要让系统定时任务（ddns task）与 Web 内置调度同时运行。
• 路由器或光猫仅支持传统 DDNS 协议时，可以使用 edge-ddns-proxy 转换到现代 DNS 服务商 API。
• 遇到问题时先用 --debug 复现，确认是否来自网络、权限或系统环境，并在提交 Issue 时附上运行版本、安装方式、系统环境和已删除凭据的日志与配置。

---

本作品整理自 GitHub 开源项目 NewFuture/DDNS，原作者 @NewFuture，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。