CDDNS : Cloudflare 动态 DNS

cddns 是一个简单的、坚定不移的绿色 DDNS CLI 和云原生服务，用于 Cloudflare，由 Rust 构建。具有分层配置和交互式文件生成器。

⚠️ 警告：此项目正在运行，但尚未被认为适合生产使用。 查看 v1.0 跟踪

目录

• CDDNS : Cloudflare 动态 DNS
• 目录
• 1 安装
  • 1.1 支持的平台
  • 1.2 要求
  • 1.3 本地安装
    • 选项 A：Cargo（推荐）
    • 选项 B：二进制文件
  • 1.4 Docker
• 2 快速入门
• 3 使用
  • 3.1 概述
    • 3.1.1 API 令牌
    • 3.1.2 库存
    • 3.1.3 配置（可选）
    • 3.1.4 环境变量
  • 3.2 子命令
    • 3.2.1 验证
    • 3.2.2 配置
      • 3.2.2.1 显示
      • 3.2.2.2 构建
    • 3.2.3 列表
      • 3.2.3.1 区域
      • 3.2.3.2 记录
    • 3.2.4 库存
      • 3.2.4.1 构建
      • 3.2.4.2 显示
      • 3.2.4.3 检查
      • 3.2.4.4 更新
      • 3.2.4.5 删除
      • 3.2.4.6 观察
  • 3.3 服务部署
    • 3.3.1 Docker
    • 3.3.2 Docker Compose
    • 3.3.3 Kubernetes
    • 3.3.4 Crontab
• 4 目的
• 5 许可证

1 安装

1.1 支持的平台

• 命令行工具
  • 本地（Windows / MacOS / Unix）
• 服务
  • Docker
  • Docker Compose
  • Kubernetes
  • Crontab

1.2 要求

• Cloudflare 账户（帮助）
• 具有 编辑 DNS 权限的 Cloudflare API 令牌（帮助）

1.3 本地安装

安装 cddns CLI 是测试您的配置和为服务部署构建必要文件的一种方便方法。

选项 A：Cargo（推荐）

Cargo 是将 CDDNS 作为 CLI 安装的首选方式（什么是 Cargo？）。

• cargo+nightly install cddns

选项 B：二进制文件

• 从 发行版 下载兼容的二进制版本

1.4 Docker

此文档中的任何命令都可以在带有 Docker 的容器中运行或测试。

docker run simbleau/cddns <SUBCOMMAND>

2 快速入门

Docker 用户：将 "cddns" 替换为 "docker run simbleau/cddns"

首先，使用以下命令测试您的 Cloudflare API 令牌（帮助）

cddns --token <YOUR_CLOUDFLARE_TOKEN> verify

然后，生成一个清单文件（帮助）并保存

注意：您可以使用 --stdout 将清单文件重定向到终端

cddns \
  --token <YOUR_CLOUDFLARE_TOKEN> \
  inventory build

检查您的清单

cddns \
  --token <YOUR_CLOUDFLARE_TOKEN> \
  inventory --path '/path/to/inventory.yml' \
  check

如果以下内容正常工作，请继续查看您操作系统特定的服务说明

• Docker
• Docker Compose
• Kubernetes
• Crontab

3 使用

3.1 概述

cddns 是一个简单的 Cloudflare DDNS 工具，只需 Cloudflare API 令牌和清单文件。cddns 可以在容器中运行或作为 CLI 本地安装。

为了运行，cddns 需要一个包含您的 DNS 记录（什么是 DNS 记录？）的清单文件，这些文件可以生成或手动编写。对于配置，cddns 采用典型的分层配置方法：配置文件是基础，然后被环境变量覆盖，最后被 CLI 参数覆盖。

3.1.1 API 令牌

cddns 需要有效的 Cloudflare API 令牌才能运行（如何创建 API 令牌？）。

您可以使用以下命令测试 API 令牌

cddns verify--令牌<YOUR_CLOUDFLARE_TOKEN>.

成功后，您可能会看到 "This API Token is valid and active"

为了避免在每条命令中使用 --token，您可以将配置文件保存或设置 CDDNS_VERIFY_TOKEN 环境变量以手动指定您的令牌。 点击此处 了解更多环境变量。

3.1.2 库存

cddns 还需要一个包含您要监视的 DNS 记录的 YAML 格式清单文件。

默认情况下，我们会检查您本地的配置目录以查找清单文件。

