From 91c9a0b2f58d90aea0313a63b655df9eac54f77d Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Thu, 23 Oct 2025 09:01:02 +0000
Subject: [PATCH] feat(docker): add DDNS_CRON environment variable for
customizable cron schedule (#574)
* Initial plan
* feat(docker): add DDNS_CRON environment variable for customizable cron schedule
Co-authored-by: NewFuture <6290356+NewFuture@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: NewFuture <6290356+NewFuture@users.noreply.github.com>
---
doc/config/env.en.md | 51 +++++++++++++++++++++++++
doc/config/env.md | 51 +++++++++++++++++++++++++
doc/docker.en.md | 88 +++++++++++++++++++++++++++++++++++++++++++
doc/docker.md | 89 ++++++++++++++++++++++++++++++++++++++++++++
docker/entrypoint.sh | 6 ++-
5 files changed, 283 insertions(+), 2 deletions(-)
diff --git a/doc/config/env.en.md b/doc/config/env.en.md
index cb2ab53..efa584b 100644
--- a/doc/config/env.en.md
+++ b/doc/config/env.en.md
@@ -27,6 +27,7 @@ All environment variables use the `DDNS_` prefix followed by the parameter name
| `DDNS_PROXY` | `http://host:port` or `DIRECT`, multiple values separated by semicolons | HTTP proxy settings | `DDNS_PROXY="http://127.0.0.1:1080;DIRECT"` |
| `DDNS_CACHE` | `true`, `false`, or file path | Enable or specify cache file | `DDNS_CACHE="/tmp/cache"` |
| `DDNS_SSL` | `true`, `false`, `auto`, or file path | SSL verification mode or certificate path | `DDNS_SSL=false`
`DDNS_SSL=/path/ca.crt` |
+| `DDNS_CRON` | Cron expression format string (Docker only) | Cron schedule for Docker container | `DDNS_CRON="*/10 * * * *"` |
| `DDNS_LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | Logging level | `DDNS_LOG_LEVEL="DEBUG"` |
| `DDNS_LOG_FILE` | File path | Output log file (default: stdout) | `DDNS_LOG_FILE="/tmp/ddns.log"` |
| `DDNS_LOG_FORMAT` | Python logging format string | Log format template | `DDNS_LOG_FORMAT="%(message)s"` |
@@ -381,6 +382,56 @@ export DDNS_TOKEN='{"api_key": "your_key", "domain": "__DOMAIN__", "ip": "__IP__
export DDNS_CACHE="/tmp/ddns.cache"
```
+### Docker Cron Schedule Configuration
+
+#### DDNS_CRON
+
+- **Type**: String
+- **Required**: No
+- **Default**: `*/5 * * * *` (every 5 minutes)
+- **Description**: Cron schedule for scheduled tasks in Docker containers. Only effective in Docker environments. Uses standard cron expression format
+- **Format**: `minute hour day month weekday`
+- **Examples**:
+
+ ```bash
+ # Run every 10 minutes
+ export DDNS_CRON="*/10 * * * *"
+
+ # Run every hour
+ export DDNS_CRON="0 * * * *"
+
+ # Run once daily at 2 AM
+ export DDNS_CRON="0 2 * * *"
+
+ # Run every 15 minutes
+ export DDNS_CRON="*/15 * * * *"
+
+ # Run every 2 hours
+ export DDNS_CRON="0 */2 * * *"
+ ```
+
+**Cron Expression Reference**:
+
+| Field | Allowed Values | Allowed Special Characters |
+|----------|----------------|----------------------------|
+| Minute | 0-59 | * , - / |
+| Hour | 0-23 | * , - / |
+| Day | 1-31 | * , - / |
+| Month | 1-12 | * , - / |
+| Weekday | 0-7 | * , - / |
+
+**Common Expressions**:
+- `*/5 * * * *` - Every 5 minutes (default)
+- `*/10 * * * *` - Every 10 minutes
+- `*/15 * * * *` - Every 15 minutes
+- `0 * * * *` - Every hour
+- `0 */2 * * *` - Every 2 hours
+- `0 0 * * *` - Daily at midnight
+- `0 2 * * *` - Daily at 2 AM
+- `0 0 * * 0` - Weekly on Sunday at midnight
+
+**Note**: This environment variable only works in Docker containers and does not affect DDNS programs running through other methods.
+
## Logging Configuration
### Log Level
diff --git a/doc/config/env.md b/doc/config/env.md
index 6fca6ba..7b12252 100644
--- a/doc/config/env.md
+++ b/doc/config/env.md
@@ -27,6 +27,7 @@ DDNS 支持通过环境变量进行配置，环境变量的优先级为：**[命
| `DDNS_PROXY` | `http://host:port` 或 DIRECT，支持多代理数组或分号分隔 | HTTP 代理设置 | `DDNS_PROXY="http://127.0.0.1:1080;DIRECT"` |
| `DDNS_CACHE` | true、false 或文件路径 | 启用缓存或指定缓存文件路径 | `DDNS_CACHE="/tmp/cache"` |
| `DDNS_SSL` | true、false、auto 或文件路径 | 设置 SSL 验证方式或指定证书路径 | `DDNS_SSL=false`
`DDNS_SSL=/path/ca.crt` |
+| `DDNS_CRON` | Cron 表达式格式字符串（仅 Docker 环境有效） | Docker 容器内定时任务周期 | `DDNS_CRON="*/10 * * * *"` |
| `DDNS_LOG_LEVEL` | DEBUG、INFO、WARNING、ERROR、CRITICAL | 设置日志等级 | `DDNS_LOG_LEVEL="DEBUG"` |
| `DDNS_LOG_FILE` | 文件路径 | 设置日志输出文件（默认输出到终端）| `DDNS_LOG_FILE="/tmp/ddns.log"` |
| `DDNS_LOG_FORMAT` | Python logging 格式模板 | 设置日志格式 | `DDNS_LOG_FORMAT="%(message)s"` |
@@ -247,6 +248,56 @@ DDNS 支持通过环境变量进行配置，环境变量的优先级为：**[命
export DDNS_SSL="/etc/ssl/certs/ca-certificates.crt" # 自定义CA证书
```
+### Docker 定时任务配置
+
+#### DDNS_CRON
+
+- **类型**: 字符串
+- **必需**: 否
+- **默认值**: `*/5 * * * *` （每 5 分钟）
+- **说明**: Docker 容器中定时任务的执行周期，仅在 Docker 环境中有效。使用标准的 cron 表达式格式
+- **格式**: `分钟 小时 日 月 星期`
+- **示例**:
+
+ ```bash
+ # 每 10 分钟执行一次
+ export DDNS_CRON="*/10 * * * *"
+
+ # 每小时执行一次
+ export DDNS_CRON="0 * * * *"
+
+ # 每天凌晨 2 点执行一次
+ export DDNS_CRON="0 2 * * *"
+
+ # 每 15 分钟执行一次
+ export DDNS_CRON="*/15 * * * *"
+
+ # 每 2 小时执行一次
+ export DDNS_CRON="0 */2 * * *"
+ ```
+
+**Cron 表达式说明**:
+
+| 字段 | 允许值 | 允许的特殊字符 |
+|------|--------|----------------|
+| 分钟 | 0-59 | * , - / |
+| 小时 | 0-23 | * , - / |
+| 日 | 1-31 | * , - / |
+| 月 | 1-12 | * , - / |
+| 星期 | 0-7 | * , - / |
+
+**常用表达式**:
+- `*/5 * * * *` - 每 5 分钟（默认）
+- `*/10 * * * *` - 每 10 分钟
+- `*/15 * * * *` - 每 15 分钟
+- `0 * * * *` - 每小时
+- `0 */2 * * *` - 每 2 小时
+- `0 0 * * *` - 每天午夜
+- `0 2 * * *` - 每天凌晨 2 点
+- `0 0 * * 0` - 每周日午夜
+
+**注意**: 此环境变量仅在 Docker 容器中生效，不影响通过其他方式运行的 DDNS 程序。
+
### 日志配置
#### DDNS_LOG_LEVEL
diff --git a/doc/docker.en.md b/doc/docker.en.md
index a6dc9c0..5d6c468 100644
--- a/doc/docker.en.md
+++ b/doc/docker.en.md
@@ -135,6 +135,94 @@ docker run -d \
## Advanced Configuration
+### Custom Cron Schedule
+
+By default, the DDNS container automatically updates DNS records every 5 minutes. You can customize the scheduled task execution interval using the `DDNS_CRON` environment variable.
+
+The `DDNS_CRON` environment variable uses standard cron expression format: `minute hour day month weekday`
+
+**Examples**:
+
+```bash
+# Run every 10 minutes
+docker run -d \
+ -e DDNS_CRON="*/10 * * * *" \
+ -e DDNS_DNS=dnspod \
+ -e DDNS_ID=12345 \
+ -e DDNS_TOKEN=mytokenkey \
+ -e DDNS_IPV4=example.com \
+ --network host \
+ newfuture/ddns
+
+# Run every hour
+docker run -d \
+ -e DDNS_CRON="0 * * * *" \
+ -e DDNS_DNS=dnspod \
+ -e DDNS_ID=12345 \
+ -e DDNS_TOKEN=mytokenkey \
+ -e DDNS_IPV4=example.com \
+ --network host \
+ newfuture/ddns
+
+# Run once daily at 2 AM
+docker run -d \
+ -e DDNS_CRON="0 2 * * *" \
+ -e DDNS_DNS=dnspod \
+ -e DDNS_ID=12345 \
+ -e DDNS_TOKEN=mytokenkey \
+ -e DDNS_IPV4=example.com \
+ --network host \
+ newfuture/ddns
+
+# Run every minute (most frequent for cron)
+docker run -d \
+ -e DDNS_CRON="* * * * *" \
+ -e DDNS_DNS=dnspod \
+ -e DDNS_ID=12345 \
+ -e DDNS_TOKEN=mytokenkey \
+ -e DDNS_IPV4=example.com \
+ --network host \
+ newfuture/ddns
+```
+
+**Cron Expression Reference**:
+
+| Field | Allowed Values | Allowed Special Characters |
+|----------|----------------|----------------------------|
+| Minute | 0-59 | * , - / |
+| Hour | 0-23 | * , - / |
+| Day | 1-31 | * , - / |
+| Month | 1-12 | * , - / |
+| Weekday | 0-7 | * , - / |
+
+**Common Expression Examples**:
+
+- `*/5 * * * *` - Every 5 minutes (default)
+- `*/10 * * * *` - Every 10 minutes
+- `*/15 * * * *` - Every 15 minutes
+- `0 * * * *` - Every hour
+- `0 */2 * * *` - Every 2 hours
+- `0 0 * * *` - Daily at midnight
+- `0 2 * * *` - Daily at 2 AM
+- `0 0 * * 0` - Weekly on Sunday at midnight
+
+**Docker Compose Example**:
+
+```yaml
+version: "3"
+services:
+ ddns:
+ image: newfuture/ddns:latest
+ restart: always
+ network_mode: host
+ environment:
+ - DDNS_CRON=*/10 * * * * # Run every 10 minutes
+ - DDNS_DNS=dnspod
+ - DDNS_ID=12345
+ - DDNS_TOKEN=mytokenkey
+ - DDNS_IPV4=example.com
+```
+
### Multi-Domain Configuration
Environment variable method for configuring multiple domains:
diff --git a/doc/docker.md b/doc/docker.md
index d2b999b..4c02e09 100644
--- a/doc/docker.md
+++ b/doc/docker.md
@@ -135,6 +135,95 @@ docker run -d \
## 高级配置
+### 自定义定时任务周期
+
+默认情况下，DDNS 容器会每 5 分钟自动更新一次 DNS 记录。您可以通过 `DDNS_CRON` 环境变量自定义定时任务的执行周期。
+
+`DDNS_CRON` 环境变量使用标准的 cron 表达式格式：`分钟 小时 日 月 星期`
+
+**示例**：
+
+```bash
+# 每 10 分钟执行一次
+docker run -d \
+ -e DDNS_CRON="*/10 * * * *" \
+ -e DDNS_DNS=dnspod \
+ -e DDNS_ID=12345 \
+ -e DDNS_TOKEN=mytokenkey \
+ -e DDNS_IPV4=example.com \
+ --network host \
+ newfuture/ddns
+
+# 每小时执行一次
+docker run -d \
+ -e DDNS_CRON="0 * * * *" \
+ -e DDNS_DNS=dnspod \
+ -e DDNS_ID=12345 \
+ -e DDNS_TOKEN=mytokenkey \
+ -e DDNS_IPV4=example.com \
+ --network host \
+ newfuture/ddns
+
+# 每天凌晨 2 点执行一次
+docker run -d \
+ -e DDNS_CRON="0 2 * * *" \
+ -e DDNS_DNS=dnspod \
+ -e DDNS_ID=12345 \
+ -e DDNS_TOKEN=mytokenkey \
+ -e DDNS_IPV4=example.com \
+ --network host \
+ newfuture/ddns
+
+# 每 30 秒执行一次（使用两个 cron 任务）
+# 注意：cron 最小单位是分钟，如需更频繁的更新，可以使用多个任务
+docker run -d \
+ -e DDNS_CRON="* * * * *" \
+ -e DDNS_DNS=dnspod \
+ -e DDNS_ID=12345 \
+ -e DDNS_TOKEN=mytokenkey \
+ -e DDNS_IPV4=example.com \
+ --network host \
+ newfuture/ddns
+```
+
+**Cron 表达式说明**：
+
+| 字段 | 允许值 | 允许的特殊字符 |
+|------|--------|----------------|
+| 分钟 | 0-59 | * , - / |
+| 小时 | 0-23 | * , - / |
+| 日 | 1-31 | * , - / |
+| 月 | 1-12 | * , - / |
+| 星期 | 0-7 | * , - / |
+
+**常用表达式示例**：
+
+- `*/5 * * * *` - 每 5 分钟（默认值）
+- `*/10 * * * *` - 每 10 分钟
+- `*/15 * * * *` - 每 15 分钟
+- `0 * * * *` - 每小时
+- `0 */2 * * *` - 每 2 小时
+- `0 0 * * *` - 每天午夜
+- `0 2 * * *` - 每天凌晨 2 点
+- `0 0 * * 0` - 每周日午夜
+
+**Docker Compose 示例**：
+
+```yaml
+version: "3"
+services:
+ ddns:
+ image: newfuture/ddns:latest
+ restart: always
+ network_mode: host
+ environment:
+ - DDNS_CRON=*/10 * * * * # 每 10 分钟执行一次
+ - DDNS_DNS=dnspod
+ - DDNS_ID=12345
+ - DDNS_TOKEN=mytokenkey
+ - DDNS_IPV4=example.com
+```
+
### 多域名配置
环境变量方式配置多域名：
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index 0861c13..4892ce2 100755
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -14,8 +14,10 @@ if [ $# -eq 0 ]; then
echo "[new] -v /host/folder/:/ddns/"
echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
fi
- echo "*/5 * * * * cd /ddns && /bin/ddns" > /etc/crontabs/root
- /bin/ddns && echo "Cron daemon will run every 5 minutes..." && exec crond -f
+ # Use DDNS_CRON environment variable for cron schedule, default to every 5 minutes
+ CRON_SCHEDULE="${DDNS_CRON:-*/5 * * * *}"
+ echo "${CRON_SCHEDULE} cd /ddns && /bin/ddns" > /etc/crontabs/root
+ /bin/ddns && echo "Cron daemon will run with schedule: ${CRON_SCHEDULE}" && exec crond -f
else
first=`echo $1 | cut -c1`
if [ "$first" = "-" ]; then