This release is a pre-release and may not be stable for production use.
DDNS
自动将 DNS 记录同步到当前 IPv4/IPv6 地址。一个无第三方运行依赖、可跨平台部署的动态 DNS 客户端。
IPv4 + IPv6
内网、公网与自定义地址来源
15+ DNS 服务商
国内、国际与自定义回调
4 种运行方式
Docker、二进制、pip、源码
仅 Python 标准库
运行时无需安装第三方依赖
查看构建、版本与发布状态
三步完成首次更新
1 安装
选择适合当前设备的运行方式。
2 配置
选择服务商，填写凭据与待更新域名。
3 运行
验证结果，再由常驻 Web 或系统任务持续更新。
安装后可以先使用不会修改真实 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 服务商校验结构，再切换到真实服务商。
多数运行配置项都可通过以下方式提供，优先级为：
少数控制项仅支持命令行，详见命令行参数文档。
凭据名称会因服务商而异，例如 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，此时 ddns -c config.json 会自动启动 Web。命令行值优先于配置，原有 ddns web 命令继续兼容。页面保存的新间隔会写回配置；暂停和恢复只影响当前进程。检测到已启用的系统任务时，Web 会阻止重复调度。生产环境应使用 systemd、launchd、Windows 服务或 Docker 负责 Web 进程保活。
让 GitHub Copilot 等本机 MCP 客户端查询缓存状态，或在人工确认后触发一次完整同步：
ddns mcp -c /etc/ddns/config.json
该 stdio 服务只使用 Python 标准库，不监听网络，也不会向模型暴露配置凭据；支持 MCP 2026-07-28，并兼容 GitHub Copilot CLI 使用的 2025-11-25。具体客户端配置、工具与限制见 MCP 命令文档。
不需要 Web 控制台时，可以安装每 5 分钟执行一次的系统定时任务：
ddns task --install 5 -c /etc/ddns/config.json
任务可通过 ddns task --status 查看，并使用 --enable、--disable 或 --uninstall 管理。不要让系统任务与 Web 内置调度同时运行。参数与平台差异请查看命令行文档。
路由器或光猫仅支持传统 DDNS 协议时，可以使用 edge-ddns-proxy 转换到现代 DNS 服务商 API。
获取帮助
开发与扩展请查看 Provider 开发指南和配置系统设计。
项目
DDNS 采用 MIT License 发布。源码、版本与变更记录均可在 GitHub 仓库查看。
2 maintainers
Metadata
2 maintainers
Release files for ddns 4.2.0b1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ddns-4.2.0b1.tar.gz | 253.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ddns-4.2.0b1-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details |
Total release size: 393.9 kB
Release files / ddns-4.2.0b1.tar.gz
| Download URL | ddns-4.2.0b1.tar.gz |
|---|---|
| Size | 253.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7164eac406672272951dc268e47612f8a2fed5eb690a1414801c197933bba02c
|
|
BLAKE2b-256 checksum How to use checksums |
0ac7bb16b63db4839a9010b51959e1b3064f0b0450a7b357709674505ba07596
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / ddns-4.2.0b1-py2.py3-none-any.whl
| Download URL | ddns-4.2.0b1-py2.py3-none-any.whl |
|---|---|
| Size | 140.7 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
1b2d1a410f42f7ccfd6b11073e0c88318d458e05f1cc8fd31a3f282fc45fe585
|
|
BLAKE2b-256 checksum How to use checksums |
8c7223763d0fad8580005af5e31c01986d14190578a556fb9cfb0f04fa89a523
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency log