• 在 Linux 上，这将是 $XDG_CONFIG_HOME/cddns/inventory.yml 或 $HOME/.config/cddns/inventory.yml
• 在 MacOS 上，这将是 $HOME/Library/Application Support/cddns/inventory.yml
• 在 Windows 上，这将是 %AppData%\cddns\inventory.yml

为了快速设置，CLI 提供了一个交互式清单文件构建器。

cddns inventory build

• 区域 是 Cloudflare 管理的域名、子域名和身份。
• 记录 是 Cloudflare 管理的 A（IPv4）或 AAAA（IPv6） DNS 记录。

要查看由您的 API 令牌管理的 DNS 记录，CLI 还提供了一个列出命令。

cddns list[记录/区域]

您可以在 inventory.yml 中查看一个带注释的示例。

您可以将 CDDNS_INVENTORY_PATH 环境变量设置为手动指定此文件的位置。 点击此处 了解更多环境变量。

3.1.3 配置（可选）

您可以选择使用 TOML 文件 保存配置，例如您的 API 密钥。 如果您存储 API 令牌，请限制此文件的权限。

默认情况下，我们会检查您本地的配置目录以查找配置文件。

• 在 Linux 上，这将是 $XDG_CONFIG_HOME/cddns/config.toml 或 $HOME/.config/cddns/config.toml
• 在MacOS上，这将是 $HOME/Library/Application Support/cddns/config.toml
• 在Windows上，这将是 %AppData%\cddns\config.toml

为了快速设置，CLI提供了一个交互式配置文件构建器。

cddns config build

您还可以访问config.toml以查看带注释的示例。

您可以将环境变量CDDNS_CONFIG设置为手动指定此文件的路径。 点击此处获取更多环境变量信息。

3.1.4 环境变量

可以存储在配置文件中的每个值都可以由环境变量替代或提供。

3.2 子命令

将--help或-h添加到任何命令或子命令将提供更多信息。

CLI对于测试和构建服务部署的文件非常有用。以下是CLI中所有命令的参考。

提示：您可以将-h或--help添加到任何子命令以获取有用的使用信息。

3.2.1 验证

帮助： cddns verify --help

verify命令将验证您的Cloudflare API令牌。

cddns verify [--token '<YOUR_CLOUDFLARE_TOKEN>']

如果您没有提供--token ...，则令牌将从您的配置文件或环境变量CDDNS_VERIFY_TOKEN中获取。

3.2.2 配置

帮助： cddns config --help

config命令将帮助您构建或管理您的配置（帮助）。cddns采用典型的分层配置方法；有3层。配置文件是基础，它被环境变量覆盖，环境变量被CLI参数覆盖。

默认情况下，cddns会在您的本地配置文件夹中检查保存的配置。

3.2.2.1 显示

要显示您的当前配置

-c 或 --config 将显示给定路径的清单

cddns config show

3.2.2.2 构建

构建配置文件

cddns config build

3.2.3 列表

帮助：cddns list --help

list 命令将打印出您的 API 令牌可见的 Cloudflare 资源。

• 区域 是 Cloudflare 管理的域名、子域名和身份。
• 记录 是 Cloudflare 管理的 A（IPv4）或 AAAA（IPv6） DNS 记录。

列出您的区域和记录

-include-zones <pattern1,pattern2,..> 将只包含与给定正则表达式模式匹配的区域 -ignore-zones <pattern1,pattern2,..> 将忽略与给定正则表达式模式匹配的区域 -include-records <pattern1,pattern2,..> 将只包含与给定正则表达式模式匹配的记录 -ignore-records <pattern1,pattern2,..> 将忽略与给定正则表达式模式匹配的记录

cddns list

3.2.3.1 区域

仅列出区域

-z 或 --zone 将只显示与给定名称或 ID 匹配的区域。

cddns list zones

3.2.3.2 记录

仅列出记录

-z 或 --zone 将只显示与给定区域名称或 ID 匹配的记录。 -r 或 --record 将只显示与给定名称或 ID 匹配的记录。

cddns list records

3.2.4 库存

帮助：cddns inventory --help

inventory 命令有多个子命令来构建和控制清单。

-p 或 --path 将显示给定路径的清单

3.2.4.1 构建

构建清单

--stdout 将清单输出到标准输出
--clean 将输出不经过后处理

cddns inventory build

3.2.4.2 显示

