whefter/cron

docker-cron 镜像文档

1. 镜像概述和主要用途

docker-cron 是一个轻量级定时任务容器，通过环境变量配置定时任务，内置 curl 和 Docker 客户端工具，专为 docker-compose 环境设计。主要用于在容器化架构中执行周期性任务，如API调用、数据备份、跨容器操作等。

2. 核心功能和特性

• 环境变量驱动配置：无需修改配置文件，直接通过环境变量定义定时任务，简化部署流程。
• 内置必要工具：集成 curl（用于HTTP请求）和 Docker 客户端（用于操作其他容器），满足常见任务需求。
• Docker 集成能力：支持挂载 docker.sock 与宿主机Docker守护进程通信，可执行 docker exec 等命令操作其他容器。
• 轻量设计：适合嵌入 docker-compose 架构，资源占用低，部署便捷。
• 灵活任务定义：支持任意Linux命令，可指定执行用户（如 root），适配多场景需求。

3. 使用场景和适用范围

• 定期API调用：通过 curl 定时触发后端服务接口（如数据同步、状态检查）。
• 系统备份任务：执行 rsync、tar 等命令定期备份数据目录。
• 跨容器操作：通过 docker exec 在其他容器内执行脚本（如数据库备份、日志清理）。
• 周期性运维任务：如日志轮转、临时文件清理、服务健康检查等。

4. 使用方法和配置说明

4.1 基本要求

• 运行环境：Docker Engine 1.13+，支持容器卷挂载。
• 推荐使用 docker-compose 进行容器编排，简化依赖管理。

4.2 核心配置参数（环境变量）

定时任务通过环境变量定义，每个任务以 CRON_ 为前缀命名，格式如下：

bash
CRON_<任务名>=<cron表达式> <执行用户> <命令>

• <任务名>：自定义标识（如 API_CALL、BACKUP），仅用于区分任务，无特殊格式要求。
• <cron表达式>：标准Cron时间格式，字段含义为 分(0-59) 时(0-23) 日(1-31) 月(1-12) 周(0-6, 0=周日)（如 0 3 * * * 表示每天凌晨3点执行）。
• <执行用户>：任务执行的Linux用户（如 root、www-data）。
• <命令>：需执行的具体命令（如 curl https://api.example.com/cron、docker exec app /backup.sh）。

4.3 关键依赖挂载

若任务中需使用 docker 命令（如 docker exec），必须将宿主机的 docker.sock 挂载到容器内，以实现与Docker守护进程的通信。挂载路径固定为 /var/run/docker.sock。

4.4 部署示例

4.4.1 docker-compose 配置（推荐）

在 docker-compose.yml 中集成：

yaml
version: '3'
services:
  cron:
    image: docker.xuanyuan.run/whefter/cron
    restart: always  # 确保容器持续运行
    network_mode: none  # 非必要时禁用网络，最小化暴露
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"  # 挂载Docker守护进程通信接口
      - "/opt:/opt"  # 可选：挂载宿主机目录（如备份源路径）
      - "/mnt/backup:/mnt/backup"  # 可选：挂载备份目标路径
    environment:
      # 示例1：每天凌晨3点以root用户调用API
      - "CRON_API_CALL=0 3 * * * root curl https://api.your-service.org/cron.php"
      # 示例2：每天凌晨4点以root用户执行目录备份
      - "CRON_DATA_BACKUP=0 4 * * * root rsync -a /opt /mnt/backup/opt"
      # 示例3：每天凌晨4点30分以root用户在其他容器内执行脚本
      - "CRON_CONTAINER_SCRIPT=30 4 * * * root docker exec service-container /app/backup.sh"

4.4.2 独立运行（docker run）

直接通过 docker run 启动容器（适合非 docker-compose 环境）：

bash
docker run -d \
  --name cron-task \
  --restart always \
  --network none \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e "CRON_HELLO=* * * * * root echo '定时任务执行' >> /var/log/cron.log" \
  docker.xuanyuan.run/whefter/cron

5. 许可证

MIT License

Copyright (c) 2019 William Hefter

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.