cfst-ddns

CloudflareSpeedTest DDNS 自动更新脚本

功能说明

自动执行 CloudflareSpeedTest 测速，并将最优 IP 通过 DNS API 更新到指定域名的 DNS 记录。

主要特性

✅ 自动测速获取最优 Cloudflare IP
✅ 支持多个 DNS 提供商（Cloudflare、DNSPod/腾讯云）
✅ 支持多域名同时更新
✅ 支持 IPv4/IPv6 双栈测速和更新
✅ 支持多种通知方式（Bark、Telegram）
✅ 智能判断是否需要更新
✅ 详细的执行日志和结果汇总
✅ 支持 Docker 部署
✅ 自动下载 CloudflareSpeedTest
✅ 支持 GitHub 镜像加速

快速开始

方式一：使用 Docker Hub 镜像（最简单）

直接使用已构建好的多架构镜像，支持 amd64、arm64、armv7 等架构：

# 1. 创建项目目录
mkdir -p cfst-ddns && cd cfst-ddns

# 2. 下载 docker-compose.yml
curl -O https://raw.githubusercontent.com/lonelyman0108/cfst-ddns/main/docker-compose.yml

# 3. 创建配置文件
mkdir -p data
curl -o data/config.sh https://raw.githubusercontent.com/lonelyman0108/cfst-ddns/main/config.example.sh
vim data/config.sh  # 编辑配置

# 4. 启动定时任务（每6小时执行一次）
docker-compose up -d

# 5. 查看日志
docker-compose logs -f cfst-ddns

可用镜像标签：

lonelyman0108/cfst-ddns:latest - 最新版本（运行时下载 cfst）
lonelyman0108/cfst-ddns:latest-bundled - 最新版本（预内置 cfst）
lonelyman0108/cfst-ddns:v1.0.0 - 特定版本（运行时下载 cfst）
lonelyman0108/cfst-ddns:v1.0.0-bundled - 特定版本（预内置 cfst）

镜像版本说明：

本项目提供两种 Docker 镜像变体：

标准版本 (latest, v1.0.0)
- CloudflareSpeedTest 在容器首次启动时下载
- 镜像体积更小
- 适合网络环境良好的场景
- 可通过 GITHUB_MIRROR 环境变量使用镜像站点
捆绑版本 (latest-bundled, v1.0.0-bundled)
- CloudflareSpeedTest 在镜像构建时已内置
- 镜像体积稍大，但启动更快
- 无需网络下载，开箱即用
- 推荐用于生产环境或网络受限场景

方式二：从源码构建 Docker 镜像

# 1. 克隆项目
git clone https://github.com/lonelyman0108/cfst-ddns.git
cd cfst-ddns

# 2. 创建数据目录并配置
mkdir -p data
cp config.example.sh data/config.sh
vim data/config.sh  # 编辑配置

# 3. 构建镜像（选择一种）
# 标准版本（运行时下载 cfst）
docker build -f Dockerfile -t cfst-ddns:latest .

# 捆绑版本（构建时内置 cfst）
docker build -f Dockerfile.bundled -t cfst-ddns:latest .

# 4. 启动定时任务（每6小时执行一次）
docker-compose up -d

# 5. 查看日志
docker-compose logs -f cfst-ddns

方式三：本地运行

# 1. 克隆项目
git clone https://github.com/lonelyman0108/cfst-ddns.git
cd cfst-ddns

# 2. 安装 CloudflareSpeedTest
./install.sh

# 3. 配置脚本
cp config.example.sh config.sh
vim config.sh

# 4. 运行脚本
./cfst_ddns.sh

详细使用步骤

1. 选择 DNS 提供商并获取 API 凭证

选项 A：使用 Cloudflare

方式一：使用 API Token（推荐）

登录 Cloudflare Dashboard
点击右上角头像 → My Profile → API Tokens
点击 "Create Token"
选择 "Edit zone DNS" 模板，或自定义权限：
- Permissions: Zone - DNS - Edit
- Zone Resources: 选择你的域名
创建后复制 Token（只显示一次）

