Docker CI镜像文档

一、镜像概述和主要用途

本镜像是一个专为CI/CD流程设计的Docker镜像，集成了Docker-in-Docker（dind）、Docker Buildx及常用开发工具（如git、curl、jq等）。其核心用途是在CI环境中提供完整的Docker构建能力，支持多平台镜像构建、容器化应用自动化部署等场景，简化CI流程中的环境配置。

二、核心功能和特性

1. Docker-in-Docker（dind）支持

• 内置Docker守护进程，允许在容器内部运行Docker命令，实现"容器中构建容器"的能力。
• 支持Docker daemon与客户端的本地通信，无需依赖外部Docker服务。

2. Docker Buildx集成

• 预装Buildx插件，提供增强的构建功能，包括：
  • 多平台镜像构建（如同时构建amd64、arm64架构）；
  • 构建缓存优化；
  • 自定义构建输出（如OCI镜像、Docker镜像格式）。

3. 预装常用CI工具

• 版本控制工具：git（支持代码拉取、分支管理）；
• 网络工具：curl（支持HTTP/HTTPS请求，用于API调用、资源下载）；
• 数据处理工具：jq（轻量级JSON处理器，用于CI流程中的配置解析、数据过滤）。

三、使用场景和适用范围

1. 自动化Docker镜像构建

适用于CI流程中触发自动构建Docker镜像（如代码提交后触发构建），无需依赖外部Docker环境。

2. 多平台镜像构建

通过Buildx支持跨架构镜像构建（如x86_64、arm64、ppc64le等），满足多硬件环境部署需求。

3. CI流程中的版本控制与数据处理

• 使用git进行代码拉取、版本标签管理；
• 通过curl调用外部API（如镜像仓库、通知服务）；
• 借助jq解析JSON格式的配置文件或API返回数据（如提取版本号、过滤构建参数）。

4. CI环境中的Docker命令执行

需在CI流程中直接运行Docker命令（如镜像推送、容器运行测试）时，可作为执行环境使用。

四、使用方法和配置说明

4.1 基本运行方式

4.1.1 启动镜像（dind模式）

由于需运行Docker守护进程，需使用--privileged权限（注意：生产环境需评估安全风险）：

docker run -d \
  --name ci-dind \
  --privileged \
  -v /var/lib/docker \  # 可选：持久化Docker数据
  sickhub/docker-ci-images

4.1.2 进入容器执行命令

docker exec -it ci-dind sh
# 验证Docker环境
docker --version
# 验证Buildx
docker buildx version
# 验证工具
git --version && curl --version && jq --version

4.2 使用Buildx构建多平台镜像

4.2.1 初始化Buildx构建器

# 进入容器后执行
docker buildx create --name multi-platform-builder --use
docker buildx inspect --bootstrap  # 启动构建器（首次需下载依赖）

4.2.2 构建并推送多平台镜像

# 示例：构建并推送到Docker Hub（需提前登录docker login）
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t username/your-image:latest \
  --push \
  /path/to/Dockerfile

4.3 集成到CI流程示例

4.3.1 GitLab CI配置（.gitlab-ci.yml）

stages:
  - build

build-image:
  stage: build
  image: sickhub/docker-ci-images
  services:
    - docker:dind  # 若需独立dind服务，可配合使用（根据GitLab Runner配置调整）
  variables:
    DOCKER_DRIVER: overlay2
    DOCKER_TLS_CERTDIR: ""  # 禁用TLS（简化本地通信）
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker buildx create --use
    - docker buildx build --platform linux/amd64,linux/arm64 -t $CI_REGISTRY_IMAGE:latest --push .

4.3.2 GitHub Actions配置（.github/workflows/build.yml）

name: Build Multi-Platform Image
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3  # 或直接使用镜像内置buildx
        with:
          driver: docker-container  # 使用容器化驱动，依赖dind

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: username/your-image:latest
          platforms: linux/amd64,linux/arm64
          # 若直接使用本镜像，可替换为：
          # image: sickhub/docker-ci-images
          # entrypoint: ["docker", "buildx", "build"]

4.4 环境变量说明

本镜像未定义强制环境变量，可根据需求通过-e参数传递自定义变量，常用场景包括：

• DOCKER_HOST：指定Docker守护进程地址（默认本地unix:///var/run/docker.sock）；
• BUILDX_PLATFORMS：默认多平台列表（如linux/amd64,linux/arm64）；
• GIT_CONFIG_USER_NAME/GIT_CONFIG_USER_EMAIL：配置git提交用户信息。

五、注意事项

1. 安全风险：--privileged模式会赋予容器极高权限，可能导致主机安全风险，生产环境建议通过非特权容器+外部Docker守护进程（如挂载/var/run/docker.sock）替代dind。
2. 资源需求：多平台构建需较高CPU/内存资源，CI环境需确保Runner配置满足需求。
3. 网络配置：若需访问私有镜像仓库或代理，需通过HTTP_PROXY等环境变量配置网络代理。