tgbyte/cron

Dockerized Cron 镜像文档

一、镜像概述

Dockerized Cron 是一个轻量级 Docker 镜像，旨在将 Unix/Linux 系统中的 cron 守护进程容器化，提供在隔离环境中执行定时任务的能力。该镜像基于 Alpine Linux 构建，保持极小体积的同时，完整支持 cron 任务调度功能，适用于需要在容器环境中运行周期性任务的场景。

二、核心功能与特性

核心功能

• 完整支持 cron 任务调度语法（兼容 Vixie Cron 标准）
• 支持自定义 crontab 文件挂载与管理
• 任务输出日志重定向至容器标准输出（stdout/stderr），便于 Docker 日志系统收集
• 支持时区配置，确保任务按预期时区执行

特性

• 轻量级：基于 Alpine Linux，镜像体积小于 10MB
• 灵活配置：支持通过文件挂载或环境变量定义 cron 任务
• 持久化：任务配置文件可通过卷挂载实现持久化，容器重启后任务不丢失
• 可观测性：任务执行日志实时输出，支持通过 docker logs 查看
• 多平台支持：支持 amd64、arm64 等主流架构

三、使用场景与适用范围

典型使用场景

• 容器化应用定时任务：为微服务或容器化应用提供定时任务能力（如数据备份、日志清理）
• CI/CD 辅助操作：定时触发构建、测试或部署流程
• 开发/测试环境：在隔离环境中调试 cron 任务逻辑
• 轻量级自动化：替代传统服务器 cron，简化任务环境依赖管理

适用范围

• 需要执行周期性命令/脚本的场景（时间粒度支持分钟级至年级）
• 任务逻辑简单、无复杂环境依赖的场景
• 追求资源占用低、部署便捷的场景

四、使用方法与配置说明

4.1 快速启动（docker run）

基本用法（挂载自定义 crontab 文件）

bash
# 1. 创建本地 crontab 文件（示例：每分钟输出当前时间到日志）
echo "* * * * * echo 'Current time: \$(date)' >> /var/log/cron.log 2>&1" > ./my-crontab

# 2. 运行容器，挂载 crontab 文件至容器内默认路径
docker run -d \
  --name docker-cron \
  -v $(pwd)/my-crontab:/etc/crontabs/root \  # 挂载自定义 crontab（root 用户任务）
  -v $(pwd)/cron-logs:/var/log \            # 挂载日志目录（可选，持久化日志）
  -e TZ=Asia/Shanghai \                     # 设置时区（默认 UTC）
  dockerized-cron:latest

说明：

• 容器内默认使用 root 用户执行任务，crontab 文件需挂载至 /etc/crontabs/root（Alpine crond 标准路径）
• 任务输出建议通过 >> /path/to/log 2>&1 重定向至文件，或直接输出到 stdout（通过 docker logs 查看）

4.2 任务配置（crontab 文件格式）

容器内 crontab 文件语法与标准 cron 一致，格式如下：

plaintext
# 分钟 小时 日 月 星期  命令/脚本（支持绝对路径）
# 取值范围：
# 分钟 (0-59), 小时 (0-23), 日 (1-31), 月 (1-12), 星期 (0-6, 0=周日)
# 特殊符号：*（任意值）、/（间隔）、,（枚举）、-（范围）

# 示例任务：
*/5 * * * * /usr/local/bin/backup.sh  # 每 5 分钟执行备份脚本
0 3 * * * /usr/local/bin/clean-logs.sh  # 每天凌晨 3 点执行日志清理
0 0 * * 0 /usr/local/bin/weekly-report.sh  # 每周日凌晨 0 点生成周报

4.3 环境变量配置

4.4 日志查看与管理

查看任务输出日志

bash
# 实时查看容器日志（包含 cron 守护进程日志与任务输出）
docker logs -f docker-cron

日志持久化（挂载日志目录）

bash
# 将容器内 /var/log 挂载至本地目录，持久化任务日志
docker run -d \
  --name docker-cron \
  -v $(pwd)/my-crontab:/etc/crontabs/root \
  -v $(pwd)/cron-logs:/var/log \  # 本地目录 cron-logs 会保存任务日志
  dockerized-cron:latest