方式二：使用 Global API Key

登录 Cloudflare Dashboard
My Profile → API Tokens → Global API Key
点击 "View" 并复制

获取 Zone ID：

进入 Cloudflare Dashboard
选择你的域名
右侧 "API" 区域可以看到 Zone ID

选项 B：使用 DNSPod

登录 DNSPod 控制台
进入用户中心 → 安全设置 → API Token
创建 Token，获取：
- ID（数字ID）
- Token（字符串）
将两者组合为 ID,Token 格式（例如：12345,1234567890abcdef1234567890abcdef）

2. 配置脚本

推荐方式：使用配置文件（避免敏感信息泄露）

# 复制配置示例文件
cp config.example.sh config.sh

# 编辑配置文件
vim config.sh  # 或使用其他编辑器

配置文件示例（config.example.sh）：

Cloudflare 配置示例

# ========== DNS 提供商选择 ==========
DNS_PROVIDER="cloudflare"

# ========== 要更新的域名列表 ==========
DNS_RECORD_NAMES="test1.example.com test2.example.com"

# ========== Cloudflare API 配置 ==========
# 方式一：使用 API Token（推荐）
CF_API_TOKEN="your_api_token_here"
CF_ZONE_ID="your_zone_id_here"

# 方式二：使用 Global API Key
# CF_API_EMAIL="[email protected]"
# CF_API_KEY="your_global_api_key"
# CF_ZONE_ID="your_zone_id_here"

DNSPod 配置示例

# ========== DNS 提供商选择 ==========
DNS_PROVIDER="dnspod"

# ========== 要更新的域名列表 ==========
# 注意：DNSPod 会自动解析主域名和子域名
DNS_RECORD_NAMES="test.example.com www.example.com example.com"

# ========== DNSPod API 配置 ==========
# 格式：ID,Token（例如：12345,1234567890abcdef1234567890abcdef）
DNSPOD_TOKEN="your_id,your_token"

通用配置（所有提供商）

# ========== 测速配置 ==========
# CloudflareSpeedTest 测速参数
# -n: 测速线程数量 -t: 延迟测速次数 -sl: 下载速度下限(MB/s)
CFST_PARAMS="-n 200 -t 4 -sl 5"

# 测速模式（同时决定 DNS 记录类型）
# v4: 仅测速 IPv4,更新 A 记录
# v6: 仅测速 IPv6,更新 AAAA 记录
# both: 同时测速 IPv4 和 IPv6,同时更新 A 和 AAAA 记录
CFST_TEST_MODE="v4"

# 跳过测速（使用已保存的测速结果）
# true: 跳过测速，使用上次结果
# false: 执行测速
SKIP_SPEED_TEST="false"

# ========== 通知配置 ==========
# Bark 通知（iOS）
ENABLE_BARK="false"
BARK_URL="https://api.day.app"
BARK_KEY=""

# Telegram 通知
ENABLE_TELEGRAM="false"
TG_BOT_TOKEN=""
TG_CHAT_ID=""

# ========== 其他配置 ==========
# 数据目录（测速结果保存位置）
# Docker: /app/data
# 本地: 脚本所在目录
DATA_DIR=""

或者直接编辑主脚本（不推荐，容易泄露敏感信息）

编辑 cfst_ddns.sh 文件的默认配置区域。

3. 可选：调整测速参数

在 config.sh 中修改测速相关配置：

# 测速参数
CFST_PARAMS="-n 200 -t 4 -sl 5"

# 测速模式
CFST_TEST_MODE="v4"  # v4/v6/both

# 跳过测速（使用已保存结果）
SKIP_SPEED_TEST="false"

测速参数说明：

-n 测速线程数量（默认200）
-t 延迟测速次数（默认4）
-sl 下载速度下限，单位MB/s（如设置为5，则只保留>=5MB/s的IP）
-dn 下载测速数量（默认10）

测速模式说明：

v4：仅测速 IPv4,更新 A 记录（默认）
v6：仅测速 IPv6,更新 AAAA 记录
both：同时测速 IPv4 和 IPv6,同时更新 A 和 AAAA 记录

