dns-manager

一个专注于 DDNS 的 DNS 记录同步工具。它从公网接口或本地网络设备获取动态 IP， 并通过 Lexicon 将对应的 A/AAAA 记录同步到 DNS 提供商。

安装

使用 pip/pipx/uv 安装

在此之前请确保使用 Python 3.12 或更高版本，并安装了 pip。

pip install dns-manager

如果想要尝试 Nightly 版本，可使用：

pip install git+https://github.com/zrr1999/dns-manager@main

在此之前请确保安装了 pipx/uv。

pipx install dns-manager
uv tool install dns-manager

pipx/uv 会无感地为 dns-manager 创建一个虚拟环境，与其余环境隔离开，避免污染其他环境， 因此相对于 pip，pipx/uv 是更推荐的安装方式。

使用说明

DDNS 配置

默认配置路径为 ~/.config/dns-manager/config.toml。例如：

[home]
domain = "mydomain.com"
setter_name = "cloudflare"
records = [
    [
      "home",
      "public:https://api.ipify.org"
    ]
]

也支持同等结构的 .json 配置。未指定 records_files 时，会自动尝试加载与主配置同目录、同后缀的 records.toml / records.json（文件不存在则跳过）。records 文件与主配置共用同一字段形状：

records = [
    ["office", "public:https://api64.ipify.org"]
]
ignore = ["mail"]

ignore 里的主机名不会被同步，远端同名记录也不会被当成 unmanaged 告警。

public: 后面是返回单个 IPv4 或 IPv6 地址的 HTTP 接口。dns-manager 会在每轮同步时 重新获取地址，并根据响应选择 A 或 AAAA 记录。单个来源应保持稳定的地址族；双栈场景应分别配置 固定返回 IPv4 与 IPv6 的来源。

也可以使用：

• snmp:<interface>：从网关接口读取地址
• default:v4 / default:v6：取本机默认出网地址
• local:v4 / local:v6：取本机主机名对应地址；可用 local:v4:1 选择第 N 个地址

Lexicon 从环境变量读取提供商凭据。例如 Cloudflare 使用：

export LEXICON_CLOUDFLARE_AUTH_TOKEN=your-token

先执行一次同步以检查配置与凭据：

dnsm update
# 或使用其他配置路径
dnsm update ./examples/simple.toml

Daemon 模式

daemon 会在前台立即同步一次，随后按固定间隔继续同步：

dnsm daemon --interval 300
# 或使用其他配置路径
dnsm daemon ./examples/simple.toml --interval 300

daemon 不会 fork、脱离终端或写入 PID 文件，适合直接交给 systemd、launchd、容器或其他 进程管理器托管。收到 SIGINT/SIGTERM 后，它会在当前同步结束后退出；再次发送信号可强制立即退出。 配置在启动时读取，修改后需重启进程。

支持的 DNS 提供商

本项目实现了一个 lexicon 的适配 Setter， 支持情况与其一致。

Cron 方式

如果不需要常驻进程，也可以用 cron 调用一次性同步：

@hourly dnsm update ~/.config/dns-manager/config.toml

如何贡献

非常欢迎你的加入！提一个 Issue 或者提交一个 Pull Request。

贡献者

感谢以下参与项目的人：

使用许可

GNU © Rongrui Zhan