circleci/docker-gc Docker Image Overview

circleci/docker-gc

circleci

用于执行Docker镜像缓存LRU垃圾回收的工具

6 次收藏下载次数: 0状态：社区镜像维护者：circleci仓库类型：镜像最近更新：13 天前

使用轩辕镜像，把时间还给真正重要的事。点击查看

中文简介版本下载

使用轩辕镜像，把时间还给真正重要的事。点击查看

Docker镜像缓存LRU垃圾回收代理

镜像概述

简介

Docker镜像缓存LRU垃圾回收代理（以下简称“镜像缓存代理”）是一款轻量级工具，通过LRU（最近最少使用）算法自动管理Docker镜像缓存，识别并回收不再需要的镜像文件，释放磁盘空间，避免因缓存膨胀导致的存储资源耗尽问题。

主要用途

自动清理Docker宿主机上长期未使用的镜像缓存
基于访问频率动态控制缓存占用空间
保障Docker环境存储资源的稳定可用
降低手动清理镜像的运维成本

核心功能与特性

LRU策略回收

采用LRU算法优先删除最近最少访问的镜像，保留高频使用镜像
基于Docker镜像元数据（如最后访问时间、创建时间）计算回收优先级

智能缓存控制

支持设置最大缓存占用空间阈值，超过阈值自动触发清理
可配置最小保留镜像数量，避免误删基础依赖镜像

自动化运维

支持定时周期检查（如每小时/每天），无需人工干预
实时监控缓存增长趋势，提前触发清理动作

安全操作保障

仅删除未被容器引用的镜像，避免影响运行中服务
支持配置排除规则，保护核心业务镜像（如指定镜像名、标签）

轻量级设计

无额外依赖，直接通过Docker API与宿主机交互
资源占用低（内存<50MB，CPU使用率<5%）

使用场景与适用范围

CI/CD流水线环境

解决因频繁构建/拉取镜像导致的缓存堆积问题
保障构建节点磁盘空间稳定，避免流水线中断

多项目开发环境

清理不同项目遗留的临时镜像，释放开发机存储资源
避免因镜像缓存过大导致的Docker服务异常

生产环境边缘节点

在资源受限的边缘设备（如IoT网关、边缘服务器）中控制镜像存储
保障核心业务镜像优先留存，提升系统稳定性

容器化测试环境

自动化清理测试过程中产生的临时镜像，降低测试环境维护成本
确保测试环境存储状态一致，减少环境差异导致的测试偏差

使用方法与配置说明

快速启动（docker run）

bash
docker run -d \
  --name image-cache-agent \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e MAX_CACHE_SIZE="20GB" \
  -e CHECK_INTERVAL="3600" \
  -e MIN_RESERVE_COUNT="5" \
  -e EXCLUDE_IMAGES="nginx:latest,mysql:8.0" \
  image-cache-lru-agent:latest

Docker Compose配置

yaml
version: '3.8'
services:
  image-cache-agent:
    image: image-cache-lru-agent:latest
    container_name: image-cache-agent
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # 挂载Docker socket以访问Docker API
    environment:
      - MAX_CACHE_SIZE=15GB  # 最大缓存占用空间
      - CHECK_INTERVAL=1800  # 检查间隔（秒），默认3600秒
      - MIN_RESERVE_COUNT=3  # 最小保留镜像数量，默认10
      - EXCLUDE_IMAGES=redis:alpine,ubuntu:22.04  # 排除的镜像（逗号分隔）
      - FORCE_CLEAN_ON_START=true  # 容器启动时是否立即执行一次清理
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error
    networks:
      - docker-network

networks:
  docker-network:
    driver: bridge

环境变量参数说明

环境变量名	描述	类型	默认值	示例值
`MAX_CACHE_SIZE`	允许的最大缓存占用空间	字符串	10GB	"20GB"、"5000MB"
`CHECK_INTERVAL`	缓存检查周期（秒）	整数	3600	1800（30分钟）
`MIN_RESERVE_COUNT`	清理后至少保留的镜像数量	整数	10	5
`EXCLUDE_IMAGES`	不参与清理的镜像（名称:标签，逗号分隔）	字符串	空	"nginx:latest,alpine:*"
`FORCE_CLEAN_ON_START`	容器启动时是否立即执行清理	布尔	false	true
`DELETE_UNUSED_DAYS`	超过指定天数未使用的镜像强制删除	整数	30	14（2周）
`LOG_LEVEL`	日志输出级别	字符串	info	debug
`DRY_RUN`	仅模拟清理操作，不实际删除镜像	布尔	false	true

高级配置示例

场景1：CI/CD节点配置

bash
docker run -d \
  --name ci-image-agent \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e MAX_CACHE_SIZE="50GB" \
  -e CHECK_INTERVAL="1800" \
  -e MIN_RESERVE_COUNT="3" \
  -e DELETE_UNUSED_DAYS="1" \
  -e EXCLUDE_IMAGES="jenkins/jnlp-agent:latest" \
  -e LOG_LEVEL="warn" \
  image-cache-lru-agent:latest

说明：CI节点每日构建产生大量临时镜像，配置1天未使用即清理，保留核心构建代理镜像

场景2：生产边缘节点配置

bash
docker run -d \
  --name edge-image-agent \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e MAX_CACHE_SIZE="10GB" \
  -e CHECK_INTERVAL="86400" \
  -e MIN_RESERVE_COUNT="8" \
  -e EXCLUDE_IMAGES="edge-gateway:prod,data-collector:*" \
  -e DRY_RUN="true" \
  image-cache-lru-agent:latest

说明：边缘节点存储资源有限，配置每日检查，先通过DRY_RUN验证清理策略，排除生产核心镜像

注意事项

权限要求：容器需挂载/var/run/docker.sock以获取Docker API访问权限，生产环境建议通过Docker用户组限制权限，避免直接使用root用户。
数据安全：首次部署建议启用DRY_RUN=true验证清理结果，确认无误后再关闭模拟模式。
排除规则：核心业务镜像务必加入EXCLUDE_IMAGES，避免因LRU误判导致服务不可用。
性能影响：清理操作可能短暂占用磁盘I/O，建议在业务低峰期配置检查间隔（如凌晨2点）。
版本兼容性：支持Docker Engine 18.09+版本，低版本可能存在API兼容性问题。