跳过测速说明：

脚本会自动保存测速结果到 result_ddns.txt.v4 和 result_ddns.txt.v6。

设置 SKIP_SPEED_TEST="true" 可跳过测速，直接使用上次保存的结果，方便快速测试其他步骤（如 DNS 更新、通知等）。

4. 配置通知（可选）

脚本支持多种通知方式，可以同时启用。

Bark 通知（iOS）

ENABLE_BARK="true"
BARK_URL="https://api.day.app"
BARK_KEY="your_bark_key"

获取 Bark Key:

在 iPhone 上安装 Bark 应用
打开应用获取设备密钥
填入配置文件

Telegram 通知

ENABLE_TELEGRAM="true"
TG_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
TG_CHAT_ID="123456789"

获取 Telegram 配置:

与 @BotFather 对话创建机器人
获取 Bot Token
与你的机器人对话，发送任意消息
访问 https://api.telegram.org/bot<你的Token>/getUpdates 获取 Chat ID
填入配置文件

5. 运行脚本

本地运行

# 进入脚本目录
cd /path/to/cfst-ddns

# 首次运行：安装 CloudflareSpeedTest
./install.sh

# 执行 DDNS 脚本
./cfst_ddns.sh

使用 Docker 运行

方式一：定时任务模式（推荐）

默认配置已启用定时任务模式（ENABLE_CRON=true），容器会持续运行并按计划执行：

# 启动定时任务容器
docker-compose up -d

# 查看运行状态
docker-compose ps

# 查看日志
docker-compose logs -f cfst-ddns

# 停止定时任务
docker-compose down

方式二：单次执行模式

如果只想手动执行一次，需要修改配置：

编辑 docker-compose.yml：

environment:
  - ENABLE_CRON=false  # 改为 false

注释掉 restart: unless-stopped：
```
# restart: unless-stopped
```
执行单次任务：
```
docker-compose run --rm cfst-ddns
```

安装 CloudflareSpeedTest

自动安装（推荐）

运行安装脚本会自动检测系统架构并下载对应版本：

./install.sh

支持的系统：

Linux (x86_64, ARM64, ARM v5/v6/v7, MIPS 等)
macOS (Intel, Apple Silicon)
Windows (x86_64, ARM64)

使用 GitHub 镜像加速

如果下载速度慢，可以使用 GitHub 镜像站点：

# 设置镜像站点环境变量
export GITHUB_MIRROR="https://你的镜像站点"
./install.sh

如果无法访问 GitHub API 获取版本信息，可以手动指定版本号：

# 手动指定版本号
export CFST_VERSION="v2.2.5"
export GITHUB_MIRROR="https://你的镜像站点"  # 可选
./install.sh

注意:

由于网络环境不同,不同镜像站点的可用性会变化,请根据实际情况选择可用的镜像站点
版本号可在 CloudflareSpeedTest Releases 页面查看

手动安装

访问 CloudflareSpeedTest Releases
下载对应系统的版本
解压到 ./cfst/ 目录
确保可执行文件有执行权限

Docker 部署

使用预构建镜像（推荐）

项目提供了两种 Docker 镜像变体，均支持多架构，自动构建并发布到 Docker Hub：

1. 标准版本（运行时下载 cfst）

# 拉取最新镜像
docker pull lonelyman0108/cfst-ddns:latest

# 或拉取特定版本
docker pull lonelyman0108/cfst-ddns:v1.0.0

2. 捆绑版本（构建时内置 cfst，推荐）

# 拉取最新捆绑镜像
docker pull lonelyman0108/cfst-ddns:latest-bundled

# 或拉取特定版本的捆绑镜像
docker pull lonelyman0108/cfst-ddns:v1.0.0-bundled

支持的架构：

linux/amd64 - x86_64 架构（Intel/AMD）
linux/arm64 - ARM 64位架构（Apple Silicon、树莓派4等）
linux/arm/v7 - ARM v7 架构（树莓派3等）

Docker 会自动选择适合你系统的架构镜像。