显示您的清单

--clean 将输出不经过后处理

cddns inventory show

3.2.4.3 检查

检查您的 DNS 记录，不进行任何更改

cddns inventory check

3.2.4.4 更新

更新 inventory check 中找到的所有过时的 DNS 记录

--force-update true 将尝试跳过提示

cddns inventory update

3.2.4.5 删除

修剪 inventory check 中找到的所有无效 DNS 记录

--force-prune true 将尝试跳过提示

cddns inventory prune

3.2.4.6 观察

持续更新错误的记录

-w 或 --watch-interval 将更改 DNS 刷新之间的 毫秒数

cddns inventory watch

3.3 服务部署

cddns 将作为服务守护进程运行，以保持 DNS 记录最新。默认检查间隔为每 30 秒一次。

3.3.1 Docker

目前支持的平台：amd64、arm64

在 Docker 上运行 cddns 是一个简单的 3 步过程。

1. 测试您的 Cloudflare API 令牌：（帮助）

export CDDNS_VERIFY_TOKEN='...'

docker run  \
  -e CDDNS_VERIFY_TOKEN \
  simbleau/cddns:latest verify

1. 测试您的清单（帮助）。

export CDDNS_INVENTORY_PATH='/to/your/inventory.yml'

docker run \
  -e CDDNS_VERIFY_TOKEN \
  -e CDDNS_INVENTORY_PATH='/inventory.yml' \
  -v $CDDNS_INVENTORY_PATH:'/inventory.yml' \
  simbleau/cddns:latest inventory check

1. 部署

所有 环境变量 都可用于额外配置。

docker run \
  -e CDDNS_VERIFY_TOKEN \
  -e CDDNS_INVENTORY_PATH='/inventory.yml' \
  -v $CDDNS_INVENTORY_PATH:/inventory.yml \
  simbleau/cddns:latest

3.3.2 Docker Compose

1. 使用上面的 Docker 指令 验证您的配置

2. 部署 Compose 文件[?]

所有 环境变量 都可用于额外配置。

# docker-compose.yaml
version: '3.3'
services:
    cddns:
        environment:
            - CDDNS_VERIFY_TOKEN
            - CDDNS_INVENTORY_PATH='/inventory.yml'
        volumes:
            - /host/path/to/inventory.yml:/inventory.yml
        image: 'simbleau/cddns:latest'

docker compose up

3.3.3 Kubernetes

我们最终将支持标准安装技术，如 Helm。您可以尝试自定义设置，或者您可以在 cddns CLI 的帮助下遵循我们的强制性步骤。

1. 为您的 API 令牌创建一个 Secret[?]

kubectl create secret generic cddns-api-token \
  --from-literal=token='YOUR_CLOUDFLARE_API_TOKEN'

2. 为您的清单创建一个 ConfigMap[?]

kubectl create configmap cddns-inventory \
  --from-file '/to/your/inventory.yml'

3. 创建一个 Deployment[?]

所有 环境变量 都可用于额外配置。

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cddns-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cddns
  template:
    metadata:
      labels:
        app: cddns
    spec:
      volumes: # Expose inventory as volume
        - name: "inventory"
          configMap:
            name: "cddns-inventory"
      containers:
      - name: cddns
        image: simbleau/cddns:latest
        volumeMounts:
        - name: inventory # Mount inventory file
            mountPath: /opt/bin/cddns/
            readOnly: true
        env:
        - name: CDDNS_INVENTORY_PATH
          value: /opt/bin/cddns/inventory.yml
        - name: CDDNS_VERIFY_TOKEN
            valueFrom: # Cloudflare API token
              secretKeyRef:
                  name: cddns-api-token
                  key: token

1. 部署

kubectl apply -f deployment.yaml

3.3.4 Crontab

1. 测试您的 Cloudflare API 令牌：（帮助）

cddns verify

1. 测试您的清单（帮助）。

cddns inventory show

1. 启动 crontab 编辑器

sudo crontab -e

1. 添加 crontab 条目（例如每 10 分钟一次）

*/10 * * * * "cfddns inventory --force-update true update"

4 目的

cddns 允许专家和家用用户在没有静态 IP 地址的情况下保持服务可用。CDDNS 将支持低端硬件，并始终坚持环保，帮助您降低成本并最大化硬件。

5 许可证

此项目同时受 Apache 2.0 和 MIT 许可的双重许可。