circleci/docker-gc

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

环境变量参数说明

高级配置示例

场景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验证清理策略，排除生产核心镜像

注意事项

1. 权限要求：容器需挂载/var/run/docker.sock以获取Docker API访问权限，生产环境建议通过Docker用户组限制权限，避免直接使用root用户。

2. 数据安全：首次部署建议启用DRY_RUN=true验证清理结果，确认无误后再关闭模拟模式。

3. 排除规则：核心业务镜像务必加入EXCLUDE_IMAGES，避免因LRU误判导致服务不可用。

4. 性能影响：清理操作可能短暂占用磁盘I/O，建议在业务低峰期配置检查间隔（如凌晨2点）。

5. 版本兼容性：支持Docker Engine 18.09+版本，低版本可能存在API兼容性问题。