镜像构建

如果需要自己构建镜像：

标准版本（运行时下载 cfst）：

# 本地构建
docker build -f Dockerfile -t cfst-ddns:latest .

# 使用 docker-compose 构建
docker-compose build

捆绑版本（构建时内置 cfst）：

# 本地构建
docker build -f Dockerfile.bundled -t cfst-ddns:latest .

# 使用构建参数指定镜像站点（可选）
docker build -f Dockerfile.bundled \
  --build-arg GITHUB_MIRROR="https://你的镜像站点" \
  -t cfst-ddns:latest .

# 使用构建参数指定 cfst 版本（可选）
docker build -f Dockerfile.bundled \
  --build-arg CFST_VERSION="v2.2.5" \
  -t cfst-ddns:latest .

CI/CD 自动构建

项目使用 GitHub Actions 自动构建和推送两种 Docker 镜像变体到 Docker Hub。

自动触发条件：

推送 Git 标签（如 v1.0.0） → 生成版本标签
- 标准版本：1.0.0、1.0、1、latest
- 捆绑版本：1.0.0-bundled、1.0-bundled、1-bundled、latest-bundled
手动触发（workflow_dispatch） → 生成开发标签
- 标准版本：dev、dev-{sha}
- 捆绑版本：dev-bundled、dev-bundled-{sha}
创建 Pull Request → 仅构建不推送

如需自己配置 CI/CD：

查看 GitHub Actions 设置指南了解如何配置 Docker Hub 密钥。

配置说明

目录结构：

cfst-ddns/
├── data/              # 配置和数据目录（挂载到容器）
│   └── config.sh      # 配置文件
├── logs/              # 日志目录（可选）
├── cfst/              # cfst 可执行文件（可选挂载，避免重复下载）
├── cfst_ddns.sh       # 主脚本
├── install.sh         # 安装脚本
├── Dockerfile         # Docker 镜像配置
└── docker-compose.yml # Docker Compose 配置

环境变量：

变量	说明	默认值
`TZ`	时区设置	`Asia/Shanghai`
`GITHUB_MIRROR`	GitHub 镜像站点（加速下载）	空（使用官方）
`CFST_VERSION`	CloudflareSpeedTest 版本号（当 GitHub API 访问失败时使用）	空（自动获取最新版本）
`AUTO_INSTALL_CFST`	自动安装 CloudflareSpeedTest	`true`
`DATA_DIR`	数据目录（测速结果保存位置）	Docker: `/app/data` 本地: 脚本所在目录
`CRON_SCHEDULE`	定时任务执行频率（cron 表达式）	`0 /6 * *`（每6小时）
`LOG_MAX_SIZE`	应用日志文件大小限制（字节）	`10485760`（10MB）

修改定时任务间隔：

编辑 docker-compose.yml:23 中的 CRON_SCHEDULE 环境变量：

environment:
  # 定时任务执行频率（cron 表达式）
  - CRON_SCHEDULE=0 */6 * * *  # 默认: 每6小时

常用示例：

每天凌晨3点：0 3 * * *
每小时：0 * * * *
每12小时：0 */12 * * *
每30分钟：*/30 * * * *

修改后重启容器：

docker-compose restart cfst-ddns

日志管理：

项目包含两层日志管理机制：

Docker 容器日志（控制 docker logs 输出）
- 位置：由 Docker 管理（通常在 /var/lib/docker/containers/）
- 配置：在 docker-compose.yml:55-59
- 默认设置：5MB × 3 个文件 = 15MB 总大小
- 查看日志：docker-compose logs -f cfst-ddns
应用日志文件（持久化日志）
- 位置：./logs/cfst-ddns.log（映射到容器的 /var/log/cfst-ddns.log）
- 自动轮转：当日志文件超过设定大小时自动轮转
- 保留策略：保留当前日志 + 1 个旧日志文件
- 默认大小限制：10MB（可通过 LOG_MAX_SIZE 环境变量调整）

修改日志大小限制：

方式一：通过环境变量（推荐）

