NearlyFreeSpeech.net 动态DNS工具

概述

以下提供了一款工具，用于使用动态IP地址更新NearlyFreeSpeech.NET DNS记录。调用此工具将执行以下操作

• 选择一个随机提供商以查询运行主机的公网IP。
• 查询配置的IP地址的NearlyFreeSpeech.NET域名上的A记录。
• 比较地址，并在它们不匹配时更新。
• (可选) 在NearlyFreeSpeech.NET上缓存检测到的公网地址几天（可配置）以限制API请求。

要求

• Python 3.8+
• PyYAML
• Requests 2.30.0+

安装

可以使用pip安装此工具

pip install nfsn-ddns
 (or)
python -m pip install nfsn-ddns

使用方法

可以使用以下命令行从命令行调用此工具

nfsn-ddns --help
 (or)
python -m nfsn-ddns --help

配置

可以使用文件、命令行参数或环境变量配置此工具。以下是一个示例配置文件（config.yaml）：

nfsn-ddns:
  api-login: <api-login>
  api-token: <api-token>
  domains:
    - <domain>
  timeout: 10

用户可以使用多种方式来配置此工具。例如，大多数选项可以从命令行配置，但某些选项（例如API令牌）可以从环境变量配置

export NFSN_DDNS_API_TOKEN=myapitoken
nfsn-ddns --api-login myaccount --ddns-domain ddns.example.com

以下列出所有可用的配置选项：

基本选项
API登录	NearlyFreeSpeech.NET用户的登录/账户。这用于验证API请求。 命令行选项：--api-login 配置键：api-login (字符串) 环境变量：NFSN_DDNS_API_LOGIN
API令牌	用于验证API请求的令牌。成员可以通过查看他们的个人资料并选择管理API密钥来获取API令牌。在此页面上，用户可以请求生成API令牌。 命令行选项：--api-token 配置键：api-token (字符串) 环境变量：NFSN_DDNS_API_TOKEN
DDNS域名	要更新的DNS资源，包括用于更新与动态检测到的IP地址及其域的DNS记录。例如 ddns.example.com 可以提供多个域名，供希望跨多个域创建DDNS记录的用户使用（尽管在尝试更新单个域的多个记录时推荐使用CNAME）。 命令行选项：--ddns-domain 配置键：domains (字符串列表) 环境变量：NFSN_DDNS_DOMAINS (分号分隔)
其他选项
缓存	配置是否将检测到的公网IP缓存到本地文件中。此功能可以用于在认为主机的公网IP没有变化时避免NFSN API调用。在成功验证配置的DNS记录后，检测到的公网IP可以存储在缓存文件中以供将来参考。下次此实用程序运行并检测到公网IP地址时，如果地址与缓存文件中的地址匹配，则不会向NFSN发出API请求。缓存将在配置的天数内被视为有效信息源（请参阅“缓存天数”）。 默认情况下，此设置未启用（除容器环境外）。 命令行选项：--cache 配置键：cache (布尔值) 环境变量：NFSN_DDNS_CACHE
缓存天数	使用缓存功能时，此值配置缓存被认为已过期的总天数。过期的缓存将导致此实用程序执行API请求以验证DNS记录是否匹配。 默认情况下，缓存被认为有效期为七天（7天）。 命令行选项：--cache-days 配置键：cache-days (整数) 环境变量：NFSN_DDNS_CACHE_DAYS
缓存文件	使用缓存功能时，如果设置此选项，将指定存储缓存内容的特定文件。 默认情况下，将使用此实用程序可写入的第一个可用路径作为缓存文件的位置。 /run/nfsn-ddns/cached-ip (or) /run/user/(UID)/cached-ip (or) nfsn-ddns-cached-ip 命令行选项：--cache-file 配置键：cache-file 环境变量：NFSN_DDNS_CACHE_FILE
IP API端点	IP API端点是用于帮助确定运行此实用程序的实例的公网IP地址的Web服务。检测到的IP将用于更新配置的DNS记录。 每次运行时都会随机选择使用的端点。如果给定的端点无法访问，则使用其他端点，直到提供IP地址或所有端点都已用尽。 默认使用的端点如下所示 https://api.ipify.org https://checkip.amazonaws.com/ https://ifconfig.me/ip https://ipinfo.io/ip https://trackip.net/ip 用户可以通过配置此选项来覆盖使用哪些端点。 配置键：myip-api-endpoints (字符串列表) 环境变量：NFSN_DDNS_MYIP_API_ENDPOINTS (分号分隔)
超时	配置在认为任何请求到外部来源（即NFSN API或IP提供商）超时前的时间（秒）。所有请求的默认超时配置为十（10）秒。 命令行选项：--timeout 配置键：timeout 环境变量：NFSN_DDNS_TIMEOUT
高级选项
NFSN API 端点	NearlyFreeSpeech.NET 的 API 端点。在大多数情况下，此选项无需更改。但是，如果需要使用不同的端点，则提供此选项。 默认配置为 https://api.nearlyfreespeech.net/dns。 配置键：nfsn-api-endpoint (str) 环境变量：NFSN_DDNS_NFSN_API_ENDPOINT

Docker

该项目支持多种方式在 Docker 环境中使用此实用程序。一个推荐的选择是使用来自 GitHub 容器仓库的预构建镜像。

预构建镜像

可以使用以下命令获取预构建镜像

docker pull ghcr.io/jdknight/nfsn-ddns

通过创建一个包含在 env.default 中定义的内容的文件 /etc/nfsn-ddns 来为此容器准备配置环境（用户可以使用任何路径或文件名，只要下面的 docker run 命令指向此文件即可）。根据所需配置调整这些选项。

可以使用以下命令运行容器

docker run --name nfsn-ddns --detach --restart unless-stopped \
    --env-file /etc/nfsn-ddns ghcr.io/jdknight/nfsn-ddns

自构建镜像

希望管理自己镜像的用户可以使用此存储库中找到的 Docker 定义。这可以通过在想要运行容器的宿主机上克隆此存储库来完成。可以在存储库上运行 Docker 构建

docker build -t ghcr.io/jdknight/nfsn-ddns --detach -f docker/Dockerfile .

然后运行上面提到的相同的 docker run 命令。

自管理 Docker Compose

用户还可以利用 Docker Compose 定义。首先，将环境模板（env.default）复制到 .nfsn-ddns.env，然后编辑所需的选项。

cp env.default .nfsn-ddns.env

接下来，使用 docker compose 加载容器

docker compose build
docker compose up --detach

默认情况下，两个 Docker 构建调用都将加载包含 PyPI 版本的 nfsn-ddns 的容器。希望在其容器中使用本地实现的用户可以通过使用带有 --build-arg local 参数的 Docker 构建来实现。

例如

docker compose build --build-arg BUILD_MODE=local
docker compose up --detach