unlockprotocol/unlock-dev

镜像概述

本镜像是一款专注于开发场景的构建加速工具，核心功能是通过智能缓存构建依赖和Docker中间层，解决频繁构建场景下重复下载依赖、重复执行构建步骤导致的效率问题。适用于需要频繁迭代代码并构建镜像的开发环境，帮助团队减少等待时间，提升开发流畅度。

主要用途

• 加速本地开发环境中的镜像构建流程
• 优化CI/CD流水线中构建阶段的执行效率
• 减少多团队协作时的重复构建资源消耗
• 降低频繁构建对网络带宽的依赖

核心功能与特性

核心功能

• 构建依赖缓存：自动识别并缓存npm、maven、pip等包管理工具的依赖文件，避免重复下载
• Docker中间层缓存：智能缓存Dockerfile构建过程中的中间层镜像，减少重复执行RUN、COPY等指令的时间
• 多工具兼容：支持Docker、Docker Compose、Buildx等主流容器构建工具的缓存对接
• 缓存生命周期管理：提供缓存过期策略、大小限制和自动清理机制，避免磁盘空间过度占用

特性

• 轻量级设计：基于Alpine Linux构建，镜像体积小于50MB，运行时内存占用低于100MB
• 灵活配置：通过环境变量和配置文件自定义缓存行为，适配不同构建场景需求
• 跨平台支持：兼容Linux、macOS（Docker Desktop）及Windows（WSL2）开发环境
• 无缝集成：提供HTTP API和CLI工具，可直接集成到现有开发流程或CI/CD平台

使用场景与适用范围

典型使用场景

1. 本地开发迭代：开发人员频繁修改代码并执行docker build时，避免每次重构都重新下载依赖
2. CI/CD流水线：在GitHub Actions、GitLab CI等平台中，加速测试环境镜像的构建步骤，缩短流水线周期
3. 多团队协作：团队共享缓存服务，新成员无需重复下载完整依赖，快速接入开发
4. 教学/演示环境：快速搭建开发环境，减少环境准备阶段的等待时间

适用范围

• 前端/后端开发团队：需要频繁构建Node.js、Java、Python等语言的应用镜像
• DevOps团队：负责优化CI/CD流水线性能的技术团队
• 开源项目维护者：为贡献者提供快速构建体验，降低参与门槛

使用方法与配置说明

前提条件

• Docker Engine 20.10.0+ 或 Docker Desktop 4.0+
• 至少1GB可用磁盘空间（建议根据项目规模调整，推荐10GB以上）

快速启动

1. 拉取镜像

bash
docker pull docker.xuanyuan.run/[镜像仓库地址]/dev-image-cache:latest

2. 基本运行命令

bash
docker run -d \
  --name dev-image-cache \
  -p 8080:8080 \  # 缓存服务端口
  -v /path/to/local/cache:/app/cache \  # 本地缓存目录映射（持久化缓存数据）
  -e CACHE_TTL=604800 \  # 缓存过期时间：7天（604800秒）
  -e CACHE_SIZE_LIMIT=20G \  # 缓存大小限制：20GB
  -e LOG_LEVEL=info \  # 日志级别：debug/info/warn/error
  [镜像仓库地址]/dev-image-cache:latest

3. 验证服务状态

bash
curl http://localhost:8080/health
# 健康检查响应示例：{"status":"healthy","cache_used":"1.2 GB","cache_total":"20 GB","cache_count":42}

Docker Compose配置示例

yaml
version: '3.8'

services:
  dev-image-cache:
    image: docker.xuanyuan.run/[镜像仓库地址]/dev-image-cache:latest
    container_name: dev-image-cache
    ports:
      - "8080:8080"
    volumes:
      - ./local-cache:/app/cache  # 本地缓存目录（建议使用绝对路径）
    environment:
      - CACHE_TTL=604800  # 7天缓存有效期
      - CACHE_SIZE_LIMIT=15G  # 限制缓存总大小为15GB
      - LOG_LEVEL=info
    restart: unless-stopped  # 确保服务持续运行

启动服务：

bash
docker-compose up -d

集成到构建流程

Docker Build集成

bash
docker build \
  --cache-from=type=http,url=http://localhost:8080/cache \  # 从缓存服务拉取缓存
  --cache-to=type=http,url=http://localhost:8080/cache,mode=max \  # 将新缓存推送到服务
  -t my-app:dev .

Docker Compose集成

在docker-compose.yml中添加缓存配置：

yaml
version: '3.8'

services:
  app:
    build:
      context: .
      cache_from:
        - type: http
          url: http://dev-image-cache:8080/cache  # 缓存服务地址（容器间通信）
      cache_to:
        - type: http
          url: http://dev-image-cache:8080/cache
          mode: max
    depends_on:
      - dev-image-cache  # 确保缓存服务先启动

  dev-image-cache:
    image: docker.xuanyuan.run/[镜像仓库地址]/dev-image-cache:latest
    volumes:
      - ./cache-data:/app/cache
    environment:
      - CACHE_SIZE_LIMIT=10G

配置参数说明

缓存管理

手动清理过期缓存

bash
docker exec dev-image-cache ./cleanup --expired

清理超出容量限制的缓存（LRU策略）

bash
docker exec dev-image-cache ./cleanup --size-exceeded

常见问题

Q: 首次使用时构建速度无提升？

A: 首次构建需要完成完整缓存初始化，需执行一次完整构建后，后续构建即可享受缓存加速。

Q: 如何验证缓存是否生效？

A: 查看构建日志，若出现Using cache或Cache hit字样，表明缓存已生效；或通过curl http://localhost:8080/stats查看缓存命中率。

Q: 多台开发机如何共享缓存？

A: 将CACHE_BACKEND配置为S3兼容对象存储（如MinIO、AWS S3），多台机器连接同一对象存储后端即可实现缓存共享。