4.5 docker-compose 配置示例

yaml
version: '3.8'

services:
  cron:
    image: dockerized-cron:latest
    container_name: app-cron
    restart: unless-stopped  # 任务持久化，容器退出后自动重启
    environment:
      - TZ=Asia/Shanghai  # 设置时区为上海
      - CRON_USER=appuser  # 非 root 用户执行任务（需确保容器内存在该用户）
    volumes:
      - ./crontabs:/etc/crontabs  # 挂载整个 crontabs 目录（支持多用户任务）
      - ./scripts:/usr/local/scripts  # 挂载任务依赖的脚本（如备份脚本）
      - ./cron-logs:/var/log  # 持久化日志
    # 可选：限制资源占用
    deploy:
      resources:
        limits:
          cpus: '0.1'
          memory: 64M

五、配置参数详解

5.1 核心配置文件路径

5.2 任务执行依赖管理

若任务依赖外部脚本或工具，需通过卷挂载或镜像构建阶段集成：

bash
# 示例：挂载本地脚本目录至容器，任务中调用脚本
docker run -d \
  -v $(pwd)/my-crontab:/etc/crontabs/root \
  -v $(pwd)/my-scripts:/usr/local/scripts \  # 本地脚本目录挂载至容器
  dockerized-cron:latest

此时 crontab 文件可直接调用脚本：

bash
# 每小时执行挂载的备份脚本
0 * * * * /usr/local/scripts/backup-data.sh >> /var/log/backup.log 2>&1

5.3 时区配置说明

容器默认时区为 UTC，若任务需按本地时区执行，需通过以下方式配置：

方法 1：通过环境变量 TZ 配置（推荐）

bash
docker run -e TZ=Asia/Shanghai dockerized-cron:latest

方法 2：挂载本地时区文件（适用于不支持 TZ 变量的场景）

bash
docker run -v /etc/timezone:/etc/timezone:ro -v /etc/localtime:/etc/localtime:ro dockerized-cron:latest

六、注意事项

1. 权限问题：

   • 挂载的 crontab 文件权限需符合容器内用户权限（如 root 用户任务文件权限建议 600）
   • 非 root 用户执行任务时，需确保用户对任务文件、脚本及输出目录有读写权限

2. 任务输出处理：

   • cron 任务默认无终端，避免使用依赖终端的命令（如 vim）
   • 任务输出建议显式重定向至文件或 stdout（>> /var/log/task.log 2>&1），否则可能丢失日志

3. 容器生命周期：

   • 容器停止后任务将终止，需通过 --restart=always 或 docker-compose restart 策略确保任务持续执行
   • 任务逻辑应设计为幂等性（重复执行不影响结果），避免容器重启导致任务重复执行问题

4. 资源限制：

   • 若任务资源消耗较高（如 CPU/内存密集型），建议通过 --cpus、--memory 限制容器资源，避免影响其他服务

七、常见问题（FAQ）

Q：任务未执行，如何排查？

A：1. 检查 crontab 文件语法（可通过 crontab -l 在容器内验证）；2. 查看容器日志（docker logs）确认 cron 守护进程是否正常启动；3. 确认任务命令在容器内可执行（如依赖工具是否存在）。

Q：如何在任务中使用环境变量？

A：需在 crontab 文件中显式定义环境变量，或通过 source /etc/environment 加载容器环境变量，例如：

bash
# 在 crontab 文件中定义环境变量
DB_HOST=db.example.com
DB_PORT=3306
* * * * * /usr/local/scripts/query-db.sh $DB_HOST $DB_PORT >> /var/log/db.log 2>&1

Q：如何更新任务配置？

A：修改本地挂载的 crontab 文件后，无需重启容器，cron 守护进程会自动检测文件变更（通常 1-2 分钟内生效）；若未自动生效，可通过 docker exec docker-cron crontab /etc/crontabs/root 手动重载。