Skip to content

Commit 91c9a0b

Browse files
CopilotNewFuture
Copilot
and
NewFuture
authored
feat(docker): add DDNS_CRON environment variable for customizable cron schedule (NewFuture#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>
1 parent f74438c commit 91c9a0b

5 files changed

Lines changed: 283 additions & 2 deletions

File tree

‎doc/config/env.en.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ All environment variables use the `DDNS_` prefix followed by the parameter name
2727
| `DDNS_PROXY` | `http://host:port` or `DIRECT`, multiple values separated by semicolons | HTTP proxy settings | `DDNS_PROXY="http://127.0.0.1:1080;DIRECT"` |
2828
| `DDNS_CACHE` | `true`, `false`, or file path | Enable or specify cache file | `DDNS_CACHE="/tmp/cache"` |
2929
| `DDNS_SSL` | `true`, `false`, `auto`, or file path | SSL verification mode or certificate path | `DDNS_SSL=false`<br>`DDNS_SSL=/path/ca.crt` |
30+
| `DDNS_CRON` | Cron expression format string (Docker only) | Cron schedule for Docker container | `DDNS_CRON="*/10 * * * *"` |
3031
| `DDNS_LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | Logging level | `DDNS_LOG_LEVEL="DEBUG"` |
3132
| `DDNS_LOG_FILE` | File path | Output log file (default: stdout) | `DDNS_LOG_FILE="/tmp/ddns.log"` |
3233
| `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__
381382
export DDNS_CACHE="/tmp/ddns.cache"
382383
```
383384

385+
### Docker Cron Schedule Configuration
386+
387+
#### DDNS_CRON
388+
389+
- **Type**: String
390+
- **Required**: No
391+
- **Default**: `*/5 * * * *` (every 5 minutes)
392+
- **Description**: Cron schedule for scheduled tasks in Docker containers. Only effective in Docker environments. Uses standard cron expression format
393+
- **Format**: `minute hour day month weekday`
394+
- **Examples**:
395+
396+
```bash
397+
# Run every 10 minutes
398+
export DDNS_CRON="*/10 * * * *"
399+
400+
# Run every hour
401+
export DDNS_CRON="0 * * * *"
402+
403+
# Run once daily at 2 AM
404+
export DDNS_CRON="0 2 * * *"
405+
406+
# Run every 15 minutes
407+
export DDNS_CRON="*/15 * * * *"
408+
409+
# Run every 2 hours
410+
export DDNS_CRON="0 */2 * * *"
411+
```
412+
413+
**Cron Expression Reference**:
414+
415+
| Field | Allowed Values | Allowed Special Characters |
416+
|----------|----------------|----------------------------|
417+
| Minute | 0-59 | * , - / |
418+
| Hour | 0-23 | * , - / |
419+
| Day | 1-31 | * , - / |
420+
| Month | 1-12 | * , - / |
421+
| Weekday | 0-7 | * , - / |
422+
423+
**Common Expressions**:
424+
- `*/5 * * * *` - Every 5 minutes (default)
425+
- `*/10 * * * *` - Every 10 minutes
426+
- `*/15 * * * *` - Every 15 minutes
427+
- `0 * * * *` - Every hour
428+
- `0 */2 * * *` - Every 2 hours
429+
- `0 0 * * *` - Daily at midnight
430+
- `0 2 * * *` - Daily at 2 AM
431+
- `0 0 * * 0` - Weekly on Sunday at midnight
432+
433+
**Note**: This environment variable only works in Docker containers and does not affect DDNS programs running through other methods.
434+
384435
## Logging Configuration
385436

386437
### Log Level

‎doc/config/env.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ DDNS 支持通过环境变量进行配置，环境变量的优先级为：**[命
2727
| `DDNS_PROXY` | `http://host:port` 或 DIRECT，支持多代理数组或分号分隔 | HTTP 代理设置 | `DDNS_PROXY="http://127.0.0.1:1080;DIRECT"` |
2828
| `DDNS_CACHE` | true、false 或文件路径 | 启用缓存或指定缓存文件路径 | `DDNS_CACHE="/tmp/cache"` |
2929
| `DDNS_SSL` | true、false、auto 或文件路径 | 设置 SSL 验证方式或指定证书路径 | `DDNS_SSL=false`<br>`DDNS_SSL=/path/ca.crt` |
30+
| `DDNS_CRON` | Cron 表达式格式字符串（仅 Docker 环境有效） | Docker 容器内定时任务周期 | `DDNS_CRON="*/10 * * * *"` |
3031
| `DDNS_LOG_LEVEL` | DEBUG、INFO、WARNING、ERROR、CRITICAL | 设置日志等级 | `DDNS_LOG_LEVEL="DEBUG"` |
3132
| `DDNS_LOG_FILE` | 文件路径 | 设置日志输出文件（默认输出到终端）| `DDNS_LOG_FILE="/tmp/ddns.log"` |
3233
| `DDNS_LOG_FORMAT` | Python logging 格式模板 | 设置日志格式 | `DDNS_LOG_FORMAT="%(message)s"` |
@@ -247,6 +248,56 @@ DDNS 支持通过环境变量进行配置，环境变量的优先级为：**[命
247248
export DDNS_SSL="/etc/ssl/certs/ca-certificates.crt" # 自定义CA证书
248249
```
249250

251+
### Docker 定时任务配置
252+
253+
#### DDNS_CRON
254+
255+
- **类型**: 字符串
256+
- **必需**: 否
257+
- **默认值**: `*/5 * * * *` （每 5 分钟）
258+
- **说明**: Docker 容器中定时任务的执行周期，仅在 Docker 环境中有效。使用标准的 cron 表达式格式
259+
- **格式**: `分钟 小时 日 月 星期`
260+
- **示例**:
261+
262+
```bash
263+
# 每 10 分钟执行一次
264+
export DDNS_CRON="*/10 * * * *"
265+
266+
# 每小时执行一次
267+
export DDNS_CRON="0 * * * *"
268+
269+
# 每天凌晨 2 点执行一次
270+
export DDNS_CRON="0 2 * * *"
271+
272+
# 每 15 分钟执行一次
273+
export DDNS_CRON="*/15 * * * *"
274+
275+
# 每 2 小时执行一次
276+
export DDNS_CRON="0 */2 * * *"
277+
```
278+
279+
**Cron 表达式说明**:
280+
281+
| 字段 | 允许值 | 允许的特殊字符 |
282+
|------|--------|----------------|
283+
| 分钟 | 0-59 | * , - / |
284+
| 小时 | 0-23 | * , - / |
285+
| 日 | 1-31 | * , - / |
286+
| 月 | 1-12 | * , - / |
287+
| 星期 | 0-7 | * , - / |
288+
289+
**常用表达式**:
290+
- `*/5 * * * *` - 每 5 分钟（默认）
291+
- `*/10 * * * *` - 每 10 分钟
292+
- `*/15 * * * *` - 每 15 分钟
293+
- `0 * * * *` - 每小时
294+
- `0 */2 * * *` - 每 2 小时
295+
- `0 0 * * *` - 每天午夜
296+
- `0 2 * * *` - 每天凌晨 2 点
297+
- `0 0 * * 0` - 每周日午夜
298+
299+
**注意**: 此环境变量仅在 Docker 容器中生效，不影响通过其他方式运行的 DDNS 程序。
300+
250301
### 日志配置
251302

252303
#### DDNS_LOG_LEVEL

‎doc/docker.en.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,94 @@ docker run -d \
135135

136136
## Advanced Configuration
137137

138+
### Custom Cron Schedule
139+
140+
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.
141+
142+
The `DDNS_CRON` environment variable uses standard cron expression format: `minute hour day month weekday`
143+
144+
**Examples**:
145+
146+
```bash
147+
# Run every 10 minutes
148+
docker run -d \
149+
-e DDNS_CRON="*/10 * * * *" \
150+
-e DDNS_DNS=dnspod \
151+
-e DDNS_ID=12345 \
152+
-e DDNS_TOKEN=mytokenkey \
153+
-e DDNS_IPV4=example.com \
154+
--network host \
155+
newfuture/ddns
156+
157+
# Run every hour
158+
docker run -d \
159+
-e DDNS_CRON="0 * * * *" \
160+
-e DDNS_DNS=dnspod \
161+
-e DDNS_ID=12345 \
162+
-e DDNS_TOKEN=mytokenkey \
163+
-e DDNS_IPV4=example.com \
164+
--network host \
165+
newfuture/ddns
166+
167+
# Run once daily at 2 AM
168+
docker run -d \
169+
-e DDNS_CRON="0 2 * * *" \
170+
-e DDNS_DNS=dnspod \
171+
-e DDNS_ID=12345 \
172+
-e DDNS_TOKEN=mytokenkey \
173+
-e DDNS_IPV4=example.com \
174+
--network host \
175+
newfuture/ddns
176+
177+
# Run every minute (most frequent for cron)
178+
docker run -d \
179+
-e DDNS_CRON="* * * * *" \
180+
-e DDNS_DNS=dnspod \
181+
-e DDNS_ID=12345 \
182+
-e DDNS_TOKEN=mytokenkey \
183+
-e DDNS_IPV4=example.com \
184+
--network host \
185+
newfuture/ddns
186+
```
187+
188+
**Cron Expression Reference**:
189+
190+
| Field | Allowed Values | Allowed Special Characters |
191+
|----------|----------------|----------------------------|
192+
| Minute | 0-59 | * , - / |
193+
| Hour | 0-23 | * , - / |
194+
| Day | 1-31 | * , - / |
195+
| Month | 1-12 | * , - / |
196+
| Weekday | 0-7 | * , - / |
197+
198+
**Common Expression Examples**:
199+
200+
- `*/5 * * * *` - Every 5 minutes (default)
201+
- `*/10 * * * *` - Every 10 minutes
202+
- `*/15 * * * *` - Every 15 minutes
203+
- `0 * * * *` - Every hour
204+
- `0 */2 * * *` - Every 2 hours
205+
- `0 0 * * *` - Daily at midnight
206+
- `0 2 * * *` - Daily at 2 AM
207+
- `0 0 * * 0` - Weekly on Sunday at midnight
208+
209+
**Docker Compose Example**:
210+
211+
```yaml
212+
version: "3"
213+
services:
214+
ddns:
215+
image: newfuture/ddns:latest
216+
restart: always
217+
network_mode: host
218+
environment:
219+
- DDNS_CRON=*/10 * * * * # Run every 10 minutes
220+
- DDNS_DNS=dnspod
221+
- DDNS_ID=12345
222+
- DDNS_TOKEN=mytokenkey
223+
- DDNS_IPV4=example.com
224+
```
225+
138226
### Multi-Domain Configuration
139227
140228
Environment variable method for configuring multiple domains:

‎doc/docker.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,95 @@ docker run -d \
135135

136136
## 高级配置
137137

138+
### 自定义定时任务周期
139+
140+
默认情况下，DDNS 容器会每 5 分钟自动更新一次 DNS 记录。您可以通过 `DDNS_CRON` 环境变量自定义定时任务的执行周期。
141+
142+
`DDNS_CRON` 环境变量使用标准的 cron 表达式格式：`分钟 小时 日 月 星期`
143+
144+
**示例**：
145+
146+
```bash
147+
# 每 10 分钟执行一次
148+
docker run -d \
149+
-e DDNS_CRON="*/10 * * * *" \
150+
-e DDNS_DNS=dnspod \
151+
-e DDNS_ID=12345 \
152+
-e DDNS_TOKEN=mytokenkey \
153+
-e DDNS_IPV4=example.com \
154+
--network host \
155+
newfuture/ddns
156+
157+
# 每小时执行一次
158+
docker run -d \
159+
-e DDNS_CRON="0 * * * *" \
160+
-e DDNS_DNS=dnspod \
161+
-e DDNS_ID=12345 \
162+
-e DDNS_TOKEN=mytokenkey \
163+
-e DDNS_IPV4=example.com \
164+
--network host \
165+
newfuture/ddns
166+
167+
# 每天凌晨 2 点执行一次
168+
docker run -d \
169+
-e DDNS_CRON="0 2 * * *" \
170+
-e DDNS_DNS=dnspod \
171+
-e DDNS_ID=12345 \
172+
-e DDNS_TOKEN=mytokenkey \
173+
-e DDNS_IPV4=example.com \
174+
--network host \
175+
newfuture/ddns
176+
177+
# 每 30 秒执行一次（使用两个 cron 任务）
178+
# 注意：cron 最小单位是分钟，如需更频繁的更新，可以使用多个任务
179+
docker run -d \
180+
-e DDNS_CRON="* * * * *" \
181+
-e DDNS_DNS=dnspod \
182+
-e DDNS_ID=12345 \
183+
-e DDNS_TOKEN=mytokenkey \
184+
-e DDNS_IPV4=example.com \
185+
--network host \
186+
newfuture/ddns
187+
```
188+
189+
**Cron 表达式说明**：
190+
191+
| 字段 | 允许值 | 允许的特殊字符 |
192+
|------|--------|----------------|
193+
| 分钟 | 0-59 | * , - / |
194+
| 小时 | 0-23 | * , - / |
195+
| 日 | 1-31 | * , - / |
196+
| 月 | 1-12 | * , - / |
197+
| 星期 | 0-7 | * , - / |
198+
199+
**常用表达式示例**：
200+
201+
- `*/5 * * * *` - 每 5 分钟（默认值）
202+
- `*/10 * * * *` - 每 10 分钟
203+
- `*/15 * * * *` - 每 15 分钟
204+
- `0 * * * *` - 每小时
205+
- `0 */2 * * *` - 每 2 小时
206+
- `0 0 * * *` - 每天午夜
207+
- `0 2 * * *` - 每天凌晨 2 点
208+
- `0 0 * * 0` - 每周日午夜
209+
210+
**Docker Compose 示例**：
211+
212+
```yaml
213+
version: "3"
214+
services:
215+
ddns:
216+
image: newfuture/ddns:latest
217+
restart: always
218+
network_mode: host
219+
environment:
220+
- DDNS_CRON=*/10 * * * * # 每 10 分钟执行一次
221+
- DDNS_DNS=dnspod
222+
- DDNS_ID=12345
223+
- DDNS_TOKEN=mytokenkey
224+
- DDNS_IPV4=example.com
225+
```
226+
138227
### 多域名配置
139228
140229
环境变量方式配置多域名：

‎docker/entrypoint.sh‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,10 @@ if [ $# -eq 0 ]; then
1414
echo "[new] -v /host/folder/:/ddns/"
1515
echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
1616
fi
17-
echo "*/5 * * * * cd /ddns && /bin/ddns" > /etc/crontabs/root
18-
/bin/ddns && echo "Cron daemon will run every 5 minutes..." && exec crond -f
17+
# Use DDNS_CRON environment variable for cron schedule, default to every 5 minutes
18+
CRON_SCHEDULE="${DDNS_CRON:-*/5 * * * *}"
19+
echo "${CRON_SCHEDULE} cd /ddns && /bin/ddns" > /etc/crontabs/root
20+
/bin/ddns && echo "Cron daemon will run with schedule: ${CRON_SCHEDULE}" && exec crond -f
1921
else
2022
first=`echo $1 | cut -c1`
2123
if [ "$first" = "-" ]; then

0 commit comments

Comments
 (0)