# docker-compose.yml
environment:
  # 应用日志轮转大小（字节）
  - LOG_MAX_SIZE=20971520  # 20MB

常用大小参考：

5MB: 5242880
10MB: 10485760（默认）
20MB: 20971520
50MB: 52428800

方式二：修改 Docker 容器日志大小

# docker-compose.yml
logging:
  driver: "json-file"
  options:
    max-size: "5m"    # 修改单个文件大小
    max-file: "3"     # 修改保留文件数量

定时执行（可选）

macOS 使用 crontab

# 编辑 crontab
crontab -e

# 添加定时任务（每天凌晨3点执行）
0 3 * * * cd /Users/lm/Desktop/cfst-ddns && ./cfst_ddns.sh >> /tmp/cfst_ddns.log 2>&1

# 或每6小时执行一次
0 */6 * * * cd /Users/lm/Desktop/cfst-ddns && ./cfst_ddns.sh >> /tmp/cfst_ddns.log 2>&1

macOS 使用 launchd（推荐）

创建配置文件 ~/Library/LaunchAgents/com.cfst.ddns.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.cfst.ddns</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/lm/Desktop/cfst-ddns/cfst_ddns.sh</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/lm/Desktop/cfst-ddns</string>
    <key>StartInterval</key>
    <integer>21600</integer>
    <key>StandardOutPath</key>
    <string>/tmp/cfst_ddns.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/cfst_ddns_error.log</string>
</dict>
</plist>

加载任务：

launchctl load ~/Library/LaunchAgents/com.cfst.ddns.plist

脚本流程

检查配置是否完整
执行 CloudflareSpeedTest 测速
获取最优 IP
查询当前 DNS 记录
对比 IP 是否需要更新
调用 Cloudflare API 更新/创建 DNS 记录
显示执行结果

注意事项

DNS 提供商特性

Cloudflare

需要配置 Zone ID 和 API Token/Key
支持 API Token（推荐）和 Global API Key 两种认证方式
所有记录必须在同一个 Zone 下

DNSPod

使用简化的 DNSPod Token API（dnsapi.cn）
自动解析主域名和子域名（例如：test.example.com → 主域名 example.com，子域名 test）
支持裸域名（例如：example.com → 主域名 example.com，子域名 @）
只需配置一个 Token（格式：ID,Token）
重要: 不同主域名需要分别执行脚本（DNSPod API 限制）

通用注意事项

首次使用建议：先手动执行一次，确认配置正确
API Token 权限：确保 Token 有 DNS 编辑权限
测速环境：关闭代理软件，否则测速结果可能不准确
DNS 记录：如果域名记录不存在，脚本会自动创建
Proxied 设置：脚本默认关闭 Cloudflare 代理（proxied: false），如需开启请修改脚本

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.claude		.claude
.github		.github
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile.bundled		Dockerfile.bundled
README.md		README.md
cfst_ddns.sh		cfst_ddns.sh
config.example.sh		config.example.sh
docker-compose.yml		docker-compose.yml
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

cfst-ddns

功能说明

主要特性

快速开始

方式一：使用 Docker Hub 镜像（最简单）

方式二：从源码构建 Docker 镜像

方式三：本地运行

详细使用步骤

1. 选择 DNS 提供商并获取 API 凭证

选项 A：使用 Cloudflare

选项 B：使用 DNSPod

2. 配置脚本

Cloudflare 配置示例

DNSPod 配置示例

通用配置（所有提供商）

3. 可选：调整测速参数

4. 配置通知（可选）

5. 运行脚本

本地运行

使用 Docker 运行

安装 CloudflareSpeedTest

自动安装（推荐）

使用 GitHub 镜像加速

手动安装

Docker 部署

使用预构建镜像（推荐）

镜像构建

CI/CD 自动构建

配置说明

定时执行（可选）

macOS 使用 crontab

macOS 使用 launchd（推荐）

脚本流程

注意事项

DNS 提供商特性

Cloudflare

DNSPod

通用注意事项

故障排查

测速失败

API 调用失败

更新后不生效

参考链接

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages