cimg/base 镜像文档

镜像概述和主要用途

cimg/base 是由 CircleCI 开发的 Ubuntu Docker 镜像，专为持续集成（CI）构建场景设计。正如其名称所示，该镜像旨在作为其他 CircleCI 便捷镜像（前缀为 cimg/ 的镜像）的基础镜像，同时也适用于用户构建自定义 Docker 镜像时作为基础。它包含运行 CircleCI 构建所需的最小工具集（如 git）以及 CI 场景中广泛使用的工具（如 docker）。

核心功能和特性

• CI 优化：针对 CircleCI 运行环境优化，确保与 CI/CD 流程无缝集成。
• 基础工具集：包含 CI 构建核心工具，如 git、docker、docker-compose、build-essential（编译工具）、jq、curl、ssh 等。
• 版本稳定性：提供多版本标签策略，满足不同稳定性需求（测试版、稳定版、月度快照版）。
• Ubuntu 基础：基于 Ubuntu LTS 版本，确保系统级稳定性和广泛的软件兼容性。
• 可扩展性：作为基础镜像，支持用户添加自定义工具和配置，构建个性化 CI 环境。

使用场景和适用范围

• CircleCI 构建环境：直接作为 CircleCI 工作流中的执行环境，运行 CI 构建步骤。
• 基础镜像开发：作为其他 cimg/ 系列镜像（如 cimg/node、cimg/python）的底层基础。
• 自定义 CI 镜像：用户基于此镜像添加特定语言或工具，构建满足项目需求的自定义 CI 镜像。
• 本地 CI 测试：在本地环境模拟 CircleCI 构建流程，验证配置和依赖。

详细的使用方法和配置说明

CircleCI 配置示例

在 .circleci/config.yml 中使用 docker 执行器指定该镜像：

jobs:
  build:
    docker:
      - image: cimg/base:2022.09  # 使用月度快照版本
    steps:
      - checkout  # 检出代码
      - run: sudo apt-get update && sudo apt-get install -y figlet  # 安装额外工具
      - run: figlet "持续集成构建成功！"  # 执行构建步骤

标签方案

镜像提供多种标签，用于满足不同稳定性需求：

注意：未指定 -version 时，默认使用最新 LTS 版本（发布后 4 个月切换）。例如，Ubuntu 22.04 于 2022 年 4 月发布，2022 年 8 月成为默认版本。上一个 LTS 版本在退出默认后仍支持 1 年。

本地使用方法

拉取镜像

从 Docker Hub 拉取官方镜像：

docker pull cimg/base:current  # 拉取最新稳定版
# 或指定具体版本
docker pull cimg/base:2022.09-22.04

本地运行容器

启动交互式容器，验证环境：

docker run -it --rm cimg/base:current bash  # 启动 bash 终端
# 在容器内验证工具
git --version
docker --version

构建自定义镜像

基于 cimg/base 创建自定义镜像，示例 Dockerfile：

FROM cimg/base:2022.09

# 安装额外工具
RUN sudo apt-get update && sudo apt-get install -y \
    wget \
    unzip \
    && sudo rm -rf /var/lib/apt/lists/*

# 设置环境变量
ENV APP_HOME=/app
WORKDIR $APP_HOME

构建并运行自定义镜像：

docker build -t my-ci-image .
docker run -it --rm my-ci-image bash

开发指南

环境要求

• Linux（已测试 Ubuntu）或 macOS 系统
• Bash 4+
• Docker Engine 20.10+

代码克隆

社区用户（无仓库写入权限）

1. Fork 仓库后克隆，需包含子模块：

   git clone --recurse-submodules <你的 Fork 仓库 URL>
   

2. 若已克隆，补全子模块：

   git submodule update --recursive
   

3. 添加上游仓库（可选）：

   git remote add upstream [***]
   

维护者（有仓库写入权限）

直接克隆仓库（包含子模块）：

git clone --recurse-submodules ***:CircleCI-Public/cimg-base.git

生成 Dockerfile

1. 修改 Dockerfile.template 文件。
2. 运行生成脚本，指定 Ubuntu 版本（如 20.04 和 22.04）：

   ./shared/gen-dockerfiles.sh 20.04 22.04
   

3. 生成的 Dockerfile 位于 ./20.04/Dockerfile 和 ./22.04/Dockerfile。

本地构建和测试

1. 进入版本目录，构建镜像：

   cd 20.04
   docker build -t test/base:20.04 .
   

2. 运行测试容器：

   docker run -it test/base:20.04 bash
   

发布流程（仅维护者）

1. 运行发布脚本，指定 LTS 版本（如 20.04）：

   ./shared/release.sh 20.04
   

2. 脚本会自动创建分支、生成 Dockerfile、提交并推送。
3. 等待 CircleCI 构建通过后，审核并合并 PR，触发正式发布。

支持政策

该镜像遵循 CircleCI 便捷镜像支持政策，包含发布、更新和废弃规则。

贡献指南

欢迎提交 Issue 和 Pull Request。贡献前请参考 贡献指南。

相关资源

• CircleCI 官方文档
• CircleCI 配置参考
• Docker 官方文档

许可证

本仓库采用 MIT 许可证，详见 LICENSE。