Metadata-Version: 2.4
Name: ddns
Version: 4.2.0b2
Summary: Dynamic DNS client for multiple providers, supporting IPv4 and IPv6.
Author-email: NewFuture <python@newfuture.cc>
License-Expression: MIT
Project-URL: Homepage, https://ddns.newfuture.cc
Project-URL: Documentation, https://ddns.newfuture.cc
Project-URL: Repository, https://github.com/NewFuture/DDNS
Project-URL: Bug Tracker, https://github.com/NewFuture/DDNS/issues
Project-URL: Source, https://github.com/NewFuture/DDNS
Keywords: ddns,ipv6,ipv4,dns,dnspod,alidns,cloudflare
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: System :: Networking
Classifier: Topic :: Software Development
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=2.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mock; python_version < "3.3" and extra == "dev"
Provides-Extra: pytest
Requires-Dist: pytest>=6.0; extra == "pytest"
Requires-Dist: pytest-cov; extra == "pytest"
Requires-Dist: mock; python_version < "3.3" and extra == "pytest"
Dynamic: license-file

# [<img src="docs/public/img/ddns.svg" width="40" height="40" alt="DDNS 标志"/>](https://ddns.newfuture.cc) DDNS

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

<div class="ddns-home-proof" role="list" aria-label="核心兼容性">
  <p role="listitem"><strong>IPv4 + IPv6</strong><br><span>内网、公网与自定义地址来源</span></p>
  <p role="listitem"><strong>15+ DNS 服务商</strong><br><span>国内、国际与自定义回调</span></p>
  <p role="listitem"><strong>4 种运行方式</strong><br><span>Docker、二进制、pip、源码</span></p>
  <p role="listitem"><strong>仅 Python 标准库</strong><br><span>运行时无需安装第三方依赖</span></p>
</div>

<div class="ddns-home-actions">
  <p class="is-primary"><a href="#选择安装方式"><strong>选择安装方式</strong><span>比较 Docker、二进制、pip 与源码</span></a></p>
  <p><a href="docs/config/studio.md"><strong>打开配置工具</strong><span>在浏览器中生成并校验 config.json</span></a></p>
</div>

<details class="ddns-home-status">
<summary>查看构建、版本与发布状态</summary>

[![GitHub](https://img.shields.io/github/license/NewFuture/DDNS?logo=github&style=flat)](https://github.com/NewFuture/DDNS)
[![Build](https://github.com/NewFuture/DDNS/actions/workflows/build.yml/badge.svg?event=push)](https://github.com/NewFuture/DDNS/actions/workflows/build.yml)
[![Publish](https://github.com/NewFuture/DDNS/actions/workflows/publish.yml/badge.svg)](https://github.com/NewFuture/DDNS/actions/workflows/publish.yml)
[![Release](https://img.shields.io/github/v/release/NewFuture/DDNS?logo=github&style=flat)](https://github.com/NewFuture/DDNS/releases/latest)
[![PyPI](https://img.shields.io/pypi/v/ddns.svg?logo=pypi&style=flat)](https://pypi.org/project/ddns/)
[![Python Version](https://img.shields.io/pypi/pyversions/ddns.svg?logo=python&style=flat)](https://pypi.org/project/ddns/)
[![Docker](https://img.shields.io/docker/v/newfuture/ddns?logo=docker&sort=semver&style=flat)](https://hub.docker.com/r/newfuture/ddns)
[![Docker image size](https://img.shields.io/docker/image-size/newfuture/ddns/latest?logo=docker&style=flat)](https://hub.docker.com/r/newfuture/ddns)

</details>

## 三步完成首次更新

<div class="ddns-home-steps" role="list" aria-label="首次更新流程">
  <p role="listitem"><strong><span>1</span> 安装</strong><br>选择适合当前设备的运行方式。</p>
  <p role="listitem"><strong><span>2</span> 配置</strong><br>选择服务商，填写凭据与待更新域名。</p>
  <p role="listitem"><strong><span>3</span> 运行</strong><br>验证结果，再由常驻 Web 或系统任务持续更新。</p>
</div>

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

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

确认输出符合预期后，再在[配置工具](docs/config/studio.md)中选择实际服务商并导出配置。

## 选择安装方式

- **[Docker（推荐）](docs/docker.md)**：适合 NAS、服务器与容器平台，支持多架构，镜像默认每 5 分钟运行一次更新任务。
- **[二进制文件](https://github.com/NewFuture/DDNS/releases/latest)**：适合不希望安装 Python 的 Windows、Linux 与 macOS 用户，单文件即可运行。
- **[pip](https://pypi.org/project/ddns/)**：适合已有 Python 环境的设备，运行 `pip install ddns` 即可安装。
- **[源码运行](https://github.com/NewFuture/DDNS/archive/master.zip)**：适合需要审阅或定制代码的用户，解压后运行 `python -m ddns`。

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

```bash
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 任务计划程序。
- 支持日志级别、日志文件、格式与时间格式配置。

## 配置与凭据

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

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

1. **[命令行参数](docs/config/cli.md)**：`ddns --key=value`
2. **[JSON 配置文件](docs/config/json.md)**：适合多域名、多服务商和远程配置
3. **[环境变量](docs/config/env.md)**：适合 Docker 与自动化部署

少数控制项仅支持命令行，详见[命令行参数文档](docs/config/cli.md)。

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

## DNS 服务商

- **国内与云平台**：[阿里 DNS](docs/providers/alidns.md)、[阿里云 ESA](docs/providers/aliesa.md)、[DNSPod](docs/providers/dnspod.md)、[腾讯云 DNS](docs/providers/tencentcloud.md)、[腾讯云 EdgeOne](docs/providers/edgeone.md)、[EdgeOne DNS](docs/providers/edgeone_dns.md)、[华为云 DNS](docs/providers/huaweidns.md)、[DNS.COM / 51DNS](docs/providers/51dns.md)、[西部数码](docs/providers/west.md)
- **国际服务商**：[Cloudflare](docs/providers/cloudflare.md)、[ClouDNS](docs/providers/cloudns.md)、[DNSPod 国际版](docs/providers/dnspod_com.md)、[HE.net](docs/providers/he.md)、[NameSilo](docs/providers/namesilo.md)、[No-IP](docs/providers/noip.md)
- **集成与验证**：[回调 API](docs/providers/callback.md)、[Debug](docs/providers/debug.md)

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

## 运行与自动化

使用配置文件运行：

```bash
ddns -c config.json
```

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

```bash
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 客户端查询缓存状态，或在人工确认后触发一次完整同步：

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

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

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

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

任务可通过 `ddns task --status` 查看，并使用 `--enable`、`--disable` 或 `--uninstall` 管理。不要让系统任务与 Web 内置调度同时运行。参数与平台差异请查看[命令行文档](docs/config/cli.md#task-management-定时任务管理)。

路由器或光猫仅支持传统 DDNS 协议时，可以使用 **[edge-ddns-proxy](https://github.com/NewFuture/edge-ddns-proxy)** 转换到现代 DNS 服务商 API。

## 获取帮助

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

开发与扩展请查看 [Provider 开发指南](docs/dev/provider.md)和[配置系统设计](docs/dev/config.md)。

## 项目

<a href="https://github.com/NewFuture/DDNS/graphs/contributors"><img src="https://contrib.rocks/image?repo=NewFuture/DDNS" alt="DDNS 项目贡献者"/></a>

DDNS 采用 [MIT License](https://github.com/NewFuture/DDNS/blob/master/LICENSE) 发布。源码、版本与变更记录均可在 [GitHub 仓库](https://github.com/NewFuture/DDNS)查看。
