eeacms/docker-cleanup

Docker Cleanup 镜像文档

镜像概述和主要用途

该镜像基于https://github.com/meltwater/docker-cleanup%E5%B9%B6%E5%81%9A%E4%BA%86%E5%B0%91%E9%87%8F%E4%BF%AE%E6%94%B9%EF%BC%8C%E7%94%A8%E4%BA%8E%E5%AE%9A%E6%9C%9F%E6%B8%85%E7%90%86%E9%80%80%E5%87%BA%E7%9A%84%E5%AE%B9%E5%99%A8%E3%80%81%E6%9C%AA%E8%A2%AB%E8%BF%90%E8%A1%8C%E4%B8%AD%E5%AE%B9%E5%99%A8%E4%BD%BF%E7%94%A8%E7%9A%84%E9%95%9C%E5%83%8F%E5%92%8C%E5%8D%B7%E3%80%82

警告：除非仔细排除，否则此脚本会删除所有退出的容器、数据卷容器和未使用的镜像。若将/var/lib/docker挂载到容器中，会清理所有未使用的数据卷。如果与您的系统或Docker版本不兼容，可能会删除所有卷，甚至正在运行的容器的卷。

通常，任何退出的Docker容器会保留在磁盘上，直到使用docker rm -v清理。同样，不再使用的镜像也会保留。对于频繁启停容器的集群节点或Jenkins构建从节点，大量退出的容器和旧镜像版本会占用磁盘空间，尤其是持续重建的SNAPSHOT镜像会留下未标记的<none>镜像。

核心功能和特性

• 定期清理退出的容器
• 删除未被运行中容器使用的镜像
• 清理未使用的卷（当挂载/var/lib/docker时）
• 支持通过环境变量配置清理规则
• 可设置清理间隔和延迟时间
• 支持排除特定镜像、容器和卷
• 可选择单次运行或循环运行模式
• 提供调试输出功能

使用场景和适用范围

• 容器频繁启停的集群节点，防止磁盘空间被退出容器和旧镜像占用
• Jenkins构建从节点，解决SNAPSHOT镜像持续重建导致的未标记镜像堆积问题
• 需要自动维护Docker环境整洁的服务器
• 任何需要定期清理Docker资源以释放磁盘空间的场景

环境变量

默认参数可通过docker run -e标志设置容器环境变量来覆盖：

• CLEAN_PERIOD=1800：完成一次清理后休眠的间隔时间（秒），默认1800秒（30分钟）
• DELAY_TIME=1800：删除退出容器和未使用镜像前的等待时间（秒），默认1800秒（30分钟）
• KEEP_IMAGES：避免清理的镜像列表，如"ubuntu:trusty, ubuntu:latest"，默认清理所有未使用镜像
• KEEP_CONTAINERS：避免清理的退出或停止容器所基于的镜像列表，如"ubuntu:trusty, ubuntu:latest"
• KEEP_CONTAINERS_NAMED：避免清理的退出或停止容器的名称列表，如"my-container1, persistent-data"
• KEEP_VOLUMES：避免清理的未使用命名卷列表，如"database-vol, caching"，使用**All**可保留所有卷
• LOOP：是否循环清理，选项为true或false，默认true（持续循环运行）
• DEBUG：设为1启用更多调试输出
• DOCKER_API_VERSION：Docker API版本，默认1.20，可通过docker version --format '{{.Client.APIVersion}}'查看主机API版本

注意：KEEP_IMAGES、KEEP_CONTAINERS和KEEP_CONTAINERS_NAMED使用左锚定正则表达式。例如，镜像foo/bar:tag可被以下任一匹配：

• foo/bar:tag
• foo/bar
• foo/b
• [[:alpha:]]*/bar
• .*/.*:tag
• .*:tag
• foo/*:tag

但不会被以下匹配：

• foo/baz
• bar:tag
• /bar
• :tag
• [[:alpha:]]*:tag

默认情况下，所有KEEP_*变量均设为**None**（等同于空字符串）。若要保留所有镜像、卷或容器（禁用对应清理功能），应使用**All**。

部署方法

该镜像使用Docker客户端列出和删除容器及镜像，因此需要将Docker客户端和套接字映射到容器中。若映射/var/lib/docker目录，脚本还会清理孤立的Docker卷。

Docker Compose和Rancher

yaml
cleanup:
  image: eeacms/docker-cleanup:2.1.0
  environment:
    CLEAN_PERIOD: '86400'          # 清理间隔：24小时
    DEBUG: '0'                     # 禁用调试输出
    DELAY_TIME: '900'              # 延迟时间：15分钟
    KEEP_CONTAINERS: '**All**'     # 保留所有容器
    KEEP_CONTAINERS_NAMED: '**All**' # 保留所有命名容器
    KEEP_VOLUMES: '**None**'       # 不保留未使用卷
    KEEP_IMAGES: rancher/, busybox, tianon/  # 保留指定镜像
    LOOP: 'true'                   # 循环运行
  labels:
    io.rancher.scheduler.global: 'true'  # 在所有节点运行
    io.rancher.scheduler.affinity:host_label_ne: janitor.exclude=true  # 排除特定节点
  privileged: true
  volumes:
  - /var/run/docker.sock:/var/run/docker.sock  # 映射Docker套接字
  - /var/lib/docker:/var/lib/docker            # 映射Docker数据目录（用于卷清理）

Systemd和CoreOS/Fleet

在/etc/systemd/system/docker-cleanup.service创建Systemd单元文件。使用CoreOS和Fleet时，添加X-Fleet部分以在所有集群节点调度该单元：

[Unit]
Description=Cleanup of exited containers and unused images/volumes
After=docker.service
Requires=docker.service

[Install]
WantedBy=multi-user.target

[Service]
Environment=IMAGE=eeacms/docker-cleanup:latest NAME=docker-cleanup

# 允许docker pull有足够时间
TimeoutStartSec=600

# 失败时重启
KillMode=none
Restart=always
RestartSec=15

ExecStartPre=-/usr/bin/docker kill $NAME
ExecStartPre=-/usr/bin/docker rm $NAME
ExecStartPre=-/bin/sh -c 'if ! docker images | tr -s " " : | grep "^${IMAGE}:"; then docker pull "${IMAGE}"; fi'
ExecStart=/usr/bin/docker run \
    -v /var/run/docker.sock:/var/run/docker.sock:rw \
    -v /var/lib/docker:/var/lib/docker:rw \
    --name=${NAME} \
    $IMAGE

ExecStop=/usr/bin/docker stop $NAME

[X-Fleet]
Global=true  # 在所有节点运行

Puppet Hiera

使用https://github.com/garethr/garethr-docker%E6%A8%A1%E5%9D%97%EF%BC%9A

classes:
  - docker::run_instance

docker::run_instance:
  'cleanup':
    image: 'eeacms/docker-cleanup:latest'
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:rw"
      - "/var/lib/docker:/var/lib/docker:rw"

命令行

bash
docker run \
  -v /var/run/docker.sock:/var/run/docker.sock:rw \
  -v /var/lib/docker:/var/lib/docker:rw \
  eeacms/docker-cleanup:latest

Kubernetes

可使用Kubernetes DaemonSet配置在集群所有节点运行eeacms/docker-cleanup容器：

bash
kubectl create -f contrib/k8s-daemonset.yml

开发

包含Makefile以帮助开发中的重复命令：

bash
make help